rikka

スマートフォンの加速度計・ジャイロスコープ CSV から歩行軌跡を推定する PDR（Pedestrian Dead Reckoning）ライブラリです。

現在の標準設定は、ジャイロの端末方位と水平加速度の移動軸を分離する gyro_accel_motion です。横歩きを連続区間で復号し、安定区間から端末と身体の時変方位差を推定します。通常歩行は補正後の body_heading、確定横歩きは motion_heading を使い、端末だけを曲げた量が進行方向へ直接入らないようにしています。確定しなかった単発候補は前進扱いにします。

セットアップ

uv sync --all-groups

AI エージェントや sandbox 環境で uv の既定キャッシュに対する権限エラーが発生した場合に限り、リポジトリ内キャッシュを使って再実行します。

UV_CACHE_DIR=.uv-cache uv run pytest

パーティクルフィルタの MP4 アニメーション出力には ffmpeg が必要です。

brew install ffmpeg

入力データ

input/sensor_data/<人名>/<データフォルダ>/ に phyphox 形式の CSV を置きます。正解経路の動画・CSV・画像は input/correct_path/<経路フォルダ>/ に分けて配置します。フロアマップ画像は input/ 直下に置きます。

input/
├── sensor_data/
│   └── natsuki/
│       └── my_walk/
│           ├── Accelerometer.csv
│           └── Gyroscope.csv
├── correct_path/
│   └── my_walk/
│       └── walk_trace.csv
└── Floormap_building14_5floor.png

対応する列名は次の通りです。

ファイル	対応列
`Accelerometer.csv`	`Time (s)`, `Acceleration x/y/z (m/s^2)` または `X/Y/Z (m/s^2)`
`Gyroscope.csv`	`Time (s)`, `Gyroscope x/y/z (rad/s)` または `X/Y/Z (rad/s)`

現在の既定入力は次です。

DATA_DIR = "input/sensor_data/hiroto/hiroto_1turn_rightsidestep_3turn_leftsidestep"

別データを使う場合は、CLI の -d で指定できます。

uv run rikka run -d input/sensor_data/natsuki/my_walk

基本コマンド

標準設定で通常 PDR を実行します。プロット表示と PNG/CSV 保存を行います。

uv run rikka run

プロット表示を止めてバッチ確認する場合だけ --no-plot を付けます。

uv run rikka run --no-plot

pdr は run の別名です。

uv run rikka pdr

パーティクルフィルタ付きで実行します。

uv run rikka particle

グラフ表示なしでパーティクルフィルタのアニメーションだけ保存する場合:

uv run rikka particle --no-plot --save-animation

問題歩の粒子状態と代表軌跡候補を静止画で確認する場合:

uv run rikka particle --no-plot --pf-seed 10 \
  --save-step-frames --step-frames-range 70 85 \
  --save-path-comparison

段階別画像は既定で無効です。--step-frames-arrows で方位矢印数、 --step-frames-dpi で解像度を調整できます。

センサー波形を確認します。入力フォルダに sensor_plot.png を保存します。同名ファイルがある場合は、sensor_plot_001.png のように連番を付けて保存します。

uv run rikka sensor

BLE ランドマーク補正

既知座標に置いた BLE ビーコンの RSSI が閾値以上になったとき、通常 PDR または particle filter にランドマーク位置を反映できます。BLE 測位自体は既定で無効です。

実測では計測ディレクトリに BLE.csv、BLE_pos.csv、walk_config.csv を置きます。起点・方位を計測ごとに解決してから、PF のRSSI測距尤度を使います。

uv run python agent/agent_diagnose_ble_ranging.py \
  -d input/senser_data_withBLE/natsuki/WithBLE_1
uv run rikka particle \
  -d input/senser_data_withBLE/natsuki/WithBLE_1 \
  --ble-landmark --pf-landmark-mode ranging --no-plot

walk_config.csv がある場合の解決順は、CLI明示値、計測設定、共通既定値です。診断は corr(RSSI, log10(distance)) <= -0.5 かつパスロス係数 1.5 <= n <= 4.0 を合格条件とします。RSSIから逆算した探索起点は検算用であり、実測起点の代わりにはしません。

実測データがない場合は、回帰テスト用サンプルを先に生成できます。

uv run rikka ble-sample
uv run rikka run --ble-landmark --no-plot
uv run rikka particle --ble-landmark --no-plot

