lsst::afw::fits::ImageScalingOptions Class Reference

Options for scaling image pixels. More...

#include <fitsCompression.h>

Public Types
enum	ScalingAlgorithm {   NONE, RANGE, STDEV_POSITIVE, STDEV_NEGATIVE,   STDEV_BOTH, MANUAL }

Public Member Functions
	ImageScalingOptions ()
	Default Ctor. More...
	ImageScalingOptions (ScalingAlgorithm algorithm_, int bitpix_, std::vector< std::string > const &maskPlanes_={}, int seed_=1, float quantizeLevel_=4.0, float quantizePad_=5.0, bool fuzz_=true, double bscale_=1.0, double bzero_=0.0)
	General purpose Ctor. More...
	ImageScalingOptions (int bitpix_, double bscale_=1.0, double bzero_=0.0)
	Manual scaling Ctor. More...
template<typename T >
ImageScale	determine (image::ImageBase< T > const &image, std::shared_ptr< image::Mask< image::MaskPixel > const > mask=nullptr) const
	Determine the scaling for a particular image. More...
template<typename T , int N>
ImageScale	determine (ndarray::Array< T const, N, N > const &image, ndarray::Array< bool, N, N > const &mask) const
	Determine the scaling for a particular image. More...

Public Attributes
ScalingAlgorithm	algorithm
	Scaling algorithm to use. More...
int	bitpix
	Bits per pixel (0, 8,16,32,64,-32,-64) More...
bool	fuzz
	Fuzz the values when quantising floating-point values? More...
int	seed
	Seed for random number generator when fuzzing. More...
std::vector< std::string >	maskPlanes
	Mask planes to ignore when doing statistics. More...
float	quantizeLevel
	Divisor of the standard deviation for STDEV_* scaling. More...
float	quantizePad
	Number of stdev to allow on the low/high side (for STDEV_POSITIVE/NEGATIVE) More...
double	bscale
	Manually specified BSCALE (for MANUAL scaling) More...
double	bzero
	Manually specified BZERO (for MANUAL scaling) More...

Detailed Description

Options for scaling image pixels.

Scaling (quantisation) of floating-point images is important in order to achieve respectable compression factors. Unfortunately, scaling a floating-point image means losing some information, in two ways: values are quantised so values in between the quanta will be rounded up or down; and values outside the range of supported values in the integer image will be clipped. This implementation is based on the successful implementation used by Pan-STARRS.

cfitsio provides a facility for scaling image pixels on write (see ImageCompressionOptions.quantizeLevel), but that facility is limited (it provides a single scaling option, and doesn't use our masks when collecting statistics). This scaling facility provides multiple scaling options, and could be extended to support more in the future (e.g., logarithmic or asinh scaling).

Scaling is specified by:

• the scaling algorithm: the algorithm used to determining the scales (and therefore the dynamic range).
• the bits per pixel: 8,16,32,64,-32,-64 (negative means floating-point but you probably don't want to use those here); larger values give more dynamic range, produce larger images (which effect may be negated by compression).
• fuzz: whether to add a random field of values distributed [0,1) before quantisation; this preserves the expectation value of the floating-point image, while increasing the variance by 1/12.
• seed: seed for the random number generator used by the fuzz.
• maskPlanes: a list of mask planes to be ignored when doing statistics.
• quantizeLevel: for the STDEV_* algorithms, specifies the ratio of the quantum size to the image standard deviation.
• quantizePad: for the STDEV_POSITIVE and STDEV_NEGATIVE algorithms, specifies how many standard deviations to allow on the short side.
• bscale, bzero: for the MANUAL algorithm, specifies the BSCALE and BZERO to use.

Scaling algorithms are:

• NONE: no scaling or quantisation at all. The image goes out the way it came in.
• RANGE: scale based on the dynamic range in the image. This preserves dynamic range at the cost of sensitivity to low-level fluctuations.
• STDEV_POSITIVE: the scale is set to sample the standard deviation of the image (bscale = stdev/quantizeLevel) and the dynamic range extends principally positive (allowing only quantizePad standard deviations negative).
• STDEV_NEGATIVE: similar to STDEV_POSITIVE, but the dynamic range extends principally negative.
• STDEV_BOTH: the scale is set similar to STDEV_POSITIVE, but the dynamic range is shared between the positive and negative sides.
• MANUAL: the scale is set manually. We do what we're told, no more, no less.

Perhaps this one class could/should have been polymorphic, with different subclasses for different algorithms? But I went with a C-like approach keying off the enum, probably because I was influenced by Pan-STARRS' C code.

Definition at line 355 of file fitsCompression.h.

Member Enumeration Documentation

ScalingAlgorithm

enum lsst::afw::fits::ImageScalingOptions::ScalingAlgorithm

Enumerator
NONE	No scaling.
RANGE	Scale to preserve dynamic range.
STDEV_POSITIVE	Scale based on the standard deviation. dynamic range positive.
STDEV_NEGATIVE	Scale based on the standard deviation, dynamic range negative.
STDEV_BOTH	Scale based on the standard deviation, dynamic range positive+negative.
MANUAL	Scale set manually.

Definition at line 357 of file fitsCompression.h.

                          {
        NONE,            
        RANGE,           
        STDEV_POSITIVE,  
        STDEV_NEGATIVE,  
        STDEV_BOTH,      
        MANUAL,          
    };

Constructor & Destructor Documentation

ImageScalingOptions() [1/3]

lsst::afw::fits::ImageScalingOptions::ImageScalingOptions ( )

inlineexplicit

Default Ctor.

Scaling is disabled by default.

Definition at line 378 of file fitsCompression.h.

            : ImageScalingOptions(NONE, 0, {}, 1, 4.0, 5.0, false, std::numeric_limits<double>::quiet_NaN(),
                                  std::numeric_limits<double>::quiet_NaN()) {}

ImageScalingOptions() [2/3]

lsst::afw::fits::ImageScalingOptions::ImageScalingOptions	(	ScalingAlgorithm	algorithm_,
		int	bitpix_,
		std::vector< std::string > const &	maskPlanes_ = {},
		int	seed_ = 1,
		float	quantizeLevel_ = 4.0,
		float	quantizePad_ = 5.0,
		bool	fuzz_ = true,
		double	bscale_ = 1.0,
		double	bzero_ = 0.0
	)

General purpose Ctor.

Parameters

[in]	algorithm_	Scaling algorithm to use
[in]	bitpix_	Bits per pixel (8,16,32,64,-32,-64), or 0 to match pixel type exactly.
[in]	maskPlanes_	Mask planes to ignore when doing statistics
[in]	seed_	Seed for random number generator when fuzzing
[in]	quantizeLevel_	Divisor of the standard deviation for STDEV_* scaling
[in]	quantizePad_	Number of stdev to allow on the low side (for STDEV_POSITIVE/NEGATIVE)
[in]	fuzz_	Fuzz the values when quantising floating-point values?
[in]	bscale_	Manually specified BSCALE (for MANUAL scaling)
[in]	bzero_	Manually specified BZERO (for MANUAL scaling)

Definition at line 130 of file fitsCompression.cc.

        : algorithm(algorithm_),
          bitpix(bitpix_),
          fuzz(fuzz_),
          seed(std::abs(seed_ - 1) % (N_RANDOM - 1) +
               1),  // zero is bad (cfitsio uses non-deterministic method)
          maskPlanes(maskPlanes_),
          quantizeLevel(quantizeLevel_),
          quantizePad(quantizePad_),
          bscale(bscale_),
          bzero(bzero_) {}

ImageScalingOptions() [3/3]

lsst::afw::fits::ImageScalingOptions::ImageScalingOptions ( int  bitpix_, double  bscale_ = 1.0, double  bzero_ = 0.0  )

inline

Manual scaling Ctor.

Parameters

[in]	bitpix_	Bits per pixel (8,16,32,64,-32,-64), or 0 to match pixel type exactly.
[in]	bscale_	Manually specified BSCALE
[in]	bzero_	Manually specified BZERO

Definition at line 403 of file fitsCompression.h.

            : ImageScalingOptions(MANUAL, bitpix_, {}, 1, 4.0, 5.0, false, bscale_, bzero_) {}

Member Function Documentation

determine() [1/2]

template<typename T >

ImageScale lsst::afw::fits::ImageScalingOptions::determine ( image::ImageBase< T > const &  image, std::shared_ptr< image::Mask< image::MaskPixel > const >  mask = nullptr  ) const

inline

Determine the scaling for a particular image.

Parameters

[in]	image	Image for which to determine scaling
[in]	mask	Mask for image (used to measuring statistics)

Definition at line 412 of file fitsCompression.h.

                                                                                              {
        auto const arrays = _toArray(image, mask);
        return determine(arrays.first, arrays.second);
    }

determine() [2/2]

template<typename T , int N>

ImageScale lsst::afw::fits::ImageScalingOptions::determine	(	ndarray::Array< T const, N, N > const &	image,
		ndarray::Array< bool, N, N > const &	mask
	)		const

Determine the scaling for a particular image.

Parameters

[in]	image	Image for which to determine scaling
[in]	mask	Mask for image (used to measuring statistics)

Member Data Documentation

algorithm

ScalingAlgorithm lsst::afw::fits::ImageScalingOptions::algorithm

Scaling algorithm to use.

Definition at line 365 of file fitsCompression.h.

bitpix

int lsst::afw::fits::ImageScalingOptions::bitpix

Bits per pixel (0, 8,16,32,64,-32,-64)

Definition at line 366 of file fitsCompression.h.

bscale

double lsst::afw::fits::ImageScalingOptions::bscale

Manually specified BSCALE (for MANUAL scaling)

Definition at line 372 of file fitsCompression.h.

bzero

double lsst::afw::fits::ImageScalingOptions::bzero

Manually specified BZERO (for MANUAL scaling)

Definition at line 373 of file fitsCompression.h.

fuzz

bool lsst::afw::fits::ImageScalingOptions::fuzz

Fuzz the values when quantising floating-point values?

Definition at line 367 of file fitsCompression.h.

maskPlanes

std::vector<std::string> lsst::afw::fits::ImageScalingOptions::maskPlanes

Mask planes to ignore when doing statistics.

Definition at line 369 of file fitsCompression.h.

quantizeLevel

float lsst::afw::fits::ImageScalingOptions::quantizeLevel

Divisor of the standard deviation for STDEV_* scaling.

Definition at line 370 of file fitsCompression.h.

quantizePad

float lsst::afw::fits::ImageScalingOptions::quantizePad

Number of stdev to allow on the low/high side (for STDEV_POSITIVE/NEGATIVE)

Definition at line 371 of file fitsCompression.h.

seed

int lsst::afw::fits::ImageScalingOptions::seed

Seed for random number generator when fuzzing.

Definition at line 368 of file fitsCompression.h.

---

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

• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/include/lsst/afw/fitsCompression.h
• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/src/fitsCompression.cc