


mapproj(n)                 Tcl Library                 mapproj(n)


______________________________________________________________________________

NAME
       mapproj - Map projection routines

SYNOPSIS
       package require Tcl  ?8.4?

       package require math::interpolate  ?1.0?

       package require math::special  ?0.2.1?

       package require mapproj  ?1.0?

       ::mapproj::toPlateCarree lambda_0 phi_0 lambda phi

       ::mapproj::fromPlateCarree lambda_0 phi_0 x y

       ::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi

       ::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y

       ::mapproj::toMercator lambda_0 phi_0 lambda phi

       ::mapproj::fromMercator lambda_0 phi_0 x y

       ::mapproj::toMillerCylindrical lambda_0 lambda phi

       ::mapproj::fromMillerCylindrical lambda_0 x y

       ::mapproj::toSinusoidal lambda_0 phi_0 lambda phi

       ::mapproj::fromSinusoidal lambda_0 phi_0 x y

       ::mapproj::toMollweide lambda_0 lambda phi

       ::mapproj::fromMollweide lambda_0 x y

       ::mapproj::toEckertIV lambda_0 lambda phi

       ::mapproj::fromEckertIV lambda_0 x y

       ::mapproj::toEckertVI lambda_0 lambda phi

       ::mapproj::fromEckertVI lambda_0 x y

       ::mapproj::toRobinson lambda_0 lambda phi

       ::mapproj::fromRobinson lambda_0 x y

       ::mapproj::toCassini lambda_0 phi_0 lambda phi

       ::mapproj::fromCassini lambda_0 phi_0 x y




mapproj                        0.1                              1





mapproj(n)                 Tcl Library                 mapproj(n)


       ::mapproj::toPeirceQuincuncial lambda_0 lambda phi

       ::mapproj::fromPeirceQuincuncial lambda_0 x y

       ::mapproj::toOrthographic lambda_0 phi_0 lambda phi

       ::mapproj::fromOrthographic lambda_0 phi_0 x y

       ::mapproj::toStereographic lambda_0 phi_0 lambda phi

       ::mapproj::fromStereographic lambda_0 phi_0 x y

       ::mapproj::toGnomonic lambda_0 phi_0 lambda phi

       ::mapproj::fromGnomonic lambda_0 phi_0 x y

       ::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi

       ::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y

       ::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi

       ::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y

       ::mapproj::toHammer lambda_0 lambda phi

       ::mapproj::fromHammer lambda_0 x y

       ::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi

       ::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y

       ::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi

       ::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y

       ::mapproj::toLambertConformalConic lambda_0 phi_0  phi_1  phi_2  lambda
       phi

       ::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y

       ::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi

       ::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y

       ::mapproj::toBehrmann lambda_0 phi_0 lambda phi

       ::mapproj::fromBehrmann lambda_0 phi_0 x y

       ::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi

       ::mapproj::fromTrystanEdwards lambda_0 phi_0 x y

       ::mapproj::toHoboDyer lambda_0 phi_0 lambda phi



mapproj                        0.1                              2





mapproj(n)                 Tcl Library                 mapproj(n)


       ::mapproj::fromHoboDyer lambda_0 phi_0 x y

       ::mapproj::toGallPeters lambda_0 phi_0 lambda phi

       ::mapproj::fromGallPeters lambda_0 phi_0 x y

       ::mapproj::toBalthasart lambda_0 phi_0 lambda phi

       ::mapproj::fromBalthasart lambda_0 phi_0 x y

_________________________________________________________________

DESCRIPTION
       The mapproj package provides a set of procedures for converting between
       world co-ordinates (latitude and longitude) and map co-ordinates  on  a
       number of different map projections.

COMMANDS
       The  following  commands convert between world co-ordinates and map co-
       ordinates:

       ::mapproj::toPlateCarree lambda_0 phi_0 lambda phi
              Converts to the plate carree (cylindrical  equidistant)  projec-
              tion.

       ::mapproj::fromPlateCarree lambda_0 phi_0 x y
              Converts from the plate carree (cylindrical equidistant) projec-
              tion.

       ::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi
              Converts to the cylindrical equal-area projection.

       ::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y
              Converts from the cylindrical equal-area projection.

       ::mapproj::toMercator lambda_0 phi_0 lambda phi
              Converts to the Mercator (cylindrical conformal) projection.

       ::mapproj::fromMercator lambda_0 phi_0 x y
              Converts from the Mercator (cylindrical conformal) projection.

       ::mapproj::toMillerCylindrical lambda_0 lambda phi
              Converts to the Miller Cylindrical projection.

       ::mapproj::fromMillerCylindrical lambda_0 x y
              Converts from the Miller Cylindrical projection.

       ::mapproj::toSinusoidal lambda_0 phi_0 lambda phi
              Converts to the sinusoidal (Sanson-Flamsteed) projection.   pro-
              jection.

       ::mapproj::fromSinusoidal lambda_0 phi_0 x y
              Converts  from  the  sinusoidal  (Sanson-Flamsteed)  projection.
              projection.



