INTERNAL: Introduction to the ESRI Projection Engine for ENVI users

In ENVI 4.7 and later versions, all calculations involving map projections in ENVI are handled using the powerful ESRI Projection Engine. This is true for all ENVI products, including ENVI, ENVI+IDL, ENVI Classic, ENVI Zoom and ENVI EX. Previous versions of ENVI used the General Cartographic Transformation Package (GCTP). While much of ENVI's map projection functionality is similar before and after this change, the switch results in some differences. This help article provides an overview of those differences, and some basic information about working with projections in ENVI using the ESRI Projection Engine syntax.

Another help article that may be helpful is:

• How to use a projection type that the ESRI Projection Engine supports, but ENVI does not.

Also, the help article:

• ESRI Projection Engine Reference

. . . provides information about and links to files used by the ESRI Projection Engine.

Projection Functionality That Is the Same Before and After ENVI 4.7:

• All previously available ENVI menu items related to map projections remain available and work the same way as before for supported projection types.
• All ENVI programming routines related to map projections (ENVI_PROJ_CREATE, ENVI_MAP_INFO_CREATE, ENVI_GET_PROJECTION, ENVI_CONVERT_FILE_MAP_PROJECTION, and ENVI_ADD_PROJECTION) are still available. They work exactly as before for supported projection types. ENVI_PROJ_CREATE and ENVI_MAP_INFO_CREATE have additional keywords that can be used to work with projection types supported by the ESRI projection engine, but not by ENVI.
• The following projection types and datums continue to be fully supported in ENVI:
  
  Projection Types
  
  Albers Conical Equal Area
  Arbitary
  Azimuthal Equadistant
  Equidistant Conic A (one std parallel)
  Equidistant Conic B (two std parallels)
  Equirectangular
  General Vertical Nearside Perspective
  Geographic
  Gnomonic
  Hammer
  Hotine Oblique Mercator B
  Lambert Azimuthal Equal Area
  Lambert Azimuthal Equal Area (sphere)
  Lambert Conformal Conic
  Mercator
  Miller Cylindrical
  Mollweide
  New Zealand Map Grid
  Orthographic
  Polar Stereographic (north pole/south pole)
  Polyconic
  Rectified Skew Orthomorphic (RSO)
  Robinson
  Sinusoidal
  State Plane
  Stereographic (ellipsoid)
  Stereographic (sphere)
  Transverse Mercator
  UTM (specific case: Transverse Mercator)
  Van der Grinten

  Datums

  Adindan
  Ain El Abd 1970
  Alaska (NAD-27)
  Anna 1 Astro 1965
  ARC-1950 mean
  ARC-1960 mean
  Ascension Island '58
  Astronomic Stn. '52
  Australian Geodetic 1966
  Australian Geodetic 1984
  Geocentric Datum of Australia 1994
  Bellevue (IGN)
  Bermuda 1957
  Bogota Observatory
  Bukit Rimpah
  Camp Area Astro
  Campo Inchauspe
  Canton Island 1966
  Cape
  Cape Canaveral mean
  Carthage
  Chatham 1971
  Chua Astro
  Corrego Alegre
  Corrego Alegre (Provisional)
  Cuba (NAD27)
  Cyprus
  Djakarta(Batavia)
  DOS 1968
  Easter Island 1967
  European 1950
  European 1950 mean
  European 1979 mean
  EGSA87
  Greenland (NAD27)
  Guam 1963
  Gunung Segara
  GUX 1 Astro
  Herat North
  Hjorsey 1955
  Hong Kong 1963
  Hu-Tzu-Shan
  Indian
  ISTS 073 Astro '69
  Johnston Island '61
  Kandawala
  Kerguelen Island
  Kertau '48
  La Reunion
  Liberia 1964
  Luzon
  Mahe 1971
  Massawa
  Merchich
  Midway Astro '61
  Minna
  Nahrwan
  Naparima BWI
  North America 1983
  North America 1927
  Nouvelle Triangulation Francaise IGN
  Observatorio 1966
  Old Hawaiian mean
  Old Hawaiian Hawaii
  Old Hawaiian Kauai
  Old Hawaiian Maui
  Old Hawaiian Oahu
  Oman
  Ordnance Survey of Great Britain '36
  Pico De Las Nieves
  Pitcairn Astro '67
  Provisional South American 1956 mean
  Puerto Rico
  Qornoq
  Qatar National
  Reseau Geodesique Francaise
  Rome 1940
  SAD-69/Brazil
  Santo (DOS)
  Sapper Hill '43
  Sierra Leone 1960
  South American 1969 mean
  South Asia
  Tananarive Observatory '25
  Timbalai 1948
  Tokyo mean
  Tristan Astro 1968
  Viti Levu 1916
  Wake-Eniwetok '60
  WGS-72
  WGS-84
  Yacare
  Zanderij
