@ziztechnology/dial-library 0.0.10 → 0.0.12

package/README.md

@@ -166,31 +166,34 @@ type SensorMetric<T> =
 | `batteryCapacity`    | `{ levelPercent, chargeCounterUah }`   | 无       |
 | `battery`            | 电池是否存在、充电状态、健康度和电压等 | 无       |
 
-如果只需要根据单次快照做无状态判断，可以使用纯函数 `classifyDrivingSnapshot()`：
+如果需要检查单次快照的车辆坐标投影和瞬时候选，可以使用 `classifyDrivingSnapshot()`：
 
 ```ts
 import { classifyDrivingSnapshot, unifiedSensorInfo } from '@ziztechnology/dial-library';
 
-const status = classifyDrivingSnapshot(await unifiedSensorInfo());
+const analysis = classifyDrivingSnapshot(await unifiedSensorInfo());
 
-if (status === null) {
+if (analysis === null) {
   console.log('传感器数据不可用、非法或已经过期');
 } else {
-  console.log('当前瞬时状态：', status);
+  console.log('纵向加速度：', analysis.metrics.longitudinal);
+  console.log('偏航角速度：', analysis.metrics.yaw);
+  console.log('瞬时候选：', analysis.candidateStatus);
+  console.log('拒绝原因：', analysis.rejectionReason);
 }
 ```
 
-`checkRunningStatus()` 是同一函数的兼容别名。单次分类不会去抖，也不会保存上一次状态；它使用 Runtime 的 `motionIntensity >= 0.4 m/s²` 判断瞬时行驶。面向 UI 时，通常应该使用下一节带 accelerometer 滑窗的状态控制器。
+该函数不返回最终的 `STOPPED` 或 `STEADY_DRIVING`，也不保存时间窗口。`candidateStatus` 只能用于诊断，面向 UI 必须使用下一节的状态控制器。
 
-设备的固定安装方向为：
+设备的正反面和车头朝向需要固定，但允许安装倾角变化。SDK 对重力向量做低通滤波，并动态建立车辆坐标系：
 
 ```text
-+X = 车身右侧
-+Y = 上方
--Z = 车辆前进方向
+right   = 将设备 +X 投影到水平面
+up      = 归一化后的 TYPE_GRAVITY
+forward = right × up
 ```
 
-因此纵向加速度取 `-linearAcceleration.z`，横向加速度取 `linearAcceleration.x`，偏航角速度取 `gyroscope.y`。
+线性加速度和陀螺仪随后投影到该坐标系。标准化后的正偏航表示左转，负偏航表示右转，因此同一安装朝向下的俯仰角偏差不会改变前后、左右和转向符号。
 
 ## 行车状态基本使用
 
