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


  >  Docs Center  >  Using ENVI  >  Running ENVI Analytics in ArcGIS Pro Tutorial

ENVI

Running ENVI Analytics in ArcGIS Pro Tutorial

Running ENVI Analytics in ArcGIS Pro Tutorial

In this tutorial you will learn how to create an ArcGIS® Python toolbox that contains ENVI geoprocessing tools. ENVI® Py for ArcGIS is required in order to create the toolbox. Each tool is based on an ENVITask in the ENVI application programming interface (API) that runs a specific analytic. You will view and run ENVI tools that are automatically installed and added to ArcGIS Pro. After configuring the ENVI environment in ArcGIS Pro, you will create a custom toolbox containing any number of ENVI analytic tools. You will also learn how to publish ENVI models as ArcGIS Pro tools.

This tutorial was tested with ENVI 5.5, Service Pack 1 and ArcGIS Pro 2.0.1 on a Windows 10 computer. You can use ENVI 5.4 or later, plus ArcGIS Pro 2.0 or later, or ArcMap™ 10.4 or later. The steps may be slightly different for ArcMap software. See the ENVI Py for ArcGIS online documentation for additional instructions with ArcMap.

See the following sections:

Before You Begin


  1. Install ArcGIS Pro with administrator privileges.
  2. Install ENVI 5.4 or later.
  3. Install ENVI Py for ArcGIS Pro by running one of the following files with administrator privileges:
    • envipyxx-arcgispro.exe: Included with your web download of ENVI software
    • setup-envipyxx-arcgispro.exe : Located on the ENVI installation DVD in the ENVIPyxx folder
  4. Follow the prompts in the ENVI Py for ArcGIS Pro installer.

View and Run Standard ENVI Tools


Once you install ENVI Py for ArcGIS Pro, an ENVI Analytics toolbox is automatically added to ArcGIS Pro. This toolbox contains several image-processing tools that are ready to use. Follow these steps to view the tools and to run an example.

  1. Start ArcGIS Pro.
  2. In the project selection screen, select the ENVIAnalytics.aptx project template. This is located in the Create a new project section.
  3. The Create a New Project dialog appears.

  4. In the Name field, enter ENVI Analytics.
  5. Select a location for the ENVI Analytics project. The default location is in your ArcGIS\Projects folder.
  6. Keep the default selection of Create a new folder for this project.
  7. Click OK. A topographic map is displayed.
  8. In the Catalog pane, click the Toolboxes folder to expand it.
  9. Click ENVI Analytics.tbx to expand it. This toolbox contains several image-processing tools:
  10. Double-click the ISODATA Classification tool. ISODATA is an unsupervised classification method. The parameters for ISODATA Classification are displayed in the Geoprocessing pane.
  11. Click the Browse button next to Input Raster.
  12. Navigate to the \data folder in your ENVI installation path; for example, C:\Program Files\Harris\ENVIxx\data\.
  13. Select Avon.dat and click OK.This is a true-color orthophoto of an area near Avon, New York.
  14. Keep the default values for Number of Classes, Change Threshold Percent, and Iterations.
  15. Tip: To learn more about these parameters, click the blue help icon in the ISODATA Classification task.

  16. To optionally specify a folder and filename for the output, type the path and filename directly in the Output Raster URI field. Be sure to include a .dat file extension with the filename.
  17. Click the Run button at the bottom of the Geoprocessing pane.
  18. When processing is complete, right-click on the new image (named ISODATAClassification_output_raster_*.dat) in the Contents pane and select Zoom to Layer. A classification image is displayed with five colors, each representing an unknown land-cover type.
  19. Remove the ISODATA classification layer from the display.

Next you will create a custom toolbox that consists of ENVI geoprocessing tools.

Create an ENVI Toolbox


