Python Script Library Reference¶

This document provides a comprehensive technical reference for the pre-built Python scripts available within the inscoper_scripts foundational library. It explicitly details the required entry points, utilized data processors, primary data outputs, and generated metadata for each core application.

Core Smart Microscopy Applications¶

Automated Screening Scripts¶

Single-cell Screening (AI-Driven)¶

• Script Name: single_cell_screening.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: detect_single_cells
• Required Data Processors: segmentation, crop
• Functional Description: Automatically screens and segments individual cells within an acquisition sequence. It utilizes a deep learning segmentation algorithm (Cellpose) to detect isolated single cells from a designated fluorescence channel, generates targeted single-cell crops, and exports them directly to disk. The UI dynamically displays single-cell geometric 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
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: detect_single_cells, run_detect_single_cells_async
• Required Data Processors: segmentation, crop
• Functional Description: Operationally equivalent to single_cell_screening.py, but utilizes classical image processing techniques (intensity thresholding, watershed transforms) rather than deep learning for cellular segmentation. This approach is faster but potentially less robust in confluent or complex scenarios.
• Disk Output: crops/*.json, crops/*.tif
• Injected Metadata: NBR_OF_CELLS, MEAN_CELL_AREA, MEDIAN_CELL_AREA, ROI_POINTS

Cellular Tracking Workflows¶

Single-cell Population Tracking¶

• Script Name: cell_population_tracking.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: cell_population_tracking
• Required Data Processors: segmentation, tracks, timeseries
• Functional Description: Dynamically tracks a population of cells over time throughout a 2D or 3D sequence. It performs frame-by-frame segmentation (using Cellpose or thresholding), links identified cells between frames to construct kinetic tracks, and computes running ensemble metrics (mean/median velocities or intensities) for the population. It features heuristics for tracking temporarily lost cells and compensating for global stage drift.
• Disk Output: tracks.csv (if explicitly enabled in context logic)
• Injected Metadata: NBR_OF_CELLS

Mechanical Hardware Tracking¶

Correlative Hardware Tracking of a Target Object¶

• Script Name: correlation_tracking_withZ.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: correlation_tracking
• Required Data Processors: motion_difference, motion_mask
• Functional Description: Tracks a targeted sample object in 3D space using phase correlation. It computes the XYZ optical shift between the current and preceding timepoints, generating real-time stage position updates to maintain the sample centered within the field of view. It supports corrective Z-axis positioning via determination of the optimal focus plane and can deploy estimation for sub-pixel shift calculations.
• Disk Output: tracks.csv (if a valid data export path is actively defined)
• Injected Metadata: Calculated vector shift values are written to runtime logs/console.

Photomanipulation Integration¶

Active FRAP / Photo-activation¶

• Script Name: roi_manipulation.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: compute_roi
• Required Data Processors: image, roi
• Functional Description: Demonstrates how to programmatically define, generate, and manipulate spatial Regions of Interest (ROIs) on an incoming image array. It creates geometric shapes (Rectangles, Circles, Lines) and can trigger a "fire-on-demand" targeted laser action on the ROI geometry, useful for developing automated FRAP or photo-activation workflows.
• Disk Output: None
• Injected Metadata: None

Focus Management¶

Algorithmic Autofocus¶

• Script Name: autofocus.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: auto_focus
• Required Data Processors: focus (implicit)
• Functional Description: Calculates the optimal Z-focus parameter from a streaming Z-stack acquisition. It analyzes relative image sharpness (contrast gradients) across the Z-slices and returns the Z-position of the sharpest focal plane. This allows for closed-loop software autofocus during time-lapse experiments without relying on hardware focus devices.
• Disk Output: None
• Injected Metadata: The calculated optimal absolute Z position is exported to standard logs.

Image Optimization¶

Dynamic Background Sampling¶

• Script Name: background_model.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: correct_background
• Required Data Processors: background, normalized
• Functional Description: Performs background correction. At the initial timepoint $t_0$, it constructs a background illumination model (e.g., computing the median intensity projection across multiple fields of view). For subsequent timepoints, it applies this model to flat-field correct the incoming raw images. It can be optionally configured to mask out distinct cells/objects before computing the background model.
• Disk Output: background.tif (The generated master background model)
• Injected Metadata: None

Structural Scripts & Utilities¶

Developmental Templates¶

Comprehensive Demo Workflow¶

• Script Name: demo.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: find_most_eccentric_cell
• Required Data Processors: segmentation, crop
• Functional Description: A demonstration script showcasing an integrated workflow: initial background subtraction, subsequent Cellpose neural network segmentation, geometric feature extraction (identifying the most eccentric cell), and stage movement targeting that cell. It serves as an example of combining API features into a cohesive sequence.
• Disk Output: background.tif, crops/*.tif, crops/*.json
• Injected Metadata: NBR_OF_CELLS

Architecture Verification¶

• Script Name: test_python_env.py
• Architectural Entry Points:
  • Image Provider: fetch_images
  • Processing Logic: test_versions
• Required Data Processors: None
• Functional Description: A diagnostic script used to verify the Python environment configuration. It identifies and prints the installed TensorFlow library version to the console. Useful for asserting that neural network dependencies are installed and accessible by the software.
• Disk Output: None
• Injected Metadata: None

Explicit Type Hints for UI Mapping¶

This critical section enumerates the uniquely specialized type hints available for explicitly defining your script parameters. Utilizing these exact types ensures the software's user interface automatically generates and maps the correct input widgets.

• "images": Represents the memory-buffered list of input images ready to be processed by the script engine.
• "IIS_CONTEXT": Represents the overarching operational acquisition context object. This crucial object grants direct access to the live microscope hardware state and programmatic execution methods (e.g., fireOnDemand()).
• "SubDeviceId": Exact string representations corresponding to the physical IDs of specific hardware sub-devices (e.g., "Stage X", "Laser 488nm"). The interpreted UI will safely provide a constrained dropdown menu containing only available, connected devices.
• "channel": Represents a channel configuration object.
• Literal["val1", "val2"]: Automatically creates a constrained dropdown selection menu populated exclusively with the explicitly specified string options.
• List[Literal[...]]: Automatically creates a multi-select, checkable list containing the specified enumeration options.
• Path: Represents a standard system file/directory path. The interpreted UI automatically provides a robust graphical file/directory picker dialog.
• bool: Generates a standard boolean checkbox or toggle switch (True/False).
• int, float, Number: Generates robust numeric input fields.

Advanced: Skipping Processing Execution¶

To optimize computational overhead and deliberately skip processing for a specific acquisition event (e.g., executing analysis only on the absolute last optical slice of a thick Z-stack, or only at highly specific chronological timepoints), the fetch_images operational function must return an definitively empty list: [].

When fetch_images is mathematically evaluated to return [], the overarching system architecture completely bypasses invoking the main, computationally heavy processing function (e.g., detect_single_cells).

Example Logic Structure (_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)

    # Architectural Gate: Only process if we have mechanically reached the final Z-slice
    if current_focus != (size_z - 1):
        return [] # Return empty list, bypassing processing

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

This specific design pattern guarantees that highly expensive computational evaluations (like neural network inference) run exclusively when the strictly necessary data (e.g., the fully acquired, complete Z-stack) is fully available in system memory.