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


  >  Docs Center  >  ENVI API  >  Data Control  >  ENVIURLRaster

ENVIURLRaster

ENVIURLRaster

This function creates a new ENVIRaster from a file or uniform resource indicator (URI).

Syntax


Result = ENVIURLRaster(URI [, Keywords=value])

Return Value


This method returns a reference to an ENVIRaster.

Arguments


URI

For local datasets, specify a scalar string that is a fully-qualified file path to a raster on disk.

For remote datasets, specify a string with the direct URL of the dataset. This option is the same as the Open Remote Dataset dialog in the ENVI interface. You can connect directly to a geodatabase, IAS, JPIP, or OGC server, or to an Esri® Image Service. If you connect to a remote dataset that requires authentication, you must set the USERNAME and PASSWORD keywords. Or, optionally set the /PROMPT_USER keyword to enter the user name and password.

Keywords


Keywords are applied only during the initial creation of the object.

DATA_IGNORE_VALUE

Set this keyword to a pixel value that will be ignored when the raster is displayed. This overrides any data ignore values set in the metadata.

DATASET_INDEX

This keyword applies to file formats with multiple datasets per file such as ECRG, HDF5, Multi-page TIFF, NetCDF-4, NITF with multiple image segments, Proba-V, and SkySat-1. Specify a zero-based index number that corresponds to a specific raster dataset that you want to open within the file. For example, DATASET_INDEX=0 will open the first raster.

You cannot set this keyword in conjunction with the TEMPLATE keyword.

  • Multi-page TIFF: Specify an index number with the specific page to open. For example, DATASET_INDEX=5 will open the sixth page.
  • NITF: For files with multiple image segments, specify an index number corresponding to an individual image segment. DATASET_INDEX=0 will open the first image segment.
  • Proba-V with radiometry:
    • DATASET_INDEX=0: VNIR band
    • DATASET_INDEX=1: SWIR band
    • DATASET_INDEX=2: NDVI band
    • DATASET_INDEX=3: Quality band
  • Proba-V without radiometry:
    • DATASET_INDEX=0: NDVI band
    • DATASET_INDEX=1: Quality band

DATASET_NAME

This keyword applies to file formats with multiple datasets per file such as ECRG, HDF4, HDF5, Multi-page TIFF, NetCDF-4, Proba-V, and SkySat-1. For NITF files with multiple image segments, use the DATASET_INDEX keyword instead.

Set this keyword to a string with the name of a raster dataset that you want to open within the file. Strings are case-sensitive.

If you do not know the dataset names, use the Dataset Browser to open the files and obtain the names.

You cannot set this keyword in conjunction with the TEMPLATE keyword.

HDF5 example

For HDF5 files, you can use the IDL H5_LIST routine to list the dataset names. This example uses an HDF5 file included in the ENVI+IDL installation. Set xx to the correct version of IDL:

File = 'C:\Program Files\Harris\IDLxx\examples\data\hdf5_test.h5' 
H5_LIST, File

IDL prints:

% Loaded DLM: HDF5.
file        C:\Program Files\Harris\IDLxx\examples\data\hdf5_test.h5
dataset/2D int array                                                          H5T_INTEGER [50, 100]
dataset          /A note H5T_STRING [2]
group              /arrays
dataset          /arrays/2D float array H5T_FLOAT [50, 100]
dataset          /arrays/2D int array H5T_INTEGER [50, 100]
...
etc.

Then enter the following command:

Raster = e.OpenRaster(File, DATASET_NAME='/arrays/2D float array')

SkySat-1 example

Set the URI argument to a metadata file. Valid strings for DATASET_NAME include Panchromatic, Multispectral, or Pan Sharpened.

File = 'C:\Data\s01_20140315T161938Z\s01_20140315T161938Z_metadata.txt'
Raster = e.OpenRaster(File, DATASET_NAME='Panchromatic')

SkySat rasters open in their native spatial reference (typically RPC). They do not reproject as they would in the ENVI user interface.

Proba-V S10 example

Valid strings include VNIR, SWIR, NDVI, and Quality.

File = 'PROBAV_S10_TOC_X19Y03_20131121_333M_V001.h5'
Raster = e.OpenRaster(file, DATASET_NAME='NDVI')

ERROR

Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''). If an error occurs and the routine is a function, then the function result will be undefined.

When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.

See Manage Errors for more information on error handling in ENVI programming.

FORMAT

Use this keyword to identify the format of the raster. If it is a known native format, then this keyword will be ignored. If it is a known external format, then the raster will open according to that format. All other values for this keyword are handled using the value as a custom open procedure.

The native formats are: bmp, envi, esri_grid, imagine, jp2, jpeg, kompsat2, landsat_metadata, mrsid, nitf, qb_tile, rapideye, tiff, tfrd, and wv_tile.

The known external formats are in this table:

File Type String Description
acres

Australian Centre for Remote Sensing (ACRES) Canadian Centre for Remote Sensing (CCRS) Landsat and SPOT data

ads40 

Airborne Digital Sensor developed by Leica Geosystems

alos

Advanced Land Observing Satellite

arcview

ArcView® raster format files that have the .bil file extension and an associated header file with the .hdr extension. ENVI extracts the header information, including the UTM and State Plane projection georeferencing information.

atsr

Gridded Brightness Temperature (GBT), Gridded Browse (GBROWSE), and Gridded SST (GSST) data from ATSR-1 and ATSR-2

avhrr

Advanced Very High Resolution Radiometer (AVHRR)

avhrr_sharp

European Space Agency SHARP data

cadrg

Compressed ARC Digitized Raster Graphics (CADRG) format

cib

Controlled Image Base (CIB) format

cosmo-skymed

COSMO-SkyMed radar format

dmc

ENVI reads and displays data from the UK-DMCSat-1, ALSAT-1, and NigeriaSat-1 satellites that are part of the DMC (Disaster Monitoring Constellation).

dmsp_noaa 

NOAA Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS) format

ecw

Enhanced Compressed Wavelet

envisat

Environmental Satellite (Envisat)

eo1_hdf

EO-1 ALI or Hyperion data in HDF format

eos_aster

Earth Observing System (EOS) Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER) data

eos_modis 

EOS Moderate Resolution Imaging Spectroradiometer (MODIS) data

er_mapper 

ER mapper format

erdas_lan

ERDAS file (*.lan)

eros_l1a

Earth Resources Observation System 1A data

eros_l1b

ImageSat International EROS A Level 1B files

ers

European Remote Sensing Satellite-1 or -2

formosat-2

FORMOSAT-2 DIMAP (.dim) data

irs_fast 

Indian Remote Sensing (IRS) data in Earth Observation Satellite Company (EOSAT) Fast format

irs_super_structured

IRS Super Structured data

jers 

Japanese Earth Resources Satellite

landsat_ceos

European Space Agency CEOS Landsat TM data

landsat_fast

Landsat TM data in EOSAT Fast format

landsat_hdf

Landsat data in Hierarchical Data Format (HDF)

landsat_mrlc

Multi-Resolution Land Characteristic format for Landsat TM and DEM data

landsat_nlaps

National Landsat Archive Production System (NLAPS) format for Landsat TM and MSS data

master

MODIS/ASTER Simulator (MASTER) MAS-50 HDF data

pci

PCI Geomatics format (.pix)

pds

Planetary Data System format

pict

QuickDraw Picture

png

Portable Network Graphics

radarsat

Canadian Radar Satellite data

seawifs

SeaWiFS data

sicd

Sensor Independent Complex Data (NITF format)

spot_cap_sisa 

SPOT 1A, 2A, and 1B data

spot_geospot 