@@ -220,9 +223,13 @@ unsubscribe();
 controller.destroy();
 ```
 
-控制器默认每 200ms 读取一次，并保证上一次读取结束后才开始下一次。它会对普通动作平滑、要求候选状态连续出现、设置状态最短展示时间，并允许急刹车等高优先级状态抢占。候选状态不会触发 UI，只有提交后的稳定状态才会通知订阅者。
+控制器默认每 200ms 读取一次，并保证上一次读取结束后才开始下一次。所有确认都使用传感器时间而不是轮询次数；相同 `sampledAtMs` 的重复数据不会推进窗口。
 
-静止和匀速使用 accelerometer 的 1 秒三轴波动窗口判断。窗口按 `sampledAtMs` 去重，至少积累 5 个有效样本；总体标准差大于 `0.4 m/s²` 时进入 `STEADY_DRIVING`，小于 `0.25 m/s²` 时进入 `STOPPED`，中间区间保持原基础状态。滑窗预热不影响加速、刹车或转弯识别。accelerometer 不可用或过期时，整次行车快照进入不可用流程。
+静止和匀速使用 accelerometer 的 1 秒三轴 MAD 稳健波动窗口，至少需要 5 个唯一样本。运动量不高于 `0.12 m/s²` 且陀螺仪足够稳定，连续 5 秒才进入 `STOPPED`；运动量达到 `0.18 m/s²` 或陀螺仪出现持续运动，连续 0.6 秒进入 `STEADY_DRIVING`。中间区间保持原基础状态。
+
+普通加速和刹车要求 0.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。转向由偏航持续值或累计转角触发并锁存到回正结束。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
+
+缓慢转向还要求偏航旋转占陀螺仪能量的主要部分，或存在足够的横向加速度；垂直颠簸占主导且缺少偏航佐证时不会创建转向事件。重力样本短时缺失时，控制器会在 `maxSampleAgeMs` 内复用最后一个滤波后的车辆坐标系；缓存到期后按传感器不可用处理。单独调用 `classifyDrivingSnapshot()` 不会使用控制器缓存。
 
 ### 读取当前状态
 
@@ -233,9 +240,11 @@ const snapshot = controller.getSnapshot();
 
 console.log(snapshot.status); // 已提交状态
 console.log(snapshot.candidate); // 正在确认的候选状态，可能为 null
-console.log(snapshot.candidateConfirmationCount);
+console.log(snapshot.candidateSinceMs); // 候选首次出现的传感器时间
+console.log(snapshot.activeTurn); // 已锁存的转向事件
+console.log(snapshot.baseStatus); // STOPPED 或 STEADY_DRIVING
 console.log(snapshot.lifecycle); // stopped、running 或 destroyed
-console.log(snapshot.tuningVersion); // driving-status-v1
+console.log(snapshot.tuningVersion);
 ```
 
 ### 调整识别参数
@@ -245,22 +254,28 @@ console.log(snapshot.tuningVersion); // driving-status-v1
 ```ts
 const controller = createDrivingStatusController({
   tuning: {
-    turnYawThreshold: 0.6,
+    turnYawThreshold: 0.13,
     motionWindowMs: 1_200,
     motionMinimumSamples: 6,
-    drivingMotionThreshold: 0.45,
-    stoppedMotionThreshold: 0.28,
-    confirmationSamples: {
-      LEFT_TURN: 3,
-      RIGHT_TURN: 3,
-    },
+    drivingMotionThreshold: 0.2,
+    stoppedMotionThreshold: 0.11,
+    stoppedConfirmationMs: 5_000,
+    longitudinalThreshold: 0.75,
+    turnYawDominanceThreshold: 0.65,
+    turnLateralEvidenceThreshold: 0.3,
   },
 });
 ```
 
-`drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，形成进入行驶和退出行驶的迟滞区间。`motionMinimumSamples` 必须是正整数，其余窗口和阈值必须是正有限数值。
+`drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，进入阈值也必须大于相应退出阈值。样本数必须是正整数，方向一致率必须大于 `0.5` 且不大于 `1`，其余窗口和阈值必须是正有限数值。
+
+### 识别诊断
+
+`onDiagnostic` 的 `sample_available` 事件包含 `frameSource`（`live` 或 `cached`）和 `frameAgeMs`。`detector_evidence` 会报告基础状态 MAD、普通/急加减速的均值、峰值、方向一致率和 RMS，以及转向的累计角度、偏航主导率和横向/垂直 RMS。
+
+检测器状态变化时还会发送 `detector_transition`，其 `phase` 为 `candidate_entered`、`candidate_rejected`、`candidate_confirmed` 或 `candidate_exited`。该事件携带当时的完整 `statistics`，可直接用于真车回放调参；同一状态不会逐轮询重复发送。
 
-固定安装的惯性传感器无法严格区分“完全静止”和“理想匀速直线运动”。默认算法使用三轴加速度波动和陀螺仪扰动近似判断，修改阈值后应在真机上路测。
+惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
 
 ### 驱动行车表情
 

package/dist/index.d.mts

