PCL
Classes | Public Types | Public Member Functions | List of all members
pcl::StarDetector Class Reference

Automatic star detection. More...

#include <StarDetector.h>

+ Inheritance diagram for pcl::StarDetector:

Classes

struct  Star
 Structure to hold the data of a detected star. More...
 

Public Types

using psf_function = PSFFit::psf_function
 
using star_list = Array< Star >
 

Public Member Functions

 StarDetector ()=default
 
 StarDetector (const StarDetector &)=default
 
 ~StarDetector () override
 
float BrightThreshold () const
 
const UInt8Image * DetectionMask () const
 
star_list DetectStars (const ImageVariant &image) const
 
void DisableClusteredSources (bool disable=true)
 
void DisableEllipticPSF (bool disable=true)
 
void DisableImageInversion (bool disable=true)
 
void DisableLocalMaximaDetection (bool disable=true)
 
void DisablePSFFitting (bool disable=true)
 
void EnableClusteredSources (bool enable=true)
 
void EnableEllipticPSF (bool enable=true)
 
void EnableImageInversion (bool enabled=true)
 
void EnableLocalMaximaDetection (bool enable=true)
 
void EnablePSFFitting (bool enable=true)
 
int HotPixelFilterRadius () const
 
bool IsClusteredSourcesEnabled () const
 
bool IsEllipticPSF () const
 
bool IsImageInversionEnabled () const
 
bool IsLocalMaximaDetectionEnabled () const
 
bool IsPSFFittingEnabled () const
 
int LocalDetectionFilterRadius () const
 
float LocalMaximaDetectionLimit () const
 
float MaxDistortion () const
 
float MinSNR () const
 
int MinStarSize () const
 
int MinStructureSize () const
 
int NoiseLayers () const
 
int NoiseReductionFilterRadius () const
 
star_list operator() (const ImageVariant &image) const
 
StarDetector & operator= (const StarDetector &)=default
 
float PeakResponse () const
 
float PSFCentroidTolerance () const
 
psf_function PSFType () const
 
float Sensitivity () const
 
void SetBrightThreshold (float r)
 
void SetDetectionMask (const UInt8Image *mask)
 
void SetHotPixelFilterRadius (int n)
 
void SetLocalDetectionFilterRadius (int n)
 
void SetLocalMaximaDetectionLimit (float v)
 
void SetMaxDistortion (float d)
 
void SetMinSNR (float snr)
 
void SetMinStructureSize (int n)
 
void SetNoiseLayers (int n)
 
void SetNoiseReductionFilterRadius (int n)
 
void SetPeakResponse (float r)
 
void SetPSFCentroidTolerance (float t)
 
void SetPSFType (psf_function type)
 
void SetSensitivity (float s)
 
void SetStructureLayers (int n)
 
void SetUpperLimit (float u)
 
int StructureLayers () const
 
Image StructureMap (const ImageVariant &image) const
 
Image Structures (const ImageVariant &image) const
 
float UpperLimit () const
 
- Public Member Functions inherited from pcl::ParallelProcess
 ParallelProcess ()=default
 
 ParallelProcess (const ParallelProcess &)=default
 
virtual ~ParallelProcess ()
 
void DisableParallelProcessing (bool disable=true) noexcept
 
void EnableParallelProcessing (bool enable=true, int maxProcessors=0) noexcept
 
bool IsParallelProcessingEnabled () const noexcept
 
int MaxProcessors () const noexcept
 
ParallelProcess & operator= (const ParallelProcess &)=default
 
void SetMaxProcessors (int maxProcessors) noexcept
 
void Swap (ParallelProcess &process) noexcept
 

Detailed Description

See also
PSFFit, PSFSignalEstimator

Definition at line 73 of file StarDetector.h.

Member Typedef Documentation

◆ psf_function

using pcl::StarDetector::psf_function = PSFFit::psf_function

Represents a point spread function type.

Definition at line 80 of file StarDetector.h.

◆ star_list

using pcl::StarDetector::star_list = Array<Star>

A dynamic array of pcl::StarDetector::Star structures.

Definition at line 182 of file StarDetector.h.

Constructor & Destructor Documentation

◆ StarDetector() [1/2]

