# coyote: FIND_BOUNDARY

- coyote/Graphics
- coyote/Mathematics
- [Source code]

NAME

      FIND_BOUNDARY

PURPOSE

      This program finds the boundary points about a region of interest (ROI)
      represented by pixel indices. It uses a "chain-code" algorithm for finding
      the boundary pixels.

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com

CATEGORY

      Graphics, math.

CALLING SEQUENCE

      boundaryPts = Find_Boundary(indices, XSize=xsize, YSize=ysize)

OPTIONAL INPUTS

      indices - A 1D vector of pixel indices that describe the ROI. For example,
           the indices may be returned as a result of the WHERE function.

OUTPUTS

      boundaryPts - A 2-by-n points array of the X and Y points that describe the
           boundary. The points are scaled if the SCALE keyword is used.

INPUT KEYWORDS

      SCALE - A one-element or two-element array of the pixel scale factors, [xscale, yscale],
           used to calculate the perimeter length or area of the ROI. The SCALE keyword is
           NOT applied to the boundary points. By default, SCALE=[1,1].
      XSIZE - The X size of the window or array from which the ROI indices are taken.
           Set to !D.X_Size by default.
      YSIZE - The Y size of the window or array from which the ROI indices are taken.
           Set to !D.Y_Size by default.

OUTPUT KEYWORDS

      AREA - A named variable that contains the pixel area represented by the input pixel indices,
           scaled by the SCALE factors.
      CENTER - A named variable that contains a two-element array containing the center point or
           centroid of the ROI. The centroid is the position in the ROI that the ROI would
           balance on if all the index pixels were equally weighted. The output is a two-element
           floating-point array in device coordinate system, unless the SCALE keyword is used,
           in which case the values will be in the scaled coordinate system.
      PERIM_AREA - A named variable that contains the (scaled) area represented by the perimeter
           points, as indicated by John Russ in _The Image Processing Handbook, 2nd Edition_ on
           page 490. This is the same "perimeter" that is returned by IDLanROI in its
           ComputeGeometry method, for example. In general, the perimeter area will be
           smaller than the pixel area.
      PERIMETER - A named variable that will contain the perimeter length of the boundary
           upon returning from the function, scaled by the SCALE factors.
      LE:
      LoadCT, 0, /Silent
      image = BytArr(400, 300)+125
      image[125:175, 180:245] = 255B
      indices = Where(image EQ 255)
      Window, XSize=400, YSize=300
      TV, image
      PLOTS, Find_Boundary(indices, XSize=400, YSize=300, Perimeter=length), $
          /Device, Color=cgColor('red')
      Print, length
          230.0

MODIFICATION HISTORY

      Written by David W. Fanning, April 2002. Based on an algorithm written by Guy
      Blanchard and provided by Richard Adams.
      Fixed a problem with distinction between solitary points and
         isolated points (a single point connected on a diagonal to
         the rest of the mask) in which the program can't get back to
         the starting pixel. 2 Nov 2002. DWF
      Added the ability to return the perimeter length with PERIMETER and
          SCALE keywords. 2 Nov 2002. DWF.
      Added AREA keyword to return area enclosed by boundary. 2 Nov 2002. DWF.
      Fixed a problem with POLYFILLV under-reporting the area by removing
          POLYFILLV and using a pixel counting method. 10 Dec 2002. DWF.
      Added the PERIM_AREA and CENTER keywords. 15 December 2002. DWF.
      Replaced the cgErrorMsg routine with the latest version. 15 December 2002. DWF.
      Fixed a problem in which XSIZE and YSIZE have to be specified as integers to work. 6 March 2006. DWF.
      Fixed a small problem with very small ROIs that caused the program to crash. 1 October 2008. DWF.
      Modified the algorithm that determines the number of boundary points for small ROIs. 28 Sept 2010. DWF.
      Modified the algorithm that determines if we are "home" to correct a problem discovered by Peter Vogt in
         which small regions connect to larger regions by pixel corners only was cut off. 12 Mar 2014. Peter Vogt.