Module Gr

This module contains the bindings to the lowlevel C interface.

Available line types, see also GR Line Types

Available marker types, see also GR Marker Types

Pattern style, see also GR Fill Patterns and Hatches

Hatch style, see also GR Fill Patterns and Hatches

Color Maps, see also GR Color Maps

set_window xmin xmax ymin ymax establishes a window, or rectangular subspace, of world coordinates to be plotted. If you desire log scaling or mirror-imaging of axes, use the gr_setscale function.

This function defines the rectangular portion of the World Coordinate space (WC) to be associated with the specified normalization transformation. The WC window and the Normalized Device Coordinates (NDC) viewport define the normalization transformation through which all output primitives are mapped. The WC window is mapped onto the rectangular NDC viewport which is, in turn, mapped onto the display surface of the open and active workstation, in device coordinates. By default, GR uses the range [0,1] x [0,1], in world coordinates, as the normalization transformation window.

Parameters

• xmin: The left horizontal coordinate of the window (xmin < xmax).
• xmax: The right horizontal coordinate of the window (xmin < xmax).
• ymin: The bottom vertical coordinate of the window (ymin < ymax).
• ymax: The top vertical coordinate of the window (ymin < ymax).

set_viewport xmin xmax ymin ymax establishes a rectangular subspace of normalized device coordinates.

This function defines the rectangular portion of the Normalized Device Coordinate (NDC) space to be associated with the specified normalization transformation. The NDC viewport and World Coordinate (WC) window define the normalization transformation through which all output primitives pass. The WC window is mapped onto the rectangular NDC viewport which is, in turn, mapped onto the display surface of the open and active workstation, in device coordinates.

Parameters

• xmin: The left horizontal coordinate of the viewport (0 <= xmin < xmax).
• xmax: The right horizontal coordinate of the viewport (xmin < xmax <= 1).
• ymin: The bottom vertical coordinate of the viewport (0 <= ymin < ymax).
• ymax: The top vertical coordinate of the viewport (ymin < ymax <= 1).

select_transformation transform selects a predefined transformation from world coordinates to normalized device coordinates.

Parameters

• transform: A normalization transformation number:

  • 0 selects the identity transformation in which both the window and viewport have the range of 0 to 1;
  • >= 1 selects a normalization transformation as defined by set_window and set_viewport.

clip indicator sets the clipping indicator. This function enables or disables clipping of the image drawn in the current window. Clipping is defined as the removal of those portions of the graph that lie outside of the defined viewport. If clipping is on, GR does not draw generated output primitives past the viewport boundaries. If clipping is off, primitives may exceed the viewport boundaries, and they will be drawn to the edge of the workstation window. By default, clipping is on.

Parameters

• indicator: An indicator specifying whether clipping is on or off.

  • false clipping is off. Data outside of the window will be drawn.
  • true clipping is on. Data outside of the window will not be drawn.

set_space zmin zmax rotation tilt sets the abstract Z-space used for mapping three-dimensional output primitives into the current world coordinate space.

This function establishes the limits of an abstract Z-axis and defines the angles for rotation and for the viewing angle (tilt) of a simulated three-dimensional graph, used for mapping corresponding output primitives into the current window. These settings are used for all subsequent three-dimensional output primitives until other values are specified. Angles of rotation and viewing angle must be specified between 0 and 90 degrees.

Parameters

• zmin: Minimum value for the Z-axis.
• zmax: Maximum value for the Z-axis.
• rotation: Angle for the rotation of the X axis, in degrees.
• tilt: Viewing angle of the Z axis, in degrees.

set_linewidth lw defines the line width of subsequent polyline output primitives.

The line width is calculated as the nominal line width generated on the workstation multiplied by the line width scale factor. This value is mapped by the workstation to the nearest available line width. The default line width is 1.0, or 1 times the line width generated on the graphics device.

set_linecolorindex c defines the color of subsequent polyline output primitives. Note: c < 1256

set_markersize ms specify the marker size for polymarkers.