mapproj                        0.1                              3





mapproj(n)                 Tcl Library                 mapproj(n)


       ::mapproj::toMollweide lambda_0 lambda phi
              Converts to the Mollweide projection.

       ::mapproj::fromMollweide lambda_0 x y
              Converts from the Mollweide projection.

       ::mapproj::toEckertIV lambda_0 lambda phi
              Converts to the Eckert IV projection.

       ::mapproj::fromEckertIV lambda_0 x y
              Converts from the Eckert IV projection.

       ::mapproj::toEckertVI lambda_0 lambda phi
              Converts to the Eckert VI projection.

       ::mapproj::fromEckertVI lambda_0 x y
              Converts from the Eckert VI projection.

       ::mapproj::toRobinson lambda_0 lambda phi
              Converts to the Robinson projection.

       ::mapproj::fromRobinson lambda_0 x y
              Converts from the Robinson projection.

       ::mapproj::toCassini lambda_0 phi_0 lambda phi
              Converts to the  Cassini  (transverse  cylindrical  equidistant)
              projection.

       ::mapproj::fromCassini lambda_0 phi_0 x y
              Converts  from  the Cassini (transverse cylindrical equidistant)
              projection.

       ::mapproj::toPeirceQuincuncial lambda_0 lambda phi
              Converts to the Peirce Quincuncial Projection.

       ::mapproj::fromPeirceQuincuncial lambda_0 x y
              Converts from the Peirce Quincuncial Projection.

       ::mapproj::toOrthographic lambda_0 phi_0 lambda phi
              Converts to the orthographic projection.

       ::mapproj::fromOrthographic lambda_0 phi_0 x y
              Converts from the orthographic projection.

       ::mapproj::toStereographic lambda_0 phi_0 lambda phi
              Converts to the stereographic (azimuthal conformal)  projection.

       ::mapproj::fromStereographic lambda_0 phi_0 x y
              Converts  from  the  stereographic (azimuthal conformal) projec-
              tion.

       ::mapproj::toGnomonic lambda_0 phi_0 lambda phi
              Converts to the gnomonic projection.




mapproj                        0.1                              4





mapproj(n)                 Tcl Library                 mapproj(n)


       ::mapproj::fromGnomonic lambda_0 phi_0 x y
              Converts from the gnomonic projection.

       ::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi
              Converts to the azimuthal equidistant projection.

       ::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y
              Converts from the azimuthal equidistant projection.

       ::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi
              Converts to the Lambert azimuthal equal-area projection.

       ::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y
              Converts from the Lambert azimuthal equal-area projection.

       ::mapproj::toHammer lambda_0 lambda phi
              Converts to the Hammer projection.

       ::mapproj::fromHammer lambda_0 x y
              Converts from the Hammer projection.

       ::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi
              Converts to the conic equidistant projection.

       ::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y
              Converts from the conic equidistant projection.

       ::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi
              Converts to the Albers equal-area conic projection.

       ::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y
              Converts from the Albers equal-area conic projection.

       ::mapproj::toLambertConformalConic lambda_0 phi_0 phi_1 phi_2 lambda
       phi
              Converts to the Lambert conformal conic projection.

       ::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y
              Converts from the Lambert conformal conic projection.

       Among the cylindrical equal-area projections, there  are  a  number  of
       choices of standard parallels that have names:

       ::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi
              Converts  to  the  Lambert  cylindrical  equal  area projection.
              (standard parallel is the Equator.)

       ::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y
              Converts from the Lambert  cylindrical  equal  area  projection.
              (standard parallel is the Equator.)

       ::mapproj::toBehrmann lambda_0 phi_0 lambda phi
              Converts  to  the  Behrmann  cylindrical  equal area projection.
              (standard parallels are 30 degrees North and South)



