Open Inventor Release 2023.2.3
 
Loading...
Searching...
No Matches
SoConverter Class Referenceabstract

Large Data Management Abstract base class for converting data sets into LDM format. More...

#include <LDM/converters/SoConverter.h>

+ Inheritance diagram for SoConverter:

Public Types

enum  ConverterError {
  CVT_FINISHED_WITH_WARNINGS = 1 ,
  CVT_NO_ERROR = 0 ,
  CVT_INPUT_PARAMS_PROBLEM = -1 ,
  CVT_FILE_EXT_UNKNOWN = -2 ,
  CVT_CANT_OPEN_INPUT_FILE = -3 ,
  CVT_CANT_CREATE_DATA_FILE = -4 ,
  CVT_CANT_CREATE_HEADER_FILE = -5 ,
  CVT_NOT_ENOUGH_DISK_SPACE = -6 ,
  CVT_CANT_READ_INPUT_FILE = -7 ,
  CVT_ABORTED = -9 ,
  CVT_NOT_INITIALIZED = -10 ,
  CVT_NO_NODE = -998 ,
  CVT_NO_LDM_LICENSE = -999
}
 Converter errors. More...
 

Public Member Functions

virtual ~SoConverter ()
 Destructor.
 
int convert (SoConverterParameters *parameters=NULL)
 Main converter function.
 
void setXmlCallback (void(*xmlCB)(FILE *, void *userData), void *userData)
 Specifies the callback that will be called when the LDM file header is generated.
 

Protected Types

enum  Abort {
  CVT_CONTINUE ,
  CVT_ABORT
}
 Abort. More...
 
enum  SampleType {
  DECIMATION ,
  AVERAGE
}
 Define available algorithm available for downsampling process. More...
 

Protected Member Functions

 SoConverter ()
 Constructor.
 
virtual void getSubSlice (const SbBox2i32 &subSlice, int sliceNumber, void *data)=0
 
virtual SbBox3f getSize (int &error)=0
 
virtual std::vector< SoDataSet::DatumElement > getDatum (int &error)=0
 
virtual SbVec3i32 getDimension (int &error)=0
 
virtual int getRange (double &rangeMin, double &rangeMax)=0
 
virtual SoVolumeHistogramgetHistogram ()
 
virtual std::vector< SbVec2d > & getTileMinMax (int numTiles)
 
virtual void closeInputFileHandles ()
 
virtual void sampleTile (const SbVec3i32 &tileDim, int border, const void *const octantTile[8], const int octantExists[8], void *parentTile)=0
 Method used to downsample a tile.
 
virtual void buildTile (SbBox3i32 &slabBox, SbVec3i32 &slabBufferDim, void *slabBuffer, SbVec3i32 &tileOrigin, void *tileBuffer)
 
void buildTile (const SbBox3i32 &subVolume, const void *subVolumeBuffer, const SbBox3i32 &tilePos, void *tileData, const SbBox3i32 &intersection)
 
virtual void outputHeader (FILE *)
 
virtual void outputTileBefore (int fileTileIndex, size_t dataSize, void *data, bool dataInverted)
 
virtual void startConversion ()
 
virtual void endConversion ()
 
virtual bool updateDataFile ()
 
virtual int getSpecificOffset (bool aligned=true)
 
virtual SbString getOriginalFilename () const
 
virtual void setOriginalFileName (const SbString &originalFileName)
 
virtual Abort progress (int numTilesGenerated, int numTilesToGenerate)
 This method is called each time a tile of data is generated.
 
ConverterError buildHeader (const SbString &, bool conversionDone=false)
 
virtual void outputDataType (FILE *fout)
 
void inputTile (int fileTileIndex, size_t dataSize, void *data, bool i=false)
 
void printTime ()
 
int buildLevelMax ()
 
void outputTile (int fileTileIndex, size_t dataSize, void *, bool i=false)
 
void printCompressionInfos ()
 
int getNumTileToGenerate (SbBox3i32 &slabBox)
 
void writeTileComplete (int fileID, bool writeHeader=false)
 
void abortConversion ()
 
void readSlab (SbBox3i32 &slabBox, char *&slabBufferPtr, int64_t subSliceSize)
 
