Namespace lsst::afw

namespace afw

namespace cameraGeom

Enums

enum ReadoutCorner

Readout corner, in the frame of reference of the assembled image

Values:

LL

LR

UR

UL

enum AssemblyState

Assembly state of the amplifier, used to identify bounding boxes and component existence.

Values:

RAW

SCIENCE

enum DetectorType

Type of imaging detector

Values:

SCIENCE

FOCUS

GUIDER

WAVEFRONT

Functions

void swap(CameraSys &a, CameraSys &b)

std::ostream &operator<<(std::ostream &os, CameraSysPrefix const &detSysPrefix)

std::ostream &operator<<(std::ostream &os, CameraSys const &cameraSys)

std::ostream &operator<<(std::ostream &os, TransformMap::Connection const &connection)

Variables

CameraSys const FOCAL_PLANE

Focal plane coordinates: Position on a 2-d planar approximation to the focal plane (x,y mm).

The origin and orientation may be defined by the camera team, but we strongly recommend that the origin be on the optical axis and (if using CCD detectors) that the X axis be aligned along CCD rows.

Note

Location and orientation of detectors are defined in a 3-d version of FOCAL_PLANE coordinates (the z axis is also relevant). Rectilinear x, y (and z when talking about the location of a detector) on the camera focal plane (mm). For z=0 choose a convenient point near the focus at x, y = 0.

CameraSys const FIELD_ANGLE

Field angle coordinates: Angle of a principal ray relative to the optical axis (x,y radians).

The orientation of the x,y axes is the same as FOCAL_PLANE.

CameraSysPrefix const PIXELS

Pixel coordinates: Nominal position on the entry surface of a given detector (x, y unbinned pixels).

For CCD detectors the x axis must be along rows (the direction of the serial register). This is required for our interpolation algorithm to interpolate across bad columns.

This ignores manufacturing imperfections, “tree ring” distortions and all other such effects. It is a uniform grid of rectangular (usually square) pixels.

Warning

This is a detector prefix; call Detector.makeCameraSys(PIXELS) to make a full CameraSys.

CameraSysPrefix const TAN_PIXELS

Tangent-plane pixels on the detector (x, y unbinned pixels)

Converting from PIXELS to TAN_PIXELS has the effect of removing optical distortion (and the distortion due to rectangular pixels) with the point at the center of the detector being unaffected by the transformation.

In detail, PIXELS->TAN_PIXELS is PIXELS->FIELD_ANGLE plus an affine transformation, such that:

• The x,y axes are parallel to the detector axes

• The dimensions are nominal pixels at the center of the focal plane (where nominal pixels size is mean of x, y pixel size).

• The point at the center of the detector has the same value in PIXELS and TAN_PIXELS

This is a detector prefix; call Detector.makeCameraSys(TAN_PIXELS) to make a full CameraSys.

CameraSysPrefix const ACTUAL_PIXELS

The actual pixels where the photon lands and electrons are generated (x,y unbinned) This takes into account manufacturing defects, “tree ring” distortions and other such effects.

This is a detector prefix; call Detector.makeCameraSys(ACTUAL_PIXELS) to make a full CameraSys.

class Amplifier

#include <Amplifier.h>

Geometry and electronic information about raw amplifier images

The Amplifier class itself is an abstract base class that provides no mutation or copy interfaces. Typically Amplifiers are constructed via the Builder subclass, which can produce a shared_ptr to an immutable Amplifier instance.

Here is a pictorial example showing the meaning of flipX and flipY:

    CCD with 4 amps        Desired assembled output      Use these parameters

    --x         x--            y
   |  amp1    amp2 |           |                               flipX       flipY
   y               y           |                       amp1    False       True
                               | CCD image             amp2    True        True
   y               y           |                       amp3    False       False
   |  amp3    amp4 |           |                       amp4    True        False
    --x         x--             ----------- x

Note

• All bounding boxes are parent boxes with respect to the raw image.

• The overscan and prescan bounding boxes represent the full regions; unusable regions are set via ISR configuration parameters.

• xyOffset is not used for instrument signature removal (ISR); it is intended for use by display utilities. It supports construction of a raw CCD image in the case that raw data is provided as individual amplifier images (which is uncommon):

  • Use 0,0 for cameras that supply raw data as a raw CCD image (most cameras)

  • Use nonzero for cameras that supply raw data as separate amplifier images with xy0=0,0 (LSST)

• This design assumes assembled X is always +/- raw X, which we require for CCDs (so that bleed trails are always along the Y axis).

Subclassed by lsst::afw::cameraGeom::Amplifier::Builder

class Camera : public lsst::afw::cameraGeom::DetectorCollection, public lsst::afw::table::io::PersistableFacade<Camera>

#include <Camera.h>

An immutable representation of a camera.

Cameras are created (and modified, when necessary) via the Camera::Builder helper class.

class CameraSys

#include <CameraSys.h>

Camera coordinate system; used as a key in in TransformMap

class CameraSysPrefix

#include <CameraSys.h>

Camera coordinate system prefix

Used for coordinate systems that are detector-based before the detector name is known (e.g. for constants such as PIXELS).

This is Jim Bosch’s clever idea for simplifying Detector.convert; CameraSys is always complete and CameraSysPrefix is not.

class Detector : public lsst::afw::cameraGeom::DetectorBase, public lsst::afw::table::io::PersistableFacade<Detector>, public Storable

#include <Detector.h>

A representation of a detector in a mosaic camera.

Detector holds both simple data fields (see DetectorBase) and a set of related coordinate systems and transforms, and acts as a container of Amplifier objects.

Detector is immutable, but copies can be modified via one of its Builder classes. A Detector must be created initially as part of a Camera (see Camera::Builder::add), but can then be modified either individually (see Detector::rebuild and Detector::PartialRebuilder) or as part of modifying the full Camera (see Detector::InCameraBuilder).

The coordinate systems and transforms known to a Detector are shared with its parent Camera and all other Detectors in that Camera.

class DetectorBase

#include <Detector.h>

An abstract base class that provides common accessors for Detector and Detector::Builder.

Subclassed by lsst::afw::cameraGeom::Detector, lsst::afw::cameraGeom::Detector::Builder

class DetectorCollection : public lsst::afw::cameraGeom::DetectorCollectionBase<Detector const>, public lsst::afw::table::io::PersistableFacade<DetectorCollection>, public lsst::afw::table::io::Persistable

#include <DetectorCollection.h>

An immutable collection of Detectors that can be accessed by name or ID

Subclassed by lsst::afw::cameraGeom::Camera

template<typename T>
class DetectorCollectionBase

#include <DetectorCollection.h>

An abstract base class for collections of Detectors and specific subclasses thereof.

This class provides the common interface and implementation for

DetectorCollection (which holds true Detector instances) and Camera::Builder (which holds Detector::InCameraBuilder instances). It is not intended to define an interface independent of those classes.

Template Parameters

• T: Element type; either Detector or a subclass thereof.

class Orientation

#include <Orientation.h>

Describe a detector’s orientation in the focal plane

All rotations are about the reference point on the detector. Rotations are intrinsic, meaning each rotation is applied in the coordinates system produced by the previous rotation. Rotations are applied in this order: yaw (Z), pitch (Y’), and roll (X’’).

Warning

: default refPoint is -0.5, -0.5 (the lower left corner of a detector). This means that the default-constructed Orientation is not a unity transform, but instead includes a 1/2 pixel shift.

class TransformMap : public lsst::afw::table::io::PersistableFacade<TransformMap>, public lsst::afw::table::io::Persistable

#include <TransformMap.h>

A registry of 2-dimensional coordinate transforms for a specific camera.

Represents the interrelationships between camera coordinate systems for a particular camera. It can be seen as a mapping between a pair of CameraSys and a Transform between them (though it does not conform to either the C++ map or Python dictionary APIs).

TransformMap supports:

• Transforming between any two supported CameraSys using the transform methods.

• Retrieving a transform between any two supported CameraSys using getTransform.

• Iteration over supported CameraSys using begin and end in C++ and standard Python iteration in Python.

TransformMap is immutable and must always be held by shared_ptr; this is enforced by making all non-deleted constructors private, and instead providing static make member functions for construction (in Python, these are exposed as regular constructors).

Unless otherwise specified, all methods guarantee only basic exception safety.

namespace coord

Functions

std::ostream &operator<<(std::ostream &os, Observatory const &obs)

Print an Observatory to the stream

Parameters

• [inout] os: Stream to print to

• [in] obs: the Observatory to print

std::ostream &operator<<(std::ostream &os, Weather const &weath)

print a Weather to an output stream

class Observatory

#include <Observatory.h>

Hold the location of an observatory

class Weather

#include <Weather.h>

Basic weather information sufficient for a simple model for air mass or refraction

Weather is immutable.

namespace detection

Typedefs

typedef std::uint64_t FootprintIdPixel

Pixel type for FootprintSet::insertIntoImage()

This is independent of the template parameters for FootprintSet, and including it within FootprintSet makes it difficult for SWIG to interpret the type.

typedef afw::table::ColumnViewT<PeakRecord> PeakColumnView

typedef afw::table::CatalogT<PeakRecord> PeakCatalog

typedef afw::table::CatalogT<PeakRecord const> ConstPeakCatalog

Functions

std::shared_ptr<Footprint> mergeFootprints(Footprint const &footprint1, Footprint const &footprint2)

Merges two Footprints appends their peaks, and unions their spans, returning a new Footprint. Region is not preserved, and is set to an empty lsst::geom::Box2I object.

std::vector<lsst::geom::Box2I> footprintToBBoxList(Footprint const &footprint)

Return a list of BBoxs, whose union contains exactly the pixels in the footprint, neither more nor less.

Useful in generating sets of meas::algorithms::Defects for the ISR

Parameters

• footprint: Footprint to turn into bounding box list

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
HeavyFootprint<ImagePixelT, MaskPixelT, VariancePixelT> makeHeavyFootprint(Footprint const &foot, lsst::afw::image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT> const &img, HeavyFootprintCtrl const *ctrl = NULL)

Create a HeavyFootprint with footprint defined by the given Footprint and pixel values from the given MaskedImage.

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
std::shared_ptr<HeavyFootprint<ImagePixelT, MaskPixelT, VariancePixelT>> mergeHeavyFootprints(HeavyFootprint<ImagePixelT, MaskPixelT, VariancePixelT> const &h1, HeavyFootprint<ImagePixelT, MaskPixelT, VariancePixelT> const &h2)

Sum the two given HeavyFootprints h1 and h2, returning a HeavyFootprint with the union footprint, and summed pixels where they overlap. The peak list is the union of the two inputs.

std::ostream &operator<<(std::ostream &os, PeakRecord const &record)

Threshold createThreshold(const double value, const std::string type = "value", const bool polarity = true)

Factory method for creating Threshold objects

Return

desired Threshold

Parameters

• value: value of threshold

• type: string representation of a ThresholdType. This parameter is optional. Allowed values are: “variance”, “value”, “stdev”, “pixel_stdev”

• polarity: If true detect positive objects, false for negative

class Footprint : public lsst::afw::table::io::PersistableFacade<lsst::afw::detection::Footprint>, public lsst::afw::table::io::Persistable

#include <Footprint.h>

Class to describe the properties of a detected object from an image

A Footprint is designed to be constructed with information about a detected object in an image. Internally a Footprint holds a SpanSet which is used to describe the location of the object in the image (the x, y pixel locations which are considered part of the object). In addition a Footprint contains a PeakCatalog which is used to store the location and intensity of peaks in the detection.

Subclassed by lsst::afw::detection::HeavyFootprint< ImagePixelT, MaskPixelT, VariancePixelT >

class FootprintControl

#include <FootprintCtrl.h>

A Control Object for Footprints, controlling e.g. how they are grown

class FootprintMergeList

#include <FootprintMerge.h>

List of Merged Footprints.

Stores a vector of FootprintMerges and SourceRecords that contain the union of different footprints and which filters it was detected in. Individual Footprints from a SourceCatalog can be added to the vector (note that any SourceRecords with parent!=0 will be skipped). If a Footprint overlaps an existing FootprintMerge, the Footprint will be added to it. If not, then a new FootprintMerge will be created and added to the vector.

The search algorithm uses a brute force approach over the current list. This should be fine if we are operating on smallish number of objects, such as at the tract level.

class FootprintSet

#include <FootprintSet.h>

A set of Footprints, associated with a MaskedImage

class GaussianPsf : public lsst::afw::table::io::PersistableFacade<GaussianPsf>, public lsst::afw::detection::Psf

#include <GaussianPsf.h>

A circularly symmetric Gaussian Psf class with no spatial variation, intended mostly for testing purposes.

This class is essentially an alternate implementation of meas::algorithms::SingleGaussianPsf; While SingleGaussianPsf inherits from ImagePsf and KernelPsf, and hence delegates to those various operations relating to the PSF model image (e.g. computeShape()), GaussianPsf computes these analytically.

template<typename ImagePixelT, typename MaskPixelT = lsst::afw::image::MaskPixel, typename VariancePixelT = lsst::afw::image::VariancePixel>
class HeavyFootprint : public lsst::afw::table::io::PersistableFacade<HeavyFootprint<ImagePixelT, MaskPixelT, VariancePixelT>>, public lsst::afw::detection::Footprint

#include <HeavyFootprint.h>

A set of pixels in an Image, including those pixels’ actual values

class HeavyFootprintCtrl

#include <FootprintCtrl.h>

A control object for HeavyFootprints

class PeakRecord : public lsst::afw::table::BaseRecord

#include <Peak.h>

Record class that represents a peak in a Footprint

class PeakTable : public lsst::afw::table::BaseTable

#include <Peak.h>

Table class for Peaks in Footprints.

class Psf : public lsst::afw::table::io::PersistableFacade<Psf>, public Storable

#include <Psf.h>

A polymorphic base class for representing an image’s Point Spread Function

Most of a Psf’s functionality involves its evaluation at a position and color, either or both of which may be unspecified (which will result in evaluation at some average position or color). Unlike the closely-related Kernel class, there is no requirement that a Psf have a well-defined spatial function or any parameters. Psfs are not necessarily continuous, and the dimensions of image of the Psf at a point may not be fixed.

Psfs have two methods for getting at image at a point:

• the image returned by computeImage() is in the same coordinate system as the pixelized image

• the image returned by computeKernelImage() is in an offset coordinate system with the point P at (0,0); this implies that the image (x0,y0) will be negative

Because P does not need to have integer coordinates, these two images are fractionally offset from each other and we use interpolation to get (1) from (2).

Psfs are immutable - derived classes should have no non-const methods, and hence should be fully-defined after construction. This allows shared_ptrs to Psfs to be passed around and shared between objects without concern for whether they will be unexpectedly modified.

In most cases, Psf derived classes should inherit from meas::algorithms::ImagePsf or meas::algorithms::KernelPsf, as these will provide default implementions for several member functions.

Subclassed by lsst::afw::detection::GaussianPsf, lsst::meas::algorithms::ImagePsf

class Threshold

#include <Threshold.h>

A Threshold is used to pass a threshold value to detection algorithms

The threshold may be a simple value (type == VALUE), or in units of the image standard deviation. Alternatively you may specify that you’ll provide the standard deviation (type == STDEV) or variance (type == VARIANCE)

Note that the constructor is not declared explicit, so you may pass a bare threshold, and it’ll be interpreted as a VALUE.

namespace fits

Functions

LSST_EXCEPTION_TYPE(FitsError, lsst::pex::exceptions::IoError, lsst::afw::fits::FitsError)

An exception thrown when problems are found when reading or writing FITS files. An exception thrown when a FITS file has the wrong type.

std::string makeErrorMessage(std::string const &fileName = "", int status = 0, std::string const &msg = "")

Return an error message reflecting FITS I/O errors.

Parameters

• [in] fileName: FITS filename to be included in the error message.

• [in] status: The last status value returned by the cfitsio library; if nonzero, the error message will include a description from cfitsio.

• [in] msg: An additional custom message to include.

std::string makeErrorMessage(std::string const &fileName, int status, boost::format const &msg)

std::string makeErrorMessage(void *fptr, int status = 0, std::string const &msg = "")

Return an error message reflecting FITS I/O errors.

Parameters

• [in] fptr: A cfitsio fitsfile pointer to be inspected for a filename. Passed as void* to avoid including fitsio.h in the header file.

• [in] status: The last status value returned by the cfitsio library; if nonzero, the error message will include a description from cfitsio.

• [in] msg: An additional custom message to include.

std::string makeErrorMessage(void *fptr, int status, boost::format const &msg)

std::string makeLimitedFitsHeader(lsst::daf::base::PropertySet const &metadata, std::set<std::string> const &excludeNames = {})

Format a PropertySet into an FITS header string in a simplistic fashion.

This function is designed to format data for creating a WCS. As such, it is quite limited:

• It skips entries whose name is longer than 8 characters, since none are used for FITS-WCS

• It skips string entries if the fully formatted string is longer than 80 characters

• It skips entries with types it cannot handle (e.g. long, long long)

• For entries that have array data, it only writes the final value, since that is the value that should be used by code that reads FITS headers.

• It makes no attempt to insure that required entries, such as SIMPLE, are present.

Return

a FITS header string (exactly 80 characters per entry, no line terminators)

Parameters

• [in] metadata: Metadata to format; if this is a PropertyList then the order of items is preserved

• [in] excludeNames: Names of entries to exclude from the returned header string

template<typename T>
int getBitPix()

Return the cfitsio integer BITPIX code for the given data type.

template<typename T, int N, int C>
ndarray::Array<T const, N, N> const makeContiguousArray(ndarray::Array<T, N, C> const &array)

Construct a contiguous ndarray

A deep copy is only performed if the array is not already contiguous.

std::shared_ptr<daf::base::PropertyList> combineMetadata(std::shared_ptr<const daf::base::PropertyList> first, std::shared_ptr<const daf::base::PropertyList> second)

Combine two sets of metadata in a FITS-appropriate fashion

“COMMENT” and “HISTORY” entries:

• If of type std::string then the values in second are appended to values in first

• If not of type std::string then they are silently ignored

All other entries:

• Values in second override values in first (regardless of type)

• Only scalars are copied; if a vector is found, only the last value is copied

Return

The combined metadata. Item names have the following order:

• names in first, omitting all names except “COMMENT” and “HISTORY” that appear in second

• names in second, omitting “COMMENT” and “HISTORY” if valid versions appear in first

Parameters

• [in] first: The first set of metadata to combine

• [in] second: The second set of metadata to combine

std::shared_ptr<daf::base::PropertyList> readMetadata(std::string const &fileName, int hdu = DEFAULT_HDU, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Return the metadata (header entries) from a FITS file.

Parameters

• fileName: the file whose header will be read

• hdu: the HDU to read (0-indexed; 0 is the Primary HDU).

• strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Parameters

• [in] fileName: File to read.

• [in] hdu: HDU to read, 0-indexed. The special value of afw::fits::DEFAULT_HDU will read the first non-empty HDU.

• [in] strip: If true, ignore special header keys usually managed by cfitsio (e.g. NAXIS).

std::shared_ptr<daf::base::PropertyList> readMetadata(fits::MemFileManager &manager, int hdu = DEFAULT_HDU, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Parameters

• manager: the in-memory file whose header will be read

• hdu: the HDU to read (0-indexed; 0 is the Primary HDU).

• strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

std::shared_ptr<daf::base::PropertyList> readMetadata(fits::Fits &fitsfile, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Parameters

• fitsfile: the file and HDU to be read

• strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

void setAllowImageCompression(bool allow)

bool getAllowImageCompression()

ImageCompressionOptions::CompressionAlgorithm compressionAlgorithmFromString(std::string const &name)

Interpret compression algorithm expressed in string.

std::string compressionAlgorithmToString(ImageCompressionOptions::CompressionAlgorithm algorithm)

Provide string version of compression algorithm.

ImageCompressionOptions::CompressionAlgorithm compressionAlgorithmFromCfitsio(int cfitsio)

Convert compression algorithm from cfitsio to ImageCompressionOptions::CompressionAlgorithm.

int compressionAlgorithmToCfitsio(ImageCompressionOptions::CompressionAlgorithm algorithm)

Convert ImageCompressionOptions::CompressionAlgorithm to cfitsio.

ImageScalingOptions::ScalingAlgorithm scalingAlgorithmFromString(std::string const &name)

Interpret scaling algorithm expressed in string.

std::string scalingAlgorithmToString(ImageScalingOptions::ScalingAlgorithm algorithm)

Provide string version of compression algorithm.

Variables

const int DEFAULT_HDU = INT_MIN

Specify that the default HDU should be read.

This special HDU number indicates that the first extension should be used if the primary HDU is empty (i.e., has NAXIS=0) and the Primary HDU is the current.

class Fits

#include <fits.h>

A simple struct that combines the two arguments that must be passed to most cfitsio routines and contains thin and/or templated wrappers around common cfitsio routines.

This is NOT intended to be an object-oriented C++ wrapper around cfitsio; it’s simply a thin layer that saves a lot of repetition, const/reinterpret casts, and replaces void pointer args and type codes with templates and overloads.

Like a cfitsio pointer, a Fits object always considers one HDU the “active” one, and most operations will be applied to that HDU.

All member functions are non-const because they may modify the ‘status’ data member.

Note

All functions that take a row or column number below are 0-indexed; the internal cfitsio calls are all 1-indexed.

class HduMoveGuard

#include <fits.h>

RAII scoped guard for moving the HDU in a Fits object.

This class attempts to ensure that the HDU state of a Fits object is restored when the guard class goes out of scope, even in the presence of exceptions. (In practice, resetting the HDU can only fail if the Fits object has become sufficiently corrupted that it’s no longer usable at all).

class HeaderIterationFunctor

#include <fits.h>

Base class for polymorphic functors used to iterator over FITS key headers.

Subclass this, and then pass an instance to Fits::forEachKey to iterate over all the keys in a header.

struct ImageCompressionOptions

#include <fitsCompression.h>

Options for tile compression of image pixels

Tile compression is a feature provided by cfitsio, where contiguous parts of the image (“tiles”, e.g., rows, multiple rows, blocks or the entire image) are compressed separately. The aim of this struct is to hold the parameters used to configure the compression.

Floating-point images can be losslessly compressed (quantizeLevel=0.0) using (only) the GZIP or GZIP_SHUFFLE compression algorithms, but the compression factor so achieved is modest (e.g., ~ 10% compression). Better compression factors can be achieved if floating-point images are first quantised into integer images. This can be done by cfitsio (through the quantizeLevel parameter) or through use of the ImageScalingOptions.

The Compression is specified by:

• the compression algorithm

• the tile size

• the quantization level (for quantization applied by cfitsio; for floating-point images)

Due to bugs, cfitsio may require setting the quantizeLevel to a value other than zero when compressing integer data, but in this case it should have no effect.

struct ImageScale

#include <fitsCompression.h>

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.

class ImageScalingOptions

#include <fitsCompression.h>

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.

struct ImageWriteOptions

#include <fits.h>

Options for writing an image to FITS

An image being written to FITS may be scaled (quantised) and/or compressed. This struct is a container for options controlling each of those separately.

class MemFileManager

#include <fits.h>

Lifetime-management for memory that goes into FITS memory files.

namespace detail

Functions

template<typename T>
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

Return

A new PixelArray.

Parameters

• [in] bitpix: Bits per pixel (0,8,16,32,64,-32,-64) for output.

• [in] array: Array with pixel values to convert.

template<typename T>
struct Bitpix

#include <fitsCompression.h>

FITS BITPIX header value by C++ type.

template<typename T>
class PixelArray : public lsst::afw::fits::detail::PixelArrayBase

#include <fitsCompression.h>

Typed array of pixel values.

class PixelArrayBase

#include <fitsCompression.h>

Abstract base class for an array of pixel values

For writing pixels out with the C-based cfitsio API, it’s helpful to have a type-agnostic holder of the pixel values (because although we can template on the array type, the output type can be configured at run-time, which means we can’t use ndarray::Array as the carrier). This is essentially a C++-ish void* array.

Subclassed by lsst::afw::fits::detail::PixelArray< T >

namespace formatters

Functions

bool extractOptionalFlag(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties, std::string const &name)

Returns true if and only if properties is non-null and contains a unique property with the given name that has type bool and a value of true.

std::string const getItemName(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

Extracts and returns the string-valued "itemName" property from the given data property object.

Exceptions

• lsst::pex::exceptions::InvalidParameterError: If the given pointer is null, or the PropertySet pointed to does not contain a unique property named "itemName".

int extractSliceId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int64_t extractFpaExposureId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int64_t extractCcdExposureId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int64_t extractAmpExposureId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int extractVisitId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int extractCcdId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int extractAmpId(std::shared_ptr<lsst::daf::base::PropertySet const> const &properties)

int countFitsHeaderCards(lsst::daf::base::PropertySet const &prop)

ndarray::Array<std::uint8_t, 1, 1> stringToBytes(std::string const &str)

Encode a std::string as a vector of uint8

std::string bytesToString(ndarray::Array<std::uint8_t const, 1, 1> const &bytes)

Decode a std::string from a vector of uint8 returned by stringToBytes

namespace geom

Typedefs

using TransformPoint2ToPoint2 = Transform<Point2Endpoint, Point2Endpoint>

using TransformPoint2ToGeneric = Transform<Point2Endpoint, GenericEndpoint>

using TransformPoint2ToSpherePoint = Transform<Point2Endpoint, SpherePointEndpoint>

Functions

std::ostream &operator<<(std::ostream &os, GenericEndpoint const &endpoint)

Print “GenericEndpoint(_n_)” to the ostream where _n_ is the number of axes, e.g. “GenericAxes(4)”.

std::ostream &operator<<(std::ostream &os, Point2Endpoint const &endpoint)

Print “Point2Endpoint()” to the ostream.

std::ostream &operator<<(std::ostream &os, SpherePointEndpoint const &endpoint)

Print “SpherePointEndpoint()” to the ostream.

Eigen::Matrix2d makeCdMatrix(lsst::geom::Angle const &scale, lsst::geom::Angle const &orientation = 0 * lsst::geom::degrees, bool flipX = false)

Make a WCS CD matrix

Return

the CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]

Parameters

• [in] scale: Pixel scale as an angle on sky/pixels

• [in] orientation: Position angle of pixel +Y, measured from N through E. At 0 degrees, +Y is along N and +X is along W/E if flipX false/true At 90 degrees, +Y is along E and +X is along N/S if flipX false/true

• [in] flipX: Flip x axis? See orientation for details.

std::shared_ptr<SkyWcs> makeFlippedWcs(SkyWcs const &wcs, bool flipLR, bool flipTB, lsst::geom::Point2D const &center)

Return a copy of a FITS-WCS with pixel positions flipped around a specified center

Parameters

• [in] wcs: The initial WCS

• [in] flipLR: Flip pixel positions left/right about center

• [in] flipTB: Flip pixel positions top/bottom about center

• [in] center: Center pixel position of flip

std::shared_ptr<SkyWcs> makeModifiedWcs(TransformPoint2ToPoint2 const &pixelTransform, SkyWcs const &wcs, bool modifyActualPixels)

Create a new SkyWcs whose pixels are transformed by pixelTransform, as described below.

If modifyActualPixels is true and the cameraGeom::ACTUAL_PIXELS frame exists then pixelTransform is inserted just after the cameraGeom::ACTUAL_PIXELS frame:

newActualPixelsToPixels = pixelTransform -> oldActualPixelsToPixels

This is appropriate for shifting a WCS, e.g. when writing FITS metadata for a subimage.

If modifyActualPixels is false or the cameraGeom::ACTUAL_PIXELS frame does not exist then pixelTransform is inserted just after the cameraGeom::PIXELS frame:

newPixelsToIwc = pixelTransform -> oldPixelsToIwc

This is appropriate for inserting a model for optical distortion.

Other than the change described above, the new SkyWcs will be just like the old one.

Return

the new WCS

Parameters

• [in] pixelTransform: Transform to insert

• [in] wcs: Input WCS

• [in] modifyActualPixels: Location at which to insert the transform; if true and the cameraGeom::ACTUAL_PIXELS frame is present then insert just after the cameraGeom::ACTUAL_PIXELS frame, else insert just after the cameraGeom::PIXELS frame.

std::shared_ptr<SkyWcs> makeSkyWcs(daf::base::PropertySet &metadata, bool strip = false)

Construct a SkyWcs from FITS keywords

This function is preferred over calling the SkyWcs metadata constructor directly because it allows us to change SkyWcs to an abstract base class in the future, without affecting code that constructs a WCS from FITS metadata.

Parameters

• [in] metadata: FITS header metadata

• [in] strip: If true: strip items from metadata used to create the WCS, such as RADESYS, EQUINOX, CTYPE12, CRPIX12, CRVAL12, etc. Always keep keywords that might be wanted for other purpposes, including NAXIS12 and date-related keywords such as “DATE-OBS” and “TIMESYS” (but not “EQUINOX”).

Exceptions

• lsst::pex::exceptions::TypeError: if the metadata does not describe a celestial WCS.

std::shared_ptr<SkyWcs> makeSkyWcs(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, std::string const &projection = "TAN")

Construct a simple FITS SkyWcs with no distortion

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the parent image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]. May be computed by calling makeCdMatrix.

• [in] projection: The name of the FITS WCS projection, e.g. “TAN” or “STG”

std::shared_ptr<SkyWcs> makeSkyWcs(TransformPoint2ToPoint2 const &pixelsToFieldAngle, lsst::geom::Angle const &orientation, bool flipX, lsst::geom::SpherePoint const &boresight, std::string const &projection = "TAN")

Construct a FITS SkyWcs from camera geometry

Return

a SkyWcs whose sky origin is the boresight and pixel origin is focal plane (0, 0).

Note

Unlike makeCdMatrix, orientation is with respect to the focal plane axes, not the CCD axes. This is because field angle is defined with respect to focal plane axes.

Parameters

• [in] pixelsToFieldAngle: Transformation from pixels to field angle (in radians).

• [in] orientation: Position angle of focal plane +Y, measured from N through E at crval. At 0 degrees, +Y is along N and +X is along W/E if flipX false/true. At 90 degrees, +Y is along E and +X is along N/S if flipX false/true.

• [in] flipX: Flip x axis? See orientation for details.

• [in] boresight: ICRS sky position at the boresight (field angle (0, 0)).

• [in] projection: The name of the FITS WCS projection, e.g. “TAN” or “STG”.

std::shared_ptr<SkyWcs> makeTanSipWcs(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, Eigen::MatrixXd const &sipA, Eigen::MatrixXd const &sipB)

Construct a TAN-SIP SkyWcs with forward SIP distortion terms and an iterative inverse.

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the parent image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]. May be computed by calling makeCdMatrix.

• [in] sipA: Forward distortion matrix for axis 1

• [in] sipB: Forward distortion matrix for axis 2

std::shared_ptr<SkyWcs> makeTanSipWcs(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, Eigen::MatrixXd const &sipA, Eigen::MatrixXd const &sipB, Eigen::MatrixXd const &sipAp, Eigen::MatrixXd const &sipBp)

Construct a TAN WCS with forward and inverse SIP distortion terms.

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the parent image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]. May be computed by calling makeCdMatrix.