mapproj                        0.1                              5





mapproj(n)                 Tcl Library                 mapproj(n)


       ::mapproj::fromBehrmann lambda_0 phi_0 x y
              Converts from the Behrmann cylindrical  equal  area  projection.
              (standard parallels are 30 degrees North and South.)

       ::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi
              Converts  to  the Trystan Edwards cylindrical equal area projec-
              tion. (standard parallels are 37.4 degrees North and South)

       ::mapproj::fromTrystanEdwards lambda_0 phi_0 x y
              Converts from the Trystan Edwards cylindrical equal area projec-
              tion. (standard parallels are 37.4 degrees North and South.)

       ::mapproj::toHoboDyer lambda_0 phi_0 lambda phi
              Converts  to  the  Hobo-Dyer  cylindrical equal area projection.
              (standard parallels are 37.5 degrees North and South)

       ::mapproj::fromHoboDyer lambda_0 phi_0 x y
              Converts from the Hobo-Dyer cylindrical equal  area  projection.
              (standard parallels are 37.5 degrees North and South.)

       ::mapproj::toGallPeters lambda_0 phi_0 lambda phi
              Converts  to  the Gall-Peters cylindrical equal area projection.
              (standard parallels are 45 degrees North and South)

       ::mapproj::fromGallPeters lambda_0 phi_0 x y
              Converts from the Gall-Peters cylindrical equal area projection.
              (standard parallels are 45 degrees North and South.)

       ::mapproj::toBalthasart lambda_0 phi_0 lambda phi
              Converts  to  the  Balthasart cylindrical equal area projection.
              (standard parallels are 50 degrees North and South)

       ::mapproj::fromBalthasart lambda_0 phi_0 x y
              Converts from the Balthasart cylindrical equal area  projection.
              (standard parallels are 50 degrees North and South.)


ARGUMENTS
       The following arguments are accepted by the projection commands:

       lambda Longitude of the point to be projected, in degrees.

       phi    Latitude of the point to be projected, in degrees.

       lambda_0
              Longitude of the center of the sheet, in degrees.  For many pro-
              jections, this figure is also the reference meridian of the pro-
              jection.

       phi_0  Latitude  of  the  center  of  the  sheet,  in degrees.  For the
              azimuthal projections, this figure is also the latitude  of  the
              center of the projection.

       phi_1  Latitude  of  the first reference parallel, for projections that



mapproj                        0.1                              6





mapproj(n)                 Tcl Library                 mapproj(n)


              use reference parallels.

       phi_2  Latitude of the second reference parallel, for projections  that
              use reference parallels.

       x      X co-ordinate of a point on the map, in units of Earth radii.

       y      Y co-ordinate of a point on the map, in units of Earth radii.


RESULTS
       For all of the procedures whose names begin with 'to', the return value
       is a list comprising an x co-ordinate and a  y  co-ordinate.   The  co-
       ordinates are relative to the center of the map sheet to be drawn, mea-
       sured in Earth radii at the reference location on the map.  For all  of
       the functions whose names begin with 'from', the return value is a list
       comprising the longitude and latitude, in degrees.

CHOOSING A PROJECTION
       This package offers a great many projections, because no single projec-
       tion  is  appropriate  to  all  maps.  This section attempts to provide
       guidance on how to choose a projection.

       First, consider the type of data that you intend to display on the map.
       If  the  data are directional (e.g., winds, ocean currents, or magnetic
       fields) then you need to use a projection that preserves angles;  these
       are  known as conformal projections.  Conformal projections include the
       Mercator, the Albers azimuthal equal-area, the stereographic,  and  the
       Peirce  Quincuncial  projection.   If the data are thematic, describing
       properties of land or water, such as temperature,  population  density,
       land  use,  or  demographics; then you need a projection that will show
       these data with the areas on the map proportional to the areas in  real
       life.   These  so-called  equal  area  projections  include the various
       cylindrical equal area projections, the sinusoidal projection, the Lam-
       bert  azimuthal equal-area projection, the Albers equal-area conic pro-
       jection, and several of the world-map projections (Miller  Cylindrical,
       Mollweide, Eckert IV, Eckert VI, Robinson, and Hammer). If the signifi-
       cant factor in your data is distance from a central point or line (such
       as  air  routes),  then you will do best with an equidistant projection
       such as plate carree, Cassini, azimuthal equidistant, or conic equidis-
       tant.   If  direction from a central point is a critical factor in your
       data (for instance, air routes, radio antenna pointing), then you  will
       almost surely want to use one of the azimuthal projections. Appropriate
       choices are azimuthal equidistant, azimuthal equal-area, stereographic,
       and perhaps orthographic.

       Next,  consider how much of the Earth your map will cover, and the gen-
       eral shape of the area of interest.  For maps of the entire Earth,  the
       cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Ham-
       mer projections are good overall choices.  The Mercator  projection  is
       traditional, but the extreme distortions of area at high latitudes make
       it a poor choice unless a conformal projection is required. The  Peirce
       projection is a better choice of conformal projection, having less dis-
       tortion of landforms.  The Miller Cylindrical is a compromise  designed