The polymarker size is calculated as the nominal size generated on the graphics device multiplied by the marker size scale factor.

set_markercolorindex c define the color of subsequent markers output primitives. Note: c < 1256

set_arrowsize size sets the arrow size to be used for subsequent arrow commands.

This function defines the arrow size for subsequent arrow primitives. The default arrow size is 1.

Parameters

• size: The arrow size to be used

set_text_font_prec ?precision font specifies the text font and precision for subsequent text output primitives.

The appearance of a font depends on the text precision value specified. STRING, CHARACTER or STROKE precision allows for a greater or lesser realization of the text primitives, for efficiency. STRING is the default precision for GR and produces the highest quality output.

XXX: CHARACTER and STROKE precision seem to be broken (and to break the axes command with it...)!

set_char_expand_factor factor sets the current character expansion factor (width to height ratio).

This function defines the width of subsequent text output primitives. The expansion factor alters the width of the generated characters, but not their height. The default text expansion factor is 1, or one times the normal width-to-height ratio of the text.

Parameters

• factor: Text expansion factor applied to the nominal text width-to-height ratio

set_text_colorindex color sets the current text color index.

This function defines the color of subsequent text output primitives. GR uses the default foreground color (black=1) for the default text color index.

Parameters

• color: The text color index (COLOR < 1256)

set_char_height height sets the current character height.

This function defines the height of subsequent text output primitives. Text height is defined as a percentage of the default window. GR uses the default text height of 0.027 (2.7% of the height of the default window).

set_char_up (x, y) Set the current character text angle up vector. This function defines the vertical rotation of subsequent text output primitives. The text up vector is initially set to (0, 1), horizontal to the baseline.

Parameters

• x: X coordinate of the text up vector
• y: Y coordinate of the text up vector

set_text_path direction defines the current direction in which subsequent text will be drawn.

set_text_align horizontal vertical specifies how the characters in a text primitive will be aligned in horizontal and vertical space. The default text alignment indicates horizontal left alignment and vertical baseline alignment.

set_fill_interior_style style sets the fill area interior style to be used for fill areas.

This function defines the interior style for subsequent fill area output primitives. The default interior style is HOLLOW.

set_fill_colorindex color sets the current fill area color index.

This function defines the color of subsequent fill area output primitives. GR uses the default foreground color (black=1) for the default fill area color index.

Parameters

• color: The fill area color index (COLOR < 1256)

set_color_representation index (red, green, blue) redefines an existing color index representation by specifying an RGB color triplet.

Parameters

• index: Color index in the range 0 to 1256
• red: Red intensity in the range 0.0 to 1.0
• green: Green intensity in the range 0.0 to 1.0
• blue: Blue intensity in the range 0.0 to 1.0

set_colormap cmap sets the currently used colormap.

A list of colormaps can be found at: GR Colormaps.

set_shadow (offsetx, offsety) blur Allows drawing of shadows, realized by images painted underneath, and offset from, graphics objects such that the shadow mimics the effect of a light source cast on the graphics objects.

Parameters

• offsetx: An x-offset, which specifies how far in the horizontal direction the shadow is offset from the object
• offsety: A y-offset, which specifies how far in the vertical direction the shadow is offset from the object
• blur: A blur value, which specifies whether the object has a hard or a diffuse edge

set_transparency alpha sets the value of the alpha component associated with GR colors.

Parameters

• alpha: An alpha value (0.0 - 1.0)

set_coord_transform transform Change the coordinate transformation according to the given matrix. Parameters

• mat: 2D transformation matrix (3x2)

polyline ?linetype ?linewidth ?coloridx x y draws a polyline using the current line attributes, starting from the first data point and ending at the last data point.

The values for x and y are in world coordinates. The attributes that control the appearance of a polyline are linetype, linewidth and color index.

polyline3d ?linetype ?linewidth ?coloridx x y z draws a polyline using the current line attributes, starting from the first data point and ending at the last data point.

The values for x, y and z are in world coordinates. The attributes that control the appearance of a polyline are linetype, linewidth and color index.