pcl::StarDetector::StarDetector ( )
default

Default constructor.

◆ StarDetector() [2/2]

pcl::StarDetector::StarDetector ( const StarDetector &  )
default

Copy constructor.

◆ ~StarDetector()

pcl::StarDetector::~StarDetector ( )
inlineoverride

Destroys a StarDetector object.

Definition at line 202 of file StarDetector.h.

Member Function Documentation

◆ BrightThreshold()

float pcl::StarDetector::BrightThreshold ( ) const
inline

Bright stars threshold.

Stars with measured SNR above this parameter in units of the minimum detection level (as defined by the sensitivity parameter) will always be detected, even if their profiles are too flat for the current peak response. This allows us to force inclusion of bright stars. The default value is 3.0.

Definition at line 475 of file StarDetector.h.

◆ DetectionMask()

const UInt8Image* pcl::StarDetector::DetectionMask ( ) const
inline

Returns a pointer to the current star detection mask image, or nullptr if no detection mask is being used.

If a detection mask is used, star detection will only consider source pixels for which the corresponding mask pixels are nonzero. This allows for the implementation of partial star detection tasks limited to arbitrary regions of interest.

Definition at line 812 of file StarDetector.h.

◆ DetectStars()

star_list pcl::StarDetector::DetectStars ( const ImageVariant &  image) const

Performs star detection with the current parameters. Returns a dynamic array of Star structures sorted by brightness (flux) in descending order.

Note
This function is thread-safe.

◆ DisableClusteredSources()

void pcl::StarDetector::DisableClusteredSources ( bool  disable = true)
inline

Disables detection of clustered sources. See IsClusteredSourcesEnabled() for a description of this parameter.

Definition at line 552 of file StarDetector.h.

◆ DisableEllipticPSF()

void pcl::StarDetector::DisableEllipticPSF ( bool  disable = true)
inline

Disables elliptical PSF fits. See IsEllipticPSF().

Definition at line 770 of file StarDetector.h.

◆ DisableImageInversion()

void pcl::StarDetector::DisableImageInversion ( bool  disable = true)
inline

Disables image inversion. See IsImageInversionEnabled() for a description of this parameter.

Definition at line 684 of file StarDetector.h.

◆ DisableLocalMaximaDetection()

void pcl::StarDetector::DisableLocalMaximaDetection ( bool  disable = true)
inline

Disables local maxima detection. See IsLocalMaximaDetectionEnabled() for a description of this parameter.

Definition at line 633 of file StarDetector.h.

◆ DisablePSFFitting()

void pcl::StarDetector::DisablePSFFitting ( bool  disable = true)
inline

Disables PSF fitting for this star detector. See IsPSFFittingEnabled() for a description of this parameter.

Definition at line 725 of file StarDetector.h.

◆ EnableClusteredSources()

void pcl::StarDetector::EnableClusteredSources ( bool  enable = true)
inline

Enables detection of clustered sources. See IsClusteredSourcesEnabled() for a description of this parameter.

Definition at line 543 of file StarDetector.h.

◆ EnableEllipticPSF()

void pcl::StarDetector::EnableEllipticPSF ( bool  enable = true)
inline

Enables elliptical PSF fits. See IsEllipticPSF().

Definition at line 762 of file StarDetector.h.

◆ EnableImageInversion()

void pcl::StarDetector::EnableImageInversion ( bool  enabled = true)
inline

Enables image inversion. See IsImageInversionEnabled() for a description of this parameter.

Definition at line 675 of file StarDetector.h.

◆ EnableLocalMaximaDetection()

void pcl::StarDetector::EnableLocalMaximaDetection ( bool  enable = true)
inline

Enables local maxima detection. See IsLocalMaximaDetectionEnabled() for a description of this parameter.

Definition at line 624 of file StarDetector.h.

◆ EnablePSFFitting()

void pcl::StarDetector::EnablePSFFitting ( bool  enable = true)
inline

Enables PSF fitting for this star detector. See IsPSFFittingEnabled() for a description of this parameter.

Definition at line 716 of file StarDetector.h.

◆ HotPixelFilterRadius()

int pcl::StarDetector::HotPixelFilterRadius ( ) const
inline

