pcl::FileFormat Class Reference

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

#include <FileFormat.h>

Inheritance diagram for pcl::FileFormat:

Public Member Functions
	FileFormat (const FileFormat &fmt)
	FileFormat (const String &nameExtOrMime, bool toRead=false, bool toWrite=false)
	~FileFormat () override
bool	CanEditPreferences () const override
bool	CanRead () const override
bool	CanReadIncrementally () const override
bool	CanStore16Bit () const override
bool	CanStore32Bit () const override
bool	CanStore64Bit () const override
bool	CanStore8Bit () const override
bool	CanStoreAlphaChannels () const override
bool	CanStoreColorFilterArrays () const override
bool	CanStoreComplex () const override
bool	CanStoreDComplex () const override
bool	CanStoreDisplayFunctions () const override
bool	CanStoreDouble () const override
bool	CanStoreFloat () const override
bool	CanStoreGrayscale () const override
bool	CanStoreICCProfiles () const override
bool	CanStoreImageProperties () const override
bool	CanStoreKeywords () const override
bool	CanStoreProperties () const override
bool	CanStoreResolution () const override
bool	CanStoreRGBColor () const override
bool	CanStoreRGBWS () const override
bool	CanStoreThumbnails () const override
bool	CanWrite () const override
bool	CanWriteIncrementally () const override
String	Description () const override
void	DisposeFormatSpecificData (void *data) const override
bool	EditPreferences () const override
StringList	FileExtensions () const override
Bitmap	Icon () const override
String	Implementation () const override
bool	IsDeprecated () const override
IsoStringList	MimeTypes () const override
IsoString	Name () const override
Bitmap	SmallIcon () const override
String	Status () const override
bool	SupportsCompression () const override
bool	SupportsMultipleImages () const override
bool	SupportsViewProperties () const override
bool	UsesFormatSpecificData () const override
bool	ValidateFormatSpecificData (const void *data) const override
uint32	Version () const override
Public Member Functions inherited from pcl::FileFormatBase
	FileFormatBase ()
virtual	~FileFormatBase () noexcept(false)

Static Public Member Functions
static Array< FileFormat >	AllFormats ()
static StringList	DrizzleFiles (const String &dirPath, bool recursive=false, bool followLinks=true)
static StringList	EphemerisFiles (const String &dirPath, bool recursive=false, bool followLinks=true)
static bool	IsSupportedFileFormatBySuffix (const String &path, bool toRead=false, bool toWrite=false)
static StringList	LocalNormalizationFiles (const String &dirPath, bool recursive=false, bool followLinks=true)
static StringList	SupportedImageFiles (const String &dirPath, bool toRead=false, bool toWrite=false, bool recursive=false, bool followLinks=true)

Detailed Description

FileFormat instances are high-level, managed objects that represent installed image file formats in the PixInsight platform. A module creates an instance of FileFormat to gain access to an installed file format through intermodule communication.

FileFormat and MetaFileFormat

FileFormat provides a description of the functionality and properties of an already installed image file format. Contrarily, by subclassing the MetaFileFormat class a module can define and implement a new image file format that can be installed in the PixInsight platform. MetaFileFormat is a formal description of a file format, while FileFormat describes an existing (and installed) file format.

As a MetaFileFormat subclass describes how a format can be instantiated, FileFormat allows a module to create new instances of a file format that can be used to access actual image files. FileFormat doesn't provide any file handling functionality; access to image files is provided by the FileFormatInstance class.

See also

FileFormatBase, MetaFileFormat, FileFormatInstance

Definition at line 97 of file FileFormat.h.

Constructor & Destructor Documentation

FileFormat() [1/2]

pcl::FileFormat::FileFormat	(	const String &	nameExtOrMime,
		bool	toRead = false,
		bool	toWrite = false
	)

Constructs a FileFormat object.

Parameters

nameExtOrMime	A format name, file suffix, or MIME type. This parameter determines how the PixInsight core application looks for an installed file format to which this FileFormat instance will be an interface.
toRead	When a file suffix or MIME type is specified and this parameter is true, a FileFormat instance will be created for an installed file format able to read files with the specified file suffix or corresponding to the specified MIME type.
toWrite	When a file suffix or MIME type is specified and this parameter is true, a FileFormat instance will be created for an installed file format able to write files with the specified file suffix or corresponding to the specified MIME type.

When a format name is used as the argument of this constructor, FileFormat will provide access to an installed file format with the specified identifier, if there exists one. If the argument is a string starting with a dot character, then it is interpreted as a file suffix. If the argument has a slash character ('/'), it is interpreted as a MIME type specifier. In the latter two cases, the PixInsight core application will search for an installed file format able to handle image files with the specified file suffix or for the specified MIME type.