polymarker ?markertype ?markersize ?coloridx x y draws marker symbols centered at the given data points.

The values for x and y are in world coordinates. The attributes that control the appearance of a polyline are markertype, markersize and color index.

polymarker3d ?markertype ?markersize ?coloridx x y z draws marker symbols centered at the given data points.

The values for x, y and z are in world coordinates. The attributes that control the appearance of a polyline are markertype, markersize and color index.

text x y content draws a text at position x, y using the current text attributes.

The values for x and y are in normalized device coordinates. The attributes that control the appearance of text are text font and precision, character expansion factor, character spacing, text color index, character height, character up vector, text path and text alignment.

(* TODO: add styling options *)

fillarea x y allows you to specify a polygonal shape of an area to be filled. The vectors x and y specify the coordinates of the polygonal shape corners.

The attributes that control the appearance of fill areas are fill area interior style, fill area style index and fill area color index. (* TODO: add styling options *)

cellarray (xmin, xmax) (ymin, ymax) (dimx, dimy) (scol, srow) (ncol, nrow) color displays rasterlike images in a device-independent manner. The cell array function partitions a rectangle given by two corner points into DIMX X DIMY cells, each of them colored individually by the corresponding color index of the given cell array.

The values for xmin, xmax, ymin and ymax are in world coordinates.

Parameters

• xmin: X coordinate of the lower left point of the rectangle
• ymin: Y coordinate of the lower left point of the rectangle
• xmax: X coordinate of the upper right point of the rectangle
• ymax: Y coordinate of the upper right point of the rectangle
• dimx: X dimension of the color index array
• dimy: Y dimension of the color index array
• scol: number of leading columns in the color index array
• srow: number of leading rows in the color index array
• ncol: total number of columns in the color index array
• nrow: total number of rows in the color index array
• color: color index array

Note: nonuniformcellarray and polycellarray have been introduced in newer versions of gr.

spline ?linetype ?linewidth ?coloridx x y m method_t generates a cubic spline-fit, starting from the first data point and ending at the last data point.

The values for x and y are in world coordinates. The attributes that control the appearance of a spline-fit are linetype, linewidth and color index.

Parameters

• x: The X coordinates
• y: The Y coordinates
• m: The number of points in the polygon to be drawn
• method: The smoothing method

gridit x y z (nx, ny) interpolates data from arbitrary points at points on a rectangular grid.

Parameters

• x: The X coordinates of the input points
• y: The Y coordinates of the input points
• z: The values of the points
• nx: The number of points in X direction for the output grid
• ny: The number of points in Y direction for the output grid

