Regions provide a means for marking particular
areas of an image for further analysis. Regions may also be used for presentation
purposes. DS9 supports a number of region descriptions, each of which may
be edited, moved, rotated, displayed, saved and loaded, via the GUI and
XPA.
Region Descriptions
Region Properties
Region File
Format
External
Region Files
Region Descriptions
Circle
Annulus
Usage: annulus x y inner outer n=#
annulus x y r1 r2 r3...
Ellipse
Usage: ellipse x y radius radius angle
Ellipse Annulus
Usage: ellipse x y r1 r2 angle...
ellipse x y r2 r3 angle &
!ellipse x y r1 r2 angle
ellipse x y r3 r4 angle &
!ellipse x y r2 r3 angle...
Box
Usage: box x y width height angle
Box Annulus
Usage: box x y w1 h1 angle
box x y w2 h2 angle &
!box x y w1 h1 angle
box x y w3 h3 angle &
!box x y w2 h2 angle...
Polygon
Usage: polygon x1 y1 x2 y2 x3 y3 ...
Line
Usage: line x1 y1 x2 y2 # line=[0|1] [0|1]
Text
Usage: text x y # text={Your Text Here}
text x y {Your Text Here}
Ruler
Usage: ruler x1 y1 x2 y2 # ruler=[pixels|degrees|arcmin|arcsec]
Circle Point
Usage: point x y # point=circle
circle point x y
Box Point
Usage: point x y # point=box
box point x y
Diamond Point
Usage: point x y # point=diamond
diamond point x y
Cross Point
Usage: point x y # point=cross
cross point x y
X Point
Usage: point x y # point=x
x point x y
Arrow Point
Usage: point x y # point=arrow
arrow point x y
BoxCircle Point
Usage: point x y # point=boxcircle
boxcircle point x y
Region Properties
Each region has a number of properties associated
with the region, which indicates how the region is to be rendered or manipulated.
Properties are defined for a region in the comment section of the region
description. The exception is the Include/Exclude property. It is set via
'+' or '-' preceeding the region. In addition, the Line, Point, and Ruler
regions have unique properties, not shared by others.
Text
All regions may have text associated with
them. Use the text property to set the text. Strings may be quoted with
" or ' or {}. For best results, use {}.
Example: circle(100,100,20) # text = {This message has both a "
and ' in it}
Color
The color property specifies the color of
the region when rendered. The follow 8 colors are supported:
white
black
red
green
blue
cyan
magenta
yellow
Example: circle(100,100,20) # color = green
Font
The font property specifies the font family,
size, and type of any text to be displayed along with the region.
Example: circle(100,100,20) # font="times 12 bold"
Can Select
The Select property specifies if the user
is allowed to select (hence, edit) the region via the GUI. For Regions
used for catalogs and such, it is desirable that the user is unable to
edit, move, or delete the region.
Example: circle(100,100,20) # select = 1
Can Edit
The Edit property specifies if the user is
allowed to edit the region via the GUI.
Example: circle(100,100,20) # edit = 1
Can Move
The Move property specifies if the user is
allowed to move the region via the GUI.
Example: circle(100,100,20) # move = 1
Can Rotate
The Rotate property specifies if the user
is allowed to rotate the region via the GUI.
Example: circle(100,100,20) # rotate = 1
Can Delete
The Delete property specifies if the user
is allowed to delete the region via the GUI.
Example: circle(100,100,20) # delete = 1
Include/Exclude
The Include/Exclude properties flags the region
with a boolean NOT for later
analysis. Use '+' for include (default), '-' for exclude.
Example: -circle(100,100,20)
Fixed in Size
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
Line
The line region may be rended 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 infomation 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"
edit=1
move=1
delete=1
include=1
fixed=0
Region File
Format
Syntax
Region arguments may be separated with either
a comma or space. Optional parens 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
Glogal 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
include=1
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 whichsposition 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
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. The non-native formats
supported by DS9 are:
FUNTools
DS9 is fully compatible with FUNTools,
with the following notes:
Reading into FUNTools from DS9:
-
POINT is ignored
-
LINE ignored
-
RULER is ignored
-
ELLIPSE ANNULUS is not supported
-
BOX ANNULUS is not supported
-
All properties are ignored
Reading from FUNTools into DS9:
-
FIELD is ignored
-
PANDA is ignored
-
PIE is ignored
Ciao
-
All point regions are translated as POINT
-
BOX is translated as ROTBOX
-
LINE ignored
-
RULER is ignored
-
TEXT is ignored
-
ELLIPSE ANNULUS is ignored
-
BOX ANNULUS is ignored
-
All properties are ignored
SAOimage
-
All point regions are translated as POINT
-
LINE is ignored
-
TEXT is ignored
-
RULER 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
-
ELLIPSE ANNULUS is ignored
-
BOX ANNULUS 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
-
The follow regions are not supported
-
ELLIPTANNULUS
-
PIE
-
SECTOR
-
DIAMOND
-
RHOMBUS
-
ROTDIAMOND
-
ROTRHOMBUS
Regions