stdpipe.cutouts module

Module for cropping the images and creating image cutouts / postage stamps

stdpipe.cutouts.crop_image_centered(data, x0, y0, r0, header=None)[source]

Crop a square region centered on a given pixel position.

Output size is 2*ceil(r0) + 1 pixels. The original center falls inside the pixel at x, y = ceil(r0), ceil(r0). If a FITS header is provided, it is adjusted so that the WCS solution remains valid for the cutout.

Parameters:
datandarray

2D image array to crop.

x0float

X coordinate of the center (0-based).

y0float

Y coordinate of the center (0-based).

r0float

Cutout half-size in pixels.

headerastropy.io.fits.Header, optional

FITS header to adjust (CRPIX shifted in-place on a copy).

Returns:
ndarray or tuple

Cropped image, or (cropped_image, adjusted_header) if header is provided.

stdpipe.cutouts.crop_image(data, x1, y1, width, height, header=None)[source]

Crop a rectangular region from an image.

Pixels outside the original image boundary are filled with zeros (or NaN for floating-point images). If a FITS header is provided, CRPIX is adjusted so that the WCS solution remains valid for the cutout.

Parameters:
datandarray

2D image array to crop.

x1int

Left edge of the crop region (0-based).

y1int

Bottom edge of the crop region (0-based).

widthint

Width of the crop region in pixels.

heightint

Height of the crop region in pixels.

headerastropy.io.fits.Header, optional

FITS header to adjust (copy is modified, original unchanged).

Returns:
ndarray or tuple

Cropped image, or (cropped_image, adjusted_header) if header is provided.

stdpipe.cutouts.get_cutout(image, candidate, radius, header=None, wcs=None, time=None, filename=None, name=None, **kwargs)[source]

Create a cutout postage stamp from one or more image planes.

The candidate may be a row from astropy.table.Table or a dict with at least x and y keys. The cutout is centered so the object falls inside the central pixel; size is 2*ceil(radius) + 1 pixels.

Parameters:
imagendarray

Primary (science) image plane.

candidatetable row or dict

Object record containing at least x and y pixel coordinates.

radiusfloat

Cutout half-size in pixels.

headerastropy.io.fits.Header, optional

Header of the original image. Copied and adjusted to represent the cutout WCS; stored as cutout['header'].

wcsastropy.wcs.WCS, optional

WCS of the original image. Adjusted and stored as cutout['wcs']. Takes precedence over header for WCS.

timeastropy.time.Time, datetime, or str, optional

Observation timestamp; stored in cutout['meta']['time'].

filenamestr, optional

Source image filename; stored in cutout['meta']['filename'].

namestr, optional

Object name; stored in cutout['meta']['name']. If omitted and candidate has ra / dec, a J2000 name is constructed.

**kwargs

Additional 2D arrays interpreted as extra image planes (e.g. mask, diff, template, convolved, err).

Returns:
dict

Cutout dictionary with at least:

  • image — primary image plane

  • mask, diff, template, etc. — extra planes if provided

  • header — adjusted FITS header, if provided

  • wcs — adjusted WCS, if provided

  • meta — dict with all candidate fields plus time, filename, and name

stdpipe.cutouts.write_cutout(cutout, filename)[source]

Store a cutout as a multi-extension FITS file.

Each image plane becomes a named FITS extension; metadata is stored as keywords in the primary header.

Parameters:
cutoutdict

Cutout structure as returned by get_cutout().

filenamestr

Output FITS filename.

stdpipe.cutouts.load_cutout(filename)[source]

Restore a cutout from a multi-extension FITS file.

Parameters:
filenamestr

Path to a FITS file written by write_cutout().

Returns:
dict

Cutout structure as returned by get_cutout().

stdpipe.cutouts.adjust_cutout(cutout, max_shift=2, max_scale=1.1, inner=None, normalize=False, fit_bg=False, verbose=False)[source]

Fit a positional and flux-scaling adjustment to minimize the image–template residual.

Optimizes a shift (dx, dy), scale, and optionally background levels to minimize the chi-squared residual between cutout['image'] and cutout['convolved']. On success, adds a cutout['adjusted'] plane with the optimized difference.

Parameters:
cutoutdict

Cutout structure as returned by get_cutout(). Must contain image, convolved, and err planes.

max_shiftfloat, optional

Maximum allowed positional shift in pixels (symmetric bound).

max_scalefloat, optional

Maximum allowed flux scale factor; scale is bounded to (1/max_scale, max_scale).

innerint, optional

If set, only the central inner × inner pixel box is used for optimization.

normalizebool, optional

If True, divide the adjusted plane by the err plane.

fit_bgbool, optional

If True, fit background levels as free parameters. If False, estimate backgrounds from the cutout using SExtractor-mode (2.5*median − 1.5*mean) and hold them fixed.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
bool

True if optimization succeeded, False otherwise.

Notes

On success the following keys are added to cutout['meta']: adjust_chi2_0, adjust_chi2, adjust_df, adjust_pval, adjust_dx, adjust_dy, adjust_scale, adjust_bg, adjust_tbg.

stdpipe.cutouts.downscale_image(image, scale=1, mode='sum', header=None)[source]

Downscale an image by an integer factor.

If the image dimensions are not divisible by scale, the image is cropped to the largest divisible size first. If a FITS header is provided, the WCS is adjusted for the downscaled pixel grid.

Parameters:
imagendarray

2D image array to downscale.

scaleint, optional

Integer downscaling factor.

modestr, optional

Pixel reduction mode: 'sum' (default), 'mean', 'and', or 'or'.

headerastropy.io.fits.Header, optional

If provided, the WCS is adjusted and a new header is returned alongside the downscaled image.

Returns:
ndarray or tuple

Downscaled image, or (downscaled_image, adjusted_header) if header is provided.