ble-sample は既定で、対象データのPDR軌跡とビーコンの距離からRSSIを生成します。評価用に正解軌跡を使う場合は次のように指定します。従来の固定ピーク時刻方式は --mode time で利用できます。

uv run rikka ble-sample \
  -d input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep \
  --source truth \
  --truth-csv "input/correct_path/1turn_rightsidestep_3turn_leftsidestep/walk_trace (3).csv"

BLE CSV は次の3列を持ちます。

列	内容
`timestamp_s`	phyphox の実験開始からの経過秒
`beacon_id`	`BLE_LANDMARKS_PX` に登録するビーコン識別子
`rssi_dbm`	受信 RSSI [dBm]

ランドマーク座標は src/rikka/common/config/__init__.py の BLE_LANDMARKS_PX に (beacon_id, pixel_x, pixel_y) で設定します。 pixel_x と pixel_y は --origin-px と同じ、フロアマップ画像の左上を (0, 0) とするピクセル座標です。補正時に --origin-px と --scale を使って PDR のメートル座標へ変換します。既定の検出下限は -70 dBm です。ピーク時刻は5サンプルの移動中央値で安定化します。

改札・自動ドア・踊り場のように、通過した事実から位置を確定できる地点は BLE_LANDMARK_ANCHORS へ追加します。既定値は空で、通常ランドマークの挙動には影響しません。

BLE_LANDMARK_ANCHORS = (
    # beacon_id, 位置σ[m], 方位[deg], 方位σ[deg], 双方向か
    ("beacon_3", 0.3, 90.0, 15.0, True),
)

方位は 0=+X、90=+Y、反時計回りが正です。方位を確定しない場合は3要素目を None にします。確定ランドマークはPFの距離比と5m上限によらず指定σの範囲へ粒子を再配置し、方位指定時は絶対方位差を減衰しない補正項へ反映します。大きなジャンプは停止せず警告します。強制補正なので、実測データで検出時刻と通過時刻が一致することを確認してから設定してください。

--ble-landmark: BLE 補正を有効化
--ble-data PATH: BLE CSV を指定
--ble-rssi-threshold DBM: 検出下限を変更
--ble-release-margin DB / --ble-release-streak N: ラッチ解除条件
--ble-sync-window S: 同時受信としてまとめる時刻窓
--ble-correction snap|warp|similarity: 通常PDRの補正方式。warp は直前拘束からの累積歩行距離比で残差を過去へ配分します。similarity は直前アンカーを固定して過去区間を回転・等方スケールし、同じ量を確定方位と歩幅へ反映します。既定の snap は後方互換のため維持しています。
--ble-preflight warn|error|off: RSSI距離整合FAIL時の扱い
--ble-max-correction M / --ble-max-warp-span M: 補正移動量とwarp区間の上限
--ble-retrofit-forward hold|freeze: similarity の回転・倍率を後続歩にも保持するか、検出歩までで固定するかを選びます。既定は hold です。
--ble-retrofit-max-heading、--ble-retrofit-stride-scale-min/max、 --ble-retrofit-min-span: 回転角・歩幅倍率・最小アンカー間距離の安全条件です。
--ble-retrofit-map-check off|warn|enforce: 地図違反を無視、警告、減衰後も違反する補正の棄却、のいずれかで扱います。減衰列は --ble-retrofit-damp-factor を複数指定して変更できます。

実測ログの検出は、閾値以上が3観測続くこと、同一ビーコンの10秒cooldown、 6dB以上のピークprominenceを要求します。合成BLEは既存goldenとの互換性のため、従来の1接近1検出規則を維持します。

実測値へ差し替える場合は、同じ3列と経過秒の時間軸へ整形し、 --ble-data <実測CSV> を指定します。絶対時刻だけの場合は、phyphox の meta/time.csv にある START の system time を引いて経過秒へ変換してください。 Thingsup形式を --ble-data で明示した場合、同じディレクトリに BLE_pos.csv が無ければ入力エラーになります。既定ランドマークへの無警告フォールバックは行いません。

