figure_implot3d
figure_implot3d, small 3-D figures with Fortran arrays (ImPlot3D).
ImPlot3D (brenocq/implot3d, MIT) draws plots in a box the user turns with the mouse (right drag: rotate; left drag: pan; wheel or middle drag: zoom; right double click: back to the initial rotation; right click: the plot's menu), through Dear ImGui's draw lists: the same in every mode. It is for figures that are plots, not scenes: probe positions, trajectories, a field as a height surface, up to about 10**4 primitives; meshes of millions of faces belong to view3d_object (plots.md, "3-D plots").
ip3_begin_plot returns true when the plot is visible: then declare its axes (ip3_setup_axes) and items, and close it with ip3_end_plot (only in that case). Items (ip3_line, ip3_scatter, ip3_surface, ip3_mesh) take real(real32) or real(real64) arrays of any stride, read in place during the call as the 2-D items are (figure_implot: ImPlot3D has one byte stride for all the arrays of an item, an array of another stride is copied at it; the dummies are ASYNCHRONOUS). Every item takes an optional spec, built by ip3_spec from ImPlot3D's defaults. A surface is coloured by FIGURE's colormaps (ip_colormap), copied into ImPlot3D's registry at their first use and followed when ig_gradient_edit changes them.
Every procedure refuses a call from a task and a call with no frame open (FIG_ERR_STATE); an item or ip3_text outside a 3-D plot, and ip3_setup_axes after the plot's first item, are usage errors (FIG_ERR_STATE, as app%set_checks says). The begin/end pair registers in the scope record of the frame (errors.md, "Pairing and frames").
Source: src/lib/figure_implot3d.F90
Dependencies
Re-exports
Contents
- plot3d_spec_object
- ip3_triangles
- ip3_quads
- ip3_line
- ip3_scatter
- ip3_surface
- ip3_mesh
- place_field
- ip3_end_plot
- ip3_setup_axes
- ip3_line_r32
- ip3_scatter_r32
- ip3_surface_r32
- ip3_surface_grid_r32
- ip3_mesh_r32
- ip3_line_r64
- ip3_scatter_r64
- ip3_surface_r64
- ip3_surface_grid_r64
- ip3_mesh_r64
- ip3_text
- ip3_image
- ip3_setup_axis
- ip3_setup_axis_ticks
- ip3_setup_box
- ip3_setup_legend
- ip3_plot_to_pixels
- ip3_triangles_r64
- ip3_quads_r64
- ip3_triangles_r32
- ip3_quads_r32
- field_range_r32
- field_range_r64
- place_field_r32
- place_field_r64
- ip3_begin_plot
- ip3_spec
- ip3_mouse_ray
- setup3d_refused
- opt
- outside_plot
- item_refused
- surface_ok
- grid_ok
- colormap3d_ok
- triangles_ok
- spec_at
- per_point_ok
- packed_colors
- rgba_ok
- rgba
Variables
| Name | Type | Attributes | Description |
|---|---|---|---|
mesh_index | integer(kind=c_int) | allocatable, target | The triangles of the last mesh, 0-based (kept and grown). |
Derived Types
plot3d_spec_object
Style of a 3-D plot item: colours, line weight, markers, flags. Build it with ip3_spec.
The C struct is private so that a spec always starts from ImPlot3D's defaults (a zeroed one draws nothing).
Components
| Name | Type | Attributes | Description |
|---|---|---|---|
c | type(im_plot3d_spec) | ImPlot3DSpec, as passed to ImPlot3D. |
Interfaces
ip3_triangles
Triangles: each three points (x(i), y(i), z(i)) in a row are one.
Module procedures: ip3_triangles_r32, ip3_triangles_r64
ip3_quads
Quadrilaterals: each four points in a row are one.
Module procedures: ip3_quads_r32, ip3_quads_r64
ip3_line
A line through the points (x(i), y(i), z(i)).
Module procedures: ip3_line_r32, ip3_line_r64
ip3_scatter
Markers at the points (x(i), y(i), z(i)).
Module procedures: ip3_scatter_r32, ip3_scatter_r64
ip3_surface
A surface z(i, j) over a grid: x(i), y(j) (a rectilinear grid) or x(i, j), y(i, j) (any grid of quadrilaterals).
Module procedures: ip3_surface_r32, ip3_surface_r64, ip3_surface_grid_r32, ip3_surface_grid_r64
ip3_mesh
A mesh of triangles: vertices (x(i), y(i), z(i)), triangles(:, k) the vertices of the k-th (from 1).
Module procedures: ip3_mesh_r32, ip3_mesh_r64
place_field
Place a rank-2 array of an item (a surface's field or grid) in a slot.
Module procedures: place_field_r32, place_field_r64
Subroutines
ip3_end_plot
End the 3-D plot (only after ip3_begin_plot returned true).
Attributes: recursive
subroutine ip3_end_plot()Call graph
ip3_setup_axes
Labels of the three axes (call right after ip3_begin_plot, before any item); with auto_fit=.true. the axes fit the data every frame, instead of once on first use. limits = [xmin, xmax, ymin, ymax, zmin, zmax]: the initial ranges (set once; the user zooms and pans from them). elevation and azimuth [degrees], both or neither: the initial rotation of the box (set once; a right double click goes back to it). Statuses: FIG_ERR_ARGUMENT for limits of size /= 6 or with a minimum not below its maximum, or one angle without the other (nothing is set up); FIG_ERR_STATE outside a 3-D plot, after its first item, or from a task.
Attributes: recursive
subroutine ip3_setup_axes(xlabel, ylabel, zlabel, auto_fit, limits, elevation, azimuth, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
xlabel | character(len=*) | in | X label. | |
ylabel | character(len=*) | in | Y label. | |
zlabel | character(len=*) | in | Z label. | |
auto_fit | logical | in | optional | Fit the axes to the data every frame (default: first use). |
limits | real(kind=real64) | in | optional | Initial ranges [xmin, xmax, ymin, ymax, zmin, zmax]. |
elevation | real(kind=real64) | in | optional | Initial elevation [degrees]. |
azimuth | real(kind=real64) | in | optional | Initial azimuth [degrees]. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_line_r32
A line through the points (x(i), y(i), z(i)), single precision; read in place with any stride. colors: the segment from point i in colors(:, i) (RGBA in [0, 1]). Statuses: FIG_ERR_ARGUMENT for series of different sizes, colours not (4, size(x)) or out of [0, 1]; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_line_r32(label, x, y, z, spec, colors, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae. |
y | real(kind=real32) | in | target, asynchronous | Ordinates. |
z | real(kind=real32) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
colors | real(kind=real64) | in | optional | Per-point RGBA, (4, size(x)). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_scatter_r32
Markers at the points (x(i), y(i), z(i)), single precision; read in place with any stride. colors: each marker filled and outlined in its own colour, colors(:, i) RGBA in [0, 1]; sizes: each its own radius [pixels]. Statuses as ip3_line, and FIG_ERR_ARGUMENT for colours not (4, size(x)) or out of [0, 1], sizes not one per point or below 0.
Attributes: recursive
subroutine ip3_scatter_r32(label, x, y, z, spec, colors, sizes, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae. |
y | real(kind=real32) | in | target, asynchronous | Ordinates. |
z | real(kind=real32) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
colors | real(kind=real64) | in | optional | Per-point RGBA, (4, size(x)). |
sizes | real(kind=real64) | in | optional | Per-point marker radii [pixels]. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_surface_r32
A surface of heights z(i, j) over the rectilinear grid x(i), y(j), single precision, coloured by colormap from scale_min to scale_max (default: z's finite range). z is read in place when its elements are equally spaced in memory (a whole array, z(:, j1:j2), a(k, :, :)), else copied; x and y are expanded into the grid's two coordinate arrays (two copies: ImPlot3D reads one value per vertex). Statuses: FIG_ERR_ARGUMENT for x, y that do not match z's shape, one scale end without the other or a minimum not below the maximum, more vertices than a C int counts, a colormap not registered; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_surface_r32(label, x, y, z, colormap, scale_min, scale_max, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae of the grid, size(z, 1). |
y | real(kind=real32) | in | target, asynchronous | Ordinates of the grid, size(z, 2). |
z | real(kind=real32) | in | target, asynchronous | Heights. |
colormap | integer(kind=int32) | in | optional | Colormap (ip_colormap; default Viridis). |
scale_min | real(kind=real64) | in | optional | Height at the colormap's first colour. |
scale_max | real(kind=real64) | in | optional | Height at its last colour. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_surface_grid_r32
A surface over any grid of quadrilaterals: the vertex (i, j) at (x(i, j), y(i, j), z(i, j)), single precision, coloured as ip3_surface. The three arrays are read in place when their elements are equally spaced in memory with one stride, else copied at the stride of z. Statuses as ip3_surface (x and y of z's shape).
Attributes: recursive
subroutine ip3_surface_grid_r32(label, x, y, z, colormap, scale_min, scale_max, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real32) | in | target, asynchronous | Ordinates of the vertices. |
z | real(kind=real32) | in | target, asynchronous | Heights of the vertices. |
colormap | integer(kind=int32) | in | optional | Colormap (ip_colormap; default Viridis). |
scale_min | real(kind=real64) | in | optional | Height at the colormap's first colour. |
scale_max | real(kind=real64) | in | optional | Height at its last colour. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_mesh_r32
A mesh of triangles, single precision: vertices (x(i), y(i), z(i)) read in place with any stride, triangles(1:3, k) the vertices of the k-th triangle (from 1; converted to ImPlot3D's 0-based indices: one copy). Statuses: FIG_ERR_ARGUMENT for series of different sizes, triangles without 3 rows or with a vertex outside [1, size(x)]; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_mesh_r32(label, x, y, z, triangles, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real32) | in | target, asynchronous | Ordinates of the vertices. |
z | real(kind=real32) | in | target, asynchronous | Heights of the vertices. |
triangles | integer(kind=int32) | in | Vertices of each triangle. | |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_line_r64
A line through the points (x(i), y(i), z(i)), double precision; read in place with any stride. colors: the segment from point i in colors(:, i) (RGBA in [0, 1]). Statuses: FIG_ERR_ARGUMENT for series of different sizes, colours not (4, size(x)) or out of [0, 1]; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_line_r64(label, x, y, z, spec, colors, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae. |
y | real(kind=real64) | in | target, asynchronous | Ordinates. |
z | real(kind=real64) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
colors | real(kind=real64) | in | optional | Per-point RGBA, (4, size(x)). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_scatter_r64
Markers at the points (x(i), y(i), z(i)), double precision; read in place with any stride. colors: each marker filled and outlined in its own colour, colors(:, i) RGBA in [0, 1]; sizes: each its own radius [pixels]. Statuses as ip3_line, and FIG_ERR_ARGUMENT for colours not (4, size(x)) or out of [0, 1], sizes not one per point or below 0.
Attributes: recursive
subroutine ip3_scatter_r64(label, x, y, z, spec, colors, sizes, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae. |
y | real(kind=real64) | in | target, asynchronous | Ordinates. |
z | real(kind=real64) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
colors | real(kind=real64) | in | optional | Per-point RGBA, (4, size(x)). |
sizes | real(kind=real64) | in | optional | Per-point marker radii [pixels]. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_surface_r64
A surface of heights z(i, j) over the rectilinear grid x(i), y(j), double precision, coloured by colormap from scale_min to scale_max (default: z's finite range). z is read in place when its elements are equally spaced in memory (a whole array, z(:, j1:j2), a(k, :, :)), else copied; x and y are expanded into the grid's two coordinate arrays (two copies: ImPlot3D reads one value per vertex). Statuses: FIG_ERR_ARGUMENT for x, y that do not match z's shape, one scale end without the other or a minimum not below the maximum, more vertices than a C int counts, a colormap not registered; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_surface_r64(label, x, y, z, colormap, scale_min, scale_max, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae of the grid, size(z, 1). |
y | real(kind=real64) | in | target, asynchronous | Ordinates of the grid, size(z, 2). |
z | real(kind=real64) | in | target, asynchronous | Heights. |
colormap | integer(kind=int32) | in | optional | Colormap (ip_colormap; default Viridis). |
scale_min | real(kind=real64) | in | optional | Height at the colormap's first colour. |
scale_max | real(kind=real64) | in | optional | Height at its last colour. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_surface_grid_r64
A surface over any grid of quadrilaterals: the vertex (i, j) at (x(i, j), y(i, j), z(i, j)), double precision, coloured as ip3_surface. The three arrays are read in place when their elements are equally spaced in memory with one stride, else copied at the stride of z. Statuses as ip3_surface (x and y of z's shape).
Attributes: recursive
subroutine ip3_surface_grid_r64(label, x, y, z, colormap, scale_min, scale_max, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real64) | in | target, asynchronous | Ordinates of the vertices. |
z | real(kind=real64) | in | target, asynchronous | Heights of the vertices. |
colormap | integer(kind=int32) | in | optional | Colormap (ip_colormap; default Viridis). |
scale_min | real(kind=real64) | in | optional | Height at the colormap's first colour. |
scale_max | real(kind=real64) | in | optional | Height at its last colour. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_mesh_r64
A mesh of triangles, double precision: vertices (x(i), y(i), z(i)) read in place with any stride, triangles(1:3, k) the vertices of the k-th triangle (from 1; converted to ImPlot3D's 0-based indices: one copy). Statuses: FIG_ERR_ARGUMENT for series of different sizes, triangles without 3 rows or with a vertex outside [1, size(x)]; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_mesh_r64(label, x, y, z, triangles, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real64) | in | target, asynchronous | Ordinates of the vertices. |
z | real(kind=real64) | in | target, asynchronous | Heights of the vertices. |
triangles | integer(kind=int32) | in | Vertices of each triangle. | |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_text
A text centred on the point (x, y, z) of the current 3-D plot (PlotText), in the plot's inlay text colour, hidden when the point is outside the box; angle turns it [radians, counter-clockwise], offset moves it [pixels] (x right, y down). Not an item: no legend entry, no part in fitting the axes. Statuses: FIG_ERR_ARGUMENT for a NaN coordinate or an offset of size /= 2; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_text(text, x, y, z, angle, offset, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Text (UTF-8). | |
x | real(kind=real64) | in | Abscissa [plot units]. | |
y | real(kind=real64) | in | Ordinate [plot units]. | |
z | real(kind=real64) | in | Height [plot units]. | |
angle | real(kind=real64) | in | optional | Angle [radians] (default: 0, horizontal). |
offset | real(kind=real64) | in | optional | Offset [pixels], (x right, y down) (default: none). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_image
An image on a quadrilateral of the box (PlotImage): corners(:, k) the x, y, z of its four corners, in the image's top-left, top-right, bottom-right, bottom-left order (a rectangle on a plane: a field on a cut, a picture on the floor); tint multiplies its colours (RGBA, default white). An item: a legend entry, part of the fit. Drawn as two triangles, sorted with the other items. Statuses: FIG_ERR_ARGUMENT for corners not 3 x 4, a tint without 4 components, a texture not initialized; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_image(label, texture, corners, tint, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
texture | type(texture_object) | in | The image. | |
corners | real(kind=real64) | in | x, y, z of the four corners (3 x 4). | |
tint | real(kind=real64) | in | optional | RGBA multiplier (default 1, 1, 1, 1). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_setup_axis
Set up one axis of the 3-D plot being declared (SetupAxis, SetupAxisScale): axis 'x', 'y' or 'z'; scale 'linear' (default), 'log' (base 10: values <= 0 are not shown) or 'symlog'; auto_fit fits the data every frame; invert grows the axis the other way; lock fixes its range against the mouse; no_grid: no grid lines; format a C printf format of one real for the tick labels ('%.1f m', '%.0e'). After ip3_begin_plot (and ip3_setup_axes, which it overrides for that axis), before any item. Statuses: FIG_ERR_ARGUMENT for an unknown axis or scale, a format refused; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.
Attributes: recursive
subroutine ip3_setup_axis(axis, label, scale, auto_fit, invert, lock, no_grid, format, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
axis | character(len=*) | in | 'x', 'y' or 'z'. | |
label | character(len=*) | in | optional | Label (default: none). |
scale | character(len=*) | in | optional | 'linear' (default), 'log', 'symlog'. |
auto_fit | logical | in | optional | Fit the data every frame. |
invert | logical | in | optional | Values grow the other way. |
lock | logical | in | optional | No pan or zoom by the user. |
no_grid | logical | in | optional | No grid lines. |
format | character(len=*) | in | optional | printf format of the tick labels (one real). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_setup_axis_ticks
Ticks of one axis of the 3-D plot being declared at the given values instead of the automatic ones (SetupAxisTicks), labelled labels (one per value; trailing blanks are not shown) or, without them, by the axis's format. Before any item. Statuses: FIG_ERR_ARGUMENT for an unknown axis, values not finite, labels not one per value, more values than a C int counts; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.
Attributes: recursive
subroutine ip3_setup_axis_ticks(axis, values, labels, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
axis | character(len=*) | in | 'x', 'y' or 'z'. | |
values | real(kind=real64) | in | Tick positions. | |
labels | character(len=*) | in | optional | One label per value. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_setup_box
The box of the 3-D plot being declared: scale its x, y, z sides relative to each other (SetupBoxScale, default 1, 1, 1: a cube); elevation and azimuth [degrees], both or neither, turn it to that view on this frame (SetupBoxRotation: a "top view" button calls it once; called every frame, the user cannot turn it), animate=.true. turning it there smoothly. Before any item. Statuses: FIG_ERR_ARGUMENT for a scale without 3 positive values, one angle without the other; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.
Attributes: recursive
subroutine ip3_setup_box(scale, elevation, azimuth, animate, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
scale | real(kind=real64) | in | optional | Relative sides [x, y, z]. |
elevation | real(kind=real64) | in | optional | Elevation [degrees]. |
azimuth | real(kind=real64) | in | optional | Azimuth [degrees]. |
animate | logical | in | optional | Turn there smoothly (default: at once). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_setup_legend
Where the 3-D plot's legend goes (SetupLegend): location a compass point, 'n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw' (default, ImPlot3D's) or 'c'; horizontal=.true.: entries in a row; no_buttons=.true.: a click on an entry does not hide its item. Before any item. Statuses: FIG_ERR_ARGUMENT for an unknown location; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.
Attributes: recursive
subroutine ip3_setup_legend(location, horizontal, no_buttons, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
location | character(len=*) | in | optional | Compass point (default 'nw'). |
horizontal | logical | in | optional | Entries in a row (default: a column). |
no_buttons | logical | in | optional | Entries do not hide their items. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_plot_to_pixels
The pixel (px, py) where the point (x, y, z) of the 3-D plot being declared is drawn (PlotToPixels), as the box is turned now: a label beside a point, a test's click. Statuses: FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_plot_to_pixels(x, y, z, px, py, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
x | real(kind=real64) | in | Abscissa. | |
y | real(kind=real64) | in | Ordinate. | |
z | real(kind=real64) | in | Height. | |
px | real(kind=real64) | out | Pixel abscissa. | |
py | real(kind=real64) | out | Pixel ordinate. | |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_triangles_r64
Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 3; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_triangles_r64(label, x, y, z, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real64) | in | target, asynchronous | Ordinates. |
z | real(kind=real64) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_quads_r64
Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 4; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_quads_r64(label, x, y, z, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real64) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real64) | in | target, asynchronous | Ordinates. |
z | real(kind=real64) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_triangles_r32
Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 3; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_triangles_r32(label, x, y, z, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real32) | in | target, asynchronous | Ordinates. |
z | real(kind=real32) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
ip3_quads_r32
Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 4; FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
subroutine ip3_quads_r32(label, x, y, z, spec, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
label | character(len=*) | in | Legend label. | |
x | real(kind=real32) | in | target, asynchronous | Abscissae of the vertices. |
y | real(kind=real32) | in | target, asynchronous | Ordinates. |
z | real(kind=real32) | in | target, asynchronous | Heights. |
spec | type(plot3d_spec_object) | in | optional | Style (default: ImPlot3D's). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
field_range_r32
The heights at a surface's first and last colours: the given ones, else z's finite range (widened by one about its centre when z is flat: ImPlot3D would divide by a zero range, an FPE under traps).
subroutine field_range_r32(z, scale_min, scale_max, lo, hi)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
z | real(kind=real32) | in | asynchronous | Heights. |
scale_min | real(kind=real64) | in | optional | Given first height. |
scale_max | real(kind=real64) | in | optional | Given last height. |
lo | real(kind=c_double) | out | First height. | |
hi | real(kind=c_double) | out | Last height. |
Call graph
field_range_r64
The heights at a surface's first and last colours: the given ones, else z's finite range (widened by one about its centre when z is flat: ImPlot3D would divide by a zero range, an FPE under traps).
subroutine field_range_r64(z, scale_min, scale_max, lo, hi)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
z | real(kind=real64) | in | asynchronous | Heights. |
scale_min | real(kind=real64) | in | optional | Given first height. |
scale_max | real(kind=real64) | in | optional | Given last height. |
lo | real(kind=c_double) | out | First height. | |
hi | real(kind=c_double) | out | Last height. |
Call graph
place_field_r32
Place a rank-2 array of a surface in slot k, single precision: in place when its elements are equally spaced in memory (column after column) at a positive multiple of the element size within a C int and, when stride is given (the item's, set by the field), at that stride; otherwise copied into the slot's scratch, at stride or contiguous (then the item's stride becomes the element size).
subroutine place_field_r32(d, k, a, stride)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
d | type(series_r32) | inout | The item's arrays. | |
k | integer(kind=int32) | in | Slot. | |
a | real(kind=real32) | in | target, asynchronous | Array. |
stride | integer(kind=int64) | in | optional | The item's stride [bytes]. |
Call graph
place_field_r64
Place a rank-2 array of a surface in slot k, double precision: in place when its elements are equally spaced in memory (column after column) at a positive multiple of the element size within a C int and, when stride is given (the item's, set by the field), at that stride; otherwise copied into the slot's scratch, at stride or contiguous (then the item's stride becomes the element size).
subroutine place_field_r64(d, k, a, stride)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
d | type(series_r64) | inout | The item's arrays. | |
k | integer(kind=int32) | in | Slot. | |
a | real(kind=real64) | in | target, asynchronous | Array. |
stride | integer(kind=int64) | in | optional | The item's stride [bytes]. |
Call graph
Functions
ip3_begin_plot
Begin a 3-D plot; if true, declare its content and call ip3_end_plot.
Attributes: recursive
Returns: logical
function ip3_begin_plot(title, width, height, equal) result(visible)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
title | character(len=*) | in | Title (also the plot id; '##id' hides it). | |
width | real(kind=real64) | in | optional | Width [pixels] (default: full width). |
height | real(kind=real64) | in | optional | Height [pixels] (default: ImPlot3D's). |
equal | logical | in | optional | Same scale on the three axes (one unit as many pixels). |
Call graph
ip3_spec
3-D item style: ImPlot3D's defaults, with the given properties overridden. Colours are RGBA in [0, 1]; an absent colour stays automatic (the next colour of the colormap; a surface's fill: its colormap).
Returns: type(plot3d_spec_object)
function ip3_spec(line_color, line_weight, fill_color, fill_alpha, marker, marker_size, marker_line_color, marker_fill_color, flags, stat) result(spec)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
line_color | real(kind=real64) | in | optional | Line colour, RGBA. |
line_weight | real(kind=real64) | in | optional | Line weight [pixels] (lines, edges, markers). |
fill_color | real(kind=real64) | in | optional | Fill colour, RGBA (surfaces, meshes: one colour). |
fill_alpha | real(kind=real64) | in | optional | Alpha multiplier of the fill colours. |
marker | integer(kind=int32) | in | optional | Marker shape (ImPlot3DMarker_*). |
marker_size | real(kind=real64) | in | optional | Marker radius [pixels]. |
marker_line_color | real(kind=real64) | in | optional | Marker outline colour, RGBA. |
marker_fill_color | real(kind=real64) | in | optional | Marker fill colour, RGBA. |
flags | integer(kind=int32) | in | optional | Item flags (ImPlot3DItemFlags_*, the item's own). |
stat | integer(kind=int32) | out | optional | Status: FIG_ERR_ARGUMENT for a colour of size /= 4. |
Call graph
ip3_mouse_ray
The ray under the pointer, in the 3-D plot's coordinates (PixelsToPlotRay): every point of the box drawn under the pointer is origin + t direction for some t (direction of length 1). True when the pointer is over the plot. A program picks with it: where the ray meets a plane (the floor: t = -origin(3) / direction(3)), the nearest of its points. Linear axes: on a log axis the ray is in the transformed space. Statuses: FIG_ERR_STATE outside a 3-D plot, from a task.
Attributes: recursive
Returns: logical
function ip3_mouse_ray(origin, direction, stat) result(over)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
origin | real(kind=real64) | out | A point of the ray. | |
direction | real(kind=real64) | out | Its direction (unit). | |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
setup3d_refused
True (a usage error reported) outside a 3-D plot or after its first item.
Attributes: recursive
Returns: logical
function setup3d_refused(caller, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
caller | character(len=*) | in | The procedure. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
opt
An optional flag, false when absent.
Attributes: pure
Returns: logical
function opt(x) result(on)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
x | logical | in | optional | Flag. |
Call graph
outside_plot
True (a usage error reported) when no 3-D plot is being declared: ImPlot3D asserts there.
Attributes: recursive
Returns: logical
function outside_plot(caller, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
caller | character(len=*) | in | The procedure. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
item_refused
True (reported) when an item cannot be drawn: from a task, no frame, no 3-D plot (FIG_ERR_STATE), series of different sizes or more points than a C int counts (FIG_ERR_ARGUMENT).
Attributes: recursive
Returns: logical
function item_refused(caller, nx, ny, nz, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
caller | character(len=*) | in | The procedure. | |
nx | integer(kind=int64) | in | Size of x. | |
ny | integer(kind=int64) | in | Size of y. | |
nz | integer(kind=int64) | in | Size of z. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
surface_ok
Whether a surface can be drawn (reported otherwise): from the main thread in a frame and a 3-D plot, x and y matching z's shape, the scale ends both given or neither and in order, a vertex count a C int holds.
Attributes: recursive
Returns: logical
function surface_ok(nx, ny, sx, sy, scale_min, scale_max, stat) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
nx | integer(kind=int64) | in | size(z, 1). | |
ny | integer(kind=int64) | in | size(z, 2). | |
sx | integer(kind=int64) | in | Abscissae given (size(z, 1) expected). | |
sy | integer(kind=int64) | in | Ordinates given (size(z, 2) expected). | |
scale_min | real(kind=real64) | in | optional | Height at the first colour. |
scale_max | real(kind=real64) | in | optional | Height at the last colour. |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
grid_ok
Whether the vertex arrays of a surface over a grid all have z's shape (FIG_ERR_ARGUMENT otherwise).
Attributes: recursive
Returns: logical
function grid_ok(sx, sy, sz, stat) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
sx | integer(kind=int64) | in | Shape of x. | |
sy | integer(kind=int64) | in | Shape of y. | |
sz | integer(kind=int64) | in | Shape of z. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
colormap3d_ok
The ImPlot3D id of the colormap to draw with (default Viridis), copied from FIGURE's registry; false, with FIG_ERR_ARGUMENT, if it is not registered.
Attributes: recursive
Returns: logical
function colormap3d_ok(colormap, cmap, stat) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
colormap | integer(kind=int32) | in | optional | Colormap (ip_colormap), if given. |
cmap | integer(kind=c_int) | out | ImPlot3D id. | |
stat | integer(kind=int32) | out | optional | Status, on a failure. |
Call graph
triangles_ok
Whether a mesh's triangles are 3 rows of vertices in [1, nv] and a count a C int holds (FIG_ERR_ARGUMENT otherwise); if so, their 0-based indices are in mesh_index.
Attributes: recursive
Returns: logical
function triangles_ok(triangles, nv, stat) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
triangles | integer(kind=int32) | in | Vertices of each triangle. | |
nv | integer(kind=int64) | in | Vertices. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
Call graph
spec_at
The C spec to pass: the given one, or ImPlot3D's defaults, with the item's stride (test_plot_stride reads it).
Returns: type(im_plot3d_spec)
function spec_at(stride, spec) result(c)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
stride | integer(kind=int64) | in | The item's stride [bytes]. | |
spec | type(plot3d_spec_object) | in | optional | Style. |
Call graph
per_point_ok
Whether the per-point colours, (4, n) in [0, 1], and radii, n finite values >= 0, fit an item of n points.
Returns: logical
function per_point_ok(who, n, colors, sizes, stat) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
who | character(len=*) | in | Calling procedure, for the message. | |
n | integer(kind=int64) | in | Points. | |
colors | real(kind=real64) | in | optional | Per-point RGBA. |
sizes | real(kind=real64) | in | optional | Per-point radii [pixels]. |
stat | integer(kind=int32) | out | optional | Status, on a failure. |
Call graph
packed_colors
RGBA colours in [0, 1], one per column, packed as Dear ImGui's ImU32 (R in the low byte, A in the high one).
Attributes: pure
Returns: integer(kind=c_int)
function packed_colors(colors) result(u)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
colors | real(kind=real64) | in | RGBA, (4, n). |
Call graph
rgba_ok
Whether an optional colour is absent or has 4 components.
Attributes: pure
Returns: logical
function rgba_ok(color) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
color | real(kind=real64) | in | optional | Colour, RGBA. |
Call graph
rgba
RGBA colour as an ImVec4.
Attributes: pure
Returns: type(im_vec4)
function rgba(color) result(v)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
color | real(kind=real64) | in | Colour, RGBA, 4 components. |
Call graph