Cutout writer fits

`cutana.cutout_writer_fits` ¶

FITS cutout writer module for Cutana - handles individual FITS file output.

This module provides static functions for: - Individual FITS file creation for each cutout - Proper WCS header preservation - Multi-extension FITS handling - File naming conventions and organization - Metadata embedding in FITS headers

`CutoutUnits(unit, bunit, conserved_flux, flux_approximate)` `dataclass` ¶

Pixel-unit description of a cutout, derived from the processing config.

Attributes:

Name	Type	Description
`unit`	`str`	Value of the deprecated descriptive `UNIT` primary-header keyword.
`bunit`	`Optional[str]`	Value of the standard `BUNIT` image-HDU keyword, or `None` when the unit is dimensionless or not known to the writer.
`conserved_flux`	`bool`	Whether flux-conserving resizing was used.
`flux_approximate`	`bool`	Whether the values only approximate the stated unit. Written to `FLUXAPPX` only when `bunit` is set, since it qualifies `bunit`; it is always False for dimensionless (normalised) pixels, where approximation to a unit is meaningless.

`ensure_output_directory(path)` ¶

Ensure output directory exists.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Path to output directory	required

`generate_fits_filename(source_id, file_naming_template, modifier, metadata)` ¶

Generate FITS filename based on template and parameters.

Parameters:

Name	Type	Description	Default
`source_id`	`str`	Source identifier	required
`file_naming_template`	`str`	Template for filename generation	required
`modifier`	`str`	includes the tilestring for euclid	required
`metadata`	`Dict[str, Any]`	Metadata dictionary containing additional information	required

Returns:

Type	Description
`str`	Generated filename

`create_wcs_header(cutout_shape, original_wcs=None, ra_source=None, dec_source=None, pixel_scale=None, resize_factor=None, rescaled_offset_x=None, rescaled_offset_y=None, extraction_origin_x=None, extraction_origin_y=None, extraction_size=None)` ¶

Create a WCS header for a cutout.

When the parent-tile WCS is available, the cutout WCS reproduces the parent sky mapping exactly (the astropy.nddata.Cutout2D construction): CRVAL, CTYPE and the CD/PC orientation are inherited unchanged, and only CRPIX is shifted to the cutout's integer extraction origin (CD rescaled when the cutout was resized).

It deliberately does NOT re-tangent the projection at the source position. Setting CRVAL to the source RA/Dec and CRPIX to the geometric centre while keeping the tile's CD matrix rotates the cutout frame by the meridian convergence between the tile centre and the source, producing a WCS error that GROWS with distance from the cutout centre (order ~1" at a few-arcmin FOV for sources far from the tile centre).

The extraction origin and size are threaded in from cutout_extraction (via metadata) rather than recomputed here, so the (already-vectorised) world_to_pixel and window/clip/pad geometry is not duplicated.

Parameters:

Name	Type	Description	Default
`cutout_shape`	`tuple`	Shape of the final cutout (height, width).	required
`original_wcs`	`Optional[WCS]`	WCS of the parent tile.	`None`
`ra_source`	`Optional[float]`	Source RA in degrees. Used as CRVAL only in the no-parent-WCS fallback.	`None`
`dec_source`	`Optional[float]`	Source Dec in degrees (see `ra_source`).	`None`
`pixel_scale`	`Optional[float]`	Pixel scale in arcsec/pixel (fallback branch only).	`None`
`resize_factor`	`Optional[float]`	final_size / requested_size (fallback branch only).	`None`
`rescaled_offset_x`	`Optional[float]`	Sub-pixel X offset in final coords (fallback branch only).	`None`
`rescaled_offset_y`	`Optional[float]`	Sub-pixel Y offset in final coords (fallback branch only).	`None`
`extraction_origin_x`	`Optional[int]`	0-based integer parent-pixel X origin of cutout pixel 0, computed at extraction time (clip/centre-pad corrected). Required for the parent-WCS branch.	`None`
`extraction_origin_y`	`Optional[int]`	As `extraction_origin_x` for the Y axis.	`None`
`extraction_size`	`Optional[int]`	Pre-resize extraction window size in parent pixels (`int(requested * padding_factor)`). Required for the parent-WCS branch; the resize ratio is `final_size / extraction_size`.	`None`

Returns:

