tclgeomap package

The tclgeomap package adds commands that store and manipulate geographic data. None of the commands in the package require Tk or an X server. Thus they can be used in background scripts. Here is a brief description of each command. Detailed descriptions are in the tclgeomap man page.

geography commands

The following commands do basic geographical calculations and formatting.

geomap::georadius gets or sets the radius of the Earth.
geomap::latlonok determines if a value is a geographic point, i.e. is of form {latitude longitude}.
geomap::mapptok determines if a value is a point on a two dimensional map, i.e. is of form {abscissa ordinate}.
geomap::lonbtwn determines if a longitude is between two others.
geomap::gclcross finds the intersection of two great circles.
geomap::rotatpt rotates a map point about the map origin.
geomap::scalept scales a map point.
geomap::domnlat puts a latitude into the interval [-90, 90].
geomap::domnlon puts a longitude within 180 degress of a reference longitude.
geomap::domnlonpt applies domnlon to a point.
geomap::gwchlon puts a longitude into the interval [-180, 180].
geomap::gwchpt applies gwchlon to a point.
geomap::dmstodec converts the degree minute second representation of an angle or geographic point to decimal.
geomap::dectodm converts a decimal representation of an angle or point to degrees and minutes.
geomap::dectodms converts a decimal representation of an angle or point to degrees, minutes, and seconds.
geomap::cartg converts a cartographic scale (e.g. 1:90000000) to floating point and back.

Here are some usage examples of the above commands, copied from an interactive tclsh session.

tclsh$ package require tclgeomap 2
2.0
tclsh$ geomap::georadius km
6366.70701949
tclsh$ geomap::latlonok [list 30.0 -97.0]
1
tclsh$ geomap::latlonok foo
0
tclsh$ geomap::lonbtwn 0 {-10 10}
1
tclsh$ geomap::lonbtwn 180 {-170 170}
1
tclsh$ geomap::lonbtwn -45 {270 360}
1
tclsh$ geomap::lonbtwn 45 {270 360}
0
tclsh$ geomap::gclcross {0 0} {0 10} {5 5} {-5 5}
0.0 5.0
tclsh$ geomap::gclcross {0 0} {10 0} {5 -5} {5 5}
5.019002 0.0
tclsh$ geomap::domnlat 80.0
80.0
tclsh$ geomap::domnlat 100.0
80.0
tclsh$ geomap::domnlon 170.0 0.0
170.0
tclsh$ geomap::domnlon 190.0 0.0
-170.0
tclsh$ geomap::domnlon -10.0 180.0
350.0
tclsh$ geomap::dmstodec {35 10 20}
35.1722222222
tclsh$ geomap::dmstodec {35 10 20 N 97 25 50 W}
35.172222 -97.430556
tclsh$ geomap::dmstodec {35 10.306 N 97 25.854 W}
35.171767 -97.4309
tclsh$ geomap::dectodm {35.171767 -97.4309}
35 10 N 97 26 W
tclsh$ geomap::dectodms {35.171767 -97.4309}
35 10 18 N 97 25 51 W
tclsh$ geomap::cartg 1:10000000
1e-07
tclsh$ geomap::cartg 1.0e-7
1:10000000

projections

Each call to geomap::projection creates a new Tcl command for converting between geographic geographic points and projection points. In this context, a geographic point is a {latitude longitude} value identifying a point on the Earth's surface. A projection point is an {abscissa ordinate} value denoting a point on a projection surface in space. The conversion performed by the new command is determined by arguments given to the projection command. The new command will have a name of form ::geomap::proj0, ::geomap::proj1, ::geomap::proj2, etc. It will have the following subcommands that access the projection and make conversions:

projId set modifies the projection.
projId info returns information about the projection.
projId fmlatlon computes the projection point corresponding to a given geographic point.
projId tolatlon computes the geographic point corresponding to a given projection point.

Here is a sample session showing some projections being created, used, and modified.

tclsh$ geomap::projection Mercator 0.0
proj0
tclsh$ proj0 info
Mercator 0.000    
tclsh$ proj0 fmlatlon {10.0 10.0}
1111200.0 1116884.875
tclsh$ proj0 tolatlon {1111200.0 1116884.875}
10.0 10.0
tclsh$ geomap::scalept [proj0 fmlatlon {10.0 10.0}] [geomap::cartg 1:10000000]
0.111120000482 0.111688487232
tclsh$ proj0 set LambertEqArea {0.0 0.0}
tclsh$ proj0 info
LambertEqArea {    0.000 0.000    }
tclsh$ proj0 fmlatlon {10.0 10.0}
1097072.625 1113996.75
tclsh$ proj0 tolatlon {1097072.625 1113996.75}
10.0 10.0
tclsh$ geomap::projection PolarStereographic N
proj1
tclsh$ proj0 info
LambertEqArea {    0.000 0.000    }
tclsh$ proj1 info
Stereographic {90.0 0.0}

linearrays

geomap::lnarr makes a linearray. In this context, a line is a list of {latitude longitude} values. A linearray is a list of lines. In other words it is a two dimensional array of lat-lon's. The first argument determines how the latitudes and longitudes for the linearray are obtained. The following forms are recognized:

geomap::lnarr fmlist creates a linearray from a list or a list of lists on the command line.
geomap::lnarr fmascii reads a linearray from a text file.
geomap::lnarr fmxdr reads a linearray from an xdr (External Data Representation) stream. Xdr is a protocol that formats data as necessary when transferring between files and processes on different systems. Consult the xdr and rpc man pages for more information. It is ubiquitous on Unix systems. If your system done not have it, you can add the necessary code from this tar ball.
geomap::lnarr fmbin reads a linearray from a binary file.

