This virtual class provides the interface through which VolumeViz accesses volume data that is not already in memory. Predefined reader classes are provided for many common formats like DICOM and SEGY. See the list of supported file formats and class names below.

Application developers may implement custom reader classes. Custom reader classes allow VolumeViz to access data stored in other file formats. This is particularly useful for converting data to LDM format. A custom reader class could also allow VolumeViz to access data through a proprietary data manager or data stored in application memory.

Minimum implementation:

The application must implement a class derived from OIV.LDM.Readers.SoVolumeReader, and must implement the method OIV.LDM.Readers.SoVolumeReader.GetDataChar(OIV.Inventor.SbBox3f@, OIV.LDM.Nodes.SoDataSet.DataTypes@, OIV.Inventor.SbVec3i32@). In addition, the optional methods OIV.LDM.Readers.SoVolumeReader.GetNumSignificantBits() and OIV.LDM.Readers.SoVolumeReader.GetMinMax(System.Int64@, System.Int64@) can be implemented. If OIV.LDM.Readers.SoVolumeReader.GetNumSignificantBits() is not implemented (or returns 0), then the number of significant bits depends on the data type. If OIV.LDM.Readers.SoVolumeReader.GetMinMax(System.Int64@, System.Int64@) is not implemented (or returns false), then VolumeViz will find the min and max voxel values. Note that this requires loading all the data and could take a lot of time for a large volume.

VolumeViz always calls OIV.LDM.Readers.SoVolumeReader.GetDataChar(OIV.Inventor.SbBox3f@, OIV.LDM.Nodes.SoDataSet.DataTypes@, OIV.Inventor.SbVec3i32@) and OIV.LDM.Readers.SoVolumeReader.GetNumSignificantBits() before requesting any data from the reader.

If the () method is not implemented (or returns false), then VolumeViz will only call OIV.LDM.Readers.SoVolumeReader.GetSubSlice(OIV.Inventor.SbBox2i32, System.Int32, OIV.Inventor.Generic.SbNativeArray{{System.Byte}}) to request data and will build the LDM tile hierarchy in memory, using the slice data. In this case, note that:

• VolumeViz always caches data in memory using an LDM multi-resolution, tiled hierarchy. Therefore OIV.LDM.Readers.SoVolumeReader.GetSubSlice(OIV.Inventor.SbBox2i32, System.Int32, OIV.Inventor.Generic.SbNativeArray{{System.Byte}}) may be called multiple times with the same slice number as tiles are constructed in memory.

• The tile dimensions used to cache data in memory are determined by the tileDimension field of the OIV.LDM.Nodes.SoLDMResourceParameters object associated with the OIV.VolumeViz.Nodes.SoVolumeData node. This field can be set by the application, but VolumeViz will not automatically set it (as it does in the case of an LDM reader). Of course a custom reader could implement the OIV.LDM.Readers.SoVolumeReader.GetTileSize(OIV.Inventor.SbVec3i32@) method for the application to call, even though VolumeViz doesn't use it.

• VolumeViz will not call the OIV.LDM.Readers.SoVolumeReader.GetHistogram(System.Collections.Generic.IList{{System.Int64}}) method. So if the application calls OIV.LDM.Readers.SoVolumeReader.GetHistogram(System.Collections.Generic.IList{{System.Int64}}) on the OIV.VolumeViz.Nodes.SoVolumeData node, VolumeViz will build the histogram. This requires loading all the data and could take a lot of time for a large volume. However if VolumeViz builds the histogram, it also finds the min and max values, so there is no extra time required for that query.

LDM (tiled) volume reader:

In addition to the usual requirements for an application-defined reader, e.g., implementing the OIV.LDM.Readers.SoVolumeReader.GetDataChar(OIV.Inventor.SbBox3f@, OIV.LDM.Nodes.SoDataSet.DataTypes@, OIV.Inventor.SbVec3i32@) method, an application-defined reader for LDM data is required to:

• Implement the () method and return true. The method must return true when the reader is passed to OIV.VolumeViz.Nodes.SoVolumeData to ensure that LDM manager classes are correctly initialized.

• Implement the OIV.LDM.Readers.SoVolumeReader.ReadTile(System.Int32, OIV.Inventor.SbBox3i32) method.

  • When implementing the readTile method, be aware that how the SoCpuBuffer object is created affects how its memory will be managed. In general you should create the object using the constructor with no parameters, then allocate memory inside the object using the setSize() method. In this case the buffer object owns the memory and the memory will be freed when LDM no longer needs this tile. This implies for example that to avoid data copying when reading tile data from a file, you should create and allocate the buffer object, map the buffer object, then read the data into the buffer object. If you create the buffer object "wrapping" an existing block of memory, that memory will not be freed when LDM releases the buffer object. The application owns that memory and is responsible for freeing it.

  • Note that readTile can return one of the specialized sub-classes of OIV.Inventor.Devices.SoCpuBufferObject that use less system memory:

    • OIV.LDM.Tiles.SoCpuBufferUniform: This buffer contains a "uniform" tile in which all the voxels have the same value. It is stored efficiently as a single value until needed.

    • OIV.LDM.Tiles.SoCpuBufferCompressed: This buffer contains a compressed tile. It is stored efficiently in its compressed form until needed.

    • OIV.LDM.Tiles.SoCpuBufferBasicProperty: This buffer contains a standard tile, but can also store the tile's min and max data values for use in various optimizations.

    • SoCpuBufferBitset: This contains a bitset tile in which each voxel is a boolean value. It is stored efficiently in a packed form until needed.

  • Also note that readTile can return an undefined tile by returning either NULL or an empty buffer. See OIV.LDM.Readers.SoVolumeReader.ReadTile(System.Int32, OIV.Inventor.SbBox3i32) for detail.

