LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
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:

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.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:

Basic Usage

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

1 #!/usr/bin/env python2
2 import lsst.afw.cameraGeom.testUtils as testUtils
3 import lsst.afw.cameraGeom as cameraGeom
4 import lsst.afw.geom as afwGeom
5 
6 # Construct a mock LSST-like camera.
7 # Normally you would obtain a camera from a data butler using butler.get("camera")
8 # but when this example was written the software stack did not including a sample data repository.
9 camera = testUtils.CameraWrapper(isLsstLike=True).camera
10 
11 # Get a detector from the camera by name (though you may specify an ID, if you prefer).
12 det = camera["R:1,0 S:1,1"]
13 
14 # Convert a 2-d point from PIXELS to both FOCAL_PLANE and PUPIL coordinates.
15 detPoint = det.makeCameraPoint(afwGeom.Point2D(25, 43.2), cameraGeom.PIXELS) # position on detector in pixels
16 fpPoint = det.transform(detPoint, cameraGeom.FOCAL_PLANE) # position in focal plane in mm
17 pupilPoint = camera.transform(detPoint, cameraGeom.PUPIL) # position in pupil, in radians
18 
19 # Find all detectors that overlap a specific point (in this case find the detector we already have)
20 detList = camera.findDetectors(fpPoint)
21 assert len(detList) == 1
22 assert detList[0].getName() == det.getName()
23 
24 # Convert a point from PUPIL to PIXELS coordinates.
25 # For a detector-based coordinate system, such as PIXELS, may specify a particular detector
26 # or let the Camera find a detector:
27 # * To specify a particular detector, specify the target coordinate system as a CameraSys
28 # with the specified detectorName filled in (e.g. use detector.makeCameraSys).
29 # This is faster than finding a detector, and the resulting point is allowed to be off the detector.
30 # * To have the Camera find a detector, specify the target coordinate system as a CameraSysPrefix
31 # (e.g. cameraGeom.PIXELS). Camera will search for a detector that overlaps the point.
32 # If it finds exactly one detector then it will use that detector, and you can figure
33 # out which detector it used from the detector name in the returned CameraPoint.
34 # If it finds no detectors, or more than one detector, then it will raise an exception.
35 detPixelsSys = det.makeCameraSys(cameraGeom.PIXELS)
36 detPointOnSpecifiedDetector = camera.transform(pupilPoint, detPixelsSys)
37 detPointOnFoundDetector = camera.transform(pupilPoint, cameraGeom.PIXELS)
38 assert detPointOnFoundDetector.getCameraSys() == detPixelsSys # same detector

Objects

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

Camera (Python only)

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 transforms between focal plane, pixels, and actual pixels coordinates.

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 PUPIL, 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:

CameraSys and CameraSysPrefix are closely related and most methods that take one type are overloaded to also take the other. For example Camera.transform(fromCameraPoint, toSys) transforms a point from one coordinate system to another. ToSys may be either a CameraSys or a CameraSysPrefix, and this affects whether tranform will use the specified detector or search for a suitable detector. See the basic usage for for a concrete example.

CameraPoint

A class that holds a 2-dimensional location and its associated camera coordinate system:

The intent is to make transformation more robust and less confusing by keeping a 2-d point and its camera coordinate system together. This is appropriate for transforming small numbers of points, but does not scale well when transforming large numbers of points, so CameraTransformMap also supports a version of transform that takes and returns a vector of geom::Point2D.

CameraTransformMap

A registry of camera coordinate system transforms, keyed by CameraSys. Specifically CameraTransformMap is geom::TransformMap<CameraSys>. Each CameraTransformMap has a native (aka "reference") coordinate system, and each transform in CameraTransformMap is an geom::XYTransform that transforms a 2-d point from the native system to the key's coordinate system in the forward direction. CameraTransformMap.transform transforms a point between any two supported coordinate systems.

Camera and Detector both contain CameraTransformMaps.