Purpose

Allows to read and apply inference tile properties from a JSON file.

The properties are later used by ProcessTiles or ApplyTileProcessorPageWise to apply the connected processor to an image. This is necessary since processor providers (e.g. TensorFlowServingTileProcessor or ONNXTileProcessor) cannot always provide suitable proposals themselves.

With this module, you can only apply a full set of properties. To change individual properties manually, use SetTileProcessorProperties.

Usage

Usually you want to place the module in between your processor and the applying module (e.g. ProcessTiles). Then specify the JSON file and press Update.

Details

Inference Properties JSON File Format

This is a typical example for a 3D segmentation/classification task with 3 one-hot encoded output classes.

{
    "VERSION": 2,
    "inputs": {
        "input": {
            "dataType": "float32",
            "dimensions": "X, Y, Z, CHANNEL1, BATCH",
            "externalDimensionForBatch": null,
            "externalDimensionForChannel1": "C",
            "externalDimensionForChannel2": null,
            "fillMode": "Reflect",
            "fillValue": null,
            "padding": [20, 20, 20, 0, 0, 0]
        }
    },
    "outputs": {
        "output": {
            "dataType": "float32",
            "referenceInput": "input",
            "stride": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
            "tileSize": [52, 52, 52, 3, 1, 1],
            "tileSizeMinimum": [4, 4, 4, 3, 1, 1],
            "tileSizeOffset": [4, 4, 4, 0, 1, 0],
            "valueMaximum": 0.0,
            "valueMinimum": 1.0
        }
    }
}

Properties with null value could have just as well been omitted.

You can obtain the currently valid JSON schema for the properties format at Used JSON Schema.

For a detailed description of the individual properties, please check out the JSON Schema Documentation.

Old JSON File Format Support (VERSION 1)

Version 1 files are supported for some more time. This is an example file (may optionally contain a "VERSION": 1 line):

{
  "externalDimensionForChannel1": "C",
  "externalToProcessorDimensionMapping": "X, Y, CHANNEL, BATCH",
  "fillMode": "FillValue",
  "fillValue": 0,
  "minimumOutputTileSize": [4, 4, 2, 1, 1, 1],
  "outputTileSize": null,
  "padding": [0, 0, 0, 0, 0, 0],
  "stride": [1, 1, 1, 1, 1, 1],
  "tileSizeOffset": [8, 8, 0, 1, 1, 1]
}

The files are auto-converted into VERSION 2 objects in such way that all outputs and inputs get the same properties, and that the first input is used as `referenceInput`.

Tips

Editing JSON Files

Editing is best done in a suitable editor. If you have associated .json files with an editor in your operating system, you can quickly edit the current file externally by using the Edit... button next to the Browse... one.

Editing gets much more convenient and less error-prone if you register the JSON schema referenced in Used JSON Schema with your file. E.g. for Visual Studio Code, you can do this by adding something like this to your setting:

"json.schemas": [
  {
    "fileMatch": ["*properties.json", "*properties.jsonc"],
    "url": "file:///c:/dev/fme/FMEwork/General/Modules/Scripts/python/tile_processing/schemas/json/properties_schema.json"
  }
],

You can obtain the currently valid JSON schema location for the properties format at Used JSON Schema.

Windows

Default Panel

../../../Projects/TileProcessing/TileProcessorPropertiesUtils/SetTileProcessorPropertiesFromJson/Modules/mhelp/Images/Screenshots/SetTileProcessorPropertiesFromJson._default.png

Input Fields

inObject

name: inObject, type: MLBase, deprecated name: inTileClassifier,inTileProperties

Optional input that may be Null or a TileProcessor, TileProcessorProperties(Source) or TileProcessorContainer object. You can and should specify exact input requirements via inRequireValidProcessor and inRequireValidProperties.

Output Fields

outObject

name: outObject, type: MLBase, deprecated name: outAutoTileClassifier,outTileClassifier,outTileProperties

Output TileProcessor, TilePropertiesSource or TileProcessorContainer (BaseList).

This is what to expect:

Input: Null (empty) -> Output: CppTileProperties

Input: TilePropertiesSource -> Output: CppTileProperties

Input: TileProcessor -> Output: TileProcessorContainer (containing the unmodified input tile processor and the new tile properties)

Input: TileProcessorContainer -> Output: TileProcessorContainer (with the same content as the input TileProcessorContainer, except for the modified/new tile properties)

Make sure to set inRequireValidProcessor and inRequireValidProperties accordingly or you will wind up with an invalid output for some of these constellations.

Parameter Fields

Visible Fields

Update

name: update, type: Trigger

Initiates update of all output field values.

Clear

name: clear, type: Trigger

Clears all output field values to a clean initial state.

On Input Change Behavior

name: onInputChangeBehavior, type: Enum, default: Clear, deprecated name: shouldAutoUpdate,shouldUpdateAutomatically

Declares how the module should react if a value of an input field changes.

Values:

Title Name Deprecated Name
Update Update TRUE
Clear Clear FALSE

[]

name: updateDone, type: Trigger, persistent: no

Notifies that an update was performed (Check status interface fields to identify success or failure).

Has Valid Output

name: hasValidOutput, type: Bool, persistent: no

Indicates validity of output field values (success of computation).

Status Code

name: statusCode, type: Enum, persistent: no

Reflects module’s status (successful or failed computations) as one of some predefined enumeration values.

Values:

Title Name
Ok Ok
Invalid input object Invalid input object
Invalid input parameter Invalid input parameter
Internal error Internal error

Status Message

name: statusMessage, type: String, persistent: no

Gives additional, detailed information about status code as human-readable message.

Auto-Update JSON From File Before Output Update

name: inAutoReadParametersFromFileBeforeUpdate, type: Bool, default: TRUE

If enabled, the properties file is read and applied anew on each Update. You can disable this, if you want to change the input tile processor but are sure that the current properties are still correct.

Inference Tile Properties File

name: inPropertiesFile, type: String

Path of the properties.json file to read from. See ‘Details’ section of the help for info on the properties file format.

Update From File Now

name: readParametersFromFile, type: Trigger

Explicitly update parameters from file.

If Property File Cannot be Accessed

name: inOnFileNotFoundError, type: Enum, default: AbortWithError, deprecated name: inOnFileNotFound,inOnFileReadError

Describes what happens if the properties file cannot be found (accessed for reading). This does not include cases where there is something wrong with the file contents (e.g. json parsing errors), which will always result in ‘abort with error’.

Values:

Title Name Description
Use Original UseOriginal The original proposals from the input (if any) will be used unmodified. A warning will be printed to the console.
Keep Previous Setup KeepPreviousSetup The current setup visible in the text field will be used to update the processor’s proposals, and a warning will be printed to the console. Use this if the remote location may be at times unavailable.
Abort With Error AbortWithError The update will be aborted and an error will be reported. The output stays invalid.

Has Valid Input Processor

name: outHasValidInputProcessor, type: Bool, persistent: no, deprecated name: outHasValidInputTileProcessor

Indicates if a valid input processor object was detected. This also indicates whether the ‘original’ parameters come from a valid input properties object, or are just the default values.

Has Valid Input Properties

name: outHasValidInputProperties, type: Bool, persistent: no, deprecated name: outHasValidInputTileProcessorProperties,outHasValidInputTileProperties

Indicates if a valid input properties object was detected. This also indicates whether the ‘original’ parameters come from a valid input properties object, or are just some placeholder values.

Out Used Properties Json

name: outUsedPropertiesJson, type: String

String representing the JSON properties used to generate the output properties (i.e. the result of the input JSON file parsed and then dumped to JSON again).

In Bypass Mode

name: outIsBypassing, type: Bool, persistent: no

Indicates if the input properties object is bypassed to the output.

This happens only in very specific circumstances, which are:

  1. There is a valid input properties object
  2. If Property File Cannot be Accessed is set to Use Original
  3. Auto-Update JSON From File Before Output Update is enabled
  4. Update was pressed, but the input file could not be read

Used JSON Schema

name: outUsedPropertiesJsonSchemaFile, type: String, persistent: no

Path to the JSON schema that is used for validating the input file (and that can be used by the user to help editing, see ‘Details’ section.

Hidden Fields

doNotClearOnFailedUpdate

name: doNotClearOnFailedUpdate, type: Bool, persistent: no

Prevents automated clear after update failed. This does not affect status fields. It enables the developer to analyze module’s state after failure.

inRequireValidProcessor

name: inRequireValidProcessor, type: Bool, default: TRUE, deprecated name: inRequireValidTileClassifier,inRequireValidTileProcessor

If enabled, the module will refuse to update if no valid input processor is connected. Enable this if you are sure the input should be/contain a processor to detect errors early.

inRequireValidProperties

name: inRequireValidProperties, type: Bool, default: FALSE, deprecated name: inRequireValidTileProcessorProperties,inRequireValidTileProperties

If enabled, the module will refuse to update if no valid input properties object is connected. Enable this if you are sure the input should be/contain properties to detect errors early.