			  libdrg version 0.1

OVERVIEW

libdrg is a library to read Digital Raster Graph (DRG) maps for
display via the X Window System.  Currently, libdrg supports only the
format produced by the USGS (TIFF, 1 line per strip, fixed colormap,
and aligned to and georeferenced in UTM).

libdrg can select the appropriate scale of map, and can mosaic
multiple maps, so that the caller can ignore these issues.  Currently
there is no way to control scale and mosaicing, so that it is not
possible to look at data outside the neatlines.  (For now, use gimp.)

libdrg is currently restricted to a single UTM zone, and is unaware of
datum.  Therefore, the program using libdrg needs to supply
coordinates that are consistent with the libdrg control files
provided.  libdrg does not actually rely on UTM --- it simply works in
a Cartesian coordinate system with easting and northing, and scale and
offset are arbitrary.  Nevertheless, UTM in NAD27 is the standard
coordinate system for libdrg due to the availability of USGS DRGs.

libdrg is alpha code and should not be used for anything important.
libdrg has many arbitrary limitations which have not been important to
the author's use (e.g. an X11 display is needed for some operations,
and libdrg must be linked with X11 libraries).  Bug reports, fixes, or
independent verificaion of correctness are solicited; please send to
<bug-libdrg@ptt.lexort.com>.

libdrg is Free Software; see the file COPYING for terms.
Additionally, while not in any way a condition for copying or use, the
author requests that if you find it useful and you have DRGs, that you
offer to make the DRGs available (e.g. over the net) to the author who
may be contacted at gdt@ptt.lexort.com.

USGS TOPOGRAPHIC MAP DIGITAL RASTER GRAPHS

The USGS documentation should be consulted.  Briefly, each map is
scanned to form a single TIFF file.  The image is processed so that it
is very nearly 250 dpi the pixels are aligned with the NAD27 UTM grid
(i.e. all pixels in a row have the same northing).  Values are
provided for the UTM coordinate of the upper left pixel and the
transform matrix to convert a UTM offset from upper left to pixel
coordinates.  Because the images are aligned and there is no
anamorphic magnification, this matrix is diagonal, and the (2,2)
element is the negative of the (1,1) element.  The pixels are selected
to be one of a small number of standard colors, and there is a
standard colormap across all maps.

CONTROL FILES

libdrg reads a control file with one line of information per map,
giving georeferencing information.  The file named in the environment
variable LIBDRG_DRGLIST is consulted, or if that variable does not
exist $HOME/.libdrg/drglist.dat.  In typical usage for New England
(US), the directory $HOME/.libdrg contains drglist-18.dat and
drglist-19.dat, with drglist.dat a symlink to the zone of primary
interest.

The control file lines are ordered.  When a map pixel is needed, the
maps named are searched in order, stopping at the first map of
appropriate scale that includes the request point.  Thus, the
large-scale maps (generally 1:25000 topographic maps, scanned at 250
dpi so that the image is 2.54 meters per pixel).  Maps of the same
scale generally do not overlap, and thus ordering among them is
unimportant.

Large-scale maps are not rendered in a highly subsampled manner.  For
example, if the scale is 2.54 * 16 meters per pixel, libdrg declines
to use a 1:25k map (2.54 m/pixel) because to do so would involve
returning every 16th pixel (or averaging them), which would not be
useful.  It is far more useful to look at a smaller scale map.
Generally, maps are shown at their native scale, or up to 3.9 times
subsampling.  If the calling program uses resolutions aligned with the
maps, this results in showing maps at their native resolutions (like
"dot-for-dot" in gimp) and subsampled by 2.  The next zoom out scale
would be 4 times undersampling, and for a 1:25k map is dot-for-dot on
the 1:100k map.  The exception to this rule is that the 1:250k maps
(the smallest scale in the DRG series) is shown at large subsampling
ratios (up to 1:256) because it is marginally more useful than nothing
even at extreme subsampling.

CONTROL FILE LINE FORMAT

Note that this file format is subject to change.
In particular, it is likely that the UTM zone will be added.

Each line in a drglist.dat file contains a number of space-delimited
fields in order.  The file is plain ASCII; strings are simply present
(without quotes) and numbers are in the usual format for floating
point constants in programming languages.  See drg_tiff_init in
drg_tiff.c for the fscanf statement that reads the file if further
clarification is needed.  "Top left" refers to the most northwesterly
pixel that is within or on the neatline of the map.  The operational
definition of the correct value is that if adjacent maps are examined,
every requested pixel should come from one or the other, and the
values that minimize data pixels and minimize the black pixels of the
neatlines are preferred.  In practice a straightforward calculation of
the coordinates of the corners works very well.

filename: the pathname of the TIFF file
scale: meters/pixel for this file
easting_origin: easting of the first column
northing_origin: northing of the first row
easting_tl: easting of top left
northing_tl: northing of top left
easting_tr: easting of top right
northing_tr: northing of top right
easting_bl: easting of bottom left
northing_bl: northing of bottom left
easting_br: easting of bottom right
northing_br): northing of bottom right

Code to produce drglist lines is not currently included in the libdrg
distribution.  Given a map and georeferencing information, a line can
be produced by hand.  Consider f42071a1.tif, the "Boston" 1:100K
topographic map that includes MIT.  The upper left corner is 42d30mN,
72d00mW (NAD27).  This can be converted to UTM in zone 19 and used for
hte 'tl' values, and so on for the other corners.  Note that all
corners must be in the same zone, which implies that maps spanning
zones are not supported.  (If you find such a map, please send me a
copy!)

USAGE

libdrg uses pkgconfig.

At some point, there will be a libdrg.m4 for autoconf use, or
instructions on how to use generic macros for pkgconfig-using
programs.

Consult the source for the type signatures of the interface functions.

The library prints lines prefixed with ';' to stdout.  This is helpful
when linked with xplot to understand what is happening, and will
likely be removed.

To use the library, the program must call drg_tiff_init.
This reads the drglist file into memory.  (Warning: max size is 1024
maps.  Change the constant or send dynamic allocation code if this
bothers you.)

The program calls drg_tiff_init_image(Display *dpy).  libdrg will look
up the standard colors and allocate colors.  The normal behavior is to
get RGB values that are half the defined values in the USGS
documentation (as if the alpha of the map as background were 0.5), in
order to make data plotted over the map stand out.  To avoid this,
compile with -DNO_HALF_BRIGHTNESS, with makes white be 3/4 and the
rest full.  This will some day be replaced with code that reads the
tiff colormaps and computes alpha dynamically.

Prior to rendering map pixels, the program must call
drg_tiff_set_scale.  This takes both x and y scale in "units" per
pixel, even though they have to be the same.

For each "scan line" of constant northing, the program must call
drg_tiff_start_line() to clear caches.  Then, calls to drg_tiff_image
can be made to fill in a line in an Ximage structure:
int
drg_tiff_image(double easting, double northing, int npixels,
		 XImage *image)

CACHING

libdrg does several kinds of caching in order to speed up map rendering.

For each map, a single decoded row is kept in memory.  (Profiling
indicates that gzip decompression of strips is a significant cause of
CPU time usage).

The second kind of caching is far more complex: for each map, for a
given northing, there is a range of valid eastings.  Valid is more
than just "the map has this pixel"; it also means "no other map of
larger scale, but not so large as to preclude selection has this
pixel".  Consider a 1:250k map covering 2 degrees by 1 degree with
scattered 1:25k maps available.  A single line may take pixels from
the 1:250k maps, from a 1:25k map, and then from the 1:250k map again.

libdrg also does negative caching of valid ranges, recording the
ranges of eastings for which there are known to be no maps.
