SoVolumeData Class Reference

Volume data property node. More...

#include <VolumeViz/nodes/SoVolumeData.h>

Inheritance diagram for SoVolumeData:

Public Types
enum	CoordinateType {   COORDINATES_UNIFORM = SoVolumeReader::COORDINATES_UNIFORM ,   COORDINATES_RECTILINEAR = SoVolumeReader::COORDINATES_RECTILINEAR }
	Coordinate type used by this data set. More...
enum	Axis {   X ,   Y ,   Z }
	Which axis to handle. More...
typedef SoLDMDataAccess	LDMDataAccess
typedef ::SoLDMResourceParameters	SoLDMResourceParameters
Public Types inherited from SoDataSet
enum	ValueInterpretation {   CONTINUOUS = 0 ,   DISCRETE = 1 }
	Specifies an image type: segmented or not segmented. More...
enum	DataType {   UNSIGNED_BYTE = SbDataType::UNSIGNED_BYTE ,   UNSIGNED_SHORT = SbDataType::UNSIGNED_SHORT ,   UNSIGNED_INT32 = SbDataType::UNSIGNED_INT32 ,   SIGNED_BYTE = SbDataType::SIGNED_BYTE ,   SIGNED_SHORT = SbDataType::SIGNED_SHORT ,   SIGNED_INT32 = SbDataType::SIGNED_INT32 ,   FLOAT = SbDataType::FLOAT ,   DOUBLE = SbDataType::DOUBLE }
	Supported data type. More...
typedef SbBool	SaveEditingCB(SoDataSet *dataSet, SoVolumeWriter *writer, int tilesRemaining, int totalTiles)
	This is the declaration to use for saveEditing callback functions.
typedef void	SoLDMDataTransformFunction(SoDataSet *ds, const SbVec3i32 &bufferDimension, void *bufferToTransform, const SbBox3i32 &dataBox, int resolutionLevel, void *userData)
Public Types inherited from SoVolumeRendering
enum	HW_Feature {   HW_3DTEXMAP = SoHardwareQuery::HW_3DTEXMAP ,   HW_TEXCOLORMAP = SoHardwareQuery::HW_TEXCOLORMAP ,   HW_TEXCOMPRESSION = SoHardwareQuery::HW_TEXCOMPRESSION }
	Hardware Features Mode. More...
enum	HW_SupportStatus {   NO = SoHardwareQuery::NO ,   YES ,   UNKNOWN }
	Hardware Features support status. More...

Public Member Functions
virtual SoType	getTypeId () const
	Returns the type identifier for this specific instance.
	SoVolumeData ()
	Constructor.
virtual SbBool	getMinMax (int64_t &min, int64_t &max)
	Returns min and max values of the data set data.
virtual SbBool	getMinMax (double &min, double &max)
	Returns min and max values of the data set.
SbBool	getHistogram (int &length, int64_t *&histogram)
	Returns the histogram of the volume data.
void	updateRegions (const SbBox3i32 *region, int num_regions)
	Updates regions of the volume that have been modified.
void	updateTilesInTextureMemory (SoLDMTileID *tiles, int numTiles)
	Reloads textures corresponding to the given tile IDs.
void	setRGBAData (const bool flag)
	Force data to be considered as RGBA values.
CoordinateType	getCoordinateType () const
const std::vector< float > &	getRectilinearCoordinates (Axis axis) const
	Returns a vector describing mapping from uniform space to rectilinear space.
virtual SbBool	startEditing (int &transactionId)
	Initiate an editing transaction.
virtual int	editTile (const SoLDMTileID &tileId, SoBufferObject *userData)
	Replaces the contents of a tile with the given data.
virtual int	editSubVolume (const SbBox3i32 &subVolume, SoBufferObject *userData)
	Replaces the contents of a subvolume with the given data.
virtual int	editTile (const SoLDMTileID &tileId, const double &value)
	Replaces the contents of a tile with the specified value.
virtual int	editSubVolume (const SbBox3i32 &subVolume, const double &value)
	Replaces the contents of a subvolume with the specified value.
virtual int	editSurfaceShape (const SoNode *surfaceShape, const float &thickness, const double &newValue)
	Replaces all voxels intersecting the polygons or lines defined by the surfaceShape and given thickness with the specified value.
virtual int	editSolidShape (const SoNode *solidShape, const double &value)
	Replaces all voxels intersecting the given shape with the specified value.
virtual int	editBoxes (const std::vector< SbVec3i32 > &boxCenters, const int &boxSize, const double &newValue)
	Replace all voxels in the region defined by a list of boxes with the specified value.
virtual SbBool	finishEditing (int transactionId)
	Terminates an editing transaction.
virtual SbBool	undoEditing (int transactionId)
	Undo all modifications associated with the specified transaction id.
virtual SbBool	redoEditing (int transactionId)
	Redo all modifications associated with the specified transaction id.
virtual SbBool	saveEditing (bool recomputeLowerResolution=TRUE, const std::vector< char * > convertionParameters=std::vector< char * >(), SaveEditingCB *callback=NULL)
	Commit all transactions.
Public Member Functions inherited from SoDataSet
const SbVec3i32 &	getDimension ()
	Returns the data set dimension.
SbVec3i32	getTileDimension ()
	Returns the tile dimension.
unsigned int	getDatumSize ()
	Returns the number of bytes per voxel.
virtual size_t	readTile (SoBufferObject *&bufferObject, SoLDMTileID tileID, bool transform)
	Copies the specified tile into the provided buffer.
virtual void	readTile (SoLDMTileID tileID, SoBufferObject *buffer, bool transform)
	Copies the specified tile into the provided buffer.
virtual void	writeTile (SoLDMTileID tileID, SoBufferObject *buffer, SoVolumeWriter *writer)
	Write the specified tile using the specified writer.
bool	isInMemory (SoLDMTileID tileID) const
	Indicates whether a tile is in main memory.
bool	isDataInMemory (const SoLDMTileID &tileID) const
	Indicates whether the data attached to a tile is in main memory.
void	getTileIDInMemory (std::vector< LDM_TILE_ID_TYPE > &tilesInMemory) const
	Debug purpose only.
SoLDMDataAccess &	getLdmDataAccess ()
	Returns a reference to the SoLDMDataAccess object.
SbBool	saveEditing ()
	Commit all transactions.
virtual bool	hasEditedTile ()
	Returns true if DataSet has edited tiles.
SoLDMReader *	getLDMReader ()
	Returns a pointer to the current data set reader object.
void	setLDMReader (SoLDMReader *reader)
	Sets the LDM volume reader object to use.
SoVolumeReader *	getReader ()
	Returns the current data set reader object.
SoVolumeReader *	getReader () const
	Returns the current data set reader object.
int	numSigBits () const
	Returns the number of significant bits.
DataType	getDataType () const
	Returns the data type.
int	getDataSize ()
	Returns the number of bytes per voxel in VolumeViz.
void	setReader (SoVolumeReader &reader, SbBool takeOwnership=FALSE)
	This method allows the data to be read directly from the disk using the specified subclass of SoVolumeReader.
virtual SbVec3f	voxelToXYZ (const SbVec3f &dataPosition) const
	Converts the specified point in voxel coordinates (I,J,K) to geometric coordinates (X,Y,Z).
virtual SbBox3f	voxelToXYZ (const SbBox3f &box) const
	Converts the specified box in voxel coordinates (I,J,K) to geometric coordinates (X,Y,Z).