In all cases, if no installed file format fits to the specified argument(s), this constructor throws an Error exception with the corresponding error message. Your code should guarantee that these exceptions will be caught and handled appropriately.

When nameExtOrMime specifies a format name, the toRead and toWrite parameters are ignored.

Example:

try
{
   // Find a format able to read XISF files
   FileFormat xisfFormat( ".xisf", true );
 
   // Create a format instance
   FileFormatInstance myXISFFile( xisfFormat );
 
   // Use the instance to open an existing file
   myXISFFile.Open( "/path/to/test.xisf" );
 
   // Read an image in 32-bit floating point format
   Image img;
   myXISFFile.ReadImage( img );
   // ...
}
catch ( Exception& x )
{
   // Handle errors ...
}

Note

The toRead and toWrite parameters are false by default, which means that no access restrictions are applied by default when creating FileFormat instances.

FileFormat() [2/2]

pcl::FileFormat::FileFormat

(

const FileFormat &

fmt

)

Copy constructor. Constructs an alias FileFormat object that refers to the same image file format as the specified object fmt.

~FileFormat()

pcl::FileFormat::~FileFormat ( )

override

Destroys this FileFormat object.

Note

This destructor does not destroy or uninstall the actual image file format it refers to, which is part of the PixInsight core application. Only the managed alias object living in the caller module is destroyed.

Member Function Documentation

AllFormats()

static Array<FileFormat> pcl::FileFormat::AllFormats ( )

static

Returns a list with all installed file formats in the PixInsight core application.

CanEditPreferences()

bool pcl::FileFormat::CanEditPreferences ( ) const

overridevirtual

Returns true only if this file format implementation allows the user to edit specific format preferences.

If this function returns true, then the EditPreferences() procedure must be reimplemented in a derived class of MetaFileFormat by the module that implements this format.

Implements pcl::FileFormatBase.

CanRead()

bool pcl::FileFormat::CanRead ( ) const

overridevirtual

Returns true only if this file format implementation can read an entire image in a single operation.

Implements pcl::FileFormatBase.

CanReadIncrementally()

bool pcl::FileFormat::CanReadIncrementally ( ) const

overridevirtual

Returns true only if this file format implementation supports incremental read operations on image files.

Incremental read operations allow the PixInsight core application and other modules to load images by successive row strips.

Implements pcl::FileFormatBase.

CanStore16Bit()

bool pcl::FileFormat::CanStore16Bit ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 16-bit unsigned integer images

Implements pcl::FileFormatBase.

CanStore32Bit()

bool pcl::FileFormat::CanStore32Bit ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 32-bit unsigned integer images

Implements pcl::FileFormatBase.

CanStore64Bit()

bool pcl::FileFormat::CanStore64Bit ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 64-bit unsigned integer images

Implements pcl::FileFormatBase.

CanStore8Bit()

bool pcl::FileFormat::CanStore8Bit ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 8-bit unsigned integer images

Implements pcl::FileFormatBase.

CanStoreAlphaChannels()

bool pcl::FileFormat::CanStoreAlphaChannels ( ) const

overridevirtual

Returns true only if this file format implementation supports alpha channels.

Implements pcl::FileFormatBase.

CanStoreColorFilterArrays()

bool pcl::FileFormat::CanStoreColorFilterArrays ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve color filter array (CFA) descriptions.

Implements pcl::FileFormatBase.

CanStoreComplex()

bool pcl::FileFormat::CanStoreComplex ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 32-bit complex floating point images (IEEE 754 32-bit single precision format for components of complex pixel sample values).

Implements pcl::FileFormatBase.

CanStoreDComplex()

bool pcl::FileFormat::CanStoreDComplex ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 64-bit complex floating point images (IEEE 754 64-bit double precision format for components of complex pixel sample values).

Implements pcl::FileFormatBase.

CanStoreDisplayFunctions()

bool pcl::FileFormat::CanStoreDisplayFunctions ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve display function (aka screen transfer function, or STF) parameters.

Implements pcl::FileFormatBase.

CanStoreDouble()

bool pcl::FileFormat::CanStoreDouble ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 64-bit floating point real images (IEEE 754 64-bit double precision format for pixel sample values).

Implements pcl::FileFormatBase.

CanStoreFloat()

bool pcl::FileFormat::CanStoreFloat ( ) const

overridevirtual

Returns true only if this file format implementation can read/write 32-bit floating point real images (IEEE 754 32-bit single precision format for pixel sample values).

Implements pcl::FileFormatBase.

CanStoreGrayscale()

