trailframe 0.1.0__tar.gz

trailframe-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__
+*.pyc
+.ruff_cache
+
+node_modules/
+dist/
+
+# Backend runtime artifacts (CWD when launched)
+/config.yaml
+/gallery.db
+/photos/
+/thumbnails/
+/trash/
+/maps/
+/activities/
+/tiles/
+/models/
+
+# Python build artifacts
+/build/
+*.egg-info

trailframe-0.1.0/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+Trailframe — photo gallery app: Python/FastAPI backend + React/TS/Vite frontend, packaged as the pip-installable app `trailframe` (wheels attached to GitHub releases). The backend serves the built frontend; in prod there is a single server.
+
+## Layout
+
+- `trailframe/` (repo root) — FastAPI app (`trailframe` package).
+- `frontend/` — Vite + React app.
+- `pyproject.toml` (repo root) — package metadata, dependencies, ruff config, hatchling build (`packages = ["trailframe"]`, force-includes `frontend/dist` as `trailframe/frontend/dist` into the wheel); console script `trailframe` = `trailframe.main:main`.
+- `supervisor.py` (repo root) — supervisor: starts `python -m trailframe.main` with CWD set to the repo root, restarts it when it exits, forwards SIGTERM/SIGBREAK.
+
+## Backend (FastAPI, Python 3.12)
+
+- Dependencies are declared in the root `pyproject.toml`. Note: `torch` (pulled by `ultralytics`) can't extract into the Store Python's site-packages (Windows long-path limit, no admin to enable them); it's installed to `C:\pylibs` (short path) and wired in via a `.pth` file in the user site-packages. `pip install <pkg>` on this machine may fail on long paths — use `pip install --target C:/pylibs <pkg>` for packages with deep dirs.
+- **Python style**: ruff configured in the root `pyproject.toml` (`ruff check`, `ruff format`).
+- **Run from the repo root**: `python -m trailframe.main` (or the `trailframe` console script once pip-installed). Package imports are `trailframe.*`; `main.py` serves `frontend/dist` relative to CWD when present, otherwise the packaged copy inside the installed `trailframe` package (`trailframe/frontend/dist`).
+- CLI flags (`main.py`): `--config` (default `config.yaml`), `--folder` (sets the `*_folder` subdirs), `--database`, `--port` (default 8000), `--openapi FILE` (write OpenAPI schema and exit).
+- **Runtime artifacts are written to CWD**: `config.yaml` (auto-saved on startup), `gallery.db`, `photos/`, `thumbnails/`, `trash/`, `maps/`, `activities/`, `models/`, `tiles/`. All are gitignored at those repo-root-relative paths — don't commit them.
+- **Wheels/releases**: build the web UI first (`npm run build` inside `frontend/`) — the hatchling force-include fails if `frontend/dist` is missing — then `python -m build` or `pip wheel .`; attach the wheel to a GitHub release (that's the distribution channel; no PyPI). The sdist carries `frontend/dist` at its original path (sdist `artifacts`) so the wheel built from the sdist (`python -m build` does this) can resolve its force-include.
+- Services are class-based singletons (`Service` subclasses) wired by hand in the `main.py` lifespan. The `Service` base class exposes non-virtual classmethod templates `configure`/`start`/`stop` that call virtual `_configure`/`_start`/`_stop`, log via `_log` (`[Name] message`), and track a state flag (`ServiceState`: `not started`/`started`/`starting failure`, set to the last on a `_start` exception which is re-raised). `name` defaults to `cls.__name__` (`get_name()`), overridable via `_name`. Pipelines live in `trailframe/services/pipelines/`: `Pipeline` is the base class managing the async queue (`add`, `get_queue_size`, `accepts`, `start`, `stop`). `PipelineEmpty` is a sentinel event: all pipelines accept it (`is_pipeline_empty`) and `add` drops it without queuing. Start order matters: `DatabaseService` must start first (tables are created in its `_start`), then `PipelineService`, then `FolderService`.
+- **Call hierarchy**: creating content or enriching a `Photo` goes `Pipeline -> Scanner -> Service` (when a service applies) — scanners orchestrate enrichment and delegate I/O/content work to services; API content fetching goes `API -> Service` and must **never** call a Scanner (e.g. wireframe/map data is read through `LocationService`/`MapService`, not the scanner).
+- **Scanners are registered explicitly** in each pipeline's `_scanners` list (NOT auto-discovered despite the empty `scanners/` namespace package). Pipelines are managed by `PipelineService` (`trailframe/services/pipeline_service.py`): it explicitly registers `CreationPipeline`/`BasicPipeline`, configures/starts/stops them, and `next(item, pipeline=None)` routes the item to the first pipeline whose `accepts(item)` matches — `pipeline=None` starts the chain, passing the current pipeline class continues to the next accepting pipeline (no match → no-op). A pipeline hands off by calling `PipelineService.next(item, cls)` from `_process_item`. `CreationPipeline` (accepts `Path`/`str`) runs `FileScanner` (fills `filename`/`file_size`), skips files already in the DB by `filename`+`file_size`, then `ExifScanner` and `ThumbnailScanner`, then inserts the `Photo`; `BasicPipeline` (accepts `Photo`) runs its scanners, each gated by its `accept(photo)` (whether the photo still needs that scanner's data), then merges the `Photo`.
+- **Scanner tracking**: scanners whose `accept(photo)` cannot be deduced from photo fields (e.g. `ObjectScanner` — YOLO object detection) set `needs_tracking = True`; after a successful scan the `Scanner` base appends the scanner name to `photo.scanners` (JSON column; NULL-safe — existing rows get `None` until re-scanned, so always read via `photo.scanners or []`). `ObjectScanner` runs ultralytics YOLO with the model named by `scanners.Object.model` (default `yolo26n.pt`; live config uses `yolo26m.pt`), stored in `general.models_folder` (`models/`) — not ultralytics' own cache; it stores detections in `photo.objects` (dedicated JSON column with `[{label, confidence, box}]`) and gates on `"Object" not in photo.scanners`. The models folder is also part of the storage statistics (`StorageService._folders`).
+- DB models are SQLModel classes in `trailframe/models/` (with their converters as classmethods, e.g. `GarminActivity.to_activity`, `GarminActivity.from_data`); tables are auto-created at startup (`DatabaseService.start`). No migrations.
+- **Thumbnails are multi-size**: `general.thumbnail_sizes` (sorted unique ints, default `[160, 400]`) drives `ThumbnailService` (`trailframe/services/thumbnail_service.py`). Files live at `{safe_filename[:2]}/{safe_filename}_{file_size}_{size}.webp` (fallback `{safe_filename}_{size}.webp` when `file_size` is missing). `generate_all` writes every size; `exists` = all sizes present; `select_size(preferred)` picks the lowest size ≥ preferred when ≤ 2×preferred, else the highest size below preferred (fallback smallest). The API serves `GET /api/photos/{photo_id}/thumbnail?size=<preferred>` and generates on demand. Legacy single-size files (`..._{file_size}.webp`, no size suffix) may still exist on disk but are unused.
+- **Favorites**: `Photo.is_favorite` column (auto-added by `_add_missing_columns`); `PUT /api/photos/{photo_id}/favorite`, `GET /api/photos?favorites=true`, and lightweight `GET /api/photos/favorites` (ID list).
+- **Maps/tiles**: `TileService` + `/api/tiles/{z}/{x}/{y}.png` proxy/cache map tiles locally (`general.tiles_folder`, TTL/size limits under `maps:` config). Activity/photo map data flows through `LocationService`/`MapService`/`api/map_data.py`.
+- **Forced scans** (`Tools` page): `POST /api/pipeline/scan {"scanners": [...]}`; `GET /api/pipeline/scanners` lists scanners from BOTH pipelines. Both `CreationPipeline` and `BasicPipeline` honor `ForcedScan` markers — selected scanners run with `force=True` (bypassing `accept` gates) until an empty scan request clears the mode.
+- **Photo deletion** (`DELETE /api/photos/{photo_id}` in `trailframe/api/photos.py`): moves the source file to the `trash/` folder (configurable via `general.trash_folder`, default `trash`) via `FolderService.delete()`, removes the thumbnail via `ThumbnailService`, and deletes the DB row.
+- **Statistics**: everything statistics-related lives in `StatisticsService` (`trailframe/services/statistics_service.py`; configured with the `general.*_folder` paths). The `Scanner` base class times each successful scan (`_record`, per-run `count`/`total_ms`). `Pipeline._flush_stats` is invoked when a pipeline's queue drains with no item in-flight (a run has ended — low priority, so nothing is written mid-run) and persists one `ScannerStat` row per scanner via `StatisticsService.record_run`. `GET /api/statistics/scanners` (`trailframe/api/statistics.py`) returns throughput (`name`/`items`/`value` = items/s); `GET /api/statistics/storage` returns the whole-database file size and folder sizes (response models `FolderStat`/`StorageStats` are plain pydantic shapes in `api/statistics.py`, **not** DB tables — per-table DB sizes are intentionally not computed, they require serializing every row and are too slow). Both feed one merged "Name | Items | Value" table on the Configuration page's "Statistics" pane (`frontend/src/pages/ConfigurationPage.tsx`). For testing the statistics endpoints, insert mock `ScannerStat` rows directly into the DB rather than running real pipeline scans.
+
+## Frontend (Vite + React 19 + TS)
+
+- Two Vite entries: `index.html` (main app) and `slideshow.html` (standalone kiosk slideshow, mini-app in `src/SlideshowApp.tsx`). Both sync state to URL: main app `/?page=<tab>&section=<activities|groups|custom>`, standalone `/slideshow.html?section=...&activity=<id>` or `?photos=<ids>&name=<label>&thumbs=1`. Param order is canonicalized by `src/lib/slideshowSections.ts`.
+- `node`/`npm`/`npx` are on PATH (`/c/Program Files/nodejs`): lint = `npm run lint`, build = `npm run build`, dev server = `npm run dev`.
+- `src/api/generated/schema.ts` is generated by `openapi-typescript` from the backend's `/openapi.json`. **Do not hand-edit it.** No script is committed and `openapi-typescript` is not in `package.json`; regenerate against `http://localhost:8000/openapi.json` (run backend first).
+- API calls use relative same-origin URLs (no `baseUrl` in `client.ts`). In dev, `vite.config.ts` proxies `/api` → `http://localhost:8000`, so the backend must be running for the dev server to work; in prod the backend serves `dist` directly.
+
+## Verification
+
+- No tests and no CI. Before testing, **check the frontend is available on port 8000**; if it is not, ask the user to run it. Perform all tests against `http://localhost:8000`.
+- **NEVER TEST GARMIN CONNECT.**
+- **Backend changes** (`trailframe/`): kill the process listening on port 8000 (e.g. `netstat -ano | findstr :8000`, then `taskkill -PID <pid> -F`). Wait automatic restart of the service.
+- **Backend API changes**: restart as above, then regenerate the typed client from `frontend/`: `npx openapi-typescript http://localhost:8000/openapi.json -o src/api/generated/schema.ts`.
+- **Frontend changes** (`frontend/`): build from `frontend/`: `npm run build`.

