See the file man.macros.

NAME

tkgeomap - a package for displaying geographic lines and points in canvas widgets.

VERSION

SYNOPSIS

package require tkgeomap ?2?

INTRODUCTION

The tkgeomap package adds two item types to the canvas widget. The first type, geomap_lnarr displays a linearray, which is an anonymous set of points created with the geomap::lnarr command. The other type, geomap_place displays a named place created with the geomap::place command. See the tclgeomap (n) man page for information on how to create linearrays and places.

DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS

The map that contains a geomap_lnarr or geomap_place item is defined by the item's coords and by its configuration. This section describes the configuration options that define the map. geomap_lnarr and geomap_place items have other type specific configuration options, which are described in later sections. Items can be drawn on the same map giving them the same map configuration. This is most easily done by giving them a common tag and applying the map configuration to items with that tag. Here are the configuration options that define a map.

-refpoint {lat lon}: This option specifies the reference point of the item, which is the {lat lon} at the x, y coordinates given as the item's coords. Note that the reference point is not necessarily the location of the place in a geomap_place item, nor is it necessarily a point on the linearray displayed in a geomap_lnarr item. It only helps define the map in which the item is displayed. Other lat-lon's are positioned relative to the reference point. A map can be shifted by changing the reference point with the -refpoint option, or by changing the item's coordinates with the canvas coords or move command. A useful convention is to keep all item coords at the center of the canvas. Then the refpoint value is the lat-lon at the center of the canvas, which is presumably a point of interest.
-projection projId: Specifies the geographic projection for converting {lat lon} values to map coordinates. projId must be the name of a command returned by the geomap::projection command. See the tclgeomap man page for information on how to create and manipulate projections. If no projection is specified, the item is not drawn.
-rotation doubleValueORdirection: Specifies the map's orientation. A value of 0.0 or north means the top of the map is north. A double value gives the number of degrees the map is rotated clockwise from the conventional north-is-up orientation. A value of north, nneast, neast, eneast, east, eseast, seast, sseast, south, sswest, swest, wswest, west, wnwest, nwest, or nnwest gives the direction at the top of the map.
-scale doubleValue: Specifies the cartographic scale for converting distances on the projection plane to distances on the printed or displayed map.

The actual canvas coordinates of a geomap_lnarr or geomap_place item can be retrieved by adding the keyword dump to the coords command.

GEOMAP_LNARR ITEMS

Items of type geomap_lnarr display and allow users to interact with arrays of geographic points, called linearrays, created with the geomap::lnarr command. See the tclgeomap (n) man page for information on how to create and manipulate linearrays. geomap_lnarr items can display linearrays in three ways. First, the points can be connected to make outlines. Second, the regions bounded by the points can be filled with a solid color, assuming they are closed polygons. Third, dots can be drawn at the points. The display method is determined by the item configuration, described below.

geomap_lnarr items are created with widget commands of the following form:

pathName create geomap_lnarr x y ?option value option value ...?

The options x and y give the canvas coordinates of the geomap_lnarr item's reference point, which is defined in its configuration. (See "DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS" above). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option value pairs may be used in itemconfigure widget commands to change the item's configuration.

COMMON CANVAS OPTIONS FOR GEOMAP_LNARR ITEMS

geomap_lnarr items support the following standard options. See the canvas (n) man page for details.

-fill
-stipple
-outline
-tags

SPECIAL OPTIONS FOR GEOMAP_LNARR ITEMS

In addition to the map options and standard options described above, geomap_lnarr items also recognize the following special options.

