This routine is obsolete and has been replaced by the ReprojectRaster task. See Convert Rasters From One Coordinate System to Another.

Use this procedure to convert a file from its current map projection to a specified output projection. This procedure requires an input file, the output projection, and the resampling and warping method; no ground control points are needed (they are generated internally). This procedure converts among many projections in ENVI Classic. Neither the input nor output projection can be Arbitrary.

Syntax

ENVI_CONVERT_FILE_MAP_PROJECTION [, BACKGROUND=integer] [, DEGREE=value], DIMS=array, FID=file ID [, GCP_NAME=string] [, GRID=array] [, O_PIXEL_SIZE=array], O_PROJ=structure [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable] [, RESAMPLING={0 | 1 | 2}] [, WARP_METHOD={0 | 1 | 2 | 3}] [, /ZERO_EDGE]

Keywords

BACKGROUND (optional)

Use this keyword to specify the output image background value. All pixels outside the warped-image boundary will be set to this value. The default is 0.

DEGREE (optional)

Use this keyword to specify the degree of the warping polynomial for the polynomial method. The degree of the polynomial is limited by the number of ground control points (GCPs). You must ensure that #GCPs > (DEGREE + 1)2. The default value is 1 (first-degree polynomial).

DIMS

The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).

  • DIMS[0]: Unused for this routine; set to -1L.
  • DIMS[1]: The starting sample number. The first x pixel is 0.
  • DIMS[2]: The ending sample number
  • DIMS[3]: The starting line number. The first y pixel is 0.
  • DIMS[4]: The ending line number

To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:

envi_file_query, fid, dims=dims

FID

The file ID (FID) is a long-integer scalar with a value greater than 0. An invalid FID has a value of -1. The FID is provided as a named variable by any routine used to open or select a file. Often, the FID is returned from the keyword R_FID in the ENVIRasterToFID routine. Files are processed by referring to their FIDs. If you work directly with the file in IDL, the FID is not equivalent to a logical unit number (LUN).

GCP_NAME (optional)

Use this optional string keyword to specify the output filename for the warp points. If WARP_METHOD=3, this keyword is ignored.

GRID (optional)

Use this keyword to specify a two-element array of long integers representing the grid spacing in pixels for the x and y warp points, respectively, used to convert between the two map projections. Regardless of the GRID value, a minimum of four corner points will be used. The default is to use every 10th point in both x and y. If WARP_METHOD=3, this keyword is ignored.

O_PIXEL_SIZE (optional)

Use this keyword to specify a two-element array of double-precision values representing the x and y pixel sizes, respectively.

O_PROJ

Use this keyword to specify the output projection for the converted file. You cannot set O_PROJ to the Arbitrary projection. O_PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.

OUT_BNAME (optional)

Use this keyword to specify a string array of output band names.

OUT_NAME

Use this keyword to specify a string with the output filename for the resulting data.

POS

Use this keyword to specify an array of band positions, indicating the band numbers on which to perform the operation. This keyword indicates the spectral subset of bands to use in processing. POS is an array of long integers, ranging from 0 to the number of bands minus 1. Specify bands starting with zero (Band 1=0, Band 2=1, etc.) For example, to process only Bands 3 and 4 of a multi-band file, POS=[2, 3].

POS is typically used with individual files. The example code below illustrates the use of POS for a single file with four bands of data:

  pos=[0,1,2,3]
                  
envi_doit, 'envi_stats_doit', dims=dims, fid=fid, pos=pos, $
                  
comp_flag=3, dmin=dmin, dmax=dmax, mean=mean, stdv=stdv, hist=hist

But what if you need to create an output file consisting of data from different bands, each from different files? Library routines such as CF_DOIT and ENVI_LAYER_STACKING_DOIT can accomplish this, but they use the POS keyword differently. Suppose you have four files, test1, test2, test3, and test4, with corresponding FIDs of fid1, fid2, fid3, and fid4, respectively. In the following example, you want Band 3 from test1 in the first position, Band 2 from test2 in the second position, Band 6 from test3 in the third position, and Band 4 from test4 in the fourth position. The code should be as follows:

  fid_array = [fid1,fid2,fid3,fid4]
                  
pos=[2,1,5,3]
                  
envi_doit, 'cf_doit', dims=dims, fid=fid_array
                  
out_name='test_composite_file'

R_FID (optional)

ENVI Classic library routines that result in new images also have an R_FID, or “returned FID.” This is simply a named variable containing the file ID to access the processed data. Specifying this keyword saves you the step of opening the new file from disk.

RESAMPLING (optional)

Set this keyword to one of the following values to specify the resampling method:

  • 0: Nearest neighbor
  • 1: Bilinear
  • 2: Cubic convolution

The default method is nearest neighbor.

WARP_METHOD (optional)

Set this keyword to one of the following values to specify the warp or rigorous projection method:

  • 0: Rotation, scaling, and translation (RST)
  • 1: Polynomial
  • 2: Triangulation
  • 3: Rigorous (pixel-by-pixel)

The default method is RST.

If WARP_METHOD=3, the GCP_NAME and GRID keywords are ignored.

ZERO_EDGE (optional)

Set this keyword to specify that the edges outside of any triangles are set to the value specified by BACKGROUND. The keyword is used only for triangulation (WARP_METHOD=2).

Example

The following example converts the file bhtmref.img from UTM zone 13 North to UTM zone 12 North.

Create the output UTM projection using ENVI_PROJ_CREATE, with UTM Zone 12 North, the default datum of North America 1927, and the default units of meters. Set the output pixel size to 28.5 meters for both x and y. Use the RST method with bilinear resampling for conversion.

forward_function ENVI_PROJ_CREATE
PRO EXAMPLE_ENVI_CONVERT_FILE_MAP_PROJECTION  
  compile_opt IDL2
  ;  
  ; First restore all the base save files.  
  ;  
  envi, /restore_base_save_files  
  ;  
  ; Initialize ENVI and send all errors  
  ; and warnings to the file batch.txt  
  ;
  envi_batch_init, log_file='batch.txt'  
  ;
  ; Open the input file  
  ;  
  envi_open_file, 'bhtmref.img', r_fid=fid  
  if (fid eq -1) then begin    
     envi_batch_exit    
     return  
  endif
  ;  
  ; Setup the values for the keywords
  ;  
  envi_file_query, fid, dims=dims, nb=nb
  pos  = lindgen(nb)  
  out_name = 'testimg'  
  o_proj = envi_proj_create(/utm, zone=12)  
  o_pixel_size = [28.5, 28.5]  
  ;  
  ; Call the doit  
  ;
  envi_convert_file_map_projection, fid=fid, $    
     pos=pos, dims=dims, o_proj=o_proj, $
     o_pixel_size=o_pixel_size, grid=[50,50], $    
     out_name=out_name, warp_method=0, $    
     resampling=1, background=0  
  ;  
  ; Exit ENVI  
  ;
  envi_batch_exit
END