ImageMapper#

class lsst.ts.wep.ImageMapper(instConfig='policy:instruments/LsstCam.yaml', opticalModel='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:

instConfig (str 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”)
opticalModel (str, 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, ...])	Center the stamp on a projection of the pupil.
`createImageMasks`(image[, zkCoeff, ...])	Create source mask, blend mask, and background mask on image plane.
`createPupilMasks`(image, *[, isBinary, ...])	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, ...])	Map a stamp from the image to the pupil plane.
`mapPupilToImage`(image[, zkCoeff, ...])	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, zkCoeff=None, nollIndices=None, isBinary=True, rMax=10, **maskKwargs)#

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:

image (Image) – A stamp object containing the metadata needed for the mapping.
zkCoeff (np.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)
nollIndices (np.ndarray, optional) – These are the Noll indices corresponding to the coefficients in zkCoeff. If None, it is assumed zkCoeff contains coefficients for consecutive indices starting with Noll index 4. (the default is None)
isBinary (bool, 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)
rMax (float, optional) – The maximum pixel distance the image can be shifted. (the default is 10)
maskKwargs (Any)

Return type:

Image

createImageMasks(image, zkCoeff=None, nollIndices=None, *, isBinary=True, dilate=0, dilateBlends=0, autoDilateMaxIter=8, autoDilateFracChange=0.005, doMaskBlends=False, ignorePlane=False, _invMap=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:

image (Image) – A stamp object containing the metadata required for constructing the mask.
zkCoeff (np.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)
nollIndices (np.ndarray, optional) – These are the Noll indices corresponding to the coefficients in zkCoeff. If None, it is assumed zkCoeff contains coefficients for consecutive indices starting with Noll index 4. (the default is None)
isBinary (bool, optional) – Whether to return a binary mask. If False, a fractional mask is returned instead. (the default is True)
dilate (int, 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 isBinary is False. (the default is 0)
dilateBlends (int or str, optional) – How many times to dilate the blended masks. Can also be set to “auto” in which case an algorithm automatically attempts to infer the correct amount of dilation. (the default is 0)
autoDilateMaxIter (int, optional) – Maximum number of iterations in the dilateBlends auto-algorithm. (the default is 8)
autoDilateFracChange (float, optional) – In the dilateBlends auto-algorithm, this is the max fractional amount the median of the top 5% of brightest pixels can change between dilation iterations of the blend mask before auto dilation stops. (the default is 0.005.)
doMaskBlends (bool, optional) – Whether to subtract the blend mask from the source mask. (the default is False)
ignorePlane (bool, optional) – If False, check that image.planeType == PlaneType.Pupil. (the default is False)
_invMap (tuple | None, default: None)

Raises:

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

Return type:

None

createPupilMasks(image, *, isBinary=True, dilate=0, dilateBlends=0, autoDilateMaxIter=8, autoDilateFracChange=0.005, doMaskBlends=False, ignorePlane=False)#

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:

image (Image) – A stamp object containing the metadata required for constructing the mask.
isBinary (bool, optional) – Whether to return a binary mask. If False, a fractional mask is returned instead. (the default is True)
dilate (int, 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 isBinary is False. (the default is 0)
dilateBlends (int or str, optional) – How many times to dilate the blended masks. Can also be set to “auto” in which case an algorithm automatically attempts to infer the correct amount of dilation. (the default is 0)
autoDilateMaxIter (int, optional) – Maximum number of iterations in the dilateBlends auto-algorithm. (the default is 8)
autoDilateFracChange (float, optional) – In the dilateBlends auto-algorithm, this is the max fractional amount the median of the top 5% of brightest pixels can change between dilation iterations of the blend mask before auto dilation stops. (the default is 0.005.)
doMaskBlends (bool, optional) – Whether to subtract the blend mask from the source mask. (the default is False)
ignorePlane (bool, 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.

Return type:

None

getProjectionSize(fieldAngle, defocalType, bandLabel=BandLabel.REF, zkCoeff=None, nollIndices=None)#

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:

fieldAngle (np.ndarray or tuple or list) – The field angle in degrees.
defocalType (DefocalType or str) – Whether the image is intra- or extra-focal. Can be specified using a DefocalType Enum or the corresponding string.
bandLabel (BandLabel 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)
zkCoeff (np.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)
nollIndices (np.ndarray, optional) – These are the Noll indices corresponding to the coefficients in zkCoeff. If None, it is assumed zkCoeff contains coefficients for consecutive indices starting with Noll index 4. (the default is None)

Returns:

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

Return type:

int

mapImageToPupil(image, zkCoeff=None, nollIndices=None, masks=None, **maskKwargs)#

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:

image (Image) – A stamp object containing the array to be mapped from the image to the pupil plane, plus the required metadata.
zkCoeff (np.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)
nollIndices (np.ndarray, optional) – These are the Noll indices corresponding to the coefficients in zkCoeff. If None, it is assumed zkCoeff contains coefficients for consecutive indices starting with Noll index 4. (the default is None)
masks (np.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.
maskKwargs (Any)

Returns:

The stamp object mapped to the image plane.

Return type:

Image

mapPupilToImage(image, zkCoeff=None, nollIndices=None, masks=None, **maskKwargs)#

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:

image (Image) – 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.
zkCoeff (np.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)
nollIndices (np.ndarray, optional) – These are the Noll indices corresponding to the coefficients in zkCoeff. If None, it is assumed zkCoeff contains coefficients for consecutive indices starting with Noll index 4. (the default is None)
masks (np.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.
maskKwargs (Any)

Returns:

The stamp object mapped to the image plane.

Return type:

Image