galapix is an interactive image viewer for large collections (tens of thousands of files) and for very large individual images. You can zoom from postage-stamp overviews down to full resolution without losing interactivity. Multi-resolution tiles are requested on demand and cached; the preferred durable backend is thumtoo.
Supported inputs include ordinary image files, many formats via ImageMagick / surfcpp, archive members (through thumtoo), and URLs where the build enables network backends.
- Large image collections with continuous pan/zoom
- Extremely large images (multi-resolution tile pyramid)
- Wide format coverage (JPEG, PNG, and formats via ImageMagick / optional tools)
- Archive-backed images when thumtoo is enabled
- Background tile loading; the UI stays responsive
- Layout tools (regular, tight, spiral, random) and overlap solving
- Workspace save/load
- Optional SpaceNavigator support (spacenavd)
- Optional ImGui status / help overlay
- Optional thumtoo tile + overview pipeline (
HAVE_THUMTOO)
galapix targets GNU/Linux and other POSIX-like systems. External helpers for exotic formats and some OS-specific paths may not be portable. OpenGL is required.
| Dependency | Role |
|---|---|
| CMake ≥ 3.x, C++20 compiler | Build |
| SDL2 | Window, input, events |
| OpenGL (libGL / Mesa) | Rendering via wstdisplay |
| GLM | Math |
| libjpeg, libpng | Common image codecs |
| ImageMagick (Magick++) | Additional formats |
| libsigc++-2 | Signals |
| curl | Optional network URLs (thumtoo / backends) |
These libraries are vendored as git subtrees under external/ and built
together with Galapix (ImGui is a plain copy there as well):
- wst — wstdisplay: OpenGL window, renderer
- thumtoo — tile/size backend
- xdgcpp, uitest
- surfcpp — software surfaces, codecs
- geomcpp, logmich, priocpp, sexpcpp, strutcpp, babyxml, tinycmmc
| Dependency | Role |
|---|---|
| thumtoo | Durable tile cache, ladder, archives, PDF tiles (-DWITH_THUMTOO=ON) |
| SQLite, libvips, libjxl | Required by thumtoo when linked |
| Poppler (via thumtoo) | PDF pages when thumtoo is built with Poppler |
| libspnav / spacenavd | 3Dconnexion SpaceNavigator |
| rsvg-convert (librsvg) | Tool icon SVG → PNG at build time |
Thumbnail generation and offline tile preparation live in thumtoo
(thumtoo-prepare and related tools). Galapix is the interactive
viewer.
# One-shot package build
nix build
# Interactive development shell (cmake, deps, helpers)
nix develop
# Inside the shell: incremental build + run
galapix-build
galapix-run [OPTIONS] [FILES]...Override the thumtoo source tree when testing a local checkout with
THUMTOO_SOURCE_DIR=/path/to/thumtoo galapix-configure in nix develop.
The flake builds with -DWITH_THUMTOO=ON; THUMTOO_DIR defaults to the
vendored external/thumtoo.
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DWITH_THUMTOO=ON \
-DTHUMTOO_DIR=/path/to/thumtoo
cmake --build build -j"$(nproc)"THUMTOO_DIR may be a thumtoo source tree (add_subdirectory) or
an install prefix. Without thumtoo:
cmake -B build -DWITH_THUMTOO=OFF
cmake --build build -j"$(nproc)"Useful options (see CMakeLists.txt / docs/THUMTOO.md):
-DBUILD_TESTS=ON— unit tests-DBUILD_BENCHMARKS=ON— benchmarks-DWITH_THUMTOO=ON|OFF— thumtoo backend
The historical ./waf build is gone; use CMake or the flake.
# After nix build:
./result/bin/galapix [OPTIONS] [FILES]...
# Dev shell:
galapix-run [OPTIONS] [FILES]...
# Or the binary in the build directory:
build/galapix [OPTIONS] [FILES]...There is no subcommand. A leading view is still accepted for older
scripts.
Useful options:
| Option | Meaning |
|---|---|
-g, --geometry WxH |
Initial window size (default 1024×768) |
-f, --fullscreen |
Start fullscreen |
-t, --threads N |
Worker threads (default 2) |
-F, --files-from FILE |
Read paths/URLs from a file |
-p, --pattern PATTERN |
Select from thumtoo cache |
--thumtoo-cache DIR |
thumtoo cache root (default ~/.cache/thumtoo) |
-a, --anti-aliasing N |
0, 2, or 4 |
-h, --help |
Help |
-V, --version |
Version |
Special URL:
galapix builtin://mandelbrot| Key | Function |
|---|---|
| F11 | Toggle fullscreen |
| 1 | Regular layout |
| 2 | Tight layout |
| 3 | Random layout |
| 4 | Solve overlaps |
| 5 | Tight layout (alternate) |
| h | Reset zoom and scroll |
| m | Move / resize tools |
| p | Pan / zoom tools |
| n | Shuffle images |
| s / Shift+s | Sort A→Z / Z→A |
| i | Keep only selected images |
| Delete | Remove selected from workspace |
| Home / End | Zoom in / out |
| Page Up / Down | Gamma |
| Shift + mouse | Rotate view |
| Left / Right | Rotate ±90° |
| Up | Reset rotation |
| Escape | Quit |
Additional bindings and the on-screen help/status UI are documented in
docs/STATUS_REPORTING.md (ImGui overlay).
Supported via the open-source spacenavd daemon when galapix is built with libspnav. The proprietary 3dxsrv daemon is not supported.
Environment variables for development (see docs/ and source):
GALAPIX_OPEN_TIMING=1— open / tile pending samplesGALAPIX_FRAME_TIMING=1— per-frame pump / prepare / draw timing
Tile preparation and cache maintenance belong to thumtoo, not the viewer.
external/— convenience / vendored pieces (e.g. ImGui)test/— automated tests (enable with-DBUILD_TESTS=ON)uitest/— interactive tests- Session handoff notes: top of TODO.md
- Architecture and docs map: AGENTS.md
Related projects: thumtoo, biltoo, dirtoo.
GNU General Public License v3 (or later). See the source headers and project license files for details.