location/com.siddharth.kmp.location.algo

Package-level declarations

Types

AlgorithmHarness

object AlgorithmHarness

Replay a recorded trace through an algorithm and score the result.

AlgorithmId

@JvmInline

value class AlgorithmId(val value: String)

Stable algorithm identity. A string so that persisted rows survive refactors of the enum-ish set.

AlgorithmState

data class AlgorithmState(val schemaVersion: Int = CURRENT_SCHEMA_VERSION, val cleanedM: Double = 0.0, val abnormalM: Double = 0.0, val mockM: Double = 0.0, val spikeM: Double = 0.0, val originalM: Double = 0.0, val accepted: Int = 0, val rejected: Int = 0, val consecutiveNormal: Int = 0, val maxSpeedMps: Double = 0.0, val avgSpeedMps: Double = 0.0, val lastFix: Fix? = null, val opaque: Map<String, Double> = emptyMap())

Everything needed to resume a journey across process death.

DeviceEnvelope

data class DeviceEnvelope(val accuracyCeilingM: Double = 50.0, val stationaryAccuracyCeilingM: Double = 25.0, val minDisplacementMultiplier: Double = 1.0, val abnormalThresholdMultiplier: Double = 1.0, val gpsIntervalMultiplier: Double = 1.0)

Device-derived scaling, computed once at the platform edge and handed in.

DistanceBucket

enum DistanceBucket : Enum<DistanceBucket>

Which running total a fix's displacement was added to.

Fix

data class Fix(val lat: Double, val lng: Double, val timeMs: Long, val accuracyM: Double, val speedMps: Double? = null, val bearingDeg: Double? = null, val altitudeM: Double? = null, val isMock: Boolean = false, val provider: String? = null, val odometerM: Double? = null)

One location sample, stripped to what a distance algorithm can legitimately use.

FixResult

data class FixResult(val verdict: FixVerdict, val emitted: Fix?, val displacementM: Double, val distanceDeltaM: Double, val bucket: DistanceBucket, val reason: String? = null)

FixVerdict

enum FixVerdict : Enum<FixVerdict>

What happened to a fix. Diagnostic granularity — never branch business logic on this.

KnobSpec

data class KnobSpec(val name: String, val default: Double, val min: Double, val max: Double, val step: Double, val unit: String, val description: String = "")

One tunable parameter, described well enough to build a slider and run a sweep without knowing anything about the algorithm behind it.

MatchedRoute

data class MatchedRoute(val distanceM: Double, val confidence: Double, val pointMatched: List<Boolean>, val legDistancesM: List<Double> = emptyList())

What a map-matching provider reported for one MatchRequest.

MatchPoint

data class MatchPoint(val lat: Double, val lng: Double, val radiusM: Double, val timeMs: Long)

One point as a map-matching request wants it: a coordinate, how much to trust it, and when it was recorded.

MatchReconciliation

object MatchReconciliation

Decide what to present when the client's own distance and a map-matched distance disagree.

MatchRequest

data class MatchRequest(val points: List<MatchPoint>)

Everything one map-matching request needs, serialization-agnostic.

MileageAlgorithm

interface MileageAlgorithm

The seam that lets more than one mileage algorithm exist at the same time.

MileageAlgorithmRegistry

class MileageAlgorithmRegistry(factories: Map<AlgorithmId, (TuningProfile, DeviceEnvelope) -> MileageAlgorithm> = emptyMap())

Where algorithms are looked up by id.

PassThroughAlgorithm

class PassThroughAlgorithm(profile: TuningProfile = defaultProfile()) : MileageAlgorithm

Trust the source; filter nothing.

Reconciliation

data class Reconciliation(val verdict: ReconciliationVerdict, val clientDistanceM: Double, val matchedDistanceM: Double, val presentedDistanceM: Double, val confidence: Double, val differenceRatio: Double)

The outcome of one reconciliation. Both source figures are always present — see MatchReconciliation — so a caller that disagrees with presentedDistanceM can still recover whichever figure it dropped.

ReconciliationVerdict

enum ReconciliationVerdict : Enum<ReconciliationVerdict>

RouteMatcher

interface RouteMatcher

The seam between "distance we computed from raw fixes" and "distance a road network says we drove".

RunReport

data class RunReport(val algorithmId: AlgorithmId, val fixCount: Int, val finalState: AlgorithmState, val verdictCounts: Map<FixVerdict, Int>, val maxDisplacementM: Double)

What one replay produced.

Scorecard

data class Scorecard(val algorithmId: AlgorithmId, val truthM: Double, val measuredM: Double, val errorM: Double, val absErrorPercent: Double, val acceptedFixes: Int, val rejectedFixes: Int)

SegmentedTripAlgorithm

class SegmentedTripAlgorithm(profile: TuningProfile = defaultProfile(), envelope: DeviceEnvelope = DeviceEnvelope.Default, delegate: MileageAlgorithm = TieredGpsAlgorithm( TuningProfile(AlgorithmId.TieredGps, "mileway.v1"), envelope, )) : MileageAlgorithm

A decorator that adds the three corrections TieredGpsAlgorithm structurally cannot make, without touching it.

SessionContext

data class SessionContext(val startedAtMs: Long, val resumedFromPause: Boolean = false, val vehicleType: String? = null)

Journey-scoped inputs that are not properties of any single fix.

TieredGpsAlgorithm

class TieredGpsAlgorithm(profile: TuningProfile = milewayV1Profile(), envelope: DeviceEnvelope = DeviceEnvelope.Default) : MileageAlgorithm

Kalman-smoothed, speed-adaptive GPS cleaning — the algorithm Mileway's LocationProcessor actually runs today, extracted onto the MileageAlgorithm seam so its thresholds can be swept and its output can be shadow-compared against other algorithms.

TraceCase

data class TraceCase(val name: String, val fixes: List<Fix>, val truthMeters: Double? = null, val notes: String = "")

A recorded drive plus what it is known to have actually been.

TraceChunk

data class TraceChunk(val fixes: List<Fix>, val overlapWithPrevious: Int)

One request-sized window of a longer trace.

TraceCodec

object TraceCodec

Read and write recorded GPS traces, so a real drive becomes a regression test.

TracePreparation

object TracePreparation

Turn a raw fix stream into something a map-matching provider can actually be asked about.

TuningProfile

data class TuningProfile(val algorithmId: AlgorithmId, val profileId: String, val values: Map<String, Double> = emptyMap(), val flags: Map<String, Boolean> = emptyMap())

A named set of knob values for one algorithm.

Functions

haversineMeters

fun haversineMeters(lat1: Double, lng1: Double, lat2: Double, lng2: Double): Double

Great-circle (haversine) distance in metres.