Calling Scripts in Inscoper I.S.¶

The Python Scripting module enables the execution of custom Python algorithms within an MDA sequence.

To ensure compatibility, scripts must adhere to the templates provided in the inscoper-scripts local package. You may use the included sample scripts for testing.

Python Environment Setup¶

Before executing any script, you must explicitly specify which Python environment the software will utilize for its calculations.

1. Navigate to Settings > Display Settings.
2. Select Script Settings from the left-hand navigation pane.

3. Choose your preferred execution environment:

   • Use Built-In (recommended): Utilizes the stable, integrated Python environment bundled securely with the software installation. This environment comes pre-loaded with standard (non-GPU) data science and essential image analysis packages.
   • Use Custom: Point the software to a specific, user-managed local Python executable (python.exe). Note: This advanced route explicitly requires the jep library (see warning below).
   • Use System: Automatically detects and utilizes the global Python installation currently defined in your operating system's PATH variables.

4. Restart Inscoper I.S. to fully instantiate the environment changes.

pip install jep

Importing and Mapping a Script Application¶

Once your Python interpreter is set, you can load your script into the MDA sequence definition.

1. Navigate to the central Acquisition tab and select the MDA (Multi-Dimensional Acquisition) sub-tab.
2. Expand the Python Script module panel and toggle the Advanced switch to enable this mode.
3. Click the "..." button adjacent to Re-scan File, browse to the inscoper-scripts local package, and select your specific .py script.

1. Map Python functions to I.I.S. parameters. Define which function handles image fetching (image provider) and which handles heavy-computations (processing), then map the functions' arguments to the proper type and value.

   1. Step A (image provider): Select the script function responsible for fetching images (e.g., fetch_images).
      • Map Arguments: Map the script variable new_image to the IMAGES data type. This allows the software to pass the most recently acquired image to your script.
      • Map channel_index to INT and assign a default value (e.g., 0). These channel indices correspond to their order within the Multi-channels dimension.

   

   1. Step B (processing function): Select the function responsible for data analysis (e.g., correlation_tracking).

      • Map Arguments: Map the images variable to the IMAGES type. This variable receives the images curated by the Image Provider function.
      • Map hardware identifiers (e.g., stage_x_id, stage_y_id, stage_z_id) to the SUBDEVICEID type and set default values matching your hardware.
      • Map logical switches (e.g., correct_z, focus_on_motion, show_plots) to BOOL and define initial states.
      • Map acquisition_context to IIS_CONTEXT. This provides access to internal software APIs, such as rendering matplotlib figures in the UI (see how to use the IIS Context Engine).

   2. Step C (device control): Declare any hardware sub-devices that will be updated by your processing function's outputs (it should match symmetrically with the return values of the processing function, e.g. if the processing function returns a tuple of new 'x', 'y', and 'z' values, then you should declare the X, Y, and Z sub-devices here). If your function only logs data without modifying hardware, leave this blank.

2. Save as a Reusable Template

   1. Once mapping is complete, click Save as Application Template.
   2. In the dialog box, select which parameters should remain editable by the user.
   3. Unselected parameters will be hardcoded to their default values and hidden from the UI.

   

Configuring the UI for Script Visualization¶

If your Python script is designed to output interactive visual graphs (via matplotlib) or text logs to the console, you must configure a data processor to receive this data.

1. Enable Expert Mode using the top-right interface toggle.
2. Within the Data Processing and Charts operational section, click Switch to Data Processor.
3. Enable Console Logging: Drag the Feedback Console module from the library into the right-hand panel workspace. This active console captures and displays all standard Python print() logging outputs.

4. Enable Graphical Output: If your script mathematically computes and pushes a figure using display_figure(..., processor_name='name'):

   • Drag a Feedback Chart module into the right-hand panel workspace.
   • Crucial: You must manually rename this chart element within the UI to exactly match the target processor_name string defined within your underlying Python script.

5. Save this complete charting layout with a descriptive, logical name and click Add.

6. Click Switch to Dimensions to return to the standard sequence configuration window.

Executing the Scripted Experiment¶

Executing a templated script is designed for operational simplicity.

1. Navigate to the Application tab.
2. Select your saved template from the dropdown list.
3. Adjust any exposed control parameters.
4. Verify that the Data Processing and Charts menu selection matches the layout required by the script.
5. Click Start Acquisition to initiate the sequence.