Leptonica  1.83.1
Image processing and image analysis suite
gplot.c File Reference
#include <string.h>
#include "allheaders.h"

Go to the source code of this file.

Macros

#define Bufsize   512 /* hardcoded below in fscanf */
 

Functions

GPLOTgplotCreate (const char *rootname, l_int32 outformat, const char *title, const char *xlabel, const char *ylabel)
 
void gplotDestroy (GPLOT **pgplot)
 
l_ok gplotAddPlot (GPLOT *gplot, NUMA *nax, NUMA *nay, l_int32 plotstyle, const char *plotlabel)
 
l_ok gplotSetScaling (GPLOT *gplot, l_int32 scaling)
 
PIXgplotMakeOutputPix (GPLOT *gplot)
 
l_ok gplotMakeOutput (GPLOT *gplot)
 
l_ok gplotGenCommandFile (GPLOT *gplot)
 
l_ok gplotGenDataFiles (GPLOT *gplot)
 
l_ok gplotSimple1 (NUMA *na, l_int32 outformat, const char *outroot, const char *title)
 
l_ok gplotSimple2 (NUMA *na1, NUMA *na2, l_int32 outformat, const char *outroot, const char *title)
 
l_ok gplotSimpleN (NUMAA *naa, l_int32 outformat, const char *outroot, const char *title)
 
PIXgplotSimplePix1 (NUMA *na, const char *title)
 
PIXgplotSimplePix2 (NUMA *na1, NUMA *na2, const char *title)
 
PIXgplotSimplePixN (NUMAA *naa, const char *title)
 
GPLOTgplotSimpleXY1 (NUMA *nax, NUMA *nay, l_int32 plotstyle, l_int32 outformat, const char *outroot, const char *title)
 
GPLOTgplotSimpleXY2 (NUMA *nax, NUMA *nay1, NUMA *nay2, l_int32 plotstyle, l_int32 outformat, const char *outroot, const char *title)
 
GPLOTgplotSimpleXYN (NUMA *nax, NUMAA *naay, l_int32 plotstyle, l_int32 outformat, const char *outroot, const char *title)
 
PIXgplotGeneralPix1 (NUMA *na, l_int32 plotstyle, const char *rootname, const char *title, const char *xlabel, const char *ylabel)
 
PIXgplotGeneralPix2 (NUMA *na1, NUMA *na2, l_int32 plotstyle, const char *rootname, const char *title, const char *xlabel, const char *ylabel)
 
PIXgplotGeneralPixN (NUMA *nax, NUMAA *naay, l_int32 plotstyle, const char *rootname, const char *title, const char *xlabel, const char *ylabel)
 
GPLOTgplotRead (const char *filename)
 
l_ok gplotWrite (const char *filename, GPLOT *gplot)
 

Variables

const char * gplotstylenames []
 
const char * gplotfileoutputs []
 

