Grunch 1.3
----------

This software package can help you scan images which are larger than
your scanner's bed will normally permit.  I wrote it when I wanted to
do full-sized scans of LP jacket covers, but had no access to flatbed
scanners large enough to scan a 12"x12" jacket in a single operation.

With the software in this package, you can scan a large image in two
"slices" (the left part and the right part) and then combine them into
a single slice.  You must have an overlap in the center of the image
of roughly 2" - that is, the center 2" of the original image must
appear in both scans.

The current version of grunch can be found on my Web site, in the
http://www.radagast.org/~dplatt/unix/ directory.

Changes
-------

Version 1.3 includes new scripts to print J- and tray-cards using the
die-cut sheets sold with the CD Stomper product.

The name
--------

"grunch" is somewhere between "grind" and "crunch", and refers to the
intensive processing required by this package.

"rgrunch" means "rotated grunch".

Copying and use
---------------

This package was written by Dave Platt, who retains all legal rights
to the package.  It is released for public use under the terms of the
GNU General Public License, Version 2, a copy of which should have
been included in the file "COPYING" in the software archive you
received.  Please refer to that file to understand your rights and
responsibilities should you choose to use or distribute this software.

Theory of operation
-------------------

This package tries to give you a seamless-looking combination of the
data in the "left" and "right" scans.  It uses a simple, but
reasonably effective pixel-value-difference-minimizing algorithm to
figure out where the two scans overlap, and how they are actually
aligned.  It can cope with real-world quirks of the scanning process
such as moderate X- and Y-axis misalignments, brightness and contrast
variations, and (in the extended version) even a couple of degrees of
rotational mismatch between the scans.

The package looks at the sizes of the left- and right-side scans to
deduce how big the combined scan should be.  It calculates the
vertical center-line of the image, and figures out where this
centerline would lie in the left- and right-side scans.  It cuts out a
thin slice from around the centerline in the right image, and a
somewhat larger window from around the centerline in the left image.
It then "slides" the slice around the window (in both the X and Y
directions), trying to find the best matchup in the pixel values.

It does this matching process three times, on successively larger
versions of the image.  It does a rough match on a 1/9-scale copy of
the scans, and then finer matches on 1/3-scale and full-sized images.

After the final position matchup is achieved, the package tries to
compensate for differences in the brightness of the two scans.  Such
differences are quite common, as many scanning packages automatically
adjust the scanner brightness and contrast based on the portion of the
image actually being scanned.  The package adjusts the brightness of
the right-hand side of the image, and attempts to reduce the average
difference between the slice and window portions of the image to zero.

Once the brightness of the right-hand image has been adjusted, the
package creates a new, composite file.  It does not create an abrupt
"seam" at the center of the new image - rather, it creates a blended
"ramp" between the left- and right-hand images.  This helps prevent
any remaining rotational or brightness errors from being visible.

An extension to this process can even cope with minor errors in the
orientation (rotation) of one or both of the scans.  The
rotated-grunch routine runs multiple grunches, twisting one of the two
scans (the right-hand one) at various angles of up to 2 degrees in
either direction.  It picks the rotation angle which results in the
least error during the grunch process.  You may notice some slight
blurring or other visual artifacts in the right-hand half of the
combined image, due to the slight smearing which occurs when the
pnmrotate program calculates the new pixel values.

It burns up a lot of CPU time, I/O time, and disk space as it does
all of this stuff.  It is, no doubt, less efficient than it could be.

Limitations
-----------

It does side-to-side matchup only - it doesn't support merging "top"
and "bottom" scans.  If you need to do the latter, you can either
rewrite it, or use "pnmrotate" to rotate the scans into left/right
orientation, grunch, and then rotate back.  Don't try the latter
unless you have _lots_ of RAM in your machine - pnmrotate is
RAM-intensive. 

Requirements
------------

You must have the following:

-  A flatbed scanner, capable of scanning at least half of the width
   of the original image (plus an inch or so) at a time.

-  Some way to scan an image into a disk file, in either TIFF or PPM
   format.

-  A copy of the "pbmplus" or "netpbm" software package... you'll need
   both the pbm applications, and the code libraries.

-  A C compiler and "make" facility.

-  A shell compatible with the GNU "bash" shell.  A vanilla "sh" shell
   may work but I haven't tried it.

-  Lots of temporary disk space (several times the size of the largest
   image you plan to merge).

-  Possibly some other things I haven't remembered.

Using it
--------

[1] Unpack the tarball (I guess you got there already if you are
    reading this).

[2] Make sure you have a functional set of pbm utilities on your
    system.  If not, download them from uunet or another good archive,
    configure, compile, and install them.

[3] Do a "make" to compile the pixel-matching utility and the "pgmramp8"
    program.
    
    If you don't have the pbmplus/netpbm include files and libraries, you
    can use the binary versions of "match" and "pgmramp8" I've included
    in this archive.  I've included versions linked against both libc5
    (for Slackware users) and glibc (for almost everybody else).  Type
    "make libc5-hacks" or "make glibc-hacks" respectively.

