LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Member Functions | Public Attributes | List of all members
lsst::afw::fits::ImageScale Struct Reference

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.

277  : bitpix(bitpix_),
278  bscale(bscale_),
279  bzero(std::floor(bzero_ / bscale_ + 0.5) * bscale_),
280  blank(bitpix > 0 ? (bitpix == 8 ? 255 : (1L << (bitpix - 1)) - 1) : 0) {}
std::floor
T floor(T... args)
lsst::afw::fits::ImageScale::bscale
double bscale
Scale to apply when reading from FITS.
Definition: fitsCompression.h:264
lsst::afw::fits::ImageScale::blank
long blank
Value for integer images indicating non-finite values.
Definition: fitsCompression.h:266
lsst::afw::fits::ImageScale::bitpix
int bitpix
Bits per pixel; negative means floating-point: 8,16,32,64,-32,-64.
Definition: fitsCompression.h:263
lsst::afw::fits::ImageScale::bzero
double bzero
Zero-point to apply when reading from FITS.
Definition: fitsCompression.h:265

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 485 of file fitsCompression.cc.

485  {
486  ndarray::Array<T, 2, 2> memory = ndarray::allocate(image.getShape());
487  memory.deep() = bscale * image + bzero;
488  return memory;
489 }
lsst::afw::image
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
Definition: imageAlgorithm.dox:1

◆ 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]imageImage to scale
[in]forceNonfiniteRemovalForce 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]fuzzAdd random values before quantising?
[in]tilesTile dimensions
[in]seedSeed for random number generator
Returns
Array of pixel values, appropriately scaled.

Definition at line 408 of file fitsCompression.cc.

411  {
412  if (!std::numeric_limits<T>::is_integer && bitpix < 0) {
413  if (bitpix != detail::Bitpix<T>::value) {
414  throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
415  "Floating-point images may not be converted to different floating-point types");
416  }
417  if (bscale != 1.0 || bzero != 0.0) {
418  throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
419  "Scaling may not be applied to floating-point images");
420  }
421  }
422 
423  if (bitpix < 0 || (bitpix == 0 && !std::numeric_limits<T>::is_integer) ||
424  (bscale == 1.0 && bzero == 0.0 && !fuzz)) {
425  if (!forceNonfiniteRemoval) {
426  // Type conversion only
427  return detail::makePixelArray(bitpix, ndarray::Array<T const, 1, 1>(ndarray::flatten<1>(image)));
428  }
429  if (!std::numeric_limits<T>::is_integer) {
430  ndarray::Array<T, 1, 1> out = ndarray::allocate(image.getNumElements());
431  auto outIter = out.begin();
432  auto const& flatImage = ndarray::flatten<1>(image);
433  for (auto inIter = flatImage.begin(); inIter != flatImage.end(); ++inIter, ++outIter) {
434  *outIter = std::isfinite(*inIter) ? *inIter : std::numeric_limits<T>::max();
435  }
436  return detail::makePixelArray(bitpix, out);
437  }
438  // Fall through for explicit scaling
439  }
440 
441  // Note: BITPIX=8 treated differently, since it uses unsigned values; the rest use signed */
442  double min = bitpix == 8 ? 0 : -std::pow(2.0, bitpix - 1);
443  double max = bitpix == 8 ? 255 : (std::pow(2.0, bitpix - 1) - 1.0);
444 
445  if (!std::numeric_limits<T>::is_integer && bitpix == 32) {
446  // cfitsio saves space for N_RESERVED_VALUES=10 values at the low end
447  min += N_RESERVED_VALUES;
448  }
449 
450  double const scale = 1.0 / bscale;
451  std::size_t const num = image.getNumElements();
452  bool const applyFuzz = fuzz && !std::numeric_limits<T>::is_integer && bitpix > 0;
453  ndarray::Array<double, 1, 1> out;
454  if (applyFuzz) {
455  if (tiles.isEmpty()) {
456  throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
457  "Tile sizes must be provided if fuzzing is desired");
458  }
459  out = CfitsioRandom(seed).forImage<double>(image.getShape(), tiles);
460  } else {
461  out = ndarray::allocate(num);
462  out.deep() = 0;
463  }
464  auto outIter = out.begin();
465  auto const& flatImage = ndarray::flatten<1>(image);
466  for (auto inIter = flatImage.begin(); inIter != flatImage.end(); ++inIter, ++outIter) {
467  double value = (*inIter - bzero) * scale;
468  if (!std::isfinite(value)) {
469  // This choice of "max" for non-finite and overflow pixels is mainly cosmetic --- it has to be
470  // something, and "min" would produce holes in the cores of bright stars.
471  *outIter = blank;
472  continue;
473  }
474  if (applyFuzz) {
475  // Add random factor [0.0,1.0): adds a variance of 1/12,
476  // but preserves the expectation value given the floor()
477  value += *outIter;
478  }
479  *outIter = (value < min ? blank : (value > max ? blank : std::floor(value)));
480  }
481  return detail::makePixelArray(bitpix, out);
482 }
min
int min
Definition: BoundedField.cc:103
max
int max
Definition: BoundedField.cc:104
LSST_EXCEPT
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
N_RESERVED_VALUES
int const N_RESERVED_VALUES
Definition: fitsCompression.cc:13
std::isfinite
T isfinite(T... args)
std::numeric_limits::max
T max(T... args)
lsst::afw.display.ds9.scale
def scale(algorithm, min, max=None, frame=None)
Definition: ds9.py:108
lsst::afw::fits::detail::makePixelArray
std::shared_ptr< PixelArrayBase > makePixelArray(int bitpix, ndarray::Array< T, 1, 1 > const &array)
Create a PixelArray suitable for an image with the nominated BITPIX.
Definition: fitsCompression.h:134
std::pow
T pow(T... args)

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:
Generated on Fri Nov 26 2021 10:16:11 for LSST Applications by doxygen 1.9.1