virtual SbVec3f	XYZToVoxel (const SbVec3f &dataPosition) const
	Converts the specified point in geometric coordinates (X,Y,Z) to voxel coordinates (I,J,K).
virtual SbBox3f	XYZToVoxel (const SbBox3f &xyzBox) const
	Converts the specified box in geometric coordinates to voxel coordinates.
void	resetReader ()
	Resets previously set custom reader setup by setReader call.
const SoLDMTopoOctree *	getLDMTopoOctree () const
	Returns the LDMTopoOctree used by this SoDataSet.
virtual SoDEPRECATED void	readTile (SoLDMTileID tileID, unsigned char *buffer, bool transform)
SoDEPRECATED void	setLDMDataTransformFunction (SoLDMDataTransformFunction *func, void *userData=NULL)
	If set, the user-defined function is called after each tile is loaded, but before it is stored in main memory.
SoDEPRECATED int	getOverlapping ()
	Returns the tile border (overlap) in voxels.
Public Member Functions inherited from SoNode
virtual void	setOverride (const SbBool state)
	Turns the override flag on or off.
virtual SbBool	isOverride () const
	Returns the state of the override flag.
virtual SoNode *	copy (SbBool copyConnections=FALSE) const
	Creates and returns an exact copy of the node.
virtual SbBool	affectsState () const
	Returns TRUE if a node has an effect on the state during traversal.
virtual void	touch ()
	Marks an instance as modified, simulating a change to it.
Public Member Functions inherited from SoFieldContainer
void	setToDefaults ()
	Sets all fields in this object to their default values.
SbBool	hasDefaultValues () const
	Returns TRUE if all of the object's fields have their default values.
SbBool	fieldsAreEqual (const SoFieldContainer *fc) const
	Returns TRUE if this object's fields are exactly equal to fc's fields.
void	copyFieldValues (const SoFieldContainer *fc, SbBool copyConnections=FALSE)
	Copies the contents of fc's fields into this object's fields.
SoNONUNICODE SbBool	set (const char *fieldDataString)
	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.
SbBool	set (const SbString &fieldDataString)
	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.
void	get (SbString &fieldDataString)
	Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.
virtual int	getFields (SoFieldList &list) const
	Appends references to all of this object's fields to resultList, and returns the number of fields appended.
virtual int	getAllFields (SoFieldList &list) const
	Returns a list of fields, including the eventIn's and eventOut's.
virtual SoField *	getField (const SbName &fieldName) const
	Returns a the field of this object whose name is fieldName.
virtual SoField *	getEventIn (const SbName &fieldName) const
	Returns a the eventIn with the given name.
virtual SoField *	getEventOut (const SbName &fieldName) const
	Returns the eventOut with the given name.
SbBool	getFieldName (const SoField *field, SbName &fieldName) const
	Returns the name of the given field in the fieldName argument.
SbBool	enableNotify (SbBool flag)
	Notification at this Field Container is enabled (if flag == TRUE) or disabled (if flag == FALSE).
SbBool	isNotifyEnabled () const
	Notification is the process of telling interested objects that this object has changed.
virtual void	setUserData (void *data)
	Sets application data.
void *	getUserData (void) const
	Gets user application data.
Public Member Functions inherited from SoBase
virtual SbName	getName () const
	Returns the name of an instance.
virtual void	setName (const SbName &name)
	Sets the name of an instance.
void	setSynchronizable (const bool b)
	Sets this to be a ScaleViz synchronizable object.
bool	isSynchronizable () const
	Gets the ScaleViz synchronizable state of this object.
Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.
void	unref () const
	Removes a reference from an instance.
void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
int	getRefCount () const
	Returns current reference count.
void	lock () const
	lock this instance.
void	unlock () const
	unlock this instance.
Public Member Functions inherited from SoTypedObject
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.
template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
Static Public Member Functions inherited from SoDataSet
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
static int	dataSize (DataType dataType)
	Returns the number of bytes per voxel of the specified data type.
static SbBool	isDataSigned (DataType dataType)
	Returns TRUE if the given data type is a signed integer data type.
static SbBool	isDataFloat (DataType dataType)
	Returns TRUE if the given data type is a float data type.
static int	getMaxNumDataSets ()
	Returns the maximum number of data sets that can be render composited on the current hardware (essentially the number of texture units - 1).
Static Public Member Functions inherited from SoNode
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
static SoNode *	getByName (const SbName &name)
	A node's name can be set using SoBase::setName().
static int	getByName (const SbName &name, SoNodeList &list)
	A node's name can be set using SoBase::setName().
Static Public Member Functions inherited from SoFieldContainer
static SoType	getClassTypeId ()
	Returns the type of this class.
Static Public Member Functions inherited from SoBase
static SoType	getClassTypeId ()
	Returns type identifier for this class.
Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
Static Public Member Functions inherited from SoVolumeRendering
static void	init ()
	Initializes the VolumeViz module database.
static void	finish ()
	Shuts down the VolumeViz module, which includes freeing any internal static memory that it allocated.
static bool	isInitialized ()
	Returns TRUE if module is currently initialized.
static void	setWriteAlternateRep (SbBool flag)
	Sets the writeAlternateRep flag.
static SbBool	getWriteAlternateRep ()
	Returns the writeAlternateRep flag.
static void	setReadAlternateRep (SbBool flag)
	Sets the readAlternateRep flag.
static SbBool	getReadAlternateRep ()
	Returns the readAlternateRep flag.
static HW_SupportStatus	isSupported (HW_Feature feature)
	Returns information about hardware support for various volume rendering features.
static SoDEPRECATED void	setDelayedRendering (SbBool flag)
	Sets the delayedRendering flag.
static SoDEPRECATED SbBool	getDelayedRendering ()
	Returns the delayedRendering flag.

Public Attributes
SoSFBool	usePalettedTexture
	For a volume containing scalar data values, controls whether scalar values (true) or RGBA values (false) are loaded on the GPU (the name is historical).
SoSFBool	useSharedPalettedTexture
	Note: On graphics boards that support programmable shaders, this field is ignored (virtually all graphics boards support programmable shaders).
SoSFBool	useExtendedData
	If TRUE, VolumeViz stores an additional copy of each loaded tile.
SoSFArray3D	data
	Specifies the volume data, including dimensions, data type and number of significant bits.
SoSFBool	dataRGBA
	Contains TRUE if the volume contains RGBA values rather than scalar values.
Public Attributes inherited from SoDataSet
SoSFInt32	dataSetId
	When using multiple SoDataSet nodes, the dataSetId field uniquely identifies each data set used in the compositing.
SoSFFilePathString	fileName
	Indicates the file location containing the data set.
SoSFBool	useCompressedTexture
	Controls use of OpenGL lossy texture compression for RGBA data (if available).
SoSFUShort	texturePrecision
	For scalar (non-RGBA) data, specifies the size of voxel values on the GPU in bits.
SoSFBox3f	extent
	The real size (extent) of the volume in modeling coordinates.
SoSFLDMDataTransform	dataTransform
	If set to an appropriate SoLDMDataTransform object, the object's transformFunction method is called after each tile is loaded, but before it is stored in main memory.
SoSFBool	allocateResourceOnRender
	Indicates if resource allocation is done only on first render traversal or as soon as the node is created.
SoSFDouble	undefinedValue
	Data with this value won't be rendered.
SoSFEnum	valueInterpretation
	Specifies if this dataset corresponds or does not correspond to a segmented image.
SoSFLDMResourceParameters	ldmResourceParameters
	Contains an SoLDMResourceParameters object which allows you to set LDM resource parameters.

