PCL
pcl::FileFormatInstance Class Reference

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())
 
FileFormatInstanceoperator= (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 FileFormatInstanceNull ()
 
- Static Public Member Functions inherited from pcl::UIObject
static UIObjectNull ()
 

Additional Inherited Members

- Protected Member Functions inherited from pcl::UIObject
 UIObject ()=default
 
 UIObject (const UIObject &x)
 
 UIObject (UIObject &&x)
 
UIObjectoperator= (const UIObject &x)
 
UIObjectoperator= (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
filePathPath 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.
hintsA 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 &lt;n&gt;" 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.
numberOfImagesThis 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:

bool Contains(const T &v) const noexcept
Definition: Array.h:1787
PropertyDescriptionArray ImagePropertyDescriptions()

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:

PropertyDescriptionArray PropertyDescriptions()

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
imagesReference 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.
filePathFile path to an existing file that will be opened.
hintsA 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]optionsReference 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]formatOptionsReference 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]bufferAddress of the destination sample buffer.
startRowFirst pixel row to read.
rowCountNumber of pixel rows to read.
channelChannel 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
propertyUnique identifier of the data property.
valueProperty 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() )
bool WriteImageProperty(const IsoString &property, const Variant &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
propertyUnique identifier of the data property.
valueProperty 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() )
bool WriteProperty(const IsoString &property, const Variant &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
bufferAddress of the source sample buffer.
startRowFirst pixel row to write.
rowCountNumber of pixel rows to write.
channelChannel 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: