com.openinventor.ldm.nodes

Class SoROI

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.misc.SoBase

com.openinventor.inventor.fields.SoFieldContainer

com.openinventor.inventor.nodes.SoNode

com.openinventor.ldm.nodes.SoROI

All Implemented Interfaces:

SafeDisposable

Direct Known Subclasses:

SoROIManip

public class SoROI
extends SoNode

Region of Interest (subvolume) node. The ROI ("region of interest") node allows you to specify a sub-region of the volume that will be rendered. Voxels within the ROI are rendered; voxels outside the ROI are not rendered. This provides a simple and very efficient form of volume clipping (much more efficient than using SoClipPlane nodes).

In addition, for large volumes that cannot be fully loading into CPU and/or GPU memory, SoROI can improve both data loading performance and image quality. VolumeViz will always try to load the highest resolution data possible for the voxels inside the region defined by the ROI. VolumeViz is not required to load data in tiles that are completely outside the ROI. VolumeViz may load tiles outside the ROI if there is sufficient memory (this is useful in cases where the user can move or resize the ROI). But in general, for large volumes, using SoROI reduces the amount of data that must be loaded and increases image quality for the voxels inside the ROI.

Note that the above discussion only applies in multi-resolution mode (the default). In fixed resolution mode (see SoLDMResourceParameters.fixedResolution), VolumeViz will try to load all the tiles in the volume at the specified resolution level regardless of the SoROI settings.

The ROI can be a simple box (default) or a complex shape defined by (up to) three box shapes (X, Y, and Z slabs) and logic flags that specify how the slabs are to be combined.

SoROI is commonly used with an opaque color map to provide a "volume probe" in seismic data applications. However it is useful with any kind of volume data to limit the data displayed and to improve loading and image quality as discussed above.

The box and subVolume fields are specified in voxel coordinates. The limits are included in the ROI. A value of 0,0,0 0,0,0 (min and max) in the subVolume field means that this field should be ignored. This is the default.

This node acts on the rendering shape nodes of VolumeViz (SoVolumeRender, SoOrthoSlice, SoObliqueSlice, SoVolumeSkin, etc.)

To define a simple ROI, set the limits of the ROI in the box field (and do not set the subVolume field). The same result is obtained by setting the box and subVolume fields to the same value, but this is not necessary. But note that the default ROI box is not automatically the full volume. You must initialize the ROI box to something, for example the volume dimensions minus one.

 // Initialize ROI box to full volume
 SoVolumeData volData = new SoVolumeData();
 . . .
 SoROIManip roiManip = new SoROIManip();
 roiManip.box.setValue( new SbVec3i32(0, 0, 0), volData.data.getSize().minus( new SbVec3i32(1, 1, 1)));
 root.addChild( roiManip );

For a complex ROI, the region defined by the SoROIbox field always acts upon the region defined by the SoROIsubVolume field, not the entire volume. For example, in EXCLUSION_BOX mode, the visible portion of the volume is the subVolume region minus the box region. You are allowed to set the box region larger than (or completely outside) the subVolume region, but only the intersection of the two regions is significant.

You can also use the convenient manipulator class SoROIManip to allow your users to interactively move and resize the region of interest.

The figures below show the subVolume field used to limit the visible portion of the volume (left) and the ROI used as an "exclusion box" to cut away part of the subvolume (right).

Example: box field used to limit visible portion of the volume

Example: box field + subVolume field used as an exclusion box

The Crop Box and Cropping Process.

The crop box is defined by three sets of parallel planes that define three slabs:

• The xmin and xmax planes define the X slab.
• The ymin and ymax planes define the Y slab.
• The zmin and zmax planes define the Z slab.

After these three planes have been specified, cropping is done in four stages.

Stage 1 determines which voxels to include relative to one or more of the slabs. Classification can be enabled or disabled relative to the X slab, Y slab, or Z slab. This classification is performed three separate times, resulting in three terms: Term 0, Term 1, and Term 2. Each term has its own logic flags that enable the three slabs, independent of the other terms. The flags are as follows:

• Enable or disable classification relative to the X slab.
• Enable or disable classification relative to the Y slab.
• Enable or disable classification relative to the Z slab.

Stage 2 determines whether to invert the values obtained in Stage 1 so that the voxels outside a slab are selected. This determination is made for each of the terms (Term 0, Term 1, Term 2). As in Stage 1, each term has its own inversion flag and is independent of the other terms.

Stage 3 creates either the union or the intersection of Term 0, Term 1, and Term 2. This is specified using a logic flag.

Stage 4 determines whether to invert the result of Stage 3 and provides the final ROI. Again, the inversion (if any) is specified using a logic flag.

Example of Cropping Process

(Figures courtesy Real Time Visualization)

The following example will show you how the cropping process works.