Friends
class	::SoVolumeState

Deprecated
enum	StorageHint {   AUTO ,   TEX2D_MULTI ,   TEX2D = TEX2D_MULTI ,   TEX3D ,   MEMORY }
	Storage Hints mode TODO: this enum should be in the private section as its storageHints deprecated field coiunterpart BUT it is used in other internal implementation place. More...
enum	SubMethod {   NEAREST ,   MAX ,   AVERAGE }
	Sub sampling method mode. More...
enum	OverMethod {   NONE ,   CONSTANT ,   LINEAR ,   CUBIC }
	Over sampling method mode. More...
SoDEPRECATED SoVolumeData *	reSampling (const SbVec3i32 &dimension, SoVolumeData::SubMethod subMethod, SoVolumeData::OverMethod=NONE)
	Re-samples the volume down to or up to the given dimension using the sub-sampling method SubMethod() and the over-sampling method OverMethod().
SoDEPRECATED SoVolumeData *	subSetting (const SbBox3i32 &region)
	Extracts the data volume defined by region.
SoDEPRECATED void	setTexMemorySize (int size)
	Specifies the maximum texture memory size to use in mega texels.
SoDEPRECATED int	getTexMemorySize ()
	Returns the maximum texture memory size to use in mega texels.

Detailed Description

Volume data property node.

This class defines the data volume and its properties, and also provides utilities for extracting a subset of the volume and for resampling the volume. The data can be stored in memory, read from a file or accessed via a user-defined reader. This node provides the data for the volume rendering shape nodes (SoVolumeRender, SoOrthoSlice, SoObliqueSlice, etc.) and is the parent class for some specialized data nodes (SoHeightFieldGeometry, SoVolumeMask, etc.).

Note: Since the camera viewpoint is used to determine which part of the volume to load, the behavior of SoVolumeData is not correctly defined when no camera node has been traversed before the SoVolumeData. This can result in console warnings.

The data volume can be specified by:

• Setting the fileName field
  This implies that the volume is stored on disk, in one of the file formats for which VolumeViz has a built-in reader. This is the most common way to load data. VolumeViz will automatically select a volume reader class based on the file extension, for example ".am" for the AmiraMesh file format. If the filename does not have an extension or does not have the appropriate extension, the application must specify a volume reader explicitly using setReader(). See the supported file formats below.
  Note that, unlike other nodes, SoVolumeData and its derived classes do not search the SoInput directory list to find files.
• Calling the setReader() method
  This is the most general method because an application can specify an instance of one of the standard VolumeViz readers or an instance of a custom subclass of SoVolumeReader.
  
  You might use this method with a standard VolumeViz reader class if the data file's name has a non-standard extension. In other words, if VolumeViz will not be able to select the correct volume reader automatically, explicitly create an instance of the correct reader and pass it to the setReader() method.
  
  VolumeViz will get the volume properties (dimensions, size, data type, etc) and access the volume data through the specified reader object. Creating an instance of a custom volume reader (see SoVolumeReader for more information) allows the application to completely control how, and from where, the data is loaded. For example the data could be accessed through an application specific API.
  Note: When using a custom reader, any reader method that changes the volume properties (dimension, size, data type, etc) should notify the SoVolumeData node by calling the reader's touch() method. If this notification is not done, SoVolumeData fields, for example extent, won't be updated correctly.
  Applications can use the getReader() method to query the current volume reader, but should always verify the class type before using the returned object.
• Setting the data field
  This implies that the entire volume has already been loaded into a contiguous block of CPU memory. We call this an "in-memory" volume.
  Volume reader: Note that when a file format reader or custom volume reader is currently being used, setting the data field will automatically replace the current volume reader. Subsequent calls to getReader() will return an SoVRMemoryReader.
  Tile size: Note that VolumeViz always manages volume data internally as "tiles" and the default tile size is small. Generally you wll get better performance by explicitly setting a larger tile size (see the ldmResourceParameters field and SoLDMResourceParameters::tileDimension).

Volume Properties:

• Dimensions
  The dimensions of the volume (number of voxels on each axis) are normally determined by the volume reader from information in ithe data file(s), the number of images in the stack, etc. (When you set the data field directly you specify the volume dimensions.) You can query the volume dimensions using the data field. For example:

  SbVec3i32 voldim = volumeData->data.getSize();

• Extent
  The geometric extent of the volume in 3D is initially determined by the volume reader but can also be set using the extent field. The volume extent is the bounding box of the volume in world coordinates. Often the volume extent in 3D is set equal to the dimensions of the volume or to values that are proportional to the volume dimensions. For example, -1 to 1 on the longest axis of the volume and proportional values for the other axes puts the origin (0,0,0) at the center of the volume, simplifying rotations. However the volume extent can be any range, for example the range of line numbers in a seismic survey. The volume extent indirectly specifies the voxel size/spacing. You can query the current volume extent using the extent field. For example:

  SbBox3f volext = volumeData->extent.getValue();

  Notes:

  • Modify extent: The application can change the volume extent (but not the dimensions) at any time. This changes the bounding box of the volume and scales the volume visualization nodes (SoOrthoSlice, etc) associated with the volume. Changing the volume extent effectively changes the voxel size. This is commonly used, for example, to scale a seismic volume along the time axis.
    
    
  • Transform nodes: The volume extent and orientation (like geometry) can be modified by transformation nodes in the scene graph and this in turn modifies the appearance of volume visualization nodes (SoVolumeRender, SoOrthoSlice, etc). However the same transformation must be applied to the volume data node as well as the volume rendering nodes associated with that volume. Effectively any transformation nodes that affect the volume must be placed before the volume data node.
    
    
  • DICOM: For some data formats, including DICOM, the volume 'position' is considered to be the center of the first voxel. VolumeViz considers the volume extent to include all of the first and last voxels. Therefore the extent 'min' is the outside corner of the first voxel.
    NOTE: Open Inventor versions < 9.8 do not automatically set the volume extent based on the Image Position Patient attribute. Use the MedicalHelper method dicomAdjustVolume.

• Voxel size/spacing
  If the volume data is uniformly sampled, the voxel size is the volume extent divided by the volume dimensions. The voxel size can be different for each axis (uniform along each axis). However VolumeViz is not limited to uniformly spaced voxels. VolumeViz also supports "rectilinear" coordinates where the voxel positions are explicitly given for each axis and also supports "projection" using the SoProjection node (with some limitations). This allows rendering of volumes defined, for example, in cylindrical coordinates or geographic coordinates.
• Data type
  VolumeViz supports volumes containing scalar data as signed and unsigned integer values (byte, short, int) or floating point values. VolumeViz also supports volumes containing RGBA data (explicit color value for each voxel). In this case the data type is always unsigned integer. You can query if the volume contains explicit RGBA values by getting the value of the dataRGBA field. The data type is determined by the reader (or when setting the data field). You can query the data type and/or number of bytes per voxel using methods inherited from SoDataSet. For example:

  int bytesPerVoxel = volumeData->getDataSize();
  SoDataSet::DataType type = volumeData->getDataType();

• Data range
  In volumes using data types larger than byte, the actual range of data values is usually smaller than the range of the data type. The application can use an SoDataRange node to specify the range of values that will be mapped into the transfer function. For some formats the application can get min and max values from the meta-data. For DICOM data, see SoVRDicomData or the MedicalHelper method dicomAdjustDataRange(). In any case, the application can query the actual minimum and maximum values using the getMinMax methods. For example:

  double minval, maxval;
  SbBool ok = volumeData->getMinMax( minval, maxval );

  Note 1: These methods might force VolumeViz to load the entire data set if the volume reader does not implement the getMinMax query. For example in an LDM format data set, the min and max values are stored in the LDM header, so the query is very fast. For other data sets VolumeViz may be forced to load the entire data set and scan all the values to compute the min and max values.
  Note 2: Changing the data range (SoDataRange) may be slow if the size of the data values is larger than the SoDataSet::texturePrecision setting. For example 32 bit values with texturePrecision = 8 or 16. In this case the data values must be re-scaled and resent to the GPU when the data range is changed.

• Other:
  Many other volume properties can be specified using fields of SoDataSet and SoVolumeData. The ldmResourceParameters field contains an SoLDMResourceParameters object that controls, for example, the amount of CPU memory and GPU memory that the volume can use.

Basic volume visualization tools:

• The volume data is specified by an SoVolumeData node. (Multiple data sets can also be specified. See the next section.)
• The region of voxels to be rendered (the "region of interest") can be specified using an SoROI node. This node limits the extent of all rendering nodes including slices.
• The range of data values to be mapped into the transfer function can be specified using an SoDataRange node.
• The color and opacity associated with each data value can be specified using an SoTransferFunction node.
• The base material properties of the voxels, e.g. emissive and specular color, can be specified using an SoMaterial node.
• Advanced rendering effects, e.g. lighting, and image quality settings can be specified using an SoVolumeRenderingQuality node. (Note: You should always enable lighting using this node, not the lighting field of SoVolumeRender.) Features include:
  • Lighting (gradient or deferred)
  • Ambient occlusion
  • Jittering (anti-aliasing)
  • Gradient computation options
  • Interpolation options
  • Edge enhancement effects
  • Cube rendering of voxels
• The SoVolumeDataDrawStyle node specifies the volume rendering style(s) for a volume or for a voxel region defined by an SoVolumeMask node. The available rendering styles are hidden (not rendered), direct volume rendering, a set of isosurfaces and/or the region boundary surface.
• Shadows can be enabled for volume rendering using an SoShadowGroup node.
• Many parameters related to memory management and performance optimizations can be specified using SoLDMGlobalResourceParameters and SoLDMResourceParameters.
• VolumeViz provides many different ways of visualizing volume data, including:
  • SoOrthoSlice: Renders a single axis aligned slice.
  • SoObliqueSlice: Renders a single arbitrarily aligned slice.
  • SoFenceSlice: Renders a "strip" of connected oblique slices.
  • SoVolumeSkin: Renders the faces of the current Region of Interest (see SoROI). Effectively a set of ortho slices.
  • SoVolumeIndexedFaceSet (etc): Renders a "slice" made up of arbitrary geometry, for example a curved or cylindrical slice.
  • SoVolumeIsosurface: Renders the isosurface defined by the specified data value. (This is done completely on the GPU. To get the geometry of an isosurface back on the CPU see the MeshViz extension.)
  • SoVolumeRender: Renders the volume using direct volume rendering.

Advanced volume visualization:

• Custom shaders Custom transfer functions, custom rendering effects and custom blending are just a few of the many possibilities that can be specified using an SoVolumeShader node and GLSL shader functions. VolumeViz provides a framework of prebuilt shader functions for commonly used calculations and effects. This allows applications to extend or replace stages in the rendering pipeline while still taking advantage of other VolumeViz features.
• Clipping
  Volume visualizations can be clipped in multiple ways:
  • Volume visualizations can be clipped by clipping planes (SoClipPlane) like any other Open Inventor geometry. (However for clipping against axis aligned planes, using an SoROI node is much more efficient.)
  • Volume visualizations can be clipped against a box specified in voxel coordinates using an SoROI node. The box can be modified by a secondary exclusion box, allowing cut-away views like the "chair cut" in seismic visualization.
  • Volume visualizations can be clipped against arbitrary polygonal geometry using an SoVolumeClippingGroup node. The clipping geometry can be any closed shape, for example a cylinder or a shape extruded from a polygon.
  • Volume visualizations can be clipping against a surface defined by a "height field" (for example a seismic horizon) using an SoUniformGridClipping node.
  • Volume visualizations can be clipped against an arbitrary voxel region using an SoVolumeMask node. SoVolumeMask also allows applying different transfer functions to different regions and other powerful features.
  • Multiple clipping techniques may be combined to "sculpt" volume regions.
• Interactivity
  VolumeViz allows the creation of highly interactive volume rendering applications:
  • Picking works for volume rendering objects like for any other Open Inventor geometry. For example the application can determine which slice was clicked when a mouse button event occurs. Specialized sub-classes of SoDetail provide more specific information for each rendering class. For example SoOrthoSliceDetail provides the IJK coordinates and value of the specific voxel under the cursor.
  • VolumeViz provides specialized draggers and manipulators to allow users to directly interact with volume rendering scenes. For example, SoOrthoSliceDragger allows dragging a slice through the volume and SoROIManip allows moving and resizing a region of interest (SoROI).
  • Modifying VolumeViz property nodes (like any Open Inventor node) automatically causes the scene graph to be re-rendered. For example the color map can be dynamically changed by modifying the fields of SoTransferFunction.
  • The volume itself can be modified interactively using the "volume edit" methods (startEditing, finishEditing, etc) in this class. Volume editing supports undo and redo and modifications can be saved back to the data source. Convenience methods are provided to modify voxels in a subvolume, a tile or a region defined by a closed polygonal surface.
  • Very large volumes and/or advanced rendering options may reduce the rendering performance even on high-end graphics hardware. VolumeViz provides multiple options for temporarily reducing the rendering complexity while interacting with the scene. See the lowResMode field in SoVolumeRender and also the SoInteractiveComplexity node.
• Transforming data
  Volume data can transformed "on the fly" at several stages in the pipeline:
  • The SoLDMDataTransform class (see the dataTransform field of SoDataSet) applies a computation to each LDM data tile requested from the volume reader before the tile is stored in system memory. This can be used to apply "static" filters to the data, for example to apply DICOM Rescale Slope and Intercept values.
  • The SoVolumeTransform node applies a computation to the LDM data tiles just before they are sent to the GPU. This can be used to apply dynamic filters to the data, for example computing seismic attribute values.
  • Both mechanisms can be used to create multiple data sets from a single data set.
• Multiple data sets
  
  • Multiple SoVolumeData nodes can be inserted in the same scene graph.
    
  • If the volumes are independent and rendered separately, use an SoVolumeGroup node to manage and correctly render intersecting regions.
    
  • More commonly multiple volumes will be combined into a single data set or single rendering using data compositing or render compositing. In these cases use an SoMultiDataSeparator as the parent of the nodes that will be composited.
  • Render compositing (see SoVolumeShader) means combining multiple volumes on the GPU at render time using a fragment shader. Render compositing can be used, for example, to implement "co-blending" of multiple volumes or to implement multi-channel color combining.
  • Data compositing allows you to combine multiple volumes (see SoDataCompositor) on the CPU at data loading time. Data compositing can be used, for example, to visualize the difference between two data sets.
  • (More details below)
