High-level interface to an image file format instance. More...

#include <FileFormatInstance.h>

Inheritance diagram for pcl::FileFormatInstance:

Public Member Functions
	FileFormatInstance (const FileFormat &fmt)

	FileFormatInstance (FileFormatInstance &&x)

	~FileFormatInstance () override

bool	CanReadIncrementally () const

bool	CanWriteIncrementally () const

bool	Close ()

bool	CloseImage ()

bool	Create (const String &filePath, const IsoString &hints=IsoString(), int numberOfImages=1)

bool	CreateImage (const ImageInfo &info)

void	EnsureUnique () override

String	FilePath () const

FileFormat	Format () const

const void *	FormatSpecificData () const

bool	HasImageProperty (const IsoString &property)

bool	HasProperty (const IsoString &property)

String	ImageFormatInfo () const

pcl::PropertyDescription	ImagePropertyDescription (const IsoString &property)

PropertyDescriptionArray	ImagePropertyDescriptions ()

bool	IsOpen () const

bool	Open (ImageDescriptionArray &images, const String &filePath, const IsoString &hints=IsoString())

FileFormatInstance &	operator= (FileFormatInstance &&x)

pcl::PropertyDescription	PropertyDescription (const IsoString &property)

PropertyDescriptionArray	PropertyDescriptions ()

bool	QueryOptions (Array< ImageOptions > &options, Array< const void * > &formatOptions)

bool	ReadColorFilterArray (ColorFilterArray &cfa)

bool	ReadDisplayFunction (DisplayFunction &df)

bool	ReadFITSKeywords (FITSKeywordArray &keywords)

bool	ReadICCProfile (ICCProfile &icc)

bool	ReadImage (DImage &image)

bool	ReadImage (FImage &image)

bool	ReadImage (ImageVariant &image)

bool	ReadImage (UInt16Image &image)

bool	ReadImage (UInt32Image &image)

bool	ReadImage (UInt8Image &image)

PropertyArray	ReadImageProperties ()

Variant	ReadImageProperty (const IsoString &property)

PropertyArray	ReadProperties ()

Variant	ReadProperty (const IsoString &property)

bool	ReadRGBWorkingSpace (RGBColorSystem &rgbws)

bool	ReadSamples (DImage::sample *buffer, int startRow, int rowCount, int channel)

bool	ReadSamples (FImage::sample *buffer, int startRow, int rowCount, int channel)

bool	ReadSamples (UInt16Image::sample *buffer, int startRow, int rowCount, int channel)

bool	ReadSamples (UInt32Image::sample *buffer, int startRow, int rowCount, int channel)

bool	ReadSamples (UInt8Image::sample *buffer, int startRow, int rowCount, int channel)

bool	ReadThumbnail (UInt8Image &thumbnail)

int	SelectedImageIndex () const

bool	SelectImage (int index)

bool	SetFormatSpecificData (const void *data)

bool	SetId (const IsoString &id)

bool	SetOptions (const ImageOptions &options)

bool	WasInexactRead () const

bool	WasLossyWrite () const

bool	WriteColorFilterArray (const ColorFilterArray &cfa)

bool	WriteDisplayFunction (const DisplayFunction &df)

bool	WriteFITSKeywords (const FITSKeywordArray &keywords)

bool	WriteICCProfile (const ICCProfile &icc)

bool	WriteImage (const DImage &image)

bool	WriteImage (const FImage &image)

bool	WriteImage (const ImageVariant &image)

bool	WriteImage (const UInt16Image &image)

bool	WriteImage (const UInt32Image &image)

bool	WriteImage (const UInt8Image &image)

bool	WriteImageProperties (const PropertyArray &properties)

bool	WriteImageProperty (const IsoString &property, const Variant &value)

bool	WriteImageProperty (const Property &property)

bool	WriteProperties (const PropertyArray &properties)

bool	WriteProperty (const IsoString &property, const Variant &value)

bool	WriteProperty (const Property &property)

bool	WriteRGBWorkingSpace (const RGBColorSystem &rgbws)

bool	WriteSamples (const DImage::sample *buffer, int startRow, int rowCount, int channel)

bool	WriteSamples (const FImage::sample *buffer, int startRow, int rowCount, int channel)

bool	WriteSamples (const UInt16Image::sample *buffer, int startRow, int rowCount, int channel)

bool	WriteSamples (const UInt32Image::sample *buffer, int startRow, int rowCount, int channel)

bool	WriteSamples (const UInt8Image::sample *buffer, int startRow, int rowCount, int channel)

bool	WriteThumbnail (const UInt8Image &image)