Start with a volume that is 100x200x100 (x, y, z). The final cropped shape will be the union of a 20x200x20 bar and a 100x25x100 box.

Here is the initial volume:

Here is the bar:

The bar can be formed in Term 0 of Stage 1 by using the intersection of the X and Z slabs, each with min and max values set to 40 and 60, respectively.

Here is the box:

The box can be formed in Term 1 of Stage 1 by using just the Y slab, with min and max values set to 125 and 150.

Term 2 of Stage 1 can be set to be identical to Term 0 or Term 1, or it can be set to include no samples by setting no enable flags (no slabs selected, so entire volume is selected) and setting the invert flag of Stage 2 so that the entire volume is deselected. To get the union of these terms in Stage 3, OR_SELECT is set. That results in the desired cropping, so Stage 4, in which the results are inverted, is not used.

Here is the code to set the box dimensions and the logic flags:

 SoROI myROI = new SoROI();
 int xmin =  40; int xmax =  60;
 int ymin = 125; int ymax = 150;
 int zmin =  40; int zmax =  60;
 myROI.box.SetValue( xmin, ymin, zmin, xmax, ymax, zmax );
 myROI.flags.setValue( SoROI.FlagsType.ENABLE_X0.getValue() |
                       SoROI.FlagsType.ENABLE_Z0.getValue() |
                       SoROI.FlagsType.ENABLE_Y1.getValue() |
                       SoROI.FlagsType.INVERT_2.getValue()  |
                       SoROI.FlagsType.OR_SELECT.getValue()  );

Here is the resulting complex crop box:

Additional Examples

	Example 1: flags = SUB_VOLUME Alternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2
	Example 2: flags = FENCE Alternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2 | OR_SELECT
	Example 3: flags = FENCE Note that example 2 and 3 have the same flags set; but in example 2, xmin, ymin, and zmin values are set to zero. Setting its xmax, ymax, and zmax values to the maximum value produces a similar crop.
	Example 4: flags = FENCE_INVERT Alternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2 | OR_SELECT | INVERT_OUTPUT
	Example 5: flags = CROSS Alternate setting:flags = ENABLE_X0 | ENABLE_Y0 | ENABLE_Y1 | ENABLE_Z1 | ENABLE_X2 | ENABLE_Z2 | OR_SELECT
	Example 6: flags = CROSS_INVERT Alternate setting:flags = CROSS | INVERT_OUTPUT

File format/default:

ROI {

subVolume	0, 0, 0, 0, 0, 0
box	0, 0, 0, 1, 1, 1
flags	7
relative	false

}

LIMITATIONS Only one ROI per volume data can be used at same time.

See also:

SoVolumeRender, SoOrthoSlice, SoObliqueSlice, SoROIManip

Action behavior:

SoCallbackAction, SoGLRenderAction, SoGetBoundingBoxAction, SoPickAction, SoWriteAction

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoROI.FlagsType Flag value mask.

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

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
SoSFBox3i32	box Specifies the bounds of the region of interest.
static int	CROSS Deprecated. Use SoROI.FlagsType.CROSS instead.
static int	CROSS_INVERT Deprecated. Use SoROI.FlagsType.CROSS_INVERT instead.
static int	ENABLE_X0 Deprecated. Use SoROI.FlagsType.ENABLE_X0 instead.
static int	ENABLE_X1 Deprecated. Use SoROI.FlagsType.ENABLE_X1 instead.
static int	ENABLE_X2 Deprecated. Use SoROI.FlagsType.ENABLE_X2 instead.
static int	ENABLE_Y0 Deprecated. Use SoROI.FlagsType.ENABLE_Y0 instead.
static int	ENABLE_Y1 Deprecated. Use SoROI.FlagsType.ENABLE_Y1 instead.
static int	ENABLE_Y2 Deprecated. Use SoROI.FlagsType.ENABLE_Y2 instead.
static int	ENABLE_Z0 Deprecated. Use SoROI.FlagsType.ENABLE_Z0 instead.
static int	ENABLE_Z1 Deprecated. Use SoROI.FlagsType.ENABLE_Z1 instead.
static int	ENABLE_Z2 Deprecated. Use SoROI.FlagsType.ENABLE_Z2 instead.
static int	EXCLUSION_BOX Deprecated. Use SoROI.FlagsType.EXCLUSION_BOX instead.
static int	FENCE Deprecated. Use SoROI.FlagsType.FENCE instead.
static int	FENCE_INVERT Deprecated. Use SoROI.FlagsType.FENCE_INVERT instead.
SoSFBitMask<SoROI.FlagsType>	flags Specifies how the bounds of the box are used.
static int	INVERT_0 Deprecated. Use SoROI.FlagsType.INVERT_0 instead.
static int	INVERT_1 Deprecated. Use SoROI.FlagsType.INVERT_1 instead.
static int	INVERT_2 Deprecated. Use SoROI.FlagsType.INVERT_2 instead.
static int	INVERT_OUTPUT Deprecated. Use SoROI.FlagsType.INVERT_OUTPUT instead.
static int	OR_SELECT Deprecated. Use SoROI.FlagsType.OR_SELECT instead.
SoSFBool	relative Specifies whether the box bounds are relative to the subvolume or the full volume (i.e., are specified in absolute slice coordinates).
static int	SUB_VOLUME Deprecated. Use SoROI.FlagsType.SUB_VOLUME instead.
SoSFBox3i32	subVolume Specifies the bounds of the subvolume that will be rendered.

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoROI() Constructor.

