Tag
All regions may have zero or more tags associated with it, which may be
used for grouping and searching.
Example: circle(100,100,20) # tag = {Group 1} tag =
{Group
2}
Line
The line region may be rendered with arrows, one at each end. To
indicate arrows, use the line property. A '1' indicates an arrow, '0'
indicates no arrow.
Example: line(100,100,200,200) # line= 1 1
Ruler
The ruler region may display information in 'pixels', 'degrees',
'arcmin', or 'arcsec'. Use the ruler property to indicate which format
to display distances in.
Example: ruler(100,100,200,200) # ruler=arcmin
Point
Point regions have an associated type and size. Use the point property
to set
the point type.
Example: point(100,100) # point=diamond 31
Default Properties
The default properties are:
text={}
color=green
font="helvetica 10 normal"
select=1
edit=1
move=1
delete=1
highlite=1
include=1
fixed=0
Region File Format
Syntax
Region arguments may be separated with either a comma or space.
Optional parentheses may be used a the beginning and end of a
description.
circle 100 100 10
circle(100 100 10)
circle(100,100,10)
Comments
All lines that begin with # are comments and will be ignored.
Delimiter
All lines may be delimited with either a new-line or semi-colon.
circle 100 100 10
ellipse 200 200 20 40 ; box 300 300 20 40
Header
A DS9 region file may start with the following optional header:
# Region file format: DS9 version 4.0
Global Properties
Global properties affect all regions unless a local property is
specified. The global keyword is first, followed by a list of
keyword = value pairs. Multiple global property lines may be used
within a region file.
global color=green font="helvetica 10 normal" edit=1 move=1
delete=1 highlite=1 include=1 wcs=wcs
Local Properties
Local properties start with a # after a region description and only
affect the region it is specified with.
physical;circle(504,513,20) # color=red text={This is a
Circle}
Coordinate Systems
For each region, it is important to specify the coordinate system
used to interpret the region, i.e., to set the context in which the
position and size values are interpreted. For this purpose, the
following keywords are recognized:
PHYSICAL
#
pixel
coords
of
original
file using LTM/LTV
IMAGE
#
pixel
coords
of
current
file
FK4,
B1950
#
sky
coordinate
systems
FK5,
J2000
#
sky
coordinate
systems
GALACTIC
#
sky
coordinate
systems
ECLIPTIC
#
sky
coordinate
systems
ICRS
#
currently
same
as
J2000
LINEAR
#
linear
wcs
as
defined
in file
AMPLIFIER
#
mosaic
coords
of
original
file using ATM/ATV
DETECTOR
#
mosaic
coords
of
original
file using DTM/DTV
Mosaic Images
While some coordinate systems are unique across mosaic images, others
coordinate systems, such as image, or physical ,
are
valid on a per segment basis. In this case, use tile to
specify
which header to use in all coordinate conversions. The default is the
first
header, or tile 1.
Example: tile 2;fk5;point(100,100)
Multiple WCS
If an image has multiple wcs's defined, use wcs#
to specify which wcs to use for all wcs references. Valid values are wcs,
wcsa,
wcsb,
wcsc...
wcsz.
Example: wcsa;linear;point(100,100) # point=diamond
Specifying Positions and Sizes
The arguments to region shapes can be floats or integers describing
positions and sizes. They can be specified as pure numbers or using
explicit formatting directives:
position arguments
[num]
#
context-dependent
(see
below)
[num]d
#
degrees
[num]r
#
radians
[num]p
#
physical
pixels
[num]i
#
image
pixels
[num]:[num]:[num] # hms
for
'odd' position arguments
[num]:[num]:[num] # dms
for
'even' position arguments
[num]h[num]m[num]s # explicit
hms
[num]d[num]m[num]s # explicit
dms
size arguments
[num]
#
context-dependent
(see
below)
[num]"
#
arc
sec
[num]'
#
arc
min
[num]d
#
degrees
[num]r
#
radians
[num]p
#
physical
pixels
[num]i
#
image
pixels
When a "pure number" (i.e. one without a format directive such as 'd'
for 'degrees') is specified, its interpretation depends on the context
defined by the 'coordsys' keyword. In general, the rule is:
All pure numbers have implied units corresponding to the
current coordinate
system.
If no such system is explicitly specified, the default system is
implicitly assumed to be PHYSICAL. In practice this means
that for IMAGE and PHYSICAL systems, pure numbers
are pixels. Otherwise, for all systems other than linear, pure numbers
are degrees. For LINEAR systems, pure numbers are in the
units of the linear system. This rule covers both positions and sizes.
The input values to each shape can be specified in several coordinate
systems including:
IMAGE
#
pixel
coords
of
current
file
LINEAR
#
linear
wcs
as
defined
in file
FK4,
B1950
#
sky
coordinate
systems
FK5, J2000
GALACTIC
ECLIPTIC
ICRS
PHYSICAL
#
pixel
coords
of
original
file using LTM/LTV
AMPLIFIER
#
mosaic
coords
of
original
file using ATM/ATV
DETECTOR
#
mosaic
coords
of
original
file using DTM/DTV
WCS,WCSA-WCSZ #
specify which WCS system to be used for
# linear and
sky coordinate systems
If no coordinate system is specified, PHYSICAL is assumed. PHYSICAL
or a World Coordinate System such as J2000 is preferred and
most general. The coordinate system specifier should appear
at the beginning of the region description, on a separate line (in a
file),
or followed by a new-line or semicolon; e.g.,
image; circle 100 100 10
physical; ellipse 200 200 10 20
fk5; point 30 50
wcsa; fk4; point 202 47
wcsp; linear; point 100 100
The use of celestial input units automatically implies WORLD
coordinates of the reference image. Thus, if the world coordinate
system of the reference image is J2000, then
circle 10:10:0 20:22:0 3'
is equivalent to:
j2000; circle 10:10:0 20:22:0 3'
Note that by using units as described above, you may mix
coordinate
systems within a region specifier; e.g.,
physical; circle 6500 9320 3'
Note that, for regions which accept a rotation angle such as:
the angle is relative to the specified coordinate system. In
particular, if the region is specified in WCS coordinates, the angle is
related to the WCS system, not x/y image coordinate axis. For WCS
systems with no rotation, this obviously is not an issue. However, some
images do define an implicit rotation (e.g., by using a non-zero CROTA
value in the WCS parameters) and for these images, the angle will be
relative to the WCS axes. In such case, a region specification such as:
fk4;ellipse(22:59:43.985, +58:45:26.92,320", 160", 30)
will not, in general, be the same region specified as:
physical;ellipse(465, 578, 40, 20, 30)
even when positions and sizes match. The angle is relative to WCS
axes in the first case, and relative to physical x,y axes in the second.