103.4. Image display with Firefly

103.4. Image display with Firefly¶

For the Rubin Science Platform at data.lsst.cloud.
Data Release: Data Preview 2
Container Size: Large
LSST Science Pipelines version: v30.0.10
Last verified to run: 2026-07-21
Repository: github.com/lsst/tutorial-notebooks
DOI: 10.11578/rubin/dc.20250909.20

Learning objective: How to use the Firefly interactive image display tool.

LSST data products: deep_coadd

Packages: lsst.daf.butler, lsst.geom, lsst.afw.display, lsst.images, firefly_client

Credit: Originally developed by the Rubin Community Science team. Please consider acknowledging them if this notebook is used for the preparation of journal articles, software releases, or other notebooks.

Get Support: Everyone is encouraged to ask questions or raise issues in the Support Category of the Rubin Community Forum. Rubin staff will respond to all questions posted there.

1. Introduction¶

Firefly is an interactive web user interface for astronomers that provides a table display, FITS/HiPS image visualization, and customizable 2D plots. All three highly interactive components can be used together on the same data set.

Firefly forms the basis of the Portal Aspect. From Notebooks, the Firefly FITS image visualization panel is recommended for displaying and manipulating images, as demonstrated in this tutorial.

Firefly development by IPAC at Caltech has been supported by NASA, principally through IRSA, and by the National Science Foundation, through the Vera C. Rubin Observatory. Firefly is open-source software, available on GitHub (Caltech-IPAC/firefly) and DockerHub (ipac/firefly).

Related tutorials: The 100-level series on the Butler demonstrates how to find and retrieve images.

1.1. Import packages¶

Import the Butler module from the lsst.daf.butler package, the geom module from lsst.geom (for converting sky coordinates to pixel positions), the display module from the lsst.afw package (for image display), the get_legacy_deep_coadd_mask_planes function from lsst.images (for mapping new mask plane names to legacy names), and the firefly_client.plot module (for FireflyClient).

In [1]:

import numpy as np
from lsst.daf.butler import Butler
import lsst.geom as geom
import lsst.afw.display as afwDisplay
from lsst.images import get_legacy_deep_coadd_mask_planes
import firefly_client.plot as ffplt
from astropy.coordinates import SkyCoord
import astropy.units as u

1.2. Define parameters and functions¶

Instantiate the butler.

In [2]:

butler = Butler("dp2", collections="dp2")

2. Start Firefly¶

Set afwDisplay to use Firefly, and define afw_display to show images in frame 1. Firefly will open in a new tab.

In [3]:

afwDisplay.setDefaultBackend("firefly")
afw_display = afwDisplay.Display(frame=1)

2.1. Set up a side-by-side view¶

To set up the JupyterLab main work area for side-by-side viewing of notebook and Firefly, click on the "Firefly Viewer" tab and drag it to the right, then down to the middle of the screen. A blue box will appear indicating the new position of the tab. Release the mouse button.

Figure 1: Side-by-side view of a Jupyter notebook and the Firefly viewer.

3. Display an image¶

Define an RA, Dec, and band (filter). These coordinates are near the center of the Extended Chandra Deep Field South (ECDFS).

In [4]:

ra = 53.076
dec = -28.110
band = 'r'

Define a query string using the coordinates and band as search constraints. Query the butler for matching deep_coadd images and retrieve the first on the list.

In [5]:

query = "band.name = :band AND patch.region OVERLAPS POINT(:ra, :dec)"
bind = {'band': band, 'ra': ra, 'dec': dec}
refs = butler.query_datasets("deep_coadd", where=query,
                             bind=bind, order_by='patch')
deep_coadd = butler.get(refs[0])

Display the retrieved image in Firefly.

In [6]:

afw_display.image(deep_coadd)

The displayed image should look like this.

Figure 2: A deep coadd in the default display mode: with the mask overlay.

4. Manipulate the mask display¶

The display framework renders each plane (each bit) of the mask in a different color.

4.1. Set mask transparency¶

Reset the mask transparency to 100% transparent.

In [7]:

afw_display.setMaskTransparency(100)

The displayed image should look like this.

Figure 3: A deep coadd without the mask.

Reset mask transparency to 50% transparent.

In [8]:

afw_display.setMaskTransparency(50)

Print the list of mask keys and color.

In [9]:

mask = deep_coadd.mask
new_to_old_names = {v.name: k for k, v in get_legacy_deep_coadd_mask_planes().items()}
for mask_key in mask.schema.names:
    print('{}: {}'.format(mask_key, afw_display.getMaskPlaneColor(new_to_old_names[mask_key])))

