Click or drag to resize
SoLDMWriter Class

Write data to disk in LDM format.

Inheritance Hierarchy
SystemObject
  OIV.InventorSoNetBase
    OIV.LDM.ConvertersSoLDMWriter

Namespace: OIV.LDM.Converters
Assembly: OIV.LDM (in OIV.LDM.dll) Version: 10.12.3.0 (10.12.3.0)
Syntax
public class SoLDMWriter : SoNetBase

The SoLDMWriter type exposes the following members.

Constructors
  NameDescription
Public methodSoLDMWriter

Constructor.

Top
Methods
  NameDescription
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodFinish
Calls Finish(true).
Public methodFinish(Boolean)

Finishes writing the LDM file and optionally invokes the converter to generate the lower resolution tiles.

Public methodGetHashCode
Overrides GetHashCode().
(Inherited from SoNetBase.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodInitialize(String, SoDataSet) Obsolete.
Calls Initialize(filename, inputVolData, System.Int32(0), (cli.array<System.String^>^)nullptr).
Public methodInitialize(String, SoDataSet, SoConverterParameters)

Initializes the writer to build a volume with the same dimensions, size and data type as inputVolData .

Public methodInitialize(String, SoDataSet, Int32) Obsolete.
Calls Initialize(filename, inputVolData, argc, (cli.array<System.String^>^)nullptr).
Public methodInitialize(String, SbBox3f, SbVec3i32, SoDataSetDataTypes) Obsolete.
Calls Initialize(filename, size, dimension, dataType, System.Int32(0), (cli.array<System.String^>^)nullptr).
Public methodInitialize(String, SoDataSet, Int32, String) Obsolete.
Public methodInitialize(String, SbBox3f, SbVec3i32, SoDataSetDataTypes, SoConverterParameters)

Initializes the writer to build a volume filename with the specified dimensions, size and data type.

Public methodInitialize(String, SbBox3f, SbVec3i32, SoDataSetDataTypes, Int32) Obsolete.
Calls Initialize(filename, size, dimension, dataType, argc, (cli.array<System.String^>^)nullptr).
Public methodInitialize(String, SbBox3f, SbVec3i32, SoDataSetDataTypes, Int32, String) Obsolete.

Initializes the writer to build a volume filename with the specified dimensions, size and data type.

Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodWriteSubVolume(SbBox3i32, SoBufferObject)
Calls WriteSubVolume(subVolume, data, true, true).
Public methodWriteSubVolume(SbBox3i32, SoBufferObject, Boolean)
Calls WriteSubVolume(subVolume, data, doLowerResolution, true).
Public methodWriteSubVolume(SbBox3i32, SoBufferObject, Boolean, Boolean)

Writes the data contained in the specified subVolume into the LDM file.

Public methodWriteTile(SbVec3i32, SoBufferObject)
Calls WriteTile(location, data, System.Int32(0)).
Public methodWriteTile(SoLDMTileID, SoBufferObject)

Writes the specified tile tileID into the LDM file.

Public methodWriteTile(SbVec3i32, SoBufferObject, Int32)

Writes the tile which includes location in data coordinates, at the specified resolution level, into the LDM file.

Top
Remarks

OIV.LDM.Converters.SoLDMWriter creates an LDM file (in the VSG .ldm format) and allows the application to store data blocks in any order. The data blocks may be specific tiles or arbitrary regions of the volume. The most common usage is to store blocks of full resolution data. OIV.LDM.Converters.SoLDMWriter incorporates an instance of the LDM converter (see OIV.LDM.Converters.SoConverter) which can automatically generate the lower resolution (subsampled) tiles after the full resolution data has been stored (for example when the OIV.LDM.Converters.SoLDMWriter.Finish(System.Boolean) method is called). However the OIV.LDM.Converters.SoLDMWriter.WriteTile(OIV.Inventor.SbVec3i32, OIV.Inventor.Devices.SoBufferObject, System.Int32) method also allows the application to directly store lower resolution tiles in case a proprietary subsampling algorithm is being used. The result will normally be a .ldm file (LDM header) and a .dat file (data).

Because the LDA format used by Amira and Avizo is an LDM format, it's possible to generate a LDA file if this extension is required for the generated file. If the output filename has a ".lda" extension, the LDMWriter will keep this extension.

It is not necessary, in all cases, to create the lower resolution tiles or even to create the complete set of full resolution tiles. OIV.LDM.Converters.SoLDMWriter supports the converter's partial conversion feature. If some tiles are missing when the OIV.LDM.Converters.SoLDMWriter.Finish(System.Boolean) method is called, then in addition to the header and data files there will also be a .fcp file with the same name as the header and data files. The LDM header file will contain a reference to this file in the CompletionFilename tag. The .fcp file stores information about which tiles actually exist. Tiles that do not exist are considered to be filled with a constant default value (see getHoleData() in the OIV.LDM.Readers.SoLDMReader class). This feature allows us, for example, to compute and visualize a subset of the volume before committing to computation on the whole volume. However note that the converter currently pre-allocates disk space for the ".dat" file assuming that all tiles will exist. So skipping creation of the subsampled tiles or writing only a subset of the tiles can reduce computation time and disk I/O time, but it does not reduce the disk space requirement for the volume.

The output volume is not required to have the same characteristics as the input volume. This allows for example, to extract a subset of a volume as a new (smaller) volume. All the options of the LDM converter are available. So the LDM writer can even create a volume with a different data type.

The return value from most methods is the enum OIV.LDM.Converters.SoConverter.ConverterErrors. Success is indicated by the value CVT_NO_ERROR.

The first step is to create an OIV.LDM.Converters.SoLDMWriter object and initialize it with the name of the output file to be created and the desired characteristics for the output volume. There are two versions of the OIV.LDM.Converters.SoLDMWriter.Initialize(System.String, OIV.LDM.Nodes.SoDataSet, OIV.LDM.Converters.SoConverterParameters) method:

  • One takes a reference to an existing data set (OIV.VolumeViz.Nodes.SoVolumeData) and creates a new volume with the same characteristics. This is useful, for example, when creating a derived volume such as seismic attributes.

  • The other takes explicit parameters for the volume dimensions, extent and data type.

Using either version it will often be necessary to specify other parameters and options to the converter using an OIV.LDM.Converters.SoConverterParameters object. Some useful and commonly used options are the tile dimensions and data compression.

If the specified output file ('filename' parameter) does not exist, the class will create it.

NOTE: If the file already exists (and is in LDM format), the class will attempt to modify the existing file. This can be useful, but can also be an unexpected result. If the goal is to create a new file, we recommend checking if the file already exists (see OIV.Inventor.Helpers.SbFileHelper) and deleting it if necessary.

The next step is to write data into the LDM file using the #WriteSubVolume() or #WriteTile()methods. Writing a subvolume is the most powerful and convenient method because it accepts an arbitrary subvolume (writing partial tiles if necessary). If your subvolume is an integral number of tiles and aligned on tile boundaries, then writing tiles will be more efficient for writing the full resolution tiles. The subvolume method also has an option to immediately generate the corresponding lower resolution tiles. If the subvolume contains "blocks" of 8 tiles that can be combined into lower resolution tile, this method provides much better performance than the OIV.LDM.Converters.SoLDMWriter.Finish(System.Boolean) method, because the full resolution data is already in memory. The following example writes eight 64x64x64 tiles into an LDM file of a volume with 128*128*128 dimension.

The final step is to call the OIV.LDM.Converters.SoLDMWriter.Finish(System.Boolean) method. This will optionally generate the lower resolution tiles, cleanup and close the LDM file.

EXAMPLE

SbBox3f   extent     = new SbBox3f( 0,0,0, 1,1,1 );
SbVec3i32 dimensions = new SbVec3i32( 128, 128, 128 );
SbVec3i32 tileSize   = new SbVec3i32( 64, 64, 64 );

SoDataSet.DataTypes type = SoDataSet.DataTypes.UNSIGNED_BYTE;
SoConverterParameters parameters = new SoConverterParameters();

SoLDMWriter myLDMWriter = new SoLDMWriter();
int rc = myLDMWriter.Initialize( "myldmfile.ldm", extent, dimensions, type, parameters );

if ( rc == (int) SoConverter.ConverterErrors.CVT_NO_ERROR )
{
 for ( int x = 0; x*tileSize[0] < dimensions[0]; ++x )
 {
   for ( int y = 0; y*tileSize[1] < dimensions[1]; ++y )
   {
     for ( int z = 0; z*tileSize[2] < dimensions[2]; ++z )
     {
       // Create buffer for tile data
       SoCpuBufferObject buffer = new SoCpuBufferObject();
       buffer.SetSize( tileSize[0] * tileSize[1] * tileSize[2] );

       // Compute data and write tile
       computeData( buffer );
       SbVec3i32 tilePosition( x, y, z );
       rc = myLDMWriter.WriteTile( tilePosition, buffer );
     }
   }
 }

 // Complete file creation
 rc = myLDMWriter.Finish();
}

See Also