ZEN-API / guided microscopy

A saved overview guides live detail scans

Segment the overview, acquire each selected region, then collect the run and compare its images.

Source walkthrough · zenapi_guidedacq.py · 12 November 2026 · not a hardware-run record

  1. READ / saved inputOverviewdata/OverViewScan.cziRead stage metadata; keep the source file.
  2. ANALYZE / local processingSegmentFilter, threshold, label objects, and derive stage-space regions.
  3. ACQUIRE / live microscopeDetail scansClone the experiment, clear regions, add one region, and await each scan.
  4. COLLECT / after successRun folderGather detail CZIs; optionally move the complete folder into workshop results.
  5. INSPECT / optionalCompareShow the original overview, segmentation overlay, and first detail scan.
  1. The script reads a saved overview; the overview acquisition call is commented out.
  2. Segmentation results define the stage regions used for detail acquisition.
  3. Each result row starts a real detail scan through ZEN-API.
  4. Only after successful acquisition does the script gather and optionally relocate the run.
  5. The final comparison uses the detail scan at its final location.
Fig. 1The overview is simulated from a file, but the detail scans operate the microscope.

Check the sample and stage alignment first. The saved overview supplies coordinates and a median Z position for live acquisition.

The launch call enables collection and comparison

Function defaults

Leave outputs in ZEN storage

move_results=False
show_summary_plot=False
open_detail=False

No final comparison unless requested.

Current script launch

Move outputs and show the plot

move_results=True
show_summary_plot=True
open_detail=False

Close the comparison window to finish.

Fig. 2The executable launch overrides two function defaults; ZEN detail-image opening remains off.
cd /d "F:\Pixi_Projects\zen_czi\smartmicroscopy"
pixi run --locked -e default python "examples\control_zen_via_zenapi\zenapi_guidedacq.py"

Use CMD from the workshop root. The workspace is pixi_smartmic; the environment is default. Configure my_config.ini and the detail experiment ZEN_API_GuidedAcq before running. Options are Python parameters, not CLI flags.

One run folder carries the generated files

WORKING LOCATION

ZEN image output directory

GA_<UTC date>_<UTC time>/
  • Overview copy: OverViewScan_OV.czi
  • Overlay preview: OverViewScan_OV.png
  • Label image: OverViewScan_seg.czi
  • Object table: OverViewScan_seg.csv
  • Detail images: zenapi_detail_<id>.czi
The PNG depends on show_segresults. The original overview stays in data.
FINAL LOCATION / move_results=True

Workshop results

results/guided_acq/GA_<UTC date>_<UTC time>/

The complete working folder moves here after acquisition. Detail-image opening and the summary use the final paths.

If disabled: the folder stays under ZEN's image output directory.

If the destination exists: raise FileExistsError and leave the new run at the source.

Unrelated output files and verbose-mode saved experiment definitions are not collected.
Fig. 3Relocation moves the gathered run folder, not the source overview or unrelated ZEN files.

The comparison shows context, boundaries, and detail

LEFT PANEL

Overview

Read channel zero from filepath_overview.

Original image context.

MIDDLE PANEL

Segmentation

Display the same overview and draw detected polygon outlines.

Not the label-mask CZI.

RIGHT PANEL

First detail

Read channel zero from the first acquired detail CZI.

If absent: No detail scans acquired.

Fig. 4The final window is a side-by-side comparison, not an automatically saved summary image.

The earlier overlay PNG is exported separately. If acquisition or moving fails, inspect the working paths for partial files; there is no automatic rollback.

The acquisition loop finishes before result relocation

flowchart TD
    A["Read saved overview and stage metadata"] -->|derive Z| B["Segment overview and write labels / CSV"]
    B -->|copy input| C["Copy overview and optionally export overlay PNG"]
    C -->|iterate results| D{"Next object?"}
    D -->|yes| E["Load and clone detail experiment"]
    E -->|replace regions| F["Clear tile regions and add selected region"]
    F -->|acquire| G["Await live detail scan"]
    G -->|continue| D
    D -->|no| H["Close API channel and gather detail CZIs"]
    H -->|check option| I{"move_results?"}
    I -->|false| J["Keep run in ZEN output directory"]
    I -->|true| K{"Destination exists?"}
    K -->|yes| L["Raise FileExistsError; keep source run"]
    K -->|no| M["Move whole run into results/guided_acq"]
    J -->|use final paths| N["Optionally open detail images in ZEN"]
    M -->|use final paths| N
    N -->|check option| O{"show_summary_plot?"}
    O -->|false| P["Finish"]
    O -->|true| Q["Show overview, overlay, and first detail"]
    Q -->|close plot| P
Fig. 5Each detected object triggers a live detail scan; output relocation and comparison follow successful acquisition.

Editable flowchart source. Other acquisition and filesystem errors propagate and stop the workflow.

sequenceDiagram
    actor User as Operator
    participant App as Guided acquisition
    participant Files as Local files
    participant Seg as Segmentation
    participant ZEN as ZEN services
    participant Plot as Matplotlib
    User->>App: Launch in pixi_smartmic default
    opt show_overview
        App->>ZEN: Open saved overview through TCP/IP
    end
    App->>Files: Read overview planetable
    Files-->>App: Stage Z values
    App->>ZEN: Initialize API and get image output path
    ZEN-->>App: Image output directory
    App->>Seg: Segment saved overview
    Seg->>Files: Write segmented CZI and object CSV
    Seg-->>App: Object results and polygon coordinates
    App->>Files: Copy overview into run folder
    opt show_segresults
        App->>Plot: Export overview with polygon outlines
        Plot->>Files: Save overlay PNG
    end
    loop Each result row
        App->>ZEN: Load and clone detail experiment
        App->>ZEN: Clear tile regions and add selected region
        App->>ZEN: Run detail experiment and await completion
        ZEN->>Files: Save detail CZI in ZEN output directory
        ZEN-->>App: Completed output name
    end
    App->>ZEN: Close API channel
    App->>Files: Move detail CZIs into run folder
    opt move_results
        App->>Files: Check final destination
        alt Destination exists
            Note over App,Files: Raise FileExistsError and stop - source run stays
        else Destination absent
            App->>Files: Move run folder under results/guided_acq
        end
    end
    Note over App,Plot: Continue only if gathering and optional relocation succeed
    opt open_detail
        App->>ZEN: Open detail images from final paths through TCP/IP
    end
    opt show_summary_plot
        App->>Files: Read overview and first detail if available
        App->>Plot: Show overview, segmentation overlay, first detail
        User->>Plot: Close comparison window
    end
    App-->>User: Finish
Fig. 6ZEN acquires and saves each detail scan before the script gathers files and opens the optional comparison.

Editable sequence source. Messages after the collision branch apply only when gathering and optional relocation succeed.

Sources and operating instructions

Dedicated README: setup, settings, outputs, and troubleshooting

zenapi_guidedacq.py: main, gca_run_detailscan, show_segmentation, and show_acquisition_summary.

processing_tools.py: segment_czi creates the segmented CZI and object CSV.

pixi.toml: workshop workspace and environment.