Returns the tuple (x', y', z') with

• x': The points in X direction for the output grid
• y': The points in Y direction for the output grid
• z': The interpolated values on the nx x ny grid points

tex_text (x, y) text draws a text at position x, y using the current text attributes. Strings can be defined to create basic mathematical expressions and Greek letters.

The values for X and Y are in normalized device coordinates. The attributes that control the appearance of text are text font and precision, character expansion factor, character spacing, text color index, character height, character up vector, text path and text alignment.

Parameters

• x: The X coordinate of starting position of the text string
• y: The Y coordinate of starting position of the text string
• text: The text to be drawn

The character string is interpreted to be a simple mathematical formula. The following notations apply:

• Subscripts and superscripts: These are indicated by carets (‘^’) and underscores (‘_’). If the sub/superscript contains more than one character, it must be enclosed in curly braces (‘{}’).
• Fractions are typeset with A ‘/’ B, where A stands for the numerator and B for the denominator.

To include a Greek letter you must specify the corresponding keyword after a backslash (‘') character. The text translator produces uppercase or lowercase Greek letters depending on the case of the keyword. For more sophisticated mathematical formulas, you should use the gr_mathtex function.

See the full documentation at GR Documentation for gr_textext.

math_tex (x, y) tex generates a character string starting at the given location. Strings can be defined to create mathematical symbols and Greek letters using LaTeX syntax.

Parameters

• x: The X coordinate of the starting position of the text string
• y: The Y coordinate of the starting position of the text string
• tex: The TeX text string to be drawn

axes ?scale ?linetype ?linewidth ?origin:(0,0) ?major:(1,1) ?size:1 x_tick y_tick draws X and Y coordinate axes with linearly and/or logarithmically spaced tick marks. Tick marks are positioned along each axis so that major tick marks fall on the axes origin (whether visible or not). Major tick marks are labeled with the corresponding data values. Axes are drawn according to the scale of the window.

Parameters

• x_tick: The interval between minor tick marks on the X axis.
• y_tick: The interval between minor tick marks on the Y axis.
• x_org: The world coordinate of the origin (point of intersection) of the X axis.
• y_org: The world coordinate of the origin (point of intersection) of the Y axis.
• major_x: Unitless integer value specifying the number of minor tick intervals between major tick marks on the X axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• major_y: Unitless integer value specifying the number of minor tick intervals between major tick marks on the Y axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• tick_size: The length of minor tick marks specified in a normalized device coordinate unit. Major tick marks are twice as long as minor tick marks. A negative value reverses the tick marks on the axes from inward facing to outward facing (or vice versa)

axes_labels ?(scale = []) ?linetype ?linewidth ?coloridx ?(origin = 0.0, 0.0) ?(major = 1, 1) ?(tick_size = -0.01) (fpx : float -> float -> string -> float -> unit) (fpy : float -> float -> string -> float -> unit) x_tick y_tick creates axes in the current workspace and supply a custom function for changing the behaviour of the tick labels.

Similar to axes but allows more fine-grained control over tick labels and text positioning by supplying callback functions. Within the callback function you can use normal GR text primitives for performing any manipulations on the label text.

See axes for more details on drawing axes.

Parameters

• x_tick: The interval between minor tick marks on the X axis.
• y_tick: The interval between minor tick marks on the Y axis.
• x_org: The world coordinate of the origin (point of intersection) of the X axis.
• y_org: The world coordinate of the origin (point of intersection) of the Y axis.
• major_x: Unitless integer value specifying the number of minor tick intervals between major tick marks on the X axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• major_y: Unitless integer value specifying the number of minor tick intervals between major tick marks on the Y axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• tick_size: The length of minor tick marks specified in a normalized device coordinate unit. Major tick marks are twice as long as minor tick marks. A negative value reverses the tick marks on the axes from inward facing to outward facing (or vice versa).
• fpx: Function pointer to a function that returns a label for a given tick on the X axis. The callback function should have the following arguments:
• x: NDC of the label in X direction.
• y: NDC of the label in Y direction.
• svalue: Internal string representation of the text drawn by GR at (x,y).
• value: Floating point representation of the label drawn at (x,y).
• fpy: Exactly same as the fpx above, but for the the Y axis.

axes3d ?scale ?linetype ?linewidth ?origin:(0,0,0) ?major:(1,1,1) ?size:1 x_tick y_tick z_tick draws X, Y and Z coordinate axes with linearly and/or logarithmically spaced tick marks. Tick marks are positioned along each axis so that major tick marks fall on the axes origin (whether visible or not). Major tick marks are labeled with the corresponding data values. Axes are drawn according to the scale of the window.

Parameters

• x_tick: The interval between minor tick marks on the X axis.
• y_tick: The interval between minor tick marks on the Y axis.
• z_tick: The length in world coordinates of the interval between minor grid lines in Z direction.
• x_org: The world coordinate of the origin (point of intersection) of the X axis.
• y_org: The world coordinate of the origin (point of intersection) of the Y axis.
• z_org: The world coordinate of the origin (point of intersection) of the Z axis.
• major_x: Unitless integer value specifying the number of minor tick intervals between major tick marks on the X axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• major_y: Unitless integer value specifying the number of minor tick intervals between major tick marks on the Y axis. Values of 0 or 1 imply no minor ticks. Negative values specify no labels will be drawn for the associated axis.
• major_z: Unitless integer value specifying the number of minor grid lines between major grid lines on the Z axis. Values of 0 or 1 imply no grid lines.
• tick_size: The length of minor tick marks specified in a normalized device coordinate unit. Major tick marks are twice as long as minor tick marks. A negative value reverses the tick marks on the axes from inward facing to outward facing (or vice versa)

surface x y z ?option draws a three-dimensional surface plot for the given data points.

Here, x and y define a grid, z is a singly dimensioned array containing at least nx * ny data points. z describes the surface height at each point on the grid.

Parameters

• x: X coordinates
• y: Y coordinates
• z: Z coordinates
• option: Surface display option

contour ?major_h x y h z sraw contours of a three-dimensional data set whose values are specified over a rectangular mesh. Contour lines may optionally be labeled.

Parameters

• x: X coordinates
• y: Y coordinates
• h: height values
• pz: Z coordinates
• major_h: Directs GR to label contour lines. For example, a value of 3 would label every third line. A value of 1 will label every line. A value of 0 produces no labels. To produce colored contour lines, add an offset of 1000 to major_h.

contourf ?(major_h = 0) x y h z draws filled contour plot of a three-dimensional data set whose values are specified over a rectangular mesh.

Parameters

• x: X coordinates
• y: Y coordinates
• h: height values. If NULL, use nh evenly distributed height values between minimum and maximum Z value.
• major_h: Directs GR to label contour lines. For example, a value of 3 would label every third line. A value of 1 will label every line. A value of 0 produces no labels. To produce colored contour lines, add an offset of 1000 to major_h

grid ?scale ?linetype ?linewidth ?origin:(0,0) ?major:(1,1) x_tick y_tick draws a linear and/or logarithmic grid.

Major grid lines correspond to the axes origin and major tick marks whether visible or not. Minor grid lines are drawn at points equal to minor tick marks. Major grid lines are drawn using black lines and minor grid lines are drawn using gray lines.

Parameters

• x_tick: The length in world coordinates of the interval between minor grid lines in X direction.
• y_tick: The length in world coordinates of the interval between minor grid lines in Y direction.
• x_org: The world coordinate of the origin (point of intersection) of the X axis.
• y_org: The world coordinate of the origin (point of intersection) of the Y axis.
• major_x: Unitless integer value specifying the number of minor grid lines between major grid lines on the X axis. Values of 0 or 1 imply no grid lines.
• major_y: Unitless integer value specifying the number of minor grid lines between major grid lines on the Y axis. Values of 0 or 1 imply no grid lines.

grid3d ?scale ?linetype ?linewidth ?origin:(0,0,0) ?major:(1,1,1) x_tick y_tick z_tick draws a linear and/or logarithmic grid.

Major grid lines correspond to the axes origin and major tick marks whether visible or not. Minor grid lines are drawn at points equal to minor tick marks. Major grid lines are drawn using black lines and minor grid lines are drawn using gray lines.

Parameters

• x_tick: The length in world coordinates of the interval between minor grid lines in X direction.
• y_tick: The length in world coordinates of the interval between minor grid lines in Y direction.
• z_tick: The length in world coordinates of the interval between minor grid lines in Z direction.
• x_org: The world coordinate of the origin (point of intersection) of the X axis.
• y_org: The world coordinate of the origin (point of intersection) of the Y axis.
• z_org: The world coordinate of the origin (point of intersection) of the Z axis.
• major_x: Unitless integer value specifying the number of minor grid lines between major grid lines on the X axis. Values of 0 or 1 imply no grid lines.
• major_y: Unitless integer value specifying the number of minor grid lines between major grid lines on the Y axis. Values of 0 or 1 imply no grid lines.
• major_z: Unitless integer value specifying the number of minor grid lines between major grid lines on the Z axis. Values of 0 or 1 imply no grid lines.

vertical_errorbars x y el eu draws a standard vertical error bar graph.

Parameters

• px: X coordinates
• py: Y coordinates
• el: absolute values of the lower error bar data
• eu: absolute values of the upper error bar data

horizontal_errorbars x y el eu draws a standard horizontal error bar graph.

Parameters

• px: X coordinates
• py: Y coordinates
• el: absolute values of the lower error bar data
• eu: absolute values of the upper error bar data

titles3d x_title y_title z_title displays axis titles just outside of their respective axes.

Parameters

• x_title: The text to be displayed on the X axis
• y_title: The text to be displayed on the Y axis
• z_title: The text to be displayed on the Z axis

tricontour x y z levels draws a contour plot for the given triangle mesh.

Parameters

• x: X coordinates
• y: Y coordinates
• z: Z coordinates
• levels: contour levels

colorbar () plots a colorbar.

drawrect ?linetype ?linewidth ?coloridx left right bottom up draws a rectangle.

Parameters

• left: Left edge of the rectangle
• right: Right edge of the rectangle
• bottom: Bottom edge of the rectangle
• up: Upper edge of the rectangle

fillrect ?fillstyle ?fillcoloridx ?linetype ?linewidth ?coloridx left right bottom up draws a filled rectangle.

Parameters

• left: Left edge of the rectangle
• right: Right edge of the rectangle
• bottom: Bottom edge of the rectangle
• up: Upper edge of the rectangle

drawarc ?linetype ?linewidth ?coloridx left right bottom up a1 a2 draws a circular or elliptical arc covering the specified rectangle.

The resulting arc begins at a1 and ends at a2 degrees. Angles are interpreted such that 0 degrees is at the 3 o’clock position. The center of the arc is the center of the given rectangle.

Parameters

• left: Left edge of the rectangle
• right: Right edge of the rectangle
• bottom: Bottom edge of the rectangle
• up: Upper edge of the rectangle
• a1: The start angle
• a2: The end angle

fillarc ?fillstyle ?fillcoloridx ?linetype ?linewidth ?coloridx left right bottom up draws a filled circular or elliptical arc covering the specified rectangle.

The resulting arc begins at a1 and ends at a2 degrees. Angles are interpreted such that 0 degrees is at the 3 o’clock position. The center of the arc is the center of the given rectangle.

Parameters

• left: Left edge of the rectangle
• right: Right edge of the rectangle
• bottom: Bottom edge of the rectangle
• up: Upper edge of the rectangle
• a1: The start angle
• a2: The end angle

drawpath vertices codes fill draws simple and compound outlines consisting of line segments and bezier curves.

The following path codes are recognized:

• `STOP end the entire path
• `MOVETO move to the given vertex
• `LINETO draw a line from the current position to the given vertex
• `CURVE3 draw a quadratic Bezier curve
• `CURVE4 draw a cubic Bezier curve
• `CLOSEPOLY draw a line segment to the start point of the current path

Parameters

• vertices: the vertices (x,y)
• codes: path codes
• fill: A flag indication whether resulting path is to be filled or not

drawarrow ?arrowsize ?arrowstyle (x1, y1) (x2, y2) draws an arrow between two points.

Different arrow styles (angles between arrow tail and wing, optionally filled heads, double headed arrows) are available. Check the documentation of set_arrowstyle and set_arrowsize for more information.

Parameters

• x1: The X coordinate of the arrow start point (tail)
• y1: The Y coordinate of the arrow start point (tail)
• x2: The X coordinate of the arrow end point (head)
• y2: The Y coordinate of the arrow end point (head)

drawimage (xmin, ymin) (xmax, ymax) image_data model draws an image into a given rectangular area.

The points (xmin, ymin) and (xmax, ymax) are world coordinates defining diagonally opposite corner points of a rectangle. This rectangle is divided into width by height cells. The two-dimensional array data specifies colors for each cell.

Parameters

• xmin: X coordinate of the lower left point of the rectangle
• ymin: Y coordinate of the lower left point of the rectangle
• xmax: X coordinate of the upper right point of the rectangle
• ymax: Y coordinate of the upper right point of the rectangle
• width: X dimension of the color index array
• height: Y dimension of the color index array
• data: color array
• model: color model

The available color models are:

• RGB 0 AABBGGRR
• HSV 1 AAVVSSHH