Detailed Description


    Basic plotting functions
         GPLOT      *gplotCreate()
         void        gplotDestroy()
         l_int32     gplotAddPlot()
         l_int32     gplotSetScaling()
         PIX        *gplotMakeOutputPix()
         l_int32     gplotMakeOutput()
         l_int32     gplotGenCommandFile()
         l_int32     gplotGenDataFiles()

    Quick, one-line plots
         l_int32     gplotSimple1()
         l_int32     gplotSimple2()
         l_int32     gplotSimpleN()
         PIX        *gplotSimplePix1()
         PIX        *gplotSimplePix2()
         PIX        *gplotSimplePixN()
         GPLOT      *gplotSimpleXY1()
         GPLOT      *gplotSimpleXY2()
         GPLOT      *gplotSimpleXYN()
         PIX        *gplotGeneralPix1()
         PIX        *gplotGeneralPix2()
         PIX        *gplotGeneralPixN()

    Serialize for I/O
         GPLOT      *gplotRead()
         l_int32     gplotWrite()


    Utility for programmatic plotting using gnuplot 4.6 or later
    Enabled:
        ~ output to png (color), ps and eps (mono), latex (mono)
        ~ optional title for plot
        ~ optional x and y axis labels
        ~ multiple plots on one frame
        ~ optional label for each plot on the frame
        ~ optional log scaling on either or both axes
        ~ choice of 5 plot styles for each array of input data
        ~ choice of 2 plot modes, either using one input array
          (Y vs index) or two input arrays (Y vs X).  For functions
          that take two arrays, the first mode (Y vs index) is
          employed if the first array is NULL.

    General usage:
        gplotCreate() initializes for plotting
        gplotAddPlot() for each plot on the frame
        gplotMakeOutput() to generate all output files and run gnuplot
        gplotDestroy() to clean up

    Example of use:
        gplot = gplotCreate("tempskew", GPLOT_PNG, "Skew score vs angle",
                   "angle (deg)", "score");
        gplotAddPlot(gplot, natheta, nascore1, GPLOT_LINES, "plot 1");
        gplotAddPlot(gplot, natheta, nascore2, GPLOT_POINTS, "plot 2");
        gplotSetScaling(gplot, GPLOT_LOG_SCALE_Y);
        gplotMakeOutput(gplot);
        gplotDestroy(&gplot);

    Example usage of one-line plot generators:

        -- Simple plots --
        Specify the root of output files, the output format,
        and the title (optional), but not the x and y coordinate labels
        or the plot labels.  The plotstyle defaults to GPLOT_LINES.
           gplotSimple2(na1, na2, GPLOT_PNG, "/tmp/lept/histo/gray",
                        "gray histogram");
        Multiple plots can be generated using gplotSimpleN().

        -- Simple plots with more options --
        Specify the root of output files, the plotstyle, the output format,
        and optionally the title, but not the x and y coordinate labels
        or the plot labels.
           gplotSimpleXY1(na1, na2, GPLOT_LINES, GPLOT_PNG,
                          "/tmp/lept/histo/gray", "gray histogram");
        Multiple plots can be generated using gplotSimpleXYN().

        -- Simple plots returning a pix --
        Specify only the title (optional).  The plotstyle defaults
        GPLOT_LINES and the output format is GPLOT_PNG..
        You can't specify the x and y coordinate labels or the plot label.
        The rootname of the generated files is determined internally.
           Pix *pix = gplotSimplePix2(na1, na2, "gray histogram");
        Multiple plots can be generated using gplotSimplePixN().

        -- General plots returning a pix --
        Specify the root of the output files, the plotstyle, and optionally
        the title and axis labels.  This does not allow the individual
        plots to have plot labels, or to use different plotstyles
        for each plot.
           Pix *pix = gplotGeneralPix2(na1, na2, "/tmp/lept/histo/gray",
                                  GPLOT_LINES, "gray histogram",
                                  "pix value", "num pixels");
        Multiple plots can be generated using gplotGeneralPixN().

    Note for output to GPLOT_LATEX:
        This creates latex output of the plot, named <rootname>.tex.
        It needs to be placed in a latex file <latexname>.tex
        that precedes the plot output with, at a minimum:
          \documentclass{article}
          \begin{document}
        and ends with
          \end{document}
        You can then generate a dvi file <latexname>.dvi using
          latex <latexname>.tex
        and a PostScript file <psname>.ps from that using
          dvips -o <psname>.ps <latexname>.dvi

    N.B. To generate plots, it is necessary to have gnuplot installed on
         your Unix system, or wgnuplot on Windows.

Definition in file gplot.c.

Function Documentation

◆ gplotAddPlot()

l_ok gplotAddPlot ( GPLOT gplot,
NUMA nax,
NUMA nay,
l_int32  plotstyle,
const char *  plotlabel 
)

gplotAddPlot()

Parameters
[in]gplot
[in]nax[optional] numa: set to null for Y_VS_I; required for Y_VS_X
[in]naynuma; required for both Y_VS_I and Y_VS_X
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]plotlabel[optional] label for individual plot
Returns
0 if OK, 1 on error
Notes:
     (1) There are 2 options for (x,y) values:
           o  To plot an array vs a linear function of the
              index, set nax = NULL.
           o  To plot one array vs another, use both nax and nay.
     (2) If nax is NULL, the x value corresponding to the i-th
         value of nay is found from the startx and delx fields
         in nay:
              x = startx + i * delx
         These are set with numaSetParameters().  Their default
         values are startx = 0.0, delx = 1.0.
     (3) If nax is defined, it must be the same size as nay, and
         must have at least one number.
     (4) The 'plotlabel' string can have spaces, double
         quotes and backquotes, but not single quotes.

