Hexagon Geospatial
MENU

Developers Knowledge Base

M.App Portfolio provides a modern, cloud-based platform for creating and delivering diverse geospatial web applications.
Through the M.App Studio, our partners can design, build, and deploy their own Hexagon Smart M.Apps.
Showing results for 
Search instead for 
Do you mean 

Creating recipes with a region of Interest.

by Technical Evangelist on ‎08-09-2016 07:43 AM (913 Views)

Contents.

 

1) Introduction.

 - No ROI Provided.

 - ROI Provided "Inline".

 - ROI Provided as JSON File Reference.
 - ROI Provided as Feature File.

 

2) The Example.

 

3) The Spatial Recipe.

 - Apply ROI (if present).

 - Cell Size.

 - Get Input Features.

 

4) JSON File Contents.

 

5) JSON Payload with ROI Inline.

 

6) Testing the Recipe in Studio.

 - Push the Data Up to M.App Chest.

 - Create a Recipe in Spatial Workshop.

 - Create the Test M.App and Run It

 - Enter the Values and Execute the Recipe.

 

Test data required to complete this guide is provided in the attachment.

 

Introduction

It is often desired that a Spatial Recipe will process on a subset of the input data. A very common case is to only process data that fall within a given rectangle, for example the rectangle defined by the current view of the data. Another common case is process on that data falls within a given polygon (or polygons), for example the boundary of a county or one or more parcels of land. We will refer to each of these as different instances of a Region of Interest (ROI). The Spatial Modeling environment is very flexible in this regard an provides a collection of operators that provide many different ways to do this.

This document provides an example that can serve as a convential means of writing models that support an ROI. The approach is very flexible in that it provides for the following cases:

 

  1. No ROI provided
  2. ROI provided “inline” in the API invocation
  3. ROI provided as a reference to a JSON file
  4. ROI Provided as a reference to a feature file (i.e. a Shapefile)

 

No ROI Provided

In this case the model will create an output whose extent is the same as the input.

 

ROI Provided “Inline”

In this case the ROI definition is provided as a part of the JSON payload which is provided to the Spatial Recipe at run time. The input is provided as an IMAGINE.FeatureSubset, which is described later in this document.

 

ROI Provided as JSON File Reference

In this case the ROI is saved in a JSON formatted file and the name of the file itself is passed in JSON payload which is provided to the Spatial Recipe at run time. This done if the number of vertices in geometry defining the ROI is very large and cases the total JSON payload to exceed its limit. In that case the JSON defining the ROI is written to file and the name of the file itself is then passed in the JSON payload.

 

ROI Provided as Feature File

In this case the ROI exists in a feature file, like a ShapeFile (the only one supported at this time) and the name of the Shapefile is passes in the JSON payload. In this case all of the geometries in the Shapefile are used.

 

 

The Example

This example applies the clump operation to an input thematic image and can optionally be limited to polygonal subset. The input image with the ROI imposed on top is shown below:

 

1example.png

 

 

The Spatial Recipe

The following is a typical recipe which can be used to clump the classes that might come out of a classification operation. This approach processes the entire input. The “Thematic In” port accepts a filename which is then input to the “Raster Input” which read data from the file and passes it downstream for processing. The “Filename Out” input names the output file to be created by the “Raster Output” operator. The model then clumps the classes writes the output file and also updates it with a new set of class tables.

 

1graph.png

 

The model below has been modified to support a ROI to optionally restrict the processing area. The “ROI In” port takes the ROI in one of the various forms described above and provides it as input to the “Apply ROI (if present)” sub model that is being used to optionally mask the output from Raster Input. It is being used, in effect, like a filter. The raster is taken from the “Raster Input” and passed through this filter and on into the “Clump” operation. The extent of the output will be set to the extent of the ROI as defined by the minimum bounding box of the geometries. Pixels that fall outside the ROI will be returned a NODATA.

 

2graph.png

 

Apply ROI (if present)

This is a sub model which contains the logic used to implement the filtering. It can be seen by expanding the sub model.

 

3graph.png

 

The general flow of this sub model is that it determines if there an ROI and if so it determines the sources of the ROI, rasterizes it then uses the information about the bounding box of the ROI and the raster to define the processing extent (which will be the intersection of the two bounding boxes) plus the cell size which will match the input. It also creates a raster mask within the extent. If there is no ROI then the pixels are just passed through with no change. The ROI source determination and the Cell Size determination are themselves handled in sub models.

 

Cell Size

The Cell Size sub model extracts the X and Y cell size plus the units from the raster input.

 

4graph.png

 

Get Input Features

This sub model determines what to do with the three possible forms of ROI input, a JSON string containing the geometry, a string that names a JSON file, a string that names a feature dataset (i.e. a Shapefile).

 

5graph.png

 

The “To String” operator will return “<featureset>” if the input is actually a JSON FeatureSubset. If this is the case it is passed on through. If the input is the name of a file then the filename will be the output of the To String and that is tested to see if it ends with .json. In this case then the Data Input operator output contains a feature set which is passed on through. If none of the above hold true then it is assumed to be the name of a dataset which is just passed through to the Features Input operator which takes either a FeatureSubset or the name of a file containing features.

 

 

JSON File Contents

The following is the content of a sample JSON file which is used to define the geometry of the ROI. It contains the serialization of an IMAGINE.FeatureSubset object. The Value of a serialized IMAGINE.FeatureSubset object is a GeoJSON object.

 

 

{
    "Type": "IMAGINE.FeatureSubset",
    "Value": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [ 721806.292, 3794829.217 ],
                            [ 726864.831, 3797362.385 ],
                            [ 737060.948, 3795304.186 ],
                            [ 737060.948, 3787783.845 ],
                            [ 734610.718, 3783825.770 ],
                            [ 729156.981, 3781530.087 ],
                            [ 722596.689, 3789367.075 ]
                        ]
                    ]
                },
                "properties": null
            }
        ],
        "attributeInfo": null,
        "crs": null,
        "geometryInfo": {
            "geometryType": 3,
            "numDimensions": 2,
            "coordinateReferenceSystemID": null
        }
    }
}

 

 

JSON Payload with ROI Inline

The following JSON is an example of the payload used to launch the model with the ROI Inline. The ROI used here is the same geometry as the example above.

 

 

{
    "Method": "Asynchronous",
    "Inputs": [
        {
            "Name": "Thematic In",
            "Data": {
                "Type": "IMAGINE.File",
                "Value": "//alpha/teamspace/args/batchtestdata/inputdata/clump_with_colors.img"
            }
        },
        {
            "Name": "ROI In",
            "Data": {
                "Type": "IMAGINE.FeatureSubset",
                "Value": {
                    "type": "FeatureCollection",
                    "features": [
                        {
                            "type": "Feature",
                            "geometry": {
                                "type": "Polygon",
                                "coordinates": [
                                    [
                                        [ 721806.292, 3794829.217 ],
                                        [ 726864.831, 3797362.385 ],
                                        [ 737060.948, 3795304.186 ],
                                        [ 737060.948, 3787783.845 ],
                                        [ 734610.718, 3783825.770 ],
                                        [ 729156.981, 3781530.087 ],
                                        [ 722596.689, 3789367.075 ]
                                    ]
                                ]
                            },
                            "properties": null
                        }
                    ],
                    "attributeInfo": null,
                    "crs": null,
                    "geometryInfo": {
                        "geometryType": 3,
                        "numDimensions": 2,
                        "coordinateReferenceSystemID": null
                    }
                }
            }
        },
        {
            "Name": "Filename Out",
            "Data": {
                "Type": "IMAGINE.File",
                "Value": "c:/data/clump_with_color_subset.img"
            }
        }
    ]
} 

 

Testing the Recipe in Studio

The model can be tested in Studio Using the following steps.

 

 

Push the Data Up To M.App Chest

 

  1. Created a folder in M.App Chest called “ROI Test”
  2. Uploaded the example image “clump_with_colors.img” and “.rrd” to that folder.
  3. Uploaded the same ROI JSON file “clump_with_colors_subset_features.json to that folder.

1studio.png

 

Create a Recipe in Spatial Workshop

 

  1. Create a new recipe in SpatialWorkshop called “Clump With Colors”
  2. Uploaded “clumpwithcolors_subset_data_from_any_source.gmdx” to the new recipe.
  3. Saved the recipe as “Clump With Colors”

Create the Test M.App and Run It

 

  1. Selected and Published the “Clump With Colors” recipe.
  2. Created a new M.App called “Test ROI” in Studio.
  3. Configured it with a Geoprocessing and a Map Window.
  4. Save the M.App and then run it.

2studio.png

 

Enter the Values and Execute the Recipe

 

  1. Select “clump_with_colors.img” as the THEMATIC IN.
  2. Select “clump_with_colors_subset_features.json” as the ROI IN
  3. Enter “clippedoutput.img” as the FILENAME OUT.
  4. Press Execute.

The result will be a subset of the input image as below:

 

3studio.png

 

Comments
by Technical Evangelist
‎09-07-2016 05:08 AM - edited ‎09-07-2016 05:27 AM

Hi Michal,

 

One of the Ignite Finalists has mentioned that the Zip file does not seem to include the Spatial Model that is referenced in the article. Could you pelase add it or otherwise provide it?

 

Great article though!

 

Cheers

 

Ian

 

Contributors