ENVITask: The New ENVI 5.1 Analytics API
Anonym
ENVI 5.1 introduced a new ENVITask API for processing your data. We developed this new API with the information on how to use it built into the API and validation as you go. The first step is to query the system to learn what ENVITasks are available for you to use. This is available as the new TASK_NAMES property on the ENVI object:
IDL> nv = ENVI()
ENVI> PRINT, nv.TASK_NAMES
QUAC RPCOrthorectification RadiometricCalibration ReprojectGLT
Once you have the task name you want, you create it using the new enviTask() function.
ENVI> oTask = ENVITask('RadiometricCalibration')
ENVI> help, oTask
oTASK ENVIRADIOMETRICCALIBRATIONTASK <196531>
Now that you have the task, you might be wondering how to use it. You can programmatically get information about individual parameters. You can get the list of parameters from the ParameterNames() function ,and can get a reference to one of the ENVITaskParameter objects by passing its name into the Parameter() function:
ENVI> print, oTask.ParameterNames()
CALIBRATION_TYPE INPUT_RASTEROUTPUT_DATA_TYPE OUTPUT_RASTER OUTPUT_RASTER_URI SCALE_FACTOR
ENVI> oParam = oTask.Parameter('input_raster')
ENVI> print, oParam
ENVITASKPARAMETER <196676>
CHOICE_LIST = !NULL
DEFAULT = !NULL
DESCRIPTION ='Specify an ENVIRaster object on which to perform radiometric calibration'
DIRECTION = 'IN'
NAME ='INPUT_RASTER'
REQUIRED = 1
TYPE ='ENVIRASTER'
VALUE = !NULL
As you can see from the print output, we give you all the information you need to construct a variable to pass in as each parameter’svalue. Aside from the parameter’s name, you get a human readable description of it, plus its IDL type, whether it is aninput or output parameter, if it’s required or optional, and its current value. Some parameters will have a default value already set for you, and some will have defined an array of allowed values in the CHOICE_LIST property. If you print on the ENVITask, you’ll get output like the above about all the parameters it owns. You don’t have to request each parameter by name to get or set its VALUE property, you can retrieve or set the values:
ENVI> print, oTask.Scale_Factor
1.0000000000000000
ENVI> oTask.Scale_Factor= 3.0
Each time you set a parameter value, it is validated. Any values that can’t be converted to the required type or don’t match the CHOICE_LIST, if it’s defined, will give you immediate feedback so you can fix them now instead of waiting for their use halfway through a lengthy calculation. Once you’ve set all your input parameters, you call the ENVITask::Execute method to run the algorithm. Here is an example that loads a user selected raster and calibrates it to a percent reflectivity, and then loads the resulting output in a raster layer:
; load the raster
nv = ENVI()
inputFile = Dialog_Pickfile(TITLE='Select a file to calibrate')
oRaster = nv.OpenRaster(inputFile)
; load the enviTask
oTask = enviTask('RadiometricCalibration')
; Set parameters
oTask.INPUT_RASTER = oRaster
oTask.CALIBRATION_TYPE = 1 ; TOA Reflectance
oTask.SCALE_FACTOR = 100
oTask.OUTPUT_DATA_TYPE = 12 ; UInt
; run the task
oTask.Execute
; load output into layer
oView = nv.GetView()
oLayer = oView.CreateLayer(oTask.Output_Raster)
This example is a little contrived, but shows how you can easily use ENVITasks for bulk batch processing of entire collections ofdata. You don’t have to open each raster in ENVI and use the Radiometric Calibration toolbox item UI anymore, you can use FILE_SEARCH and do a FOR loop over each file in a given directory. One thing to note is that this example did not use the OUTPUT_RASTER_URI parameter at all. The ENVITasks are defined using a convention where each ENVIRaster output parameter is coupled with an input parameter, which has the same name with ‘_URI’ appended. This allows the user of the task to specify the output location and filename they want, if they want to keep the output raster. If the input URIparameter is not defined, then ENVITask will generate a temporary file. Furthermore, it will delete the temporary file when ENVI shuts down. This way if you want to chain multiple ENVITasks together you don’t have to worry about cleaning up intermediate products.
In ENVI 5.1 we released just a few ENVITasks, however look for many more ENVITasks in future releases.