Module Plplot.Plot

A higher-level OCaml interface to PLplot

THIS API IS NOT FIXED AND MAY CHANGE BEFORE THE 5.10.0 RELEASE

type side_t = [
  1. | `top
  2. | `bottom
  3. | `left
  4. | `right
]
type 'a tagged_side_t = [
  1. | `top of 'a
  2. | `bottom of 'a
  3. | `left of 'a
  4. | `right of 'a
]

The different sides of a (2D) plot. These values are used to represent, e.g., offsets along axes and text placement.

type axis_options_t = [
  1. | `axis
  2. | `frame0
  3. | `frame1
  4. | `time
  5. | `fixed_point
  6. | `major_grid
  7. | `minor_grid
  8. | `invert_ticks
  9. | `log
  10. | `unconventional_label
  11. | `label
  12. | `custom_label
  13. | `minor_ticks
  14. | `minor_tick_count of int
  15. | `major_ticks
  16. | `major_tick_spacing of float
  17. | `vertical_label
]

These are the available options for drawing plot axes. These values map to individual letters provided to Plplot.plbox and similar functions.

type stream_t

A plot stream.

type color_t = [
  1. | `white
  2. | `red
  3. | `yellow
  4. | `green
  5. | `gray
  6. | `blue
  7. | `light_blue
  8. | `purple
  9. | `pink
  10. | `black
  11. | `brown
  12. | `index of int
]

Colors from the indexed color map (color map 0), from the cmapo_alternate.pal file! Note that these will NOT match up with colors from the default color palette!

type map_t = [
  1. | `globe
  2. | `usa
  3. | `countries
  4. | `all
]

Different map outlines available for map

type pltr_t = float -> float -> float * float

Type signature for coordinate transform functions

type plot_t

A plottable element, usable by the function plot.

type plot_device_family_t = [
  1. | `cairo
  2. | `qt
  3. | `core
  4. | `wx
]

The different available plot device families. This is not a complete representation of all of the available devices provided by PLplot.

type plot_device_t = [
  1. | `pdf of plot_device_family_t
  2. | `png of plot_device_family_t
  3. | `ps of plot_device_family_t
  4. | `svg of plot_device_family_t
  5. | `window of plot_device_family_t
  6. | `prompt
    (*

    Ask for the correct device to use at run-time

    *)
  7. | `stream of int
    (*

    Pre-defined plot streams

    *)
  8. | `other_device of string
]

Plot devices. The constructor argument allows one to define which device family is used.

PLplot plotting devices otherwise not available from this list

type plot_scaling_t = [
  1. | `preset
  2. | `greedy
  3. | `equal
  4. | `equal_square
]

Type of scaling to use for plot axes, as in Plplot.plenv.

type color_palette_t

A color palette, usually loaded from disk

type line_style_t = [
  1. | `solid
  2. | `line1
  3. | `line2
  4. | `line3
  5. | `line4
  6. | `line5
  7. | `line6
  8. | `line7
  9. | `line8
    (*

    These correspond to PLplot's pre-defined line styles as set by pllsty.

    *)
  10. | `custom of (int * int) list
]

Line plotting styles/patterns.

A custom line style, with each (mark, space) pair defining the length of one segment and gap in the line drawing pattern.

val default_axis_options : axis_options_t list

The default list of axis rendering options, used for all plots generated with init if no custom options are provided.

val rgb_of_color : color_t -> int * int * int

Convert color_t values to r, g, b integer values, each ranging in value from 0 - 255.

A recommended/standard file name extension, given a particular plot device.

Plot streams
val make_stream : ?stream:int -> unit -> stream_t

Make a new stream_t, possibly using an existing plot stream index. If no stream argument is provided then a new plot stream is created.

val start_page : ?stream:stream_t -> (float * float) -> (float * float) -> plot_scaling_t -> unit

start_page ?stream (x0, y0) (x1, y1) scaling starts a new plot page with the given dimensions and scaling.

val next_page : ?stream:stream_t -> (float * float) -> (float * float) -> plot_scaling_t -> unit

An alias for start_page.

val make : ?stream:stream_t -> ?filename:string -> ?size:(int * int) -> ?pre:(unit -> unit) -> plot_device_t -> stream_t

Create a new plot instance. See init for a description of the parameters.

val init : ?filename:string -> ?size:(int * int) -> ?pages:(int * int) -> ?pre:(unit -> unit) -> (float * float) -> (float * float) -> plot_scaling_t -> plot_device_t -> stream_t

init ?filename ?size ?pages (x0, y0) (x1, y1) scale device - Start a new plot stream for a 2D plot with plot axis extents given by (x0, y0) to (x1, y1). A call to init is roughly equivalent to calling make and then start_page.

  • parameter filename

    Plot output filename. A suitable file extension will be added if it does not already exist.

  • parameter size

    Dimension of the plot in physical units (e.g., pixels for bitmap outputs (PNG, X) and 1/72 inch for vector outputs (PS, PDF, SVG)

  • parameter pages

    Layout of multiple plots on a single page

  • parameter pre

    This function, if provided, is called just before the plot instance is initialized. It can be used to, for example, load custom color palettes.

val with_stream : ?stream:stream_t -> (unit -> 'a) -> 'a

with_stream ?stream f performs f with stream as the active plot stream. If stream is not provided then the currently active plot stream is left active. Once f is complete, the previously active plot stream is restored.

val make_stream_active : stream:stream_t -> unit

make_stream_active stream makes stream in to the currently active plot stream for The standard PLplot API calls or any function which is not provided with an explicit stream argument.

Colors
val set_color : ?stream:stream_t -> color_t -> unit

set_color ?stream color sets the current active plot color to color.

val set_color_scale : ?stream:stream_t -> ?pos:float array -> ?alt_hue_path:bool array -> color_t array -> unit

set_color_scale ?stream ?pos ?alt_hue_path colors sets the continuous color map (color map 1) to a scale determined by interpolating between colors. pos can be used to specify where in the color scale (0.0 - 1.0) the a color interpolation point should fall. pos defaults to even spacing. alt_hue_path can be used to specify that a given segment should be interpolated using the alternative hue path which always includes the hue=0 point. Plplot.plscmap1l is used internally to set the color scale.

val indexed_palette : string -> color_palette_t

PLplot has two color palettes - indexed (color map 0) and continuous (color map 1). These functions can be used with load_palette to set custom indexed and continuous color palettes.

val continuous_palette : ?interpolate:bool -> string -> color_palette_t

continuous_palette ?interpolate filename - If interpolate is true (the default) then a smooth palette is generated using the color definitions in the palette file filename. Otherwise, the colors are considered to be discrete, giving a segmented palette.

val load_palette : ?stream:stream_t -> color_palette_t -> unit

load_palette ?stream palette loads either indexed or continuous color palette information from a file on disk.

Plot elements
val arc : ?fill:bool -> color_t -> float -> float -> float -> float -> float -> float -> float -> plot_t

arc ?fill color x y a b angle0 angle1 rotate

val axes : ?color:color_t -> ?style:line_style_t -> ?width:float -> ?labelfunc:([ `x | `y | `z ] -> float -> string) -> axis_options_t list -> axis_options_t list -> plot_t