Reads the primary format for SPOT data. ArcView® raster image files have a similar format specification. The GeoSPOT format is described in detail in documentation available from SPOT Image.

spot_vegetation 

SPOT vegetation data

srf
Spectral Response Function. Engineering data that quantify the spectral response and sensitivity of detectors on an airborne or satellite sensor. The term SRF also refers to a data format that contains SRF data for particular sensors.
tims 

Thermal Infrared Multispectral Scanner data

topsar

Raw AIRSAR Integrated Processor Data format (Cvv, incidence angle, correlation image, or DEM)

usgs_doq 

USGS Digital Orthophoto Quadrangle data

usgs_native_dem 

USGS Digital Elevation Model data

usgs_sdts_dem

USGS Spatial Data Transfer Standard

xwd

X Window Dump

INTERLEAVE

This keyword only applies to three-dimensional datasets and specifies the interleave of the dataset when an interleave is not specifically defined in the file (as with HDF5 datasets). Set this keyword to one of the following strings:

String Interleave Data Array
bil Band interleaved by line [ncolumns, nbands, nrows]
bip Band interleaved by pixel [nbands, ncolumns, nrows]
bsq Band sequential [ncolumns, nrows, nbands]

This keyword is optional and the default value 'bsq' is used if it is not set. You can only set this keyword if you also set DATASET_NAME.

METADATA_OVERRIDE

Set this keyword to an ENVIRasterMetadata object. The metadata information for the newly created ENVIRaster will be taken from both the specified object and the ENVIRaster on disk (specified with URI).

If the ENVIRasterMetadata object specified by this keyword and the ENVIRaster specified by URI both have the same tag, the tag information from the ENVIRasterMetadata object will take precedence. Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.

If the ENVIRasterMetadata object contains the string 'read procedures,' then the ENVIRaster is opened using a custom read routine.

The DATA_IGNORE_VALUE keyword takes precedence over the METADATA_OVERRIDE keyword.

For NPP VIIRS files, only the I, M, DNB, or NCC bands (rasters) can be overridden. Metadata override is not allowed for the Latitude, Longitude, Height, or Quality bands.

PASSWORD

Set this keyword to a string with a valid password for opening a remote dataset that requires authentication.

PROMPT_USER

Set this keyword in an interactive session (not for use with batch mode) if you want ENVI to prompt you for certain input parameters instead of performing default actions.

If you set the PROMPT_USER keyword and open an NPP VIIRS dataset, the NPP VIIRS Parameters dialog will appear for you to select calibration options. If you do not set this keyword and you open an NPP VIIRS dataset, the dataset will be calibrated to radiance, by default.

SPATIALREF_OVERRIDE

Set this keyword to an ENVIPseudoRasterSpatialRef, ENVIRPCRasterSpatialRef, or ENVIStandardRasterSpatialRef object. The spatial reference information for the newly created ENVIRaster will be taken from the specified object and not from the associated raster data file. Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.

If the ENVIRaster contains a combination of standard and auxiliary (RPCs or pseudo) map information, and you set SPATIALREF_OVERRIDE to an ENVIStandardRasterSpatialRef object, the original auxiliary map information will be lost.

TEMPLATE

Set this keyword to a string with the name of a custom XML template used to open NetCDF-4, HDF4, HDF-EOS, or HDF5 datasets. Creating and restoring templates can be helpful when you want to build the same raster and metadata structure from several source files. Setting this keyword assumes that you previously created a template manually or by using the Dataset Browser. See Work with Templates for more information.

You cannot set this keyword when setting DATASET_INDEX or DATASET_NAME.

TIME_OVERRIDE

Set this keyword to an ENVITime object. The time information for the newly created ENVIRaster will be taken from the specified object and not from the associated raster data file. Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.

USERNAME

Set this keyword to a string with a valid user name for opening a remote dataset that requires authentication.

UVALUE

