Click or drag to resize
SoLDMDataAccess Class

Volume data access methods.

Inheritance Hierarchy
SystemObject
  OIV.InventorSoNetBase
    OIV.LDMSoLDMDataAccess

Namespace: OIV.LDM
Assembly: OIV.LDM (in OIV.LDM.dll) Version: 2024.1.0.0 (2024.1.0)
Syntax
public class SoLDMDataAccess : SoNetBase

The SoLDMDataAccess type exposes the following members.

Constructors
  NameDescription
Public methodSoLDMDataAccess

Constructor.

Top
Methods
  NameDescription
Public methodEndRequest

This method is called each time a data request is finished, meaning that the data requested asynchronously is now available.

Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodGetData(Int32, SbBox3i32)
Calls GetData(resolution, subVolume0, (OIV.Inventor.Devices.SoBufferObject ^)nullptr).
Public methodGetData(Int32, SbVec3i32)

Returns a reference to the block of data (LDM tile) which contains the voxel at dataPosition.

Public methodGetData(Int32, SbBox3i32, SoBufferObject)

Given a subvolume in voxel coordinates, copies the associated data into an application buffer.

Public methodGetData(Int32, SbBox3i32, SbNativeArrayByte) Obsolete.

Public methodGetData(Int32, SbBox3i32, SbLine)
Calls GetData(resolution, subVolume0, line, (OIV.Inventor.Devices.SoBufferObject ^)nullptr).
Public methodGetData(Int32, SbBox3i32, SbPlane)
Calls GetData(resolution, subVolume0, plane, (OIV.Inventor.Devices.SoBufferObject ^)nullptr).
Public methodGetData(Int32, SbBox3i32, SbVec2i32)
Calls GetData(resolution, subVolume, coord, (OIV.Inventor.Devices.SoBufferObject ^)nullptr).
Public methodGetData(Int32, SbBox3i32, SbLine, SoBufferObject)

Given a subvolume in voxel coordinates and a line, copies the data intersecting the line and the subvolume into an application buffer.

Public methodGetData(Int32, SbBox3i32, SbLine, SbNativeArrayByte) Obsolete.

Public methodGetData(Int32, SbBox3i32, SbPlane, SoBufferObject)

Given a subvolume in voxel coordinates and a plane, copies the data intersecting the plane and the subvolume into an application buffer.

Public methodGetData(Int32, SbBox3i32, SbPlane, SbNativeArrayByte) Obsolete.

Public methodGetData(Int32, SbBox3i32, SbVec2i32, SoBufferObject)

Data values in a single seismic trace (a row of voxels along the volume X axis) are copied into an application buffer.

Public methodGetData(Int32, SbBox3i32, SbVec2i32, SbNativeArrayByte) Obsolete.

Public methodGetData(SoLDMDataAccessDataInfoPolyLine, Int32, SbBox3i32, SbVec3i32)
Calls GetData(infoPolyline, resolution, subVolume, polyline, (OIV.Inventor.Devices.SoBufferObject ^)nullptr).
Public methodGetData(SoLDMDataAccessDataInfoPolyLine, Int32, SbBox3i32, SbVec3i32, SoBufferObject)

Given a subvolume in voxel coordinates and a polyline (set of connected line segments), copies the data intersecting each line segment with the subvolume into an application buffer.

Public methodGetData(SoLDMDataAccessDataInfoPolyLine, Int32, SbBox3i32, SbVec3i32, SbNativeArrayByte) Obsolete.

Public methodGetDataSet

Returns the associated dataset.

Public methodGetGetDataMode

Returns the GetDataMode (see setGetDataMode).

Public methodGetHashCode
Overrides GetHashCode().
(Inherited from SoNetBase.)
Public methodGetRequestedData(Int32, SoLDMDataAccessDataInfoBox)

Returns the data associated with requestID into infoBox.

Public methodGetRequestedData(Int32, SoLDMDataAccessDataInfoLine)

Returns the data associated with requestID into infoLine.

Public methodGetRequestedData(Int32, SoLDMDataAccessDataInfoPlane)

Returns the data associated with requestID into infoPlane.

Public methodGetRequestedData(Int32, SoLDMDataAccessDataInfoPolyLine)

Returns the data associated with requestID into infoPolyline.

Public methodGetRequestedData(Int32, SoLDMDataAccessDataInfoTrace)

Returns the data associated with requestID into infoTrace .

Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodIsTileUniform

Returns true if the tile containing the data located at position dataPosition (IJK voxel coordinates) at the specified resolution is uniform (all voxels have the same value).

Public methodReleaseData

Tells VolumeViz that this block of data (returned by getData above) is no longer in use by the application.

Public methodRequestData(Int32, SbBox3i32, SoBufferObject)

Given a subvolume in voxel coordinates, asynchronously copies the associated data into an application buffer.

Public methodRequestData(Int32, SbBox3i32, SbNativeArrayByte) Obsolete.

Public methodRequestData(Int32, SbBox3i32, SbLine, SoBufferObject)

Given a subvolume in voxel coordinates and a line, asynchronously copies the data intersecting the line and the subvolume into an application buffer.

Public methodRequestData(Int32, SbBox3i32, SbLine, SbNativeArrayByte) Obsolete.

Public methodRequestData(Int32, SbBox3i32, SbPlane, SoBufferObject)

Given a subvolume in voxel coordinates and a plane, asynchronously copies the data intersecting the plane and the subvolume into an application buffer.

Public methodRequestData(Int32, SbBox3i32, SbPlane, SbNativeArrayByte) Obsolete.

Public methodRequestData(Int32, SbBox3i32, SbVec2i32, SoBufferObject)

Data values in a single seismic trace (a row of voxels along the volume X axis) are asynchronously copied into an application buffer.

Public methodRequestData(Int32, SbBox3i32, SbVec2i32, SbNativeArrayByte) Obsolete.

Public methodRequestData(Int32, SbBox3i32, SbVec3i32, SoBufferObject)

Given a subvolume in voxel coordinates and a stack of line, asynchronously copies the data intersecting each line and the subvolume into an application buffer.

Public methodRequestData(Int32, SbBox3i32, SbVec3i32, SbNativeArrayByte) Obsolete.

Public methodSetDataSet

Set dataset to fetch data from.

Public methodSetGetDataMode

Set the GetDataMode.

Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodVoxelToXYZ(SbBox3i32)

Converts the specified box in voxel coordinates (I,J,K) to geometric coordinates (X,Y,Z).

Public methodVoxelToXYZ(SbVec3i32)

Converts a voxel coordinate (I,J,K) to a geometry coordinate (X,Y,Z).

Public methodXYZToVoxel(SbBox3f)

Converts the specified box in geometric coordinates (X,Y,Z) to voxel coordinates (I,J,K).

Public methodXYZToVoxel(SbVec3f)

Converts a geometry coordinate (X,Y,Z) to a voxel coordinate (I,J,K).

Top
Remarks

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();
}

See Also