Chapter 13: Geographical Projections and Plotting Maps

This chapter presents different  methods  to project geogra-
phical coordinates  onto a plane surface.  Several base maps
are stored in DISLIN for plotting maps.

13.1 Axis Systems and Secondary Axes

                         G R A F M P

The routine GRAFMP plots a geographical axis system.

The call is:  CALL GRAFMP (XA, XE, XOR, XSTP,
                           YA, YE, YOR, YSTP)        level 2

XA, XE        are the lower and upper limits of the X-axis.
XOR, XSTP     are the  first  X-axis label  and the step be-
              tween labels.
YA, YE        are the lower and upper limits of the Y-axis.
YOR, YSTP     are the  first  Y-axis label  and the step be-
              tween labels.

Notes:     -  GRAFMP  must be called  from level 1  and sets
              the level to 2.
           -  The axes must be linear  and  scaled in ascen-
              ding order. In general,  X-axes must be scaled
              between  -180  and 180 degrees and  Y-axes be-
              tween -90 and 90 degrees.
           -  For elliptical projections, the plotting of an
              axis system will be suppressed. This will also
              be done for azimuthal projections with YE - YA
              > 90.
           -  The statement  CALL GRIDMP (I, J)  overlays an
              axis system with a longitude and latitude grid
              where I and J are the number of grid lines be-
              tween labels in the X- and Y-direction.

                         X A X M A P

The routine XAXMAP plots a secondary X-axis.

The call is:  CALL XAXMAP (A, B, OR, STEP, CSTR, NT, NY)
                                                     level 2

A, B          are the lower and upper limits of the X-axis.
OR, STEP      are the  first label  and the step between la-
              bels.
CSTR          is a  character  string  containing  the  axis
              name.
NT            indicates how ticks,  labels and the axis name
              are plotted. If NT = 0,  they are plotted in a
              clockwise direction. If NT = 1, they are plot-
              ted in a counter-clockwise direction.
NY            defines the horizontal position of the X-axis.
              A secondary axis  must be  located inside  the
              axis system.

                        Y A X M A P

The routine YAXMAP plots a secondary Y-axis.

The call is:  CALL YAXMAP (A, B, OR, STEP, CSTR, NT, NX)
                                                     level 2

A, B          are the lower and upper limits of the Y-axis.
OR, STEP      are the  first label  and the step between la-
              bels.
CSTR          is a  character  string  containing  the  axis
              name.
NT            indicates how ticks,  labels and the axis name
              are plotted. If NT = 0,  they are plotted in a
              clockwise direction. If NT = 1, they are plot-
              ted in a counter-clockwise direction.
NX            defines the  vertical  position of the Y-axis.
              A secondary axis  must be  located inside  the
              axis system.

13.2 Defining the Projection

Since a  globe cannot be unfolded into a plane surface, many
different  methods have been  developed to represent a globe
on a plane surface.  In cartography,  there are  4 basic me-
thods differentiated by attributes  such as  equal distance,
area and angle.

The 4 basic methods are:

a) Cylindrical Projections

   The surface  of the globe  is projected  onto  a cylinder
   which can be unfolded  into a  plane surface  and touches
   the globe at the equator. The latitudes and longitudes of
   the globe are projected as straight lines.

b) Conical Projections

   The surface  of the globe is projected  onto a cone which
   can  also be  unfolded  into  a plane  surface.  The cone
   touches or intersects the  globe  at two  latitudes.  The
   longitudes are projected  as straight lines  intersecting
   at the top of the cone and the latitudes are projected as
   concentric circles around the top of the cone.

c) Azimuthal Projections

   For azimuthal projections, a hemisphere is projected onto
   a plane which touches  the hemisphere  at a point  called
   the map pole.  The longitudes and latitudes are projected
   as circles.

d) Elliptical Projections

   Elliptical projections  project the entire surface of the
   globe onto an elliptical region.

                       P R O J C T

The routine PROJCT selects the geographical projection.

The call is:  CALL PROJCT (CTYPE)                    level 1

