先进的地理定位

Tracelet 不仅仅是一个后台位置包装器。它包含一套专门为解决移动地理定位中最困难的问题而设计的高级算法：GPS 抖动、隧道停电和高速电池消耗。

1.卡尔曼滤波器（轨迹平滑）

原始 GPS 数据本质上是有噪声的。如果用户沿着笔直的道路行走，原始坐标将随机左右跳跃，从而创建一条“锯齿状”线。如果计算这条锯齿线的距离，它会人为地将用户的总距离夸大最多 20%。

它是如何运作的

通过设置 useKalmanFilter: true，Tracelet 应用了最初为航天器导航开发的高级数学算法。它将当前的 GPS 位置与设备的速度（速度和航向）融合起来，以“预测”用户的实际位置，从而有效地消除噪音并生成完美的曲线。

final config = Config.highAccuracy(
  geo: tl.GeoConfig(
    filter: tl.LocationFilter(
      useKalmanFilter: true, // Enable trajectory smoothing
      trackingAccuracyThreshold: 50,
    ),
  ),
);

2. 航位推算（隧道和 GPS 被拒绝）

当用户开车进入长隧道或地下停车场时，他们就会失去与 GPS 卫星的连接。传统的追踪器只会从隧道入口到出口画一条直线，跳过实际的地下路线。

它是如何运作的

通过设置 enableDeadReckoning: true，Tracelet 可以检测 GPS 何时丢失，并立即无缝切换到设备的内部 IMU（惯性测量单元）。它使用加速计和陀螺仪根据用户最后已知的速度继续计算用户的轨迹，即使完全在地下也能模拟 GPS 更新。

final config = Config.balanced(
  geo: tl.GeoConfig(
    enableDeadReckoning: true,
    deadReckoningActivationDelay: 10, // Wait 10 seconds of no GPS before activating
    deadReckoningMaxDuration: 300, // Stop dead reckoning after 5 minutes to prevent drift
  ),
);

如果您的 distanceFilter 设置为 20 米，则 Tracelet 每 20 米唤醒一次。如果用户在笔直的高速公路上以 120 公里/小时的速度行驶，则不到一秒即可行驶 20 米。这会导致数据库在一条完美的直线上充满数百个无用的点，从而耗尽电池电量。

它是如何运作的

Tracelet 的 弹性引擎 检测高速并动态“拉伸”您的距离过滤器。 20m 的过滤器可能会在高速公路上自动拉伸到 200m，并在用户从匝道进入城市时收缩回 20m。

final config = Config.balanced(
  geo: tl.GeoConfig(
    disableElasticity: false, // Ensure elasticity is on
    elasticityMultiplier: 2.0, // Make the dynamic stretching 2x more aggressive
  ),
);

4. 自适应模式（省电）

如果员工的手机电池快没电了，您的首要任务不应该是高频 5 米跟踪。它应该确保手机能够正常工作直到轮班结束。

它是如何运作的

通过设置 enableAdaptiveMode: true，Tracelet 会持续监控操作系统的电池 API。当电池电量低于临界阈值（例如 20%、10%）时，Tracelet 会自动将 desiredAccuracy 从 GPS 降级为 Wi-Fi/蜂窝网络，并扩展 distanceFilter，从而保留足够的电量来保持手机运行。

final config = Config.balanced(
  geo: tl.GeoConfig(
    enableAdaptiveMode: true,
  ),
);

5. 稀疏更新（仅限蜂窝塔）

有时您不需要逐向导航的准确性；您只需要大致了解用户所在的城市或社区（例如，社交网络应用程序或天气应用程序）。

它是如何运作的

通过启用 enableSparseUpdates，Tracelet 完全绕过了耗电的 GPS 芯片。它专门使用手机信号塔切换和 Wi-Fi 三角测量来更新位置。电池消耗降至接近于零。

final config = Config.lowPower(
  geo: tl.GeoConfig(
    enableSparseUpdates: true,
    sparseDistanceThreshold: 500.0, // Only trigger if they move 500m
    sparseMaxIdleSeconds: 3600, // Or trigger once an hour even if they haven't moved
  ),
);

6. Live Provider 选项（运行时覆盖）

有时，您的应用程序知道 SDK 无法知道的事情：送货司机刚刚休息了 30 分钟，骑手正在场地内等待，或者您自己的固定启发法被触发。您希望“立即”放松 GPS，并在情况发生变化时迅速恢复到完全精确度。

到目前为止，唯一的旋钮是 setConfig()。但 desiredAccuracy 和 distanceFilter 是与跟踪相关的键，因此通过配置更改它们保留新值并执行干净的全管道重新启动 - 对于永久配置来说是正确的，但它会创建一个可避免的跟踪间隙并重建处理器状态只是为了应用临时电源策略。更糟糕的是，由于更改持续存在，因此在“低功耗”阶段终止并重新启动的应用程序将以降低的准确性永久唤醒跟踪。

它是如何运作的

Tracelet.updateLocationProviderOptions() 就地更新 正在运行 操作系统位置提供程序 — 没有 stop()，没有 start()，修复流中没有间隙：

• iOS 将新值直接分配给实时 CLLocationManager（desiredAccuracy / distanceFilter 在活动管理器上是可变的）。
• Android 使用新的 LocationRequest 重新订阅现有的融合提供者回调。重新注册相同的回调替换适当的请求，因此订阅永远不会丢失。
• Web 没有实时提供程序控件，并且始终返回 false。

覆盖是故意的短暂且仅限提供者：

• 持久的 Config 和 Tracelet.activeConfig 永远不会被触及 - 不会将任何内容写入存储，因此进程重新启动始终会返回到您的真实配置。
• Rust 接受点过滤器和处理器状态保持不变：轨道连续性、里程表以及接受的交付点都保持完全按照配置工作。
• 调用 stop() 会自动清除覆盖。

// Device confirmed stationary — drop Core Location to ~100m accuracy
// and only deliver a fix every 25 meters:
await Tracelet.updateLocationProviderOptions(
  desiredAccuracy: DesiredAccuracy.medium,
  distanceFilter: 25,
);
 
// Movement detected — restore the configured provider options.
// No arguments = clear the override:
await Tracelet.updateLocationProviderOptions();

返回值和验证

当应用实时更新时，该调用返回 true；当无法应用实时更新时，该调用返回 false — 它永远不会重新启动管道作为后备：

distanceFilter 必须是有限且非负的（否则会抛出 RangeError）。 0 值请求提供程序生成的每个修复（iOS 上为 kCLDistanceFilterNone）。