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