BLE 有効時は output/<timestamp>/landmark_corrections.csv に検出時刻、RSSI、補正前座標、ランドマーク座標、補正後座標、検出距離、最接近時間差、アンカーの位置・方位設定を保存します。similarity では回転角、歩幅倍率、減衰係数、地図違反辺数、棄却理由も保存します。補正後の step_headings.csv には累積方位補正、累積歩幅倍率を保存し、step_lengths.csv と再積分すると軌跡に一致します。 trajectory.png（PFでは pf_trajectory.png）には、BLE_pos.csv で座標が確定した全ビーコンを星印で表示し、補正前後の軌跡と補正地点を重ねて描画します。最終歩より後で補正できなかった検出は step=-1、applied=False としてCSVに残ります。

particle filter では --pf-landmark-mode で反映方式を選びます。

none: 検出を軌跡へ反映しない。BLE 無効時と固定 seed の結果が一致します。
observation: ランドマーク距離の下限付きガウス尤度を粒子重みと sequence 経路スコアへ加えます。
reset: ランドマーク周辺の歩行可能位置へ粒子を再配置します。比較実験用で、位置以外の heading drift・stride scale・motion state は引き継ぎます。祖先経路が不連続になるため、reset 使用時の代表軌跡は pf-path-selection にかかわらず時点別の current 経路を使います。
hybrid（既定）: ランドマーク距離が粒子群の広がりの4倍以内ならobservation、それより遠く、かつ距離が2mを超える場合はresetを使います。通常resetの距離が 5mを超える検出は安全のため再配置せず、通常のPF更新を続けます。確定ランドマークはこの判定より優先されます。
ranging: RSSI領域でパスロスモデルの期待値と観測値を比較します。弱いRSSIは遠い粒子を支持し、resetを行わないため、祖先経路の再重み付けで検出前の軌跡にも観測が反映されます。pf-path-selection=sequence では合法な単一祖先経路を選びます。実測BLEではこの方式を使用します。

--pf-landmark-retrofit は既定で無効です。確定ランドマークが粒子を再配置した歩で、代表経路選択後のアンカー直前区間だけを相似変換し、位置ジャンプを解消します。粒子履歴と重みは変更せず、変換後の全辺が歩行可能な場合だけ採用します。

観測尤度の既定値は sigma=1.0m、floor=0.05 です。合成BLEと対応する正解軌跡の 6 seed評価で選んだ値なので、実測BLE取得後には再校正が必要です。PF の landmark_corrections.csv にある before/after は反映前後の粒子重み付き平均、raw_trajectory の描画は同じ歩列から作った通常 PDR 軌跡を表します。

ランドマーク測位は推定方式ごとに責務を分離しています。

ble/: BLE CSV、RSSI 判定、サンプル生成
landmark/lib/: 検出元や推定方式に依存しない座標変換、歩割り当て、時間整合評価、アンカー固定の相似変換
pdr/lib/landmark_correction.py: 通常 PDR 固有の完全座標補正
particle/lib/landmark.py: PF 固有の観測尤度と reset 再配置
common/lib/models.py: PDR / PF が共有する LandmarkRange、PathLossModel など

ble.pipeline.run_ble_landmark_detection() は軌跡を変更せず、検出列だけを返します。通常 PDR は検出を完全座標補正に使い、PF は同じ検出を観測尤度または再配置へ使います。

データフロー

rikka.__init__.main() から Click の cli.options に入り、 cli.commands.run() が設定の組み立てと各 pipeline の呼び出しを担当します。 run / pdr / particle は、同じ CSV 読み込みと PDR ステップ準備を通ります。通常 PDR はそのステップ列をそのまま軌跡へ積み上げ、particle filter は同じ PreparedPdrSteps をフロアマップ制約で補正します。最後に plot.pipeline が CSV・画像・アニメーションを出力します。

