ImageMapper

class lsst.ts.wep.ImageMapper(instConfig: Union[str, dict, Instrument] = 'policy:instruments/LsstCam.yaml', opticalModel: str = 'offAxis')

Bases: object

Class for mapping the pupil to the image plane, and vice versa.

This class also creates image masks.

Details mapping between the pupil and image planes are derived and discussed in https://sitcomtn-111.lsst.io

Parameters:

instConfigstr or dict or Instrument, optional

Instrument configuration. If a string, it is assumed this points to a config file, which is used to configure the Instrument. If the path begins with “policy:”, then it is assumed the path is relative to the policy directory. If a dictionary, it is assumed to hold keywords for configuration. If an Instrument object, that object is just used. (the default is “policy:instruments/LsstCam.yaml”)

opticalModelstr, optional

The optical model to use for mapping between the image and pupil planes. Can be “offAxis”, “onAxis”, or “paraxial”. offAxis is a numerical model that is valid for all optical systems, but requires an accurate Batoid model. onAxis is an analytic model that is valid for all optical systems near the optical axis. paraxial is an analytic model that is valid for slow optical systems near the optical axis. offAxis is recommended when you have a Batoid model and onAxis is recommended when you do not. paraxial is primarily meant for testing (the default is “offAxis”)

Attributes Summary

instrument	The instrument object that defines the optical geometry.
opticalModel	The name of the optical model to use for image mapping.

Methods Summary

centerOnProjection(image[, zkCoeff, binary, ...])	Center the stamp on a projection of the pupil.
createImageMasks(image[, zkCoeff, binary, ...])	Create source mask, blend mask, and background mask on image plane.
createPupilMasks(image, *[, binary, dilate, ...])	Create source mask, blend mask, and background mask on pupil plane.
getProjectionSize(fieldAngle, defocalType[, ...])	Return size of the pupil projected onto the image plane (in pixels).
mapImageToPupil(image[, zkCoeff, masks])	Map a stamp from the image to the pupil plane.
mapPupilToImage(image[, zkCoeff, masks])	Map the pupil to the image plane.

Attributes Documentation

instrument

The instrument object that defines the optical geometry.

opticalModel

The name of the optical model to use for image mapping.

Methods Documentation

centerOnProjection(image: Image, zkCoeff: Optional[ndarray] = None, binary: bool = True, rMax: float = 10, **maskKwargs) → Image

Center the stamp on a projection of the pupil.

In addition to the parameters listed below, you can provide any keyword argument for mask creation, and these will be passed for creating the masks for the projection.

Note this function also sets the masks for the image.

Parameters:

imageImage

A stamp object containing the metadata needed for the mapping.

zkCoeffnp.ndarray, optional

The wavefront at the pupil, represented as Zernike coefficients in meters, for Noll indices >= 4. (the default are the intrinsic Zernikes at the donut position)

binarybool, optional

If True, a binary mask is used to estimate the center of the image, otherwise a forward model of the image is used. The latter will likely result in a more accurate center, but takes longer to calculate. (the default is True)

rMaxfloat, optional

The maximum pixel distance the image can be shifted. (the default is 10)

createImageMasks(image: Image, zkCoeff: Optional[ndarray] = None, *, binary: bool = True, dilate: int = 0, dilateBlends: int = 0, maskBlends: bool = False, ignorePlane: bool = False, _invMap: Optional[tuple] = None) → None

Create source mask, blend mask, and background mask on image plane.

Note the masks are stored in image.mask, image.maskBlends, and image.maskBackground. The mask is 1 for source pixels and 0 for other pixels. The blend mask has 1 for blend pixels and 0 for other pixels. The background mas has 1 for background pixels and 0 for other pixels.

Parameters:

imageImage

A stamp object containing the metadata required for constructing the mask.

zkCoeffnp.ndarray, optional

The wavefront at the pupil, represented as Zernike coefficients in meters, for Noll indices >= 4. (the default are the intrinsic Zernikes at the donut position)

binarybool, optional

Whether to return a binary mask. If False, a fractional mask is returned instead. (the default is True)

dilateint, optional

How many times to dilate the central mask. This adds a boundary of that many pixels to the mask. Note this is not an option if binary==False. (the default is 0)

dilateBlendsint, optional

How many times to dilate the blended masks. Note this only matters if maskBlends==True, and is not an option if binary==False. (the default is 0)

maskBlendsbool, optional