virtual void adjustParameters ()
 
virtual void handleCustomTags (FILE *)
 
bool isFastUpdate ()
 Return TRUE if converter can do a fast update of the LDM file (ie: converting a ldm file with borders to a borderless one)
 

Protected Attributes

SoVolumeReaderm_reader
 
SbBox3f m_volumeSize
 
void(* m_xmlCB )(FILE *, void *)
 
void * m_xmlCBUserData
 
SoLDMTopoOctreem_LDMTopo
 
int64_t m_filesize
 
int64_t m_compressedFilesize
 
SbString m_fileCompletion
 
SbString m_fileCompletionName
 
SbString m_fileExt
 
int m_pid
 
int m_levelMax
 
bool m_thinDataSet
 
SbVec3i32 m_volumeDimension
 
int m_numTilesToGenerate
 
bool m_abort
 
SiBitFile * m_bitFile
 
SoDataCompressorm_ldmCompressor
 
int64_t m_sizeOfTileIndex
 
char m_compressionType [256]
 
SoDataCompressInfo * m_lastWrittenCompressInfo
 
bool m_fromInitializeFiles
 
SampleType m_sampleType
 
int m_currentWordFormat
 
SoPerfCounterManagerm_perfManager
 
SoConverterParametersm_parameters
 
SbString m_originalFileName
 
std::vector< SbVec2dm_tileMinMax
 One minMax for each file ids.
 
SoConverter::ConverterError m_statusAdjustParameters
 

Static Protected Attributes

static const char * m_dataTypeStr []
 
static const char * m_dataTypeXml []
 

Deprecated

SoDEPRECATED int convert (int argc, char **argv)
 
SoDEPRECATED int convert (const SbStringList &arguments)
 
virtual SoDEPRECATED void outputTileBefore (int fileTileIndex, int dataSize, void *data, bool dataInverted)
 

Detailed Description

Large Data Management Abstract base class for converting data sets into LDM format.

This is the abstract base class for classes that convert existing data sets into the LDM (Large Data Management) format.

SoConverter provides powerful features including:

  • Command line parsing for easy creation of stand-alone converter programs.
  • Checkpoint and restart for interrupted conversions.
  • Multiple subsampling algorithms for creating low resolution tiles.
  • Automatic loading of any supported data format (see SoVolumeData).
  • Conversion of any data format by providing a custom reader (see SoVolumeReader).
  • Special handling to minimize disk space for "thin volumes" where one dimension is smaller than the tile size. (Currently only implemented for Z dimension.)
  • Optional data compression to reduce disk space.
  • Optional data type conversion, e.g. float to byte.

Information common to all converter classes is included here including command line, incomplete conversion, compression and subsampling. Normally you will use, for example, the derived class SoVolumeConverter to convert volume data. You can also subclass from SoVolumeConverter to use a custom volume reader, provide a custom subsampling method, etc.

Command Line

When used as a command line application the string should have the following form:

inputFilename [-t tiledim] [-o filename] [-O [filename]] [-m memsize] [-h] [-w B|L] [-f u8|u16|u32|s8|s16|s32|f [-r min max]] [-q] [-D] [-P portnum] [-c type] [-l level] [-C] [-s [0..N]] [-u value] [-verticalFlip]

where:

-t tiledim Dimension of tiles. Must be a power of two. Default is 128, meaning 128x128x128.

-b bordersize DEPRECATED Since OIV9.0, this parameter will be ignored.

-o filename Name of created XML header ldm file. Default is inputFilename with extension .ldm.

-O filename Name of the file containing the data. If filename is omitted, the default filename is the same as the output filename specified by the -o option, with extension .dat instead.

-m memsize Maximum size of memory to use in MB. Default is 512 MB.

-h Output the header only.

-w wordfmt Indicates the target machine word format is Big Endian (B) or Little Endian (L). Default is the current machine word format.

-f datafmt Indicates the output data format with * = 8,16,32. u*:unsigned integer, s*:signed integer, f:float. If the output data format is float, the values are mapped to the range [0-1]. Default is the input data format.
-r min max Indicates the input data range to map to the new data format specified by the -f option. If not specified, and input type is float and ouput type is integer, the values are simply cast into the output data type.
-q Quiet mode.

