From 1f64931c728625cf209f3c41b90b200f77fa2d36 Mon Sep 17 00:00:00 2001 From: dax Date: Tue, 4 Aug 2026 06:19:01 +0000 Subject: pathways: walking mosaic navigator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the scrolling facet-grid with a walkable maze. You start on a random photo; every photo holds up to four paths (labels, keywords, camera, lens ranked by count, library as fallback), one per cardinal direction, each an ordered cycle. Arrow keys or hover-revealed buttons lock the next photo of that path onto the grid in the direction moved; visited photos form a panable mosaic with focus-jump on revisits. Server: precomputes per-photo exits; adds /api/exits/:id and /api/random. Client: zero-dependency rewrite — splash, hidden exits, drag-pan, pointer capture, reduced-motion support. --- README.md | 57 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 22 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 346e910..36e7b53 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,30 @@ # pathways -A photo viewer that organises a PhotoPrism library into paths — shared labels, -keywords, cameras, lenses, and dominant colours — instead of a flat grid or -albums. +A photo viewer that walks your library as a maze. You start on one random +picture; every photo secretly holds up to four paths — its biggest memberships +across labels, keywords, camera, and lens — one per direction. Press a +direction (arrow keys, or the buttons that appear when you hover) and the next +photo of that path locks into the grid beside you, in the direction you moved. +The visited pictures accumulate into a mosaic you can pan around and step back +through. The live instance lives at and reads the PhotoPrism database directly (read-only) on the same machine. PhotoPrism's admin UI stays behind basic auth at ; pathways is public. -## How it works +## How the paths work -- `server.mjs` — a single Node process (`nodejs_22`, no build step). It pools - the MariaDB `photoprism` database, groups the primary files into *paths* - (facets with ≥3 photos) and exposes three endpoints: - - `GET /api/paths` — every photo (id, thumb, title, date) plus the paths - - `GET /api/photo/:id` — one photo plus its connections across labels, - keywords, camera, and lens - - `GET /api/health` — liveness probe -- `public/` — the front end. Progressive reveal on scroll, a lightbox with - connection chips that jump you to the linked path, and a dominant-colour - swatch under every thumbnail. In colour mode the paths themselves are - computed client-side from each photo's dominant hue. - -Thumbnails are served as static files by Caddy from -`/srv/photoprism/storage/cache/thumbnails/{a}/{b}/{c}/{hash}_{size}.jpg` -(`720x720_fit` for the grid, `1920x1200_fit` in the lightbox). +- Every photo's paths are its member groups: label(s), keyword(s), camera, + lens. They're ranked by member count; the top four (one per direction) become + its exits. +- Paths with a single member are skipped; a photo with fewer than four usable + paths is topped up with a "library" path (all photos), so every direction + always leads somewhere. +- Each path is an ordered cycle (by taken date, then id): walking "grey" goes + grey → grey → … and wraps around. Assignment is deterministic, so revisiting + a photo always offers the same four exits. +- If a step lands on a photo already placed in the mosaic, focus just jumps to + its existing tile — the mosaic never holds two copies. ## Run it @@ -38,13 +38,26 @@ DB_HOST=127.0.0.1 DB_USER=photoprism DB_PASSWORD=… DB_NAME=photoprism \ On NixOS the box runs it as a systemd unit (`systemd.services.pathways`), started after `mysql.service`, as user `dax`. +## API + +- `GET /api/paths` — every photo (id, thumb, title, date) plus the facets + (groups with ≥3 members) +- `GET /api/random` — one random photo +- `GET /api/exits/:id` — a photo plus its four exits; each exit has the path + it follows (`type`, `name`, `count`) and the `next` photo in that path's cycle +- `GET /api/health` — liveness probe + +Thumbnails are served as static files by Caddy from +`/srv/photoprism/storage/cache/thumbnails/{a}/{b}/{c}/{hash}_{size}.jpg` +(`720x720_fit` for tiles). + ## Layout ``` server.mjs API + static file serving -public/index.html viewer page -public/app.css styling -public/app.js viewer logic (paths, colours, lightbox) +public/index.html splash + the walkable stage +public/app.css tiles, hover exits, lock-in animation +public/app.js grid state, exits, pan/click/keyboard, cycling walk ``` The thumbnail path sharding matches PhotoPrism: directory = first three -- cgit v1.3.1