docs: add comprehensive README, architecture documentation, and file format specification

2026-10-06 10:19:19 +02:00
parent d7ffef5368
commit 8da3c04e0c
3 changed files with 438 additions and 0 deletions
@@ -0,0 +1,139 @@
+# Architektur & Technische Dokumentation von ink-notes
+
+Dieses Dokument beschreibt die interne Architektur, mathematische Modelle und Rendering-Pipelines von `ink-notes`.
+
+---
+
+## 1. Die Inking-Pipeline
+
+```
+[Hardware Stylus / Touch / Maus]
+              │
+              ▼
+       [winit Event-Loop]
+              │ (tx, ty, pressure, timestamp)
+              ▼
+   [Viewport Invertierung]  (screen_to_page: Umrechnung in DIN-A4-Einheiten)
+              │
+              ▼
+       [1€-Filter]          (Jitter-Beseitigung bei langsamen Bewegungen)
+              │
+              ▼
+ [Centripetal Catmull-Rom]  (C1-stetige Spline-Interpolation, alpha = 0.5)
+              │
+              ▼
+   [Mesh-Tessellierung]     (Drucksensitive Dreiecksstreifen via Normalen)
+              │
+              ▼
+       [wgpu GPU-Buffer]    (Vertex- & Index-Buffer im VRAM)
+```
+
+### 1.1. 1€-Filter (One-Euro-Filter)
+Stift- und Touch-Eingaben unterliegen bei niedrigen Geschwindigkeiten oft Mikrozittern (Jitter). Standard-Tiefpassfilter verursachen jedoch bei schnellen Schwüngen eine störende Verzögerung (Latenz).
+
+Der 1€-Filter (`filter.rs`) löst dieses Dilemma mit einer adaptiven Grenzfrequenz $f_c$:
+$$f_c = f_{c,\min} + \beta \cdot |\dot{x}|$$
+- Bei geringer Geschwindigkeit ($|\dot{x}| \approx 0$) dominiert $f_{c,\min}$, wodurch Zittern maximal geglättet wird.
+- Bei schnellen Zügen wächst $\beta \cdot |\dot{x}|$ an, wodurch der Filter durchlässig wird und Latenz eliminiert.
+
+### 1.2. Centripetal Catmull-Rom Splines
+Um Ecken zu vermeiden und eine organische Schriftführung zu erzielen, werden Abtastpunkte mit einem zentripetalen Catmull-Rom-Spline (`spline.rs`) interpoliert ($\alpha = 0.5$):
+$$t_{i+1} = t_i + ||P_{i+1} - P_i||^\alpha$$
+Diese Parametrisierung garantiert:
+- Keine Selbstüberschneidungen bei scharfen Wendungen.
+- Keine unerwünschten Cusp-Schleifen.
+- Perfekte $C^1$-Stetigkeit an den Stützstellen.
+
+### 1.3. Drucksensitive Dreiecksstreifen (Tessellierung)
+Aus den interpolierten Spline-Punkten mit Radius $r_i = f(\text{pressure}_i)$ wird ein Triangle-Strip erzeugt:
+1. Richtungsvektor $T_i = P_{i+1} - P_i$.
+2. Senkrechter Normalenvektor $N_i = (-T_{i,y}, T_{i,x}) / ||T_i||$.
+3. An inneren Stützstellen werden Normalen benachbarter Segmente gemittelt (Winkelhalbierende).
+4. Eckpunkte des Dreiecksstreifens:
+   $$V_{i,\text{left}} = P_i + N_i \cdot r_i, \quad V_{i,\text{right}} = P_i - N_i \cdot r_i$$
+
+---
+
+## 2. Rendering & Kamera-Pipeline (`wgpu`)
+
+### 2.1. Virtuelles Koordinatensystem
+Die Anwendung rechnet intern in virtuellen DIN-A4-Koordinaten:
+- Breite: **2100 Einheiten** (210 mm)
+- Höhe: **2970 Einheiten** (297 mm)
+- 1 mm entspricht exakt **10 Einheiten**.
+
+### 2.2. Viewport & Projektionsmatrix (`viewport.rs`)
+Der Vertex-Shader transformiert DIN-A4-Koordinaten über eine Orthogonal-Projektion kombiniert mit Pan und Zoom in Normalized Device Coordinates (NDC, $[-1, 1]$):
+
+```wgsl
+struct CameraUniform {
+    transform: mat4x4<f32>,
+};
+```
+
+Die Projektionsmatrix $M$ wird berechnet aus:
+1. Skalierung des DIN-A4-Papiers auf den Viewport unter Berücksichtigung des Seitenverhältnisses.
+2. Anwenden des Zoom-Faktors $z \in [0.25, 5.0]$.
+3. Translation durch den Pan-Offset $(p_x, p_y)$.
+
+### 2.3. Cursor-zentrierter Zoom
+Beim Zoomen mit dem Mausrad wird der neue Pan-Offset so korrigiert, dass der Punkt unter dem Cursor fixiert bleibt:
+$$\vec{p}_{\text{neu}} = \vec{c} - (\vec{c} - \vec{p}_{\text{alt}}) \cdot \frac{z_{\text{neu}}}{z_{\text{alt}}}$$
+
+### 2.4. Render-Passes
+In jedem Frame werden zwei Hauptpässe durchlaufen:
+1. **Pass 1 (Canvas):**
+   - Hintergrund-Quad und Linien/Gitter (Instanced oder Batch Vertex-Buffer).
+   - Gespeicherte Striche und Geometrie-Meshes.
+   - Aktiver Live-Strich (Ephemeral Buffer).
+   - Auswahl-Overlay & Transformationsgriffe.
+2. **Pass 2 (egui UI):**
+   - Floating Glassmorphism-Toolbar.
+   - Farb- und Werkzeug-Popovers.
+   - Modal-Dokumentenmanager.
+
+---
+
+## 3. Geometrieerkennung & Shape-Fitting (`geometry.rs`)
+
+Die Erkennung erfolgt rein analytisch und deterministisch ohne schwere ML-Frameworks:
+
+### 3.1. Ramer-Douglas-Peucker (RDP)
+Reduziert den Rohpfad auf signifikante Eckpunkte mit konfigurierbarem Toleranzabstand $\epsilon$.
+
+### 3.2. Erkennungsregeln:
+- **Gerade:** Verhältnis von Sehnenlänge ($||P_{\text{end}} - P_{\text{start}}||$) zur Pfad-Bogenlänge $> 0.92$.
+- **Rechteck:** RDP liefert 4 dominante Ecken; Kantenwinkel liegen zwischen $75^\circ$ und $105^\circ$.
+- **Kreis / Ellipse:** Pfad ist geschlossen ($||P_{\text{start}} - P_{\text{end}}|| < 0.1 \times \text{Umfang}$); Standardabweichung der Radien vom Mittelpunkt ist minimal ($< 0.12 \times \bar{r}$).
+- **Koordinatensystem:** Zwei orthogonale Schenkel mit Schnittpunkt nahe dem Start/Ende; Winkel $80^\circ$ bis $100^\circ$ wird exakt auf $90^\circ$ eingerastet; positive Achsenenden erhalten Pfeilspitzen.
+- **Dreiecke / Rhomben / Oktaeder:** Spezifische Eckpunkt- und Symmetrieanalysen der RDP-Kontur.
+
+### 3.3. Draw-and-Hold Erkennung
+Hält der Anwender den Stift am Ende eines Strichs für $> 400\text{ ms}$ innerhalb eines Radius von $< 3\text{ px}$ ruhig, wird die Form im fliegenden Wechsel als Vektorform visualisiert und beim Abheben des Stifts fixiert.
+
+---
+
+## 4. Persistenz & Autosave-Architektur (`storage.rs`, `autosave.rs`)
+
+```
+[UI / Inking Event]
+       │
+       ▼
+ [mark_page_dirty]
+       │
+       ▼
+[AutosaveController] ──(1.5s Debounce)──► [Hintergrund-Thread (MPSC)]
+                                                   │
+                                                   ▼
+                                         [Temp-Datei *.tmp schreiben]
+                                                   │
+                                                   ▼
+                                         [Atomares std::fs::rename]
+                                                   │
+                                                   ▼
+                                         [manifest.json / page_<id>.json]
+```
+
+- **Keine UI-Blockierung:** Disk-I/O erfolgt vollständig in einem dedizierten Worker-Thread.
+- **Atomarität:** Daten werden stets zuerst in `.json.tmp` geschrieben und via `fs::rename` atomar ersetzt.
+- **Verlustfreier Notizbuchwechsel:** Bei `switch_notebook_dir` wird synchron `flush()` aufgerufen, um alle ungespeicherten Daten des aktuellen Dokuments sicherzustellen, bevor der Pfad gewechselt wird.
@@ -0,0 +1,134 @@
+# Dateiformat & Speicherstruktur von ink-notes
+
+Dieses Dokument beschreibt die Speicherstruktur und die JSON-Dateiformate, mit denen `ink-notes` Dokumente auf dem Dateisystem ablegt.
+
+---
+
+## 1. Verzeichnisstruktur
+
+Notizbücher werden standardmäßig unter dem XDG-Datenpfad gespeichert:
+
+```text
+~/.local/share/ink-notes/
+└── notebooks/
+    ├── <notebook_id_1>/
+    │   ├── manifest.json
+    │   ├── page_1.json
+    │   ├── page_2.json
+    │   └── ...
+    └── <notebook_id_2>/
+        ├── manifest.json
+        └── page_1.json
+```
+
+---
+
+## 2. Dokumenten-Manifest (`manifest.json`)
+
+Das Manifest enthält Metadaten über das gesamte Dokument sowie die Reihenfolge und IDs aller Seiten:
+
+```json
+{
+  "id": "notebook-a1b2c3d4",
+  "title": "Mathematik Vorlesung",
+  "version": 1,
+  "pages": [
+    {
+      "id": 1,
+      "file_name": "page_1.json"
+    },
+    {
+      "id": 2,
+      "file_name": "page_2.json"
+    }
+  ],
+  "current_page_index": 0,
+  "next_page_id": 3,
+  "next_stroke_id": 42,
+  "created_at": 1775460000,
+  "modified_at": 1775463600
+}
+```
+
+### Felder:
+- `id`: Eindeutige ID des Notizbuchs (z. B. UUID oder `"default"`).
+- `title`: Vom Nutzer vergebener Anzeigename des Notizbuchs.
+- `version`: Format-Versionsnummer (aktuell `1`).
+- `pages`: Geordnete Liste von Seitenreferenzen.
+- `current_page_index`: Index der zuletzt aktiven Seite für Session-Restore.
+- `next_page_id`: Inkrementierender ID-Zähler für neue Seiten.
+- `next_stroke_id`: Globaler ID-Zähler für neue Striche.
+- `created_at` / `modified_at`: UNIX-Zeitstempel in Sekunden.
+
+---
+
+## 3. Seitendatei (`page_<id>.json`)
+
+Jede Seite wird in einer eigenen Datei gespeichert, um Lazy-Loading und schnelles inkrementelles Speichern zu ermöglichen.
+
+```json
+{
+  "id": 1,
+  "background": "Grid5mm",
+  "strokes": [
+    {
+      "id": 1,
+      "color": [0.12, 0.12, 0.14, 1.0],
+      "width_mm": 0.5,
+      "samples": [
+        {
+          "x": 350.2,
+          "y": 420.5,
+          "pressure": 0.65,
+          "timestamp": 12.345
+        },
+        {
+          "x": 352.1,
+          "y": 425.8,
+          "pressure": 0.70,
+          "timestamp": 12.355
+        }
+      ],
+      "recognized_shape": null
+    },
+    {
+      "id": 2,
+      "color": [0.15, 0.35, 0.85, 1.0],
+      "width_mm": 0.8,
+      "samples": [],
+      "recognized_shape": {
+        "Rectangle": {
+          "top_left": { "x": 500.0, "y": 600.0 },
+          "width": 300.0,
+          "height": 200.0
+        }
+      }
+    }
+  ]
+}
+```
+
+### Felder:
+- `id`: Eindeutige ID der Seite.
+- `background`: Papiermuster (`Blank`, `Grid5mm`, `Lined`, `DotGrid`).
+- `strokes`: Liste der auf der Seite gezeichneten Striche und Vektorformen.
+  - `id`: Eindeutige ID des Strichs.
+  - `color`: RGBA-Farbwerte im Bereich `[0.0, 1.0]`.
+  - `width_mm`: Basis-Strichbreite in Millimetern.
+  - `samples`: Rohabtastpunkte entlang des Pfads (`x`, `y` in DIN-A4-Einheiten, `pressure` in `[0.0, 1.0]`, `timestamp` in Sekunden).
+  - `recognized_shape`: Optionales Enum für geometrische Vektorformen:
+    - `Line { start, end }`
+    - `Rectangle { top_left, width, height }`
+    - `Circle { center, radius }`
+    - `Axes { origin, x_end, y_end, has_arrows }`
+    - `Triangle { p1, p2, p3 }`
+    - `Rhombus { center, width, height }`
+    - `Octahedron { center, radius }`
+
+---
+
+## 4. Atomares Schreibverfahren
+
+Um Datenverlust bei Stromausfall oder plötzlichem Prozessabbruch zu verhindern:
+1. Daten werden in `<ziel>.tmp` serialisiert und per `fsync` auf das Speichermedium geschrieben.
+2. Mittels `std::fs::rename("<ziel>.tmp", "<ziel>")` wird die Zieldatei auf POSIX-Systemen atomar ersetzt.