@c Copyright (C) 1992 Free Software Foundation.
@c This is part of the GNU font utilities manual.
@c For copying conditions, see the file fontutil.texi.

@node IMGrotate, Fontconvert, Imageto, Top
@chapter IMGrotate

@pindex imgrotate
@cindex rotation, of images
@cindex image rotation

IMGrotate rotates an IMG file, either 90 or 180 degrees clockwise.  We
call the latter---somewhat inaccurately---a ``flip''.  (We haven't
needed other rotation angles, so we haven't implemented them.)

The IMG format is an image format output by a few programs, including the
one that drives the scanner we have.  (Again, we haven't needed other
image formats, so we haven't implemented them.)

Both the input and output are IMG files.

The current implementation of IMGrotate uses an extremely slow and
stupid algorithm, because it was a quick hack.  It would be useful to
replace it with a better algorithm.  @xref{Program features}, for a
reference.

@menu
* IMGrotate usage::             Doing the image rotation.
* Invoking IMGrotate::          Command-line options.
@end menu


@node IMGrotate usage, Invoking IMGrotate,  , IMGrotate
@section IMGrotate usage

@cindex IMGrotate usage
@cindex usage of IMGrotate

The physical construction of a source to be scanned may make it hard
or impossible to end up with an upright image.  But the task of
extracting characters from an image is complicated by allowing for a
rotated image.  Hence this program to turn rotated images upright.

@flindex x @r{prefix}
By default, the name of the output file is the same as the input file;
both are extended with @file{.img} if necessary.  If this would result
in the output overwriting the input, @samp{x} is prepended to the output
name.

@menu
* Clockwise rotation::          Rotating clockwise.
* Flip rotation::               FLipping end-for-end.
@end menu


@node Clockwise rotation, Flip rotation,  , IMGrotate usage
@subsection Clockwise rotation

@cindex clockwise rotation
@cindex rotation, clockwise
@opindex -rotate-clockwise

You specify clockwise rotation of an image with the option
@samp{-rotate-clockwise}.  This rotates the input 90 degrees clockwise.
For example, the following (an @samp{h} on its side):

@example
      *****
     *
     *
***********
@end example

@noindent turns upright.


@node Flip rotation,  , Clockwise rotation, IMGrotate usage
@subsection Flip rotation

@cindex flip rotation
@cindex rotation, flip

You specify ``flip'' rotation of an image with the option @samp{-flip}.
This flips the input end for end and reverses left and right, i.e., does
a 180 degree rotation.  For example, the following (an @samp{h} upside
down and backwards):

@example
  *  *
  *  *
  *  *
   ***
     *
     *
     *
@end example

@noindent turns upright.


@node Invoking IMGrotate,  , IMGrotate usage, IMGrotate
@section Invoking IMGrotate

@cindex IMGrotate options
@cindex invocation of IMGrotate
@cindex options for IMGrotate

This section describes the options that IMGrotate accepts.
@xref{Command-line options}, for general option syntax.

The name of the main input file (@pxref{Main input file}) is called
@var{image-name} below.

@table @samp

@opindex -flip
@item -flip
Rotate the input 180 degrees, i.e., flip it end for end and left to
right.  @xref{Flip rotation}.

@opindex -help
@item -help
Print a usage message.  @xref{Common options}.

@opindex -output-file
@cindex output file, naming
@item -output-file @var{filename}
Write to @var{filename} if @var{filename} has a suffix.  If it doesn't,
write to @file{@var{filename}.img}, unless that would overwrite the
input, in which case write to @file{x@var{filename}.img}.  By default,
use @var{image-name} for @var{filename}.

@opindex -rotate-clockwise
@item -rotate-clockwise
Rotate the input 90 degrees clockwise.  @xref{Clockwise rotation}.

@opindex -verbose
@item -verbose
Output progress reports.  @xref{Common options}.

@opindex -version
@item -version
Print the version number.  @xref{Common options}.

@end table
