Cheshire II Commands

COMMANDS

map- Create and manipulate map widgets (This is a builtin command for the cheshire2 and staffcheshire interpreters)

SYNOPSIS

map pathName ?options

See 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.)

"WIDGET-SPECIFIC OPTIONS"

Name: mapfile
Class: Mapfile
Command-Line Switch: -mapfile filename
This is required to specify the name of the file containing the map data. The currently sorted formats for map data are described below.

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.

INTRODUCTION

The map command creates a new window (given by the pathName argument) and makes it into a map widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the map such as its colors and centerpoint. The map command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

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.

"WIDGET COMMAND"

The map command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

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.

"OVERVIEW OF DRAWING ITEM TYPES"

The sections below describe the various types of drawing items supported by map widgets. Each item type is characterized by two things: first, the form of the create command used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the create and itemconfigure widget commands. Most items don't support indexing or selection or the commands related to them, such as index and insert. Where items do support these facilities, it is noted explicitly in the descriptions below (at present, only text items provide this support).

"LINE ITEMS"

Items of type line appear on the display as a single line segment. Lines are created with widget commands of the following form:

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

"RECTANGLE ITEMS"

Items of type rectangle appear on the display as a box of connected four connected line segments. Rectangles are created with widget commands of the following form:

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

"FILLEDRECTANGLE ITEMS"

Items of type filledrectangle appear on the display as a transparent filled box. Filledrectangles are created with widget commands of the following form:

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

"POLYGON ITEMS"

Items of type polygon appear on the display as a transparent filled shapes. Polygons are created with widget commands of the following form:

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

"POLYLINE ITEMS"

Items of type polyline appear on the display as one or more connected line segments. Lines are created with widget commands of the following form:

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

"POINT ITEMS"

Items of type point appear on the display as a single point or pixel at the latitude and longitude specified:

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

WDB-II Map Format

The WDB-II files used for the map drawing routines are sequential files composed of fixed length six byte records which can be accessed randomly. Each record is composed of three 16-bit signed integers. There are no record separators used in these files. The record layout is :

| 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.

"SCREEN COORDINATES"

All coordinates related to the width and height of maps are stored as floating-point numbers. These coordinates are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is m then the distance is in millimeters on the screen; if it is c then the distance is in centimeters; i means inches, and p means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right.

"SCREEN COORDINATES"

Coordinates of objects to be drawn on maps (including the base map itself) must be specified in some form of latitude and longitude. Complete latitude and longitude constants are specified as:

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...

ACKNOWLEDGEMENTS

Parts of the WDBII documentation and the associated data files are in the public domain and may used without fee so long as appropriate credits are included. Credit is hereby given to Fred Pospeschil and Antonio Riveria who created the microcomputer version of WDB-II on which this map widget is based. The original coordinate data for WDB-II was created by the Central Intelligence Agency.

BUGS

Works only with a particular version of The WDB II database, and is not a general map drawing facility.

Zooming is somewhat logrithmic, and probably should not be.

SEE ALSO

AUTHOR

Ray R. Larson ()