Scale to apply to image. More...

#include <fitsCompression.h>

Public Member Functions
	ImageScale (int bitpix_, double bscale_, double bzero_)
	Constructor. More...

template<typename T >
std::shared_ptr< detail::PixelArrayBase >	toFits (ndarray::Array< T const, 2, 2 > const &image, bool forceNonfiniteRemoval, bool fuzz=true, ndarray::Array< long, 1 > const &tiles=ndarray::Array< long, 1, 1 >(), int seed=1) const
	Convert to an array of pixel values to write to FITS. More...

template<typename T >
ndarray::Array< T, 2, 2 >	fromFits (ndarray::Array< T, 2, 2 > const &image) const
	Convert to an array. More...

Public Attributes
int	bitpix
	Bits per pixel; negative means floating-point: 8,16,32,64,-32,-64. More...

double	bscale
	Scale to apply when reading from FITS. More...

double	bzero
	Zero-point to apply when reading from FITS. More...

long	blank
	Value for integer images indicating non-finite values. More...

Detailed Description

Scale to apply to image.

Images are scaled to the type implied by the provided BITPIX using the provided scale and zero-point:

value in memory = BZERO + BSCALE * value in FITS

In addition to scaling, a random field of values distributed [0,1) may be added before quantisation ("fuzz"); this preserves the expectation value of the floating-point image, while increasing the variance by 1/12.

Definition at line 262 of file fitsCompression.h.

Constructor & Destructor Documentation

◆ ImageScale()

lsst::afw::fits::ImageScale::ImageScale	(	int	bitpix_,
		double	bscale_,
		double	bzero_
	)

inline

Constructor.

We make BZERO an integer multiple of BSCALE, because cfitsio notes: "This helps to ensure the same scaling will be performed if the file undergoes multiple fpack/funpack cycles".

The BLANK is 255 for BITPIX=8 since FITS specifies that uses unsigned char; otherwise it is set to the maximum int for the appropriate signed integer.

Definition at line 276 of file fitsCompression.h.

             : bitpix(bitpix_),
               bscale(bscale_),
               bzero(std::floor(bzero_ / bscale_ + 0.5) * bscale_),
               blank(bitpix > 0 ? (bitpix == 8 ? 255 : (1L << (bitpix - 1)) - 1) : 0) {}

Member Function Documentation

◆ fromFits()

template<typename T >

ndarray::Array< T, 2, 2 > lsst::afw::fits::ImageScale::fromFits ( ndarray::Array< T, 2, 2 > const & image ) const

Convert to an array.

Use of this method is generally not necessary, since cfitsio automatically applies the scaling on read. However, it may be useful for applying novel scalings (e.g., logarithmic).

Definition at line 486 of file fitsCompression.cc.

                                                                                    {
     ndarray::Array<T, 2, 2> memory = ndarray::allocate(image.getShape());
     memory.deep() = bscale * image + bzero;
     return memory;
 }

◆ toFits()

template<typename T >

std::shared_ptr< detail::PixelArrayBase > lsst::afw::fits::ImageScale::toFits	(	ndarray::Array< T const, 2, 2 > const &	image,
		bool	forceNonfiniteRemoval,
		bool	fuzz = `true`,
		ndarray::Array< long, 1 > const &	tiles = `ndarray::Array<long, 1, 1>()`,
		int	seed = `1`
	)		const

Convert to an array of pixel values to write to FITS.

Parameters

[in]	image	Image to scale
[in]	forceNonfiniteRemoval	Force removal of non-finite values? This is useful for lossless compression, because cfitsio doesn't mask out non-finite values, and they end up contaminating the entire tile.
[in]	fuzz	Add random values before quantising?
[in]	tiles	Tile dimensions
[in]	seed	Seed for random number generator

Returns: Array of pixel values, appropriately scaled.