-c type Type of compression used. See also "-l level". By default the following compression types are available:

  • gzip:
    This is a lossless compression and can be used on any type of data. See SoGzipDataCompressor.
  • jpeg:
    This is a lossy compression. See SoJpegDataCompressor.
    Limitation: Can only be used on 8-bit scalar data sets.

-l level Level of compression used. See also "-c type". The meaning of this parameter depends on the type of compression used:

            - gzip: <BR>
              Lossless compression.
              Level must be between 0 and 9: 0 gives no compression, 9 gives best compression but slower speed.
              Default is 3.

            - jpeg: <BR>
              Lossy compression.
              Level 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.

-C Data integrity check. When compression is enabled using -c, 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.
-s 0..n 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. If not specified, by default the decimation algorithm is used (n=0).
-u value Undefined value. The given value will marked as undefined in the LDM file. This is currently used by SoHeightFieldRender (vertices with undefined values are not rendered).

-rgba Specifies that output will be unsigned int32 RGBA values.

-noHistogram Disable histogram computation (conversion will be faster).

-B value Define threshold value to generate a bitset dataset.
Any value in the dataset less than or equal to the threshold will generate a zero bit. Values greater than threshold will generate a one bit.

-verticalFlip Flip the output on Y axis.

The return value may be one of the following:

CVT_FINISHED_WITH_WARNINGS Some warnings occured but task complete
CVT_NO_ERROR No problem, task complete
CVT_INPUT_PARAMS_PROBLEM Input parameters problem: input filename missing, bad parameter value, or invalid option
CVT_FILE_EXT_UNKNOWN Unknown file type (file extension)
CVT_CANT_OPEN_INPUT_FILE Could not open input file (does not exist)
CVT_CANT_CREATE_DATA_FILE Could not create data file
CVT_CANT_CREATE_HEADER_FILE Could not create header file
CVT_NOT_ENOUGH_DISK_SPACE Could not allocate disk space for the data file
CVT_ABORTED Conversion has been aborted by the application, task not complete
CVT_NO_NODE Distributed converter cannot be used as the license does not allow any client node
CVT_NO_LDM_LICENSE No LDM license

Incomplete Conversion

The converter saves the progress of the conversion in case the user wishes to abort or start visualizing the converted data or if the program crashes for any reason. In this case, the LDM files (header and data) are coupled with a completion file (name of the header file with an extension of .fcp). When restarting the converter, if the header file points to a .fcp file (XML tag <completionFilename>), the conversion will restart where it previously ended. When visualizing an incompletely converted file, it is possible to know where data actually exists by turning on the topology outlines (see SoVolumeRendering). Red outlines indicate actual data.

In order to restart an incomplete conversion, the header file must be in synch with the completion file. For this reason when writing the pair of header/completion files, the converter first backs up the pair of files before overwriting them (.ldm and .fcp with .bck extension). If the header file is lost or its size is less than the size of the backed up header file, then you can rename the backed up completion and header files to restart the conversion.

EXAMPLE

EXAMPLE

SEE ALSO

SoConverterParameters, SoVolumeConverter, SoVolumeReader, SoDataCompressor, SoJpegDataCompressor, SoGzipDataCompressor

Definition at line 307 of file SoConverter.h.

Member Enumeration Documentation

◆ Abort

enum SoConverter::Abort
protected

Abort.

Enumerator
CVT_CONTINUE 
CVT_ABORT 

Definition at line 501 of file SoConverter.h.

◆ ConverterError

Converter errors.

Enumerator
CVT_FINISHED_WITH_WARNINGS 

Finished with warnings.

CVT_NO_ERROR 

No error.

CVT_INPUT_PARAMS_PROBLEM 

Input params problems.

CVT_FILE_EXT_UNKNOWN 

Unknown file extension.

CVT_CANT_OPEN_INPUT_FILE 

Unable to open file.

CVT_CANT_CREATE_DATA_FILE 

Unable to create data file.

CVT_CANT_CREATE_HEADER_FILE 

Unable to create header file.

CVT_NOT_ENOUGH_DISK_SPACE 

