SoVolumeData Class Reference

The main interface for setting up volume data sets. More...

#include <VolumeViz/nodes/SoVolumeData.h>

Inheritance diagram for SoVolumeData:

Public Types
enum	StorageHint {   AUTO, TEX2D_MULTI, TEX2D = TEX2D_MULTI, TEX3D,   MEMORY, VOLUMEPRO, TEX2D_SINGLE }
enum	SubMethod { NEAREST, MAX, AVERAGE }
enum	OverMethod { NONE, CONSTANT, LINEAR, CUBIC }
enum	DataType { UNSIGNED_BYTE, UNSIGNED_SHORT }
Public Types inherited from SoVolumeRendering
enum	HW_Feature { HW_VOLUMEPRO, HW_3DTEXMAP, HW_TEXCOLORMAP, HW_TEXCOMPRESSION }
enum	HW_SupportStatus { NO, YES, UNKNOWN }
Public Types inherited from SoNode
enum	NodeType

Public Member Functions
void	setVolumeData (const SbVec3s &dimension, void *data, SoVolumeData::DataType type=SoVolumeData::UNSIGNED_BYTE, int significantbits=0)
SbBool	getVolumeData (SbVec3s &dimension, void *&data, SoVolumeData::DataType &type, int *significantbits=NULL) const
uint32_t	getVoxelValue (const SbVec3s &voxelpos) const
void	setVolumeSize (const SbBox3f &size)
SbBox3f	getVolumeSize (void) const
void	setPageSize (int size)
void	setPageSize (const SbVec3s &size)
const SbVec3s &	getPageSize (void) const
void	setReader (SoVolumeReader &reader)
SoVolumeReader *	getReader (void) const
void	setTexMemorySize (int megatexels)
int	getTexMemorySize (void) const
SbBool	getMinMax (int &minval, int &maxval)
SbBool	getHistogram (int &length, int *&histogram)
SoVolumeData *	subSetting (const SbBox3s &region)
void	updateRegions (const SbBox3s *region, int num)
void	loadRegions (const SbBox3s *region, int num, SoState *state, SoTransferFunction *node)
SoVolumeData *	reSampling (const SbVec3s &dimension, SoVolumeData::SubMethod subMethod, SoVolumeData::OverMethod=NONE)
void	enableSubSampling (SbBool enable)
SbBool	isSubSamplingEnabled (void) const
void	enableAutoSubSampling (SbBool enable)
SbBool	isAutoSubSamplingEnabled (void) const
void	enableAutoUnSampling (SbBool enable)
SbBool	isAutoUnSamplingEnabled (void) const
void	unSample (void)
void	setSubSamplingMethod (SubMethod method)
SubMethod	getSubSamplingMethod (void) const
void	setSubSamplingLevel (const SbVec3s &roi, const SbVec3s &secondary)
void	getSubSamplingLevel (SbVec3s &roi, SbVec3s &secondary) const
Public Member Functions inherited from SoVolumeRendering
HW_SupportStatus	isSupported (HW_Feature feature)
Public Member Functions inherited from SoNode
void	setOverride (const SbBool state)
SbBool	isOverride (void) const
void	setNodeType (const NodeType type)
NodeType	getNodeType (void) const
virtual SoNode *	copy (SbBool copyconnections=FALSE) const
virtual SbBool	affectsState (void) const
virtual void	GLRenderBelowPath (SoGLRenderAction *action)
virtual void	GLRenderInPath (SoGLRenderAction *action)
virtual void	GLRenderOffPath (SoGLRenderAction *action)
virtual void	getMatrix (SoGetMatrixAction *action)
virtual void	handleEvent (SoHandleEventAction *action)
virtual void	rayPick (SoRayPickAction *action)
virtual void	search (SoSearchAction *action)
virtual void	write (SoWriteAction *action)
virtual void	audioRender (SoAudioRenderAction *action)
virtual void	getPrimitiveCount (SoGetPrimitiveCountAction *action)
virtual void	grabEventsSetup (void)
virtual void	grabEventsCleanup (void)
virtual void	startNotify (void)
virtual void	notify (SoNotList *l)
SbUniqueId	getNodeId (void) const
virtual SoChildList *	getChildren (void) const
virtual void	writeInstance (SoOutput *out)
virtual SoNode *	addToCopyDict (void) const
virtual void	copyContents (const SoFieldContainer *from, SbBool copyconnections)
virtual SoFieldContainer *	copyThroughConnection (void) const
Public Member Functions inherited from SoFieldContainer
void	setToDefaults (void)
SbBool	hasDefaultValues (void) const
SbBool	fieldsAreEqual (const SoFieldContainer *container) const
void	copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
SbBool	set (const char *const fielddata)
void	get (SbString &fielddata)
virtual int	getFields (SoFieldList &l) const
virtual int	getAllFields (SoFieldList &l) const
virtual SoField *	getField (const SbName &name) const
virtual SoField *	getEventIn (const SbName &name) const
virtual SoField *	getEventOut (const SbName &name) const
SbBool	getFieldName (const SoField *const field, SbName &name) const
SbBool	enableNotify (const SbBool flag)
SbBool	isNotifyEnabled (void) const
SbBool	set (const char *fielddata, SoInput *input)
void	get (SbString &fielddata, SoOutput *out)
virtual SbBool	validateNewFieldValue (SoField *field, void *newval)
virtual void	addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
SbBool	getIsBuiltIn (void) const
virtual const SoFieldData *	getFieldData (void) const
virtual void	getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
void	setUserData (void *userdata) const
void *	getUserData (void) const
Public Member Functions inherited from SoBase
void	ref (void) const
void	unref (void) const
void	unrefNoDelete (void) const
int32_t	getRefCount (void) const
void	touch (void)
virtual SoType	getTypeId (void) const=0
SbBool	isOfType (SoType type) const
virtual SbName	getName (void) const
virtual void	setName (const SbName &newname)
void	addAuditor (void *const auditor, const SoNotRec::Type type)
void	removeAuditor (void *const auditor, const SoNotRec::Type type)
const SoAuditorList &	getAuditors (void) const
SbBool	shouldWrite (void)
void	assertAlive (void) const

