SETSPHERE, INITSPHERES, and SPHEREDAT

Fortran version:

    LOGICAL FUNCTION SETSPHERE( AXISMAJOR, AXISMINOR )
    LOGICAL FUNCTION INITSPHERES()
    LOGICAL FUNCTION SPHEREDAT( INSPHERE, INPARAM, IOPARAM )
    
      REAL*8 , INTENT(IN   ) :: AXISMAJOR     ! small integer, or major axis (meters)
      REAL*8 , INTENT(IN   ) :: AXISMINOR     ! minor axis (meters) or eccentricity
      INTEGER, INTENT(  OUT) :: INSPHERE      ! argument for GCTP
      REAL*8 , INTENT(INOUT) :: INPARAM( 15 ) ! argument for GCTP
      REAL*8 , INTENT(INOUT) :: IOPARAM( 15 ) ! argument for GCTP

Summary:

SETSPHERE(), INITSPHERES(), and SPHEREDAT() may be used to set up the choice of spheres for LL2UTM(), UTM2LL(), LL2LAM(), LAM2LLL(), etc., and for setting up the argument-lists for USGS National Mapping Division's General Cartographic Transformation Package routine GTPZ0().

INITSPHERES() uses environment variable IOAPI_ISPH to set up internal sphere specifications; it is called automatically during the initialization of the wrapper routines, and defaults to the GRS-1980 geodetic spheroid in the absence of user specification. Sphere-specification should follow the criteria below. Since INITSPHERES() is called automatically by the wrapper-routines, its use should not be needed unless you want to call GCTP directly.

SETSPHERE() uses sphere specifications established by SETSPHERE() or INITSPHERES(), and sets up the arguments INSPH, TPARIN, and TPARIO for GCTP accordingly.

SPHEREDAT() uses the most recently stored sphere specifications established by SETSPHERE() or INITSPHERES() to set up the arguments INSPH, TPARIN, and TPARIO accordingly for USGS National Mapping Division's General Cartographic Transformation Package routine GTPZ0(). (Normally this functionality is handled within the wrapper-routines; it should be needed only for direct calls to GCTP.)

Note that GCTP only permits the specification of one sphere at a time, so sphere-to-sphere coordinate transformations must use Lat-Lon as an intermediate step between the starting projection and spheroid and the final projection and spheroid. For example, to transform from UTM coordinates <x,y> on Clarke 1880 to Lambert coordinates <s,t> on GRS 1980, one might set the spheroid to 1 with SETSPHERE and use UTM2LL on <x,y> to compute Lat-Lon coordinates <p,q>, then set the spheroid to 8 with SETSPHERE and use LL2LAM to transform <p,q> into the desired <s,t>.

Note that for backwards-compatibility both MODULE M3UTILIO and MODULE MODGCTP declare these routines. If you USE both of these modules for these routines, you must re-name the M3UTILIO version in the following fashion:

    USE M3UTILIO, M3U_INITSPHERES => INITSPHERES,   &
                  M3U_SETSPHERE   => SETSPHERE,     &
                  M3U_SPHEREDAT   => SPHEREDAT
    

Sphere Specification:

Small integers in the range 0, ..., 21 may be used to designate "standard" USGS spheroids, according to the following list which may be found in MODULE MODGCTP as STDSPHERES and SPHERENAMES):
  1. Clarke 1866
  2. Clarke 1880
  3. Bessel
  4. New International 1967
  5. International 1909
  6. WGS 72
  7. Everest
  8. WGS 66
  9. GRS 1980
  10. Airy
  11. Modified Everest
  12. Modified Airy
  13. WGS 84
  14. Southeast Asia
  15. Australian National
  16. Krassovsky
  17. Hough
  18. Mercury 1960
  19. Modified Mercury 1968
  20. Normal Sphere, R_Earth=6370997
  21. Normal Sphere (MM5 / WRF-ARW) R_Earth=6370000
  22. Normal Sphere (WRF-NMM) R_Earth=6371200
DOUBLE PRECISION sphere radius in meters may be used to designate a requested spherical Earth. A pair of DOUBLE PRECISION containing the major axis and the minor axis in meters, or the major axis and square of the eccentricity may be used to designate a requested spheroidal Earth. Examples are as follows:

Preconditions

For INITSPHERES():
    setenv IOAPI_ISPH <value>
    
to establish program-wide non-default geodetic spheroid choices.

Fortran Usage:

For I/O API Version 3.2 or later:
    USE MODGCTP
    
For I/O API Version 3.1:
    USE M3UTILIO, M3U_INITSPHERES => INITSPHERES,   &
                  M3U_SETSPHERE   => SETSPHERE,     &
                  M3U_SPHEREDAT   => SPHEREDAT
    
For earlier versions:
    LOGICAL, EXTERNAL :: INITSPHERES, SETSPHERE, SPHEREDAT
    

    ...
    !!   Arguments for GTPZ0:

    REAL*8          CRDIN( 2 )      !  input coordinates x,y
    INTEGER*4       INSYS           !  input projection code
    INTEGER*4       INZONE          !  input utm zone, etc.
    REAL*8          TPAIN( 15 )     !  input projection parameters
    INTEGER*4       INUNIT          !  input units code
    INTEGER*4       INSPH           !  spheroid code
    INTEGER*4       IPR             !  error print flag
    INTEGER*4       JPR             !  projection parameter print flag
    INTEGER*4       LEMSG           !  error message unit number
    INTEGER*4       LPARM           !  projection parameter unit number
    REAL*8          CRDIO( 2 )      !  output coordinates x,y
    INTEGER*4       IOSYS           !  output projection code
    INTEGER*4       IOZONE          !  output utm zone, etc.
    REAL*8          TPOUT( 15 )     !  output projection parameters
    INTEGER*4       IOUNIT          !  output units code
    INTEGER*4       LN27            !  NAD1927 file unit number
    INTEGER*4       LN83            !  NAD1983 file unit number
    CHARACTER*128   FN27            !  NAD1927 file name
    CHARACTER*128   FN83            !  NAD1983 file name
    INTEGER*4       LENGTH          !  NAD* record-length
    INTEGER*4       IFLG            !  error flag
    ...
    IF ( .NOT. INITSPHERES() ) THEN
        !!   first, call initspheres() or setsphere()
        EFLAG = .TRUE.
        MESG  = 'SETSPHERE/INITSPHERES() failure'
        CALL M3MESG( MESG )
    ELSE IF ( .NOT. SPHEREDAT( INSPH, TPAIN, TPOUT ) ) THEN
        !!  then call spheredat() on TPAIN and TPOUT:
        EFLAG = .TRUE.
        MESG  = 'SETSPHERE/SPHEREDAT() failure'
        CALL M3MESG( MESG )
    END IF
    ...
    !!  then use TPAIN and TPOUT in call to GTP0()
    CALL GTPZ0( CRDIN, INSYS, INZONE, TPAIN, INUNIT, INSPH, &
                IPR, JPR, LEMSG, LPARM,                     &
                CRDIO, IOSYS, IOZONE, TPOUT, IOUNIT,        &
                LN27, LN83, FN27, FN83, LENGTH, IFLG )
    ...
    

See also Coordinate-coordinate conversion routines:


Previous: GCTP

Previous: LL2UTM and UTM2LL

Next: UNGRIDB

Up: MODULE MODGCTP

Up: Coordinate and Grid Related Routines

To: Models-3/EDSS I/O API: The Help Pages