[4] Check the parameters in the "munch" script.  In particular, make
    sure that the "tmp" variable points to a filesystem location that
    (a) you can write to, and (b) has oodles of free space.
    
[5] Check the installation directory in the Makefile (default is
    /usr/local/bin) and then do a "make install" to install the 
    executables and scripts.

[6] Scan the left- and right-side portions of an LP jacket or similar
    large image.  Name them (e.g.) "foo-1.tif" and "foo-2.tif", where
    "foo" is the image name.  The images may be saved either as TIFF
    files (.tif or .tiff suffix) or as pbmplus files (.pbm, .pgm, or
    .ppm suffixes).  TIFF files are often smaller (due to the
    Lempel-Ziv compression usually used) but are processed more slowly
    due to the decompression required.
    
    You'll need to scan the image at a relatively high resolution...
    150 pixels/inch or higher.  If you try a low-resolution scan, the
    image will be too small to process.

[6] Grunch the image:  "grunch foo".  Go out for a cup of coffee -
    it'll be running for a while.

[7] Inspect the resulting image "foo-autojoin.tif" using The GIMP or a
    similar image viewer.  Check the seam between the left and right
    halves for anything visually anomalous.

If you were careful when you inserted the LP jacket into the scanner,
and got it onto the scanner bed in the same orientation during both
scans, the "grunch" joining will often be quite acceptable.

If you accidentally misaligned the image during one scan or the other
(rotating it slightly) there may be some objectionable blurring of the
pixels on either side of the image seam.  If this happens, you can try
rescanning one or both halves of the image (being more careful this
time) or you can try a "rotated grunch":

[8] "rgrunch foo".  Go to bed, and check the results in the morning.

If the grunch or rgrunch routines produce a horribly-misaligned image
(a Frankenstein's Monster sort of goofup), try rescanning the image
with a greater or lesser amount of overlap between the two scans.  The
difference-minimizing algorithm can be fooled repeated patterns
appearing in an image (e.g. horizontal or vertical stripes, "op art"
patterns, etc.) - you might try reducing the "limit" variable at the
top of the "munch" script, to reject poorer matches more effectively.
If your scanner software has an automatic brightness/contrast
adjustment feature, try disabling it... or, scan one side of the
image, lock the brightness/contrast adjustment, and then scan the
other side with exactly the same adjustment values.

Rapid production of jewel-box artwork
-------------------------------------

I've included copies of some dumb, simple-minded little scripts I use to
scan LP covers and produce booklets and tray cards for insertion into the
jewel-boxes of the CD-Rs I burn from the LP.  These scripts require that you
have built and installed the SANE scanner-driving software (go to
http://www.mostang.com/sane to download it) and that you have a PostScript
printer (or a suitable Ghostscript configuration for whatever printer you
have).

The following scripts are enclosed:

-  "scancover".  Walks you through the process of scanning the front and back
   covers of the LP (front left, front right, back left, back right) and
   then grunches the strips into two auto-joined tiff files.  If invoked as
   (e.g.) "scancover foo" you'll end up with "foo-a-autojoin.tif" and
   "foo-b-autojoin.tif".
   
-  "printcover".  Prints the front- and rear-cover TIFF files onto a single
   sheet of paper, in a form which can be folded and trimmed to make a
   simple booklet for insertion into the front cover of a jewel box.  Invoke
   as (e.g.) "printcover foo".
   
-  "printcard".  Prints a tray-card for insertion into the back cover of a
   jewel box.  The graphic on the tray-card will consist of either text (if a
   text file named (e.g.) "foo-card.txt" exists), or a specific graphic
   you've scanned (if "foo-card.tif" exists), or the same graphic used on
   the rear of the booklet (from "foo-b-autojoin.tif").  Prints text on the
   spine of the tray-card, using the second argument specified on the
   command line (if present) or the first line in the -card.txt file.
   
   Invoke as (e.g.) "printcard foo 'Artist / Title'"
   
-  "printsheet".  Prints a J-card (for the front cover) and a tray-card (for
   the rear cover) in a single operation, in a format designed to be printed
   on the die-cut-cardboard sheets sold with the CD Stomper.  The J-card
   portion of the sheet is printed according to the same rules as in the
   "printcard" script.
   
-  "printcolorsheet".  Identical to "printsheet" except that the artwork is
   printed in color rather than grayscale.

-  "makecover" and "makecard" and "texttocard" and "makesheet" and
   "makecolorsheet" - these do the actual dirty work for the shell scripts 
   above.

You may wish to edit some or all of these scripts, to adjust the image
placement, positions of the cut lines, scanning resolution, font or font
size, etc., or to remove the "ppmtopgm" step which forces the images to be
printed in grayscale rather than color.  My apologies for the messiness of
the scripts.

I find that 24-lb 100%-cotton bond paper works very nicely for jewel-box
inserts... it's bright white, stiff enough to fold well and hold its shape,
and much less expensive than commercial jewel-box insert forms (e.g. from
Neato or Stomper).