Laurent Zimmermann wrote:
>Yes, that is a very good idea to document the binary format of UOV files !
I screened my hard disk to dig out Bill's 1995 letter describing the UOV
format.
It is still the same format today.
Hartwig
Bill' s letter follows
----------------------------------------------------------------------------
----------------------------------------
I recently finished a description of the overlay format. I really
should have sent a copy to you earlier... anyway, the description follows:
FORMAT AND USE OF GUIDE .UOV (USER OVERLAY) FILES
With Guide 4.0, there is now a fairly powerful system for adding
user-described overlays to a chart. The program is distributed with some
sample overlays such as the outlines of the Palomar Sky Survey plates and
the AAVSO charts. Some others are stored in the \TEXT directory of the
Guide CD-ROM, such as CHART.UOV (shows areas for which the AAVSO has
comparison-star charts) and LEITNER.UOV (an example overlay showing some
areas covered by a set of plates).
First, I'll discuss how to add a new .UOV file so that Guide will
recognize it. This will allow you to view CHART.UOV or LEITNER.UOV, or
.UOV files created by others and distributed on networks; using them
is simple to do. Second, I'll discuss the format of the overlays; this
is useful if you want to create or read overlays with your own software.
If you don't want to do that, you can ignore the second part. You do need
to be a bit of a programming, bits-and-bytes kind of citizen to make use
of the overlay format information.
To view overlays such as CHART.UOV or LEITNER.UOV, you first have to
copy the .UOV file to the Guide directory on your hard drive. Next,
you'll have to edit the file OVERLAYS.NAM on your hard drive. This file
contains a line for each overlay. A line such as
pq_and.uov * PQ And finder chart 91 0
means "the file pq_and.uov, which will be listed in the software by the
name 'PQ And finder chart', can be displayed at fields of view ranging from
zero to 91 degrees." The asterisk means that this overlay is currently
turned on; were it not, there would be a space in that column of the file.
The "PQ And finder chart" essentially just provides a long file name
scheme
without the need for Windows 95. The file does need a .UOV extension;
aside
from that, any DOS filename will serve.
You'll notice that the top line contains a four-digit number declaring
how many overlays are listed in the file. If you add or remove a line, you
need to change this number. Also, each line is exactly the same length;
keep this in mind when you edit the file.
And now for the actual .UOV file format... The following types of
objects
are supported:
'l' Lines (series of segments, such as in constellation boundaries)
'c' Closed polygon (such as the plate outlines in POSS.UOV; identical
to 'l', except that the first and last points are connected)
'x' Object trails (as created in planetary animation; like 'l', except
that they get cross-marks at the interval specified in the
Animation
menu)
't' Text
'e' Circle
's' Star (not yet supported, but will be soon)
Every object begins with a line of ASCII text, terminated with either a
line-feed (ASCII 10) or carriage-return/line-fee (ASCII 13 and 10). The
first character of the line is one of the six letters listed above. The
second character is a space by default; when an object is deleted, this
character is replaced by a '!'. The third character is a '0'. After this,
things become confused:
For 'c', 'l', 'x', the fourth through sixth characters
contain the object line style and color. This number is equal to
(style * 16 + color), where
style=0 means solid line,
style=1 means long dashes,
style=2 means shorter dashes,
style=3 means dot-dash.
Colors 0-15 refer to
0 Black
1 Bright Green
2 Orange
3 Cyan
4 Yellow
5 Red
6 Brown
7 Purple
8 Blue
9 Magenta
10 Dark Green
11 Middle Green
12 Bright Green
13 Dark Gray
14 Light Gray
15 White
Characters 7-end of line contain the number of points N in the line.
Finally, after the carraige-return/line-feed or line-feed, N points are
stored, each six bytes long. Each point contains a three-byte RA and
three-
byte declination. Three bytes allows one to specify any angle from 0 to
360 degrees with a precision of .077 arcseconds, sufficient for most
purposes. The data for an angle X degrees is stored in the three bytes as
follows:
-180 <= x < 180; add or subtract 360 to get into this range
Z = (X + 180) * (2^24) / 360
(so 0 <= Z < 2^24, a 24-bit quantity)
byte[0] = Z mod 256 (least significant byte of Z)
byte[1] = (Z / 256) mod 256 (next least significant byte of Z)
byte[2] = (Z / 65536) mod 256 (most significant byte of Z)
For 't' (text) objects, the fourth through sixth characters now store
the color and text alignment, stored as (alignment * 16 + color), where
'color' has the same meaning as before, and
alignment=0 means centered vertically and horizontally,
alignment=1 means aligned center and right,
alignment=2 means aligned center and left,
alignment=3 means aligned at the lower center,
alignment=4 means aligned to the lower right,
alignment=5 means aligned to the lower left,
alignment=6 means aligned at the upper center,
alignment=7 means aligned to the upper right,
alignment=8 means aligned to the upper left,
The text follows, starting in the seventh character. Following the line
is one point, stored in six bytes, in the form described for 'l', 'x',
and
'c' objects.
For 'c' (circle) objects, the drawing style and color are set as for
'l', 'x', and 'c' objects. The CR/LF or line-feed is followed by 9 bytes:
6 contain the circle's center point in RA/dec, as defined above, and the
last three contain the circle's radius, defined in angular measure, and
also stored as described above.
For 's' (star) objects, the format is quite different, because no color
is stored. Instead, characters 4-7 store the magnitude in units of .01 mag
(i.e., "1289" means a magnitude 12.89 star). The star's position follows
stored as before, as a six-byte value. As mentioned above, stars are not
supported yet.
As with anything else in Guide, let me know if you have questions about
any of this, or ideas for improvement, and so forth.