#include <string.h>
#include "allheaders.h"

Functions
GPLOT *	gplotCreate (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 plottitle)

l_ok	gplotSetScaling (GPLOT *gplot, l_int32 scaling)

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)

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

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

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

GPLOT *	gplotRead (const char *filename)

l_ok	gplotWrite (const char filename, GPLOT gplot)

Variables
static const l_int32	L_BUFSIZE = 512

const char *	gplotstylenames []

const char *	gplotfileoutputs []

Detailed Description

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

Quick and dirty plots
     l_int32     gplotSimple1()
     l_int32     gplotSimple2()
     l_int32     gplotSimpleN()
     l_int32     gplotSimpleXY1()
     l_int32     gplotSimpleXY2()
     l_int32     gplotSimpleXYN()

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 graph
    ~ optional x and y axis labels
    ~ multiple plots on one frame
    ~ optional title for each plot on the frame
    ~ optional log scaling on either or both axes
    ~ choice of 5 plot styles for each plot
    ~ choice of 2 plot modes, either using one input array
      (Y vs index) or two input arrays (Y vs X).  This
      choice is made implicitly depending on the number of
      input arrays.

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);

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 *	plottitle
	)

gplotAddPlot()

Parameters

[in]	gplot
[in]	nax	[optional] numa: set to null for Y_VS_I; required for Y_VS_X
[in]	nay	numa: required for both Y_VS_I and Y_VS_X
[in]	plotstyle	GPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]	plottitle	[optional] title 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 'plottitle' string can have spaces, double
         quotes and backquotes, but not single quotes.

Definition at line 263 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]	rootname	root for all output files
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[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 138 of file gplot.c.

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

◆ gplotDestroy()

void gplotDestroy ( GPLOT ** pgplot )

gplotDestroy()

Parameters

[in,out] pgplot to be nulled

Definition at line 197 of file gplot.c.

References GPlot::cmddata, GPlot::cmdname, GPlot::datanames, numaDestroy(), GPlot::outname, GPlot::plotdata, GPlot::plotstyles, GPlot::plottitles, GPlot::rootname, sarrayDestroy(), GPlot::title, GPlot::xlabel, and GPlot::ylabel.

◆ gplotGenCommandFile()

l_ok gplotGenCommandFile ( GPLOT * gplot )

gplotGenCommandFile()

Parameters

[in] gplot

Returns: 0 if OK, 1 on error

Definition at line 422 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 528 of file gplot.c.

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

◆ 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) This is the only function 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 379 of file gplot.c.

◆ gplotRead()

GPLOT* gplotRead ( const char * filename )

gplotRead()

Parameters

[in] filename

Returns: gplot, or NULL on error

Definition at line 827 of file gplot.c.

◆ gplotSetScaling()

l_ok gplotSetScaling	(	GPLOT *	gplot,
		l_int32	scaling
	)

gplotSetScaling()

Parameters

[in]	gplot
[in]	scaling	GPLOT_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 343 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]	na	numa; plot Y_VS_I
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional], can be NULL

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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 575 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]	na1	numa; plotted with Y_VS_I
[in]	na2	ditto
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional]

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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 604 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]	naa	numaa; we plotted with Y_VS_I for each numa
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional]

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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 635 of file gplot.c.

References gplotSimpleXYN().

◆ gplotSimpleXY1()

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

gplotSimpleXY1()

Parameters

[in]	nax	[optional]
[in]	nay
[in]	plotstyle	GPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional], can be NULL

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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.

Definition at line 668 of file gplot.c.

Referenced by gplotSimple1().

◆ gplotSimpleXY2()

l_ok 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]	plotstyle	GPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional]

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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.

Definition at line 723 of file gplot.c.

Referenced by gplotSimple2().

◆ gplotSimpleXYN()

l_ok 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]	naay	numaa of arrays to plot against nax
[in]	plotstyle	GPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS
[in]	outformat	GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_LATEX
[in]	outroot	root of output files
[in]	title	[optional]

Returns: 0 if OK, 1 on error

Notes:
     (1) This gives 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.

Definition at line 779 of file gplot.c.

References numaaGetCount().

Referenced by gplotSimpleN().

◆ 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 912 of file gplot.c.

References fopenWriteStream().

Variable Documentation

◆ gplotfileoutputs

const char* gplotfileoutputs[]

Initial value:

used in simple file input

Definition at line 110 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 105 of file gplot.c.

Functions

Variables

Detailed Description

Function Documentation

◆ gplotAddPlot()

◆ gplotCreate()

◆ gplotDestroy()

◆ gplotGenCommandFile()

◆ gplotGenDataFiles()

◆ gplotMakeOutput()

◆ gplotRead()

◆ gplotSetScaling()

◆ gplotSimple1()

◆ gplotSimple2()

◆ gplotSimpleN()

◆ gplotSimpleXY1()

◆ gplotSimpleXY2()

◆ gplotSimpleXYN()

◆ gplotWrite()

Variable Documentation

◆ gplotfileoutputs

◆ gplotstylenames