com.openinventor.ldm.writers

Class SoVRLdmFileWriter

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.misc.SoBase

com.openinventor.inventor.fields.SoFieldContainer

com.openinventor.ldm.writers.SoVolumeWriter

com.openinventor.ldm.writers.SoVRLdmFileWriter

All Implemented Interfaces:

SafeDisposable

public class SoVRLdmFileWriter
extends SoVolumeWriter

Write data to disk in LDM format. Creates an LDM file (in the VSG .ldm format) and allows the application to store data blocks in any order. The most common usage is to store blocks of full resolution data. This class can automatically generate the lower resolution (subsampled) tiles after the full resolution data has been stored (when the finish() method is called and doMultiResolution is set to true). However the writeTile() 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).

It is not necessary, in all cases, to create the lower resolution tiles or even to create the complete set of full resolution tiles. This class supports partial writing feature. If some tiles are missing when the finish 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 defaultValue). 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 writer 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 first step is to create an SoVRLdmFileWriter object and initialize it with the desired characteristics for the output volume. The initialize methods initialize the writer using its current parameters. It must not be modified once initialized.

The next step is to write data into the LDM file using the writeTile methods.

The final step is to call the finish method. This will optionally generate the lower resolution tiles (see doMultiResolution), cleanup and close the LDM file.

EXAMPLE

 SoVRLdmFileWriter writer = new SoVRLdmFileWriter();
 // set parameters
 writer.headerFilename.setValue( "myFile.ldm" );
 writer.dimension.setValue( 128, 128, 128 );
 writer.extent.setValue( -1,-1,-1, 1,1,1  );
 
 // Initialize
 writer.initialize();
 
 // Write data
 SoLDMTileID tileID = new SoLDMTileID( 0 );
 SoCpuBufferObject tileBuffer = new SoCpuBufferObject();
 writer.writeTile( tileID, tileBuffer );
 
 // Finalize
 writer.finish();

See also:

SoVolumeWriter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoVRLdmFileWriter.CoordinateTypes Coordinate type used by this data set.

Nested classes/interfaces inherited from class com.openinventor.ldm.writers.SoVolumeWriter

SoVolumeWriter.WordFormats

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
SoSFDouble	bitSetThreashold Set the bitset threshold value.
SoSFInt32	compressionLevel Set compression level.
SoSFString	compressionName Compression name.
static int	COORDINATES_RECTILINEAR Deprecated. Use SoVRLdmFileWriter.CoordinateTypes.COORDINATES_RECTILINEAR instead.
static int	COORDINATES_UNIFORM Deprecated. Use SoVRLdmFileWriter.CoordinateTypes.COORDINATES_UNIFORM instead.
SoMFFloat	coordinatesX Rectilinear coordinates along X.
SoMFFloat	coordinatesY Rectilinear coordinates along Y.
SoMFFloat	coordinatesZ Rectilinear coordinates along Z.
SoSFEnum<SoVRLdmFileWriter.CoordinateTypes>	coordinateType .
SoSFBool	crcCheck Set CRC32 check on compression.
SoSFString	dataFilename Data Filename.
SoSFDouble	defaultValue Set the default value.
SoSFBool	doMultiResolution Auto compute sub-resolution tiles when finish writing.
SoSFBool	enableHistogram Specify if the histogram must be computed or not.
SoSFBool	enableTileMinMax Specify if tile min/max should be computed even if enableHistogram is false.
SoSFString	headerFilename Header Filename.
SoSFBool	headerOnly Generate only header file.
SoSFVec2d	inputDataRange Range of input datas ((min, max) of data).
SoSFBool	isRGBA true if RGBA mode (output will be unsigned int32 RGBA values).
SoSFInt32	lowResAlgorithm Specifies the algorithm used to build low resolution tiles.
SoSFString	originalFilename Filename of original file.
SoSFBool	saveAsBitSet Save the data as a bitSet (8 values per byte).
SoSFVec3i32	tileDimension Tile dimension.
SoSFDouble	undefinedValue Set the undefined value.
SoSFBool	verbose verbose.

Fields inherited from class com.openinventor.ldm.writers.SoVolumeWriter

dataType, dimension, extent, WF_BIG_ENDIAN, WF_LITTLE_ENDIAN, wordFormat

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoVRLdmFileWriter() Constructor.

Method Summary

Methods inherited from class com.openinventor.ldm.writers.SoVolumeWriter

closeAllHandles, finish, initialize, isDataConverted, restoreAllHandles, writeSubSlice, writeTile

Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer

copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults

Methods inherited from class com.openinventor.inventor.misc.SoBase

dispose, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable, touch

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COORDINATES_UNIFORM

@Deprecated
public static final int COORDINATES_UNIFORM

Deprecated. Use SoVRLdmFileWriter.CoordinateTypes.COORDINATES_UNIFORM instead.

COORDINATES_RECTILINEAR

@Deprecated
public static final int COORDINATES_RECTILINEAR

Deprecated. Use SoVRLdmFileWriter.CoordinateTypes.COORDINATES_RECTILINEAR instead.

headerFilename

public final SoSFString headerFilename

Header Filename.

dataFilename

public final SoSFString dataFilename

Data Filename. By default, take headerFilename and use ".ldm" extension.

originalFilename

public final SoSFString originalFilename

Filename of original file. Empty by default. Needed if you want to keep an "history" of file.

tileDimension

public final SoSFVec3i32 tileDimension

Tile dimension. Default is (64, 64, 64).

doMultiResolution

public final SoSFBool doMultiResolution

Auto compute sub-resolution tiles when finish writing. Default is true.

lowResAlgorithm

public final SoSFInt32 lowResAlgorithm

Specifies the algorithm used to build low resolution tiles. Available options are :

• 0 to use decimation algorithm (one voxel out of two).
• n to use weighted average algorithm : voxels of tile of resolution N+1 are built from the average of the 6 neighbors from resolution N and the current voxel value weighted by n. by default the decimation algorithm is used (n=0).

saveAsBitSet

public final SoSFBool saveAsBitSet

Save the data as a bitSet (8 values per byte). You should specified the bitSetThreashold if you use this feature. Default is false.

bitSetThreashold

public final SoSFDouble bitSetThreashold

Set the bitset threshold value. For each value (V) of a dataset, if V > threshold the bitset is set to 1 for this bit, or to 0 otherwise. Default is 0. Used only if saveAsBitSet is true.

isRGBA

public final SoSFBool isRGBA

true if RGBA mode (output will be unsigned int32 RGBA values). Default is false.

enableHistogram

public final SoSFBool enableHistogram

Specify if the histogram must be computed or not. Default is true.

Disabling histogram generation will greatly speedup the writing process, but some VolumeViz rendering features and optimizations won't be available.

Enabling the histogram enables computation of:

• dataset min and max values
• per Tile min max values

Note also that if RGBA mode is set then no histogram is computed.

enableTileMinMax

public final SoSFBool enableTileMinMax

Specify if tile min/max should be computed even if enableHistogram is false. Note that when enableHistogram to true, tile min/max is always computed. Default is false.

undefinedValue

public final SoSFDouble undefinedValue

Set the undefined value.
The given value will be stored in the LDM file. Default is NaN (Not a Number). This is currently used by SoHeightFieldRender (vertices with undefined values are not rendered).

defaultValue

public final SoSFDouble defaultValue

Set the default value. The given value will be stored in the LDM file. Default is 0. If tiles are missing, LDM will use this value to display missing tiles.

compressionName

public final SoSFString compressionName

Compression name. The following compression types are currently supported: "gzip" and "jpeg". Jpeg is a lossy compression format and should not be used if data degradation is unacceptable. You can set the compressionLevel field to adjust compression quality. If empty, no compression will be used. Default is empty.

compressionLevel

public final SoSFInt32 compressionLevel

Set compression level. The meaning of this parameter depends on the type of compression used (see compressionName): -For gzip, it must be between 0 and 9: 0 gives no compression, 9 gives best compression but slower speed. Default is 3. -For jpeg, it must be between 0 and 100: 0 gives best compression but most loss of data, 100 gives minimum compression and minimum data alteration. Default is 85.

-1 use default value of specified compressor (3 for gzip, 85 for jpeg). Default is -1.

headerOnly

public final SoSFBool headerOnly

Generate only header file. Default is false.

verbose

public final SoSFBool verbose

verbose. Default is true.

crcCheck

public final SoSFBool crcCheck

Set CRC32 check on compression. When compression is enabled using (see compressionName), adds a data integrity check value to all compressed tiles. If the environment variable LDM_COMPRESS_CHECK_CRC32 is set, data values will be checked each time they are read from disk. Default is false.

inputDataRange

public final SoSFVec2d inputDataRange

Range of input datas ((min, max) of data). If not specified, range has to be computed, which will increase writing time. Default is an invalid range (1, -1)

coordinateType

public final SoSFEnum<SoVRLdmFileWriter.CoordinateTypes> coordinateType

. Default is COORDINATES_UNIFORM.

coordinatesX

public final SoMFFloat coordinatesX

Rectilinear coordinates along X. Used only if coordinateType is COORDINATES_RECTILINEAR.

coordinatesY

public final SoMFFloat coordinatesY

Rectilinear coordinates along Y. Used only if coordinateType is COORDINATES_RECTILINEAR.

coordinatesZ

public final SoMFFloat coordinatesZ

Rectilinear coordinates along Z. Used only if coordinateType is COORDINATES_RECTILINEAR.

Constructor Detail

SoVRLdmFileWriter

public SoVRLdmFileWriter()

Constructor.