Pholio

Pholio is a desktop application for managing large photo and video libraries, built for volume and speed.

• Libraries — point Pholio at one or more folders; it indexes every photo and video into its own embedded database, one per library, and keeps it in sync as files change.
• Gallery — a justified, date-grouped grid that stays fluid on tens of thousands of files, with a full-screen photo view and an info panel for the selected file.
• Metadata — reads EXIF, IPTC and XMP (RAW, HEIF and video included), edits capture date, location and rating, and writes them back to the file itself.
• Places — offline reverse geocoding from a bundled GeoNames dataset, plus optional online place search (LocationIQ).
• People — local face and animal detection and clustering (ONNX Runtime, nothing leaves the machine); naming a person makes their photos searchable.
• Search — free text, rating (r:4+), people (p:Alice) and folder (path:Holidays/2024) filters, combined freely — see the in-app guide (the ? next to the search bar) or src/main/resources/userguide.
• Command line — the same binary runs headless: pholio scan <dir> reports the media files a folder holds.

Built with Java 26, JavaFX (AtlantaFX, GemsFX, Ikonli), Spring Boot, H2, PicoCLI and metadata-extractor.

Build and run

Requirements: a JDK 26 that bundles JavaFX (e.g. Azul Zulu FX 26). Maven comes with the wrapper.

./mvnw verify                      # compile, test, build target/pholio.jar
java -jar target/pholio.jar        # desktop interface (the default)
java -jar target/pholio.jar scan ~/Pictures [-R]   # headless scan; -R: do not recurse
java -jar target/pholio.jar -V     # version
java -jar target/pholio.jar --help

Any argument Pholio does not recognise is read as a command and starts it headless; pass --ui to force the window.

Development

JVM options (-D…)

Option	Default	Effect
--enable-native-access=javafx.graphics,ALL-UNNAMED	—	Not a property, but recommended: silences the restricted-method warnings from JavaFX, JNA and the macOS process naming.
-Dpholio.home=<dir>	OS user dirs	Puts configuration, data (libraries) and cache under one root — keeps a test run out of your real profile.
-Dpholio.skipTheme=true	false	Starts without the AtlantaFX theme, on JavaFX's default styling (to tell a theme issue from a layout one).
-Dpholio.modalBackend=dialogPane	stage	Shows dialogs in GemsFX's embedded DialogPane instead of a separate window.
-Djavafx.enablePreview=true	set by the app	Required for the JavaFX HeaderBar preview API; GuiBootstrap sets it unless you pass a value.
-Dprism.dirtyopts=false	set by the app	Works around a stale-paint bug in Prism; GuiBootstrap sets it unless you pass a value.

Application settings (--pholio.…= arguments)

Spring Boot settings from application.yaml, overridable on the command line (they bypass PicoCLI, so they never read as a command):

Setting	Default	Effect
--pholio.dev-tools.enabled=	true	F12 opens the DevToolsFX scene-graph inspector.
--pholio.library.routing.enabled=	true	Routes the database to the library picked in the header; false pins spring.datasource.url.
--pholio.pools.cpu=	0	Threads for decoding work (thumbnails, hashes); 0 = cores − 1.
--pholio.pools.scheduler=	2	Scheduler threads.
--pholio.window.default-width= / default-height=	1440 / 900	First-run window size.
--logging.level.org.icroco.pholio=	DEBUG	Log level of Pholio's own code.

Useful scripts

• python3 tools/icons/make-macos-icon.py — regenerates the macOS icon, icon.png and pholio.icns from src/main/resources/images/spo-1024x1024.png.

Release

./mvnw -Prelease validate

Needs a clean working tree (or -Drelease.allowDirty=true) and a logged-in GitHub CLI (gh auth login). In order, it:

1. bumps the version to YYYY.M.N — same month as the current version: N + 1, otherwise build 0 of the current month;
2. runs a fresh ./mvnw verify;
3. writes distrib/release_note/release-note-<version>.md from the Conventional Commits since the previous release (grouped by type, then scope);
4. creates GitHub release v<version> in Imag-In/Pholio with the jar, its SHA-256 and the release note;
5. commits pom.xml and tags v<version> locally;
6. commits the release note in distrib/ and pushes it.

The source repository itself is never pushed to GitHub: Imag-In/Pholio only receives release assets and the distrib/ worktree (an orphan branch), and a local pre-push hook enforces it. See AGENTS.md for the details, and keep commit messages in the Conventional Commits format so they reach the release note.