xlens.utils.image

Image utilities for working with LSST exposures and PSF models.

This module collects helper routines that are repeatedly used across xlens when generating or post-processing simulated images. The implementations originate from the LSST Science Pipelines, and the docstrings have been expanded here to clarify how they interact with the rest of xlens.

Attributes

badMaskDefault

Classes

LsstPsf

Adapter that exposes an LSST PSF model with an anacal interface.

Functions

`subpixel_shift`(→ numpy.typing.NDArray)	Shift an image by arbitrary subpixel offsets using Fourier methods.
`resize_array`(array[, target_shape])	Resize an image-like array to a square target shape.
`truncate_square`(→ None)	Zero out pixels outside a centred square support region.
`get_psf_array`(*, lsst_psf, lsst_bbox, npix[, dg, ...])	Compute an average PSF image over a regular grid.
`get_blocks`(*, lsst_psf, lsst_bbox, pixel_scale, npix, ...)
`get_blocks_cells`(*, cell_coadd, pixel_scale, npix)
`stack_psfs_cells`(*, cell_coadd, npix)
`combine_sim_exposures`(exposures, noises)	Combine simulated exposures using inverse-variance weights.
`rotate_noise_corr`(noise_corr)
`generate_pure_noise`(*, ny, nx, pixel_scale, seed, ...)
`estimate_noise_variance`(exposure[, mask_array])
`prepare_data`(*, band, exposure, seed[, noiseId, ...])	Collect metadata and auxiliary arrays for shear measurement tasks.

Module Contents

badMaskDefault = ['BAD', 'SAT', 'CR', 'NO_DATA', 'UNMASKEDNAN', 'CROSSTALK', 'INTRP', 'STREAK', 'VIGNETTED', 'CLIPPED'][source]

subpixel_shift(image: numpy.typing.NDArray, shift_x: float, shift_y: float) → numpy.typing.NDArray[source]

Shift an image by arbitrary subpixel offsets using Fourier methods.

Parameters:

image – Two-dimensional array containing the image that should be shifted.
shift_x – Desired shift in the x-direction, expressed in pixel units. The value can be any real number; positive values move the image towards larger x.
shift_y – Desired shift in the y-direction, expressed in pixel units. Positive values move the image towards larger y.

Returns:

The shifted image. The output has the same shape as the input and is guaranteed to be real-valued.

Return type:

numpy.ndarray

resize_array(array: numpy.typing.NDArray[Any], target_shape: tuple[int, int] = (64, 64))[source]

Resize an image-like array to a square target shape.

The function first crops the array symmetrically if it is larger than the requested output size and then applies zero-padding when the array is too small.

Parameters:

array – Input array to resize. The array is assumed to be two-dimensional.
target_shape – Tuple of (height, width) describing the requested output shape.

Returns:

The resized array.

Return type:

numpy.ndarray

class LsstPsf(psf, npix, lsst_bbox=None)[source]

Bases: anacal.psf.BasePsf

Adapter that exposes an LSST PSF model with an anacal interface.

psf[source]

shape[source]

draw(x, y)[source]: Evaluate the PSF image centered on the requested pixel position.

truncate_square(arr: numpy.typing.NDArray, rcut: int) → None[source]

Zero out pixels outside a centred square support region.

The function is primarily used when constructing PSF postage stamps. It enforces a compact support by setting all pixels farther than rcut from the stamp centre to zero while leaving the inner region untouched.

Parameters:

arr (numpy.ndarray) – Square, two-dimensional array to modify in place.
rcut (int) – Half-width of the square region that should be kept. The resulting mask spans 2 * rcut + 1 pixels in both directions.

Raises:

ValueError – If arr is not a square 2-D array or if rcut is too large for the provided array size.

get_psf_array(*, lsst_psf, lsst_bbox, npix: int, dg: int = 250, lsst_mask=None)[source]

Compute an average PSF image over a regular grid.

The function samples the provided LSST PSF model at a grid of points across the bounding box and averages the resulting images. Pixels that are flagged as INEXACT_PSF in the optional mask are excluded from the average, mimicking the behaviour in the LSST pipelines.

