Segment analysis contract
Crossing discovery issues one opaque reference for each consecutive ordered zone/visit pair. The signed descriptor contains the track, ordered zone visits, canonical fractional positions, and zone/source revisions. Times, coordinates and measurements are reconstructed from the revision-checked canonical source using the discovery rules. Stored point IDs do not define the interval.
Import, discovery, and interval clipping share RecordingContinuity geometry rules. Nearby duplicate timestamps retain geometry support without inventing interior crossing timestamps. Explicit recording gaps and unsupported stored intervals split discovery. Consecutive known timestamps also expose gaps across untimed observations. Supported endpoint elapsed time remains available across a path gap when the clock is coherent; complete distance and average speed remain unavailable. Clock resets invalidate elapsed time even when the final endpoint difference is positive. The requested radius is the inner qualification circle. Zone departure uses an exit radius of radius + max(2 m, 20% × radius); closest approach still selects the visit's point. A crossing within any confirmed nonzero stationary span, including identical coordinates, produces AMBIGUOUS_DWELL timing for both adjacent attempts. Distance retains canonical observed geometry; no stationary coordinates are rewritten.
Discovery requires actual visits to every requested zone. Per-zone counts are exact within the filtered population before the complete-route intersection. Full timing and metric processing is limited to the candidate intersection. Each track's crossings, revision and attempt summaries are calculated in a separate read-only persistence context, which closes before the next track loads. Only compact results remain in the response. Other candidates use geometry and continuity projections one track at a time for exact per-zone qualification. Source memory therefore depends on the largest individual track; response memory still grows with the number of visits. Preliminary map counts are candidates. Candidate SQL uses canonical recorded paths, densified along the same wrapped lon/lat curve with a 0.25 m allowance; isolated fixes are retained without connecting recording gaps.
Stop notes use canonical stationary spans clipped by position and time. Total stopped time includes short pauses; break count and longest break use the one-minute visible-break threshold. Ambiguous marker timing or incomplete motion/path coverage makes these observed lower bounds.
SegmentAttemptResolver owns reference validation. References are signed server descriptors scoped to the authenticated user and expire after 30 minutes. Their signing key is derived separately from the persisted login key, so cache eviction and application restarts do not invalidate unchanged attempts. Expired, invalid, deleted, or changed sources return HTTP 410; another owner receives HTTP 404. The comparison offers Refresh results. No persistent attempt entity is needed.
The canonical revision includes point metrics and relevant events, covering changes that do not increment the parent track version. Every core, health, and comparison request revalidates it. Core results are cached for ten minutes with a 250,000-source-point weight limit. Optional health responses are uncached and use one repeatable-read database snapshot. Browser caches are disabled for these endpoints.
On this page
Calculation ownership
| Server responsibility | Rule |
|---|---|
| Identity and clipping | All services use the same resolved attempt. Exact analysis endpoints retain their measurements; virtual speed/slope interpolate the full-track physics window samples, while raw estimated power belongs to the interval's ending fix. Display windows are computed over the full track before clipping. |
| Distance, elapsed time, average speed | Use discovery's authoritative values with separate availability. Cumulative distance becomes unavailable after unsupported path coverage. Supported geometry progress ends at the authoritative distance; only discrepancies up to 1 cm are reconciled. Larger discrepancies log a diagnostic and make distance, speed and distance progress unavailable with DISTANCE_MISMATCH; elapsed time and independent metrics remain inspectable. Validation runs before discovery summaries are published. Recording breaks remain explicit. |
| Energy | Sum canonical interval work, prorated at fractional boundaries. Never subtract an invented whole-track baseline. An unsupported interval makes total energy unavailable; a supported initial prefix can remain visible as incomplete coverage. |
| Ascent/descent and maximum power | Calculate before series reduction. Unsupported cumulative elevation boundaries produce unavailable totals. Maximum power covers available endpoint and interior estimates. |
| Ordinary HR | Integrate raw BPM over canonical recorded support, including detected stops. Keep surrounding samples for integration, restrict recorded chart samples before bucketing, and preserve the existing BPM sample-gap limit. A sample with unavailable map distance can still appear on the time axis. |
| Cardiac cost | Use the same exact interval but retain the existing covered moving-time and minimum-work rules. Coasting counts; detected stops do not. |
| Consolidation | Arithmetic means with separate valid counts for elapsed time, distance, and visit speed. Incomplete path coverage and distance mismatches are excluded from performance means and default trends; individual endpoint elapsed times remain inspectable. Total visits and valid metric counts remain separate. HR uses covered-time weighting. |
| Comparison | Finish difference and equal-distance difference are separate results. Equal-distance interpolation has no extrapolation and preserves arrival and the limit after a stop. It requires the same ordered zone pair and zone revision. |
| Ghosts | For each reference distance, the attempt's distance at the reference's arrival time and the resulting lead. Samples cover the reference's timed geometry plus the attempt's own sample times. A reference stop adds a departure sample; an attempt past its end is FINISHED at its final distance; recording breaks are UNAVAILABLE. |
The client selects, requests, formats, and renders generated API values. It may interpolate map display positions within supported server geometry; it does not rebuild analytical totals, health averages, or time-gap curves. One selection owner handles reference validity, request generations, cancellation, and per-track retries. Core and health use independent pools of at most four requests each.
Core chart series share ChartSeriesMetrics and ChartBucketBuilder with track details: windowed speed/power, averaged elevation/slope, and last cumulative energy per bucket. Walking/hiking uses a 60-second display window; other activities use 30 seconds. The x request selects time or distance bucketing. Comparison Graph settings starts collapsed and reuses the saved track-detail Points (3–3,000) and Height (100–640 px) preferences. Height resizes all comparison graphs without requesting data. Counts are soft limits: exact endpoints, stops, gaps and null transitions take priority. Instantaneous maximum power remains a separate full-density summary. Full geometry and comparison breakpoints are retained. Large canonical tracks therefore still have a source-size-dependent response and calculation cost; chart reduction never changes the summaries.
API and verification
Discovery uses includeHealth=false for independent core loading. Existing callers retain the default inline HR behavior. The generated SegmentAnalysisControllerApi exposes core, health, comparison, and per-track table-HR requests. DTO units are explicit; unavailable optional fields may be absent or null, and display conversion preserves both as unavailable.
The schema is exported from the running server at /mtl/v3/api-docs, retaining http://localhost:8080/mtl as its server URL. Maven generates the TypeScript package in the development container; there is no new generator workaround.
Current segment tests cover exact boundaries, references, health support, and comparisons. Use the testing workflow for new verification.
Changed derived geometry and continuity metadata require reimporting existing tracks, or recreating the database. No legacy-data backfill is provided. Calculation version changes invalidate previous attempt references.