geomap::lnarr creates a new Tcl command, whose name is given by the user, that accesses the linearray. The new command will have the following subcommands:

lnArrName tolist converts the linearray to a Tcl list.
lnArrName toascii writes the linearray to a text file.
lnArrName toxdr writes the linearray to an xdr stream.
lnArrName tobin writes the linearray to a binary file.
lnArrName info gets information about the linearray, such as the number of lines, number of points, maxima, and minima.
lnArrName descr gets or sets a string descriptor.
lnArrName containpt determines whether a point is contained in any of the lines in the linearray, assuming they are closed polygons.

Here is a sample session showing some linearrays being created, used, and modified.

tclsh$ geomap::lnarr fmlist line0 {{0 0} {0 10} {10 10} {10 0} {0 0}}
line0
tclsh$ line0 info
{} {10.0 10.0 0.0 0.0} 1 5 5
tclsh$ line0 descr "Behold my box"
Behold my box
tclsh$ line0 info
{Behold my box} {10.0 10.0 0.0 0.0} 1 5 5
tclsh$ exec mkdir -p lines
tclsh$ cd lines
tclsh$ line0 toxdr line0.xdr
tclsh$ ls -l
total 1
-rw-r--r--    1 gordonc  other          64 Jul 23 11:34 line0.xdr
tclsh$ rename line0 {}
tclsh$ line0 info
invalid command name "line0"
while evaluating {line0 info}
tclsh$ geomap::lnarr fmxdr line1 line0.xdr
line1
tclsh$ line1 info
{Behold my box} {10.0 10.0 0.0 0.0} 1 5 5
tclsh$ line1 containpt {5.0 5.0}
1
tclsh$ line1 containpt {15.0 15.0}
0
tclsh$ geomap::lnarr fmlist lines::line1 {{0 0} {0 -10} {-10 -10} {-10 0} {0 0}}
lines::line1
tclsh$ lines::line1 descr {Another box, in a namespace}
Another box, in a namespace
tclsh$ line1 info
{Behold my box} {10.0 10.0 0.0 0.0} 1 5 5
tclsh$ lines::line1 info
{Another box, in a namespace} {0.0 0.0 -10.0 -10.0} 1 5 5
tclsh$ geomap::lnarr fmlist lines1 [list [line1 tolist] [lines::line1 tolist]]
lines1
tclsh$ lines1 descr {This linearray has two lines}
This linearray has two lines
tclsh$ lines1 info
{This linearray has two lines} {10.0 10.0 -10.0 -10.0} 2 10 5
tclsh$ lines1 tolist
{{0.0 0.0} {0.0 10.0} {10.0 10.0} {10.0 0.0} {0.0 0.0}}
        {{0.0 0.0} {0.0 -10.0} {-10.0 -10.0} {-10.0 0.0} {0.0 0.0}}
tclsh$ lines1 containpt {5 -5}
0
tclsh$ lines1 containpt {5 5}
1
tclsh$ lines1 containpt {-5 5}
0
tclsh$ lines1 containpt {-5 -5}
1

places

geomap::place works with places. In this context, a place is a {latitude longitude} value with a name. Some of the geomap::place subcommands also accept un-named points. The following subcommands are recognized:

geomap::place new creates a new named place.
geomap::place set creates, relocates, or retrieves the location of a named place.
geomap::place distance computes the distance between two places or points.
geomap::place azrng computes the azimuth and range from one place or point to another place or point.
geomap::place nearest finds the place in a given list nearest a given place or point.
geomap::place step computes the point a given distance and direction from a place or point.
geomap::place inrange gets the places from a list that are within a given range from a place or point.

geomap::place new and sometimes geomap::place set create a new Tcl command, whose name is given by the user, that accesses the place. The new command will have the following subcommands:

placeName set gets or sets the {latitude longitude} for the place.
placeName nearest finds the place in a given list nearest the place.
placeName step computes the point a given distance and direction from the place.
placeName inrange gets the places from a list that are within a given range from the place.

Here is a sample session showing the place commands in action.

tclsh$ geomap::place distance {0 0} {10 0}
10.0
tclsh$ geomap::place distance {0 0} {10 0} km
1111.2
tclsh$ geomap::place distance {0 0} {10 0} nmi
600.0
tclsh$ geomap::place distance {0 0} {1 1}
1.414178
tclsh$ geomap::place azrng {0 0} {1 1}
44.995636 1.414178
tclsh$ geomap::place step {0 0} 44.995636 1.414178
1.0 1.0
tclsh$ geomap::place new place1 {0 0}
place1
tclsh$ place1 set
0.0 0.0
tclsh$ place1 step 44.995636 1.414178
1.0 1.0
tclsh$ place1 set {30 -97}
30 -97
tclsh$ geomap::place new place2 {30 -90}
place2
tclsh$ geomap::place azrng place1 place2
88.248366 6.061234
tclsh$ geomap::place new place3 {30 -80}
place3
tclsh$ geomap::place new place4 {30 -70}
place4
tclsh$ place1 inrange 7.0 {place2 place3 place4}
place2
tclsh$ place1 inrange {800 km} {place2 place3 place4}
place2
tclsh$ place1 inrange {4800 km} {place2 place3 place4}
place2 place3 place4

Return to tkgeomap home