#include <ImFusion/Base/ImFusionFile.h>

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

Inheritance diagram for ImFusion::ImFusionFile:

Detailed Description

Loading and saving of the ImFusion file format.

See also: ImFusionFileIoAlgorithm

Classes
struct	CompressionSettings
	Compression settings for nested ImFusionFile save operations. More...

Public Types
enum class	CompressionMode { None = 0 , RLE = 1 , Huffman = 6 , FFV1 = 64 , ZSTD = 65 , H264 = 128 }
	Compression modes for ImFusionFile format. More...
using	CompressionOverride = std::unordered_map<std::string, CompressionMode>
	Map of data names to compression modes for per-data compression control.

Public Member Functions
std::optional< OwningDataList >	load (int blockId=-1)
	Load the file and add content to provided data list, returns true on success If the given blockId is < 0, all data stored in the file will be loaded.
bool	loadMetaInfo ()
	Load only the meta-info block in the file, returns true on success.
bool	save (DataList data)
	Save data to a file, returns true on success.
bool	save (const SharedImageSet *img)
	Convenience method to save an image data set, returns true on success.
void	setProperties (Properties *p)
	Set global properties.
const Properties *	properties () const
	Get global properties.
void	addGroup (ImFusionFileGroup &g)
	Add group.
const std::map< Data *, unsigned int > &	dataBlockIds () const
	Returns the map of the written/loaded data to their corresponding block IDs.
void	setLoadAllSharedImageSetProperties (bool val)
	Defines whether properties should be copied to all contained SharedImageSets.
void	setEnsureTopLeftOriginOnLoad (bool val)
	Defines whether legacy data with origin in botton-left corner should be flipped when loading.
bool	isEnsuringTopLeftOriginOnLoad () const
	Returns whether legacy data with origin in botton-left corner should be flipped when loading.
