Skip to content

Cutout extraction

cutana.cutout_extraction

Vectorized cutout extraction utilities for Cutana.

This module provides optimized, vectorized functions for extracting multiple cutouts simultaneously from FITS files using batch processing of coordinates and bounds calculations.

get_pixel_scale_arcsec_per_pixel(wcs_obj)

Calculate pixel scale in arcseconds per pixel from WCS.

Parameters:

Name Type Description Default
wcs_obj WCS

WCS object for coordinate transformation

 required

Returns:

Type Description
float

Pixel scale in arcseconds per pixel

arcsec_to_pixels(diameter_arcsec, wcs_obj)

Convert diameter in arcseconds to pixels using WCS information.

Parameters:

Name Type Description Default
diameter_arcsec float

Diameter in arcseconds

 required
wcs_obj WCS

WCS object for pixel scale calculation

 required

Returns:

Type Description
int

Diameter in pixels (integer)

extract_cutouts_vectorized_from_extension(hdu, wcs_obj, ra_array, dec_array, size_pixels_array, source_ids=None, padding_factor=1.0, config=None)

Extract multiple cutouts from a single FITS extension using vectorized operations.

This function implements the vectorized approach: Step 1: Build source batch arrays (ra, dec, size_pixels) Step 2: Use vectorized SkyCoord for coordinate transformation Step 3: Vectorized bound computation Step 4: Broadcasted array operations for cutout extraction Step 5: Vectorized padding

Parameters:

Name Type Description Default
hdu ImageHDU

FITS ImageHDU object

 required
wcs_obj WCS

WCS object for this extension

 required
ra_array ndarray

Array of right ascensions in degrees

 required
dec_array ndarray

Array of declinations in degrees

 required
size_pixels_array ndarray

Array of cutout sizes in pixels

 required
source_ids List[str]

Optional list of source IDs for logging

 None
padding_factor float

Factor to scale the extraction area (1.0 = no padding)

 1.0

Returns:

Type Description
List[Optional[ndarray]]

Tuple of (cutout_list, success_mask, pixel_offset_x, pixel_offset_y,
ndarray

origin_x, origin_y) where:
ndarray
  • cutout_list: List of cutout arrays (or None for failures)
ndarray
  • success_mask: Boolean array indicating successful extractions
Tuple[List[Optional[ndarray]], ndarray, ndarray, ndarray]
  • pixel_offset_x: Array of sub-pixel X offsets (positive = target toward right)
Tuple[List[Optional[ndarray]], ndarray, ndarray, ndarray]
  • pixel_offset_y: Array of sub-pixel Y offsets (positive = target toward top)
Tuple[List[Optional[ndarray]], ndarray, ndarray, ndarray]
  • origin_x: Array of 0-based parent-pixel X origins of cutout pixel 0 (the clip- and centre-pad-corrected window start). Pre-resize cutout pixel p maps to parent pixel origin + p; the FITS writer uses this to build the cutout WCS without recomputing the (already-vectorised) extraction geometry.
Tuple[List[Optional[ndarray]], ndarray, ndarray, ndarray]
  • origin_y: As origin_x for the Y axis.

extract_cutouts_batch_vectorized(sources_batch, hdul, wcs_dict, fits_extensions=None, padding_factor=1.0, config=None)

Extract cutouts for a batch of sources using vectorized operations.

This function groups sources and processes them with vectorized coordinate transformations and batch cutout extraction.

Parameters:

Name Type Description Default
sources_batch List[Dict[str, Any]]

List of source dictionaries containing RA, Dec, size info

 required
hdul HDUList

Pre-loaded FITS HDUList

 required
wcs_dict Dict[str, WCS]

WCS dictionary for the FITS file

 required
fits_extensions List[str]

List of extension names to process

 None
padding_factor float

Factor to scale the extraction area (1.0 = no padding)

 1.0

Returns:

Type Description
Dict[str, Dict[str, ndarray]]

Tuple of (combined_cutouts, combined_wcs, source_ids, pixel_scale, combined_offsets) where:
Dict[str, Dict[str, WCS]]
  • combined_cutouts: Dict mapping source_id -> {ext_name: cutout_array}
List[str]
  • combined_wcs: Dict mapping source_id -> {ext_name: wcs_object}
float
  • source_ids: List of source IDs that were processed
Dict[str, Dict[str, float]]
  • pixel_scale: Pixel scale in arcseconds per pixel
Tuple[Dict[str, Dict[str, ndarray]], Dict[str, Dict[str, WCS]], List[str], float, Dict[str, Dict[str, float]]]
  • combined_offsets: Dict mapping source_id -> {"x": offset_x, "y": offset_y}