• [in] sipA: Forward distortion matrix for axis 1

• [in] sipB: Forward distortion matrix for axis 2

• [in] sipAp: Reverse distortion matrix for axis 1

• [in] sipBp: Reverse distortion matrix for axis 2

std::shared_ptr<TransformPoint2ToPoint2> makeWcsPairTransform(SkyWcs const &src, SkyWcs const &dst)

A Transform obtained by putting two SkyWcs objects “back to back”.

Provides basic exception safety.

Return

a Transform whose forward transformation converts from src pixels to dst pixels, and whose inverse transformation converts in the opposite direction.

Parameters

• src: the WCS for the source pixels

• dst: the WCS for the destination pixels

std::shared_ptr<TransformPoint2ToSpherePoint> getIntermediateWorldCoordsToSky(SkyWcs const &wcs, bool simplify = true)

Return a transform from intermediate world coordinates to sky

std::shared_ptr<TransformPoint2ToPoint2> getPixelToIntermediateWorldCoords(SkyWcs const &wcs, bool simplify = true)

Return a transform from pixel coordinates to intermediate world coordinates

The pixel frame is is the base frame: cameraGeom::ACTUAL_PIXELS, if present, else cameraGeom::PIXELS.

std::ostream &operator<<(std::ostream &os, SkyWcs const &wcs)

Print a SkyWcs to an ostream (delegates to SkyWcs.toString()).

template<class FromEndpoint, class ToEndpoint>
std::ostream &operator<<(std::ostream &os, Transform<FromEndpoint, ToEndpoint> const &transform)

Print a Transform to an ostream

The format is “Transform<_fromEndpoint_, _toEndpoint_>” where fromEndpoint and toEndpoint are the appropriate endpoint printed to the ostream; for example “Transform<GenericEndpoint(4), Point2Endpoint()>”

lsst::geom::AffineTransform linearizeTransform(TransformPoint2ToPoint2 const &original, lsst::geom::Point2D const &inPoint)

Approximate a Transform by its local linearization.

Return

an lsst::geom::AffineTransform whose value and Jacobian at inPoint match those of original. It may be invertible; in general, linearizations are invertible if the Jacobian at inPoint is invertible.

Template Parameters

• FromEndpointToEndpoint: The endpoints of the transform.

Parameters

• original: the Transform to linearize

• inPoint: the point at which a linear approximation is desired

Exceptions

• pex::exceptions::InvalidParameterError: Thrown if original does not have a well-defined value and Jacobian at inPoint Not exception safe.

std::shared_ptr<TransformPoint2ToPoint2> makeTransform(lsst::geom::AffineTransform const &affine)

Wrap an lsst::geom::AffineTransform as a Transform.

Provides basic exception safety.

Return

a Transform that that maps any lsst::geom::Point2D x to affine(x). It shall be invertible iff affine is invertible.

Parameters

• affine: The lsst::geom::AffineTransform to wrap.

std::shared_ptr<TransformPoint2ToPoint2> makeRadialTransform(std::vector<double> const &coeffs)

A purely radial polynomial distortion.

The Transform transforms an input \(x\) to

\[ \frac{x}{r} \sum_{i=1}^{N} \mathrm{coeffs[i]} \ r^i \]

where \(r\) is the magnitude of \(x\).

Return

the radial distortion represented by coeffs. The Transform shall have an inverse, which may be approximate.

Parameters

• coeffs: radial polynomial coefficients. May be an empty vector to represent the identity transformation; otherwise must have size > 1, coeffs[0] = 0, and coeffs[1] 0.

Exceptions

• pex::exceptions::InvalidParameterError: Thrown if coeffs does not have the required format. Provides basic exception safety.

std::shared_ptr<TransformPoint2ToPoint2> makeRadialTransform(std::vector<double> const &forwardCoeffs, std::vector<double> const &inverseCoeffs)

A purely radial polynomial distortion.

Similar to makeRadialTransform(std::vector<double> const &), but allows the user to provide an inverse.

Return

the radial distortion represented by coeffs. The Transform shall have an inverse, whose accuracy is determined by the relationship between forwardCoeffs and inverseCoeffs.

Parameters

• forwardCoeffs: radial polynomial coefficients. May be an empty vector to represent the identity transformation; otherwise must have size > 1, coeffs[0] = 0, and coeffs[1] 0.

• inverseCoeffs: coefficients for the inverse transform, as above. Does not need to have the same degree as forwardCoeffs, but either both must be empty or neither must be empty.

Exceptions

• pex::exceptions::InvalidParameterError: Thrown if forwardCoeffs or inverseCoeffs does not have the required format. Provides basic exception safety.

std::shared_ptr<TransformPoint2ToPoint2> makeIdentityTransform()

Trivial Transform x x.

Provides basic exception safety.

Return

a Transform mapping any lsst::geom::Point2D to itself. The Transform’s inverse shall be itself.

std::shared_ptr<daf::base::PropertyList> createTrivialWcsMetadata(std::string const &wcsName, lsst::geom::Point2I const &xy0)

void deleteBasicWcsMetadata(daf::base::PropertySet &metadata, std::string const &wcsName)

Eigen::Matrix2d getCdMatrixFromMetadata(daf::base::PropertySet &metadata)

Read a CD matrix from FITS WCS metadata

The elements of the returned matrix are in degrees

Exceptions

• pex::exceptions::TypeError: if no CD matrix coefficients found (missing coefficients are set to 0, as usual, but they cannot all be missing).

lsst::geom::Point2I getImageXY0FromMetadata(daf::base::PropertySet &metadata, std::string const &wcsName, bool strip = false)

Eigen::MatrixXd getSipMatrixFromMetadata(daf::base::PropertySet const &metadata, std::string const &name)

bool hasSipMatrix(daf::base::PropertySet const &metadata, std::string const &name)

std::shared_ptr<daf::base::PropertyList> makeSipMatrixMetadata(Eigen::MatrixXd const &matrix, std::string const &name)

std::shared_ptr<daf::base::PropertyList> makeSimpleWcsMetadata(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, std::string const &projection = "TAN")

Make FITS metadata for a simple FITS WCS (one with no distortion).

This can also be used as a starting point for creating metadata for more sophisticated FITS WCS.

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]

• [in] projection: The name of the FITS WCS projection, e.g. “TAN” or “STG”

std::shared_ptr<daf::base::PropertyList> makeTanSipMetadata(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, Eigen::MatrixXd const &sipA, Eigen::MatrixXd const &sipB)

Make metadata for a TAN-SIP WCS without inverse matrices

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the parent image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]. May be computed by calling makeCdMatrix.

• [in] sipA: Forward distortion matrix for axis 1

• [in] sipB: Forward distortion matrix for axis 2

std::shared_ptr<daf::base::PropertyList> makeTanSipMetadata(lsst::geom::Point2D const &crpix, lsst::geom::SpherePoint const &crval, Eigen::Matrix2d const &cdMatrix, Eigen::MatrixXd const &sipA, Eigen::MatrixXd const &sipB, Eigen::MatrixXd const &sipAp, Eigen::MatrixXd const &sipBp)

Make metadata for a TAN-SIP WCS

Parameters

• [in] crpix: Center of projection on the CCD using the LSST convention: 0, 0 is the lower left pixel of the parent image

• [in] crval: Center of projection on the sky

• [in] cdMatrix: CD matrix, where element (i-1, j-1) corresponds to FITS keyword CDi_j and i, j have range [1, 2]. May be computed by calling makeCdMatrix.

• [in] sipA: Forward distortion matrix for axis 1

• [in] sipB: Forward distortion matrix for axis 2

• [in] sipAp: Reverse distortion matrix for axis 1

• [in] sipBp: Reverse distortion matrix for axis 2

template<typename PointT, typename ArrayT>
class BaseEndpoint

#include <Endpoint.h>

Virtual base class for endpoints, which are helper classes for Transform

Endpoints transform points and lists of points from LSST-specific data types, such as lsst::geom::Point2D and lsst::geom::SpherePoint, to a form accepted by ast::Mapping.tran. Each type of endpoint is used for a particular LSST data type, for example:

• Point2Endpoint is used for lsst::geom::Point2D data

• SpherePointEndpoint for lsst::geom::SpherePoint data

• GenericEndpoint is used when no other form will do; its LSST data type is identical to the type used for ast::Mapping.applyForward.

Endpoints use the following forms of data for raw data:

• std::vector<double> for a single point

• ndarray<double, 2, 2> with dimensions number of axes x number of points for an array of points

Endpoints are designed as helper classes for Transform. Each transform has a two endpoints: one for input data and one for output data.

Endpoint also provides two methods to work with ast::Frames:

• normalizeFrame verifies that a frame is the correct type, and adjusts its settings if necessary

• makeFrame creates a new frame with the correct type and settings

Template Parameters

• PointT: LSST data type for one point

• ArrayT: LSST data type for an array of points

template<typename PointT>
class BaseVectorEndpoint : public lsst::afw::geom::BaseEndpoint<PointT, std::vector<PointT>>

#include <Endpoint.h>

Base class for endpoints with Array = std::vector<Point> where Point has 2 dimensions

Note

Subclasses must provide dataFromPoint, dataFromArray, pointFromData and arrayFromData

class GenericEndpoint : public lsst::afw::geom::BaseEndpoint<std::vector<double>, ndarray::Array<double, 2, 2>>

#include <Endpoint.h>

A generic endpoint for data in the format used by ast::Mapping

Thus supports all ast frame classes and any number of axes, and thus can be used as an endpoint for any ast::Mapping.

class Point2Endpoint : public lsst::afw::geom::BaseVectorEndpoint<lsst::geom::Point2D>

#include <Endpoint.h>

An endpoint for lsst::geom::Point2D

class SipApproximation

#include <SipApproximation.h>

A fitter and results class for approximating a general Transform in a form compatible with FITS WCS persistence.

The Simple Imaging Polynomial (SIP) convention (Shupe et al 2005) adds forward and reverse polynomial mappings to a standard projection FITS WCS projection (e.g. “TAN” for gnomonic) that relate Intermediate World Coordinates (see Calabretta & Greisen 2002) to image pixel coordinates. The SIP “forward” transform is defined by polynomial coeffients \(A\) and \(B\) that map pixel coordinates \((u, v)\) to Intermediate World Coordinates \((x, y)\) via

\[\begin{split} \boldsymbol{S}\left[\begin{array}{c} x \\ y \end{array}\right] \equiv \left[\begin{array}{c} x_s \\ y_s \end{array}\right] = \left[\begin{array}{c} (u - u_0) + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{A}_{p,q} (u - u_0)^p (v - v_0)^q \\ (v - v_0) + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{B}_{p,q} (u - u_0)^p (v - v_0)^q \end{array}\right] \end{split}\]

The reverse transform has essentially the same form:

\[\begin{split} \left[\begin{array}{c} u - u_0 \\ v - v_0 \end{array}\right] = \left[\begin{array}{c} x_s + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{AP}_{p,q} x_s^p y_s^q \\ y_s + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{BP}_{p,q} x_s^p y_s^q \end{array}\right] \end{split}\]

In both cases, \((u_0, v_0)\) is the pixel origin (CRPIX in FITS WCS) and \(\boldsymbol{S}\) is the inverse of the Jacobian “CD” matrix. Both CRPIX and CD are considered fixed inputs, and we do not attempt to null the zeroth- and first-order terms of \(A\) and \(B\) (as some SIP fitters do); together, these conventions make solving for the coefficients a much simpler linear problem.

While LSST WCSs are in general too complex to be described exactly in FITS WCS, they can generally be closely approximated by standard FITS WCS projection with additional SIP distortions. This class fits such an approximation, given a TransformPoint2ToPoint2 object that represents the exact mapping from pixels to Intermediate World Coordinates with a SIP distortion.

Note

In the implementation, we typically refer to \((u-u_0, v-v_0)\) as dpix (for “pixel delta”), and \((x_s, y_s)\) as siwc

(for “scaled

intermediate world coordinates”).

class SkyWcs : public lsst::afw::table::io::PersistableFacade<SkyWcs>, public Storable

#include <SkyWcs.h>

A 2-dimensional celestial WCS that transform pixels to ICRS RA/Dec, using the LSST standard for pixels.

SkyWcs is an immutable object that can not only represent any standard FITS WCS, but can also contain arbitrary Transforms, e.g. to model optical distortion or pixel imperfections.

In order to make a SkyWcs that models optical distortion, say, it is usually simplest to start with a standard FITS WCS (such as a TAN WCS) as an approximation, then insert a transform that models optical distortion by calling makeModifiedWcs. However, it is also possible to build a SkyWcs entirely from transforms, if you prefer, by building an ast::FrameDict and constructing the SkyWcs from that.

Frames of reference

SkyWcs internally keeps track of the following frames of reference:

• cameraGeom::ACTUAL_PIXELS (optional): “actual” pixel position using the LSST standard. This has the same meaning as the cameraGeom::ACTUAL_PIXELS frame: actual pixels include effects such as “tree ring” distortions and electrical effects at the edge of CCDs. This frame should only be provided if there is a reasonable model for these imperfections.

• cameraGeom::PIXELS: nominal pixel position, using the LSST standard. This has the same meaning as the cameraGeom::PIXELS frame: nominal pixels may be rectangular, but are uniform in size and spacing.

• IWC: intermediate world coordinates (the FITS WCS concept).

• SKY: position on the sky as ICRS, with standard RA, Dec axis order.

Pixel position standards

The LSST standard for pixel position is: 0,0 is the center of the lower left image pixel. The FITS standard for pixel position is: 1,1 is the center of the lower left image pixel.

LSST and FITS also use a different origin for subimages:

• LSST pixel position is in the frame of reference of the parent image

• FITS pixel position is in the frame of reference of the subimage However, SkyWcs does not keep track of this difference. Code that persists and unpersists SkyWcs using FITS-WCS header cards must handle the offset, e.g. by calling copyAtShiftedPixelOrigin

Internal details: the contained ast::FrameDict

SkyWcs contains an ast::FrameDict which transforms from pixels to sky (in radians) in the forward direction.

This FrameDict contains the named frames described in frames of reference, e.g. “SKY”, “IWC”, cameraGeom::PIXELS and possibly cameraGeom::ACTUAL_PIXELS. “SKY” is the current frame. If cameraGeom::ACTUAL_PIXELS is present then it is the base frame, otherwise cameraGeom::PIXELS is the base frame.

The “SKY” frame is of type ast::SkyFrame and has the following attributes:

• SkyRef is set to the sky origin of the WCS (ICRS RA, Dec) in radians.

• SkyRefIs is set to “Ignored” so that SkyRef is not used in transformations.

The other frames are of type ast::Frame and have 2 axes.

class Span

#include <Span.h>

A range of pixels within one row of an Image

class SpanPixelIterator : public boost::iterator_facade<SpanPixelIterator, lsst::geom::Point2I const, boost::random_access_traversal_tag>

#include <SpanPixelIterator.h>

An iterator that yields lsst::geom::Point2I and increases in the x direction.

This is used to iterate over the pixels in a Span, and by extension to iterate over regions like boxes and ellipses.

class SpherePointEndpoint : public lsst::afw::geom::BaseVectorEndpoint<lsst::geom::SpherePoint>

#include <Endpoint.h>

An endpoint for lsst::geom::SpherePoint

A SpherePointEndpoint always has 2 axes: longitude, latitude

template<class FromEndpoint, class ToEndpoint>
class Transform : public lsst::afw::table::io::PersistableFacade<Transform<FromEndpoint, ToEndpoint>>, public lsst::afw::table::io::Persistable

#include <Transform.h>

Transform LSST spatial data, such as lsst::geom::Point2D and lsst::geom::SpherePoint, using an AST mapping.

This class contains two Endpoints, to specify the “from” and “to” LSST data type, and an ast::Mapping to specify the transformation.

Depending on the ast::FrameSet or ast::Mapping used to define it, a Transform may provide either a forward transform, an inverse transform, or both. In particular, the inverse of a forward-only transform is an inverse-only transform. The hasForward and hasInverse methods can be used to check which transforms are available.

Unless otherwise stated, all constructors and methods may throw std::runtime_error to indicate internal errors within AST.

Transforms are always immutable.

Note

You gain some safety by constructing a Transform from an ast::FrameSet, since the base and current frames in the FrameSet can be checked against by the appropriate endpoint.

Note

”In place” versions of applyForward and applyInverse are not available because data must be copied when converting from LSST data types to the type used by astshim, so it didn’t seem worth the bother.

namespace detail

Functions

std::shared_ptr<ast::FrameSet> readFitsWcs(daf::base::PropertySet &metadata, bool strip = true)

Read a FITS convention WCS FrameSet from FITS metadata

The resulting FrameSet may be any kind of WCS supported by FITS; if it is a celestial WCS then 1,1 will be the lower left corner of the image (the FITS convention, not the LSST convention).

This routine replaces RADECSYS with RADESYS if the former is present and the latter is not, since that is a common misspelling in FITS headers.

The returned FrameSet will have an IWC (intermediate world coordinate system) frame.

Parameters

• [inout] metadata: FITS header cards

• [in] strip: If true: strip items from metadata used to create the WCS, such as RADESYS, EQUINOX, CTYPE12, CRPIX12, CRVAL12, etc. Always keep keywords that might be wanted for other purpposes, including NAXIS12 and date-related keywords such as “DATE-OBS” and “TIMESYS” (but not “EQUINOX”).

Exceptions

• pex::exceptions::TypeError: if the metadata does not contain a FITS-WCS

std::shared_ptr<ast::FrameDict> readLsstSkyWcs(daf::base::PropertySet &metadata, bool strip = true)

Read an LSST celestial WCS FrameDict from a FITS header.

Calls getImageXY0FromMetadata to determine image XY0.

Saves CRVAL by setting the output SkyFrame’s SkyRef to CRVAL and SkyRefIs=”Ignore” (so SkyRef is not treated as an offset).

The frames of the returned WCS will be as follows:

• ”PIXELS” (base frame): pixel frame with 0,0 the lower left corner of the image (LSST convention)

• ”IWC”: FITS WCS intermediate world coordinate system

• ”SKY” (current frame): an ast::SkyFrame with domain “SKY”: ICRS RA, Dec

Warning

Does not compensate for the offset between a subimage and its parent image; callers must do that manually, e.g. by calling SkyWcs::copyAtShiftedPosition.

Warning

the general SkyWcs generated by LSST software cannot be exactly represented using standard WCS FITS cards, and so this function cannot read those. This function is intended for two purposes:

• Read the standard FITS WCS found in raw data and other images from non-LSST observatories and convert it to the LSST pixel convention.

• Read the approximate FITS WCS that LSST writes to FITS images (for use by non-LSST code).

All frames are instances of ast::Frame except the SKY frame. All have 2 axes.

Parameters

• [inout] metadata: FITS header cards

• [in] strip: If true: strip items from metadata used to create the WCS, such as RADESYS, EQUINOX, CTYPE12, CRPIX12, CRVAL12, etc. Always keep keywords that might be wanted for other purpposes, including NAXIS12 and date-related keywords such as “DATE-OBS” and “TIMESYS” (but not “EQUINOX”).

Exceptions

• lsst::pex::exceptions::TypeError: if the metadata does not describe a celestial WCS.

std::shared_ptr<daf::base::PropertyList> getPropertyListFromFitsChan(ast::FitsChan &fitsChan)

Copy values from an AST FitsChan into a PropertyList

Warning

COMMENT and HISTORY cards are treated as string values

Exceptions

• lsst::pex::exceptions::TypeError: if fitsChan contains cards whose type is not supported by PropertyList: complex numbers, or cards with no value

ast::FitsChan getFitsChanFromPropertyList(daf::base::PropertySet &metadata, std::set<std::string> const &excludeNames = {}, std::string options = "")

Construct AST FitsChan from PropertyList

Return

an ast::FitsChan representing this PropertyList

Parameters

• [in] metadata: Metadata to transfer; if this is a PropertyList then the order of items is preserved.

• [in] excludeNames: Names of entries to exclude from the returned header string.

• [in] options: Options string to pass to ast::FitsChan constructor.

template<class Transform>
std::shared_ptr<Transform> readStream(std::istream &is)

Deserialize a Transform from an input stream

Template Parameters

• Transform: the Transform class; can be Transform<FromEndpoint, ToEndpoint>, SkyWcs, or any other compatible class, i.e. it must support the following (see Transform.h for details):

  • a constructor that takes an ast::FrameSet

  • static method getShortClassName

  • method getMapping

Parameters

• [in] is: input stream from which to deserialize this Transform

template<class Transform>
void writeStream(Transform const &transform, std::ostream &os)

Serialize a Transform to an output stream

Version 1 format is as follows:

• The version number (an integer)

• A space

• The short class name, as obtained from getShortClassName

• A space

• The contained ast::FrameSet written using FrameSet.show(os, false)

Parameters

• [out] os: output stream to which to serialize this Transform

• [in] transform: Transform to serialize

Variables

constexpr int serializationVersion = 1

version of serialization used when writing (older versions may also be supported when reading)

namespace ellipses

Typedefs

typedef Separable<Distortion, DeterminantRadius> SeparableDistortionDeterminantRadius

typedef Separable<Distortion, TraceRadius> SeparableDistortionTraceRadius

typedef Separable<Distortion, LogDeterminantRadius> SeparableDistortionLogDeterminantRadius

typedef Separable<Distortion, LogTraceRadius> SeparableDistortionLogTraceRadius

typedef Separable<ConformalShear, DeterminantRadius> SeparableConformalShearDeterminantRadius

typedef Separable<ConformalShear, TraceRadius> SeparableConformalShearTraceRadius

typedef Separable<ConformalShear, LogDeterminantRadius> SeparableConformalShearLogDeterminantRadius

typedef Separable<ConformalShear, LogTraceRadius> SeparableConformalShearLogTraceRadius

typedef Separable<ReducedShear, DeterminantRadius> SeparableReducedShearDeterminantRadius

typedef Separable<ReducedShear, TraceRadius> SeparableReducedShearTraceRadius

typedef Separable<ReducedShear, LogDeterminantRadius> SeparableReducedShearLogDeterminantRadius

typedef Separable<ReducedShear, LogTraceRadius> SeparableReducedShearLogTraceRadius

class Axes : public lsst::afw::geom::ellipses::BaseCore

#include <Axes.h>

An ellipse core for the semimajor/semiminor axis and position angle parametrization (a,b,theta).

class BaseCore

#include <BaseCore.h>

A base class for parametrizations of the “core” of an ellipse - the ellipticity and size.

A subclass of BaseCore provides a particular interpretation of the three pointing point values that define an ellipse’s size and ellipticity (including position angle). All core subclasses are implicitly convertible and can be assigned to from any other core.

Subclassed by lsst::afw::geom::ellipses::Axes, lsst::afw::geom::ellipses::Quadrupole, lsst::afw::geom::ellipses::Separable< Ellipticity_, Radius_ >

Coordinate transforms

These member functions transform the ellipse by the given lsst::geom::LinearTransform. The transform can be done in-place by calling inPlace() on the returned expression object, or returned as a new shared_ptr by calling copy().

class ConformalShear : public lsst::afw::geom::ellipses::detail::EllipticityBase

#include <ConformalShear.h>

A logarithmic complex ellipticity with magnitude \(|e| = \ln (a/b) \).

For a more complete definition, see Bernstein and Jarvis (2002); this the same as their conformal shear \(\eta\) (eq. 2.3-2.6).

class DeterminantRadius

#include <radii.h>

The radius defined as the 4th root of the determinant of the quadrupole matrix.

The determinant radius is equal to the standard radius for a circle, and \(\pi R_{det}^2\) is the area of the ellipse.

class Distortion : public lsst::afw::geom::ellipses::detail::EllipticityBase

#include <Distortion.h>

A complex ellipticity with magnitude \(|e| = \frac{a^2 - b^2}{a^2 + b^2}\).