mapproj                        0.1                              7





mapproj(n)                 Tcl Library                 mapproj(n)


       to give shapes similar to the traditional Mercator, but with less polar
       stretching.  The Peirce Quincuncial projection shows all the continents
       with acceptable distortion if a reference meridian close to +20 degrees
       is chosen.  The Robinson projection yields attractive maps  for  things
       like  political  divisions,  but should be avoided in presenting scien-
       tific data, since other projections have moe useful  geometric  proper-
       ties.

       If  the  map  will  cover  a  hemisphere,  then  choose  stereographic,
       azimuthal-equidistant, Hammer, or Mollweide projections; these all pro-
       ject the hemisphere into a circle.

       If  the  map  will  cover  a large area (at least a few hundred km on a
       side), but less than a  hemisphere,  then  you  have  several  choices.
       Azimuthal projections are usually good (choose stereographic, azimuthal
       equidistant, or  Lambert  azimuthal  equal-area  according  to  whether
       shapes,  distances  from  a  central  point,  or  areas are important).
       Azimuthal projections (and possibly the  Cassini  projection)  are  the
       only really good choices for mapping the polar regions.

       If  the large area is in one of the temperate zones and is round or has
       a primarily east-west extent,  then  the  conic  projections  are  good
       choices.  Choose the Lambert conformal conic, the conic equidistant, or
       the Albers equal-area conic according to whether  shape,  distance,  or
       area  are  the most important parameters.  For any of these, the refer-
       ence parallels should be chosen at approximately 1/6  and  5/6  of  the
       range  of  latitudes  to  be  displayed.   For instance, maps of the 48
       coterminous United States are attractive with  reference  parallels  of
       28.5 and 45.5 degrees.

       If  the  large area is equatorial and is round or has a primarily east-
       west extent, then the Mercator projection is a good choice for  a  con-
       formal  projection;  Lambert cylindrical equal-area and sinusoidal pro-
       jections are good equal-area projections; and the  plate  carree  is  a
       good equidistant projection.

       Large  areas  having a primarily North-South aspect, particularly those
       spanning the Equator, need some other choices.  The Cassini  projection
       is a good choice for an equidistant projection (for instance, a Cassini
       projection with a central meridian  of  80  degrees  West  produces  an
       attractive  map  of  the  Americas). The cylindrical equal-area, Albers
       equal-area conic, sinusoidal, Mollweide and Hammer projections are pos-
       sible  choices for equal-area projections.  A good conformal projection
       in this situation is the Transverse Mercator, which alas,  is  not  yet
       implemented.

       Small  areas  begin  to  get  into a realm where the ellipticity of the
       Earth affects the map scale.  This package does not attempt  to  handle
       accurate  mapping  for  large-scale  topographic maps.  If slight scale
       errors are acceptable in your application, then any of the  projections
       appropriate to large areas should work for small ones as well.

       There are a few projections that are included for their special proper-
       ties.  The orthographic projection produces views of the Earth as  seen



mapproj                        0.1                              8





mapproj(n)                 Tcl Library                 mapproj(n)


       from  space.  The gnomonic projection produces a map on which all great
       circles (the shortest distance between two points on the  Earth's  sur-
       face)  are rendered as straight lines.  While this projection is useful
       for navigational planning, it has  extreme  distortions  of  shape  and
       area,  and  can display only a limited area of the Earth (substantially
       less than a hemisphere).

KEYWORDS
       geodesy, map, projection

COPYRIGHT
       Copyright (c) 2007 Kevin B. Kenny <kennykb@acm.org>













































mapproj                        0.1                              9