No enough disk space.

CVT_CANT_READ_INPUT_FILE 

Unable to read input file.

CVT_ABORTED 

Conversion aborted.

CVT_NOT_INITIALIZED 

Uninitialized converter.

CVT_NO_NODE 

No node.

CVT_NO_LDM_LICENSE 

No LDM license.

Definition at line 319 of file SoConverter.h.

◆ SampleType

enum SoConverter::SampleType
protected

Define available algorithm available for downsampling process.

Enumerator
DECIMATION 

Decimation : Only one voxel out of two.

AVERAGE 

Average : Voxel value in parent tile is an average of Neighbor voxel in child tile.

Definition at line 511 of file SoConverter.h.

Constructor & Destructor Documentation

◆ ~SoConverter()

virtual SoConverter::~SoConverter ( )
virtual

Destructor.

◆ SoConverter()

SoConverter::SoConverter ( )
protected

Constructor.

Member Function Documentation

◆ abortConversion()

void SoConverter::abortConversion ( )
protected

◆ adjustParameters()

virtual void SoConverter::adjustParameters ( )
inlineprotectedvirtual

Definition at line 600 of file SoConverter.h.

◆ buildHeader()

ConverterError SoConverter::buildHeader ( const SbString ,
bool  conversionDone = false 
)
protected

◆ buildLevelMax()

int SoConverter::buildLevelMax ( )
protected

◆ buildTile() [1/2]

void SoConverter::buildTile ( const SbBox3i32 subVolume,
const void *  subVolumeBuffer,
const SbBox3i32 tilePos,
void *  tileData,
const SbBox3i32 intersection 
)
protected

◆ buildTile() [2/2]

virtual void SoConverter::buildTile ( SbBox3i32 slabBox,
SbVec3i32 slabBufferDim,
void *  slabBuffer,
SbVec3i32 tileOrigin,
void *  tileBuffer 
)
protectedvirtual

◆ closeInputFileHandles()

virtual void SoConverter::closeInputFileHandles ( )
protectedvirtual

◆ convert() [1/3]

SoDEPRECATED int SoConverter::convert ( const SbStringList arguments)

◆ convert() [2/3]

SoDEPRECATED int SoConverter::convert ( int  argc,
char **  argv 
)

◆ convert() [3/3]

int SoConverter::convert ( SoConverterParameters parameters = NULL)

Main converter function.


Call this method to launch the converter. Conversion parameters may be specified using an instance of SoConverterParameters. Returns 0 if conversion was successful, else returns one of the CVT_ error codes above.

◆ endConversion()

virtual void SoConverter::endConversion ( )
inlineprotectedvirtual

Definition at line 490 of file SoConverter.h.

◆ getDatum()

virtual std::vector< SoDataSet::DatumElement > SoConverter::getDatum ( int &  error)
protectedpure virtual

◆ getDimension()

virtual SbVec3i32 SoConverter::getDimension ( int &  error)
protectedpure virtual

◆ getHistogram()

virtual SoVolumeHistogram * SoConverter::getHistogram ( )
protectedvirtual

◆ getNumTileToGenerate()

int SoConverter::getNumTileToGenerate ( SbBox3i32 slabBox)
protected

◆ getOriginalFilename()

SbString SoConverter::getOriginalFilename ( ) const
inlineprotectedvirtual

Definition at line 646 of file SoConverter.h.

◆ getRange()

virtual int SoConverter::getRange ( double &  rangeMin,
double &  rangeMax 
)
protectedpure virtual

◆ getSize()

virtual SbBox3f SoConverter::getSize ( int &  error)
protectedpure virtual

◆ getSpecificOffset()

virtual int SoConverter::getSpecificOffset ( bool  aligned = true)
inlineprotectedvirtual

Definition at line 493 of file SoConverter.h.

◆ getSubSlice()

virtual void SoConverter::getSubSlice ( const SbBox2i32 subSlice,
int  sliceNumber,
void *  data 
)
protectedpure virtual

◆ getTileMinMax()

virtual std::vector< SbVec2d > & SoConverter::getTileMinMax ( int  numTiles)
protectedvirtual

◆ handleCustomTags()

