PCL
pcl::LocalNormalizationData Class Reference

Normalization data parser and generator. More...

#include <LocalNormalizationData.h>

Public Types

typedef BicubicBSplineInterpolation< normalization_coefficientmatrix_interpolation
 
typedef Array< matrix_interpolationmatrix_interpolations
 
typedef normalization_matrices::sample normalization_coefficient
 
typedef DImage normalization_matrices
 

Public Member Functions

 LocalNormalizationData ()=default
 
 LocalNormalizationData (const LocalNormalizationData &)=default
 
 LocalNormalizationData (LocalNormalizationData &&)=default
 
 LocalNormalizationData (const String &filePath, bool ignoreNormalizationData=false)
 
 LocalNormalizationData (const XMLDocument &xml, bool ignoreNormalizationData=false)
 
 LocalNormalizationData (const XMLElement &element, bool ignoreNormalizationData=false)
 
virtual ~LocalNormalizationData ()
 
void Clear ()
 
TimePoint CreationTime () const
 
void DisableCompression (bool disable=true)
 
void EnableCompression (bool enable=true)
 
bool HasInterpolations () const
 
void InitInterpolations ()
 
bool IsCompressionEnabled () const
 
int NormalizationScale () const
 
int NumberOfChannels () const
 
double operator() (double z, int x, int y, int c=0) const
 
void Parse (const String &filePath, bool ignoreNormalizationData=false)
 
void Parse (const XMLDocument &xml, bool ignoreNormalizationData=false)
 
void Parse (const XMLElement &element, bool ignoreNormalizationData=false)
 
const StringReferenceFilePath () const
 
int ReferenceHeight () const
 
int ReferenceWidth () const
 
const normalization_matricesScale () const
 
XMLDocumentSerialize () const
 
void SerializeToFile (const String &path) const
 
void SetNormalizationMatrices (const normalization_matrices &A, const normalization_matrices &B)
 
void SetNormalizationScale (int scale)
 
void SetReferenceDimensions (int width, int height)
 
void SetReferenceFilePath (const String &filePath)
 
void SetTargetFilePath (const String &filePath)
 
const StringTargetFilePath () const
 
const normalization_matricesZeroOffset () const
 

Detailed Description

LocalNormalizationData implements support for the XML normalization data format (XNML format, .xnml file suffix).

An XNML file stores local normalization function data suitable for pixel rejection and image integration tasks, including drizzle integration. The LocalNormalizationData class is a high-level interface for parsing and generation of these special files.

Local normalization functions are serialized as floating point real images, where each channel stores scaling and zero offset coefficients, sampled at a prescribed normalization scale, for a channel of a specific image.

For a channel index c and position vector i on a given input image, the local normalization function is:

v'(c,i) = U(A(c,i))*v(c,i) + U(B(c,i))

where A(c) is the matrix of scaling coefficients, B(c) is the matrix of zero offset coefficients, U() is a scale-dependent interpolation functional, v is an input pixel value, and v' is the normalized pixel value. Local normalization matrices are conveniently stored as multichannel, two-dimensional images, which facilitates two-dimensional interpolation with smooth pixel interpolation algorithms.

Normalization matrices are normally much smaller than the reference image dimensions. This happens because we define local normalization functions at a specific dimensional scale, which typically corresponds to a large dyadic wavelet scale of 64, 128, or 256 pixels. For this reason, normalization matrices require a smooth interpolation to compute normalization coefficients at reference image coordinates.

See also
DrizzleData

Definition at line 109 of file LocalNormalizationData.h.

Member Typedef Documentation

◆ matrix_interpolation

Represents a smooth interpolation used for calculation of local normalization function values at image pixel coordinates.

Definition at line 128 of file LocalNormalizationData.h.

◆ matrix_interpolations

Represents an array of local normalization interpolators.

Definition at line 133 of file LocalNormalizationData.h.

◆ normalization_coefficient