Size of the hot pixel removal filter.

This is the radius in pixels of a median filter applied by the star detector before the structure detection phase. A median filter is very efficient to remove hot pixels. To disable hot pixel removal, set this parameter to zero. The default value is 1 pixel.

Definition at line 272 of file StarDetector.h.

◆ IsClusteredSourcesEnabled()

bool pcl::StarDetector::IsClusteredSourcesEnabled ( ) const
inline

Returns true iff detection of clustered sources is allowed.

If this parameter is false, a local maxima map will be generated to identify and prevent detection of multiple sources that are too close to be separated as individual structures, such as double and multiple stars. In general, barycenter positions cannot be accurately determined for sources with several local maxima. If this parameter is true, non-separable multiple sources will be detectable as single objects. The default value is false.

Definition at line 534 of file StarDetector.h.

◆ IsEllipticPSF()

bool pcl::StarDetector::IsEllipticPSF ( ) const
inline

Returns true if elliptical point spread functions (PSFs) will be fitted when PSF fitting is enabled. Returns false if circular functions will be fitted. Elliptical PSFs are disabled by default.

Definition at line 754 of file StarDetector.h.

◆ IsImageInversionEnabled()

bool pcl::StarDetector::IsImageInversionEnabled ( ) const
inline

Returns true iff image inversion is enabled for this star detector.

When inversion is enabled, the star detector algorithm will look for dark stars over a bright background. This feature is disabled by default.

Definition at line 666 of file StarDetector.h.

◆ IsLocalMaximaDetectionEnabled()

bool pcl::StarDetector::IsLocalMaximaDetectionEnabled ( ) const
inline

Returns true iff detection of local maxima is enabled.

When this parameter is enabled, each reported Star object will include the number of local maxima detected in the corresponding image structure, irrespective of the current state of the detection of clustered sources parameter (see IsClusteredSourcesEnabled()).

When disabled, the number of local maxima will be zero for all reported Star objects, and the detection of clustered sources parameter will be implicitly disabled.

The default value is true.

Definition at line 615 of file StarDetector.h.

◆ IsPSFFittingEnabled()

bool pcl::StarDetector::IsPSFFittingEnabled ( ) const
inline

Returns true iff PSF fitting is enabled for this star detector.

When PSF fitting is enabled, a point spread function of the type specified by PSFType() will be fitted numerically for each detected star. The Levenberg-Marquardt non-linear least squares algorithm will be used to minimize the difference between the fitted function and the pixel sample values in the detection region. See the PSFFit class for complete information on our PSF fitting implementation.

When PSF fitting is enabled, the pos data member of the pcl::StarDetector::Star corresponds to the centroid of the fitted PSF instead of the barycenter position calculated by the star detection algorithm, and the signal member is a robust estimate of the mean signal evaluated over the local background, also from the fitted PSF.

PSF fitting is disabled by default.

Definition at line 707 of file StarDetector.h.

◆ LocalDetectionFilterRadius()

int pcl::StarDetector::LocalDetectionFilterRadius ( ) const
inline

Size of the local maxima detection filter.

This is the radius in pixels of a structuring element used to generate a local maxima map, when detection of clustered sources is disabled. The default value is 2, which applies a 5x5 filter.

Definition at line 564 of file StarDetector.h.

◆ LocalMaximaDetectionLimit()

float pcl::StarDetector::LocalMaximaDetectionLimit ( ) const
inline

Returns the local maxima detection limit.

This parameter is a normalized pixel value in the [0,1] range. Structures with pixels above this value will be excluded for local maxima detection. The default value is 0.75.

Definition at line 586 of file StarDetector.h.

◆ MaxDistortion()

float pcl::StarDetector::MaxDistortion ( ) const
inline

Maximum star distortion.

Internally, star distortion is evaluated in units of coverage of a square region circumscribed to each detected structure. The coverage of a perfectly circular star is π/4 (about 0.8). Lower values denote elongated or irregular sources.

To isolate the public interface of this class from its internal implementation, this parameter is normalized to the [0,1] range, where 0 and 1 represent minimum and maximum distortion, respectively. This abstraction allows us to change the star detection engine without breaking dependent tools and processes.

