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


  >  Docs Center  >  Using ENVI  >  Create Models

ENVI

Create Models

Create Models

This topic describes the process of creating a model. See the following sections:

Add Tasks


Tasks are processing operations that act on input data. The Tasks list includes all of the ENVITasks that are available in the current ENVI session. To learn more about a task and its parameters, click the button in the user interface. Or, right-click on the task name in the Tasks list and select Task Help.

Follow these steps to add a Task node to a model:

Search Tasks

Enter a keyword in the search box of the Tasks list to search for specific tasks. The tasks that include the keyword are displayed; for example:

When you select a task, a brief description of that task is displayed below the Tasks list. Click the Reset button to remove the keyword from the search box.

You can also search for tasks by category. Click the Filter by Tag button next to the search box. The Select Tag dialog displays; for example:

Select a tag to see a list of tasks that fall within that category. For example, clicking the Subsets button populates the search result list with the following tasks:

You can apply a maximum of two filters. The current filters are displayed below the search window. Click a filter to remove it.

Or, click the Reset button to remove all filters.

Finally, you can right-click on any task in the list and select Find Similar Tasks. The list is updated to show tasks that are in the same category. For example, the Thematic Change task is categorized as both "ENVI" and "Change Detection." Right-clicking on Thematic Change and selecting Find Similar Tasks populates the search results with other tasks that are labeled with the same categories.

Add Tasks to Models

  1. Double-click a task name to add it to the model.
  2. Click the button in the Task node to display the task parameter dialog; for example:
  3. Enter values for each parameter as needed, and click OK.

Tip: You may not want to select an Input Raster here, depending on how the model will be used. See Define Task Input Data for different options for specifying input data.

If a model contains a task that ENVI does not recognize, the task node is colored red. For example, the RPC Orthorectification Using DSM From Dense Image Matching task requires the ENVI Photogrammetry Module. If this module has not been installed, the task is colored red to indicate it is undefined, and the model will not run.

Define Task Input Data

You have several options for specifying input data for tasks.

File and Dataset Nodes

You can add a File or Dataset node to a model, then connect it to a Task node.

A File node represents one or more files on disk that contain data that ENVI can read. Follow these steps to add a File node to a model:

  1. Double-click File in the Basic Nodes list. A Select Type dialog appears.
  2. Select the data type of the input file. The options are as follows:
  3. Choose one or more input files from the Select File(s) dialog and click Open. The node displays the data type and the filename; for example:

The purpose of a File node is to take one or more file strings and open them into data types that ENVI can read. Examples include rasters, vectors, ground control points, tie points, and other data types. The exception to this behavior is the URI String type, which will leave the string untouched and not attempt to open it. Use URI String if you have a task that needs a string input and knows how to use it. An example is the Extract Raster from File task node.

Use a Dataset node to specify data that is already open in ENVI. Follow these steps to add a Dataset node:

  1. Double-click Dataset in the Basic Nodes list. A Select Type dialog appears.
  2. Select the data type of the input dataset. The options are as follows:
  3. Select one or more files from the Data Selection dialog. The following example shows a Sentinel-2 dataset:
  4. Optionally define a spatial subset, spectral subset, and/or mask.
  5. Tip: Another option for spatial and spectral subsetting is to add a Geographic Subset Raster or Subset Raster Task node to the model. If the input image is georeferenced to a standard map projection, enter a four-element array of coordinates into the Subrect field as follows:

    Geographic coordinates (degrees): [minLongitude, minLatitude, maxLongitude, maxLatitude]

    Map coordinates (eastings/northings): [minX, minY, maxX, maxY]

    To define a spectral subset, enter an array of zero-based band numbers in the Bands field. You can do this with a Geographic Subset Raster or Subset Raster Task node. For example, to include the first two bands in an image, enter [0, 1] in the Bands field.

  6. Click OK. The node displays the data type and filename.
  7. Connect the Task node to the File or Dataset node; for example:

Task Parameter Dialogs

You can also define input data by using a task parameter dialog, instead of using File or Dataset nodes. Click the button in a Task node to display the task parameter dialog. Then manually select a file or dataset; for example:

