From 94124f974e6532183e3178f9838edbc9990fa783 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=27=C3=A9lectron=20rare?=
 <108685187+electron-rare@users.noreply.github.com>
Date: Mon, 18 May 2026 17:38:16 +0200
Subject: [PATCH] docs: document oscope-sphere project

Add the project CLAUDE.md and README covering the build, the stereo
channel convention, the three layers, controls, and the 16 MS/s
dual-channel hardware constraint.
---
 oscope-sphere/CLAUDE.md | 62 +++++++++++++++++++++++++++++++++++++++++
 oscope-sphere/README.md | 56 +++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+)
 create mode 100644 oscope-sphere/CLAUDE.md
 create mode 100644 oscope-sphere/README.md

diff --git a/oscope-sphere/CLAUDE.md b/oscope-sphere/CLAUDE.md
new file mode 100644
index 0000000..fe07881
--- /dev/null
+++ b/oscope-sphere/CLAUDE.md
@@ -0,0 +1,62 @@
+# oscope-sphere
+
+Visualiseur openFrameworks C++ : capture Hantek 6022 (2 canaux) via
+libusb -> FFT -> une sphere 3D stereo avec 3 couches composables.
+Derive de `oscope-of` (couche capture reutilisee, demoparty jetee).
+
+## Build
+
+```bash
+cd oscope-sphere
+make            # debug
+make Release    # release
+make Run        # lance bin/oscope-sphere
+
+./tests/run_tests.sh   # tests C++ purs (clang++, sans openFrameworks)
+```
+
+Cible macOS principale (Hantek via libusb). `config.make` detecte
+libusb (pkg-config, puis brew, puis chemins par defaut).
+
+## Architecture
+
+| Composant | Fichier |
+|-----------|---------|
+| Capture USB Hantek 6022 (16 MS/s, 2 ch) | `HantekDevice.{h,cpp}` (copie) |
+| Downsampling + FFT 2048 | `AudioAnalyzer.{h,cpp}`, `FFT.{h,cpp}` (copie) |
+| Ring buffer SPSC CH1/CH2 | `ScopeData.h` (copie) |
+| Spectrogramme roulant log-freq | `SpectrogramBuffer.{h,cpp}` |
+| Signal de demo (pas de scope) | `DemoSignal.{h,cpp}` |
+| Sphere : peau spectro + relief waveform + points | `SphereViz.{h,cpp}` |
+| Anneaux waveform orbitaux | `OrbitRings.{h,cpp}` |
+| Cycle de vie, camera, HUD | `ofApp.{h,cpp}`, `main.cpp` |
+| Shaders sphere | `bin/data/shaders/sphere.{vert,frag}` |
+
+## Convention canaux
+
+La sphere est coupee a l'equateur : hemisphere Nord = CH1, Sud = CH2.
+Cette convention tient sur les 3 couches.
+
+## Couches (touches 1 / 2 / 3)
+
+- A (`1`) : sphere — peau spectrogramme + deplacement waveform
+- B (`2`) : deux anneaux waveform orbitaux (un par canal)
+- C (`3`) : nuage de points
+- `c` : cycle colormap (magma / viridis) ; `space` : fige le defilement
+
+## Conventions
+
+- GLSL 150 GL 3.2 core uniquement. Shaders dans `bin/data/shaders/`.
+- Pas d'allocations dans `update()` / `draw()` — buffers preallouees.
+- AudioAnalyzer mixe ses 2 arguments : `update(chX, chX)` isole chX.
+  Deux analyzers, un par canal.
+- 24/48 MS/s sont mono-canal sur le firmware OpenHantek6022 — la
+  capture deux-canaux tourne donc a 16 MS/s.
+- Scope absent -> mode demo automatique (signal synthetique).
+
+## Anti-patterns
+
+- Ne pas committer `bin/oscope-sphere*` (binaires).
+- Ne pas faire d'I/O fichier ni de `new` dans la hot loop.
+- Ne pas modifier les 4 fichiers copies de `oscope-of` — les
+  resynchroniser depuis `oscope-of/src/` si besoin.
diff --git a/oscope-sphere/README.md b/oscope-sphere/README.md
new file mode 100644
index 0000000..fb251fd
--- /dev/null
+++ b/oscope-sphere/README.md
@@ -0,0 +1,56 @@
+# oscope-sphere
+
+A minimal openFrameworks visualiser: it captures both channels of a
+Hantek 6022 oscilloscope and renders them as a single 3D sphere.
+
+The sphere is split at the equator — **northern hemisphere = CH1,
+southern hemisphere = CH2** — across three composable layers:
+
+- **Layer A** — the sphere itself: its skin is a scrolling spectrogram
+  (latitude = log frequency, longitude = time) and its geometry is
+  displaced radially by the live waveform.
+- **Layer B** — two waveform rings orbiting the sphere in perpendicular
+  planes, one per channel.
+- **Layer C** — the sphere rendered as a point cloud.
+
+It reuses the capture and analysis layer of the sibling `oscope-of`
+project.
+
+## Build and run
+
+```bash
+cd oscope-sphere
+make && make Run
+```
+
+Requires openFrameworks (GL 3.2 core) and libusb-1.0. Without a scope
+connected the app runs in demo mode on a synthetic signal.
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| `1` / `2` / `3` | toggle layers A / B / C |
+| `c` | cycle colormap (magma / viridis) |
+| `space` | freeze the spectrogram scroll |
+| mouse drag | orbit the camera |
+
+## Tests
+
+```bash
+./tests/run_tests.sh
+```
+
+Runs the pure-C++ unit tests (FFT, per-channel split, spectrogram
+buffer, demo signal) — no openFrameworks needed.
+
+## Hardware note
+
+24/48 MS/s are single-channel-only on the OpenHantek6022 firmware;
+because both channels are used, capture runs at 16 MS/s. Only one
+process may own the scope at a time — close OpenHantek6022 before
+running this app.
+
+## License
+
+GPL-3.0, as part of the AV-Live monorepo.