Before creating a custom toolbox, you need to create a new project called "TutorialProject." This project will be created from the "ENVI Py Management" project template. Follow these steps:

  1. Click the Project tab in the ArcGIS Pro menu bar.
  2. In the New screen, under Computer, click the Browse button.
  3. Navigate to C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\Lib\site-packages\envipyarc\esri\projecttemplates\.
  4. Select ENVIPyManagement.aptx and click OK. The Create a New Project dialog appears.
  5. In the Name field, enter TutorialProject.
  6. Select a location for the new project. The default location is in your ArcGIS\Projects folder.
  7. Keep the default selection of Create a new folder for this project, then click OK.

Create a Custom Toolbox

  1. At the bottom of the Geoprocessing pane, click the Catalog tab to switch back to the Catalog pane.
  2. Click ENVI Management Tools.pyt to expand it.
  3. Double-click Create ENVI Toolbox.
  4. In the ENVI Task Name(s) field, you can add as many ENVITasks as you want. Here are some tips:
    • Not all ENVITasks can be exposed as standalone tools because they require data types that are incompatible with ArcGIS Pro. See Appendix: Supported ENVITasks for a list of supported tasks.
    • Omit the "ENVI" prefix and "Task" suffix when entering task names in the ENVI Task Name(s) field. For example, enter ISODATAClassification instead of ENVIISODATAClassificationTask.
    • After entering a task name, press the Enter or Tab key on your keyboard to add a new task name.
    • To remove a task, click inside of its field and click the Remove icon (the red X); for example:
  5. Click the Browse button to the right of the Output Toolbox folder. The Output Toolbox dialog appears.
  6. Under Project, double-click Folders.
  7. Double-click the TutorialProject folder.
  8. In the Name field, enter a name for your toolbox; for example, ENVI_SpectralProcessingTools.tbx. The following figure shows an example of some tasks that comprise the new toolbox:

  9. Click Save. The toolbox setup is ready.
  10. Click the Run button at the bottom of the Geoprocessing pane.
  11. When the toolbox is complete, a green check box indicates that the toolbox was successfully created.

  12. Click the Catalog tab at the bottom of the Geoprocessing pane to switch to the Catalog pane.
  13. Select the Project tab in the Catalog pane.
  14. Right-click on Toolboxes and select Add Toolbox. The Add Toolbox dialog appears.
  15. Navigate to the TutorialProject folder, and double-click it.
  16. Select the Python toolbox you just created (for example, ENVI_SpectralProcessingTools.pyt), and click OK. The new toolbox appears under the Toolboxes list in the Catalog pane.
  17. Double-click the new toolbox to see the tools within it; for example:
  18. Click the Project tab in the ArcGIS Pro menu bar.
  19. Click Save to save the current project.
  20. Close ArcGIS Pro.

Publish an ENVI Model as an ArcGIS Pro Tool


You can use the ENVI Modeler to create models with data-processing workflows that combine multiple tasks. Then you can save the entire model as a metatask, which is a single task that encompasses all of the tasks in the model. The metatask can be published as a standalone tool in ArcGIS Pro.

This section demonstrates how to do this using a simple pre-built model that performs ISODATA unsupervised classification and smooths the resulting classes.

Note: Before you begin, ensure that your ArcGIS Pro \Toolboxes folder has write permission. ENVI will attempt to publish the model/metatask in this example to the \Toolboxes folder. The default location is C:\Program Files\ArcGIS\Pro\Resources\ArcToolBox\Toolboxes\. If you do not have sufficient privileges to change the permission of this folder, you will need to perform some extra steps to add the new tool to ArcGIS Pro.

