                  Calibrating pnm2ppa for Your Printer

Note.  These instructions assume that you are already able to print postscript
files with your PPA printer.   If you have properly configured your print 
filters, "lpr test.ps" will successfully invoke ghostscript and pnm2ppa
to print the postscript file test.ps.   Alternatively, you may be using 
shell scripts like "lprbw", "lprcolor" and "lpreco" supplied with the
pnm2ppa source code, and modified by you for your defaults.

In case you have not managed to set this up yet, the "brute force" command 
line for printing test.ps is something like (all in a  single line)

gs -sDEVICE=ppmraw -q -sPAPERSIZE=a4 -dNOPAUSE -r600 -sOutputFile=- < test.ps | \
pnm2ppa <options>  -s a4  -i - -o - - > /dev/lp0

In this example the papersize is "a4" (specified twice, once for gs and once
for pnm2ppa).  Other valid paper sizes are the US sizes "letter" and "legal"
(substitute e.g., "letter" for "a4" in the above example).   The example
uses the printer port /dev/lp0; possibly your printer is on /dev/lp1 or 
/dev/lp2, etc. (/dev/lp0 is the default for printers on the primary 
parallel port in Linux systems with 2.2.x or newer kernels; it was /dev/lp1
in older Linux systems).  You should not actually  type "<options>"  ; this is
the place for typing pnm2ppa options such as "--eco" (ink economy mode), which
you will probably wish to usually use.  Type "pnm2ppa" or "man pnm2ppa"
for two different descriptions of the possible options.   The example also
assumes that  the pnm2ppa  executable is already in your path; if not, you
must give its full path.  It also assumes the the configuration file 
/etc/pnm2ppa.conf is in place.  If it is elsewhere, you must specify
its full path with the  -f option.


Upon being able to print successfully, you can (if necessary) adjust both 
the centering of the  printed output on the paper (the X and Y Offsets,
(xoff and yoff  parameters in  pnm2ppa.conf) and the relative
positioning of the color and black printing (ColOffsX and ColOffsY parameters 
in pnm2ppa.conf)  (Default values for each printer model are compiled into 
pnm2ppa; if you wish to change these values and recompile pnm2ppa with new 
defaults, you can change them in the source code file defaults.h)

                    -------------------------
 (1) Calibrating the X and Y Offsets.

Adjust these to correctly center the printout on the paper.

The simplest approach is to print a suitable test page, such as
the files testpage.ps (US Letter size) or testpage-a4.ps
(US Legal) from Red Hat Linux.   These pages show a border
that should be correctly positioned relative to the edges of the 
paper.    Uncomment and make small adjustments to the default
values for these in pnm2ppa.conf, until the printout is satifactory.

Alternatively, you can use the 'calibrate' program that is supplied
with pnm2ppa, which  creates a calibrated grid pattern in the raw
pixmap  format accepted by pnm2ppa. (The three paper sizes,
US Letter,  US Legal, and A4, are supported).
If your paper size is A4, and your printer filter accepts
the "-l" (direct output) option to lpr, the command to run is:

    calibrate -a4  | pnm2ppa -s a4 -i -  -o - | lpr -l

(Substitute "letter" or "legal" for "a4" twice to change
the papersize.)  If your paper size is US letter (the default),
you only need to run

    calibrate  | pnm2ppa  -i -  -o - | lpr -l

If "lpr -l" is not valid, you need to know  which port your
printer is attached to.   Assuming it is /dev/lp0, the above 
command becomes

    calibrate  | pnm2ppa  -i -  -o -  > /dev/lp0


[Note: if attempting to print only causes all three lights on the printer
to blink (because you attempted to print outside the allowed region), try 
widening the margin settings in pnm2ppa.conf to something 
ridiculous during this procedure (like 600)]


The numerical values marking grid intersections are pixel coordinates.
Unfortunately, these coordinates are probably cut off before the edge of the
paper.  You'll have to use a ruler to estimate the pixel coordinate of the 
left and top edges of the actual sheet of paper (should be within +/- 300, may
be negative, there are 600 pixels per inch).

Add these coordinates to the default X and Y offsets by either: (1) editing the
defaults.h file and recompiling, (2) modifying the default values in
/etc/pnm2ppa.conf, if you've set this up, or (3) using the '-x' and '-y'
command-line parameters.    When properly calibrated, the center mark should 
be in the center of the paper.  Also, the margins should be able to be as 
small as 1/4 inch without causing the printer to choke with 'blinking lights 
syndrome'.

     -----------------------------------

(2) Calibrating the X and Y Color Offsets.


The color ink now has to be calibrated with respect to the black ink.
This can be done by printing the test page test.ps.

On the printout you see several items:
- top left, you see a square with both black and colored items. These should
  align correctly, or you have to adapt your settings.

- You see a large vertical, and also horizontal, bar.On the sides of this bar
  there are a blue and a green line. These should align with the 0 mark.

- You also see a small vertical, and horizontal, bar, with a red bar on
  its side.

If these items do NOT line up, you should take the following steps:

1) take for the large bar the number of the tickmark just smaller
   then the place where the green and blue lines point to. The minor
   tick marks are 25 points.

2) To this number, add the number of the tick mark at which a red tick
   mark exactly lines up. This might not work if the offsets are way off;
   in that case, apply correction of step 1, and print again.

3) Add the horizontal offset to the value ColOffsX, and the vertical offset to 
   the value ColOffsY in the pnm2ppa.conf file

Now you can print test.ps again to see whether this procedure did work.


                     ------------------------

[TODO: Add shearing adjustments to pnm2ppa and explain here]
[ajv: XXX haven't seen shearing for a while now]

[TODO: describe the gamma calibration of color]   