Public Member Functions inherited from pcl::UIObject
virtual	~UIObject () noexcept(false)

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static FileFormatInstance &	Null ()

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

FileFormatInstance, along with FileFormat, allows full access to any installed file format through intermodule communication.

FileFormatInstance represents a live instance of an installed image format; usually (but not necessarily) a disk file.

See also: FileFormat

Definition at line 89 of file FileFormatInstance.h.

Constructor & Destructor Documentation

◆ FileFormatInstance() [1/2]

pcl::FileFormatInstance::FileFormatInstance ( const FileFormat & fmt )

Constructs a file format instance of the specified file format fmt.

◆ FileFormatInstance() [2/2]

pcl::FileFormatInstance::FileFormatInstance ( FileFormatInstance && x )

inline

Move constructor.

Definition at line 101 of file FileFormatInstance.h.

◆ ~FileFormatInstance()

pcl::FileFormatInstance::~FileFormatInstance ( )

inlineoverride

Destroys a file format instance.

After destruction of this instance, the server-side object is also destroyed if it is no longer referenced by other FileFormatInstance objects. When the server-side object is destroyed, any open files are automatically flushed and closed, as necessary.

Definition at line 114 of file FileFormatInstance.h.

Member Function Documentation

◆ CanReadIncrementally()

bool pcl::FileFormatInstance::CanReadIncrementally ( ) const

Returns true iff this instance can perform incremental read operations.

Do not confuse this member function with FileFormat::CanReadIncrementally(), which tells you if a given file format has the capability of performing incremental file reads in general. The value returned by this function refers specifically to this format instance (e.g., a particular file).

◆ CanWriteIncrementally()

bool pcl::FileFormatInstance::CanWriteIncrementally ( ) const

Returns true iff this instance can perform incremental write operations.

Do not confuse this member function with FileFormat::CanWriteIncrementally(), which tells you if a given file format has the capability of performing incremental file writes in general. The value returned by this function refers specifically to this format instance (e.g., a particular file).

◆ Close()

bool pcl::FileFormatInstance::Close ( )

Closes an image file (after Open() or Create()).

Returns true iff the file was successfully closed.

◆ CloseImage()

bool pcl::FileFormatInstance::CloseImage ( )

Closes the image that has been created by a previous call to CreateImage().

Returns true iff the image was successfully closed.

Note: This member function must be reimplemented by all derived classes supporting incremental write operations.

◆ Create()

bool pcl::FileFormatInstance::Create	(	const String &	filePath,
		const IsoString &	hints = `IsoString()`,
		int	numberOfImages = `1`
	)

Creates an image file for writing.

Parameters

filePath	Path to a file that will be created. If a file exists at the same path, it will be overwritten and its current contents will be lost.
hints	A string containing a (possibly empty) list of hints intended to modify the way an image file is generated and/or the way image data are to be encoded and written. A format module can simply ignore all of these hints, or just look for one or more hints that it recognizes and supports, ignoring others. When two or more hints are specified, they must be separated by space characters (0x20). Many standard file formats support some hints. For example, the standard JPEG format recognizes the "quality <n>" hint to force generation of a JPEG image with a given quality level <n> in the range 1 to 100, irrespective of the current JPEG format settings.
numberOfImages	This is the number of images that will be written to the file after creation. It can be zero if an empty file is being created, and also less than zero if the number of images is unknown or cannot be defined at the point of creation. This parameter defaults to one.

Returns true iff the file was successfully created. Returns false in the event of error.

◆ CreateImage()

bool pcl::FileFormatInstance::CreateImage ( const ImageInfo & info )

Creates a new image with the geometry and color space as specified by an ImageInfo structure. The newly created image will be written by subsequent incremental write operations.

The sample data type and other format-independent and format-specific image parameters have been specified by previous calls to SetOptions() and SetFormatSpecificData().

Returns true iff the image was successfully created.

Note: This member function should not be invoked for file formats that don't support incremental write operations, or for format instances that don't allow them.

◆ EnsureUnique()

void pcl::FileFormatInstance::EnsureUnique ( )

inlineoverridevirtual

Ensures that the server-side object managed by this instance is uniquely referenced.

Since file format instances are unique objects, calling this member function has no effect.

Reimplemented from pcl::UIObject.

Definition at line 134 of file FileFormatInstance.h.

◆ FilePath()

String pcl::FileFormatInstance::FilePath ( ) const

Returns the absolute file path of this file format instance. If no file path has been set yet (by calling Open() or Create()), this member function returns an empty string.

◆ Format()

FileFormat pcl::FileFormatInstance::Format ( ) const

