🖊️ InkScribe Pro (TabletNote AI)

Fast, hybrid handwriting-to-text note-taking app for graphics tablets and touch screens on Windows.
Powered by Windows Ink (Offline) and Google Gemini Vision (Online AI).

🇹🇷 Türkçe Dokümantasyon

---

🌟 Highlights

• ⚡ Hybrid Recognition Engine:
  • Offline (Windows Ink): Ultra-fast 30ms local handwriting recognition powered by native Windows Ink APIs. No internet connection required.
  • Online (Google Gemini Vision AI): High-accuracy cloud AI recognition using ultra-fast gemini-3.5-flash-lite (~1.2s) with fallback to gemini-3-flash-preview.
  • Resilient Fallback & Quota Protection: Automatically fails over to the next candidate model or drops smoothly to offline Windows Ink if network drops or rate limits occur.
• 🛡️ Explicit Privacy Consent:
  • Handwriting drawings are never transmitted to Google Cloud without explicit user confirmation via an interactive GUI dialog (tkinter.messagebox.askyesno).
• ⌨️ Natural Word-Spaced Auto-Type:
  • Recognized words automatically append trailing whitespace when pasted into your active application (Word, Notion, VS Code, Browser), preventing consecutive handwritten words from sticking together.
• 🎯 Smart Jitter & Tremor Reduction (Adaptive Low-Pass Filter):
  • Eliminates digitizer sensor noise and hand jitter on budget drawing tablets (VEIKK, XP-Pen, Huion) using speed-adaptive dynamic low-pass filtering.
  • Aggressively filters micro-tremors at slow writing speeds for clean letter curves, while scaling to zero latency during fast flicks and crosses.
  • Delivers a smooth, natural ballpoint pen feel and significantly improves Windows Ink / OCR recognition accuracy.
• 💬 Live 2-Line Note Preview & Floating Toast Notifications:
  • Displays the last 2 recognized notes directly on the pad's footer in real-time.
  • Automatically loads and displays the latest notes whenever you switch between notebooks.
  • Displays non-intrusive, temporary toast alerts (e.g., when undo is blocked) with distinct background shading.
• 🖥️ Dual Display Modes with Non-Activating Focus:
  • Floating Mini Pad: Sleek dark-glass PIP (picture-in-picture) notepad that floats on top of your apps. Movable and resizable (DPI scaled). Equipped with Win32 WS_EX_NOACTIVATE so it never steals keyboard focus from Word, your browser, or code editor.
  • Transparent Full-Screen Overlay: Annotate and take notes directly over your entire screen.
• ↶ Smart Undo Buffer:
  • Stylus-friendly [↶] top bar button and Ctrl + Z keyboard shortcut in Full-Screen mode.
  • Protects against accidental scratch-outs or clears without contaminating the restored canvas with scribble lines.
  • Simultaneously reconstructs both the PIL image and native Windows Ink stroke containers.
• ✍️ Intuitive In-Pad Gestures:
  • Scratch-out: Scribble over your drawing to instantly wipe the canvas clean (protected by oscillation density checks against cursive words).
  • Vertical Stroke / Enter Hook (↵): Natural downward stroke creates a newline immediately (protected by Anti-S algorithms so letters like "S" or "s" never trigger false-positive newlines).
• 📚 Floating Card Multi-Notebook Management (defterler/):
  • All notes are organized cleanly in the dedicated defterler/ subfolder (existing root files are migrated automatically).
  • Single compact dropdown card button [📓 Not Defteri (...) ▾] on the top bar switches between Genel, Ders Notları, Yapılacaklar, and Fikirler without button clutter.
  • Interactive popup card includes 📂 Bu Defteri Aç (.txt) and 📁 Defterler Klasörünü Aç to open files and folders in Windows Explorer instantly.
  • In Yapılacaklar (To-Do), sequential handwritten words append to the current item with spacing; a new task item ([ ] ) starts only upon drawing an Enter Hook (↵) or clicking [↵ Gönder].
• 🛡️ Privacy-First Logging & 0% Idle CPU:
  • Handwritten notes are never logged as plaintext; only length and status are tracked.
  • Built-in RotatingFileHandler (128 KB cap, WARNING and ERROR levels only) prevents disk bloat and eliminates unnecessary I/O.
  • Zero idle CPU footprint when nothing is drawn on the canvas.

---

⌨️ Controls & Shortcuts

Shortcut / Button	Supported Mode	Description
F8	Global (Always)	Toggle Note Pad display (configurable in config.json)
F9	Global (Always)	Switch between Floating Mini Pad and Full-Screen Mode
F10	Global (Always)	Cycle Output Target: Dual (Screen+TXT) ➔ Screen Only ➔ TXT Only
[📓 Not Defteri ▾]	Mini Pad & Full-Screen	Open dropdown card: switch notebook, view active .txt, or open defterler/ folder
[↵ Gönder] Button	Mini Pad & Full-Screen	Convert and transmit handwriting immediately without waiting (inserts newline if empty)
[⏱️ Timeout] Button	Mini Pad Bottom Bar	Cycle writing timeout with one tap (1.5s ➔ 2.5s ➔ 3.5s ➔ 5.0s ➔ Manual)
[🎯 Output] Button	Mini Pad Bottom Bar & Full-Screen	One-click toggle between output targets (Dual / Screen Only / TXT Only)
[↶] Button	Mini Pad & Full-Screen	Undo last cleared or scratched-out drawing
[Temizle] Button	Mini Pad & Full-Screen	Clear canvas (saved to undo buffer)
[Tab ⇥] Button	Mini Pad & Full-Screen	Send immediate Tab key to active target window (jump to next form field / cell)
Enter Hook (↵)	Stylus / Pen Gesture	Draw a downward stroke turning left (↵) or vertical flick to start a new line / to-do item (Anti-S protected)
Strike-left (←)	Stylus / Pen Gesture	Quick right-to-left stroke to undo last drawn stroke or restore cleared canvas
Flick-right (→)	Stylus / Pen Gesture	Quick left-to-right stroke to send Tab key to active app (pastes written text first if present)
Scratch-out	Stylus / Pen Gesture	Erase stroke and clear pad (recoverable via ↶ button)
Ctrl + Z	Full-Screen Mode	Undo last cleared drawing
Enter	Full-Screen Mode	Convert drawing to text immediately
Esc	Full-Screen Mode	Hide drawing pad
Shift + Esc	Full-Screen Mode	Exit application completely