CTYPE         is a character string defining the projection.
  = 'CYLI'    defines a cylindrical equidistant projection.
  = 'MERC'    selects the Mercator projection.
  = 'EQUA'    defines a cylindrical equal-area projection.
  = 'HAMM'    defines the elliptical projection of Hammer.
  = 'AITO'    defines the elliptical projection of Aitoff.
  = 'WINK'    defines the elliptical projection of Winkel.
  = 'SANS'    defines the elliptical Mercator-Sanson projec-
              tion.
  = 'CONI'    defines a conical equidistant projection.
  = 'ALBE'    defines a conical equal-area projection
              (Albers).
  = 'CONF'    defines a conical conformal projection.
  = 'AZIM'    defines an azimuthal equidistant projection.
  = 'LAMB'    defines an azimuthal equal-area projection.
  = 'STER'    defines an azimuthal stereographic projection.
  = 'ORTH'    defines an azimuthal orthographic projection.
  = 'MYPR'    defines a user-defined projection.
                                    Default: CTYPE = 'CYLI'.

Notes:     -  For cylindrical equidistant  projections,  the
              scaling  parameters in  GRAFMP  must be in the
              range:

                         -540 <= XA <= XE <= 540
                         -180 <= YA <= YE <= 180

              For Mercator projections:

                         -540 <= XA <= XE <= 540
                         - 85 <= YA <= YE <=  85

              For cylindrical equal-area projections:

                         -540 <= XA <= XE <= 540
                         - 90 <= YA <= YE <=  90

              For elliptical projections:

                         -540 <= XA <= XE <= 540
                             XE - XA <= 360
                         - 90 <= YA <= YE <=  90

              For conical projections:

                         -540 <= XA <= XE <= 540
                            0 <= YA <= YE <=  90  or
                         - 90 <= YA <= YE <=   0

              For azimuthal projections  with  YE - YA > 90,
              the  hemisphere  around  the map pole  is pro-
              jected  onto  a  circle. Therefore,  the hemi-
              sphere  can be selected with the map pole. The
              plotting of the axis system is by default sup-
              pressed. 
              If  YE  -  YA  <=  90,  the part  of the globe
              defined by the axis scaling  is projected onto
              a rectangle. The map pole will be set by GRAF-
              MP to ((XA+XE)/2, (YE+YA)/2).  The scaling pa-
              rameters must be in the range:

                         -180 <= XA <= XE <= 180 and
                                  XE - XA <= 180
                         - 90 <= YA <= YE <=  90
           -  For all projections except the default projec-
              tion, longitude and latitude coordinates  will
              be projected with the same scaling factor  for
              the  X- and  Y-axis. The scaling factor is de-
              termined  by the  scaling  of the Y-axis while
              the scaling of the  X-axis  is used  to centre
              the map.  The longitude  (XA+XE)/2 always lies
              in the centre of the axis system.
           -  Geographical projections  can only be used for
              routines described in this chapter or routines
              that plot contours.

13.3 Plotting Maps

                         W O R L D

The routine  WORLD plots coastlines  and lakes or political
borders. Coastlines and lakes are plotted by default, poli-
tical borders can be enabled with the routine MAPOPT.

The call is:  CALL WORLD                             level 2

Note:         The routine WORLD  supports also some external
              map coordinates (see MAPBAS).

                         S H D M A P

The routine SHDMAP plots shaded continents.

The call is:  CALL SHDMAP (CMAP)                     level 2
CMAP          is a character string defining the continent.
  = 'AFRI'    means Africa.
  = 'ANTA'    means the Antarctic.
  = 'AUST'    means Australia.
  = 'EURA'    means Europe and Asia.
  = 'NORT'    means North America.
  = 'SOUT'    means South America.
  = 'LAKE'    means lakes.
  = 'ALL'     means all continents and lakes.
  = 'SEA'     means that oceans and lakes are shaded.
  = 'LSEA'    means that oceans and lakes are shaded, where
              'gshhs_l.b' is used for sea shading.
  = 'ISEA'    means that oceans and lakes are shaded, where
              'gshhs_i.b' is used for sea shading.
  = 'HSEA'    means that oceans and lakes are shaded, where
              'gshhs_h.b' is used for sea shading.
  = 'LAND'    means that all land is shaded without lakes.
  = 'GSHL'    means that  'gshhs_l.b'  is used for all land
              shading.
  = 'GSHI'    means that  'gshhs_i.b'  is used for all land
              shading.
  = 'GSHH'    means that  'gshhs_h.b'  is used for all land
              shading.