• If you wish to add a projection type to ENVI that is not supported by the ESRI Projection Engine, you can do so by adding IDL code for the forward and reverse transform equations to ENVI's save_add directory, and adding a reference to that code in ENVI's useradd.txt file. This is the same way that unsupported projection types were added to ENVI in previous versions.

Projection Functionality That Changed as of ENVI 4.7:

• Several projection types that ENVI previously supported are not supported by the ESRI Projection Engine, and so are no longer supported in ENVI 4.7 and later versions. Those projection types are:
  
  Alaska Conformal
  Hotine Oblique Mercator A
  Integerized Sinusoidal
  Interrupted Goode
  Interrupted Mollweide
  Oblated Equal Area
  Oblique Conformal Conic
  Space Oblique Mercator A (generic, landsat 1,2,3,4)
  Space Oblique Mercator B (landsat 5, 7)
  Wagner VII
• If you try to read an image that uses one of the projection types that is no longer supported, ENVI will read the image without error, but the map projection associated with the image will be a map-based arbitrary projection. This is true when reading the image via the ENVI interface, or programmatically. The map projection will be listed as  "Arbitrary (Map Based)".
• The ESRI Projection Engine supports over 70 projection types and 680 datums, many of which have never been supported by ENVI. While ENVI still does not provide direct support for those projection types (i.e., you cannot select a projection with one of those types from ENVI tools), ENVI does now provide some support for those projection types:
  
  • ENVI will read and use the projection information for those projection types under certain circumstances: a) when raster or vector data is being read into ENVI from an ESRI geodatabase, and b) when an image is being read into ENVI from an ENVI format file that contains the new coordinate system string in its header. In those cases, the projection information will be correctly interpreted by ENVI, and inherited by new datasets created during the processing of that data. For example, if you use an image in one of those projection types during Layer Stacking, ENVI will allow that projection as one of the options for the output map projection of the stack of images.
  • It is possible to programmatically put an image into one of those projection types, using the previously available ENVI Classic projection routines, such as ENVI_PROJ_CREATE, and ENVI_CONVERT_FILE_MAP_PROJECTION or ENVI_MAP_INFO_CREATE and ENVI_SETUP_HEAD.
  • It is possible to programmatically perform a datum shift from a previously supported datum to a datum that is supported by the ESRI Projection Engine using the same method outlined above for putting the image into a projection supported by the ESRI Projection Engine.

How to interpret the new coordinate system strings

Georeferenced raster data in ENVI 4.7 and later versions contains geographic information in a new field in the ENVI header. For datasets in Geographic Lat/Long, the new field will be a "Geographic Coordinate System" (GCS) string. For datasets in an actual projection, the geographic information is contained in a "Projected Coordinate System" (PCS) string, which includes a GCS string. 

In addition to the new GCS and PCS strings, ENVI also includes map information in the old "map_info" and/or "projection" header items, to allow compatibility with older versions of ENVI.

The format of the information in the new GCS and PCS strings is that required by the ESRI Projection Engine. You can see the values for predefined GCS strings listed in EnviPEGeogcs.txt, under the heading "Strings". There are over 700 predefined GCS strings. These strings list the coordinate system name, datum, spheroid, prime meridian, and units.

You can see the values for predefined PCS strings listed in EnviPEProjcsString.txt. There are over 3000 predefined PCS strings. These strings contain a projection number, the word PROJCS, and list all of the geographic coordinate system parameters (i.e., a complete GCS string), plus detailed parameters that describe the projected coordinate system.

For more information about how geographic information is stored in ENVI image headers, see the ENVI documentation for "The ENVI Header Format."

How to create a Log for projection problems

The ESRI Projection Engine has a method for logging information about projection problems that can be used to help Exelis VIS Technical Support track down problems you encounter with projections. To create such a log, use the following steps:

1. In a text editor, open the pelog.txt file that you will find in the pedata subdirectory under your IDL resource directory. For example, with a typical Windows installation of ENVI 5.0, you would find the pelog.txt file at C:\Program Files\Exelis\IDL82\resource\pedata\pelog.txt.
2. Change the last line of this file from:
   
   
   0000,0000,0000,0000

   To

   1111,1100,0011,1110
3. Save the changes to the pelog.txt file.

This change will result in ENVI writing a variety of information to a map_pe_1.log file in C:\Program Files\Exelis\IDL84\resource\pedata\logs (for a typical Windows installation of ENVI 5.2) when performing tasks that use the ESRI Projection Engine. If you run into problems while working with map projections in ENVI, this log file may provide useful information about the nature of the problem. When working with Exelis VIS Technical Support on projection problems in ENVI, we may request that you enable this logging, and send in the resulting *.log file.

Reviewed 10/15/14 by PS