typedef normalization_matrices::sample pcl::LocalNormalizationData::normalization_coefficient

Represents a local normalization function coefficient.

Definition at line 121 of file LocalNormalizationData.h.

◆ normalization_matrices

Represents a per-channel set of local image normalization matrices.

Definition at line 116 of file LocalNormalizationData.h.

Constructor & Destructor Documentation

◆ LocalNormalizationData() [1/6]

pcl::LocalNormalizationData::LocalNormalizationData ( )
default

Constructs an empty LocalNormalizationData object.

◆ LocalNormalizationData() [2/6]

pcl::LocalNormalizationData::LocalNormalizationData ( const LocalNormalizationData )
default

Copy constructor.

◆ LocalNormalizationData() [3/6]

pcl::LocalNormalizationData::LocalNormalizationData ( LocalNormalizationData &&  )
default

Move constructor.

◆ LocalNormalizationData() [4/6]

pcl::LocalNormalizationData::LocalNormalizationData ( const String filePath,
bool  ignoreNormalizationData = false 
)
inline

Constructs a new LocalNormalizationData instance by loading and parsing a file in XNML format.

Parameters
filePathPath to an existing file that will be parsed. The file contents must be in XML normalization data format (usually, a file with the .xnml suffix).
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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 169 of file LocalNormalizationData.h.

◆ LocalNormalizationData() [5/6]

pcl::LocalNormalizationData::LocalNormalizationData ( const XMLDocument xml,
bool  ignoreNormalizationData = false 
)
inline

Constructs a new LocalNormalizationData instance by parsing a well-formed XML document in XNML format.

Parameters
xmlReference to the source XML document. This constructor expects an XML document in valid XML normalization data format (.xnml).
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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 193 of file LocalNormalizationData.h.

◆ LocalNormalizationData() [6/6]

pcl::LocalNormalizationData::LocalNormalizationData ( const XMLElement element,
bool  ignoreNormalizationData = false 
)
inline

Constructs a new LocalNormalizationData instance by parsing an XML element in XNML format.

Parameters
elementReference to the source XML element. This constructor expects an XML document tree in valid XML normalization data format (.xnml) rooted at the specified element.
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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 217 of file LocalNormalizationData.h.

◆ ~LocalNormalizationData()

virtual pcl::LocalNormalizationData::~LocalNormalizationData ( )
inlinevirtual

Virtual destructor.

Definition at line 225 of file LocalNormalizationData.h.

Member Function Documentation

◆ Clear()

void pcl::LocalNormalizationData::Clear ( )

Clears all of the image normalization data transported by this instance, yielding an empty LocalNormalizationData object.

◆ CreationTime()

TimePoint pcl::LocalNormalizationData::CreationTime ( ) const
inline

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

Definition at line 462 of file LocalNormalizationData.h.

◆ DisableCompression()

void pcl::LocalNormalizationData::DisableCompression ( bool  disable = true)
inline

Disables compression of serialized local normalization data.

See also
IsCompressionEnabled(), EnableCompression()

Definition at line 571 of file LocalNormalizationData.h.

◆ EnableCompression()

void pcl::LocalNormalizationData::EnableCompression ( bool  enable = true)
inline

Enables compression of serialized local normalization data.

See also
IsCompressionEnabled(), DisableCompression()

Definition at line 561 of file LocalNormalizationData.h.

◆ HasInterpolations()

bool pcl::LocalNormalizationData::HasInterpolations ( ) const
inline

Returns true iff valid local normalization function data have been loaded and the internal interpolators have been initialized.

Definition at line 424 of file LocalNormalizationData.h.

◆ InitInterpolations()

void pcl::LocalNormalizationData::InitInterpolations ( )

Initializes the internal local normalization function interpolators. After this initialization, operator()() can be called repeatedly to apply the local normalization function to pixel sample values in reference image coordinates.