flowchart TD
    command["uv run rikka run / pdr / particle"] --> entry["rikka.__init__.main()"]
    entry --> cli_options["cli.options\nClickコマンド・オプション"]
    cli_options --> cli_run["cli.commands.run()\n設定構築・pipeline呼び出し"]

    input_dir["input/sensor_data/<data_dir>/"] --> acc_csv["Accelerometer.csv"]
    input_dir --> gyro_csv["Gyroscope.csv"]

    cli_run --> pdr_pipeline["pdr.pipeline.run_pdr()"]
    pdr_pipeline --> load["load_sensor_data()\n列名を t,x,y,z に正規化"]
    acc_csv --> load
    gyro_csv --> load
    load --> preprocess["process_sensor_data()\n重力推定 / 線形加速度 / 水平加速度 / gyro bias / low_angle"]

    preprocess --> step_detect["detect_step_result()\n歩行ステップのピーク・区間を検出"]
    preprocess --> heading["resolve_step_heading()\nbody_heading / motion_heading / movement_type を推定"]
    step_detect --> heading
    preprocess --> step_length["estimate_step_length()\nWeinberg などで歩幅候補を推定"]
    step_detect --> step_length
    heading --> sidestep["motion segment decode / dynamic body heading\nsidestep smoothing / heading stabilize"]
    step_length --> sidestep
    sidestep --> prepared["prepare_pdr_steps_with_settings()\nPreparedPdrSteps"]

    prepared --> pdr_branch{"コマンド"}
    ble_csv["input/ble/*.csv"] --> ble_pipeline["ble.pipeline.run_ble_landmark_detection()\nLandmarkDetection 列"]
    pdr_branch -->|rikka run / pdr| pdr_landmark["pdr.lib.landmark_correction\n通常PDRの完全座標補正"]
    ble_pipeline --> pdr_landmark
    pdr_landmark --> det_traj["TrajectoryResult\n通常 PDR 軌跡"]
    pdr_branch -->|rikka particle| particle_pipeline["particle.pipeline.run_particle()"]
    ble_pipeline --> particle_pipeline
    particle_pipeline --> pf["particle.lib.runner.run_particle_steps()\n地図拘束 / 重み / 再標本化 / recovery"]

    floormap["input/Floormap_building14_5floor.png"] --> pf_map["FloorMap\n通路/壁判定"]
    pf_map --> particle_pipeline
    pf --> pf_path["既定: 重み付き平均を優先\nsequence: 反転減少時だけ単一祖先経路"]

    det_traj --> plot_pipeline["plot.pipeline.write_outputs() / render()"]
    pf_path --> pf_result["TrajectoryResult\nPF補正軌跡・diagnostics"]
    pf_result --> plot_pipeline
    floormap --> plot_pipeline
    plot_pipeline --> output_dir["output/<timestamp>/\nCSV / PNG / MP4 または GIF"]

センサー波形だけを確認する sensor コマンドは、軌跡推定までは進まず、前処理とステップ検出結果を入力フォルダ内の画像へ保存します。

flowchart LR
    input["input/sensor_data/<data_dir>/\nAccelerometer.csv / Gyroscope.csv"] --> load["load_sensor_data()"]
    load --> preprocess["process_sensor_data()"]
    preprocess --> detect["detect_step_result()"]
    detect --> sensor_plot["plot_sensor_data()\nsensor_plot.png"]
    sensor_plot --> input

標準設定

uv run rikka run の現在の主要な既定値です。