Definition at line 409 of file fitsCompression.cc.

                                                                            {
     if (!std::numeric_limits<T>::is_integer && bitpix < 0) {
         if (bitpix != detail::Bitpix<T>::value) {
             throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                               "Floating-point images may not be converted to different floating-point types");
         }
         if (bscale != 1.0 || bzero != 0.0) {
             throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                               "Scaling may not be applied to floating-point images");
         }
     }
 
     if (bitpix < 0 || (bitpix == 0 && !std::numeric_limits<T>::is_integer) ||
         (bscale == 1.0 && bzero == 0.0 && !fuzz)) {
         if (!forceNonfiniteRemoval) {
             // Type conversion only
             return detail::makePixelArray(bitpix, ndarray::Array<T const, 1, 1>(ndarray::flatten<1>(image)));
         }
         if (!std::numeric_limits<T>::is_integer) {
             ndarray::Array<T, 1, 1> out = ndarray::allocate(image.getNumElements());
             auto outIter = out.begin();
             auto const& flatImage = ndarray::flatten<1>(image);
             for (auto inIter = flatImage.begin(); inIter != flatImage.end(); ++inIter, ++outIter) {
                 *outIter = std::isfinite(*inIter) ? *inIter : std::numeric_limits<T>::max();
             }
             return detail::makePixelArray(bitpix, out);
         }
         // Fall through for explicit scaling
     }
 
     // Note: BITPIX=8 treated differently, since it uses unsigned values; the rest use signed */
     double min = bitpix == 8 ? 0 : -std::pow(2.0, bitpix - 1);
     double max = bitpix == 8 ? 255 : (std::pow(2.0, bitpix - 1) - 1.0);
 
     if (!std::numeric_limits<T>::is_integer && bitpix == 32) {
         // cfitsio saves space for N_RESERVED_VALUES=10 values at the low end
         min += N_RESERVED_VALUES;
     }
 
     double const scale = 1.0 / bscale;
     std::size_t const num = image.getNumElements();
     bool const applyFuzz = fuzz && !std::numeric_limits<T>::is_integer && bitpix > 0;
     ndarray::Array<double, 1, 1> out;
     if (applyFuzz) {
         if (tiles.isEmpty()) {
             throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                               "Tile sizes must be provided if fuzzing is desired");
         }
         out = CfitsioRandom(seed).forImage<double>(image.getShape(), tiles);
     } else {
         out = ndarray::allocate(num);
         out.deep() = 0;
     }
     auto outIter = out.begin();
     auto const& flatImage = ndarray::flatten<1>(image);
     for (auto inIter = flatImage.begin(); inIter != flatImage.end(); ++inIter, ++outIter) {
         double value = (*inIter - bzero) * scale;
         if (!std::isfinite(value)) {
             // This choice of "max" for non-finite and overflow pixels is mainly cosmetic --- it has to be
             // something, and "min" would produce holes in the cores of bright stars.
             *outIter = blank;
             continue;
         }
         if (applyFuzz) {
             // Add random factor [0.0,1.0): adds a variance of 1/12,
             // but preserves the expectation value given the floor()
             value += *outIter;
         }
         *outIter = (value < min ? blank : (value > max ? blank : std::floor(value)));
     }
     return detail::makePixelArray(bitpix, out);
 }

Member Data Documentation

◆ bitpix

int lsst::afw::fits::ImageScale::bitpix

Bits per pixel; negative means floating-point: 8,16,32,64,-32,-64.

Definition at line 263 of file fitsCompression.h.

◆ blank

long lsst::afw::fits::ImageScale::blank

Value for integer images indicating non-finite values.

Definition at line 266 of file fitsCompression.h.

◆ bscale

double lsst::afw::fits::ImageScale::bscale

Scale to apply when reading from FITS.

Definition at line 264 of file fitsCompression.h.

◆ bzero

double lsst::afw::fits::ImageScale::bzero

Zero-point to apply when reading from FITS.

Definition at line 265 of file fitsCompression.h.

The documentation for this struct 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

Public Member Functions

Public Attributes