Architecture
This page is a high-level overview. The source code in src/ is the reference for the details; each module starts with a comment describing its role. AGENTS.md, at the root of the repository, keeps the detailed notes for contributors and coding agents: mechanisms, decisions and conventions.
Layout
Image Toolkit is a single Cargo crate (no workspace) that builds one binary, image-toolkit. The interface is built with egui through its eframe framework, drawn on the GPU with wgpu.
| Module | Role |
|---|---|
main.rs | Creates the window and starts the app. |
app.rs | The interface: toolbar, thumbnail grid, viewer, status bar, keyboard handling, saved preferences. |
library.rs | Scans the opened folder: which files are listed, in which order. |
decode.rs | Turns a file into pixels for display: embedded JPEG previews of RAW files (through rawler), standard images (through image), orientation, reduction to the displayed size. |
loader.rs | The background decoding queue and its worker threads. |
i18n.rs | Every interface text, in French and English. |
How the pieces fit
- The interface thread draws every frame and never decodes images itself.
- The folder scan runs on a thread of its own, so opening a large tree does not freeze the window.
- Decoding runs on a pool of worker threads, one per CPU core minus one. At every frame the interface tells the loader which images it needs, most urgent first: the visible thumbnails, then a few rows around them; in the viewer, the current image, then its neighbours. Workers always take the most urgent request. Requests that scrolled out of view before a worker reached them are dropped, which keeps a fast scroll through thousands of photos from queueing thousands of decodes.
- The grid is virtualized: only the visible rows are laid out and drawn, and decoded thumbnails beyond a fixed budget are evicted, farthest from view first, and decoded again when needed.
- Errors stay per file. A file that fails to decode, even one that makes rawler panic, becomes an error placeholder; it never stops the scan or the other decodes.
Files are only ever read in 0.1.0. Writing (XMP sidecars, deletion) arrives with the versions listed in the roadmap.
Blur detection
The blur detection planned for 0.4.0 comes from the author’s command-line tool blurdetector. Its code is being moved into this crate rather than pulled in as a dependency, so that from then on blur detection is developed here, as a native feature of Image Toolkit.
Translations
Every fixed interface text is a variant of one enumeration in i18n.rs, translated in both languages in the same place. A missing translation is therefore a compile error rather than a blank label. Texts that contain a number, such as the image count with its plural rules, are small functions in the same file.