Note:         Shading patterns  can be selected with  SHDPAT
              and MYPAT except for 'SEA' and 'LAND' shading,
              where a solid shading is used.  Colours can be
              defined with COLOR and SETCLR.

                        S H D A F R

The routine SHDAFR plots shaded African countries.

The call is:  CALL SHDAFR (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array  containing the countries
              to be shaded. INRAY can have the following va-
              lues:

    1: Algeria           19: Gabon          37: Nigeria
    2: Angola            20: Gambia         38: Ruanda
    3: Benin             21: Ghana          39: Senegal
    4: Botswana          22: Guinea         40: Seychelles
    5: Burkina Faso      23: Guinea Bissau  41: Sierra Leone
    6: Burundi           24: Kenya          42: Somalia
    7: Cameroon          25: Lesotho        43: South Africa
    8: Central Afr. Rep. 26: Liberia        44: Sudan 
    9: Chad              27: Libya          45: Swaziland
   10: Comoros           28: Madagascar     46: Tanzania
   11: Congo, Dem. Rep.  29: Malawi         47: Togo        
   12: Congo, Rep.       30: Mali           48: Tunisia
   13: Cote d'Ivoire     31: Mauritania     49: Uganda
   14: Djibouti          32: Mauritius      50: West Sahara
   15: Egypt             33: Morocco        51: Zambia 
   16: Equatorial Guinea 34: Mozambique     52: Zimbawe
   17: Eritrea           35: Namibia       
   18: Ethiopia          36: Niger           0: Africa

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of countries to be shaded.

Note:         The  plotting  of outlines  can be  suppressed
              with CALL NOARLN.

                        S H D A S I

The routine SHDASI plots shaded Asiatic countries.

The call is:  CALL SHDASI (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array  containing the countries
              to be shaded. INRAY can have the following va-
              lues:

    1: Afghanistan     19: Jordan         37: Saudiarab  
    2: Armenia         20: Kazakhstan     38: Scrilanka  
    3: Azerbaijan      21: Korea (North)  39: Singapore 
    4: Bangladesh      22: Korea (South)  40: Spratly  
    5: Bhutan          23: Kuwait         41: Syria 
    6: Brunei          24: Kyrgyzstan     42: Taiwan 
    7: Burma           25: Laos           43: Tajikistan  
    8: Cambodia        26: Lebanon        44: Thailand 
    9: China           27: Malaysia       45: Turkey 
   10: Emirates        28: Maldives       46: Turkmenistan
   11: Gaza            29: Mongolia       47: Uzbekistan
   12: Georgia         30: Nepal          48: Vietnam
   13: India           31: Oman           49: Westbank  
   14: Indonesia       32: Pakistan       50: Yemen 
   15: Iran            33: Paracel       
   16: Irak            34: Philippines   
   17: Israel          35: Quatar        
   18: Japan           36: Russia          0: All

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of countries to be shaded.

Note:         The  plotting  of outlines  can be  suppressed
              with CALL NOARLN.

                        S H D A U S

The routine  SHDAUS  plots shaded countries of Australia and 
Oceania.

The call is:  CALL SHDAUS (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array  containing the countries
              to be shaded. INRAY can have the following va-
              lues:

    1: Australia       6: Nauru            11: Solomon  
    2: Fiji            7: Newcaledonia     12: Tonga  
    3: Kiribati        8: Newsealand       13: Tuvalu 
    4: Marshall        9: Papanewguinea    14: Vanuatu
    5: Micronesia     10: Samoa             0: All

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 

Note:         The  plotting  of outlines  can be  suppressed
              with CALL NOARLN.

                        S H D E U R

The routine SHDEUR plots shaded European countries.

The call is:  CALL SHDEUR (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array  containing the countries
              to be shaded. INRAY can have the following va-
              lues:

         1: Albania         17: Luxembourg    33: Belarus
         2: Andorra         18: Malta         34: Bosnia 
         3: Belgium         19: Netherlands   35: Croatia
         4: Bulgaria        20: North Ireland 36: Czech 
         5: Germany         21: Norway        37: Estonia
         6: Denmark         22: Austria       38: Latvia
         7: Cyprus          23: Poland        39: Lithuania
         8: United Kingdom  24: Portugal      40: Macedonia
         9: Finland         25: Romania       41: Moldavia
        10: France          26: Sweden        42: Russia
        11: Greece          27: Switzerland   43: Serbia         
        12: Ireland         28: Spain         44: Slovakia
        13: Iceland         29: CSFR          45: Slovenia
        14: Italy           30: Turkey        46: Ukraine
        15: Yugoslavia      31: USSR          47: Kosovo
        16: Liechtenstein   32: Hungary       48: Montenegro
                                               0: Europe

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of countries to be shaded.

Notes:      - The  plotting  of outlines  can be  suppressed
              with CALL NOARLN.
            - To stay  compatible  with older programs,  the 
              number 15 (Yugoslavia) plots Bosnia,  Croatia,
              Macedonia, Serbia and Slovenia,  the number 29
              (CSFR) plots  Czech Republic and Slovakia  and
              the number 31 (USSR)  plots  Belarus, Estonia,
              Latvia,  Lithuania, Moldavia, Russia and Ukra-
              ine.

                        S H D N O R

The routine  SHDNOR  plots  shaded countries  of  North  and 
Central America.

The call is:  CALL SHDNOR (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array containing the  states to
              be shaded.  INRAY  can have  the following va-    
              lues:

   1: Alaska           13: El Salvador  25: Nicaragua
   2: Antigua, Barbuda 14: Greenland    26: Panama
   3: Bahamas          15: Grenada      27: Puerto Rico
   4: Barbados         16: Guadeloupe   28: St. Kitts, Nevis
   5: Belize           17: Guatemala    29: St. Lucia
   6: British Virgin   18: Haiti        30: St. Vincent
   7: Caiman Islands   19: Honduras     31: Trinidad
   8: Canada           20: Jamaica      32: USA
   9: Costa Rica       21: Martinique      
  10: Cuba             22: Mexico        0: All 
  11: Dominica         23: Montserrat      
  12: Dominican Rep.   24: Neth. Antilles

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of states to be shaded.

                        S H D S O U

The routine SHDSOU plots shaded states of South America.

The call is:  CALL SHDSOU (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array containing the  states to
              be shaded.  INRAY  can have  the following va-    
              lues:

     1: Argentina    6: Ecuador         11: Suriname
     2: Bolivia      7: French Guyana   12: Uruguay
     3: Brazil       8: Guyana          13: Venezuela
     4: Chile        9: Paraguay         
     5: Colombia    10: Peru             0: All

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of states to be shaded.

                        S H D U S A

The routine SHDUSA plots shaded USA states.

The call is:  CALL SHDUSA (INRAY, IPRAY, ICRAY, N)   level 2

INRAY         is an  integer array containing the  states to
              be shaded.  INRAY  can have  the following va-    
              lues:

        1: Alabama     19: Maine          37: Oregon 
        2: Alaska      20: Maryland       38: Pennsylvania
        3: Arizona     21: Massachusetts  39: Rhode Island
        4: Arkansas    22: Michigan       40: South Carolina
        5: California  23: Minnesota      41: South Dakota
        6: Colorado    24: Mississippi    42: Tennessee
        7: Connecticut 25: Missouri       43: Texas
        8: Delaware    26: Montana        44: Utah
        9: Florida     27: Nebraska       45: Vermont 
       10: Georgia     28: Nevada         46: Virginia
       11: Hawaii      29: New Hampshire  47: Washington
       12: Idaho       30: New Jersey     48: West Virginia
       13: Illinois    31: New Mexico     49: Wisconsin
       14: Indiana     32: New York       50: Wyoming
       15: Iowa        33: North Carolina 51: Washington DC 
       16: Kansas      34: North Dakota   
       17: Kentucky    35: Ohio           
       18: Louisiana   36: Oklahoma        0: USA

IPRAY         is an  integer array  containing  shading pat-
              terns.
ICRAY         is an integer array containing colour numbers.
              The value -1 means  that the current colour is
              used. 
N             is the number of states to be shaded.

                         M A P I M G

The routine  MAPIMG  plots a BMP  or  GIF raster image to an
axis system.  Some parameters  which describe  the location,
scale and  rotation of  the map  are passed to  MAPIMG.  The 
parameters have  the  same meaning  as the attributes of the
ESRI World File Format.   

The call is:  CALL MAPIMG (CFIL, X1, X2, X3, X4, X5, X6) 
                                                     level 2
CFIL          is a character string that  contains  the name
              of a BMP or GIF file.
X1            is the  pixel size  in the  X-direction in map 
              units per pixel.
X2            is the rotation about the Y-axis.
X3            is the rotation about the X-axis.
X4            is the  pixel size  in the  Y-direction in map 
              units per pixel. This value is normally a neg-
              ative number.
X5            is the X-coordinate of the centre of the upper
              left pixel.
X6            is the Y-coordinate of the centre of the upper
              left pixel.

13.4 Plotting Data Points

                         C U R V M P

The routine CURVMP plots curves through data points or marks
them with symbols.

The call is:  CALL CURVMP (XRAY, YRAY, N)            level 2

XRAY, YRAY    are real arrays containing the data points.
N             is the number of data points.

Notes:     -  CURVMP is similar to  CURVE except that only a
              linear interpolation can be used.
           -  In general,  a line between two points  on the
              globe  will  not  be  projected  as a straight
              line. Therefore, CURVMP interpolates lines li-
              nearly by small steps.  An alternate  plotting
              mode can be set with MAPMOD.

13.5 Parameter Setting Routines

                         M A P B A S

The routine  MAPBAS  defines  the map data file  used in the
routine WORLD.  An internal  DISLIN  map file, some external
map files compiled by  Paul Wessel  and map files in  Mapgen
format can be used.  The map files  compiled by  Paul Wessel
can be copied from the servers

   http://www.ngdc.noaa.gov/mgg/shorelines/data/gshhs
   ftp://ftp.soest.hawaii.edu/pwessel/gshhs/

The external map files 'gshhs_l.b', 'gshhs_i.b', 'gshhs_h.b'
and  'gshhs_f.b'  must be copied  to the map subdirectory of 
the DISLIN directory.

Map files in  Mapgen format are available from the Coastline
Extractor:

   http://rimmer.ngdc.noaa.gov/

The call is:  CALL MAPBAS (CBAS)                  level 1, 2

CBAS          is a  character string  defining  the map data
              file:

 = 'DISLIN'   defines the DISLIN base map.
 = 'GSHL'     defines 'gshhs_l.b' as base map.
 = 'GSHI'     defines 'gshhs_i.b' as base map.
 = 'GSHH'     defines 'gshhs_h.b' as base map.
 = 'GSHF'     defines 'gshhs_f.b' as base map.
 = 'MAPFIL'   defines an external map file as base map 
              that is specified with the routine MAPFIL.
                                   Default: CBAS = 'DISLIN'.

                         M A P F I L

The routine  MAPFIL  defines  an external map file.  The map
file can be used as base map if the routine MAPBAS is called
with the parameter 'MAPFIL'.

The call is:  CALL MAPFIL (CFIL, COPT)            level 1, 2

CFIL          is a character string  containing the filename
              of the external map file.
COPT          is a character string describing the format of
              the map coordinates.  COPT can have the values
              'GSHHS' and 'MAPGEN'.

                         M A P L E V

The routine  MAPLEV  defines land, lake or river coordinates
for  WORLD  if the external map files  from  Paul Wessel are
used.

The call is:  CALL MAPLEV (COPT)                  level 1, 2

COPT          is a character string that can have the values
              'BOTH', 'LAND',  'LAKE' and 'RIVERS'. The key-
              word 'BOTH' means 'LAND' and 'LAKE'. If COPT =
              'RIVERS',  the WDB rivers distributed with the
              GSHHS coordinates are plotted.
                                    Default:  COPT = 'BOTH'.

                         M A P P O L

MAPPOL defines the map pole used for azimuthal projections.

The call is:  CALL MAPPOL (XPOL, YPOL)               level 1

XPOL, YPOL    are the longitude and latitude coordinates  in
              degrees where:
                         -180 <= XPOL <= 180 and
                          -90 <= YPOL <=  90.
                                           Default: (0., 0.)

Note:         For an azimuthal  projection  with  YE - YA <=
              90,  the  map pole  will be  set by  GRAFMP to
              ((XA+XE)/2, (YA+YE)/2).

                         M A P S P H

For an azimuthal projection with YE - YA > 90,  DISLIN auto-
matically projects a hemisphere  around the map pole  onto a
circle. The hemisphere can be reduced using MAPSPH.

The call is:  CALL MAPSPH (XRAD)                     level 1

XRAD          defines the  region  around  the map pole that
              will be projected onto a circle   (0 < XRAD <=
              90).
                                         Default: XRAD = 90.

                         M A P R E F

The routine MAPREF defines, for conical projections, two la-
titudes where the cone intersects or touches the globe.

The call is:  CALL MAPREF (YLW, YUP)                 level 1

YLW, YUP      are the lower and upper latitudes where:

                      0 <= YLW <= YUP <= 90  or
                   - 90 <= YLW <= YUP <=  0
                       Default:  YLW = YA + 0.25 * (YE - YA)
                                 YUP = YA + 0.75 * (YE - YA)

Note:         YLW and  YUP can have identical values and lie
              outside of the axis scaling.

                         M A P L A B

The routine  MAPLAB enables axis system labels for azimuthal
and elliptical projections.

The call is:  CALL MAPLAB (COPT, CKEY)            level 1, 2

COPT          is a  character  string  that  can contain the
              options 'NONE', 'LEFT', 'RIGHT' and 'BOTH'.  
CKEY          is a character string containing  the  keyword
              'LATITUDE'.
                              Default: ('NONE', 'LATITUDE').

                         M A P M O D

The routine MAPMOD determines how data  points will be  con-
nected by CURVMP.

The call is:  CALL MAPMOD (CMODE)                 level 1, 2

CMODE         is a character string defining  the connection
              mode.
 = 'STRAIGHT' defines straight lines.
 = 'INTER'    means  that lines will be interpolated linear-
              ly.
 = 'GREAT'    means Great Circle interpolation.
                                  Default:  CMODE = 'INTER'.

                         M A P O P T

The routine  MAPOPT enables political borders plotted by the
routine WORLD, or sets an option to adjust the length of the
X-axis to the scaling.

The call is:  CALL MAPOPT (COPT, CKEY)            level 1, 2

COPT          is a character string containing an option.
CKEY          is a character string containing a keyword:
 = 'WORLD'    If  CKEY = 'WORLD',  COPT  can have the values 
              'COAST',  'BORDERS'  and  'BOTH'.  The default
              value is COPT = 'COAST'.
 = 'XAXIS'    If  CKEY = 'XAXIS',  COPT  can have the values
              'STANDARD' and 'AUTO'. Normally, longitude and 
              latitude  coordinates  will be  projected with
              the same scaling factor where the scaling fac-
              tor is determined by the scaling of the Y-axis
              while  the scaling  of the  X-axis  is used to 
              centre  the  map.  For  COPT = 'AUTO',  DISLIN 
              tries the change the length of the X-axis,  so
              that  the axis length  corresponds to the sca-
              ling parameters in  GRAFMP for the X-axis.  The 
              default value is COPT = 'STANDARD'.  

13.6 Conversion of Coordinates

                         P O S 2 P T

The routine  POS2PT converts map coordinates to plot coordi-
nates.

The call is:  CALL POS2PT (XLONG, YLAT, XP, YP)      level 2

XLONG, YLAT   are the map  coordinates in  degrees.  The map
              coordinates should be in the range of the axis
              scaling.
XP, YP        are the plot coordinates calculated by POS2PT.

The corresponding functions are:

              XP = X2DPOS (XLONG, YLAT)
              YP = Y2DPOS (XLONG, YLAT)

                         P T 2 P O S

The routine PT2POS is the inverse routine to POS2PT and con-
verts plot coordinates to map coordinates.  The plot coordi-
nates should be located in the current axis system.

The call is:  CALL POS2PT (XP, YP, XLONG, YLAT)      level 2

XP, YP        are the plot coordinates.
XLONG, YLAT   are the map coordinates calculated by PT2POS.


13.7 User-defined Projections

A user-defined  projection  can be enabled  with the keyword
'MYPR' in the routine PROJCT. For a user-defined projection,
the user must write a routine that  converts  longitude  and
latitude coordinates  to axis coordinates  (plot coordinates
relative to the origin of the axis system).  The name of the
user written routine  must  then passed  to  DISLIN with the 
routine SETCBK.

                         S E T C B K

The routine SETCBK defines a user written callback routine.

The call is:  CALL SETCBK (ROUTINE, 'MYPR') level 0, 1, 2, 3

ROUTINE       is the name of a routine defined by the user. 
              In Fortran, the routine must be declared as 
              EXTERNAL.

In the following example, a cylindrical projection is imple-
mented as a user-defined projection:

      PROGRAM MYPR
      EXTERNAL MYFUNC
      COMMON /MYCOMM/ XA,XE,YA,YE,NXL,NYL

      XA = -180.
      XE = 180.
      YA = -90.
      YE = 90.

      NXL = 2400
      NYL = 1200

      CALL METAFL ('cons')
      CALL DISINI
      CALL PAGERA 
      CALL COMPLX 
      CALL AXSLEN (NXL, NYL)

      CALL PROJCT ('MYPR') 
      CALL SETCBK (MYFUNC, 'MYPR')

      CALL GRAFMP (XA, XE, XA, 90., YA, YE, YA, 30.)
      CALL GRIDMP (1,1)
      CALL WORLD 
      CALL DISFIN 
      END

      SUBROUTINE MYFUNC (XP, YP)  
      COMMON /MYCOMM/ XA,XE,YA,YE,NXL,NYL
      XP = (XP - XA)/(XE - XA) * (NXL - 1)
      YP = (YP - YA)/(YE - YA) * (NYL - 1)
      END

13.8 Examples

            PROGRAM EX13_1

            CALL SETPAG('DA4L')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL FRAME(3)
            CALL AXSPOS(400,1850)
            CALL AXSLEN(2400,1400)

            CALL NAME('Longitude','X')
            CALL NAME('Latitude','Y')
            CALL TITLIN('World Coastlines and Lakes',3)

            CALL LABELS('MAP','XY')
            CALL GRAFMP(-180.,180.,-180.,90.,
           *             -90., 90., -90.,30.)

            CALL GRIDMP(1,1)
            CALL WORLD

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END

            PROGRAM EX13_2
            CHARACTER*6 CPROJ(3),CTIT*60
            DATA CPROJ/'Sanson','Winkel','Hammer'/

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL HEIGHT(40)
            CALL AXSLEN(1600,750)

            NYA=3850
            DO I=1,3
              NYA=NYA-950
              CALL AXSPOS(250,NYA)

              CALL PROJCT(CPROJ(I))
              CALL NOCLIP
              CALL GRAFMP(-180.,180.,-180.,30.,
          *                -90., 90., -90.,15.)

              WRITE(CTIT,'(2A)') 
          *     'Elliptical Projection of ', CPROJ(I)
              CALL TITLIN(CTIT,4)
              CALL TITLE

              CALL WORLD
              CALL GRIDMP(1,1)
              CALL ENDGRF
            END DO

            CALL DISFIN
            END

            PROGRAM EX13_3
            DIMENSION NXA(4),NYA(4),XPOL(4),YPOL(4)
            CHARACTER*60 CTIT
            DATA NXA/200,1150,200,1150/,
           *     NYA/1600,1600,2700,2700/
            DATA XPOL/0.,0.,0.,0./,YPOL/0.,45.,90.,-45./

            CTIT='Azimuthal Lambert Projections'

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL HEIGHT(50)
            NL=NLMESS(CTIT)
            NX=(2250-NL)/2.
            CALL MESSAG(CTIT,NX,300)

            CALL AXSLEN(900,900)
            CALL PROJCT('LAMBERT')

            DO I=1,4
              CALL AXSPOS(NXA(I),NYA(I))
              CALL MAPPOL(XPOL(I),YPOL(I))
              CALL GRAFMP(-180.,180.,-180.,30.,
           *               -90., 90., -90.,30.)

              CALL WORLD
              CALL GRIDMP(1,1)
              CALL ENDGRF
            END DO

            CALL DISFIN
            END

            PROGRAM EX13_4
            DIMENSION INRAY(1),IPRAY(1),ICRAY(1)

            INRAY(1)=0
            IPRAY(1)=0
            ICRAY(1)=1

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL INTAX
            CALL TICKS(1,'XY')
            CALL FRAME(3)
            CALL AXSLEN(1600,2200)
            CALL AXSPOS(400,2700)

            CALL NAME('Longitude','X')
            CALL NAME('Latitude','Y')
            CALL TITLIN('Conformal Conic Projection',3)

            CALL LABELS('MAP','XY')
            CALL PROJCT('CONF')
            CALL GRAFMP(-10.,30.,-10.,5.,35.,70.,35.,5.)

            CALL GRIDMP(1,1)
            CALL SHDEUR(INRAY,IPRAY,ICRAY,1)

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END