axes ?color ?style ?width xopt yopt

val default_axes : plot_t

default_axes is equivalent to axes default_axis_options default_axis_options

val circle : ?fill:bool -> color_t -> float -> float -> float -> plot_t

circle ?fill color x y r

val contours : color_t -> pltr_t -> float array -> float array array -> plot_t

contours color tranform_func contours data

val image : ?range:(float * float) -> (float * float) -> (float * float) -> float array array -> plot_t

image ?range (x0, y0) (x1, y1) data

val imagefr : ?range:(float * float) -> scale:(float * float) -> (float * float) -> (float * float) -> float array array -> plot_t

imagefr ?range ~scale (x0, y0) (x1, y1) data

val join : ?style:line_style_t -> ?width:float -> color_t -> (float * float) -> (float * float) -> plot_t

join ?style color (x0, y0) (x1, y1)

val label : ?color:color_t -> string -> string -> string -> plot_t

label ?color x_label y_label title adds axis labels and a title.

val lines : ?label:string -> ?style:line_style_t -> ?width:float -> color_t -> float array -> float array -> plot_t

lines ?label ?style color xs ys

val map : ?sw:(float * float) -> ?ne:(float * float) -> color_t -> map_t -> plot_t

map ?sw ?ne color outline_type

val points : ?label:string -> ?symbol:string -> ?scale:float -> color_t -> float array -> float array -> plot_t

points ?label ?symbol ?scale color xs ys

val polygon : ?fill:bool -> color_t -> float array -> float array -> plot_t

polygon ?fill color xs ys

val rectangle : ?fill:bool -> color_t -> (float * float) -> (float * float) -> plot_t

rectangle ?fill color (x0, y0) (x1, y1)

val shades : ?fill_width:float -> ?contour:(color_t * float) -> ?rect:bool -> (float * float) -> (float * float) -> float array -> float array array -> plot_t

shades ?fill_width ?contour ?rect (x0, y0) (x1, y1) contours data

val text : ?dx:float -> ?dy:float -> ?just:float -> color_t -> float -> float -> string -> plot_t

text ?dx ?dy ?just color x y string writes the text string inside the plot window, at an optional angle defined by the offsets dx and dy.

