plan.md file
This commit is contained in:
yzinchuk
@@ -0,0 +1,380 @@
|
|||||||
|
# OCR Screenshot Gallery — Project Reference
|
||||||
|
|
||||||
|
A Qt6 desktop application for Linux that OCRs screenshots and provides a searchable, paginated gallery interface. Users run a Python OCR script to populate a SQLite database, then browse and search all recognized text visually.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
ocr-screenshot-gallery/
|
||||||
|
├── CMakeLists.txt # CMake build configuration (Qt6)
|
||||||
|
├── build.sh # One-shot build automation script
|
||||||
|
├── README.md # User-facing documentation
|
||||||
|
├── resources.qrc # Qt resource file bundling icons
|
||||||
|
├── screenshot-gallery.desktop # Linux XDG desktop entry
|
||||||
|
├── .gitignore
|
||||||
|
│
|
||||||
|
├── src/ # C++ application source
|
||||||
|
│ ├── main.cpp
|
||||||
|
│ ├── mainwindow.h / mainwindow.cpp
|
||||||
|
│ ├── imagegallery.h / imagegallery.cpp
|
||||||
|
│ ├── databasemanager.h / databasemanager.cpp
|
||||||
|
│ ├── settingsdialog.h / settingsdialog.cpp
|
||||||
|
│ └── updatedatabasedialog.h / updatedatabasedialog.cpp
|
||||||
|
│
|
||||||
|
├── OCR-scripts/ # Python OCR utilities + shell helpers
|
||||||
|
│ ├── ocr_screenshots.py # Main OCR runner
|
||||||
|
│ ├── ocr_rofi.sh # Rofi launcher integration
|
||||||
|
│ ├── direct_rofi_ocr.sh
|
||||||
|
│ ├── simple_rofi_ocr.sh
|
||||||
|
│ ├── rofi_ocr_search.sh
|
||||||
|
│ ├── ocr_search_rofi.py
|
||||||
|
│ ├── search_ocr.py
|
||||||
|
│ └── screenshot_ocr.db # Example/seed database
|
||||||
|
│
|
||||||
|
├── icons/ # Application icon assets
|
||||||
|
│ ├── orcs-gallery-512.png
|
||||||
|
│ ├── orcs-gallery-256.png
|
||||||
|
│ ├── orcs-gallery-128.png
|
||||||
|
│ └── orcs-gallery-64.png
|
||||||
|
│
|
||||||
|
└── build/ # CMake build output (git-ignored)
|
||||||
|
└── screenshot-gallery # Compiled executable
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
| Layer | Technology |
|
||||||
|
|---|---|
|
||||||
|
| GUI framework | Qt 6 (Core, Gui, Widgets, Sql, Concurrent) |
|
||||||
|
| Build system | CMake 3.16+, C++17 |
|
||||||
|
| Database | SQLite 3 via Qt6::Sql |
|
||||||
|
| Full-text search | SQLite FTS5 with Porter stemmer |
|
||||||
|
| OCR engine | Tesseract (invoked via Python subprocess) |
|
||||||
|
| OCR scripting | Python 3 |
|
||||||
|
| Linux integration | XDG Base Directory Specification |
|
||||||
|
| Launcher integration | Rofi (optional, via shell scripts) |
|
||||||
|
|
||||||
|
Qt modules used: `Qt6::Core`, `Qt6::Gui`, `Qt6::Widgets`, `Qt6::Sql`, `Qt6::Concurrent`
|
||||||
|
|
||||||
|
Qt features relied upon: MOC (signals/slots), QSettings (INI persistence), QProcess (subprocess management), QtConcurrent (thread pool), QScrollArea, QGridLayout, QSqlDatabase.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
### Automated (recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod +x build.sh
|
||||||
|
./build.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
The script checks for cmake and Qt6 packages, creates the build directory, runs cmake, then `make -j$(nproc)`.
|
||||||
|
|
||||||
|
### Manual
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p build && cd build
|
||||||
|
cmake ..
|
||||||
|
make -j$(nproc)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/screenshot-gallery
|
||||||
|
```
|
||||||
|
|
||||||
|
### Install system-wide
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd build && sudo make install
|
||||||
|
screenshot-gallery # from anywhere
|
||||||
|
```
|
||||||
|
|
||||||
|
Installation puts:
|
||||||
|
- Binary → `${CMAKE_INSTALL_BINDIR}` (typically `/usr/local/bin/`)
|
||||||
|
- Icons → `/share/icons/hicolor/{64x64,128x128,256x256,512x512}/apps/orcs-gallery.png`
|
||||||
|
- Desktop entry → `/share/applications/screenshot-gallery.desktop`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database
|
||||||
|
|
||||||
|
### Location
|
||||||
|
|
||||||
|
Default (XDG-compliant): `~/.local/share/screenshot-gallery/screenshot_ocr.db`
|
||||||
|
|
||||||
|
Configurable in Settings dialog; stored in `~/.config/ScreenshotOCRGallery/settings.ini`.
|
||||||
|
|
||||||
|
### Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE ocr_results (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
filename TEXT UNIQUE,
|
||||||
|
full_path TEXT,
|
||||||
|
ocr_text TEXT,
|
||||||
|
file_size INTEGER,
|
||||||
|
created_date TEXT,
|
||||||
|
ocr_date TEXT
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
- `filename` — bare filename, uniqueness-constrained (prevents duplicate OCR runs)
|
||||||
|
- `full_path` — absolute path used to load the thumbnail image
|
||||||
|
- `ocr_text` — raw Tesseract output; this is what gets searched
|
||||||
|
- `file_size`, `created_date`, `ocr_date` — metadata/audit fields
|
||||||
|
|
||||||
|
### FTS5 Virtual Table (auto-created if SQLite FTS5 is available)
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE VIRTUAL TABLE ocr_fts USING fts5(
|
||||||
|
ocr_text,
|
||||||
|
content='ocr_results',
|
||||||
|
content_rowid='id',
|
||||||
|
tokenize='porter unicode61'
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
Three triggers keep `ocr_fts` in sync with `ocr_results` (INSERT, UPDATE, DELETE). The Porter stemmer enables morphological matching (e.g. "running" matches "run"). Unicode61 tokenizer handles non-ASCII text.
|
||||||
|
|
||||||
|
When FTS5 is unavailable, the app falls back to a `LIKE '%...%'` query on a standard index on `ocr_text`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Application Architecture
|
||||||
|
|
||||||
|
### Source Files
|
||||||
|
|
||||||
|
#### `main.cpp`
|
||||||
|
Entry point. Constructs `QApplication`, sets app metadata and icon, instantiates `MainWindow`, calls `app.exec()`.
|
||||||
|
|
||||||
|
#### `mainwindow.h/.cpp`
|
||||||
|
Central controller. Inherits `QMainWindow`.
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
- Menu bar: File → Open, Settings, Update Database, Quit
|
||||||
|
- Search bar (`QLineEdit`) with a 500 ms typing-inactivity timer (`m_typingTimer`) — search only fires after the user stops typing
|
||||||
|
- Animated "Searching…" status bar indicator (`m_searchingAnimationTimer`)
|
||||||
|
- Instantiates and owns `DatabaseManager` and `ImageGallery`
|
||||||
|
- Reads/writes settings via `QSettings` (INI at `~/.config/ScreenshotOCRGallery/settings.ini`)
|
||||||
|
- On search complete: updates status bar with result count
|
||||||
|
- On clear search: reloads all images (first page)
|
||||||
|
|
||||||
|
Settings keys:
|
||||||
|
- `databasePath` — path to `.db` file
|
||||||
|
- `screenshotsDir` — directory scanned by OCR script
|
||||||
|
- `imagePreloadCount` — initial gallery page size (default: 20)
|
||||||
|
|
||||||
|
#### `imagegallery.h/.cpp`
|
||||||
|
Custom `QWidget` displaying thumbnails in a responsive grid.
|
||||||
|
|
||||||
|
**`ImageThumbnail`** (inner `QLabel` subclass):
|
||||||
|
- Fixed 256×256 px display
|
||||||
|
- `mousePressEvent` opens file in default viewer (`QDesktopServices::openUrl`)
|
||||||
|
- Filename label overlaid at bottom with semi-transparent dark background
|
||||||
|
- Cursor changes to `Qt::PointingHandCursor` on hover
|
||||||
|
|
||||||
|
**`ImageGallery`**:
|
||||||
|
- `QScrollArea` wrapping a `QWidget` with `QGridLayout`
|
||||||
|
- Column count recalculated on resize: `columns = max(1, availableWidth / (256 + spacing))`
|
||||||
|
- Pagination: default 20 images per page; "Load More Images (X of Y)" button for explicit load
|
||||||
|
- `loadImages(offset, limit)` — populates grid from cached results
|
||||||
|
- `setSearchResults(paths)` — accepts async search output, resets pagination
|
||||||
|
- `showLoadingIndicator()` / `hideLoadingIndicator()` — spinners during async ops
|
||||||
|
- Scroll area horizontal scrollbar always off; vertical scrollbar auto
|
||||||
|
- 300 ms periodic resize check to handle dynamic reflows
|
||||||
|
|
||||||
|
#### `databasemanager.h/.cpp`
|
||||||
|
All SQLite operations. Thread-safe via `QMutex`.
|
||||||
|
|
||||||
|
Key public API:
|
||||||
|
| Method | Description |
|
||||||
|
|---|---|
|
||||||
|
| `initialize(path)` | Opens/validates an existing database |
|
||||||
|
| `createDatabase(path)` | Creates schema from scratch |
|
||||||
|
| `getAllImages(offset, limit)` | Paginated full-path list, no search filter |
|
||||||
|
| `getImageCount()` | Total row count (cached) |
|
||||||
|
| `searchImages(text, offset, limit)` | FTS5 or LIKE search, runs in background thread via `QtConcurrent::run` |
|
||||||
|
| `cancelSearch()` | Sets cancellation flag; background thread checks it |
|
||||||
|
| `initializeFTS()` | Creates virtual table + triggers if FTS5 available |
|
||||||
|
| `prepareFTSQuery(text)` | Converts user text to FTS5 query syntax |
|
||||||
|
|
||||||
|
Caching:
|
||||||
|
- `m_searchCache`: `QMap<QString, CachedResult>` keyed by query string, 5-minute TTL
|
||||||
|
- `m_allImagesCache`: paginated all-images results
|
||||||
|
- `m_imageCountCache`: row count integer
|
||||||
|
- Cache eviction when `m_searchCache` exceeds 50 entries
|
||||||
|
- All cache access under `m_cacheMutex`
|
||||||
|
|
||||||
|
Threading: each background thread gets its own `QSqlDatabase` connection (Qt requirement). Connections named by `QThread::currentThread()` pointer.
|
||||||
|
|
||||||
|
#### `settingsdialog.h/.cpp`
|
||||||
|
Modal `QDialog` for user configuration.
|
||||||
|
|
||||||
|
Fields:
|
||||||
|
- Database file path — `QLineEdit` + `QPushButton` (opens `QFileDialog::getSaveFileName`)
|
||||||
|
- Screenshots directory — `QLineEdit` + `QPushButton` (opens `QFileDialog::getExistingDirectory`)
|
||||||
|
- Image preload count — `QLineEdit` with `QIntValidator(1, 100)`
|
||||||
|
|
||||||
|
On Accept:
|
||||||
|
- Creates missing directories (prompts user)
|
||||||
|
- Auto-appends `/screenshot_ocr.db` if a directory path is given for the DB field
|
||||||
|
- Saves to `QSettings`
|
||||||
|
|
||||||
|
#### `updatedatabasedialog.h/.cpp`
|
||||||
|
Non-modal `QDialog` that manages the OCR subprocess.
|
||||||
|
|
||||||
|
Behavior:
|
||||||
|
- Launches `python3 OCR-scripts/ocr_screenshots.py --db <path> --screenshots-dir <dir>`
|
||||||
|
- Streams stdout/stderr into a `QPlainTextEdit` log (errors highlighted red)
|
||||||
|
- Indeterminate `QProgressBar` while running
|
||||||
|
- Cancel → sends `SIGTERM`; force-kills after 3 s if process doesn't exit
|
||||||
|
- Close button disabled until process finishes
|
||||||
|
- Emits `updateFinished()` on success → `MainWindow` reloads gallery
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GUI Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
┌───────────────────────────────────────────────────────────┐
|
||||||
|
│ File │ ← Menu bar
|
||||||
|
├───────────────────────────────────────────────────────────┤
|
||||||
|
│ [ Search OCR text... ] [×] │ ← Search bar
|
||||||
|
├───────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||||
|
│ │ │ │ │ │ │ │ │ │ ← Thumbnails
|
||||||
|
│ │ image │ │ image │ │ image │ │ image │ │ 256×256 px
|
||||||
|
│ │ │ │ │ │ │ │ │ │ dynamic grid
|
||||||
|
│ │ name.png │ │ name.png │ │ name.png │ │ name.png │ │
|
||||||
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||||
|
│ … │
|
||||||
|
│ [ Load More Images (20 of 157) ] │ ← Pagination
|
||||||
|
│ │
|
||||||
|
├───────────────────────────────────────────────────────────┤
|
||||||
|
│ Ready Showing 20 of 157 │ ← Status bar
|
||||||
|
└───────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
Grid columns reflow automatically:
|
||||||
|
- < ~280 px wide: 1 column
|
||||||
|
- ~280–560 px: 2 columns
|
||||||
|
- ~560–840 px: 3 columns
|
||||||
|
- ~840–1120 px: 4 columns
|
||||||
|
- 1120 px+: 5+ columns
|
||||||
|
|
||||||
|
No horizontal scrollbar ever appears.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## OCR Scripts
|
||||||
|
|
||||||
|
### `OCR-scripts/ocr_screenshots.py`
|
||||||
|
|
||||||
|
Main OCR runner. Scans a screenshots directory, runs Tesseract on each image not already in the database, and writes results to SQLite.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 OCR-scripts/ocr_screenshots.py \
|
||||||
|
--db ~/.local/share/screenshot-gallery/screenshot_ocr.db \
|
||||||
|
--screenshots-dir ~/Screenshots
|
||||||
|
```
|
||||||
|
|
||||||
|
- Handles `SIGTERM` gracefully (used by the Update Database dialog cancel button)
|
||||||
|
- Skips files already present in `ocr_results.filename`
|
||||||
|
- Outputs progress to stdout and errors to stderr
|
||||||
|
|
||||||
|
### Rofi Integration Scripts
|
||||||
|
|
||||||
|
These scripts hook OCR-screenshot workflows into the [Rofi](https://github.com/davatorium/rofi) application launcher for keyboard-driven use:
|
||||||
|
|
||||||
|
| Script | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `ocr_rofi.sh` | Take a screenshot, OCR it immediately, copy text to clipboard |
|
||||||
|
| `direct_rofi_ocr.sh` | Same, direct variant |
|
||||||
|
| `simple_rofi_ocr.sh` | Minimal version |
|
||||||
|
| `rofi_ocr_search.sh` | Launch Rofi with searchable OCR text list |
|
||||||
|
| `ocr_search_rofi.py` | Python backend for Rofi search |
|
||||||
|
| `search_ocr.py` | Standalone CLI search against the database |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Settings & Configuration
|
||||||
|
|
||||||
|
**Settings file:** `~/.config/ScreenshotOCRGallery/settings.ini`
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[General]
|
||||||
|
databasePath=/home/<user>/.local/share/screenshot-gallery/screenshot_ocr.db
|
||||||
|
screenshotsDir=/home/<user>/Screenshots
|
||||||
|
imagePreloadCount=20
|
||||||
|
```
|
||||||
|
|
||||||
|
All three keys have fallbacks defined in `MainWindow::loadSettings()` and `SettingsDialog`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Search Flow
|
||||||
|
|
||||||
|
1. User types in search bar.
|
||||||
|
2. Each keystroke resets the 500 ms `m_typingTimer`.
|
||||||
|
3. Timer fires → `MainWindow::performSearch()` called.
|
||||||
|
4. `DatabaseManager::searchImages()` dispatched via `QtConcurrent::run()`.
|
||||||
|
5. Inside the thread: check `m_searchCache`; if miss, build FTS5 or LIKE query and execute.
|
||||||
|
6. Result (list of `full_path` strings) returned to main thread via signal.
|
||||||
|
7. `ImageGallery::setSearchResults()` resets pagination, populates grid with first page.
|
||||||
|
8. Status bar updated: "Found N results for 'query'".
|
||||||
|
9. User clicks "Load More" → `getAllImages(offset, limit)` or subsequent search page fetched.
|
||||||
|
10. Clearing the search bar → `searchImages("")` → gallery reverts to full unfiltered list.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance Design
|
||||||
|
|
||||||
|
| Concern | Solution |
|
||||||
|
|---|---|
|
||||||
|
| Full-text search speed | FTS5 virtual table (≈100× faster than LIKE on large datasets) |
|
||||||
|
| UI responsiveness | All DB queries on background threads via `QtConcurrent` |
|
||||||
|
| Repeated searches | 5-minute LRU cache in `DatabaseManager` |
|
||||||
|
| Large galleries | Explicit pagination (default 20, user-controlled via Load More) |
|
||||||
|
| Column reflow cost | 300 ms debounce on resize events |
|
||||||
|
| Typing lag | 500 ms inactivity timer before issuing query |
|
||||||
|
| Thread-safe DB access | Per-thread `QSqlDatabase` connections + `QMutex` guards |
|
||||||
|
| Missing files | Placeholder thumbnail rendered inline; no crash |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Linux Desktop Integration
|
||||||
|
|
||||||
|
**`screenshot-gallery.desktop`**
|
||||||
|
```ini
|
||||||
|
[Desktop Entry]
|
||||||
|
Type=Application
|
||||||
|
Name=Screenshot OCR Gallery
|
||||||
|
Icon=orcs-gallery
|
||||||
|
Exec=screenshot-gallery
|
||||||
|
Categories=Graphics;Utility;Viewer;
|
||||||
|
Keywords=screenshots;ocr;gallery;search;images;
|
||||||
|
```
|
||||||
|
|
||||||
|
XDG paths used by the application:
|
||||||
|
- Config: `QStandardPaths::AppConfigLocation` → `~/.config/ScreenshotOCRGallery/`
|
||||||
|
- Data: `QStandardPaths::AppLocalDataLocation` → `~/.local/share/screenshot-gallery/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Notes
|
||||||
|
|
||||||
|
- No `.ui` files — all widgets constructed programmatically in C++.
|
||||||
|
- `CMAKE_AUTOMOC ON` and `CMAKE_AUTORCC ON` are set; `CMAKE_AUTOUIC OFF`.
|
||||||
|
- Qt resource system (`resources.qrc`) embeds icons at compile time; no runtime asset paths needed.
|
||||||
|
- `QSettings` uses `IniFormat` explicitly so the file is human-readable.
|
||||||
|
- The `UpdateDatabaseDialog` is instantiated fresh each time (not reused) to avoid stale process state.
|
||||||
|
- `ImageGallery` does not use a `QAbstractItemModel`; it builds `ImageThumbnail` widgets directly and manages them in a flat list (`m_thumbnails`).
|
||||||
|
- Database connections must not be shared across threads — each `QtConcurrent` task opens its own named connection and closes it on exit.
|
||||||
Reference in New Issue
Block a user