Returns a FileFormat object that represents the installed file format that this instance belongs to.

◆ FormatSpecificData()

const void* pcl::FileFormatInstance::FormatSpecificData ( ) const

Returns a format-specific data block for the current image in this file, or zero if no such data have been retrieved.

See SetFormatSpecificData() for a description of format-specific data functionality in PCL.

Format-specific data blocks do not pertain to the caller's heap, but to the underlying module that implements the file format. Therefore, all format-specific data blocks must be deallocated, when appropriate, by calling FileFormat::DisposeFormatSpecificData().

◆ HasImageProperty()

bool pcl::FileFormatInstance::HasImageProperty ( const IsoString & property )

inline

Returns true iff the specified property exists associated with the current image in this file. Returns false if no such property exists.

This is a convenience member function, equivalent to the following code:

ImagePropertyDescriptions().Contains( property );

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

Definition at line 493 of file FileFormatInstance.h.

◆ HasProperty()

bool pcl::FileFormatInstance::HasProperty ( const IsoString & property )

inline

Returns true iff the specified property exists associated with this file. Returns false if no such property exists for this file.

This is a convenience member function, equivalent to the following code:

PropertyDescriptions().Contains( property );

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with HasImageProperty(). This function returns true if a given property of the whole file exists, while HasImageProperty() returns true if a property of the currently selected image exists.

Definition at line 388 of file FileFormatInstance.h.

◆ ImageFormatInfo()

String pcl::FileFormatInstance::ImageFormatInfo ( ) const

Provides a human-readable summary of format-specific properties for the current image in this file.

The returned string should include format-specific information, not generic image information. For example, it won't include image dimensions, color space, and other things that can be retrieved with the Open() member function.

◆ ImagePropertyDescription()

pcl::PropertyDescription pcl::FileFormatInstance::ImagePropertyDescription ( const IsoString & property )

inline

Returns a description (unique identifier and data type) of the specified data property associated with the current image. If no such property exists, the returned PropertyDescription object specifies an invalid data type and empty identifier.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

Definition at line 513 of file FileFormatInstance.h.

References pcl::Array< T, A >::End(), and pcl::Array< T, A >::Search().

◆ ImagePropertyDescriptions()

PropertyDescriptionArray pcl::FileFormatInstance::ImagePropertyDescriptions ( )

Returns a description of all data properties associated with the current image in this file. For each data property, the returned array provides information on the unique identifier of a property and its data type.

Returns an empty array if there are no properties stored for the current image in this file.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

◆ IsOpen()

bool pcl::FileFormatInstance::IsOpen ( ) const

Returns true iff this file is currently open.

◆ Null()

static FileFormatInstance& pcl::FileFormatInstance::Null ( )

static

Returns a reference to a null format instance. A null FileFormatInstance object does not correspond to an existing image file format instance in the PixInsight core application.

◆ Open()

bool pcl::FileFormatInstance::Open	(	ImageDescriptionArray &	images,
		const String &	filePath,
		const IsoString &	hints = `IsoString()`
	)

Opens an image file for reading and/or information retrieval.

Parameters

images	Reference to a dynamic array of ImageDescription structures. On successful return, this array will describe the image(s) stored in this image file. Each ImageDescription structure will contain ImageInfo and ImageOptions objects that describe both basic image parameters (as geometry and color space) and format-independent image options (pixel format, embedded data, etc). Descriptive information is provided by the underlying format module with data retrieved from the opened image file.
filePath	File path to an existing file that will be opened.
hints	A string containing a (possibly empty) list of hints intended to modify the way an image file is opened and/or the way image data are to be read and decoded. A format module can simply ignore all of these hints, or just look for one or more hints that it recognizes and supports, ignoring others. When two or more hints are specified, they must be separated by space characters (0x20). Most standard file formats support hints. For example, the standard DSLR_RAW format recognizes the "raw" hint to force reading pure raw data (no deBayerization, no black pedestal subtraction, no white balancing) irrespective of the current DSLR RAW format settings. The default value is an empty string.

This member function can provide an empty images array. If this happens, it means that the file is empty, that is, it contains no image. Although there is no standard file format module that supports empty image files as of writing this documentation, this is a possibility that must be taken into account by calling modules.

Returns true if the file was successfully opened; false in the event of error.

◆ operator=()

FileFormatInstance& pcl::FileFormatInstance::operator= ( FileFormatInstance && x )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 121 of file FileFormatInstance.h.

◆ PropertyDescription()

pcl::PropertyDescription pcl::FileFormatInstance::PropertyDescription ( const IsoString & property )

inline