Definition at line 316 of file gplot.c.

◆ gplotCreate()

GPLOT* gplotCreate ( const char *  rootname,
l_int32  outformat,
const char *  title,
const char *  xlabel,
const char *  ylabel 
)

gplotCreate()

Parameters
[in]rootnameroot for all output files
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]title[optional] overall title
[in]xlabel[optional] x axis label
[in]ylabel[optional] y axis label
Returns
gplot, or NULL on error
Notes:
     (1) This initializes the plot.
     (2) The 'title', 'xlabel' and 'ylabel' strings can have spaces,
         double quotes and backquotes, but not single quotes.

Definition at line 187 of file gplot.c.

Referenced by boxaPlotSides(), boxaPlotSizes(), numaQuantizeCrossingsByWidth(), and pixSplitDistributionFgBg().

◆ gplotDestroy()

void gplotDestroy ( GPLOT **  pgplot)

◆ gplotGenCommandFile()

l_ok gplotGenCommandFile ( GPLOT gplot)

gplotGenCommandFile()

Parameters
[in]gplot
Returns
0 if OK, 1 on error

Definition at line 497 of file gplot.c.

◆ gplotGenDataFiles()

l_ok gplotGenDataFiles ( GPLOT gplot)

gplotGenDataFiles()

Parameters
[in]gplot
Returns
0 if OK, 1 on error
Notes:
     (1) The pathnames in the gplot command file are actual pathnames,
         which can be in temp directories.  Consequently, they must not be
         rewritten by calling fopenWriteStream(), and we use fopen().

Definition at line 603 of file gplot.c.

References GPlot::datanames, L_NOCOPY, GPlot::plotdata, sarrayGetCount(), and sarrayGetString().

◆ gplotGeneralPix1()

PIX* gplotGeneralPix1 ( NUMA na,
l_int32  plotstyle,
const char *  rootname,
const char *  title,
const char *  xlabel,
const char *  ylabel 
)

gplotGeneralPix1()

Parameters
[in]nadata array
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]rootnameroot for all output files
[in]title[optional] overall title
[in]xlabel[optional] x axis label
[in]ylabel[optional] y axis label
Returns
pix of plot, or NULL on error
Notes:
     (1) The 'title', 'xlabel' and 'ylabel' strings can have spaces,
         double quotes and backquotes, but not single quotes.

Definition at line 1054 of file gplot.c.

◆ gplotGeneralPix2()

PIX* gplotGeneralPix2 ( NUMA na1,
NUMA na2,
l_int32  plotstyle,
const char *  rootname,
const char *  title,
const char *  xlabel,
const char *  ylabel 
)

gplotGeneralPix2()

Parameters
[in]na1x-axis data array
[in]na2y-axis data array
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]rootnameroot for all output files
[in]title[optional] overall title
[in]xlabel[optional] x axis label
[in]ylabel[optional] y axis label
Returns
pix of plot, or NULL on error
Notes:
     (1) The 'title', 'xlabel' and 'ylabel' strings can have spaces,
         double quotes and backquotes, but not single quotes.

Definition at line 1101 of file gplot.c.

◆ gplotGeneralPixN()

PIX* gplotGeneralPixN ( NUMA nax,
NUMAA naay,
l_int32  plotstyle,
const char *  rootname,
const char *  title,
const char *  xlabel,
const char *  ylabel 
)

gplotGeneralPixN()

Parameters
[in]naxx-axis data array
[in]naayarray of y-axis data arrays
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]rootnameroot for all output files
[in]title[optional] overall title
[in]xlabel[optional] x axis label
[in]ylabel[optional] y axis label
Returns
pix of plot, or NULL on error
Notes:
     (1) The 'title', 'xlabel' and 'ylabel' strings can have spaces,
         double quotes and backquotes, but not single quotes.

Definition at line 1151 of file gplot.c.

References numaaGetCount().

◆ gplotMakeOutput()

l_ok gplotMakeOutput ( GPLOT gplot)

gplotMakeOutput()

