Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial (non-profit) use, ONLY.

    For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

    If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

    Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

    Please read the Pointers For Use on my home page to properly install and customize my scripts.

WHITEBOARD


Processes a picture of a whiteboard to clean up the background and correct the perspective

Download Script

last modified: December 16, 2018



USAGE: USAGE: whiteboard [-c coords] [-a aspect ] [-m magnify] [-d dimensions] [-e enhance ] [-f filtersize] [-o offset] [-t threshold] [-s sharpen] [-S saturation] [-w whitecolor] [-p percent] infile outfile
USAGE: whiteboard [-help]

-c .... coords .......... a list of the four x,y coordinates of the corner of
......................... the whiteboard in the picture ordered clockwise
......................... from the upper left corner. The default is the
......................... four corners of the input image.
-a .... aspect .......... width-to-height aspect ratio of actual whiteboard;
......................... typical aspect ratios are: 2 (2:1), 1.5 (3:2) and
......................... 1.33 (4:3); floats>0; The default is computed
......................... automatically
-m .... magnify ......... ouptut image magnification (or minification) factor
......................... applied to automatically computed dimensions; float>0;
......................... values>1 are magnify; values<1 are minify;
......................... default=1 (no change)
-d .... dimensions ...... desired dimension(s) of the output; choices are:
......................... WIDTH, xHEIGHT or WIDTHxHEIGHT; if either of the
......................... first two, then the other will be computed from the
......................... aspect ratio and magnify will be ignored; if the latter,
......................... then both aspect and magnify will be ignored; default is
......................... to ignore dimensions and use aspect and magnify
-e .... enhance ......... enhance image brightness before cleaning background;
......................... choices are: none, stretch, whitebalance or both;
......................... default=stretch
-f .... filtersize ...... size of processing filter to clean up background;
......................... integer>0; default=15
-o .... offset .......... offset of filter in percent to reduce noise;
......................... integer>=0; default=5
-t .... threshold ....... text smoothing threshold; 0<=threshold<=100;
......................... nominal value is about 50; default is no smoothing
-s .... sharpamt ........ sharpening amount in pixels; float>=0;
........................ nominal about 1; default=0
-S .... saturation ...... color saturation expressed as percent; integer>=0;
......................... default=200 (double saturation)
-w .... whitecolor ...... desired color for whiteboard background;
......................... default=white
-p .... percent ......... percent near white to use for white balancing;
......................... float>=0; default=0.01

PURPOSE: To process a picture of a whiteboard to clean up the background and correct the perspective.

DESCRIPTION: WHITEBOARD processses a picture of a whiteboard with writing on it to clean up the background and correct the perspective. The four corners of the actual interior of the whiteboard in the picture must be supplied in order to correct the perspective.

ARGUMENTS:

-c coords ... COORDS is a list of the four x,y coordinates of the corner of the whiteboard in the picture ordered clockwise startin with the upper left corner, e.g. "x1,y1 x2,y2 x3,y3 x4,y4". The default will be the four corners of the input image and thus will not trim any existing border or area outside the whiteboard, nor will it correct any perspective distortion.

-a aspect ... ASPECT is the width-to-height aspect ratio of actual whiteboard. Typical values are: 2 (2:1), 1.5 (3:2) and 1.33 (4:3). Values are floats>0. The default is computed automatically.

-m magnify ... MAGNIFY is the output image magnification (or minification) factor Values are floats>0. Values larger than 1 will magnify. Values less than 1 will minify. The default=1 and will produce an output whose height is the length of the left edge as defined by the supplied coordinates and whose width=height*aspect. A value of 2 will be twice that size and a value of 0.5 will be half that size. If no coordinates are supplied, then the width and height will be those of the input image multiplied by the magnify factor.

-d dimensions ... DIMENSIONS are the desired dimension(s) of the output image. Choices are: WIDTH, xHEIGHT or WIDTHxHEIGHT; if either of the first two options are selected, then the other dimension will be computed from the aspect ratio and magnify will be ignored. If the latter option is selected, then both aspect and magnify will be ignored. If no coordinates are supplied, then the input image aspect ratio will be use. The default is to ignore dimensions and use the aspect and magnify.

-e enhance ... ENHANCE the image brightness before cleaning the background. # The choices are: none, stretch, white balance or both. The default=stretch.

-f filtersize ... FILTERSIZE is the size of the filter used to clean up the background. Values are integers>0. The filtersize needs to be larger than the thickness of the writing, but the smaller the better beyond this. Making it larger will increase the processing time and may lose text. The default is 15.

-o offset ... OFFSET is the offset threshold in percent used by the filter to eliminate noise. Values are integers>=0. Values too small will leave much noise and artifacts in the result. Values too large will remove too much text leaving gaps. The default is 5.

-t threshold ... THRESHOLD is the text smoothing threshold. Values are integers between 0 and 100. Smaller values smooth/thicken the text more. Larger values thin, but can result in gaps in the text. Nominal value is in the middle at about 50. The default is to disable smoothing.

-s sharpamt ... SHARPAMT is the amount of sharpening to be applied to the resulting image in pixels. Values are floats>=0. If used, it should be small (suggested about 1). The default=0 (no sharpening).

-S saturation ... SATURATION is the desired color saturation of the text expressed as a percentage. Values are integers>=0. A value of 100 means no change. The default=200. Larger values will make the text colors more saturated.

-w whitecolor ... WHITECOLOR is the desired background color of the whiteboard after it has been cleaned up. Any valid IM color may be use. The default is white.

-p percent ... PERCENT near white to use for white balancing; float>=0; default=0.01

NOTE: For coordinate selection, one can use the IM display function and on the Mac option-rightmousebutton hold and drag to display coordinates. I am not sure what the equivalent is on other systems. Possibly middle mouse button.

NOTE: Requires IM 6.3.6-0 or higher only if control points are supplied or magnification is not equal to 1, due to the control point ordering for the perspective and also due to the use of -set option:distort:viewport.

Thanks to Jens Mueller for suggesting this function and supplying references to examples.

REFERENCES:
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

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.


EXAMPLES


Example 1
(http://softtouchit.com/xpe/portal/674eef30-1119-1000-8121-46648aa451c5)

 

Original

 

Arguments:
(no preprocessing, no smoothing)
-c "101,53 313,31 313,218 101,200"
-e none -a 1.33 -m 2 -f 25 -o 3

 

Arguments:
(stretch, no smoothing)
-c "101,53 313,31 313,218 101,200"
-e stretch -a 1.33 -m 2 -f 25 -o 3

 

Arguments:
(stretch & white balance, no smoothing)
-c "101,53 313,31 313,218 101,200"
-e both -a 1.33 -m 2 -f 25 -o 3

 

Arguments:
(stretch & white balance, with smoothing)
(magnify=2 or use -d WIDTH or -d xHEIGHT)
-c "101,53 313,31 313,218 101,200"
-e both -a 1.33 -m 2 -f 25 -o 3 -t 60
or
-c "101,53 313,31 313,218 101,200"
-e both -a 1.33 -d 391 -f 25 -o 3 -t 60
or
-c "101,53 313,31 313,218 101,200"
-e both -a 1.33 -d x294 -f 25 -o 3 -t 60

 



Example 2

 

Original

 

Arguments:
-c "13,3 342,6 331,467 38,482"
-e both -a 0.75 -f 12 -o 3 -t 40
Arguments:
-c "13,3 342,6 331,467 38,482"
-e both -f 12 -o 3 -t 40
(automatic aspect determination)


Example 3

 

Original

 

Arguments:
-c "55,60 420,76 416,277 75,345"
-e both -a 1.5 -f 12 -o 7 -t 30
Arguments:
-c "55,60 420,76 416,277 75,345"
-e both -f 12 -o 7 -t 30
(automatic aspect determination)


Example 4

 

Original

 

Arguments:
(no preprocessing, no smoothing)
-e none -f 12 -o 3

 

Arguments:
(stretch & white balance, no smoothing)
-e both -f 12 -o 3

 

Arguments:
(stretch & white balance, with smoothing)
-e both -f 12 -o 3 -t 30

 

Arguments:
(stretch & white balance, with smoothing, with sharpening)
-e both -f 12 -o 3 -t 30 -s 1

 



Example 5

 

Original

 

Arguments:
-e both -f 12 -o 3


What the script does is as follows:

  • Optionally, enhance the image to stretch and/or white balance
  • Uses the aspect ratio, magnification factor and left side length to
    compute the output width and height, if user supplied coords are provided
  • Optionally uses -distort perspective to correct for perspective distorton using
    the user supplied coordinates and the dimension of the output
  • Creates a grayscale version of the perspectively corrected image and
    applies a local area threshold using -lat and (optionally) some blurring for
    antialiasing to create a mask
  • Composites the mask with the corrected image to make the background white
  • Optionally sharpens and changes the saturation

This is equivalent to the following IM commands for the case of enhance=stretch:

  • convert $tmpA1 -contrast-stretch 0 $tmpA1
  • Extracts and separates the user supplied input coords
    "x1,y1 x2,y2 x3,y3 x4,y4", if provided
  • height=`convert xc: -format "%[fx:$magnify*hypot(($x1-$x4),($y1-$y4))]" info:`
  • width=`convert xc: -format "%[fx:$aspect*$height]" info:`
  • Creates output coords, "xx1,yy1 xx2,yy2 xx3,yy3 xx4,yy4", from the width and height
  • coords="$x1,$y1 $xx1,$yy1 $x2,$y2 $xx2,$yy2 $x3,$y3 $xx3,$yy3 $x4,$y4 $xx4,$yy4"
  • convert \( $infile -virtual-pixel white -set option:distort:viewport \
    ${width}x${height}+0+0 -distort perspective "$coords" \) \
    \( -clone 0 -colorspace gray -negate -lat ${filtersize}x${filtersize}+${offset}% \
    -contrast-stretch 0 -blur 0x$bluramt \) \
    -compose copy_opacity -composite -fill "$wcolor" -opaque none +matte \
    -sharpen 0x$sharpamt -modulate 100,$saturation \
    $outfile