NAME

iso_surface -- render isosurface

PROTOTYPE

unitptr iso_surface( int iOperands, int iDx, int iDy, int iDz, char *pcOptions, void (*pGLRenderer)(char, /* if non-null, the unit will use, unitptr uHost)

ARGUMENTS

int iOperands
nr of operandsi (may be zero)
int iDx
nr of mesh values along x-direction
int iDy
nr of mesh values along y-direction
int iDz
nr of mesh values along z-direction
char *pcOptions
options [see below]
void (*pGLRenderer)(char
- not documented in source --
/* if non-null, the unit will use
if non-null, the unit will use this function as its render function (cf 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:

X_in[1]:
the level value
Y_in[iDx*iDy*iDz]:
(packed input field 0) a iDx*iDy*iDz-array providing the isodata (linear storage, x index varying fastest, z index slowest).
Z_in[iNum]:
(input field 1) color information. The dimension iNum depends on the chosen color option (see below).
CTL_in[]:
(control field)

SYNOPSIS:

Computes and optionally renders an isosurface for a volume data set of iDx x iDy x iDz scalar values on a 3-dimensional orthogonal grid. The isosurface will belong to the isovalue specified at input field X_in. The data at input field Y_in[] specify the volume data, the data at input field Z_in[] specify how the isosurface will be colored (see OPTIONS below). The computed isosurface will consist of a set of triangles. If iOperands==0, the unit will always render the isosurface. If iOperands>0, the unit will also render the surface, but will during rendering also act as an iterator over all triangles of the isosurface, executing its abs(iOperands) successor units for each triangle while offering the vertices of the current triangle at the three output fields X_out[3]..Z_out[3]. A fourth output field will hold a normal vector for the current triangle with length normalized to the area of the current triangle. This mode allows to perform special computations on the isosurface, such as flow or surface calculation. Finally, when iOperands<0, the the same operations will be performed, but rendering will be suppressed. This mode allows to perform computations with the surface, without any graphical rendering involved.

EXECUTION OF CREATED UNIT:

OPTIONS:

The option string pcOpt allows to specify a rendering window and to set various options that affect the computation of the isosurface and, in particular, the adopted coloring strategy. For the non-GL-version, the rendering window must belong to a plot3d unit and is specified by a string name (not beginning with a %-character). For the GL-version, the rendering window is automatically chosen to be the window that belongs to the view3d unit in whose scope the present unit lies. Additional options are of the form %a:...dC with a..d zero to four colon-separated numeric parameters and C a command letter from the set . selecting one of the following options:

COLOR OPTIONS FOR GL-VERSION:

These options are only available for the GL version iso_surface_GL of the present unit:
%r:g:bR:
pointwise RGB-coloring: in this case, Z_in[] is an array of N=iDx x iDy x iDz RGB-triples (i.e., its dimension is 3N) that specify a color value for each point of the volume data. The layout of Z_in[] is the same as that of Y_in[], i.e., the n-th color triple belongs to the n-th point in Y_in[]. If no parameters r,g,b are given, the color range is 0..255 for each color channel. Otherwise, the color range will be 0..r, 0..g and 0..b for the red, green and blue channel, respectively (but note that the type of the color input field Z_in[] will always be the same as the type of the volume data input field Y_in[]; thus, in the case of integer data, small values of r,g,b will lead to more or less coarse rounding of color values!)
%h:s:iH:
(THIS NOT YET IMPLEMENTED) pointwise HSI-coloring: this is fully analogous to pointwise RGB-coloring, but with the input values at Z_in[] now interpreted as HSI-triples. (again with default range 0..255 in each parameter, or 0..h, 0..s, 0..i, if 3 parameters are given).
%a:bI:
(THIS NOT YET IMPLEMENTED) pointwise intensity `coloring'': the color input array now expects only N=iDx x iDy x iDy intensity values for a gray level. If two parameters a,b are given, a will be mapped to black, and b to white, with linear interpolation for intermediate values and clipping at the limits. If only a single parameter a is specified, %aI will be interpreted as %0:aI.
%a:bC:
(THIS NOT YET IMPLEMENTED) pointwise hue coloring: similar to %a:bI, but now each input value specifies a color hue.
If the analogous options, but with lower command letters r, h, i, c are given, the coloring modes will be global: in this case, input field Z_in[] only expects the color parameters (RGB-triple, HSI-triple, intensity or hue) for a single point and all vertices will share this specified color. If rendering is combined with iterator mode (for iOperands>0), the r, h, i, c modes can be used to implement again a position-dependent coloring: in this case, the color that is valid at Z_[] at the end of the current iteration will be used to render the current triangle (each triangle is rendered at the end of the associated iteration, i.e., when all operands have been executed). This allows, e.g., to make the color of the isosurface a function of the result of the operand's computation on the local triangle. Note, however, that in this mode combination only a single color per triangle can be specified, whereas the capital letter modes %R,H,I,C allow to specify a color for each vertex (and triangles are then colored by interpolating their vertex colors, thus leading to smoother coloring).

GENERAL OPTIONS:

These options are available for both the GL and the non-GL version of the unit.
%B:
remove backfacing triangles from both rendering and iterated triangle set
%b:
remove backfacing triangles only from rendering and iterated triangle set

NOTE:

The present unit comes in two versions: the `plain'' version will render into the non-GL window of a plot3d unit, the GL version will render into the GL-window of a view3d unit. Only the latter alternative offers the various coloring options listed above. In the plain version, the iso-surface will be rendered as a mesh surface and only the coloring options %c and %i will be recognized. In this case, the colors for option %c will be specified by negative integers that are interpreted in the same manner as by the write_pix unit in Colormap mode.

EXAMPLES:

STATUS:

Alpha.

SEE ALSO:

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst_iso.c