In this case, you do not need to connect the task to a File or Dataset node. However, this hides the input raster from all model users. You should use File or Dataset nodes if you want to expose the input files that were used in the model.

Input Parameters Nodes

Add an Input Parameters node when you want the model to display a dialog for users to select an input file or other task parameters. This option is useful for models that you share with others. Follow these steps to add an Input Parameters node:

  1. Double-click Input Parameters in the Basic Nodes list.
  2. Draw a connector between the Input Parameters node and a Task node. The Connect Parameters dialog appears.
  3. Click the input parameters (on the right side) that you want to expose to end users. Lines are drawn between those parameters and the Add New Input(s) button; for example:

When you or others run the model, an Input Parameters dialog will appear that contains all of the parameter options you specified; for example:

Once a parameter has been exposed in this manner, it can be reused by other tasks. In this example, the same Input Raster parameter can also be used for the Dice Raster by Number of Pixels task:

Parameters that can be reused appear above the Add New Input(s) button.

Click the button in the Input Parameters node to update the following items for parameters:

  • The display name, which is the label that model users will see when running the task; for example:
  • Description
  • The order in which the parameters appear to the user. Use the and buttons to set the parameter order.

For example:

You can also expose to model users where to write output files. To do this, double-click the connector between the Input Parameters node and the Task node that produces output. Then click the Output Raster URI button on the right side of the Edit Connection Parameters dialog. A line is drawn between this button and the Add New Input(s) button; for example:

When the model runs, the Input Parameters dialog will have an Output Raster URI field to specify where to write the output:

Arrays of Values

Add an Array of Values node to a model to specify an array of numbers or strings as input to a task. For example, suppose that you want to run the ISODATA Classification task multiple times, using a different Number of Classes value each time, for comparison. Provide an array of integers using an Array of Values node, then connect that node to an Iterator node (described in Batch-Process Data). For example:

Manage Multiple Connections

You can add multiple File or Dataset nodes to a task that requires multiple inputs. An example is the Create Subrects from Vector task, which accepts both an input raster and vector:

In some cases, a connection represents multiple links between input and output parameters. If more than one connection is possible between two nodes, a Connect Parameters dialog appears so that you can specify the correct connection. For example, the RPC Orthorectification task accepts an Input Raster and a DEM Raster as input. If you connect a raster-based File node to this task, the ENVI Modeler does not know which input parameter to link it to. When the Connect Parameters dialog appears, click the input file button on the left side, then click the button on the right side for the raster that it represents. A red line connects the two buttons. In the following example, the file qb_boulder_msi represents the Input Raster:

To define the DEM Raster in this example, repeat these steps by connecting a separate File node to the RPC Orthorectification node. When the Connect Parameters dialog appears, click the button for the DEM file on the left, followed by the DEM Raster button on the right:

To remove a connection in the Connect Parameters dialog, click the associated button on the left side (qb_boulder_msi or GMTED2010.jp2 in this example).

Extract Properties and Metadata

Add an Extract Properties and Metadata node to extract specific properties from an object to use as input to another task. For example, you can extract the spatial reference from a raster to use as the Spatial Reference input to the Build Band Stack Task.

Follow these steps:

  1. Double-click Extract Properties/Metadata in the Tasks list.
  2. Draw a connector between the output of a task and the Extract Properties and Metadata node.
  3. Click the button in the Extract Properties and Metadata node. The Extract Properties and Metadata dialog appears, listing the known properties and metadata items from the input.
  4. If the input dataset has other properties that are not listed here, enter them (one per line) in the Other Properties list. Or, if you added custom metadata to an input dataset, enter those metadata names in the Other Properties list.
  5. Click OK.
  6. The following example shows the properties of a raster derived from the Extract Examples from Raster task, which is used in the ENVI classification framework:

  7. Connect the Extract Properties and Metadata node to a Task node that will accept its input.
  8. Match the output properties or metadata items on the left with their corresponding items on the right; for example:

Extract Elements from Arrays

