SOME DOCUMENTATION OF THE .QWE FORMAT

OVERALL ORGANIZATION:

   A planet or satellite can have up to three "bitmaps".  Each bitmap
is stored in a file with extension .QWE.  Consider,  for example,
Mars,  planet #4.  Its first bitmap is stored in the file 'planet04.qwe'.
Later,  when I added another bitmap,  it was named 'planeu04.qwe',  and
the third was 'planev04.qwe'.  Were more bitmaps to be added (and this
is a possibility),  they would be 'planew04.qwe',  and so on... after
'planez04.qwe',  we would switch back to 'planea04.qwe'.  Sort of like
the weird way in which variable stars are named.

   After plane*09.qwe (Pluto),  we have plane*10.qwe (Earth's moon),
then 11=Io,  12=Europa,  13=Ganymede,  14=Callisto,  15...22 = Mimas...
Japetus.  The full list of satellite numbers,  now up to 107,  follows
this text (I just cut-and-pasted from some source code.)

WHY I MADE YET ANOTHER FORMAT:

   The .QWE format allows one to store a given bitmap at multiple
resolutions.  For example:  the Clementine bitmap for the Moon is,
at maximum resolution,  12288 x 6144 pixels.  That sort of high
resolution is necessary when you really zoom in on the moon.  But
that .QWE also contains 4096x2048,  2048x1024,  1024x512,  256x128,
128x64,  64x32,  and 32x16 sampled versions of the big bitmap.

   Thus,  when you're at a wide field of view showing an entire
hemisphere of the moon,  Guide need not load in 12288 x 6144 pixels.
It can select something a little more suitable (the smaller bitmaps
make perfect sense when the moon only spans a few pixels on-screen,
a common occurrence.)  This scheme does add about 13% or so to the
file size,  but that's a small price to pay for "proper" drawing
without slowdowns at all scales.

   The other down side to doing this is that I had to come up with
my own format,  since (as far as I know,  at the time I did all this),
other formats don't support this sort of multiple-resolution trickery.

   In a perfect world,  the sampled versions would have been the
medians of pixels in the big image,  or averages,  or something of
that ilk.  (This is done frequently in games,  so that objects in
the distance look decent and not "pixillated" at different scales;
the technique is called MIP-mapping.)  I've left things imperfect;
all the .QWEs I've made so far just pick one pixel out of the
sampled area.

PROJECTION:

   The bitmaps are stored in cylindrical equal-area (Peters) projection.
The equal-area projection choice resulted in a modest speedup in the
code,  for reasons I'll spare you... the result is that,  for
a height x width bitmap,  the relationship between (lat, lon) and
(image_x, image_y) is:

image_x = (lat + 180) * width / 360
image_y = (1 - sin( lat)) * height / 2

lon = 360 * image_x / width - 180
lat = arcsin( 1 - 2 * image_y / height)

   This also has a downside:  the polar areas are "under-represented".
Get a viewpoint from high above a planet's pole and look down,  and
you will see that pixels look "stretched" near the poles.  Fortunately,
one rarely sees this effect... as yet,  no one has commented to me
on the phenomenon.

FORMAT:

   A series of short (two-byte,  Intel order) integers is stored in
the header of each QWE.  For the large Clementine lunar image,  these
integers are:

9     Nine sizes stored in this QWE
32    First bitmap: 32 by 16 pixels
16
64    Second bitmap: 64 by 32
32
128   Third bitmap
64
256   Fourth bitmap
128
512   Fifth bitmap
256
1024  Sixth bitmap
512
2048  Seventh bitmap
1024
4096  Eighth bitmap
2048
12288 Ninth and final and largest bitmap
6144

   ...for a total of 19 short integers,  or 38 bytes in the header.

   The actual image data is stored in 256 colors,  meaning we need
a palette.  That's what follows the above 38 bytes:  you get 3 * 256,
or 768,  bytes of palette data.  For each palette entry,  an R, G, and
B are given;  each value can range from 0 to 63 (_not_ 0 to 255,  as
in formats such as .BMP).

   Following the header and palette,  we get the actual images,
stored uncompressed as one byte/pixel.  Thus,  the palette bytes
would be followed by 32 * 16 = 512 bytes for the lowest-resolution
image,  then by 64 * 32 = 2048 bytes for the next,  and so on.
That's all there is to it.

WHY UNCOMPRESSED?

   Suppose you zoom in on a small chunk of the moon,  thereby requiring
that largest 12288 x 6144 image.  Since you'll only be covering a small
range of latitude,  it's quite likely that only a few hundred of those
6144 lines will actually be needed to cover the current field of view.
Because the .QWE data is uncompressed,  Guide can quickly figure out
the offset to the first line that's really needed,  and grab just
that chunk of the data.  If it were compressed,  it would have to
decompress the whole thing just to get the lines it wanted.

   It's also uncompressed because,  until we started to get some
_really_ big images such as the Clementine one,  and the Mars Global
Surveyor imagery,  and a couple of recent one-km resolution images of
the earth,  the file size didn't matter all that much.  I am now
pondering an extension to the QWE format which would allow line-by-line
(or perhaps "chunk of N pixels by chunk of N pixels") compression,
with an index to each chunk stored in the header.

/* 10 = lunar       */
/* 11 = io          */
/* 12 = europa      */
/* 13 = ganymede    */
/* 14 = callisto    */
/*                  */
/* 15 = mimas       */
/* 16 = enceladus   */
/* 17 = tethys      */
/* 18 = dione       */
/* 19 = rhea        */
/* 20 = titan       */
/* 21 = hyperion    */
/* 22 = iapetus     */
/*                  */
/* 23 = miranda     */
/* 24 = ariel       */
/* 25 = umbriel     */
/* 26 = titania     */
/* 27 = oberon      */

/* 28 = phobos      */
/* 29 = deimos      */

/* 30 = triton      */
/* 31 = charon      */

/* 32 = Himalia (J6)    (506) */
/* 33 = Elara (J7)      (507) */
/* 34 = Pasiphae (J8)   (508) */
/* 35 = Sinope (J9)     (509) */
/* 36 = Lysithea (J10)  (510) */
/* 37 = Carme (J11)     (511) */
/* 38 = Ananke (J12)    (512) */
/* 39 = Leda (J13)      (513) */

/* 40 = Phoebe          (609) */
/* 41 = Caliban (U16)   (716) */
/* 42 = Sycorax (U17)   (717) */
/* 43 = Nereid (N2)     (802) */

/* 44 = U18 = Prospero  (718) */
/* 45 = U19 = Setebos   (719) */
/* 46 = U20 = Stephano  (720) */

/* 47 = Amalthea        (505) */
/* 48 = Thebe           (514) */
/* 49 = Adrastea        (515) */
/* 50 = Metis           (516) */

/* 51 = Atlas           (615) */
/* 52 = Prometheus      (616) */
/* 53 = Pandora         (617) */
/* 54 = Pan             (618) */

/* 55 = Cordelia        (706) */
/* 56 = Ophelia         (707) */
/* 57 = Bianca          (708) */
/* 58 = Cressida        (709) */
/* 59 = Desdemona       (710) */
/* 60 = Juliet          (711) */
/* 61 = Portia          (712) */
/* 62 = Rosalind        (713) */
/* 63 = Belinda         (714) */
/* 64 = Puck            (715) */
/* 65 = 1986U10         (718) */

/* 66 = Proteus         (808) */
/* 67 = Larissa         (807) */
/* 68 = Despina         (805) */
/* 69 = Galatea         (806) */
/* 70 = Thalassa        (804) */
/* 71 = Naiad           (803) */

/* 72 = S/1999 J 1      (517)   Jupiter XVII  Callirrhoe  */

/*  73 = S/2000 S 1     (619) */
/*  74 = S/2000 S 2     (620) */
/*  75 = S/2000 S 3     (621) */
/*  76 = S/2000 S 4     (622) */
/*  77 = S/2000 S 5     (623) */
/*  78 = S/2000 S 6     (624) */
/*  79 = S/2000 S 7     (625) */
/*  80 = S/2000 S 8     (626) */
/*  81 = S/2000 S 9     (627) */
/*  82 = S/2000 S 10    (628) */
/*  83 = S/2000 S 11    (629) */
/*  84 = S/2000 S 12    (630) */
/*  85 = S/2000 J 1     (518) Jupiter XVIII   Themisto    */
/*  86 = S/2000 J 2     (519) Jupiter XXIII   Kalyke      */
/*  87 = S/2000 J 3     (520) Jupiter XXIV    Iocaste     */
/*  88 = S/2000 J 4     (521) Jupiter XXV     Erinome     */
/*  89 = S/2000 J 5     (522) Jupiter XXII    Harpalyke   */
/*  90 = S/2000 J 6     (523) Jupiter XXVI    Isonoe      */
/*  91 = S/2000 J 7     (524) Jupiter XXVII   Praxidike   */
/*  92 = S/2000 J 8     (525) Jupiter XIX     Magaclite   */
/*  93 = S/2000 J 9     (526) Jupiter XX      Taygete     */
/*  94 = S/2000 J 10    (527) Jupiter XXI     Chaldene    */
/*  95 = S/2000 J 11    (528) */
/*  96 = S/2001 J 1     (529) */
/*  97 = S/2001 J 2     (530) */
/*  98 = S/2001 J 3     (531) */
/*  99 = S/2001 J 4     (532) */
/* 100 = S/2001 J 5     (533) */
/* 101 = S/2001 J 6     (534) */
/* 102 = S/2001 J 7     (535) */
/* 103 = S/2001 J 8     (536) */
/* 104 = S/2001 J 9     (537) */
/* 105 = S/2001 J 10    (538) */
/* 106 = S/2001 J 11    (539) */
/* 107 = S/2001 U 1     (721) */

/* Still missing: S/2003 J 1...12,  S/2002 J 1, S/2002 N1...3 */
