NAME
draw_mesh -- draw a mesh of markers
PROTOTYPE
unitptr draw_mesh( char *pcWdw, int iDx, int iDy, int iNum, char *pcFmt, unitptr uHost)
ARGUMENTS
- char *pcWdw
- specifies which window to draw into: if this string can be interpreted as an integer number iPos, the iPos -th successor window (if iPos>0 ) or the -iPos -th predecessor window (if iPos<0 ) is used; otherwise, a window that has pcWdw as its title is sought.
- int iDx
- first mesh dimension
- int iDy
- second mesh dimension
- int iNum
- nr of data points per record (each record specifies one mesh point)
- char *pcFmt
- format string specifying which data elements of each record are translated into graphical attributes (such as location, symbol type or color) of associated mesh point (see below)
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE OF CREATED UNIT:
If iDx>0 and iDy>0:
- in_0[iDx*iDy*iNum]:
- (packed input field 0) mesh data
- in_1[7]:
- (input field 1) default values to be used
to render attributes not specified in pcFmt string.
- CTL_in[1]:
- (control field) taken as linewidth
- out_0[2]:
- (output field 0) coordinates of current mesh pt
- out_1[]:
- (output field 1) remaining attributes of current meshpt
If iDx=iDy=0:
- in_0[*]:
- (dynamic float input field 0) input mesh data
- in_1[7]:
- (input field 1) default values to be used
to render attributes not specified in pcFmt string.
- in_2[*]:
- (dynamic float input field 0) mesh size info array:
either a sequence of (Dx,Dy) pairs for partitioning
the input mesh data at field in_0 into as many
meshes as there are pairs, or an integer G>0
followed by G integer values ni>=0. Each nonzero
ni specifies to connect the next ni data points
by a line. Corresponding points of consecutive lines
of equal ni will also be connected by a second,
orthogonal set of lines to form a mesh. Values of
ni=0 may be interspersed as separators to allow
drawing of several meshes. Which format is used
will be recognized automatically.
- CTL_in[1]:
- (control field) taken as linewidth
- out_0[2]:
- (output field 0) coordinates of current mesh point
- out_1[]:
- (output field 1) remaining attributes of current mesh
point
EXECUTION OF CREATED UNIT:
INITIALIZATION:
DESCRIPTION:
Creates a unit execution of which will render iDx*iDy data
points in various user-selectable ways (if iDx=iDy=0, the
input will become a dynamic float array, and there will be
an additional dynamic float input field to provide the
mesh size specification. This allows detailed control of
the connecting of points by mesh lines, including the drawing
of several meshes). Each data point is
identified by an index pair (i,j). The input field Z_in is
considered as an array of iDx*iDy*iNum (or more, in the case
of iDx=iDy=0) float values. Each block
of dim consecutive float values is considered as a "data
record", specifying a single point (i,j), i=0..nx-1,
j=0..ny-1. (the first iNum elements of the data record for
point (i,j) are taken from pins (i+j*nx)*iNum+k, k=0..iNum-1).
The format string pcFmt determines, which of the iNum values of
a data record are used to render the associated mesh point
and how the selected values are translated into graphical
attributes, such as location and color of the point (the
specification in pcFmt applies for all data records).
The graphics attributes that are to be used for rendering
and the values of each data record that determine them are
selected by specifying a (single) mask field in the format
string pcFmt. The mask field consists of up to iDim characters
enclosed by the pair %C (percent sign and a command
letter C). Each occupied character location matches one of
the iNum values of a record (starting with the first value at
the leftmost character location), and the character itself
selects the attribute to be determined by this value (for
the allowable characters and their meaning, see below). A
special role is played by the characters # and *. The char-
acter # acts as a place holder, i.e. each occurrence of a #
matches a a single element of a record, however, without
using its value. The first (i.e. leftmost) occurrence of a *
acts as exactly as many placeholder #'s as are necessary to
make the remaining characters (including other \*'s or #'s)
of the mask match the remaining values of the record. All
additional occurrences of a * are regarded as if each of
them were a single #.
In addition to \* and #, 9 other characters are currently
recognized in the mask field (any other unrecognized charac-
ter is treated as if it were a #) and interpreted in the
following way:
- x:
- use value at matching position as x-location of the mesh
point
- y:
- use value at matching position as y-location of the mesh
point
- z:
- use value at matching position as z-location of the mesh
point (implies drawing into window of plot3d-unit)
- s:
- use value at matching position as relative (s) or
absolute (S) size of the mesh point
- m:
- use value at matching position as specifying a marker
type
- c:
- use value at matching position as color at
at mesh point
- g:
- use value at matching position as gray level at
at mesh point
- u:
- use value at matching position as horizontal (x) component
if vector or error bar is specified
- v:
- likewise, for vertical (y) component
- w:
- likewise, for depth (z) component (implies drawing
into a plot3d window)
If one of x or y is missing, a default range of
X_in[0]..X_in[1] and Y_in[0]..Y_in[1] is used along the
corresponding axis. The same assumption is made for the z-direction
The command character C immediately following the control
field determines, how the selected attributes are displayed
graphically. Currently, the following alternatives for C
are recognized:
- P
- "Point Cloud": Display data as a
"cloud" of iDx*iDy symbols, using the speci-
fied symbol type,
location and color.
- E
- "Error Bars": As P, but use any speci-
fied size values to display two error
bars centered at each point location and
extending by the specified sizes along
the two axis directions (i.e. the
total length of the error bar parallel
to the x-axis is 2*xsize and similarly
for the other two directions).
- V
- "Vector field": As P, but in addition
display at each location a vector the
components of which are given by the
two size values.
- D
- "Direction field": As V, but center the
mid point of the vector at the specified
point locations.
- M
- "Mesh plot": As P, but with an additional
mesh of
grid lines appropriately colored, if
a value for C is specified. Any specified size
values are disregarded.
- C
- integer from the range 1-7 specifying one
of the colors white,red,green,blue,yellow,
magenta, cyan.
- G
- integer from the range 0..255 specifying
a gray value. NOTE: when both C and G
are given, the rightmost occurrence
is used [not implemented]
- S
- integer from the range 1-7 specifying
a marker symbol to be centered at (x,y)
Markers are point,square,diamond,triangle,
cross,plus,star,circle.
- W:
- size (width) of the marker symbol,
in absolute user coord
- w:
- as W, but window units (the window taken
as 1000 units wide)
FURTHER OPTIONS:
The above can be followed by the option %I to activate
inverse drawing mode.
In this mode, drawing is made in inverse color and the
second and each subsequent exec_unit call
will first undraw the previously drawn mesh before
drawing the new mesh, again using inverse color. This
allows to display changes without intervening global clears
(which are also slow for large windows).
CONTROL MODES:
EXAMPLES:
STATUS:
Preliminary. Some options are not yet implemented.
SEE ALSO:
draw_sym, draw_str, mesh_unit
FILE
/homes/jontrup/nst5/man/../o.sol2//../nstsrc/nst_draw.c