Add an Extract Elements from Arrays node to extract one or more elements from a 1-D or multi-dimensional array. Follow these steps:

  1. Double-click Extract Elements from Arrays in the Tasks list.
  2. Draw a connector between an array input node, and the Extract Elements from arrays node. Examples of array input include an Array of Values node or a task that produces an array.
  3. Click the button in the Extract Elements from Array node. The Extract Elements from Array dialog appears, listing the known properties and metadata items from the input.
  4. In the Indices field, specify one or more zero-based elements to extract from the input array. For 1-D arrays, this is the subscript of the array element. For example, if the array is [1, 2, 3, 4, 5, 6] and you want to extract the third element (with a value of 3), enter an Indices value of 2. See the table below for guidelines on specifying ranges of subscripts.
  5. For multi-dimensional arrays, specify the 1-D subscript of the array element to extract. For example, suppose that you have an array with three columns and two rows:

    1 2 3
    4 5 6

    To extract the array element in the first column and second row (with a value of 4), enter an Indices value of 3. Array elements are stored in row order in IDL.

  6. Click OK.

Array Subscript Ranges

The following table summarizes the different ways to specify ranges of array subscripts.

Subscript Format

Description

[n]

A simple subscript, either positive or negative.

Positive subscripts are indexed from the beginning of the array, while negative subscripts are indexed from the end (where -1 is the last element). When used with multidimensional arrays, simple subscripts specify only elements with subscripts equal to the given subscript in that dimension.

[s0:s1]

Subscript range from s0 to s1.

This denotes all elements whose subscripts range from the expression s0 through s1(s0 must not be greater than s1). For example, if the variable vec is a 10-element vector, vec[4:8] is a five-element vector composed of vec[4] through vec[8]. Negative indices may be used, where -1 indicates the last element. For example, vec[-6:-2] returns the same five elements as vec[4:8].

[s0:s1:n]

Every n-th element in a range of subscripts from s0 to s1.

The expression n is referred to as the subscript stride. The stride value may be positive or negative (but must not be zero). If the stride is positive then s0 must be less than or equal to s1. If the stride is negative then s0 must be greater than or equal to s1. If the stride is 1, then the result is identical in meaning to [s0:s1], as described above. For example, if the variable vec is a 50-element vector, vec[5:13:2] is a five-element vector composed of vec[5], vec[7], vec[9], vec[11], and vec[13]. In another example, vec[-1:0:-3] would return every third element of vec, in reverse order.

Metatasks

To organize a model when it contains many elements, you can create a metatask that encloses multiple Task nodes. A metatask is a task that contains other tasks. It contains JSON code that combines multiple tasks, similar to ENVITask templates. See Metatasks in the ENVI API Programming Guide for more information.

You can generate a metatask and save it to a .task file on disk, or publish it so that it becomes available for use with other ENVITasks. Use the Code > Generate Metatask option in the ENVI Modeler menu bar. See Generate and Run Code From Models for details.

Create Metatasks from Models

The Create Task from Model option collapses multiple nodes into a single node. For example, here is a typical Image Registration workflow that consists of three Task nodes:

By using Create Task from Model, the model is collapsed into a single element as follows:

The metatask that will be created from this model will ignore the Data Manager and View Nodes. The input rasters defined by the File nodes will become static inputs to the nodes used in the model. The Define Metatask Inputs and Outputs section below provides some guidance for managing inputs and outputs.

Follow these steps to create a metatask from a model:

  1. Display a model.
  2. Select Edit > Create Task from Model from the ENVI Modeler menu bar, or click the Create Task from Model button in the toolbar. The model elements are collapsed into a single box, in a new "Untitled" tab.
  3. Click the Rename button and enter a name for the task.

To expand the task to see its contents, click the button. The nodes and connectors that comprise the model are displayed in a new tab, with the exception of Comment nodes.

Note: This feature does not support metatasks that contain iterators or aggregators.

Define Metatask Inputs and Outputs

Before creating a task using the Code > Generate Metatask or Edit > Create Task from Model menu option, you should define input and output parameters for the model.

Add an Input Parameters node to the beginning. This will allow anyone who runs the model to choose inputs through an Input Parameters dialog.