項目	既定値	説明
`DATA_DIR`	`input/sensor_data/hiroto/hiroto_1turn_rightsidestep_3turn_leftsidestep`	入力データ
`FLOORMAP_PATH`	`input/Floormap_building14_5floor.png`	背景マップ
`FLOORMAP_ORIGIN_PX`	`(2050, 400)`	軌跡の開始ピクセル
`FLOORMAP_SCALE`	`0.01`	1px あたりのメートル数
`INITIAL_DIRECTION`	`90.0`	歩行開始方向 [deg]
`STEP_DETECTION_METHOD`	`peak`	ステップ検出
`HEADING_METHOD`	`gyro_accel_motion`	方位・移動方向推定
`FORWARD_HEADING_SOURCE`	`body`	通常歩行はジャイロ由来の体・端末方向を使用
`GYRO_BIAS_METHOD`	`prewalk_guarded`	小さい歩行前biasだけを採用し、端末回転の誤認を抑制
`USER_HEIGHT_M`	`1.68`	Weinberg 歩幅補正用の身長
`SIDESTEP_LATERAL_RATIO`	`1.2`	横方向/前方向の比率がこの値以上で横歩き候補
`SIDESTEP_MIN_LATERAL_DISPLACEMENT_M`	`0.03`	横歩き判定に必要な横方向変位 [m]
`SIDESTEP_SMOOTHING_METHOD`	`clustered`	同方向 evidence の連続クラスタを評価し、確定横歩きまたは横歩き疑いとして軌跡へ反映
`SIDESTEP_LENGTH_SCALE`	`0.8`	横歩き歩幅の倍率
`TURNING_LENGTH_SCALE`	`0.3`	旋回中歩幅の倍率
`MOTION_ESTIMATION`	`adaptive`	運動状態・方位・歩幅を確率状態として逐次推定
`SMOOTHING_MODE`	`causal`	各歩までの観測だけを使う因果推定
`PF_HEADING_DRIFT_RETENTION`	`0.85`	PFの通常方位ドリフトを次歩へ保持する割合
`PF_SIGMA_INIT_HEADING`	`0.03`	PFの初期方位ばらつき [rad]
`PF_SIGMA_HEADING`	`0.01`	PFの1歩ごとの方位ノイズ [rad]
`PF_SIGMA_STEP_LENGTH_RATIO`	`0.01`	永続倍率で説明できない1歩ごとの歩幅ノイズ
`PF_STRIDE_SCALE_PRIOR_MEAN`	`1.03`	正解軌跡長から校正したPF歩幅倍率の事前中心
`PF_STRIDE_SCALE_RETENTION`	`0.995`	学習した歩幅倍率偏差を次歩へ保持する割合
`PF_STRIDE_SCALE_MIN / MAX`	`0.90 / 1.15`	PFが保持する歩幅倍率の範囲
`PF_RESAMPLE_ESS_RATIO`	`0.5`	PFで再標本化を開始するESS比率
`PF_REJUVENATION_SIGMA_HEADING`	`0.009`	再標本化後に加える適応方位ノイズの上限 [rad]
`PF_RECOVERY_VALID_RATIO`	`0.05`	PFでmap-aware recoveryを開始する有効粒子率
`PF_MOTION_PREDICTIVE_WEIGHT_POWER`	`0.1`	運動状態予測尤度を弱くPF重みへ反映する指数
`PF_PATH_SELECTION`	`sequence`	持続反転が減る場合だけ単一祖先経路を採用

gyro_accel_motion では次を分けて扱います。

body_heading: ジャイロから推定した体/端末の向き
motion_heading: 水平加速度から推定した1歩ごとの移動方向特徴
movement_type: センサー上の判定結果
trajectory_movement_type: 軌跡計算に使った移動タイプ
forward_heading_source: forward 判定ステップの軌跡方位ソース

横歩き判定の見方

実行後、output/<timestamp>/step_headings.csv を確認します。

重要な列は次です。

列	意味
`movement_type`	センサー上の判定。`sidestep_left/right` なら横歩きとして検出済み
`trajectory_movement_type`	軌跡に反映した移動タイプ。`forward` なら検出は横歩きだが軌跡上は前進扱い
`body_heading_deg`	体/端末の向き
`motion_heading_deg`	水平加速度から見た移動方向
`selected_heading_deg`	実際に軌跡へ使った方位
`forward_heading_source`	`forward` 判定ステップの軌跡方位ソース
`lateral_forward_ratio`	横方向変位 / 前方向変位
`forward_displacement`	体方向への変位特徴
`lateral_displacement`	横方向への変位特徴
`motion_heading_correction_deg`	水平加速度方向の補正角
`decoded_motion_mode`	区間復号した `forward / sidestep_left / sidestep_right`
`device_body_offset_deg`	歩ごとに推定した端末−身体方位差
`body_heading_update_reason`	動的方位を更新したか、更新を止めた理由

標準設定の clustered では、同方向の横歩き evidence が連続する区間をクラスタとして評価します。条件を満たす1歩の隙間は最大1つまでクラスタに含め、横歩き evidence が 2歩以上かつクラスタ全体の横方向変位が閾値を満たす場合、確定横歩きとして軌跡へ反映します。

確定しなかった強い単発 evidence は、標準の --sidestep-suspect-mode forward では trajectory_movement_type="forward"として前進扱いにします。また、forward判定ステップはジャイロ由来のbody_headingで軌跡へ積みます。比較のため水平加速度由来のmotion_headingで積む場合は次を指定します。

uv run rikka run --forward-heading-source motion

正解軌跡との複数seed比較を実行する場合:

MPLBACKEND=Agg uv run python \
  agent/agent_evaluate_pf_ground_truth.py \
  --plot-path output/diagnostics/pf_ground_truth_comparison.png

運動状態・方位・歩幅を確率状態として逐次推定する標準モードは次のように実行する。 causal は各歩までの観測だけを使い、offline は記録全体を使って運動状態列を後向き平滑化する。標準設定は adaptive + causal である。

