PCL
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< FileFormatAllFormats ()
 
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
nameExtOrMimeA 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.
toReadWhen 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.
toWriteWhen 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 ...
}
FileFormat(const String &nameExtOrMime, bool toRead=false, bool toWrite=false)
32-bit floating point real image.
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
dirPathPath to an existing directory in the local filesystem, where drizzle data files will be looked for.
recursiveTrue 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.
followLinksTrue 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
dirPathPath to an existing directory in the local filesystem, where ephemeris data files will be looked for.
recursiveTrue 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.
followLinksTrue 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
pathA 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.
toReadTrue to identify an installed file format module able to read files.
toWriteTrue 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
dirPathPath to an existing directory in the local filesystem, where local normalization data files will be looked for.
recursiveTrue 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.
followLinksTrue 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
dirPathPath to an existing directory in the local filesystem, where supported image files will be looked for.
toReadTrue to select files supported for read operations.
toWriteTrue to select files supported for write operations.
recursiveTrue 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.
followLinksTrue 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: