The Data Access API provides methods to conveniently extract data from a volume. This is useful, for example, to extract data for computation, for segmentation or for display using other primitives. The data is accessible whether the OIV.VolumeViz.Nodes.SoVolumeData is part of a scene graph or not. These methods are only valid in LDM mode (which is the default mode). The Data Access API automatically takes advantage of LDM multi-threaded data loading when multiple tiles (not already in cache) are needed to complete the request.

The Data Access API automatically loads all data required to satisfy the request and can be invoked asynchronously to allow simultaneous loading and computation. The application can request data at any resolution level, e.g. full resolution (level 0) data, independent of the resolution level currently being used for rendering. For some requests, e.g. line and plane, the application can also specify a subvolume (region of interest) that limits the extent of the data request.

OIV.LDM.SoLDMDataAccess provides the following data requests:

• 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. (This is the best way to query individual voxels. See the method for more information.)

Each data request returns information struct specific to the request type. For example, OIV.LDM.SoLDMDataAccess.DataInfoBox is returned by the subvolume request. All these structs contain an errorFlag member containing the result of the request and a bufferSize member containing the amount of data (in bytes) returned. The application should always check these values. Note that even when errorFlag is CORRECT, bufferSize may be zero, meaning no data was returned. This happens, for example, if the specified plane is completely outside the volume.

The application is responsible for allocating and freeing the memory to store the requested data. Calling the data request method with a null bufferObject will return the size of the memory needed, in bytes, in the bufferSize member of the information struct. Once the buffer is allocated, a second call will extract the data from the volume. Since Open Inventor 8.0 we recommend using the methods that return data into an OIV.Inventor.Devices.SoBufferObject. Because this class abstracts access to data stored on different devices it is possible, for example, to conveniently fetch data into CPU memory or directly into GPU memory.

Each data request can be either synchronous or asynchronous. Synchronous means that all the data will be loaded before the function returns. Asynchronous means that the function will return immediately and you will be notified when the data is actually available. This allows the application to continue to work while the data is being loaded, for example to overlap data loading and computation. Synchronous access is done using the getData methods.

To do asynchronous access, you must create a new class derived from OIV.LDM.SoLDMDataAccess and implement your own version of the OIV.LDM.SoLDMDataAccess.EndRequest(System.Int32) method. Begin a request by calling the appropriate requestData method. This method will return a requestId.

• If the requestID is positive, this value will be passed to the OIV.LDM.SoLDMDataAccess.EndRequest(System.Int32) method when the requested data is ready, and can then be used with the appropriate getRequestedData method to complete the transaction.

• If the requestID is negative, the data is already in memory. In this case OIV.LDM.SoLDMDataAccess.EndRequest(System.Int32) will not be called, and -requestID (a positive value) should be used with the getRequestedData method. The data inside the destBuffer will be aligned as in the original volume. The info structure contains additional information about the current request including error status, coordinates (for line and polyline requests), tile id (for tile requests), etc.

Three different modes are available to control how data is requested from the volume reader when the necessary tiles are not already present in LDM cache memory:

• CACHE: When data is requested, the data is copied from the LDM cache (tiles in memory) if possible. If any required tiles are not in the LDM cache, LDM will load those tiles into cache, then copy the data from the cache. This is the default behavior.

• DIRECT: When data is requested, the data is copied from the LDM cache (tiles in memory) if possible. If any required tiles are not in the LDM cache, LDM will request the data directly from the volume reader without loading any tiles into the LDM cache memory. This could potentially be slower than the previous mode, but uses less I/O and less memory. It allows getting data without loading the whole tile into memory, for example when the requested data is a slice.

• DIRECT_AND_PREFETCH: This mode is a mix of the previous modes. When data is requested, the data is copied from the LDM cache if possible. If any required tiles are not in the LDM cache, LDM will request the data directly from the volume reader to avoid reading complete tiles immediately, but will also schedule the relevant tiles to be loaded into the LDM cache memory asynchronously. This may improve performance overall if the application is likely to load additional data from these tiles.

Note that DIRECT access requires that specific methods are implemented in the data set reader, for example readXSliceInTile (see OIV.LDM.Readers.SoLDMReader and OIV.LDM.Readers.SoVolumeReader). The default LDM reader implements these methods for the standard Open Inventor LDM file format. Custom LDM readers may need to be enhanced.

EXAMPLE

The following example shows how to extract a subvolume from a given volume.

SoVolumeData volData = new SoVolumeData();
volData.fileName.Value = "<path-to-filename>";

int      resolution = 0; // Full resolution data
SbBox3i32 subvolume = new SbBox3i32( 0, 0, 0, 63, 63, 63 );
SoLDMDataAccess access = volData.GetLdmDataAccess();
SoLDMDataAccess.DataInfoBox info = access.GetData( resolution, subvolume );

if (info.ErrorFlag == SoLDMDataAccess.ErrorValues.CORRECT)
{
   // Create and size a buffer to store the data
   SoCpuBufferObject buffer = new SoCpuBufferObject();
   buffer.SetSize((uint)info.BufferSize);

   // Call to get the actual data
   info = access.GetData(resolution, subvolume, buffer);

   // Access the data then unmap the buffer
   SbNativeArray<uint> data = (SbNativeArray<uint>)buffer.Map( SoBufferObject.AccessModes.READ_ONLY );
   uint value = data[0];
   . . .
   buffer.Unmap();
}

Reference