Returns a description (unique identifier and data type) of the specified data property associated with this file. If no such property exists, the returned PropertyDescription object specifies an invalid data type and an empty identifier.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with ImagePropertyDescription(). This function describes a property of the whole file, while ImagePropertyDescription() describes a property of the currently selected image.

Definition at line 413 of file FileFormatInstance.h.

References pcl::Array< T, A >::End(), and pcl::Array< T, A >::Search().

◆ PropertyDescriptions()

PropertyDescriptionArray pcl::FileFormatInstance::PropertyDescriptions ( )

Returns a description of all data properties associated with this file. For each data property, the returned array provides information on the unique identifier of a property and its data type.

Returns an empty array if there are no properties associated with this file.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with ImagePropertyDescriptions(). This function returns information on the properties of the whole file, while ImagePropertyDescriptions() returns information on the properties of the currently selected image.

◆ QueryOptions()

bool pcl::FileFormatInstance::QueryOptions	(	Array< ImageOptions > &	options,
		Array< const void * > &	formatOptions
	)

Queries image options and format-specific data before creating a new image file. Returns true if the file creation operation can continue; false if it should be aborted.

Parameters

[out]	options	Reference to a dynamic array of ImageOptions objects. Each of these objects provides a general description of an image stored in a file instance of this file format. The underlying file format module is responsible for setting the appropriate values in the passed structures. The returned options can be used to generate a new file through a subsequent call to Create(). Formats that support multiple images per file can receive more than one ImageOptions structure stored in this array. Passing more than one ImageOptions object to a format that doesn't support multiple images will be caught and blocked by the PixInsight core application.
[out]	formatOptions	Reference to a dynamic array of format-specific data blocks. Each void pointer in this array can be either zero or point to valid format-specific data for the format of this instance. This array can be empty if no format-specific data is being set. See the SetFormatSpecificData() member function for more information on format-specific data blocks.

A module should call this function just before calling Create(), as part of a File > Save As operation, or equivalent. Typically, the underlying format module will open a dialog box to let the user modify some working options. This function will return true unless the user cancels the format options dialog.

◆ ReadColorFilterArray()

bool pcl::FileFormatInstance::ReadColorFilterArray ( ColorFilterArray & cfa )

Extraction of the color filter array (CFA) for the current image in this file.

Returns true iff the file access operation was successful, even if no CFA was extracted. Returns false in the event of error.