trailframe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thibault "Sildra" Fresnet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trailframe-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: trailframe
+Version: 0.1.0
+Summary: Photo gallery app with FastAPI backend and React frontend
+Project-URL: Homepage, https://github.com/Sildra/Trailframe
+Project-URL: Issues, https://github.com/Sildra/Trailframe/issues
+Author-email: Thibaut Fresnet <sildra.fr@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite
+Requires-Dist: fastapi
+Requires-Dist: garminconnect
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: pillow
+Requires-Dist: py-staticmaps
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: s2sphere
+Requires-Dist: shapely
+Requires-Dist: sqlalchemy[asyncio]
+Requires-Dist: sqlmodel
+Requires-Dist: ultralytics
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: openapi-typescript; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Trailframe
+
+[![GitHub Release](https://img.shields.io/github/release/sildra/trailframe.svg?style=for-the-badge)](https://github.com/sildra/trailframe/releases)
+[![GitHub Activity](https://img.shields.io/github/commit-activity/y/sildra/trailframe.svg?style=for-the-badge)](https://github.com/sildra/trailframe/commits/main)
+[![License](https://img.shields.io/github/license/sildra/trailframe.svg?style=for-the-badge)](LICENSE)
+
+
+A self-hosted photo gallery for people who move: photos and GPS activities (Garmin Connect / GPX) live side by side, linked by time and place. One server hosts everything — a FastAPI backend that also serves its web UI.
+
+![Gallery view](docs/img/gallery_fish_dog.jpg)
+
+## Photo library
+
+- Automatic ingestion of a photo folder, with EXIF capture (camera, date, GPS) on import.
+- Multi-size thumbnails generated and cached per photo; sizes are configurable.
+- **Favorites** — mark photos you love and find them instantly; favorite-only views everywhere.
+- **Automatic groups** — related photos are clustered so bursts and series stay together.
+- Filter and combine by date range, group, location, tags, and favorites.
+
+## Activities
+
+- Import activities from Garmin Connect or GPX files.
+- Every activity gets a trace map; photos taken during the activity appear alongside it.
+- Interactive map with selectable traces and popups showing distance, duration, and time.
+
+![Garmin activities](docs/img/activities_garmin.png)
+
+## Slideshows
+
+- Slideshow sources: an activity (photos + trace), a group, or a fully custom selection.
+- Custom slideshows support date ranges, groups, locations, tags, randomization, and favorites-only.
+- **Thumbnail mode** renders slides from cached thumbnails instead of full images — smooth playback even for large libraries, with the size chosen automatically from the available screen space.
+- Standalone kiosk entry (`/slideshow.html`) with deep-linkable URLs for dedicated screens.
+- ZIP export of an activity's photos.
+
+![Slideshow with activity trace](docs/img/slideshow_activity_1.png)
+![Slideshow photo view](docs/img/slideshow_activity_2.jpg)
+
+## Enrichment pipelines
+
+Photos are processed by pluggable scanners:
+
+| Scanner | What it does |
+| --- | --- |
+| File | Registers the file (name, size) |
+| EXIF | Extracts camera metadata, dates, and GPS position |
+| Thumbnail | Generates all configured thumbnail sizes |
+| Activity | Links photos to imported activities |
+| Brisque | Scores image quality |
+| Location | Resolves GPS coordinates to places and countries |
+| Object | Detects objects in photos (YOLO models, downloaded automatically) |
+| PerceptualHash | Fingerprints images for duplicate/near-duplicate grouping |
+
+Scanners can be force re-run individually from the Tools page — e.g. regenerate all thumbnails after changing their sizes.
+
+## Maps
+
+- Wireframe maps of your photo coverage and per-photo location maps.
+- Built-in tile cache/proxy: tiles are fetched once from the configured provider and served locally afterwards.
+
+![Tools map with activity traces](docs/img/tools_map.png)
+
+## Statistics
+
+- Per-scanner throughput (items processed and speed).
+- Storage overview: database size plus disk usage of every data folder.
+
+## Install
+
+A wheel is attached to every [release](https://github.com/sildra/trailframe/releases/latest): download the latest `trailframe-…-py3-none-any.whl` and install it with pip (Python 3.12 or newer):
+
+```bash
+pip install trailframe-…-py3-none-any.whl
+```
+
+All Python dependencies are pulled in automatically; the web UI is bundled inside the wheel.
+
+## Running
+
+Run the `trailframe` command from the folder where all data (database, thumbnails, caches, trash) should live:
+
+```bash
+trailframe --config path/to/config.yaml
+```
+
+(`python -m trailframe.main` is equivalent.) The server listens on port 8000 by default; open `http://localhost:8000`. On first start a default `config.yaml` is written to the current directory.
+
+### From source
+
+Build the web UI once (`npm install && npm run build` inside `frontend/`), then start the server from the repository root:
+
+```bash
+python supervisor.py --config path/to/config.yaml
+```
+
+The supervisor restarts the server whenever it exits and forwards SIGTERM/SIGBREAK to it. To build a wheel yourself, build the web UI first, then run `pip wheel .`.

trailframe-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Trailframe
+
+[![GitHub Release](https://img.shields.io/github/release/sildra/trailframe.svg?style=for-the-badge)](https://github.com/sildra/trailframe/releases)
+[![GitHub Activity](https://img.shields.io/github/commit-activity/y/sildra/trailframe.svg?style=for-the-badge)](https://github.com/sildra/trailframe/commits/main)
+[![License](https://img.shields.io/github/license/sildra/trailframe.svg?style=for-the-badge)](LICENSE)
+
+
+A self-hosted photo gallery for people who move: photos and GPS activities (Garmin Connect / GPX) live side by side, linked by time and place. One server hosts everything — a FastAPI backend that also serves its web UI.
+
+![Gallery view](docs/img/gallery_fish_dog.jpg)
+
+## Photo library
+
+- Automatic ingestion of a photo folder, with EXIF capture (camera, date, GPS) on import.
+- Multi-size thumbnails generated and cached per photo; sizes are configurable.
+- **Favorites** — mark photos you love and find them instantly; favorite-only views everywhere.
+- **Automatic groups** — related photos are clustered so bursts and series stay together.
+- Filter and combine by date range, group, location, tags, and favorites.
+
+## Activities
+
+- Import activities from Garmin Connect or GPX files.
+- Every activity gets a trace map; photos taken during the activity appear alongside it.
+- Interactive map with selectable traces and popups showing distance, duration, and time.
+
+![Garmin activities](docs/img/activities_garmin.png)
+
+## Slideshows
+
+- Slideshow sources: an activity (photos + trace), a group, or a fully custom selection.
+- Custom slideshows support date ranges, groups, locations, tags, randomization, and favorites-only.
+- **Thumbnail mode** renders slides from cached thumbnails instead of full images — smooth playback even for large libraries, with the size chosen automatically from the available screen space.
+- Standalone kiosk entry (`/slideshow.html`) with deep-linkable URLs for dedicated screens.
+- ZIP export of an activity's photos.
+
+![Slideshow with activity trace](docs/img/slideshow_activity_1.png)
+![Slideshow photo view](docs/img/slideshow_activity_2.jpg)
+
+## Enrichment pipelines
+
+Photos are processed by pluggable scanners:
+
+| Scanner | What it does |
+| --- | --- |
+| File | Registers the file (name, size) |
+| EXIF | Extracts camera metadata, dates, and GPS position |
+| Thumbnail | Generates all configured thumbnail sizes |
+| Activity | Links photos to imported activities |
+| Brisque | Scores image quality |
+| Location | Resolves GPS coordinates to places and countries |
+| Object | Detects objects in photos (YOLO models, downloaded automatically) |
+| PerceptualHash | Fingerprints images for duplicate/near-duplicate grouping |
+
+Scanners can be force re-run individually from the Tools page — e.g. regenerate all thumbnails after changing their sizes.
+
+## Maps
+
+- Wireframe maps of your photo coverage and per-photo location maps.
+- Built-in tile cache/proxy: tiles are fetched once from the configured provider and served locally afterwards.
+
+![Tools map with activity traces](docs/img/tools_map.png)
+
+## Statistics
+
+- Per-scanner throughput (items processed and speed).
+- Storage overview: database size plus disk usage of every data folder.
+
+## Install
+
+A wheel is attached to every [release](https://github.com/sildra/trailframe/releases/latest): download the latest `trailframe-…-py3-none-any.whl` and install it with pip (Python 3.12 or newer):
+
+```bash
+pip install trailframe-…-py3-none-any.whl
+```
+
+All Python dependencies are pulled in automatically; the web UI is bundled inside the wheel.
+
+## Running
+
+Run the `trailframe` command from the folder where all data (database, thumbnails, caches, trash) should live:
+
+```bash
+trailframe --config path/to/config.yaml
+```
+
+(`python -m trailframe.main` is equivalent.) The server listens on port 8000 by default; open `http://localhost:8000`. On first start a default `config.yaml` is written to the current directory.
+
+### From source
+
+Build the web UI once (`npm install && npm run build` inside `frontend/`), then start the server from the repository root:
+
+```bash
+python supervisor.py --config path/to/config.yaml
+```
+
+The supervisor restarts the server whenever it exits and forwards SIGTERM/SIGBREAK to it. To build a wheel yourself, build the web UI first, then run `pip wheel .`.

trailframe-0.1.0/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?