# 🖋️ ink-notes Eine latenzoptimierte, hardwarebeschleunigte Inking- und Notizbuch-Anwendung für Linux, entwickelt in **Rust** mit **wgpu** und **winit**. `ink-notes` kombiniert minimale Eingabelatenz beim Zeichnen mit Stift, Touchpad oder Maus mit einem flüssigen stufenlosen Viewport, automatischer Geometrie- und Formerkennung, Objekttransformationen, Multi-Dokumenten-Verwaltung und Vektor-PDF-Export. --- ## ✨ Features im Überblick ### ⚡ Latenzoptimierte Inking-Pipeline - **Hardware-Rendering:** Direct-to-Screen-Rendering mit `wgpu` (Vulkan / X11 / Wayland) unter Nutzung von `PresentMode::Mailbox` für minimale Eingabeverzögerung. - **Zwei-Stufen-Modell:** 1. *Live-Phase:* Eingehende Stylus-Samples werden in Echtzeit durch einen 1€-Filter (One-Euro-Filter) entprellt und inkrementell als GPU-Meshes dargestellt. 2. *Commit-Phase (Post-Stroke Finalisierung):* Akausale Ecken-Erkennung (Corner Preservation bei Knicken > 65°), gewichtetes 3-Punkt-Druckfenster, Ramer-Douglas-Peucker (RDP) Dezimierung und saubere runde Endkappen. - **Centripetal Catmull-Rom Splines:** Weiche C1-stetige Kurveninterpolation ohne Überschwinger oder Schleifen. - **Werkzeuge:** - **Stift (Pen):** Feine, variable Strichstärken (0.3 mm bis 1.2 mm) mit Notiz-Farben (Schwarz, Blau, Rot, Grün, Grau). - **Textmarker (Highlighter):** Breite, halbtransparente Striche (4.0 mm bis 8.0 mm) mit Multiplikations-Blending. - **Radierer (Eraser):** Segment- und abstandsbasierte Löschung einzelner Striche auf dem DIN-A4-Canvas. ### 🔍 Stufenloser Zoom & Pan (Kamera) - **Viewport-Transformation:** 2D-Projektionsmatrix im WGSL-Vertex-Shader. - **Cursor-zentrierter Zoom:** Stufenloses Zoomen von **25 % bis 500 %** zentriert auf die Cursor-Position via Mausrad, Trackpad-Pinch oder Tastenkürzel (`Strg +` / `Strg -` / `Strg 0`). - **Pan:** Verschieben des Canvas per mittlerer Maustaste, `Leertaste + Drag` oder Trackpad-Pan. - **Inverse Koordinatentransformation:** Präzise Umrechnung von Bildschirm- in DIN-A4-Dokumentkoordinaten (`screen_to_page`). ### 📐 Geometrie- & Objekterkennung (Shape Recognition) - **Erkannte Primitiven:** - **Geraden (Line):** Sehnen- zu Pfadlängenverhältnis > 0.92. - **Rechtecke (Rectangle):** 4 orthogonale Ecken via Douglas-Peucker-Polygonzug (RDP). - **Kreise & Ellipsen (Circle/Ellipse):** Geschlossene Pfade mit minimaler Varianz via Least-Squares Circle Fit. - **Koordinatensysteme (Axes):** Zwei orthogonale Achsen (80°–100° gesnappt auf exakt 90°) mit Richtungspfeilen. - **Dreiecke, Rhomben / Rauten & Oktaeder:** Regelmäßige Polygone mit Eckpunkt-Analyse. - **Interaktionsmodelle:** - **Draw-and-Hold:** Verweilt der Stift am Ende eines Strichs für > 400 ms regungslos (< 3 px), snappt die Skizze sofort automatisch in eine perfekte Vektorform ein. - **Formen-Werkzeug (Shape Mode):** Direkte Erkennung und Ersetzung beim Loslassen. ### 🖐️ Objektauswahl & Transformation (Lasso / Select) - **Lasso & Klick-Auswahl:** Schnelles Markieren einzelner Striche oder Gruppen per Rahmen (`V`). - **Echtzeit-Verschieben:** Freies Verschieben ausgewählter Objekte über die Seite. - **Stufenlose Skalierung:** Größenänderung über interaktive Eck-Griffe. - **Drehung:** Stufenlose Rotation um das Objektzentrum über den oberen Dreh-Griff oder exakte 90°-Schritte mit Taste `R`. - **Multicolor-Umfärbung:** Ausgewählte Objekte direkt über die Farbpalette umfärben. - **Clipboard & Editieren:** Kopieren (`Strg + C`), Einfügen (`Strg + V`) und Löschen (`Entf` / `Backspace`). - **Undo / Redo:** Vollständige Transaktionshistorie (`Strg + Z` / `Strg + Y`) für alle Aktionen inklusive Transformationen. ### 📚 Multi-Dokumenten- & Notizbuch-Verwaltung - **Dateisystem-Architektur:** Jedes Dokument wird in einem separaten Verzeichnis unter `~/.local/share/ink-notes/notebooks//` mit `manifest.json` und Einzelseiten (`page_.json`) gespeichert. - **Dokumenten-Manager:** Toolbar-Modal zum Anlegen, Wechseln, Umbenennen und Löschen von Notizbüchern. - **Verlustfreier Wechsel:** Beim Dokumentenwechsel sichert ein synchroner Disk-Flush alle anstehenden Änderungen garantiert ab. ### 📄 Seiten & Hintergründe - **Virtuelles DIN-A4-Raster:** 2100 × 2970 Koordinateneinheiten (10 Einheiten = 1 mm). - **Hintergrundmuster:** Blanko, Kariert (5 mm), Liniert (7.5 mm), Punktraster (5 mm). - **Seitenverwaltung:** Vor- und Zurückblättern, neue Seiten anfügen, Seitensprung-Menü. ### 💾 Autosave & Persistenz - **Asynchroner Autosave-Controller:** Sichert Änderungen im Hintergrund nach 1.5 s Ruhezeit (Debounce), ohne das Zeichnen zu blockieren. - **Atomares Schreiben:** Temp-Dateien mit atomarem Rename (`manifest.json.tmp` -> `manifest.json`) schützen vor Datenkorruption bei Abstürzen. - **Dediziertes Speichern (`Strg + S`):** Sofortiger, synchroner Disk-Flush mit visueller Toast-Rückmeldung. - **Sicherer Shutdown:** `Strg + Q` oder Schließen des Fensters führt vor Programmende einen vollständigen synchronen Flush aus. ### 🖨️ Vektor-PDF-Export - Exportiert das Dokument via `printpdf` nach `~/Documents/.pdf` (mit automatischer Kollisionsvermeidung `_1`, `_2`). - Striche und geometrische Formen werden als skalierbare Vektoren ausgegeben. Kürzel: `Strg + E`. --- ## 📦 Release, Packaging & Updater - **Natives .deb-Paket**: Optimiert für Zorin OS 18 (Ubuntu 24.04 LTS Basis) mit vollständiger XDG Desktop-Integration (`.desktop`, Hicolor-Icons SVG & PNG, AppStream Metainfo, Debian Copyright & Changelog). - **Portables .AppImage**: Eigenständiges x86_64 Bundle. - **In-App Updater (`src/updater.rs`)**: Automatischer Prüflauf gegen Gitea Releases, SemVer-Filterung, SHA-256-Prüfung und atomarer In-Place Austausch. ### 1. Release-Pakete bauen ```bash # Baut .deb, .AppImage und berechnet SHA256SUMS.txt in target/ ./scripts/build-release.sh ``` Ergebnis in `target/`: - `ink-notes_0.1.0_amd64.deb` - `ink-notes_0.1.0_x86_64.AppImage` - `SHA256SUMS.txt` ### 2. Installation auf Zorin OS 18 / Ubuntu 24.04 ```bash # Natives Debian-Paket installieren sudo dpkg -i target/ink-notes_0.1.0_amd64.deb # Oder portables AppImage starten chmod +x target/ink-notes_0.1.0_x86_64.AppImage ./target/ink-notes_0.1.0_x86_64.AppImage ``` #### Hinweise zu AppImage, glibc & FUSE: - **glibc-Mindestversion:** `ink-notes` benötigt `glibc >= 2.39` (Standard unter Ubuntu 24.04 LTS und Zorin OS 18). - **Host-Grafikstack:** Das AppImage bündelt die Anwendungslogik, nutzt für maximale Performance und Hardwarebeschleunigung jedoch den Treiber- und Grafikstack des Host-Systems (Vulkan ICD-Treiber, Wayland bzw. X11). - **FUSE 2 / FUSE 3 Kompatibilität:** Ubuntu 24.04-basierte Distributionen nutzen standardmäßig FUSE 3 (`fuse3`). Sollte das AppImage beim Start einen Fehler bezüglich `libfuse.so.2` ausgeben, kann entweder das Kompatibilitätspaket installiert werden: ```bash sudo apt install libfuse2t64 ``` oder das AppImage direkt ohne FUSE entpackt und ausgeführt werden: ```bash ./ink-notes_0.1.0_x86_64.AppImage --appimage-extract-and-run ``` ### 3. Release auf Gitea veröffentlichen Das Skript arbeitet vollkommen idempotent und aktualisiert bei wiederholter Ausführung Release-Notizen und Assets: ```bash export GITEA_TOKEN="" ./scripts/publish-gitea-release.sh ``` --- ## 🛡️ Updater-Sicherheit Der In-App-Updater (`src/updater.rs`) folgt strengen Sicherheitsrichtlinien: 1. **SHA-256-Integritätsprüfung:** - Vor jeder Ausführung oder Installation wird die offizielle Prüfsummendatei `SHA256SUMS.txt` aus dem Release bezogen. - Der SHA-256-Hash des heruntergeladenen Pakets wird berechnet (`sha2`). - Weicht die Prüfsumme ab oder fehlt ein Eintrag, wird die Datei sofort gelöscht und der Installationsvorgang mit Fehlermeldung abgebrochen. - *Hinweis zur Authentizität:* Eine Prüfsumme vom selben Release-Server garantiert Schutz gegen Übertragungsfehler und Datei-Beschädigungen, jedoch keine kryptografische Nicht-Abstreitbarkeit gegenüber einem kompromittierten Server. 2. **Signatur-Ausblick:** - Die Updater-Architektur enthält Schnittstellen für optionale `.sig`/`.minisig`-Signaturen zur zukünftigen End-to-End-Kryptoverifikation über öffentliche Schlüssel. 3. **Redirect-Schutz & HTTPS:** - Alle API- und Download-Endpunkte erzwingen standardmäßig HTTPS. - Bei HTTP-Redirects werden sensible Autorisierungs-Header (`Authorization: token ...`) verworfen, sobald die Weiterleitung auf eine andere Origin oder ein externes CDN verweist. 4. **Isolierter Download-Pfad & Path-Traversal-Schutz:** - Downloads werden in einem isolierten Benutzerverzeichnis abgelegt (`$XDG_CACHE_HOME/ink-notes/updates` bzw. `~/.cache/ink-notes/updates`, Berechtigung `0700`). - Asset-Namen werden sanitisiert: Pfadtrenner (`/`, `\`), Pfadüberquerungen (`..`), Steuerzeichen und leere Dateinamen werden strikt abgewiesen. 5. **Atomarer AppImage-Tausch:** - Kein direktes Überschreiben laufender Programmdateien per `fs::copy` (verhindert den Linux-Kernel-Fehler *"Text file busy"*). - Die neue Datei wird temporär im selben Verzeichnis angelegt (`.new.`), mit Ausführungsrechten (`0755`) versehen, das bestehende AppImage als `.bak` gesichert (dessen Fehler nicht ignoriert werden) und anschließend per atomarem `fs::rename` ausgetauscht. --- ## ⚙️ CI-Runner einrichten (Gitea Actions / act_runner) Der Veröffentlichungs-Workflow liegt unter [`.gitea/workflows/release.yaml`](.gitea/workflows/release.yaml). ### Runner-Label konfigurieren Der Workflow nutzt standardmäßig das Runner-Label: ```yaml runs-on: ubuntu-latest ``` In der Konfigurationsdatei Ihres Gitea `act_runner` (`config.yaml`) muss dieses Label auf ein passendes Container-Image oder den Host gemappt sein: ```yaml runner: labels: - "ubuntu-latest:docker://catthehacker/ubuntu:act-latest" # oder für native Host-Ausführung: # - "ubuntu-latest:host" ``` ### Diagnose & Fehlerbehebung Bleibt ein Release-Job auf **"Waiting to run"** hängen: 1. **Runner online?** Prüfen Sie in Gitea unter *Einstellungen -> Aktionen -> Runner*, ob der `act_runner` aktiv und mit einem grünen Punkt als *Online* markiert ist. 2. **Label-Übereinstimmung:** Stimmen die im Runner registrierten Labels exakt mit dem `runs-on`-Feld in `.gitea/workflows/release.yaml` überein? 3. **Rechte:** Der Workflow prüft `if [ "$(id -u)" -ne 0 ]` und setzt `sudo` nur ein, wenn der Runner nicht als `root` läuft. Das verhindert Fehler sowohl in unprivilegierten Host-Umgebungen als auch in Root-Containern. --- ## 🚀 Schnellstart (Entwicklung) ### Voraussetzungen - **Rust & Cargo:** Version 1.75 oder neuer (`rustup update stable`) - **System-Bibliotheken (Linux):** - Vulkan-Treiber (z. B. `mesa-vulkan-drivers` oder proprietäre Treiber) - X11 / Wayland Bibliotheken (`libx11-dev`, `libxcursor-dev`, `libxrandr-dev`, `libxi-dev`, `libxkbcommon-dev`) ### Bauen & Ausführen ```bash # Repository klonen git clone https://gitea.pansi.eu/harald/ink-notes.git cd ink-notes # Kompilieren und starten via Starter-Skript ./run.sh ``` Alternativ direkt mit Cargo: ```bash cargo run --release ``` --- ## ⌨️ Tastatur- & Maus-Shortcuts | Aktion | Tastenkürzel / Mausgeste | | :--- | :--- | | **Zeichnen** | Linke Maustaste / Stiftspitze | | **Canvas verschieben (Pan)** | Mittlere Maustaste **oder** `Leertaste + Drag` | | **Zoom zentriert auf Cursor** | Mausrad / Touchpad-Pinch | | **Zoom zurücksetzen (100 %)** | `Strg + 0` | | **Zoom In / Out** | `Strg + +` / `Strg + -` | | **Auswahlwerkzeug (Lasso)** | `V` | | **Auswahl um 90° drehen** | `R` | | **Kopieren & Einfügen** | `Strg + C` / `Strg + V` | | **Auswahl löschen** | `Entf` oder `Backspace` | | **Undo / Redo** | `Strg + Z` / `Strg + Y` (oder `Strg + Shift + Z`) | | **Nächste Seite** | `Bild ab (PageDown)` oder `N` | | **Vorherige Seite** | `Bild auf (PageUp)` | | **Erste / Letzte Seite** | `Pos 1 (Home)` / `Ende (End)` | | **Jetzt speichern (Disk Flush)** | `Strg + S` | | **Vektor-PDF-Export** | `Strg + E` | | **Dialoge / Menüs schließen** | `Esc` | | **Beenden (mit Disk-Flush)** | `Strg + Q` (oder Fenster schließen) | --- ## 🏗️ Projekt- und Modul-Architektur ```text src/ ├── main.rs # Event-Loop (winit), Input-Routing, App-Orchestrierung ├── lib.rs # Bibliotheks-Exporte für Tests und Komponenten ├── canvas.rs # wgpu Render-Pipeline, GPU-Buffer, Zeichenzustand ├── viewport.rs # Kamera-Pan, Zoom, 2D-Transformationsmatrizen ├── shader.wgsl # WGSL Vertex- & Fragment-Shader für Inking-Meshes ├── filter.rs # One-Euro-Filter gegen Eingabe-Jitter ├── spline.rs # Catmull-Rom, Corner Preservation & Dreiecksstreifen ├── geometry.rs # RDP-Algorithmus, Least-Squares Circle Fit, Shape Recognition ├── selection.rs # Lasso-Auswahl, Bounding-Box, Griffe, Rotation & Skalierung ├── background.rs # Tessellierung für Kariert, Liniert, Punktraster ├── document.rs # Notizbuch-Datenmodell, Seiten, DIN-A4-Koordinatensystem ├── history.rs # Undo/Redo-Transaktionsstapel (Add, Erase, Transform) ├── storage.rs # Atomares Laden/Speichern von Manifest & Seiten, Multi-Notebooks ├── autosave.rs # Debounced Hintergrund-Autosave mit MPSC-Kanal ├── updater.rs # In-App Gitea Updater (SemVer, HTTPS, SHA256-Integrität, Self-Update) ├── export.rs # Skalierbarer Vektor-PDF-Export via printpdf └── ui.rs # Floating Glassmorphism-Toolbar, Dokumenten- & Update-Manager (egui) ``` Ausführliche Details zur Architektur und mathematischen Modellen findest du unter [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). --- ## 🧪 Tests ausführen Die gesamte Inking-Pipeline, Geometrieerkennung, Speicherlogik und der Updater sind mit umfassenden Unit-Tests abgesichert: ```bash cargo test ``` Alle Unit-Tests prüfen Berechnungen, Hit-Testing, Undo/Redo, Persistenz, Updater-Sicherheit und Versionsvergleiche konsistent ab. --- ## 📄 Lizenz Dieses Projekt ist unter der [MIT-Lizenz](LICENSE) lizenziert (Copyright © 2026 Harald Pansi).