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

derive Zcopy inputiterate resultsyesreplace regionsacquirecontinuenocheck optionfalsetrueyesnouse final pathsuse final pathscheck optionfalsetrueclose plotRead saved overview and stagemetadataSegment overview and writelabels / CSVCopy overview and optionallyexport overlay PNGNext object?Load and clone detailexperimentClear tile regions and addselected regionAwait live detail scanClose API channel and gatherdetail CZIsmove_results?Keep run in ZEN outputdirectoryDestination exists?Raise FileExistsError; keepsource runMove whole run intoresults/guided_acqOptionally open detail images inZENshow_summary_plot?FinishShow overview, overlay, andfirst detailderive Zcopy inputiterate resultsyesreplace regionsacquirecontinuenocheck optionfalsetrueyesnouse final pathsuse final pathscheck optionfalsetrueclose plotRead saved overview and stagemetadataSegment overview and writelabels / CSVCopy overview and optionallyexport overlay PNGNext object?Load and clone detailexperimentClear tile regions and addselected regionAwait live detail scanClose API channel and gatherdetail CZIsmove_results?Keep run in ZEN outputdirectoryDestination exists?Raise FileExistsError; keepsource runMove whole run intoresults/guided_acqOptionally open detail images inZENshow_summary_plot?FinishShow overview, overlay, andfirst detail
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.

opt[show_overview]opt[show_segresults]loop[Each result row][Destination absent]alt[Destination exists]opt[move_results]opt[open_detail]opt[show_summary_plot]Launch inpixi_smartmicdefaultOpen saved overview through TCP/IPRead overviewplanetableStage Z valuesInitialize API and get image output pathImage output directorySegment saved overviewWrite segmentedCZI and object CSVObject results and polygoncoordinatesCopy overview intorun folderExport overview with polygon outlinesSave overlay PNGLoad and clone detail experimentClear tile regions and add selected regionRun detail experiment and await completionSave detail CZI in ZEN outputdirectoryCompleted output nameClose API channelMove detail CZIsinto run folderCheck finaldestinationMove run folderunderresults/guided_acqOpen detail images from final paths through TCP/IPRead overview andfirst detail ifavailableShow overview, segmentation overlay, first detailClose comparison windowFinishRaise FileExistsErrorand stop - source runstaysContinue only if gathering and optional relocation succeedOperatorGuidedacquisitionLocal filesSegmentationZEN servicesMatplotlibOperatorGuidedacquisitionLocal filesSegmentationZEN servicesMatplotlibopt[show_overview]opt[show_segresults]loop[Each result row][Destinationabsent]alt[Destinationexists]opt[move_results]opt[open_detail]opt[show_summary_plot]Launch inpixi_smartmicdefaultOpen saved overview through TCP/IPReadoverviewplanetableStage ZvaluesInitialize API and get image output pathImage output directorySegment saved overviewWritesegmentedCZI andobject CSVObject results andpolygon coordinatesCopyoverviewinto runfolderExport overview with polygon outlinesSave overlay PNGLoad and clone detail experimentClear tile regions and add selected regionRun detail experiment and awaitcompletionSave detail CZI in ZENoutput directoryCompleted output nameClose API channelMovedetailCZIs intorun folderCheckfinaldestinationMove runfolderunderresults/guided_acqOpen detail images from final pathsthrough TCP/IPReadoverviewand firstdetail ifavailableShow overview, segmentation overlay, first detailClose comparison windowFinishRaiseFileExistsErrorand stop -source runstaysContinue only if gathering and optional relocation succeedOperatorGuidedacquisitionLocalfilesSegmentationZENservicesMatplotlibOperatorGuidedacquisitionLocalfilesSegmentationZENservicesMatplotlib
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.