com.openinventor.volumeviz.nodes

Class SoHeightFieldRender

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.misc.SoBase

com.openinventor.inventor.fields.SoFieldContainer

com.openinventor.inventor.nodes.SoNode

com.openinventor.inventor.nodes.SoShape

com.openinventor.ldm.nodes.SoLdmShape

com.openinventor.volumeviz.nodes.SoVolumeShape

com.openinventor.volumeviz.nodes.SoSlice

com.openinventor.volumeviz.nodes.SoHeightFieldRender

All Implemented Interfaces:

SafeDisposable

public class SoHeightFieldRender
extends SoSlice

Heightfield rendering node. SoHeightFieldRender displays a uniform grid in the XY plane whose vertices are height (Z) values stored in 2D LDM format (any LDM data set with the Z dimension equal to 1). Adding the combination of LDM data management with advanced GPU features provides a way to handle extremely large surfaces. Just as with volume data, LDM uses tiles of data and multiple levels of resolution to enable interactive frame rates even for data sets that cannot fit in system memory.

This node is used similar to SoVolumeRender, but instead of an SoVolumeData node, you use an SoHeightFieldGeometry for the data set (height values) and one or more SoHeightFieldProperty nodes for property data sets. Generally it obeys the same rules regarding multiple data sets (see SoMultiDataSeparator). Undefined or undesired points may be excluded by setting their value to the "undefined" value in the SoHeightFieldGeometry data set. In addition, undefined or undesired cells may be excluded by specifying a binary mask using an SoHeightFieldPropertyMask node.

Data set values are converted to height values in 3D space in two ways depending on the data type:

• Integer values are normalized between [0,1] ([-1,1] for signed types) based on the range of values for the specific data type. For example, for UNSIGNED BYTE values the range 0..255 is mapped to 0..1.
• Floating point values are not normalized (are used "as is").

Any height values in the SoHeightFieldGeometry data set that are equal to the "undefined" value will be rendered as holes in the mesh. The undefined value can be specified during the LDM conversion using the "-u" option to the LDM converter:

   convert -u 127 -b 1 inputFile.lst

Or by setting the undefinedValue field of the SoHeightFieldGeometry node. The default value is NaN (Not a Number).

An SoHeightFieldPropertyMask node may be used to specify undefined cells in the mesh. An undefined cell effectively removes the four corresponding height values from the mesh. (SoVolumeMask does not apply to height field rendering.)

A lighted heightfield

VolumeViz provides default shaders that conveniently color the surface using a single property, as shown in the images. However it is also possible to combine multiple properties using a custom shader program, in the same way that you would combine multiple volumes.

The field cellOutline enables drawing the edges of the mesh cells. BoundaryCells are cells close to undefined value. If the boundaryCells field is set to ALWAYS, these cells must be always considered at all resolution levels to avoid artifacts. In SMART mode, the default, we don't take this into account for distant views.

Normally this node uses the OpenGL tessellation shader extension to speed up rendering and automatically adjust the number of generated triangles depending on the camera position and orientation. In this mode, to change the number of generated triangles, use an SoComplexity node. A value of 1 means a full tessellation with a maximum of 4 triangles per pixel and a value of 0.5 means a maximum of 1 triangle per pixel.

If tessellation shaders are not available, use the SoComplexity node to control and limit the number of generated triangles. Use the SoGLExtension method isAvailable( "GL_ARB_tessellation_shader" ) to check if tessellation shaders are supported.

Multidata rules apply to the creation of a scene graph using a SoHeightFieldRender. SoMultiDataSeparator must be used instead of SoSeparator. A minimal scene graph displaying a heightfield is:

EXAMPLE

 // Create nodes
 SoHeightFieldGeometry HFGeom = new SoHeightFieldGeometry();
   HFGeom.fileName.setValue( "$OIVHOME/examples/source/VolumeViz/Data/horizon.ldm" );
   HFGeom.dataSetId.setValue( 1 );
 
 SoHeightFieldProperty HFProp = new SoHeightFieldProperty();
   HFProp.fileName.setValue( "$OIVHOME/examples/source/VolumeViz/Data/horizon.ldm" );
   HFProp.dataSetId.setValue( 2 );
 
 SoMaterial material = new SoMaterial ();
   material.diffuseColor.setValue( 1, 1, 1 );
 
 SoTransferFunction TF = new SoTransferFunction();
   TF.predefColorMap.setValue( SoTransferFunction.PredefColorMaps.STANDARD );
 
 SoHeightFieldRender HFRend = new SoHeightFieldRender();
 
 // Limit triangles (optional)
 SoComplexity complexity = new SoComplexity();
   complexity.value.setValue( 0.25 );
 
 // Build scene graph
 SoMultiDataSeparator volSep = new SoMultiDataSeparator();
   volSep.addChild( HFGeom );
   volSep.addChild( HFProp );
   volSep.addChild( material );
   volSep.addChild( complexity );
   volSep.addChild( TF );
   volSep.addChild( HFRend );
 root.addChild( volSep );             

