Python Script Library Reference¶

This page is the reference for the pre-built Python scripts in the inscoper_scripts library. For each script, it lists the entry points, the required data processors, the files written to disk, and the metadata injected into the acquisition.

Smart Microscopy Scripts¶

Screening¶

Single-cell screening (deep learning)¶

• Script name: single_cell_screening.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: detect_single_cells
• Required data processors: segmentation, crop
• Description: Automatically screens and segments individual cells within an acquisition sequence. It uses a deep learning segmentation algorithm (Cellpose) to detect isolated single cells in a selected fluorescence channel, crops each cell, and writes the crops to disk. The interface displays the per-cell measurements.
• Disk output: crops/*.json, crops/*.tif
• Injected metadata: NBR_OF_CELLS, MEAN_CELL_AREA, MEDIAN_CELL_AREA, ROI_POINTS

Single-cell screening (thresholding)¶

• Script name: single_cell_screening_no_ai.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: detect_single_cells, run_detect_single_cells_async
• Required data processors: segmentation, crop
• Description: Equivalent to single_cell_screening.py, but segments cells with classical image processing (intensity thresholding and watershed transforms) instead of deep learning. This is faster, but less reliable on confluent or cluttered fields.
• Disk output: crops/*.json, crops/*.tif
• Injected metadata: NBR_OF_CELLS, MEAN_CELL_AREA, MEDIAN_CELL_AREA, ROI_POINTS

Cell tracking¶

Cell population tracking¶

• Script name: cell_population_tracking.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: cell_population_tracking
• Required data processors: segmentation, tracks, timeseries
• Description: Tracks a population of cells over time in a 2D or 3D sequence. It segments each frame (with Cellpose or thresholding), links cells between frames to build tracks, and computes running population metrics (mean and median velocity or intensity). It includes heuristics for cells that are temporarily lost and for global stage drift.
• Disk output: tracks.csv (if enabled)
• Injected metadata: NBR_OF_CELLS

Stage-based tracking¶

Correlation tracking of a target object¶

• Script name: correlation_tracking_withZ.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: correlation_tracking
• Required data processors: motion_difference, motion_mask
• Description: Tracks an object in 3D using phase correlation. It computes the XYZ shift between the current and previous timepoints and updates the stage position to keep the object centered in the field of view. It also corrects the Z position by locating the best focus plane, and can estimate sub-pixel shifts.
• Disk output: tracks.csv (if an export path is set)
• Injected metadata: None. The computed shifts are written to the logs.

Photomanipulation¶

FRAP and photo-activation¶

• Script name: roi_manipulation.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: compute_roi
• Required data processors: image, roi
• Description: Shows how to define and manipulate regions of interest (ROIs) on an incoming image array. It creates rectangles, circles, and lines, and can fire the laser on demand over the ROI geometry. Use it as a starting point for automated FRAP or photo-activation workflows.
• Disk output: None
• Injected metadata: None

Focus¶

Software autofocus¶

• Script name: autofocus.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: auto_focus
• Required data processors: focus (implicit)
• Description: Determines the best Z position from a Z-stack acquired during the sequence. It measures image sharpness (contrast gradients) across the slices and returns the Z position of the sharpest focus plane. This provides software autofocus during a time-lapse without a hardware focus device.
• Disk output: None
• Injected metadata: None. The selected Z position is written to the logs.

Image correction¶

Background model¶

• Script name: background_model.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: correct_background
• Required data processors: background, normalized
• Description: Corrects the background illumination. At the first timepoint \(t_0\)$t_0$, it builds a background model (for example, the median intensity projection across several fields of view). At later timepoints, it applies that model to flat-field correct the incoming images. It can mask out cells and objects before building the model.
• Disk output: background.tif (the background model)
• Injected metadata: None

Templates¶

Demonstration workflow¶

• Script name: demo.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: find_most_eccentric_cell
• Required data processors: segmentation, crop
• Description: A demonstration script that chains background subtraction, Cellpose segmentation, feature extraction (finding the most eccentric cell), and a stage move onto that cell. Use it as an example of combining several API features in one sequence.
• Disk output: background.tif, crops/*.tif, crops/*.json
• Injected metadata: NBR_OF_CELLS

Python environment check¶

• Script name: test_python_env.py
• Entry points:
  • Image provider: fetch_images
  • Processing function: test_versions
• Required data processors: None
• Description: A diagnostic script that verifies the Python environment. It prints the installed TensorFlow version to the console, which confirms that the deep learning dependencies are installed and reachable from the software.
• Disk output: None
• Injected metadata: None

Type Hints for Interface Mapping¶

The type hints below declare your script parameters. The software uses them to generate the matching input widget in the interface.

• "images": The list of buffered input images passed to the script.
• "IIS_CONTEXT": The acquisition context object. It gives access to the microscope hardware state and to the execution methods (e.g., fireOnDemand()).
• "SubDeviceId": The identifier of a hardware sub-device (e.g., "Stage X", "Laser 488nm"). The interface provides a dropdown list limited to the connected devices.
• "channel": Represents a channel configuration object.
• Literal["val1", "val2"]: Creates a dropdown list containing only the given string options.
• List[Literal[...]]: Creates a multi-selection checkable list of the given options.
• Path: A file or directory path. The interface provides a file or directory picker.
• bool: Creates a checkbox or toggle switch.
• int, float, Number: Create numeric input fields.

Skipping the Processing Function¶

To skip processing for a given acquisition event (for example, to analyze only the last slice of a Z-stack, or only selected timepoints), return an empty list from fetch_images: [].

When fetch_images returns [], the software does not call the processing function (e.g., detect_single_cells) for that event.

Example (_image_provider_functions.py):

def fetch_zstack(new_image, channel_index: int = 0) -> List[Dict]:
    # ... preliminary metadata extraction ...
    current_focus = meta_dict.get('focusIndex', 0)
    size_z = meta_dict.get('focusSize', 1)

    # Process only on the last Z slice
    if current_focus != (size_z - 1):
        return [] # An empty list skips the processing function

    # ... otherwise construct and return the required image list ...

This pattern restricts expensive operations, such as neural network inference, to the events where the required data (here, the complete Z-stack) is in memory.