CASA Region Format
Overview
The CASA region file format provides a flexible, easily edited set of region definitions which are accepted across CASA tasks. Region files may be written by hand or using the CASA viewer but note that the viewer currently only supports rectangles, ellipses (with no PA), polygons, and some symbols. Updates for full support are on the way..
For a file to be recognized as a valid CASA region text file, the first line must contain the string:
#CRTF
"CRTF" stands for "CASA Region Text Format". One may also include an optional version number at the end of the string, so it reads "#CRTFv0"; this indicates the version of the format definition.
Region files have two different kinds of definitions, "regions" and "annotations", each of which is one line long. To indicate an annotation, a line must begin with "ann". Lines that begin with the comment character (#) are not considered for processing or display.
The second line of a file may define global parameters that are to be used for all regions and annotations in that file, in which case the line starts with the word "global". The parameters set here may also be overridden by keywords in a specific line, in which case the keywords pertain only to that one line.
- Regions: all regions are considered by tasks. They will be displayed by visualization tasks as well as used to create masks, etc., as appropriate.
- Annotations: these are used by display tasks, and are for visual reference only.
Some tasks, like clean, require that a region cannot be entirely outside the image.
Region definitions
All regions lines will follow this general arrangement:
{shape} {additional parameter=value pairs}
The possible parameter/value pairs are described in more detail below. Note that most parameters beyond the shape and its coordinates can be defined globally.
Possible units for coordinates are:
- sexagesimal, e.g. 18h12m24s for right ascension or -03.47.27.1 for declination
- decimal degrees, e.g. 140.0342deg for both RA and Dec
- radians, e.g. 2.37666rad for both RA and Dec
- pixels, e.g. 204pix
Possible units of length are:
- degrees, e.g. 23deg
- arcminutes, e.g. 23arcmin
- arcseconds, e.g. 23arcsec
- radians, e.g. 0.00035rad
- pixels, e.g. 23pix
Units must always be included when defining a region. If any fractional pixel is covered, the entire pixel is used. For purely single-pixel work there are alternate methods which may be preferable to using regions, eg. ia.topixel, ia.toworld, ia.pixelvalue.
See Appendix A for a complete list of allowed units, as defined by the quanta toolkit module.
Allowed shapes
NOTE that the viewer is currently only supporting a subset.
- Rectangular box; the two coordinates are two opposite corners:
box[[x1, y1], [x2, y2]]
- Center box; [x, y] define the center point of the box and [x_width, y_width] the width of the sides:
centerbox[[x, y], [x_width, y_width]]
- Rotated box; [x, y] define the center point of the box; [x_width, y_width] the width of the sides; rotang the rotation angle:
rotbox[[x, y], [x_width, y_width], rotang]
- Polygon; there could be many [x, y] corners; note that the last point
will connect with the first point to close the polygon:
poly[[x1, y1], [x2, y2], [x3, y3], ...]
- Circle; center of the circle [x,y], r is the radius:
circle[[x, y], r]
- Annulus; center of the circle is [x, y], [r1, r2] are inner and outer radii:
annulus[[x, y], [r1, r2]]
- Ellipse; center of the ellipse is [x, y]; semi-major and semi-minor axes are [bmaj, bmin]; position angle of the major axis is pa:
ellipse[[x, y], [bmaj, bmin], pa]
Annotation definitions
In addition to the definitions for regions [above], the following are always treated as annotations:
- Line; coordinates define the end points of the line:
line[[x1, y1], [x2, y2]]
- Vector; coordinates define end points; second coordinate pair is location of tip of arrow:
vector[[x1, y1], [x2, y2]]
- Text; coordinates define leftmost point of text string:
text[[x, y], 'my text']
- Symbol; coordinates define location of symbol (see Appendix A for a list of allowed symbols):
symbol[[x, y], {symbol}]
Global definitions
Definitions to be used throughout the region file are placed on a line beginning with 'global', usually at the top of the file. These definitions may also be used on any individual region or annotation line; in this case, the value defined on that line will override the predefined global (but only for that line). If a 'global' line occurs later in the file, subsequent lines will obey those definitions.
Coordinate reference frame:
- Possible values: J2000, JMEAN, JTRUE, APP, B1950, B1950_VLA, BMEAN, BTRUE, GALACTIC, HADEC, AZEL, AZELSW, AZELNE, AZELGEO, AZELSWGEO, AZELNEGEO, JNAT, ECLIPTIC, MECLIPTIC, TECLIPTIC, SUPERGAL, ITRF, TOPO, ICRS
- Default: image value
coord = J2000
Frequency/velocity axis:
- Possible values: REST, LSRK, LSRD, BARY, GEO, TOPO, GALACTO, LGROUP, CMB
- Default: image value
frame=TOPO
Frequency/velocity range:
- Possible units: GHz, MHz, kHz, km/s, Hz, channel, chan (=channel)
- Default: image range
range=[min, max]
Correlation axis:
- Possible values: I, Q, U, V, RR, RL, LR, LL, XX, XY, YX, YY, RX, RY, LX, LY, XR, XL, YR, YL, PP, PQ, QP, QQ, RCircular, LCircular, Linear, Ptotal, Plinear, PFtotal, PFlinear, Pangle
- Default: all planes present in image
corr=[X, Y]
Velocity calculation:
- Possible values: RADIO, OPTICAL, Z, BETA, GAMMA
- Default: image value
veltype=RADIO
Rest frequency:
- Default: image value
restfreq=1.42GHz
Line characteristics:
- Possible values: any line style recognized by matplotlib: '-'=solid, '--'=dashed, ':'=dotted
- Default: linewidth=1, linestyle='-'
linewidth=1
linestyle='-'
Symbol characteristics:
symsize = 1
symthick = 1
Region, symbol, and text color:
- Possible values: any color recognized by matplotlib, including hex values
- Default: color=green
color=red
Text font characteristics:
- Possible values: see Appendix B.
- 'usetex' is a boolean parameter that determines whether or not the text line should be interpreted as LaTeX, and would require working LaTeX, dvipng, and Ghostscript installations (equivalent to the text.usetex parameter in matplotlib).
font=Helvetica
fontsize=10pt
fontstyle=bold
usetex=True/False
Label position:
- Possible values: 'left', 'right', 'top', 'bottom'
- Default: 'top'
labelpos='right'
Label color:
- Default: color of associated region.
- Allowed values: same as values for region colors.
labelcolor='green'
Label offset:
- Default: [0,0].
- Allowed values: any positive or negative number, in units of pixels.
labeloff=[1, 1]
Allowed additional parameters
These must be defined per region line:
Labels: text label for a region; should be placed so text does not overlap with region boundary
label='string'
"OR/NOT" operators: A "+" at the beginning of a line will flag it with a boolean "OR" (default), and a "-" will flag it with a boolean "NOT". Overlapping regions will be treated according to their sequence in the file; i.e., ((((entireImage OR line1) OR line2) NOT line3) OR line4). This allows some flexibility in building "non-standard" regions. Note that a task (e.g., clean) will still consider all lines: if one wishes to remove a region from consideration, it should be commented out ("#").
- Default: OR (+)
Examples
A file with both global definitions and per-line definitions:
#CRTF0
global coord=B1950_VLA, frame=BARY, corr=[I, Q], color=blue
# A simple circle region:
circle[[18h12m24s, -23d11m00s], 2.3arcsec]
# A box region, this one only for annotation:
ann box[[140.0342deg, -12.34243deg], [140.0360deg, -12.34320deg]]
# A rotated box region, for a particular range of velocities:
rotbox[[12h01m34.1s, 12d23m33s], [3arcmin, 1arcmin], 12deg], range=[-1240km/s, 1240km/s]
# An annular region, overriding some of the global defaults:
annulus[[17h51m03.2s, -45d17m50s], [0.10deg, 4.12deg]], corr=[I,Q,U,V], color=red, label='My label here'
# Cuts an ellipse out of the previous regions, but only for Q and a particular frequency range:
-ellipse[[17:51:03.2, -45.17.50], [0.25deg, 1.34deg], 45rad], range=[1.420GHz, 1.421GHz], corr=[Q], color=green, label='Removed this'
# A diamond marker, in J2000 coordinates:
symbol[[32.1423deg, 12.1412deg], D], linewidth=2, coord=J2000, symsize=2
Appendix A
Allowed units
These are all allowed units, as defined by the quanta toolkit module. All are included for completeness; note that many do not make sense in the context of region files.
==== Prefix ====
E (exa) 1e+18
G (giga) 1000000000
M (mega) 1000000
P (peta) 1e+15
T (tera) 1e+12
Y (yotta) 1e+24
Z (zetta) 1e+21
a (atto) 1e-18
c (centi) 0.01
d (deci) 0.1
da (deka) 10
f (femto) 1e-15
h (hecto) 100
k (kilo) 1000
m (milli) 0.001
n (nano) 1e-09
p (pico) 1e-12
u (micro) 1e-06
y (yocto) 1e-24
z (zepto) 1e-21
==== SI ====
$ (currency) 1 _
% (percent) 0.01
%% (permille) 0.001
A (ampere) 1 A
AE (astronomical unit) 149597870659 m
AU (astronomical unit) 149597870659 m
Bq (becquerel) 1 s-1
C (coulomb) 1 s.A
F (farad) 1 m-2.kg-1.s4.A2
Gy (gray) 1 m2.s-2
H (henry) 1 m2.kg.s-2.A-2
Hz (hertz) 1 s-1
J (joule) 1 m2.kg.s-2
Jy (jansky) 1e-26 kg.s-2
K (kelvin) 1 K
L (litre) 0.001 m3
M0 (solar mass) 1.98891944407e+30 kg
N (newton) 1 m.kg.s-2
Ohm (ohm) 1 m2.kg.s-3.A-2
Pa (pascal) 1 m-1.kg.s-2
S (siemens) 1 m-2.kg-1.s3.A2
S0 (solar mass) 1.98891944407e+30 kg
Sv (sievert) 1 m2.s-2
T (tesla) 1 kg.s-2.A-1
UA (astronomical unit) 149597870659 m
V (volt) 1 m2.kg.s-3.A-1
W (watt) 1 m2.kg.s-3
Wb (weber) 1 m2.kg.s-2.A-1
_ (undimensioned) 1 _
a (year) 31557600 s
arcmin (arcmin) 0.000290888208666 rad
arcsec (arcsec) 4.8481368111e-06 rad
as (arcsec) 4.8481368111e-06 rad
cd (candela) 1 cd
cy (century) 3155760000 s
d (day) 86400 s
deg (degree) 0.0174532925199 rad
g (gram) 0.001 kg
h (hour) 3600 s
l (litre) 0.001 m3
lm (lumen) 1 cd.sr
lx (lux) 1 m-2.cd.sr
m (metre) 1 m
min (minute) 60 s
mol (mole) 1 mol
pc (parsec) 3.08567758065e+16 m
rad (radian) 1 rad
s (second) 1 s
sr (steradian) 1 sr
t (tonne) 1000 kg
==== Custom ====
" (arcsec) 4.8481368111e-06 rad
"_2 (square arcsec) 2.35044305391e-11 sr
' (arcmin) 0.000290888208666 rad
'' (arcsec) 4.8481368111e-06 rad
''_2 (square arcsec) 2.35044305391e-11 sr
'_2 (square arcmin) 8.46159499408e-08 sr
: (hour) 3600 s
:: (minute) 60 s
::: (second) 1 s
Ah (ampere hour) 3600 s.A
Angstrom (angstrom) 1e-10 m
Btu (British thermal unit (Int)) 1055.056 m2.kg.s-2
CM (metric carat) 0.0002 kg
Cal (large calorie (Int)) 4186.8 m2.kg.s-2
FU (flux unit) 1e-26 kg.s-2
G (gauss) 0.0001 kg.s-2.A-1
Gal (gal) 0.01 m.s-2
Gb (gilbert) 0.795774715459 A
Mx (maxwell) 1e-08 m2.kg.s-2.A-1
Oe (oersted) 79.5774715459 m-1.A
R (mile) 0.000258 kg-1.s.A
St (stokes) 0.0001 m2.s-1
Torr (torr) 133.322368421 m-1.kg.s-2
USfl_oz (fluid ounce (US)) 2.95735295625e-05 m3
USgal (gallon (US)) 0.003785411784 m3
WU (WSRT flux unit) 5e-29 kg.s-2
abA (abampere) 10 A
abC (abcoulomb) 10 s.A
abF (abfarad) 1000000000 m-2.kg-1.s4.A2
abH (abhenry) 1e-09 m2.kg.s-2.A-2
abOhm (abohm) 1e-09 m2.kg.s-3.A-2
abV (abvolt) 1e-08 m2.kg.s-3.A-1
ac (acre) 4046.8564224 m2
arcmin_2 (square arcmin) 8.46159499408e-08 sr
arcsec_2 (square arcsec) 2.35044305391e-11 sr
ata (technical atmosphere) 98066.5 m-1.kg.s-2
atm (standard atmosphere) 101325 m-1.kg.s-2
bar (bar) 100000 m-1.kg.s-2
beam (undefined beam area) 1 _
cal (calorie (Int)) 4.1868 m2.kg.s-2
count (count) 1 _
cwt (hundredweight) 50.80234544 kg
deg_2 (square degree) 0.000304617419787 sr
dyn (dyne) 1e-05 m.kg.s-2
eV (electron volt) 1.60217733e-19 m2.kg.s-2
erg (erg) 1e-07 m2.kg.s-2
fl_oz (fluid ounce (Imp)) 2.84130488996e-05 m3
ft (foot) 0.3048 m
fu (flux unit) 1e-26 kg.s-2
fur (furlong) 201.168 m
gal (gallon (Imp)) 0.00454608782394 m3
ha (hectare) 10000 m2
hp (horsepower) 745.7 m2.kg.s-3
in (inch) 0.0254 m
kn (knot (Imp)) 0.514773333333 m.s-1
lambda (lambda) 1 _
lb (pound (avoirdupois)) 0.45359237 kg
ly (light year) 9.46073047e+15 m
mHg (metre of mercury) 133322.387415 m-1.kg.s-2
mile (mile) 1609.344 m
n_mile (nautical mile (Imp)) 1853.184 m
oz (ounce (avoirdupois)) 0.028349523125 kg
pixel (pixel) 1 _
sb (stilb) 10000 m-2.cd
sq_arcmin (square arcmin) 8.46159499408e-08 sr
sq_arcsec (square arcsec) 2.35044305391e-11 sr
sq_deg (square degree) 0.000304617419787 sr
statA (statampere) 3.33564095198e-10 A
statC (statcoulomb) 3.33564095198e-10 s.A
statF (statfarad) 1.11188031733e-12 m-2.kg-1.s4.A2
statH (stathenry) 899377374000 m2.kg.s-2.A-2
statOhm (statohm) 899377374000 m2.kg.s-3.A-2
statV (statvolt) 299.792458 m2.kg.s-3.A-1
u (atomic mass unit) 1.661e-27 kg
yd (yard) 0.9144 m
yr (year) 31557600 s
==== User ====
pix (pixel units) 1
Allowed symbols
'.' point marker ',' pixel marker 'o' circle marker 'v' triangle_down marker '^' triangle_up marker '<' triangle_left marker '>' triangle_right marker '1' tri_down marker '2' tri_up marker '3' tri_left marker '4' tri_right marker 's' square marker 'p' pentagon marker '*' star marker 'h' hexagon1 marker 'H' hexagon2 marker '+' plus marker 'x' x marker 'D' diamond marker 'd' thin_diamond marker '|' vline marker '_' hline marker
Appendix B
Allowed fonts for Linux
"Century Schoolbook L" "Console" "Courier" "Courier 10 Pitch" "Cursor" "David CLM" "DejaVu LGC Sans" "DejaVu LGC Sans Condensed" "DejaVu LGC Sans Light" "DejaVu LGC Sans Mono" "DejaVu LGC Serif" "DejaVu LGC Serif Condensed" "Dingbats" "Drugulin CLM" "East Syriac Adiabene" "Ellinia CLM" "Estrangelo Antioch" "Estrangelo Edessa" "Estrangelo Nisibin" "Estrangelo Nisibin Outline" "Estrangelo Talada" "Fangsong ti" "Fixed [Sony]" "Fixed [Eten]" "Fixed [Misc]" "Fixed [MNKANAME]" "Frank Ruehl CLM" "fxd" "Goha-Tibeb Zemen" "goth_p" "Gothic [Shinonome]" "Gothic [mplus]" "hlv" "hlvw" "KacstArt" "KacstBook" "KacstDecorative" "KacstDigital" "KacstFarsi" "KacstLetter" "KacstPoster" "KacstQura" "KacstQuraFixed" "KacstQuran" "KacstTitle" "KacstTitleL" "Liberation Mono" "Liberation Sans" "Liberation Serif" "LKLUG" "Lohit Bengali" "Lohit Gujarati" "Lohit Hindi" "Lohit Kannada" "Lohit Malayalam" "Lohit Oriya" "Lohit Punjabi" "Lohit Tamil" "Lohit Telugu" "LucidaTypewriter" "Luxi Mono" "Luxi Sans" "Luxi Serif" "Marumoji" "Miriam CLM" "Miriam Mono CLM" "MiscFixed" "Monospace" "Nachlieli CLM" "Nimbus Mono L" "Nimbus Roman No9 L" "Nimbus Sans L" "Nimbus Sans L Condensed" "PakTypeNaqsh" "PakTypeTehreer" "qub" "Sans Serif" "Sazanami Gothic" "Sazanami Mincho" "Serif" "Serto Batnan" "Serto Jerusalem" "Serto Jerusalem Outline" "Serto Mardin" "Standard Symbols L" "sys" "URW Bookman L" "URW Chancery L" "URW Gothic L" "URW Palladio L" "Utopia" "Yehuda CLM"
Allowed fonts for MacOS X
"Abadi MT Condensed Light" "Adobe Caslon Pro" "Adobe Garamond Pro" "Al Bayan" "American Typewriter" "Andale Mono" "Apple Braille" "Apple Chancery" "Apple LiGothic" "Apple LiSung" "Apple Symbols" "AppleGothic" "AppleMyungjo" "Arial" "Arial Black" "Arial Hebrew" "Arial Narrow" "Arial Rounded MT Bold" "Arial Unicode MS" "Arno Pro" "Ayuthaya" "Baghdad" "Baskerville" "Baskerville Old Face" "Batang" "Bauhaus 93" "Bell Gothic Std" "Bell MT" "Bernard MT Condensed" "BiauKai" "Bickham Script Pro" "Big Caslon" "Birch Std" "Blackoak Std" "Book Antiqua" "Bookman Old Style" "Bookshelf Symbol 7" "Braggadocio" "Britannic Bold" "Brush Script MT" "Brush Script Std" "Calibri" "Calisto MT" "Cambria" "Candara" "Century" "Century Gothic" "Century Schoolbook" "Chalkboard" "Chalkduster" "Chaparral Pro" "Charcoal CY" "Charlemagne Std" "Cochin" "Colonna MT" "Comic Sans MS" "Consolas" "Constantia" "Cooper Black" "Cooper Std" "Copperplate" "Copperplate Gothic Bold" "Copperplate Gothic Light" "Corbel" "Corsiva Hebrew" "Courier" "Courier New" "Curlz MT" "DecoType Naskh" "Desdemona" "Devanagari MT" "Didot" "Eccentric Std" "Edwardian Script ITC" "Engravers MT" "Euphemia UCAS" "Eurostile" "Footlight MT Light" "Franklin Gothic Book" "Franklin Gothic Medium" "Futura" "Garamond" "Garamond Premier Pro" "GB18030 Bitmap" "Geeza Pro" "Geneva" "Geneva CY" "Georgia" "Giddyup Std" "Gill Sans" "Gill Sans MT" "Gill Sans Ultra Bold" "Gloucester MT Extra Condensed" "Goudy Old Style" "Gujarati MT" "Gulim" "GungSeo" "Gurmukhi MT" "Haettenschweiler" "Harrington" "HeadLineA" "Hei" "Heiti SC" "Heiti TC" "Helvetica" "Helvetica CY" "Helvetica Neue" "Herculanum" "Hiragino Kaku Gothic Pro" "Hiragino Kaku Gothic ProN" "Hiragino Kaku Gothic Std" "Hiragino Kaku Gothic StdN" "Hiragino Maru Gothic Pro" "Hiragino Maru Gothic ProN" "Hiragino Mincho Pro" "Hiragino Mincho ProN" "Hiragino Sans GB" "Hobo Std" "Hoefler Text" "Impact" "Imprint MT Shadow" "InaiMathi" "Kai" "Kailasa" "Kino MT" "Kokonor" "Kozuka Gothic Pro" "Kozuka Mincho Pro" "Krungthep" "KufiStandardGK" "Letter Gothic Std" "LiHei Pro" "LiSong Pro" "Lithos Pro" "Lucida Blackletter" "Lucida Bright" "Lucida Calligraphy" "Lucida Console" "Lucida Fax" "Lucida Grande" "Lucida Handwriting" "Lucida Sans" "Lucida Sans Typewriter" "Lucida Sans Unicode" "Marker Felt" "Marlett" "Matura MT Script Capitals" "Meiryo" "Menlo" "Mesquite Std" "Microsoft Sans Serif" "Minion Pro" "Mistral" "Modern No. 20" "Monaco" "Monotype Corsiva" "Monotype Sorts" "MS Gothic" "MS Mincho" "MS PGothic" "MS PMincho" "MS Reference Sans Serif" "MS Reference Specialty" "Mshtakan" "MT Extra" "Myriad Pro" "Nadeem" "New Peninim MT" "News Gothic MT" "Nueva Std" "OCR A Std" "Onyx" "Optima" "Orator Std" "Osaka" "Papyrus" "PCMyungjo" "Perpetua" "Perpetua Titling MT" "PilGi" "Plantagenet Cherokee" "Playbill" "PMingLiU" "Poplar Std" "Prestige Elite Std" "Raanana" "Rockwell" "Rockwell Extra Bold" "Rosewood Std" "Sathu" "Silom" "SimSun" "Skia" "Stencil" "Stencil Std" "STFangsong" "STHeiti" "STKaiti" "STSong" "Symbol" "Tahoma" "Tekton Pro" "Thonburi" "Times" "Times New Roman" "Trajan Pro" "Trebuchet MS" "Tw Cen MT" "Verdana" "Webdings" "Wide Latin" "Wingdings" "Wingdings 2" "Wingdings 3" "Zapf Dingbats" "Zapfino"
