GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TCLGEOMAP (n)

NAME

tclgeomap, georadius, latlonok, mapptok, lonbtwn, gclcross, rotatpt, scalept, domnlat, domnlon, domnlonpt, gwchlon, gwchpt, dmstodec, dectodm, dectodms, cartg, centroid, projection, lnarr, place - commands for manipulating geographic data in Tcl.

CONTENTS

Version
Synopsis
Introduction
General Geography Commands
Time
Projections
Projection Commands
Linearrays
Linearray Command
Places
Place Command
Variables
Files
Author

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 distances 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 (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

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

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 dimensional 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 additional 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 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

Commands created with geomap::projection ... accept the following subcommands. 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 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 geomap::lnarr command creates and manages linearrays. In this context, a {lat lon} pair is a geopoint. A set of geopoints make a geoline. 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 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

Subcommands that add a linearray to the database also create a Tcl command named lnArrName to access and manipulate the array. Its behavior is determined by the first argument. The following forms are permitted:
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 geomap::place command creates and manipulates places. In this context 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 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

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

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 libtclgeomap.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 tclgeomap distribution for installation information.

AUTHOR

Gordon Carrie <user0@tkgeomap.org>
Search for    or go to Top of page |  Section n |  Main Index


Tcl TCLGEOMAP (n) 2

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.