@@ -69,38 +69,91 @@ declare const unifiedSensorInfo: () => Promise<UnifiedSensorInfoPayload>;
 interface DrivingStatusTuning {
   version: string;
   maxSampleAgeMs: number;
-  rapidLongitudinalThreshold: number;
-  longitudinalThreshold: number;
-  turnYawThreshold: number;
-  turnLateralThreshold: number;
+  gravityFilterTimeConstantMs: number;
+  biasFilterTimeConstantMs: number;
+  vehicleRightMinimumNorm: number;
   motionWindowMs: number;
   motionMinimumSamples: number;
-  drivingMotionThreshold: number;
   stoppedMotionThreshold: number;
+  drivingMotionThreshold: number;
   stoppedGyroThreshold: number;
-  hysteresisRatio: number;
-  smoothingWindowSize: number;
-  confirmationSamples: Readonly<Record<CarRunningStatus, number>>;
-  minimumDisplayMs: Readonly<Record<CarRunningStatus, number>>;
-}
-type DrivingStatusTuningOverrides = Partial<Omit<DrivingStatusTuning, 'confirmationSamples' | 'minimumDisplayMs'>> & {
-  confirmationSamples?: Partial<Record<CarRunningStatus, number>>;
-  minimumDisplayMs?: Partial<Record<CarRunningStatus, number>>;
-};
+  stoppedRawGyroThreshold: number;
+  drivingGyroThreshold: number;
+  drivingRawGyroThreshold: number;
+  stoppedConfirmationMs: number;
+  drivingConfirmationMs: number;
+  longitudinalWindowMs: number;
+  longitudinalMinimumSamples: number;
+  longitudinalThreshold: number;
+  longitudinalExitThreshold: number;
+  longitudinalSignCoherence: number;
+  longitudinalReleaseMs: number;
+  rapidLongitudinalWindowMs: number;
+  rapidLongitudinalMinimumSamples: number;
+  rapidLongitudinalPeakThreshold: number;
+  rapidLongitudinalMeanThreshold: number;
+  rapidLongitudinalSignCoherence: number;
+  rapidMinimumDisplayMs: number;
+  verticalBumpRatio: number;
+  longitudinalReversalWindowMs: number;
+  turnWindowMs: number;
+  turnMinimumSamples: number;
+  turnYawThreshold: number;
+  turnConfirmationMs: number;
+  turnIntegratedAngleThreshold: number;
+  turnSignCoherence: number;
+  turnYawDominanceThreshold: number;
+  turnLateralEvidenceThreshold: number;
+  turnVerticalNoiseFloor: number;
+  turnVerticalBumpRatio: number;
+  turnExitYawThreshold: number;
+  turnExitConfirmationMs: number;
+  turnClosureWindowMs: number;
+}
+type DrivingStatusTuningOverrides = Partial<DrivingStatusTuning>;
 declare const DEFAULT_DRIVING_STATUS_TUNING: Readonly<DrivingStatusTuning>;
+interface DrivingVehicleFrame {
+  up: Vector3Value;
+  right: Vector3Value;
+  forward: Vector3Value;
+}
+interface DrivingMetricsCorrection {
+  filteredGravity?: Vector3Value;
+  filteredGravitySampledAtMs?: number;
+  linearAccelerationBias?: Vector3Value;
+  gyroscopeBias?: Vector3Value;
+}
 interface DrivingSnapshotMetrics {
   capturedAtMs: number;
+  linearAccelerationSampledAtMs: number;
+  gyroscopeSampledAtMs: number;
+  gravitySampledAtMs: number;
   longitudinal: number;
   lateral: number;
+  vertical: number;
   yaw: number;
-  motionIntensity: number;
   gyroMagnitude: number;
+  rawGyroMagnitude: number;
+  rawLinearAcceleration: Vector3Value;
+  rawGyroscope: Vector3Value;
+  frame: DrivingVehicleFrame;
+}
+type DrivingSnapshotCandidate = Exclude<CarRunningStatus, 'STOPPED' | 'STEADY_DRIVING'>;
+type DrivingSnapshotRejectionReason = 'vertical_bump' | null;
+interface DrivingSnapshotAnalysis {
+  capturedAtMs: number;
+  metrics: DrivingSnapshotMetrics;
+  candidateStatus: DrivingSnapshotCandidate | null;
+  rejectionReason: DrivingSnapshotRejectionReason;
+  quality: {
+    frameValid: true;
+    maximumSampleAgeMs: number;
+  };
 }
