Open the visual walkthrough for the workflow, output locations, and end-of-run options.
zenapi_guidedacq.py segments an existing overview CZI, converts detected objects into tile regions, and runs a live ZEN detail scan for each result row. The overview acquisition is currently simulated with a saved image; the detail acquisitions are real microscope operations.
pixi_smartmic:default environment as described in
the workshop README.my_config.ini beside the script.
Keep credentials private. This script currently selects that filename,
not config.ini.data/OverViewScan.czi under the workshop root, or
change filepath_overview inside main().ZEN_API_GuidedAcq available in ZEN, or change
detail_exp. Prepare a suitable tile experiment and check its acquisition
settings before running.Run from the workshop root, replacing the example checkout path if necessary:
cd /d "F:\Pixi_Projects\zen_czi\smartmicroscopy"
pixi run --locked -e default python "examples\control_zen_via_zenapi\zenapi_guidedacq.py"
pixi_smartmic is the workspace name; default is the environment name
passed to -e. No Conda activation or VS Code interpreter selection is
needed. Use this workshop environment, not the separate zen-pixi-workspace.
The script has no command-line argument parser. Edit its configuration and
the final asyncio.run(main(...)) call to change behavior. Do not pass
--move-results or --show-summary-plot: those CLI flags do not exist.
The current launch call enables moving results and the final comparison:
asyncio.run(main(move_results=True, show_summary_plot=True))
The parameters of main() are:
region_type="polygon": use object polygons. Alternatives are "rectangle"
and "ellipse", derived from object bounding boxes.open_detail=False: when True, open every completed detail CZI in ZEN
from its final location.move_results=False: when True, move the whole run folder under the
workshop’s results/guided_acq. The launch call sets this to True.show_summary_plot=False: when True, show the overview, segmentation
overlay, and first detail scan side by side. The launch call sets this
to True. Close the window to let the script finish.Other settings are inside main():
show_overview=True opens the saved overview in ZEN; it does not acquire
a new overview. The gca_run_overviewscan() invocation is commented out.show_segresults=True exports the overview with polygon outlines as PNG.verbose=False; enabling it also saves a cloned detail experiment as
<detail_exp>_cloned with override allowed. That experiment remains in
ZEN’s experiment storage, not the run results folder.0, Gaussian filtering with size 7,
triangle thresholding, and minimum object size 100000. The call also
passes max_holesize=1000; see
processing_tools.py for its processing implementation.The stage Z value is the median overview planetable Z value. Polygon and bounding-box stage coordinates are converted from micrometres to metres for the ZEN tile-region requests.
The overview is a saved input; the detail-scan loop performs live acquisition. The chart shows the normal workflow and the destination-collision branch. Other acquisition or filesystem errors propagate and stop the run.
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
ZEN services include experiment acquisition, tile-region operations, and TCP/IP image-opening commands. File reads and writes are shown separately. An exception stops execution; the messages below the collision branch apply only when gathering and optional relocation succeed.
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
The run starts under ZEN’s configured image output directory:
<ZEN image output directory>\
GA_<UTC date>_<UTC time>\
OverViewScan_OV.czi
OverViewScan_OV.png
OverViewScan_seg.czi
OverViewScan_seg.csv
zenapi_detail_0.czi
zenapi_detail_1.czi
...
Names beginning with OverViewScan follow the input overview’s basename.
The PNG is created only when show_segresults=True. Detail files are
generated for the detected result rows, so their count varies.
When move_results=True, the complete run folder moves to:
F:\Pixi_Projects\zen_czi\smartmicroscopy\results\guided_acq\GA_<UTC date>_<UTC time>\
The destination is derived from the workshop root, so it follows your checkout
if you put the workshop elsewhere. When False, the folder stays under ZEN’s
image output directory. The source overview in data is copied, not moved.
Unrelated files in ZEN’s output directory are not collected.
An existing destination run folder raises FileExistsError; it is not
overwritten, and the newly gathered files remain at the ZEN-side location.
Relocation runs only after successful acquisition. If acquisition or moving
fails, inspect the logged paths for partial results; there is no automatic
failure cleanup or rollback.
The final plot reads channel 0 and displays:
filepath_overview.If there is no detail scan, the last panel says No detail scans acquired. The comparison window is interactive and blocks until closed. It is not automatically saved; the earlier overlay PNG is a separate export.
main().The visual walkthrough describes source behavior, not a recorded hardware run.