Parameters:

lsst_psf (lsst.meas.algorithms.Psf) – LSST PSF model.
lsst_bbox (lsst.geom.Box2I) – Bounding box defining the region to evaluate the PSF.
npix (int) – Target shape (npix, npix) to which each PSF will be resized.
dg (int, optional) – Grid spacing in pixels (default is 250).
lsst_mask (MaskX or None, optional) – LSST mask image. If provided, pixels with INEXACT_PSF will be skipped.

Returns:

out – Averaged PSF as a 2D array of shape (npix, npix).

Return type:

numpy.ndarray

get_blocks(*, lsst_psf, lsst_bbox, pixel_scale, npix, psf_array)[source]

get_blocks_cells(*, cell_coadd, pixel_scale, npix)[source]

stack_psfs_cells(*, cell_coadd, npix)[source]

combine_sim_exposures(exposures: Sequence, noises: Sequence[numpy.typing.NDArray])[source]: Combine simulated exposures using inverse-variance weights.

rotate_noise_corr(noise_corr)[source]

generate_pure_noise(*, ny: int, nx: int, pixel_scale: float, seed: int, band: str | None, noise_variance: float, noise_corr=None, noiseId: int = 0, rotId: int = 0)[source]

estimate_noise_variance(exposure, mask_array=None)[source]

prepare_data(*, band: str | None, exposure, seed: int, noiseId: int = 0, rotId: int = 0, npix: int = 32, noise_corr: numpy.typing.NDArray | None = None, do_noise_bias_correction: bool = True, badMaskPlanes: List[str] = badMaskDefault, skyMap=None, tract: int = 0, patch: int = 0, star_cat: numpy.typing.NDArray | None = None, psf_array: numpy.typing.NDArray | None = None, mask_array: numpy.typing.NDArray | None = None, noise_array: numpy.typing.NDArray | None = None, detection: astropy.table.Table | None = None, blocks: List | None = None, **kwargs)[source]

Collect metadata and auxiliary arrays for shear measurement tasks.

The routine orchestrates several helper utilities in this module to build a dictionary consumed by the analysis pipeline. It extracts PSF postage stamps, prepares the galaxy image data, and computes deterministic random seeds used when adding synthetic noise.

Parameters:

band (str) – Photometric band label used to tag the output dictionary.
exposure (lsst.afw.image.ExposureF) – LSST exposure containing the science image and its associated PSF and mask information.
seed (int) – Base seed that, together with noiseId and rotId, controls the stochastic components of the processing.
noiseId (int, optional) – Identifier for the noise realisation. Defaults to 0.
rotId (int, optional) – Identifier for the rotation realisation. Defaults to 0.
npix (int, optional) – Target size of the PSF postage stamp in pixels. Defaults to 32.
noise_corr (numpy.ndarray, optional) – Noise correlation function sampled on the same grid as the PSF stamp.
do_noise_bias_correction (bool, optional) – If True (default) include the per-block noise-bias correction arrays in the output payload.
badMaskPlanes (list of str, optional) – Collection of mask plane names that should be treated as invalid.
skyMap (optional) – Sky-map descriptor propagated to the output dictionary unchanged.
tract (int, optional) – Identifiers for the tract and patch associated with exposure.
patch (int, optional) – Identifiers for the tract and patch associated with exposure.
star_cat (numpy.ndarray, optional) – Catalogue of reference stars used for PSF modelling.
mask_array (numpy.ndarray, optional) – Pre-computed boolean mask array. If None the mask is built from exposure directly.
noise_array (numpy.ndarray, optional) – Pre-computed pure noise array. If None the mask is built from exposure directly.
detection (astropy.table.Table, optional) – Detection catalogue that provides initial estimates for source properties.
**kwargs – Additional keyword arguments propagated to downstream consumers.

Returns:

A dictionary containing harmonised image data, PSF information, and metadata ready for the anacal measurement pipeline.

Return type:

dict