VMF.txt

The VMF format is a convenient ASCII vector map format which has been 
designed to work with sunclock. It has been originally inspired by the
algorithms used by xearth ((C) Kirk Lauritz Johnson) to encode Earth 
regions - however, many changes have been introduced later, so that not 
much of the original settings remain ...

We now come to the precise VMF specifications

=============================
INITIAL SIGNATURE OF THE FILE
=============================

>>>   %!VMF is the initial signature for the format

========
COMMENTS
========

Any character % indicates a comment until a newline character is found.
Comments can be included anywhere (in general at the beginning of a new line.)

======
COLORS
======

The first data to be specified at the top of the VMF file should be a 
list of colors, either in the form explicit RGB values (#rrggbb 
where rr, gg, bb are 2 place hexadecimal values standing respectively 
for red, green, blue in the range 0..255) or conventional names of 
colors, in the format understood by the XAllocNamedColor() Xlib routine.
Each color occupies one line, and the end of the list is indicated by a
semicolon ;

Then come a default color, indicated by its index in the range
0 .. num_colors. This is the color which will be used if there is no 
other match from the list of colors.
 
The next data are the palette values, given in the form  
(color --> list of codes):

>>>   c0  j1 j2 j3 ...
>>>   c1  k1 k2 ...
>>>   c2  l1 l2 l3 l4
>>>   c4  ...
>>>   (etc)
>>>   cN  u1 u2 ...
>>>   ;

Do not forget the final semicolon to indicate that the palette values are 
complete. The meaning of this is that codes j1 j2 j3 will be attributed 
color 0 (first listed color), codes k1 k2 will be attributed color 1 
(second listed color), etc. All c* values should be in the range
0 .. num_colors-1

The next value is the "background value", that is the color code which will
be affected to all pixels, before the codes are modified by drawing objects 
on the map (thus initially the screen is entirely filled with this color).

====================
RANGE OF COORDINATES
====================

Follows a line starting with the keyword "range" and indicating four 
float values:

>>>   range  <phi_min> <phi_max> <theta_min> <theta_max>

which sets the range in which the latitude phi and longitude vary, e.g. :
>>>   range  -90.0 90.0 -180.0 180.0

=======================
OPTIONAL OPTIONS / DATA
=======================

Then come a number of optional options and flags and arrays of curves /
filled areas / text labels in any succession. The positions are specified
by arrays of coordinate values, given as pairs (phi, theta) of latitude 
and longitude of points on Earth in decimal degrees, with -90 <= phi <= 90
and (ususally) -180 <= theta <= 180 (the latter is not absolutely 
required since longitudes are taken mod 360 degrees). They are just
Such arrays are meant to represent piecewise linear curves, which can be
either open or closed, filled as regions or just represented as continuous
lines. The syntax is as follows

>>>   #<index> <color_value>
>>>   phi1 theta1  phi2 theta2  phi3 theta3 ...
>>>   ;

where <index> is an arbitrary nonnegative integer (normally the actual
rank of the curve by increasing order in the file, but the VMF format
does not check this), and <color_value> is an arbitrary (positive or 
negative) integer. The end of the array of coordinates is indicated by
a semicolon (usually starting a new line). In between, the coordinates
are just float values separated by blank spaces or new lines (no 
parentheses nor commas should be used).

===============
DRAWING OPTIONS
===============

The drawing options (to be set before a curve or filled area is started) are

>>>   fillmode 2       % fill curves
>>>   closedcurves     % close the curves before filling

Other options :

>>>   fillmode 0       % draw line (no filling)
>>>   fillmode 1       % draw line (alternate algorithm)
>>>   opencurves       % don't close the path before drawing a line

>>>   zoomwidth <val>  % don't draw unless zoom.width >= value
>>>   zoomheight <val> % don't draw unless zoom.height >= value

Normally, the curves should be non-self-intersecting and traced in a
counter-clockwise orientation (in case of a filled area, reversing the 
orientation is equivalent to taking the opposite of the value
<color_value> representing the color code).

