Edit online

Custom Scripting module

You can use this module to call a Python script during the acquisition sequence. You must have at your disposal python scripts, structured with a template similar to that of the applications included in the inscoper-scripts resource provided with this module. In this guide, you may select any script provided as part of this resource.

Python Environment Setup

Before running scripts, you must define which Python engine the software uses.

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

    display_settings_python

  3. Choose your environment:
    1. Use Built-In (recommended): Uses the Python version included with the installation. This contains standard image analysis packages.
    2. Use Custom: Select a local directory containing a specific python.exe.
      1. Critical Requirement: If using a custom environment (like Conda), you must ensure the package jep is installed, or the script will fail.
    3. Use System: Uses the global Python version installed on your OS.
  4. Restart I.I.S. for these changes to take effect.
Note on Installing Packages: If you need extra libraries in the Built-In environment:
  1. Open a console/terminal in the I.I.S. installation folder.
  2. Navigate to the python folder.
  3. Run: ./python.exe -m pip install <package_name>

Creating a New Script Application

  1. Go to the Acquisition tab and select MDA (Multi-Dimensional Acquisition).
  2. Expand the Python Script module and toggle Advanced on.
    Figure 1. Advanced Script importation tab

    script_advanced_options

    1. Click the “…” button (next to "Re-scan File") and browse for your .py file.
  3. Map Python Functions to I.I.S. Functions: You must tell the system which part of your code handles images and which part handles processing. Then you must map the script's arguments to I.I.S. hardware or settings.
    1. Step A: Image Provider: Select the function in your script that fetches images (e.g., fetch_images).
      1. Map Arguments: Pair the script variable new_image to the Type IMAGES. In practice this pattern allows the software to send the last acquired image to the script.
      2. Pair channel_index to INT and set a default value (0). Channel indices coincide with the order of the channels in the multi-channels dimension.
      Figure 2. Pair function arguments to valid types and default values

      script_function_import

    2. Step B: Processing Function: Select the function that analyzes the data (e.g., correlation_tracking).
      1. Map Arguments: Pair the script variable images to the Type IMAGES. This variable received the images selected by the image provider function when entering the processing function.
      2. Pair stage_x_id to SUBDEVICEID and set a default value to the name of your X axis subdevice. This variable tells explicitly the script the name of the X axis subdevice for this system.
      3. Pair stage_y_id to SUBDEVICEID and set a default value to the name of your Y axis subdevice.
      4. Pair stage_z_id to SUBDEVICEID and set a default value to the name of your focus axis subdevice.
      5. Pair correct_z to BOOL and set a default value.
      6. Pair focus_on_motion to BOOL and set a default value.
      7. Pair show_plots to BOOL and set a default value.
      8. Pair acquisition_context to IIS_CONTEXT and set a default value. The IIS context allows the script to useful software functions (e.g. send a matplotlib figure to the software).
    3. Step C: Device Control: Set the Device Control subdevices that should match with the outputs of the processing function. If the function does not update devices, it should not return anything and this part should be left blank. In the tracking example, add your three subdevices (stage_x_id, stage_y_id, stage_z_id).
  4. Save as Template
    1. Once mapped, click Save as Application Template.
    2. A pop-up will appear. Tick the boxes for parameters you want visible to the end-user.
      Figure 3. Generate an application template after importing a script

      script_application_template

    3. Unticked parameters will be hidden and locked.

If your script outputs graphs or logs, you need to configure the display panel.

  1. Toggle Expert Mode (Top-right corner).
  2. In the Data Processing and Charts section, click Switch to Data Processor.
  3. Add the Console: Drag and drop the Feedback Console chart to the right panel. This displays Python print() statements.
  4. Add Charts: If your script uses display_figure(..., processor_name='name'):
    • Drag a Feedback Chart to the panel.
    • Crucial Step: Rename this chart to match the processor_name defined in your Python script header (e.g., check the DATA_PROCESSOR variable in your code).
  5. Name this configuration (e.g., "tracking_charts") and click Add.
  6. Click Switch to Dimensions to return to the main view.

Running the Experiment

Once the template is saved, daily operation is simple.

  1. Go to the Application tab.
  2. Select your new template (e.g., "tracking").
  3. Adjust the visible control parameters.
  4. Ensure Data Processing and Charts is set to the layout you created in Part 3.
  5. Press Start Acquisition.
Figure 4. Typical application view for the correlation_tracking_withZ.py script

script_tracking

Figure 5. Typical application view for the single_cell_screening.py script

script_screening