USAGE: xtract [-p procedure] [-c coords] [-b bgcolor] [-e extend] [-t1 thresh1] [-t2 thresh2] [-t3 thresh3] [-f filtsize] [-a aspect] [-w width] [-h height] [-d dimension] [-s scolor] [-L linewidth] [-m mcolor] [u unrotate] [-C crop] [-F fuzzval] [-R rotate] [-I info] [-S show] infile outfile

USAGE: xtract [-help]

-p ... procedure ... procedure (technique) for processing; choices are: deskew,
.................... unrotate, mask or perspective; default=perspective
-c ... coords ...... pixel coordinate to extract background color;
.................... may be expressed as gravity value (e.g. northwest) or
.................... as "x,y" value; default is 0,0
-b ... bcolor ...... background color outside the quadrilateral region;
.................... any valid IM color; default determined by coords argument
-e ... extend ...... extend (pad) the input with background color as preprocessing
.................... to keep corners away from bounding edges of input image;
.................... integer>=0; default=10
-t1 ... thresh1 .... lower Canny edge detector threshold value in percent;
.................... 0<=integer<=100; default=10
-t2 ... thresh2 .... upper Canny edge detector threshold value in percent;
.................... 0<=integer<=100; default=75; nominal 75-90; smaller values
.................... include more edges
-t3 ... thresh3 .... Hough line detector threshold value in percent; 0<=integer<=100;
.................... default=10; percent of longest dimension of input image;
.................... too large values remove longest lines; typically 5-20%
-f1 ... filtsize ... Hough line detector filter size in pixels; integer>=0;
.................... default=15; needs to be larger for larger images; typically 9-15;
.................... larger values condense close, nearly parallel edges
-a ... aspect ...... desired width/height aspect ratio; float>0; or "edges"
.................... or "points"; default=edges; used only for procedure=unperspective
.................... default will be computed automatically
-w ... width ....... desired width of output in pixels; integer>0; default determined
.................... automatically from dimension parameter below;
.................... only one of width or height may be specified
-h ... height ...... desired height of output in pixels; integer>0; default determined
.................... automatically from dimension parameter below;
.................... only one of width or height may be specified
-d ... dimension ... output dimension method; choices are: el
.................... (length of longest edge of quadrilaterl, bh (quadrilateral
.................... bounding box height), bw (quadrilateral bounding box width),
.................... h (input image height), w (input image width); default=el
-s ... scolor ...... stroke color for showing the Hough lines on an ancillary image
.................... when -S show != none, described below; any valid IM color;
.................... default=red
-L ... linewidth ... linewidth of stroke for showing the Hough lines on an ancillary
.................... image when -S show != none, described below; integer>=0; default=2
-m ... mcolor ...... desired masking background color to show outside the extracted
.................... quadrilateral when procedure=mask; any valid IM color;
.................... default=none
-u ... unrotate .... unrotate the masked result and trim to its bounding box when
.................... procedure=mask; choices are: yes or no; default=no;
.................... requires separate unrotate script
-C ... crop ........ crop (trim) the masked result (without unrotating) when
.................... procedure=mask; choices are: yes or no; default=no
-F ... fuzzval ..... fuzzvalue to use to extract the background when unrotate=yes;
.................... 0<=integer<=100; default=10
-R ... rotate ...... rotate the image in 90 degree amounts as postprocessing;
.................... choices are: 0, 90, 180, 270, -90; default=0
-I ... info ........ list various information to the terminal depending upon
.................... procedure, including: rotation angle, crop box, aspect ratio
.................... and/or control points used for perspective correction
-S ... show ........ show ancillary images for deskewed/unrotated image,
.................... Canny edges, Hough lines superimposed on image; choices are:
.................... none, view (to display) or save (to disk); default=none

PURPOSE: To use Hough lines to extract and rectify a quadrilateral area from an image.

DESCRIPTION: XTRACT attempts to extract and correct orientation and/or perspective in an image using the Canny edge detector followed by the Hough line detector to find the four sides of a quadrilateral region of an image inside a background color. There are four approaches that may be used.

If the image has a nearly solid color background and the quadrilateral is a rectangle that is rotate by 5 degrees or less, one can use the procedure=deskew.

If the image has a nearly solid color background and the quadrilateral is a rectangle that is rotate by more than 5 degrees, one can use the procedure=unrotate. This will estimate the rotation angle from the orientation of longest Hough line as determined by the Hough accumulator value.

Otherwise, one can use procedure=unperspective to process the image. This will attempt to correct the perspective distortion. However, it needs to use the aspect ratio of the corrected image. One may provide the aspect ratio as a float value or let the script attempt to estimate the aspect ratio. There are two approaches that may be use for the estimation. One is to use the lengths of the edges of the quadrilateral as determined by the Hough line intersection. The other approach is to use the Hough line intersection vertices. The latter is more subject to inaccurate estimations.

Lastly, one can just mask the quadrilateral region with an option to unrotate and trim the image or just trim the image to its bounding box. If unrotate=yes, then my separate script, unrotate, will be needed.

The script works best when the quadrilateral area is cleanly separated by good contrast from the background area and contains no very long, high contrast edges in it. The three most important arguments are: thresh2, thresh3 and filtsize.

The script will error out, if fewer than 4 edges are extracted. The script will use the longest 4 edges, but will error out, if other than 4 intersection points are located within the bounds of the input image.

ARGUMENTS:

-p procedure ... PROCEDURE (technique) for processing. Choices are: deskew, unrotate, mask or perspective. The default=perspective.

-c coords ... COORDS is any location within the input image for the algorithm to find the background color. It may be specified in terms of gravity parameters (NorthWest, North, NorthEast, East, SouthEast, South, SouthWest or West) or as a pixel coordinate "x,y". The default is the upper left corner = NorthWest = "0,0".

-b bcolor ... BCOLOR is the background color outside the quadrilateral region. Any valid IM color is permitted. The default will be determined by the coords argument.

-e extend ... EXTEND (pad) the input with background color as a preprocessing step in order to keep the corners of the quadrilateral area away from bounding edges of input image. Values are integer>=0. The default=10.

-t1 thresh1 ... THRESH1 is the lower Canny edge detector threshold value in percent. Values are 0<=integers<=100. The default=10.

-t2 thresh2 ... THRESH2 is the upper Canny edge detector threshold value in percent. Values are 0<=integers<=100. The default=75. Typical values are in the range 75-90. Smaller values will include more edges.

-t3 thresh3 ... THRESH3 is the Hough line detector threshold value in percent of the longest dimension of input image converted to pixels. Values are 0<=integers<=100. The default=10. Too large values remove longer lines. Typical values are in the range of 5-20.

-f1 filtsize ... FILTSIZE is the Hough line detector filter size in pixels. Value are integers>=0. The default=15. Values needs to be larger for larger image dimensions. Typical values are in the range 9-15. Larger values condense close, nearly parallel edges.

-a aspect ... ASPECT is the desired width/height aspect ratio. Values are either floats>0; or "edges" or "points". The default will be computed automatically using the lengths of the four quadrilateral edges. Aspect is used only for procedure=unperspective.

-w width ... WIDTH is the desired width of the output. Values are integers>0. The default is determined automatically from the dimensions parameter below. Only one of width or height may be specified. Note: the output size will only be close to the value specified.

-h height ... HEIGHT is the desired height of the output. Values are integers>0. The default is determined automatically from the dimensions parameter below. Only one of width or height may be specified. Note: the output size will only be close to the value specified.

-d dimensions ... DIMENSIONS specifies how to compute the output dimension. Choices are: el (length of the longest edge of the quadrilateral), bh (quadrilateral bounding box height), bw (quadrilateral bounding box width), h (input image height), or w (input image width). The default=el.

-s scolor ... SCOLOR is the stroke color used for showing the Hough lines on an ancillary image when -S show != none, as described below. Any valid IM color is allowed. The default=red.

-L linewidth ... LINEWIDTH of the stroke color for showing the Hough lines on an ancillary image when -S show != none, described below. Values are integers>=0. The default=2.

-m mcolor ... MCOLOR is the desired masking background color to show outside the extracted quadrilateral when procedure=mask. Any valid IM color is allowed. The default=none.

-u unrotate ... UNROTATE the masked result and trim to its bounding box when procedure=mask. The choices are: yes or no. The default=no. Note that this requires my separate unrotate script.

-C crop ... CROP (trim) the masked result (without unrotating) when procedure=mask. The choices are: yes or no. The default=no.

-F fuzzval ... FUZZVAL is the fuzz value to use to extract the background when unrotate=yes. Values are 0<=integers<=100. The default=10.

-R rotate ... ROTATE the output image in 90 degree amounts as a postprocessing step. The choices are: 0, 90, 180, 270, -90. The default=0.

-I info ... INFO list various information to the terminal depending upon procedure, including: rotation angle, crop box, aspect ratio and/or control points used for the perspective correction.

-S show ... SHOW ancillary images: deskewed/unrotated image, Canny edge image, and Hough lines superimposed on input image. Choices are: none, view (to display) or save (to disk). The default=none.

REFERENCES for aspect=points:
http://www.sagenb.org/home/pub/704/
http://research.microsoft.com/users/zhang/Papers/WhiteboardRectification.pdf
http://research.microsoft.com/en-us/um/people/zhang/papers/tr03-39.pdf

REQUIREMENTS: Imagemggick 6.8.9-0 is needed by the Canny edge detector. The argument -u unrotate requires my unrotate script.

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.