• Data Access
  LDM is a powerful data manager for large volume data and VolumeViz provides a Data Access API that allows applications to take advantage of this for applying algorithms to their volume data.
  • SoLDMDataAccess provides the methods to extract data from a volume. The data is accessible whether the SoVolumeData is part of a scene graph or not.
  • Data access methods can be invoked synchronously or asynchronously to allow simultaneous loading and computation. The application can request data at any resolution level, independent of the resolution level currently being used for rendering
  • VolumeViz supports a variety of data requests including:
    • Subvolume: The set of voxels inside a specified subvolume.
    • Plane: The set of voxels intersecting an arbitrary plane.
    • Line: The set of voxels intersecting an arbitrary line.
    • Trace: A column of axis aligned voxels (e.g. a seismic trace).
    • Polyline: The set of voxels intersecting an arbitrary polyline.
    • Tile: Direct access to the tile containing a specified voxel.
  • Extracted, modified or synthesized data can be written to an LDM format file by subvolume or tile using the SoLDMWriter class.
• Computation
  Volume computations can take advantage of the Open Inventor computing framework to manage data, devices and algorithms on the CPU and GPU.
  • The SoBufferObject class abstracts data management. Each buffer object is an instance of a device specific data object, for example SoCpuBufferObject. This allows the application to control where memory is actually allocated. It also allows algorithms to be implemented on CPU or GPU (or both) using SoBufferObject without knowing where the memory is allocated (Open Inventor will transfer when necessary).
  • The SoDevice class abstracts computing and rendering devices. Device specific classes, for example SoCpuDevice, allow querying the number of available devices, available memory and other properties.
  • The computing framework classes are integrated with the data transform, compositing and data access classes mentioned previously.

Multiple data sets:

Multiple SoVolumeData nodes can be inserted in the same scene graph. If the volumes are independent and rendered separately, use an SoVolumeGroup node to manage and correctly render intersecting regions. More commonly multiple volumes will be combined together in a single rendering using render compositing (SoVolumeShader) or data compositing (SoDataCompositor). In these cases you must use an SoMultiDataSeparator as the parent of the nodes that will be composited.

Render compositing (SoVolumeShader or SoVolumeRenderingQuality) is a way of combining multiple volumes on the GPU at render time using a GLSL fragment shader. The volumes can each have their own transfer function or they can all use the same one. Render compositing can be used, for example, to implement "co-blending" of multiple volumes or to implement multi-channel color combining. The number of volumes to compose is limited by the number of OpenGL texture units supported by the graphics board (normally at least 16). This number is returned by the getMaxNumDataSets function.

Data compositing allows you to combine multiple volume data sets (see SoDataCompositor) or to transform a single data set in memory (see setLDMDataTransformFunction()) instead of storing the combined data sets on disk. For example, it can be used to visualize the result of the difference between two data sets. There is no limit on the number of volumes that can be composed on the CPU.

Note that the word composition is also used in SoVolumeRender. There it refers to the way that samples along the raycasting ray are combined to form the final image.

The dataSetId field is used to differentiate SoVolumeData nodes when doing render or data compositing.

Some rules must be observed when doing render or data compositing:

• Each SoVolumeData node must have a unique dataSetId.
  
• All the SoVolumeData nodes to be composited must have the same volume dimensions (number of voxels in X, Y, and Z) and tile size.
  
• All the SoVolumeData nodes to be composited, as well as the compositing node (e.g. SoVolumeShader or SoVolumeRenderingQuality) and the rendering node (e.g. SoVolumeRender), must be under an SoMultiDataSeparator node.
• The SoVolumeData nodes to be composited must be all scalar data sets or all RGBA data sets. To composite scalar and RGBA data sets under the same SoMultiDataSeparator, set the usePalettedTexture field to false in the scalar dataset's SoVolumeData node to force the scalar data to be converted into RGBA data.
• An SoVolumeData node used in a data compositing scheme must not be inserted multiple times in the scene graph. Use another volume data node pointing to the same file.
• Each SoVolumeData node has its own resource settings (see field ldmResourceParameters). The resources required for the composition are the sum of the resources for all of the SoVolumeData nodes involved.
  

When using a fragment shader to do render compositing, texture coordinates can be retrieved from texture unit 0 (texture coordinates are sent using glTexCoord function). To minimize the number of texture units needed, all the transfer functions (see SoTransferFunction) for the volumes to be composited are stored in a single 2D texture. By default this texture is loaded in texture unit 0. However this default behavior can be changed through SoPreferences using the environment variable IVVR_TF_TEX_UNIT. Each volume's data is loaded in the texture unit specified by its dataSetId. Therefore do not set dataSetId to the texture unit used to store the transfer functions.

Please see SoMultiDataSeparator and SoVolumeShader for more information, and example code, for compositing multiple volumes.

RGBA Data

Voxels in an RGBA volume are UNSIGNED_INT32, containing 8 bits each of Red, Green, Blue and Alpha. All rendering nodes (slices, volume rendering, etc) work with RGBA volumes. Region of Interest, clipping and other features also work with RGBA volumes. However because the volume already specifies the colors to be used for rendering, the data range, transfer function and some rendering features are ignored. Lighting works with RGBA volumes using gradient vectors computed from the luminance value of the voxels.

Notes:

• In-memory volumes
  For compatibility with older versions of Open Inventor, if the data is in-memory the unsigned int values must contain ABGR values, not RGBA. Use the SbColor getPackedValueEndiannessOrder() method to convert values, not the getPackedValue() method.
• Texture compression
  The useCompressedTexture option (see SoDataSet) is true by default. This can significantly reduce the amount of GPU memory required to hold an RGBA volume. But it uses a "lossy" compression algorithm which may result in values on the GPU being slightly different than the actual value in the volume. For example "gray scale" colors could have a slight color in some cases. You should always set this option to false when using "RGBA" data to store 32-bit "id" values. Please also note that this compression is not supported on Intel GPUs, so you should set this option to FALSE in this case as well.

Volume Editing

Volume editing is based on transactions. A transaction is created by calling the following methods:

int transationId;
volumeData->startEditing( transationId );
//... editing calls ...
volumeData->finishEditing( transationId );

Starting a transaction returns a unique id identifying the current transaction. This id is used to finish the transaction by calling finishEditing(). After the transaction is finished, this id can also be used to undo or redo the transaction. The finish method will schedule a redraw so the modified data is displayed. Multiple transactions may be active at the same time.

After a transaction is finished, the effect can be undone by calling undoEditing() with the transaction id. Undo also schedules a redraw so the correct data is displayed. Similarly a transaction that was undone can be re-applied by calling redoEditing() with the transaction id.

Calling saveEditing() will update the data source associated with this SoVolumeData node with all edits performed on the volume since the last save. Updating is done using the SoVolumeWriter returned by the current SoVolumeReader. The save method may only be called when no transactions are active, i.e. after finish has been called for all transactions.
Note:

• Until the edits have been saved, memory is required for both the original data and the modified data. This implies both an additional memory requirement and that buffer objects passed to (for example) editSubVolume() must not be modified until after the saveEditing() call.
• After the edits have been saved, all transaction ids are invalid, so undo and redo can no longer be called with those transaction ids.
• saveEditing currently only works for data loaded using SoVRLDMFileReader (an LDM format tiled data set) or SoVRMemoryReader (data set completely in memory).
• VolumeViz applies edition transaction on the fly each time a tile is requested. Thus, loading, data access and picking performance may be impacted. To retrieve initial performances, you may have to call saveEditing() to flush editing transactions.

VolumeViz provides multiple methods to modify data including:

• Fill a subvolume with a value or a buffer of values ( editSubVolume() )
• Fill a tile with a specified value or a buffer of values ( editTile() )
• Fill a list of cubic subvolumes with a value ( editBoxes() )
• Fill the voxels inside a closed polygonal solid with a value ( editSolidShape() )
• Fill the voxels intersecting a polygonal surface with a value ( editSurfaceShape() )

