Coordinates and regions#

Regions are how you point at things: a circle on a star to read its magnitude, a box on a galaxy for its statistics, a line across a cluster for a profile. This page shows how to read sky coordinates in the viewer, how to draw regions from Python, and how to read back what you drew by hand.

The examples use the sample star field, image (a FITS file with a WCS), and stars, a pandas table of the stars in it with their sky positions and magnitudes.

Coordinates under the cursor#

Hover anywhere on an image with a WCS and the readout gives the pixel, its value, and its RA and Dec. Two settings change how positions are written:

  • sky_format: "sexagesimal" (the default, 10:00:24.0 +02:12:00) or "degrees".

  • region_coords: whether region cards and the Regions panel give positions on the "sky" (the default), in "pixel" coordinates, or not at all ("off").

import pixel_clarity as pc

pc.show(image, sky_format="degrees")

Press j (or the pin in the toolbar) to go to a position: type an RA and Dec, in degrees or as h:m:s ±d:m:s, and the view centers on it and marks the spot.

Drawing regions by hand#

The region tools are in the toolbar, or on the keys b (box), o (circle), l (line) and p (point). Each region gets a card with its statistics: mean, median, standard deviation, sum, a centroid, and on a flux-calibrated image an AB magnitude less the local sky. a pins the statistics onto the image beside the region; t adds a text label; g plots a region through the planes of a cube or the frames of a stack. A line or a box also plots the values along it: see Profiles and spectra. A selected box has a round handle to turn it by, and Add annulus in a circle’s right-click menu puts a ring around it.

Regions save and load as .reg files compatible with DS9, from the Regions panel.

Drawing regions from Python#

add_regions takes region text (a .reg file’s contents, or its path) or objects from the regions package, in pixel or sky coordinates. Sky regions are placed with the image’s WCS, so a catalog with RA and Dec lands on the right stars without converting anything first.

Here we circle the five brightest stars in the catalog, by their sky positions, and draw a box on the galaxy in pixel coordinates. With leader_lines=True, a statistics card you pin to the image (select a region and press a) is joined to its region by a line, which helps when there are several close together.

v = pc.show(image, scale="asinh", limits="99.5", leader_lines=True)

bright = stars.nsmallest(5, "mag")
v.add_regions(
    "\n".join(f'fk5; circle({s.ra}, {s.dec}, 2.5") # text={{m = {s.mag:.1f}}}' for s in bright.itertuples()),
    name="5 brightest",
)
v.add_regions("image; box(981, 641, 300, 170) # color=yellow text={galaxy}", name="galaxy")

The name shows in the message the viewer gives when the regions arrive. Each call adds to what is there; nothing is replaced. Circles, boxes (turned ones too), ellipses, annuli, polygons, lines, points and text labels all come through, with their colors and labels, and DS9’s projection, a line widened into a band. An annulus with several radii becomes one region per ring. Elliptical and box annuli and other shapes are skipped, and the message says which.

A whole catalog#

A few hundred regions are fine as ordinary, editable regions. Past 2000 shapes the viewer draws them as a catalog overlay instead: much faster, and still readable at any zoom, but not editable one by one. Adding another overlay under the same name replaces it, which is handy when you are trying different cuts on a catalog.

cat = pc.show(image, scale="asinh", limits="99.5", cmap="magma")

faint = stars[stars.mag > 20]
cat.add_regions("\n".join(f'fk5; circle({s.ra}, {s.dec}, 1.5") # color=cyan' for s in faint.itertuples()), name="faint stars")

With the regions package#

If you already work with regions objects, pass them as they are, one or a list:

from astropy.coordinates import SkyCoord
import astropy.units as u
from regions import CircleSkyRegion, RectanglePixelRegion, PixCoord

objs = pc.show(image, scale="asinh", limits="99.5")
objs.add_regions([
    CircleSkyRegion(SkyCoord(150.1, 2.2, unit="deg"), radius=5 * u.arcsec),
    RectanglePixelRegion(PixCoord(980, 640), width=320, height=200),
])

Reading regions back#

Whatever is drawn on the viewer, by Python or by hand, can be read back. regions_ds9 gives it as region text in image coordinates, with no extra package needed. Here is what v, the viewer with the five brightest stars, holds: the circles placed by their sky positions, now in its pixels, and the box.

print(v.regions_ds9)

# Region file format: DS9 version 4.1
global color=green width=1 font="helvetica 10 normal roman"
image
circle(1392.617,535.829,22.7273) # color=green text={m = 13.5}
circle(20.2025,1375.4827,22.7273) # color=green text={m = 13.5}
circle(1316.8995,1412.3955,22.7273) # color=green text={m = 13.6}
circle(1022.2182,732.7132,22.7273) # color=green text={m = 13.6}
circle(1578.9817,1263.359,22.7273) # color=green text={m = 13.6}
box(981,641,300,170,0) # color=yellow text={galaxy}

regions gives the same as regions pixel regions (pip install 'pixel-clarity[regions]'), ready for photometry or to turn into sky regions with the image’s WCS:

from astropy.io import fits
from astropy.wcs import WCS

wcs = WCS(fits.getheader(image))
for r in v.regions:
    print(r.to_sky(wcs))

Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.081879, 2.191928)>
radius: 2.5 arcsec
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.123845, 2.217584)>
radius: 2.5 arcsec
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.084194, 2.218712)>
radius: 2.5 arcsec
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.093205, 2.197944)>
radius: 2.5 arcsec
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.07618, 2.214158)>
radius: 2.5 arcsec
Region: RectangleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (150.09446538, 2.19514166)>
width: 33.0 arcsec
height: 18.7 arcsec
angle: 359.9998 deg

Both read what the viewer last saved, so draw or move a region, then run the cell again. That works even while another cell is busy, and for a viewer opened in a tab of its own. Coordinates are the image’s pixels: for a stack, its frames’; for an RGB set, the red image’s; for a mosaic, the mosaic’s own plane.

Note

The viewers on this page are web pages written from these examples, so the regions are drawn as they were added. In a notebook, regions and regions_ds9 also pick up whatever you change.