CASA Region Format

Overview

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 first 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.

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
• pixels, e.g. 204pix

Possible units of length are:

• degrees, e.g. 23deg
• arcminutes, e.g. 23arcmin
• arcseconds, e.g. 23arcsec
• pixels, e.g. 23pix

Units must always be included when defining a region.

Allowed shapes

• Rectangular box:

box[[x1, y1], [x2, y2]]   
# the two coordinates are two opposite corners

• Center box:

centerbox[[x, y], [x_width, y_width]]   
# [x, y] define the center point of the box and 
[x_width, y_width] the width of the sides

• Rotated box:

rotbox[[x, y], [x_width, y_width], rotang]  
# [x, y] define the center point of the box; [x_width, y_width] 
the width of the sides; rotang the rotation angle

• Polygon:

poly[[x1, y1], [x2, y2], [x3, y3], ...]    
# there could be many [x, y] corners; note that the last point 
will connect with the first point to close the polygon

• Circle:

circle[[x, y], r]  
# center of the circle [x,y], r is the radius

• Annulus:

annulus[[x, y], [r1, r2]] 
# center of the circle is [x, y], [r1, r2] are inner and outer 
radii

• Ellipse:

ellipse[[x, y], [bmaj, bmin], pa]   
# center of the ellipse is [x, y]; semi-major and semi-minor axes 
are [bmaj, bmin]; position angle of the major axis is pa

Annotation definitions

In addition to the definitions for regions [above], the following are always treated as annotations:

Line: line[[x1, y1], [x2, y2]]   # coordinates define the end points of the line

Vector: vector[[x1, y1], [x2, y2]]  # coordinates define end points; second coordinate pair is location of tip of arrow

Text: text[[x, y], 'my text']  # coordinates define leftmost point of text string

Symbol: symbol[[x, y], {symbol}]  # coordinates define location of symbol; any matplotlib symbol is allowed: '.'    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

Global definitions

Global definitions are placed on a line beginning with 'global', usually at the top of the region file.  They also may be used on any region or annotation line [the aforementioned additional parameter=value pairs]; 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. Allowed definitions are (taken from Measures definitions where possible):

Coordinate reference frame: coord=J2000 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

Frequency/velocity axis: frame=TOPO Possible values: REST, LSRK, LSRD, BARY, GEO, TOPO, GALACTO, LGROUP, CMB Default: image value

Frequency/velocity range: range=[min, max] Possible units: GHz, MHz, kHz, km/s, Hz, channel Default: image range

Correlation axis: corr=[X, Y]   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

Velocity calculation: veltype=RADIO   Possible values: RADIO, OPTICAL, Z, BETA, GAMMA Default: image value

Rest frequency: restfreq=1.42GHz Default: image value

Line characteristics: linewidth=1 linestyle='-' Possible values: any line style recognized by matplotlib: '-'=solid, '--'=dashed, '-.'=dot-dashed, ':'=dotted Default: linewidth=1, linestyle='-'

Symbol characteristics: symsize = 1 symthick = 1

Region, symbol, and text color: color=red Possible values: any color recognized by matplotlib, including hex values Default: color=green

Text font characteristics: font=Helvetica fontsize=10pt fontstyle=bold usetex=True/False Possible values: those available in matplotlib. The '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).

Allowed additional parameters

These must be defined per region line:

Labels: label='string'   # text label for a region; should be placed so text does not overlap with region boundary

"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:

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