Calling this member function is not necessary when valid local normalization data have been loaded from an XNML file or XML document, since in this case the internal interpolators are always initialized automatically. This function must be called, however, for newly defined normalization data set by calling SetReferenceDimensions() and SetNormalizationMatrices().

If this object has not been initialized with valid local normalization data, this member function throws an Error exception.

See also
operator()()

◆ IsCompressionEnabled()

bool pcl::LocalNormalizationData::IsCompressionEnabled ( ) const
inline

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

Data compression is enabled by default for newly constructed LocalNormalizationData objects. Currently the LZ4 compression codec is applied for serialization of local normalization matrices.

See also
EnableCompression(), DisableCompression()

Definition at line 551 of file LocalNormalizationData.h.

◆ NormalizationScale()

int pcl::LocalNormalizationData::NormalizationScale ( ) const
inline

Returns the scale in pixels at which the local normalization functions were sampled and calculated. For valid normalization data, the returned value must be larger than zero, and should normally be larger than or equal to 32 pixels.

See also
SetNormalizationScale()

Definition at line 290 of file LocalNormalizationData.h.

◆ NumberOfChannels()

int pcl::LocalNormalizationData::NumberOfChannels ( ) const
inline

Returns the number of channels or pixel sample planes in the image represented by this instance, or zero if this object has not been initialized with valid data.

Definition at line 345 of file LocalNormalizationData.h.

◆ operator()()

double pcl::LocalNormalizationData::operator() ( double  z,
int  x,
int  y,
int  c = 0 
) const
inline

Returns a locally normalized pixel sample value.

Parameters
zInput pixel sample value (unnormalized).
xHorizontal image pixel coordinate.
yVertical image pixel coordinate.
cChannel index.

This operator interpolates local normalization functions and applies the corresponding linear transformation to the input value z, which gives the return value. Note that the normalized value might be out of the input pixel sample range. In such case the normalized value should be truncated or rescaled as appropriate.

For performance reasons, this operator does not check that the required normalization and interpolation data have been initialized; if they are not, calling this operator will most likely lead to a crash. Interpolation data are automatically initialized when a valid XNML file or XML element is loaded and parsed. For newly constructed objects, make sure you define the reference dimensions and normalization matrices. Then call InitInterpolations() before starting to call this operator.

Definition at line 451 of file LocalNormalizationData.h.

◆ Parse() [1/3]

void pcl::LocalNormalizationData::Parse ( const String filePath,
bool  ignoreNormalizationData = false 
)

Loads and parses a normalization data file in XNML format.

Parameters
filePathPath to an existing file that will be parsed. The file contents must be in XML normalization data format (usually, a file with the .xnml suffix).
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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.

◆ Parse() [2/3]

void pcl::LocalNormalizationData::Parse ( const XMLDocument xml,
bool  ignoreNormalizationData = false 
)

Parses a well-formed XML document in XNML format.

Parameters
xmlReference to the source XML document. This member function expects an XML document in valid XML normalization data format (.xnml).
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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.

◆ Parse() [3/3]

void pcl::LocalNormalizationData::Parse ( const XMLElement element,
bool  ignoreNormalizationData = false 
)

Parses an XML element in XNML format.

Parameters
elementReference to the source XML element. This member function expects an XML document tree in valid XML normalization data format (.xnml) rooted at the specified element.
ignoreNormalizationDataIf true, local normalization data will be ignored and not parsed. This includes matrices of normalization function coefficients. Setting this parameter to true can be useful when the caller only needs to retrieve information on file paths and reference dimensions.

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.

◆ ReferenceFilePath()

const String& pcl::LocalNormalizationData::ReferenceFilePath ( ) const
inline

Returns the full path to the reference image file used for calculation of the normalization data represented by this instance, or an empty string if that file path is not available.

See also
SetReferenceFilePath()

Definition at line 236 of file LocalNormalizationData.h.

◆ ReferenceHeight()

int pcl::LocalNormalizationData::ReferenceHeight ( ) const
inline