Supported file formats:

File extension	Reader class	Description
.am	SoVRAmFileReader	Avizo Mesh file format
.dc3, .dic, .dicom	SoVRDicomFileReader	DICOM file format
.fld	SoVRAvsFileReader	AVS field file format
.lda or .ldm	SoVRLdmFileReader	LDM file format
.sgy or .segy	SoVRSegyFileReader	SEG Y rev 1 file format
.vol	SoVRVolFileReader	Vol file format
.vox	SoVRVoxFileReader	Vox file format
.lst	SoVRRasterStackReader	Lst file format

File format notes:

• Avizo mesh
  Avizo mesh is a general purpose file format that can contain many different kinds of data. The VolumeViz file reader can load Avizo mesh files containing a 3-dimensional "Lattice" data object with uniform coordinates and any data type. See SoVRAmFileReader for limitations.
  
  Note: Unlike Amira and Avizo, VolumeViz cannot automatically open Amira/Avizo format data files unless they have the file name extension ".am". To open an Amira/Avizo data file with a different extension, the application must explicitly create an instance of SoVRAmFileReader and use the setReader() method.
• AVS field
  AVS field is a general purpose file format that can contain many different kinds of data. The VolumeViz file reader can load AVS field files containing 3-dimensional, uniform data of type "byte". See SoVRAvsFileReader.
• DICOM
  A widely used format for storing medical image data (CT, MRI, etc), defined by the National Electrical Manufacturers Association (NEMA) (medical.nema.org). See SoVRDicomFileReader
• LDM
  LDM is a format defined by VSG for storing hierarchical multi-resolution volume data. VolumeViz includes a utility program that can convert any other format supported by VolumeViz into this format (see SoVolumeConverter). Preprocessing volume data into this format provides the maximum benefits from the VolumeViz large data management (LDM) features. See SoVRLdmFileReader.
• SEGY
  A widely used format for storing seismic trace data, defined by the Society of Exploration Geophysicists publication "Digital Tape Standards" (www.seg.org). The VolumeViz reader supports all sizes of integer and float data, and can correctly determine the number of samples per trace in many cases. However the reader also has many options to adapt to differences in SEGY file headers. See SoVRSegyFileReader.
• VOL
  A simple volume interchange format (see "Introduction to Volume Rendering", Lichtenbelt, Crane, Naqvi, 1998). The VolumeViz reader can load files containing 8- or 16-bit voxels. See SoVRVolFileReader.
• VOX
  A volume interchange format defined by TeraRecon Inc. (www.terarecon.com). The VolumeViz reader can load "Vox1999a" files containing 8- or 16-bit voxels (first volume only). See SOVRVoxFileReader.
• LST (stack of images)
  A simple format for loading a stack of images. Specify the names of the image files in a .lst file. VolumeViz can load image data in most common image formats including BMP, DDS, GIF, JPEG, JPEG2000, PNG and TIFF. See SoVRRasterStackReader for details and limitations.

Note: '3D TIFF' files (multiple images in one file) are not currently supported.

FILE FORMAT/DEFAULT

VolumeData {

allocateResourceOnRender	FALSE
data	NODATA 0 0 0 UBYTE 8
dataRGBA	FALSE
dataSetId	1
dataTransform	NULL
extent	-1 -1 -1 1 1 1
fileName	""
texturePrecision	0
undefinedValue	NaN
useCompressedTexture	TRUE
useExtendedData	FALSE
usePalettedTexture	TRUE
useSharedPalettedTexture	TRUE

}

ACTION BEHAVIOR

SoCallbackAction, SoGLRenderAction, SoGetBoundingBoxAction, SoPickAction, SoWriteAction
Sets volume data parameters in the traversal state.

SEE ALSO

SoVolumeRender, SoOrthoSlice, SoObliqueSlice, SoVolumeReader, SoVolumeSkin, SoDataCompositor, SoLDMGlobalResourceParameters, SoLDMResourceParameters

Definition at line 726 of file SoVolumeData.h.

Member Typedef Documentation

LDMDataAccess

typedef SoLDMDataAccess SoVolumeData::LDMDataAccess

Definition at line 736 of file SoVolumeData.h.

SoLDMResourceParameters

typedef ::SoLDMResourceParameters SoVolumeData::SoLDMResourceParameters

Definition at line 737 of file SoVolumeData.h.

Member Enumeration Documentation

Axis

enum SoVolumeData::Axis

Which axis to handle.

See also

getRectilinearCoordinates

Enumerator
X
Y
Z

Definition at line 932 of file SoVolumeData.h.

CoordinateType

enum SoVolumeData::CoordinateType

Coordinate type used by this data set.

Enumerator
COORDINATES_UNIFORM	Uniform grid spacing along each axis.
COORDINATES_RECTILINEAR	Grid spacing defined by x, y, z values.

Definition at line 914 of file SoVolumeData.h.

OverMethod

enum SoVolumeData::OverMethod

Over sampling method mode.

Enumerator
NONE	None.
CONSTANT	Constant.
LINEAR	Linear.
CUBIC	Cubic.

Definition at line 1033 of file SoVolumeData.h.

StorageHint

enum SoVolumeData::StorageHint

Storage Hints mode TODO: this enum should be in the private section as its storageHints deprecated field coiunterpart BUT it is used in other internal implementation place.

Enumerator
AUTO	Auto (Default)
TEX2D_MULTI	Multi-texture 2D.
TEX2D	(synonym for TEXT2D_MULTI)
TEX3D	Texture 3D.
MEMORY	In memory.

Definition at line 992 of file SoVolumeData.h.

SubMethod

enum SoVolumeData::SubMethod

Sub sampling method mode.

Enumerator
NEAREST	Nearest.
MAX	Max.
AVERAGE	Average.

Definition at line 1020 of file SoVolumeData.h.

Constructor & Destructor Documentation

SoVolumeData()

SoVolumeData::SoVolumeData

(

)

Constructor.

Member Function Documentation

editBoxes()

virtual int SoVolumeData::editBoxes ( const std::vector< SbVec3i32 > &  boxCenters, const int &  boxSize, const double &  newValue  )

virtual

Replace all voxels in the region defined by a list of boxes with the specified value.

boxCenter and boxSize are defined in ijk (voxel) space.

Call startEditing() before calling this method. Returns 0 if successful.

Reimplemented from SoDataSet.

editSolidShape()

virtual int SoVolumeData::editSolidShape ( const SoNode *  solidShape, const double &  value  )

virtual

Replaces all voxels intersecting the given shape with the specified value.

The geometry defined under solidShape must represent a list of closed surfaces otherwise the result is unpredictable. solidShape must not contain any lines or open polyhedrons (polyhedron with shapes). The result is based on the odd-winding rule, so the result is not necessarily the union or the intersection of the closed surfaces. If you want to voxelize lines or single polygons, see also the editSurfaceShape method.

If the goal is to define a shape which is the result of the intersection/union of multiple closed surfaces, see the SoCSGShape node.

solidShape is defined in the same 3D space as the dataSet. The solidShape can be deleted after calling this function.

Call startEditing() before calling this method. Returns 0 if successful.

Warning

The modification may be postponed until the tiles are really needed. Therefore the surfaceShape node (and children if any) must not be modified until after saveEditing() is called.

Reimplemented from SoDataSet.

Reimplemented in SoVolumeMask.

editSubVolume() [1/2]

virtual int SoVolumeData::editSubVolume ( const SbBox3i32 &  subVolume, const double &  value  )

virtual

Replaces the contents of a subvolume with the specified value.

The subvolume is specified in voxel/cell coordinates. Call startEditing() before calling this method. Returns 0 if successful.

Reimplemented from SoDataSet.

Reimplemented in SoVolumeMask.

editSubVolume() [2/2]

virtual int SoVolumeData::editSubVolume ( const SbBox3i32 &  subVolume, SoBufferObject *  userData  )

virtual

Replaces the contents of a subvolume with the given data.

The buffer size (in bytes) must match the subvolume size (in bytes) exactly. The subvolume is specified in voxel/cell coordinates. Call startEditing() before calling this method. Returns 0 if successful.

Warning

The modification may be postponed until the tiles are really needed. Therefore the contents of the userData buffer must not be modified until after saveEditing() is called. However the buffer may be unref'd.

Reimplemented from SoDataSet.

Reimplemented in SoVolumeMask.

editSurfaceShape()

virtual int SoVolumeData::editSurfaceShape ( const SoNode *  surfaceShape, const float &  thickness, const double &  newValue  )

virtual

Replaces all voxels intersecting the polygons or lines defined by the surfaceShape and given thickness with the specified value.

surfaceShape is defined in the same 3D space as the dataSet. thickness is defined in voxels. The surfaceShape can be deleted after calling this function.

Call startEditing() before calling this method. Returns 0 if successful.

Warning

The modification may be postponed until the tiles are really needed. Therefore the surfaceShape node (and children if any) must not be modified until after saveEditing() is called.

Reimplemented from SoDataSet.

Reimplemented in SoVolumeMask.

editTile() [1/2]

virtual int SoVolumeData::editTile ( const SoLDMTileID &  tileId, const double &  value  )

virtual

Replaces the contents of a tile with the specified value.

Call startEditing() before calling this method. Returns 0 if successful.

Reimplemented from SoDataSet.

editTile() [2/2]

virtual int SoVolumeData::editTile ( const SoLDMTileID &  tileId, SoBufferObject *  userData  )

virtual

Replaces the contents of a tile with the given data.

The buffer size (in bytes) must match the tile size (in bytes) exactly. Call startEditing() before calling this method. Returns 0 if successful.

Warning

The modification may be postponed until the tile is really needed. Therefore the contents of the userData buffer must not be modified until after saveEditing() is called. However the buffer may be unref'd.

Reimplemented from SoDataSet.

finishEditing()

virtual SbBool SoVolumeData::finishEditing ( int  transactionId )

virtual

Terminates an editing transaction.

Returns true if successful. May only be called with a valid transaction id returned by the startEditing() method. On error does nothing. The finish method will schedule a redraw so the correct data is displayed. To commit the edits, in other words to save the edited data back to the data source, call saveEditing().

Reimplemented from SoDataSet.

getClassTypeId()

static SoType SoVolumeData::getClassTypeId ( )

static

Returns the type identifier for this class.

getCoordinateType()

CoordinateType SoVolumeData::getCoordinateType

(

)

const

getHistogram()

SbBool SoVolumeData::getHistogram	(	int &	length,
		int64_t *&	histogram
	)

Returns the histogram of the volume data.

Returns FALSE if the requested data is not available.

Notes:

• Byte
  For byte data, VolumeViz computes a histogram with 256 bins, spanning the range of byte values (0..255 or -128..127).
• Integer
  For integer data types larger than 1 byte, VolumeViz computes a histogram with 65536 bins, spanning the range of the data type. For example, if the volume contains signed_short data, the histogram has 65536 bins spanning the range -32768..32767.
• Float
  For float data, VolumeViz computes a histogram with 65536 bins, spanning the specified data range or -20000 to 20000 if no range was specified. The data range can be specified when converting to LDM format, using the converter's "-r" option. Otherwise it is not currently possible to specify the data range for the histogram without using SoVolumeHistogram directly.
• Bins
  For all data types larger than one byte, only the bins that are inside the actual range of the data are interesting. For example a signed_short data set might range from -2048 to 5000. In this case the first non-empty bin is number 30720 (out of 65536 total bins) and the last non-empty bin is number 37827.
• New histogram
  To compute a histogram (for example with different parameters or for a subvolume) use the SoVolumeHistogram class.

Warnings:

• This method returns a reference to VolumeViz internal storage. Do not modify this memory.
• Histogram computation
  This method might force VolumeViz to load the entire data set if the volume reader does not respond to the getHistogram query. Normally for an LDM format data set, the histogram values are stored in the LDM header. For a non-LDM data set, if a filename and/or reader have been specified and the data set has not yet been loaded, VolumeViz will load the entire data set to compute these values. For a large data set this may take a long time.

getMinMax() [1/2]

virtual SbBool SoVolumeData::getMinMax ( double &  min, double &  max  )

virtual

Returns min and max values of the data set.

Returns FALSE if the requested data is not available (for example, if no data set exists).

NOTE: This method might force LDM to load the entire data set if the volume reader does not respond to the getMinMax query. Normally for an LDM format data set, the min and max values are stored in the LDM header. For a non-LDM data set, if a filename and/or reader have been specified and the data set has not yet been loaded, LDM will load the entire data set to compute the min and max values. For a large data set this may take a long time.

Reimplemented from SoDataSet.

getMinMax() [2/2]

virtual SbBool SoVolumeData::getMinMax ( int64_t &  min, int64_t &  max  )

virtual

Returns min and max values of the data set data.

Returns FALSE if the requested data is not available (for example, if no data set exists).

NOTE: This method might force LDM to load the entire data set if the volume reader does not respond to the getMinMax query. Normally for an LDM format data set, the min and max values are stored in the LDM header. For a non-LDM data set, if a filename and/or reader have been specified and the data set has not yet been loaded, LDM will load the entire data set to compute the min and max values. For a large data set this may take a long time.

Reimplemented from SoDataSet.

getRectilinearCoordinates()

const std::vector< float > & SoVolumeData::getRectilinearCoordinates

(

Axis

axis

)

const

Returns a vector describing mapping from uniform space to rectilinear space.

You can specify that you want the vector to return the coordinates from the X, Y, or Z axis.

getTexMemorySize()

SoDEPRECATED int SoVolumeData::getTexMemorySize

(

)

Returns the maximum texture memory size to use in mega texels.

getTypeId()

virtual SoType SoVolumeData::getTypeId ( ) const

virtual

Returns the type identifier for this specific instance.

Reimplemented from SoDataSet.

Reimplemented in SoHeightFieldGeometry, SoHeightFieldProperty, SoHeightFieldPropertyMask, and SoVolumeMask.

redoEditing()

virtual SbBool SoVolumeData::redoEditing ( int  transactionId )

virtual

Redo all modifications associated with the specified transaction id.

Returns true if successful. On error does nothing. May only be called after the specified transaction has been terminated (see finishEditing() method) and undone (see undoEditing() method). Schedules a redraw so the correct data is displayed.

Note: Redo is no longer available after transactions are saved. After calling saveEditing(), the transaction ids are no longer valid and the modified data is the new reference.

Reimplemented from SoDataSet.

reSampling()

SoDEPRECATED SoVolumeData * SoVolumeData::reSampling	(	const SbVec3i32 &	dimension,
		SoVolumeData::SubMethod	subMethod,
		SoVolumeData::OverMethod	= NONE
	)

Re-samples the volume down to or up to the given dimension using the sub-sampling method SubMethod() and the over-sampling method OverMethod().

