Loading...
Searching...
No Matches
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().