Class SoLDMWriter
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.ldm.converters.SoLDMWriter
-
public class SoLDMWriter extends Inventor
Write data to disk in LDM format.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.SoLDMWriter
incorporates an instance of the LDM converter (seeSoConverter
) which can automatically generate the lower resolution (subsampled) tiles after the full resolution data has been stored (for example when thefinish()
method is called). However thewriteTile()
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.
SoLDMWriter
supports the converter's partial conversion feature. If some tiles are missing when thefinish
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 theSoLDMReader
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
SoConverter.ConverterError
. Success is indicated by the value CVT_NO_ERROR.The first step is to create an
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 theinitialize()
method:- One takes a reference to an existing data set (
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
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
SbFileHelper
) and deleting it if necessary.The next step is to write data into the LDM file using the
writeSubVolume()
orwriteTile()
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 thefinish
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
finish
method. This will optionally generate the lower resolution tiles, cleanup and close the LDM file.EXAMPLE // Initialize the LDM writer 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 == SoConverter.ConverterErrors.CVT_NO_ERROR.getValue() ) { 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] ); // Tile size is 64 // 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:
SoVolumeConverter
- One takes a reference to an existing data set (
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
-
Field Summary
-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor Description SoLDMWriter()
Constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description int
finish()
Calls finish(true).int
finish(boolean doMultiResolution)
Finishes writing the LDM file and optionally invokes the converter to generate the lower resolution tiles.int
initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType)
Deprecated.int
initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, int argc)
Deprecated.int
initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, int argc, java.lang.String[] argv)
Deprecated.As of Open Inventor 9000.int
initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, SoConverterParameters parameters)
Initializes the writer to build a volume filename with the specified dimensions, size and data type.int
initialize(java.lang.String filename, SoDataSet inputVolData)
Deprecated.int
initialize(java.lang.String filename, SoDataSet inputVolData, int argc)
Deprecated.int
initialize(java.lang.String filename, SoDataSet inputVolData, int argc, java.lang.String[] argv)
Deprecated.As of Open Inventor 9000.int
initialize(java.lang.String filename, SoDataSet inputVolData, SoConverterParameters parameters)
Initializes the writer to build a volume with the same dimensions, size and data type as inputVolData .int
writeSubVolume(SbBox3i32 subVolume, SoBufferObject data)
Calls writeSubVolume(subVolume, data, true, true).int
writeSubVolume(SbBox3i32 subVolume, SoBufferObject data, boolean doLowerResolution)
Calls writeSubVolume(subVolume, data, doLowerResolution, true).int
writeSubVolume(SbBox3i32 subVolume, SoBufferObject data, boolean doLowerResolution, boolean doOverlappingTiles)
Writes the data contained in the specified subVolume into the LDM file.int
writeTile(SbVec3i32 location, SoBufferObject data)
Calls writeTile(location, data, (int)0).int
writeTile(SbVec3i32 location, SoBufferObject data, int resolution)
Writes the tile which includes location in data coordinates, at the specified resolution level, into the LDM file.int
writeTile(SoLDMTileID tileID, SoBufferObject data)
Writes the specified tile tileID into the LDM file.-
Methods inherited from class com.openinventor.inventor.Inventor
dispose, getNativeResourceHandle
-
-
-
-
Method Detail
-
writeSubVolume
public int writeSubVolume(SbBox3i32 subVolume, SoBufferObject data)
Calls writeSubVolume(subVolume, data, true, true).
-
writeSubVolume
public int writeSubVolume(SbBox3i32 subVolume, SoBufferObject data, boolean doLowerResolution)
Calls writeSubVolume(subVolume, data, doLowerResolution, true).
-
initialize
@Deprecated public int initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType)
Deprecated.Calls initialize(filename, size, dimension, dataType, (int)0, (java.lang.String[])null).
-
initialize
@Deprecated public int initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, int argc)
Deprecated.Calls initialize(filename, size, dimension, dataType, argc, (java.lang.String[])null).
-
initialize
@Deprecated public int initialize(java.lang.String filename, SoDataSet inputVolData, int argc)
Deprecated.Calls initialize(filename, inputVolData, argc, (java.lang.String[])null).
-
writeTile
public int writeTile(SbVec3i32 location, SoBufferObject data)
Calls writeTile(location, data, (int)0).
-
finish
public int finish()
Calls finish(true).
-
initialize
@Deprecated public int initialize(java.lang.String filename, SoDataSet inputVolData)
Deprecated.Calls initialize(filename, inputVolData, (int)0, (java.lang.String[])null).
-
initialize
@Deprecated public int initialize(java.lang.String filename, SoDataSet inputVolData, int argc, java.lang.String[] argv)
Deprecated.As of Open Inventor 9000. Use equivalent method that take SoConverterParameters as parameter.Initializes the writer to build a volume with the same dimensions, size and data type as inputVolData . Other parameters (e.g. tile size) and converter options (e.g. "-q" to suppress output) can be specified using argc and argv . SeeSoConverter.convert
for a list of command line arguments. Result code is defined by the enumSoConverter.ConverterError
.Warning Deprecated since Open Inventor 9000. Use equivalent method that take
SoConverterParameters
as parameter.
-
finish
public int finish(boolean doMultiResolution)
Finishes writing the LDM file and optionally invokes the converter to generate the lower resolution tiles. Default is to invoke the converter. Result code is defined by the enumSoConverter.ConverterError
.
-
writeSubVolume
public int writeSubVolume(SbBox3i32 subVolume, SoBufferObject data, boolean doLowerResolution, boolean doOverlappingTiles)
Writes the data contained in the specified subVolume into the LDM file.
All tiles that are completely inside the subvolume are written into the file overwriting any already existing data for those tiles. (Overwritten values are still taken into account for the histogram). All tiles that are partially inside the subvolume are also written into the file. If a partially inside tile already exists in the file(perhaps from a previous call to writeSubVolume), that tile will first be read back from the file, updated with the new voxel values, then re-written into the file.If doLowerResolution is true (default), builds the lower resolution tiles immediately, if possible. The converter needs 8 neighbors tiles of max resolution to build one of resolution max-1 low resolution. So if the given subVolume does not contain those 8 neighbors, the low resolution tile cannot be built during this call. It's then important to notice that a call to writeSubVolume with doLowerResolution set to true and a call to finish(false) can potentially result in missing low resolution tile in the generated LDM file. Otherwise, this can be significantly faster than building them in the
finish()
method, because the full resolution data is already in memory. If doLowerResolution is false, the lower resolution tiles are not generated during this call, but can still be generated later if thefinish()
method is called with doMultiResolution set to true.doOverlappingTiles is no longer used and ignored since Open Inventor 9.0
Returns a result code defined by the enum
SoConverter.ConverterError
(zero if successful).
-
writeTile
public int writeTile(SoLDMTileID tileID, SoBufferObject data)
Writes the specified tile tileID into the LDM file.
-
writeTile
public int writeTile(SbVec3i32 location, SoBufferObject data, int resolution)
Writes the tile which includes location in data coordinates, at the specified resolution level, into the LDM file. Result code is defined by the enumSoConverter.ConverterError
.
-
initialize
@Deprecated public int initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, int argc, java.lang.String[] argv)
Deprecated.As of Open Inventor 9000. Use equivalent method that take SoConverterParameters as parameter.Initializes the writer to build a volume filename with the specified dimensions, size and data type. Other parameters (e.g. tile size) and converter options (e.g. "-q" to suppress output) can be specified using argc and argv . SeeSoConverter.convert
for a list of command line arguments. Result code is defined by the enumSoConverter.ConverterError
.Warning Deprecated since Open Inventor 9000. Use equivalent method that take
SoConverterParameters
as parameter.
-
initialize
public int initialize(java.lang.String filename, SbBox3f size, SbVec3i32 dimension, SoDataSet.DataTypes dataType, SoConverterParameters parameters)
Initializes the writer to build a volume filename with the specified dimensions, size and data type. Other parameters (e.g. tile size) and converter options can be specified usingSoConverterParameters
. Result code is defined by the enumSoConverter.ConverterError
.
-
initialize
public int initialize(java.lang.String filename, SoDataSet inputVolData, SoConverterParameters parameters)
Initializes the writer to build a volume with the same dimensions, size and data type as inputVolData . Other parameters (e.g. tile size) and converter options can be specified usingSoConverterParameters
. Result code is defined by the enumSoConverter.ConverterError
.
-
-