### JS9/DS9/Funtools Spatial Regions

In many X-ray astronomical analysis software suites (e.g., fitsio, ciao, funtools), spatial regions allow one to select sections of an image or rows of a table by means of simple geometric shapes. When an image is filtered, only pixels found within these shapes are processed. When a table is filtered, only rows found within these shapes are processed.

In these systems, spatial region filtering is accomplished by means of region specifications. Typically, region specifications use bracket notation appended to the filename of the data being processed:

      funcnts "foo.fits[circle(512,512,100)]"

JS9 implements a subset of the widely-used DS9/Funtools regions syntax, as described below.

### Region Expressions

Spatial region specifications consist of one or more lines containing:

      # comment until end of line
      # each region expression contains shapes and optional local json objects
      [region_expression1] {local json object}  # tags
      [region_expression2] # tags

A single region expression consists of:

      # shape name and parens are required
      # arguments are separated by commas. spaces are optional, as is the + sign
      [+-]shape(val, val, ...)

where regions shapes can be:

      shape:        arguments:
      -----         ----------------------------------------
      annulus       (xcenter, ycenter, inner_radius, outer_radius)
      box           (xcenter, ycenter, xwidth, yheight[, angle])
      circle        (xcenter, ycenter, radius)
      ellipse       (xcenter, ycenter, xwidth, yheight[, angle])
      text          (x1, x2, text)
      point         (x1, y1)
      polygon       (x1, y1, x2, y2, ..., xn yn)

Note that other keyword keywords (e.g., the DS9 "global" keyword and DS9/Funtools region shapes not yet implemented in JS9) are silently ignored.

All arguments to regions are real values; integer values are automatically converted to real where necessary. All angles are in degrees and run from the positive image x-axis to the positive image y-axis.

### Region Exclusion

Shapes also can be globally excluded from a region descriptor by using a minus sign before a region:

      operator      arguments:
      --------      -----------
      -             Globally exclude the region expression following '-' sign
                    from ALL regions specified in this file

### Local Properties of Regions

DS9/Funtools regions utilize a key=value syntax within an in-line comment to specify secondary properties such as color. It also uses single tokens in the in-line comments to specify tags such as "source" and "background".

JS9 retains the use of comments to specify tags, but utilizes a JSON object to specify secondary properties. This optional object follows the region specification:

        point(4300.00, 4250.00) {"color": "red"} # background,include
        point(350.897859, 58.835164) {"ptshape": "circle", "ptsize": 5}

See the JS9.Regions.opts object in the JS9 source code for a list of properties that can be passed in this JSON object.

### 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 position and size values are interpreted. For this purpose, the following keywords are recognized:

      name                  description
      ----                  ------------------------------------------
      physical              pixel coords of original file using LTM/LTV
      image                 pixel coords of current file
      FK4                   sky coordinate system
      FK5                   sky coordinate system
      galactic              sky coordinate system
      ecliptic              sky coordinate system
      ICRS                  currently same as J2000

If no coordinate system is specified, physical is assumed. The coordinate system specifier should appear at the beginning of the region description, separated by semi-colon, or on a separate line. Note that multiple coordinate systems can be in the same specifier. Each one pertains to the region following until the next coordinate system is defined:

      # Region file format: JS9 version 1.0
      ICRS
      point(23:23:27.815, +58:48:42.017)
      box(23:23:27.815, +58:48:42.017, 29.51", 29.51", 0.000)
      physical
      ellipse(4300.00, 4250.00, 30.00, 20.00, 0.00)
      box(4300.00, 4250.00, 60.00, 60.00, 0.00)
      ICRS
      circle(350.897859, 58.835164, 0.76')
      ellipse(350.897859, 58.835164, 14.76", 9.84", 0.000)

### Specifying Positions, Sizes, and Angles

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    description
      ------------------    ------------------------------
      [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        description
      --------------        -----------
      [num]                 context-dependent (see below)
      [num]"                arc seconds
      [num]'                arc minutes
      [num]d                degrees
      [num]r                radians

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 all means that for IMAGE and PHYSICAL systems, pure numbers are pixels. Otherwise, for all systems, pure numbers are degrees.

### Examples

        # js9 region format, properties contained in json
        ellipse(23:23:22.179, +58:48:10.542, 40", 20", 60) {"text": "json ellipse test", "textOpts": {"color": "yellow", "fontSize": 16, "fontStyle": "italic", "fontWeight": "bold"}, "color": "violet"} # json test tag, another tag

        # ds9 format, properties contained in comment string
        box(23:23:35.486, +58:50:03.146, 40", 20", 30) # width=4 text={ds9 box test} dash=1 color=red fixed=1 rotate=0 tag="ds9 test tag"

        # hybrid js9/ds9 format
        circle(23:23:29.526, +58:49:09.56, 14.756997") {"strokeWidth": 1, "strokeDashArray": [3,1], "transparentCorners": true} # text="hybrid circle test" tag="ds9 test tag" tag="json test tag"

##### Last updated: February 2, 2017