Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.

  >  Docs Center  >  ENVI API  >  Map Information


Map Information

Map Information

This topic summarizes the routines and tasks that are available in the ENVI API for working with map information. Before proceeding, you should review the Coordinate Systems Background help topic to understand terms such as geographic coordinate system, projected coordinate system, and spatial reference.

See the following sections:

Coordinate Systems

Coordinate system parameters for vectors are stored in an ENVICoordSys object. If a vector file is georeferenced to a standard coordinate system, you can get the details of the coordinate system through its COORD_SYS property.

For rasters (images) and vectors, you can also create a new ENVICoordSys object by supplying a coordinate system code or string. See the Coordinate System Strings help topic for more information.

Rasters have a SPATIALREF property that contains the information needed to build an ENVICoordSys object, plus additional details.

The following examples create a coordinate system object that represents a UTM Zone 1N (WGS-84) projection:

ENVI> CoordSys = ENVICoordSys(COORD_SYS_CODE=32601)


ENVI> CoordSysString = 'PROJCS["WGS_1984_UTM_Zone_1N",GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]],PROJECTION["Transverse_Mercator"],PARAMETER["False_Easting",500000.0],PARAMETER["False_Northing",0.0],PARAMETER["Central_Meridian",-177.0],PARAMETER["Scale_Factor",0.9996],PARAMETER["Latitude_Of_Origin",0.0],UNIT["Meter",1.0]]'
ENVI> CoordSys = ENVICoordSys(COORD_SYS_STR=CoordSysString)

For a full list of coordinate system strings and codes, refer to the following text files in the \IDLxx\resource\pedata\predefined directory of the ENVI distribution:

  • EnviPEProjcsStrings.txt: PROJCS codes and strings
  • EnviPEGeogcsStrings.txt: GEOGCS codes and strings

Types of Map Information

This section summarizes the different types of map information that apply to rasters:

  • Standard spatial reference: This is the most common type of map information used for georeferencing rasters. A standard spatial reference consists of a coordinate system, pixel size, tie-point pixel coordinates, and map coordinates for that tie-point location. If a raster is georeferenced to a standard spatial reference, you can get the details of the spatial reference through its SPATIALREF property. Standard spatial reference information is stored in an ENVIStandardRasterSpatialRef object.
  • Rational polynomial coefficients (RPCs): These provide a mathematical model of the physical relationship between image coordinates and ground coordinates. An RPC-based image is not in a true map projection, but it still gives a reliable estimate of geographic locations for each pixel. RPC information is stored in an ENVIRPCRasterSpatialRef object. See Georeference Imagery Using RPCs below.
  • Pseudo: Pseudo map information refers to a non-standard projection that involves an affine map transformation. When an image is not georeferenced to a standard map projection and you only know the geographic coordinates and map projection of four points in the image, you can define these tie points in an ENVI header file or in the metadata of the raster object. ENVI will use these points to warp the image and to calculate geographic coordinates for each pixel. The pixel size varies in the rectified image. This type of projection contains a high degree of variability and is not geographically accurate; the (x,y) locations in the rectified image are only best guesses.
  • Pseudo map information is stored in an ENVIPseudoRasterSpatialRef object.

  • Geographic lookup tables (GLTs): Some data types provide Latitude and Longitude bands in addition to standard image products. These can be used to reference pixel locations to map coordinates. ENVI currently only supports NPP VIIRS when creating GLTs in the ENVI API. GLT information is stored in an ENVIGLTRasterSpatialRef object.

In rare cases, rasters may contain multiple sources of map information (for example, a standard map projection plus RPCs). In this case, ENVI has rules of precedence on what map information is applied to the raster:

  • Primary map information is stored in the SPATIALREF property of the ENVIRaster object, while secondary map information is stored in the AUXILIARY_SPATIALREF property.
  • If the raster only has one spatial reference, the AUXILIARY_SPATIALREF property returns a !NULL value.
  • If the raster contains standard map information plus RPC or pseudo information, the standard map information will be used as the primary spatial reference and the RPC or pseudo information will be the auxiliary spatial reference. RPC information will be written to the header file (for ENVI-format files) if you call ENVIRaster::WriteMetadata.
  • If the raster contains RPC and pseudo map information, the RPC information will be used as the primary spatial reference.

Georeference Imagery Using RPCs

Some sensors such as WorldView-2 and Cartosat-1 provide pre-computed RPCs that you can use to georeference the imagery. Use the ENVIRPCOrthorectificationTask routine to georeference imagery using RPCs in the ENVI API. For the most accurate results, you should supply a digital elevation model (DEM) and ground control points. See the following topics for more information:

Create a Georeferenced Layer Stack

A layer stack is a single raster that contains georeferenced bands from different source rasters. A layer stack ensures that all of the source rasters have the same dimensions, pixel sizes, and spatial reference, so they can be used for intercomparison and image processing. This is different from a band stack (also called a metaspectral raster), where the source rasters can have different pixel sizes and do not have to be georeferenced to a spatial grid.

