audace-display 0.1.0__tar.gz

audace_display-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invisensing
+
+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.

audace_display-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: audace-display
+Version: 0.1.0
+Summary: Visualization of Audace DAS acquisition files (.dat / .hdf5 / .tdms / .sgy).
+Author: Invisensing
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/invisensing-io/audace-display
+Project-URL: Source, https://github.com/invisensing-io/audace-display
+Project-URL: Issues, https://github.com/invisensing-io/audace-display/issues
+Keywords: DAS,fiber-optic-sensing,visualization,audace,invisensing,waterfall
+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: Topic :: Scientific/Engineering :: Visualization
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: invisensing>=1.1.0
+Provides-Extra: interactive
+Requires-Dist: pyqtgraph>=0.13; extra == "interactive"
+Requires-Dist: PyQt5>=5.15; extra == "interactive"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# audace-display
+
+Visualization of **Audace DAS** acquisition files -- simple, fast, safe.
+
+`audace-display` reads any format produced by the Filewriter
+(`.dat`, `.hdf5`, `.tdms`, `.sgy`) via the [`invisensing`](https://pypi.org/project/invisensing/)
+library, automatically detects the file mode, and shows:
+
+- a **heatmap** (time x distance waterfall) for **demodulated** files,
+- an **animated oscilloscope** (lines replayed in real time, looping) for **raw**
+  files.
+
+Reading is **streamed and decimated**: a multi-GB file is reduced to screen
+resolution without ever being fully loaded into memory.
+
+## Installation
+
+```bash
+pip install audace-display              # matplotlib (static + interactive + PNG)
+pip install audace-display[interactive] # + pyqtgraph backend (fast interactive)
+```
+
+Dependencies: `numpy`, `matplotlib`, `invisensing` (>= 1.1.0 recommended for the
+O(1) seek and TDMS/SEG-Y streaming; works from 1.0.0). Optional `interactive`
+extra: `pyqtgraph` + `PyQt5`.
+
+## Quick start
+
+```bash
+# Auto: heatmap if demodulated, oscilloscope if raw -- zero options
+audace-display acquisition.dat
+
+# PNG export (server / headless mode, no X11/Wayland)
+audace-display acquisition.dat --save output.png
+```
+
+That's all for everyday use. The rest is fine-grained control.
+
+## Display (backends)
+
+| Mode | Command | For |
+|------|---------|-----|
+| interactive matplotlib | *(default)* | quick look, publication quality |
+| headless PNG | `--save out.png` | server without X11/Wayland, batch scripts |
+| interactive pyqtgraph | `--backend pyqtgraph` | smooth exploration (GPU pan/zoom) on large files |
+
+matplotlib stays the default (simple, no heavy dependency). For smooth pan/zoom
+on long acquisitions, `--backend pyqtgraph` is far more responsive (GPU
+re-render + on-the-fly downsampling) -- install the extra
+`pip install audace-display[interactive]`. `--save` always renders the PNG via
+matplotlib, regardless of `--backend`.
+
+```bash
+audace-display heatmap acq.dat --backend pyqtgraph   # fast viewer
+audace-display acq.dat --backend pyqtgraph           # same, in auto mode
+audace-display acq.dat --save out.png                # headless PNG
+```
+
+## Raw mode: real-time oscilloscope
+
+For a **raw** file, the default is an **animated oscilloscope**: each frame draws
+the current line (pulse) -- amplitude vs distance along the fiber -- and the
+cursor **advances at `trigger_frequency` lines/second** (real time), **looping**.
+At high rates, lines are skipped to stay real-time (the pace stays exact, locked
+to the clock). Optimized: O(1) per-line seek (invisensing >= 1.1.0), "peak"
+decimation of large lines, reused curve, frozen axes. For maximum smoothness,
+`--backend pyqtgraph`.
+
+```bash
+audace-display scope acq.dat                  # real time, looping
+audace-display scope acq.dat --speed 0.25     # 4x slow motion
+audace-display scope acq.dat --fps 60 --backend pyqtgraph
+audace-display scope acq.dat --start-time 1.0 --duration 0.5   # loop over 0.5 s
+audace-display scope acq.dat --line 1000 --save frame.png      # 1 frozen line (PNG)
+```
+
+| Option | Effect |
+|--------|--------|
+| `--speed F`   | Playback speed (1.0 = real time = `trig_frequency` lines/s) |
+| `--fps N`     | Render frames/s (default 30) |
+| `--line N`    | Frozen line exported with `--save` (default 0) |
+| `--max-points N` | Max points drawn per line (peak decimation). Default 4000 |
+
+Requires `invisensing >= 1.1.0` (O(1) per-line seek).
+
+## Subcommands
+
+| Command   | Role |
+|-----------|------|
+| *(none)*  | Auto: heatmap (demodulated) or animated oscilloscope (raw) |
+| `info`    | Header metadata + stats of the default channel |
+| `heatmap` | Time x distance waterfall, color = channel |
+| `scope`   | Oscilloscope: replays the lines (pulses) in real time, looping |
+| `fft`     | Temporal spectrum (FFT along the pulses) at 1+ position(s) |
+| `trace`   | 1-D time trace at one position |
+| `demod`   | Demodulate via an **external script**, then show as heatmap |
+
+```bash
+audace-display info acquisition.dat
+audace-display heatmap acquisition.dat --channel magnitude --db
+audace-display heatmap acquisition.dat --start-time 0.5 --duration 1.0
+audace-display heatmap acquisition.dat --start-distance 50 --end-distance 200
+audace-display fft   acquisition.dat --position 120
+audace-display fft   acquisition.dat --position 50,100,150 --db
+audace-display fft   acquisition.dat --position-range 100:200 --window blackman
+audace-display trace acquisition.dat --position 100
+```
+
+## Channels per mode
+
+| File mode          | Valid channels                                      | Default     |
+|--------------------|-----------------------------------------------------|-------------|
+| `raw`              | `raw`                                               | `raw`       |
+| `iq`               | `i`, `q`, `magnitude` (\|IQ\|), `phase_wrapped`     | `magnitude` |
+| `arctan_magnitude` | `arctan`, `magnitude` (sqrt(I^2+Q^2))               | `magnitude` |
+| `phase`            | `phase`                                             | `phase`     |
+
+Common aliases: `mag`/`amp` -> `magnitude`, `atan` -> `arctan`, `angle` ->
+`phase_wrapped`. **No demodulation** is applied: channels are read as the
+Filewriter wrote them.
+
+## Large files (200 MB - 10 GB)
+
+The heatmap is computed in a **single streaming pass**: pulses are read in chunks
+and aggregated on the fly into a `--max-time-bins x --max-space-bins` grid
+(2000 x 2000 by default). RAM does not depend on file size. Line plots use a
+**min/max-preserving decimation** (no visual aliasing).
+
+| Option | Effect |
+|--------|--------|
+| `--max-time-bins N`  | Temporal (X) resolution of the waterfall. Default 2000 |
+| `--max-space-bins N` | Spatial (Y) resolution of the waterfall. Default 2000 |
+| `--reduce {mean,rms,std,peak}` | Temporal aggregation statistic. Default `mean` |
+| `--max-pulses N`     | Bound the number of pulses read (default: whole file) |
+| `--subsample-time N` | (fft/trace) keep only one pulse out of N |
+
+`.dat` and `.hdf5` stream natively; `.tdms` and `.sgy` also stream with
+`invisensing >= 1.1.0`. `--start-time` seeks directly (O(1) seek) with 1.1.0.
+
+## Demodulation via external plugin
+
+`audace-display` contains **no demodulation code**: it defines a contract and
+loads a Python script that **you** provide (never published). The result is
+displayed as a heatmap.
+
+```python
+# my_demod.py
+import numpy as np
+
+class Demodulator:
+    OUTPUT_LABEL = "phase (rad)"   # colorbar label (optional)
+    IS_ANGULAR   = True            # diverging colormap (optional)
+
+    def __init__(self, *, sample_rate, trig_frequency, line_size, meta):
+        ...                        # init filters / state
+
+    def process(self, chunk):      # called on contiguous time chunks
+        # chunk: (rows, line_size) raw -> (rows, positions) float32
+        ...
+```
+
+```bash
+audace-display demod raw.dat --script my_demod.py --save demod.png
+```
+
+Stateless alternative: a function
+`demodulate(chunk, *, sample_rate, trig_frequency, line_size, meta) -> ndarray`.
+Chunks arrive **in time order** (compatible with stateful filters).
+
+## Programmatic API
+
+```python
+from invisensing import File
+from audace_display import load_decimated, resolve_channel
+
+with File("acquisition.dat") as f:
+    _, resolver, label, is_angular = resolve_channel(None, f.mode)
+    res = load_decimated(f, lambda raw: resolver(f, raw),
+                         max_time_bins=1000, max_space_bins=1000)
+    # res.data: (n_time, n_space) float32 ; res.t_extent, res.d_extent
+```
+
+## Default behavior
+
+- **Interactive display** by default; `--save out.png` for headless mode (the
+  `Agg` backend is chosen automatically when there is no display).
+- **Auto colormap**: `viridis` (sequential) for magnitude/raw, `RdBu_r`
+  (diverging, centered on 0) for phase/arctan. Override with `--cmap`.
+- **Auto-scaling**: 1/99 percentiles in linear, `median - 30 dB -> max` in dB,
+  centered on 0 for angular channels. Override with `--vmin`/`--vmax`.
+
+## License
+
+MIT.

audace_display-0.1.0/README.md

@@ -0,0 +1,194 @@
+# audace-display
+
+Visualization of **Audace DAS** acquisition files -- simple, fast, safe.
+
+`audace-display` reads any format produced by the Filewriter
+(`.dat`, `.hdf5`, `.tdms`, `.sgy`) via the [`invisensing`](https://pypi.org/project/invisensing/)
+library, automatically detects the file mode, and shows:
+
+- a **heatmap** (time x distance waterfall) for **demodulated** files,
+- an **animated oscilloscope** (lines replayed in real time, looping) for **raw**
+  files.
+
+Reading is **streamed and decimated**: a multi-GB file is reduced to screen
+resolution without ever being fully loaded into memory.
+
+## Installation
+
+```bash
+pip install audace-display              # matplotlib (static + interactive + PNG)
+pip install audace-display[interactive] # + pyqtgraph backend (fast interactive)
+```
+
+Dependencies: `numpy`, `matplotlib`, `invisensing` (>= 1.1.0 recommended for the
+O(1) seek and TDMS/SEG-Y streaming; works from 1.0.0). Optional `interactive`
+extra: `pyqtgraph` + `PyQt5`.
+
+## Quick start
+
+```bash
+# Auto: heatmap if demodulated, oscilloscope if raw -- zero options
+audace-display acquisition.dat
+
+# PNG export (server / headless mode, no X11/Wayland)
+audace-display acquisition.dat --save output.png
+```
+
+That's all for everyday use. The rest is fine-grained control.
+
+## Display (backends)
+
+| Mode | Command | For |
+|------|---------|-----|
+| interactive matplotlib | *(default)* | quick look, publication quality |
+| headless PNG | `--save out.png` | server without X11/Wayland, batch scripts |
+| interactive pyqtgraph | `--backend pyqtgraph` | smooth exploration (GPU pan/zoom) on large files |
+
+matplotlib stays the default (simple, no heavy dependency). For smooth pan/zoom
+on long acquisitions, `--backend pyqtgraph` is far more responsive (GPU
+re-render + on-the-fly downsampling) -- install the extra
+`pip install audace-display[interactive]`. `--save` always renders the PNG via
+matplotlib, regardless of `--backend`.
+
+```bash
+audace-display heatmap acq.dat --backend pyqtgraph   # fast viewer
+audace-display acq.dat --backend pyqtgraph           # same, in auto mode
+audace-display acq.dat --save out.png                # headless PNG
+```
+
+## Raw mode: real-time oscilloscope
+
+For a **raw** file, the default is an **animated oscilloscope**: each frame draws
+the current line (pulse) -- amplitude vs distance along the fiber -- and the
+cursor **advances at `trigger_frequency` lines/second** (real time), **looping**.
+At high rates, lines are skipped to stay real-time (the pace stays exact, locked
+to the clock). Optimized: O(1) per-line seek (invisensing >= 1.1.0), "peak"
+decimation of large lines, reused curve, frozen axes. For maximum smoothness,
+`--backend pyqtgraph`.
+
+```bash
+audace-display scope acq.dat                  # real time, looping
+audace-display scope acq.dat --speed 0.25     # 4x slow motion
+audace-display scope acq.dat --fps 60 --backend pyqtgraph
+audace-display scope acq.dat --start-time 1.0 --duration 0.5   # loop over 0.5 s
+audace-display scope acq.dat --line 1000 --save frame.png      # 1 frozen line (PNG)
+```
+
+| Option | Effect |
+|--------|--------|
+| `--speed F`   | Playback speed (1.0 = real time = `trig_frequency` lines/s) |
+| `--fps N`     | Render frames/s (default 30) |
+| `--line N`    | Frozen line exported with `--save` (default 0) |
+| `--max-points N` | Max points drawn per line (peak decimation). Default 4000 |
+
+Requires `invisensing >= 1.1.0` (O(1) per-line seek).
+
+## Subcommands
+
+| Command   | Role |
+|-----------|------|
+| *(none)*  | Auto: heatmap (demodulated) or animated oscilloscope (raw) |
+| `info`    | Header metadata + stats of the default channel |
+| `heatmap` | Time x distance waterfall, color = channel |
+| `scope`   | Oscilloscope: replays the lines (pulses) in real time, looping |
+| `fft`     | Temporal spectrum (FFT along the pulses) at 1+ position(s) |
+| `trace`   | 1-D time trace at one position |
+| `demod`   | Demodulate via an **external script**, then show as heatmap |
+
+```bash
+audace-display info acquisition.dat
+audace-display heatmap acquisition.dat --channel magnitude --db
+audace-display heatmap acquisition.dat --start-time 0.5 --duration 1.0
+audace-display heatmap acquisition.dat --start-distance 50 --end-distance 200
+audace-display fft   acquisition.dat --position 120
+audace-display fft   acquisition.dat --position 50,100,150 --db
+audace-display fft   acquisition.dat --position-range 100:200 --window blackman
+audace-display trace acquisition.dat --position 100
+```
+
+## Channels per mode
+
+| File mode          | Valid channels                                      | Default     |
+|--------------------|-----------------------------------------------------|-------------|
+| `raw`              | `raw`                                               | `raw`       |
+| `iq`               | `i`, `q`, `magnitude` (\|IQ\|), `phase_wrapped`     | `magnitude` |
+| `arctan_magnitude` | `arctan`, `magnitude` (sqrt(I^2+Q^2))               | `magnitude` |
+| `phase`            | `phase`                                             | `phase`     |
+
+Common aliases: `mag`/`amp` -> `magnitude`, `atan` -> `arctan`, `angle` ->
+`phase_wrapped`. **No demodulation** is applied: channels are read as the
+Filewriter wrote them.
+
+## Large files (200 MB - 10 GB)
+
+The heatmap is computed in a **single streaming pass**: pulses are read in chunks
+and aggregated on the fly into a `--max-time-bins x --max-space-bins` grid
+(2000 x 2000 by default). RAM does not depend on file size. Line plots use a
+**min/max-preserving decimation** (no visual aliasing).
+
+| Option | Effect |
+|--------|--------|
+| `--max-time-bins N`  | Temporal (X) resolution of the waterfall. Default 2000 |
+| `--max-space-bins N` | Spatial (Y) resolution of the waterfall. Default 2000 |
+| `--reduce {mean,rms,std,peak}` | Temporal aggregation statistic. Default `mean` |
+| `--max-pulses N`     | Bound the number of pulses read (default: whole file) |
+| `--subsample-time N` | (fft/trace) keep only one pulse out of N |
+
+`.dat` and `.hdf5` stream natively; `.tdms` and `.sgy` also stream with
+`invisensing >= 1.1.0`. `--start-time` seeks directly (O(1) seek) with 1.1.0.
+
+## Demodulation via external plugin
+
+`audace-display` contains **no demodulation code**: it defines a contract and
+loads a Python script that **you** provide (never published). The result is
+displayed as a heatmap.
+
+```python
+# my_demod.py
+import numpy as np
+
+class Demodulator:
+    OUTPUT_LABEL = "phase (rad)"   # colorbar label (optional)
+    IS_ANGULAR   = True            # diverging colormap (optional)
+
+    def __init__(self, *, sample_rate, trig_frequency, line_size, meta):
+        ...                        # init filters / state
+
+    def process(self, chunk):      # called on contiguous time chunks
+        # chunk: (rows, line_size) raw -> (rows, positions) float32
+        ...
+```
+
+```bash
+audace-display demod raw.dat --script my_demod.py --save demod.png
+```
+
+Stateless alternative: a function
+`demodulate(chunk, *, sample_rate, trig_frequency, line_size, meta) -> ndarray`.
+Chunks arrive **in time order** (compatible with stateful filters).
+
+## Programmatic API
+
+```python
+from invisensing import File
+from audace_display import load_decimated, resolve_channel
+
+with File("acquisition.dat") as f:
+    _, resolver, label, is_angular = resolve_channel(None, f.mode)
+    res = load_decimated(f, lambda raw: resolver(f, raw),
+                         max_time_bins=1000, max_space_bins=1000)
+    # res.data: (n_time, n_space) float32 ; res.t_extent, res.d_extent
+```
+
+## Default behavior
+
+- **Interactive display** by default; `--save out.png` for headless mode (the
+  `Agg` backend is chosen automatically when there is no display).
+- **Auto colormap**: `viridis` (sequential) for magnitude/raw, `RdBu_r`
+  (diverging, centered on 0) for phase/arctan. Override with `--cmap`.
+- **Auto-scaling**: 1/99 percentiles in linear, `median - 30 dB -> max` in dB,
+  centered on 0 for angular channels. Override with `--vmin`/`--vmax`.
+
+## License
+
+MIT.

audace_display-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "audace-display"
+version = "0.1.0"
+description = "Visualization of Audace DAS acquisition files (.dat / .hdf5 / .tdms / .sgy)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Invisensing" }]
+keywords = ["DAS", "fiber-optic-sensing", "visualization", "audace", "invisensing", "waterfall"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.21",
+    "matplotlib>=3.5",
+    "invisensing>=1.1.0",
+]
+
+[project.optional-dependencies]
+# Fast interactive backend (smooth pan/zoom). Otherwise: matplotlib (always present).
+interactive = ["pyqtgraph>=0.13", "PyQt5>=5.15"]
+test = ["pytest>=7"]
+
+[project.scripts]
+audace-display = "audace_display.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/invisensing-io/audace-display"
+Source = "https://github.com/invisensing-io/audace-display"
+Issues = "https://github.com/invisensing-io/audace-display/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

