Metadata-Version: 2.4
Name: pyconfocal
Version: 0.1.0rc7
Summary: Protocol-first modular confocal microscopy acquisition and control
Keywords: confocal,microscopy,spectroscopy,instrument-control,scientific-instruments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: ui
Requires-Dist: PySide6>=6.6; extra == "ui"
Requires-Dist: pyqtgraph>=0.13; extra == "ui"
Provides-Extra: windows
Requires-Dist: PySide6>=6.6; extra == "windows"
Requires-Dist: pyqtgraph>=0.13; extra == "windows"
Requires-Dist: pyusb>=1.2; extra == "windows"
Requires-Dist: seabreeze[pyseabreeze]; extra == "windows"
Provides-Extra: hardware-pi
Requires-Dist: PIPython>=2.13; extra == "hardware-pi"
Provides-Extra: hardware-ni
Requires-Dist: nidaqmx>=1.0; extra == "hardware-ni"
Requires-Dist: nifpga; extra == "hardware-ni"
Provides-Extra: hardware-rf
Requires-Dist: pyvisa>=1.13; extra == "hardware-rf"
Provides-Extra: hardware-visa
Requires-Dist: pyvisa>=1.13; extra == "hardware-visa"
Provides-Extra: hardware-serial
Requires-Dist: pyserial>=3.5; extra == "hardware-serial"
Provides-Extra: hardware-usb
Requires-Dist: pyusb>=1.2; extra == "hardware-usb"
Provides-Extra: hardware-dotnet
Requires-Dist: pythonnet>=3.0; extra == "hardware-dotnet"
Provides-Extra: hardware-seabreeze
Requires-Dist: seabreeze[pyseabreeze]; extra == "hardware-seabreeze"
Provides-Extra: hardware-pco
Requires-Dist: pco; extra == "hardware-pco"
Provides-Extra: hardware-pvcam
Requires-Dist: pyvcam; extra == "hardware-pvcam"
Provides-Extra: hardware-basler
Requires-Dist: pypylon; extra == "hardware-basler"

# 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:

```bash
pip install pyconfocal
```

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

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

Other hardware integrations are opt-in, for example:

```bash
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:

```text
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:

```text
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

```text
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:

```text
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:

```bash
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

```bash
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.