ℹ️ Keyboard Focus in Mini Pad Mode:
The Floating Mini Pad utilizes Windows WS_EX_NOACTIVATE window styling so your background application (Word, Notion, VS Code, Browser, etc.) keeps its physical typing focus and text cursor untouched while you write notes with your stylus. Therefore, hardware keyboard strokes (Esc, Enter, Ctrl+Z) continue to route to your underlying app. In Floating Mini Pad mode, all interactions are performed directly via stylus/touch controls ([↶], [Temizle], [✕] buttons and gestures). Keyboard shortcuts are active in Full-Screen overlay mode.

---

🚀 Quick Start

1. Prerequisites

• OS: Windows 10 or Windows 11
• Python: 3.10 or higher
• Graphics Tablet or Stylus: Wacom, VEIKK, XP-Pen, Huion, or any Windows Pen/Touch compatible device.

  💡 Recommended Tablet Driver Settings (VEIKK, XP-Pen, Huion, Wacom):

  1. Windows Ink: Ensure the "Windows Ink" checkbox is enabled in your tablet driver settings (essential for low-latency digitizer integration and smooth handwriting).
  2. Screen Mapping:
     • For Full-Screen Mode: Set to "Full Screen (Display 1)". (If using dual/multi-monitors, select the specific active monitor rather than "All Displays" to prevent horizontal aspect ratio distortion).
     • ⭐ Pro-Tip for Floating Mini Pad (1:1 Pad Mapping): In your tablet driver's Mapping tab, map the active screen area directly to the Mini Pad's desktop bounding box (for 1080p: approx X: 1009, Y: 607, W: 875, H: 406), with Tablet Area set to Full Tablet (100%). This dedicates your entire physical tablet surface solely to the writing canvas, providing a natural, pen-on-paper feel with maximum precision.
  3. Tablet Area & Mode: Set cursor type to "Pen / Absolute Mode" (avoid Mouse/Relative mode). Enable "Keep Aspect Ratio" if available for 1:1 geometric drawing fidelity.

• (Recommended) Ensure your language handwriting pack is installed in Windows:

  Settings > Time & Language > Language & Region > Preferred Language > Options > Handwriting.

2. Clone the Repository

git clone https://github.com/radpy-v4/inkscribe-pro.git
cd inkscribe-pro

3. Install Dependencies

pip install -r requirements.txt

4. Configuration (Optional Gemini Vision AI)

Copy the template configuration file:

copy config.example.json config.json

Open config.json and insert your Google AI Studio Gemini API key:

{
    "gemini_api_key": "YOUR_GEMINI_API_KEY",
    "gemini_model": "gemini-3.5-flash-lite",
    "model_adaylari": [
        "gemini-3.5-flash-lite",
        "gemini-3-flash-preview"
    ],
    "gemini_timeout": 3.5,
    "ai_modu_aktif": true
}

(You can also set the GEMINI_API_KEY environment variable. If left empty, the application runs entirely in offline mode using Windows Ink).

---

🏃 Run Application

python app.py

(For headless background execution without a console window, run pythonw app.py).

Press F8 anywhere in Windows to bring up the notepad and start writing with your pen!

---

🧪 Running Unit Tests

Run the hardware-independent logic and algorithm test suite:

python -m unittest tests/test_logic.py

---

📦 Build Standalone Executable (.exe)

You can package the application into a standalone Windows binary using the automated build scripts (which execute logic tests first and then compile the single-file executable):

:: Windows CMD / Double Click
build.bat

or via PowerShell:

.\build.ps1

(Or directly via PyInstaller: pyinstaller TabletNotAlici.spec)

The compiled single-file executable will be located in dist/TabletNotAlici.exe. In standalone mode, user settings, notebooks, and logs are safely and persistently stored under %APPDATA%\InkScribePro to prevent temporary _MEIPASS data loss.

---

🏗️ Modular Architecture

The codebase is organized into clean, single-responsibility modules:

TABLET_ELYAZİ/
├── src/
│   ├── __init__.py      # Package indicator & public API exports
│   ├── config.py        # ConfigManager, persistent settings & Windows startup registry
│   ├── engine.py        # RecognitionEngine: Windows Ink (Offline) & Gemini Vision (Online)
│   ├── gestures.py      # Pure Scratch-out & Vertical Stroke (Enter) algorithms
│   ├── storage.py       # NotebookManager, multi-notebooks & text formatting
│   ├── tray.py          # TrayManager: System tray icon & desktop notifications
│   └── ui.py            # ArkaPlanNotDonusturucu: Dual-mode UI, drawing canvas & workflow
├── app.py               # Lightweight main entry point
├── tests/
│   └── test_logic.py    # Hardware-independent unit test suite (28 tests)
├── TabletNotAlici.spec  # PyInstaller build specification
└── config.json          # User configuration

---

📄 License

This project is open-source and licensed under the MIT License.