1 files changed, 203 insertions, 0 deletions
diff --git a/funtools/doc/pod/regbounds.pod b/funtools/doc/pod/regbounds.pod
new file mode 100644
index 0000000..c63a0bd
--- /dev/null
+++ b/funtools/doc/pod/regbounds.pod
@@ -0,0 +1,203 @@
+=pod
+
+=head1 NAME
+
+
+
+B<RegBounds: Region Boundaries>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+Describes how spatial region boundaries are handled.
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+
+The golden rule for spatial region filtering was first enunciated by
+Leon VanSpeybroeck in 1986:
+
+
+Each photon will be counted once, and no photon will be counted
+more than once.
+
+
+This means that we must be careful about boundary
+conditions.  For example, if a circle is contained in an annulus such
+that the inner radius of the annulus is the same as the radius of the
+circle, then photons on that boundary must always be assigned to one
+or the other region. That is, the number of photons in both regions
+must equal the sum of the number of photons in each region taken
+separately.
+
+With this in mind, the rules for determining whether a boundary image
+pixel or table row are assigned to a region are defined below.
+
+B<Image boundaries : radially-symmetric shapes (circle, annuli, ellipse)>
+
+For image filtering, pixels whose center is inside the boundary are
+included.  This also applies non-radially-symmetric shapes.  When a
+pixel center is exactly on the boundary, the pixel assignment rule is:
+
+
+
+=over 4
+
+
+
+
+=item *
+
+the outer boundary of a symmetric shape does not include such pixels
+
+
+=item *
+
+the inner boundary of a symmetric shape (annulus) includes such pixels
+
+
+=back
+
+
+
+In this way, an annulus with radius from 0 to 1, centered exactly on a
+pixel, includes the pixel on which it is centered, but none of its
+neighbors.
+
+These rules ensure that when defining concentric shapes, no pixels are
+omitted between concentric regions and no pixels are claimed by two
+regions.  When applied to small symmetric shapes, the shape is less
+likely to be skewed, as would happen with non-radially-symmetric
+rules.  These rules differ from the rules for box-like shapes, which
+are more likely to be positioned adjacent to one another.
+
+B<Image Boundaries: non-radially symmetric shapes (polygons, boxes)>
+
+For image filtering, pixels whose center is inside the boundary are
+included. This also applies radially-symmetric shapes.  When a pixel
+center is exactly on the boundary of a non-radially symmetric region,
+the pixel is included in the right or upper region, but not the left
+or lower region.  This ensures that geometrically adjoining regions
+touch but don't overlap.
+
+B<Row Boundaries are Analytic>
+
+When filtering table rows, the boundary rules are the same as for
+images, except that the calculation is not done on the center of a
+pixel, (since table rows, especially X-ray events rows, often have
+discrete, floating point positions) but are calculated exactly. That
+is, an row is inside the boundary without regard to its integerized
+pixel value.  For rows that are exactly on a region boundary, the
+above rules are applied to ensure that all rows are counted once and
+no row is counted more than once.
+
+
+Because row boundaries are calculated differently from image boundaries,
+certain programs will give different results when filtering the same
+region file. In particular, fundisp/funtable (which utilize analytic
+row filtering) perform differently from funcnts (which performs image
+filtering, even on tables).
+
+B<Image Boundaries vs. Row Boundaries: Practical Considerations>
+
+
+You will sometimes notice a discrepancy between running funcnts on an
+binary table file and running fundisp on the same file with the same filter.
+For example, consider the following:
+
+  fundisp test1.fits"[box(4219,3887,6,6,0)]" | wc
+  8893  320148 3752846
+
+Since fundisp has a 2-line header, there are actually 8891 photons
+that pass the filter.  But then run funtable and select only the
+rows that pass this filter, placing them in a new file:
+
+  ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits
+
+Now run funcnts using the original filter on the derived file:
+
+  ./funcnts test2.fits "physical; box(4219,3887,6,6,0)"
+
+  [... lot of processed output ...]
+
+  # the following source and background components were used:
+  source region(s)
+  ----------------
+  physical; box(4219,3887,6,6,0)
+ 
+   reg       counts    pixels
+  ---- ------------ ---------
+     1     7847.000        36
+
+There are 1044 rows (events) that pass the row filter in fundisp (or
+funtable) but fail to make it through funcnts. Why?
+
+
+The reason can be traced to how analytic row filtering (fundisp, funtable)
+differs from integerized pixel filtering(funcnts, funimage). Consider the
+region:
+
+  box(4219,3887,6,6,0)
+
+Analytically (i.e., using row filtering), positions will pass this
+filter successfully if:
+
+  4216 <= x <= 4222
+  3884 <= y <= 3890
+
+For example, photons with position values of x=4216.4 or y=3884.08 will pass.
+
+
+Integerized image filtering is different in that the pixels that will
+pass this filter have centers at:
+
+  x = 4217, 4218, 4219, 4220, 4221, 4222
+  y = 3885, 3886, 3887, 3888, 3889, 3890
+
+Note that there are 6 pixels in each direction, as specified by the region.
+That means that positions will pass the filter successfully if:
+
+  4217 <= (int)x <= 4222
+  3885 <= (int)y <= 3890
+
+Photons with position values of x=4216.4 or y=3884.08 will NOT pass.
+
+
+Note that the position values are integerized, in effect, binned into
+image values.  This means that x=4222.4 will pass this filter, but not
+the analytic filter above. We do this to maintain the design goal that
+either all counts in a pixel are included in an integerized filter, or
+else none are included.
+
+
+[It could be argued that the correct photon limits for floating point
+row data really should be:
+
+  4216.5 <= x <= 4222.5
+  3884.5 <= y <= 3890.5
+
+since each pixel extends for .5 on either side of the center. We chose
+to the maintain integerized algorithm for all image-style filtering so
+that funcnts would give the exact same results regardless of whether
+a table or a derived non-blocked binned image is used.]
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+
+=cut