ImFusion::ImFusionImage Class Reference

#include <ImFusion/Base/ImFusionImage.h>

Loading and saving of the ImFusion image format. More...

Inheritance diagram for ImFusion::ImFusionImage:

Detailed Description

Loading and saving of the ImFusion image format.

Classes
class	ImFusionImageHeader
	For image types, the corresponding data block contains the following header. More...

Public Member Functions
	ImFusionImage ()
	Constructor with filename to load or save.
	~ImFusionImage () override
	Deletes all auxiliary storage however not any loaded data.
void	setCompressionOptions (int mode, int passes, int dx, int dy)
	Set options for image compression.
void	setCompressionOptions (ImFusionFile::CompressionMode mode, int passes, int dx, int dy)
Data *	loadInstance (unsigned int type, unsigned int headerSize) override
	Create specialized instance for a given data type or return null if not supported.
unsigned int	saveType (const Data *data) override
	Return type for saving a given data instance or null if not supported.
bool	load (unsigned int type, Data *data, std::istream &file, Progress *p=0) override
	Load specified data type into given class instance from file, return true upon success.
bool	save (Data *data, std::ostream &file, Progress *p=0) override
	Save a data instance to file, return true if successful.
bool	loadFromAsyncFormat (SharedImageSet *is, std::istream &file, Progress *p=0)
	Loads a SharedImageSet that was saved using the async save methods.
void	setCurrentFilePath (const std::string &path)
	Sets the path of the current IMF file being loaded/saved.
const std::string &	currentFilePath () const
	Returns the path of the current IMF file being loaded/saved.
Public Member Functions inherited from ImFusion::ImFusionFilePlugin
virtual	~ImFusionFilePlugin ()=default
	Destructor.
virtual bool	save (Data *data, std::ostream &file, Progress *progress, const ImFusionFile::CompressionSettings &compression)
	Write this plugin's portion of a Data instance to the output stream, with compression settings.
virtual std::unique_ptr< Properties >	customPropertiesToSave (Data *)
	Lets plugin save custom properties as part of the global file metadata.
virtual bool	loadCustomProperties (Data *, Properties *)
	Load custom properties as returned previously by customPropertiesToSave().
virtual void	applyFlipToEnsureConsistency (Data *)
	Is called after the image content had to be flipped to ensure a consistent coordinate system.
virtual bool	beginBlockRead (std::iostream &, unsigned long long)
	Initialize plugin with current file pointer.
virtual bool	endBlockRead ()
	Indicate to plugin that it will lose read access to the file pointer after this call.
virtual void	setBlockType (unsigned int type)
	Set the type of current data block which is being loaded/saved.

Static Public Member Functions
static unsigned int	imageSaveType (const SharedImageSet *is)
	Return the first 9 bits of the save type of a given SharedImageSet.

Protected Member Functions
virtual bool	loadHeader (std::istream &file)
	Load the file header, return true upon success.
virtual unsigned char	saveHeader (std::ostream &file, SharedImageSet *is, ImageCompression *c, int nf)
	Save the file header, return the data format.
bool	loadFrame (std::istream &file, const ImageDescriptor &d, const mat4 &m, const double t, unsigned int blockType, SharedImageSet *is)
	Loads an image data frame, returns true if successful.
ImageDescriptor	loadDescriptor (std::istream &file)
	Load an image descriptor.
void	saveDescriptor (std::ostream &file, const ImageDescriptor &d, int reverseScaling=1)
	Save an image descriptor.
mat4	loadMatrix (std::istream &file)
	Load a transformation matrix.
void	saveMatrix (std::ostream &file, const mat4 &m)
	Save a matrix.
void	saveImage (std::ostream &file, const MemImage *img, unsigned char format) const
	Save a single image given compression format.
template<typename T>
void	loadImage (std::istream &file, TypedImage< T > *img) const
	Template method to load a compressed image.
template<typename T>
void	saveImage (std::ostream &file, const TypedImage< T > *img, unsigned char format) const
	Template method to actually save an image with compression.
Data::Modality	computeModality (unsigned int blockType) const
	Assemble image modality from block type and data format.
std::string	currentFileDirectory () const
	Returns the directory of the ImFusion file currently being loaded/saved.
virtual bool	loadCompressedImageSet (std::istream &file, SharedImageSet *is)
	Decompress and load a shared image set.