Configure the Model

  1. Start ENVI.
  2. From the ENVI menu bar, select Display > ENVI Modeler.
  3. From the ENVI Modeler menu bar, select File > Open.
  4. Navigate to the examples folder of your ENVI installation path; for example, C:\Program Files\Harris\ENVIxx\examples\.
  5. Select the file Modeler_Tutorial.model and click Open. The model elements are displayed:

    Before you can publish the model to ArcGIS Pro, you must make a few changes. You need to define input and output parameters so that all users can run the model using their own data and write the output to their own directory. Notice that the model already has an Input Parameters node. When the model is converted to a tool in ArcGIS Pro, an Input Parameters dialog will display so that you can select your own input file. Now you just need to add an Output Parameters node. Continue with these steps:

  6. Select the Data Manager and View nodes, and press the Delete key to remove them. The grey connectors are also removed.
  7. In the Basic Nodes list on the left side of the ENVI Modeler, double-click Output Parameters. A new Output Parameters node is added to the display.
  8. Move the Output Parameters node to the end of the model, then draw a line to connect it with the Classification Smoothing node:

    If you were to run the model now, the resulting image from Classification Smoothing would export to the ENVI temporary directory. Since you are creating a model to possibly share with others, you should display a dialog for users to choose the location of the output image. You will do this next.

  9. Drag the Input Parameters node down, then add a connector between this node and the Classification Smoothing node (the last task in the processing chain). The Connect Parameters dialog appears:
  10. Click the Output Raster URI button on the right. A red line is drawn between this and the Add New Input(s) button.
  11. Click OK in the Connect Parameters dialog. Now is a good time to make sure the model runs successfully.

Run the Model

  1. Click the Run button in the ENVI Modeler. After a few seconds, the Input Parameters dialog appears.
  2. Click the Browse button next to the Input Raster field. The Data Selection dialog appears.
  3. Click the Open File button in the Data Selection dialog.
  4. Navigate to the \data folder in your ENVI installation path; for example, C:\Program Files\Harris\ENVIXX\data\. Select the file Avon.dat and click Open.
  5. Click OK in the Data Selection dialog.
  6. Click the Browse button next to the Output Raster URI field.
  7. Select a folder and filename (with a .dat extension) for the output image.
  8. Click OK in the Input Parameters dialog to run the model. The output image is created in the folder that you specified.
  9. From the ENVI Modeler menu bar, select File > Save As. The Select Output Model File dialog appears.
  10. Navigate to a folder that has write permission, and rename the model to ClassificationWorkflow.model. Click Save.

Generate a Metatask from the Model

  1. From the ENVI Modeler menu bar, select Code > Generate Metatask. The Metatask dialog appears with JSON code for the metatask.
  2. In the Metatask toolbar, click the Publish Task button. The Publish Metatask dialog appears.
  3. In the Name field, enter ClassificationWorkflow.
  4. In the Display Name field, enter Classification Workflow.
  5. Enter an optional Description.
  6. Click the ArcGIS Pro check box, then click OK.

    An Information dialog appears, indicating where the metatask file was written. The default path is the custom_code folder of your ENVI installation path; for example:

    C:\Program Files\Harris\ENVI55\custom_code
  7. Click OK in the Information dialog.
  8. If the above folder does not have write permission, then ENVI writes the metatask to C:\Users\<username>\.idl\envi\custom_codex_x\, where x_x is the ENVI version number. If this is the case, move the metatask file (ClassificationWorkflow.task) to the custom_code folder of your ENVI installation path, with administrator privileges.
  9. Close the Metatask dialog and the ENVI Modeler, then exit ENVI.

Run the ClassificationWorkflow Tool in ArcGIS Pro.

  1. Restart ArcGIS Pro.
  2. Select TutorialProject.
  3. Now that the ClassificationWorkflow tool has been successfully created, it should be available under the Toolboxes folder of the Catalog pane. By default, ENVI adds the tool to the Toolboxes folder of your ArcGIS Pro installation path.
  4. Double-click the ClassificationWorkflow tool.
  5. Click the Browse button next to Input Raster.
  6. Navigate to the \data folder in your ENVI installation path; for example, C:\Program Files\Harris\ENVIXX\data\. Select the file Avon.dat and click OK.
  7. Optionally enter a full path and filename for the output image, in the Output Raster URI field. Be sure to include a .dat extension with the filename.
  8. Click Run. When processing is complete, the resulting ISODATA (smoothed) classification image appears:

Manually Adding the Toolbox

If you cannot provide write permission to the \Toolboxes folder (for example, if you do not have sufficient privileges; see the note above), ENVI automatically adds the new toolbox to an arc_toolboxes subfolder in the ENVI auxiliary folder. The location of this folder is defined in the Auxiliary File Directory preference in ENVI. The default path is:

  C:\Users\<username>\.idl\envi\auxiliary\arc_toolboxes

ArcGIS Pro will not show the new toolbox right away. Follow these steps to manually add the new toolbox:

  1. Select the Project tab in the Catalog pane.
  2. Right-click on Toolboxes and select Add Toolbox. The Add Toolbox dialog appears.
  3. Navigate to the arc_toolboxes folder.
  4. Select ClassificationWorkflow.pyt and click OK. The ClassificationWorkflow tool is now available for you to use in ArcGIS Pro.

Tips for Using ENVI Tools


ENVI tools have specific requirements for input parameters. Click the tooltip next to a parameter to learn more about it. Since each tool is based on an ENVITask, you can also refer to the ENVI Help topic for that task to see an example of how it is used.

Some tools such as ApplyGainOffset and GaussianStretchRaster have input parameters that accept multiple values. Since you cannot enter an array of values in ArcGIS Pro (as you can with an ENVITask in the ENVI API), you must enter the values line-by-line. For example, the ApplyGainOffset tool requires a gain and offset value for each band of an image. If an image has six bands, you must enter each gain and offset value separately:

In this example, the Data Gain Value of 2 and the Data Offset Value of 12.33 pertain to the first band in the image.

Other tools accept a two-element array of values for kernels and X/Y dimensions. Again, enter each value in a separate line. For example, the DimensionsResampleRaster tool accepts two values for the Output Raster Dimensions parameter: the number of pixels in the X direction and the number of pixels in the Y direction. To resample an image to a new raster with 512 rows and 512 columns, enter the values as follows:

Finally, most tools have an output parameter such as Output Raster or Output Raster URI. These are optional, and you can still run the tool without specifying an output file. However, output parameters are actually treated as inputs in ENVITasks. If you click the Browse button next to an output parameter field, and you specify a filename and location, you will receive an error that the output file does not exist. Instead, type the full path and name for the output file in the field provided; for example:

When the tool runs, the output will be written to that location.

With raster output, you can also omit the Output Raster or Output Raster URI field and display the resulting image in ArcGIS Pro. Then right-click on the layer name in the Contents window and select Data > Export to export the image to one of several common image formats.

Appendix: Supported ENVITasks


Some data types that are used in ENVI are not supported in ArcGIS Pro. These include regions of interest (ROIs), point clouds, ground control points (GCPs), tie points, multi-dimensional arrays of data, and others. If an ENVI tool exposes an input or output parameter that includes any of these data types, the tool will not run and an error message will appear in the progress bar.

Tip: If you want to use ENVITasks that operate on these data types (for example, ROIs or multi-dimensional arrays), you can create a model that includes these tasks as long they do not expose input/output parameters for unsupported data types to the end user. Use the ENVI Modeler to create a new metatask from the model. Then publish the metatask to ArcGIS Pro.

The ENVITasks listed below have been successfully tested and verified to work with ArcMap and ArcGIS Pro. Refer to the ENVI Help for more information about these tasks. Items marked with an asterisk (*) are meant to be used within a processing chain (such as an ENVI or ArcGIS model) and will not display any results.

The following ENVI Crop Science tasks are supported in ArcGIS Pro. ENVI Crop Science must be licensed and installed on your system. Refer to the ENVI Crop Science Help for more information about these tasks.

  • AgCalculateAndRasterizeCropMetrics
  • AgCalculateAndRasterizeCropMetricsWithSpectralIndex

  • AgCalculateCropMetrics*

  • AgCalculateGetisOrd*
  • AgCountAndRasterizeCrops
  • AgCropCount*
  • AgCropsToShapefile
  • AgDevelopingHotspotColorSlice

  • AgEnhanceCrops
  • AgFindAndRasterizeCropGaps

  • AgFindDevelopingHotspots

  • AgFindDevelopingHotspotsWithSpectralIndex

  • AgHotspotAnalysis
  • AgHotspotColorSlice
  • AgRasterizeCrops
  • AgSpectralHotspotAnalysis



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