Plotting of CPL objects

Functions
cpl_error_code	cpl_plot_bivector (const char *pre, const char *options, const char *post, const cpl_bivector *bivector)
	Plot a bivector.
cpl_error_code	cpl_plot_bivectors (const char *pre, const char **options, const char *post, const cpl_bivector **bivectors, cpl_size nbvec)
	Plot an array of bivectors.
cpl_error_code	cpl_plot_column (const char *pre, const char *options, const char *post, const cpl_table *tab, const char *xlab, const char *ylab)
	Plot a column of a table.
cpl_error_code	cpl_plot_columns (const char *pre, const char *options, const char *post, const cpl_table *tab, const char **labels, cpl_size nlabels)
	Plot severals column of a table.
cpl_error_code	cpl_plot_image (const char *pre, const char *options, const char *post, const cpl_image *image)
	Plot an image.
cpl_error_code	cpl_plot_image_col (const char *pre, const char *options, const char *post, const cpl_image *image, cpl_size firstcol, cpl_size lastcol, cpl_size colstep)
	Plot a range of image columns.
cpl_error_code	cpl_plot_image_row (const char *pre, const char *options, const char *post, const cpl_image *image, cpl_size firstrow, cpl_size lastrow, cpl_size rowstep)
	Plot a range of image rows.
cpl_error_code	cpl_plot_mask (const char *pre, const char *options, const char *post, const cpl_mask *mask)
	Plot a mask.
cpl_error_code	cpl_plot_vector (const char *pre, const char *options, const char *post, const cpl_vector *vector)
	Plot a vector.
cpl_error_code	cpl_plot_vectors (const char *pre, const char *options, const char *post, const cpl_vector **vectors, cpl_size nvec)
	Plot an array of vectors.

Detailed Description

This module provides functions to plot basic CPL objects

This module is offered to help during the development process. The functions offered should NOT be used in any operational environment. For that reason, the support of those remains limited, and no functionality extension can be expected from the CPL team.

The created plot windows can be closed by pressing the 'q' key like you would do with a normal gnuplot window.

The default behaviour of the plotting is to use gnuplot (with option -persist). The user can control the actual plotting-command used to create the plot by setting the environment variable CPL_PLOTTER. Currently, if CPL_PLOTTER is set it must contain the string 'gnuplot'. Setting it to 'cat > my_gnuplot_$$.txt' causes a number of ASCII-files to be created, which each produce a plot when given as standard input to gnuplot.

A finer control of the plotting options can be obtained by writing an executable script, e.g. my_gnuplot, that executes gnuplot after setting the desired gnuplot options (e.g. set terminal pslatex color) and then setting CPL_PLOTTER to my_gnuplot.

Images can be plotted not only with gnuplot, but also using the pnm format. This is controlled with the environment variable CPL_IMAGER. If CPL_IMAGER is set to a string that does not contain the word gnuplot, the recipe will generate the plot in pnm format. E.g. setting CPL_IMAGER to 'display - &' will produce a gray-scale image using the image viewer display.

#include "cpl_plot.h"

Function Documentation

cpl_plot_bivector()

cpl_error_code cpl_plot_bivector	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_bivector *	bivector
	)

Plot a bivector.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
bivector	The bivector to plot

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The bivector must have a positive number of elements.

See also

also cpl_mplot_open().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_bivector_get_size(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y_data_const(), CPL_ERROR_NONE, cpl_free(), CPL_SIZE_FORMAT, and cpl_sprintf().

Referenced by cpl_plot_column().

cpl_plot_bivectors()

cpl_error_code cpl_plot_bivectors	(	const char *	pre,
		const char **	options,
		const char *	post,
		const cpl_bivector **	bivectors,
		cpl_size	nbvec
	)

Plot an array of bivectors.

Parameters

pre	An optional string with pre-plot commands
options	Array of strings with plotting options
post	An optional string with post-plot commands
bivectors	The bivectors array to plot
nbvec	The number of bivectors, at least one is required

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

Each bivector in the array defines a sequence of points to be plotted. The bivectors can have different size.

The options array must be of same size as the bivectors array. The i'th string in the array specifies the plotting options for the i'th bivector.

See also

also cpl_mplot_open().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_DATA_NOT_FOUND
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_bivector_get_size(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y_data_const(), cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_FILE_IO, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_malloc(), CPL_SIZE_FORMAT, and cpl_sprintf().

cpl_plot_column()

cpl_error_code cpl_plot_column	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_table *	tab,
		const char *	xlab,
		const char *	ylab
	)

Plot a column of a table.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
tab	The table to plot
xlab	The label of the column used in x
ylab	The label of the column used in y

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

See also

also cpl_mplot_open().

If xlab is NULL, the sequence number is used for X.

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_DATA_NOT_FOUND
• CPL_ERROR_INVALID_TYPE
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_bivector_unwrap_vectors(), cpl_bivector_wrap_vectors(), cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_plot_bivector(), cpl_table_cast_column(), cpl_table_count_invalid(), cpl_table_delete(), cpl_table_duplicate_column(), cpl_table_erase_invalid(), cpl_table_get_column_type(), cpl_table_get_data_double(), cpl_table_get_data_double_const(), cpl_table_get_nrow(), cpl_table_has_column(), cpl_table_new(), CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT, cpl_vector_delete(), cpl_vector_duplicate(), cpl_vector_get_size(), cpl_vector_set(), cpl_vector_unwrap(), and cpl_vector_wrap().

cpl_plot_columns()

cpl_error_code cpl_plot_columns	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_table *	tab,
		const char **	labels,
		cpl_size	nlabels
	)

