Visualizing Regions on Images

Firefly supports DS9-style region overlays. This notebook demonstrates how to create a region layer, add/remove region data, and delete a layer.

Setup

First, we create a FireflyClient instance and open a Firefly viewer. See Initializing a FireflyClient instance for more details. Then, we display a FITS image from a URL so that we have an image to overlay regions on. See Displaying a FITS Image for more details.

from firefly_client import FireflyClient
import tempfile

# Initialize a FireflyClient instance
fc = FireflyClient.make_client(url="https://irsa.ipac.caltech.edu/irsaviewer")

# Display a FITS image (from URL of WISE W2 cutout of M51 galaxy)
img_url = 'https://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/9a/05379a/141/05379a141-w2-int-1b.fits?center=202.4841667,47.23055556&size=400pix'
plot_id = 'wise-cutout'
fc.show_fits_image(file_input=img_url, plot_id=plot_id, title='WISE Cutout')

{'success': True}

Create a region layer

Regions are drawn as layers on top of images. Typically, you create a layer with overlay_region_layer(), then add more items with add_region_data().

From region commands (string)

A string or list of strings containing region commands can be added as an overlay layer on an image.

region_data = ["icrs",
               "circle 202.4841667d 47.23055556d 6' # color=red",
               "text 202.5608556d 47.3021292d {M51} # color=red",
               ]
region_layer_id = 'wise-regions'
fc.overlay_region_layer(region_data=region_data,
                        title='WISE Annotations',
                        region_layer_id=region_layer_id,
                        plot_id=plot_id)

{'success': True}

From a region file

If you have a region file (.reg or .txt), you can directly upload that using upload_file method and overlay it by using file_on_server parameter of overlay_region_layer method.

# Set it to region file you have locally
reg_fpath = None

# Here we genrate a region file using region data defined above
with tempfile.NamedTemporaryFile(mode='w+t', delete=False, suffix=".txt") as reg_file:
    reg_file.write("\n".join(region_data))
    reg_fpath = reg_file.name

fc.overlay_region_layer(file_on_server=fc.upload_file(reg_fpath),
                        title='WISE Annotations',
                        region_layer_id=region_layer_id, # same ID to replace previous one
                        plot_id=plot_id)

{'success': True}

Add region data to an existing layer

To add more regions to the same layer, use add_region_data(). Pass the ID of that layer as region_layer_id parameter.

ra, dec = 202.49808, 47.26617
point_source = f'icrs;point {ra}d {dec}d # point=cross 25 text={{NGC 5195}} color=cyan'
fc.add_region_data(region_data=point_source,
                   region_layer_id=region_layer_id)

{'success': True}

Remove a region command

You can use remove_region_data() to remove an individual region command if you saved the exact string you added.

fc.remove_region_data(region_data=point_source, region_layer_id=region_layer_id)

{'success': True}

Delete an entire region layer

To remove the entire region layer, use delete_region_layer().

fc.delete_region_layer(region_layer_id)

{'success': True}