display_footprints#

lsst.analysis.ap.display_footprints(butler=None, visit=None, detector=None, backend='firefly', *, exposure=None, catalog=None, image_type='difference', catalog_dataset='dia_source_unfiltered', style='outline', palette=('lime', 'red', 'cyan', 'magenta', 'yellow', 'orange', 'deepskyblue', 'pink', 'white', 'violet', 'gold', 'lightgreen'), frame=0, mask_transparency=80, strip_metadata=True, image_datasets={'difference': 'difference_image', 'science': 'preliminary_visit_image', 'template': 'template_detector'})#

Overlay diaSource footprints on an exposure in Firefly, color-cycled so that touching footprints get distinct colors.

The footprints come from an afw SourceCatalog (the diffim detection output, which still carries per-source Footprints – the transformed and APDB diaSource tables are DataFrames with the footprints stripped). Supply the data one of two ways:

  • pass butler plus visit and detector to load the exposure (image_datasets[image_type]) and catalog (catalog_dataset) from the butler; or

  • pass exposure and catalog directly, skipping the butler.

The footprints are then drawn on a single Firefly frame using the backend’s native footprint overlay.

Each footprint is assigned one of the palette colors by greedy graph coloring over a bounding-box-touch adjacency graph, so no two touching footprints share a color (see _footprint_adjacency and _greedy_color). The color chosen for each footprint is randomized among those its neighbors are not using, so the palette is spread across the frame and re-running produces a different coloring. Because Firefly’s overlayFootprints takes a single color per call, the catalog is split into one sub-catalog per color and each is overlaid as its own Firefly layer.

Re-running on the same frame overwrites each color layer in place. Color layers left over from a previous run that used more colors are not cleared automatically.

Parameters#

butlerlsst.daf.butler.Butler, optional

Butler to load the exposure and catalog from. Required (with visit and detector) unless exposure and catalog are given directly.

visit, detectorint, optional

Visit and detector ids to load data for. Required with butler.

backendstr, optional

afw display backend. Only "firefly" is supported, since the overlay uses Firefly’s native footprint rendering.

exposurelsst.afw.image.Exposure, optional

Exposure to draw on, supplied directly instead of via the butler. Must be given together with catalog; when set, butler, visit, detector, catalog_dataset, image_type, and image_datasets are all ignored.

cataloglsst.afw.table.SourceCatalog, optional

Footprint-bearing source catalog, supplied directly instead of via the butler. Must be given together with exposure.

image_type{“science”, “template”, “difference”}, optional

Which image to display the footprints on (butler mode only). Default "difference".

catalog_datasetstr, optional

Butler dataset of the footprint-bearing afw source catalog (butler mode only). Default "dia_source_unfiltered" (the pre-filter detection catalog, which still carries footprints; the transformed/standardized diaSource tables have them stripped).

style{“outline”, “fill”}, optional

Footprint rendering style. "outline" (default) keeps the color coding legible where footprints overlap; "fill" shades the interior.

palettesequence of str, optional

Colors cycled across footprints. Defaults to the 12-color _OBJECT_PALETTE also used by the cutout plotters.

frameint, optional

Display frame to draw the image and footprints in. Default 0.

mask_transparencyint or None, optional

Mask-plane transparency forwarded to the display (0 = opaque, 100 = fully transparent). Pass None to leave it untouched.

strip_metadatabool, optional

Drop LTV1/LTV2 keywords from the exposure metadata before sending to the backend.

image_datasetsdict [str, str], optional

Mapping from image-type key to butler dataset name.