Static Public Member Functions
static void	initClass (void)
Static Public Member Functions inherited from SoVolumeRendering
static void	init (void)
static void	initClass (void)
static void	setReadAlternateRep (SbBool flag)
static void	setWriteAlternateRep (SbBool flag)
static SbBool	getReadAlternateRep (void)
static SbBool	getWriteAlternateRep (void)
static void	setDelayedRendering (SbBool flag)
static SbBool	getDelayedRendering (void)
Static Public Member Functions inherited from SoNode
static uint32_t	getCompatibilityTypes (const SoType &nodetype)
static SoType	getClassTypeId (void)
static SoNode *	getByName (const SbName &name)
static int	getByName (const SbName &name, SoNodeList &l)
static void	initClass (void)
static void	initClasses (void)
static SbUniqueId	getNextNodeId (void)
static int	getActionMethodIndex (const SoType type)
static void	getBoundingBoxS (SoAction *action, SoNode *node)
static void	GLRenderS (SoAction *action, SoNode *node)
static void	callbackS (SoAction *action, SoNode *node)
static void	getMatrixS (SoAction *action, SoNode *node)
static void	handleEventS (SoAction *action, SoNode *node)
static void	pickS (SoAction *action, SoNode *node)
static void	rayPickS (SoAction *action, SoNode *node)
static void	searchS (SoAction *action, SoNode *node)
static void	writeS (SoAction *action, SoNode *node)
static void	audioRenderS (SoAction *action, SoNode *node)
static void	getPrimitiveCountS (SoAction *action, SoNode *node)
Static Public Member Functions inherited from SoFieldContainer
static void	initClass (void)
static SoType	getClassTypeId (void)
static void	cleanupClass (void)
static void	initCopyDict (void)
static void	addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
static SoFieldContainer *	checkCopy (const SoFieldContainer *orig)
static SoFieldContainer *	findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
static void	copyDone (void)
Static Public Member Functions inherited from SoBase
static void	initClass (void)
static SoType	getClassTypeId (void)
static void	addName (SoBase *const base, const char *const name)
static void	removeName (SoBase *const base, const char *const name)
static void	incrementCurrentWriteCounter (void)
static void	decrementCurrentWriteCounter (void)
static SoBase *	getNamedBase (const SbName &name, SoType type)
static int	getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
static SbBool	read (SoInput *input, SoBase *&base, SoType expectedtype)
static void	setInstancePrefix (const SbString &c)
static void	setTraceRefs (SbBool trace)
static SbBool	getTraceRefs (void)
static SbBool	connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
static SbBool	readRoute (SoInput *input)