Shaders

When used with an SoVolumeShader, a new shader function is available to compute lighting:

• vec4 VVizComputeFrontColor(vec3 normal, vec4 color)): Add lighting to the color col.

The following shader code code will light a heightfield:

 vec4 VVizComputeVolumeRendering(float sf);
 float VVizCombineData(vec2 tcoord);
 vec3 VVizComputeCoordinates(const vec3);
 void VVizOutputColor(vec4 color);
 vec4 VVizComputeFrontColor(vec3 n, vec4 col);
 vec3 VVizComputeGradient(vec3 tcoord);
 
 void main()
 {
   vec3 tCoord0 = VVizComputeCoordinates(gl_TexCoord[0].xyz);
   vec3 grad = VVizComputeGradient(tCoord0);
   vec3 normal = normalize(gl_NormalMatrix*grad);
 
   float sf = VVizCombineData(tCoord0.xy);
   vec4 col = VVizComputeVolumeRendering(sf);
 
   col = VVizComputeFrontColor(normal, col);*
   VVizOutputColor(col);
 }

Picking:

Similar to other geometry, SoPickedPoint can return an SoDetail object specific to the SoHeightFieldRender node. The specific class is SoHeightFieldDetail.

Only GPU picking is supported. This means that the SoRayPickAction used for picking must have its scene manager initialized using the method SoAction.setSceneManager(). SoHandleEventAction does this automatically, so it is not necessary for the application to take any action when using (for example) a SoEventCallback node and calling the getPickedPoint() method. However if the application creates its own SoRayPickAction then it must set the scene manager. If no scene manager is specified, a warning message is issued.

Limitations:

At least one SoHeightFieldProperty which defines a property data set associated with the grid must be in the state.