Parameters
[in]gplot
Returns
0 if OK; 1 on error
Notes:
     (1) This uses gplot and the new arrays to add a plot
         to the output, by writing a new data file and appending
         the appropriate plot commands to the command file.
     (2) Along with gplotMakeOutputPix(), these are the only functions
         in this file that requires the gnuplot executable to
         actually generate the plot.
     (3) The command file name for unix is canonical (i.e., directory /tmp)
         but the temp filename paths in the command file must be correct.
     (4) The gnuplot program for Windows is wgnuplot.exe.

Definition at line 456 of file gplot.c.

◆ gplotMakeOutputPix()

PIX* gplotMakeOutputPix ( GPLOT gplot)

gplotMakeOutputPix()

Parameters
[in]gplot
Returns
0 if OK; 1 on error
Notes:
     (1) This wraps gplotMakeOutput(), and returns a pix.
         See gplotMakeOutput() for details.
     (2) The gplot output format must be an image (png or pnm).

Definition at line 423 of file gplot.c.

References GPlot::outformat.

◆ gplotRead()

GPLOT* gplotRead ( const char *  filename)

gplotRead()

Parameters
[in]filename
Returns
gplot, or NULL on error

Definition at line 1199 of file gplot.c.

◆ gplotSetScaling()

l_ok gplotSetScaling ( GPLOT gplot,
l_int32  scaling 
)

gplotSetScaling()

Parameters
[in]gplot
[in]scalingGPLOT_LINEAR_SCALE, GPLOT_LOG_SCALE_X, GPLOT_LOG_SCALE_Y, GPLOT_LOG_SCALE_X_Y
Returns
0 if OK; 1 on error
Notes:
     (1) By default, the x and y axis scaling is linear.
     (2) Call this function to set semi-log or log-log scaling.

Definition at line 394 of file gplot.c.

References GPLOT_LINEAR_SCALE.

◆ gplotSimple1()

l_ok gplotSimple1 ( NUMA na,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimple1()

Parameters
[in]nanuma; plot Y_VS_I
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional], can be NULL
Returns
0 if OK, 1 on error
Notes:
     (1) This generates a line plot of a numa, where the array value
         is plotted vs the array index.  The plot is generated
         in the specified output format; the title  is optional.
     (2) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.

Definition at line 649 of file gplot.c.

References gplotSimpleXY1().

Referenced by numaSplitDistribution(), and pixGetDifferenceStats().

◆ gplotSimple2()

l_ok gplotSimple2 ( NUMA na1,
NUMA na2,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimple2()

Parameters
[in]na1numa; plot with Y_VS_I
[in]na2ditto
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional]
Returns
0 if OK, 1 on error
Notes:
     (1) This generates a line plot of two numa, where the array values
         are each plotted vs the array index.  The plot is generated
         in the specified output format; the title  is optional.
     (2) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.

Definition at line 685 of file gplot.c.

References gplotSimpleXY2().

Referenced by compareTilesByHisto(), and pixCompareTilesByHisto().

◆ gplotSimpleN()

l_ok gplotSimpleN ( NUMAA naa,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimpleN()

Parameters
[in]naanumaa; plot Y_VS_I for each numa
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional]
Returns
0 if OK, 1 on error
Notes:
     (1) This generates a line plot of all numas in a numaa (array of numa),
         where the array values are each plotted vs the array index.
         The plot is generated in the specified output format;
         the title  is optional.
     (2) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.

Definition at line 723 of file gplot.c.

References gplotSimpleXYN().

◆ gplotSimplePix1()

PIX* gplotSimplePix1 ( NUMA na,
const char *  title 
)

gplotSimplePix1()

Parameters
[in]nanuma; plot Y_VS_I
[in]title[optional], can be NULL
Returns
pix of plot, or null on error
Notes:
     (1) This generates a line plot of a numa as a pix, where the array
         value is plotted vs the array index.  The title is optional.
     (2) The temporary plot file is a png; its name is generated internally
         and stored in gplot.

Definition at line 754 of file gplot.c.

References gplotSimpleXY1(), and lept_mkdir().

◆ gplotSimplePix2()

PIX* gplotSimplePix2 ( NUMA na1,
NUMA na2,
const char *  title 
)

gplotSimplePix2()

