NAME

make_mesh - render various types of mesh objects

PROTOTYPE

unitptr make_mesh( int nx, int ny, int dim, char *fmt, unitptr host)

ARGUMENTS

int nx
number of mesh points along first mesh direction
int ny
number of mesh points along second mesh direction
int dim
number of data elements per record (each record specifies one mesh point)
char *fmt
format string specifying which data elements of each record are used for rendering and how these are translated into graphics attributes for the rendered mesh point (such as location, shape, color)
unitptr host
host unit for newly created instance

RETURN VALUE:

unitptr u
pointer to newly created unit

INTERFACE OF CREATED UNIT:

X_in[2]:
default range for x-values. (default is (0,1)).
Y_in[2]:
default range for y-values. (default is (0,1)).
Z_in[nx*ny*dim]:
(packed input field) data input. Must be connected to a packed field or assigned to a float array holding nx*ny*dim float values, grouped into nx*ny consecutive blocks ("data records") of dim values each. Each record specifies one data point of the mesh plot.
in_3[3]:
default color, if none of rgb is specified (default values: (255,180,80) (orange)).
in_4[3]:
default sizes, if none of XYZ is specified (preset values: (0,0,0)).
in_5[3]:
value range for color (changing values in this field will also affect the interpretation of the color values in field in_3!). Default is (255,255,255).
in_6[3]:
minimum value for color. (changing values in this field will also affect the interpretation of the color values in field in_3!). Default is (0,0,0).

DESCRIPTION:

Creates a unit execution of which will render nx*ny data points in various user-selectable ways. Each data point is identified by an index pair (i,j). Input field Z_in is considered as an array of nx*ny*dim 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 dim elements of the data record for point (i,j) are taken from pins (i+j*nx)*dim+k, k=0..dim-1). The format string fmt determines, which of the dim 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 fmt 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 fmt. The mask field consists of up to dim characters enclosed by the pair "%..C" (percent sign and a command letter C). Each occupied character location matches one of the dim 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 character # 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 character 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
X:
use value at matching position as x-size of the mesh point
Y:
use value at matching position as y-size of the mesh point
Z:
use value at matching position as z-size of the mesh point
r:
use value at matching position as red-intensity (range 0..255) at mesh point
g:
use value at matching position as green-intensity (0..255) at mesh point
b:
use value at matching position as blue-intensity (range 0..255) at mesh point
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. If z is missing, a value of zero is used. If all three of r,g,b are missing, a default color that is specified at input field in_3 is used. If at least one of r,g,b is specified, the color values for the unspecified colors are set to zero intensity. If all of X,Z,Z are missing, default sizes specified at input field in_4 are used. If at least one of X,Y,Z is specified, a value of zero is used for the unspecified sizes. 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 nx*ny dots, using the specified location and color. Each dot is one pixel large, and any specified size values are disregarded.
E:
"Error Bars": As .P, but use any specified size values to display three error bars centered at each point location and extending by the specified sizes along the three 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 three size values.
D:
"Direction field": As V, but center the mid point of the vector at the specified point locations.
M:
"Mesh plot": Display data as a mesh of grid lines appropriately colored, if r,g,b are specified. Any specified size values are without effect.
S:
"Surface plot": Display data as a gouraud-shaded surface. Any specified size values are without effect.
If no mask field is specified, the default mask zM is used (in this case, a mesh surface is constructed, using the first element of each record as z-value).

SEE ALSO:

view3d

EXAMPLES:

The programs fview.c and xor.c use the make_mesh -unit to create data plots. The program somdemo.c shows how a make_mesh -unit can access and render the weight values of a som_layer -unit.

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_solid.c