Region Files

CASA Region Text Files usage and definition

Regions (region)

The region parameter points to a CASA region which can be directly specified or listed in a ImageRegion file. An ImageRegion file can be created with the CASA viewer’s region manager, or directly using the CASA region file (crtf) syntax. Typically ImageRegion files will have the suffix ".crtf" for CASA Region Text Format.

For example:

region='circle[[18h12m24s, -23d11m00s], 2.3arcsec]'

or

region='myimage.im.crtf'

to specify a region file. For the most part, the region parameter in tasks only accepts strings (e.g. file names, region shape descriptions) while the region parameter in ia tool methods only accepts python region dictionaries (e.g. produced using the rg tool).

 

Alert: When both the region parameter and any of box/chans/stokes are specified simultaneously, the task may perform unwanted selections. While it is safest to only specify one of these (sets of) parameters, the following rules apply:

For image analysis tasks and tool methods which also accept the box, chans, and/or stokes parameters, the following rules apply if the region parameter is specified:

  • If region is specified as a python dictionary (eg such as various rg tool methods return), a binary region file, or a region-in-image, then it is not permissable to specify any of the box, chans, or stokes parameters.
  • If the region parameter is specified to be a CRTF file name, or a CRTF region
    string, the following rules apply:
    • If box is specified, the resulting selection is the union of the box specification with any regions in the CRTF file/string. This is the equivalent of translating the box specification into the equivalent "box" CRTF specification and prepending that specification to the specified CRTF file/string in the region parameter.
    • If chans is specified, it must be able to be represented as a single contiguous range of channels. In this case, the chans specification overrides any global or per-region range specification in the CRTF file/string, and is used as the global spectral range selection for all regions in the CRTF file/string.
    • If stokes is specified, this specification overrides any global or per-region corr specification in the CRTF file/string, and is used as the global correlation selection for all regions in the CRTF file/string.

Alert: Some region file specifications are not (yet) recognized by the viewer.