For a more complete definition, see Bernstein and Jarvis (2002); this the same as their distortion \(\delta\) (eq. 2.7).

class Ellipse

#include <Ellipse.h>

An ellipse defined by an arbitrary BaseCore and a center point.

An ellipse is composed of its center coordinate and its Core - a parametrization of the ellipticity and size of the ellipse. Setting the core of an ellipse never changes the type of the contained core, it merely sets the parameters of that core by converting the parameters.

Coordinate transforms

These member functions transform the ellipse by the given lsst::geom::AffineTransform. The transform can be done in-place by calling inPlace() on the returned expression object, or returned as a new shared_ptr by calling copy().

class LogDeterminantRadius

#include <radii.h>

The natural logarithm of the DeterminantRadius

class LogTraceRadius

#include <radii.h>

The natural logarithm of the TraceRadius

class Parametric

#include <Parametric.h>

A functor that returns points on the boundary of the ellipse as a function of a parameter that runs between 0 and 2 pi (but is not angle).

class PixelRegion

#include <PixelRegion.h>

A pixelized region containing all pixels whose centers are within an Ellipse.

The pixel region for an ellipse may be larger or smaller in area than the ellipse itself, depending on the details of where pixel centers land, and it may be empty even if the area of the ellipse is nonzero.

class Quadrupole : public lsst::afw::geom::ellipses::BaseCore

#include <Quadrupole.h>

An ellipse core with quadrupole moments as parameters.

class ReducedShear : public lsst::afw::geom::ellipses::detail::EllipticityBase

#include <ReducedShear.h>

A complex ellipticity with magnitude \(|e| = \frac{a-b}{a+b} \).

For a more complete definition, see Bernstein and Jarvis (2002); this the same as their reduced shear \(g\) (eq. 2.8).

template<typename Ellipticity_, typename Radius_>
class Separable : public lsst::afw::geom::ellipses::BaseCore

#include <Separable.h>

An ellipse core with a complex ellipticity and radius parameterization.

class TraceRadius

#include <radii.h>

The radius defined as \(\sqrt{0.5(I_{xx} + I_{yy})}\)

The trace radius is equal to the standard radius for a circle

namespace detail

class EllipticityBase

#include <EllipticityBase.h>

EllipticityBase is a base class for complex ellipticity types.

EllipticityBase does not have a virtual destructor, and only exists for code reuse purposes. The ellipticity classes are not polymorphic simply to keep them small.

Subclassed by lsst::afw::geom::ellipses::ConformalShear, lsst::afw::geom::ellipses::Distortion, lsst::afw::geom::ellipses::ReducedShear

namespace polygon

Functions

LSST_EXCEPTION_TYPE(SinglePolygonException, lsst::pex::exceptions::RuntimeError, lsst::afw::geom::polygon::SinglePolygonException)

An exception that indicates the single-polygon assumption has been violated

The single-polygon assumption is used in Polygon::intersectionSingle and Polygon::unionSingle.

std::ostream &operator<<(std::ostream &os, Polygon const &poly)

Stream polygon.

class Polygon : public lsst::afw::table::io::PersistableFacade<Polygon>, public Storable

#include <Polygon.h>

Cartesian polygons

Polygons are defined by a set of vertices

namespace image

Typedefs

typedef std::int32_t MaskPixel

default type for Masks and MaskedImage Masks

typedef float VariancePixel

default type for MaskedImage variance images

Enums

enum ImageOrigin

Values:

PARENT

LOCAL

enum xOrY

Values:

X

Y

enum RotType

Type of rotation.

Values:

UNKNOWN

Rotation angle is unknown. Note: if there is no instrument rotator then it is better to compute SKY or HORIZON and use that rotation type rather than specify UNKNOWN.

SKY

Position angle of focal plane +Y, measured from N through E. At 0 degrees, +Y is along N and +X is along E/W depending on handedness. At 90 degrees, +Y is along E and +X is along S/N depending on handedness.

HORIZON

Position angle of focal plane +Y, measured from +Alt through +Az. At 0 degrees, +Y is along +Alt and +X is along +/-Az, depending on handedness. At 90 degrees, +Y is along +Az and +X is along -/+Alt, depending on handedness.

MOUNT

The position sent to the instrument rotator; the details depend on the rotator.

Functions

double abMagFromFlux(double flux)

Compute AB magnitude from flux in Janskys.

double abMagErrFromFluxErr(double fluxErr, double flux)

Compute AB magnitude error from flux and flux error in Janskys.

double fluxFromABMag(double mag)

Compute flux in Janskys from AB magnitude.

double fluxErrFromABMagErr(double magErr, double mag)

Compute flux error in Janskys from AB magnitude error and AB magnitude.

template<typename T>
ndarray::Array<T, 1> abMagFromFlux(ndarray::Array<T const, 1> const &flux)

Compute AB magnitude from flux in Janskys.

template<typename T>
ndarray::Array<T, 1> abMagErrFromFluxErr(ndarray::Array<T const, 1> const &fluxErr, ndarray::Array<T const, 1> const &flux)

Compute AB magnitude error from flux and flux error in Janskys.

template<typename T>
ndarray::Array<T, 1> fluxFromABMag(ndarray::Array<T const, 1> const &mag)

Compute flux in Janskys from AB magnitude.

template<typename T>
ndarray::Array<T, 1> fluxErrFromABMagErr(ndarray::Array<T const, 1> const &magErr, ndarray::Array<T const, 1> const &mag)

Compute flux error in Janskys from AB magnitude error and AB magnitude.

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
std::shared_ptr<Exposure<ImagePixelT, MaskPixelT, VariancePixelT>> makeExposure(MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT> &mimage, std::shared_ptr<geom::SkyWcs const> wcs = std::shared_ptr<geom::SkyWcs const>())

Parameters

• mimage: the Exposure’s image

• wcs: the Exposure’s WCS

A function to return an Exposure of the correct type (cf. std::make_pair)

template<typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT> &operator+=(Image<LhsPixelT> &lhs, Image<RhsPixelT> const &rhs)

Add lhs to Image rhs (i.e. pixel-by-pixel addition) where types are different.

template<typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT> &operator-=(Image<LhsPixelT> &lhs, Image<RhsPixelT> const &rhs)

Subtract lhs from Image rhs (i.e. pixel-by-pixel subtraction) where types are different.

template<typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT> &operator*=(Image<LhsPixelT> &lhs, Image<RhsPixelT> const &rhs)

Multiply lhs by Image rhs (i.e. pixel-by-pixel multiplication) where types are different.

template<typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT> &operator/=(Image<LhsPixelT> &lhs, Image<RhsPixelT> const &rhs)

Divide lhs by Image rhs (i.e. pixel-by-pixel division) where types are different.

template<typename PixelT>
void swap(Image<PixelT> &a, Image<PixelT> &b)

template<typename PixelT>
void swap(DecoratedImage<PixelT> &a, DecoratedImage<PixelT> &b)

lsst::geom::Box2I bboxFromMetadata(daf::base::PropertySet &metadata)

Determine the image bounding box from its metadata (FITS header)

Note that this modifies the metadata, stripping the WCS headers that provide the xy0.

template<typename T1, typename T2>
bool imagesOverlap(ImageBase<T1> const &image1, ImageBase<T2> const &image2)

Return true if the pixels for two images or masks overlap in memory.

template<typename LhsT>
void for_each_pixel(Image<LhsT> &lhs, pixelOp0<LhsT> const &func)

Parameters

• lhs: Image to set

• func: functor to call

Set each pixel in an Image<LhsT> to func()

template<typename LhsT>
void for_each_pixel(Image<LhsT> &lhs, pixelOp1<LhsT> const &func)

Parameters

• lhs: Image to set

• func: functor to call

Set each pixel in an Image<LhsT> to func(lhs)

template<typename LhsT>
void for_each_pixel(Image<LhsT> &lhs, pixelOp1XY<LhsT> const &func)

Parameters

• lhs: Image to set

• func: functor to call

Set each pixel in an Image<LhsT> to func(x, y, lhs)

(x, y) allow for lhs.getXY0()

template<typename LhsT, typename RhsT>
void for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const &rhs, pixelOp1<RhsT> const &func)

Parameters

• lhs: Image to set

• rhs: other Image to pass to func

• func: functor to call

Set each pixel in an Image<LhsT> to func(rhs), getting the rhs from an Image<RhsT>

template<typename LhsT, typename RhsT>
void for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const &rhs, pixelOp2<LhsT, RhsT> const &func)

Parameters

• lhs: Image to set

• rhs: other Image to pass to func

• func: functor to call

Set each pixel in an Image<LhsT> to func(lhs, rhs), getting the rhs from an Image<RhsT>

template<typename LhsT, typename RhsT>
void for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const &rhs, pixelOp2XY<LhsT, RhsT> const &func)

Parameters

• lhs: Image to set

• rhs: other Image to pass to func

• func: functor to call

Set each pixel in an Image<LhsT> to func(x, y, lhs, rhs), getting the rhs from an Image<RhsT>

(x, y) allow for lhs.getXY0()

template<typename PixelT>
void swap(ImageBase<PixelT> &a, ImageBase<PixelT> &b)

template<typename Image1T, typename Image2T>
double innerProduct(Image1T const &lhs, Image2T const &rhs, int const border = 0)

Calculate the inner product of two images

Return

The inner product

Parameters

• lhs: first image

• rhs: Other image to dot with first

• border: number of pixels to ignore around the edge

Exceptions

• lsst::pex::exceptions::LengthError: if all the images aren’t the same size

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator+(Image<PixelT> const &img, ImageSlice<PixelT> const &slc)

Overload operator+()

We require two of these, one for image+slice (this one) and one for slice+image (next one down)

Parameters

• img: The Image

• slc: The ImageSlice

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator+(ImageSlice<PixelT> const &slc, Image<PixelT> const &img)

Overload operator+()

We require two of these, one for image+slice (previous one) and one for slice+image (this)

Parameters

• slc: The ImageSlice

• img: The Image

template<typename PixelT>
void operator+=(Image<PixelT> &img, ImageSlice<PixelT> const &slc)

Overload operator+=()

We’ll only allow ‘image += slice’. It doesn’t make sense to add an image to a slice.

Parameters

• [inout] img: The Image

• [in] slc: The ImageSlice

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator-(Image<PixelT> const &img, ImageSlice<PixelT> const &slc)

Overload operator-()

We’ll only allow ‘image - slice’, as ‘slice - image’ doesn’t make sense.

Parameters

• img: The Image

• slc: The ImageSlice

template<typename PixelT>
void operator-=(Image<PixelT> &img, ImageSlice<PixelT> const &slc)

Overload operator-=()

Only ‘image -= slice’ is defined. ‘slice -= image’ wouldn’t make sense.

Parameters

• [inout] img: The Image

• [in] slc: The ImageSlice

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator*(Image<PixelT> const &img, ImageSlice<PixelT> const &slc)

Overload operator*()

We’ll define both ‘image*slice’ (this one) and ‘slice*image’ (next one down).

Parameters

• img: The Image

• slc: The ImageSlice

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator*(ImageSlice<PixelT> const &slc, Image<PixelT> const &img)

Overload operator*()

We’ll define both ‘image*slice’ (this one) and ‘slice*image’ (next one down).

Parameters

• slc: The Image

• img: The ImageSlice

template<typename PixelT>
void operator*=(Image<PixelT> &img, ImageSlice<PixelT> const &slc)

Overload operator*=()

Only ‘image *= slice’ is defined, as ‘slice *= image’ doesn’t make sense.

Parameters

• [inout] img: The Image

• [in] slc: The ImageSlice

template<typename PixelT>
std::shared_ptr<Image<PixelT>> operator/(Image<PixelT> const &img, ImageSlice<PixelT> const &slc)

Overload operator/()

Only ‘image / slice’ is defined, as ‘slice / image’ doesn’t make sense.

Parameters

• img: The Image

• slc: The ImageSlice

template<typename PixelT>
void operator/=(Image<PixelT> &img, ImageSlice<PixelT> const &slc)

Overload operator/=()

Only ‘image /= slice’ is defined, as ‘slice /= image’ doesn’t make sense.

Parameters

• [inout] img: The Image

• [in] slc: The ImageSlice

double indexToPosition(double ind)

Parameters

• ind: image index

Convert image index to image position

The LSST indexing convention is:

• the index of the bottom left pixel is 0,0

• the position of the center of the bottom left pixel is PixelZeroPos, PixelZeroPos

Return

image position

int positionToIndex(double pos)

Parameters

• pos: image position

Convert image position to nearest integer index

The LSST indexing convention is:

• the index of the bottom left pixel is 0,0

• the position of the center of the bottom left pixel is PixelZeroPos, PixelZeroPos

Return

nearest integer index

int positionToIndex(double &residual, double pos)

Parameters

• residual: fractional part of index

• pos: image position

Convert image position to index (nearest integer and fractional parts)

The LSST indexing convention is:

• the index of the bottom left pixel is 0,0

• the position of the center of the bottom left pixel is PixelZeroPos, PixelZeroPos

Note: in python this is called positionToIndexAndResidual

Return

nearest integer index

std::pair<int, double> positionToIndex(double const pos, bool)

Parameters

• pos: image position

Convert image position to index (nearest integer and fractional parts)

Return

std::pair(nearest integer index, fractional part)

template<typename PixelT>
void swap(Mask<PixelT> &a, Mask<PixelT> &b)

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT> *makeMaskedImage(typename std::shared_ptr<Image<ImagePixelT>> image, typename std::shared_ptr<Mask<MaskPixelT>> mask = Mask<MaskPixelT>(), typename std::shared_ptr<Image<VariancePixelT>> variance = Image<VariancePixelT>())

Parameters

• image: image

• mask: mask

• variance: variance

A function to return a MaskedImage of the correct type (cf. std::make_pair)

template<typename ImagePixelT1, typename ImagePixelT2>
bool imagesOverlap(MaskedImage<ImagePixelT1, MaskPixel, VariancePixel> const &image1, MaskedImage<ImagePixelT2, MaskPixel, VariancePixel> const &image2)

Return true if the pixels for two masked images (image, variance or mask plane) overlap in memory.

std::ostream &operator<<(std::ostream &os, Measurement const &measurement)

void assertNonNegative(double value, std::string const &name)

Raise lsst::pex::exceptions::InvalidParameterError if value is not >=0.

Used for checking the calibration mean/error in the constructor.

Parameters

• value: Value that should be positive.

• name: Text to prepend to error message.

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if value < 0

std::shared_ptr<PhotoCalib> makePhotoCalibFromMetadata(daf::base::PropertySet &metadata, bool strip = false)

Construct a PhotoCalib from FITS FLUXMAG0/FLUXMAG0ERR keywords.

This provides backwards compatibility with the obsoleted Calib object that PhotoCalib replaced. It should not be used outside of reading old Exposures written before PhotoCalib existed.

Return

Pointer to the constructed PhotoCalib, or nullptr if FLUXMAG0 is not in the metadata.

Parameters

• metadata: FITS header metadata containing FLUXMAG0 and FLUXMAG0ERR keys.

• strip: Strip FLUXMAG0 and FLUXMAG0ERR from metadata?

std::shared_ptr<PhotoCalib> makePhotoCalibFromCalibZeroPoint(double instFluxMag0, double instFluxMag0Err)

Construct a PhotoCalib from the deprecated Calib-style instFluxMag0/instFluxMag0Err values.

This provides backwards compatibility with the obsoleted Calib object that PhotoCalib replaced. It should not be used outside of tests that compare with old persisted Calib objects.

Return

Pointer to the constructed PhotoCalib.

Parameters

• instFluxMag0: The instrumental flux at zero magnitude. If 0, the resulting PhotoCalib will have infinite calibrationMean and non-finite (inf or NaN) calibrationErr.

• instFluxMag0Err: The instrumental flux at zero magnitude error. If 0, the resulting PhotoCalib will have 0 calibrationErr.

std::shared_ptr<daf::base::PropertyList> readMetadata(std::string const &fileName, int hdu = fits::DEFAULT_HDU, bool strip = false)

Return the metadata (header entries) from a FITS file.

Parameters

• [in] fileName: File to read.

• [in] hdu: HDU to read, 0-indexed. The special value of afw::fits::DEFAULT_HDU will read the first non-empty HDU.

• [in] strip: If true, ignore special header keys usually managed by cfitsio (e.g. NAXIS).

template<typename ImageT>
ImageT::SinglePixel badPixel(typename ImageT::Pixel bad = 0)

Parameters

• bad: The bad value if NaN isn’t supported

Return a value indicating a bad pixel for the given Image type

A quiet NaN is returned for types that support it otherwise bad

std::ostream &operator<<(std::ostream &os, VisitInfo const &visitInfo)

Variables

double const JanskysPerABFlux = 3631.0

const double PixelZeroPos = 0.0

position of center of pixel 0

