map now working

2026-03-28 19:34:22 +01:00
parent 5d58126d2f
commit 3441079913
18 changed files with 1489 additions and 10 deletions
@@ -0,0 +1,162 @@
+# BincioActivity
+
+A federated, open-source, self-hosted activity stats platform.
+Own your data. Share what you want. Follow friends by URL.
+
+## What it is
+
+BincioActivity turns a folder of GPX/FIT/TCX files into a beautiful, modern
+static website — no database, no server required. It can run from the local
+filesystem, GitHub Pages, or any static host.
+
+**Federation**: anyone can "follow" a friend's data by adding a URL to their
+config. Friends' activities appear in your site, attributed to them.
+
+## Quick start
+
+```bash
+# Install
+pip install bincio          # or: uv add bincio
+
+# Extract your activities
+cp extract_config.example.yaml extract_config.yaml
+# edit extract_config.yaml with your paths
+bincio extract
+
+# Build the site (requires Node ≥ 20)
+cd site && npm install
+BINCIO_DATA_DIR=~/bincio_data npm run build
+# open site/dist/index.html
+```
+
+## Two stages
+
+### Stage 1 — Extract (`bincio extract`)
+
+Reads GPX, FIT, TCX files (including `.gz` compressed) and writes a
+BincioActivity Schema (BAS) data store: plain JSON + GeoJSON files.
+
+```
+bincio extract                              # uses extract_config.yaml
+bincio extract --input ~/rides --output ~/bincio_data
+bincio extract --file ride.gpx             # single file → stdout
+bincio extract --since 2025-01-01          # incremental
+```
+
+Supported sources:
+- GPX (generic, Garmin extensions)
+- FIT (Garmin, Hammerhead Karoo)
+- TCX (including Garmin's https:// namespace variant)
+- All of the above gzip-compressed (`.gz`)
+- Strava bulk export (`activities.csv` carries titles and descriptions)
+
+### Stage 2 — Render (`bincio render`)
+
+Generates a static site from the BAS data store using Astro.
+
+```
+cd site
+BINCIO_DATA_DIR=~/bincio_data npm run dev    # development
+BINCIO_DATA_DIR=~/bincio_data npm run build  # production build → site/dist/
+```
+
+## Configuration
+
+### extract_config.yaml
+
+```yaml
+owner:
+  handle: yourname
+  display_name: Your Name
+
+input:
+  dirs:
+    - ~/Activities/gpx
+    - ~/Activities/fit
+  metadata_csv: ~/strava_export/activities.csv   # optional Strava metadata
+
+output:
+  dir: ~/bincio_data
+
+default_privacy: public   # public | blur_start | no_gps | private
+
+track:
+  rdp_epsilon: 0.0001     # GPS simplification (~11m at equator)
+
+incremental: true          # skip already-processed files
+```
+
+### site/.env
+
+```
+BINCIO_DATA_DIR=/path/to/bincio_data
+```
+
+## The BincioActivity Schema (BAS)
+
+The data store is a directory of plain JSON files:
+
+```
+bincio_data/
+  index.json               ← activity feed + owner manifest
+  activities/
+    {id}.json              ← full activity with timeseries
+    {id}.geojson           ← simplified GPS track
+```
+
+See `SCHEMA.md` for the full specification. The schema is versioned and
+published as a standalone document so anyone can write importers in any
+language.
+
+## Federation
+
+Add a friend's `index.json` URL to your `site_config.yaml`:
+
+```yaml
+data_sources:
+  - type: local
+    path: ~/bincio_data
+  - type: remote
+    handle: alice
+    url: https://alice.github.io/bincio/index.json
+```
+
+At build time the renderer fetches their public data and renders it under
+`/friends/alice/`.
+
+## Privacy
+
+Privacy is enforced at the data layer — activities never leave your control:
+
+| Level | GPS track | Stats visible |
+|---|---|---|
+| `public` | Full track | Yes |
+| `blur_start` | First/last 200 m removed | Yes |
+| `no_gps` | Not published | Yes |
+| `private` | Not published | Not in index |
+
+## Tech stack
+
+| Layer | Technology |
+|---|---|
+| Extract | Python 3.12, click, fitdecode, gpxpy, lxml, rdp |
+| Site framework | Astro (static generation) |
+| UI components | Svelte 5 |
+| Styling | Tailwind CSS |
+| Charts | Observable Plot |
+| Maps | MapLibre GL + OpenFreeMap tiles |
+| Package manager (Python) | uv |
+| Package manager (Node) | npm |
+
+## Development
+
+```bash
+# Python
+uv sync
+uv run pytest
+uv run bincio --help
+
+# Site
+cd site && npm install
+BINCIO_DATA_DIR=/tmp/bincio_test npm run dev
+```