virtual bool	saveCompressedImageSet (std::ostream &file, SharedImageSet *is)
	Compress and save a shared image set.

Protected Attributes
Progress *	m_progress
	Optional progress callback interface.
std::vector< ImageDescriptor >	m_desc
	Image descriptors for per frame data.
std::vector< mat4 >	m_matrices
	Matrix transformation for per frame data.
std::vector< double >	m_timestamps
	Timestamp for per frame data.
ImFusionImageHeader *	m_header
	The image format header.
DataList	m_data
	List of all loaded image data.
Protected Attributes inherited from ImFusion::ImFusionFilePlugin
unsigned int	m_blockType = 0
	Keeps the type of currently saving/loading data block.

Options which are handed through to the ImageCompression class
int	m_cMode
	Main compression mode.
int	m_cPasses
	Number of passes for image compression.
int	m_cDiffX
	X range for difference compression.
int	m_cDiffY
	X range for difference compression.

Members for streaming
std::iostream *	m_stream
	file stream
unsigned long long	m_streamWritten
	number of bytes written
unsigned long long	m_streamStartPos
	start offset

Members of async. saving
ImFusionImageHeader	m_asyncHeader
	Header of the current stream (with unknown frame number).
std::streampos	m_asyncPosHeader
	Header position in current stream.
int	m_asyncFrameCounter
	Frame counter (to fix header afterwards).
std::unique_ptr< ImageCompressionCodec >	m_asyncCompressor
	FFMPEP image compression engine.
std::string	m_currentFilePath
	Path of the current IMF file being loaded/saved.
std::string	m_asyncFilePath
	Path to the binary file with the actual images.

Methods for saving a SharedImageSet async
Asynchronous saving allows writing image frames incrementally to a file stream, which is particularly useful for streaming scenarios or when frames arrive over time. The workflow consists of three steps: Call startSaveAsync() to initialize the file format and write the header Call addFrameAsync() for each image frame to be saved Call closeAsync() to finalize the file and optionally write timestamps The file must be finalized with closeAsync() before it can be read. To load a file saved with these methods always use loadFromAsyncFormat() after calling closeAsync(). See also loadFromAsyncFormat() Example usage: std::fstream file("output.bin", std::fstream::out | std::fstream::binary); ImFusionImage imi; imi.setCompressionOptions(0, 0, 0, 0); // Initialize async saving if (!imi.startSaveAsync(imageSet, file)) return false; // Save each frame for (int i = 0; i < imageSet->size(); i++) { auto img = dynamic_cast<TypedImage<unsigned char>*>(imageSet->mem(i)); if (!imi.addFrameAsync(img, file)) return false; } // Finalize and save timestamps if (!imi.closeAsync(imageSet, file, true)) return false; file.close();
bool	startSaveAsync (SharedImageSet *is, std::ostream &file, Progress *p=0)
	Prepares the asynchronous saving of images.
bool	addFrameAsync (const MemImage *memImg, std::ostream &file)
	Saves a single image frame to the file.
bool	closeAsync (SharedImageSet *is, std::ostream &file, bool saveTimestamps=false)
	Finalizes the asynchronous save operation.
bool	closeAsync (std::ostream &file, const std::vector< double > &timestamps)
	Finalizes the asynchronous save operation with explicit timestamps.

Methods for streaming images into file
bool	beginBlockWrite (std::iostream &io) override
	Begin block to be written into file. Returns true if successful, false otherwise.
bool	blockWriteImage (SharedImageSet *is)
	Stream image with header into block. Returns true if successful, false otherwise.
unsigned long long	endBlockWrite () override
	Finish block written into file. Returns number of bytes written to the block.

Member Function Documentation

setCompressionOptions()

void ImFusion::ImFusionImage::setCompressionOptions	(	int	mode,
		int	passes,
		int	dx,
		int	dy )

Set options for image compression.

Deprecated

"Use setCompressionOptions(ImFusionFile::CompressionMode mode, int passes, int dx, int dy) instead."

loadInstance()

Data * ImFusion::ImFusionImage::loadInstance ( unsigned int type, unsigned int headerSize )

overridevirtual

Create specialized instance for a given data type or return null if not supported.

Implements ImFusion::ImFusionFilePlugin.

saveType()

unsigned int ImFusion::ImFusionImage::saveType ( const Data * data )

overridevirtual

Return type for saving a given data instance or null if not supported.

Implements ImFusion::ImFusionFilePlugin.

load()

bool ImFusion::ImFusionImage::load ( unsigned int type, Data * data, std::istream & file, Progress * p = 0 )

overridevirtual

Load specified data type into given class instance from file, return true upon success.

Reimplemented from ImFusion::ImFusionFilePlugin.

save()

bool ImFusion::ImFusionImage::save ( Data * data, std::ostream & file, Progress * p = 0 )

overridevirtual

Save a data instance to file, return true if successful.

Reimplemented from ImFusion::ImFusionFilePlugin.

startSaveAsync()

bool ImFusion::ImFusionImage::startSaveAsync	(	SharedImageSet *	is,
		std::ostream &	file,
		Progress *	p = 0 )

Prepares the asynchronous saving of images.

Initializes the file format and writes the header. The provided SharedImageSet must already contain at least one image to ensure correct metadata extraction. This method does not save any image data, it only uses metadata of the provided SharedImageSet; call addFrameAsync() for each frame to be saved.

Parameters

is	SharedImageSet containing at least one image for metadata extraction
file	Output stream to write to
p	Optional progress callback interface

Returns

true if successful, false otherwise

addFrameAsync()

bool ImFusion::ImFusionImage::addFrameAsync	(	const MemImage *	memImg,
		std::ostream &	file )

Saves a single image frame to the file.

Must be called after startSaveAsync() and before closeAsync(). This method is blocking and writes the frame data immediately to the stream. Call this method once for each frame in the sequence.

Parameters

memImg	Pointer to the image frame to save (must be unsigned char type)
file	Output stream to write to (must be the same as passed to startSaveAsync beforehand)

Returns

true if successful, false otherwise

closeAsync() [1/2]

bool ImFusion::ImFusionImage::closeAsync	(	SharedImageSet *	is,
		std::ostream &	file,
		bool	saveTimestamps = false )

Finalizes the asynchronous save operation.

Must be called after all frames have been written with addFrameAsync(). This method updates the file header with the correct frame count and optionally appends timestamps. Without calling this method, the saved file will not be readable.

Parameters

is	SharedImageSet to extract timestamps from (can be nullptr if saveTimestamps is false)
file	Output stream to write to (must be the same as passed to startSaveAsync/addFrameAsync beforehand)
saveTimestamps	If true, timestamps from the SharedImageSet are appended to the file

Returns

true if successful, false otherwise

closeAsync() [2/2]

bool ImFusion::ImFusionImage::closeAsync	(	std::ostream &	file,
		const std::vector< double > &	timestamps )

Finalizes the asynchronous save operation with explicit timestamps.

Same as the other closeAsync() overload but accepts timestamps as a vector instead of extracting them from a SharedImageSet. This is particularly useful when the async-saving should be disentangled from the lifetime of the SharedImageSet container, allowing the container to be destroyed before finalization.

Parameters

file	Output file stream to write to
timestamps	Vector of timestamps to append (one per frame). If empty, no timestamps are saved.

Returns

true if successful, false otherwise

See also

closeAsync(SharedImageSet*, std::ostream&, bool)

loadFromAsyncFormat()

bool ImFusion::ImFusionImage::loadFromAsyncFormat	(	SharedImageSet *	is,
		std::istream &	file,
		Progress *	p = 0 )

Loads a SharedImageSet that was saved using the async save methods.

Reads a file that was created with startSaveAsync(), addFrameAsync(), and closeAsync(). Internally calls load() to read the image data, and then reads any timestamps that were appended at the end of the file.

Parameters

is	SharedImageSet to load the data into
file	Input file stream to read from
p	Optional progress callback interface

Returns

true if successful, false otherwise

See also

startSaveAsync(), addFrameAsync(), closeAsync()

beginBlockWrite()

bool ImFusion::ImFusionImage::beginBlockWrite ( std::iostream & io )

overridevirtual

Begin block to be written into file. Returns true if successful, false otherwise.

Reimplemented from ImFusion::ImFusionFilePlugin.

endBlockWrite()

unsigned long long ImFusion::ImFusionImage::endBlockWrite ( )

overridevirtual

Finish block written into file. Returns number of bytes written to the block.

Reimplemented from ImFusion::ImFusionFilePlugin.

---

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

• ImFusion/Base/ImFusionImage.h