• Implement the OIV.LDM.Readers.SoVolumeReader.GetTileSize(OIV.Inventor.SbVec3i32@) method

An application-defined LDM reader may optionally:

• Implement the OIV.LDM.Readers.SoVolumeReader.GetMinMax(System.Int64@, System.Int64@) method Return true and the requested values if the min and max data values for the volume are known to the reader, e.g., are in the file header. The reader should implement this method if possible, because applications typically query these values to setup their OIV.LDM.Nodes.SoDataRange node. If this method is not implemented, and the application calls OIV.VolumeViz.Nodes.SoVolumeData.GetMinMax(System.Int64@, System.Int64@) is called, then VolumeViz must load every tile to compute the volume min and max. This can cause a long delay.

• Implement the OIV.LDM.Readers.SoVolumeReader.GetTileMinMax(System.Int32) method Return the min and max values for the specified data tile. This information benefits optimizations such as OIV.LDM.SoLDMGlobalResourceParameters.SetIgnoreFullyTransparentTiles(System.Boolean). If this method is not implemented, VolumeViz will automatically compute the min and max values for each tile when it is loaded. Automatic computation works fine for volume data, but we strongly recommend implementing this method for height field data.

• Implement the OIV.LDM.Readers.SoVolumeReader.GetHistogram(System.Collections.Generic.IList{{System.Int64}}) method Return true and the requested values if the min and max data values are known to the reader, e.g., are in the file header.

General information:

Starting with Open Inventor 7.0, general rectilinear grids are supported. This feature allows non-uniform voxel spacing along each axis of the volume. The AmiraMesh reader (.am file), the in-memory reader, and the LDM reader support rectilinear coordinates. Call the method setRectilinearCoordinates to specify rectilinear coordinates (if they are not already stored in the data file and set by the reader).

Starting with Open Inventor 7.0, OIV.LDM.Readers.SoVolumeReader is derived from OIV.Inventor.Fields.SoFieldContainer. This allows client classes like OIV.VolumeViz.Nodes.SoVolumeData to be automatically notified when the reader's state changes, and update their own state appropriately. Any reader method that changes the volume properties (dimension, size, data type, etc) should trigger notification by calling the reader's OIV.Inventor.Misc.SoBase.Touch() method. If this notification is not done, client node fields, for example OIV.LDM.Nodes.SoDataSet.extent, won't be updated correctly. For example, a reader with a method setData(SbVec3i32 size, void* data) that loads a new data set should call OIV.Inventor.Misc.SoBase.Touch() at its end. This reader could also be implemented using an OIV.Inventor.Fields.SoSFArray3D field instead of the setData method. Modifying this field will automatically trigger notification.

Applications should subclass from OIV.LDM.Readers.SoVolumeReader when creating any type of custom volume reader, including an LDM (tiled) volume reader. The classes OIV.LDM.Readers.SoLDMReader and OIV.LDM.Readers.SoVRLdmFileReader are internal classes which are specific to the VSG defined LDM file format.

This class cannot be instantiated directly.

Supported file formats:

File extension	Reader class	Description
.am	OIV.VolumeViz.Readers.SoVRAmFileReader	Avizo Mesh file format
.dc3, .dic, .dicom	OIV.VolumeViz.Readers.SoVRDicomFileReader	DICOM file format
.fld	OIV.VolumeViz.Readers.SoVRAvsFileReader	AVS field file format
.lda or .ldm	OIV.LDM.Readers.SoVRLdmFileReader	LDM file format
.mrc	OIV.VolumeViz.Readers.SoVRMrcFileReader	MRC file format
.sgy or .segy	OIV.VolumeViz.Readers.SoVRSegyFileReader	SEG Y rev 1 file format
.vol	OIV.VolumeViz.Readers.SoVRVolFileReader	Vol file format
.vox	OIV.VolumeViz.Readers.SoVRVoxFileReader	Vox file format
.lst	OIV.VolumeViz.Readers.SoVRRasterStackReader	Lst file format (stack of images)

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 OIV.VolumeViz.Readers.SoVRAmFileReader for limitations.

• 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 OIV.VolumeViz.Readers.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 OIV.VolumeViz.Readers.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 OIV.VolumeViz.Converters.SoVolumeConverter). Preprocessing volume data into this format provides the maximum benefits from the VolumeViz large data management (LDM) features. See OIV.LDM.Readers.SoVRLdmFileReader.

• MRC MRC is a file format that has become an industry standard for cryo-electron microscopy (cryoEM) and electron tomography (ET) (http://www.ccpem.ac.uk/mrc_format/mrc2014.php). See OIV.VolumeViz.Readers.SoVRMrcFileReader.

• 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 OIV.VolumeViz.Readers.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 OIV.VolumeViz.Readers.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 (one image per file). 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 OIV.VolumeViz.Readers.SoVRRasterStackReader for details and limitations.

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

Reference