ENVI ® Py Engine¶
ENVI Py Engine provides a client Python package, named envipyengine, to run ENVI analytics provided by ENVI Desktop. The Python package provides the ability to query for available tasks, retrieve task information, and execute tasks on the desktop.
There is an additional client Python package available, named envipyarc, to provide the ability to run ENVI analytics through ArcMap and ArcGIS Pro.
See http://www.harrisgeospatial.com/ for more details on product offerings.
Usage¶
Before using ENVI Py Engine, you must first configure the package so it can find your Engine executable within your ENVI/IDL installation. To do this make sure the “engine” config option is set:
>>> import envipyengine
>>> engine = envipyengine.config.get('engine')
If the above command throws an error, then you will need to set the ‘engine’ property to the the full path of the ‘taskengine’ executable in your ENVI installation:
>>> envipyengine.config.set('engine', <path-to-executable>)
When specifying paths in Python strings on Windows, be sure to use two backslashes as your directory separator.
To connect to the ENVI Task Engine and list the available tasks, create a new instance of the Engine class with the engine name from the Python command line:
>>> from envipyengine import Engine
>>> envi_engine = Engine('ENVI')
>>> envi_engine.tasks()
You must have write permissions for Python’s current working directory in order to run the examples.
To get an ENVI task object, use the task()
method on the Engine object:
>>> task = envi_engine.task('SpectralIndex')
To get a list of task parameter information, use the parameters
property on the Task object:
>>> task.parameters
To execute a task, use the execute()
method on the Task object. A GSF Job object is returned after the job has been submitted:
>>> input_raster = dict(url='<path_to_input_raster>', factory='URLRaster')
>>> parameters = dict(INPUT_RASTER=input_raster,
INDEX='Normalized Difference Vegetation Index')
>>> task.execute(parameters)
API Documentation¶
ENVI Py Engine¶
The ENVI Py Engine object selects a task engine to use with ENVI Py
-
class
envipyengine.engine.
Engine
(engine_name, cwd=None)[source]¶ The ENVI Py Engine Class.
Example: Import the module for the example
>>> from envipyengine import Engine >>> from pprint import pprint
Create an ENVI Engine and print a list of available tasks.
>>> envi_engine = Engine('ENVI') >>> tasks = envi_engine.tasks() >>> pprint(tasks) ['AdditiveLeeAdaptiveFilter', 'AdditiveMultiplicativeLeeAdaptiveFilter', 'ApplyGainOffset', ...
-
name
¶ Returns the name of the task engine associated with the Engine.
Returns: The task engine name (i.e. ENVI, IDL, etc.)
-
ENVI Py Engine Task¶
The ENVI Py Engine task object provides task information and can submit a job to the Task Engine with input.
-
class
envipyengine.task.
Task
(uri=None, cwd=None)[source]¶ The ENVI Py Engine Task object represents a Task Engine task and its parameters.
Example: Import the modules for the example.
>>> from envipyengine import Engine >>> from pprint import pprint
Create an Engine object for ENVI and get a task
>>> envi_engine = Engine('ENVI') >>> task = envi_engine.task('SpectralIndex')
Investigate task information.
>>> print(task.name) 'SpectralIndex' >>> print(task.description, type(task.description)) ('This task creates a spectral index raster from one pre-defined spectral index. Spectral indices are combinations of surface reflectance at two or more wavelengths that indicate relative abundance of features of interest.', <type 'str'>) >>> print(task.display_name, type(task.display_name)) ('Spectral Index', <type 'str'>) >>> task_parameters = task.parameters >>> pprint(task_parameters)
Execute a job using the Task Engine
>>> input_raster = dict(url='C:\Program Files\Harris\ENVI54\data\qb_boulder_msi', factory='URLRaster') >>> parameters = dict(INPUT_RASTER=input_raster, INDEX='Normalized Difference Vegetation Index') >>> result = task.execute(parameters)
-
description
¶ The task description
Returns: a string
-
display_name
¶ The display name of the task
Returns: a string
-
execute
(parameters, cwd=None)[source]¶ Executes a synchronous task using the Task Engine
Parameters: - parameters – A dictionary of key-value pairs of parameter names and values. The dictionary serves as input to the job.
- cwd – Set to the current working directory the engine will run in. Defaults to the python current working directory if none specified.
Returns: A dictionary containing the Task Engine output.
-
name
¶ The name of the task
Returns: a string
-
parameters
¶ A list of the task parameter definitions. Each task parameter is a dictionary containing, but not limited to, the following keys:
Key Data Type Type Description name string Required The name of the parameter display_name string Required The display name of the parameter type string Required The parameter data type direction string Required Can be input or output description string Required The parameter description required bool Required Indicates if the parameter is required on input when submitting a job dimensions string Optional Indicates if the parameter is an array if set. Dimesions is of the format [dim1,dim2,...] choice_list list Optional A list of available choices for the parameter input min type Optional The minimum value allowed for the parameter max type Optional The maximum value allowed for the parameter Returns: a list of parameter dictionaries
-
uri
¶ The task unique identifier
-
ENVI Py Engine Config¶
The config module is used to configure settings for ENVI Py Engine.
The following properties are currently supported:
Property Name | Data Type | Description |
---|---|---|
engine | string | The full path to the engine executable. Example: “C:\Program Files\Harris\ENVI54\IDL86\bin\bin.x86_64\taskengine.exe” |
engine-args | string | Any additional command line arguments that will be passed to the taskengine executable. |
Environment Variable | string | Any valid environment variable and value pairs. |
Names | All name/value pairs specified in this section will be interpreted as environment variables for use when running the Engine. |
Please refer to the following examples of setting configuration values.
- Set the Engine Executable path for the current user:
>>> import envipyengine >>> envipyengine.config.set('engine', <executable-path>)
- Set the ENVI Engine Executable path for all users.
>>> import envipyengine >>> envipyengine.config.set('engine', <install-dir>, system=True)
- Specify additional arguments for the Task Engine:
>>> import envipyengine >>> envipyengine.config.set('engine-args', '--compile')
- Specify an environment variable to be used when running the task engine:
>>> import envipyengine >>> envipyengine.config.set_environment(dict('IDL_PATH'=<path-to-idl-code>)
The locations of the configuration files are:
OS and Configuration Type | Configuration File |
---|---|
Windows User Configuration | C:\Users\<user>\AppData\Local\envipyengine\settings.cfg |
Windows System Configuration | C:\ProgramData\envipyengine\settings.cfg |
Mac OS X User Configuration | /Users/<user>/Library/Preferences/envipyengine/settings.cfg |
Max OS X System Configuration | /Library/Preferences/envipyengine/settings.cfg |
Linux User Configuration | /home/<user>/.envipyengine/settings.cfg |
Linux System Configuration | /var/lib/envipyengine/settings.cfg |
-
envipyengine.config.
get
(property_name)[source]¶ Returns the value of the specified configuration property. Property values stored in the user configuration file take precedence over values stored in the system configuration file.
Parameters: property_name – The name of the property to retrieve. Returns: The value of the property.
-
envipyengine.config.
get_environment
()[source]¶ Return all environment values from the config files. Values stored in the user configuration file will take precedence over values stored in the system configuration file.
Returns: A dictionary containing the name/value pairs of all environment settings in the config file.
-
envipyengine.config.
remove
(property_name, system=False)[source]¶ Remove a configuration property/value setting from the config file.
Parameters: - property_name – The name of the property to remove.
- system – Set to True to modify the system configuration file. If not set, the user config file will be modified.
-
envipyengine.config.
remove_environment
(environment_var_name, system=False)[source]¶ Remove the specified environment setting from the appropriate config file.
Parameters: - environment_var_name – The name of the environment setting to remove.
- system – Set to True to modify the system configuration file. If not set, the user config file will be modified.
-
envipyengine.config.
set
(property_name, value, system=False)[source]¶ Sets the configuration property to the specified value.
Parameters: - property_name – The name of the property to set.
- value – The value for the property.
- system – Set to True to modify the system configuration file. If not set, the user config file will be modified.
-
envipyengine.config.
set_environment
(environment, system=False)[source]¶ Set engine environment values in the config file.
Parameters: - environment – A dictionary containing the environment variable settings as key/value pairs.
- system – Set to True to modify the system configuration file. If not set, the user config file will be modified.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line