This is GridPix version 2.1.

GridPix enables you to present large images over the Internet in an
efficient manner.  For more information about the implementation and
technical stuff, please visit:

  http://now.cs.berkeley.edu/Td/GridPix/

The Fine Arts Museums of San Francisco has been using GridPix to
exhibit their collections for some time.  Their site is at:

  http://www.thinker.org/

Click on the middle link ("Imagebase"), do a search, select a
thumbnail and select the screen size.  A new GridPix window should pop 
up on your screen.

For an example of a very large GridPix file, please try:

  http://stampede.cs.berkeley.edu/cgi-bin/getimg2.cgi?interceptor&1008&720

You will need the jpeg library and the netpbm toolkit to compile and
use GridPix.  They can be found at:

  ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
  ftp://ftp.x.org/R5contrib/netpbm-1mar1994.tar.gz

The cgi scripts assume you have perl in /usr/bin.  Edit the "#!"
lines at the beginning of the scripts if perl is in a different
location on your system.

The rest of this file discusses how to setup a GridPix server.

(A) The programs

(1) gridpack

    gridpack creates a GridPix file.  The input is ppm (portable
    pixmap); if your input is a different format, you need to first
    convert it to ppm.  For more information on ppm, please read the
    documentations in the netpbm toolkit.

    The easiest way to run gridpack is to redirect the input and
    specify the output file using the "-o" (output file) option.  For
    example, with a tga file as input:

    tgatoppm myfile.tga | gridpack -o myfile.gpx

    will give you a GridPix file in "myfile.gpx".

    There are three more options, "-t" (tile size), "-l (number of
    levels)" and "-q" (quality).  The "tile size" will change the
    number of pixels on a side of a GridPix tile.  The default is 144.
    The "number of levels" controls the number of smaller resolution
    levels it stores in a file.  (The larger ones are generated on the
    fly.)  The default is 4, meaning there are three levels underneath
    the original size (50%, 25% and 12.5%).  Finally, the "quality" is
    the value used in the jpeg encoding.  (The higher the number, the
    higher the quality and the size of the output file.)  The default
    is 75.

(2) gridunpack

    gridunpack reads a GridPix file and returns a tile.  You will
    never have to call it by yourself, so don't worry about its
    arguments.  If you use the supplied Makefile, is will also be
    installed as "gettile.cgi" (symlink).

(3) mkhtml

    mkhtml returns an HTML page to the user's browser, displaying some
    part of the image plus navigation buttons.  The image part is
    composed of multiple references to gettile.cgi arranged in a
    table.  You will never have to call it by yourself.

(4) mkhtml.cgi is just a CGI wrapper for mkhtml.  You will never have
    to call it by yourself.

(5) getimg2.cgi

    getimg2.cgi is the entry point to the images.  It takes three
    arguments: image name, width and height.  They should be supplied
    with '&' in between as per normal CGI convention.  Here's an
    example:

    http://hostname/cgi-bin/getimg2.cgi&1234&1000&700

    will return image "1234.gpx" on machine "hostname" with a window
    that has a viewable area of 1000 by 700 pixels.

(B) Options

    There are several options you can set when compiling and
    installing these programs, resulting in a slightly different
    behavior.  These are in the supplied Makefile, so comment them out
    (or uncomment them) as you wish.

    GRIDROOT: This is the base of the GridPix tree.  Default (set in
            Makefile) is \"/usr/local/www/data/gridpix/\".  Note the
            quotes.

    RESIZE: It will enable the "resize" buttons.  Without this option, 
            mkhtml will always display the image with the same size
            (supplied from getimg2.cgi initially...see the explanation 
            of getimg2.cgi).

    SUBDIR: It will enable subdir support.  With this option, mkhtml
            will assume that the file name has 16 digits plus ".gpx"
            at the end, and the first 12 digits is the name of the
            subdirectory.  For instance, if the file is called
            "1234567890123456.gpx", it is supposed to be accessed as
            "${GRIDROOT}123456789012/images/1234567890123456.gpx".
            (Don't ask me why it is this way -- it was the easiest way
            to convert a bunch of PhotoCD images we had.)

            You probably don't want to define this this unless you
            have a large collection of images.  Without this option,
            the image will be called "${GRIDROOT}<name>.gpx".

(C) Installation

    Type "make all install" and all the programs and necessary bitmap
    data will be installed.  (The Makefile is written for BSD make;
    you may need to change the syntax slightly if you are using GNU
    make.)

(D) Images

    Use the "gridpack" program to create a GridPix file.  Put it in
    the directory you specify by GRIDROOT and SUBDIR above.  Put a
    link to getimg2.cgi with that image name on your page.  Since
    GridPix does not offer a way to return to the original page (yet),
    I recommend you use a JavaScript to popup a new window instead of
    just putting it in as a link.

Note that this is the very first time I'm letting people use this
program.  The code is still ugly and there very are probably a lot of
system dependencies that I forgot to erase.  I will appreciate it very 
much if you let me know of any such problems you encountered while
trying to get it to work on your system.

Satoshi Asami
asami@cs.berkeley.edu
