Class lsst::afw::fits::ImageScalingOptions

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.