Public Attributes
SoSFString	fileName
SoSFEnum	storageHint
SoSFBool	usePalettedTexture
SoSFBool	useSharedPalettedTexture
SoSFBool	useCompressedTexture
Public Attributes inherited from SoNode
	INVENTOR
	VRML1
	VRML2
	INVENTOR_1
	INVENTOR_2_0
	INVENTOR_2_1
	INVENTOR_2_5
	INVENTOR_2_6
	COIN_1_0
	COIN_2_0
	EXTENSION
	COIN_2_2
	COIN_2_3
	COIN_2_4
	INVENTOR_5_0
	COIN_2_5
	COIN_3_0
	INVENTOR_6_0
	COIN_4_0

Protected Member Functions
virtual void	doAction (SoAction *action)
virtual void	GLRender (SoGLRenderAction *action)
virtual void	callback (SoCallbackAction *action)
virtual void	getBoundingBox (SoGetBoundingBoxAction *action)
virtual void	pick (SoPickAction *action)
Protected Member Functions inherited from SoNode
virtual SbBool	readInstance (SoInput *in, unsigned short flags)
Protected Member Functions inherited from SoBase
virtual void	destroy (void)
SbBool	hasMultipleWriteRefs (void) const
SbBool	writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
void	writeFooter (SoOutput *out) const
virtual const char *	getFileFormatName (void) const
virtual SoNotRec	createNotRec (void)

Friends
class	SoVolumeDataP

Additional Inherited Members
Protected Types inherited from SoBase
enum	BaseFlags
Static Protected Member Functions inherited from SoNode
static const SoFieldData **	getFieldDataPtr (void)
static void	setNextActionMethodIndex (int index)
static int	getNextActionMethodIndex (void)
static void	incNextActionMethodIndex (void)
static void	setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)
Static Protected Member Functions inherited from SoBase
static uint32_t	getCurrentWriteCounter (void)
static void	staticDataLock (void)
static void	staticDataUnlock (void)
Protected Attributes inherited from SoNode
SbUniqueId	uniqueId
Protected Attributes inherited from SoFieldContainer
SbBool	isBuiltIn
Static Protected Attributes inherited from SoNode
static SbUniqueId	nextUniqueId
static int	nextActionMethodIndex

Detailed Description

The main interface for setting up volume data sets.

This node class provides the interface for setting up the voxel data to be rendered. For a complete, stand-alone usage example, see the SIM Voleon main page documentation.

Volume data will by default be normalized to be within a 2x2x2 unit dimensions cube. (But note that this is up to the reader classes, so it may not be the same for all readers. Check the individual class documentation for the file formats you are using.)

As an example, if you set up a voxel data set of dimensions 100x400x200, this will be rendered within a bounding box of <-0.25, -1, -0.5> to <0.25, 1, 0.5>. Notice that the largest dimension (the Y dimension in this example) will be made to fit within unit size 2, and the other dimensions will be scaled accordingly.

You may use SoVolumeData::setVolumeSize() to force a different unit size box around the volume, or you can simply use the standard Coin transformation nodes, like e.g. SoScale, to accomplish this.

The volume rendering of SIM Voleon works well on volume data sets of any dimensions. With other volume rendering systems, it is often necessary to accommodate the rendering system by preprocessing the dataset to be of power-of-two dimensions, either to avoid the rendering to take up an extraordinary amount of resources related to texture mapping, or from down-right failing. This restriction is not present in SIM Voleon, which works well with different dimensions along the principal axes, and with any non-power-of-two dimension.