Type	Description
`Header`	FITS header with WCS information.

`resolve_cutout_units(config)` ¶

Derive the pixel-unit description of a cutout from the processing config.

The unit depends on normalisation as well as on flux handling: normalisation stretches pixels into the data_type range and therefore destroys the physical scale, so a normalised cutout is dimensionless no matter what the flux-conversion settings say. do_only_cutout_extraction bypasses normalisation entirely; otherwise the scale only survives the cases preserves_physical_scale allows.

Parameters:

Name	Type	Description	Default
`config`	`DotMap`	Processing configuration.	required

Returns:

Type	Description
`CutoutUnits`	The resolved :class:`CutoutUnits`.

Raises:

Type	Description
`AttributeError`	If a required configuration key is missing (DotMap attribute access on a non-dynamic config).

`write_single_fits_cutout(cutout_data, output_path, preserve_wcs=True, compression=None, overwrite=False)` ¶

Write a single cutout as individual FITS file.

Parameters:

Name	Type	Description	Default
`cutout_data`	`Dict[str, Any]`	Dictionary containing cutout data and metadata	required
`output_path`	`str`	Full path for output FITS file	required
`preserve_wcs`	`bool`	Whether to preserve WCS information	`True`
`compression`	`Optional[str]`	Optional compression method ('gzip', 'rice', etc.)	`None`
`overwrite`	`bool`	Whether to overwrite existing files	`False`

Returns:

Type	Description
`bool`	True if successful, False otherwise

Raises:

Type	Description
`KeyError`	If `cutout_data` is missing the mandatory unit metadata.

`write_fits_batch(batch_data, output_directory, config, file_naming_template=None, preserve_wcs=True, compression=None, create_subdirs=False, overwrite=False, modifier='')` ¶

Write a batch of cutouts as FITS files.

Parameters:

Name	Type	Description	Default
`batch_data`	`List[Dict[str, Any]]`	List of cutout data dictionaries	required
`output_directory`	`str`	Base output directory	required
`config`	`DotMap`	Configuration DotMap	required
`file_naming_template`	`str`	Template for filename generation	`None`
`preserve_wcs`	`bool`	Whether to preserve WCS information	`True`
`compression`	`Optional[str]`	Optional compression method	`None`
`create_subdirs`	`bool`	Whether to create subdirectories for organization	`False`
`overwrite`	`bool`	Whether to overwrite existing files	`False`
`modifier`	`str`	None	`''`

Returns:

Type	Description
`List[str]`	List of written file paths

Cutout writer fits

cutana.cutout_writer_fits ¶

CutoutUnits(unit, bunit, conserved_flux, flux_approximate) dataclass ¶

ensure_output_directory(path) ¶

generate_fits_filename(source_id, file_naming_template, modifier, metadata) ¶

create_wcs_header(cutout_shape, original_wcs=None, ra_source=None, dec_source=None, pixel_scale=None, resize_factor=None, rescaled_offset_x=None, rescaled_offset_y=None, extraction_origin_x=None, extraction_origin_y=None, extraction_size=None) ¶

resolve_cutout_units(config) ¶

write_single_fits_cutout(cutout_data, output_path, preserve_wcs=True, compression=None, overwrite=False) ¶

write_fits_batch(batch_data, output_directory, config, file_naming_template=None, preserve_wcs=True, compression=None, create_subdirs=False, overwrite=False, modifier='') ¶

`cutana.cutout_writer_fits` ¶

`CutoutUnits(unit, bunit, conserved_flux, flux_approximate)` `dataclass` ¶

`ensure_output_directory(path)` ¶

`generate_fits_filename(source_id, file_naming_template, modifier, metadata)` ¶

`create_wcs_header(cutout_shape, original_wcs=None, ra_source=None, dec_source=None, pixel_scale=None, resize_factor=None, rescaled_offset_x=None, rescaled_offset_y=None, extraction_origin_x=None, extraction_origin_y=None, extraction_size=None)` ¶

`resolve_cutout_units(config)` ¶

`write_single_fits_cutout(cutout_data, output_path, preserve_wcs=True, compression=None, overwrite=False)` ¶

`write_fits_batch(batch_data, output_directory, config, file_naming_template=None, preserve_wcs=True, compression=None, create_subdirs=False, overwrite=False, modifier='')` ¶