Working with Map Information in the ENVI API

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

See the following sections:

Coordinate Systems

The coordinate system string field in an ENVI header file lists the coordinate system of a georeferened image; for example:

coordinate system string = {PROJCS["NAD_1983_StatePlane_Kentucky_North_FIPS_1601_Feet",GEOGCS["GCS_North_American_1983",DATUM["D_North_American_

etc...}

Coordinate system parameters for vectors are stored in an ENVICoordSys object in the ENVI API. 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 and vectors, you can also create a new ENVICoordSys object by supplying a coordinate system code or string. See Coordinate System Strings and Codes 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)

Or,

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:

Spatial References

The map info field in an ENVI header file provides the details of a spatial reference associated with a raster. It also includes information about the coordinate system; for example::

map info = {State Plane (NAD 83), 1.0000, 1.0000, 1539909.1830, 542497.7997, 2.0000000000e+000, 2.0000000000e+000, 1601, units=US Survey Feet}

 

coordinate system string = {PROJCS["NAD_1983_StatePlane_Kentucky_North_FIPS_1601_Feet",GEOGCS["GCS_North_American_1983",DATUM["D_North_American_

etc...}

In this example, 1.0000 and 1.0000 are the tie-point loations (the pixel coordinates of the upper-left pixel). The values 1539909.1830 and 542497.7997 are the X (easting) and Y (northing) map coordinates, respectively. The values 2.0e+000 are the X and Y pixel sizes. The coordinate system string line that follows provides the details on the coordinate system for this image.

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.

RPC information is stored in an ENVIRPCRasterSpatialRef object. See Georeference Imagery Using RPCs below.

Pseudo map information is stored in an ENVIPseudoRasterSpatialRef object.

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:

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 RPCOrthorectification task 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:

Georeference Imagery Using GLTs

ENVI currently only supports NPP VIIRS when creating GLTs in the ENVI API.

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. Use ENVILayerStackRaster or the BuildLayerStack task 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.

Create a Band Stack

A band stack (also called metaspectral raster) is a single raster that contains bands from different source rasters. As with layer stacks, the input rasters can have different pixel sizes but they do not have to be georeferenced. The following additional rules apply:

Use ENVIMetaspectralRaster or the BuildBandStack task to create a band-stacked raster.

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.

Reproject Rasters

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

ENVIReprojectRaster

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.

ENVIGridDefinition::CreateGridFromCoordSys

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:

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.

ENVITasks

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

Convert Between Different Coordinate Types

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

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 tasks to convert between coordinates: