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.

UNROTATE2


Unrotate2 a rotated image and trim2 the surrounding border.

Download Script

last modified: November 26, 2021



USAGE: unrotate2 [-m mode] [-f fuzzval] [-c coords] [-b bcolor] [-d discard] [-k kernel] [-l lthresh] [-a athresh] [-t trim] [-F fuzztrim] [-g graphics] [-r rot180] [-R refine] infile outfile

USAGE: unrotate2 [-h or -help]

-m ... mode ....... mode of orientation of image; landscape or portrait;
................... default will be determined from the dimensions of the
................... input; if width>=height, then landscape;
................... if width<height, then portrait
-f ... fuzzval .... fuzz value for floodfilling the background to separate
................... image from background; 0<=integer<=100; default=15
-c ... coords ..... pixel coordinate to extract background color and seed
................... location for flood fill; may be expressed as gravity
................... value (NorthWest, etc)or as "x,y" value; default is
................... NorthWest=(0,0)
-b ... bcolor ..... background color to use instead of option -c;
................... any valid IM color; default is to use option -c
-d ... discard .... discard any region that has an area smaller than
................... this size; integer>0; default=1000
-k ... kernel ..... morphology close kernel dimension; integer>0; default=5
-l ... lthresh .... hough line length threshold as a percent of the minimum
................... trimmed dimension of the mask created from the flood
................... fill; 0<integer<=100; default=35
-a ... athresh .... angle threshold (tolerance) when matching the hough line
................... angles with the angles from the canny edges; integer>0;
................... default=1
-t ... trimtype ... type of trimming to apply to the output; choices are
................... outer, inner or none; default=outer
-F ... fuzztrim ... fuzz value for trimming the output image;
................... 0<=integer<=100; default=0
-r ... rot180 ..... rotate the input image by 180 (after flood filling);
................... choices are yes or no; default=no
-R ... refine ..... refine least squares fitting of lines to get angles
................... after discarding outliers; choices are yes or no;
................... default=yes
-g ... graphics ... mode for graphic image presentation of extracted mask
................... image; choices are view or save; default is no graphic

PURPOSE: To unrotate a rotated image and trim the surrounding border.

DESCRIPTION: UNROTATE2 computes the amount an image has been rotated and attempts to automatically unrotate the image. It assumes that the image contains a relatively constant color background area around the rotated data that is not too similar in color to the color near the boundary of the image data. The user is expected to identify the background color or a coordinate within the background region for the algorithm to extract the background color. A fuzz value should be specified when the background color is not uniform. A mask image is then created by a fuzzy flood fill. Then Canny edges are extracted and straight lines fit to each of the edges to compute their orientation angles. Hough lines are detected and used to check and filter the Canny fit lines. The angles are then averaged and the negative result is used to unrotate the image. The unrotation is indeterminant to 90, 180 and 270 degrees unless the landscape or portrait mode is identified. However, the result may still be off by 180 degrees. The script works best the more rectangular the image. Since a square image is neither landscape nor portrait, after unrotation it may still be off by 90, 180 or 270 degrees. The default mode will be determined from the largest dimension of the trimmed mask. Rectangular images should unrotate correctly with the default, whether landscape or portrait, if the orientation is less than 45 degrees. Otherwise, one needs to specify the proper mode of orientation of the image. Trimming can be applied to the unrotated result as an outer trim, which stops at the first image pixel on each side, but which may leave a bit of background around. Or trimming may be an inner trim, which will remove all background on each side, but may trim some of the image data as well.

ARGUMENTS:

-m mode ... MODE of orientation of the image. Choices are landscape (l) or portrait (p). The default will be determined from the dimensions of the input. If width>=height, then landscape. If width<height, then portrait.

-f fuzzflood ... FUZZFLOOD is the fuzz value for flood filling the background in order to separate the image from the background. Values are 0<=integer<=100. The default=15.

-c coords ... COORDS are the pixel coordinates to identify the background color and to seed the location for the flood fill. It may be expressed as a gravity value (NorthWest, etc) or as an "x,y" value. The default is NorthWest, i.e., 0,0.

-b bcolor ... BCOLOR is the background color to use instead of option -c. Any valid IM color is allowed. The default is to use option -c.

-d discard ... DISCARD any region that has an area smaller than this size when identifying the largest white area in the mask representing the image region. That is merge small regions into its surrounding color. Values are integer>0. The default=1000.

-k kernel ... KERNEL size for the morphology close processing to remove holes and gaps in the white part of the mask before extracting edges. Values are integer>0. The default=5.

-l lthresh ... LTHRESH is the Hough line length threshold as a percent of the minimum dimension of the (trimmed) mask created from the flood fill. Values are 0<integer<=100. The default=35.

-a athresh ... ATHRESH is the angle threshold (tolerance) when matching the Hough line angles with the angles from the canny edges. Values are integer>0. The default=1.

-t trimtype ... TRIMTYPE is the type of trimming to apply to the output. The choices are outer (0), inner (i) or none (n). The default=outer.

-F fuzztrim ... FUZZTRIM is the fuzz value for trimming the output image. Values are 0<=integer<=100. The default=0.

-r rot180 ... RO180 specifies to rotate the image by 180 degrees. The choices are yes (y) or no (n). The default=no.

-R refine ... REFINE the least squares fitting of the straight edges to get the orientation angles after discarding outliers. The choices are yes (y) or no (n). The default=yes.

-g graphics ... GRAPHICS is the mode for graphic image presentation of the extracted mask image. The choices are view (v) or save (s). The default is no graphic. The graphic is available to check to be sure the straight sides of white region in the mask are not too broken up, thereby producing erroneous angles for the edges and thus a bad rotation.

LIMITATIONS: This script does not perform well on nearly square images and may be off by increments of 90 degrees even for rectangular images. Note that trimtype of inner is only available for IM 7.0.8-31 and 6.9.10-31 or higher.

ADVICE: If the unrotation is not good, check the graphic image to see that the sides of the white region are straight and not broken up. If the sides have gaps, then increase the kernel value. If extraneous white regions appear in the mask, then increase the discard value.

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 -- Landscape Orientation Image

Original Image: 10 degree orientation

Arguments:
-f 15 -t none

Arguments:
-f 15 -t outer

Arguments:
-f 15 -t inner -F 5



Example 2 -- Landscape Orientation Image

Original Image: -80 degree orientation

Arguments:
-f 15 -t outer -m landscape



Example 3 -- Portrait Orientation Image

Original Image: 10 degree orientation

Arguments:
-f 15 -t outer



Example 4 -- Portrait Orientation Image

Original Image: -80 degree orientation

Arguments:
-f 15 -t outer -m portrait



What the script does is as follows:

  • Reads the input into MPC format
  • Converts the image into a trimmed binary mask by floodfilling and using connected components
  • Extracts Canny edges and Hough lines from the binary mask
  • Dilates each Hough line and uses it as a mask to get the corresponding edge pixels
  • Performs a least squares regression analysis to get the angle of the edge pixels
  • Averages the angles after deciding if the image is landscape or portrait
  • Unrotates the image by the negative of the average angle
  • Saves the output