Introduction
------------

This source code is an evolutionary product, meaning that it has grown 
as my understanding of the IMG file format has.  This makes it more of
experimental code as opposed to a set of objects or API's useful to
an end developer.  In particular, this means:

  - The code is not really well organized at the moment.  This is a
    side effect of an evolutionary process vs. a high-level
    architecture, and the invalidation of some assumptions that were
    made when I initially got started due to a lack of understanding 
    of the IMG format, itself...it's hard to architect when you
    don't know what you're doing.  I had to start somewhere (you have
    to break some eggs to make an omelette).

  - The code is messy.  There are inconsistencies and poor choices, 
    a bad blending of objects and certainly poor object design.  See
    above before complaining.  I already know.

  - The code will change.  This is a first-cut at extracting information
    from an IMG file and the code was written to help me understand how
    that is done.  With a more complete picture of the IMG format, I
    can re-architect, but for now it will stay in this sloppy, evolutionary
    state.

  - It should go without saying that this code is not suitable for 
    inclusion in 3rd-party applications.  It's an instructive tool
    only.  Of course, I can't stop you from doing that, but at least I
    warned you first.

Despite these issues, the code is not entirely stupid.

The use of mmap(2) should allow it to handle an IMG file of any
size at the expense of a bit of performance.  The alternatives would
be to load the whole file into memory, which would be rude and
possibly overkill but pretty fast, or to use STDIO to hunt and peck
for the information you need, which would be painfully slow.

It is also designed to be byte-order independant and should work
on big-endian systems (IMG files use a little-endian format), though
extensive testing has not been done.  It should be portable to most
UNIX OS's though I am not rigorously checking for header files and
data type definitions so some tweaking may be needed.  It's been
compiled and run successfully under HP-UX 11 and Solaris 2.7.


Bugs
----

Yes, there are bugs.  Lots of them.  It goes without saying that this 
is a work in progress.  I have opted to release partially-working code
for people to play with rather than wait until it was completely
functional.

Things that I know do not work:

   - If the map is locked, I rely on some hardcoded map defaults that
     may not be valid assumptions for all map products (or individual
     IMG files).

   - Can only handle "single" IMG files (i.e., it can't parse the
     combined IMG files that are uploaded to the GPSr)

   - Sometimes it hangs and sometimes it coredumps. 

   - It only knows about 6 bit encoding for labels.

   - There are a few problems working out city properties for POIs.

   - Parsing of NET is limited to fetching labels only.  NOD is not
     touched.

There's probably a bunch of stuff that's wrong that I don't even know
about.