If a point is contained in several overlapping domains bounded by the
specified curves, the "color value" obtained at that point is (as a 
consequence of the filling algorithm) the sum of the <color_value>'s
corresponding to each curve, plus the background value.
(If there are many domains overlapping randomly, it may then be advisable
to use powers of 2 as color values, so that the combination produces
a result that is unique to those combinations of domains.)
The practical limit on the code values is 2^15-1.

=====
FLAGS
=====

Sunclock sets a "vmfflag" value (default value 0xFFFFFFFF = -1) whose
purpose is to enable/disable sections of the VMF file according to
the vmfflag value, using an AND test. The value of the flag can be set
e.g. as follows :

>>>   flag 4

Then if  vmfflag&4  is non zero, the following section will be drawn,
otherwise it will be ignored.

The zeroth order bit (i.e. &1) determines whether features which have their
own zeroth bit set are to be drawn in clock window mode (versus map mode - 
if the zeroth bit is not set, the feature will always be drawn, whether
the window is in map mode or not).

===========
TEXT LABELS
===========

Finally, here is the syntax for putting text labels

>>>   label 1720 14 0 -87.000 165.000
>>>   +11 timezone
>>>   ;

This is the label of index 1719 (value irrelevant), color 14, in position 0
(-1=on the left, 0=centered, 1=on the right), at coordinates 
  phi=latitude=-87.0, theta=longitude=165.0
whose string value is "+11 timezone". Multi-line labels are allowed.
In order to disable the new line character (so that no line break
appears, the last character of the line should be \
Any initial blank space of each line is removed (if one insists on
starting by a blank space, the line should start with two blank spaces).
The label terminates when ; is met as the first character of the line.

===========
END OF FILE
===========

Not surprinsingl, the end of the file is marked by the keyword "end"


========================
A TYPICAL SAMPLE OF DATA
========================

%!VMF
% Vector Map Format for Sunclock
%
% List of colors
#BFEFFF % 0 LightBlue1
#FFFACD % 1 LemonChiffon
#FFFF69 % 2 LightYellow
#BEB208 % 3 DarkGold
#86CB28 % 4 YellowGreen
#D7EB00 % 5 GreenGold
#8CCD8C % 6 LightGreen3
#CD7054 % 7 Salmon3
#EE8262 % 8 Salmon2
#DEB887 % 9 Burlywood
#F4A460 % 10 SandyBrown
#000000 % 11 Black
#0000FF % 12 Blue
#FF0000 % 13 Red
#000000 % 14 Black
;

% Default color
0

% Palette (possibly several codes for each color: ci j1 j2 j3 ... )
c0 0
c1 1
c2 2
c3 3
c4 4
c5 5
c6 6
c7 7
c8 8
c9 9
c10 10
c11 11
c12 12
c13 13
;

% Background value
1

% Coordinate range (latitude, longitude)
range -90 90 -180 180

% List of closed curves of land areas & lakes
% Set internal flag
flag 2

% Fill mode = fill areas within closed curves
fillmode 2
closedcurves

#0 3
 21.364 -157.706   21.568 -157.862   21.642 -158.075   21.456 -158.211
 21.383 -158.017   21.252 -157.823 ;
  
#1 3
 21.159 -156.871   21.196 -157.065   21.085 -157.279   21.103 -157.065
 21.048 -156.871
;
    

% Fill mode = fill areas within closed curves
fillmode 2
closedcurves

#0 3
 21.364 -157.706   21.568 -157.862   21.642 -158.075   21.456 -158.211
 21.383 -158.017   21.252 -157.823 ;
  
#1 -4
 21.159 -156.871   21.196 -157.065   21.085 -157.279   21.103 -157.065
 21.048 -156.871
;
    
%% Note : putting 0 as color is equivalent to disabling the curve)

% Fill mode = draw open curves
fillmode 0
opencurves

#1565 13
 90.000 -157.512   70.964 -157.512
 ;
 
#1566 13
 90.000 -142.503   79.997 -142.503   69.972 -142.503
;

% Write a few labels (with flag = 9)

flag 9
label 1708 14 0 -87.000 0.000
0
;
label 1709 14 0 -87.000 15.000
+1
;
label 1710 14 0 -87.000 30.000
+2
;
label 1711 14 0 -87.000 45.000
+3
;
    
end