audace_display-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audace_display-0.1.0/src/audace_display/__init__.py

@@ -0,0 +1,47 @@
+"""audace-display -- visualization of Audace DAS acquisition files.
+
+Reads any format produced by the Filewriter (``.dat`` / ``.hdf5`` / ``.tdms`` /
+``.sgy``) via the :mod:`invisensing` library, and shows:
+
+- a **heatmap** (time x distance waterfall) for demodulated files,
+- an **animated oscilloscope** for raw files,
+
+with automatic mode detection. *Streaming* decimation to handle multi-GB files
+in bounded RAM.
+
+CLI: ``audace-display FILE`` (auto) or subcommands
+``info`` / ``heatmap`` / ``fft`` / ``trace`` / ``scope`` / ``demod``.
+
+Programmatic API (stable):
+
+    from audace_display import load_decimated, load_columns, resolve_channel
+"""
+from __future__ import annotations
+
+from ._errors import AudaceDisplayError
+from .channels import resolve_channel, CHANNELS, DEFAULT_CHANNEL
+from .reader import (
+    load_decimated,
+    load_columns,
+    position_step_m,
+    time_window_pulses,
+    DecimatedResult,
+)
+from .demod import load_demodulator, DemodPlugin
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AudaceDisplayError",
+    "resolve_channel",
+    "CHANNELS",
+    "DEFAULT_CHANNEL",
+    "load_decimated",
+    "load_columns",
+    "position_step_m",
+    "time_window_pulses",
+    "DecimatedResult",
+    "load_demodulator",
+    "DemodPlugin",
+    "__version__",
+]