FITS uses 1.0, SDSS uses 0.5, LSST uses 0.0 (http://dev.lsstcorp.org/trac/wiki/BottomLeftPixelProposalII%3A)

class ApCorrMap : public lsst::afw::table::io::PersistableFacade<ApCorrMap>, public Storable

#include <ApCorrMap.h>

A thin wrapper around std::map to allow aperture corrections to be attached to Exposures.

ApCorrMap simply adds error handling accessors, persistence, and a bit of encapsulation to std::map (given the simplified interface, for instance, we could switch to unordered_map or some other underyling container in the future).

class CheckIndices

#include <ImageBase.h>

A class used to request that array accesses be checked.

class CoaddInputs : public lsst::afw::table::io::PersistableFacade<CoaddInputs>, public Storable

#include <CoaddInputs.h>

A simple Persistable struct containing ExposureCatalogs that record the inputs to a coadd.

The visits catalog corresponds to what task code refers to as coaddTempExps, while the ccds catalog corresponds to individual input CCD images (calexps), and has a “visitId” column that points back to the visits catalog.

The records in the visits catalog will all have the same Wcs as the coadd, as they represent images that have already been warped to the coadd frame. Regardless of whether or not the coadd is PSF-matched, the visit record Psf will generally be CoaddPsfs (albeit single-depth ones, so they simply pick out the single non-coadd-Psf that is valid for each point).

class Color

#include <Color.h>

Describe the colour of a source

We need a concept of colour more general than “g - r” in order to calculate e.g. atmospheric dispersion or a source’s PSF

Note

This is very much just a place holder until we work out what we need. A full SED may be required, in which case a constructor from an SED name might be appropriate, or a couple of colours, or …

template<typename PixelT>
struct ConstReference

#include <ImageBase.h>

metafunction to extract const reference type from PixelT

template<typename PixelT>
class DecoratedImage

#include <Image.h>

A container for an Image and its associated metadata

class DefectBase

#include <Defect.h>

Encapsulate information about a bad portion of a detector

Subclassed by lsst::meas::algorithms::Defect

template<typename ImageT, typename MaskT = lsst::afw::image::MaskPixel, typename VarianceT = lsst::afw::image::VariancePixel>
class Exposure

#include <Exposure.h>

A class to contain the data, WCS, and other information needed to describe an image of the sky. Exposure Class Implementation for LSST: a templated framework class for creating an Exposure from a MaskedImage and a Wcs.

An Exposure is required to take one afwImage::MaskedImage or a region (col, row) defining the size of a MaskedImage (this can be of size 0,0). An Exposure can (but is not required to) contain an afwImage::SkyWcs.

The template types should optimally be a float, double, unsigned int 16 bit, or unsigned int 32 bit for the image (pixel) type and an unsigned int 32 bit for the mask type. These types have been explicitly instantiated for the Exposure class. All MaskedImage and Wcs constructors are ‘const’ to allow for views and copying.

An Exposure can get and return its MaskedImage, SkyWcs, and a subExposure. The getSubExposure member takes a BBox region defining the subRegion of the original Exposure to be returned. The member retrieves the MaskedImage corresponding to the subRegion. The MaskedImage class throws an exception for any subRegion extending beyond the original MaskedImage bounding box. This member is not yet fully implemented because it requires the SkyWcs class to return the SkyWcs metadata to the member so the CRPIX values of the SkyWcs can be adjusted to reflect the new subMaskedImage origin. The getSubExposure member will eventually return a subExposure consisting of the subMAskedImage and the SkyWcs object with its corresponding adjusted metadata.

The hasWcs member is used to determine if the Exposure has a SkyWcs. It is not required to have one.

class ExposureFitsReader

#include <ExposureFitsReader.h>

A FITS reader class for Exposures and their components.

All ExposureFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; ExposureFitsReader guards against this by resetting those before any use of the Fits object.

class ExposureInfo

#include <ExposureInfo.h>

A collection of all the things that make an Exposure different from a MaskedImage

The constness semantics of the things held by ExposureInfo are admittedly a bit of a mess, but they’re that way to preserve backwards compatibility for now. Eventually I’d like to make a lot of these things immutable, but in the meantime, here’s the summary:

• Filter is held and returned by value.

• VisitInfo is immutable and is held by a const ptr and has a setter and getter.

• Metadata is held by non-const pointer, and you can get a non-const pointer via a const member function accessor (i.e. constness is not propagated).

• all other types are only accessible through non-const pointers

The setter for Wcs clones its input arguments (this is a departure from the previous behavior for Wcs but it’s safer w.r.t. aliasing and it matches the old (and current) behavior of the Exposure and ExposureInfo constructors, which clone their arguments. The setter for Psf and constructors do not clone the Psf, as Psfs are immutable and hence we don’t need to ensure strict ownership. The setter for Detector does not clone its input argument, because while it technically isn’t, we can safely consider a Detector to be immutable once it’s attached to an ExposureInfo.

class Filter : public Storable

#include <Filter.h>

Holds an integer identifier for an LSST filter.

class FilterProperty

#include <Filter.h>

Describe the properties of a Filter (e.g. effective wavelength)

template<typename PixelT>
class Image : public lsst::afw::image::ImageBase<PixelT>

#include <Image.h>

A class to represent a 2-dimensional array of pixels.

Subclassed by lsst::afw::image::ImageSlice< PixelT >

template<typename PixelT>
class ImageBase

#include <ImageBase.h>

The base class for all image classed (Image, Mask, MaskedImage, …)

Subclassed by lsst::afw::image::Image< lsst::afw::math::Kernel::Pixel >, lsst::afw::image::Image< Pixel >, lsst::afw::image::Image< PixelT >

class ImageBaseFitsReader

#include <ImageBaseFitsReader.h>

Base class for image FITS readers.

This class should be considered an implementation detail of ImageFitsReader and MaskFitsReader that provides their common methods, not the definition of an interface.

All ImageBaseFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; ImageBaseFitsReader guards against this by resetting those before any use of the Fits object.

Subclassed by lsst::afw::image::ImageFitsReader, lsst::afw::image::MaskFitsReader

class ImageFitsReader : public lsst::afw::image::ImageBaseFitsReader

#include <ImageFitsReader.h>

A FITS reader class for regular Images.

All ImageFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; ImageFitsReader guards against this by resetting those before any use of the Fits object.

template<typename ImageT>
class ImagePca

Subclassed by lsst::ip::diffim::detail::KernelPca< ImageT >, lsst::meas::algorithms::PsfImagePca< ImageT >

template<typename PixelT>
class ImageSlice : public lsst::afw::image::Image<PixelT>

#include <ImageSlice.h>

A class to specify a slice of an image

template<typename MaskPixelT = lsst::afw::image::MaskPixel>
class Mask : public lsst::afw::image::ImageBase<MaskPixelT>

#include <Mask.h>

Represent a 2-dimensional array of bitmask pixels

Some mask planes are always defined (although you can add more with Mask::addMaskPlane):

• BAD This pixel is known to be bad (e.g. the amplifier is not working)

• CR This pixel is contaminated by a cosmic ray

• DETECTED This pixel lies within an object’s Footprint

• DETECTED_NEGATIVE This pixel lies within an object’s Footprint, and the detection was looking for pixels below a specified level

• EDGE This pixel is too close to the edge to be processed properly

• INTRP This pixel has been interpolated over

  Note

  should be called INTERPOLATED

• SAT This pixel is saturated and has bloomed

  Note

  should be called SATURATED

• SUSPECT This pixel is untrustworthy, and you may wish to discard any Source containing it

template<typename ImagePixelT, typename MaskPixelT = lsst::afw::image::MaskPixel, typename VariancePixelT = lsst::afw::image::VariancePixel>
class MaskedImage

#include <MaskedImage.h>

A class to manipulate images, masks, and variance as a single object.

class MaskedImageFitsReader

#include <MaskedImageFitsReader.h>

A FITS reader class for MaskedImages and their components.

All MaskedImageFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; MaskedImageFitsReader guards against this by resetting those before any use of the Fits object.

class MaskFitsReader : public lsst::afw::image::ImageBaseFitsReader

#include <MaskFitsReader.h>

A FITS reader class for Masks.

All MaskFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; MaskFitsReader guards against this by resetting those before any use of the Fits object.

struct Measurement

#include <PhotoCalib.h>

A value and its error.

class PhotoCalib : public lsst::afw::table::io::PersistableFacade<PhotoCalib>, public Storable

#include <PhotoCalib.h>

The photometric calibration of an exposure.

A PhotoCalib is a BoundedField (a function with a specified domain) that converts from post-ISR counts-on-chip (ADU) to flux and magnitude. It is defined such that a calibration of 1 means one count is equal to one nanojansky (nJy, 10^-35 W/m^2/Hz in SI units). The nJy was chosen because it represents a linear flux unit with values in a convenient range (e.g. LSST’s single image depth of 24.5 is 575 nJy). See more detailed discussion in: https://pstn-001.lsst.io/

PhotoCalib is immutable.

The spatially varying flux calibration has units of nJy/ADU, and is defined such that, at a position (x,y) in the domain of the boundedField calibration and for a given measured source instFlux:

\[ instFlux*calibration(x,y) = flux [nJy] \]

while the errors (constant on the domain) are defined as:

\[ sqrt((instFluxErr/instFlux)^2 + (calibrationErr/calibration)^2)*flux = fluxErr [nJy] \]

This implies that the conversions from instFlux and instFlux error to magnitude and magnitude error are as follows:

\[ -2.5*log_{10}(instFlux*calibration(x,y)*1e-9/referenceFlux) = magnitude \]

where referenceFlux is the AB Magnitude reference flux from Oke & Gunn 1983 (first equation),

\[ referenceFlux = 1e23 * 10^{(48.6/-2.5)} \]

and

\[ 2.5/log(10)*sqrt((instFluxErr/instFlux)^2 + (calibrationErr/calibration)^2) = magnitudeErr \]

Note that this is independent of referenceFlux.

template<typename ValT>
struct pixelOp0 : public std::function<ValT()>

#include <ImageAlgorithm.h>

A functor class equivalent to std::function<ValT ()>, but with a virtual operator()

template<typename ValT>
struct pixelOp1 : public std::function<ValT(ValT)>

#include <ImageAlgorithm.h>

A functor class equivalent to std::function<ValT (ValT)>, but with a virtual operator()

template<typename ValT>
struct pixelOp1XY : public std::function<ValT(int, int, ValT)>

#include <ImageAlgorithm.h>

A functor class equivalent to std::function<ValT (int, int, ValT)>, but with a virtual operator()

template<typename LhsT, typename RhsT>
struct pixelOp2 : public std::function<LhsT(LhsT, RhsT)>

#include <ImageAlgorithm.h>

A functor class equivalent to std::function<LhsT (LhsT, RhsT)>, but with a virtual operator()

template<typename LhsT, typename RhsT>
struct pixelOp2XY : public std::function<LhsT(int, int, LhsT, RhsT)>

#include <ImageAlgorithm.h>

A functor class equivalent to std::function<LhsT (int, int, LhsT, RhsT)>, but with a virtual operator()

template<typename PixelT>
struct Reference

#include <ImageBase.h>

metafunction to extract reference type from PixelT

class TransmissionCurve : public lsst::afw::table::io::PersistableFacade<TransmissionCurve>, public Storable, public std::enable_shared_from_this<TransmissionCurve>

#include <TransmissionCurve.h>

A spatially-varying transmission curve as a function of wavelength.

TransmissionCurve can only be evaluated at discrete (albeit arbitrary) user-provided positions; it does not provide an interface for computing average transmission over regions or computing spatially-varying scalars from integrals over the wavelength dimension.

TransmissionCurves are immutable and are expected to be passed and held by shared_ptr<TransmissionCurve const>. As such they are neither copyable nor movable (because there should be no need to copy or move).

All wavelength values should be in Angstroms.

The flux units and overall normalization of TransmissionCurves is unspecified by the class, but their normalization and units should always be consistent throughout the spatial area over which they are defined (an implementation should not e.g. re-normalize to unit bolometric flux at each position it is evaluated at). Other classes and functions using TransmissionCurves should of course document the flux units and/or normalization expected/provided.

class VisitInfo : public lsst::afw::table::io::PersistableFacade<VisitInfo>, public Storable

#include <VisitInfo.h>

Information about a single exposure of an imaging camera.

Includes exposure duration and date, and telescope pointing and orientation.

All information is for the middle of the exposure and at the boresight (center of the focal plane). Thus for a mosaic camera VisitInfo is the same for all detectors in the mosaic.

VisitInfo is immutable.

namespace detail

Typedefs

typedef std::map<std::string, int> MaskPlaneDict

Functions

int stripFilterKeywords(std::shared_ptr<lsst::daf::base::PropertySet> metadata)

Remove Filter-related keywords from the metadata

Return

Number of keywords stripped

Parameters

• [inout] metadata: Metadata to be stripped

void setVisitInfoMetadata(daf::base::PropertyList &metadata, VisitInfo const &visitInfo)

Set FITS metadata from a VisitInfo

Parameters

• [inout] metadata: FITS keyword metadata to set

• [in] visitInfo: instance of VisitInfo from which to set metadata

int stripVisitInfoKeywords(daf::base::PropertySet &metadata)

Remove VisitInfo-related keywords from the metadata

Return

Number of keywords stripped

Parameters

• [inout] metadata: FITS keyword metadata

Variables

std::string const wcsNameForXY0 = "A"

std::string const fitsFile_RE = "\.fits(\.[fg]z)?$"

regexp to identify when MaskedImages should be written as MEFs

std::string const compressedFileNoMEF_RE = "(\.gz)$"

regexp to identify compressed files that we can’t write MEFs to

struct basic_tag

#include <ImageBase.h>

Base image tag.

Subclassed by lsst::afw::image::detail::Image_tag, lsst::afw::image::detail::Mask_tag, lsst::afw::image::detail::MaskedImage_tag

struct Image_tag : public lsst::afw::image::detail::basic_tag

#include <ImageBase.h>

tag for an Image

template<typename ImageT>
struct image_traits

#include <ImageBase.h>

traits class for image categories

struct Mask_tag : public lsst::afw::image::detail::basic_tag

#include <Mask.h>

tag for a Mask

struct MaskedImage_tag : public lsst::afw::image::detail::basic_tag

#include <MaskedImage.h>

A traits class for MaskedImage.

struct MaskedImagePixel_tag

#include <MaskedImage.h>

A class used to identify classes that represent MaskedImage pixels.

Subclassed by lsst::afw::image::pixel::Pixel< _ImagePixelT, _MaskPixelT, _VariancePixelT >, lsst::afw::image::pixel::SinglePixel< _ImagePixelT, _MaskPixelT, _VariancePixelT >

class StorableMap

#include <StorableMap.h>

A map of Storable supporting strongly-typed access.

A Key for the map is parameterized by both the key type K and a corresponding value type V. The map is indexed uniquely by a value of type K; no two entries in the map may have identical values of Key::getId().

All operations are sensitive to the value type of the key: a contains call requesting a SkyWcs labeled “value”, for example, will report no such object if instead there is a Psf labeled “value”. At present, a StorableMap does not store type information internally, instead relying on RTTI for type checking.

namespace details

Functions

template<typename OperatorT, typename PixelT>
void operate(Image<PixelT> &img, ImageSlice<PixelT> const &slc, typename ImageSlice<PixelT>::ImageSliceType sliceType)

A function to loop over pixels and perform the requested operation

namespace pixel

Functions

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
SinglePixel<ImagePixelT, MaskPixelT, VariancePixelT> makeSinglePixel(ImagePixelT x, MaskPixelT m, VariancePixelT v)

Return a SinglePixel

This function is useful as function overloading will choose the correct return type (cf. std::make_pair()

template<typename ExprT1>
UnaryExpr<ExprT1, std::negate<typename exprTraits<ExprT1>::ImagePixelT>, noop<typename exprTraits<ExprT1>::MaskPixelT>, noop<typename exprTraits<ExprT1>::VariancePixelT>> operator-(ExprT1 e1)

Template for -e1.

template<typename ExprT1, typename ExprT2>
BinaryExpr<ExprT1, ExprT2, std::plus<typename exprTraits<ExprT1>::ImagePixelT>, bitwise_or<typename exprTraits<ExprT1>::MaskPixelT>, variance_plus<typename exprTraits<ExprT1>::VariancePixelT>> operator+(ExprT1 e1, ExprT2 e2)

Template for (e1 + e2)

template<typename ExprT1, typename ExprT2>
ExprT1 operator+=(ExprT1 &e1, ExprT2 e2)

template for e1 += e2

template<typename ExprT1, typename ExprT2>
ExprT1 plus(ExprT1 &lhs, ExprT2 const &rhs, float covariance)

Like operator+(), but assume that covariance’s 2*alpha*sqrt(vx*vy)

Parameters

• lhs: Left hand value

• rhs: Right hand value

• covariance: Assume that covariance is 2*alpha*sqrt(vx*vy) (if variances are known)

template<typename ExprT1, typename ExprT2>
BinaryExpr<ExprT1, ExprT2, std::minus<typename exprTraits<ExprT1>::ImagePixelT>, bitwise_or<typename exprTraits<ExprT1>::MaskPixelT>, variance_plus<typename exprTraits<ExprT1>::VariancePixelT>> operator-(ExprT1 e1, ExprT2 e2)

Template to evaluate (e1 - e2)

template<typename ExprT1, typename ExprT2>
ExprT1 operator-=(ExprT1 &e1, ExprT2 e2)

Template to evaluate e1 -= e2.

template<typename ExprT1, typename ExprT2>
BinaryExpr<ExprT1, ExprT2, std::multiplies<typename exprTraits<ExprT1>::ImagePixelT>, bitwise_or<typename exprTraits<ExprT1>::MaskPixelT>, variance_multiplies<typename exprTraits<ExprT1>::VariancePixelT>> operator*(ExprT1 e1, ExprT2 e2)

Template to evaluate (e1 * e2)

template<typename ExprT1, typename ExprT2>
ExprT1 operator*=(ExprT1 &e1, ExprT2 e2)

Template to evaluate e1 *= e2.

template<typename ExprT1, typename ExprT2>
BinaryExpr<ExprT1, ExprT2, std::divides<typename exprTraits<ExprT1>::ImagePixelT>, bitwise_or<typename exprTraits<ExprT1>::MaskPixelT>, variance_divides<typename exprTraits<ExprT1>::VariancePixelT>> operator/(ExprT1 e1, ExprT2 e2)

Template to evaluate (e1 / e2)

template<typename ExprT1, typename ExprT2>
ExprT1 operator/=(ExprT1 &e1, ExprT2 e2)

Template to evaluate e1 /= e2.

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
std::ostream &operator<<(std::ostream &os, SinglePixel<ImagePixelT, MaskPixelT, VariancePixelT> const &v)

Print a SinglePixel.

template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
std::ostream &operator<<(std::ostream &os, Pixel<ImagePixelT, MaskPixelT, VariancePixelT> const &v)

Print a Pixel.

template<typename ExprT1, typename ExprT2, typename BinOp, typename MaskBinOp, typename VarBinOp>
std::ostream &operator<<(std::ostream &os, BinaryExpr<ExprT1, ExprT2, BinOp, MaskBinOp, VarBinOp> const &v)

Evaluate and print a BinaryExpr.

template<typename ExprT1, typename ExprT2, typename ImageBinOp, typename MaskBinOp, typename VarianceBinOp>
class BinaryExpr

#include <Pixel.h>

Class for representing binary operations.

template<typename ExprT1, typename ImageBinOp, typename MaskBinOp, typename VarianceBinOp>
class BinaryExpr<ExprT1, double, ImageBinOp, MaskBinOp, VarianceBinOp>

#include <Pixel.h>

Partial specialization of BinaryExpr when ExprT2 is a double (i.e no mask/variance part)

template<typename T1>
struct bitwise_or : public std::binary_function<T1, T1, T1>

#include <Pixel.h>

bitwise_or doesn’t seem to be in std::

Note

We provide a single-operand version for when the right-hand-side of an expression is a scalar, not a masked pixel,

template<typename ExprT>
struct exprTraits

#include <Pixel.h>

A traits class to return the types of the image/mask/variance.

template<>
struct exprTraits<double>

#include <Pixel.h>

A specialisation of exprTraits for double

template<>
struct exprTraits<float>

#include <Pixel.h>

A specialisation of exprTraits for float

template<>
struct exprTraits<int>

#include <Pixel.h>

A specialisation of exprTraits for int

template<>
struct exprTraits<unsigned short>

#include <Pixel.h>

A specialisation of exprTraits for unsigned short

template<typename T1>
struct noop : public std::unary_function<T1, T1>

#include <Pixel.h>

A noop functor (useful for e.g. masks and variances when changing the sign of the image)

template<typename _ImagePixelT, typename _MaskPixelT, typename _VariancePixelT = double>
class Pixel : public lsst::afw::image::detail::MaskedImagePixel_tag

#include <Pixel.h>

A pixel of a MaskedImage.

template<typename PixelT>
struct PixelTypeTraits

#include <Pixel.h>

Pixel type traits.

template<typename _ImagePixelT, typename _MaskPixelT, typename _VariancePixelT>
struct PixelTypeTraits<SinglePixel<_ImagePixelT, _MaskPixelT, _VariancePixelT>>

#include <Pixel.h>

Specialization for a pixel of a MaskedImage.

template<typename _ImagePixelT, typename _MaskPixelT, typename _VariancePixelT = double>
class SinglePixel : public lsst::afw::image::detail::MaskedImagePixel_tag

#include <Pixel.h>

A single pixel of the same type as a MaskedImage.

template<typename ExprT1, typename ImageBinOp, typename MaskBinOp, typename VarianceBinOp>
class UnaryExpr

#include <Pixel.h>

Class for representing Unary operations.

template<typename T1>
struct variance_divides

#include <Pixel.h>

Calculate the variance when we divide two Pixels

Note

We provide a single-operand version for when the right-hand-side of an expression is a scalar, not a masked pixel,

template<typename T1>
struct variance_multiplies

#include <Pixel.h>

Calculate the variance when we multiply two Pixels

Note

We provide a single-operand version for when the right-hand-side of an expression is a scalar, not a masked pixel,

template<typename T1>
struct variance_plus

#include <Pixel.h>

Calculate the variance when we add (or subtract) two Pixels

Note

We provide a single-operand version for when the right-hand-side of an expression is a scalar, not a masked pixel,

template<typename T1>
struct variance_plus_covar

#include <Pixel.h>

The variance of the sum of a pair of correlated pixels

The covariance is modelled as alpha*sqrt(var_x*var_y)

Note

We provide a single-operand version for when the right-hand-side of an expression is a scalar, not a masked pixel,

namespace python

Functions

void checkBounds(geom::Point2I const &index, geom::Box2I const &bbox)

namespace math

Typedefs

typedef std::vector<std::shared_ptr<Kernel>> KernelList

typedef lsst::afw::image::VariancePixel WeightPixel

Enums

enum UndersampleStyle

Values:

THROW_EXCEPTION

REDUCE_INTERP_ORDER

INCREASE_NXNYSAMPLE

enum Property

control what is calculated

Values:

NOTHING = 0x0

We don’t want anything.

ERRORS = 0x1

Include errors of requested quantities.

NPOINT = 0x2

number of sample points

MEAN = 0x4

estimate sample mean

STDEV = 0x8

estimate sample standard deviation

VARIANCE = 0x10

estimate sample variance

MEDIAN = 0x20

estimate sample median

IQRANGE = 0x40

estimate sample inter-quartile range

MEANCLIP = 0x80

estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)

STDEVCLIP = 0x100

estimate sample N-sigma clipped stdev (N set in StatisticsControl, default=3)

VARIANCECLIP = 0x200

estimate sample N-sigma clipped variance (N set in StatisticsControl, default=3)

MIN = 0x400

estimate sample minimum

MAX = 0x800

estimate sample maximum

SUM = 0x1000

find sum of pixels in the image

MEANSQUARE = 0x2000

find mean value of square of pixel values

ORMASK = 0x4000

get the or-mask of all pixels used.

NCLIPPED = 0x8000

number of clipped points

NMASKED = 0x10000

number of masked points

Functions

template<typename PixelT>
std::shared_ptr<Approximate<PixelT>> makeApproximate(std::vector<double> const &x, std::vector<double> const &y, image::MaskedImage<PixelT> const &im, lsst::geom::Box2I const &bbox, ApproximateControl const &ctrl)

Construct a new Approximate object, inferring the type from the type of the given MaskedImage.

Parameters

• x: the x-values of points

• y: the y-values of points

• im: The values at (x, y)

• bbox: Range where approximation should be valid

• ctrl: desired approximation algorithm

UndersampleStyle stringToUndersampleStyle(std::string const &style)

Conversion function to switch a string to an UndersampleStyle

template<typename ImageT>
std::shared_ptr<Background> makeBackground(ImageT const &img, BackgroundControl const &bgCtrl)

A convenience function that uses function overloading to make the correct type of Background

cf. std::make_pair()

std::shared_ptr<BoundedField> operator*(double const scale, std::shared_ptr<BoundedField const> bf)

template<typename OutImageT, typename InImageT>
void scaledPlus(OutImageT &outImage, double c1, InImageT const &inImage1, double c2, InImageT const &inImage2)

Compute the scaled sum of two images

outImage = c1 inImage1 + c2 inImage2

For example to linearly interpolate between two images set: c1 = 1.0 - fracDist c2 = fracDist where fracDist is the fractional distance of outImage from inImage1: location of outImage - location of inImage1 fracDist = —————————————- location of inImage2 - location of inImage1

Parameters

• [out] outImage: output image

• [in] c1: coefficient for image 1

• [in] inImage1: input image 1

• [in] c2: coefficient for image 2

• [in] inImage2: input image 2

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if outImage is not same dimensions as inImage1 and inImage2.

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, typename lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel>::const_xy_locator kernelLocator, int kWidth, int kHeight)

Apply convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

• inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

• kernelLocator: locator for (0,0) pixel of kernel (the origin of the kernel, not its center)

• kWidth: number of columns in kernel

• kHeight: number of rows in kernel

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, std::vector<lsst::afw::math::Kernel::Pixel> const &kernelColList, std::vector<lsst::afw::math::Kernel::Pixel> const &kernelRowList)

Apply separable convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

• inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

• kernelXList: kernel column vector

• kernelYList: kernel row vector

template<typename OutImageT, typename InImageT, typename KernelT>
void convolve(OutImageT &convolvedImage, InImageT const &inImage, KernelT const &kernel, ConvolutionControl const &convolutionControl = ConvolutionControl())

Convolve an Image or MaskedImage with a Kernel, setting pixels of an existing output image.

Various convolution kernels are available, including:

• FixedKernel: a kernel based on an image

• AnalyticKernel: a kernel based on a Function

• SeparableKernel: a kernel described by the product of two one-dimensional Functions: f0(x) * f1(y)

• LinearCombinationKernel: a linear combination of a set of spatially invariant basis kernels.

• DeltaFunctionKernel: a kernel that is all zeros except one pixel whose value is 1. Typically used as a basis kernel for LinearCombinationKernel.

If a kernel is spatially varying, its spatial model is computed at each pixel position on the image (pixel position, not pixel index). At present (2009-09-24) this position is computed relative to the lower left corner of the sub-image, but it will almost certainly change to be the lower left corner of the parent image.

All convolution is performed in real space. This allows convolution to handle masked pixels and spatially varying kernels. Although convolution of an Image with a spatially invariant kernel could, in fact, be performed in Fourier space, the code does not do this.

Note that mask bits are smeared by convolution; all nonzero pixels in the kernel smear the mask, even pixels that have very small values. Larger kernels smear the mask more and are also slower to convolve. Use the smallest kernel that will do the job.

convolvedImage has a border of edge pixels which cannot be computed normally. Normally these pixels are set to the standard edge pixel, as returned by edgePixel(). However, if your code cannot handle nans in the image or infs in the variance, you may set doCopyEdge true, in which case the edge pixels are set to the corresponding pixels of the input image and (if there is a mask) the mask EDGE bit is set.

The border of edge pixels has size:

• kernel.getCtrX() along the left edge

• kernel.getCtrY() along the bottom edge

• kernel.getWidth() - 1 - kernel.getCtrX() along the right edge

• kernel.getHeight() - 1 - kernel.getCtrY() along the top edge You can obtain a bounding box for the good pixels in the convolved image from a bounding box for the entire image using the Kernel method shrinkBBox.

Convolution has been optimized for the various kinds of kernels, as follows (listed approximately in order of decreasing speed):

• DeltaFunctionKernel convolution is a simple image shift.

• SeparableKernel convolution is performed by convolving the input by one of the two functions, then the result by the other function. Thus convolution with a kernel of size nCols x nRows becomes convolution with a kernel of size nCols x 1, followed by convolution with a kernel of size 1 x nRows.

• Convolution with spatially invariant versions of the other kernels is performed by computing the kernel image once and convolving with that. The code has been optimized for cache performance and so should be fairly efficient.

• Convolution with a spatially varying LinearCombinationKernel is performed by convolving the image by each basis kernel and combining the result by solving the spatial model. This will be efficient provided the kernel does not contain too many or very large basis kernels.

• Convolution with spatially varying AnalyticKernel is likely to be slow. The code simply computes the output one pixel at a time by computing the AnalyticKernel at that point and applying it to the input image. This is not favorable for cache performance (especially for large kernels) but avoids recomputing the AnalyticKernel. It is probably possible to do better.

Additional convolution functions include:

• convolveAtAPoint(): convolve a Kernel to an Image or MaskedImage at a point.

• basicConvolve(): convolve a Kernel with an Image or MaskedImage, but do not set the edge pixels of the output. Optimization of convolution for different types of Kernel are handled by different specializations of basicConvolve().

afw/examples offers programs that time convolution including timeConvolve and timeSpatiallyVaryingConvolve.

Parameters

• [out] convolvedImage: convolved image; must be the same size as inImage

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if convolvedImage is not the same size as inImage

• lsst::pex::exceptions::InvalidParameterError: if inImage is smaller than kernel in columns and/or rows.

• std::bad_alloc: when allocation of memory fails

template<typename OutImageT, typename InImageT, typename KernelT>
void convolve(OutImageT &convolvedImage, InImageT const &inImage, KernelT const &kernel, bool doNormalize, bool doCopyEdge = false)

Old, deprecated version of convolve.

Parameters

• [out] convolvedImage: convolved image; must be the same size as inImage

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] doNormalize: if true, normalize the kernel, else use “as is”

• [in] doCopyEdge: if false (default), set edge pixels to the standard edge pixel; if true, copy edge pixels from input and set EDGE bit of mask

template<typename ImageT>
ImageT::SinglePixel edgePixel(lsst::afw::image::detail::Image_tag)

Return an off-the-edge pixel appropriate for a given Image type

The value is quiet_NaN if that exists for the pixel type, else 0

template<typename MaskedImageT>
MaskedImageT::SinglePixel edgePixel(lsst::afw::image::detail::MaskedImage_tag)

Return an off-the-edge pixel appropriate for a given MaskedImage type

The components are:

• image = quiet_NaN if that exists for the pixel type, else 0

• mask = NO_DATA bit set

• variance = infinity if that exists for the pixel type, else 0

Exceptions

• lsst::pex::exceptions::LogicError: Thrown if the global mask plane dictionary does not have a NO_DATA bit.

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, std::vector<Kernel::Pixel> const &kernelXList, std::vector<Kernel::Pixel> const &kernelYList)

Apply separable convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

• inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

• kernelXList: kernel column vector

• kernelYList: kernel row vector

template<class UF>
UF::result_type int1d(UF const &func, IntRegion<typename UF::result_type> &reg, typename UF::result_type const &abserr = DEFABSERR, typename UF::result_type const &relerr = DEFRELERR)

Front end for the 1d integrator

template<class BF, class YREG>
BF::result_type int2d(BF const &func, IntRegion<typename BF::result_type> &reg, YREG const &yreg, typename BF::result_type const &abserr = DEFABSERR, typename BF::result_type const &relerr = DEFRELERR)

Front end for the 2d integrator

template<class TF, class YREG, class ZREG>
TF::result_type int3d(TF const &func, IntRegion<typename TF::result_type> &reg, YREG const &yreg, ZREG const &zreg, typename TF::result_type const &abserr = DEFABSERR, typename TF::result_type const &relerr = DEFRELERR)

Front end for the 3d integrator

template<class BF>
BF::result_type int2d(BF const &func, IntRegion<typename BF::result_type> &reg, IntRegion<typename BF::result_type> &yreg, typename BF::result_type const &abserr = DEFABSERR, typename BF::result_type const &relerr = DEFRELERR)

Front end for the 2d integrator

template<class TF>
TF::result_type int3d(TF const &func, IntRegion<typename TF::result_type> &reg, IntRegion<typename TF::result_type> &yreg, IntRegion<typename TF::result_type> &zreg, typename TF::result_type const &abserr = DEFABSERR, typename TF::result_type const &relerr = DEFRELERR)

Front end for the 3d integrator

template<typename UnaryFunctionT>
UnaryFunctionT::result_type integrate(UnaryFunctionT func, typename UnaryFunctionT::argument_type const a, typename UnaryFunctionT::argument_type const b, double eps = 1.0e-6)

The 1D integrator

Note

This simply wraps the int1d function above and handles the instantiation of the intRegion.

template<typename BinaryFunctionT>
BinaryFunctionT::result_type integrate2d(BinaryFunctionT func, typename BinaryFunctionT::first_argument_type const x1, typename BinaryFunctionT::first_argument_type const x2, typename BinaryFunctionT::second_argument_type const y1, typename BinaryFunctionT::second_argument_type const y2, double eps = 1.0e-6)

The 2D integrator

Note

Adapted from RHL’s SDSS code

std::shared_ptr<Interpolate> makeInterpolate(std::vector<double> const &x, std::vector<double> const &y, Interpolate::Style const style = Interpolate::AKIMA_SPLINE)

A factory function to make Interpolate objects

Parameters

• x: the x-values of points

• y: the values at x[]

• style: desired interpolator

std::shared_ptr<Interpolate> makeInterpolate(ndarray::Array<double const, 1> const &x, ndarray::Array<double const, 1> const &y, Interpolate::Style const style = Interpolate::AKIMA_SPLINE)

Interpolate::Style stringToInterpStyle(std::string const &style)

Conversion function to switch a string to an Interpolate::Style.

Parameters

• style: desired type of interpolation

Interpolate::Style lookupMaxInterpStyle(int const n)

Get the highest order Interpolation::Style available for ‘n’ points.

Parameters

• n: Number of points

int lookupMinInterpPoints(Interpolate::Style const style)

Get the minimum number of points needed to use the requested interpolation style

Parameters

• style: The style in question

void printKernel(lsst::afw::math::Kernel const &kernel, bool doNormalize, double x = 0, double y = 0, std::string pixelFmt = "%7.3f")

Print the pixel values of a Kernel to std::cout

Rows increase upward and columns to the right; thus the lower left pixel is (0,0).

Parameters

• kernel: the kernel

• doNormalize: if true, normalize kernel

• x: x at which to evaluate kernel

• y: y at which to evaluate kernel

• pixelFmt: format for pixel values

template<typename ReturnT>
FitResults minimize(lsst::afw::math::Function1<ReturnT> const &function, std::vector<double> const &initialParameterList, std::vector<double> const &stepSizeList, std::vector<double> const &measurementList, std::vector<double> const &varianceList, std::vector<double> const &xPositionList, double errorDef)

Find the minimum of a function(x)

Uses the Minuit fitting package with a standard definition of chiSq (see MinimizerFunctionBase1).

Return

true if minimum is valid, false otherwise

Parameters

• function: function(x) to be minimized

• initialParameterList: initial guess for parameters

• stepSizeList: step size for each parameter; use 0.0 to fix a parameter

• measurementList: measured values

• varianceList: variance for each measurement

• xPositionList: x position of each measurement

• errorDef: what is this?

To do:

• Document stepSizeList better

• Document errorDef

• Compute stepSize automatically? (if so, find a different way to fix parameters)

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if any input vector is the wrong length

template<typename ReturnT>
FitResults minimize(lsst::afw::math::Function2<ReturnT> const &function, std::vector<double> const &initialParameterList, std::vector<double> const &stepSizeList, std::vector<double> const &measurementList, std::vector<double> const &varianceList, std::vector<double> const &xPositionList, std::vector<double> const &yPositionList, double errorDef)

Find the minimum of a function(x, y)

Uses the Minuit fitting package with a standard definition of chiSq. (see MinimizerFunctionBase2).

To do:

• Document stepSizeList better

• Document errorDef

• Compute stepSize automatically? (if so, find a different way to fix parameters)

Return

true if minimum is valid, false otherwise

Parameters

• function: function(x,y) to be minimized

• initialParameterList: initial guess for parameters

• stepSizeList: step size for each parameter; use 0.0 to fix a parameter

• measurementList: measured values

• varianceList: variance for each measurement

• xPositionList: x position of each measurement

• yPositionList: y position of each measurement

• errorDef: what is this?

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if any input vector is the wrong length

template<typename ImageT>
std::shared_ptr<ImageT> offsetImage(ImageT const &image, float dx, float dy, std::string const &algorithmName = "lanczos5", unsigned int buffer = 0)

Return an image offset by (dx, dy) using the specified algorithm

Note

The image pixels are always offset by a fraction of a pixel and the image origin (XY0) picks is modified to handle the integer portion of the offset. In the special case that the offset in both x and y lies in the range (-1, 1) the origin is not changed. Otherwise the pixels are shifted by (-0.5, 0.5] pixels and the origin shifted accordingly.

Parameters

• image: The image to offset

• dx: move the image this far in the column direction

• dy: move the image this far in the row direction

• algorithmName: Type of resampling Kernel to use

• buffer: Width of buffer (border) around kernel image to allow for warping edge effects (pixels). Values < 0 are treated as 0. This is only used during computation; the final image has the same dimensions as the kernel.

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if the algorithm is invalid

template<typename ImageT>
std::shared_ptr<ImageT> rotateImageBy90(ImageT const &image, int nQuarter)

Rotate an image by an integral number of quarter turns

Parameters

