@glandais/vcyclist-engine 1.2.1 → 2.0.0

package/README.md

@@ -3,6 +3,9 @@
 [![npm engine](https://img.shields.io/npm/v/@glandais/vcyclist-engine?label=%40glandais%2Fvcyclist-engine)](https://www.npmjs.com/package/@glandais/vcyclist-engine)
 [![npm elevation](https://img.shields.io/npm/v/@glandais/vcyclist-elevation?label=%40glandais%2Fvcyclist-elevation)](https://www.npmjs.com/package/@glandais/vcyclist-elevation)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-engine?label=io.github.glandais%3Avcyclist-engine)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-engine)
+[![Maven Central gpx](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-gpx?label=io.github.glandais%3Avcyclist-gpx)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-gpx)
+[![Maven Central fit](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-fit?label=io.github.glandais%3Avcyclist-fit)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-fit)
+[![Maven Central map](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-map?label=io.github.glandais%3Avcyclist-map)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-map)
 
 Kotlin Multiplatform port of [`@glandais/virtual-cyclist`](https://github.com/glandais/virtual-cyclist):
 physics-based cycling simulator that turns a static GPS trace into a virtualized ride with
@@ -38,9 +41,21 @@ TypeScript library for elevation data.
 | Module | Purpose | Targets |
 |---|---|---|
 | **`:elevation`** | Terrarium tile fetch + DEM lookup + Haversine + Douglas-Peucker 3D + triangular smoother. See [`elevation/README.md`](elevation/README.md). | JVM, JS Node, JS browser, Wasm browser |
-| **`:engine`** | Path model (36 fields × `DoubleArray`), physics (4 resistive `PowerProvider`s + cyclist input + `MaxSpeedComputer` + `VirtualizeService`), GPX I/O, `Enhancer` pipeline, JVM CLI. | JVM, JS Node, JS browser, Wasm browser |
+| **`:gpx`** | Path model (36 fields × `DoubleArray`), resamplers, Douglas-Peucker simplifier, elevation steps, GPX I/O. Published to Maven Central; **not** published to npm — its JS output ships inside `@glandais/vcyclist-engine`. | JVM, JS Node, JS browser, Wasm browser |
+| **`:engine`** | Physics (4 resistive `PowerProvider`s + cyclist input + `MaxSpeedComputer` + `VirtualizeService`), `Enhancer` pipeline, JVM CLI, JS/Wasm façades. Re-exports `:gpx` via `api`, so `io.github.glandais.engine.path.*` and `…engine.gpx.*` stay importable from `:engine`. | JVM, JS Node, JS browser, Wasm browser |
+| **`:fit`** | Garmin FIT encoding. `FitCourse` model + unit conversions in commonMain; `expect object FitEncoder` with a JVM `actual` on `com.garmin:fit` and JS/Wasm `actual`s on `@garmin/fitsdk`. | JVM, JS Node, JS browser, Wasm browser |
+| **`:map`** | Static map rendering: Web Mercator projection, image framing, tile download + cache, PNG output (`java.awt` / `ImageIO`). **JVM-only.** No default tile source — see [`map/README.md`](map/README.md) for the usage-policy obligations. | JVM only |
+| **`:cli`** | Command-line tool (picocli). **JVM-only, not published as a library** — distributed as an executable jar. Replaces gpx2web's `gpxtools-cli`. | JVM only |
 | **`:codegen`** | Tiny build-time helper that regenerates `GeneratedPath.kt` + `PointFieldAccessors.kt` from `PointField` (run only when the field list changes). | JVM only |
 
+### Migrating from gpx2web
+
+vcyclist replaces the `gpx` and `gpxtools-cli` modules of
+[gpx2web](https://github.com/glandais/gpx2web).
+[`docs/gpx2web-coverage.md`](docs/gpx2web-coverage.md) has one row per Java class — ported,
+replaced, or not ported with the reason — plus the deliberate behavioural differences. For the
+command-line options specifically, see [`cli/README.md`](cli/README.md).
+
 ## Install
 
 ### npm (Kotlin/JS or Kotlin/Wasm consumers)
@@ -64,20 +79,32 @@ dependencies {
 
 Replace `1.0.0` by the latest version shown in the badges above. KMP consumers automatically
 get the platform-specific variant (`-jvm`, `-js`, `-wasm-js`) for their target.
+`vcyclist-gpx` (the `Path` model + GPX I/O) comes in transitively via `vcyclist-engine`, and
+can also be depended on alone if you only need parsing and resampling.
 
 See [`docs/publishing.md`](docs/publishing.md) for the release process.
 
 ## Quick start
 
-### Run the JVM CLI
+### Run the CLI
+
+The CLI is **not** on Maven Central — it is an application, distributed as a self-contained jar
+attached to each [GitHub release](https://github.com/glandais/vcyclist/releases). Download
+`vcyclist-cli-<version>-all.jar` and run it with Java 21+, or build it yourself:
 
 ```bash
-# Enhance a GPX file with the default cyclist (80 kg / 280 W) and bike (Crr 0.004) :
-./gradlew :engine:run -Pargs="enhance path/to/input.gpx -o /tmp/output.gpx"
+# Build a self-contained jar, then run it from anywhere:
+./gradlew :cli:executableJar
+java -jar cli/build/libs/vcyclist-cli-*-all.jar enhance route.gpx --gpx out.gpx --csv out.csv
+
+# Or, during development:
+./gradlew :cli:run -Pargs="enhance route.gpx --gpx /tmp/out.gpx"
 ```
 
-The CLI runs the full enhancement pipeline (no elevation correction — no HTTP) and writes the
-simulated trace back to a GPX file. See [`engine/src/jvmMain/.../EngineCli.kt`](engine/src/jvmMain/kotlin/io/github/glandais/engine/EngineCli.kt).
+`enhance` runs the physics pipeline; `export` produces maps, FIT, CSV and JSON from a file you
+already have. Elevation correction is off unless you pass `--fix-elevation`, so nothing touches
+the network by default. Full usage, exit codes and the migration table from gpx2web's
+`gpxtools-cli` are in [`cli/README.md`](cli/README.md).
 
 ### Try the browser demos (elevation only)
 
@@ -115,10 +142,26 @@ suspend fun virtualize(xml: String): String {
 The Kotlin/JS variant (`@glandais/vcyclist-engine`, `@glandais/vcyclist-elevation`) runs
 **in both browser and Node.js / Bun**. The Wasm variants (`*-wasm`) are browser-only.
 
+#### Getting at the exports
+
+Kotlin/JS emits a **UMD bundle that preserves the package namespace**, so the module has
+exactly one top-level export, `io`. Named imports do not work — `import { parseGpx } from
+'@glandais/vcyclist-engine'` fails under Node ESM with *"Named export 'parseGpx' not found"*.
+Unwrap the namespace once and destructure from it :
+
+```js
+import * as engineRaw from '@glandais/vcyclist-engine';   // or: require('@glandais/vcyclist-engine')
+
+const engine = engineRaw.io.github.glandais.engine;
+```
+
+Every snippet below assumes that `engine`. `demo/src/engine-shim.ts` does the same unwrap and
+adds TypeScript types for the DTOs, which Kotlin/JS emits as referenced names only.
+
 #### Browser
 
 ```js
-import { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } from '@glandais/vcyclist-engine';
+const { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } = engine;
 
 const handle = parseGpx(gpxXml);
 console.log('input points:', pathSize(handle));
@@ -130,7 +173,7 @@ const xml = writeGpx(out);
 #### Node.js / Bun (with elevation correction)
 
 ```js
-import { parseGpx, enhance, writeGpx } from '@glandais/vcyclist-engine';
+const { parseGpx, enhance, writeGpx } = engine;
 
 const handle = parseGpx(gpxXml);
 const out = await enhance(handle, { fixElevation: true });  // fetches DEM tiles, decodes WebP
@@ -141,6 +184,35 @@ const xml = writeGpx(out);
 (mapterhorn Terrarium tiles) and runs the full pipeline (densify → fix elevation → smooth →
 max speeds → virtualize → resample → simplify).
 
+#### FIT export
+
+```js
+const { parseGpx, enhance, pathToFit } = engine;
+
+const out = await enhance(parseGpx(gpxXml), null);
+const fit = pathToFit(out, 'My route', Date.parse('2026-08-01T08:00:00Z'));
+// Kotlin/JS returns an Int8Array; the -wasm build returns a Uint8Array. Both are the same file.
+```
+
+FIT has no relative clock, so the start instant is mandatory. The output is a **Course** file
+(a route to follow), which is what a virtualized trace should be — not an Activity.
+
+#### Multi-track GPX
+
+`parseGpx` returns the **first** track, which is what most files contain. For documents with
+several `<trk>` or several `<trkseg>` :
+
+```js
+const { parseGpxTracks, parseGpxSegments, writeGpxTracks } = engine;
+
+const tracks = parseGpxTracks(gpxXml);       // one path per <trk>, segments concatenated
+const segments = parseGpxSegments(gpxXml);   // one path per <trkseg>, always continuous
+const xml = writeGpxTracks(tracks);          // one <trk> per path
+```
+
+Concatenating segments folds the pause between them into `totalDistance` — a `<trkseg>`
+boundary is a physical discontinuity. Use `parseGpxSegments` when that artefact matters.
+
 On Node.js / Bun, tile decoding uses [`@jsquash/webp`](https://www.npmjs.com/package/@jsquash/webp)
 (a pure-WASM WebP decoder, ~50 KB, listed as a runtime `dependency` of
 `@glandais/vcyclist-engine` and `@glandais/vcyclist-elevation`). It is loaded lazily via