Whether to subtract the blend mask from the source mask. (the default is False)

ignorePlanebool, optional

If False, check that image.planeType == PlaneType.Pupil. (the default is False)

Raises:

ValueError

The image is not on the image plane or the dilate values are invalid.

createPupilMasks(image: Image, *, binary: bool = True, dilate: int = 0, dilateBlends: int = 0, maskBlends: bool = False, ignorePlane: bool = False) → None

Create source mask, blend mask, and background mask on pupil plane.

Note the masks are stored in image.mask, image.maskBlends, and image.maskBackground. The mask is 1 for source pixels and 0 for other pixels. The blend mask has 1 for blend pixels and 0 for other pixels. The background mas has 1 for background pixels and 0 for other pixels.

Parameters:

imageImage

A stamp object containing the metadata required for constructing the mask.

binarybool, optional

Whether to return a binary mask. If False, a fractional mask is returned instead. (the default is True)

dilateint, optional

How many times to dilate the central mask. This adds a boundary of that many pixels to the mask. Note this is not an option if binary==False. (the default is 0)

dilateBlendsint, optional

How many times to dilate the blended masks. Note this only matters if maskBlends==True, and is not an option if binary==False. (the default is 0)

maskBlendsbool, optional

Whether to subtract the blend mask from the source mask. (the default is False)

ignorePlanebool, optional

If False, check that image.planeType == PlaneType.Pupil. (the default is False)

Raises:

ValueError

The image is not on the pupil plane or the dilate values are invalid.

getProjectionSize(fieldAngle: Union[ndarray, tuple, list], defocalType: Union[DefocalType, str], bandLabel: Union[BandLabel, str] = BandLabel.REF, zkCoeff: Optional[ndarray] = None) → int

Return size of the pupil projected onto the image plane (in pixels).

The returned number is the number of pixels per side needed to contain the image template in a square array.

Note this function returns a conservative estimate, as it does not account for vignetting.

Parameters:

fieldAnglenp.ndarray or tuple or list

The field angle in degrees.

defocalTypeDefocalType or str

Whether the image is intra- or extra-focal. Can be specified using a DefocalType Enum or the corresponding string.

bandLabelBandLabel or str

Photometric band for the exposure. Can be specified using a BandLabel Enum or the corresponding string. If None, BandLabel.REF is used. The empty string “” also maps to BandLabel.REF. (the default is BandLabel.REF)

zkCoeffnp.ndarray, optional

The wavefront at the pupil, represented as Zernike coefficients in meters, for Noll indices >= 4. (the default are the intrinsic Zernikes at the donut position)

Returns:

int

Number of pixels on a side needed to contain the pupil projection.

mapImageToPupil(image: Image, zkCoeff: Optional[ndarray] = None, masks: Optional[ndarray] = None, **maskKwargs) → Image

Map a stamp from the image to the pupil plane.

In addition to the parameters listed below, you can provide any keyword argument for mask creation, and these will be passed to self.createPupilMasks() when the image is masked. Note this only happens if masks=None.

Parameters:

imageImage

A stamp object containing the array to be mapped from the image to the pupil plane, plus the required metadata.

zkCoeffnp.ndarray, optional

The wavefront at the pupil, represented as Zernike coefficients in meters, for Noll indices >= 4. (the default are the intrinsic Zernikes at the donut position)

masksnp.ndarray, optional

You can provide the image masks if they have already been computed. This is just to speed up computation. If not provided, the masks are created after the mapping.

Returns:

Image

The stamp object mapped to the image plane.

mapPupilToImage(image: Image, zkCoeff: Optional[ndarray] = None, masks: Optional[Tuple[ndarray]] = None, **maskKwargs) → Image

Map the pupil to the image plane.

In addition to the parameters listed below, you can provide any keyword argument for mask creation, and these will be passed to self.createPupilMasks() when the image is masked. Note this only happens if masks=None.

Parameters:

imageImage

A stamp object containing the metadata needed for the mapping. It is assumed that mapping the pupil to the image plane is meant to model the image contained in this stamp.

zkCoeffnp.ndarray, optional

The wavefront at the pupil, represented as Zernike coefficients in meters, for Noll indices >= 4. (the default are the intrinsic Zernikes at the donut position)

masksnp.ndarray, optional

You can provide the image masks if they have already been computed. This is just to speed up computation. If not provided, the masks are created after the mapping.

Returns:

Image

The stamp object mapped to the image plane.