Drizzle integration data parser and generator. More...

#include <DrizzleData.h>

Public Types
using	point_list = Array< DPoint >

using	spline = vector_spline::spline

using	vector_spline = PointSurfaceSpline

using	weight_vector = Array< float >

Public Member Functions
	DrizzleData ()=default

	DrizzleData (const DrizzleData &)=default

	DrizzleData (const String &filePath, DrizzleParserOptions options=DrizzleParserOptions())

	DrizzleData (const XMLDocument &xml, DrizzleParserOptions options=DrizzleParserOptions())

	DrizzleData (const XMLElement &element, DrizzleParserOptions options=DrizzleParserOptions())

	DrizzleData (DrizzleData &&)=default

virtual	~DrizzleData ()

const point_list &	AdaptiveNormalizationCoordinates () const

const MultiVector &	AdaptiveNormalizationLocationVectors () const

const vector_spline &	AlignmentInverseSplines () const

const Matrix &	AlignmentMatrix () const

const DPoint &	AlignmentOrigin () const

const vector_spline &	AlignmentSplines () const

const String &	AlignmentTargetFilePath () const

int	CFASourceChannel () const

const String &	CFASourceFilePath () const

const String &	CFASourcePattern () const

void	Clear ()

void	ClearIntegrationData ()

TimePoint	CreationTime () const

void	DisableCompression (bool disable=true)

void	EnableCompression (bool enable=true)

void	GetAdaptiveNormalizationScaleVectors (MultiVector &sLow, MultiVector &sHigh) const

void	GetAdaptiveNormalizationZeroOffsetVectors (MultiVector &mLow, MultiVector &mHigh) const

void	GetLocalDistortionModel (point_list &P1, point_list &D2, point_list &P2, point_list &D1, weight_vector &W, int &order, float &regularization, bool &extrapolate)

bool	HasAdaptiveNormalizationData () const

bool	HasAlignmentInverseSplines () const

bool	HasAlignmentMatrix () const

bool	HasAlignmentSplines () const

bool	HasImageWeightsData () const

bool	HasIntegrationData () const

bool	HasLocalDistortionModel () const

bool	HasRejectionData () const

bool	IsCompressionEnabled () const

bool	IsRejected (const Point &position, int channel=0) const

const DVector &	Location () const

const String &	Metadata () const

int	NumberOfChannels () const

DrizzleData &	operator= (const DrizzleData &)=default

DrizzleData &	operator= (DrizzleData &&)=default

void	Parse (const String &filePath, DrizzleParserOptions options=DrizzleParserOptions())

void	Parse (const XMLDocument &xml, DrizzleParserOptions options=DrizzleParserOptions())

void	Parse (const XMLElement &element, DrizzleParserOptions options=DrizzleParserOptions())

double	Pedestal () const

int	ReferenceHeight () const

const DVector &	ReferenceLocation () const

int	ReferenceWidth () const

const UI64Vector &	RejectionHighCount () const

const UI64Vector &	RejectionLowCount () const

const UInt8Image &	RejectionMap () const

const DVector &	Scale () const

XMLDocument *	Serialize () const

void	SerializeToFile (const String &path) const

void	SetAdaptiveNormalizationCoordinates (const point_list &points)

void	SetAdaptiveNormalizationLocationVectors (const MultiVector &m)

void	SetAdaptiveNormalizationScaleVectors (const MultiVector &sLow, const MultiVector &sHigh)

void	SetAdaptiveNormalizationZeroOffsetVectors (const MultiVector &mLow, const MultiVector &mHigh)

void	SetAlignmentInverseSplines (const vector_spline &Sinv)

void	SetAlignmentMatrix (const Matrix &H)

void	SetAlignmentOrigin (const DPoint &p0)

void	SetAlignmentSplines (const vector_spline &S)

void	SetAlignmentTargetFilePath (const String &filePath)

void	SetCFASourceChannel (int channel)

void	SetCFASourceFilePath (const String &filePath)

void	SetCFASourcePattern (const String &cfaPattern)

void	SetLocation (const DVector &v)

void	SetMetadata (const String &metadata)

void	SetPedestal (double p)

void	SetReferenceDimensions (int width, int height)

void	SetReferenceLocation (const DVector &v)

void	SetRejectionMap (const UInt8Image &map)

void	SetScale (const DVector &v)

void	SetSourceFilePath (const String &filePath)

void	SetWeight (const DVector &v)

const String &	SourceFilePath () const

const DVector &	Weight () const

Detailed Description

DrizzleData implements support for the XML drizzle data format (XDRZ format, .xdrz file suffix).

A drizzle image integration process has been formalized as the following chain of subtasks on the PixInsight/PCL platform:

1. Demosaicing. Only required if the input data set has been mosaiced with a color filter array (CFA), such as a Bayer or X-Trans filter.

2. Image registration. Generates image alignment information in the form of alignment matrices (projective transformations) and/or two-dimensional surface splines for arbitrary distortion correction.

3. Image integration. Generates statistical data for each channel of the integrated image. This includes estimates of location and scale, statistical weights and pixel rejection data.

4. Drizzle integration. The input data for the drizzle algorithm is the input image for subtasks 1 (CFA drizzle) or 2 (normal drizzle). The information generated by subtasks 2 and 3 is used to perform a drizzle image integration process by inverse coordinate projection with image weighting, image normalization, and pixel rejection.

An XDRZ file stores all the data generated by the above drizzle integration subtasks as an XML document. The DrizzleData class is a high-level interface for parsing and generation of these special files.

This class also implements an internal read-only compatibility layer with the old plain text drizzle data format (.drz file suffix) used by versions of PixInsight before the 1.8.5 standard distribution. By using the class constructor or the Parse() member function to load and parse an existing file, the correct file format is detected automatically.

See also: LocalNormalizationData, FluxCalibrationData

Definition at line 142 of file DrizzleData.h.

Member Typedef Documentation

◆ point_list

using pcl::DrizzleData::point_list = Array<DPoint>

An ordered list of image coordinates. Used to store reference image coordinates or image displacements in distortion models. Also used to store interpolation node coordinates for adaptive normalization.

Definition at line 164 of file DrizzleData.h.

◆ spline

using pcl::DrizzleData::spline = vector_spline::spline

Represents a coordinate interpolating/approximating surface spline used for image registration with arbitrary distortion correction.

Definition at line 157 of file DrizzleData.h.

◆ vector_spline

using pcl::DrizzleData::vector_spline = PointSurfaceSpline

Represents a vector surface spline interpolation/approximation in two dimensions. This class is used to implement image alignment with arbitrary distortion correction.

Definition at line 151 of file DrizzleData.h.

◆ weight_vector

using pcl::DrizzleData::weight_vector = Array<float>

An ordered list of statistical weights corresponding to points in a distortion model.

Definition at line 170 of file DrizzleData.h.

Constructor & Destructor Documentation

◆ DrizzleData() [1/6]

pcl::DrizzleData::DrizzleData ( )

default

Default constructor. Constructs an empty DrizzleData object.

◆ DrizzleData() [2/6]

pcl::DrizzleData::DrizzleData ( const DrizzleData & )

default

Copy constructor.

◆ DrizzleData() [3/6]

pcl::DrizzleData::DrizzleData ( DrizzleData && )

default

Move constructor.

◆ DrizzleData() [4/6]

