Click or drag to resize
SoROI Class

Region of Interest (subvolume) node.

Inheritance Hierarchy

Namespace: OIV.LDM.Nodes
Assembly: OIV.LDM (in OIV.LDM.dll) Version: 10.12.3.0 (10.12.3.0)
Syntax
public class SoROI : SoNode

The SoROI type exposes the following members.

Constructors
  NameDescription
Public methodSoROI

Constructor.

Top
Methods
  NameDescription
Public methodAffectsState

Returns true if a node has an effect on the state during traversal.

(Inherited from SoNode.)
Public methodCallback
Public methodCopy
Calls Copy(false).
(Inherited from SoNode.)
Public methodCopy(Boolean)

Creates and returns an exact copy of the node.

(Inherited from SoNode.)
Public methodCopyFieldValues(SoFieldContainer)
Calls CopyFieldValues(fc, false).
(Inherited from SoFieldContainer.)
Public methodCopyFieldValues(SoFieldContainer, Boolean)

Copies the contents of fc's fields into this object's fields.

(Inherited from SoFieldContainer.)
Public methodDispose
Releases all resources used by SoDisposable.
(Inherited from SoDisposable.)
Public methodDistribute
(Inherited from SoNode.)
Public methodDoAction
Public methodEnableNotify

Notification at this Field Container is enabled (if flag == true) or disabled (if flag == false).

(Inherited from SoFieldContainer.)
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodFieldsAreEqual

Returns true if this object's fields are exactly equal to fc's fields.

(Inherited from SoFieldContainer.)
Public methodGet

Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.

(Inherited from SoFieldContainer.)
Public methodGetAllFields

Returns a list of fields, including the eventIn's and eventOut's.

(Inherited from SoFieldContainer.)
Public methodGetAlternateRep

This method is called by actions to allow the node to provide an "alternate representation" when appropriate (typically depending on the action type).

(Overrides SoNodeGetAlternateRep(SoAction).)
Public methodGetBoundingBox
Public methodGetEventIn

Returns a the eventIn with the given name.

(Inherited from SoFieldContainer.)
Public methodGetEventOut

Returns the eventOut with the given name.

(Inherited from SoFieldContainer.)
Public methodGetField

Returns a the field of this object whose name is fieldName.

(Inherited from SoFieldContainer.)
Public methodGetFieldName

Returns the name of the given field in the fieldName argument.

(Inherited from SoFieldContainer.)
Public methodGetFields

Appends references to all of this object's fields to resultList, and returns the number of fields appended.

(Inherited from SoFieldContainer.)
Public methodGetHashCode
Overrides GetHashCode().
(Inherited from SoNetBase.)
Public methodGetMatrix
(Inherited from SoNode.)
Public methodGetName

Returns the name of an instance.

(Inherited from SoBase.)
Public methodGetPrimitiveCount
(Inherited from SoNode.)
Public methodGetRenderEngineMode

Returns the supported Render engine mode.

(Inherited from SoNode.)
Public methodGetRenderUnitID
(Inherited from SoNode.)
Public methodGetStringName (Inherited from SoBase.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodGLRender
Public methodGLRenderBelowPath
(Inherited from SoNode.)
Public methodGLRenderInPath
(Inherited from SoNode.)
Public methodGLRenderOffPath
(Inherited from SoNode.)
Public methodGrabEventsCleanup
(Inherited from SoNode.)
Public methodGrabEventsSetup
(Inherited from SoNode.)
Public methodHandleEvent
(Inherited from SoNode.)
Public methodHasDefaultValues

Returns true if all of the object's fields have their default values.

(Inherited from SoFieldContainer.)
Public methodIsBoundingBoxIgnoring

This method is used by getBoundingBox action traversal to know if the current node must be traversed or not, ie the bounding should be ignored.

(Inherited from SoNode.)
Public methodIsNotifyEnabled

Notification is the process of telling interested objects that this object has changed.

(Inherited from SoFieldContainer.)
Public methodIsOverride

Returns the state of the override flag.

(Inherited from SoNode.)
Public methodIsSynchronizable

Gets the ScaleViz synchronizable state of this object.

(Inherited from SoBase.)
Public methodPick
Public methodRayPick
(Inherited from SoNode.)
Public methodSearch
(Inherited from SoNode.)
Public methodSet

Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.

(Inherited from SoFieldContainer.)
Public methodSetName (Inherited from SoBase.)
Public methodSetOverride

Turns the override flag on or off.

(Inherited from SoNode.)
Public methodSetSynchronizable

Sets this to be a ScaleViz synchronizable object.

(Inherited from SoBase.)
Public methodSetToDefaults

Sets all fields in this object to their default values.

(Inherited from SoFieldContainer.)
Public methodToString
Converts this SoBase structure to a human readable string.
(Inherited from SoBase.)
Public methodTouch

Marks an instance as modified, simulating a change to it.

(Inherited from SoNode.)
Public methodWrite
Top
Properties
  NameDescription
Public propertybox

Specifies the bounds of the region of interest.

Public propertydataSetId

Specifies which OIV.VolumeViz.Nodes.SoVolumeData node to use.

Public propertyflags

Specifies how the bounds of the box are used.

Public propertyIsDisposable
ISafeDisposable interface implementation.
(Inherited from SoDisposable.)
Public propertyrelative

Specifies whether the box bounds are relative to the subvolume or the full volume (i.e., are specified in absolute slice coordinates).

Public propertysubVolume

Specifies the bounds of the subvolume that will be rendered.

Public propertyUserData
Gets or sets the user data to be contained by the field container.
(Inherited from SoFieldContainer.)
Top
Remarks

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 OIV.Inventor.Nodes.SoClipPlane nodes).

The OIV.VolumeViz.Nodes.SoVolumeData node on which the ROI will be applied can be specified with OIV.LDM.Nodes.SoROI.dataSetId. When this field is set to 0, the last OIV.VolumeViz.Nodes.SoVolumeData node on state is used.

In addition, for large volumes that cannot be fully loading into CPU and/or GPU memory, OIV.LDM.Nodes.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 OIV.LDM.Nodes.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 OIV.LDM.Nodes.SoLDMResourceParameters.fixedResolution), VolumeViz will try to load all the tiles in the volume at the specified resolution level regardless of the OIV.LDM.Nodes.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.

OIV.LDM.Nodes.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 OIV.LDM.Nodes.SoROI.box and OIV.LDM.Nodes.SoROI.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 OIV.LDM.Nodes.SoROI.subVolume field means that this field should be ignored. This is the default.

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

To define a simple ROI, set the limits of the ROI in the OIV.LDM.Nodes.SoROI.box field (and do not set the OIV.LDM.Nodes.SoROI.subVolume field). The same result is obtained by setting the OIV.LDM.Nodes.SoROI.box and OIV.LDM.Nodes.SoROI.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.

SoVolumeData volData = new SoVolumeData();
. . .
SoROIManip roiManip = new SoROIManip();
roiManip.box.SetValue( new SbVec3i32(0, 0, 0), volData.data.GetSize() - new SbVec3i32(1, 1, 1));
root.AddChild( roiManip );

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

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

The figures below show the OIV.LDM.Nodes.SoROI.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: OIV.LDM.Nodes.SoROI.box field used to limit visible portion of the volume

Example: OIV.LDM.Nodes.SoROI.box field + OIV.LDM.Nodes.SoROI.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.Value = SoROI.FlagsType.ENABLE_X0 | 
                   SoROI.FlagsType.ENABLE_Z0 |
                   SoROI.FlagsType.ENABLE_Y1 |
                   SoROI.FlagsType.INVERT_2  |
                   SoROI.FlagsType.OR_SELECT;
Here is the resulting complex crop box:

Additional Examples

Example 1: flags = SUB_VOLUMEAlternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2
Example 2: flags = FENCEAlternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2 | OR_SELECT
Example 3: flags = FENCENote 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_INVERTAlternate setting:flags = ENABLE_X0 | ENABLE_Y1 | ENABLE_Z2 | OR_SELECT | INVERT_OUTPUT
Example 5: flags = CROSSAlternate setting:flags = ENABLE_X0 | ENABLE_Y0 | ENABLE_Y1 | ENABLE_Z1 | ENABLE_X2 | ENABLE_Z2 | OR_SELECT
Example 6: flags = CROSS_INVERTAlternate setting:flags = CROSS | INVERT_OUTPUT

FILE FORMAT/DEFAULT

ROI {
dataSetId 0
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.

ACTION BEHAVIOR

OIV.Inventor.Actions.SoCallbackAction, OIV.Inventor.Actions.SoGLRenderAction, OIV.Inventor.Actions.SoGetBoundingBoxAction, OIV.Inventor.Actions.SoPickAction, OIV.Inventor.Actions.SoWriteAction

See Also