PCL
pcl::FileFormatBase Class Referenceabstract

Abstract base class for image file format descriptions. More...

#include <FileFormatBase.h>

+ Inheritance diagram for pcl::FileFormatBase:

Public Member Functions

 FileFormatBase ()
 
virtual ~FileFormatBase () noexcept(false)
 
virtual bool CanEditPreferences () const =0
 
virtual bool CanRead () const =0
 
virtual bool CanReadIncrementally () const =0
 
virtual bool CanStore16Bit () const =0
 
virtual bool CanStore32Bit () const =0
 
virtual bool CanStore64Bit () const =0
 
virtual bool CanStore8Bit () const =0
 
virtual bool CanStoreAlphaChannels () const =0
 
virtual bool CanStoreColorFilterArrays () const =0
 
virtual bool CanStoreComplex () const =0
 
virtual bool CanStoreDComplex () const =0
 
virtual bool CanStoreDisplayFunctions () const =0
 
virtual bool CanStoreDouble () const =0
 
virtual bool CanStoreFloat () const =0
 
virtual bool CanStoreGrayscale () const =0
 
virtual bool CanStoreICCProfiles () const =0
 
virtual bool CanStoreImageProperties () const =0
 
virtual bool CanStoreKeywords () const =0
 
virtual bool CanStoreProperties () const =0
 
virtual bool CanStoreResolution () const =0
 
virtual bool CanStoreRGBColor () const =0
 
virtual bool CanStoreRGBWS () const =0
 
virtual bool CanStoreThumbnails () const =0
 
virtual bool CanWrite () const =0
 
virtual bool CanWriteIncrementally () const =0
 
virtual String Description () const =0
 
virtual void DisposeFormatSpecificData (void *data) const =0
 
virtual bool EditPreferences () const =0
 
virtual StringList FileExtensions () const =0
 
virtual Bitmap Icon () const =0
 
virtual String Implementation () const =0
 
virtual bool IsDeprecated () const =0
 
virtual IsoStringList MimeTypes () const =0
 
virtual IsoString Name () const =0
 
virtual Bitmap SmallIcon () const =0
 
virtual String Status () const =0
 
virtual bool SupportsCompression () const =0
 
virtual bool SupportsMultipleImages () const =0
 
virtual bool SupportsViewProperties () const =0
 
virtual bool UsesFormatSpecificData () const =0
 
virtual bool ValidateFormatSpecificData (const void *data) const =0
 
virtual uint32 Version () const =0
 

Detailed Description

FileFormatBase defines a number of descriptive properties of a file format in the PixInsight platform.

FileFormatBase is an abstract base class of the MetaFileFormat and FileFormat instantiable classes. MetaFileFormat describes an installable file format, while the FileFormat class provides direct access to an installed file format through intermodule communication.

In more practical terms, modules defining new file formats must implement derived classes of MetaFileFormat, while FileFormat is used by modules requiring direct access to image files through installed file formats.

Note that the FileFormatBase, MetaFileFormat, FileFormat, FileFormatImplementation and FileFormatInstance classes are conceptually parallel to the ProcessBase, MetaProcess, Process, ProcessImplementation and ProcessInstance classes, respectively. This is just a reflection of the strong object orientation and modularity that characterize the PixInsight platform.

See also
MetaFileFormat, FileFormat, FileFormatImplementation, FileFormatInstance

Definition at line 95 of file FileFormatBase.h.

Constructor & Destructor Documentation

◆ FileFormatBase()

pcl::FileFormatBase::FileFormatBase ( )
inline

Constructs a FileFormatBase object.

Definition at line 102 of file FileFormatBase.h.

◆ ~FileFormatBase()

virtual pcl::FileFormatBase::~FileFormatBase ( )
inlinevirtualnoexcept

Virtual destructor.

Definition at line 109 of file FileFormatBase.h.

Member Function Documentation

◆ CanEditPreferences()

virtual bool pcl::FileFormatBase::CanEditPreferences ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanRead()

virtual bool pcl::FileFormatBase::CanRead ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanReadIncrementally()

virtual bool pcl::FileFormatBase::CanReadIncrementally ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStore16Bit()

virtual bool pcl::FileFormatBase::CanStore16Bit ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStore32Bit()

virtual bool pcl::FileFormatBase::CanStore32Bit ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStore64Bit()

virtual bool pcl::FileFormatBase::CanStore64Bit ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStore8Bit()

virtual bool pcl::FileFormatBase::CanStore8Bit ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreAlphaChannels()

virtual bool pcl::FileFormatBase::CanStoreAlphaChannels ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreColorFilterArrays()

virtual bool pcl::FileFormatBase::CanStoreColorFilterArrays ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreComplex()

virtual bool pcl::FileFormatBase::CanStoreComplex ( ) const
pure virtual

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).

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreDComplex()

virtual bool pcl::FileFormatBase::CanStoreDComplex ( ) const
pure virtual

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).

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreDisplayFunctions()

virtual bool pcl::FileFormatBase::CanStoreDisplayFunctions ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreDouble()

virtual bool pcl::FileFormatBase::CanStoreDouble ( ) const
pure virtual

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).

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreFloat()

virtual bool pcl::FileFormatBase::CanStoreFloat ( ) const
pure virtual

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).

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreGrayscale()

virtual bool pcl::FileFormatBase::CanStoreGrayscale ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreICCProfiles()

virtual bool pcl::FileFormatBase::CanStoreICCProfiles ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreImageProperties()

virtual bool pcl::FileFormatBase::CanStoreImageProperties ( ) const
pure virtual

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

See also
CanStoreProperties(), SupportsViewProperties()

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreKeywords()

virtual bool pcl::FileFormatBase::CanStoreKeywords ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreProperties()

virtual bool pcl::FileFormatBase::CanStoreProperties ( ) const
pure virtual

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()

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreResolution()

virtual bool pcl::FileFormatBase::CanStoreResolution ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreRGBColor()

virtual bool pcl::FileFormatBase::CanStoreRGBColor ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreRGBWS()

virtual bool pcl::FileFormatBase::CanStoreRGBWS ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanStoreThumbnails()

virtual bool pcl::FileFormatBase::CanStoreThumbnails ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanWrite()

virtual bool pcl::FileFormatBase::CanWrite ( ) const
pure virtual

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

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ CanWriteIncrementally()

virtual bool pcl::FileFormatBase::CanWriteIncrementally ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Description()

virtual String pcl::FileFormatBase::Description ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ DisposeFormatSpecificData()

virtual void pcl::FileFormatBase::DisposeFormatSpecificData ( void *  data) const
pure virtual

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().

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ EditPreferences()

virtual bool pcl::FileFormatBase::EditPreferences ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ FileExtensions()

virtual StringList pcl::FileFormatBase::FileExtensions ( ) const
pure virtual

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".

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Icon()

virtual Bitmap pcl::FileFormatBase::Icon ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Implementation()

virtual String pcl::FileFormatBase::Implementation ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ IsDeprecated()

virtual bool pcl::FileFormatBase::IsDeprecated ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ MimeTypes()

virtual IsoStringList pcl::FileFormatBase::MimeTypes ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Name()

virtual IsoString pcl::FileFormatBase::Name ( ) const
pure virtual

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".

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ SmallIcon()

virtual Bitmap pcl::FileFormatBase::SmallIcon ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Status()

virtual String pcl::FileFormatBase::Status ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ SupportsCompression()

virtual bool pcl::FileFormatBase::SupportsCompression ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ SupportsMultipleImages()

virtual bool pcl::FileFormatBase::SupportsMultipleImages ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ SupportsViewProperties()

virtual bool pcl::FileFormatBase::SupportsViewProperties ( ) const
pure virtual

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()

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ UsesFormatSpecificData()

virtual bool pcl::FileFormatBase::UsesFormatSpecificData ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ ValidateFormatSpecificData()

virtual bool pcl::FileFormatBase::ValidateFormatSpecificData ( const void *  data) const
pure virtual

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().

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.

◆ Version()

virtual uint32 pcl::FileFormatBase::Version ( ) const
pure virtual

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.

Implemented in pcl::MetaFileFormat, and pcl::FileFormat.


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