Designing an Operation Interface

Once a tool has been selected, the next step is to design the interface for the operation. The interface defines the parameters, inputs, and outputs of the operation, allowing Stage2 to integrate and execute the tool within workflows.

To learn more about the different parts of operations, you can check out the Operations docs

---

Tools for Building an Operation Interface

Stage2 provides multiple tools to help construct an operation interface:

• Foundry: (Section coming soon) A user-friendly tool for designing operation interfaces.
• Stage2 Webclient: Refer to the Operation Modal section for more details.
• Raw JSON Definition: Allows complete control over the operation interface by directly defining it in JSON.

For this example, we will define the Preprocess Image operation interface using raw JSON for the sake of low-level clarity.

---

Defining the Interface

Operation Overview

Operation Name: Preprocess Image
Description: This operation takes a raw image as input and preprocesses it by converting to grayscale, cropping to a region of interest, enhancing contrast, and normalizing pixel values. The result is a processed image ready for machine learning workflows.

---

Parameters

Parameters define how users can configure the operation. For the Preprocess Image operation, the parameters are as follows:

1. Automatic ROI (autoROI)

   • Type: Boolean
   • Reasoning: This option leverages ImageMagick's built-in capabilities for automatic ROI detection, simplifying preprocessing for users who do not need precise manual cropping.
   • Description: If set to true, the operation will automatically select a region of interest for cropping.
   • Restrictions: Defaults to false if not provided.

2. Region of Interest (roi) (Optional)

   • Type: Array of integers (e.g., [x1, y1, x2, y2])
   • Reasoning: An array of integers is appropriate for defining pixel-based coordinates.
   • Description: Defines the cropping area using coordinates for the top-left and bottom-right corners. This parameter will have no effect if autoROI is set to true.
   • Restrictions: Values must be positive

3. Contrast Factor (contrastFactor) (Optional)

   • Type: Number
   • Reasoning: A numeric multiplier gives users granular control over contrast adjustments.
   • Description: Multiplier to adjust image contrast.
   • Restrictions: Must be a positive number (minimum 0.1) to avoid unintended results.

4. Normalization Range (normalizationRange) (Optional)

   • Type: Array of two numbers (e.g., [0, 1])
   • Reasoning: Normalization requires defining a range, and an array of numbers is concise and clear.
   • Description: Specifies the range for normalizing pixel values.
   • Restrictions: Array must contain exactly two numbers, with the first less than the second.
     To take pressure off the end user to select values, we can define the 2 most common normalization ranges as choices for this parameter
     • [0, 1] --> This is common when the downstream model expects pixel values as normalized fractions
     • [-1, 1] --> This range is often used in neural networks where the activation functions naturally operate ina symmetric range

---

Inputs and Outputs

Inputs:

• A single raw image file

Output:

• A processed image file

---

Complete Operation Interface

Below is the JSON representation of the operation interface:

{
  "name": "Preprocess Image",
  "description": "This operation takes a raw image as input and preprocesses it by converting to grayscale, cropping to a region of interest, enhancing contrast, and normalizing pixel values. The result is a processed image ready for machine learning workflows.",
  "family": "compute",
  "category": undefined,
  "thumbnail": "image_transform.png",
  "parameters": {
    "Automatic ROI": {
      "type": "boolean",
      "description": "If set to true, the operation will automatically select a region of interest for cropping.",
      "nullable": true,
      "defaultValue": false
    },
    "Region of Interest": {
      "type": "array",
      "description": "Defines the cropping area using coordinates for the top-left and bottom-right corners. This parameter will have no effect if 'Automatic ROI' is set to true.",
      "nullable": true,
      "defaultValue": [0, 0, 0, 0],
      "elementType": {
        "type": "integer",
        "nullable": false,
        "defaultValue": 0
      },
      "minSize": 4,
      "maxSize": 4
    },
    "Contrast Factor": {
      "type": "number",
      "description": "Multiplier to adjust image contrast.",
      "nullable": true,
      "defaultValue": 1.0,
      "min": 0.1,
      "max": null // inf
    },
    "Normalization Range": {
      "type": "array",
      "description": "Specifies the range for normalizing pixel values.",
      "nullable": true,
      "defaultValue": [0, 1],
      "choices": [
        [0, 1],
        [-1, 1]
      ],
      "elementType": {
        "type": "number",
        "nullable": false,
        "defaultValue": 0
      },
      "minSize": 2, // could also be `null` since choices are defined
      "maxSize": 2 // could also be `null` since choices are defined
    }
  },
  "inputs": {
    "Raw Image File": {
      "multiplicity": {
        "min": 1, // must accept a minimum of one input
        "max": 1  // cannot accept more than one input
      }
    }
  },
  "output":{} // declare there is an output
}