If the volume data is set from a memory location with the SoVolumeData::setVolumeData() method, the voxel data can be changed during visualization at will. But after making a batch of changes, make sure you notify the node that data has been modified by doing the following:

volumedatanode->touch();

Internal regeneration of textures etc. for visualization will then be done automatically by the SIM Voleon rendering system.

Member Function Documentation

setVolumeData()

void SoVolumeData::setVolumeData	(	const SbVec3s &	dimensions,
		void *	data,
		SoVolumeData::DataType	type = SoVolumeData::UNSIGNED_BYTE,
		int	significantbits = 0
	)

This method lets the user set up a volume data set from data in memory, instead of loading it from file (through the SoVolumeData::fileName field).

data should point to the block of voxels, of the data size given by type. dimensions specifies the size layout of the voxel array along the 3 axes.

The data block passed in to this function will not be freed when the node is destructed, or new data set – that is considered the responsibility of the caller.

The input data will be mapped to the world coordinate system as follows: increasing memory addresses will first be mapped to increasing voxel positions along the X axis, row by row. The rows will be mapped to increasing positions along the Y axis, making up slices. Slices will be mapped to increasing Z axis positions.

The data will be mapped to be within a cube of size 2x2x2, where the largest voxel dimension(s) will be used to normalize the other dimensions.

As an example, if you set up a voxel data set of dimensions 100x400x200, this will be rendered within a bounding box of <-0.25, -1, -0.5> to <0.25, 1, 0.5>. Notice that the largest dimension (the Y dimension in this example) will be made to fit within unit size 2, and the other dimensions will be scaled accordingly.

References SbString::getString(), SoDebugError::postInfo(), SoDebugError::postWarning(), and SoBase::touch().

getVolumeData()

SbBool SoVolumeData::getVolumeData	(	SbVec3s &	dimensions,
		void *&	data,
		SoVolumeData::DataType &	type,
		int *	significantbits = NULL
	)		const

Returns information about the voxel dimensions, a data pointer to the memory block of voxels, and a type indicator for how many bytes are used for each voxel.

The return value is FALSE if the data could not be loaded.

References SoDebugError::postWarning().

getVoxelValue()

uint32_t SoVolumeData::getVoxelValue

(

const SbVec3s &

voxelpos

)

const

Returns "raw" value of voxel at given position.

setVolumeSize()

void SoVolumeData::setVolumeSize

(

const SbBox3f &

size

)

Sets the geometric size of the volume.

This will override the value found in a volume data file by a reader (if any).

References SbBox3f::getBounds(), and SoBase::touch().

getVolumeSize()

SbBox3f SoVolumeData::getVolumeSize

(

void

)

const

Returns geometric size of volume.

References SbBox3f::setBounds().

setPageSize() [1/2]

void SoVolumeData::setPageSize

(

int

size

)

Sets the largest internal size of texture pages and texture cubes. This sets all dimensions to the same value at once. Default value is 128^3.

The size value must be a power of two.

This is essentially of interest only for the internal implementation, and should usually not be necessary to change from application code.

setPageSize() [2/2]

void SoVolumeData::setPageSize

(

const SbVec3s &

texsize

)

Sets the largest internal size of texture pages and texture cubes. Default value is [128, 128, 128].

All elements of texsize must be a power of two.

This is essentially of interest only for the internal implementation, and should usually not be necessary to change from application code.

References SoBase::touch().

getPageSize()

const SbVec3s & SoVolumeData::getPageSize

(

void

)

const

Returns internal dimensions of each 2D texture rectangle or 3D texture cube.

setTexMemorySize()

void SoVolumeData::setTexMemorySize

(

int

megatexels

)

Set the maximum number of texels we can bind up for 2D and 3D textures for volume rendering. The value is given in number of megatexels, e.g. an argument value "16" will be interpreted to set the limit at 16*1024*1024=16777216 texels.