-declare const classifyDrivingSnapshot: (info: UnifiedSensorInfoPayload, tuningOverrides?: DrivingStatusTuningOverrides) => CarRunningStatus | null;
-declare const checkRunningStatus: (info: UnifiedSensorInfoPayload, tuningOverrides?: DrivingStatusTuningOverrides) => CarRunningStatus | null;
+declare const classifyDrivingSnapshot: (info: UnifiedSensorInfoPayload, tuningOverrides?: DrivingStatusTuningOverrides) => DrivingSnapshotAnalysis | null;
 declare const resolveDrivingStatusTuning: (overrides?: DrivingStatusTuningOverrides) => DrivingStatusTuning;
-declare const extractDrivingSnapshotMetrics: (info: UnifiedSensorInfoPayload, tuning?: Pick<DrivingStatusTuning, "maxSampleAgeMs">) => DrivingSnapshotMetrics | null;
-declare const classifyDrivingMetrics: (metrics: DrivingSnapshotMetrics, tuning?: DrivingStatusTuning) => CarRunningStatus;
+declare const extractDrivingSnapshotMetrics: (info: UnifiedSensorInfoPayload, tuning?: Pick<DrivingStatusTuning, "maxSampleAgeMs" | "vehicleRightMinimumNorm">, correction?: DrivingMetricsCorrection) => DrivingSnapshotMetrics | null;
+declare const buildVehicleFrame: (gravity: Vector3Value, rightMinimumNorm?: number) => DrivingVehicleFrame | null;
 //#endregion
 //#region src/sensor/driving_expressions.d.ts
 interface MediaLibraryRef {
@@ -199,10 +252,54 @@ interface DrivingStatusEvent {
   reason: DrivingStatusChangeReason;
   atMs: number;
 }
+type DrivingFrameSource = 'live' | 'cached';
+type DrivingDetectorName = 'base' | 'rapid_longitudinal' | 'longitudinal' | 'turn';
+type DrivingDetectorTransitionPhase = 'candidate_entered' | 'candidate_rejected' | 'candidate_confirmed' | 'candidate_exited';
+type DrivingDetectorRejectionReason = 'vertical_bump' | 'longitudinal_reversal' | null;
+interface DrivingBaseDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  motionMad: number | null;
+  gyroMagnitude: number;
+  rawGyroMagnitude: number;
+}
+interface DrivingLongitudinalWindowStatistics {
+  sampleCount: number;
+  durationMs: number;
+  mean: number;
+  peak: number;
+  coherence: number;
+}
+interface DrivingRapidLongitudinalStatistics extends DrivingLongitudinalWindowStatistics {
+  longitudinalRms: number;
+  verticalRms: number;
+  hasReversal: boolean;
+}
+interface DrivingTurnDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  strongMean: number;
+  strongCoherence: number;
+  signedAngle: number;
+  gentleCoherence: number;
+  yawRms: number;
+  rawGyroRms: number;
+  yawDominance: number;
+  lateralRms: number;
+  verticalRms: number;
+}
+interface DrivingDetectorStatistics {
+  base: DrivingBaseDetectorStatistics;
+  longitudinal: DrivingLongitudinalWindowStatistics | null;
+  rapidLongitudinal: DrivingRapidLongitudinalStatistics | null;
+  turn: DrivingTurnDetectorStatistics | null;
+}
 type DrivingStatusDiagnosticEvent = {
   type: 'sample_available';
   atMs: number;
   capturedAtMs: number;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
   tuningVersion: string;
 } | {
   type: 'sample_unavailable';
@@ -210,6 +307,28 @@ type DrivingStatusDiagnosticEvent = {
   unavailableForMs: number;
   category: 'provider_error' | 'invalid_or_stale_snapshot';
   tuningVersion: string;
+} | {
+  type: 'detector_evidence';
+  atMs: number;
+  motionMad: number | null;
+  baseCondition: 'warming_up' | 'stationary' | 'moving' | 'hysteresis';
+  rapidCandidate: 'RAPID_ACCELERATION' | 'SUDDEN_BRAKING' | null;
+  longitudinalCandidate: 'ACCELERATION' | 'BRAKING' | null;
+  turnCandidate: 'LEFT_TURN' | 'RIGHT_TURN' | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
+  statistics: DrivingDetectorStatistics;
+  tuningVersion: string;
+} | {
+  type: 'detector_transition';
+  atMs: number;
+  detector: DrivingDetectorName;
+  phase: DrivingDetectorTransitionPhase;
+  status: CarRunningStatus | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  statistics: DrivingDetectorStatistics;
+  tuningVersion: string;
 } | {
   type: 'candidate_changed';
   atMs: number;
@@ -223,13 +342,6 @@ type DrivingStatusDiagnosticEvent = {
   previousStatus: CarRunningStatus;
   reason: DrivingStatusChangeReason;
   tuningVersion: string;
-} | {
-  type: 'status_held_by_min_duration';
-  atMs: number;
-  status: CarRunningStatus;
-  candidate: CarRunningStatus;
-  remainingMs: number;
-  tuningVersion: string;
 } | {
   type: 'fallback_to_stopped';
   atMs: number;
@@ -239,8 +351,10 @@ type DrivingStatusDiagnosticEvent = {
 interface DrivingControllerSnapshot {
   lifecycle: 'stopped' | 'running' | 'destroyed';
   status: CarRunningStatus;
+  baseStatus: 'STOPPED' | 'STEADY_DRIVING';
+  activeTurn: 'LEFT_TURN' | 'RIGHT_TURN' | null;
   candidate: CarRunningStatus | null;
-  candidateConfirmationCount: number;
+  candidateSinceMs: number | null;
   statusCommittedAtMs: number;
   lastAvailableAtMs: number | null;
   unavailableSinceMs: number | null;
@@ -320,4 +434,4 @@ interface DrivingExpressionPlayer {
 }
 declare const createDrivingExpressionPlayer: (container: HTMLElement, options: DrivingExpressionPlayerOptions) => DrivingExpressionPlayer;
 //#endregion
-export { AvailableSensorMetric, BATTERY_HEALTH_LABELS, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, CarRunningStatus, CompleteDrivingExpressionsConfig, DEFAULT_DRIVING_STATUS_TUNING, DrivingControllerSnapshot, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingSensorProvider, DrivingSnapshotMetrics, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, checkRunningStatus, classifyDrivingMetrics, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };
+export { AvailableSensorMetric, BATTERY_HEALTH_LABELS, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, CarRunningStatus, CompleteDrivingExpressionsConfig, DEFAULT_DRIVING_STATUS_TUNING, DrivingBaseDetectorStatistics, DrivingControllerSnapshot, DrivingDetectorName, DrivingDetectorRejectionReason, DrivingDetectorStatistics, DrivingDetectorTransitionPhase, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingFrameSource, DrivingLongitudinalWindowStatistics, DrivingMetricsCorrection, DrivingRapidLongitudinalStatistics, DrivingSensorProvider, DrivingSnapshotAnalysis, DrivingSnapshotCandidate, DrivingSnapshotMetrics, DrivingSnapshotRejectionReason, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingTurnDetectorStatistics, DrivingVehicleFrame, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, buildVehicleFrame, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };