Flux calibration data parser and generator. More...

#include <FluxCalibrationData.h>

Public Member Functions
	FluxCalibrationData ()=default

	FluxCalibrationData (const FluxCalibrationData &)=default

	FluxCalibrationData (const String &filePath)

	FluxCalibrationData (const XMLDocument &xml)

	FluxCalibrationData (const XMLElement &element)

	FluxCalibrationData (FluxCalibrationData &&)=default

virtual	~FluxCalibrationData ()

void	Clear ()

TimePoint	CreationTime () const

const DVector &	FluxScaleFactors () const

const DVector &	FluxScaleSigmas () const

const FVector &	MeanFWHMx () const

const FVector &	MeanFWHMy () const

FluxCalibrationData &	operator= (const FluxCalibrationData &)=default

FluxCalibrationData &	operator= (FluxCalibrationData &&)=default

void	Parse (const String &filePath)

void	Parse (const XMLDocument &xml)

void	Parse (const XMLElement &element)

double	ScaleNormalizationFactor () const

XMLDocument *	Serialize () const

void	SerializeToFile (const String &path) const

void	SetFluxScaleFactors (const DVector &v)

void	SetFluxScaleSigmas (const DVector &v)

void	SetMeanFWHMx (const FVector &v)

void	SetMeanFWHMy (const FVector &v)

void	SetScaleNormalizationFactor (double k)

void	SetStarCounts (const IVector &v)

void	SetTargetFilePath (const String &filePath)

void	SetVersion (uint32 v)

const IVector &	StarCounts () const

const String &	TargetFilePath () const

uint32	Version () const

Detailed Description

FluxCalibrationData implements support for the XML flux calibration data format (XFCL format, .xfcl file suffix).

Flux calibration is essential for critical tasks requiring accurate and robust estimates of statistical scale computed for deep-sky astronomical images. On the PixInsight platform, we have implemented absolute, universally comparable, spectrophotometry-based scale estimation based on stellar photometry and Gaia mean spectra provided by the Gaia DR3 catalog. The primary tool to generate these estimates and XFCL files is SpectrophotometricFluxCalibration (SPFC).

Absolute spectrophotometry-based scale estimates are currently required by the MultiscaleGradientCorrection process and are critically important for generating Multiscale All-Sky Reference Survey (MARS) databases.

See also: LocalNormalizationData, DrizzleData

Definition at line 99 of file FluxCalibrationData.h.

Constructor & Destructor Documentation

◆ FluxCalibrationData() [1/6]

pcl::FluxCalibrationData::FluxCalibrationData ( )

default

Default constructor. Constructs an empty FluxCalibrationData object.

◆ FluxCalibrationData() [2/6]

pcl::FluxCalibrationData::FluxCalibrationData ( const FluxCalibrationData & )

default

Copy constructor.

◆ FluxCalibrationData() [3/6]

pcl::FluxCalibrationData::FluxCalibrationData ( FluxCalibrationData && )

default

Move constructor.

◆ FluxCalibrationData() [4/6]

pcl::FluxCalibrationData::FluxCalibrationData ( const String & filePath )

inline

Constructs a new FluxCalibrationData instance by loading and parsing an existing file.

Parameters

filePath Path to an existing file that will be parsed. The file contents must be in XML flux calibration data format (normally, a file with the .xfcl suffix).

This constructor validates the data retrieved from the specified file. It throws the appropriate Error exceptions in the event of parsing errors or invalid data.

Definition at line 130 of file FluxCalibrationData.h.

◆ FluxCalibrationData() [5/6]

pcl::FluxCalibrationData::FluxCalibrationData ( const XMLDocument & xml )

inline

Constructs a new FluxCalibrationData instance by parsing a well-formed XML document.

Parameters

xml	Reference to the source XML document. This constructor expects an XML document in valid XFCL flux calibration data format (.xfcl).

This constructor validates the data retrieved from the specified XML document. It throws an Error exception in the event of an invalid document or invalid data.

Definition at line 147 of file FluxCalibrationData.h.

◆ FluxCalibrationData() [6/6]

pcl::FluxCalibrationData::FluxCalibrationData ( const XMLElement & element )

inline

Constructs a new FluxCalibrationData instance by parsing an XML element.

Parameters

element Reference to the source XML element. This constructor expects an XML document tree in valid XFCL flux calibration data format (.xfcl) rooted at this element.

This constructor validates the data retrieved from the specified XML element. It throws an Error exception in the event of invalid data.

Definition at line 163 of file FluxCalibrationData.h.

◆ ~FluxCalibrationData()

virtual pcl::FluxCalibrationData::~FluxCalibrationData ( )

inlinevirtual

Virtual destructor.

Definition at line 171 of file FluxCalibrationData.h.

Member Function Documentation

◆ Clear()

void pcl::FluxCalibrationData::Clear ( )

Clears all the flux calibration data transported by this instance, yielding an empty FluxCalibrationData object.

◆ CreationTime()

TimePoint pcl::FluxCalibrationData::CreationTime ( ) const

inline

Returns the UTC time this flux calibration data was created, or an invalid TimePoint instance if creation time information is not available.

Definition at line 420 of file FluxCalibrationData.h.

◆ FluxScaleFactors()

const DVector& pcl::FluxCalibrationData::FluxScaleFactors ( ) const

inline

Returns the vector of per-channel flux scale factors for the calibration target image represented by this instance.

Returns a reference to an empty vector if this object has not been initialized with valid flux calibration data.

See also: SetFluxScaleFactors()

Definition at line 220 of file FluxCalibrationData.h.

◆ FluxScaleSigmas()

const DVector& pcl::FluxCalibrationData::FluxScaleSigmas ( ) const

inline

Returns the vector of per-channel flux calibration dispersion estimates for the calibration target image represented by this instance.

Returns a reference to an empty vector if this object has not been initialized with valid flux calibration data.

See also: SetFluxScaleSigmas()

Definition at line 245 of file FluxCalibrationData.h.

◆ MeanFWHMx()

const FVector& pcl::FluxCalibrationData::MeanFWHMx ( ) const

inline

Returns the vector of per-channel X-axis, mean PSF full width at half maximum (FWHM) estimates for the calibration target image represented by this instance.

For each measured star, the X-axis corresponds to the major axis of the fitted elliptical point spread function. For mean flux calibration data results, a Gaussian PSF is assumed.

Returns a reference to an empty vector if this object has not been initialized with valid flux calibration data, or if PSF FWHM data is not available in this instance.

See also: SetMeanFWHMx()

Definition at line 276 of file FluxCalibrationData.h.

◆ MeanFWHMy()

const FVector& pcl::FluxCalibrationData::MeanFWHMy ( ) const

inline

Returns the vector of per-channel Y-axis, mean PSF full width at half maximum (FWHM) estimates for the calibration target image represented by this instance.

For each measured star, the Y-axis corresponds to the minor axis of the fitted elliptical point spread function. For mean flux calibration data results, a Gaussian PSF is assumed.

Returns a reference to an empty vector if this object has not been initialized with valid flux calibration data, or if PSF FWHM data is not available in this instance.

See also: SetMeanFWHMy()

Definition at line 308 of file FluxCalibrationData.h.

◆ operator=() [1/2]

FluxCalibrationData& pcl::FluxCalibrationData::operator= ( const FluxCalibrationData & )

default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

FluxCalibrationData& pcl::FluxCalibrationData::operator= ( FluxCalibrationData && )

default

Move assignment operator. Returns a reference to this object.

◆ Parse() [1/3]

void pcl::FluxCalibrationData::Parse ( const String & filePath )

Loads and parses a flux calibration data file.

Parameters

filePath Path to an existing file that will be parsed. The file contents must be in XML flux calibration data format (normally, a file with the .xfcl suffix).

All previous data transported by this instance will be replaced with new data acquired from the specified file.

This function validates the data retrieved from the specified file. It throws an Error exception in the event of parsing errors or invalid data.

◆ Parse() [2/3]

void pcl::FluxCalibrationData::Parse ( const XMLDocument & xml )

Parses a well-formed XML document.

Parameters

xml	Reference to the source XML document. This member function expects an XML document in valid XFCL flux calibration data format (.xfcl).

All previous data transported by this instance will be replaced with new data acquired from the specified XML contents.

This function validates the data retrieved from the specified XML document. It throws an Error exception in the event of an invalid document or invalid data.

◆ Parse() [3/3]

void pcl::FluxCalibrationData::Parse ( const XMLElement & element )

Parses an XML element.

Parameters

element Reference to the source XML element. This function expects an XML document tree in valid XFCL flux calibration data format (.xfcl) rooted at this element.

All previous data transported by this instance will be replaced with new data acquired from the specified XML contents.

This function validates the data retrieved from the specified XML element. It throws an Error exception in the event of invalid data.

◆ ScaleNormalizationFactor()

double pcl::FluxCalibrationData::ScaleNormalizationFactor ( ) const

inline

Returns the normalization factor applied to raw flux calibration scale factors.

Normalization allows us to generate flux scale factors within manageable ranges for typical deep-sky images, i.e., in [100,0.001] instead of [1e-7,1e-12], for example. In current versions of the SpectrophotometricFluxCalibration process, the normalization factor is 1.0e+08. Although it is unlikely to happen, the normalization factor might change in a future version. By including it in flux calibration data, we can ensure compatibility with future calibration data.

See also: SetScaleNormalizationFactor

Definition at line 370 of file FluxCalibrationData.h.

◆ Serialize()

XMLDocument* pcl::FluxCalibrationData::Serialize ( ) const

Serializes the flux calibration data transported by this object as a new XML document in .xfcl format.

The returned XMLDocument object has been allocated dynamically. The caller is responsible for destroying and deallocating it as appropriate.

◆ SerializeToFile()

void pcl::FluxCalibrationData::SerializeToFile ( const String & path ) const

Serializes the flux calibration data transported by this object as a new XML document file in .xfcl format. The file will be newly created at the specified file path.

Warning: If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ SetFluxScaleFactors()

void pcl::FluxCalibrationData::SetFluxScaleFactors ( const DVector & v )

inline

Sets a new vector of per-channel flux scale factors for the calibration target image represented by this instance.

See also: FluxScaleFactors()

Definition at line 231 of file FluxCalibrationData.h.

◆ SetFluxScaleSigmas()

void pcl::FluxCalibrationData::SetFluxScaleSigmas ( const DVector & v )

inline

Sets a new vector of per-channel flux calibration dispersion estimates for the calibration target image represented by this instance.

See also: FluxScaleSigmas()

Definition at line 256 of file FluxCalibrationData.h.

◆ SetMeanFWHMx()

void pcl::FluxCalibrationData::SetMeanFWHMx ( const FVector & v )

inline

Sets a new vector of per-channel X-axis, mean PSF full width at half maximum (FWHM) estimates for the calibration target image represented by this instance.

See also: MeanFWHMx()

Definition at line 288 of file FluxCalibrationData.h.

◆ SetMeanFWHMy()

void pcl::FluxCalibrationData::SetMeanFWHMy ( const FVector & v )

inline

Sets a new vector of per-channel Y-axis, mean PSF full width at half maximum (FWHM) estimates for the calibration target image represented by this instance.

See also: MeanFWHMy()

Definition at line 320 of file FluxCalibrationData.h.

◆ SetScaleNormalizationFactor()

void pcl::FluxCalibrationData::SetScaleNormalizationFactor ( double k )

inline

Defines the normalization factor applied to raw flux calibration scale factors.

Calling this member function is not necessary for generation of new flux calibration data if the default normalization factor is used (see the __PCL_SPFC_NORMALIZATION_FACTOR macro definition).

See also: ScaleNormalizationFactor()

Definition at line 385 of file FluxCalibrationData.h.

◆ SetStarCounts()

void pcl::FluxCalibrationData::SetStarCounts ( const IVector & v )

inline

Sets a new vector of per-channel measured star counts for the calibration target image represented by this instance.

See also: StarCounts()

Definition at line 351 of file FluxCalibrationData.h.

◆ SetTargetFilePath()

void pcl::FluxCalibrationData::SetTargetFilePath ( const String & filePath )

inline

Sets the path to the flux calibration target image represented by this instance.

See also: TargetFilePath()

Definition at line 206 of file FluxCalibrationData.h.

References pcl::File::FullPath().

◆ SetVersion()

void pcl::FluxCalibrationData::SetVersion ( uint32 v )

inline

Sets a version number for the flux calibration data in this instance.

See also: Version()

Definition at line 411 of file FluxCalibrationData.h.

◆ StarCounts()

const IVector& pcl::FluxCalibrationData::StarCounts ( ) const

inline

Returns the vector of per-channel measured star counts for the calibration target image represented by this instance.

Star counts refer to the sets of stars used for the calculation of robust flux calibration factors. Note that this typically includes outlier rejection procedures, so the actual numbers of measured stars are usually larger than the values returned by this function.

Returns a reference to an empty vector if this object has not been initialized with valid flux calibration data, or if star count data is not available in this instance.

See also: SetStarCounts()

Definition at line 340 of file FluxCalibrationData.h.

◆ TargetFilePath()

const String& pcl::FluxCalibrationData::TargetFilePath ( ) const

inline

Returns the full path to the flux calibration target image represented by this instance.

The file identified by this function stores the input image of the flux calibration task, e.g. as processed by the SpectrophotometricFluxCalibration (SPFC) tool.

See also: SetSourceFilePath()

Definition at line 195 of file FluxCalibrationData.h.

◆ Version()

uint32 pcl::FluxCalibrationData::Version ( ) const

inline

Returns a version number for the flux calibration data in this instance.

The value returned by this function normally corresponds to the version of the SpectrophotometricFluxCalibration process used to generate the flux calibration data. This version number can be useful to ensure backward compatibility in future implementations.

See also: SetVersion()

Definition at line 401 of file FluxCalibrationData.h.

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

FluxCalibrationData.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FluxCalibrationData() [1/6]

◆ FluxCalibrationData() [2/6]

◆ FluxCalibrationData() [3/6]

◆ FluxCalibrationData() [4/6]

◆ FluxCalibrationData() [5/6]

◆ FluxCalibrationData() [6/6]

◆ ~FluxCalibrationData()

Member Function Documentation

◆ Clear()

◆ CreationTime()

◆ FluxScaleFactors()

◆ FluxScaleSigmas()

◆ MeanFWHMx()

◆ MeanFWHMy()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Parse() [1/3]

◆ Parse() [2/3]

◆ Parse() [3/3]

◆ ScaleNormalizationFactor()

◆ Serialize()

◆ SerializeToFile()

◆ SetFluxScaleFactors()

◆ SetFluxScaleSigmas()

◆ SetMeanFWHMx()

◆ SetMeanFWHMy()

◆ SetScaleNormalizationFactor()

◆ SetStarCounts()

◆ SetTargetFilePath()

◆ SetVersion()

◆ StarCounts()

◆ TargetFilePath()

◆ Version()