If an SoROI is in the state, SoHeightFieldRender renders only one box of the ROI (ie: correct rendering only if SoROI's flag field is set to SUB_VOLUME)

Only SoHeightFieldGeometry data sets with a depth of 1 (Z dimension = 1) can be rendered.

The SoHeightFieldProperty and SoHeightFieldPropertyMask data sets must have exactly the same dimensions as the SoHeightFieldGeometry.

Triangle orientation after GPU tessellation cannot be controlled. Undefined value rendering is indeterministic.

For low resolution, undefined values can be taken into account in the property but not in the geometry. In such cases, coloring artifacts can appear.

Lighting is limited to directional lights and base color. Other kinds of lights can be implemented manually using a custom shader.

By default, two-sided lighting is not enabled ("back" side of surface will not be lighted). Use an SoShapeHints node to enable two-sided lighting.

The enableBumpMapping field is not supported on this node

SoHeightFieldPropertyMask and cellOutline can be used only if tesselation shaders are supported. Use the SoGLExtension method isAvailable( "GL_ARB_tessellation_shader" ) to check this support.

File format/default:

HeightFieldRender {

enableBumpMapping	false
bumpScale	1.0
alternateRep	NULL
useRGBA	false
normalPrecision	HIGH
cellOutline	false

}

See also:

SoHeightFieldProperty, SoHeightFieldPropertyMask, SoHeightFieldRender, SoHeightFieldGeometry, SoMultiDataSeparator

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoHeightFieldRender.BoundaryCellsType Boundary cells mode.
static class	SoHeightFieldRender.NormalPrecisions Deprecated.

Nested classes/interfaces inherited from class com.openinventor.volumeviz.nodes.SoSlice

SoSlice.AlphaUses

Nested classes/interfaces inherited from class com.openinventor.volumeviz.nodes.SoVolumeShape

SoVolumeShape.Compositions, SoVolumeShape.Interpolations

Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoShape

SoShape.ShapeTypes

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALWAYS Deprecated. Use SoHeightFieldRender.BoundaryCellsType.ALWAYS instead.
SoSFEnum<SoHeightFieldRender.BoundaryCellsType>	boundaryCells Boundary cells mode.
SoSFBool	cellOutline If true, draw outline of each heightField cell (default is false).
SoSFColor	cellOutlineColor When cellOutline is true, this value specifies the cell outline color.
SoSFFloat	cellOutlineWidth When cellOutline is true, this value specifies the cell outline width in pixels.
static int	HIGH Deprecated. Use SoHeightFieldRender.NormalPrecisions.HIGH instead.
static int	NONE Deprecated. Use SoHeightFieldRender.BoundaryCellsType.NONE instead.
static int	NORMAL Deprecated. Use SoHeightFieldRender.NormalPrecisions.NORMAL instead.
SoSFEnum<SoHeightFieldRender.NormalPrecisions>	normalPrecision Deprecated. As of Open Inventor 9300 See documentation for more details
static int	SMART Deprecated. Use SoHeightFieldRender.BoundaryCellsType.SMART instead.

Fields inherited from class com.openinventor.volumeviz.nodes.SoSlice

ALPHA_AS_IS, ALPHA_BINARY, ALPHA_OPAQUE, alphaUse, alternateRep, bumpScale, enableBumpMapping, largeSliceSupport, useRGBA

Fields inherited from class com.openinventor.volumeviz.nodes.SoVolumeShape

ALPHA_BLENDING, composition, COMPOSITION_LAST, CUBIC, interpolation, LINEAR, MAX_INTENSITY, MIN_INTENSITY, MULTISAMPLE_12, NEAREST, SUM_INTENSITY, TRILINEAR

Fields inherited from class com.openinventor.inventor.nodes.SoShape

boundingBoxIgnoring, LINES, POINTS, POLYGONS, TEXT

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoHeightFieldRender() Constructor.

Method Summary

Modifier and Type	Method and Description
static boolean	isSupported() Calls isSupported((com.openinventor.inventor.misc.SoState)null).
static boolean	isSupported(SoState state) Returns true if graphic card can render a SoHeightFieldRender.

Methods inherited from class com.openinventor.ldm.nodes.SoLdmShape

intersect

Methods inherited from class com.openinventor.inventor.nodes.SoShape

getShapeType, isPrimitiveRestartAvailable, isPrimitiveRestartAvailable

Methods inherited from class com.openinventor.inventor.nodes.SoNode

affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write

Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer

copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults

Methods inherited from class com.openinventor.inventor.misc.SoBase

dispose, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALWAYS

@Deprecated
public static final int ALWAYS

Deprecated. Use SoHeightFieldRender.BoundaryCellsType.ALWAYS instead.

SMART

@Deprecated
public static final int SMART

Deprecated. Use SoHeightFieldRender.BoundaryCellsType.SMART instead.

NONE

@Deprecated
public static final int NONE

Deprecated. Use SoHeightFieldRender.BoundaryCellsType.NONE instead.

NORMAL

@Deprecated
public static final int NORMAL

Deprecated. Use SoHeightFieldRender.NormalPrecisions.NORMAL instead.

HIGH

@Deprecated
public static final int HIGH

Deprecated. Use SoHeightFieldRender.NormalPrecisions.HIGH instead.

cellOutline

public final SoSFBool cellOutline

If true, draw outline of each heightField cell (default is false).

cellOutlineWidth

public final SoSFFloat cellOutlineWidth

When cellOutline is true, this value specifies the cell outline width in pixels. Default is 2 pixels.

Since:

Open Inventor 9.7

cellOutlineColor

public final SoSFColor cellOutlineColor

When cellOutline is true, this value specifies the cell outline color. Default is black : (0, 0, 0).

Since:

Open Inventor 9.7

boundaryCells

public final SoSFEnum<SoHeightFieldRender.BoundaryCellsType> boundaryCells

Boundary cells mode. Setting this field to SMART will not compute boundary cells for distant views. . Default is SMART.

normalPrecision

@Deprecated
public final SoSFEnum<SoHeightFieldRender.NormalPrecisions> normalPrecision

Deprecated. As of Open Inventor 9300 See documentation for more details

Deprecated since Open Inventor 9300
No longer used. Normals are now computed on the fly on gpu.

Constructor Detail

SoHeightFieldRender

public SoHeightFieldRender()

Constructor.

Method Detail

isSupported

public static boolean isSupported()

Calls isSupported((com.openinventor.inventor.misc.SoState)null).

isSupported

public static boolean isSupported(SoState state)

Returns true if graphic card can render a SoHeightFieldRender. GPU must support geometry shaders, floating point textures and vertex buffer objects (VBO) and tessellation shaders