NAME

VERSION

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

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 (centimeters).

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

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 intersection 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 negative. The input angle or location must be in one of the following 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 {latitude 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 {latitude 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

geomap::time jul_to_cal {julian_day second}

Returns a list of form {year month day hour minute second} corresponding 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 second}.

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

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

Projection commands assume a spherical Earth. Most of the formulas are from Snyder, John P., Map Projections used by the U.S. Geological Survey. (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 reference longitude refLon (i.e. longitudes will range from refLon - 180 torefLon + 180)

geomap::projection Mercator refLon

Creates a command that makes conversions with Mercator projection 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 projection referenced to refPt.

geomap::projection PolarStereographic N|S

Creates a command that makes conversions with Stereographic projection referenced to North or South Pole (for argument N or S, respectively)

geomap::projection Orthographic refPt

Creates a command that makes conversions with Orthographic projection referenced to refPt.

PROJECTION COMMANDS

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 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. 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 corresponding to {lat lon} for the projection.

projId tolatlon {abscissa ordinate}

Returns the {lat lon} corresponding to projection coordinates {abscissa ordinate}.

LINEARRAYS

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 linearray 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 command named lnArrName whose behavior is described in the ARRAY COMMAND 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 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 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 arguments 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 command named lnArrName whose behavior is described in the LINEARRAY COMMAND 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 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 platform 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 information. 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 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 number 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 COMMAND 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 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 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 integer giving the number of points in the line followed by the latitude-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 COMMAND 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 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.

LINEARRAY COMMAND

lnArrName tolist

Returns the linearray named lnArrName as a list in the same format 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 maximum 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 subcommand.

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

PLACES

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 database 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 section. 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 placeName. 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 command. 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 command. 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 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).

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

placeName set ?{lat lon}?

Without {lat lon}, returns the {lat lon} of the place named placeName 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 QUALIFIED.

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

VARIABLES

FILES

AUTHOR