Use ENVILayerStackRaster or ENVIBuildLayerStackTask to construct a layer-stacked raster. The source rasters can be band groups within a metaspectral dataset (such as Landsat, ASTER, or Sentinel-2); or they can come from different raster files.

Image-to-Map Registration

Use ENVI_REGISTER_DOIT to perform image-to-map registration. Use the PTS keyword, and specify the base points in map coordinates.

Create a Band Stack

Use ENVIMetaspectralRaster or ENVIBuildBandStackTask to create a band-stacked (or metaspectral) raster. A common use is to include bands from different rasters. Metaspectral rasters are similar to layer-stacked rasters, but the following rules apply:

  • The input rasters must have the same number of rows and columns.
  • The input rasters can have different pixel sizes.
  • The input rasters do not need to be georeferenced, but you can georeference the resulting metaspectral raster using the SPATIALREF keyword.
  • The input rasters can be of different interleave types, but the resulting metaspectral raster will be BSQ.
  • The input rasters can be of different data types, but the resulting metaspectral raster will be cast to the highest data type out of all the rasters.

Reproject Rasters

Use the following routines to reproject rasters to a different coordinate system.


The simplest option is to use ENVIReprojectRaster. This reprojects a raster in a standard spatial reference to any supported coordinate system that you specify. See the Example code for ENVIReprojectRaster.


Use the CreateGridFromCoordSys method to create a spatial grid raster with the same spatial extent as the source raster but in a different coordinate system. This is an advanced option for users who want to specify the details needed for georeferencing or reprojection, namely:

  • Coordinate system
  • Spatial (geographic) extent
  • Pixel (cell) size
  • Rows and columns

It preserves the spatial extent, rows, and columns from the original grid. The typical workflow is as follows:

  1. Query the SPATIALREF property of a raster to determine its current grid parameters: coordinate system, pixel size, rows, columns, tie-point pixel location, and tie-point map coordinates.
  2. Define an ENVICoordSys object based on the coordinate system that the raster will convert to.
  3. Create a spatial grid definition with these parameters.
  4. Invoke the CreateGridFromCoordSys method.
  5. Create a new spatial grid raster based on the grid definition.

The reprojected result is a virtual raster. To save the result to disk, use the ENVIRaster::Export method.

See the Example code for CreateGridFromCoordSys.


If you are writing a script that uses ENVITasks, use the following tasks to convert rasters from one coordinate system to another:

  • ENVIReprojectRasterTask: Reproject a raster in a standard spatial reference to any supported coordinate system that you specify. This is the simplest option.
  • ENVIRegridRasterTask: Regrid a raster to a spatial grid raster, which is a raster that has been reprojected and resampled to a grid with a standard spatial reference, predefined pixel size, and the same number of rows and columns. This task is similar to ENVIReprojectRasterTask, except that you must take additional steps to define a coordinate system object, create a spatial grid definition, and reproject the raster to the spatial grid.

Convert Between Different Coordinate Types

Different options are available to convert from one coordinate type to another:

  • Geographic (longitude/latitude)
  • Map (eastings/northings)
  • Military Grid Reference System (MGRS)

ENVICoordSys Methods

Conversion methods are provided as a convenience when working with one particular coordinate system:

Here is a common use case: Suppose that you have an image that is a UTM projection, with coordinates in eastings and northings (in meters). You want to define a spatial subset based on known latitude and longitude coordinates (in degrees). Because the spatial reference of the source image uses map coordinates, then the SUB_RECT value must also use map coordinates. You can use the ConvertLonLatToMap method to convert the geographic coordinates to map coordinates as follows. Be sure to arrange the minimum and maximum x,y values in the correct order.

Raster = e.OpenRaster(File)
; This is the area of interest:
UpperLeftLat = 35.1
UpperLeftLon = -112.1
LowerRightLat = 34.7
LowerRightLon = -111.6
; Get the spatial reference of the raster
SpatialRef = Raster.SPATIALREF
; Convert from Lon/Lat to MapX/MayY
SpatialRef.ConvertLonLatToMap, UpperLeftLon, UpperLeftLat, $
  MapX, MapY
SpatialRef.ConvertLonLatToMap, LowerRightLon, LowerRightLat, $
  MapX2, MapY2
; Define the geographic subset
Subset = Raster.Subset(SPATIALREF=SpatialRef, $
  SUB_RECT=[MapX, MapY2, MapX2, MapY])

Other methods convert a set of values in one coordinate system to the same geographic location in another coordinate system:

ENVIRasterSpatialRef Methods

These same coordinate conversion methods are available with the following types of map objects:

ENVIGridDefinition Methods

Two conversion methods are available when creating a spatial grid definition, which contains a coordinate system plus a geographic (spatial) extent, pixel size, and number of rows and columns.

Coordinate Conversion Tasks

Use the following ENVITasks when writing an image-processing script that uses other ENVITasks, or when writing client applications using ENVI Services Engine (ESE):

© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us