%N boxes %F $MIR/src/subs/boxes.for
%D Summary of region of interest routines.
%P mjs
%: region-of-interest
%B
  This collection of routines allows the user to specify a fairly
  arbitrary region of interest, and for the programmer to retrieve
  these specifications in a reasonably convenient form.  There
  are six programmer callable routines:

       subroutine BoxInput(key,file,boxes,maxboxes)
       subroutine BoxMask(tno,boxes,maxboxes)
       subroutine BoxSet(boxes,naxis,nsize,flags)
       subroutine BoxDef(boxes,naxis,blc,trc)
       subroutine BoxInfo(boxes,naxis,blc,trc)
       subroutine BoxBound(boxes,shape,naxis,type,blx,trc)
       logical function BoxRect(boxes)
       subroutine BoxRuns(naxis,plane,flags,boxes,
    *                  runs,maxruns,nruns,xminv,xmaxv,yminv,ymaxv)

  BoxInput     This reads the region of interest from the task
               parameters.
  BoxMask      "AND" in a mask from a data file.
  BoxSet       The programmer calls this to indicate the size of the
               image of interest.
  BoxInfo      Returns information about the region currently selected.
  BoxRect      This returns .true. if the selected region is purely
               rectangular (i.e. describable by blc and trc).
  BoxRuns      The programmer calls this to retrieve the region-of-
               interest selected for a particular plane.

  The BOX routines work by reading the region specified on the command
  line and breaking it into an intermediate form, stored in the "boxes"
  array.  This intermediate form consists of a number of subregion
  specifications which are ANDed and ORed together to produce the
  output region.  The subregions can consist of IMAGE (a rectangular
  subregion of a range of planes), BOX (a number of rectangular
  subregions of a range of planes), POLY (a polygonal region of a range
  of planes) and MASK (an arbitrary region, specified by a mask file).
  A positive value (the norm) indicates the subregion is "ORed",
  whereas a negative value (rare) indicates it is "ANDed".  Each shape
  is described by XMIN,XMAX,YMIN,YMAX,ZMIN,ZMAX which gives the cube
  which bounds the shape.  In some cases these are unknown, if so they
  are set to zero.

  Some shapes require extra DATA (the size of which is given by SIZE):
    BOX  This requires the blc and trc for the corners of the boxes,
         stored as (xmin,ymin),(xmax,ymax). For N boxes, SIZE=4*N.
         The boxes are sorted in increasing order of xmin.
    POLY This also gives the (x1,y1),(x2,y2) coordinate pair of each of
         the line segments which make the polygon (except horizontal
          segments are discarded).  For a poly made of N (non-
          horizontal) line segments, SIZE=4*N.  The line segments are
          sorted in increasing order of min(x1,x2).
    MASK Additional info is the handle of the mask file.
    PERC This requires the percentage of the x and y axis to select,
         SIZE=2.        

  The routine BoxRuns returns the region of a particular plane that was
  selected. This is returned in "runs", which is a table of entries of
  (j,xmin,xmax). One entry indicates that
  pixels (xmin,j) to (xmax,j) are selected. There may be multiple (or
  zero) entries for a particular value of j, though all entries are
  non-overlapping. The table is in increasing j and xmin.

  History:
    Refer to the RCS log, v1.1 includes prior revision information.

  CARMA Customizations:

  2011-Jul-13  pkgw  Add box(m) shorthand for box(-m,-m,m,m)

 $Id$