virtual void SoConverter::handleCustomTags ( FILE *  )
inlineprotectedvirtual

Definition at line 601 of file SoConverter.h.

◆ inputTile()

void SoConverter::inputTile ( int  fileTileIndex,
size_t  dataSize,
void *  data,
bool  i = false 
)
protected

◆ isFastUpdate()

bool SoConverter::isFastUpdate ( )
protected

Return TRUE if converter can do a fast update of the LDM file (ie: converting a ldm file with borders to a borderless one)

◆ outputDataType()

virtual void SoConverter::outputDataType ( FILE *  fout)
protectedvirtual

◆ outputHeader()

virtual void SoConverter::outputHeader ( FILE *  )
inlineprotectedvirtual

Definition at line 474 of file SoConverter.h.

◆ outputTile()

void SoConverter::outputTile ( int  fileTileIndex,
size_t  dataSize,
void *  ,
bool  i = false 
)
protected

◆ outputTileBefore() [1/2]

virtual SoDEPRECATED void SoConverter::outputTileBefore ( int  fileTileIndex,
int  dataSize,
void *  data,
bool  dataInverted 
)
inlineprotectedvirtual

Definition at line 479 of file SoConverter.h.

◆ outputTileBefore() [2/2]

virtual void SoConverter::outputTileBefore ( int  fileTileIndex,
size_t  dataSize,
void *  data,
bool  dataInverted 
)
inlineprotectedvirtual

Definition at line 485 of file SoConverter.h.

◆ printCompressionInfos()

void SoConverter::printCompressionInfos ( )
protected

◆ printTime()

void SoConverter::printTime ( )
protected

◆ progress()

virtual Abort SoConverter::progress ( int  numTilesGenerated,
int  numTilesToGenerate 
)
protectedvirtual

This method is called each time a tile of data is generated.

numTilesGenerated represents the number of tiles already generated and numTilesToGenerate is the total number of tiles to generate. So the quotient of these two numbers represents the progress of the task. If this method returns ABORT, the task is stopped. By default it returns CONTINUE.

◆ readSlab()

void SoConverter::readSlab ( SbBox3i32 slabBox,
char *&  slabBufferPtr,
int64_t  subSliceSize 
)
protected

◆ sampleTile()

virtual void SoConverter::sampleTile ( const SbVec3i32 tileDim,
int  border,
const void *const  octantTile[8],
const int  octantExists[8],
void *  parentTile 
)
protectedpure virtual

Method used to downsample a tile.

The input are the eight higher resolution tiles used to create the one lower resolution tile (parent). By default, the converter simply takes one voxel out of two in the higher resolution tile to create the parent tile. This method can be overriden by a custom converter to use a different approach. Inputs are: tileDim is the size of the tile to create in number of voxels. dataType is the type of the data (the value corresponds to the SoDataSet::DataType enum). border only a border of 0 is supported since Open Inventor 9.0. octantTile are the values of the 8 higher resolution tiles. octantExists let the user know if a given octant is free of data (the data is an asymmetric volume). Output is the parentTile buffer.

◆ setOriginalFileName()

void SoConverter::setOriginalFileName ( const SbString originalFileName)
inlineprotectedvirtual

Definition at line 652 of file SoConverter.h.

◆ setXmlCallback()

void SoConverter::setXmlCallback ( void(*)(FILE *, void *userData)  xmlCB,
void *  userData 
)

Specifies the callback that will be called when the LDM file header is generated.

This allows the application to add custom XML tags. The custom tags can be read back using the method SoVRLdmFileReader::getXmlTag().

◆ startConversion()

virtual void SoConverter::startConversion ( )
inlineprotectedvirtual

Definition at line 489 of file SoConverter.h.

◆ updateDataFile()

virtual bool SoConverter::updateDataFile ( )
inlineprotectedvirtual

Definition at line 492 of file SoConverter.h.

◆ writeTileComplete()

void SoConverter::writeTileComplete ( int  fileID,
bool  writeHeader = false 
)
protected

Member Data Documentation

◆ m_abort

bool SoConverter::m_abort
protected

Definition at line 565 of file SoConverter.h.

◆ m_bitFile

