The regions filtering library and associated programs

HTML documentation, available in the doc directory, is viewable
at http://js9.si.edu/regions/reghelp.html.

In astronomical data analysis, it often is useful to select spatial
regions of an image for detailed processing. The regions library
provides support for filtering FITS images and binary tables using
simple geometric shapes, including boolean operations between
shapes. The regcnts program uses this library to calculate
background-subtracted counts in regions.

For example, given a FITS image or binary table, you can specify an image
filters using shapes such as circles and annuli:

    $ regdisp snr.fits "circle 512 512 5"
    regions: circle 512 512 5
    .............
    .............
    ....11111....
    ...1111111...
    ..111111111..
    ..111111111..
    ..111111111..
    ..111111111..
    ..111111111..
    ...1111111...
    ....11111....
    .............
    .............
    LL corner: 506,506
    UR corner: 518,518
    
    $ regdisp snr.fits "annulus 512 512 10 12"
    regions: annulus 512 512 10 12
    ...........................
    ...........................
    .........111111111.........
    .......1111111111111.......
    ......111.........111......
    .....111...........111.....
    ....11...............11....
    ...111...............111...
    ...11.................11...
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ..11...................11..
    ...11.................11...
    ...111...............111...
    ....11...............11....
    .....111...........111.....
    ......111.........111......
    .......1111111111111.......
    .........111111111.........
    ...........................
    ...........................
    LL corner: 499,499
    UR corner: 525,525

Then you can run regcnts to find the background-subtracted counts in the 
circle, with the background coming from the annulus:

    regcnts snr.fits "circle 512 512 5" "annulus 512 512 10 12"
    # source
    #   data_file:		snr.fits
    #   arcsec/pixel:	8
    # background
    #   data_file:		snr.fits
    # column units
    #   area:		arcsec**2
    #   surf_bri:		cnts/arcsec**2
    #   surf_err:		cnts/arcsec**2

    # background-subtracted results
     reg   net_counts     error   background    berror      area  surf_bri  surf_err
    ---- ------------ --------- ------------ --------- --------- --------- ---------
       1       89.500    23.713      310.500    12.740   4416.00     0.020     0.005

    # source_region(s):
    # circle 512 512 5

    # source_data
     reg       counts    pixels
    ---- ------------ ---------
       1      400.000        69

    # background_region(s)
    # annulus 512 512 10 12

    # background_data
     reg       counts    pixels
    ---- ------------ ---------
    all       594.000       132

Region specification supports WCS units, include and exclude regions,
file-based input, boolean operations between regions and a host of
other capabilities. DS9 and JS9 regions can be input directly into regcnts.

    $ regcnts snr.fits \
      'fk5;annulus(23:01:08.159,+58:52:55.31,0",40",80",120",160",200",240",280",320",360",400")' \
      'fk5;circle(22:57:49.696,+58:55:46.78,322.587")'
    # source
    #   data_file:		snr.fits
    #   arcsec/pixel:	8
    # background
    #   data_file:		snr.fits
    # column units
    #   area:		arcsec**2
    #   surf_bri:		cnts/arcsec**2
    #   surf_err:		cnts/arcsec**2

    # background-subtracted results
     reg   net_counts     error   background    berror      area  surf_bri  surf_err
    ---- ------------ --------- ------------ --------- --------- --------- ---------
       1     1160.505    34.118        3.495     0.226   4800.00     0.242     0.007
       2     1796.003    42.515       10.997     0.711  15104.00     0.119     0.003
       3      793.734    28.520       18.266     1.182  25087.99     0.032     0.001
       4      425.464    21.301       25.536     1.652  35071.99     0.012     0.001
       5      324.382    19.012       32.618     2.110  44799.99     0.007     0.000
       6      366.740    20.342       40.260     2.604  55295.99     0.007     0.000
       7      431.911    22.129       48.089     3.111  66047.99     0.007     0.000
       8      411.387    21.874       54.613     3.533  75007.98     0.005     0.000
       9      520.745    24.479       62.255     4.027  85503.98     0.006     0.000
      10      564.035    25.552       68.965     4.461  94719.98     0.006     0.000

    # source_region(s):
    # fk5;annulus(23:01:08.159,+58:52:55.31,0",40",80",120",160",200",240",280",320",360",400")

    # source_data
     reg       counts    pixels
    ---- ------------ ---------
       1     1164.000        75
       2     1807.000       236
       3      812.000       392
       4      451.000       548
       5      357.000       700
       6      407.000       864
       7      480.000      1032
       8      466.000      1172
       9      583.000      1336
      10      633.000      1480

    # background_region(s)
    # fk5;circle(22:57:49.696,+58:55:46.78,322.587")

    # background_data
     reg       counts    pixels
    ---- ------------ ---------
    all       239.000      512

See INSTALL for installation instructions, but it's the standard GNU build
(along with the requirement to use --with-cfitsio to specify the FITS library):

    ./configure --with-cfitsio=[cfitsio_base]   # site-specific configuration
    make			                # build the software
    make install		                # install it
    make clean		                        # clean up

The Regions package is distributed under the terms of The MIT License.