SoConverter Class Reference
[Converters]

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

#include <LDM/converters/SoConverter.h>

Inheritance diagram for SoConverter:

Classes
struct	Stat
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 }
Public Member Functions
virtual	~SoConverter ()
int	convert (SoConverterParameters *parameters=NULL)
void	setXmlCallback (void(xmlCB)(FILE , void userData), void userData)
Protected Types
enum	Abort { CVT_CONTINUE, CVT_ABORT }
enum	SampleType { DECIMATION, AVERAGE }
Protected Member Functions
	SoConverter ()
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 SoVolumeHistogram *	getHistogram ()
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
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, int 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)
ConverterError	buildHeader (const SbString &, bool conversionDone=false)
virtual void	outputDataType (FILE *fout)
void	inputTile (int fileTileIndex, int dataSize, void *data, bool i=false)
void	printTime ()
int	buildLevelMax ()
void	outputTile (int fileTileIndex, int 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 ()
Protected Attributes
SoVolumeReader *	m_reader
SbBox3f	m_volumeSize
void(*	m_xmlCB )(FILE , void )
void *	m_xmlCBUserData
SoLDMTopoOctree *	m_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
SoDataCompressor *	m_ldmCompressor
int64_t	m_sizeOfTileIndex
char	m_compressionType [256]
SoDataCompressInfo *	m_lastWrittenCompressInfo
bool	m_fromInitializeFiles
SampleType	m_sampleType
int	m_currentWordFormat
SoPerfCounterManager *	m_perfManager
SoConverterParameters *	m_parameters
SbString	m_originalFileName
std::vector< SbVec2d >	m_tileMinMax
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)

Detailed Description

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. jp3d: This is a wavelet compression that can be lossless or lossy. See SoJp3dDataCompressor. Limitation: 32 bit data values (float or integer) are always converted to 16 bit values.
-l level	Level of compression used. See also "-c type". The meaning of this parameter depends on the type of compression used: gzip: Lossless compression. Level must be between 0 and 9: 0 gives no compression, 9 gives best compression but slower speed. Default is 3. jpeg: 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. jp3d: Wavelet compression that can be lossless or lossy. A level of 0 specifies the lossless mode, and any other value sets the target PSNR (Peak Signal to Noise Ratio). Typical values for PSNR are: 70dB for near lossless mode, and 40dB for visually lossless mode.
-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

   int main( int argc, char ** argv)
   {
     SoVolumeRendering::init();

     // Create parameter object from command line args
     SoConverterParameters* pParameters = SoConverterParameters::create(argc,argv);

     // Start converter 
     SoVolumeConverter converter;
     int ret = converter.convert( pParameters );

     delete pParameters;
     SoVolumeRendering::finish();
     return ret;
   }

EXAMPLE

SoConverterParameters

     // Create parameter object with input file and desired options
     SoConverterParameters* parameters = new SoConverterParameters();
     parameters->setInputFileName( "filename.sgy" );
     parameters->setTileDim( 128 );

     // Start converter
     SoVolumeConverter converter;
     int result = converter.convert( parameters );

See the example programs in $OIVHOME/examples/source/VolumeViz/Converters.

Member Enumeration Documentation

enum SoConverter::Abort [protected]

Abort.

Enumerator:

CVT_CONTINUE
CVT_ABORT

enum SoConverter::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.

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.

Constructor & Destructor Documentation

virtual SoConverter::~SoConverter ( ) [virtual]

Destructor.

SoConverter::SoConverter ( ) [protected]

Constructor.

Member Function Documentation

void SoConverter::abortConversion ( ) [protected]

virtual void SoConverter::adjustParameters ( ) [inline, protected, virtual]

ConverterError SoConverter::buildHeader	(	const SbString &	,
		bool	conversionDone = `false`
	)			`[protected]`

int SoConverter::buildLevelMax ( ) [protected]

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

virtual void SoConverter::buildTile	(	SbBox3i32 &	slabBox,
		SbVec3i32 &	slabBufferDim,
		void *	slabBuffer,
		SbVec3i32 &	tileOrigin,
		void *	tileBuffer
	)			`[protected, virtual]`

virtual void SoConverter::closeInputFileHandles ( ) [protected, virtual]

SoDEPRECATED int SoConverter::convert ( const SbStringList & arguments )

Deprecated:: Deprecated since Open Inventor 9000
Use convert( SoConverterParameters* parameters = NULL) instead.

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

Deprecated:: Deprecated since Open Inventor 9000
Use convert( SoConverterParameters* parameters = NULL) instead.

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.

virtual void SoConverter::endConversion ( ) [inline, protected, virtual]

virtual std::vector<SoDataSet::DatumElement> SoConverter::getDatum ( int & error ) [protected, pure virtual]

virtual SbVec3i32 SoConverter::getDimension ( int & error ) [protected, pure virtual]

virtual SoVolumeHistogram* SoConverter::getHistogram ( ) [protected, virtual]

int SoConverter::getNumTileToGenerate ( SbBox3i32 & slabBox ) [protected]

SbString SoConverter::getOriginalFilename ( ) const [inline, protected, virtual]

virtual int SoConverter::getRange	(	double &	rangeMin,
		double &	rangeMax
	)			`[protected, pure virtual]`

virtual SbBox3f SoConverter::getSize ( int & error ) [protected, pure virtual]

virtual int SoConverter::getSpecificOffset ( bool aligned = true ) [inline, protected, virtual]

virtual void SoConverter::getSubSlice	(	const SbBox2i32 &	subSlice,
		int	sliceNumber,
		void *	data
	)			`[protected, pure virtual]`

virtual std::vector<SbVec2d>& SoConverter::getTileMinMax ( int numTiles ) [protected, virtual]

virtual void SoConverter::handleCustomTags ( FILE * ) [inline, protected, virtual]

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

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

virtual void SoConverter::outputDataType ( FILE * fout ) [protected, virtual]

virtual void SoConverter::outputHeader ( FILE * ) [inline, protected, virtual]

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

void SoConverter::outputTileBefore	(	int	fileTileIndex,
		int	dataSize,
		void *	data,
		bool	dataInverted
	)			`[inline, protected, virtual]`

void SoConverter::printCompressionInfos ( ) [protected]

void SoConverter::printTime ( ) [protected]

virtual Abort SoConverter::progress	(	int	numTilesGenerated,
		int	numTilesToGenerate
	)			`[protected, virtual]`

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.

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

virtual void SoConverter::sampleTile	(	const SbVec3i32 &	tileDim,
		int	border,
		const void *const	octantTile[8],
		const int	octantExists[8],
		void *	parentTile
	)			`[protected, pure 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.

void SoConverter::setOriginalFileName ( const SbString & originalFileName ) [inline, protected, virtual]