SiBitFile* SoConverter::m_bitFile
protected

Definition at line 567 of file SoConverter.h.

◆ m_compressedFilesize

int64_t SoConverter::m_compressedFilesize
protected

Definition at line 551 of file SoConverter.h.

◆ m_compressionType

char SoConverter::m_compressionType[256]
protected

Definition at line 572 of file SoConverter.h.

◆ m_currentWordFormat

int SoConverter::m_currentWordFormat
protected

Definition at line 593 of file SoConverter.h.

◆ m_dataTypeStr

const char* SoConverter::m_dataTypeStr[]
staticprotected

Definition at line 591 of file SoConverter.h.

◆ m_dataTypeXml

const char* SoConverter::m_dataTypeXml[]
staticprotected

Definition at line 592 of file SoConverter.h.

◆ m_fileCompletion

SbString SoConverter::m_fileCompletion
protected

Definition at line 552 of file SoConverter.h.

◆ m_fileCompletionName

SbString SoConverter::m_fileCompletionName
protected

Definition at line 553 of file SoConverter.h.

◆ m_fileExt

SbString SoConverter::m_fileExt
protected

Definition at line 554 of file SoConverter.h.

◆ m_filesize

int64_t SoConverter::m_filesize
protected

Definition at line 550 of file SoConverter.h.

◆ m_fromInitializeFiles

bool SoConverter::m_fromInitializeFiles
protected

Definition at line 576 of file SoConverter.h.

◆ m_lastWrittenCompressInfo

SoDataCompressInfo* SoConverter::m_lastWrittenCompressInfo
protected

Definition at line 573 of file SoConverter.h.

◆ m_ldmCompressor

SoDataCompressor* SoConverter::m_ldmCompressor
protected

Definition at line 570 of file SoConverter.h.

◆ m_LDMTopo

SoLDMTopoOctree* SoConverter::m_LDMTopo
protected

Definition at line 547 of file SoConverter.h.

◆ m_levelMax

int SoConverter::m_levelMax
protected

Definition at line 558 of file SoConverter.h.

◆ m_numTilesToGenerate

int SoConverter::m_numTilesToGenerate
protected

Definition at line 564 of file SoConverter.h.

◆ m_originalFileName

SbString SoConverter::m_originalFileName
protected

Definition at line 598 of file SoConverter.h.

◆ m_parameters

SoConverterParameters* SoConverter::m_parameters
protected

Definition at line 597 of file SoConverter.h.

◆ m_perfManager

SoPerfCounterManager* SoConverter::m_perfManager
protected

Definition at line 596 of file SoConverter.h.

◆ m_pid

int SoConverter::m_pid
protected

Definition at line 557 of file SoConverter.h.

◆ m_reader

SoVolumeReader* SoConverter::m_reader
protected

Definition at line 441 of file SoConverter.h.

◆ m_sampleType

SampleType SoConverter::m_sampleType
protected

Definition at line 587 of file SoConverter.h.

◆ m_sizeOfTileIndex

int64_t SoConverter::m_sizeOfTileIndex
protected

Definition at line 571 of file SoConverter.h.

◆ m_statusAdjustParameters

SoConverter::ConverterError SoConverter::m_statusAdjustParameters
protected

Definition at line 612 of file SoConverter.h.

◆ m_thinDataSet

bool SoConverter::m_thinDataSet
protected

Definition at line 559 of file SoConverter.h.

◆ m_tileMinMax

std::vector<SbVec2d> SoConverter::m_tileMinMax
protected

One minMax for each file ids.

Definition at line 604 of file SoConverter.h.

◆ m_volumeDimension

SbVec3i32 SoConverter::m_volumeDimension
protected

Definition at line 560 of file SoConverter.h.

◆ m_volumeSize

SbBox3f SoConverter::m_volumeSize
protected

Definition at line 536 of file SoConverter.h.

◆ m_xmlCB

void(* SoConverter::m_xmlCB) (FILE *, void *)
protected

Definition at line 545 of file SoConverter.h.

◆ m_xmlCBUserData

void* SoConverter::m_xmlCBUserData
protected

Definition at line 546 of file SoConverter.h.


The documentation for this class was generated from the following file: