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