dirigo 0.3.8__tar.gz

dirigo-0.3.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Massachusetts Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dirigo-0.3.8/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: dirigo
+Version: 0.3.8
+Summary: Dirigo is an extensible backend for scientific image acquisition
+Author-email: "T. D. Weber" <tweber@mit.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/dirigo-developers/dirigo
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba
+Requires-Dist: scipy
+Requires-Dist: toml
+Requires-Dist: platformdirs
+Requires-Dist: tifffile
+Requires-Dist: nidaqmx
+Dynamic: license-file
+
+# Dirigo
+![PyPI](https://img.shields.io/pypi/v/dirigo)
+[![Documentation Status](https://readthedocs.org/projects/dirigo/badge/?version=latest)](https://dirigo.readthedocs.io/en/latest/?badge=latest)
+
+**Dirigo** is an extensible, high-performance backend for scientific image acquisition, designed with high-speed laser scanning microscopy in mind but adaptable to a wide range of medium- to high-complexity imaging systems.
+
+Dirigo separates hardware control, acquisition logic, and user interface, making it easy to:
+
+- Add new hardware via plugin drivers that implement generic device interfaces (digitizers, scanners, stages, cameras, etc.)
+
+- Reconfigure data acquisition and processing pipelines using a Worker/publisher–subscriber model
+
+- Integrate adaptive acquisition strategies through feedback loops between processing and control
+
+- Build custom GUIs or integrate with existing tools via a clean API (a reference GUI is available as a [separate package](https://github.com/dirigo-developers/dirigo-gui))
+
+Performance-critical operations are accelerated with [Numba](https://numba.pydata.org/) JIT compilation, releasing the GIL during execution and enabling parallel/vectorized processing.
+
+Dirigo follows a modular, package-oriented architecture: almost all components—hardware drivers, processing modules, GUIs—are separate Python packages that can be developed, installed, and updated independently.
+
+Dirigo is in *very* early development. While the API and architecture are functional, documentation and ready-to-use releases are in progress.
+
+
+## Digitizer ↔ LSM mode compatibility
+
+**Legend:** ✓ supported now · △ possible/experimental · ✗ not recommended/unsupported · — unknown  
+
+| Digitizer (vendor/model family) | Galvo–Galvo **analog** | Galvo–Galvo **photon counting** | Resonant–Galvo **analog** | Polygon–Galvo **analog** |
+|---|:---:|:---:|:---:|:---:|
+| **NI X-Series** (e.g., PCIe-63xx) | ✓* | ✓ (up to 4 chan.) | ✗† | ✗† |
+| **NI S-Series** (e.g., PCI-6110/6115) | ✓ | ✓ (up to 2 chan.) | △§ | △§ |
+| **AlazarTech** (e.g., ATS9440) | ✓ | ✗ | ✓ | ✓ |
+| **Teledyne SP Devices** (e.g., ADQ32) | ✓ | ✗ | ✓ | ✓ |
+| **Other / custom** (contact [TDW](https://github.com/tweber225)) | — | — | — | — |
+
+*Notes*  
+\* Multichannel acquisition subject to aggregate AI sample rate (e.g 2 channels: 500 kS/s, 4 channels 250 kS/s).  
+† AI sample rate typically insufficient for resonant/polygon rates.  
+§ Borderline: Max sample rate may limit pixels per line, dependent on scanner frequency. Not yet validated.  
+
+
+## Funding
+
+Development of Dirigo has been supported in part by the National Cancer Institute of the National Institutes of Health under award number R01CA249151.
+
+The content of this repository is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.

dirigo-0.3.8/README.md

@@ -0,0 +1,46 @@
+# Dirigo
+![PyPI](https://img.shields.io/pypi/v/dirigo)
+[![Documentation Status](https://readthedocs.org/projects/dirigo/badge/?version=latest)](https://dirigo.readthedocs.io/en/latest/?badge=latest)
+
+**Dirigo** is an extensible, high-performance backend for scientific image acquisition, designed with high-speed laser scanning microscopy in mind but adaptable to a wide range of medium- to high-complexity imaging systems.
+
+Dirigo separates hardware control, acquisition logic, and user interface, making it easy to:
+
+- Add new hardware via plugin drivers that implement generic device interfaces (digitizers, scanners, stages, cameras, etc.)
+
+- Reconfigure data acquisition and processing pipelines using a Worker/publisher–subscriber model
+
+- Integrate adaptive acquisition strategies through feedback loops between processing and control
+
+- Build custom GUIs or integrate with existing tools via a clean API (a reference GUI is available as a [separate package](https://github.com/dirigo-developers/dirigo-gui))
+
+Performance-critical operations are accelerated with [Numba](https://numba.pydata.org/) JIT compilation, releasing the GIL during execution and enabling parallel/vectorized processing.
+
+Dirigo follows a modular, package-oriented architecture: almost all components—hardware drivers, processing modules, GUIs—are separate Python packages that can be developed, installed, and updated independently.
+
+Dirigo is in *very* early development. While the API and architecture are functional, documentation and ready-to-use releases are in progress.
+
+
+## Digitizer ↔ LSM mode compatibility
+
+**Legend:** ✓ supported now · △ possible/experimental · ✗ not recommended/unsupported · — unknown  
+
+| Digitizer (vendor/model family) | Galvo–Galvo **analog** | Galvo–Galvo **photon counting** | Resonant–Galvo **analog** | Polygon–Galvo **analog** |
+|---|:---:|:---:|:---:|:---:|
+| **NI X-Series** (e.g., PCIe-63xx) | ✓* | ✓ (up to 4 chan.) | ✗† | ✗† |
+| **NI S-Series** (e.g., PCI-6110/6115) | ✓ | ✓ (up to 2 chan.) | △§ | △§ |
+| **AlazarTech** (e.g., ATS9440) | ✓ | ✗ | ✓ | ✓ |
+| **Teledyne SP Devices** (e.g., ADQ32) | ✓ | ✗ | ✓ | ✓ |
+| **Other / custom** (contact [TDW](https://github.com/tweber225)) | — | — | — | — |
+
+*Notes*  
+\* Multichannel acquisition subject to aggregate AI sample rate (e.g 2 channels: 500 kS/s, 4 channels 250 kS/s).  
+† AI sample rate typically insufficient for resonant/polygon rates.  
+§ Borderline: Max sample rate may limit pixels per line, dependent on scanner frequency. Not yet validated.  
+
+
+## Funding
+
+Development of Dirigo has been supported in part by the National Cancer Institute of the National Institutes of Health under award number R01CA249151.
+
+The content of this repository is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.

dirigo-0.3.8/dirigo/__init__.py

@@ -0,0 +1,6 @@
+print('importing dirigo')
+
+from .components import units, io
+
+
+__all__ = ["units", "io"]

dirigo-0.3.8/dirigo/components/hardware.py

@@ -0,0 +1,206 @@
+from functools import lru_cache, cached_property
+import importlib.metadata as im
+from typing import TYPE_CHECKING
+
+from dirigo.components.optics import LaserScanningOptics, CameraOptics
+from dirigo.hw_interfaces.detector import DetectorSet, Detector
+
+if TYPE_CHECKING:
+    from dirigo.components.io import SystemConfig
+    from dirigo.hw_interfaces.digitizer import Digitizer
+    from dirigo.hw_interfaces.stage import MultiAxisStage
+    from dirigo.hw_interfaces.encoder import MultiAxisLinearEncoder
+    from dirigo.hw_interfaces.scanner import FastRasterScanner, SlowRasterScanner, ObjectiveZScanner
+    from dirigo.hw_interfaces.camera import FrameGrabber, LineCamera
+    from dirigo.hw_interfaces.illuminator import Illuminator
+
+
+
+@lru_cache
+def _eps(group: str) -> dict[str, im.EntryPoint]:
+    return {ep.name.lower(): ep for ep in im.entry_points().select(group=group)}
+
+
+class HardwareError(RuntimeError): pass
+
+
+class NotConfiguredError(HardwareError):
+    def __init__(self, section: str):
+        super().__init__(f"[{section}] missing in system_config.toml")
+        self.section = section
+
+
+class PluginNotFoundError(HardwareError):
+    def __init__(self, group: str, type_name: str, available: list[str]):
+        avail = ", ".join(available) or "none"
+        super().__init__(f"No plugin '{type_name}' in entry-point group '{group}'. Available: {avail}")
+        self.group, self.type_name, self.available = group, type_name, available
+
+
+class PluginInitError(HardwareError):
+    def __init__(self, cls, kwargs: dict):
+        super().__init__(f"Failed to initialize {cls.__name__} with kwargs {kwargs}")
+        self.cls, self.kwargs = cls, kwargs
+
+
+class Hardware:
+    """ 
+    Loads hardware specified in system_config.toml and holds references to the 
+    components.
+    """
+    def __init__(self, system_config: "SystemConfig") -> None:
+        self._cfg = system_config
+
+    # --- helper ---
+    def _load(self, group: str, type_name: str, **kw):
+        """
+        Lazy-load the concrete driver class registered under *type_name*
+        in entry-point *group*, instantiate it with **kw, and return it.
+        """
+        try:
+            cls = _eps(group)[type_name.lower()].load()
+        except KeyError as e:
+            raise PluginNotFoundError(group, type_name, available=list(_eps(group)).copy()) from e
+        try:
+            return cls(**kw)
+        except TypeError as e:
+            raise PluginInitError(cls, kwargs=kw) from e
+    
+    # --- hardward devices (lazy loading) ---
+    @cached_property
+    def digitizer(self) -> "Digitizer":
+        cfg = self._cfg.digitizer
+        if cfg is None:
+            raise NotConfiguredError("digitizer")
+        return self._load("dirigo_digitizers", cfg["type"], **cfg)
+    
+    @cached_property
+    def fast_raster_scanner(self) -> "FastRasterScanner":
+        cfg = self._cfg.fast_raster_scanner
+        if cfg is None:
+            raise NotConfiguredError("fast raster scanner")
+        return self._load("dirigo_scanners", cfg["type"], **cfg)
+
+    @cached_property
+    def slow_raster_scanner(self) -> "SlowRasterScanner":
+        cfg = self._cfg.slow_raster_scanner
+        if cfg is None:
+            raise NotConfiguredError("slow raster scanner")
+        return self._load("dirigo_scanners", cfg["type"],
+            fast_scanner=self.fast_raster_scanner, **cfg)
+    
+    @cached_property
+    def objective_z_scanner(self) -> "ObjectiveZScanner":
+        cfg = self._cfg.objective_z_scanner
+        if cfg is None:
+            raise NotConfiguredError("objective z scanner")
+        return self._load("dirigo_scanners", cfg["type"], **cfg)
+
+    @cached_property
+    def stages(self) -> "MultiAxisStage":
+        cfg = self._cfg.stages
+        if cfg is None:
+            raise NotConfiguredError("stages")
+        return self._load("dirigo_stages", cfg["type"], **cfg)
+    
+    @cached_property
+    def preferred_z_motor(self):
+        """Returns the objective z scanner or multi-axis stage z axis."""
+        try:
+            return self.objective_z_scanner
+        except NotConfiguredError:
+            pass
+
+        try:
+            return self.stages.z
+        except (NotConfiguredError, NotImplementedError):
+            pass
+
+        raise NotConfiguredError("No Z motor")
+    
+    @cached_property
+    def encoders(self) -> "MultiAxisLinearEncoder":
+        cfg = self._cfg.encoders
+        if cfg is None:
+            raise NotConfiguredError("encoders")
+        return self._load("dirigo_encoders", cfg["type"], **cfg)
+
+    @cached_property
+    def detectors(self) -> DetectorSet[Detector]:
+        cfg = self._cfg.detectors
+        if cfg is None:
+            raise NotConfiguredError("detectors")
+        dset = DetectorSet()
+        for key, det_cfg in cfg.items():
+            det = self._load("dirigo_detectors",
+                             det_cfg.pop("type"),
+                             **det_cfg,
+                             fast_scanner=self.fast_raster_scanner)
+            dset.append(det)
+        return dset
+
+    @cached_property
+    def frame_grabber(self) -> "FrameGrabber":
+        cfg = self._cfg.frame_grabber
+        if cfg is None:
+            raise NotConfiguredError("frame grabber")
+        return self._load("dirigo_frame_grabbers", cfg["type"], **cfg)
+    
+    @cached_property
+    def line_camera(self) -> "LineCamera": # this could just be camera
+        cfg = self._cfg.line_camera
+        if cfg is None:
+            raise NotConfiguredError("line camera")
+        return self._load("dirigo_line_cameras", cfg["type"], 
+            frame_grabber=self.frame_grabber, **cfg)
+    
+    @cached_property
+    def illuminator(self) -> "Illuminator":
+        cfg = self._cfg.illuminator
+        if cfg is None:
+            raise NotConfiguredError("illuminator")
+        return self._load("dirigo_illuminators", cfg["type"], **cfg)
+
+    @cached_property
+    def laser_scanning_optics(self) -> LaserScanningOptics:
+        cfg = self._cfg.laser_scanning_optics
+        if cfg is None:
+            raise NotConfiguredError("laser scanning optics")
+        return LaserScanningOptics(**cfg)
+
+    @cached_property
+    def camera_optics(self) -> CameraOptics:
+        cfg = self._cfg.camera_optics
+        if cfg is None:
+            raise NotConfiguredError("camera optics")
+        return CameraOptics(**cfg)
+        
+    # --- conveniences ---
+    # TODO deprecate these methods to restore Hardware as a container/lazy loader
+    @property
+    def nchannels_enabled(self) -> int:
+        """
+        Returns the number channels currently enabled on the primary data 
+        acquisition device.
+        """
+        if self._cfg.digitizer:
+            return sum([channel.enabled for channel in self.digitizer.channels])
+        elif self._cfg.line_camera:
+            return 1 # monochrome only for now, but RGB cameras should be 3-channel
+        else:
+            raise RuntimeError("No channels available: lacking digitizer or camera")
+        
+    @property
+    def nchannels_present(self) -> int:
+        """
+        Returns the number channels present on the primary data acquisition 
+        device.
+        """
+        if self._cfg.digitizer:
+            return len(self.digitizer.channels)
+        elif self._cfg.line_camera:
+            return 1 # monochrome only for now, but RGB cameras should be 3-channel
+        else:
+            raise RuntimeError("No channels available: lacking digitizer or camera")
+        
+    # TODO __repr__ method

dirigo-0.3.8/dirigo/components/io.py

@@ -0,0 +1,226 @@
+from pathlib import Path
+import tomllib
+import csv
+from typing import Any
+from functools import cached_property
+from types import MappingProxyType
+from copy import deepcopy
+
+import numpy as np
+from numpy.polynomial.polynomial import Polynomial
+import platformdirs as pd
+
+from dirigo.components import units
+
+
+
+def config_path() -> Path:
+    return pd.user_config_path("Dirigo")
+
+
+def load_toml(file_name: Path | str) -> dict[str, Any]:
+    file_name = Path(file_name)
+    if not file_name.exists():
+        raise FileNotFoundError(f"Can not find TOML file: {file_name}")
+    if file_name.suffix != ".toml":
+        raise ValueError(f"Requested to load a non-TOML file: {file_name}")
+    with open(file_name, mode="rb") as toml_file:
+        toml_contents = tomllib.load(toml_file)
+    return toml_contents
+
+
+try: 
+    d = load_toml(config_path() / "logging.toml")           # 1st choice: user-specified path
+    _data_path = Path(d['data_path'])
+except:
+    _data_path = pd.user_documents_path() / "Dirigo"        # Backup path
+    
+def data_path() -> Path:
+    return _data_path
+
+def load_scanner_calibration(
+        path: Path = config_path() / "scanner/calibration.csv"
+        ) -> tuple:
+    
+    ampls, freqs, phases = np.loadtxt(
+        path,
+        delimiter=',',
+        unpack=True,
+        skiprows=1
+    )
+    return ampls, freqs, phases
+
+
+def load_line_distortion_calibration(
+        amplitude: units.Angle,
+        path: Path = config_path() / "optics/line_distortion_calibration.csv"
+    ):
+    data = np.loadtxt(path, delimiter=',', dtype=np.float64, skiprows=1, ndmin=2)
+    amplitudes = data[:,0]
+    coefs = data[:,1:]
+
+    for i,a in enumerate(amplitudes):
+        if abs(a - amplitude)/amplitude < 0.001:
+            return Polynomial(coefs[i])
+    
+    raise RuntimeError("Could not find distortion calibration")
+
+
+def update_distortion_table(
+    scanner_ampl: units.Angle,
+    c0=None,
+    c1=None,
+    c2=None,
+    path: Path = config_path() / "optics/line_distortion_calibration.csv"
+):
+    """
+    Update polynomial coefficients for a given scanner amplitude.
+
+    Parameters
+    ----------
+    scanner_ampl : units.Angle
+        Scanner amplitude (matched in radians).
+    c0, c1, c2 : float | None
+        Polynomial coefficients to update. None leaves value unchanged.
+    path : Path
+        CSV file path.
+    """
+    rows = []
+    updated = False
+
+    with path.open("r", newline="") as f:
+        reader = csv.DictReader(f)
+        fieldnames = reader.fieldnames
+        if fieldnames is None:
+            raise ValueError("CSV has no header")
+
+        for row in reader:
+            row_rad = float(row["# scanner amplitude (rad)"])
+
+            if abs(row_rad - scanner_ampl) <= 1e-3:
+                if c0 is not None:
+                    row["c0"] = f"{float(c0):.16e}"
+                if c1 is not None:
+                    row["c1"] = f"{float(c1):.16e}"
+                if c2 is not None:
+                    row["c2"] = f"{float(c2):.16e}"
+                updated = True
+
+            rows.append(row)
+
+    if not updated:
+        raise ValueError(
+            f"No entry found for scanner amplitude {scanner_ampl}"
+        )
+
+    with path.open("w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def load_stage_scanner_angle(
+        path: Path = config_path() / "optics/stage_scanner_angle.csv"
+    ) -> units.Angle:
+    try:
+        data = np.loadtxt(path, delimiter=',', dtype=np.float64, skiprows=1)
+        return units.Angle(float(data))
+    except FileNotFoundError:
+        # If not calibrated, then return 0 angle (no error axis error)
+        return units.Angle("0 deg")
+
+
+def load_signal_offset(
+        path: Path = config_path() / "digitizer/signal_offset.csv"
+):
+    try:
+        return np.loadtxt(path, delimiter=',', dtype=np.float64, skiprows=1, ndmin=1)
+    except FileNotFoundError:
+        return np.array([0])
+
+
+def load_line_gradient_calibration(
+        line_width: units.Position,
+        pixel_size: units.Position,
+        path: Path = config_path() / "optics/line_gradient.csv"
+    ):
+    """Returns a function to correct intensity vignetting."""
+
+    entries = np.loadtxt(
+        fname       = path, 
+        delimiter   = ',',
+        dtype       = np.float64, 
+        skiprows    = 1, 
+    )
+
+    x = entries[:,0]
+    if abs(line_width - (x[-1] - x[0])) / line_width > 0.001:
+        raise RuntimeError("Line gradient calibrated on different line size.")
+    print(abs(pixel_size - (x[1] - x[0])))
+    if abs(pixel_size - (x[1] - x[0])) / pixel_size > 0.01:
+        raise RuntimeError("Line gradient calibrated on different pixel size.")
+        # one could interpolate here probably TODO
+    
+    n_x, n_c = entries.shape
+    n_c -= 1 # -1 to account for x axis label
+    correction = np.zeros((n_x,n_c), dtype=np.float32)
+    for c in range(n_c):
+        y = entries[:,c+1]
+        correction[:,c] = 1 / y
+
+    return np.average(correction,axis=1)
+
+        
+_CONFIG_KEYS = (
+    "laser_scanning_optics", "camera_optics", "digitizer", "detectors",
+    "objective_z_scanner", "stages", "line_camera", "illuminator",
+    "frame_grabber", "encoders", "fast_raster_scanner", "slow_raster_scanner",
+)
+
+class SystemConfig:
+    """
+    Slotted, read-mostly config: each known section becomes an attribute whose
+    value is either a dict[...] or None if the section is absent in TOML.
+    No cached_property needed; lookups are direct attribute access.
+    """
+    __slots__ = (*_CONFIG_KEYS, "_raw")
+
+    # explicit (optional) type hints for IDEs / type checkers
+    laser_scanning_optics:  dict[str, Any] | None
+    camera_optics:          dict[str, Any] | None
+    digitizer:              dict[str, Any] | None
+    detectors:              dict[str, Any] | None
+    objective_z_scanner:    dict[str, Any] | None
+    stages:                 dict[str, Any] | None
+    line_camera:            dict[str, Any] | None
+    illuminator:            dict[str, Any] | None
+    frame_grabber:          dict[str, Any] | None
+    encoders:               dict[str, Any] | None
+    fast_raster_scanner:    dict[str, Any] | None
+    slow_raster_scanner:    dict[str, Any] | None
+
+    def __init__(self, data: dict[str, dict[str, Any]]):
+        self._raw = data
+        for key in _CONFIG_KEYS:
+            setattr(self, key, data.get(key))  # missing -> None
+
+    @classmethod
+    def from_toml(cls, toml_path: "Path") -> "SystemConfig":
+        return cls(load_toml(toml_path))
+
+    def has(self, key: str) -> bool:
+        return getattr(self, key) is not None
+
+    def to_dict(self, *, copy: bool = False, readonly: bool = False) -> dict[str, dict[str, Any] | None]:
+        # expose the normalized view (sections -> dict | None)
+        d = {k: getattr(self, k) for k in _CONFIG_KEYS}
+        if copy:
+            return deepcopy(d)
+        if readonly:
+            return MappingProxyType(d)
+        return d
+
+    def raw(self) -> dict[str, dict[str, Any]]:
+        # original TOML mapping (no None entries; missing keys absent)
+        return self._raw
+    

dirigo-0.3.8/dirigo/components/optics.py

@@ -0,0 +1,82 @@
+from typing import Optional
+
+from dirigo.components import units, io
+
+
+"""
+Notes:
+Concerning distortion and magnification error, we assume that the scanner always
+produces the correct angle. This may or may not be true, but besides the point.
+Any corrections are applied at Optics class level.
+"""
+
+class LaserScanningOptics: 
+    def __init__(self, 
+                 objective_focal_length: str, 
+                 relay_magnification: float) -> None:
+        """
+        fast_axis_correction (float): extends scan by factor to correct mag error
+        """
+        self._objective_focal_length = units.Position(objective_focal_length)
+        self._relay_magnification = float(relay_magnification)
+
+        # load line width calibration, TODO
+
+        # Load stage-scanner angle
+        self.stage_scanner_angle = io.load_stage_scanner_angle()
+        
+
+    @property
+    def objective_focal_length(self) -> units.Position:
+        """Returns the objective focal length."""
+        return self._objective_focal_length
+    
+    @property
+    def relay_magnification(self) -> float:
+        """Returns the scan relay system (typically: scan lens + tube lens) 
+        lateral magnification.
+        """
+        return self._relay_magnification
+
+    def scan_angle_to_object_position(self, 
+                                      angle: units.Angle, 
+                                      axis: Optional[str] = None
+                                      ) -> units.Position:
+        """
+        Return the focus position for a certain scanner angle (optical).
+
+        Specify axis ('fast', 'slow') to invoke correction factor.
+        """
+        objective_angle = angle / self.relay_magnification 
+        position = float(objective_angle) * self.objective_focal_length
+        return units.Position(position)
+
+    def object_position_to_scan_angle(self, 
+                                      position: units.Position) -> units.Angle:
+        """
+        Return the scanner angle (optical) required for a certain focus position.
+
+        Specify axis ('fast', 'slow') to invoke correction factor.
+        """
+        objective_angle = position / self.objective_focal_length
+        angle = objective_angle * self.relay_magnification
+            
+        return units.Angle(angle)
+       
+
+class CameraOptics:
+    """
+    Optics to use with a parallel array of detectors, usually an image sensor.
+    """
+    def __init__(self, magnification: float | int, **kwargs):
+        if not (isinstance(magnification, float) or isinstance(magnification, int) ):
+            raise ValueError("Magnification must be a float or an integer")
+        self._magnification = float(magnification)
+
+        self.stage_camera_angle = units.Angle(0) # TODO load this from calibration
+
+    @property
+    def magnification(self) -> float:
+        return self._magnification
+
+