uv run rikka run
uv run rikka particle --pf-seed 42
uv run rikka particle --motion-estimation adaptive --smoothing offline --pf-seed 42
uv run rikka run --motion-estimation robust --smoothing causal

運動状態の予測尤度は、5記録・6 seed評価で最も安定した指数 0.1 を標準値として弱くPF重みへ反映する。中央値を優先する場合は offline、最悪seedのRMSEを優先する場合は causal が今回の評価では良かった。

uv run rikka particle --motion-estimation adaptive \
  --motion-predictive-weight-power 0.1 \
  --pf-path-selection sequence --pf-particles 500 --pf-seed 42

粒子数の既定値は rikka.common.config の PF_NUM_PARTICLES で設定します。実行単位で変更する場合はCLIの --pf-particles、Python APIの particle_count を使います。

robust は移動軸の180度方向曖昧性を区間で解決する実験方式である。5反復計測では一部データを改善した一方で中央値を悪化させたため、既定や推奨へは昇格していない。 sequence は反転が実際に減る場合だけ単一粒子の完全な祖先経路を使い、それ以外は到達可能な平均経路へ戻る標準設定である。

単一計測では、方位ドリフト後に地図上の対称な分岐へ到達すると、壁交差がなくても逆側の廊下へ収束し、単一PFだけでは一意に直せない場合がある。複数計測の代表軌跡を作るときは、終端15%の方向を計測・PDR/PF方式ごとに等重みで比較し、多数方向から90度を超えて外れる候補を除外してからmedoidを選ぶ。正解軌跡はこの選択には使用せず、選択後の評価だけに使う。

評価CSV/JSONでは次も確認する。

terminal_direction_error_deg: 正解終端区間との方位差
terminal_progress_cosine: 正解終端方向への投影。負なら逆向き
terminal_opposed_fraction: 終端15%で対応接線が90度以上逆向きの割合
terminal_direction_failure: projectionが負、または逆向き割合が0.5以上

通常PDRの方式比較は、同じ正解ルートに対応するデータをまとめて指定できる。

MPLBACKEND=Agg uv run python agent/agent_evaluate_adaptive_pdr.py \
  --data-dir \
  input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep \
  input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep5 \
  input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep6 \
  input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep7 \
  input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep8

横歩き判定を軌跡へそのまま反映して比較したい場合:

uv run rikka run --sidestep-smoothing none

旧方式の単発横歩き抑制と比較したい場合:

uv run rikka run --sidestep-smoothing isolated

横歩き判定を増やす/減らす場合:

# 拾いやすくする
uv run rikka run --sidestep-lateral-ratio 1.0

# 厳しくする
uv run rikka run --sidestep-lateral-ratio 1.5

ジャイロバイアス比較

定速の端末回転を静止中のbiasと誤認すると、全区間へ誤った補正が入り軌跡が曲がり続けます。そのため標準の prewalk_guarded は、推定値が±0.003 rad/s以内の場合だけ採用し、それを超える場合は0へ戻します。記録前後に確実な静止区間を用意できる場合は prewalk_robust、補正しない比較には zero、既知の校正値がある場合は manual も使用できます。

uv run rikka run \
  -d input/sensor_data/natsuki/1turn_rightsidestep_3turn_leftsidestep2 \
  --gyro-bias-method manual \
  --gyro-bias 0.002

主な出力

通常 PDR は output/<timestamp>/ に保存します。

ファイル	内容
`trajectory.csv`	移動後座標。列は `timestamp_s,x,y`
`trajectory.png`	フロアマップ上の軌跡
`step_lengths.csv`	ステップごとの歩幅
`step_length_observations.csv`	1歩区間の歩幅候補、周期、振幅、品質、不確かさ
`motion_posteriors.csv`	adaptive時の運動状態確率、方位・歩幅・端末姿勢ずれの事後分布
`direction_posteriors.csv`	robust時の移動軸2方向の確率、採用方位、反転根拠
`step_lengths.png`	歩幅グラフ
`step_vectors.csv`	ステップごとの変位ベクトル
`step_vectors/step_*.png`	各ステップの変位と加速度分布
`step_headings.csv`	方位候補、横歩き判定、軌跡反映タイプ
`gyro_bias.csv`	ジャイロバイアス推定の診断情報
`step_segments.csv`	`paper_vertical_threshold` 使用時のステップ区間