If a reader is specified, the original volume data is not loaded.

Over-sampling is not yet implemented. NONE (default) indicates that no over-sampling is performed. For example if the original dimension is 256x256x64 and the reSampling dimension is 128x128x128, the result is a volume of dimension 128x128x64.

saveEditing()

virtual SbBool SoVolumeData::saveEditing ( bool  recomputeLowerResolution = TRUE, const std::vector< char * >  convertionParameters = std::vector< char * >(), SaveEditingCB *  callback = NULL  )

virtual

Commit all transactions.

All modified tiles are written back to the data source using the current reader format. May only be called when no threads are editing, i.e. after all threads that called startEditing have called finishEditing.

Returns true if successful. On error does nothing returns false. Returns false if:

• No edits have been done.
• Transaction(s) still in progress (finishEditing has not been called).
• Volume was not loaded using a volume reader (direct from memory doesn't work).
• No volume writer class exists for this volume reader.

Warning: Effectively, saveEditing currently only works for data loaded using an SoVRLDMFileReader (an LDM format tiled data set) or an SoVRMemoryReader (data set completely in memory).

Reimplemented from SoDataSet.

setRGBAData()

void SoVolumeData::setRGBAData

(

const bool

flag

)

Force data to be considered as RGBA values.

Note that this call should be used only when setting data from memory through the data field and the data format must be UNSIGNED_INT32.

setTexMemorySize()

SoDEPRECATED void SoVolumeData::setTexMemorySize

(

int

size

)

Specifies the maximum texture memory size to use in mega texels.

64 is the default.

startEditing()

virtual SbBool SoVolumeData::startEditing ( int &  transactionId )

virtual

Initiate an editing transaction.

Returns true if successful and also returns a unique transaction id. This value is required for finishing the edit transaction (see finishEditing()) and for undo/redo (see undoEditing() and redoEditing()). Multiple transactions may be active at the same time.

Reimplemented from SoDataSet.

subSetting()

SoDEPRECATED SoVolumeData * SoVolumeData::subSetting

(

const SbBox3i32 &

region

)

Extracts the data volume defined by region.

If a reader is specified, the original volume data is not loaded.

undoEditing()

virtual SbBool SoVolumeData::undoEditing ( int  transactionId )

virtual

Undo all modifications associated with the specified transaction id.

Returns true if successful. On error does nothing. May only be called after the specified transaction has been terminated (see finishEditing() method). Schedules a redraw so the correct data is displayed.

Note: Undo is no longer available after transactions are saved. After calling saveEditing(), the transaction ids are no longer valid and the modified data is the new reference.

Reimplemented from SoDataSet.

updateRegions()

void SoVolumeData::updateRegions	(	const SbBox3i32 *	region,
		int	num_regions
	)

Updates regions of the volume that have been modified.

This method notifies VolumeViz that voxels in the specified regions have been modified by the application and textures may need to be recreated. Only bricks currently needed for rendering some volume geometry, e.g., a slice or subvolume, are immediately updated.

updateTilesInTextureMemory()

void SoVolumeData::updateTilesInTextureMemory	(	SoLDMTileID *	tiles,
		int	numTiles
	)

Reloads textures corresponding to the given tile IDs.

Only supported in LDM mode. Useful for a bottom-up approach (a custom tile manager starts loading full resolution and returns fake data for lower resolution. Once the real low resolution data is in memory, update).

Friends And Related Symbol Documentation

::SoVolumeState

friend class ::SoVolumeState

friend

Definition at line 1272 of file SoVolumeData.h.

Member Data Documentation

data

SoSFArray3D SoVolumeData::data

Specifies the volume data, including dimensions, data type and number of significant bits.

Use this field if your volume data is already loaded into memory in a contiguous block of memory. Otherwise use the fileName field or the setReader method.

The numSigBits parameter of SoSFArray3D::setValue indicates the number of bits really used for each value. If it equals 0, that means to use all bits, e.g., 8 bits if type = UNSIGNED_BYTE, 16 bits if type = UNSIGNED_SHORT and so on. This parameter is useful particularly when textures are loaded in paletted mode. Currently most hardware supports only 8 bits, so VolumeViz must discard the least significant bits. For example if type is UNSIGNED_SHORT, by default in paletted mode VolumeViz will discard the lowest 8 bits. If you specify numSigBits = 10, VolumeViz will discard only the lowest 2 bits.

Calling SoSFArray3D::setValue with a CopyPolicy set to NO_COPY is equivalent to calling the deprecated SoVolumeData::setValue method.

Volume reader: Note that when a file format reader or custom volume reader is currently being used, setting the data field will automatically replace the current volume reader. Subsequent calls to getReader() will return an SoVRMemoryReader.

NOTE: field available since Open Inventor 7.1

Definition at line 816 of file SoVolumeData.h.

dataRGBA

SoSFBool SoVolumeData::dataRGBA

Contains TRUE if the volume contains RGBA values rather than scalar values.

Default is FALSE.

This field is set automatically by volume readers. If the application is setting an in-memory volume into the data field, the data field must be set to UNSIGNED_INT32 format and the dataRGBA field must be set to TRUE.

Note that, for compatibility with older versions of Open Inventor, if the data is in-memory the the unsigned int values must contain ABGR values, not RGBA. Use the SbColor getPackedValueEndiannessOrder() method to convert values, not the getPackedValue() method.

NOTE: field available since Open Inventor 9.0

Definition at line 834 of file SoVolumeData.h.

useExtendedData

SoSFBool SoVolumeData::useExtendedData

If TRUE, VolumeViz stores an additional copy of each loaded tile.

There is an additional memory cost but the performance of SoOrthoSlice roaming will be roughly the same along each axis.

NOTE: field available since Open Inventor 6.0

Definition at line 791 of file SoVolumeData.h.

usePalettedTexture

SoSFBool SoVolumeData::usePalettedTexture

For a volume containing scalar data values, controls whether scalar values (true) or RGBA values (false) are loaded on the GPU (the name is historical).

The default is true, meaning to load scalar values on the GPU. This implies that the GPU will interpolate between data values and the GPU will apply the color map. Using scalar values has several advantages and is the recommended setting in most cases. Loading scalar values (generally) uses less GPU memory per voxel and the color map can be changed interactively because no volume data needs to be reloaded on the GPU. Also note that interpolating between color values (rather than data values) could result in unexpected colors that are not even part of the color map. The size (in bytes) of the scalar values on the GPU is determined by the texturePrecision field.

If this field is false, the color map is applied on the CPU and the resulting RGBA values are loaded on the GPU. This implies that the GPU will interpolate between color values. There are a few cases where this setting is better. For example, interpolating between data values could create values that not actually in the data set. Also, applying the color map on the CPU means that a very large color map can be used because the size is not limited by the maximum texture size on the GPU.

If the volume contains explicit RGBA values, then this field is ignored and RGBA values are sent to the GPU.

Definition at line 769 of file SoVolumeData.h.

useSharedPalettedTexture

SoSFBool SoVolumeData::useSharedPalettedTexture

Note: On graphics boards that support programmable shaders, this field is ignored (virtually all graphics boards support programmable shaders).

Controls use of the OpenGL shared texture palette extension (if available). FALSE means don't use it. Default is TRUE. On machines that support paletted textures, using a shared palette conserves texture memory because a single palette (color map) can be used for all the textures.

Definition at line 781 of file SoVolumeData.h.

---

The documentation for this class was generated from the following file:

• VolumeViz/nodes/SoVolumeData.h