bool pcl::FileFormat::CanStoreGrayscale ( ) const

overridevirtual

Returns true only if this file format implementation can read/write grayscale pixel data.

Implements pcl::FileFormatBase.

CanStoreICCProfiles()

bool pcl::FileFormat::CanStoreICCProfiles ( ) const

overridevirtual

Returns true only if this file format implementation can embed/extract ICC color profiles.

Implements pcl::FileFormatBase.

CanStoreImageProperties()

bool pcl::FileFormat::CanStoreImageProperties ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve data properties associated with individual images.

See also

CanStoreProperties(), SupportsViewProperties()

Implements pcl::FileFormatBase.

CanStoreKeywords()

bool pcl::FileFormat::CanStoreKeywords ( ) const

overridevirtual

Returns true only if this file format implementation can embed/extract FITS header keyword collections.

Implements pcl::FileFormatBase.

CanStoreProperties()

bool pcl::FileFormat::CanStoreProperties ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve data properties associated with format instances or image files.

Note

Don't confuse this member function with CanStoreImageProperties(). This function returns true if the implementation can store properties associated with an entire file or format instance, while CanStoreImageProperties() returns true if the implementation can store properties associated with individual images.

See also

CanStoreImageProperties(), SupportsViewProperties()

Implements pcl::FileFormatBase.

CanStoreResolution()

bool pcl::FileFormat::CanStoreResolution ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve image resolution data.

Implements pcl::FileFormatBase.

CanStoreRGBColor()

bool pcl::FileFormat::CanStoreRGBColor ( ) const

overridevirtual

Returns true only if this file format implementation can read/write RGB color pixel data.

Implements pcl::FileFormatBase.

CanStoreRGBWS()

bool pcl::FileFormat::CanStoreRGBWS ( ) const

overridevirtual

Returns true only if this file format implementation can store/retrieve RGB working space data.

Implements pcl::FileFormatBase.

CanStoreThumbnails()

bool pcl::FileFormat::CanStoreThumbnails ( ) const

overridevirtual

Returns true only if this file format implementation can embed/extract thumbnail images.

Implements pcl::FileFormatBase.

CanWrite()

bool pcl::FileFormat::CanWrite ( ) const

overridevirtual

Returns true only if this file format implementation can write an entire image in a single operation.

Implements pcl::FileFormatBase.

CanWriteIncrementally()

bool pcl::FileFormat::CanWriteIncrementally ( ) const

overridevirtual

Returns true only if this file format implementation supports incremental write operations on image files.

Incremental write operations allow the PixInsight core application and other modules to write images by successive row strips.

Implements pcl::FileFormatBase.

Description()

String pcl::FileFormat::Description ( ) const

overridevirtual

Returns a brief description text for this file format.

This function should provide a simple, typically single-line, description of this image file format for quick reference. Example: "Flexible Image Transport System". The Implementation() member function has been designed to provide a more complete description of a format's functionality and capabilities.

Implements pcl::FileFormatBase.

DisposeFormatSpecificData()

void pcl::FileFormat::DisposeFormatSpecificData ( void *  data ) const

overridevirtual

Disposes a format-specific data block.

File formats that use format-specific data reimplement this function to destroy and deallocate, as appropriate, their own format-specific data structures.

This function will be called by the PixInsight core application with the data argument pointing to the beginning of a format-specific data block. This function will only be called after validation of the data block by ValidateFormatSpecificData().

Implements pcl::FileFormatBase.

DrizzleFiles()

static StringList pcl::FileFormat::DrizzleFiles ( const String &  dirPath, bool  recursive = false, bool  followLinks = true  )

static

Returns a list with the full file paths of all drizzle data files in a given directory of the local filesystem.

Parameters

dirPath	Path to an existing directory in the local filesystem, where drizzle data files will be looked for.
recursive	True to search for files recursively throughout the entire subtree rooted at dirPath. False to restrict the file search operation to existing files on dirPath. This parameter is false by default.
followLinks	True to follow symbolic links to directories and files, on platforms supporting symbolic links. This is true by default. This parameter is ignored on Windows.

Currently this function looks for files with the .drz (compatibility text drizzle format) and .xdrz (XML drizzle data format, XDRZ) suffixes.

See also

DrizzleData

EditPreferences()

bool pcl::FileFormat::EditPreferences ( ) const

overridevirtual

Handles a request to edit format preferences. Returns true if the preferences were successfully edited.

When implemented, this procedure should open a dialog box to let the user edit format-specific preferences and operating options. This function should only return true if the user accepts the new settings (e.g. by clicking the dialog's OK button).

Note

This member function will never be called if the CanEditPreferences() member function is not reimplemented to return true in a derived class of MetaFileFormat by the module that implements this file format.

Implements pcl::FileFormatBase.

EphemerisFiles()

static StringList pcl::FileFormat::EphemerisFiles ( const String &  dirPath, bool  recursive = false, bool  followLinks = true  )

static

Returns a list with the full file paths of all ephemeris data files in a given directory of the local filesystem.

Parameters

dirPath	Path to an existing directory in the local filesystem, where ephemeris data files will be looked for.
recursive	True to search for files recursively throughout the entire subtree rooted at dirPath. False to restrict the file search operation to existing files on dirPath. This parameter is false by default.
followLinks	True to follow symbolic links to directories and files, on platforms supporting symbolic links. This is true by default. This parameter is ignored on Windows.

Currently this function looks for files with the .xeph suffix (Extensible Ephemeris Data format, XEPH).

See also

EphemerisFile

FileExtensions()

StringList pcl::FileFormat::FileExtensions ( ) const

overridevirtual

Returns the list of file extensions associated to this file format.

The returned list must be a sequence of ".xxx...x" strings in priority order. Examples: ".fit", ".fits", ".fts".

Implements pcl::FileFormatBase.

Icon()

Bitmap pcl::FileFormat::Icon ( ) const

overridevirtual

Returns a large icon image that identifies this format.

The returned image is used to identify all instances of this format (e.g., images and files) in the core application's GUI. It is used on the Format Explorer window, on image icons of this format, and in general for every graphical item related to this format or to an instance of this format.

Implements pcl::FileFormatBase.

Implementation()

String pcl::FileFormat::Implementation ( ) const

overridevirtual

Returns a descriptive text about this implementation of a particular image file format.

This function must provide a brief but sufficiently informative description of this file format implementation. The returned description will appear on the Format Explorer window, and should provide information about how this format has been implemented in a module. Avoid too exhaustive descriptions that are better reserved for a technical manual. Avoid also describing a file format itself; the information given should not intend to replace an official/formal definition of an image format.

Descriptions of file format implementations are always printed on PixInsight consoles. This means that the text output functionality of the Console class can be used to format the string returned by this function. Refer to that class and its documentation for further information.

Implements pcl::FileFormatBase.

IsDeprecated()

bool pcl::FileFormat::IsDeprecated ( ) const

overridevirtual

Returns true only if this file format has been deprecated or declared obsolete on the PixInsight platform.

When this function returns true, the Status() member function should also return information about the current status of this file format, including an explanation of the reasons for deprecation.

Implements pcl::FileFormatBase.

IsSupportedFileFormatBySuffix()

static bool pcl::FileFormat::IsSupportedFileFormatBySuffix ( const String &  path, bool  toRead = false, bool  toWrite = false  )

static

Returns true iff the specified file suffix corresponds to an installed file format.

Parameters

path	A file path including a file suffix identifying an image format, such as ".xisf", ".jpg", etc. This parameter is case-insensitive. Existence of an actual file at the specified path is not verified.
toRead	True to identify an installed file format module able to read files.
toWrite	True to identify an installed file format module able to write files.

Note

The toRead and toWrite parameters are false by default, which means that no access restrictions are applied by default.

LocalNormalizationFiles()

static StringList pcl::FileFormat::LocalNormalizationFiles ( const String &  dirPath, bool  recursive = false, bool  followLinks = true  )

static

Returns a list with the full file paths of all local normalization data files in a given directory of the local filesystem.

Parameters

dirPath	Path to an existing directory in the local filesystem, where local normalization data files will be looked for.
recursive	True to search for files recursively throughout the entire subtree rooted at dirPath. False to restrict the file search operation to existing files on dirPath. This parameter is false by default.
followLinks	True to follow symbolic links to directories and files, on platforms supporting symbolic links. This is true by default. This parameter is ignored on Windows.

Currently this function looks for files with the .xnml suffix (XML local normalization data format, XNML).

See also

LocalNormalizationData

MimeTypes()

IsoStringList pcl::FileFormat::MimeTypes ( ) const

overridevirtual

Returns a list of MIME types corresponding to the data supported by this file format.

The returned list must be a sequence of "media_type/content_type" items approved by IANA (see http://www.iana.org/assignments/media-types/), for example: "image/fits", "application/fits".

Providing a list of MIME types is not mandatory, but highly recommended for all format support modules implementing standard (i.e., recognized by IANA) image formats.

Implements pcl::FileFormatBase.

Name()

IsoString pcl::FileFormat::Name ( ) const

overridevirtual

Returns the identifier of this file format (also known as the format name).

File format identifiers are unique, valid C identifiers. Examples: "FITS", "TIFF", "JPEG2000".

Implements pcl::FileFormatBase.

SmallIcon()

Bitmap pcl::FileFormat::SmallIcon ( ) const

overridevirtual

Returns a small icon image that identifies this format.

For details on format icon images, see the documentation for Icon().

Small icons are used on interface elements where screen space must be preserved. Two good examples are the Format Explorer window and the ImageContainer interface.

Implements pcl::FileFormatBase.

Status()

String pcl::FileFormat::Status ( ) const

overridevirtual

Returns a description of the current status of this file format implementation.

This function should return an empty string for normal file format implementations. Exceptions to this rule are obsolete or deprecated file formats (see the IsDeprecated() member function), deficient implementations, or other special cases where the user should be aware of important potential problems or limitations.

The output of this function should be essentially plain text with basic HTML tags. No console tags should be used.

Implements pcl::FileFormatBase.

SupportedImageFiles()

static StringList pcl::FileFormat::SupportedImageFiles ( const String &  dirPath, bool  toRead = false, bool  toWrite = false, bool  recursive = false, bool  followLinks = true  )

static

Returns a list with the full file paths of all supported image files in a given directory of the local filesystem.

Parameters

dirPath	Path to an existing directory in the local filesystem, where supported image files will be looked for.
toRead	True to select files supported for read operations.
toWrite	True to select files supported for write operations.
recursive	True to search for files recursively throughout the entire subtree rooted at dirPath. False to restrict the file search operation to existing files on dirPath. This parameter is false by default.
followLinks	True to follow symbolic links to directories and files, on platforms supporting symbolic links. This is true by default. This parameter is ignored on Windows.

Note

The toRead and toWrite parameters are false by default, which means that no access restrictions are applied by default.

SupportsCompression()

bool pcl::FileFormat::SupportsCompression ( ) const

overridevirtual

Returns true only if this file format implementation supports compression of pixel data.

This refers to compression of source pixels, not to native compression schemes used by some file formats.

For example, the compression schemes employed in the JPEG and JPEG2000 formats must not cause this member function to return true. The optional ZIP and LZW compressions used in TIFF are the exact kind of compressions that must cause this member function to return true.

Implements pcl::FileFormatBase.

SupportsMultipleImages()

bool pcl::FileFormat::SupportsMultipleImages ( ) const

overridevirtual

Returns true only if this file format implementation supports multiple images stored in a single file.

For example, multiple images (e.g., taken with different filters) can be stored in FITS files by means of FITS image extensions, forming a data cube of several images with the same dimensions, or even a collection of independent images.

Implements pcl::FileFormatBase.

SupportsViewProperties()

bool pcl::FileFormat::SupportsViewProperties ( ) const

overridevirtual

Returns true only if this file format implementation supports data properties of different data types such as Float64, UI32Vector, String, Complex32, etc.

If this member function returns true, a reimplementation of CanStoreProperties() and/or CanStoreImageProperties() (depending on format capabilities) must also return true, and the format must implement all property data types supported by View objects. For information on supported view property types, see the VTYPE_XXX predefined constants in PCL API headers.

This function should return false if this format only supports storage of BLOB properties, represented as ByteArray objects, or a limited subset of view property types.

See also

CanStoreProperties(), CanStoreImageProperties(), View::PropertyValue(), View::SetPropertyValue()

Implements pcl::FileFormatBase.

UsesFormatSpecificData()

bool pcl::FileFormat::UsesFormatSpecificData ( ) const

overridevirtual

Returns true only if this file format implementation uses format-specific data.

Format-specific data are preserved on a per-instance (say per-file) basis by the PixInsight application, who actually knows nothing about them.

Implements pcl::FileFormatBase.

ValidateFormatSpecificData()

bool pcl::FileFormat::ValidateFormatSpecificData ( const void *  data ) const

overridevirtual

Validates a format-specific data block.

File formats that use format-specific data reimplement this function to validate format-specific data structures. If this function returns true, that means that the passed data block is a valid format-specific data structure for this file format implementation.

This function will be called by the PixInsight core application for validation of the data block before calling FileFormatImplementation::SetFormatSpecificData() and DisposeFormatSpecificData().

Implements pcl::FileFormatBase.

Version()

uint32 pcl::FileFormat::Version ( ) const

overridevirtual

Returns a version number for this file format, encoded as a hexadecimal number.

For example, version 1.0.5 should be returned as 0x105, and version 3.11.5 as 0x3B5. The default return value is 0x100, corresponding to version 1.0.0.

Implements pcl::FileFormatBase.

---

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

• FileFormat.h