pcl::DrizzleData::DrizzleData	(	const String &	filePath,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

inline

Constructs a new DrizzleData instance by loading and parsing a file.

Parameters

filePath	Path to an existing file that will be parsed. The file contents can be in XML drizzle data format (normally, a file with the .xdrz suffix), or in old plain text format (typically with the .drz suffix). This constructor will detect the format in use from the first bytes of the file, and will decode it correspondingly.
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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 206 of file DrizzleData.h.

◆ DrizzleData() [5/6]

pcl::DrizzleData::DrizzleData	(	const XMLDocument &	xml,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

inline

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

Parameters

xml	Reference to the source XML document. This constructor expects an XML document in valid XML drizzle data format (.xdrz).
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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 227 of file DrizzleData.h.

◆ DrizzleData() [6/6]

pcl::DrizzleData::DrizzleData	(	const XMLElement &	element,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

inline

Constructs a new DrizzleData instance by parsing an XML element.

Parameters

element	Reference to the source XML element. This constructor expects an XML document tree in valid XML drizzle data format (.xdrz) rooted at this element.
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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 246 of file DrizzleData.h.

◆ ~DrizzleData()

virtual pcl::DrizzleData::~DrizzleData ( )

inlinevirtual

Virtual destructor.

Definition at line 254 of file DrizzleData.h.

Member Function Documentation

◆ AdaptiveNormalizationCoordinates()

const point_list& pcl::DrizzleData::AdaptiveNormalizationCoordinates ( ) const

inline

Returns the vector of adaptive normalization node coordinates.

Adaptive normalization is based on surface interpolation of location and scale estimates computed for regions of interest distributed over source and reference images. This function returns the list of 2-D interpolation node coordinates. See GetAdaptiveNormalizationScaleVectors() for a complete description of the adaptive output normalization procedure.

See also: SetAdaptiveNormalizationCoordinates()

Definition at line 825 of file DrizzleData.h.

◆ AdaptiveNormalizationLocationVectors()

const MultiVector& pcl::DrizzleData::AdaptiveNormalizationLocationVectors ( ) const

inline

Returns the vectors of per-channel adaptive estimates of location for the drizzle source image represented by this instance.

See GetAdaptiveNormalizationScaleVectors() for a complete description of the adaptive output normalization procedure.

Typically, the components of the multivector structure returned by this function are median values, or similar robust estimates of location, computed on a regular grid for each channel of the image identified by AlignmentTargetFilePath(). These estimates are normally generated by a regular integration task.

See also: SetAdaptiveNormalizationLocationVectors()

Definition at line 857 of file DrizzleData.h.

◆ AlignmentInverseSplines()

const vector_spline& pcl::DrizzleData::AlignmentInverseSplines ( ) const

inline

Returns the inverse vector surface spline interpolation/approximation device in two dimensions for the drizzle source image represented by this instance. These splines define an inverse image registration transformation with corrections for arbitrary distortions.

See also: SetAlignmentInverseSplines(), SetAlignmentSplines()

Definition at line 572 of file DrizzleData.h.

◆ AlignmentMatrix()

const Matrix& pcl::DrizzleData::AlignmentMatrix ( ) const

inline

Returns the 3x3 alignment matrix for the drizzle source image represented by this instance. The returned matrix defines a projective geometric transformation, also known as homography.

See also: SetAlignmentMatrix()

Definition at line 500 of file DrizzleData.h.

◆ AlignmentOrigin()

const DPoint& pcl::DrizzleData::AlignmentOrigin ( ) const

inline

Returns the origin of image alignment coordinates. The returned point corresponds to image coordinates {0,0} in the coordinate system used for image registration.

See also: SetAlignmentOrigin()

Definition at line 472 of file DrizzleData.h.

◆ AlignmentSplines()

const vector_spline& pcl::DrizzleData::AlignmentSplines ( ) const

inline

Returns the vector surface spline interpolation/approximation device in two dimensions for the drizzle source image represented by this instance. These splines define an image registration transformation with corrections for arbitrary distortions.

See also: SetAlignmentSplines(), SetAlignmentInverseSplines()

Definition at line 535 of file DrizzleData.h.

◆ AlignmentTargetFilePath()

const String& pcl::DrizzleData::AlignmentTargetFilePath ( ) const

inline

Returns the full path to the registered image file corresponding to the drizzle source image represented by this instance, or an empty string if that file path is not available.

The file identified by this function stores the output image of the image registration task. This file can be used as input for a regular (non-drizzle) integration task.

Note: This file should not be used as input for drizzle integration, since it has already been registered and interpolated. Use SourceFilePath() or CFASourceFilePath() as input for drizzle or CFA drizzle, respectively.

See also: SetAlignmentTargetFilePath()

Definition at line 408 of file DrizzleData.h.

◆ CFASourceChannel()

int pcl::DrizzleData::CFASourceChannel ( ) const

inline

Returns the channel index selected for the CFA mosaiced/unregistered image file corresponding to the drizzle source image represented by this instance.

The returned value is the zero-based index of an image channel in a color filter array (CFA) source frame, where typically 0 corresponds to red, 1 to green and 2 to blue. This member function returns a value < 0 if no channel index has been defined.

The CFA channel index can be defined for drizzle integration of separate color components working with color filter array (CFA) images. This is useful for correction of non-isotropic channel misalignments, such as those caused by chromatic aberration or atmospheric dispersion, by computing image registration transformations with distortion corrections among color components for each source frame. When a channel index has been defined, the final CFA drizzle integration generates a monochrome single-channel image instead of an RGB image.

See also: SetCFASourceChannel(), CFASourceFilePath(), CFASourcePattern()

Definition at line 371 of file DrizzleData.h.

◆ CFASourceFilePath()

const String& pcl::DrizzleData::CFASourceFilePath ( ) const

inline

Returns the full path to the mosaiced/unregistered image file corresponding to the drizzle source image represented by this instance.

The file identified by this function stores the input image of the image demosaicing task. This file can be used as input for a CFA drizzle integration task.

See also: SetCFASourceFilePath(), CFASourcePattern(), CFASourceChannel()

Definition at line 304 of file DrizzleData.h.

◆ CFASourcePattern()

const String& pcl::DrizzleData::CFASourcePattern ( ) const

inline

Returns a string representation of the color filter array (CFA) used by the mosaiced/unregistered image file corresponding to the drizzle source image represented by this instance.

The CFA corresponds to the file represented by CFASourceFilePath(). For the standard Bayer filters, this function returns "RGGB", "BGGR", "GBRG", and "GRBG".

See also: SetCFASourcePattern(), CFASourceChannel(), CFASourceFilePath()

Definition at line 331 of file DrizzleData.h.

◆ Clear()

void pcl::DrizzleData::Clear ( )

Clears all drizzle integration data transported by this instance, yielding an empty DrizzleData object.

◆ ClearIntegrationData()

void pcl::DrizzleData::ClearIntegrationData ( )

Clears the image integration data transported by this instance. This includes statistical location and scale estimates for image normalization, image weights, pixel rejection data, and adaptive normalization data.

◆ CreationTime()

TimePoint pcl::DrizzleData::CreationTime ( ) const

inline

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

Definition at line 1188 of file DrizzleData.h.

◆ DisableCompression()

void pcl::DrizzleData::DisableCompression ( bool disable = true )

inline

Disables compression of serialized drizzle data.

See also: IsCompressionEnabled(), EnableCompression()

Definition at line 1298 of file DrizzleData.h.

◆ EnableCompression()

void pcl::DrizzleData::EnableCompression ( bool enable = true )

inline

Enables compression of serialized drizzle data.

See also: IsCompressionEnabled(), DisableCompression()

Definition at line 1288 of file DrizzleData.h.

◆ GetAdaptiveNormalizationScaleVectors()

void pcl::DrizzleData::GetAdaptiveNormalizationScaleVectors	(	MultiVector &	sLow,
		MultiVector &	sHigh
	)		const

inline

Provides the vectors of per-channel adaptive scale factors for the drizzle source image represented by this instance.

Parameters

[out]	sLow	Reference to a multivector where a copy of the current set of low adaptive scale factor vectors will be stored.
[out]	sHigh	Reference to a multivector where a copy of the current set of high adaptive scale factor vectors will be stored.

For a channel index c and position vector i on a given input drizzle integration image, the adaptive normalization function is given by:

v'(c,i) = v(c,i) * (a*U(S0(c,i)) + (1-a)*U(S1(c,i)))
                 + (a*U(Z0(c,i)) + (1-a)*U(Z1(c,i)))

where:

S0 is a matrix of low adaptive scale factors,
S1 is a matrix of high adaptive scale factors,
Z0 is a matrix of low adaptive zero offset coefficients,
Z1 is a matrix of high adaptive zero offset coefficients,
U is a scale-dependent interpolation functional,
v is the source pixel value,
v' is the resulting normalized pixel value,
a is an indicator function given by:

a = 1   if v(c,i) ≤ U(L(c,i))
a = 0   if v(c,i) > U(L(c,i))

and L is a matrix of adaptive location estimates.

Typically, the components of the multivector structures provided by this function are the result of dividing reference scale estimates by robust estimates of dispersion, such as MAD or the square root of the biweight midvariance, among many others, computed for each channel of the image identified by AlignmentTargetFilePath(). Scale factors are normally generated by a regular integration task.

See also: SetAdaptiveNormalizationScaleVectors()

Definition at line 922 of file DrizzleData.h.

◆ GetAdaptiveNormalizationZeroOffsetVectors()

void pcl::DrizzleData::GetAdaptiveNormalizationZeroOffsetVectors	(	MultiVector &	mLow,
		MultiVector &	mHigh
	)		const

inline

Provides the vectors of per-channel adaptive zero offset coefficients for the drizzle source image represented by this instance.

Parameters

[out]	mLow	Reference to a multivector where a copy of the current set of low adaptive zero offset coefficient vectors will be stored.
[out]	mHigh	Reference to a multivector where a copy of the current set of high adaptive zero offset coefficient vectors will be stored.

See GetAdaptiveNormalizationScaleVectors() for a complete description of the output adaptive normalization procedure.

See also: SetAdaptiveNormalizationZeroOffsetVectors()

Definition at line 958 of file DrizzleData.h.

◆ GetLocalDistortionModel()

void pcl::DrizzleData::GetLocalDistortionModel	(	point_list &	P1,
		point_list &	D2,
		point_list &	P2,
		point_list &	D1,
		weight_vector &	W,
		int &	order,
		float &	regularization,
		bool &	extrapolate
	)

inline

Stores a copy of the local distortion model in the specified arrays.

Parameters

[out]	P1	Reference to an array of points where the function will store a copy of the reference image coordinates of the local distortion model.
[out]	D2	Reference to an array of points where the function will store a copy of the set of pixels displacements of the local distortion model.
[out]	P2	Reference to an array of points where the function will store a copy of the reference image coordinates of the inverse local distortion model.
[out]	D1	Reference to an array of points where the function will store a copy of the set of pixels displacements of the inverse local distortion model.
[out]	W	Reference to an array of scalars where the function will store a copy of the set of statistical weights associated with the local distortion model. This array can be empty if the local distortion model is unweighted.
	order	Reference to a variable that will be assigned the derivability order for surface interpolation generation. Normally this is a surface spline derivative order.
	regularization	Reference to a variable that will be assigned the recommended regularization factor for surface interpolation generation. Normally this is a thin plate spline smoothness factor.
	extrapolate	Reference to a variable that will be assigned true if the local distortion model has to be extrapolated over the entire reference image; false if the model can only be interpolated within the containing rectangle of the set P.

If this instance does not transport a valid local distortion model, the specified arrays P1, D2, P2 and D1 will be empty after calling this function.

Deprecated:: This function is deprecated. It is kept only to support existing drizzle data files and dependent applications. This function should not be used in newly produced code unless strictly necessary for backwards compatibility.

See also: SetLocalDistortionModel(), HasLocalDistortionModel()

Definition at line 653 of file DrizzleData.h.

◆ HasAdaptiveNormalizationData()

bool pcl::DrizzleData::HasAdaptiveNormalizationData ( ) const

inline

Returns true iff this instance transports adaptive normalization data, i.e. vectors of adaptive normalization coordinates and multivectors of adaptive normalization location estimates, scale factors and zero offset coefficients.

Definition at line 983 of file DrizzleData.h.

◆ HasAlignmentInverseSplines()

bool pcl::DrizzleData::HasAlignmentInverseSplines ( ) const

inline

Returns true iff this instance defines an inverse vector surface spline interpolation/approximation device.

See also: AlignmentInverseSplines(), HasAlignmentSplines(), HasAlignmentMatrix()

Definition at line 596 of file DrizzleData.h.

◆ HasAlignmentMatrix()

bool pcl::DrizzleData::HasAlignmentMatrix ( ) const

inline

Returns true iff this instance defines a 3x3 alignment matrix for the projective image registration transformation.

See also: AlignmentMatrix(), HasAlignmentSplines()

Definition at line 522 of file DrizzleData.h.

◆ HasAlignmentSplines()

bool pcl::DrizzleData::HasAlignmentSplines ( ) const

inline

Returns true iff this instance defines a vector surface spline interpolation/approximation device.

See also: AlignmentSplines(), HasAlignmentInverseSplines(), HasAlignmentMatrix()

Definition at line 559 of file DrizzleData.h.

◆ HasImageWeightsData()

bool pcl::DrizzleData::HasImageWeightsData ( ) const

inline

Returns true iff this DrizzleData object transports per-channel statistical image weights. If no weight information is available, the Weight() member function will return a reference to an internal vector with all components set to one.

Definition at line 1061 of file DrizzleData.h.

◆ HasIntegrationData()

bool pcl::DrizzleData::HasIntegrationData ( ) const

inline

Returns true iff this DrizzleData object transports image integration data for normalization and image combination. This includes at least location and reference location estimates, and optionally (but usually present) scaling factors and statistical image weights.

Definition at line 1050 of file DrizzleData.h.

◆ HasLocalDistortionModel()

bool pcl::DrizzleData::HasLocalDistortionModel ( ) const

inline

Returns true iff this instance defines a local distortion model consisting of a list of reference points and their corresponding pixel displacements in image coordinates.

Deprecated:: This function is deprecated. It is kept only to support existing drizzle data files and dependent applications. This function should not be used in newly produced code unless strictly necessary for backwards compatibility.

Definition at line 678 of file DrizzleData.h.

◆ HasRejectionData()

bool pcl::DrizzleData::HasRejectionData ( ) const

inline

Returns true iff pixel rejection information is available for the drizzle image represented by this instance.

Definition at line 1179 of file DrizzleData.h.

◆ IsCompressionEnabled()

bool pcl::DrizzleData::IsCompressionEnabled ( ) const

inline

Returns true if drizzle data compression is enabled for serializations performed with this object.

Drizzle data compression is enabled by default for newly constructed DrizzleData objects. Currently the LZ4 compression codec is applied for serialization of pixel rejection data.

See also: EnableCompression(), DisableCompression()

Definition at line 1278 of file DrizzleData.h.

◆ IsRejected()

bool pcl::DrizzleData::IsRejected	(	const Point &	position,
		int	channel = `0`
	)		const

inline

Returns true iff the pixel at the specified pixel coordinates has been rejected for the drizzle source image represented by this instance.

See also: RejectionMap(), HasRejectionData()

Definition at line 1156 of file DrizzleData.h.

◆ Location()

const DVector& pcl::DrizzleData::Location ( ) const

inline

Returns the vector of per-channel robust estimates of location for the drizzle source image represented by this instance.

See Scale() for a description of the output normalization procedure.

Typically, the components of the vector returned by this function are median values, or similar robust estimates of location, computed for each channel of the image identified by AlignmentTargetFilePath(). These estimates are normally generated by a regular integration task.

See also: SetLocation(), ReferenceLocation(), Scale(), AdaptiveNormalizationLocation()

Definition at line 719 of file DrizzleData.h.

◆ Metadata()

const String& pcl::DrizzleData::Metadata ( ) const

inline

Returns a string serialization of metadata items corresponding to the drizzle source image represented by this instance. Metadata items are normally generated and serialized by a regular integration task.

See also: SetMetadata()

Definition at line 690 of file DrizzleData.h.

◆ NumberOfChannels()

int pcl::DrizzleData::NumberOfChannels ( ) const

inline

Returns the number of channels or pixel sample planes in the image represented by this instance.

Definition at line 460 of file DrizzleData.h.

◆ operator=() [1/2]

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

default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

DrizzleData& pcl::DrizzleData::operator= ( DrizzleData && )

default

Move assignment operator. Returns a reference to this object.

◆ Parse() [1/3]

void pcl::DrizzleData::Parse	(	const String &	filePath,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

Loads and parses a drizzle data file.

Parameters

filePath	Path to an existing file that will be parsed. The file contents can be in XML drizzle data format (normally, a file with the .xdrz suffix), or in old plain text format (typically with the .drz suffix). This function will detect the format in use from the first bytes read from the file, and will decode it correspondingly.
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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::DrizzleData::Parse	(	const XMLDocument &	xml,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

Parses a well-formed XML document.

Parameters

xml	Reference to the source XML document. This member function expects an XML document in valid XML drizzle data format (.xdrz).
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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::DrizzleData::Parse	(	const XMLElement &	element,
		DrizzleParserOptions	options = `DrizzleParserOptions()`
	)

Parses an XML element.

Parameters

element	Reference to the source XML element. This member function expects an XML document tree in valid XML drizzle data format (.xdrz) rooted at this element.
options	Optional set of flags controlling the way drizzle data are parsed and verified. See the DrizzleParserOption namespace for more information.

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.

◆ Pedestal()

double pcl::DrizzleData::Pedestal ( ) const

inline

Returns a positive value in the range [0,1] to be subtracted from the image represented by this instance.

Definition at line 997 of file DrizzleData.h.

◆ ReferenceHeight()

int pcl::DrizzleData::ReferenceHeight ( ) const

inline

Returns the height in pixels of the registration reference image.

See also: ReferenceWidth(), SetReferenceDimensions()

Definition at line 439 of file DrizzleData.h.

◆ ReferenceLocation()

const DVector& pcl::DrizzleData::ReferenceLocation ( ) const

inline

Returns the vector of per-channel robust estimates of location for the reference integration image associated with the drizzle source image represented by this instance.

See Scale() for a description of the output normalization procedure.

Typically, the components of the vector returned by this function are median values, or similar robust estimates of location, computed for each channel of an image used as reference by a regular integration task.

See also: SetLocation(), ReferenceLocation(), Scale(), ReferenceAdaptiveNormalizationLocation()

Definition at line 751 of file DrizzleData.h.

◆ ReferenceWidth()

int pcl::DrizzleData::ReferenceWidth ( ) const

inline

Returns the width in pixels of the registration reference image.

See also: ReferenceHeight(), SetReferenceDimensions()

Definition at line 429 of file DrizzleData.h.

◆ RejectionHighCount()

const UI64Vector& pcl::DrizzleData::RejectionHighCount ( ) const

inline

Returns the vector of per-channel high pixel rejection counts for the drizzle source image represented by this instance.

The components of the returned vector are the total amounts of rejected high pixels for each channel of the image identified by AlignmentTargetFilePath(). Pixel rejection counts are normally generated by a regular image integration task.

See also: RejectionLowCount(), RejectionMap()

Definition at line 1093 of file DrizzleData.h.

◆ RejectionLowCount()

const UI64Vector& pcl::DrizzleData::RejectionLowCount ( ) const

inline

Returns the vector of per-channel low pixel rejection counts for the drizzle source image represented by this instance.

The components of the returned vector are the total amounts of rejected low pixels for each channel of the image identified by AlignmentTargetFilePath(). Pixel rejection counts are normally generated by a regular image integration task.

See also: RejectionHighCount(), RejectionMap()

Definition at line 1077 of file DrizzleData.h.

◆ RejectionMap()

const UInt8Image& pcl::DrizzleData::RejectionMap ( ) const

inline

Returns a reference to a pixel rejection map generated for the drizzle image represented by this instance.

This member function returns a reference to an 8-bit unsigned integer image known as drizzle rejection map. Each channel of the rejection map corresponds to the same channel of the image represented by this object. For a channel index c, a pixel sample of a rejection map can have the following values:

0 (no bit set): The corresponding pixel has not been rejected for image channel c.

Bit 0 set: High statistical rejection: The pixel has been rejected above the estimated central value of its pixel integration stack using a statistical rejection algorithm (such as sigma clipping).

Bit 1 set: Low statistical rejection: The pixel has been rejected below the estimated central value of its pixel integration stack using a statistical rejection algorithm (such as sigma clipping).

Bit 2 set: High range rejection: The pixel has been rejected because its value is greater than or equal to a prescribed upper limit.

Bit 3 set: Low range rejection: The pixel has been rejected because its value is smaller than or equal to a prescribed lower limit.

Bit 4 set: High large-scale rejection: The pixel belongs to a bright large-scale image structure that has been rejected using multiscale analysis techniques.

Bit 5 set: Low large-scale rejection: The pixel belongs to a dark large-scale image structure that has been rejected using multiscale analysis techniques.

Bits 6 and 7 are reserved for future extensions and should be zero in the current implementation.

Rejection maps are automatically generated from pixel rejection data stored in .xdrz files. Pixel rejection data are normally generated by a regular image integration task.

If no pixel rejection information is available in this instance, this function returns a reference to an empty image.

See also: SetRejectionMap(), HasRejectionData(), IsRejected()

Definition at line 1145 of file DrizzleData.h.

◆ Scale()

const DVector& pcl::DrizzleData::Scale ( ) const

inline

Returns the vector of per-channel scaling factors for the drizzle source image represented by this instance.

For normalization of output pixel samples in a channel c of the drizzle image, the following equation should be implemented:

vc' = (vc - Lc)*Sc + L0c

where vc is the source pixel sample, Lc is the location estimate given by Location()[c], Sc is the scaling factor given by Scale()[c], L0c is the reference location estimate given by ReferenceLocation()[c], and vc' is the normalized pixel sample value.

Typically, the components of the vector returned by this function are the result of dividing reference scale estimates by robust estimates of dispersion, such as MAD or the square root of the biweight midvariance, among many others, computed for each channel of the image identified by AlignmentTargetFilePath(). Scaling factors are normally generated by a regular integration task.

See also: SetScale(), Location(), ReferenceLocation(), GetAdaptiveNormalizationScaleVectors()

Definition at line 793 of file DrizzleData.h.

◆ Serialize()

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

Serializes the drizzle integration data transported by this object as a new XML document in .xdrz format.

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

◆ SerializeToFile()

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

Serializes the drizzle integration data transported by this object as a new XML document file in .xdrz 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.

◆ SetAdaptiveNormalizationCoordinates()

void pcl::DrizzleData::SetAdaptiveNormalizationCoordinates ( const point_list & points )

inline

Sets the vector of adaptive normalization node coordinates. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: AdaptiveNormalizationCoordinates()

Definition at line 837 of file DrizzleData.h.

◆ SetAdaptiveNormalizationLocationVectors()

void pcl::DrizzleData::SetAdaptiveNormalizationLocationVectors ( const MultiVector & m )

inline

Sets new vectors of per-channel adaptive estimates of location for the drizzle source image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: AdaptiveNormalizationLocationVectors()

Definition at line 870 of file DrizzleData.h.

◆ SetAdaptiveNormalizationScaleVectors()

void pcl::DrizzleData::SetAdaptiveNormalizationScaleVectors	(	const MultiVector &	sLow,
		const MultiVector &	sHigh
	)

inline

Sets new vectors of per-channel adaptive scaling factors for the drizzle source image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: GetAdaptiveNormalizationScaleVectors()

Definition at line 935 of file DrizzleData.h.

◆ SetAdaptiveNormalizationZeroOffsetVectors()

void pcl::DrizzleData::SetAdaptiveNormalizationZeroOffsetVectors	(	const MultiVector &	mLow,
		const MultiVector &	mHigh
	)

inline

Sets new vectors of per-channel adaptive zero offsets for the drizzle source image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: GetAdaptiveNormalizationZeroOffsetVectors()

Definition at line 971 of file DrizzleData.h.

◆ SetAlignmentInverseSplines()

void pcl::DrizzleData::SetAlignmentInverseSplines ( const vector_spline & Sinv )

inline

Sets a new inverse vector surface spline interpolation/approximation device. This member function is reserved for image registration tasks involved in drizzle integration processes.

See also: AlignmentInverseSplines(), AlignmentSplines()

Definition at line 584 of file DrizzleData.h.

◆ SetAlignmentMatrix()

void pcl::DrizzleData::SetAlignmentMatrix ( const Matrix & H )

inline

Defines a new 3x3 alignment matrix. This function is reserved for image registration tasks involved in drizzle integration processes.

See also: AlignmentMatrix()

Definition at line 511 of file DrizzleData.h.

◆ SetAlignmentOrigin()

void pcl::DrizzleData::SetAlignmentOrigin ( const DPoint & p0 )

inline

Defines the origin of image alignment coordinates. This function is reserved for image registration tasks involved in drizzle integration processes.

Note: The default alignment origin coordinates are {0.5,0.5}, that is, the center of the top-left pixel in the image coordinate system. These coordinates ensure compatibility with old versions of drizzle data serializations and standard image registration tools on the PixInsight platform.

Definition at line 488 of file DrizzleData.h.

◆ SetAlignmentSplines()

void pcl::DrizzleData::SetAlignmentSplines ( const vector_spline & S )

inline

Sets a new vector surface spline interpolation/approximation device. This member function is reserved for image registration tasks involved in drizzle integration processes.

See also: AlignmentSplines(), AlignmentInverseSplines()

Definition at line 547 of file DrizzleData.h.

◆ SetAlignmentTargetFilePath()

void pcl::DrizzleData::SetAlignmentTargetFilePath ( const String & filePath )

inline

Sets the path to the registered image file corresponding to the drizzle image represented by this instance.

See also: AlignmentTargetFilePath()

Definition at line 419 of file DrizzleData.h.

References pcl::File::FullPath().

◆ SetCFASourceChannel()

void pcl::DrizzleData::SetCFASourceChannel ( int channel )

inline

Defines the channel index selected for the CFA mosaiced/unregistered image file corresponding to the drizzle source image represented by this instance.

The specified channel can be < 0 to disable the CFA channel index feature. See CFASourceChannel() for more information on CFA channel indexes and their role for CFA drizzle integrations.

See also: CFASourceChannel(), SetCFASourceFilePath(), SetCFASourcePattern()

Definition at line 387 of file DrizzleData.h.

References int32_max, and pcl::Range().

◆ SetCFASourceFilePath()

void pcl::DrizzleData::SetCFASourceFilePath ( const String & filePath )

inline

Sets the path to the mosaiced/unregistered image file corresponding t the drizzle source image represented by this instance.

See also: CFASourceFilePath(), SetCFASourcePattern(), SetCFASourceChannel()

Definition at line 315 of file DrizzleData.h.

References pcl::File::FullPath().

◆ SetCFASourcePattern()

void pcl::DrizzleData::SetCFASourcePattern ( const String & cfaPattern )

inline

Defines the color filter array (CFA) used by the mosaiced/unregistered image file corresponding to the drizzle source image represented by this instance.

See CFASourcePattern() for more information on CFA representations.

See also: CFASourcePattern(), SetCFASourceChannel(), SetCFASourceFilePath()

Definition at line 345 of file DrizzleData.h.

◆ SetLocation()

void pcl::DrizzleData::SetLocation ( const DVector & v )

inline

Sets a new vector of per-channel robust estimates of location for the drizzle source image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: Location(), ReferenceLocation(), SetScale(), SetAdaptiveNormalizationLocation()

Definition at line 732 of file DrizzleData.h.

◆ SetMetadata()

void pcl::DrizzleData::SetMetadata ( const String & metadata )

inline

Defines a string serialization of metadata items for the drizzle source image represented by this instance.

See also: Metadata()

Definition at line 701 of file DrizzleData.h.

◆ SetPedestal()

void pcl::DrizzleData::SetPedestal ( double p )

inline

Defines a positive value in the range [0,1] to be subtracted from the image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

Definition at line 1007 of file DrizzleData.h.

References pcl::Range().

◆ SetReferenceDimensions()

void pcl::DrizzleData::SetReferenceDimensions	(	int	width,
		int	height
	)

inline

Sets new registration reference image dimensions in pixels, width and height, respectively.

See also: ReferenceWidth(), ReferenceHeight()

Definition at line 450 of file DrizzleData.h.

◆ SetReferenceLocation()

void pcl::DrizzleData::SetReferenceLocation ( const DVector & v )

inline

Sets a new vector of per-channel robust estimates of location for the reference integration image. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: ReferenceLocation(), Location(), SetScale(), SetReferenceAdaptiveNormalizationLocation()

Definition at line 764 of file DrizzleData.h.

◆ SetRejectionMap()

void pcl::DrizzleData::SetRejectionMap ( const UInt8Image & map )

inline

Defines per-channel pixel rejection data for the drizzle source image represented by this instance. The specified map image is a drizzle rejection map as described in RejectionMap().

See also: RejectionMap(), HasRejectionData()

Definition at line 1170 of file DrizzleData.h.

◆ SetScale()

void pcl::DrizzleData::SetScale ( const DVector & v )

inline

Sets a new vector of per-channel scaling factors for the drizzle source image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: Scale(), SetLocation(), SetAdaptiveNormalizationScaleVectors()

Definition at line 809 of file DrizzleData.h.

◆ SetSourceFilePath()

void pcl::DrizzleData::SetSourceFilePath ( const String & filePath )

inline

Sets the path to the unregistered image file corresponding to the drizzle image represented by this instance.

See also: SourceFilePath()

Definition at line 289 of file DrizzleData.h.

References pcl::File::FullPath().

◆ SetWeight()

void pcl::DrizzleData::SetWeight ( const DVector & v )

inline

Sets a new vector of per-channel statistical weights for the drizzle image represented by this instance. This function is reserved for image integration tasks involved in drizzle integration processes.

See also: Weight(), SetLocation(), SetReferenceLocation(), SetScale()

Definition at line 1039 of file DrizzleData.h.

◆ SourceFilePath()

const String& pcl::DrizzleData::SourceFilePath ( ) const

inline

Returns the full path to the unregistered image file corresponding to the drizzle source image represented by this instance.

The file identified by this function stores the input image of the image registration task. This file can be used as input for a drizzle integration task.

See also: SetSourceFilePath()

Definition at line 278 of file DrizzleData.h.

◆ Weight()

const DVector& pcl::DrizzleData::Weight ( ) const

inline

Returns the vector of per-channel statistical weights for the drizzle image represented by this instance.

Typically, the components of the returned vector are efficient statistical weights computed for each channel of the image identified by AlignmentTargetFilePath(). These weights are normally generated by a regular integration task.

See also: SetWeight(), Location(), ReferenceLocation(), Scale()

Definition at line 1023 of file DrizzleData.h.

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

DrizzleData.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ point_list

◆ spline

◆ vector_spline

◆ weight_vector

Constructor & Destructor Documentation

◆ DrizzleData() [1/6]

◆ DrizzleData() [2/6]

◆ DrizzleData() [3/6]

◆ DrizzleData() [4/6]

◆ DrizzleData() [5/6]

◆ DrizzleData() [6/6]

◆ ~DrizzleData()

Member Function Documentation

◆ AdaptiveNormalizationCoordinates()

◆ AdaptiveNormalizationLocationVectors()

◆ AlignmentInverseSplines()

◆ AlignmentMatrix()

◆ AlignmentOrigin()

◆ AlignmentSplines()

◆ AlignmentTargetFilePath()

◆ CFASourceChannel()

◆ CFASourceFilePath()

◆ CFASourcePattern()

◆ Clear()

◆ ClearIntegrationData()

◆ CreationTime()

◆ DisableCompression()

◆ EnableCompression()

◆ GetAdaptiveNormalizationScaleVectors()

◆ GetAdaptiveNormalizationZeroOffsetVectors()

◆ GetLocalDistortionModel()

◆ HasAdaptiveNormalizationData()

◆ HasAlignmentInverseSplines()

◆ HasAlignmentMatrix()

◆ HasAlignmentSplines()

◆ HasImageWeightsData()

◆ HasIntegrationData()

◆ HasLocalDistortionModel()

◆ HasRejectionData()

◆ IsCompressionEnabled()

◆ IsRejected()

◆ Location()

◆ Metadata()

◆ NumberOfChannels()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Parse() [1/3]

◆ Parse() [2/3]

◆ Parse() [3/3]

◆ Pedestal()

◆ ReferenceHeight()

◆ ReferenceLocation()

◆ ReferenceWidth()

◆ RejectionHighCount()

◆ RejectionLowCount()

◆ RejectionMap()

◆ Scale()

◆ Serialize()

◆ SerializeToFile()

◆ SetAdaptiveNormalizationCoordinates()

◆ SetAdaptiveNormalizationLocationVectors()

◆ SetAdaptiveNormalizationScaleVectors()

◆ SetAdaptiveNormalizationZeroOffsetVectors()

◆ SetAlignmentInverseSplines()

◆ SetAlignmentMatrix()

◆ SetAlignmentOrigin()

◆ SetAlignmentSplines()

◆ SetAlignmentTargetFilePath()

◆ SetCFASourceChannel()

◆ SetCFASourceFilePath()

◆ SetCFASourcePattern()

◆ SetLocation()

◆ SetMetadata()

◆ SetPedestal()

◆ SetReferenceDimensions()

◆ SetReferenceLocation()