ImageCutoutFactory

class lsst.dax.images.cutout.ImageCutoutFactory(butler: Butler, projection_finder: ProjectionFinder, output_root: str | ParseResult | ResourcePath | Path, temporary_root: str | ParseResult | ResourcePath | Path | None = None, logger: Logger | None = None)

Bases: object

High-level interface to the image cutout functionality.

Parameters

butlerButler

Butler that subimages are extracted from.

projection_finderProjectionObject

Object that obtains the WCS and bounding box for butler datasets of different types. May include caches.

output_rootconvertible to ResourcePath

Root of output file URIs.

temporary_rootconvertible to ResourcePath, optional

Local filesystem root to write files to before they are transferred to output_root (passed as the prefix argument to ResourcePath.temporary_uri).

loggerlogging.Logger, optional

Logger to use for timing messages. If None, a default logger will be used.

Methods Summary

extract_ref(stencil, ref[, cutout_mode])	Extract a subimage from a fully-resolved DatasetRef.
extract_search(stencil, dataset_type_name, ...)	Extract a subimage from a dataset identified by a (dataset type, data ID, collection path) tuple.
extract_uuid(stencil, uuid, *[, component, ...])	Extract a subimage from a dataset identified by its UUID.
process_ref(stencil, ref, *[, mask_plane, ...])	Extract and write a cutout from a fully-resolved DatasetRef.
process_search(stencil, dataset_type_name, ...)	Extract and write a cutout from a dataset identified by a (dataset type, data ID, collection path) tuple.
process_uuid(stencil, uuid, *[, component, ...])	Extract and write a cutout from a dataset identified by its UUID.
write_fits(extract_result)	Write a Extraction to a remote FITS file in output_root.

Methods Documentation

extract_ref(stencil: SkyStencil, ref: DatasetRef, cutout_mode: CutoutMode = CutoutMode.FULL_EXPOSURE) → Extraction

Extract a subimage from a fully-resolved DatasetRef.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

refDatasetRef

Fully-resolved reference to the dataset to obtain the cutout from. Must have DatasetRef.id not None (use extract_search instead when this is not the case). Need not have an expanded data ID. May represent an image-like dataset component.

Returns

resultExtraction

Struct that combines the cutout itself with additional metadata and the pixel-coordinate stencil. The cutout is not masked; Extraction.mask must be called explicitly if desired.

extract_search(stencil: SkyStencil, dataset_type_name: str, data_id: DataCoordinate | Mapping[str, Any], collections: Sequence[str]) → Extraction

Extract a subimage from a dataset identified by a (dataset type, data ID, collection path) tuple.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

dataset_type_namestr

Name of the butler dataset. Use .-separate terms to read an image-like component.

data_iddict or DataCoordinate

Mapping-of-dimensions identifier for the dataset within its collection.

collectionsIterable [ str ]

Collections to search for the dataset, in the order they should be searched.

Returns

resultExtraction

Struct that combines the cutout itself with additional metadata and the pixel-coordinate stencil. The cutout is not masked; Extraction.mask must be called explicitly if desired.

extract_uuid(stencil: SkyStencil, uuid: UUID, *, component: str | None = None, cutout_mode: CutoutMode = CutoutMode.FULL_EXPOSURE) → Extraction

Extract a subimage from a dataset identified by its UUID.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

uuidUUID

Unique ID of the dataset to read from.

componentstr, optional

If not None (default), read this component instead of the composite dataset.

Returns

resultExtraction

Struct that combines the cutout itself with additional metadata and the pixel-coordinate stencil. The cutout is not masked; Extraction.mask must be called explicitly if desired.

process_ref(stencil: SkyStencil, ref: DatasetRef, *, mask_plane: str | None = 'OUTSIDE_STENCIL', cutout_mode: CutoutMode = CutoutMode.FULL_EXPOSURE) → ResourcePath

Extract and write a cutout from a fully-resolved DatasetRef.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

refDatasetRef

Fully-resolved reference to the dataset to obtain the cutout from. Must have DatasetRef.id not None (use extract_search instead when this is not the case). Need not have an expanded data ID. May represent an image-like dataset component.

mask_planestr, optional

If not None, set this mask plane in the extracted cutout to flag pixels that lie outside the stencil region. Does nothing if the image type does not have a mask plane. Defaults to OUTSIDE_STENCIL.

Returns

uriResourcePath

Full path to the extracted cutout.

process_search(stencil: SkyStencil, dataset_type_name: str, data_id: DataCoordinate | Mapping[str, Any], collections: Sequence[str], *, mask_plane: str | None = 'OUTSIDE_STENCIL') → ResourcePath

Extract and write a cutout from a dataset identified by a (dataset type, data ID, collection path) tuple.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

dataset_type_namestr

Name of the butler dataset. Use .-separate terms to read an image-like component.

data_iddict or DataCoordinate

Mapping-of-dimensions identifier for the dataset within its collection.

collectionsIterable [ str ]

Collections to search for the dataset, in the order they should be searched.

mask_planestr, optional

If not None, set this mask plane in the extracted cutout to flag pixels that lie outside the stencil region. Does nothing if the image type does not have a mask plane. Defaults to OUTSIDE_STENCIL.

Returns

uriResourcePath

Full path to the extracted cutout.

process_uuid(stencil: SkyStencil, uuid: UUID, *, component: str | None = None, mask_plane: str | None = 'OUTSIDE_STENCIL', cutout_mode: CutoutMode = CutoutMode.FULL_EXPOSURE) → ResourcePath

Extract and write a cutout from a dataset identified by its UUID.

Parameters

stencilSkyStencil

Definition of the cutout region, in sky coordinates.

uuidUUID

Unique ID of the dataset to extract the subimage from.

componentstr, optional

If not None (default), read this component instead of the composite dataset.

mask_planestr, optional

If not None, set this mask plane in the extracted cutout to flag pixels that lie outside the stencil region. Does nothing if the image type does not have a mask plane. Defaults to OUTSIDE_STENCIL.

Returns

uriResourcePath

Full path to the extracted cutout.

write_fits(extract_result: Extraction) → ResourcePath

Write a Extraction to a remote FITS file in output_root.

Parameters

extract_resultExtraction

Result of a call to a extract_* method.

Returns

uriResourcePath

Full path to the extracted cutout.