audace_display-0.1.0/src/audace_display/__main__.py

@@ -0,0 +1,9 @@
+"""Enables ``python -m audace_display``."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

audace_display-0.1.0/src/audace_display/_errors.py

@@ -0,0 +1,12 @@
+"""Single error type for audace-display.
+
+Any user-facing error condition (unreadable file, unknown channel, empty slice,
+invalid demod plugin...) raises :class:`AudaceDisplayError`. The CLI catches it,
+prints the message and exits with a non-zero code, without a noisy traceback.
+Other exceptions propagate (a bug to fix).
+"""
+from __future__ import annotations
+
+
+class AudaceDisplayError(Exception):
+    """Expected error, to be presented cleanly to the user."""

audace_display-0.1.0/src/audace_display/channels.py

@@ -0,0 +1,103 @@
+"""Registry of displayable *channels*.
+
+A channel is a 2-D numpy view ``(rows, positions)`` of a file's content for a
+given mode. The *resolver* converts the raw buffer returned by
+:meth:`invisensing.File.read_lines` (i16 / i32 / f32, possibly interleaved) into
+a physical ``float32`` value.
+
+No demodulation here: we only **read** channels already written by the
+Filewriter (raw, I/Q, arctan+magnitude, phase). ``phase_wrapped`` (``arg(I+jQ)``)
+is just a *view* of already-produced IQ data, not a demodulation.
+"""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import numpy as np
+from invisensing import Mode
+
+from ._errors import AudaceDisplayError
+
+# Resolver: (File, raw_buffer) -> ndarray (rows, positions) float32
+Resolver = Callable[[object, np.ndarray], np.ndarray]
+
+# Common aliases -> canonical name
+ALIASES: dict[str, str] = {
+    # raw ADC
+    "raw": "raw", "adc": "raw",
+    # IQ
+    "i": "i", "q": "q",
+    # magnitude (= |IQ| or sqrt(I^2+Q^2) depending on mode)
+    "magnitude": "magnitude", "mag": "magnitude",
+    "amp": "magnitude", "amplitude": "magnitude", "|iq|": "magnitude",
+    # arctan (ARCTAN_MAGNITUDE mode)
+    "arctan": "arctan", "atan": "arctan",
+    # phase wrapped from IQ (!= demodulated phase of PHASE mode)
+    "phase_wrapped": "phase_wrapped", "wrapped": "phase_wrapped",
+    "angle": "phase_wrapped",
+    # demodulated phase (PHASE mode)
+    "phase": "phase", "p": "phase", "phi": "phase",
+}
+
+
+def _ch_raw(f, buf: np.ndarray) -> np.ndarray:
+    """Raw ADC codes -> volts via the header `range`."""
+    return buf.astype(np.float32) * np.float32(f.range / 32768.0)
+
+
+def _ch_magnitude(f, buf: np.ndarray) -> np.ndarray:
+    """Magnitude in volts. `|IQ|` in IQ mode, `sqrt(I^2+Q^2)` in ArctanMag."""
+    if f.mode is Mode.IQ:
+        return np.abs(f.get_iq_volts(buf)).astype(np.float32)
+    return f.get_magnitude_volts(buf)
+
+
+def _ch_phase_wrapped(f, buf: np.ndarray) -> np.ndarray:
+    """`arg(I+jQ)` in radians in [-pi, +pi[ from an IQ file."""
+    return np.angle(f.get_iq_volts(buf)).astype(np.float32)
+
+
+# canonical -> (valid modes, resolver, colorbar/y label, angular?)
+CHANNELS: dict[str, tuple[set, Resolver, str, bool]] = {
+    "raw":           ({Mode.RAW},                       _ch_raw,                                "ADC (V)",            False),
+    "i":             ({Mode.IQ},                         lambda f, b: f.get_i_volts(b),          "I (V)",              False),
+    "q":             ({Mode.IQ},                         lambda f, b: f.get_q_volts(b),          "Q (V)",              False),
+    "magnitude":     ({Mode.IQ, Mode.ARCTAN_MAGNITUDE},  _ch_magnitude,                          "|signal| (V)",       False),
+    "phase_wrapped": ({Mode.IQ},                         _ch_phase_wrapped,                      "arg(I+jQ) (rad)",    True),
+    "arctan":        ({Mode.ARCTAN_MAGNITUDE},           lambda f, b: f.get_arctan_radians(b),   "arctan(Q/I) (rad)",  True),
+    "phase":         ({Mode.PHASE},                      lambda f, b: f.get_phase(b),            "phase (rad)",        True),
+}
+
+DEFAULT_CHANNEL: dict[Mode, str] = {
+    Mode.RAW:              "raw",
+    Mode.IQ:               "magnitude",
+    Mode.ARCTAN_MAGNITUDE: "magnitude",
+    Mode.PHASE:            "phase",
+}
+
+
+def resolve_channel(name: Optional[str], mode: Mode) -> tuple[str, Resolver, str, bool]:
+    """Resolve a user name into ``(canonical, resolver, label, is_angular)``.
+
+    ``name=None`` -> the mode's default channel. Raises
+    :class:`AudaceDisplayError` if the name is unknown or unavailable for the
+    file's mode.
+    """
+    if name is None:
+        canonical = DEFAULT_CHANNEL[mode]
+    else:
+        canonical = ALIASES.get(name.lower())
+        if canonical is None:
+            known = ", ".join(sorted(set(ALIASES.values())))
+            raise AudaceDisplayError(f"unknown channel '{name}'. Known: {known}")
+
+    valid_modes, resolver, label, is_angular = CHANNELS[canonical]
+    if mode not in valid_modes:
+        for_mode = ", ".join(
+            sorted(k for k, (modes, *_rest) in CHANNELS.items() if mode in modes)
+        )
+        raise AudaceDisplayError(
+            f"channel '{canonical}' unavailable in mode {mode.value}. "
+            f"Available for this mode: {for_mode}"
+        )
+    return canonical, resolver, label, is_angular