If no CFA is defined for the current image, this function will assign an empty CFA to cfa (see ColorFilterArray's default constructor).

To prevent runtime errors, you should only call this member function for instances of file formats supporting color filter arrays. See FileFormat::CanStoreColorFilterArrays().

◆ ReadDisplayFunction()

bool pcl::FileFormatInstance::ReadDisplayFunction ( DisplayFunction & df )

Extraction of the display function associated with the current image in this file.

Returns true iff the file access operation was successful, even if no display function was extracted. Returns false in the event of error.

If no display function is defined for the current image, this function will assign an identity display function to df (see DisplayFunction's default constructor).

To prevent runtime errors, you should only call this member function for instances of file formats supporting display functions. See FileFormat::CanStoreDisplayFunctions().

◆ ReadFITSKeywords()

bool pcl::FileFormatInstance::ReadFITSKeywords ( FITSKeywordArray & keywords )

Extraction of embedded keywords for the current image in this file.

If the current image embeds FITS header keywords, they will be added to the specified keywords list. Otherwise the keywords list will be left empty. In any case, previous contents of the kwywords list will be destroyed.

Returns true iff the file access operation was successful, even if no keyword was extracted. Returns false in the event of error.

◆ ReadICCProfile()

bool pcl::FileFormatInstance::ReadICCProfile ( ICCProfile & icc )

Extraction of the ICC color profile associated with the current image in this file.

If the current image embeds an ICC profile, it will be assigned to the specified icc object. Otherwise, icc will be set to a null profile.

Returns true iff the file access operation was successful, even if no ICC profile was extracted. Returns false in the event of error.

◆ ReadImage() [1/6]

bool pcl::FileFormatInstance::ReadImage ( DImage & image )

Reads the current image in 64-bit floating point format. Returns true iff the image was successfully read.

◆ ReadImage() [2/6]

bool pcl::FileFormatInstance::ReadImage ( FImage & image )

Reads the current image in 32-bit floating point format. Returns true iff the image was successfully read.

◆ ReadImage() [3/6]

bool pcl::FileFormatInstance::ReadImage ( ImageVariant & image )

inline

Reads the current image and stores it in the image transported by the specified ImageVariant object, using the pixel sample format of the transported image. Returns true iff the ImageVariant object transports a valid image and the image was successfully read.

Definition at line 593 of file FileFormatInstance.h.

References pcl::ImageVariant::BitsPerSample(), pcl::ImageVariant::IsComplexSample(), and pcl::ImageVariant::IsFloatSample().

◆ ReadImage() [4/6]

bool pcl::FileFormatInstance::ReadImage ( UInt16Image & image )

Reads the current image in 16-bit unsigned integer format. Returns true iff the image was successfully read.

◆ ReadImage() [5/6]

bool pcl::FileFormatInstance::ReadImage ( UInt32Image & image )

Reads the current image in 32-bit unsigned integer format. Returns true iff the image was successfully read.

◆ ReadImage() [6/6]

bool pcl::FileFormatInstance::ReadImage ( UInt8Image & image )

Reads the current image in 8-bit unsigned integer format. Returns true iff the image was successfully read.

◆ ReadImageProperties()

PropertyArray pcl::FileFormatInstance::ReadImageProperties ( )

Returns an array with all data properties of the current image.

If no property exists associated with the current image in this file, an empty array will be returned.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

◆ ReadImageProperty()

Variant pcl::FileFormatInstance::ReadImageProperty ( const IsoString & property )

Extraction of a data property of the current image with the specified unique identifier.

If no property with the specified identifier exists associated with the current image in this file, an invalid Variant object will be returned.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

◆ ReadProperties()

PropertyArray pcl::FileFormatInstance::ReadProperties ( )

Returns an array with all data properties associated with this file.

Returns an empty array if there are no properties associated with this file.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with ReadImageProperties(). This function returns the properties of the whole file, while ReadImageProperties() returns the properties of the currently selected image.

◆ ReadProperty()

Variant pcl::FileFormatInstance::ReadProperty ( const IsoString & property )

Extraction of a data property associated with this file with the specified unique identifier.

If no property with the specified identifier exists associated with this file, an invalid Variant object will be returned.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with ReadImageProperty(). This function returns the value of a property of the whole file, while ReadImageProperty() returns the value of a property of the currently selected image.

◆ ReadRGBWorkingSpace()

bool pcl::FileFormatInstance::ReadRGBWorkingSpace ( RGBColorSystem & rgbws )

Extraction of the RGB working space associated with the current image in this file.

Returns true iff the file access operation was successful, even if no RGBWS was extracted. Returns false in the event of error.

If no RGBWS is defined for the current image, this function will assign a default-constructed RGBColorSystem object to rgbws (see RGBColorSystem::sRGB).

To prevent runtime errors, you should only call this member function for instances of file formats supporting RGB working spaces. See FileFormat::CanStoreRGBWS().

◆ ReadSamples() [1/5]

bool pcl::FileFormatInstance::ReadSamples	(	DImage::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental read in 64-bit floating point sample format.

This is an overloaded member function for the DImage type; see ReadSamples( FImage::sample*, int, int, int, int ) for a full description.

◆ ReadSamples() [2/5]

bool pcl::FileFormatInstance::ReadSamples	(	FImage::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental read in 32-bit floating point sample format.

Parameters

[out]	buffer	Address of the destination sample buffer.
	startRow	First pixel row to read.
	rowCount	Number of pixel rows to read.
	channel	Channel index to read.

Returns true if the specified pixel row(s) were successfully read; false in the event of error, or if the operation was cancelled.

Incremental read operations allow loading images by successive pixel row strips. They are useful to manage very large files, or large sets of image files that don't fit in the available RAM.

When a file format implements incremental reading, the corresponding FileFormat::CanReadIncrementally() returns true. Furthermore, the CanReadIncrementally() member function of this class should also return true for this object, allowing incremental reads for this particular format instance. Otherwise this function must not be invoked - it will throw an exception if called for a format that does not support incremental reads, and will fail unexpectedly if called for an instance that does not allow them.

◆ ReadSamples() [3/5]

bool pcl::FileFormatInstance::ReadSamples	(	UInt16Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental read in 16-bit unsigned integer sample format.

This is an overloaded member function for the UInt16Image type; see ReadSamples( FImage::sample*, int, int, int, int ) for a full description.

◆ ReadSamples() [4/5]

bool pcl::FileFormatInstance::ReadSamples	(	UInt32Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental read in 32-bit unsigned integer sample format.

This is an overloaded member function for the UInt32Image type; see ReadSamples( FImage::sample*, int, int, int, int ) for a full description.

◆ ReadSamples() [5/5]

bool pcl::FileFormatInstance::ReadSamples	(	UInt8Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental read in 8-bit unsigned integer sample format.

This is an overloaded member function for the UInt8Image type; see ReadSamples( FImage::sample*, int, int, int, int ) for a full description.

◆ ReadThumbnail()

bool pcl::FileFormatInstance::ReadThumbnail ( UInt8Image & thumbnail )

Extraction of an embedded thumbnail for the current image in this file.

If the current image embeds a thumbnail image, it will be assigned to the specified thumbnail 8-bit integer image. Otherwise, a null image will be assigned to thumbnail.

Returns true iff the file access operation was successful, even if no thumbnail image was extracted. Returns false in the event of error.

◆ SelectedImageIndex()

int pcl::FileFormatInstance::SelectedImageIndex ( ) const

Returns the current zero-based image index in this file.

This member function must only be called for file formats that support multiple images stored in a single file. It should not be called if the FileFormat::SupportsMultipleImages() member function returns false for the file format this instance belongs to.

◆ SelectImage()

bool pcl::FileFormatInstance::SelectImage ( int index )

Selects the image at the specified zero-based index in this file.

Returns true if the specified image was successfully selected; false in the event of error.

This member function must only be called for file formats that support multiple images stored in a single file. It should not be called if the FileFormat::SupportsMultipleImages() member function returns false for the file format this instance belongs to.

◆ SetFormatSpecificData()

bool pcl::FileFormatInstance::SetFormatSpecificData ( const void * data )

Specifies a format-specific data block for the next image that will be written or created in this file.

Format-specific data are arbitrary data blocks; the PixInsight core application knows nothing about them except that it keeps them for all open image files and passes them among instances, even instances of different file formats. The core application deallocates format-specific data blocks when appropriate, by invoking the corresponding module deallocation routines.

Format-specific data are often used by image file formats to store working data on a per-instance basis (which usually means on a per-file basis), such as compression modes and ratios, file organization modes, and many other critical working parameters that can persist across different file format instances.

When a file format uses (or can use) format-specific data, the corresponding FileFormat::UsesFormatSpecificData() member function returns true.

Returns true iff the specified data block was accepted by this instance. Returns false if the data block is invalid, or in the event of error.

note A module should verify validity of a format-specific data block with FileFormat::ValidateFormatSpecificData() before calling this function to pass the block to an instance.

◆ SetId()

bool pcl::FileFormatInstance::SetId ( const IsoString & id )

Specifies an identifier for the next image that will be written or created in this file.

Returns true iff the identifier was successfully assigned. Returns false in the event of error.

Note: Most file format implementations don't support image identifiers and simply ignore a call to this function, reporting success.

◆ SetOptions()

bool pcl::FileFormatInstance::SetOptions ( const ImageOptions & options )

Specifies a set of format-independent image options for the next image that will be written or created in this file.

Returns true iff the options were successfully assigned. Returns false in the event of error.

Note: A file format implementations may ignore any format-independent options set with a call to this function, reporting success.

◆ WasInexactRead()

bool pcl::FileFormatInstance::WasInexactRead ( ) const

Returns true iff the last file read operation was inexact.

This function can be called just after a successful call to ReadImage() or Read(). If a file format instance reads source images inexactly, (e.g., by applying a rounding function to source sample values), then this function should return true.

◆ WasLossyWrite()

bool pcl::FileFormatInstance::WasLossyWrite ( ) const

Returns true iff the last file write operation in this file was lossy.

This function can ve called just after successful completion of a call to WriteImage() or Write(). If a file format instance writes lossy image data (e.g., by applying some lossy compression scheme), then this function will return true.

◆ WriteColorFilterArray()

bool pcl::FileFormatInstance::WriteColorFilterArray ( const ColorFilterArray & cfa )

Specifies a color filter array (CFA) that will be embedded in the next image written or created in this file.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting color filter arrays. See FileFormat::CanStoreColorFilterArrays().

◆ WriteDisplayFunction()

bool pcl::FileFormatInstance::WriteDisplayFunction ( const DisplayFunction & df )

Specifies a display function that will be embedded in the next image written or created in this file.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting display functions. See FileFormat::CanStoreDisplayFunctions().

◆ WriteFITSKeywords()

bool pcl::FileFormatInstance::WriteFITSKeywords ( const FITSKeywordArray & keywords )

Specifies a set of FITS keywords to be embedded in the next image written or created in this file.

Returns true if the specified keywords list was successfully embedded in the image; false in the event of error.

◆ WriteICCProfile()

bool pcl::FileFormatInstance::WriteICCProfile ( const ICCProfile & icc )

Specifies an ICC profile to be embedded in the next image written or created in this file.

Returns true if the specified ICC profile was successfully embedded in the image; false in the event of error.

◆ WriteImage() [1/6]

bool pcl::FileFormatInstance::WriteImage ( const DImage & image )

Writes a 64-bit floating point image to this file. Returns true iff the image was successfully written.

◆ WriteImage() [2/6]

bool pcl::FileFormatInstance::WriteImage ( const FImage & image )

Writes a 32-bit floating point image to this file. Returns true iff the image was successfully written.

◆ WriteImage() [3/6]

bool pcl::FileFormatInstance::WriteImage ( const ImageVariant & image )

inline

Writes image transported by the specified ImageVariant object to this file, using the pixel sample format of the transported image. Returns true iff the ImageVariant object transports a valid image and the image was successfully written.

Definition at line 1025 of file FileFormatInstance.h.

References pcl::ImageVariant::BitsPerSample(), pcl::ImageVariant::IsComplexSample(), and pcl::ImageVariant::IsFloatSample().

◆ WriteImage() [4/6]

bool pcl::FileFormatInstance::WriteImage ( const UInt16Image & image )

Writes a 16-bit unsigned integer image to this file. Returns true iff the image was successfully written.

◆ WriteImage() [5/6]

bool pcl::FileFormatInstance::WriteImage ( const UInt32Image & image )

Writes a 32-bit unsigned integer image to this file. Returns true iff the image was successfully written.

◆ WriteImage() [6/6]

bool pcl::FileFormatInstance::WriteImage ( const UInt8Image & image )

Writes an 8-bit unsigned integer image to this file. Returns true iff the image was successfully written.

◆ WriteImageProperties()

bool pcl::FileFormatInstance::WriteImageProperties ( const PropertyArray & properties )

Specifies a set of data properties to be embedded in the next image written or created in this file.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

◆ WriteImageProperty() [1/2]

bool pcl::FileFormatInstance::WriteImageProperty	(	const IsoString &	property,
		const Variant &	value
	)

Specifies a data property to be embedded in the next image written or created in this file.

Parameters

property	Unique identifier of the data property.
value	Property value.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties for individual images. See FileFormat::CanStoreImageProperties().

◆ WriteImageProperty() [2/2]

bool pcl::FileFormatInstance::WriteImageProperty ( const Property & property )

inline

Specifies a data property to be embedded in the next image written or created in this file.

Calling this member function is equivalent to:

WriteImageProperty( property.Id(), property.Value() )

Definition at line 963 of file FileFormatInstance.h.

References pcl::Property::Id(), and pcl::Property::Value().

◆ WriteProperties()

bool pcl::FileFormatInstance::WriteProperties ( const PropertyArray & properties )

Specifies a set of data properties to be embedded in this file.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with WriteImageProperties(). This function defines a set of properties for the whole file, while WriteImageProperties() defines properties for the currently selected image.

◆ WriteProperty() [1/2]

bool pcl::FileFormatInstance::WriteProperty	(	const IsoString &	property,
		const Variant &	value
	)

Specifies a data property to be embedded in this file.

Parameters

property	Unique identifier of the data property.
value	Property value.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting data properties. See FileFormat::CanStoreProperties().

Note: Don't confuse this member function with WriteImageProperty(). This function defines a property of the whole file, while WriteImageProperty() defines a property of the currently selected image.

◆ WriteProperty() [2/2]

bool pcl::FileFormatInstance::WriteProperty ( const Property & property )

inline

Specifies a data property to be embedded in this file.

Calling this member function is equivalent to:

WriteProperty( property.Id(), property.Value() )

Definition at line 913 of file FileFormatInstance.h.

References pcl::Property::Id(), and pcl::Property::Value().

◆ WriteRGBWorkingSpace()

bool pcl::FileFormatInstance::WriteRGBWorkingSpace ( const RGBColorSystem & rgbws )

Specifies the parameters of an RGB working space that will be embedded in the next image written or created in this file.

Returns true only if the embedding operation was successful.

To prevent runtime errors, you should only call this member function for instances of file formats supporting RGB working spaces. See FileFormat::CanStoreRGBWS().

◆ WriteSamples() [1/5]

bool pcl::FileFormatInstance::WriteSamples	(	const DImage::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental write of a 64-bit floating point image.

This is an overloaded member function for the DImage type; see WriteSamples( const FImage::sample*, int, int, int ) for a full description.

◆ WriteSamples() [2/5]

bool pcl::FileFormatInstance::WriteSamples	(	const FImage::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental write of 32-bit floating point pixel samples.

Parameters

buffer	Address of the source sample buffer.
startRow	First pixel row to write.
rowCount	Number of pixel rows to write.
channel	Channel index to write.

Returns true iff the specified pixel row(s) were successfully written; false in the event of error, or if the operation was cancelled.

Incremental write operations allow the PixInsight core application and other modules to generate images by successive row strips. They are useful to generate extremely large images, or large sets of images that don't fit in the available RAM.

When a file format implements incremental writing, the corresponding FileFormat::CanWriteIncrementally() returns true. Furthermore, the CanWriteIncrementally() member function of this class should also return true for this object, allowing incremental writes for this particular format instance. Otherwise this function must not be invoked - it will throw an exception if called for a format that does not support incremental writes, and will fail unexpectedly if called for an instance that does not allow them.

◆ WriteSamples() [3/5]

bool pcl::FileFormatInstance::WriteSamples	(	const UInt16Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental write of a 16-bit unsigned integer image.

This is an overloaded member function for the UInt16Image type; see WriteSamples( const FImage::sample*, int, int, int ) for a full description.

◆ WriteSamples() [4/5]

bool pcl::FileFormatInstance::WriteSamples	(	const UInt32Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental write of a 32-bit unsigned integer image.

This is an overloaded member function for the UInt32Image type; see WriteSamples( const FImage::sample*, int, int, int ) for a full description.

◆ WriteSamples() [5/5]

bool pcl::FileFormatInstance::WriteSamples	(	const UInt8Image::sample *	buffer,
		int	startRow,
		int	rowCount,
		int	channel
	)

Incremental write of an 8-bit unsigned integer image.

This is an overloaded member function for the UInt8Image type; see WriteSamples( const FImage::sample*, int, int, int ) for a full description.

◆ WriteThumbnail()

bool pcl::FileFormatInstance::WriteThumbnail ( const UInt8Image & image )

Specifies a thumbnail image to be embedded in the next image written or created in this file.

Returns true if the specified thumbnail image was successfully embedded in the image; false in the event of error.

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

FileFormatInstance.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FileFormatInstance() [1/2]

◆ FileFormatInstance() [2/2]

◆ ~FileFormatInstance()

Member Function Documentation

◆ CanReadIncrementally()

◆ CanWriteIncrementally()

◆ Close()

◆ CloseImage()

◆ Create()

◆ CreateImage()

◆ EnsureUnique()

◆ FilePath()

◆ Format()

◆ FormatSpecificData()

◆ HasImageProperty()

◆ HasProperty()

◆ ImageFormatInfo()

◆ ImagePropertyDescription()

◆ ImagePropertyDescriptions()

◆ IsOpen()

◆ Null()

◆ Open()

◆ operator=()

◆ PropertyDescription()

◆ PropertyDescriptions()

◆ QueryOptions()

◆ ReadColorFilterArray()

◆ ReadDisplayFunction()

◆ ReadFITSKeywords()

◆ ReadICCProfile()

◆ ReadImage() [1/6]

◆ ReadImage() [2/6]

◆ ReadImage() [3/6]

◆ ReadImage() [4/6]

◆ ReadImage() [5/6]

◆ ReadImage() [6/6]

◆ ReadImageProperties()

◆ ReadImageProperty()

◆ ReadProperties()

◆ ReadProperty()

◆ ReadRGBWorkingSpace()

◆ ReadSamples() [1/5]

◆ ReadSamples() [2/5]

◆ ReadSamples() [3/5]

◆ ReadSamples() [4/5]

◆ ReadSamples() [5/5]

◆ ReadThumbnail()

◆ SelectedImageIndex()

◆ SelectImage()

◆ SetFormatSpecificData()

◆ SetId()

◆ SetOptions()

◆ WasInexactRead()

◆ WasLossyWrite()

◆ WriteColorFilterArray()

◆ WriteDisplayFunction()

◆ WriteFITSKeywords()

◆ WriteICCProfile()

◆ WriteImage() [1/6]

◆ WriteImage() [2/6]

◆ WriteImage() [3/6]

◆ WriteImage() [4/6]

◆ WriteImage() [5/6]

◆ WriteImage() [6/6]

◆ WriteImageProperties()

◆ WriteImageProperty() [1/2]

◆ WriteImageProperty() [2/2]

◆ WriteProperties()

◆ WriteProperty() [1/2]

◆ WriteProperty() [2/2]

◆ WriteRGBWorkingSpace()

◆ WriteSamples() [1/5]

◆ WriteSamples() [2/5]

◆ WriteSamples() [3/5]

◆ WriteSamples() [4/5]