NO_DATA: orange
INTERPOLATED: green
COSMIC_RAY: magenta
SATURATED: green
DETECTION_EDGE: yellow
CLIPPED: blue
REJECTED: cyan
DETECTED: blue
INEXACT_PSF: magenta

Click on the layers icon (red arrow) to open the layers pop-up box in the Firefly display and see the mask names and colors.

Figure 4: The layers overlay with all masks toggled to display.

4.2. Select mask layers to display¶

Set all mask layers to 100% transparent.

In [10]:

afw_display.setMaskTransparency(100)

Set the DETECTED mask layer, indicating pixels that are part of a detected object, to 80% transparent to show only that layer.

In [11]:

afw_display.setMaskTransparency(80, 'DETECTED')

Re-display all masks by setting all mask layers to 50% transparent.

In [12]:

afw_display.setMaskTransparency(50)

Open the layers pop-up box again and untoggle all but the DETECTED mask layer.

Figure 5: The layers overlay with all masks toggled off except DETECTED.

Click the X in the upper right corner of the window to dismiss it.

4.3. Change the mask colors¶

The Wikipedia page for X11 color names has a table with color swatches and their hexadecimal format.

Set all masks to be transparent and then only the DETECTED mask to be 80% transparent.

In [13]:

afw_display.setMaskTransparency(100)
afw_display.setMaskTransparency(80, 'DETECTED')

Change the DETECTED mask plane color to "Deep Pink", #FF1493.

In [14]:

afw_display.setMaskPlaneColor('DETECTED', '#FF1493')

Re-display the deep_coadd to see the new mask color.

In [15]:

afw_display.image(deep_coadd)

Change the mask color to cyan from within Firefly.

Click on the color button for the DETECTED mask layer (red arrow) to open the color picker, and choose cyan (Hex 50E3C2).

Figure 6: The color for the DETECTOR mask has been reset to cyan.

Click "OK" to dismiss the color picker, and then the X in the upper right corner of the Layers pop-up window to dismiss it.

Notice: Modifications to the displayed masked colors made via afw_display commands will be mirrored in the Firefly overlay display panel. However, changes performed in the Firefly overlay display panel might not be mirrored in the afw_display variables.

Re-apply transparency to the DETECTED mask.

In [16]:

afw_display.setMaskTransparency(80, 'DETECTED')

5. Manipulate the image display¶

5.1. Set the scale¶

Notice that the default scale (white-grey-black) is a linear stretch range from 1% to 99% pixel values.

Figure 7: The stretch drop down menu in the Firefly display, with the default scale setting.

Control the colorbar scaling algorithm with the display’s scale method.

Set the scale to asinh stretch with explicit minimum (black) and maximum (white) values.

In [17]:

afw_display.scale("asinh", -5, 100)

Use an automatic algorithm like zscale (or minmax) to select the white and black thresholds.

In [18]:

afw_display.scale("asinh", "zscale")

Option to reset the stretch back to the default from the command line.

In [19]:

# afw_display.scale("linear", 1, 99)

5.2. Zoom in and out¶

Use the zoom method to zoom in by a factor of 4.

In [20]:

afw_display.zoom(4)

The result should look like this.

Figure 8: Zoom in to 4x scale.

Zoom out to a factor of 1.

In [21]:

afw_display.zoom(1)

The result should look like this.

Figure 9: Zoom out to 1x scale.

Reset to full-frame by clicking on the icon marked with the red arrow in Figure 9.

5.3. Plot markers¶

Use the dataId for the deep_coadd image to retrieve the object table for the tract.

In [22]:

dataId = refs[0].dataId

Retrieve the patch and the objects' r-band sky coordinates. The object table stores position as r_ra/r_dec rather than pixel coordinates, so these are converted to pixel positions using the deep_coadd WCS before plotting.

In [23]:

use_columns = ['objectId', 'patch', 'r_ra', 'r_dec', 'r_extendedness', 'r_psfFlux']
objects = butler.get('object', tract=dataId.get('tract'),
                     skymap=dataId.get('skymap'),
                     parameters={'columns': use_columns})

Identify objects in the patch of the displayed deep_coadd image.

In [24]:

tx = np.where(objects['patch'] == dataId.get('patch'))[0]
print(len(tx))

9058

Use buffering to display orange circles at the location of every object.

In [25]:

with afw_display.Buffering():
    for i in tx:
        sky_point = SkyCoord(ra=objects[i]['r_ra'] * u.deg, dec=objects[i]['r_dec'] * u.deg)
        pix = deep_coadd.sky_projection.sky_to_pixel(sky_point)
        afw_display.dot('o', pix.x, pix.y, size=20, ctype='orange')

