Project structure¶
For human readability the project has been subdivided into the following folder structure:
zooui/
├── app.py
├── __main__.py
├── config.py
├── logger.py
├── utils/
│ ├── _packaging.py
│ └── _xdg.py
├── resources/
│ └── _usage_rst.py
├── data/
│ ├── home.pzs
│ ├── home.png
│ ├── icon.png
│ ├── test_pdf.pdf
│ ├── zooui.desktop
│ ├── 01_red_stripes.png ... 07_climb.png
│ └── SVG/
│ ├── circle.svg
│ ├── square.svg
│ ├── up_triangle.svg
│ ├── down_triangle.svg
│ ├── up_arrow.svg
│ ├── down_arrow.svg
│ ├── left_arrow.svg
│ ├── right_arrow.svg
│ ├── topleft_arrow.svg
│ ├── topright_arrow.svg
│ ├── bottomleft_arrow.svg
│ ├── bottomright_arrow.svg
│ ├── vertical_stick.svg
│ ├── horizontal_stick.svg
│ └── diagonal_stick.svg
├── converters/
│ ├── converter.py
│ ├── converterrunner.py
│ ├── pdfconverter.py
│ └── vipsconverter.py
├── backup/
│ └── backupmanager.py
├── objects/
│ ├── physicalobject.py
│ ├── objectsutils/
│ │ └── zoom/
│ │ └── zoommanager.py
│ ├── mediaobjects/
│ │ ├── mediaobject.py
│ │ ├── pdfmediaobject.py
│ │ ├── stringmediaobject.py
│ │ ├── svgmediaobject.py
│ │ ├── tiledmediaobject.py
│ │ └── mediaobjectsutils/
│ │ ├── string/
│ │ │ ├── parallellayout.py
│ │ │ └── textlayout.py
│ │ └── svg/
│ │ ├── svgcache/
│ │ │ └── svgcache.py
│ │ └── utils/
│ │ ├── svgarrowutils.py
│ │ ├── svgcircleutils.py
│ │ ├── svgsquareutils.py
│ │ ├── svgstickutils.py
│ │ └── svgtriangleutils.py
│ └── scene/
│ ├── qzui.py
│ ├── scene.py
│ └── sceneutils/
│ ├── autosave.py
│ ├── clipboard.py
│ ├── parallel.py
│ └── prioritybatcher.py
├── tilesystem/
│ ├── tile.py
│ ├── tilecache.py
│ ├── tilemanager.py
│ ├── tiler/
│ │ ├── ppm.py
│ │ ├── tiler.py
│ │ └── tilerrunner.py
│ ├── tileproviders/
│ │ ├── tileprovider.py
│ │ ├── statictileprovider.py
│ │ ├── dynamictileprovider.py
│ │ └── ferndynamictileprovider.py
│ └── tilestore/
│ ├── cleanuptilestore.py
│ ├── tilecache.py
│ └── tilestore.py
└── windows/
├── mainwindow.py
└── dialogwindows/
├── dialogwindows.py
├── autosavesettingsdialog.py
├── modifystringdialog.py
├── modifysvginputdialog.py
├── modifytiledmediaobjectdialog.py
├── stringinputdialog.py
├── svgpickerinputdialog.py
├── zoomsensitivitydialog.py
└── zoomsettingsdialog.py
Project class hierarchy¶
PhysicalObject and media types¶
- physicalobject
- mediaobject
tiledmediaobject
stringmediaobject
svgmediaobject
- scene
- qzui
prioritybatcher
autosave — Timer-based autosave orchestration
clipboard — Copy/paste operations
parallel — Parallel rendering
Zoom manager¶
zoommanager — Zoom level tracking and physics
Media object utilities¶
- String utilities
mediaobjectsutils/string/textlayout.py— Text layout enginemediaobjectsutils/string/parallellayout.py— Parallel text rendering
- SVG utilities
mediaobjectsutils/svg/svgcache/svgcache.py— SVG rendering cachemediaobjectsutils/svg/utils/svgarrowutils.py— Arrow shape generatormediaobjectsutils/svg/utils/svgcircleutils.py— Circle shape generatormediaobjectsutils/svg/utils/svgsquareutils.py— Square shape generatormediaobjectsutils/svg/utils/svgstickutils.py— Stick figure generatormediaobjectsutils/svg/utils/svgtriangleutils.py— Triangle shape generator
Converters¶
- converter
vipsconverter
converterrunner — Process-based parallel conversion
Tile system¶
tile
tilecache — In-memory LRU cache
tilemanager — Central tile coordinator
- tiler
ppm
tilerrunner — Process-based parallel tiling
- tileprovider
statictileprovider
- dynamictileprovider
ferntileprovider
- tilestore
cleanuptilestore.py— Auto-cleanup of stale tiles
Windows and dialogs¶
mainwindow
- dialogwindows
stringinputdialog
modifystringdialog
svgpickerinputdialog
modifysvginputdialog
modifytiledmediaobjectdialog
zoomsensitivitydialog
zoomsettingsdialog
autosavesettingsdialog
Configuration and backup¶
config.py— User configuration management (ConfigManager)backup/backupmanager.py— Per-scene backup creation and rotation
Architecture diagram¶
Here is a schematic of the program architecture, with a legend of core components and design patterns.
Key Design Patterns:
Abstract Base Classes: Converter, TileProvider, MediaObject, PhysicalObject
Process Pooling: Parallel media conversion (converterrunner) and tile generation (tilerrunner)
Thread Pooling: Concurrent tile creation with worker thread pools in TileManager
Autosave: Timer-based per-scene backup orchestration with rotation and cleanup
Clipboard: Copy/paste with grid-aligned positioning via
sceneutils/clipboard.pyParallel Rendering: Multi-priority render pipeline with render order toggle (Ctrl+R)
Hybrid Rendering: CPU-efficient text caching for StringMediaObject
Caching Strategy: Three-tier (Memory → Disk → Source)
Observer Pattern: Qt signals/slots for event handling
Template Method: Tile provider request processing
Singleton-like: TileManager module-level functions
Core Components:
| Component | Responsibility | Key Files |
|---------------------|-------------------------------------|-----------|
| **zooui/app.py** | Application entry, initialization, dep check | zooui/app.py |
| **__main__.py** | ``python -m zooui`` module entry point | zooui/__main__.py |
| **ConfigManager** | User configuration management | zooui/config.py |
| **LoggerConfig** | Centralized logging system | zooui/logger.py |
| **_packaging** | Source/pip/frozen path resolution | zooui/utils/_packaging.py |
| **_xdg** | XDG Base Directory writable paths | zooui/utils/_xdg.py |
| **_usage_rst** | Embedded usage instructions (RST) | zooui/resources/_usage_rst.py |
| **MainWindow** | Qt main window and menus | zooui/windows/mainwindow.py |
| **QZUI** | Rendering widget, input handling | zooui/objects/scene/qzui.py |
| **Scene** | MediaObject container, autosave | zooui/objects/scene/scene.py |
| **Autosave** | Timer-based per-scene backups | zooui/objects/scene/sceneutils/autosave.py |
| **Clipboard** | Copy/paste with grid alignment | zooui/objects/scene/sceneutils/clipboard.py |
| **MediaObject** | Displayable media in ZUI | zooui/objects/mediaobjects/ |
| **ZoomManager** | Zoom level tracking and physics | zooui/objects/objectsutils/zoom/zoommanager.py |
| **PriorityBatcher** | Priority-based tile request batching| zooui/objects/scene/sceneutils/prioritybatcher.py |
| **TileManager** | Tile coordination and caching | zooui/tilesystem/tilemanager.py |
| **TileProvider** | Tile loading/generation | zooui/tilesystem/tileproviders/ |
| **TileStore** | Persistent tile storage | zooui/tilesystem/tilestore/ |
| **Converter** | Media format conversion | zooui/converters/ |
| **ConverterRunner** | Process-based parallel conversion | zooui/converters/converterrunner.py |
| **TilerRunner** | Process-based parallel tiling | zooui/tilesystem/tiler/tilerrunner.py |
| **BackupManager** | Per-scene backup creation/rotation | zooui/backup/backupmanager.py |
Complete Application Lifecycle:
START | Enter Qt Event Loop ←──────────┐
↓ | ↓ │
Check System Deps → Parse Args → Init Logging| │ ┌─────────────────────┐ │
↓ ↑ | ├─→│ User Input Events │───┤
ConfigManager reads │ | │ └─────────────────────┘ │
~/.config/zooui/config.json ←──────────┘ | │ │
↓ | │ ┌─────────────────────┐ │
Init TileManager | ├─→│ QZUI Render Loop │───┤
↓ | │ │ • Update physics │ │
├─→ Create TileCache (80% static, | │ │ • PriorityBatcher │ │
│ 20% dynamic) | │ │ • Request tiles │ │
├─→ Start StaticTileProvider thread | │ │ • Render scene │ │
├─→ Start DynamicTileProvider threads | │ └─────────────────────┘ │
└─→ Auto cleanup TileStore (if enabled) | │ │
↓ | │ ┌─────────────────────┐ │
Create Qt App | ├─→│ Tile Providers │───┤
↓ | │ │ • Process requests │ │
Create MainWindow | │ │ • Load/generate │ │
↓ | │ │ • Cache tiles │ │
├─→ Create QZUI widget | │ │ • PriorityBatcher │ │
│ ├─→ Create Scene | │ └─────────────────────┘ │
│ ├─→ Start render thread (10 fps) | │ │
│ └─→ Init PriorityBatcher | │ ┌─────────────────────┐ │
├─→ Setup menus | ├─→│ Autosave Timer │───┤
├─→ Init ConverterRunner (process pool) | │ │ • Per-scene backup │ │
├─→ Init TilerRunner (process pool) | │ │ • Rotation/cleanup │ │
├─→ Load default scene | │ └─────────────────────┘ │
└─→ Start autosave timer | │ │
↓ | └────────────────────────────┘
Show Window | ↓
↓ | User Closes Window
| ↓
| Stop Autosave → Cleanup Pools
| ↓
| Exit Event Loop → Cleanup & Exit
| ↓
| END
Program schematic:
┌─────────────────────────────────────────────────────────────────┐
│ zooui/app.py │
│ • Check system dependencies (libvips, pdftoppm) │
│ • Parse CLI arguments │
│ • Load configuration via ConfigManager │
│ • Initialize logging system │
│ • Initialize TileManager │
│ • Create MainWindow & QZUI │
│ • Start process pools (Converter / Tiler) │
└─────────────┬───────────────────────────────────────────────────┘
│
├──────────────────────────────────────────────────────────────┐
│ │
▼ ▼
┌─────────────────────────────┐ ┌──────────────────────────────┐
│ ConfigManager │ │ LoggerConfig │
│ • JSON config file I/O │ │ • Centralized logging │
│ • CLI override support │ │ • File + Console handlers │
│ • Autosave settings │ │ • Color-coded output │
└─────────────────────────────┘ └──────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ TileManager (Module) │
│ • init() — Setup caches and thread pools │
│ • load_tile() / get_tile() / get_tile_robust() │
│ • Manages Static and Dynamic tile providers │
│ • Coordinates with TilerRunner (process pool) │
└──────────┬──────────────────┬────────────────┬─────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ TileCache (LRU) │ │ ConverterRunner│ │ TilerRunner │
│ • In-memory cache│ │ (Process Pool) │ │ (Process Pool) │
│ • 80% static │ │ • Parallel fmt │ │ • Parallel tile │
│ • 20% dynamic │ │ conversion │ │ generation │
│ • Thread-safe │ │ • libvips/PIL │ │ • PPM format │
└──────────────────┘ └──────────────┘ └──────────────────┘
┌─────────────────────────────┐
│ MainWindow (Qt) │
│ • Menu system │
│ • File operations │
│ • Central widget: QZUI │
│ • Dialog management │
└─────────────┬───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ QZUI (Qt Widget + Thread) │
│ • Rendering loop (10 fps) │
│ • Input handling (mouse, touch, keyboard) │
│ • Viewport management (pan, zoom) │
│ • Requests tiles via PriorityBatcher │
│ • Renders Scene content │
└─────────────┬───────────────────────────────────────────────────┘
│
├──────────────────────────────┬────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐
│ Scene │ │ PriorityBatcher │ │ ZoomManager │
│ • Container for media │ │ • Priority queue │ │ • Zoom level │
│ • Coordinate transforms │ │ • Tile request │ │ • Physics │
│ • Thread-safe (RLock) │ │ batching │ │ • Sensitivity │
│ • Save/Load .pzs files │ └─────────┬───────────┘ └─────────────────┘
│ • Autosave integration │ │
│ • Clipboard integration │ │ tile requests
└──────┬──────────────┬───────┘ │
│ │ │
▼ ▼ │
┌──────────────┐ ┌────────────────┐ │
│ Autosave │ │ Clipboard │ │
│ • Per-scene │ │ • Copy/paste │ │
│ backups │ │ • Grid-align │ │
│ • Rotation │ │ • Selection │ │
│ • Expiration │ └────────────────┘ │
└──────┬───────┘ │
│ │
▼ │
┌──────────────┐ │
│ BackupManager │ │
│ • Dir mgmt │ │
│ • Cleanup │ │
└──────────────┘ │
│
┌──────────────────────────────────────────┘
│
▼
┌───────────────────────────────────┐
│ MediaObject │
│ ┌─────────────────────┐ │
│ │ PhysicalObject │ │
│ │ • x, y, z coords │ │
│ │ • vx, vy, vz │ │
│ │ • damping │ │
│ └─────────────────────┘ │
│ ▲ │
│ │ │
│ ┌──────┴──────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ TiledMediaObject StringMediaObj │
│ SVGMediaObject │
│ • SVG cache • Hybrid │
│ • Shape utils render │
│ (5 shape types) • Text │
│ layout │
│ • Parall │
└───────────────────────────────────┘
│
│ requests tiles
▼
┌──────────────────────────────────────┐
│ TileProvider (Abstract) │◄─── PriorityBatcher
│ • Thread-based (ThreadPool) │
│ • LIFO task queue │
│ • Condition variables │
│ • Pause/resume support │
└─────────────┬────────────────────────┘
│
┌─────────┴──────────┐
│ │
▼ ▼
┌────────────┐ ┌──────────────────┐
│ Static │ │ DynamicProvider │
│ Provider │ │ • FernProvider │
│ │ └────────┬─────────┘
└────┬───────┘ │
│ │
└─────────┬───────────┘
│
▼
┌──────────────────┐
│ TileStore │
│ • Disk storage │
│ • SHA-1 hashing │
│ • Auto cleanup │
│ (cleanuptls) │
└──────────────────┘