PCL
|
Drizzle integration data parser and generator. More...
#include <DrizzleData.h>
Public Types | |
using | point_list = Array< DPoint > |
using | rejection_coordinates = Array< Point > |
using | rejection_data = Array< rejection_coordinates > |
using | spline = vector_spline::spline |
using | vector_spline = PointSurfaceSpline |
using | weight_vector = Array< float > |
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:
An XDRZ file stores all of 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.
Definition at line 142 of file DrizzleData.h.
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.
A list of coordinates corresponding to pixels rejected by an image integration task.
Definition at line 176 of file DrizzleData.h.
A set of per-channel pixel rejection coordinates.
Definition at line 181 of file DrizzleData.h.
Represents a coordinate interpolating/approximating surface spline used for image registration with arbitrary distortion correction.
Definition at line 157 of file DrizzleData.h.
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.
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.
|
default |
Default constructor. Constructs an empty DrizzleData object.
|
default |
Copy constructor.
|
default |
Move constructor.
|
inline |
Constructs a new DrizzleData instance by loading and parsing a file.
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 217 of file DrizzleData.h.
|
inline |
Constructs a new DrizzleData instance by parsing a well-formed XML document.
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 238 of file DrizzleData.h.
|
inline |
Constructs a new DrizzleData instance by parsing an XML element.
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 257 of file DrizzleData.h.
|
inlinevirtual |
Virtual destructor.
Definition at line 265 of file DrizzleData.h.
|
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.
Definition at line 836 of file DrizzleData.h.
|
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.
Definition at line 868 of file DrizzleData.h.
|
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.
Definition at line 583 of file DrizzleData.h.
|
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.
Definition at line 511 of file DrizzleData.h.
|
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.
Definition at line 483 of file DrizzleData.h.
|
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.
Definition at line 546 of file DrizzleData.h.
|
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.
Definition at line 419 of file DrizzleData.h.
|
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.
Definition at line 382 of file DrizzleData.h.
|
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.
Definition at line 315 of file DrizzleData.h.
|
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".
Definition at line 342 of file DrizzleData.h.
void pcl::DrizzleData::Clear | ( | ) |
Clears all of the drizzle integration data transported by this instance, yielding an empty DrizzleData object.
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.
|
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 1199 of file DrizzleData.h.
|
inline |
Disables compression of serialized drizzle data.
Definition at line 1309 of file DrizzleData.h.
|
inline |
Enables compression of serialized drizzle data.
Definition at line 1299 of file DrizzleData.h.
|
inline |
Provides the vectors of per-channel adaptive scale factors for the drizzle source image represented by this instance.
[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.
Definition at line 933 of file DrizzleData.h.
|
inline |
Provides the vectors of per-channel adaptive zero offset coefficients for the drizzle source image represented by this instance.
[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.
Definition at line 969 of file DrizzleData.h.
|
inline |
Stores a copy of the local distortion model in the specified arrays.
[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.
Definition at line 664 of file DrizzleData.h.
|
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 994 of file DrizzleData.h.
|
inline |
Returns true iff this instance defines an inverse vector surface spline interpolation/approximation device.
Definition at line 607 of file DrizzleData.h.
|
inline |
Returns true iff this instance defines a 3x3 alignment matrix for the projective image registration transformation.
Definition at line 533 of file DrizzleData.h.
|
inline |
Returns true iff this instance defines a vector surface spline interpolation/approximation device.
Definition at line 570 of file DrizzleData.h.
|
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 1072 of file DrizzleData.h.
|
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 1061 of file DrizzleData.h.
|
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.
Definition at line 689 of file DrizzleData.h.
|
inline |
Returns true iff pixel rejection information is available for the drizzle image represented by this instance.
Definition at line 1190 of file DrizzleData.h.
|
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.
Definition at line 1289 of file DrizzleData.h.
|
inline |
Returns true iff the pixel at the specified pixel coordinates has been rejected for the drizzle source image represented by this instance.
Definition at line 1167 of file DrizzleData.h.
|
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.
Definition at line 730 of file DrizzleData.h.
|
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.
Definition at line 701 of file DrizzleData.h.
|
inline |
Returns the number of channels or pixel sample planes in the image represented by this instance.
Definition at line 471 of file DrizzleData.h.
|
default |
Copy assignment operator. Returns a reference to this object.
|
default |
Move assignment operator. Returns a reference to this object.
void pcl::DrizzleData::Parse | ( | const String & | filePath, |
DrizzleParserOptions | options = DrizzleParserOptions() |
||
) |
Loads and parses a drizzle data file.
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 of the 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.
void pcl::DrizzleData::Parse | ( | const XMLDocument & | xml, |
DrizzleParserOptions | options = DrizzleParserOptions() |
||
) |
Parses a well-formed XML document.
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 of the 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.
void pcl::DrizzleData::Parse | ( | const XMLElement & | element, |
DrizzleParserOptions | options = DrizzleParserOptions() |
||
) |
Parses an XML element.
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 of the 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.
|
inline |
Returns a positive value in the range [0,1] to be subtracted from the image represented by this instance.
Definition at line 1008 of file DrizzleData.h.
|
inline |
Returns the height in pixels of the registration reference image.
Definition at line 450 of file DrizzleData.h.
|
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.
Definition at line 762 of file DrizzleData.h.
|
inline |
Returns the width in pixels of the registration reference image.
Definition at line 440 of file DrizzleData.h.
|
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.
Definition at line 1104 of file DrizzleData.h.
|
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.
Definition at line 1088 of file DrizzleData.h.
|
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:
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.
Definition at line 1156 of file DrizzleData.h.
|
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.
Definition at line 804 of file DrizzleData.h.
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.
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.
|
inline |
Sets the vector of adaptive normalization node coordinates. This function is reserved for image integration tasks involved in drizzle integration processes.
Definition at line 848 of file DrizzleData.h.
|
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.
Definition at line 881 of file DrizzleData.h.
|
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.
Definition at line 946 of file DrizzleData.h.
|
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.
Definition at line 982 of file DrizzleData.h.
|
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.
Definition at line 595 of file DrizzleData.h.
|
inline |
Defines a new 3x3 alignment matrix. This function is reserved for image registration tasks involved in drizzle integration processes.
Definition at line 522 of file DrizzleData.h.
|
inline |
Defines the origin of image alignment coordinates. This function is reserved for image registration tasks involved in drizzle integration processes.
Definition at line 499 of file DrizzleData.h.
|
inline |
Sets a new vector surface spline interpolation/approximation device. This member function is reserved for image registration tasks involved in drizzle integration processes.
Definition at line 558 of file DrizzleData.h.
|
inline |
Sets the path to the registered image file corresponding to the drizzle image represented by this instance.
Definition at line 430 of file DrizzleData.h.
References pcl::File::FullPath().
|
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.
Definition at line 398 of file DrizzleData.h.
References int32_max, and pcl::Range().
|
inline |
Sets the path to the mosaiced/unregistered image file corresponding t the drizzle source image represented by this instance.
Definition at line 326 of file DrizzleData.h.
References pcl::File::FullPath().
|
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.
Definition at line 356 of file DrizzleData.h.
|
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.
Definition at line 743 of file DrizzleData.h.
|
inline |
Defines a string serialization of metadata items for the drizzle source image represented by this instance.
Definition at line 712 of file DrizzleData.h.
|
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 1018 of file DrizzleData.h.
References pcl::Range().
|
inline |
Sets new registration reference image dimensions in pixels, width and height, respectively.
Definition at line 461 of file DrizzleData.h.
|
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.
Definition at line 775 of file DrizzleData.h.
|
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().
Definition at line 1181 of file DrizzleData.h.
|
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.
Definition at line 820 of file DrizzleData.h.
|
inline |
Sets the path to the unregistered image file corresponding to the drizzle image represented by this instance.
Definition at line 300 of file DrizzleData.h.
References pcl::File::FullPath().
|
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.
Definition at line 1050 of file DrizzleData.h.
|
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.
Definition at line 289 of file DrizzleData.h.
|
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.
Definition at line 1034 of file DrizzleData.h.