pyConfocal 0.1.0rc7

pyConfocal is a protocol-first modular confocal microscopy acquisition and control package. It modernizes the useful operator workflows of a legacy LabVIEW confocal-control program without silently removing supported experiment surfaces.

Install

Core package:

pip install pyconfocal

Windows operator package with Qt UI and the redistributable Ocean Optics SeaBreeze/PyUSB fallback:

py -m pip install "pyconfocal[windows]"
pyconfocal gui

Other hardware integrations are opt-in, for example:

pip install "pyconfocal[hardware-ni]"
pip install "pyconfocal[hardware-pi]"
pip install "pyconfocal[hardware-basler]"
pip install "pyconfocal[hardware-pco]"

Manufacturer runtimes/SDKs that are not redistributable through PyPI remain separate prerequisites. driver-discover and driver-doctor report what is available without silently promoting missing hardware to test data.

Operator workbench

The default center surfaces are:

• Scanning — XY confocal mapping from physical X/Y bounds and one common square-pixel pitch.
• Autofocus — local XY localization followed by an explicit Z sweep and focus memory.
• ODMR — RF frequency sweep against the count path.
• Saturation — configured level sweep against the count path.
• Laser Power — explicit static analog-output control.
• Pulse / AWG — visible PARTIAL surface while physical adapter support remains gated.
• Camera — optional scientific-camera capture/live view.
• Spectroscopy — optional integrated spectrum acquisition.
• Data — browse/reload autosaved runs and convert legacy data.
• Diagnostics — read-only backend/runtime status and migration evidence.

The Surfaces menu keeps every center surface reachable. Runtime Devices is read-only discovery/inventory, Hardware Setup is configuration, and the CPS monitor can be expanded without opening a second detector reader.

Persistent operator state

The workbench keeps these states visible:

Mode | Session | Physical verification | Owner

Autosave state is shown in the bottom-right status bar. Software support and physical verification remain separate facts: TEST-SIGNAL is non-physical, and LIVE remains non_verified until a concrete physical attach succeeds for that exact device identity.

Scanning

Scanning is planned from physical coordinates:

Reference: Relative to current XY | Absolute stage XY
X from / X to
Y from / Y to
Pitch X = Y (nm)
Integration / point

The UI derives Nx×Ny, total samples and nominal integration-only acquisition time. If an endpoint is not an integer multiple of the common pitch, the effective endpoint is explicitly snapped rather than silently changing one axis pitch.

Square-pixel invariant

dx = dy
screen X:Y physical scale = 1:1

A rectangular field of view therefore contains square pixels arranged over a rectangle. The Scan map is never stretched merely to fill unused UI space. Displayed and saved count data remains raw; there is no implicit background/reference subtraction.

Position and CPS

Motion and detector acquisition share one persistent session. XYZ position refreshes every 500 ms while idle. During Scanning/Autofocus, actual stage readback is streamed from the worker after moves.

The CPS alignment monitor uses the same detector session. Expand opens a larger resizable view of the same trace and pauses while another experiment owns the count path.

Ocean Optics / Ocean Insight spectrometers

The spectroscopy path supports automatic Ocean-family discovery with two layers:

1. OceanDirect when the vendor SDK is installed locally, including supported USB/network devices.
2. SeaBreeze/pyseabreeze as the redistributable USB/legacy fallback.

The driver does not require a hard-coded model choice: a unique discovered physical spectrometer can be selected automatically; multiple devices require an explicit serial/resource. OceanDirect itself is proprietary and is not bundled in the PyPI package.

Raw acquisition semantics are preserved: pyConfocal does not silently apply background subtraction, and OceanDirect electric-dark/nonlinearity correction is explicitly disabled by the integration layer where supported.

Hardware Setup

Configuration surfaces are:

Devices
Motion
Detector
Timing / DAQ
RF / ODMR
Analog Output
Pulse / AWG
Camera
Spectroscopy
Data

The Devices tab is read-only discovery. Saving configuration never connects, moves, arms, triggers, enables RF or writes analog output.

Modes

• REAL-OFFLINE — read-only discovery/status.
• TEST-SIGNAL — explicit deterministic/synthetic or in-memory test backends; never physical verification.
• LIVE-HARDWARE — configured physical adapters only; failures do not silently fall back to TEST-SIGNAL.

Driver layer

pyconfocal.drivers provides discovery, identity resolution, driver matching, attach, runtime introspection, semantic capability mapping, Driver Doctor diagnostics and per-device physical verification.

Useful commands:

pyconfocal driver-discover
pyconfocal driver-doctor
pyconfocal gui

A software-supported driver remains non_verified until a successful physical attach on the concrete device identity. Vendor emulators, simulation, replay and remote sources never create physical verification evidence.

Run from a source checkout

python -m venv .venv
. .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[ui,test]"
python -m pyconfocal gui

Validation status

0.1.0rc7 is a software/offline release candidate. The integrated Windows Server 2025 CI run completed 268 passed, 3 skipped, 7 subtests passed, produced the frozen Windows application, passed the frozen offscreen GUI self-test and uploaded the Windows package artifact. Physical Windows HIL remains a separate gate for actual motion, detector acquisition, RF/AO wiring, cameras, spectrometers and future Pulse/AWG adapters.