The Fixed in Size property specifies that the region does not change
in size as the image magnification factor changes. This allows the user
to build complex pointer type regions.
Example: circle(100,100,20) # fixed = 1
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. Use the point property to set
the point type.
Example: point(100,100) # point=diamond
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 3.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 global wcs=wcs#
to specify which wcs to use for all wcs references. Valid values are wcs,
wcsa, wcsb, wcsc... wcsz. This is only valid as a global property.
Example: global wcs=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
# various 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
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
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'
External Region Files
DS9 can read and write a number of region file formats. Not all formats
support all the functionality of DS9 regions. Therefore, the user may loose
some information when writing and then reading back from a region file in
a format other that DS9. On output, the regions File Format menu or the XPA regions point is used specify the output
coordinate system and format. On input, the menu or xpa point is used
only for the X Y format. For all other formats, the input coordinate
system is specified in the regions file itself.
Funtools
DS9 is fully compatible with Funtools, with the following notes:
Reading into Funtools from DS9:
- TEXT is ignored
- PROJECTION ignored
- RULER is ignored
- COMPASS is ignored
- All properties are ignored
Reading from Funtools into DS9:
- FIELD is ignored
- PIE is ignored
CIAO
- All point regions are translated as POINT
- BOX is translated as ROTBOX
- LINE ignored
- RULER is ignored
- COMPASS is ignored
- TEXT is ignored
- PROJECTION ignored
- ELLIPSE ANNULUS is ignored
- BOX ANNULUS is ignored
- PANDA is translated as PIE
- All properties are ignored
SAOimage
- All point regions are translated as POINT
- LINE is ignored
- TEXT is ignored
- PROJECTION ignored
- RULER is ignored
- COMPASS is ignored
- PANDA is ignored
- All properties are ignored
IRAF PROS
- All point regions are translated as POINT
- BOX is translated as ROTBOX
- LINE is ignored
- TEXT is ignored
- RULER is ignored
- COMPASS is ignored
- PROJECTION ignored
- PANDA is ignored
- All properties are ignored
FITS REGION Binary Table
- Read Only. DS9 currently can not write in this format.
- POINT is translated into BOX CIRCLE POINT
- ROTBOX is translated into BOX
- RECTANGLE is translated into BOX
- ROTRECTANGLE is translated into a BOX
- PIE is translated into PANDA
- The follow regions are not supported
- ELLIPTANNULUS
- SECTOR
- DIAMOND
- RHOMBUS
- ROTDIAMOND
- ROTRHOMBUS
X Y
This format consists of a number of coordinate pairs, one per line.
The coordinate format for both input and output is specified via the Save
Regions Parameters menu or XPA regions point.
The first two coordinates are read, the rest of the line is ignored. The
comment character '#' may be used at the beginning of line and the line is
ignored. This format is very useful for reading in coordinates from other
external analysis programs, such as IRAF.
Example:
# this is a comment
physical # this overrides the specified coordinate system
300 300
400 400 # this is a comment
500 500 this is ignored 550 700
- Save/List Regions-- all regions are output as a coordinate
pairs.