Plot severals column of a table.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
tab	The table to plot
labels	The labels of the columns
nlabels	The number of labels

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

See also

also cpl_mplot_open().

If xlab is NULL, the sequence number is used for X.

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_DATA_NOT_FOUND
• CPL_ERROR_INVALID_TYPE
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_FILE_IO, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_malloc(), CPL_SIZE_FORMAT, cpl_sprintf(), cpl_table_cast_column(), cpl_table_delete(), cpl_table_duplicate_column(), cpl_table_erase_column(), cpl_table_get_column_type(), cpl_table_get_data_double_const(), cpl_table_get_nrow(), cpl_table_has_column(), cpl_table_new(), CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, and CPL_TYPE_INT.

cpl_plot_image()

cpl_error_code cpl_plot_image	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_image *	image
	)

Plot an image.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
image	The image to plot

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The image must have a positive number of pixels.

See also

also cpl_image_open().

If the specified plotting command does not contain the string 'gnuplot', the plotting command is assumed to be able to parse a pgm (P5) image from stdin. Valid examples of such a command may include 'cat > myplot$$.pgm' and 'display - &'.

The 'pre' and 'post' commands are ignored in PGM-plots, while the 'options' string is written as a comment in the header of the image.

See also cpl_plot_vector().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References CPL_ERROR_NONE, cpl_free(), cpl_image_cast(), cpl_image_delete(), cpl_image_get_data_double(), cpl_image_get_data_double_const(), cpl_image_get_max(), cpl_image_get_min(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_multiply_scalar(), cpl_image_subtract_scalar(), cpl_image_subtract_scalar_create(), cpl_malloc(), CPL_SIZE_FORMAT, cpl_sprintf(), and CPL_TYPE_DOUBLE.

cpl_plot_image_col()

cpl_error_code cpl_plot_image_col	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_image *	image,
		cpl_size	firstcol,
		cpl_size	lastcol,
		cpl_size	colstep
	)

Plot a range of image columns.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
image	The image to plot
firstcol	The first column to plot (1 for first)
lastcol	The last column to plot
colstep	The positive column stride

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The image must have a positive number of pixels.

lastcol shall be greater than or equal to firstcol.

See also

also cpl_mplot_open().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_ACCESS_OUT_OF_RANGE (firstcol or lastcol are out of range)
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_image_cast(), cpl_image_delete(), cpl_image_get_data_double_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), CPL_SIZE_FORMAT, cpl_sprintf(), and CPL_TYPE_DOUBLE.

cpl_plot_image_row()

cpl_error_code cpl_plot_image_row	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_image *	image,
		cpl_size	firstrow,
		cpl_size	lastrow,
		cpl_size	rowstep
	)

Plot a range of image rows.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
image	The image to plot
firstrow	The first row to plot (1 for first)
lastrow	The last row to plot
rowstep	The positive row stride

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The image must have a positive number of pixels.

lastrow shall be greater than or equal to firstrow.

See also

also cpl_mplot_open().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_ACCESS_OUT_OF_RANGE (firstrow or lastrow are out of range)
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_image_cast(), cpl_image_delete(), cpl_image_get_data_double_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), CPL_SIZE_FORMAT, cpl_sprintf(), and CPL_TYPE_DOUBLE.

cpl_plot_mask()

cpl_error_code cpl_plot_mask	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_mask *	mask
	)

Plot a mask.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
mask	The mask to plot

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

If the specified plotting command does not contain the string 'gnuplot', the plotting command is assumed to be able to parse a pgm (P5) mask from stdin. Valid examples of such a command may include 'cat > myplot$$.pgm' and 'display - &'.

The 'pre' and 'post' commands are ignored in PGM-plots, while the 'options' string is written as a comment in the header of the mask.

See also cpl_plot_vector().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References CPL_ERROR_NONE, cpl_free(), cpl_malloc(), cpl_mask_get_data_const(), cpl_mask_get_size_x(), cpl_mask_get_size_y(), CPL_SIZE_FORMAT, and cpl_sprintf().

cpl_plot_vector()

cpl_error_code cpl_plot_vector	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_vector *	vector
	)

Plot a vector.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
vector	The vector to plot

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The vector must have a positive number of elements.

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References CPL_ERROR_NONE, cpl_free(), CPL_SIZE_FORMAT, cpl_sprintf(), cpl_vector_get_data_const(), and cpl_vector_get_size().

cpl_plot_vectors()

cpl_error_code cpl_plot_vectors	(	const char *	pre,
		const char *	options,
		const char *	post,
		const cpl_vector **	vectors,
		cpl_size	nvec
	)

Plot an array of vectors.

Parameters

pre	An optional string with pre-plot commands
options	An optional string with plotting options
post	An optional string with post-plot commands
vectors	The vectors array to plot
nvec	The number of vectors

Returns

CPL_ERROR_NONE or the relevant CPL_ERROR_# on error

The array should contain at least 3 vectors, the first one can be NULL.

The non-NULL vectors must have the same number of elements. The first vector gives the x-axis. If NULL, the index is used.

See also

also cpl_mplot_open().

Possible cpl_error_code set in this function:

• CPL_ERROR_FILE_IO
• CPL_ERROR_NULL_INPUT
• CPL_ERROR_ILLEGAL_INPUT
• CPL_ERROR_UNSUPPORTED_MODE if plotting is unsupported on the specific run-time system.

References cpl_ensure_code, CPL_ERROR_FILE_IO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_malloc(), CPL_SIZE_FORMAT, cpl_sprintf(), cpl_vector_get_data_const(), and cpl_vector_get_size().