Next, add an Output Parameters node to a model from which you will generate a metatask. Why is this important? Suppose that you want to create a metatask from the following model:

If you select Code > Generate Metatask and click the Run button from the Metatask dialog, no output is displayed or saved to an output file. Similarly, if you click the Create Task from Model button, a new Task node is created without any way to specify output; it does not have an arrow on its right side.

Adding an Output Parameters node to the end of the model ensures that model users can access the output. It also lets you connect the outputs of a metatask to other nodes.

See Define Output for directions on how to specify output file locations.

See the Image Registration Metatask topic for an example of how to create a metatask.

Tip: The Output Parameters node can also be used in a metatask to present the numeric results of a model, insteaed of creating an output file.

Add Breakpoints


Adding breakpoints to tasks allows you to stop at those tasks during model execution, so that you can adjust parameters and preview results. Breakpoints can only be added to Task nodes. Adding multiple breakpoints to a model allows you to create an interactive workflow.

Note: This feature is only available if you have an ENVI+IDL license.

Follow these steps to add breakpoints:

  1. Click on a Task node in the layout window.
  2. Click the Toggle Breakpoint button in the ENVI Modeler toolbar. The task now contains a breakpoint icon.

When you run the model, the process stops at the breakpoint. The following example shows how the model stops at the ISODATA Classification task. In the user interface, click the Preview button and experiment with different parameter values to obtain the desired results. When you click OK in the user interface, the model continues running.

Changes to parameters only persist for that model instance. If you run the model again, the changes on your last breakpoint will not persist.

To remove a breakpoint, select the Task node and click the Toggle Breakpoint button, or click the red breakpoint dot on the node.

Batch-Process Data


A powerful feature of the ENVI Modeler is the ability to batch-process multiple datasets without requiring you to write a programming script. Use the Iterator node for this purpose. Follow these steps:

  1. Double-click Iterator in the Basic Nodes list.
  2. Place the Iterator node between a node that defines a set of items to iterate and the first task in the loop.
  3. Add input and output connectors to the Iterator node.

The following example batch-processes four input files and adds the results to the Data Manager:

See Generate Filename Node for another example that uses the Iterator node.

Use the Aggregator node to collect multiple items and add them to an array.

Follow these steps:

  1. Double-click Aggregator in the Basic Nodes list.
  2. Place the Aggregator node in the appropriate location in the model.
  3. Add input and output connectors to the Iterator node.

Here is an example that performs temporal classification. Instead of classifying a single image based on spectral signatures, the model calculates a Normalized Difference Vegetation Index for multiple images, assembles the results into a multi-band image, and creates a classification image of the NDVI results over time. This is an example of how the Aggregator node can be used in combination with an Iterator node:

Aggregator nodes have an option to separate lists or arrays into individual elements, if your model requires it. Click the button to display the Aggregator dialog. If the Extract option is set to Yes (the default option), any array added to the Aggregator node will be disassembled, and each of its elements will be added as a separate item.

For example, suppose that the following arrays have been added to an Aggregator node:

  [1,2]
  [3,4,5]
  [3,4,5,6]

By setting the Extract option to Yes, the output will be disassembled as follows:

1
2
3
4
5
3
4
5
6

Define Output


When you run a model, you may want to save the results to an output file. This section describes the different options for defining the output of a model.

Output Parameters

Click the button in the Task node where you want to create output, then specify the output filename and location in the dialog for that task. For example, the Classification Smoothing node has an Output Raster parameter:

This is a good option to run a model once and save the results to disk.

If you do not specify an Output Raster, ENVI will write a temporary file to the directory specified by the Temporary Directory preference, then delete the temporary files once ENVI closes. ENVI creates the filename automatically, based on the task name; for example, ClassificationSmoothing_output_raster_<date>.dat.

Some Task nodes create virtual rasters, where no output is written to disk. Virtual rasters provide an efficient way to pass the results of one raster to the input of another task. See the Virtual Rasters topic for a full list. An example is the Band Math node:

You can choose to write the output to disk by selecting the File radio button and specifying an output filename and location.

