Module `Hugin.Artist`

Artist: Visual element constructors and style specifications.

type color = {

r : float;
g : float;
b : float;
a : float;

}

color is an RGBA color record with components in 0.0,1.0.

type cmap

cmap is colormap mapping normalized 0.0,1.0 to RGBA colors.

module Color : sig ... end

Predefined colors.

module Colormap : sig ... end

type line_style =

| Solid
(*
continuous line .
*)
| Dashed
(*
repeating dash pattern .
*)
| DashDot
(*
dash-dot sequence .
*)
| Dotted
(*
dotted line .
*)
| None
(*
no line.
*)

Patterns for stroked lines.

type marker_style =

| Circle
(*
circular markers.
*)
| Point
(*
single-pixel points.
*)
| Pixel
(*
same as Point.
*)
| Square
(*
square markers.
*)
| Triangle
(*
triangular markers.
*)
| Plus
(*
plus-sign markers.
*)
| Star
(*
star-shaped markers.
*)
| None
(*
no markers.
*)

Shapes for data point markers.

type plot_style

Abstract type representing the style (color, marker, line) for a plot element. Used by functions like Plotting.errorbar to style the central data points.

val plot_style : 
  ?color:color ->
  ?linewidth:float ->
  ?linestyle:line_style ->
  ?marker:marker_style ->
  unit ->
  plot_style

plot_style ?color ?linewidth ?linestyle ?marker ()

Create a reusable style for line and marker artists.

Parameters

color: stroke/marker color.
linewidth: width of stroked lines.
linestyle: pattern for stroked lines.
marker: shape for data point markers.

Returns

a plot_style object to style artists like errorbar, hist, etc.

type step_where =

| Pre
(*
step change at the x coordinate before drawing segment.
*)
| Post
(*
step change at the x coordinate after drawing segment.
*)
| Mid
(*
step change at midpoint between coordinates.
*)

Position of step relative to the x-coordinate in step plots.

type t

A visual element to be drawn on an Axes.

val line2d : 
  ?color:color ->
  ?linewidth:float ->
  ?linestyle:line_style ->
  ?marker:marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

line2d ?color ?linewidth ?linestyle ?marker ?label x y

Create a 2D polyline connecting points (x.i, y.i).

Parameters

?color: line/marker color.
?linewidth: width of the line.
?linestyle: pattern for the line.
?marker: marker style at each data point.
?label: legend entry.
x: 1D float32 array of x coordinates.
y: 1D float32 array of y coordinates.

Returns

an artist t for rendering on an axes.

Raises

Invalid_argument if x and y lengths differ.

val line3d : 
  ?color:color ->
  ?linewidth:float ->
  ?linestyle:line_style ->
  ?marker:marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

line3d ?color ?linewidth ?linestyle ?marker ?label x y z

Create a 3D polyline connecting points (x.i, y.i, z.i).

Parameters

?color: line/marker color.
?linewidth: width of the line.
?linestyle: pattern for the line.
?marker: marker style at each data point.
?label: legend entry.
x: 1D float32 nx of x coordinates.
y: 1D float32 nx of y coordinates.
z: 1D float32 nx of z coordinates.

Returns

an artist t representing the configured 3D line.

Raises

Invalid_argument if lengths of x, y, and z differ.

Examples

  let a3d = line3d x_arr y_arr z_arr in
  Axes.add_artist a3d ax3d

val scatter : 
  ?s:float ->
  ?c:color ->
  ?marker:marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

scatter ?s ?c ?marker ?label x y

Create a scatter plot artist for points (x.i, y.i).

Parameters

?s: marker size in points (default 6.0).
?c: marker color (default Artist.Color.blue).
?marker: marker style (default Circle).
?label: legend entry.
x: 1D float32 nx of x coordinates.
y: 1D float32 nx of y coordinates.

Returns

an artist t representing the scatter plot.

Raises

Invalid_argument if lengths of x and y differ.

Examples

  let sc =
    scatter ~s:10. ~c:Color.red ~marker:Circle ~label:"pts" ~x x_arr ~y
      y_arr
  in
  Axes.add_artist sc axes

val bar : 
  ?width:float ->
  ?bottom:float ->
  ?color:color ->
  ?label:string ->
  height:Nx.float32_t ->
  Nx.float32_t ->
  t

bar ?width ?bottom ?color ?label ~height x

Create a bar plot artist for (x, height) data.

Parameters

?width: width of each bar (default 0.8).
?bottom: y-coordinate of the bottom of the bars (default 0.0).
?color: bar color.
?label: legend entry.
height: 1D float32 nx of heights.
x: 1D float32 nx of x coordinates.

Returns

an artist t representing the bar plot.

