Class ImageScalingOptions

Class Documentation

class ImageScalingOptions

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.

Unnamed Group

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

Parameters

  • [in] image: Image for which to determine scaling

  • [in] mask: Mask for image (used to measuring statistics)

template<typename T, int N>
ImageScale determine(ndarray::Array<T const, N, N> const &image, ndarray::Array<bool, N, N> const &mask) const

Public Types

enum ScalingAlgorithm

Values:

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.

Public Functions

ImageScalingOptions()

Default Ctor

Scaling is disabled by default.

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)

ImageScalingOptions(int bitpix_, double bscale_ = 1.0, double bzero_ = 0.0)

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

Public Members

ScalingAlgorithm algorithm

Scaling algorithm to use.

int bitpix

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

bool fuzz

Fuzz the values when quantising floating-point values?

int seed

Seed for random number generator when fuzzing.

std::vector<std::string> maskPlanes

Mask planes to ignore when doing statistics.

float quantizeLevel

Divisor of the standard deviation for STDEV_* scaling.

float quantizePad

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

double bscale

Manually specified BSCALE (for MANUAL scaling)

double bzero

Manually specified BZERO (for MANUAL scaling)