Parameters
[in]na1numa; plot with Y_VS_I
[in]na2ditto
[in]title[optional], can be NULL
Returns
pix of plot, or null on error
Notes:
     (1) This generates a pix with line plots of two numa, where each of
         two arrays is plotted vs the array index.  the title is optional.
     (2) The temporary plot file is a png; its name is generated internally
         and stored in gplot.

Definition at line 795 of file gplot.c.

References gplotSimpleXY2(), and lept_mkdir().

◆ gplotSimplePixN()

PIX* gplotSimplePixN ( NUMAA naa,
const char *  title 
)

gplotSimplePixN()

Parameters
[in]naanumaa; plot Y_VS_I for each numa
[in]title[optional], can be NULL
Returns
pix of plot, or null on error
Notes:
     (1) This generates a pix with an arbitrary number of line plots,
         each coming from a numa in naa.  Each array value is plotted
         vs the array index.  The title is optional.
     (2) The temporary plot file is a png; its name is generated internally
         and stored in gplot.

Definition at line 837 of file gplot.c.

References gplotSimpleXYN(), and lept_mkdir().

◆ gplotSimpleXY1()

GPLOT* gplotSimpleXY1 ( NUMA nax,
NUMA nay,
l_int32  plotstyle,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimpleXY1()

Parameters
[in]nax[optional]
[in]nay[required]
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional], can be NULL
Returns
gplot or null on error
Notes:
     (1) This generates a plot of a nay vs nax, generated in
         the specified output format.  The title is optional.
     (2) Use 0 for default plotstyle (lines).
     (3) nax is optional.  If NULL, nay is plotted against
         the array index.
     (4) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.
     (5) The returned gplot must be destroyed by the caller.

Definition at line 887 of file gplot.c.

Referenced by gplotSimple1(), and gplotSimplePix1().

◆ gplotSimpleXY2()

GPLOT* gplotSimpleXY2 ( NUMA nax,
NUMA nay1,
NUMA nay2,
l_int32  plotstyle,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimpleXY2()

Parameters
[in]nax[optional], can be NULL
[in]nay1
[in]nay2
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional]
Returns
gplot or null on error
Notes:
     (1) This generates plots of nay1 and nay2 against nax, generated
         in the specified output format.  The title is optional.
     (2) Use 0 for default plotstyle (lines).
     (3) nax is optional.  If NULL, nay1 and nay2 are plotted
         against the array index.
     (4) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.
     (5) The returned gplot must be destroyed by the caller.

Definition at line 942 of file gplot.c.

Referenced by gplotSimple2(), and gplotSimplePix2().

◆ gplotSimpleXYN()

GPLOT* gplotSimpleXYN ( NUMA nax,
NUMAA naay,
l_int32  plotstyle,
l_int32  outformat,
const char *  outroot,
const char *  title 
)

gplotSimpleXYN()

Parameters
[in]nax[optional]; can be NULL
[in]naaynumaa of arrays to plot against nax
[in]plotstyleGPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]outformatGPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX, GPLOT_PNM
[in]outrootroot of output files
[in]title[optional]
Returns
gplot or null on error
Notes:
     (1) This generates plots of each Numa in naa against nax,
         generated in the specified output format.  The title is optional.
     (2) Use 0 for default plotstyle (lines).
     (3) nax is optional.  If NULL, each Numa array is plotted against
         the array index.
     (4) When calling these simple plot functions more than once, use
         different outroot to avoid overwriting the output files.
     (5) The returned gplot must be destroyed by the caller.

Definition at line 999 of file gplot.c.

References numaaGetCount().

Referenced by gplotSimpleN(), and gplotSimplePixN().

◆ gplotWrite()

l_ok gplotWrite ( const char *  filename,
GPLOT gplot 
)

gplotWrite()

Parameters
[in]filename
[in]gplot
Returns
0 if OK; 1 on error

Definition at line 1282 of file gplot.c.

References fopenWriteStream().

Variable Documentation

◆ gplotfileoutputs

const char* gplotfileoutputs[]
Initial value:
= {"",
"PNG",
"PS",
"EPS",
"LATEX",
"PNM"}

used in simple file input

Definition at line 157 of file gplot.c.

◆ gplotstylenames

const char* gplotstylenames[]
Initial value:
= {"with lines",
"with points",
"with impulses",
"with linespoints",
"with dots"}

used in gnuplot cmd file

Definition at line 152 of file gplot.c.