Raises

Invalid_argument if lengths of x and height differ.

Examples

  let b =
    bar ~width:0.5 ~bottom:0. ~color:Color.green ~label:"bars"
      ~height:height_arr x_arr
  in
  Axes.add_artist b axes

val step : 
  ?color:color ->
  ?linewidth:float ->
  ?linestyle:line_style ->
  ?where:step_where ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

step ?color ?linewidth ?linestyle ?where ?label x y

Create a step plot artist for (x, y) data.

Parameters

?color: line color.
?linewidth: line width in points.
?linestyle: pattern for stepped line.
?where: position of step relative to x (Pre, Post, Mid).
?label: legend entry.
x: 1D float32 nx of x coordinates.
y: 1D float32 nx of y coordinates.

Returns

an artist t representing the step plot.

Raises

Invalid_argument if lengths of x and y differ.

Examples

  let st = step x_arr y_arr ~where:Mid in
  Axes.add_artist st axes

val fill_between : 
  ?color:color ->
  ?where:Nx.float32_t ->
  ?interpolate:bool ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

fill_between ?color ?where ?interpolate ?label x y1 y2

Create an artist filling the area between two curves y1(x) and y2(x).

Parameters

?color: fill color.
?where: 1D float32 mask; true values fill region.
?interpolate: whether to interpolate missing segments (default false).
?label: legend entry.
x: 1D float32 nx of x coordinates.
y1: 1D float32 nx of lower bound values.
y2: 1D float32 nx of upper bound values.

Returns

an artist t representing the filled region.

Raises

Invalid_argument if lengths of x, y1, and y2 differ.

Examples

  let fb = fill_between x_arr y_lo y_hi in
  Axes.add_artist fb axes

val text : ?color:color -> ?fontsize:float -> x:float -> y:float -> string -> t

text ?color ?fontsize ~x ~y content

Create a text annotation at the specified coordinates.

Parameters

?color: text color (default Artist.Color.black).
?fontsize: font size in points (default 12.0).
x: x-coordinate in data units.
y: y-coordinate in data units.
content: text string to display.

Returns

a t representing the text artist.

Notes

Text is anchored at (x,y); alignment options not configurable.

Examples

  let tx = text ~x:0.5 ~y:0.5 "Hello" in
  Axes.add_artist tx axes

val image : 
  ?extent:(float * float * float * float) ->
  ?cmap:cmap ->
  ?aspect:string ->
  Nx.uint8_t ->
  t

image ?extent ?cmap ?aspect data

Create an image artist from a uint8 nx.

Parameters

?extent: (xmin, xmax, ymin, ymax) for positioning; defaults to data indices.
?cmap: colormap for interpreting scalar data; ignored for RGB(A) arrays.
?aspect: aspect ratio, e.g., "auto" or "equal" (default "auto").
data: uint8 nx of shape |H;W|, |H;W;1|, |H;W;3|, or |H;W;4|.

Returns

a t representing the image artist.

Raises

Invalid_argument if data rank or channel count is unsupported.

Examples

  let img = image ~extent:(0., 10., 0., 5.) img_arr in
  Axes.add_artist img axes

val contour : 
  ?colors:color array ->
  ?linewidths:float array ->
  ?linestyles:line_style array ->
  levels:float array ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

contour ?colors ?linewidths ?linestyles ~levels x y z

Create contour lines for 2D scalar field z(x,y).

Parameters

?colors: array of colors for each contour level.
?linewidths: array of line widths for each level.
?linestyles: array of line styles for each level.
levels: array of z values at which to draw contours.
x: 1D array of x coordinates.
y: 1D array of y coordinates.
z: 2D array of z values with shape (len(y), len(x)).

Returns

a t representing the contour artist.

Raises

Invalid_argument if dimensions don't match.

Examples

  let c = contour ~levels:[| 0.0; 0.5; 1.0 |] x y z in
  Axes.add_artist c axes

val contourf : 
  ?cmap:cmap ->
  ?alpha:float ->
  levels:float array ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  t

contourf ?cmap ?alpha ~levels x y z

Create filled contours for 2D scalar field z(x,y).

Parameters

?cmap: colormap for filling (default Viridis).
?alpha: transparency (0.0 to 1.0, default 1.0).
levels: array of z values defining contour boundaries.
x: 1D array of x coordinates.
y: 1D array of y coordinates.
z: 2D array of z values with shape (len(y), len(x)).

Returns

a t representing the filled contour artist.

Raises

Invalid_argument if dimensions don't match.

Examples

  let cf = contourf ~cmap:Coolwarm ~levels:[| 0.0; 0.5; 1.0 |] x y z in
  Axes.add_artist cf axes