• image: The image to rotate

• nQuarter: the desired number of quarter turns

template<typename ImageT>
std::shared_ptr<ImageT> flipImage(ImageT const &inImage, bool flipLR, bool flipTB)

Flip an image leftright and/or topbottom

Parameters

• inImage: The image to flip

• flipLR: Flip left <> right?

• flipTB: Flip top <> bottom?

template<typename ImageT>
std::shared_ptr<ImageT> binImage(ImageT const &inImage, int const binX, int const binY, lsst::afw::math::Property const flags = lsst::afw::math::MEAN)

Parameters

• inImage: The image to bin

• binX: Output pixels are binX*binY input pixels

• binY: Output pixels are binX*binY input pixels

• flags: how to generate super-pixels

template<typename ImageT>
std::shared_ptr<ImageT> binImage(ImageT const &inImage, int const binsize, lsst::afw::math::Property const flags = lsst::afw::math::MEAN)

Parameters

• inImage: The image to bin

• binsize: Output pixels are binsize*binsize input pixels

• flags: how to generate super-pixels

template<typename ImageT>
void randomUniformImage(ImageT *image, Random &rand)

Set image to random numbers uniformly distributed in the range [0, 1)

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomUniformPosImage(ImageT *image, Random &rand)

Set image to random numbers uniformly distributed in the range (0, 1)

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomUniformIntImage(ImageT *image, Random &rand, unsigned long n)

Set image to random integers uniformly distributed in the range 0 … n - 1

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

• [in] n: (exclusive) upper limit for random variates

template<typename ImageT>
void randomFlatImage(ImageT *image, Random &rand, double const a, double const b)

Set image to random numbers uniformly distributed in the range [a, b)

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

• [in] a: (inclusive) lower limit for random variates

• [in] b: (exclusive) upper limit for random variates

template<typename ImageT>
void randomGaussianImage(ImageT *image, Random &rand)

Set image to random numbers with a gaussian N(0, 1) distribution

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomChisqImage(ImageT *image, Random &rand, double const nu)

Set image to random numbers with a chi^2_{nu} distribution

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

• [in] nu: number of degrees of freedom

template<typename ImageT>
void randomPoissonImage(ImageT *image, Random &rand, double const mu)

Set image to random numbers with a Poisson distribution with mean mu (n.b. not per-pixel)

Parameters

• [out] image: The image to set

• [inout] rand: definition of random number algorithm, seed, etc.

• [in] mu: mean of distribution

template<typename PixelT>
std::shared_ptr<lsst::afw::image::Image<PixelT>> statisticsStack(std::vector<std::shared_ptr<lsst::afw::image::Image<PixelT>>> &images, Property flags, StatisticsControl const &sctrl = StatisticsControl(), std::vector<lsst::afw::image::VariancePixel> const &wvector = std::vector<lsst::afw::image::VariancePixel>(0))

Parameters

• images: Images to process

• flags: statistics requested

• sctrl: Control structure

• wvector: vector containing weights

A function to compute some statistics of a stack of Images

template<typename PixelT>
void statisticsStack(lsst::afw::image::Image<PixelT> &out, std::vector<std::shared_ptr<lsst::afw::image::Image<PixelT>>> &images, Property flags, StatisticsControl const &sctrl = StatisticsControl(), std::vector<lsst::afw::image::VariancePixel> const &wvector = std::vector<lsst::afw::image::VariancePixel>(0))

Parameters

• out: Output image

• images: Images to process

• flags: statistics requested

• sctrl: Control structure

• wvector: vector containing weights

@ brief compute statistical stack of Image. Write to output image in-situ

template<typename PixelT>
std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>> statisticsStack(std::vector<std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>>> &images, Property flags, StatisticsControl const &sctrl, std::vector<lsst::afw::image::VariancePixel> const &wvector, image::MaskPixel clipped, std::vector<std::pair<image::MaskPixel, image::MaskPixel>> const &maskMap)

A function to compute some statistics of a stack of Masked Images

If none of the input images are valid for some pixel, the afwMath::StatisticsControl::getNoGoodPixelsMask() bit(s) are set.

Parameters

• [in] images: MaskedImages to process.

• [in] flags: Statistics requested.

• [in] sctrl: Control structure.

• [in] wvector: Vector of weights.

• [in] clipped: Mask to set for pixels that were clipped (NOT rejected due to masks).

• [in] maskMap: Vector of pairs of mask pixel values; any pixel on an input with any of the bits in .first will result in all of the bits in .second being set on the corresponding pixel on the output.

All the work is done in the function computeMaskedImageStack.

template<typename PixelT>
std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>> statisticsStack(std::vector<std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>>> &images, Property flags, StatisticsControl const &sctrl = StatisticsControl(), std::vector<lsst::afw::image::VariancePixel> const &wvector = std::vector<lsst::afw::image::VariancePixel>(0), image::MaskPixel clipped = 0, image::MaskPixel excuse = 0)

Parameters

• images: MaskedImages to process

• flags: statistics requested

• sctrl: control structure

• wvector: vector containing weights

• clipped: bitmask to set if any input was clipped or masked

• excuse: bitmask to excuse from marking as clipped

A function to compute some statistics of a stack of Masked Images

If none of the input images are valid for some pixel, the afwMath::StatisticsControl::getNoGoodPixelsMask() bit(s) are set.

Delegates to the more general version of statisticsStack taking a maskMap.

template<typename PixelT>
void statisticsStack(lsst::afw::image::MaskedImage<PixelT> &out, std::vector<std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>>> &images, Property flags, StatisticsControl const &sctrl, std::vector<lsst::afw::image::VariancePixel> const &wvector, image::MaskPixel clipped, std::vector<std::pair<image::MaskPixel, image::MaskPixel>> const &maskMap)

A function to compute some statistics of a stack of Masked Images

If none of the input images are valid for some pixel, the afwMath::StatisticsControl::getNoGoodPixelsMask() bit(s) are set.

Parameters

• [out] out: Output MaskedImage.

• [in] images: MaskedImages to process.

• [in] flags: Statistics requested.

• [in] sctrl: Control structure.

• [in] wvector: Vector of weights.

• [in] clipped: Mask to set for pixels that were clipped (NOT rejected due to masks).

• [in] maskMap: Vector of pairs of mask pixel values; any pixel on an input with any of the bits in .first will result in all of the bits in .second being set on the corresponding pixel on the output.

All the work is done in the function computeMaskedImageStack.

template<typename PixelT>
void statisticsStack(lsst::afw::image::MaskedImage<PixelT> &out, std::vector<std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>>> &images, Property flags, StatisticsControl const &sctrl = StatisticsControl(), std::vector<lsst::afw::image::VariancePixel> const &wvector = std::vector<lsst::afw::image::VariancePixel>(0), image::MaskPixel clipped = 0, image::MaskPixel excuse = 0)

Parameters

• out: Output image

• images: MaskedImages to process

• flags: statistics requested

• sctrl: control structure

• wvector: vector containing weights

• clipped: bitmask to set if any input was clipped or masked

• excuse: bitmask to excuse from marking as clipped

@ brief compute statistical stack of MaskedImage. Write to output image in-situ

template<typename PixelT>
std::vector<PixelT> statisticsStack(std::vector<std::vector<PixelT>> &vectors, Property flags, StatisticsControl const &sctrl = StatisticsControl(), std::vector<lsst::afw::image::VariancePixel> const &wvector = std::vector<lsst::afw::image::VariancePixel>(0))

Parameters

• vectors: Vectors to process

• flags: statistics requested

• sctrl: control structure

• wvector: vector containing weights

A function to compute some statistics of a stack of std::vectors

template<typename PixelT>
std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>> statisticsStack(lsst::afw::image::Image<PixelT> const &image, Property flags, char dimension, StatisticsControl const &sctrl = StatisticsControl())

A function to compute statistics on the rows or columns of an image

template<typename PixelT>
std::shared_ptr<lsst::afw::image::MaskedImage<PixelT>> statisticsStack(lsst::afw::image::MaskedImage<PixelT> const &image, Property flags, char dimension, StatisticsControl const &sctrl = StatisticsControl())

A function to compute statistics on the rows or columns of an image

Property stringToStatisticsProperty(std::string const property)

Conversion function to switch a string to a Property (see Statistics.h)

template<typename Pixel>
Statistics makeStatistics(lsst::afw::image::Image<Pixel> const &img, lsst::afw::image::Mask<image::MaskPixel> const &msk, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Handle a watered-down front-end to the constructor (no variance)

template<typename ImageT, typename MaskT, typename VarianceT>
Statistics makeStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Handle a straight front-end to the constructor

template<typename Pixel>
Statistics makeStatistics(lsst::afw::image::MaskedImage<Pixel> const &mimg, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Handle MaskedImages, just pass the getImage() and getMask() values right on through.

template<typename Pixel>
Statistics makeStatistics(lsst::afw::image::MaskedImage<Pixel> const &mimg, lsst::afw::image::Image<WeightPixel> const &weights, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Handle MaskedImages, just pass the getImage() and getMask() values right on through.

Statistics makeStatistics(lsst::afw::image::Mask<lsst::afw::image::MaskPixel> const &msk, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Specialization to handle Masks

Parameters

• msk: Image (or MaskedImage) whose properties we want

• flags: Describe what we want to calculate

• sctrl: Control how things are calculated

template<typename Pixel>
Statistics makeStatistics(lsst::afw::image::Image<Pixel> const &img, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Parameters

• img: Image (or Image) whose properties we want

• flags: Describe what we want to calculate

• sctrl: Control calculation

The makeStatistics() overload to handle regular (non-masked) Images

template<typename EntryT>
Statistics makeStatistics(std::vector<EntryT> const &v, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Parameters

• v: Image (or MaskedImage) whose properties we want

• flags: Describe what we want to calculate

• sctrl: Control calculation

The makeStatistics() overload to handle std::vector<>

template<typename EntryT>
Statistics makeStatistics(std::vector<EntryT> const &v, std::vector<WeightPixel> const &vweights, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Parameters

• v: Image (or MaskedImage) whose properties we want

• vweights: Weights

• flags: Describe what we want to calculate

• sctrl: Control calculation

The makeStatistics() overload to handle std::vector<>

template<typename EntryT>
Statistics makeStatistics(lsst::afw::math::MaskedVector<EntryT> const &mv, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Parameters

• mv: MaskedVector

• flags: Describe what we want to calculate

• sctrl: Control calculation

The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>

template<typename EntryT>
Statistics makeStatistics(lsst::afw::math::MaskedVector<EntryT> const &mv, std::vector<WeightPixel> const &vweights, int const flags, StatisticsControl const &sctrl = StatisticsControl())

Parameters

• mv: MaskedVector

• vweights: weights

• flags: Describe what we want to calculate

• sctrl: Control calculation

The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>

std::shared_ptr<SeparableKernel> makeWarpingKernel(std::string name)

Return a warping kernel given its name.

Intended for use with warpImage() and warpExposure().

Allowed names are:

• bilinear: return a BilinearWarpingKernel

• lanczos#: return a LanczosWarpingKernel of order #, e.g. lanczos4

• nearest: return a NearestWarpingKernel

A warping kernel is a subclass of SeparableKernel with the following properties (though for the sake of speed few, if any, of these are enforced):

• Width and height are even. This is unusual for a kernel, but it is more efficient because if the extra pixel was included it would always have value 0.

• The center pixels should be adjacent to the kernel center. Again, this avoids extra pixels that are sure to have value 0.

• It has two parameters: fractional x and fractional row position on the source image. The fractional position is the offset of the pixel position on the source from the center of a nearby source pixel:

  • The pixel whose center is just below or to the left of the source position: 0 <= fractional x and y < 0 and the kernel center is the default (size-1)/2.

  • The pixel whose center is just above or to the right of the source position: -1.0 < fractional x and y <= 0 and the kernel center must be set to (size+1)/2.

template<typename DestExposureT, typename SrcExposureT>
int warpExposure(DestExposureT &destExposure, SrcExposureT const &srcExposure, WarpingControl const &control, typename DestExposureT::MaskedImageT::SinglePixel padValue = lsst::afw::math::edgePixel<typename DestExposureT::MaskedImageT>(typename lsst::afw::image::detail::image_traits<typename DestExposureT::MaskedImageT>::image_category()))

Parameters

• destExposure: Remapped exposure. Wcs and xy0 are read, MaskedImage is set, and PhotoCalib, Filter and VisitInfo are copied from srcExposure. All other attributes are left alone (including Detector and Psf)

• srcExposure: Source exposure

• control: control parameters

• padValue: use this value for undefined (edge) pixels

Warp (remap) one exposure to another.

This is a convenience wrapper around warpImage().

template<typename DestImageT, typename SrcImageT>
int warpImage(DestImageT &destImage, geom::SkyWcs const &destWcs, SrcImageT const &srcImage, geom::SkyWcs const &srcWcs, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

Warp an Image or MaskedImage to a new Wcs. See also convenience function warpExposure() to warp an Exposure.

Parameters

• destImage: remapped image

• destWcs: WCS of remapped image

• srcImage: source image

• srcWcs: WCS of source image

• control: control parameters

• padValue: use this value for undefined (edge) pixels

Edge pixels are set to padValue; these are pixels that cannot be computed because they are too near the edge of srcImage or miss srcImage entirely.

Algorithm Without Interpolation:

Return

the number of valid pixels in destImage (those that are not edge pixels).

For each integer pixel position in the remapped Exposure:

• The associated pixel position on srcImage is determined using the destination and source WCS

• The warping kernel’s parameters are set based on the fractional part of the pixel position on srcImage

• The warping kernel is applied to srcImage at the integer portion of the pixel position to compute the remapped pixel value

• A flux-conservation factor is determined from the source and destination WCS and is applied to the remapped pixel

The scaling of intensity for relative area of source and destination uses two minor approximations:

• The area of the sky marked out by a pixel on the destination image corresponds to a parallellogram on the source image.

• The area varies slowly enough across the image that we can get away with computing the source area shifted by half a pixel up and to the left of the true area.

Algorithm With Interpolation:

Interpolation simply reduces the number of times WCS is used to map between destination and source pixel position. This computation is only made at a grid of points on the destination image, separated by interpLen pixels along rows and columns. All other source pixel positions are determined by linear interpolation between those grid points. Everything else remains the same.

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if destImage overlaps srcImage

• std::bad_alloc: when allocation of CPU memory fails

Warning

The code that tests for image overlap is not guranteed to work correctly, based on the C++ standard. It is, in theory, possible for the code to report a “false positive”, meaning that it may claim that images overlap when they do not. We don’t believe that any of our current compilers have this problem. If, in the future, this becomes a problem then we will probably have to remove the test and rely on users being careful.

template<typename DestImageT, typename SrcImageT>
int warpImage(DestImageT &destImage, SrcImageT const &srcImage, geom::TransformPoint2ToPoint2 const &srcToDest, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

A variant of warpImage that uses a Transform<Point2Endpoint, Point2Endpoint> instead of a pair of WCS to describe the transformation.

Return

the number of good pixels

Parameters

• [inout] destImage: Destination image; all pixels are set

• [in] srcImage: Source image

• [in] srcToDest: Transformation from source to destination pixels, in parent coordinates; the inverse must be defined (and is the only direction used). makeWcsPairTransform(srcWcs, destWcs) is one way to compute this transform.

• [in] control: Warning control parameters

• [in] padValue: Value used for pixels in the destination image that are outside the region of pixels that can be computed from the source image

template<typename DestImageT, typename SrcImageT>
int warpCenteredImage(DestImageT &destImage, SrcImageT const &srcImage, lsst::geom::LinearTransform const &linearTransform, lsst::geom::Point2D const &centerPosition, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

Parameters

• destImage: remapped image

• srcImage: source image

• linearTransform: linear transformation to apply

• centerPosition: pixel position for location of linearTransform

• control: control parameters

• padValue: use this value for undefined (edge) pixels

Warp an image with a LinearTranform about a specified point.

This enables warping an image of e.g. a PSF without translating the centroid.

Variables

template<typename T>
bool constexpr IS_NOTHROW_INIT = noexcept(static_cast<T>(1.0))

Test that a Function’s return value is nothrow-castable to T

std::complex is an example of a numeric type that does not satisfy this requirement.

double const MOCK_INF = 1.e10

double const DEFABSERR = 1.e-15

double const DEFRELERR = 1.e-6

generic_kernel_tag generic_kernel_tag_

deltafunction_kernel_tag deltafunction_kernel_tag_

class AnalyticKernel : public lsst::afw::table::io::PersistableFacade<AnalyticKernel>, public lsst::afw::math::Kernel

#include <Kernel.h>

A kernel described by a function.

The function’s x, y arguments are as follows:

• -getCtr() for the lower left corner pixel

• 0, 0 for the center pixel

• (getDimensions() - 1) - getCtr() for the upper right pixel

Note: each pixel is set to the value of the kernel function at the center of the pixel (rather than averaging the function over the area of the pixel).

template<typename PixelT>
class Approximate

#include <Approximate.h>

Approximate values for a MaskedImage

class ApproximateControl

#include <Approximate.h>

Control how to make an approximation

Note

the x- and y-order must be the same, due to a limitation of Chebyshev1Function2

class Background

#include <Background.h>

A virtual base class to evaluate image background levels

Subclassed by lsst::afw::math::BackgroundMI

class BackgroundControl

#include <Background.h>

Pass parameters to a Background object

class BackgroundMI : public lsst::afw::math::Background

#include <Background.h>

A class to evaluate image background levels

Break an image up into nx*ny sub-images and use a statistical to estimate the background levels in each square. Then use a user-specified or algorithm to estimate background at a given pixel coordinate.

Methods are available to return the background at a point (inefficiently), or an entire background image. BackgroundControl contains a public StatisticsControl member to allow user control of how the backgrounds are computed.

math::BackgroundControl bctrl(7, 7);  // number of sub-image squares in {x,y}-dimensions
bctrl.sctrl.setNumSigmaClip(5.0);     // use 5-sigma clipping for the sub-image means
std::shared_ptr<math::Background> backobj = math::makeBackground(img, bctrl);
// get a whole background image
Image<PixelT> back = backobj->getImage<PixelT>(math::Interpolate::NATURAL_SPLINE);

// get the background at a pixel at i_x,i_y
double someValue = backobj.getPixel(math::Interpolate::LINEAR, i_x, i_y);

template<typename ReturnT>
class BasePolynomialFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <Function.h>

Base class for 2-dimensional polynomials of the form:

f(x,y) =   c0 f0(x) f0(y)                                        (0th order)
         + c1 f1(x) f0(x) + c2 f0(x) f1(y)                       (1st order)
         + c3 f2(x) f0(y) + c4 f1(x) f1(y) + c5 f0(x) f2(y)      (2nd order)
         + ...

and typically f0(x) = 1

Subclassed by lsst::afw::math::Chebyshev1Function2< ReturnT >, lsst::afw::math::PolynomialFunction2< ReturnT >

class BilinearWarpingKernel : public lsst::afw::math::SeparableKernel

#include <warpExposure.h>

Bilinear warping: fast; good for undersampled data.

The kernel size is 2 x 2.

For more information about warping kernels see makeWarpingKernel

class BoundedField : public lsst::afw::table::io::PersistableFacade<BoundedField>, public lsst::afw::table::io::Persistable

#include <BoundedField.h>

An abstract base class for 2-d functions defined on an integer bounding boxes

Integer bounding boxes (lsst::geom::Box2I) are inclusive of the end pixels (integer positions correspond to the centers of the pixels and include the entirety of those pixels). Thus a BoundedField defined on the box [x0, x1] x [y0, y1] actually covers the range [x0 - 0.5, x1 + 0.5] x [y0 - 0.5, y1 + 0.5].

BoundedField provides a number of ways of accessing the function, all delegating to a single evaluate-at-a-point implementation. The base class does not mandate anything about how the field is constructed, so it’s appropriate for use with e.g. model-fitting results, interpolation results points, or functions known a priori.

Usually, BoundedField will be used to represent functions that correspond to images, for quantities such as aperture corrections, photometric scaling, PSF model parameters, or backgrounds, and its bounding box will be set to match the PARENT bounding box of the image.

Subclassed by lsst::afw::math::ChebyshevBoundedField, lsst::afw::math::PixelAreaBoundedField, lsst::afw::math::ProductBoundedField, lsst::afw::math::TransformBoundedField, lsst::meas::algorithms::CoaddBoundedField

class CandidateVisitor

Subclassed by lsst::ip::diffim::detail::AssessSpatialKernelVisitor< PixelT >, lsst::ip::diffim::detail::BuildSingleKernelVisitor< PixelT >, lsst::ip::diffim::detail::BuildSpatialKernelVisitor< PixelT >, lsst::ip::diffim::detail::KernelPcaVisitor< PixelT >, lsst::ip::diffim::detail::KernelSumVisitor< PixelT >

template<typename ReturnT>
class Chebyshev1Function1 : public lsst::afw::math::Function1<ReturnT>

#include <FunctionLibrary.h>

1-dimensional weighted sum of Chebyshev polynomials of the first kind.

f(x) = c0 T0(x’) + c1 T1(x’) + c2 T2(x’) + … = c0 + c1 T1(x’) + c2 T2(x’) + … where:

• Tn(x) is the nth Chebyshev function of the first kind: T0(x) = 1 T1(x) = 2 Tn+1(x) = 2xTn(x) + Tn-1(x)

• x’ is x offset and scaled to range [-1, 1] as x ranges over [minX, maxX]

The function argument must be in the range [minX, maxX].

template<typename ReturnT>
class Chebyshev1Function2 : public lsst::afw::math::BasePolynomialFunction2<ReturnT>

#include <FunctionLibrary.h>

2-dimensional weighted sum of Chebyshev polynomials of the first kind.

f(x,y) = c0 T0(x’) T0(y’) # order 0

• c1 T1(x’) T0(y’) + c2 T0(x’) T1(y’) # order 1

• c3 T2(x’) T0(y’) + c4 T1(x’) T1(y’) + c5 T0(x’) T2(y’) # order 2

• …

= c0 # order 0

• c1 T1(x’) + c2 T1(y’) # order 1

• c3 T2(x’) + c4 T1(x’) T1(y’) + c5 T2(y’) # order 2

• …

where:

• Tn(x) is the nth Chebyshev function of the first kind: T0(x) = 1 T1(x) = x Tn+1(x) = 2xTn(x) + Tn-1(x)

• x’ is x offset and scaled to range [-1, 1] as x ranges over [minX, maxX]

• y’ is y offset and scaled to range [-1, 1] as y ranges over [minY, maxY]

Return value is incorrect if function arguments are not in the range [minX, maxX], [minY, maxY].

class ChebyshevBoundedField : public lsst::afw::table::io::PersistableFacade<ChebyshevBoundedField>, public lsst::afw::math::BoundedField

#include <ChebyshevBoundedField.h>

A BoundedField based on 2-d Chebyshev polynomials of the first kind.

The 2-d Chebyshev polynomial used here is defined as:

\[ f(x,y) = \sum_i \sum_j a_{i,j} T_i(x) T_j(y) \]

where \(T_n(x)\) is the n-th order Chebyshev polynomial of \(x\) and \(a_{i,j}\) is the corresponding coefficient of the (i,j) polynomial term.

ChebyshevBoundedField supports fitting to gridded and non-gridded data, as well coefficient matrices with different x- and y-order.

There is currently quite a bit of duplication of functionality between ChebyshevBoundedField, ApproximateChebyshev, and Chebyshev1Function2; the intent is that ChebyshevBoundedField will ultimately replace ApproximateChebyshev and should be preferred over Chebyshev1Function2 when the parametrization interface that is part of the Function2 class is not needed.

class ChebyshevBoundedFieldControl

#include <ChebyshevBoundedField.h>

A control object used when fitting ChebyshevBoundedField to data (see ChebyshevBoundedField::fit)

class ConvolutionControl

#include <ConvolveImage.h>

Parameters to control convolution

template<typename T>
class Covariogram

#include <GaussianProcess.h>

The parent class of covariogram functions for use in Gaussian Process interpolation

Each instantiation of a Covariogram will store its own hyper parameters

Subclassed by lsst::afw::math::NeuralNetCovariogram< T >, lsst::afw::math::SquaredExpCovariogram< T >

struct deltafunction_kernel_tag : public lsst::afw::math::generic_kernel_tag

#include <traits.h>

Kernel has only one non-zero pixel.

class DeltaFunctionKernel : public lsst::afw::table::io::PersistableFacade<DeltaFunctionKernel>, public lsst::afw::math::Kernel

#include <Kernel.h>

A kernel that has only one non-zero pixel (of value 1)

It has no adjustable parameters and so cannot be spatially varying.

template<typename ReturnT>
class DoubleGaussianFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <FunctionLibrary.h>

double Guassian (sum of two Gaussians)

Intended for use as a PSF model: the main Gaussian represents the core and the second Gaussian represents the wings.

f(x,y) = A (e^(-r^2 / 2 sigma1^2) + ampl2 e^(-r^2 / 2 sigma2^2)) where:

• A = 1 / (2 pi (sigma1^2 + ampl2 sigma2^2))

• r^2 = x^2 + y^2 coefficients c[0] = sigma1, c[1] = sigma2, c[2] = ampl2

struct FitResults

#include <minimize.h>

Results from minimizing a function

class FixedKernel : public lsst::afw::table::io::PersistableFacade<FixedKernel>, public lsst::afw::math::Kernel

#include <Kernel.h>

A kernel created from an Image

It has no adjustable parameters and so cannot be spatially varying.

template<typename ReturnT>
class Function : public lsst::afw::table::io::PersistableFacade<Function<ReturnT>>, public lsst::afw::table::io::Persistable

#include <Function.h>

Basic Function class.

Function objects are functions whose parameters may be read and changed using getParameters and setParameters. They were designed for use with the Kernel class.

These are simple functors with the restrictions that:

• Function arguments and parameters are double precision

• The return type is templated

To create a function for a particular equation, subclass Function or (much more likely) Function1 or Function2. Your subclass must:

• Have one or more constructors, all of which must initialize _params

• Define operator() with code to compute the function using this->_params or this->getParams() to reference the parameters

• If the function is a linear combination of parameters then override the function isLinearCombination.

If you wish to cache any information you may use the _isCacheValid flag; this is automatically set false whenever parameters are changed.

Design Notes: The reason these functions exist (rather than using a pre-existing function class, such as Functor in VisualWorkbench) is because the Kernel class requires function objects with a standard interface for setting and getting function parameters.

The reason isLinearCombination exists is to support refactoring LinearCombinationKernels.

Subclassed by lsst::afw::math::Function1< ReturnT >, lsst::afw::math::Function2< ReturnT >

template<typename ReturnT>
class Function1 : public lsst::afw::table::io::PersistableFacade<Function1<ReturnT>>, public lsst::afw::math::Function<ReturnT>

#include <Function.h>

A Function taking one argument.

Subclass and override operator() to do useful work.

Subclassed by lsst::afw::math::Chebyshev1Function1< ReturnT >, lsst::afw::math::GaussianFunction1< ReturnT >, lsst::afw::math::IntegerDeltaFunction1< ReturnT >, lsst::afw::math::LanczosFunction1< ReturnT >, lsst::afw::math::NullFunction1< ReturnT >, lsst::afw::math::PolynomialFunction1< ReturnT >

template<typename ReturnT>
class Function2 : public lsst::afw::table::io::PersistableFacade<Function2<ReturnT>>, public lsst::afw::math::Function<ReturnT>

#include <Function.h>

A Function taking two arguments.

Subclass and override operator() to do useful work.

Subclassed by lsst::afw::math::BasePolynomialFunction2< ReturnT >, lsst::afw::math::DoubleGaussianFunction2< ReturnT >, lsst::afw::math::GaussianFunction2< ReturnT >, lsst::afw::math::IntegerDeltaFunction2< ReturnT >, lsst::afw::math::LanczosFunction2< ReturnT >, lsst::afw::math::NullFunction2< ReturnT >

template<typename ReturnT>
class GaussianFunction1 : public lsst::afw::math::Function1<ReturnT>

#include <FunctionLibrary.h>

1-dimensional Gaussian

f(x) = A e^(-x^2 / 2 sigma^2) where:

• A = 1 / (sqrt(2 pi) xSigma) coefficient c0 = sigma

template<typename ReturnT>
class GaussianFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <FunctionLibrary.h>

2-dimensional Gaussian

f(x,y) = A e^((-pos1^2 / 2 sigma1^2) - (pos2^2 / 2 sigma2^2)) where:

• A = 1 / (2 pi sigma1 sigma2)

• pos1 = cos(angle) x + sin(angle) y

• pos2 = -sin(angle) x + cos(angle) y coefficients c0 = sigma1, c1 = sigma2, c2 = angle

Note

if sigma1 > sigma2 then angle is the angle of the major axis

template<typename T>
class GaussianProcess

#include <GaussianProcess.h>

Stores values of a function sampled on an image and allows you to interpolate the function to unsampled points

The data will be stored in a KD Tree for easy nearest neighbor searching when interpolating.

The array _function[] will contain the values of the function being interpolated. You can provide a two dimensional array _function[][] if you wish to interpolate a vector of functions. In this case _function[i][j] is the jth function associated with the ith data point. Note: presently, the covariance matrices do not relate elements of _function[i][] to each other, so the variances returned will be identical for all functions evaluated at the same point in parameter space.

_data[i][j] will be the jth component of the ith data point.

_max and _min contain the maximum and minimum values of each dimension in parameter space (if applicable) so that data points can be normalized by _max-_min to keep distances between points reasonable. This is an option specified by calling the relevant constructor.

class GaussianProcessTimer

#include <GaussianProcess.h>

This is a structure for keeping track of how long the interpolation methods spend on different parts of the interpolation

_eigenTime keeps track of how much time is spent using Eigen’s linear algebra packages

_iterationTime keeps track of how much time is spent iterating over matrix indices (this is also a catch-all for time that does not obviously fit in the other categories)

_searchTime keeps track of how much time is spent on nearest neighbor searches (when applicable)

_varianceTime keeps track of how much time is spent calculating the variance of our interpolated function value (note: time spent using Eigen packages for this purpose is tallied here, not in _eigenTime)

_totalTime keeps track of how much time total is spent on interpolations

_interpolationCount keeps track of how many points have been interpolated

struct generic_kernel_tag

#include <traits.h>

Tags carrying information about Kernels Kernel with no special properties.

Subclassed by lsst::afw::math::deltafunction_kernel_tag

template<typename ValueT>
class ImageImposter

#include <Statistics.h>

A vector wrapper to provide a vector with the necessary methods and typedefs to be processed by Statistics as though it were an Image.

template<typename ValueT>
class infinite_iterator : public boost::iterator_adaptor<infinite_iterator<ValueT>, const ValueT *, const ValueT, boost::forward_traversal_tag>

#include <Statistics.h>

This iterator will never increment. It is returned by row_begin() in the MaskImposter class (below) to allow phony mask pixels to be iterated over for non-mask images within Statistics.

template<typename ReturnT>
class IntegerDeltaFunction1 : public lsst::afw::math::Function1<ReturnT>

#include <FunctionLibrary.h>

1-dimensional integer delta function.

f(x) = 1 if x == xo, 0 otherwise.

For use as a kernel function be sure to handle the offset for row and column center; see examples/deltaFunctionKernel for an example.

template<typename ReturnT>
class IntegerDeltaFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <FunctionLibrary.h>

2-dimensional integer delta function.

f(x) = 1 if x == xo and y == yo, 0 otherwise.

For use as a kernel function be sure to handle the offset for row and column center; see examples/deltaFunctionKernel for an example.

template<typename KernelT>
struct is_analyticKernel

#include <traits.h>

traits class to determine if a Kernel is represented as an analytic function

Subclassed by lsst::afw::math::is_analyticKernel< KernelT * >, lsst::afw::math::is_analyticKernel< std::shared_ptr< KernelT > >

template<typename T>
class KdTree

#include <GaussianProcess.h>

The data for GaussianProcess is stored in a KD tree to facilitate nearest-neighbor searches

Note: I have removed the ability to arbitrarily specify a distance function. The KD Tree nearest neighbor search algorithm only makes sense in the case of Euclidean distances, so I have forced KdTree to use Euclidean distances.

class Kernel : public lsst::afw::table::io::PersistableFacade<Kernel>, public lsst::afw::table::io::Persistable

#include <Kernel.h>

Kernels are used for convolution with MaskedImages and (eventually) Images

Kernel is a virtual base class; it cannot be instantiated. The following notes apply to Kernel and to its subclasses.

The template type should usually be float or double; integer kernels should be used with caution because they do not normalize well.

The center pixel of a Kernel is at index: (width-1)/2, (height-1)/2. Thus it is centered along columns/rows if the kernel has an odd number of columns/rows and shifted 1/2 pixel towards 0 otherwise. A kernel should have an odd number of columns and rows unless it is intended to shift an image.

Spatially Varying Kernels

Kernels may optionally vary spatially (so long as they have any kernel parameters). To make a spatially varying kernel, specify a spatial function at construction (you cannot change your mind once the kernel is constructed). You must also specify a set of spatial parameters, and you may do this at construction and/or later by calling setSpatialParameters. The spatial parameters are a vector (one per kernel function parameter) of spatial function parameters. In other words the spatial parameters are a vector of vectors indexed as [kernel parameter][spatial parameter]. The one spatial function is used to compute the kernel parameters at a given spatial position by computing each kernel parameter using its associated vector of spatial function parameters.

The convolve function computes the spatial function at the pixel position (not index) of the image. See the convolve function for details.

Note that if a kernel is spatially varying then you may not set the kernel parameters directly; that is the job of the spatial function! However, you may change the spatial parameters at any time.

Design Notes

The basic design is to use the same kernel class for both spatially varying and spatially invariant kernels. The user either does or does not supply a function describing the spatial variation at creation time. In addition, analytic kernels are described by a user-supplied function of the same basic type as the spatial variation function.

Several other designs were considered, including: A) Use different classes for spatially varying and spatially invariant versions of each kernel. Thus instead of three basic kernel classes (FixedKernel, AnalyticKernel and LinearCombinationKernel) we would have five (since FixedKernel cannot be spatially varying). Robert Lupton argued that was a needless expansion of the class hiearchy and I agreed. B) Construct analytic kernels by defining a subclass of AnalyticKernel that is specific to the desired functional (e.g. GaussianAnalyticKernel). If spatial models are handled the same way then this creates a serious proliferation of kernel classes (even if we only have two different spatial models, e.g. polynomial and Chebyshev polynomial). I felt it made more sense to define the spatial model by some kind of function class (often called a “functor”), and since we needed such a class, I chose to use it for the analytic kernel as well.

However, having a separate function class does introduce some potential inefficiencies. If a function is part of the class it can potentially be evaluated more quickly than calling a function for each pixel or spatial position.

A possible variant on the current design is to define the spatial model and analytic kernel by specifying the functions as template parameters. This has the potential to regain some efficiency in evaluating the functions. However, it would be difficult or impossible to pre-instantiate the desired template classes, a requirement of the LSST coding standards.

Subclassed by lsst::afw::math::AnalyticKernel, lsst::afw::math::DeltaFunctionKernel, lsst::afw::math::FixedKernel, lsst::afw::math::LinearCombinationKernel, lsst::afw::math::SeparableKernel

template<typename KernelT>
struct kernel_traits

#include <traits.h>

template trait class with information about Kernels

template<typename ReturnT>
class LanczosFunction1 : public lsst::afw::math::Function1<ReturnT>

#include <FunctionLibrary.h>

1-dimensional Lanczos function

f(x) = sinc(pi x’) sinc(pi x’ / n) where x’ = x - xOffset and coefficient c0 = xOffset

Warning: the Lanczos function is sometimes forced to 0 if |x’| > n but this implementation does not perform that truncation so as to improve Lanczos kernels.

template<typename ReturnT>
class LanczosFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <FunctionLibrary.h>

2-dimensional separable Lanczos function

f(x, y) = sinc(pi x’) sinc(pi x’ / n) sinc(pi y’) sinc(pi y’ / n) where x’ = x - xOffset and y’ = y - yOffset and coefficients c0 = xOffset, c1 = yOffset

Warning

the Lanczos function is sometimes forced to 0 if |x’| > n or |y’| > n but this implementation does not perform that truncation so as to improve Lanczos kernels.

class LanczosWarpingKernel : public lsst::afw::math::SeparableKernel

#include <warpExposure.h>

Lanczos warping: accurate but slow and can introduce ringing artifacts.

This kernel is the product of two 1-dimensional Lanczos functions. The number of minima and maxima in the 1-dimensional Lanczos function is 2*order + 1. The kernel has one pixel per function minimum or maximum; but as applied to warping, the first or last pixel is always zero and can be omitted. Thus the kernel size is 2*order x 2*order.

For more information about warping kernels see makeWarpingKernel

class LeastSquares

#include <LeastSquares.h>

Solver for linear least-squares problems.

Linear least-squares problems are defined as finding the vector \(x\) that minimizes \(\left|A x - b\right|_2\), with the number of rows of \(A\) generally greater than the number of columns. We call \(A\) the design matrix, \(b\) the data vector, and \(x\) the solution vector. When the rank of \(A\) is equal to the number of columns, we can obtain using the solution using the normal equations:

\[ A^T A x = A^T b \]

If \(A\) is not full-rank, the problem is underconstrained, and we usually wish to solve the minimum-norm least-squares problem, which also minimizes \(|x|_2\). This can be done by computing a pseudo-inverse of \(A\) using an SVD or complete orthogonal factorization of \(A\), or by performing an Eigen decomposition of \(A^T A\).

This class can be constructed from the design matrix and data vector, or from the two terms in the normal equations (below, we call the matrix \(A^TA\) the Fisher matrix, and the vector \(A^T b\) simply the “right-hand side” (RHS) vector). If initialized with the design matrix and data vector, we can still use the normal equations to solve it. The solution via the normal equations is more susceptible to round-off error, but it is also faster, and if the normal equation terms can be computed directly it can be significantly less expensive in terms of memory. The Fisher matrix is a symmetric matrix, and it should be exactly symmetric when provided as input, because which triangle will be used is an implementation detail that is subject to change and may depend on the storage order.

The solver always operates in double precision, and returns all results in double precision. However, it can be initialized from single precision inputs. It isn’t usually a good idea to construct the normal equations in single precision, however, even when the data are single precision.

class LinearCombinationKernel : public lsst::afw::table::io::PersistableFacade<LinearCombinationKernel>, public lsst::afw::math::Kernel

#include <Kernel.h>

A kernel that is a linear combination of fixed basis kernels.

Convolution may be performed by first convolving the image with each fixed kernel, then adding the resulting images using the (possibly spatially varying) kernel coefficients.

The basis kernels are cloned (deep copied) so you may safely modify your own copies.

Warnings:

• This class does not normalize the individual basis kernels; they are used “as is”.

template<typename ValueT>
class MaskImposter

#include <Statistics.h>

A Mask wrapper to provide an infinite_iterator for Mask::row_begin(). This allows a fake Mask to be passed in to Statistics with a regular (non-masked) Image.

class NearestWarpingKernel : public lsst::afw::math::SeparableKernel

#include <warpExposure.h>

Nearest neighbor warping: fast; good for undersampled data.

The kernel size is 2 x 2.

For more information about warping kernels see makeWarpingKernel

template<typename T>
class NeuralNetCovariogram : public lsst::afw::math::Covariogram<T>

#include <GaussianProcess.h>

a Covariogram that recreates a neural network with one hidden layer and infinite units in that layer

Contains two hyper parameters (_sigma0 and _sigma1) that characterize the expected variance of the function being interpolated

see Rasmussen and Williams (2006) http://www.gaussianprocess.org/gpml/ equation 4.29

template<typename ReturnT>
class NullFunction1 : public lsst::afw::math::Function1<ReturnT>

#include <Function.h>

a class used in function calls to indicate that no Function1 is being provided

template<typename ReturnT>
class NullFunction2 : public lsst::afw::math::Function2<ReturnT>

#include <Function.h>

a class used in function calls to indicate that no Function2 is being provided

class PixelAreaBoundedField : public lsst::afw::math::BoundedField

#include <PixelAreaBoundedField.h>

A BoundedField that evaluate the pixel area of a SkyWcs in angular units.

Typically used to move an image or source flux between surface brightness and fluence.

template<typename ReturnT>
class PolynomialFunction1 : public lsst::afw::math::Function1<ReturnT>

#include <FunctionLibrary.h>

1-dimensional polynomial function.

f(x) = c0 + c1 x + c2 x^2 + … cn-1 x^(n-1)

template<typename ReturnT>
class PolynomialFunction2 : public lsst::afw::math::BasePolynomialFunction2<ReturnT>

#include <FunctionLibrary.h>

2-dimensional polynomial function with cross terms

f(x,y) = c0 (0th order)

• c1 x + c2 y (1st order)

• c3 x^2 + c4 x y + c5 y^2 (2nd order)

• c6 x^3 + c7 x^2 y + c8 x y^2 + c9 y^3 (3rd order)

• …

Intermediate products for the most recent y are cached, so when computing for a set of x, y it is more efficient to change x before you change y.

class ProductBoundedField : public lsst::afw::table::io::PersistableFacade<ProductBoundedField>, public lsst::afw::math::BoundedField

#include <ProductBoundedField.h>

A BoundedField that lazily multiplies a sequence of other BoundedFields.

class Random

#include <Random.h>

A class that can be used to generate sequences of random numbers according to a number of different algorithms. Support for generating random variates from the uniform, Gaussian, Poisson, and chi-squared distributions is provided.

This class is a thin wrapper for the random number generation facilities of GSL, which supports many additional distributions that can easily be added to this class as the need arises.

See

Random number generation in GSL

See

Random number distributions in GSL

class SeparableKernel : public lsst::afw::table::io::PersistableFacade<SeparableKernel>, public lsst::afw::math::Kernel

#include <Kernel.h>

A kernel described by a pair of functions: func(x, y) = colFunc(x) * rowFunc(y)

The function’s x, y arguments are as follows:

• -getCtr() for the lower left corner pixel

• 0, 0 for the center pixel

• (getDimensions() - 1) - getCtr() for the upper right pixel

Note: each pixel is set to the value of the kernel function at the center of the pixel (rather than averaging the function over the area of the pixel).

Subclassed by lsst::afw::math::BilinearWarpingKernel, lsst::afw::math::LanczosWarpingKernel, lsst::afw::math::NearestWarpingKernel

class SpatialCell

#include <SpatialCell.h>

Class to ensure constraints for spatial modeling

A given image is divided up into cells, with each cell represented by an instance of this class. Each cell itself contains a list of instances of classes derived from SpatialCellCandidate. One class member from each cell will be chosen to fit to a spatial model. In case of a poor fit, the next class instance in the list will be fit for. If all instances in a list are rejected from the spatial model, the best one will be used.

See

The SpatialCellSet example in the module documentation.

class SpatialCellCandidate

#include <SpatialCell.h>

Base class for candidate objects in a SpatialCell

Subclassed by lsst::afw::math::SpatialCellImageCandidate

class SpatialCellCandidateIterator

#include <SpatialCell.h>

An iterator that only returns usable members of the SpatialCell

class SpatialCellImageCandidate : public lsst::afw::math::SpatialCellCandidate

#include <SpatialCell.h>

Base class for candidate objects in a SpatialCell that are able to return an Image of some sort (e.g. a PSF or a DIA kernel)

Subclassed by lsst::ip::diffim::KernelCandidate< _PixelT >, lsst::meas::algorithms::PsfCandidate< PixelT >

class SpatialCellSet

#include <SpatialCell.h>

A collection of SpatialCells covering an entire image

template<typename T>
class SquaredExpCovariogram : public lsst::afw::math::Covariogram<T>

#include <GaussianProcess.h>

SquaredExpCovariogram

a Covariogram that falls off as the negative exponent of the square of the distance between the points

Contains one hyper parameter (_ellSquared) encoding the square of the characteristic length scale of the covariogram

class Statistics

#include <Statistics.h>

A class to evaluate image statistics

The basic strategy is to construct a Statistics object from an Image and a statement of what we want to know. The desired results can then be returned using Statistics methods. A StatisticsControl object is used to pass parameters. The statistics currently implemented are listed in the enum Properties in Statistics.h.

 // sets NumSigclip (3.0), and NumIter (3) for clipping
 lsst::afw::math::StatisticsControl sctrl(3.0, 3);

 sctrl.setNumSigmaClip(4.0);            // reset number of standard deviations for N-sigma clipping
 sctrl.setNumIter(5);                   // reset number of iterations for N-sigma clipping
 sctrl.setAndMask(0x1);                 // ignore pixels with these mask bits set
 sctrl.setNanSafe(true);                // check for NaNs & Infs, a bit slower (default=true)

 lsst::afw::math::Statistics statobj =
     lsst::afw::math::makeStatistics(*img, afwMath::NPOINT |
                                           afwMath::MEAN | afwMath::MEANCLIP, sctrl);
 double const n = statobj.getValue(lsst::afw::math::NPOINT);
 std::pair<double, double> const mean =
                                  statobj.getResult(lsst::afw::math::MEAN); // Returns (value, error)
 double const meanError = statobj.getError(lsst::afw::math::MEAN);                // just the error

Note

Factory function: We used a helper function, makeStatistics, rather that the constructor directly so that the compiler could deduce the types cf. std::make_pair()

Note

Inputs: The class Statistics is templated, and makeStatistics() can take either: (1) an image, (2) a maskedImage, or (3) a std::vector<> Overloaded makeStatistics() functions then wrap what they were passed in Image/Mask-like classes and call the Statistics constructor.

Note

Clipping: The clipping is done iteratively with numSigmaClip and numIter specified in the StatisticsControl object. The first clip (ie. the first iteration) is performed at: median +/- numSigmaClip*IQ_TO_STDEV*IQR, where IQ_TO_STDEV=~0.74 is the conversion factor between the IQR and sigma for a Gaussian distribution. All subsequent iterations perform clips at mean +/- numSigmaClip*stdev.

class StatisticsControl

#include <Statistics.h>

Pass parameters to a Statistics object

A class to pass parameters which control how the stats are calculated.

class TransformBoundedField : public lsst::afw::table::io::PersistableFacade<TransformBoundedField>, public lsst::afw::math::BoundedField

#include <TransformBoundedField.h>

A BoundedField based on geom::Transform<Poin2Endpoint, GenericEndpoint<1>>.

TransformBoundedField supports arbitrary transforms.

class WarpingControl

#include <warpExposure.h>

Parameters to control convolution

Note

padValue is not member of this class to avoid making this a templated class.

namespace detail

Functions

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

Low-level convolution function that does not set edge pixels.

convolvedImage must be the same size as inImage. convolvedImage has a border in which the output pixels are not set. This border has size:

• kernel.getCtrX() along the left edge

• kernel.getCtrY() along the bottom edge

• kernel.getWidth() - 1 - kernel.getCtrX() along the right edge

• kernel.getHeight() - 1 - kernel.getCtrY() along the top edge

Parameters

• [out] convolvedImage: convolved image

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

• lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

• lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

• std::bad_alloc: when allocation of CPU memory fails

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::DeltaFunctionKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving delta function kernels

Parameters

• [out] convolvedImage: convolved image

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::LinearCombinationKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving a LinearCombinationKernel

The Algorithm:

• If the kernel is spatially varying and contains only DeltaFunctionKernels then convolves the input Image by each basis kernel in turn, solves the spatial model for that component and adds in the appropriate amount of the convolved image.

• In all other cases uses normal convolution

Parameters

• [out] convolvedImage: convolved image

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

• lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

• lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

• std::bad_alloc: when allocation of CPU memory fails

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::SeparableKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving separable kernels

Parameters

• [out] convolvedImage: convolved image

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

template<typename OutImageT, typename InImageT>
void convolveWithBruteForce(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

Convolve an Image or MaskedImage with a Kernel by computing the kernel image at every point. (If the kernel is not spatially varying then only compute it once).

convolvedImage must be the same size as inImage. convolvedImage has a border in which the output pixels are not set. This border has size:

• kernel.getCtrX() along the left edge

• kernel.getCtrY() along the bottom edge

• kernel.getWidth() - 1 - kernel.getCtrX() along the right edge

• kernel.getHeight() - 1 - kernel.getCtrY() along the top edge

Warning

Low-level convolution function that does not set edge pixels.

Parameters

• [out] convolvedImage: convolved image

• [in] inImage: image to convolve

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

• lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

• lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

• std::bad_alloc: when allocation of CPU memory fails

template<typename OutImageT, typename InImageT>
void convolveWithInterpolation(OutImageT &outImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, ConvolutionControl const &convolutionControl)

Convolve an Image or MaskedImage with a spatially varying Kernel using linear interpolation.

This is a low-level convolution function that does not set edge pixels.

The algorithm is as follows:

• divide the image into regions whose size is no larger than maxInterpolationDistance

• for each region:

  • convolve it using convolveRegionWithInterpolation (which see)

Note that this routine will also work with spatially invariant kernels, but not efficiently.

Parameters

• [out] outImage: convolved image = inImage convolved with kernel

• [in] inImage: input image

• [in] kernel: convolution kernel

• [in] convolutionControl: convolution control parameters

Exceptions

• lsst::pex::exceptions::InvalidParameterError: if outImage is not the same size as inImage

template<typename OutImageT, typename InImageT>
void convolveRegionWithInterpolation(OutImageT &outImage, InImageT const &inImage, KernelImagesForRegion const &region, ConvolveWithInterpolationWorkingImages &workingImages)

Convolve a region of an Image or MaskedImage with a spatially varying Kernel using interpolation.

This is a low-level convolution function that does not set edge pixels.

Warning

: this is a low-level routine that performs no bounds checking.

Parameters

• [out] outImage: convolved image = inImage convolved with kernel

• [in] inImage: input image

• [in] region: kernel image region over which to convolve

• [in] workingImages: working kernel images

struct ConvolveWithInterpolationWorkingImages

#include <Convolve.h>

kernel images used by convolveRegionWithInterpolation

class KernelImagesForRegion

#include <Convolve.h>

A collection of Kernel images for special locations on a rectangular region of an image

See the Location enum for a list of those special locations.

This is a low-level helper class for recursive convolving with interpolation. Many of these objects may be created during a convolution, and many will share kernel images. It uses shared pointers to kernels and kernel images for increased speed and decreased memory usage (at the expense of safety). Note that null pointers are NOT acceptable for the constructors!

Warning

The kernel images along the top and right edges are computed one row or column past the bounding box. This allows abutting KernelImagesForRegion to share corner and edge kernel images, which is useful when dividing a KernelImagesForRegion into subregions.

Warning

The bounding box for the region applies to the parent image.

Also note that it uses lazy evaluation: images are computed when they are wanted.

class RowOfKernelImagesForRegion

#include <Convolve.h>

A row of KernelImagesForRegion

Intended for iterating over subregions of a KernelImagesForRegion using computeNextRow.

class Spline

Subclassed by lsst::afw::math::detail::SmoothedSpline, lsst::afw::math::detail::TautSpline

struct TrapezoidalPacker

#include <TrapezoidalPacker.h>

A helper class ChebyshevBoundedField, for mapping trapezoidal matrices to 1-d arrays.

This class is not Swigged, and should not be included by any other .h files (including lsst/afw/math/detail.h); it’s for internal use by ChebyshevBoundedField only, and it’s only in a header file instead of that .cc file only so it can be unit tested.

We characterize the matrices by their number of columns (nx) and rows (ny), and the number of complete rows minus one (m).

This splits up the matrix into a rectangular part, in which the number of columns is the same for each row, and a wide trapezoidal or triangular part, in which the number of columns decreases by one for each row.

Here are some examples of how this class handles different kinds of matrices:

A wide trapezoidal matrix with orderX=4, orderY=3: nx=5, ny=4, m=0

0 1 2 3 4 5 6 7 8 9 10 11 12 13

A tall trapezoidal matrix with orderX=2, orderY=4 nx=3, ny=5, m=2

0 1 2 3 4 5 6 7 8 9 10 11

A triangular matrix with orderX=3, orderY=3 nx=4, ny=5, m=0

0 1 2 3 4 5 6 7 8 9

A wide rectangular matrix with orderX=3, orderY=2 nx=4, ny=3, m=3

0 1 2 3 4 5 6 7 8 9 10 11

A tall rectangular matrix with orderX=2, orderY=3 nx=3, ny=4, m=4

0 1 2 3 4 5 6 7 8 9 10 11

template<typename DestImageT, typename SrcImageT>
class WarpAtOnePoint

#include <WarpAtOnePoint.h>

A functor that computes one warped pixel

namespace details

Functions

template<class T>
T norm(const T &x)

template<class T>
T real(const T &x)

template<class T>
T Epsilon()

template<class T>
T MinRep()

template<class T>
T rescale_error(T err, T const &resabs, T const &resasc)

template<class UF>
bool intGKPNA(UF const &func, IntRegion<typename UF::result_type> &reg, typename UF::result_type const epsabs, typename UF::result_type const epsrel, std::map<typename UF::result_type, typename UF::result_type> *fxmap = 0)

Non-adaptive integration of the function f over the region ‘reg’.

Note

The algorithm computes first a Gaussian quadrature value then successive Kronrod/Patterson extensions to this result. The functions terminates when the difference between successive approximations (rescaled according to rescale_error) is less than either epsabs or epsrel * I, where I is the latest estimate of the integral. The order of the Gauss/Kronron/Patterson scheme is determined by which file is included above. Currently schemes starting with order 1 and order 10 are calculated. There seems to be little practical difference in the integration times using the two schemes, so I haven’t bothered to calculate any more.

template<class UF>
void intGKP(UF const &func, IntRegion<typename UF::result_type> &reg, typename UF::result_type const epsabs, typename UF::result_type const epsrel, std::map<typename UF::result_type, typename UF::result_type> *fxmap = 0)

An adaptive integration algorithm which computes the integral of f over the region reg.

The area and estimated error are returned as reg.Area() and reg.Err() If desired, *retx and *retf return std::vectors of x,f(x) respectively They only include the evaluations in the non-adaptive pass, so they do not give an accurate estimate of the number of function evaluations.

Note

First the non-adaptive GKP algorithm is tried. If that is not accurate enough (according to the absolute and relative accuracies, epsabs and epsrel), the region is split in half, and each new region is integrated. The routine continues by successively splitting the subregion which gave the largest absolute error until the integral converges.

template<class UF>
AuxFunc1<UF> Aux1(UF uf)

Auxiliary function 1

template<class UF>
AuxFunc2<UF> Aux2(UF uf)

Auxiliary function 2

template<class BF, class Tp>
binder2_1<BF> bind21(const BF &oper, const Tp &x)

template<class TF, class Tp>
binder3_1<TF> bind31(const TF &oper, const Tp &x)

int gkp_n(int level)

template<class T>
const std::vector<T> &gkp_x(int level)

template<class T>
const std::vector<T> &gkp_wa(int level)

template<class T>
const std::vector<T> &gkp_wb(int level)

Variables

const int NGKPLEVELS = 5

template<class UF>
struct AuxFunc1 : public std::unary_function<UF::argument_type, UF::result_type>

#include <Integrate.h>

Auxiliary struct 1

template<class T>
struct ConstantReg1 : public std::unary_function<T, IntRegion<T>>

#include <Integrate.h>

Helpers for constant regions for int2d, int3d:

template<typename BinaryFunctionT>
class FunctionWrapper : public std::unary_function<BinaryFunctionT::second_argument_type, BinaryFunctionT::result_type>

#include <Integrate.h>

Wrap an integrand in a call to a 1D integrator: romberg()

When romberg2D() is called, it wraps the integrand it was given in a FunctionWrapper functor. This wrapper calls romberg() on the integrand to get a 1D (along the x-coord, for constant y) result . romberg2D() then calls romberg() with the FunctionWrapper functor as an integrand.

namespace table

Unnamed Group

typedef lsst::geom::Angle Angle

typedef lsst::geom::SpherePoint SpherePoint

Unnamed Group

template<typename RecordT, typename Catalog, typename T>
std::shared_ptr<RecordT> _Catalog_find(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T>
int _Catalog_lower_bound(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T>
int _Catalog_upper_bound(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T>
std::pair<int, int> _Catalog_equal_range(Catalog const &catalog, T const &value, Key<T> const &key)

Typedefs

typedef PointKey<int> Point2IKey

typedef PointKey<double> Point2DKey

using Box2IKey = BoxKey<lsst::geom::Box2I>

using Box2DKey = BoxKey<lsst::geom::Box2D>

typedef ColumnViewT<ExposureRecord> ExposureColumnView

typedef ExposureCatalogT<ExposureRecord> ExposureCatalog

typedef ExposureCatalogT<ExposureRecord const> ConstExposureCatalog

typedef CatalogT<BaseRecord> BaseCatalog

typedef CatalogT<BaseRecord const> ConstBaseCatalog

typedef ColumnViewT<SimpleRecord> SimpleColumnView

typedef SortedCatalogT<SimpleRecord> SimpleCatalog

typedef SortedCatalogT<SimpleRecord const> ConstSimpleCatalog

typedef SourceColumnViewT<SourceRecord> SourceColumnView

typedef SortedCatalogT<SourceRecord> SourceCatalog

typedef SortedCatalogT<SourceRecord const> ConstSourceCatalog

typedef ColumnViewT<AmpInfoRecord> AmpInfoColumnView

typedef CatalogT<AmpInfoRecord> AmpInfoCatalog

typedef CatalogT<AmpInfoRecord const> ConstAmpInfoCatalog

typedef Match<SimpleRecord, SimpleRecord> SimpleMatch

typedef Match<SimpleRecord, SourceRecord> ReferenceMatch

typedef Match<SourceRecord, SourceRecord> SourceMatch

typedef std::vector<SimpleMatch> SimpleMatchVector

typedef std::vector<ReferenceMatch> ReferenceMatchVector

typedef std::vector<SourceMatch> SourceMatchVector

typedef std::int64_t RecordId

Type used for unique IDs for records.

FITS isn’t fond of uint64, so we can save a lot of pain by using signed ints here unless we really need unsigned.

typedef lsst::afw::detection::Footprint Footprint

typedef boost::mpl::vector<RecordId, std::uint16_t, std::int32_t, float, double, lsst::geom::Angle, std::uint8_t> ScalarFieldTypes

An MPL vector of scalar field types.

typedef boost::mpl::vector<RecordId, std::uint16_t, std::int32_t, float, double, lsst::geom::Angle, std::uint8_t, Flag, std::string, Array<std::uint16_t>, Array<int>, Array<float>, Array<double>, Array<std::uint8_t>> FieldTypes

An MPL vector of all field types.

Enums

enum CoordinateType

Enum used to set units for geometric FunctorKeys.

Values:

PIXEL

CELESTIAL

enum SourceFitsFlags

Bitflags to be passed to SourceCatalog::readFits and SourceCatalog::writeFits

Note that these flags may also be passed when reading/writing SourceCatalogs via the Butler, by passing a “flags” key/value pair as part of the data ID.

Values:

SOURCE_IO_NO_FOOTPRINTS = 0x1

Do not read/write footprints at all.

SOURCE_IO_NO_HEAVY_FOOTPRINTS = 0x2

Read/write heavy footprints as non-heavy footprints.

Functions

SourceMatchVector matchXy(SourceCatalog const &cat1, SourceCatalog const &cat2, double radius, MatchControl const &mc = MatchControl())

Parameters

• cat1: first catalog

• cat2: second catalog

• radius: match radius (pixels)

• mc: how to do the matching (obeys MatchControl::findOnlyClosest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, in pixels, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchXy(cat1,radius). The match is performed in pixel space (2d cartesian).

SourceMatchVector matchXy(SourceCatalog const &cat, double radius, MatchControl const &mc = MatchControl())

Parameters

• cat: the catalog to self-match

• radius: match radius (pixels)

• mc: how to do the matching (obeys MatchControl::symmetricMatch)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, in pixels, is at most radius. The match is performed in pixel space (2d cartesian).

SourceMatchVector matchXy(SourceCatalog const &cat1, SourceCatalog const &cat2, double radius, bool closest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, in pixels, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchXy(cat1,radius). The match is performed in pixel space (2d cartesian).

Parameters

• [in] cat1: first catalog

• [in] cat2: second catalog

• [in] radius: match radius (pixels)

• [in] closest: if true then just return the closest match

SourceMatchVector matchXy(SourceCatalog const &cat, double radius, bool symmetric)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, in pixels, is at most radius. The match is performed in pixel space (2d cartesian).

Parameters

• [in] cat: the catalog to self-match

• [in] radius: match radius (pixels)

• [in] symmetric: if cat to true symmetric matches are produced: i.e. if (s1, s2, d) is reported, then so is (s2, s1, d).

template<typename Cat1, typename Cat2>
std::vector<Match<typename Cat1::Record, typename Cat2::Record>> matchRaDec(Cat1 const &cat1, Cat2 const &cat2, lsst::geom::Angle radius, MatchControl const &mc = MatchControl())

Parameters

• cat1: first catalog

• cat2: second catalog

• radius: match radius

• mc: how to do the matching (obeys MatchControl::findOnlyClosest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchRaDec(cat1,radius). The match is performed in ra, dec space.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

template<typename Cat>
std::vector<Match<typename Cat::Record, typename Cat::Record>> matchRaDec(Cat const &cat, lsst::geom::Angle radius, MatchControl const &mc = MatchControl())

Parameters

• cat: the catalog to self-match

• radius: match radius

• mc: how to do the matching (obeys MatchControl::symmetricMatch)

template<typename Cat1, typename Cat2>
std::vector<Match<typename Cat1::Record, typename Cat2::Record>> matchRaDec(Cat1 const &cat1, Cat2 const &cat2, lsst::geom::Angle radius, bool closest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchRaDec(cat1,radius). The match is performed in ra, dec space.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

Parameters

• [in] cat1: first catalog

• [in] cat2: second catalog

• [in] radius: match radius

• [in] closest: if true then just return the closest match

template<typename Cat>
std::vector<Match<typename Cat::Record, typename Cat::Record>> matchRaDec(Cat const &cat, lsst::geom::Angle radius, bool symmetric)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, is at most radius. The match is performed in ra, dec space.

This is instantiated for Simple and Source catalogs.

Parameters

• [in] cat: the catalog to self-match

• [in] radius: match radius

• [in] symmetric: if cat to true symmetric matches are produced: i.e. if (s1, s2, d) is reported, then so is (s2, s1, d).

template<typename Record1, typename Record2>
BaseCatalog packMatches(std::vector<Match<Record1, Record2>> const &matches)

Return a table representation of a MatchVector that can be used to persist it.

The schema of the returned object has “first” (RecordId), “second” (RecordID), and “distance” (double) fields.

Parameters

• [in] matches: A std::vector of Match objects to convert to table form.

template<typename Cat1, typename Cat2>
std::vector<Match<typename Cat1::Record, typename Cat2::Record>> unpackMatches(BaseCatalog const &matches, Cat1 const &cat1, Cat2 const &cat2)

Reconstruct a MatchVector from a BaseCatalog representation of the matches and a pair of catalogs.

If an ID cannot be found in the given tables, that pointer will be set to null in the returned match vector.

Note

The first and second catalog arguments must be sorted in ascending ID order on input; this will allow us to use binary search algorithms to find the records referred to by the match table.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

Parameters

• [in] matches: A normalized BaseCatalog representation, as produced by packMatches.

• [in] cat1: A CatalogT containing the records used on the ‘first’ side of the match, sorted by ascending ID.

• [in] cat2: A CatalogT containing the records used on the ‘second’ side of the match, sorted by ascending ID. May be the same as first.

template<typename ReferenceCollection>
void updateRefCentroids(geom::SkyWcs const &wcs, ReferenceCollection &refList)

Update centroids in a collection of reference objects

Template Parameters

• RefCollection: Type of sequence of reference objects, e.g. lsst::afw::table::SimpleCatalog or std::vector<std::shared_ptr<lsst::afw::table::SimpleRecord>>

Parameters

• [in] wcs: WCS to map from sky to pixels

• [inout] refList: Collection of reference objects. The schema must have three fields:

  • ”coord”: a field containing an ICRS lsst::afw::SpherePoint; this field is read

  • ”centroid”: a field containing lsst::geom::Point2D; this field is written

  • ”hasCentroid”: a flag; this field is written

Exceptions

• lsst::pex::exceptions::NotFoundError: if refList’s schema does not have the required fields.

template<typename SourceCollection>
void updateSourceCoords(geom::SkyWcs const &wcs, SourceCollection &sourceList)

Update sky coordinates in a collection of source objects

Template Parameters

• SourceCollection: Type of sequence of sources, e.g. lsst::afw::table::SourceCatalog or std::vector<std::shared_ptr<lsst::afw::table::SourceRecord>>

Parameters

• [in] wcs: WCS to map from pixels to sky

• [inout] sourceList: Collection of sources. The schema must have two fields:

  • ”slot_Centroid”: a field containing lsst::geom::Point2D; this field is read

  • ”coord”: a field containing an ICRS lsst::afw::SpherePoint; this field is written

Exceptions

• lsst::pex::exceptions::NotFoundError: if refList’s schema does not have the required fields.

class AliasMap

#include <AliasMap.h>

Mapping class that holds aliases for a Schema

Aliases need not be complete, but they must match to the beginning of a field name to be useful. For example, if “a_b_c” is a true field name, “x_->a_b” is a valid alias that will cause “x_y_c” to map to “a_b_c”, but “y_z->b_c” will not cause “a_y_z” to be matched.

Aliases are not checked to see if they match any existing fields, and if an alias has the same name as a field name, it will take precedence and hide the true field.

Unlike the other components of a Schema, aliases can be modified and removed, even after a Table has been constructed from the Schema.

AliasMaps are shared when Schemas are copy-constructed, but can be separated manually by calling Schema::disconnectAliases() or Schema::setAliasMap(). In addition, the AliasMap is deep-copied when used to construct a Table (or Catalog).

In order to allow Tables to react to changes in aliases (which may be used to define cached Keys held by the table, as in SourceTable’s “slots” mechanism), an AliasMap that is part of a Schema held by a Table will hold a pointer to that Table, and call BaseTable::handleAliasChanges() when its aliases are set or removed.

template<typename T>
class Array

#include <misc.h>

Tag types used to declare specialized field types.

See the documentation for specializations of FieldBase and KeyBase for more information.

template<typename T>
class ArrayKey : public lsst::afw::table::FunctorKey<ndarray::Array<T const, 1, 1>>, public lsst::afw::table::ReferenceFunctorKey<ndarray::ArrayRef<T, 1, 1>>, public lsst::afw::table::ConstReferenceFunctorKey<ndarray::ArrayRef<T const, 1, 1>>

#include <arrays.h>

A FunctorKey used to get or set a ndarray::Array from a sequence of scalar Keys.

ArrayKey operates on the convention that arrays are defined by a set of contiguous scalar fields (i.e. added to the Schema in order, with no interruption) of the same type, with a common field name prefix and “_0”, “_1” etc. suffixes.

class BaseColumnView

#include <BaseColumnView.h>

Column-wise view into a sequence of records that have been allocated contiguously.

A BaseColumnView can be created from any iterator range that dereferences to records, as long as those records’ field data is contiguous in memory. In practice, that means they must have been created from the same table, and be in the same order they were created (with no deletions). It also requires that those records be allocated in the same block, which can be guaranteed with BaseTable::preallocate().

Geometric (point and shape) fields cannot be accessed through a BaseColumnView, but their scalar components can be.

BaseColumnView and its subclasses are always non-const views into a catalog, and so cannot be obtained from a catalog-of-const (trying this results in an exception, not a compilation error). As a result, all its accessors return arrays of non-const elements, even though they are themselves const member functions. This is no different from a shared_ptr<T>’s get() member function returning a non-const T*, even though get() is a const member function.

Subclassed by lsst::afw::table::ColumnViewT< RecordT >

class BaseRecord

#include <BaseRecord.h>

Base class for all records.

BaseRecord is a polymorphic base class that provides the core record interface: access to fields and links back to the table it is associated with. Field access is provided by the templated get, set, and operator[] member functions. As templates they are nonvirtual and cannot be overridden by subclasses. The implementations for these accessors is in the FieldBase template specializations.

Each subclass of BaseRecord should be paired with a subclass of BaseTable. All record creation goes through a table, as the table allocates the memory used to store a record’s fields and holds the Schema instance that defines those fields.

Records are noncopyable, and are hence usually passed by shared_ptr or [const-]reference.

Subclassed by lsst::afw::detection::PeakRecord, lsst::afw::table::ExposureRecord, lsst::afw::table::SimpleRecord

class BaseTable : public std::enable_shared_from_this<BaseTable>

#include <BaseTable.h>

Base class for all tables.

Tables have two largely distinct purposes:

• They serve as factories for records, allocating their field data in blocks.

• They carry additional information (such as the schema) that should be shared by multiple records.

It’s mostly a matter of convenience that we use the same class to serve both needs.

Tables do not actually maintain a list of all the records they have allocated - but those records hold a pointer back to the table. This allows the work of holding and iterating over records to be delegated to templated container classes (such as CatalogT) while allowing tables to be polymorphic, non-template classes. In some sense, then, it may make more sense to think of a table as a combination factory and “container header”.

Tables are always created in shared_ptrs (a requirement of enable_shared_from_this). BaseTable provides a make static member function to create a new table, and most derived table classes should do the same.

Each table class should be associated with a particular record class (1-to-1). Each table instance may be associated with many record instances.

Subclassed by lsst::afw::detection::PeakTable, lsst::afw::table::ExposureTable, lsst::afw::table::SimpleTable

class BitsColumn

#include <BaseColumnView.h>

A packed representation of a collection of Flag field columns.

The packing of bits here is not necessarily the same as the packing using in the actual table, as the latter may contain more than 64 bits spread across multiple integers.

A BitsColumn can only be constructed by calling BaseColumnView::getBits().

template<typename Box>
class BoxKey : public lsst::afw::table::FunctorKey<Box>

#include <aggregates.h>

A FunctorKey used to get or set a lsst::geom::Box2I or Box2D from a (min, max) pair of PointKeys.

The Box2IKey and Box2DKey typedefs should be preferred to using the template name directly.

template<typename BaseT>
class CatalogIterator : public boost::iterator_adaptor<CatalogIterator<BaseT>, BaseT, BaseT::value_type::element_type>

#include <Catalog.h>

Iterator class for CatalogT.

Iterators dereference to record references or const references, even though the CatalogT container is based on a vector of shared_ptr internally. This is usually very convenient (and is one of the reasons for having a custom container class in the first place).

Sometimes, however, we’d like to get a shared_ptr from an iterator (especially because records are noncopyable). With that in mind, CatalogIterator is implicitly convertible to the shared_ptr type it holds internally, and can also be assigned a shared_ptr to set the pointer in the underlying container. This conversion makes sense from the perspective that both iterators and smart pointers mimic the interface of pointers and provide the same interface to get at the underlying record.

template<typename RecordT>
class CatalogT

#include <Catalog.h>

A custom container class for records, based on std::vector.

CatalogT wraps a std::vector<std::shared_ptr<RecordT>> in an interface that looks more like a std::vector<RecordT>; its iterators and accessors return references or const references, rather than pointers, making them easier to use. It also holds a table, which is used to allocate new records and determine the schema, but no checking is done to ensure that records added to the catalog use the same table or indeed have the same schema.

Because a CatalogT is holds shared_ptrs internally, many of its operations can be either shallow or deep, with new deep copies allocated by the catalog’s table object. New records can be also be inserted by pointer (shallow) or by value (deep).

The constness of records is determined by the constness of the first template parameter to CatalogT; a container instance is always either const or non-const in that respect (like smart pointers). Also like smart pointers, const member functions (and by extension, const_iterators) do not allow the underlying pointers to be changed, while non-const member functions and iterators do.

CatalogT does not permit empty (null) pointers as elements. As a result, CatalogT has no resize member function.

CatalogT has a very different interface in Python; it mimics Python’s list instead of C++’s std::vector. It is also considerably simpler, because it doesn’t need to deal with iterator ranges or the distinction between references and shared_ptrs to records. See the Python docstring for more information.

Subclassed by lsst::afw::table::SortedCatalogT< RecordT >

class CentroidSlotDefinition : public lsst::afw::table::SlotDefinition

#include <slots.h>

SlotDefinition specialization for centroids.

template<typename RecordT>
class ColumnViewT : public lsst::afw::table::BaseColumnView

Subclassed by lsst::afw::table::SourceColumnViewT< RecordT >

template<typename T>
class ConstReferenceFunctorKey

#include <FunctorKey.h>

Base class for objects that can return a const reference to part of a record, but are not a true Key

Objects that inherit from ConstReferenceFunctorKey can be passed to BaseRecord::operator[], just as true Keys can, but the record will simply pass itself to ReferenceFunctorKey::getConstReference().

Note

We’d combine this with the ReferenceFunctorKey interface if it weren’t for the fact that we can’t pass multiple template arguments to a Swig macro if either contains commas, and we’d need that to wrap a combined interface base class.

class CoordKey : public lsst::afw::table::FunctorKey<lsst::geom::SpherePoint>

#include <aggregates.h>

A FunctorKey used to get or set celestial coordinates from a pair of lsst::geom::Angle keys.

Coords are always stored and returned in the ICRS system. Coords in other systems may be assigned, but this will result in a conversion to ICRS.

class EllipseKey : public lsst::afw::table::FunctorKey<lsst::afw::geom::ellipses::Ellipse>

#include <aggregates.h>

A FunctorKey used to get or set a geom::ellipses::Ellipse from an (xx,yy,xy,x,y) tuple of Keys.

template<typename RecordT>
class ExposureCatalogT : public lsst::afw::table::SortedCatalogT<RecordT>

#include <Exposure.h>

Custom catalog class for ExposureRecord/Table.

We don’t expect to subclass ExposureRecord/Table, so unlike other Catalogs we can (and do) define some ExposureCatalogT member functions in Exposure.cc where the explicit instantiation is done.

class ExposureRecord : public lsst::afw::table::BaseRecord

#include <Exposure.h>

Record class used to store exposure metadata.

class ExposureTable : public lsst::afw::table::BaseTable

#include <Exposure.h>

Table class used to store exposure metadata.

Record class used to store exposure metadata.

template<typename T>
struct Field : public lsst::afw::table::FieldBase<T>

#include <Field.h>

A description of a field in a table.

Field combines a type with the field name, documentation, units, and in some cases, the size of the field.

Specializations for different field types are inherited through FieldBase; see the documentation for those specializations for additional information about particular field types.

template<typename T>
struct FieldBase

#include <FieldBase.h>

Field base class default implementation (used for numeric scalars and lsst::geom::Angle).

Subclassed by lsst::afw::table::Key< afw::table::Array< Scalar > >, lsst::afw::table::Key< afw::table::Flag >, lsst::afw::table::Key< afw::table::RecordId >, lsst::afw::table::Key< CentroidElement >, lsst::afw::table::Key< double >, lsst::afw::table::Key< Element >, lsst::afw::table::Key< ErrElement >, lsst::afw::table::Key< float >, lsst::afw::table::Key< FluxErrElement >, lsst::afw::table::Key< int >, lsst::afw::table::Key< lsst::afw::table::Array< int > >, lsst::afw::table::Key< lsst::afw::table::Array< Scalar > >, lsst::afw::table::Key< lsst::geom::Angle >, lsst::afw::table::Key< Mag >, lsst::afw::table::Key< MagErrElement >, lsst::afw::table::Key< meas::base::Flux >, lsst::afw::table::Key< RecordId >, lsst::afw::table::Key< Scalar >, lsst::afw::table::Field< T >, lsst::afw::table::Key< T >

template<typename U>
struct FieldBase<Array<U>>

#include <FieldBase.h>

Field base class specialization for arrays.

The Array tag is used for both fixed-length (same size in every record, accessible via ColumnView) and variable-length arrays; variable-length arrays are initialized with a size of 0. Ideally, we’d use complete different tag classes for those two very different types, but boost::variant and boost::mpl put a limit of 20 on the number of field types, and we’re running out. In a future reimplementation of afw::table, we should fix this.

template<>
struct FieldBase<Flag>

#include <Flag.h>

Specialization for Flag fields.

Flag fields are handled specially in many places, because their keys have both an offset into an integer element and the bit in that element; while other fields have one or more elements per field, Flags have multiple fields per element. This means we can’t put all the custom code for Flag in FieldBase, and because Flags have an explicit Key specialization, we put the record access implementation in Key.

Subclassed by lsst::afw::table::Field< Flag >, lsst::afw::table::Key< Flag >

template<>
struct FieldBase<std::string>

#include <FieldBase.h>

Field base class specialization for strings.

Subclassed by lsst::afw::table::Key< std::string >

class FluxSlotDefinition : public lsst::afw::table::SlotDefinition

#include <slots.h>

SlotDefinition specialization for fluxes.

template<typename T>
class FunctorKey : public lsst::afw::table::OutputFunctorKey<T>, public lsst::afw::table::InputFunctorKey<T>

#include <FunctorKey.h>

Convenience base class that combines the OutputFunctorKey and InputFunctorKey

Most objects that can set a calculated or compound value from a record can also get that value back, so we provide this class to aggregate those interfaces.

class IdFactory

#include <IdFactory.h>

A polymorphic functor base class for generating record IDs for a table.

The IDs produced by an IdFactory need not be sequential, but they must be unique, both with respect to the IDs it generates itself and those passed to it via the notify() member function. Valid IDs must be nonzero, as zero is used to indicate null in some contexts.

template<typename T>
class InputFunctorKey

#include <FunctorKey.h>

Base class for objects that can set a value on a record, but are not a true Key themselves.

Objects that inherit from InputFunctorKey can be passed to BaseRecord::set(), just as true Keys can, but the record will simply pass itself to OutputFunctorKey::set() along with the value that was passed.

Subclassed by lsst::afw::table::FunctorKey< T >

template<typename T>
class Key : public lsst::afw::table::KeyBase<T>, public lsst::afw::table::FieldBase<T>

#include <Key.h>

A class used as a handle to a particular field in a table.

All access to table data ultimately goes through Key objects, which know (via an internal offset) how to address and cast the internal data buffer of a record or table.

Keys can be obtained from a Schema by name:

schema.find("myfield").key

and are also returned when a new field is added. Compound and array keys also provide accessors to retrieve scalar keys to their elements (see the documentation for the KeyBase specializations), even though these element keys do not correspond to a field that exists in any Schema. For example:

Schema schema;
Key< Array<float> > arrayKey = schema.addField< Array<float> >("array", "docs for array", 5);
Key< Point<int> > pointKey = schema.addField< Point<int> >("point", "docs for point");
Key<float> elementKey = arrayKey[3];
Key<int> xKey = pointKey.getX();
std::shared_ptr<BaseTable> table = BaseTable::make(schema);
std::shared_ptr<BaseRecord> record = table.makeRecord();
assert(&record[arrayKey][3] == &record[elementKey3]);
assert(record.get(pointKey).getX() == record[xKey]);

Key inherits from FieldBase to allow a key for a dynamically-sized field to know its size without needing to specialize Key itself or hold a full Field object.

template<>
class Key<Flag> : public lsst::afw::table::KeyBase<Flag>, public lsst::afw::table::FieldBase<Flag>

#include <Flag.h>

Key specialization for Flag.

Flag fields are special; their keys need to contain not only the offset to the integer element they share with other Flag fields, but also their position in that shared field.

Flag fields operate mostly like a bool field, but they do not support reference access, and internally they are packed into an integer shared by multiple fields so the marginal cost of each Flag field is only one bit.

template<typename T>
class KeyBase

#include <KeyBase.h>

A base class for Key that allows subfield keys to be extracted for some field types.

Subclassed by lsst::afw::table::Key< afw::table::Array< Scalar > >, lsst::afw::table::Key< afw::table::Flag >, lsst::afw::table::Key< afw::table::RecordId >, lsst::afw::table::Key< CentroidElement >, lsst::afw::table::Key< double >, lsst::afw::table::Key< Element >, lsst::afw::table::Key< ErrElement >, lsst::afw::table::Key< float >, lsst::afw::table::Key< FluxErrElement >, lsst::afw::table::Key< int >, lsst::afw::table::Key< lsst::afw::table::Array< int > >, lsst::afw::table::Key< lsst::afw::table::Array< Scalar > >, lsst::afw::table::Key< lsst::geom::Angle >, lsst::afw::table::Key< Mag >, lsst::afw::table::Key< MagErrElement >, lsst::afw::table::Key< meas::base::Flux >, lsst::afw::table::Key< RecordId >, lsst::afw::table::Key< Scalar >, lsst::afw::table::Key< std::string >, lsst::afw::table::Key< T >

template<typename U>
class KeyBase<Array<U>>

#include <KeyBase.h>

KeyBase specialization for Arrays.

template<>
class KeyBase<Flag>

#include <Flag.h>

A base class for Key that allows the underlying storage field to be extracted.

Subclassed by lsst::afw::table::Key< Flag >

template<typename Record1, typename Record2>
struct Match

#include <Match.h>

Lightweight representation of a geometric match between two records.

This is a template so it can hold derived record classes without a lot of casting and properly use lsst::geom::Angle for the distance when we do spherical coordinate matches.

class MatchControl

#include <Match.h>

Pass parameters to algorithms that match list of sources

template<typename T>
class OutputFunctorKey

#include <FunctorKey.h>

Base class for objects that can extract a value from a record, but are not a true Key themselves.

Objects that inherit from OutputFunctorKey can be passed to BaseRecord::get(), just as true Keys can, but the record will simply pass itself to OutputFunctorKey::get() and return the result.

Subclassed by lsst::afw::table::FunctorKey< T >

template<typename T>
class PointKey : public lsst::afw::table::FunctorKey<lsst::geom::Point<T, 2>>

#include <aggregates.h>

A FunctorKey used to get or set a lsst::geom::Point from an (x,y) pair of int or double Keys.

class QuadrupoleKey : public lsst::afw::table::FunctorKey<lsst::afw::geom::ellipses::Quadrupole>

#include <aggregates.h>

A FunctorKey used to get or set a geom::ellipses::Quadrupole from a tuple of constituent Keys.

template<typename T>
class ReferenceFunctorKey

#include <FunctorKey.h>

Base class for objects that can return a non-const reference to part of a record, but are not a true Key

Objects that inherit from ReferenceFunctorKey can be passed to BaseRecord::operator[], just as true Keys can, but the record will simply pass itself to ReferenceFunctorKey::getReference().

Note

We’d combine this with the ConstReferenceFunctorKey interface if it weren’t for the fact that we can’t pass multiple template arguments to a Swig macro if either contains commas, and we’d need that to wrap a combined interface base class.

class Schema

#include <Schema.h>

Defines the fields and offsets for a table.

Schema behaves like a container of SchemaItem objects, mapping a descriptive Field object with the Key object used to access record and ColumnView values. A Schema is the most important ingredient in creating a table.

Because offsets for fields are assigned when the field is added to the Schema, Schemas do not support removing fields, though they do allow renaming.

Field names in Schemas are expected to be underscore-separated names (e.g. ‘a_b_c’, but see afwTableFieldNames for the full conventions, including when to use underscores vs. CamelCase). The SubSchema class and Schema::operator[] provide a heirarchical interface to these names, but are implemented entirely as string splitting/joining operations that ultimately forward to member functions that operate on the fully-qualified field name, so there is no requirement that names be separated by underscores, and no performance advantage to using a SubSchema.

A SchemaMapper object can be used to define a relationship between two Schemas to be used when copying values from one table to another or loading/saving selected fields to disk.

Schema uses copy-on-write, and hence should always be held by value rather than smart pointer. When creating a Python interface, functions that return Schema by const reference should be converted to return by value (returnCopy) to ensure proper memory management and encapsulation.

template<typename T>
struct SchemaItem

#include <SchemaImpl.h>

A simple pair-like struct for mapping a Field (name and description) with a Key (used for actual data access).

class SchemaMapper

#include <SchemaMapper.h>

A mapping between the keys of two Schemas, used to copy data between them.

SchemaMapper is initialized with its input Schema, and contains member functions to add mapped or unmapped fields to the output Schema.

class ShapeSlotDefinition : public lsst::afw::table::SlotDefinition

#include <slots.h>

SlotDefinition specialization for shapes.

class SimpleRecord : public lsst::afw::table::BaseRecord

#include <Simple.h>

Record class that must contain a unique ID field and a celestial coordinate field.

SimpleTable / SimpleRecord are intended to be the base class for records representing astronomical objects. In additional to the minimal schema and the convenience accessors it allows, a SimpleTable may hold an IdFactory object that is used to assign unique IDs to new records.

Subclassed by lsst::afw::table::SourceRecord

class SimpleTable : public lsst::afw::table::BaseTable

#include <Simple.h>

Table class that must contain a unique ID field and a celestial coordinate field.

Record class that must contain a unique ID field and a celestial coordinate field.

SimpleTable / SimpleRecord are intended to be the base class for records representing astronomical objects. In additional to the minimal schema and the convenience accessors it allows, a SimpleTable may hold an IdFactory object that is used to assign unique IDs to new records.

Subclassed by lsst::afw::table::SourceTable

class SlotDefinition

#include <slots.h>

Base class for helper classes that define slots on SourceTable/SourceRecord.

Each type of slot corresponds to a subclass of SlotDefinition, and each actual slot corresponds to a particular field name prefix. For instance, to look up the centroid slot, we look for fields named “slot_Centroid_x” and “slot_Centroid_y”. Instead of actually naming a particular field that, however, we use Schema’s alias mechanism (see AliasMap) to make these field name lookups resolve to the name of other fields. The actual definition of the slots is thus managed by the Schema’s AliasMap, though a SourceTable object will cache Keys for the various slots to make sure accessing slot values is efficient (more precisely, when you set an alias related to a slot on an AliasMap, any table it corresponds to will receive a notification that it should update its Keys). These cached Keys are actually stored within the SlotDefinition (as data members of derived classes).

Note that the uncertainty and failure flag components of slots are not required; a slot may have only a measurement defined, or a measurement and either one of these (but not both). A slot may not have only an uncertainty and/or a a failure flag, however.

A SlotDefinition instance is not just an internal object used by SourceTable; it can also be used to inspect the slots via SourceTable::getXxxSlot(), which is now the preferred way to access the Keys that slots correspond to. SlotDefinition objects should only be constructed by SourceTable, however.

Subclassed by lsst::afw::table::CentroidSlotDefinition, lsst::afw::table::FluxSlotDefinition, lsst::afw::table::ShapeSlotDefinition

struct SlotSuite

#include <slots.h>

An aggregate containing all of the current slots used in SourceTable.

This is essentially for internal use by SourceTable only; it is defined here to keep the source code for the slot mechanism in one place as much as possible.

template<typename RecordT>
class SortedCatalogT : public lsst::afw::table::CatalogT<RecordT>

#include <SortedCatalog.h>

Custom catalog class for record/table subclasses that are guaranteed to have an ID, and should generally be sorted by that ID.

For a record/table pair to be used with SortedCatalogT, the table class must provide a static getIdKey() member function that returns the key to the ID field.

Subclassed by lsst::afw::table::ExposureCatalogT< RecordT >

class SourceRecord : public lsst::afw::table::SimpleRecord

#include <Source.h>

Record class that contains measurements made on a single exposure.

Sources provide four additions to SimpleRecord / SimpleRecord:

• Specific fields that must always be present, with specialized getters. The schema for a SourceTable should always be constructed by starting with the result of SourceTable::makeMinimalSchema.

• A shared_ptr to a Footprint for each record.

• A system of aliases (called slots) in which a SourceTable instance stores keys for particular measurements (a centroid, a shape, and a number of different fluxes) and SourceRecord uses this keys to provide custom getters and setters. These are not separate fields, but rather aliases that can point to custom fields. See the SlotDefinition hierarchy for more information.

class SourceTable : public lsst::afw::table::SimpleTable

#include <Source.h>

Table class that contains measurements made on a single exposure.

Record class that contains measurements made on a single exposure.

Sources provide four additions to SimpleRecord / SimpleRecord:

• Specific fields that must always be present, with specialized getters. The schema for a SourceTable should always be constructed by starting with the result of SourceTable::makeMinimalSchema.

• A shared_ptr to a Footprint for each record.

• A system of aliases (called slots) in which a SourceTable instance stores keys for particular measurements (a centroid, a shape, and a number of different fluxes) and SourceRecord uses this keys to provide custom getters and setters. These are not separate fields, but rather aliases that can point to custom fields. See the SlotDefinition hierarchy for more information.

class SubSchema

#include <Schema.h>

A proxy type for name lookups in a Schema.

Elements of schema names are assumed to be separated by underscores (“a_b_c”); an incomplete lookup is one that does not resolve to a field. Not that even complete lookups can have nested names; a Point field, for instance, has “x” and “y” nested names.

This proxy object is implicitly convertible to both the appropriate Key type and the appropriate Field type, if the name is a complete one, and supports additional find() operations for nested names.

SubSchema is implemented as a proxy that essentially calls Schema::find after concatenating strings. It does not provide any performance advantage over using Schema::find directly. It is also lazy, so looking up a name prefix that does not exist within the schema is not considered an error until the proxy is used.

Some examples:

Schema schema(false);
Key<int> a_i = schema.addField<int>("a_i", "integer field");
Key< Point<double> > a_p = schema.addField< Point<double> >("a_p", "point field");

assert(schema["a_i"] == a_i);
SubSchema a = schema["a"];
assert(a["i"] == a_i);
Field<int> f_a_i = schema["a_i"];
assert(f_a_i.getDoc() == "integer field");
assert(schema["a_i"] == "a_i");
assert(schema.find("a_p_x") == a_p.getX());

namespace detail

Functions

int indexCovariance(int i, int j)

Defines the ordering of packed covariance matrices.

This storage is equivalent to LAPACK ‘UPLO=U’.

int computeCovariancePackedSize(int size)

Defines the packed size of a covariance matrices.

struct FlagExtractor

#include <BaseColumnView.h>

Functor to compute a flag bit, used to create an ndarray expression template for flag columns.

struct RecordData

#include <BaseTable.h>

Helper struct that contains the information passed from BaseTable to BaseRecord at construction.

This can’t be a nested class of either of those two classes for dependency reasons, but it should nevertheless be considered opaque by all derived Table and Record classes.

class SchemaImpl

#include <SchemaImpl.h>

A private implementation class to hide the messy details of Schema.

This can’t be a real pimpl class, because some of the most important functionality is in the forEach function, a templated function we can’t explicitly instantiate in a source file. But putting all the details here draws a clear line between what users should look at (Schema) and what they shouldn’t (this).

Because Schema holds SchemaImpl by shared pointer, one SchemaImpl can be shared between multiple Schemas (and SubSchemas), which implement copy-on-write by creating a new SchemaImpl if the pointer they have isn’t unique when they are modified.

class SchemaMapperImpl

#include <SchemaMapperImpl.h>

A private implementation class to hide the messy details of SchemaMapper.

This class is very similar in spirit to SchemaImpl; look there for more information (though SchemaMapper is not copy-on-write).

namespace io

Functions

LSST_EXCEPTION_TYPE(PersistenceError, lsst::pex::exceptions::IoError, lsst::afw::table::io::PersistenceError)

An exception thrown when problems occur during persistence. An exception thrown when an InputArchive’s contents do not make sense.

This is the exception thrown by the LSST_ARCHIVE_ASSERT macro.

struct ArchiveIndexSchema

#include <ArchiveIndexSchema.h>

Schema for the index catalog that specifies where objects are stored in the data catalogs.

Each row in the index catalog corresponds to a combination of an object and a data catalog, and contains the range of rows used by that object in the catalog (in the ‘row0’ and ‘nrows’ fields). The ‘cat.archive’ field indicates which catalog in the archive the index entry refers to (where 0 is the index itself, and 1 is the first data catalog), and ‘cat.persistable’ refers to which catalog the index entry refers to from the perspective of the saved object.

An object may thus have more than one row in the index, but the ‘id’ and ‘name’ fields must be the same for all index entires that correspond to a single object. These contain, respectively, the unique ID returned by OutputArchive::put and the name returned by Persistable::getPersistenceName() and used by InputArchive to look up a PersistableFactory in the registry.

class CatalogVector : public std::vector<BaseCatalog>

#include <CatalogVector.h>

A vector of catalogs used by Persistable.

This should really be thought of as just a typedef, but we can’t forward-declare a typedef to a template class, so we use a trivial subclass instead. That may seem like a dirty hack, but it has a huge benefit in keeping compilation times down: it keeps us from needing to include Catalog.h in Persistable.h, which otherwise would pull all of the afw::table headers into the header of any class that wanted to make use of a Persistable subclass.

CatalogVector is also used in such limited circumstances that we don’t really have to worry about the fact that std::vector doesn’t have a virtual destructor and that we only have default and copy constructors for CatalogVector.

class FitsColumnReader

#include <FitsSchemaInputMapper.h>

Polymorphic reader interface used to read different kinds of objects from one or more FITS binary table columns.

class FitsReader

#include <FitsReader.h>

A utility class for reading FITS binary tables.

FitsReader itself provides the implementation for reading standard FITS binary tables (with a limited subset of FITS column types), but it also allows subclasses to be used instead, depending on what’s actually in the FITS file. If the FITS header has the key “AFW_TABLE” with a value other than “BASE”, FitsReader::apply consults a registry of subclasses to retreive one corresponding to that key. This means the type of records/tables loaded correctly depends on the file itself, rather than the caller. For instance, if you load a FITS table corresponding to a saved SourceCatalog using BaseCatalog::readFits, you’ll actually get a BaseCatalog whose record are actually SourceRecords and whose table is actually a SourceTable. On the other hand, if you try to load a non-Source FITS table into a SourceCatalog, you’ll get an exception when it tries to dynamic_cast the table to a SourceTable.

class FitsSchemaInputMapper

#include <FitsSchemaInputMapper.h>

A class that describes a mapping from a FITS binary table to an afw::table Schema.

A FitsSchemaInputMapper is created every time a FITS binary table is read into an afw::table catalog, allowing limited customization of the mapping between on-disk FITS table columns an in-memory fields by subclasses of BaseTable.

The object is constructed from a daf::base::PropertyList that represents the FITS header, which is used to populate a custom container of FitsSchemaItems. These can then be retrieved by name or column number via the find() methods, allowing the user to create custom readers for columns or groups of columns via addColumnReader(). They can also be removed from the “regular” fields via the erase() method. Those regular fields are filled in by the finalize() method, which automatically generates mappings for any FitsSchemaItems that have not been removed by calls to erase(). Once finalize() has been called, readRecord() may be called repeatedly to read FITS rows into record objects according to the mapping that has been defined.

struct FitsSchemaItem

#include <FitsSchemaInputMapper.h>

A structure that describes a field as a collection of related strings read from the FITS header.

class FitsWriter

#include <FitsWriter.h>

Writer object for FITS binary tables.

FitsWriter itself provides support for writing FITS binary tables from base containers. Derived record/base pairs should derive their own writer from FitsWriter and reimplement BaseTable::makeFitsWriter to return it. Subclasses will usually delegate most of the work back to FitsWriter.

class InputArchive

#include <InputArchive.h>

A multi-catalog archive object used to load table::io::Persistable objects.

An InputArchive can be constructed directly from the catalogs produced by OutputArchive, or more usefully, read from a multi-extension FITS file.

See

OutputArchive

class OutputArchive

#include <OutputArchive.h>

A multi-catalog archive object used to save table::io::Persistable objects.

OutputArchive should generally be used directly only by objects that do not themselves inherit from Persistable, but contain many objects that do (such as Exposure). It provides an interface for adding objects to the archive (put()), transforming them into catalogs that can be retrieved directly or written to a FITS file. The first catalog is an index that indicates which rows of the subsequent catalogs correspond to each object.

See getIndexCatalog() for a more detailed description of the index.

class OutputArchiveHandle

#include <OutputArchive.h>

An object passed to Persistable::write to allow it to persist itself.

OutputArchiveHandle provides an interface to add additional catalogs and save nested Persistables to the same archive.

class Persistable

#include <Persistable.h>

A base class for objects that can be persisted via afw::table::io Archive classes.

Inheriting from Persistable provides a public API for reading/writing individual objects to FITS that is fully defined in the base class, with derived classes only needing to implement persistence to catalogs. It is expected that objects that contain multiple persistables (such as Exposures) will create their own InputArchives and OutputArchives, and use these to avoid writing the same object twice (which would otherwise be a big concern for future objects like ExposureCatalog and CoaddPsf).

Generally speaking, an abstract base class that inherits from Persistable should also inherit from PersistableFacade<Base>. A concrete class that inherits (possibly indirectly) from Persistable should inherit from PersistableFacade<Derived> (though this just provides a slightly nicer interface to users), implement isPersistable(), getPersistenceName(), getPythonModule(), and write(), and define a subclass of PersistenceFactory. Inheritance from PersistableFacade should always precede inheritance from Persistable.

Persistable has no pure virtual member functions, and instead contains a default implementation that throws LogicError when the user attempts to save an object for which persistence has not actually been implemented.

Subclassed by lsst::afw::math::Function< Kernel::Pixel >, lsst::afw::cameraGeom::DetectorCollection, lsst::afw::cameraGeom::TransformMap, lsst::afw::detection::Footprint, lsst::afw::geom::Transform< FromEndpoint, ToEndpoint >, lsst::afw::math::BoundedField, lsst::afw::math::Function< ReturnT >, lsst::afw::math::Kernel, lsst::meas::modelfit::Mixture, lsst::afw::geom::Transform< afw::geom::Point2Endpoint, afw::geom::GenericEndpoint >

template<typename T>
class PersistableFacade

#include <Persistable.h>

A CRTP facade class for subclasses of Persistable.

Derived classes should generally inherit from PersistableFacade at all levels, but only inherit from Persistable via the base class of each hierarchy. For example, with Psfs:

class Psf: public PersistableFacade<Psf>, public Persistable { ... };
class DoubleGaussianPsf: public PersistableFacade<DoubleGaussianPsf>, public Psf { ... };

Inheriting from PersistableFacade is not required for any classes but the base of each hierarchy, but doing so can save users from having to do some dynamic_casts.

Note

PersistableFacade should usually be the first class in a list of base classes; if it appears after a base class that inherits from different specialization of PersistableFacade, those base class member functions will hide the desired ones.

class PersistableFactory

#include <Persistable.h>

A base class for factory classes used to reconstruct objects from records.

Classes that inherit from Persistable should also subclass PersistableFactory, and instantiate exactly one instance of the derived factory with static duration (usually the class and instance are both defined in an anonymous namespace in a source file).

Subclassed by lsst::meas::algorithms::KernelPsfFactory< T, K >

namespace python

Functions

template<typename T>
void declarePersistableFacade(pybind11::module &module, std::string const &suffix)

Wraps an instantiation of PersistableFacade.

Pybind11 shall assume that PersistableFacade is managed using std::shared_ptr, as this is required for compatibility with existing subclasses of PersistableFacade. This means that wrapping will only work if new classes also use std::shared_ptr as their holder type.

Template Parameters

• T: The type of object this PersistableFacade is for.

Parameters

• module: The pybind11 module that shall contain PersistableFacade<T>

• suffix: A string to disambiguate this class from other PersistableFacades. The Python name of this class shall be PersistableFacade<suffix>.

template<typename Class, typename ...Args>
void addPersistableMethods(pybind11::class_<Class, Args...> &cls)

Add table::io::Persistable and PersistableFacade methods to the pybind11 wrapper for a class

Use this instead of declarePersistableFacade to avoid circular import issues in Python; it allows your class to be used without importing lsst.afw.table.

Use as follows:

• When declaring the pybind11 class that wraps your Class do not list table::io::PersistableFacade<Class> and table::io::Persistable as subclasses.

• Call this function to wrap the methods that make your object persistable.

namespace python

Typedefs

using PyCatalog = pybind11::class_<CatalogT<Record>, std::shared_ptr<CatalogT<Record>>>

using PyColumnView = pybind11::class_<ColumnViewT<Record>, std::shared_ptr<ColumnViewT<Record>>, BaseColumnView>

using PySortedCatalog = pybind11::class_<SortedCatalogT<Record>, std::shared_ptr<SortedCatalogT<Record>>, CatalogT<Record>>

Functions

template<typename T, typename Record>
ndarray::Array<typename Field<T>::Value const, 1, 1> _getArrayFromCatalog(CatalogT<Record> const &catalog, Key<T> const &key)

Extract a column from a potentially non-contiguous Catalog.

Parameters

• catalog: Catalog

• key: Key to column to extract

template<typename Record>
ndarray::Array<double const, 1, 1> _getArrayFromCatalog(CatalogT<Record> const &catalog, Key<lsst::geom::Angle> const &key)

Parameters

• catalog: Catalog

• key: Key to column to extract

template<typename T, typename Record>
void declareCatalogOverloads(PyCatalog<Record> &cls)

Declare field-type-specific overloaded catalog member functions for one field type

Template Parameters

• T: Field type.

• Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

• [in] cls: Catalog pybind11 class.

template<typename Record>
PyCatalog<Record> declareCatalog(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Wrap an instantiation of lsst::afw::table::CatalogT<Record>.

In addition to calling this method you must call addCatalogMethods on the class object in Python.

Template Parameters

• Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

• [in] wrappers: Package manager class will be added to.

• [in] name: Name prefix of the record type, e.g. “Base” or “Simple”.

• [in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

template<typename Record>
PyColumnView<Record> declareColumnView(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Declare member and static functions for a given instantiation of lsst::afw::table::ColumnViewT<RecordT>.

Template Parameters

• Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

• [in] wrappers: Package manager class will be added to.

• [in] name: Name prefix of the record type, e.g. “Base” or “Simple”.

• [in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

template<typename Record>
PySortedCatalog<Record> declareSortedCatalog(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Wrap an instantiation of lsst::afw::table::SortedCatalogT<Record>.

In addition to calling this method (which also instantiates and wraps the CatalogT base class), you must call addCatalogMethods on the class object in Python.

Template Parameters

• Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

• [in] wrappers: Package manager class will be added to.

• [in] name: Name prefix of the record type, e.g. “Base” or “Simple”.

• [in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

namespace typehandling

Functions

template<typename V, typename K>
constexpr Key<K, V> makeKey(K const &id)

Factory function for Key, to enable type parameter inference.

Provides the same exception safety as the copy-constructor of

K.

Return

a key of the desired type

Parameters

• id: the key ID to create.

Calling this function prevents you from having to explicitly name the key type:

auto key = makeKey<int>("foo");

template<typename K, typename V>
std::ostream &operator<<(std::ostream &os, Key<K, V> const &key)

Output operator for Key.

The output will use C++ template notation for the key; for example, a key “foo” pointing to an int may print as "foo<int>".

Provides basic exception safety if the output operator of

K is exception-safe.

Return

a reference to os

Parameters

• os: the desired output stream

• key: the key to print

Warning

the type name is compiler-specific and may be mangled or unintuitive; for example, some compilers say “i” instead of “int”

void swap(PolymorphicValue &lhs, PolymorphicValue &rhs)

Swap specialization for PolymorphicValue.

std::string declareGenericMapRestrictions(std::string const &className, std::string const &keyName)

LSST_EXCEPTION_TYPE (UnsupportedOperationException, pex::exceptions::RuntimeError, lsst::afw::typehandling::UnsupportedOperationException) class Storable std::ostream& lsst::afw::typehandling::operator<<(std::ostream & os, Storable const & storable)

Exception thrown by Storable operations for unimplemented operations.

As with all RuntimeError, callers should assume that this exception may be thrown at any time. Interface supporting iteration over heterogenous containers.

Storable may be subclassed by either C++ or Python classes. Many operations defined by Storable are optional, and may throw UnsupportedOperationException if they are not defined.

Note

Any C++ subclass X of Storable that supports Python subclasses must have a pybind11 wrapper that uses StorableHelper<X> (or a subclass) and lsst::utils::python::PySharedPtr. Output operator for Storable.

Return

a reference to os

Parameters

• os: the desired output stream

• storable: the object to print

Exceptions

• UnsupportedOperationException: Thrown if storable does not have an implementation of Storable::toString.

template<typename K>
class GenericMap

#include <GenericMap.h>

Interface for a heterogeneous map.

Objects of type GenericMap cannot necessarily have keys added or removed, although mutable values can be modified as usual. In Python, a GenericMap behaves like a collections.abc.Mapping. See MutableGenericMap for a GenericMap that must allow insertions and deletions.

A

Key for the map is parameterized by both the key type K and a corresponding value type V. The map is indexed uniquely by a value of type K; no two entries in the map may have identical values of Key::getId().

Template Parameters

• K: the key type of the map.

All operations are sensitive to the value type of the key: a contains call requesting an integer labeled “value”, for example, will report no such integer if instead there is a string labeled “value”. For Python compatibility, a GenericMap does not store type information internally, instead relying on RTTI for type checking.

All subclasses must guarantee, as a class invariant, that every value in the map is implicitly nothrow-convertible to the type indicated by its key. For example, MutableGenericMap ensures this by appropriately templating all operations that create new key-value pairs.

A GenericMap may contain primitive types, strings, Storable, and shared pointers to Storable as values. It does not support unique pointers to Storable because such pointers are read destructively. For safety reasons, it may not contain references, C-style pointers, or arrays to any type. Due to implementation restrictions, const types (except pointers to const Storable) are not currently supported.

Subclassed by lsst::afw::typehandling::MutableGenericMap< K >

template<typename K, typename V>
class Key

#include <Key.h>

Key for type-safe lookup in a GenericMap.

Key objects are equality-comparable, hashable, sortable, or printable if and only if K is comparable, hashable, sortable, or printable, respectively. Key can be used in compile-time expressions if and only if K can (in particular, Key<std::string, V> cannot).

Template Parameters

• K: the logical type of the key (e.g., a string)

• V: the type of the value mapped to this key

template<typename K>
class MutableGenericMap : public lsst::afw::typehandling::GenericMap<K>

#include <GenericMap.h>

Interface for a GenericMap that allows element addition and removal.

In Python, a MutableGenericMap behaves like a collections.abc.MutableMapping.

Note

Unlike standard library maps, this class does not support operator[] or insert_or_assign. This is because these operations would have surprising behavior when dealing with keys of different types but the same Key::getId().

Subclassed by lsst::afw::typehandling::SimpleGenericMap< K >

class PolymorphicValue

#include <PolymorphicValue.h>

Container that passes Storable objects by value while preserving type.

This class is implicitly convertible to and from a reference to Storable, but behaves like a value: changing the internal Storable changes the object’s state, and copying the object creates a new Storable.

Note

While a PolymorphicValue is always initialized with a Storable, it may become empty if it is the source of a move-construction or move-assignment. Conversion of an empty value to Storable& throws.

template<typename K>
class SimpleGenericMap : public lsst::afw::typehandling::MutableGenericMap<K>

#include <SimpleGenericMap.h>

A GenericMap that allows insertion and deletion of arbitrary values.

In Python, a SimpleGenericMap behaves like a dict. In particular, it will iterate over keys in the order they were added.

Template Parameters

• K: the key type of the map. Must be hashable.

template<class Base = Storable>
class StorableHelper : public Base

#include <python.h>

“Trampoline” for Storable to let it be used as a base class in Python.

Subclasses of Storable that are wrapped in pybind11 should have a similar helper that subclasses StorableHelper<subclass>. This helper can be skipped if the subclass neither adds any virtual methods nor implements any abstract methods.

See

pybind11 documentation

Template Parameters

• Base: the exact (most specific) class being wrapped

namespace detail

Variables

template<typename, typename = void>
constexpr bool IS_SMART_PTR = false

namespace test

Functions

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestConstAt, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestAt, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestEquals, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestConstVisitor, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestModifyingVoidVisitor, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestModifyingReturningVisitor, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestMutableEquals, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestSize, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestMutableSize, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakContains, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestContains, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestKeys, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestKeyOrder, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestClearIdempotent, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestClear, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertInt, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakInsertInt, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertString, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestWeakInsertString, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertStorable, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInterleavedInserts, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestErase, GenericMapFactory)

BOOST_TEST_CASE_TEMPLATE_FUNCTION(TestInsertEraseInsert, GenericMapFactory)

template<class GenericMapFactory>
void addGenericMapTestCases(boost::unit_test::test_suite *const suite)

Create generic test cases for a specific GenericMap implementation.

Template Parameters

• GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

Parameters

• suite: the test suite to add the tests to.

template<class GenericMapFactory>
void addMutableGenericMapTestCases(boost::unit_test::test_suite *const suite)

Create generic test cases for a specific MutableGenericMap implementation.

The tests will include all those added by addGenericMapTestCases.

Template Parameters

• GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

Parameters

• suite: the test suite to add the tests to.

template<class GenericMapFactory>
void addGenericMapTestCases()

Create generic test cases for a specific GenericMap implementation.

The tests will be added to the master test suite.

Template Parameters

• GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

template<class GenericMapFactory>
void addMutableGenericMapTestCases()

Create generic test cases for a specific MutableGenericMap implementation.

The tests will be added to the master test suite. They will include all tests added by addGenericMapTestCases.

Template Parameters

• GenericMapFactory: a subclass of GenericFactory that creates the desired implementation. Must be default-constructible.

class GenericFactory

#include <test.h>

Abstract factory that creates GenericMap and MutableGenericMap instances as needed.