Generate Filename Node

Add a Generate Filename node to your model when you want to specify filenames and locations for task output. Draw a connector between the Generate Filename node and the last task in the model. In the Edit Connection Parameters dialog, the Output Filename parameter of the Generate Filename node should connect to the Output Raster URI parameter of the task; for example:

Then click the button in the Generate Filename node, and set the Directory, Filename Prefix, Extension, and Append Random Number parameters.

You can also use the Generate Filename node in conjunction with the Iterator node. For example, suppose that you want to run the ISODATA Classification task multiple times, using a different Number of Classes value each time, for comparison. Provide an array of integers using an Array of Values node, then connect that node to an Iterator node:

Add a Generate Filename node to the output of the Iterator node. Draw a connector between the two. In the Edit Connection Parameters dialog, connect the Iteration Index parameter of the Iterator node to the Number to Append parameter of the Generate Filename node:

Next, connect the output of the Generate Filename node to the input of the Classification Smoothing node. The Output Filename parameter of Generate Filename connects to the Output Raster URI parameter of Classification Smoothing:

Click the button in the Generate Filename node, and set the Directory, Filename Prefix, and Extension parameters. In this example, the Append Random Number option is set to No:

When the model runs, it creates three image files in the specified directory: ISODATAResult000.dat, ISODATAResult001.dat, and ISODATAResult002.dat.

Data Manager Node

Another option for creating an output file is to add a Data Manager node to the model, then connect it to the right side of the Task node. When the model runs, the output is added to the Data Manager. Use the File > Save As > Save As (ENVI, NITF, TIFF, DTED) menu option to save the output to disk. The Data Manager node is described next.

Add Processing Results to the Data Manager


Add Data Manager nodes to a model whenever you create output that you want to add to the ENVI Data Manager. Only rasters and vectors can be added to the Data Manager. Follow these steps:

  1. Double-click Data Manager in the Basic Nodes list.
  2. Add a connector between the Data Manager node and the right side of a task.

In the following example, the results of ISODATA Classification and Classification Smoothing are both added to the Data Manager:

When running a metatask, all raster and vector parameters that are connected to either a View or Data Manager node will be displayed and added to the Data Manager.

Display Processing Results


Add View nodes to display output from tasks in a model. Only rasters and vectors can be added to views. Follow these steps:

  1. Double-click View in the Basic Nodes list.
  2. Add a connector between the View node and the right side of a task.

For example, you may want to display the input raster along with the output from a task. This creates two layers in the Layer Manager.

Add Comments


Use Comment nodes to add notes or instructions for yourself or other model users. Follow these steps:

  1. Double-click Comment in the Basic Nodes list.
  2. Enter text in the Comment field, and press the Enter key on your keyboard.
  3. Move the Comment node to the desired location in the model.
  4. To edit text after creating a Comment node, click the button.

Import Items into a Model


You can import task files, metatasks, and other models into an existing model tab. This could be useful, for example, when colleagues build different components of a model and you want to create a larger model from them.

Select File > Import from the ENVI Modeler menu bar, and choose the appropriate action. You can also drag and drop data items from the Data Manager or Layer Manager to your model. Files from disk are also accepted.

Validate and Run the Model


After you have added the desired nodes and connectors, you are ready to run your model. Validation is necessary to ensure that the required input parameters are present, that all parameter values are valid, and that all connections and output parameters are configured properly. You can validate the model before running it by selecting Code > Validate Model from the ENVI Modeler menu bar. Or, run the model and ENVI will validate it before running it.

Validation problems include errors and warnings. If your model has errors, you will not be allowed to run the model. Warnings are recommendations that you should note, but you can still run the model.

To run a model, click the Run button or select Code > Run Model from the ENVI Modeler menu bar. Nodes are colored green when the model successfully completes those steps. If an error occurs, the model stops on the offending node (colored bright yellow) and issues an error message with the details of the problem.

Note: The ability to highlight nodes as you run a model to show progress requires an ENVI+IDL license.

See Also


Generate and Run Code From Models, ENVI Modeler Examples, Getting Started with the ENVI Modeler



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