-lnarr arrayName: Specifies the name of a linearray to display in the item. arrayName should be the name of a linearray, usually created by the geomap::lnarr command. See the tclgeomap (n) man page for information on how to create linearrays. When setting the linearray to display, arrayName MUST BE FULLY QUALIFIED unless the array command is global. If arrayName is an empty string, no linearray will be displayed in the item. When this option is used to retrieve the array name, such as with cget, only the base name (without any :: namespace qualifiers) is returned. If linearray arrayName is deleted, the item disappears from the canvas, although the item continues to exist, and the value for this option becomes an empty string.
-width outlineWidth: Specifies the width of lines to draw. outlineWidth can be a coordinate specifier as described in the canvas (n) man page, or it can be none, "", or a negative number to indicate no lines should be drawn.
-linestyle style: Specifies a linestyle, either LineSolid or LineOnOffDash.
-dashes dashLength: Specifies the length of dashes it line style is LineOnOffDash.
-smooth boolean: Specifies whether to smooth the outline. boolean must have one of the forms accepted by Tk_GetBoolean. Currently, only bezier smoothing is available. If set, the line will be rendered as a set of parabolic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment.
-splinesteps number: Specifies the degree of smoothness desired for curves: each spline will be approximated with number line segments. This option is ignored unless the -smooth option is true.
-shape polygonType: Tells the type of shape to be filled in when using the -fill option. This option is usually unnecessary, but might improve performance. Shape must be one of Convex, Nonconvex, or Complex. Convex means any segment connecting two points on the polygon does not cross the polygon. This type of shape can be faster to draw. Nonconvex means the shape is not convex, but it does not cross itself. Complex means the shape might cross itself. Results are undefined if a shape is given as convex when it is not, or nonconvex when it is complex. Note that the assumption must apply for all projections used.
-dotsize number: Specifies size in pixels of dots to draw at the segment ends. If number is greater than 0 and the -width and -fill options are set to 0, the linearray will be displayed as a collection of dots, which can be useful for making density plots or simple images.

GEOMAP_PLACE ITEMS

Items of type geomap_place display and allow users to interact with named geographic locations. See the tclgeomap (n) man page for information on how to create and manipulate places. geomap_place items can display dots, bitmaps, and text at given geographic locations.

geomap_place items are created with widget commands of the following form:

pathName create geomap_place x y ?option value option value ...?

The options x and y give the canvas coordinates of the geomap_place item's reference point, which is defined in its configuration. (See "DEFINING A GEOGRAPHIC MAP FOR GEOMAP_LNARR AND GEOMAP_PLACE ITEMS" above). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option value pairs may be used in itemconfigure widget commands to change the item's configuration.

OPTIONS FOR GEOMAP_PLACE ITEMS

In addition to the map configuration options described above, geomap_place items recognize the following options.

-place placeName: Specifies the name of a geoplace to display in the item. placeName should be the name of a geoplace created with either the geomap::place new or geomap::place set command. See the tclgeomap (n) man page for information on how to create places. When setting the place to display, placeName MUST BE FULLY QUALIFIED unless the place command is global. If placeName is an empty string, no place will be displayed in the item. When this option is used to retrieve the place name, such as with cget, only the base name (without any :: namespace qualifiers) is returned. If geoplace placeName is deleted, the item disappears from the canvas, although the item continues to exist, and the value for this option becomes an empty string.
-dotcolor color: Specifies the color of a dot drawn at the place. color may have any of the forms accepted by Tk_GetColor. If color is an empty string, no dot is drawn at the place.
-dotsize integer: Specifies the size of dot to draw at the place. If integer is <= 0, no dot is drawn at the place.
-bitmap bitmap: Specifies a bitmap to draw at the place. bitmap may have any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string, no bitmap is drawn.
-bitmapcolor color: Specifies the bitmap color. color specifies the bitmap foreground color, which is used for bitmap pixels whose value is 1. color may have any of the forms accepted by Tk_GetColor. If color is an empty string, no bitmap is drawn at the place.
-text string: Specifies a string of text to display at the place.
-textcolor color: Specifies the text color. color may have any of the forms accepted by Tk_GetColor.
-font fontName: Specifies the font to use for the text item. fontName may be any string acceptable to Tk_GetFontStruct.
-anchor anchorPos: Tells how to position the text relative to the place. It may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the text is centered on the place; if anchorPos is n then the North end of the text will be at the place.
-arrow {azimuth shaft_len tip_len}: Draws an arrow at the place. The arrow will be oriented azimuth degrees clockwise from true north. The shaft will be shaft_len pixels long. The tip will have edges 'shaft_len * tip_len' pixels long, i.e. tip_len is a fraction of shaft_len.
-arrowcolor color: Specifies the arrow color. color may have any of the forms accepted by Tk_GetColor.
-tags tagList: Standard tags option to identify the item in canvas widget commands.

FILES

These commands are added to wish by the tkgeomap package in file libtkgeomap.so or libtkgeomap.a built by the tkgeomap-2.11.6 distribution. It is part of the tkgeomap executable, or can be added to the current interpreter with the load or package commands. Run package names to determine if the tkgeomap package is present. See the tkgeomap-2.11.6 distribution for installation information.
The code for the bezier spline computation was shamelessly lifted from tkTrig.c and tkUtil.c of the Tk8.3.0 source distribution.

AUTHOR

Gordon Carrie <user0@tkgeomap.org>