Cheshire
II CommandsSee the ``options'' manual entries for Tcl/Tk for details
on the standard options available for widgets.
(An example script using map widgets is included in
the cheshire2 directory of the distribution called map2.tcl -- it uses
data in the cheshire2/MAPDATA directory.)
Name: latitude
Class: Latitude
Command-Line Switch: -latitude latitude
Sets the latitude for the centerpoint of the displayed
map. Defaults to 0o0'0''N (the equator).
Name: longitude
Class: Longitude
Command-Line Switch: -longitude longitude
Sets the longitude for the centerpoint of the displayed
map. Defaults to 0o0'0''W (the prime meridian).
Name: height
Class: Height
Command-Line Switch: -height heightvalue
Specifies a desired window height that the map widget
should request from its geometry manager. The value may be specified in
any of the forms described in the COORDINATES section below.
Name: width
Class: width
Command-Line Switch: -width widthvalue
Specifies a desired window width that the map widget
should request from its geometry manager. The value may be specified in
any of the forms described in the COORDINATES section below.
Name: background
Class: Background
Command-Line Switch: -background or -bg color
This sets the background color to be used for the map
widget -- it defaults to Black (#000) on color screens, and to White (#FFF)
on monochrome.
Name: coastlines
Class: Coastlines
Command-Line Switch: -coastlines color
This sets the color for lines used to draw the outline
of continents. It defaults to green (#0A0).
Name: countries
Class: Countries
Command-Line Switch: -countries color
This sets the color for lines used to draw political
borders of countries. It defaults to red (#D00).
Name: states
Class: States
Command-Line Switch: -states color
This sets the color for lines used to draw political
borders of states in the U.S. and international zones (like the old Berlin
corridors). It defaults to yellow (#FF0).
Name: islands
Class: Islands
Command-Line Switch: -islands color
This sets the color for lines used to draw the coastlines
of islands (smaller than an continent). It defaults to light green (#5F5).
Name: lakes
Class: Lakes
Command-Line Switch:
-lakes color
This sets the color for lines used to draw the shorelines
of lakes. It defaults to light blue (#AAF).
Name: rivers
Class: Rivers
Command-Line Switch: -rivers color
This sets the color for lines used to draw the shorelines
of rivers. It defaults to blue (#33F).
Name: zoom
Class: Zoom
Command-Line Switch:
-zoom zoom_value
This sets the zoom_value (a floating-point number)
for the map. The zoom_value indicates how much area is displayed
around the centerpoint. when the zoom_value is about 1, the whole
world is displayed, when it is ~1000, or greater, the map is zoomed-in
to the maximum resolution. The zoom scale is not linear, and higher values
zoom-in less than low values.
Name: aspect
Class: Aspect
Command-Line Switch: -aspect aspect_value
The aspect_value is used to adjust the relationship
of X and Y points in drawing the map. This provides a rough way to correct
for distortion in the polar regions due to the cylindrical projection used
for the map. When looking at a full-size (zoom_value ~ 1) map centered
at the equator, an aspect value of about 110-120 appears similar
to a Mercator projection. This will vary depending on the size of the map
window. The aspect value can be used to "tweak" the appearance of the map.
It has a more obvious effect at higher "zoom" values.
Name: detail
Class: Detail
Command-Line Switch: -detail detail_value
This sets the level of detail drawn for the map. Acceptable
values range from 0 to 10. However, with the current default map provided
with the widget, only values 1 through 5 are really usable. The highest
level of detail is provided by a value of 1, and increasing the number
reduces the number of points/lines drawn. A value of 5 draws only every
fifth point, this can be done very fast, but there isn't much accuracy
or detail. A value of 1 or 0 takes longer to draw the map, but provides
much more detail.
The map widget has been developed as an extension to the Tcl/Tk language and is intended to provide a toolkit for simple geographic information retrieval (GIR) applications. The map widget and its associated widget commands (see below) provide a simple way to put geographic functionality into Tcl/Tk applications. A map widget is created in the same way as any other widget, e.g.:
map .mp.win1.mapwin -mapfile map.data -width 7i -height 3.5i -detail 4 -aspect 100
This statement starts with the "verb" map that indicates a request for a new map "widget". The verb is followed by the name to be used for the widget window created. The map widget follows the Tcl/Tk object-oriented style of object creation, with all subsequent operations on an object treated as commands where the "verb" is the name of the object involved, called "widget commands". In the statement shown above, the widget name is followed by a number of options specifying some characteristics of the map. The -mapfile option indicates the file name of where the map data is located.
The map widget currently uses data in a compressed format derived the World Data Bank II data set originally created by the Central Intelligence Agency and released to the public domain. Additional formats are planned for support of such things as TIGER map data (but aren't in the current release). The next options in the command above (-width and -height) provide the dimensions of the widget and may be specified in inches, centimeters, millimeters, printer's points, or screen pixel units. The -detail option indicates how detailed the map drawing should be, ranging from 1, representing the highest detail available, to 5 indicating that only about 1/5 of the detail will be displayed. The -aspect option is used to correct the appearance of map when zoomed in at high and low latitudes (the map widget uses a cylindrical projection, so there is a "spreading out" of features when drawing high and low latitudes). There are an number of additional options that can be specified in the map command, as shown above in the WIDGET SPECIFIC OPTIONS section.
pathName option ?arg arg ...?
Option and the args determine the exact behavior of the command.
The following widget commands are possible for map widgets:
pathName centerpixelscreenx screeny?
Given a screen x-coordinate screenx and screen y-coordinate screeny this command centers the map view on the point indicated by these screen coordinates.
pathName configure ?option? ?value? ?option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for ormation on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the canvas command.
pathName create type color lat lon ?lat lon ...? ?
Create a new drawing object in pathName of type type in color color. The exact format of the arguments after type and color depends on type, but usually they consist of the latitude and longitude coordinates for one or more points. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item.
pathName destroy object_id
Deletes a drawing object created by the create command from the map. The object_id argument is the id returned by the create command for the item.
pathName display | redisplay
Redraw the current map at the current latitude and longitude. (Generally not needed, re-drawing is usually automatic when any change is made to the map widget options).
pathName distance pixel1_x pixel1_y pixel2_x pixel2_y
Return the approximate distance in miles (float value) between the points on the map indicated by the screen pixel x and y coordinates.
pathName getcenter
Return a list whose elements are the latitude and longitude associated with the centerpoint of the current map display.
pathName getframe
Return a list whose elements are the latitude and longitude associated with the top left corner and bottom right corner of the current map display. E.g., the value will look something like:
54o5'48''N 110o1'1''W 31o10'48''N 68o21'1''W
pathName getlatitude
Return the latitude associated with the centerpoint of the current map display.
pathName getlongitude
Return the longitude associated with the centerpoint of the current map display.
pathName getlatlon screenx screeny
Return a list whose elements are the latitude and longitude associated with the given screen pixel coordinates of the current map display.
pathName getxy latitude longitude
Return a list whose elements are the screen pixel x and y coordinates associated with the given latitude and longitude specifications. If the map display doesn't contain the coordinate specified, the list elements returned are {-1 -1}.
pathName rubberband end? | type color lat lon ?lat lon ...?
Create a new drawing object that can be "stretched" as it is displayed without affecting other display graphics. The drawing objects are of any type described in the following section. Otherwise this is similar to the the create command above. The end option transforms the rubberband object into a normal object, in the color specified in the original rubberband command. There can be only one rubberband object at a time.
pathName zoommap [+|-]zoomval
Zoom the map view to a different level. Using plus (+) or minus (-) changes the zoom value relative to its current setting. Any other number (in a floating point form) zooms to that value and redisplays the map.
pathName create line color lat1 lon1 lat2 lon2
The arguments lat1 through lon2 give the coordinates for
two latitude/longitude points that describe the end points of the line
on the map. Color gives the color to be used for drawing the line (in any
standard TK color format). For example:
.map create line white 0o0'0''N 179o0'0''W 0o0'0''N
179o59'59''E
pathName create rectangle color lat1 lon1 lat2 lon2
The arguments lat1 through lon2 give the latitude and
longitude coordinates for the top-left and bottom-right corners of the
box, respectively. Color gives the color to be used for drawing the rectangle
(in any standard TK color format). For example:
.map create rectangle violet 50o0'0''N 70o0'0''W
10o0'0''N 20o0'0''W
pathName create filledrectangle color lat1 lon1 lat2 lon2
The arguments lat1 through lon2 give the latitude and
longitude coordinates for the top-left and bottom-right corners of the
box, respectively. Color gives the color to be used for filling the rectangle
(in any standard TK color format). A stipple pattern is used for filledrectangle
items. For example:
.map create filledrectangle violet 55o0'0''N 75o0'0''W
5o0'0''N 15o0'0''W
pathName create polygon color lat1 lon1 ... latN lonN
The arguments lat1 through lonN give the latitude and
longitude coordinates for each vertex of the polygon. Note that the last
vertex pair is NOT automatically the same as the first supplied, so polygon
items need to have the last vertex the same as the first to create the
filled object. Color gives the color to be used for filling the rectangle
(in any standard TK color format). A stipple pattern is used for filledrectangle
items. For example:
.map create polygon blue 23o0'0''N 120o0'0''W 24o0'0''N
120o0'0''W 25o0'0''N 22o0'0''W 20o0'0''N 122o0'0''W 23o0'0''N 120o0'0''W
pathName create polyline color lat1 lon1 ... latN lonN
The arguments lat1 through lonN give the coordinates for
a series of two or more points that describe a series of connected line
segments. Note that the last vertex pair is NOT automatically the same
as the first supplied, so polyline items need to have the last vertex the
same as the first to create a closed set of lines. Color gives the color
to be used for the lines (in any standard TK color format). For example:
.map create polyline yellow 23o0'0''N 120o0'0''W 24o0'0''N
120o0'0''W 25o0'0''N 22o0'0''W 20o0'0''N 122o0'0''W 23o0'0''N 120o0'0''W
pathName create point color lat lon
The arguments lat and lon give the coordinates for the
latitude/longitude point on the map. Color gives the color to be used for
drawing the point (in any standard TK color format). For example:
.map create point white 23o0'0''N 120o0'0''W
| Code | Latitude | Longitude
Or, as a structure in C:
struct { short Code;
short Latitude;
short Longitude; } PNT ;
Within the WDB-II files the records are stored as shown below. In some cases there may be hundreds of points in a single line segment. In other cases there may be consecutive header records which locate individual points to be plotted.
|Header|Point1|Point2|...|PointN|Header|Point1|Point2|...|PointN|Header|Point1|Point2|Header|
Header|Header|Point1|Point2|PointN|
The same format is used for both the line header records
and point records. The usage of each field is as follows :
CODE - Line Header Records.
The CODE field is used to :
1. Identify the type of line segment which is described by the point records which follow it,
2. Identify the line or point within the line type, and
3. Provide the coordinates if the record describes a point.
In header records the CODE field is always a positive
four digit number in the form of :
ABBB where
A =
BBB =
CODES =
1 = Coast lines
001 -> 208
1001 -> 1208
2 = Country boundries
001 -> 301
2001 -> 2301
4 = State boundries
001 -> 111
4001 -> 4111
5 = Islands
001 -> 344
5001 -> 5344
6 = Lakes
001 -> 103
6001 -> 6103
7 = Rivers
001 -> 196
7001 -> 7196
CODE - Point records.
In point records the CODE field contains the detail level. The detail level is a value in the range of 1 through 5. To properly retrieve points at any detail level use the following comparison :
if (code >= desired_detail_level) ...
LATITUDE and LONGITUDE - In both header and point records.
The latitude and longitude fields contain the coordinate
values expressed in signed minutes. The values in these fields are computed
with the formula COORD_VALUE = (Degrees * 60) + Minutes. Thus, the ranges
of coordinate values in WDB-II are :
90 00N = 5400
90 00S = -5400
180 00E = 10800
180 00W = -10800
WDB-II uses the standard four quadrant cartesian coordinate system in which north, south, east, and west are referenced to the equator and the Greenwich meridian.
When a header record is followed by point records the coordinates in the header record are the beginning of the line. When a header record is followed by another header record then the coordinates in the header record should be plotted as a single point. When working at low levels of detail it is common to find multiple consecutive header records which locate isolated points. There may also be gaps between some of the lines.
degreesominutes'seconds''{N,S,E,W}
(that is lowercase 'o' for the degrees symbol). In this
form the coordinates of San Francisco might be specified as: 37o46'30''N
122o25'1''W. There are a few functions for transforming from one coordinate
specification to another. The degrees_to_latlon tcl function takes
longitude and latitude values expressed as decimal degrees (eg. "37.775002
-122.416946" for the latlon value shown above). latlon_to_degrees
performs the inverse operation. For example:
% degrees_to_latlon 45.000 -122.50
45o0'0"N 122o30'0"W
% latlon_to_degrees 45o0'0"N 122o30'0"W
45.000000 -122.500000
If someone wants to hack up a set of other coordinate transforms, please do...
Zooming is somewhat logrithmic, and probably should not be.