val text_outside : ?just:float -> ?perp:bool -> color_t -> float tagged_side_t -> float -> string -> plot_t

text_outside ?just ?perp color side offset string writes text outside of the plot window, along side, displaced from the axis by offset * character height.

val func : ?symbol:string -> ?step:float -> color_t -> (float -> float) -> (float * float) -> plot_t

func ?symbol ?step color f (min, max) plots the function f from x = min to x = max. step can be used to tighten or coarsen the sampling of plot points.

val transform : pltr_t -> plot_t

transform f sets the universal coordinate transformation function.

val clear_transform : plot_t

clear_transform clears any currently defined universal coordinate transform function.

val pltr : pltr_t -> plot_t

pltr f sets the coordinate transformation function used by imagefr and other functions affected by Plplot.plset_pltr.

val clear_pltr : plot_t

clear_pltr clears any currently defined function-specific pltr transform function.

val custom : (unit -> unit) -> plot_t

custom f will call f () when the plot element is used. This function can be used to create customized plot elements for use with plot.

val list : plot_t list -> plot_t

list l makes a plot element from a list of plot elements, allowing, for example, a plot to be created piece-by-piece before being rendered.

val maybe : plot_t option -> plot_t

maybe m_p will plot the contents of m_p. If m_p is None then this is effectively a no-op.

val plot : ?stream:stream_t -> plot_t list -> unit

Plot a list of plottable elements

Support functions
val character_height : ?stream:stream_t -> unit -> float

Character height in world coordinate units

type position_t

Positioning within viewport or subpage

val viewport_pos : ?side1:side_t -> ?side2:side_t -> ?inside:bool -> float -> float -> position_t

Position relative to the plot viewport

val subpage_pos : ?side1:side_t -> ?side2:side_t -> ?inside:bool -> float -> float -> position_t

Position relative to the plot subpage

type legend_entry_t

Legend entry

type 'a layout_t

Layout of elements

val no_legend : legend_entry_t

Empty legend entry

val box_legend : ?pattern:int -> ?scale:float -> ?line_width:float -> ?label_color:color_t -> label:string -> color_t -> legend_entry_t

Color-filled box legend entry

val line_legend : ?style:int -> ?width:float -> ?label_color:color_t -> label:string -> color_t -> legend_entry_t

Line legend entry

val symbol_legend : ?scale:float -> ?number:int -> ?label_color:color_t -> label:string -> color_t -> string -> legend_entry_t

Symbol/point legend entry

val row_major : 'a -> 'b -> ('a * 'b) layout_t

Row-major layout

val column_major : 'a -> 'b -> ('a * 'b) layout_t

Column-major layout

val legend : ?pos:position_t -> ?plot_width:float -> ?bg:color_t -> ?bb:(color_t * line_style_t) -> ?layout:(int * int) layout_t -> ?color:color_t -> ?text_offset:float -> ?text_scale:float -> ?text_spacing:float -> ?text_justification:float -> ?text_left:bool -> legend_entry_t list list -> plot_t

legend entries

type colorbar_axis_t

Colorbar axis definitions

type colorbar_kind_t

Available colorbar kinds

val colorbar_axis : ?axis:axis_options_t list -> float array -> colorbar_axis_t

colorbar_axis ?axis values creates a colorbar_axis_t with the given axis options and range values.

val gradient_colorbar : ?axis:axis_options_t list -> float array -> colorbar_kind_t

gradient_colorbar ?axis [|min; max|] from min to max

val image_colorbar : ?axis:axis_options_t list -> float array -> colorbar_kind_t

image_colorbar ?axis [|min; max|] from min to max

val shade_colorbar : ?custom:bool -> ?axis:axis_options_t list -> float array -> colorbar_kind_t

shade_colorbar ?custom ?axis contours defines a shaded contour colorbar with axis labels at even spacings (custom = false) or at the locations of the values in contours (custom = true - the default).

val default_colorbar_axis : axis_options_t list

Default options used for a colorbar axis

val colorbar : ?pos:position_t -> ?bg:color_t -> ?bb:(color_t * line_style_t) -> ?cap:(float option * float option) -> ?contour:(color_t * float) -> ?orient:(float * float) tagged_side_t -> ?axis:colorbar_axis_t list -> ?label:string tagged_side_t list -> ?color:color_t -> ?scale:float -> colorbar_kind_t -> plot_t

colorbar colorbar_kind

val plot_axes : ?stream:stream_t -> axis_options_t list -> axis_options_t list -> unit

Draw the plot axes on the current plot page

Finishing up a plot page
val end_stream : ?stream:stream_t -> unit -> unit

end_stream ?stream () ends stream. This or finish should be called once all plotting is complete.

val finish : ?stream:stream_t -> unit -> unit

finish ?stream () draws default x and y axes, then closes stream.