Use this keyword only the FORMAT keyword is not a known native or external file type. The value set with this keyword will be passed into the custom open procedure's UVALUE keyword. If the custom open procedure does not accept the UVALUE keyword, then it will be ignored.

Dehydrated Form


Key

Description

factory

Required. A string value of URLRaster indicating what object type the hash represents.

auxiliary_url A string array containing the URLs for any auxiliary files associated with the raster file. This key is generated on output if auxiliary files exist. On input this key is ignored to allow ENVIURLRaster to override various behaviors.

data_ignore_value

A scalar numeric value that masks out any pixels matching the value. Example:

"data_ignore_value" : -9999

dataset_index

A scalar integer value that is the zero-based index of the raster to load from a container format consisting of multiple rasters. Example:

"dataset_index" : 1

dataset_name

A case-sensitive scalar string that identifies which raster to load from a container format consisting of multiple rasters. Example:

"dataset_name""cirrus"

format

A scalar string that specifies the format of the raster. Known native values will be ignored, known external formats will force the loading of the raster according to the given format, and unknown formats will be treated as the name of the custom read procedure. Example:

"format" : "alos"

interleave

A case-insensitive string used in conjuction with dataset_name to indicate how to interpret 3D pixel arrays. Specify bsq, bil, or bip. If not specified, then bsq is the default. Example:

  "interleave" : "bip"

metadata_override

The hash representation of an ENVIRasterMetadata object. Example:

"metadata_override" : {
   "factory": "RasterMetadata",
   "WAVELENGTH": [485.00000000000000, 
      560.00000000000000, 660.00000000000000,
      830.00000000000000],
   "WAVELENGTH UNITS": "Nanometers",
   "SENSOR TYPE": "QuickBird",
   "BAND NAMES": ["Band 1", "Band 2", "Band 3", "Band 4"]
}

password

A scalar string to use when opening a remote dataset that requires authentication. For security reasons, this is not included in the hash returned from the Dehydrate method, but you can manually add it before the hash is passed into ENVIHydrate.

prompt_user

A Boolean value that instructs the system to prompt the user with interactive dialogs when opening the raster. This is not included in the hash returned from the Dehydrate method since it is not compatible with batch-mode processing, but you can manually add it before the hash is passed into ENVIHydrate.

spatialref_override

The hash representation of a spatial reference of type ENVIStandardRasterSpatialRef, ENVIPseudoRasterSpatialRef or ENVIRPCRasterSpatialRef. Example:

"spatialref_override" : {
   "factory": "StandardRasterSpatialRef",
   "rotation": 0.00000000,
   "tie_point_pixel": [0.00000000, 0.00000000],
   "coord_sys_code": 32611,
   "pixel_size": [30.000000, 30.000000],
   "tie_point_map": [493785.00, 4899315.0]
}

template

Scalar string with the name of a custom XML file to use when opening a HDF5 file. Example:

"template" : "/mydata/my_template.xml"

time_override

The hash representation of an ENVITime object. Example:

"time_override" : {
   "acquisition": "2015-10-30T16:05:32.3258314Z",
   "factory": "Time"
}

url

Required. A scalar string with the local filename or URI to a remote data source. Example:

"url" : "/usr/local/harris/envi/data/qb_boulder_msi"

username

A scalar string to use when opening a remote dataset that requires authentication. For security reasons, this is not included in the hash returned from the Dehydrate method, but you can manually add it before the hash is passed into ENVIHydrate.

uvalue

Any data type is allowed. This key is used when format is not a known native or external type but specifies a custom read procedure. The uvalue is passed into that procedure's UVALUE keyword, if it exists. Example:

"uvalue" : 3.14159

Version History


ENVI 5.3, Service Pack 1

Introduced

ENVI 5.3, Service Pack 2 Added auxiliary_url key to dehydrated form

API Version


3.3

See Also


ENVI function, ENVI::GetView, ENVIView::CreateLayer, ENVIRaster



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