Use this parameter, if necessary, to control inclusion of elongated stars, complex clusters of stars, and nonstellar image features. The default value is 0.6.

Definition at line 508 of file StarDetector.h.

◆ MinSNR()

float pcl::StarDetector::MinSNR ( ) const
inline

Minimum signal-to-noise ratio of a detectable star.

Given a source with estimated brightness s, local background b and local background dispersion n, SNR is evaluated as (s - b)/n. Stars with measured SNR below this parameter won't be detected.

The value of this parameter can be increased to limit star detection to a subset of the brightest sources in the image adaptively, instead of imposing an arbitrary limit on the number of detected stars. The default value is zero.

Definition at line 451 of file StarDetector.h.

◆ MinStarSize()

int pcl::StarDetector::MinStarSize ( ) const
inline

Returns the automatically calculated minimum star size in square pixels.

The value returned by this function is only valid after a successful execution of the DetectStars() function (or, equivalently, operator()()) with a zero minimum structure size parameter value. See the MinStructureSize() member function for more information.

Definition at line 363 of file StarDetector.h.

◆ MinStructureSize()

int pcl::StarDetector::MinStructureSize ( ) const
inline

Minimum size of a detectable star structure in square pixels.

This parameter can be used to prevent the detection of small and bright image artifacts wrongly as stars. This can be useful to work with uncalibrated or poorly calibrated data, especially demosaiced CFA frames where uncorrected hot pixels have generated large bright artifacts that cannot be removed with a median filter, or for rejection of cosmic rays.

This parameter can be used in three ways:

  • Automatic mode. A zero value enables an adaptive algorithm to find an optimal minimum structure size using statistical analysis techniques. This is the default option.
  • Disabled. A value of one turns off minimum structure size rejection since no detectable star can be represented by less than one pixel.
  • Literal value. A value > 1 forces using the specified minimum structure size in square pixels.

Definition at line 339 of file StarDetector.h.

◆ NoiseLayers()

int pcl::StarDetector::NoiseLayers ( ) const
inline

Number of (dyadic) wavelet layers used for noise reduction.

Noise reduction prevents detection of bright noise structures as false stars, including hot pixels and cosmic rays. This parameter can also be used to control the sizes of the smallest detected stars (increase it to exclude more stars), although the minimum structure size parameter can be more efficient for this purpose. The default value is 0, which effectively disables this noise reduction feature.

Note
Although the current star detection algorithm does not use a wavelet transform for structure detection, this parameter is still expressed as a number of dyadic wavelet layers for convenience and compatibility with existing implementations.

Definition at line 249 of file StarDetector.h.

◆ NoiseReductionFilterRadius()

int pcl::StarDetector::NoiseReductionFilterRadius ( ) const
inline

Size of the noise reduction filter.

This is the radius in pixels of a Gaussian convolution filter applied to the working image used for calculation of star positions during the star detection phase. Use it only for very low SNR images, where the star detector cannot find reliable stars with default parameters.

Be aware that noise reduction will modify star profiles and hence the way star positions are calculated, resulting in a less accurate centroid determination. Under extreme low-SNR conditions, however, this is probably better than working with the actual data anyway.

The default value is zero, which effectively disables this feature.

Definition at line 302 of file StarDetector.h.

◆ operator()()

star_list pcl::StarDetector::operator() ( const ImageVariant &  image) const
inline

Performs star detection with the current parameters. Returns a dynamic array of Star structures sorted by brightness (flux) in descending order.

This operator is equivalent to the DetectStars( const ImageVariant& ) member function.

Note
This function is thread-safe.

Definition at line 852 of file StarDetector.h.

◆ operator=()

StarDetector& pcl::StarDetector::operator= ( const StarDetector &  )
default

Copy assignment operator. Returns a reference to this object.

◆ PeakResponse()

float pcl::StarDetector::PeakResponse ( ) const
inline

Peak sensitivity of the star detection device.

Internally, the peak response property of the star detection algorithm is expressed in kurtosis units. For each detected structure, kurtosis is evaluated from all significant pixels with values greater than the estimated mean local background. Peak response is the minimum value of kurtosis necessary to trigger star detection.

To isolate the public interface of this class from its internal implementation, this parameter is normalized to the [0,1] range, where 0 and 1 represent minimum and maximum peak response, respectively. This abstraction allows us to change the star detection engine without breaking dependent tools and processes.

If you decrease this parameter, stars will need to have stronger (or more prominent) peaks to be detected. This is useful to prevent detection of saturated stars, as well as small nonstellar features. By increasing this parameter, the star detection algorithm will be more sensitive to peakedness, and hence more tolerant with relatively flat image features. The default value is 0.5.

Definition at line 424 of file StarDetector.h.

◆ PSFCentroidTolerance()

float pcl::StarDetector::PSFCentroidTolerance ( ) const
inline

Returns the centroid tolerance in pixels.

The centroid tolerance is the maximum allowed distance in pixels between a detected star position (or barycenter) and the centroid position of the corresponding fitted PSF. Stars where that distance is greater than the value returned by this function will be rejected and excluded for signal estimation. This allows preventing PSF fits departing too much from detected star coordinates, which enforces robustness and stability of the PSF fitting process.

The default centroid tolerance is 1.5 pixels.

Definition at line 788 of file StarDetector.h.

◆ PSFType()

psf_function pcl::StarDetector::PSFType ( ) const
inline

Returns the type of point spread function (PSF) fitted numerically when PSF fitting is enabled. See IsPSFFittingEnabled() and the pcl::PSFunction namespace.

Definition at line 735 of file StarDetector.h.

◆ Sensitivity()

float pcl::StarDetector::Sensitivity ( ) const
inline

Sensitivity of the star detection device.

Internally, the sensitivity of the star detection algorithm is expressed in signal-to-noise ratio units with respect to the evaluated dispersion of local background pixels for each detected structure. Given a source with estimated brightness s, local background b and local background dispersion n, sensitivity is the minimum value of (s - b)/n necessary to trigger star detection.

To isolate the public interface of this class from its internal implementation, this parameter is normalized to the [0,1] range, where 0 and 1 represent minimum and maximum sensitivity, respectively. This abstraction allows us to change the star detection engine without breaking dependent tools and processes.

Increase this value to favor detection of fainter stars. Decrease it to restrict detection to brighter stars. The default value is 0.5.

Definition at line 387 of file StarDetector.h.

◆ SetBrightThreshold()

void pcl::StarDetector::SetBrightThreshold ( float  r)
inline

Sets the bright stars threshold. See BrightThreshold() for a description of this parameter.

Definition at line 484 of file StarDetector.h.

References pcl::Range().

◆ SetDetectionMask()

void pcl::StarDetector::SetDetectionMask ( const UInt8Image *  mask)
inline

Sets the detection mask image. See DetectionMask() for a description of this parameter.

If the specified mask pointer is nullptr, no mask will be used in subsequent star detection tasks performed by this object. Otherwise, the specified mask image must have the same dimensions as the image(s) that will be specified for star detection, and must remain valid while this object performs star detection tasks.

Definition at line 827 of file StarDetector.h.

References pcl::ImageGeometry::IsEmpty().

◆ SetHotPixelFilterRadius()

void pcl::StarDetector::SetHotPixelFilterRadius ( int  n)
inline

Sets the size of the hot pixel removal filter. See HotPixelFilterRadius() for a description of this parameter.

Definition at line 281 of file StarDetector.h.

References pcl::Range().

◆ SetLocalDetectionFilterRadius()

void pcl::StarDetector::SetLocalDetectionFilterRadius ( int  n)
inline

Sets the radius in pixels of the local maxima detection filter. See LocalDetectionFilterRadius() for a description of this parameter.

Definition at line 573 of file StarDetector.h.

References pcl::Range().

◆ SetLocalMaximaDetectionLimit()

void pcl::StarDetector::SetLocalMaximaDetectionLimit ( float  v)
inline

Sets the local maxima detection limit. See LocalMaximaDetectionLimit() for a description of this parameter.

Definition at line 595 of file StarDetector.h.

References pcl::Range().

◆ SetMaxDistortion()

void pcl::StarDetector::SetMaxDistortion ( float  d)
inline

Sets the maximum star distortion. See MaxDistortion() for a description of this parameter.

Definition at line 517 of file StarDetector.h.

