tclgeomap(n) Tcl Extensions tclgeomaptclgeomap(n)NAME
tclgeomap, georadius, latlonok, mapptok, lonbtwn, gclcross, rotatpt,
scalept, domnlat, domnlon, domnlonpt, gwchlon, gwchpt, dmstodec, dec‐
todm, dectodms, cartg, centroid, projection, lnarr, place - commands
for manipulating geographic data in Tcl.
VERSION
2
SYNOPSIS
package require tclgeomap ?2?
geomap::version
geomap::georadius ?radius? unit
geomap::latlonok {lat lon}
geomap::mapptok {abscissa ordinate}
geomap::lonbtwn lon {lon1 lon2}
geomap::gclcross l1p1 l1p2 l2p1 l2p2
geomap::rotatpt {abs ord} theta
geomap::scalept {abs ord} factor
geomap::domnlat lat
geomap::domnlon lon rlon
geomap::domnlonpt {lat lon} rlon
geomap::gwchlon lon
geomap::gwchpt {lat lon}
geomap::dmstodec {deg ?min ?sec?? NorS deg ?min ?sec?? WorE}
geomap::dectodm degOR{lat lon}
geomap::dectodms degOR{lat lon}
geomap::cartg {1:XXXXXXX}ORdoubleValue
geomap::centroid point_list
geomap::time jul_to_cal {julian_day second}
geomap::time cal_to_jul {year month day hour minute second}
geomap::time incr {year month day hour minute second} seconds
geomap::time cmp time1 time2
geomap::time diff time1 time2
geomap::projection projType ?options?
projId set projType ?options?
projId rotation ?angle?
projId info
projId fmlatlon {lat lon}
projId tolatlon {abscissa ordinate}
geomap::lnarr fmlist lnArrName listValue
geomap::lnarr fmascii lnArrName fileName ?-descrlen len? ?-format format?
geomap::lnarr fmxdr lnArrName fileName
geomap::lnarr fmbin lnArrName fileName
lnArrName tolist
lnArrName toascii fileName ?-ptperln n? ?-format format?
lnArrName toxdr fileName
lnArrName tobin fileName
lnArrName info
lnArrName descr ?newDescriptor?
lnArrName containpt geopoint
geomap::place new placeName {lat lon}
geomap::place set placeName ?{lat lon}?
geomap::place distance placeNameOR{lat lon} placeNameOR{lat lon} ?unit?
geomap::place azrng placeNameOR{lat lon} placeNameOR{lat lon} ?unit?
geomap::place nearest placeNameOR{lat lon} placeList
geomap::place step placeNameOR{lat lon} bearing range ?unit?
geomap::place inrange placeNameOR{lat lon} {range ?unit?} ?placeList?
placeName set ?{lat lon}?
placeName nearest placeList
placeName step bearing range ?unit?
placeName inrange {range ?unit?} placeList
INTRODUCTION
The tclgeomap package adds Tcl commands for storing and manipulating
geographic data. It includes commands for calculating geographic dis‐
tances and angles, applying common map projections, creating named
places, and creating sets of anonymous points. Unless otherwise noted,
angles, including latitudes, longitudes, and great circle distances are
measured in DEGREES, and straight-line distances are measured in
METERS.
GENERAL GEOGRAPHY COMMANDS
geomap::version
Prints version and copyright information.
geomap::georadius ?radius? unit
Returns the radius of the Earth in unit, or sets the radius of
the Earth to value radius in unit unit. unit must be one of nmi
(international standard nautical mile = 1852.0 m), smi (statute
mile = 1609.344 m), km (kilometers), meters (meters) or cm (cen‐
timeters).
geomap::latlonok {lat lon}
Returns true (1) if {lat lon} is a valid geographic point. It
returns false (0) if {lat lon} is invalid, for example, if one
attempts to convert a projection point that is outside the pro‐
jection domain.
geomap::mapptok {abscissa ordinate}
Returns true (1) if {abscissa ordinate} is a valid map point,
otherwise it returns false (0).
geomap::lonbtwn lon {lon1 lon2}
Returns true (1) if longitude lon is between longitudes lon1 and
lon2, otherwise it returns false (0). It correctly handles
intervals containing the International Dateline and other singu‐
larities.
geomap::gclcross l1p1 l1p2 l2p1 l2p2
Returns the {lat lon} of the intersection of two great circles,
given two points on each great circle. The great circles must
be defined as follows:
l1p1 = {lat11 lon11} = 1st point of 1st great circle
l1p2 = {lat12 lon12} = 2nd point of 1st great circle
l2p1 = {lat21 lon21} = 1st point of 2nd great circle
l2p2 = {lat22 lon22} = 2nd point of 2nd great circle
Great circles intersect at two points. The result is the inter‐
section closer to the average location of the four points. If
the intersection is undefined (i.e. all the points are on the
same great circle), the command raises an error.
geomap::rotatpt {abs ord} theta
Returns point {abs ord} rotated theta degrees clockwise.
geomap::scalept {abs ord} factor
Returns {abs ord} scaled by factor.
geomap::domnlat lat
Returns a latitude equivalent to lat in the range -90 <= lat <=
90. In this context, equivalent means with the same sine.
geomap::domnlon lon rlon
Returns a longitude equivalent to lon but in the domain of rlon.
In other words, it adds or subtracts a multiple of 360 such that
rlon - 180 < lon < rlon + 180.
geomap::domnlonpt {lat lon} rlon
Returns a point equivalent to {lat lon} whose longitude is in
the domain of rlon.
geomap::gwchlon lon
Equivalent to "domnlon lon 0.0".
geomap::gwchpt {lat lon}
Equivalent to "domnlonpt {lat lon} 0.0".
geomap::dmstodec {deg ?min ?sec?? NorS deg ?min ?sec?? WorE}
Returns the decimal representation of an angle or {lat lon}
value given in degree-minute-second representation. In the
result, southern latitudes and western longitudes will be nega‐
tive. The input angle or location must be in one of the follow‐
ing forms:
deg min sec NorS deg min sec WorE
deg min NorS deg min WorE
deg NorS deg WorE
deg min sec
deg min
geomap::dectodm degOR{lat lon}
Returns a list of form {degrees minutes} corresponding to deg,
which must be an angle given as a decimal value, or it returns a
list of form {deg min NorS deg min WorE} corresponding to {lati‐
tude longitude}, which must be a geographic location given as a
pair of decimal values.
geomap::dectodms degOR{lat lon}
Returns a list of form {degrees minutes} corresponding to deg,
which must be an angle given as a decimal value, or it returns a
list of form {deg min NorS deg min WorE} corresponding to {lati‐
tude longitude}, which must be a geographic location given as a
pair of decimal values.
geomap::cartg {1:XXXXXXX}ORdoubleValue
Returns the floating point representation of a map scale given
in cartographic notation 1:XXXXXXX, where XXXXXXXX is number, or
it returns the cartographic representation of a map scale given
as a floating point value doubleValue.
geomap::centroid point_list
Returns the mean position of the points in point_list, which
should be a list of form {{lat1 lon1} {lat2 lon2} ...}.
TIME
The geomap::time command does some simple time calculations. Its
behavior is determined by its first argument. The following forms are
permitted:
geomap::time jul_to_cal {julian_day second}
Returns a list of form {year month day hour minute second} cor‐
responding to Julian day julian_day at time second seconds after
midnight.
geomap::time cal_to_jul {year month day hour minute second}
Returns a list of form {julian_day seconds} giving the Julian
day and time corresponding to {year month day hour minute sec‐
ond}.
geomap::time incr {year month day hour minute second} seconds
Adds seconds seconds to {year month day hour minute second}.
The result is a list of form {year month day hour minute sec‐
ond}.
geomap::time cmp time1 time2
Compares two times, given as lists of form {year month day hour
minute second}. Result is -1 if time1 is earlier than time2.
Result is 0 if time1 is the same time as time2. Result is 1 if
time1 is later than time2.
geomap::time diff time1 time2
Returns time1 minus time2 in seconds.
PROJECTIONS
The geomap::projection command creates a Tcl command that converts
{latitude longitude} values to projection coordinates and back. In
this context, projection coordinates specify locations on a two dimen‐
sional plane or surface near the spherical Earth onto which points on
the Earth's surface are projected. A projection is characterized by a
type, given as projType, such as Mercator or Orthographic, and addi‐
tional options which depend on the projection type.
Projection commands assume a spherical Earth. Most of the formulas are
from Snyder, John P., Map Projections used by the U.S. Geological Sur‐
vey. (Geological Survey bulletin ; 1532) United States Government
Printing Office, Washington: 1982.
The geomap::projection returns the name of the new Tcl command that
accesses the projection. The command name will have form
::geomap::projx, where x is an integer. The following projType values
and options are recognized:
geomap::projection CylEqDist refLat refLon
Creates a command that makes conversions with Cylindrical
Equidistant projection with reference latitude refLat and refer‐
ence longitude refLon (i.e. longitudes will range from refLon -
180 torefLon + 180)
geomap::projection Mercator refLon
Creates a command that makes conversions with Mercator projec‐
tion referenced to refLon (i.e. longitudes range from refLon -
180 torefLon + 180)
geomap::projection CylEqArea refLon
Creates a command that makes conversions with Cylindrical Equal
Area projection referenced to refLon (i.e. longitudes range from
refLon - 180 torefLon + 180)
geomap::projection LambertConfConic refLat refLon
Creates a command that makes conversions with Lambert Conformal
Conic projection with reference latitude refLat and reference
longitude refLon. If refLat is 90 degrees, creates North Polar
Stereographic. If refLat is -90 degrees, creates South Polar
Stereographic. If refLat is 0, creates Mercator referenced to
refLon.
geomap::projection LambertEqArea refPt
Creates a command that makes conversions with Lambert Azimuthal
Equal Area projection referenced to refPt.
geomap::projection Stereographic refPt
Creates a command that makes conversions with Stereographic pro‐
jection referenced to refPt.
geomap::projection PolarStereographic N|S
Creates a command that makes conversions with Stereographic pro‐
jection referenced to North or South Pole (for argument N or S,
respectively)
geomap::projection Orthographic refPt
Creates a command that makes conversions with Orthographic pro‐
jection referenced to refPt.
PROJECTION COMMANDS
Commands created with geomap::projection ... accept the following sub‐
commands. Here, projId is the command name returned by the
geomap::projection command.
projId set projType ?arg ...?
Changes the projType and parameters for the projection. Types
and arguments are same as for geomap::projection command.
projId rotation ?angle?
Without argument, returns the current rotation angle for the
projection If present, angle specifies the projection orienta‐
tion. 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. projId info
Returns a string description of the projection. The first word
is always a projType, that can be used as the first argument to
projId set or geomap::projection, followed by the projection's
parameters, if any.
projId fmlatlon {lat lon}
Returns {abscissa ordinate} on the projection surface corre‐
sponding to {lat lon} for the projection.
projId tolatlon {abscissa ordinate}
Returns the {lat lon} corresponding to projection coordinates
{abscissa ordinate}.
LINEARRAYS
The geomap::lnarr command creates and manages linearrays. In this con‐
text, a {lat lon} pair is a geopoint. A set of geopoints make a geo‐
line. A set of geolines make a linearray. They are most often used
for drawing outlines or for drawing large sets of anonymous points.
The behavior of the geomap::lnarr command is determined by its first
argument. The following forms are permitted:
geomap::lnarr fmlist lnArrName listValue
Creates a linearray from a list.
The listValue can be a list of geopoints, in which case the lin‐
earray has one geoline. For example,
{{lat1 lon1} {lat2 lon2} {lat3 lon3} {lat4 lon4}}
would be interpreted as a linearray with one geoline of four
points.
More generally, listValue can contain several lists, each of
which contains the points in a geoline. For example
{{{lat11 lon11} {lat12 lon12} {lat13 lon13} {lat14 lon14}}
{{lat21 lon21} {lat22 lon22} {lat23 lon23}}}
has two geolines, the first with four geopoints, the second with
three.
If successful, geomap::lnarr fmlist will create a new Tcl com‐
mand named lnArrName whose behavior is described in the ARRAY
COMMAND section below. It is important to note that this com‐
mand will silently delete any previous command named lnArrName.
lnArrName can have namespace qualifiers to put it in a names‐
pace.
The array can be deleted by deleting the lnArrName Tcl command,
usually by changing its name to {} with rename, or by deleting
the namespace that contains the command.
geomap::lnarr fmascii lnArrName fileName ?-descrlen len? ?-format fmt?
Loads a linearray named from an ascii file or process named
fileName.
If the first character of fileName is not | then the command
opens a file. If the first character of fileName is | then the
remaining characters of fileName are treated as a list of argu‐
ments that describe a command pipeline to invoke, in the same
style as the arguments for exec.
If present, the descrlen option indicates an amount of data at
the start of the file to put into the new array's descriptor.
If len is a number, or number with a b appended to it (e.g. 10
or 10b) then that number of bytes from the start of the file is
given to the array descriptor. If len is a number with an l
appended to it (e.g. 10l) then that number of lines from the
start of the file is given to the array descriptor. The command
assumes {lat lon} values are in the file immediately after the
descriptor. If there is no descrlen option, geomap::lnarr
fmascii starts reading line data immediately and the array's
descriptor is an empty string. An array descriptor can be
retrieved with the 'lnArrName descr' command.
The line data must take the following form: for each line, an
integer giving the number of points in the line, and then the
points as {lat lon} pairs. The {lat lon} pairs are read using a
"%f %f" format specifier unless the format option is present,
which must give a format specifier that directs fscanf to read
two float values.
Reading continues until geomap::lnarr finishes reading a line
and does not find an integer giving the number of points in
another line. Behavior is undefined, and probably bad, if there
is a mismatch between the integer count and actual number of
points in a line.
If successful, geomap::lnarr fmascii will create a new Tcl com‐
mand named lnArrName whose behavior is described in the LINEAR‐
RAY COMMAND section below. It is important to note that this
command will silently delete any previous command named lnAr‐
rName. lnArrName can have namespace qualifiers to put it in a
namespace.
The array can be deleted by deleting the lnArrName Tcl command,
usually by changing its name to {} with rename, or by deleting
the namespace that contains the command.
geomap::lnarr fmxdr lnArrName fileName
Loads a linearray named lnArrName from an xdr (external data
representation) file or process named fileName. Xdr is a plat‐
form transparent format for storing strings, integers, and
floats. See the librpc man page (probably named xdr, rpc, or
librpc, or enter man -k xdr) or visit
http://www.acc.umu.se/~balp/rpcunix/,
http://www.ietf.org/rfc/rfc1832.txt or similar for more informa‐
tion. If the first character of fileName is not | then the com‐
mand opens a file. If the first character of fileName is | then
the remaining characters of fileName are treated as a list of
arguments that describe a command pipeline to invoke, in the
same style as the arguments for exec.
The xdr file or process must have the following sequence of xdr
records:
xdr_string: file descriptor, which becomes the array descriptor,
accessible with the 'lnArrName descr' command,
xdr_integer: number of points in the first geoline,
xdr_float xdr_float xdr_float xdr_float ... : latitude longitude
values for each point in the first geoline,
xdr_integer: number of points in the second geoline,
xdr_float xdr_float xdr_float xdr_float ... : latitude longitude
values for each point in the second geoline,
and so on...
Thus, there is an xdr_integer record followed by twice that num‐
ber of xdr_float records for each geoline in the linearray.
All latitude and longitude values in the xdr stream are separate
xdr float records. None of the values are stored in xdr arrays.
If successful, geomap::lnarr fmxdr will create a new Tcl command
named lnArrName, whose behavior is described in the ARRAY COM‐
MAND section below. It is important to note that this command
will silently delete any previous command named lnArrName.
lnArrName can have namespace qualifiers to put it in a names‐
pace.
The array can be deleted by deleting the lnArrName Tcl command,
usually by changing its name to {} with rename, or by deleting
the namespace that contains the command.
geomap::lnarr fmbin lnArrName fileName
Loads a linearray named lnArrName from a native binary file or
process named fileName. The stream should consist of an integer
descriptor length, a descriptor, and then for each line an inte‐
ger giving the number of points in the line followed by the lat‐
itude-longitude values for the points as float values.
If successful, geomap::lnarr fmbin will create a new Tcl command
named lnArrName, whose behavior is described in the ARRAY COM‐
MAND section below. It is important to note that this command
will silently delete any previous command named lnArrName.
lnArrName can have namespace qualifiers to put it in a names‐
pace.
The array can be deleted by deleting the lnArrName Tcl command,
usually by changing its name to {} with rename, or by deleting
the namespace that contains the command.
LINEARRAY COMMAND
Subcommands that add a linearray to the database also create a Tcl com‐
mand named lnArrName to access and manipulate the array. Its behavior
is determined by the first argument. The following forms are permit‐
ted:
lnArrName tolist
Returns the linearray named lnArrName as a list in the same for‐
mat as read by the fmlist command.
lnArrName toascii fileName ?-ptperln n? ?-format format?
Write a linearray to file fileName as printable text. The file
will contain the array's descriptor, followed by the lines.
Each line will consist of an integer giving the number of points
in the line printed with "%d " format followed by the points as
{lat lon} pairs. If present, the ptperln option gives the maxi‐
mum number of {lat lon} pairs in each line of output, before a
newline is inserted. The {lat lon} pairs will be printed with
"%f %f " format, unless a different format is specified by the
format option, which must be a format specifier that directs the
C standard library function fprintf to print two float values.
lnArrName toxdr fileName
Sends a linearray to a file named fileName in the same format
expected by the fmxdr subcommand.
lnArrName tobin fileName
Sends the linearray named lnArrName to a file named fileName in
a a native binary format that can be read by the fmbin subcom‐
mand.
lnArrName info
Returns a list containing {{descriptor} {maxLat maxLon minLat
minLon} {number of lines} {total number of points} {number of
points in longest line}} for the linearray. If a max or min is
undefined, it is given as undef.
lnArrName descr ?newDescriptor?
Without newDescriptor argument, returns the descriptor for the
linearray named lnArrName. With newDescriptor, sets the
descriptor for array to newDescriptor, and returns the new
descriptor.
lnArrName containpt geopoint
Assume each of the geolines in the linearray named lnArrName is
a simple polygon. This procedure returns true (1) if geopoint
is contained in any of these polygons, otherwise returns false
(0). Behavior is undefined if any of the lines cross them‐
selves.
PLACES
The geomap::place command creates and manipulates places. In this con‐
text a place is a point on the Earth's surface with a specific {lat
lon} and a name. Places can be cities, observation stations, and other
points of interest.
The behavior of the geomap::place command is determined by its first
argument. The following forms are permitted:
geomap::place new placeName {lat lon}
This command adds a new place named placeName to the place data‐
base at {lat lon}. Return value is placeName. It returns an
error message if a there is already a command named placeName.
If successful, geomap::place new will create a new Tcl command
placeName whose behavior is described in the PLACE COMMAND sec‐
tion. It is important to note that this command will silently
delete any previous command named placeName. placeName can have
namespace qualifiers to put it in a namespace. The place can be
deleted by removing its command.
geomap::place set placeName ?{lat lon}?
If called without a {lat lon} argument, this command returns the
{lat lon} of the place named placeName. If no such place
exists, this command returns an error message. With a {lat lon}
argument, geomap::place sets coordinates of a place named place‐
Name. If no place named placeName exists, a place with that
name and a corresponding command is created, in the same manner
as geomap::place new. Any previous command named placeName is
deleted.
geomap::place distance placeNameOR{lat lon} placeNameOR{lat lon} ?unit?
Returns the distance between two places or {lat lon} pairs,
assuming a spherical Earth with radius set by the georadius com‐
mand. Default distance unit is great circle degrees, unless
unit is specified, which can be nmiles (international standard
nautical mile = 1852.0 m), smiles (statute mile = 1609.344 m),
km (kilometer), or gsdeg (great circle degrees).
geomap::place azrng placeNameOR{lat lon} placeNameOR{lat lon} ?unit?
Returns {azimuth range} from the first place to the second,
assuming a spherical Earth with radius set by the georadius com‐
mand. Range is given in great circle degrees, unless unit is
specified, which can be nmiles (nautical miles), smiles (statute
miles), km (kilometers), or gsdeg (great circle degrees).
geomap::place nearest placeNameOR{lat lon} placeList
Returns the name of the place in placeList nearest the given
placeName or {lat lon}, assuming a spherical Earth with radius
set by the geomap::georadius command. Names in placeList must
refer to commands created by geomap::place new or geomap::place
set. If the place commands are in namespaces, they MUST BE
FULLY QUALIFIED.
geomap::place step placeNameOR{lat lon} bearing range ?unit?
Returns {lat lon} of point at given bearing and range from the
place named placeName or the point at coordinates {lat lon}.
Bearing can be a number of degrees clockwise from North or one
of north nneast neast eneast east eseast seast sseast south
sswest swest wswest west wnwest nwest or nnwest. Default dis‐
tance unit is great circle degrees, unless unit is specified,
which can be nmiles (nautical miles), smiles (statute miles), km
(kilometers), or gsdeg (great circle degrees).
geomap::place inrange placeNameOR{lat lon} {range ?unit?} placeList
Returns a list of places in placeList within range of place
named placeName or the point at coordinates {lat lon}. Default
unit for range is great circle degrees, unless range is given
with unit, which can be nmiles (nautical miles), smiles (statute
miles), km (kilometers), or gsdeg (great circle degrees). Names
in placeList must refer to commands created by geomap::place new
or geomap::place set. If the place commands are in namespaces,
they MUST BE FULLY QUALIFIED.
PLACE COMMAND
Subcommands that add a place to the database also create a Tcl command
named placeName to access and manipulate the place. Its behavior is
determined by the first argument. The following forms are permitted:
placeName set ?{lat lon}?
Without {lat lon}, returns the {lat lon} of the place named pla‐
ceName or an error message if the place does not exist. With
{lat lon}, sets coordinates of the place.
placeName nearest placeList
Returns the name of the place in placeList nearest the given
placeName, assuming a spherical Earth with radius set by the
geomap::georadius command. Names in placeList must refer to
commands created by geomap::place new or geomap::place set. If
the place commands are in namespaces, they MUST BE FULLY QUALI‐
FIED.
placeName step bearing range ?unit?
Returns {lat lon} of point at given bearing and range from the
place named placeName. bearing can be a number of degrees
clockwise from North or one of n nne ne ene e ese se sse s ssw
sw wsw w wnw nw or nnw. Default distance unit is great circle
degrees, unless unit is specified, which can be nmiles (nautical
miles), smiles (statute miles), km (kilometers), or gsdeg (great
circle degrees).
placeName inrange {range ?unit?} placeList
Returns a list of places in placeList within range of place
named placeName. Default unit for range is great circle
degrees, unless range is given with unit, which can be nmiles
(nautical miles), smiles (statute miles), km (kilometers), or
gsdeg (great circle degrees). Names in placeList must refer to
commands created by geomap::place new or geomap::place set. If
the place commands are in namespaces, they MUST BE FULLY QUALI‐
FIED.
VARIABLES
Variable ::geomap::tclgeomap_lib_file contains the full path name of
the file that provided the tclgeomap package.
FILES
These commands are added to Tcl by the tclgeomap package in file libt‐
clgeomap.so or libtclgeomap.a built by the tclgeomap distribution. It
is part of the tclgeomap and tkgeomap executables, or can be added to
the current interpreter with the load or package commands. Run package
names to determine if the tclgeomap package is present. See the tclge‐
omap distribution for installation information.
AUTHOR
Gordon Carrie <user0@tkgeomap.org>
Tcl 2 tclgeomap(n)
