Provided by: tcllib_1.14-dfsg-1_all bug

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::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::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 carr['e]e (cylindrical equidistant) projection.

       ::mapproj::fromPlateCarree lambda_0 phi_0 x y
              Converts from the plate carr['e]e (cylindrical equidistant) projection.

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

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

       ::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) projection.

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

       ::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::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 projection. (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  projection.  (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 projections, this
              figure is also the reference meridian of the projection.

       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 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, measured 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 projection 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  Lambert  azimuthal
       equal-area  projection,  the Albers equal-area conic projection, and several of the world-
       map projections (Miller Cylindrical,  Mollweide,  Eckert  IV,  Eckert  VI,  Robinson,  and
       Hammer).  If  the significant 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
       carr['e]e,  Cassini,  azimuthal  equidistant,  or  conic equidistant.  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 general shape of the
       area of interest.  For maps of the entire Earth, the cylindrical equal area, Eckert IV and
       VI,  Mollweide,  Robinson,  and Hammer 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  distortion  of  landforms.   The  Miller
       Cylindrical  is  a compromise designed 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 scientific data, since other projections
       have moe useful geometric properties.

       If the map will cover a  hemisphere,  then  choose  stereographic,  azimuthal-equidistant,
       Hammer, or Mollweide projections; these all project 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 reference
       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 conformal projection; Lambert cylindrical
       equal-area and sinusoidal projections are  good  equal-area  projections;  and  the  plate
       carr['e]e 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 possible 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  properties.   The
       orthographic  projection  produces  views  of  the Earth as seen from space.  The gnomonic
       projection produces a map on which all great circles (the shortest  distance  between  two
       points  on  the Earth's surface) 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>