References pcl::Range().

◆ SetMinSNR()

void pcl::StarDetector::SetMinSNR ( float  snr)
inline

Sets the minimum signal-to-noise detection level. See MinSNR() for a description of this parameter.

Definition at line 460 of file StarDetector.h.

References pcl::Max().

◆ SetMinStructureSize()

void pcl::StarDetector::SetMinStructureSize ( int  n)
inline

Sets the minimum size n ≥ 0 of a detectable star structure in square pixels. See MinStructureSize() for a detailed description of this parameter and its possible values.

Definition at line 349 of file StarDetector.h.

References pcl::Max().

◆ SetNoiseLayers()

void pcl::StarDetector::SetNoiseLayers ( int  n)
inline

Sets the number of wavelet layers used for noise reduction. See NoiseLayers() for a description of this parameter.

Definition at line 258 of file StarDetector.h.

References pcl::Range().

◆ SetNoiseReductionFilterRadius()

void pcl::StarDetector::SetNoiseReductionFilterRadius ( int  n)
inline

Sets the size in pixels of the noise reduction filter. See NoiseReductionFilterRadius() for a description of this parameter.

Definition at line 311 of file StarDetector.h.

References pcl::Range().

◆ SetPeakResponse()

void pcl::StarDetector::SetPeakResponse ( float  r)
inline

Sets the peak sensitivity. See PeakResponse() for a description of this parameter.

Definition at line 433 of file StarDetector.h.

References pcl::Range().

◆ SetPSFCentroidTolerance()

void pcl::StarDetector::SetPSFCentroidTolerance ( float  t)
inline

Sets the centroid tolerance in pixels. See PSFCentroidTolerance() for a description of this parameter.

Definition at line 797 of file StarDetector.h.

References pcl::Max().

◆ SetPSFType()

void pcl::StarDetector::SetPSFType ( psf_function  type)
inline

Sets the type of point spread function (PSF) fitted numerically when PSF fitting is enabled. See PSFType().

Definition at line 744 of file StarDetector.h.

◆ SetSensitivity()

void pcl::StarDetector::SetSensitivity ( float  s)
inline

Sets the star detection sensitivity. See Sensitivity() for a description of this parameter.

Definition at line 396 of file StarDetector.h.

References pcl::Range().

◆ SetStructureLayers()

void pcl::StarDetector::SetStructureLayers ( int  n)
inline

Sets the number of wavelet layers used for structure detection. See StructureLayers() for a description of this parameter.

Definition at line 228 of file StarDetector.h.

References pcl::Range().

◆ SetUpperLimit()

void pcl::StarDetector::SetUpperLimit ( float  u)
inline

Sets the upper star detection limit. See UpperLimit() for a description of this parameter.

Definition at line 654 of file StarDetector.h.

References pcl::Range().

◆ StructureLayers()

int pcl::StarDetector::StructureLayers ( ) const
inline

Number of (dyadic) wavelet layers used for structure detection.

This parameter determines the size in pixels of the largest image structures that can be detected. With more layers, larger stars (and perhaps also some nonstellar objects) will be detected. The default value is 5, which corresponds to structures in the scale of 32 pixels.

Note
Although the current star detection algorithm does not use a wavelet transform for structure detection, this parameter is still expressed as a number of dyadic wavelet layers for convenience and compatibility with existing implementations.

Definition at line 219 of file StarDetector.h.

◆ StructureMap()

Image pcl::StarDetector::StructureMap ( const ImageVariant &  image) const

Computes a binary map of star detection structures for the specified image and the current set of star detection parameters.

Returns the star detection map as a new image.

◆ Structures()

Image pcl::StarDetector::Structures ( const ImageVariant &  image) const

Isolates star detection structures for the specified image.

Returns a new image which is the result of multiplying the specified image by the binarized structure map generated with the current star detection parameters.

◆ UpperLimit()

float pcl::StarDetector::UpperLimit ( ) const
inline

Upper star detection limit in the normalized [0,1] range.

Stars with peak values larger than this value won't be detected. This can be useful to reject all stars brighter than a fixed level systematically. The default value is 1.0, which effectively disables this feature.

Definition at line 645 of file StarDetector.h.

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