Note that you can in general not know in advance how much actual texture memory a texel is going to use, as textures can be paletted with a variable number of bits-per-texel, and even compressed before transferred to the graphics card's on-chip memory.

Due to the above mentioned reasons, the usefulness of this method is rather dubious, but it is still included for compatibility with TGS VolumeViz API extension to Open Inventor.

The default value is to allow unlimited texture memory usage. This means that it's up to the underlying OpenGL driver to take care of the policy of how to handle scarcity of resources. This is the recommended strategy from OpenGL documentation.

Note that SIM Voleon's default differs from TGS's VolumeViz default, which is set at 64 megatexels.

References SoDebugError::postWarning(), and SoBase::touch().

getTexMemorySize()

int SoVolumeData::getTexMemorySize

(

void

)

const

Returns limitation forced on texture memory usage.

See also

SoVolumeData::setTexMemorySize()

Since

SIM Voleon 2.0

getHistogram()

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

Returns a reference to a histogram of all voxel values. length will be set to either 256 for 8-bit data or 65356 for 16-bit data.

At each index of the histogram table, there will be a value indicating the number of voxels that has the data value corresponding to the index.

Return value is always TRUE.

loadRegions()

void SoVolumeData::loadRegions	(	const SbBox3s *	region,
		int	num,
		SoState *	state,
		SoTransferFunction *	node
	)

Force loading of given subregion. This function should usually not be of interest to the application programmer.

Since

SIM Voleon 2.0

References SoDebugError::post().

Member Data Documentation

usePalettedTexture

SoSFBool SoVolumeData::usePalettedTexture

Indicate whether or not to use paletted textures.

Paletted textures uses only 1/4th of the amount of graphics card memory resources versus ordinary RGBA textures, with no degradation of rendering quality.

Not all graphics cards and drivers supports paletted textures, but the library will fall back on non-paletted textures automatically if that is the case.

SIM Voleon supports two different OpenGL techniques for doing paletted textures: either through using the GL_EXT_paletted_texture extension available on many older OpenGL drivers, or by using fragment shader programs, the latter typically available on most modern OpenGL drivers.

Default value of this field is TRUE. Apart from debugging purposes, there are not many good reasons to set this field to FALSE.

It might however be of interest if one wants to take advantage of the typically larger resource savings which can be made from setting SoVolumeData::useCompressedTexture to TRUE, as that hint will be overridden by a TRUE value in this field (as long as paletted textures are actually supported by the OpenGL driver).

This because paletted textures can not be "lossy" compressed, so only one of paletted textures and texture compression can be active at the same time – not both of them. The policy of SIM Voleon is to prefer paletted textures, as that has certain other beneficial effects apart from resource savings, mainly that one can modify the SoTransferFunction at runtime with no rendering performance hit.

useSharedPalettedTexture

SoSFBool SoVolumeData::useSharedPalettedTexture

Indicate whether or not to share texture palettes.

Sharing of texture palettes is useful for slightly better utilization of graphics card memory.

Default value is TRUE. Apart from debugging purposes, there is really no good reason to set this field to FALSE.

NOTE: The actions of switching this flag have not been properly implemented in Coin yet, its value is simply ignored.

Since

SIM Voleon 2.0

TGS VolumeViz ?.?

useCompressedTexture

SoSFBool SoVolumeData::useCompressedTexture

Indicate whether or not to use compressed textures, if supported by the graphics card and driver.

Compressed textures can save a major amount of texture memory out of the graphics card memory resources, typically by a factor of about 5x - 15x. Texture compression is however lossy, meaning that there will be a certain amount of degradation of visual quality – but this should usually not be noticeable.

Not all graphics cards and drivers supports compressed textures, but the library will fall back on non-compressed textures automatically if that is the case.

Default value is TRUE. To secure no loss of visual quality, set this field to FALSE.

Note that texture compression will not be done if paletted textures are used. See the discussion at the end of the API documentation for the SoVolumeData::usePalettedTexture field.

---

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

• SoVolumeData.h
• VolumeData.cpp