The result should look like this.

Figure 10: Objects in the patch plotted as orange circles.

Why are no objects near the edges marked?

The deep_coadd images are per-patch, and patches and deep_coadd images overlap at their edges. The object table is by tract, and has no duplicates -- there is only one row per detected object. For every object the patch column is the patch for which they are closest to the center. The stars and galaxies near the edges of the displayed deep_coadd image are listed as belonging to the adjacent patch.

Erase the markers.

In [26]:

afw_display.erase()

5.4. Draw lines¶

Draw a line on the image with pixel coordinates. The coordinates are in zero based image pixel rather than FITS image pixel. Click the "EQ-J2000:" at bottom left (purple arrow in Figure 11) to switch to "Zero Based Image Pixel (0 Based Pix)", and pixel values instead of sky coordinates will appear when the mouse is hovered over the image, which is one way to read off coordinates for a line.

Figure 11: The readout coordinates panel.

Alternatively, select two point sources (r_extendedness of 0) from the objects table used in Section 5.3. and convert their sky coordinates to pixel coordinates with the deep_coadd WCS.

In [27]:

star_tx = tx[objects['r_extendedness'][tx] == 0]
star_tx = star_tx[np.argsort(objects['r_psfFlux'][star_tx])[::-1]][:3]
star_points = []
for i in star_tx:
    sky_point = SkyCoord(ra=objects[i]['r_ra'] * u.deg, dec=objects[i]['r_dec'] * u.deg)
    pix = deep_coadd.sky_projection.sky_to_pixel(sky_point)
    star_points.append([pix.x, pix.y])

Plot a line between the two points

In [28]:

afw_display.line([star_points[0], star_points[1]], ctype='red')

The result should look like this.

Figure 12: A red line drawn on the image.

Draw other two more lines in purple to make a triangle.

In [29]:

afw_display.line([star_points[0], star_points[2], star_points[1]], ctype='purple')

Erase the lines and set the mask to transparent.

In [30]:

afw_display.erase()

In [31]:

afw_display.setMaskTransparency(100)

5.5. Open multiple frames¶

Get another deep_coadd image, from a different patch of the same tract, to display side by side with the first.

In [32]:

tract_query = "band.name = :band AND patch.tract = :tract"
tract_bind = {'band': band, 'tract': dataId.get('tract')}
tract_refs = butler.query_datasets("deep_coadd", where=tract_query, bind=tract_bind,
                                   skymap=dataId.get('skymap'), order_by='patch')
second_ref = next(r for r in tract_refs if r.dataId.get('patch') != dataId.get('patch'))
deep_coadd_new = butler.get(second_ref)

Set up another frame. Display the new image in the new frame, so that two images are displayed side-by-side.

In [33]:

afw_display2 = afwDisplay.Display(frame=2)

In [34]:

afw_display2.image(deep_coadd_new)

The result should look like this, after setting the left image to full-frame (by clicking on the icon marked with the red arrow in Figure 9).

Figure 13: Displaying two images side by side.

Close the two images by moving the cursor to the cross (x) at the top right of each image and then clicking it.

6. Use the FireflyClient¶

Get the FireflyClient object.

In [35]:

fc = afw_display.getClient()

Use the same FireflyClient instance in the firefly_client.plot module.

In [36]:

ffplt.use_client(fc)

Upload the table of selected objects in the deep_coadd, which was used in Section 5.3. above, to Firefly.

The catalog is shown in an interactive table viewer, which is essentially and instance of the Portal Aspect launched within the Notebook Aspect.

Warning: Uploading a table also opens a HiPS/MOC coverage panel showing the catalog's sky footprint. Individual markers in this panel are auto-clustered by zoom level, so nearby markers may render as separate groups; this is a display effect, not a property of the catalog.

In [37]:

tbl_id = ffplt.upload_table(objects[tx], title='Object Catalog')

Make a scatter plot using the coordinates. Plots are rendered by plotly.

In [38]:

ffplt.scatter(x_col='r_ra',
              y_col='r_dec',
              size=3,
              color='blue',
              title='r_ra vs. r_dec',
              xlabel='r_ra',
              ylabel='r_dec')

Find the result in the "Pinned Chart" tab in the left-side panel.

The highlighted point in the scatter plot corresponds to the highlighted row in the table. Click another point or row for another object.

The result should look like this.

Figure 14: Using FireflyClient.

Find more tutorials for the Portal Aspect (FireflyClient) in the documentation for Data Preview 2.