Method Summary

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

ENABLE_X0

@Deprecated
public static final int ENABLE_X0

Deprecated. Use SoROI.FlagsType.ENABLE_X0 instead.

ENABLE_Y0

@Deprecated
public static final int ENABLE_Y0

Deprecated. Use SoROI.FlagsType.ENABLE_Y0 instead.

ENABLE_Z0

@Deprecated
public static final int ENABLE_Z0

Deprecated. Use SoROI.FlagsType.ENABLE_Z0 instead.

INVERT_0

@Deprecated
public static final int INVERT_0

Deprecated. Use SoROI.FlagsType.INVERT_0 instead.

ENABLE_X1

@Deprecated
public static final int ENABLE_X1

Deprecated. Use SoROI.FlagsType.ENABLE_X1 instead.

ENABLE_Y1

@Deprecated
public static final int ENABLE_Y1

Deprecated. Use SoROI.FlagsType.ENABLE_Y1 instead.

ENABLE_Z1

@Deprecated
public static final int ENABLE_Z1

Deprecated. Use SoROI.FlagsType.ENABLE_Z1 instead.

INVERT_1

@Deprecated
public static final int INVERT_1

Deprecated. Use SoROI.FlagsType.INVERT_1 instead.

ENABLE_X2

@Deprecated
public static final int ENABLE_X2

Deprecated. Use SoROI.FlagsType.ENABLE_X2 instead.

ENABLE_Y2

@Deprecated
public static final int ENABLE_Y2

Deprecated. Use SoROI.FlagsType.ENABLE_Y2 instead.

ENABLE_Z2

@Deprecated
public static final int ENABLE_Z2

Deprecated. Use SoROI.FlagsType.ENABLE_Z2 instead.

INVERT_2

@Deprecated
public static final int INVERT_2

Deprecated. Use SoROI.FlagsType.INVERT_2 instead.

OR_SELECT

@Deprecated
public static final int OR_SELECT

Deprecated. Use SoROI.FlagsType.OR_SELECT instead.

INVERT_OUTPUT

@Deprecated
public static final int INVERT_OUTPUT

Deprecated. Use SoROI.FlagsType.INVERT_OUTPUT instead.

SUB_VOLUME

@Deprecated
public static final int SUB_VOLUME

Deprecated. Use SoROI.FlagsType.SUB_VOLUME instead.

EXCLUSION_BOX

@Deprecated
public static final int EXCLUSION_BOX

Deprecated. Use SoROI.FlagsType.EXCLUSION_BOX instead.

CROSS

@Deprecated
public static final int CROSS

Deprecated. Use SoROI.FlagsType.CROSS instead.

CROSS_INVERT

@Deprecated
public static final int CROSS_INVERT

Deprecated. Use SoROI.FlagsType.CROSS_INVERT instead.

FENCE

@Deprecated
public static final int FENCE

Deprecated. Use SoROI.FlagsType.FENCE instead.

FENCE_INVERT

@Deprecated
public static final int FENCE_INVERT

Deprecated. Use SoROI.FlagsType.FENCE_INVERT instead.

box

public final SoSFBox3i32 box

Specifies the bounds of the region of interest. If subVolume is non-empty, the box is clamped at the bounds of the subvolume. Depending on the relative field, the bounds may be relative to the subvolume. Default is an (essentially) empty box.

flags

public final SoSFBitMask<SoROI.FlagsType> flags

Specifies how the bounds of the box are used. Default is SUB_VOLUME. The region of interest is the box itself.

subVolume

public final SoSFBox3i32 subVolume

Specifies the bounds of the subvolume that will be rendered. By default, it is an empty box and has no effect. The subvolume is always a simple box.

relative

public final SoSFBool relative

Specifies whether the box bounds are relative to the subvolume or the full volume (i.e., are specified in absolute slice coordinates). true means that if the subvolume is non-empty, moving the subvolume through the volume also moves the ROI box through the volume. Default is false.

Constructor Detail

SoROI

public SoROI()

Constructor.