パーティクルフィルタでは追加で次を保存します。

ファイル	内容
`pf_trajectory.png`	PF の平均優先、または反転抑制された単一祖先軌跡
`particle_diagnostics.csv`	各歩のESS、有効粒子数、位置・方位分散、歩幅倍率、recovery、軌跡選択モード
`particle_filter.mp4` / `.gif`	パーティクル分布アニメーション
`particle_frames/step_*.png`	明示保存時の開始・提案・壁判定・重み・選択/復旧・確定と方位ローズ
`particle_paths_comparison.png`	明示保存時の加重平均・単一祖先・個別粒子経路と方位変化の比較

コード構成

公開エントリポイントと CLI をアダプターとして、実装は common / pdr / particle / plot の4領域に分割されています。

ファイル	役割
`__init__.py`	`main()` と公開APIのエントリポイント
`cli/options.py`	ClickコマンドとCLIオプションの定義
`cli/commands.py`	入力読込、設定構築、PDR・PF・出力pipelineの接続
`common/config/`, `common/settings.py`	定数と検証済み設定
`common/lib/models.py`	`PreparedPdrSteps`、`TrajectoryResult` などの共有型
`pdr/pipeline.py`	センサー入力から通常PDR結果までの手順
`pdr/lib/`	歩検出、歩幅、方位、運動状態、積分、fusion
`particle/pipeline.py`	準備済み歩列へ地図拘束を適用する手順
`particle/lib/`	提案、地図拘束、重み、再標本化、復旧、経路、記録
`plot/pipeline.py`	CSV・図・animationの出力手順
`plot/lib/`	フロアマップ座標変換と個別成果物

particle.pipeline.run_particle() は prepare_pdr_steps_with_settings() が作った PreparedPdrSteps を境界として受け取り、フロアマップ制約で軌跡を補正します。低水準のPF段階実行は particle.lib.runner.run_particle_steps() が担当します。

関数単位の読み順、設定、入出力、通常PDRとPFの分岐は、コードリード資料にまとめています。

Python から使う

import pandas as pd
from rikka.cli.commands import run

df_acc = pd.DataFrame(...)   # 列: t, x, y, z
df_gyro = pd.DataFrame(...)  # 列: t, x, y, z

trajectory_df = run(df_acc=df_acc, df_gyro=df_gyro)

df_acc と df_gyro は両方渡すか、両方省略してください。片方だけ渡すと ValueError になります。戻り値は timestamp_s, x, y 列を持つ pandas.DataFrame です。APIから呼んだ場合も output/<timestamp>/ を作成し、 CSVと、設定に応じた画像・アニメーションを保存します。

区間復号・動的身体方位と従来clusterをAPIで比較する場合は、 prepare_pdr_steps(..., motion_refinement=False) で従来処理を実行できます。

グラフを表示しない場合:

trajectory_df = run(df_acc=df_acc, df_gyro=df_gyro, plot=False)

パーティクルフィルタを使う場合:

trajectory_df = run(
    df_acc=df_acc,
    df_gyro=df_gyro,
    use_particle_filter=True,
    particle_count=500,
    save_step_frames=True,
    step_frames_range=(70, 85),
    save_path_comparison=True,
)

開発コマンド

uv run ruff format
uv run ruff check
uv run mypy src/
uv run pytest
uv build

CI と同等の pre-commit チェック:

uv run pre-commit run --all-files

リポジトリ管理の Git hook を使う場合:

git config core.hooksPath .githooks

接続確認

from rikka import ping

print(ping())  # Hello, rikka

Name		Name	Last commit message	Last commit date
.githooks		.githooks
.github		.github
.vscode		.vscode
docs		docs
src/rikka		src/rikka
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
AGENTS.md		AGENTS.md
README.md		README.md
mise.toml		mise.toml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

rikka

セットアップ

入力データ

基本コマンド

BLE ランドマーク補正

データフロー

標準設定

横歩き判定の見方

ジャイロバイアス比較

主な出力

コード構成

Python から使う

開発コマンド

接続確認

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

rikka

セットアップ

入力データ

基本コマンド

BLE ランドマーク補正

データフロー

標準設定

横歩き判定の見方

ジャイロバイアス比較

主な出力

コード構成

Python から使う

開発コマンド

接続確認

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages