Package com.openinventor.ldm.writers

Class 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

    • Field Detail

      • 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 (128, 128, 128).

      • 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)

      • 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.