CameraGeom

Overview

The cameraGeom package describes the geometry of an imaging camera, including the location of each detector (e.g. CCD) on the focal plane, information about the amplifier subregions of each detector, and the location of known bad pixels in each detector. The cameraGeom package supports operations such as:

• Assemble images from raw data (combining amplifier subregions and trimming overscan). CameraGeom does not assemble an entire image (see ip_isr AssembleCcdTask for that) but includes functions in assembleImage that do much of the work.
• Transform 2-d points between various camera coordinate systems, using Camera.transform. This can be used as part of generating a WCS or to examine the effects of optical distortion.
• Create a graphic showing the layout of detectors on the focal plane, using utils.plotFocalPlane.
• Display a mosaic image that combines all detector images, using utils.showMosaic.

Data for constructing a Camera comes from the appropriate observatory-specific obs_ package. For example obs_lsstSim contains data for the LSST camera simulator, obs_sdss contains data for the SDSS imager, and obs_subaru contains data for both Suprime-Cam and Hyper Suprime-Cam (HSC).

Camera Geometry Utilities

There are a few utilities available for visualizing and debugging Camera objects. Examples of available utility methods are: display a particular amp, display an assembled sensor, display a the full camera modaic, plot the sensor boundaries with a grid of test points in FOCAL_PLANE coordinates. An example of how to use the utilities to visualize a camera is available in the obs_lsstSim package as $OBS_LSSTSIM_DIR/bin/displayCamera.py. Following is the help from displayCamera.py:

usage: displayCamera.py [-h] [--showAmp SHOWAMP [SHOWAMP ...]]
                        [--showCcd SHOWCCD [SHOWCCD ...]]
                        [--showRaft SHOWRAFT [SHOWRAFT ...]] [--showCamera]
                        [--cameraBinSize CAMERABINSIZE] [--plotFocalPlane]

Display the lsstSim camera

optional arguments:
  -h, --help            show this help message and exit
  --showAmp SHOWAMP [SHOWAMP ...]
                        Show an amplifier segment on an image display. May occur multiple
                        times. Format like R:Rx,Ry S:Sx,Sy A:Ax,Ay e.g. "R:2,2
                        S:1,1 A:0,0"
  --showCcd SHOWCCD [SHOWCCD ...]
                        Show a CCD from the mosaic on an image display. May occur multiple
                        times. Format like R:Rx,Ry S:Sx,Sy e.g. "R:2,2 S:1,1"
  --showRaft SHOWRAFT [SHOWRAFT ...]
                        Show a Raft from the mosaic on an image display. May occur multiple
                        times. Format like R:Rx,Ry e.g. "R:2,2"
  --showCamera          Show the camera mosaic an image display.
  --cameraBinSize CAMERABINSIZE
                        Size of binning when displaying the full camera mosaic
  --plotFocalPlane      Plot the focalplane in an interactive matplotlib
                        window

Camera Coordinate Systems

The cameraGeom package supports the following camera-based 2-dimensional coordinate systems, and it is possible to add others:

• FOCAL_PLANE: 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).
• FIELD_ANGLE: 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.
• PIXELS: 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.
• ACTUAL_PIXELS: like PIXELS, but takes into account pixel-level distortions (deviations from the nominal model of uniformly spaced rectangular pixels).
• TAN_PIXELS: is a variant of PIXELS with estimated optical distortion removed. TAN_PIXELS is an affine transformation from FIELD_ANGLE coordinates, where PIXELS and TAN_PIXELS match at the center of the pupil frame.

Basic Usage

The file examples/cameraGeomExample.py shows some basic usage of the cameraGeom package

#!/usr/bin/env python
import lsst.geom
import lsst.afw.cameraGeom.testUtils as testUtils
import lsst.afw.cameraGeom as cameraGeom

# Construct a mock LSST-like camera.
# Normally you would obtain a camera from a data butler using butler.get("camera")
# but when this example was written the software stack did not including a
# sample data repository.
camera = testUtils.CameraWrapper(isLsstLike=True).camera

# Get a detector from the camera by name (though you may specify an ID, if
# you prefer).
det = camera["R:1,0 S:1,1"]

# Convert a 2-d point from PIXELS to both FOCAL_PLANE and FIELD_ANGLE coordinates.
pixelPos = lsst.geom.Point2D(25, 43.2)
# position in focal plane in mm
focalPlanePos = det.transform(pixelPos, cameraGeom.PIXELS, cameraGeom.FOCAL_PLANE)
# position in as a field angle, in radians
fieldAnglePos = det.transform(pixelPos, cameraGeom.PIXELS, cameraGeom.FIELD_ANGLE)

# Find all detectors that overlap a specific point (in this case find the
# detector we already have)
detList = camera.findDetectors(focalPlanePos, cameraGeom.FOCAL_PLANE)
assert len(detList) == 1
assert detList[0].getName() == det.getName()

Objects

The cameraGeom package contains the following important objects; unless otherwise noted, all are available in both C++ and Python:

Camera

Camera is a collection of Detectors.

Camera also supports coordinate transformation between all camera coordinate systems.

Detector

Detector contains information about a given imaging detector (typically a CCD), including its position and orientation in the focal plane and information about amplifiers (such as the image region, overscan and readout corner). Amplifier data is stored as records in an amp info table, and Detector acts as a collection of amp info records.

Detector also supports transformation between focal plane, pixels, and (if a suitable transform has been provided) actual pixels coordinates. However Detector does not support FIELD_ANGLE coordinates; use a Camera for that.

CameraSys and CameraSysPrefix

CameraSys represents a camera coordinate system. It contains a coordinate system name and a detector name. The detector name is blank for non-detector-based camera coordinate systems such as FOCAL_PLANE and FIELD_ANGLE, but must always name a specific detector for detector-based coordinate systems.

CameraSysPrefix is a specialized variant of CameraSys that represents a detector-based coordinate system when the detector is not specified. CameraSysPrefix contains a coordinate system name but no detector name.

A constant is provided each camera coordinate system:

• FOCAL_PLANE (a CoordSys) for the FOCAL_PLANE system
• FIELD_ANGLE (a CoordSys) for the FIELD_ANGLE system
• PIXELS (a CoordSysPrefix) for the PIXELS system
• ACTUAL_PIXELS (a CoordSysPrefix) for the ACTUAL_PIXELS system

All Detector methods that take a CameraSys also accept a CameraSysPrefix instead. For example to transform a list of points from PIXELS to FOCAL_PLANE system using a Detector:

focalPlanePoints = Detector.transform(pixelPoints, PIXELS, FOCAL_PLANE)

Camera methods always require a CameraSys; a CameraSysPrefix is not acceptable because the camera does not know which detector to use. For example to transform a list of points from PIXELS on a specific detector to FIELD_ANGLE:

fieldAnglePoints = camera.transform(pixelPoints, detector.makeCameraSys(PIXELS), FIELD_ANGLE)

TransformMap

TransformMap is a collection of Transforms from one camera coordinate system to another.

Camera and Detector both contain TransformMaps. The transform map in Camera does not support detector-based coordinate systems (e.g. PIXELS), but Camera::getTransform and Camera::transform do support detector-based coordinate systems (since the camera contains information about the detectors).