bool	fileSizeFitsBlockData (size_t *sizeOfContent=nullptr) const
std::streampos	getReadPosition ()
	Read position of the reading-head in the current input stream (i.e.
bool	load (DataList &data, int blockId=-1)

Static Public Member Functions
static void	addPlugin (std::unique_ptr< ImFusionFilePlugin > p)
	Add a plugin for custom data types to load and save.
static void	addPlugin (ImFusionFilePlugin *p)

Methods for general load and save
static bool	canSave (const DataList &data)
static std::optional< OwningDataList >	load (const ByteBufferView &byteBufferView, int blockId=-1)
	Use this to avoid having to copy the underlying buffer.
static std::vector< std::unique_ptr< ImFusionFilePlugin > > &	plugins ()
	Retrieve the vector of available plugins.
	ImFusionFile (std::string filename)
	Constructor with filename to load or save.
	ImFusionFile (std::vector< char > &buffer)
	Constructor with buffer to load or save to.
void	setProgress (Progress *p)
	Set an optional progress interface.
void	setCompression (int mode)
	Set compression mode.
void	setCompression (CompressionMode mode)
void	setCompressionOptions (int mode, int passes, int dx, int dy)
	Set options for image compression.
void	setCompressionOptions (CompressionMode mode, int passes, int dx, int dy)
void	setCompressionOverride (CompressionOverride overrides)
	Set per-data compression override for nested data control.
const std::set< std::string > &	ignoredDataComponentIds () const
	Returns the list of DataComponentIDs that should not be written/read.
void	setIgnoredDataComponentIds (const std::set< std::string > &value)
	Sets the list of DataComponentIDs that should not be written/read.
void	setSaveUnrestoredDataComponents (bool enable)
	Sets whether DataComponents should be saved which couldn't be restored when the input dataset was loaded.

Methods for selective query and loading of data
bool	open (int mode)
	Open the file and retrieve block information, return true on success and at least one block present.
bool	beginBlockWrite (ImFusionFilePlugin p, Data d=0)
	Initialize plugin The file will open a new block and initialize the plugin with the file pointer.
unsigned long long	endBlockWrite ()
	Close block and disable plugin access.
bool	beginBlockRead (int block, ImFusionFilePlugin *p)
	Initialize plugin The file will read the block header and point the plugin to the position after the header.
unsigned long long	endBlockRead ()
	Close block and disable plugin access.
int	listBlocks (std::vector< unsigned int > &blockTypeOut, std::vector< unsigned long long > &blockSizeOut)
	Return block information, available after having called open().
bool	close ()
	Close the file manually if selective read methods above have been used.

Member Typedef Documentation

◆ CompressionOverride

using ImFusion::ImFusionFile::CompressionOverride = std::unordered_map<std::string, CompressionMode>

Map of data names to compression modes for per-data compression control.

Use "<ALL>" as key to set compression for all data not explicitly listed.

Member Enumeration Documentation

◆ CompressionMode

enum class ImFusion::ImFusionFile::CompressionMode

strong

Compression modes for ImFusionFile format.

Enumerator
None	No compression.
RLE	Run-length encoding.
Huffman	Huffman encoding.
FFV1	FFV1 lossless video codec.
ZSTD	ZSTD lossless compression.
H264	H264 lossy video codec.

Member Function Documentation

◆ addPlugin()

void ImFusion::ImFusionFile::addPlugin ( ImFusionFilePlugin * p )

static

Deprecated: "Use addPlugin(std::unique_ptr<ImFusionFilePlugin>) for correct ownership semantics."

◆ canSave()

bool ImFusion::ImFusionFile::canSave ( const DataList & data )

static

Determines if all Data items in the given data list can be saved into an ImFusion file

◆ setCompression()

void ImFusion::ImFusionFile::setCompression ( int mode )

Set compression mode.

Deprecated: "Use setCompression(CompressionMode mode) instead."

◆ setCompressionOptions()

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

Set options for image compression.

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

◆ setCompressionOverride()

void ImFusion::ImFusionFile::setCompressionOverride ( CompressionOverride overrides )

Set per-data compression override for nested data control.

The callback is consulted for each Data element

◆ setIgnoredDataComponentIds()

void ImFusion::ImFusionFile::setIgnoredDataComponentIds ( const std::set< std::string > & value )

Sets the list of DataComponentIDs that should not be written/read.

Note: If this set consists of the single value "<ALL>", all DataComponents will be ignored.

◆ setSaveUnrestoredDataComponents()

void ImFusion::ImFusionFile::setSaveUnrestoredDataComponents ( bool enable )

Sets whether DataComponents should be saved which couldn't be restored when the input dataset was loaded.

An ImFusionFile might contain DataComponents of plugins that are currently not loaded. In this case, the particular DataComponent cannot be restored and are instead saved inside the UnrestoredDataComponents component. If this component is present and this option enabled, the configuration of those components is written back to the resulting ImFusionFile.

This option is important for e.g. scripts that load a ImFusionFile, modify the data and save it again.

Unrestored component ids that are in ignoredDataComponentIds will not be saved, regardless of this option.

Enabled by default.

◆ open()

bool ImFusion::ImFusionFile::open ( int mode )

Open the file and retrieve block information, return true on success and at least one block present.

Parameters

mode	Access mode 0 = read, 1 = write

◆ beginBlockWrite()

bool ImFusion::ImFusionFile::beginBlockWrite	(	ImFusionFilePlugin *	p,
		Data *	d = 0 )

Initialize plugin The file will open a new block and initialize the plugin with the file pointer.

The plugin can then write freely to the block.

Parameters

p	plugin for writing to block
d	data for determining save type

Returns: true if successful, false otherwise

◆ endBlockWrite()

unsigned long long ImFusion::ImFusionFile::endBlockWrite ( )

Close block and disable plugin access.

Returns: number of bytes written to block, -1 on error

◆ beginBlockRead()

bool ImFusion::ImFusionFile::beginBlockRead	(	int	block,
		ImFusionFilePlugin *	p )

Initialize plugin The file will read the block header and point the plugin to the position after the header.

The plugin can then access the data in the block.

Parameters

block	block number
p	plugin for writing to block

Returns: true if successful, false otherwise

◆ endBlockRead()

unsigned long long ImFusion::ImFusionFile::endBlockRead ( )

Close block and disable plugin access.

Returns: number of bytes written to block, -1 on error

◆ listBlocks()

int ImFusion::ImFusionFile::listBlocks	(	std::vector< unsigned int > &	blockTypeOut,
		std::vector< unsigned long long > &	blockSizeOut )

Return block information, available after having called open().

Parameters

[out]	blockTypeOut	list of block types
[out]	blockSizeOut	list of block sizes in bytes

Returns: number of blocks or -1 on error

◆ load() [1/2]

std::optional< OwningDataList > ImFusion::ImFusionFile::load ( int blockId = -1 )

Load the file and add content to provided data list, returns true on success If the given blockId is < 0, all data stored in the file will be loaded.

If the given blockId is >= 0, only the data in the given block will be loaded.

◆ getReadPosition()

std::streampos ImFusion::ImFusionFile::getReadPosition ( )

Read position of the reading-head in the current input stream (i.e.

number of bytes that were read) Basically returns the tellg() of the underlying stream, and returns -1 if no valid stream is present. Only valid when using the buffer constructor This function is not supported on older MacOS systems

◆ load() [2/2]

bool ImFusion::ImFusionFile::load	(	DataList &	data,
		int	blockId = -1 )

Deprecated: "Use the std::optional<OwningDataList> load(int) overload instead for correct ownership semantics."

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

ImFusion/Base/ImFusionFile.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Methods for general load and save

Methods for selective query and loading of data

Member Typedef Documentation

◆ CompressionOverride

Member Enumeration Documentation

◆ CompressionMode

Member Function Documentation

◆ addPlugin()

◆ canSave()

◆ setCompression()

◆ setCompressionOptions()

◆ setCompressionOverride()

◆ setIgnoredDataComponentIds()

◆ setSaveUnrestoredDataComponents()

◆ open()

◆ beginBlockWrite()

◆ endBlockWrite()

◆ beginBlockRead()

◆ endBlockRead()

◆ listBlocks()

◆ load() [1/2]

◆ getReadPosition()

◆ load() [2/2]