Returns the height in pixels of the normalization reference and target images, or -1 if this object has not been initialized with valid data.

See also
ReferenceWidth(), SetReferenceDimensions()

Definition at line 323 of file LocalNormalizationData.h.

◆ ReferenceWidth()

int pcl::LocalNormalizationData::ReferenceWidth ( ) const
inline

Returns the width in pixels of the normalization reference and target images, or -1 if this object has not been initialized with valid data.

See also
ReferenceHeight(), SetReferenceDimensions()

Definition at line 312 of file LocalNormalizationData.h.

◆ Scale()

const normalization_matrices& pcl::LocalNormalizationData::Scale ( ) const
inline

Returns a reference to the set of matrices of scaling coefficients in the local normalization function.

See the class description for detailed information on local normalization functions.

See also
ZeroOffset(), SetNormalizationMatrices(), NormalizationScale()

Definition at line 373 of file LocalNormalizationData.h.

◆ Serialize()

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

Serializes the normalization data transported by this object as a new XML document in XNML format.

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

◆ SerializeToFile()

void pcl::LocalNormalizationData::SerializeToFile ( const String path) const

Serializes the normalization data transported by this object as a new XML document file in XNML format (.xnml). 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.

◆ SetNormalizationMatrices()

void pcl::LocalNormalizationData::SetNormalizationMatrices ( const normalization_matrices A,
const normalization_matrices B 
)
inline

Sets new local normalization function matrices.

Parameters
AReference to an image storing the matrices of scaling normalization coefficients.
BReference to an image storing the matrices of zero offset normalization coefficients.

See the class description for detailed information on local normalization functions.

See also
ZeroOffset(), Scale()

Definition at line 392 of file LocalNormalizationData.h.

◆ SetNormalizationScale()

void pcl::LocalNormalizationData::SetNormalizationScale ( int  scale)
inline

Sets the scale in pixels at which the local normalization functions have been sampled and calculated.

See also
NormalizationScale()

Definition at line 301 of file LocalNormalizationData.h.

◆ SetReferenceDimensions()

void pcl::LocalNormalizationData::SetReferenceDimensions ( int  width,
int  height 
)
inline

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

See also
ReferenceWidth(), ReferenceHeight()

Definition at line 334 of file LocalNormalizationData.h.

◆ SetReferenceFilePath()

void pcl::LocalNormalizationData::SetReferenceFilePath ( const String filePath)
inline

Sets the path to the reference image file used for calculation of the normalization data stored in this instance.

See also
ReferenceFilePath()

Definition at line 247 of file LocalNormalizationData.h.

References pcl::File::FullPath().

◆ SetTargetFilePath()

void pcl::LocalNormalizationData::SetTargetFilePath ( const String filePath)
inline

Sets the path to the image file for which the normalization data stored in this instance was calculated.

See also
TargetFilePath()

Definition at line 277 of file LocalNormalizationData.h.

References pcl::File::FullPath().

◆ TargetFilePath()

const String& pcl::LocalNormalizationData::TargetFilePath ( ) const
inline

Returns the full path to the image file for which the normalization data represented by this instance was calculated, or an empty string if such file path is not available.

The file identified by this function stores the input image of the image normalization task that created this object. This file can be used as input for a regular (non-drizzle) integration task, and the data transported by this object can then be used for normalization of pixel values in pixel rejection and/or integration output generation, including drizzle integration.

See also
SetTargetFilePath()

Definition at line 266 of file LocalNormalizationData.h.

◆ ZeroOffset()

const normalization_matrices& pcl::LocalNormalizationData::ZeroOffset ( ) const
inline

Returns a reference to the set of matrices of zero offset coefficients in the local normalization function.

See the class description for detailed information on local normalization functions.

See also
Scale(), SetNormalizationMatrices(), NormalizationScale()

Definition at line 359 of file LocalNormalizationData.h.


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