rikka

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

---

セットアップ

uv sync --all-groups

MP4 アニメーション出力（uv run rikka particle）には ffmpeg が必要です。

brew install ffmpeg

---

使い方

入力データの配置

input/<データフォルダ>/ に以下の2ファイルを置きます（phyphox 形式の CSV）。

input/
└── my_walk/
    ├── Accelerometer.csv
    └── Gyroscope.csv

各 CSV の列構成は次のとおりです（phyphox アプリの出力形式）。

ファイル	列
Accelerometer.csv	Time (s), Acceleration x (m/s^2), Acceleration y (m/s^2), Acceleration z (m/s^2)
Gyroscope.csv	Time (s), Gyroscope x (rad/s), Gyroscope y (rad/s), Gyroscope z (rad/s)

列名が X (m/s^2) / X (rad/s) 形式の場合も自動で対応します。

src/rikka/config.py の DATA_DIR を対象フォルダに変更します。

DATA_DIR = "input/my_walk"

---

実行コマンド

通常の PDR 軌跡推定

uv run rikka run [OPTIONS]

# 例: フロアマップと起点を変更して実行
uv run rikka run -f input/map.png --origin-px 1000 500 --no-plot

# 例: 身長 1.78m として Weinberg 歩幅係数を補正して実行
uv run rikka run --height-m 1.78 --no-plot

• 軌跡グラフ（trajectory.png）と歩幅グラフ（step_lengths.png）、CSV を output/<timestamp>/ に保存します。

PDR 軌跡推定（run の別名）

uv run rikka pdr [OPTIONS]

• run と同じ処理・オプションです。

パーティクルフィルタ付き軌跡推定

uv run rikka particle

# グラフ表示とアニメーション保存を無効化して実行
uv run rikka particle --no-plot

# グラフ表示なしでアニメーションだけ保存
uv run rikka particle --no-plot --save-animation

• マップマッチングでパーティクルを通路内に収束させながら軌跡を推定します。
• pf_trajectory.png・step_lengths.png・particle_filter.mp4（または .gif）を出力します。
• --no-plot を指定するとグラフ表示とアニメーション保存を行いません。
• MP4 出力には ffmpeg が必要です（brew install ffmpeg）。

センサーデータの可視化

uv run rikka sensor

• 生加速度・線形加速度ノルム・ジャイロ・積算角度を4段グラフにして input/<データフォルダ>/sensor_plot.png に保存します。

簡易接続確認

引数なしで呼び出し、"Hello, rikka" が返れば接続・インポートが正常に動作しています。

from rikka import ping

print(ping())  # → Hello, rikka

---

歩幅グラフ（step_lengths.png）

uv run rikka / uv run rikka particle 実行時に自動生成されます。

• 折れ線グラフ：各ステップの歩幅 [m]
• 赤い水平線：平均値
• 赤い半透明帯：±1σ 範囲（σ = 標準偏差。帯の幅が狭いほど歩幅が安定していることを示す）
• 右上テキスト・コンソール出力：mean / std / n

---

Python から直接使う

CSV 以外のソース（リアルタイム取得・前処理済みデータなど）から DataFrame を用意して渡すこともできます。

import pandas as pd
from rikka.analyze.pdr import run

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

# 通常の PDR
trajectory = run(df_acc=df_acc, df_gyro=df_gyro)

# パーティクルフィルタ
trajectory = run(df_acc=df_acc, df_gyro=df_gyro, use_particle_filter=True)

# グラフ非表示（バッチ処理向け）
trajectory = run(df_acc=df_acc, df_gyro=df_gyro, plot=False)

# グラフ非表示でパーティクルフィルタのアニメーションだけ保存
trajectory = run(
    df_acc=df_acc,
    df_gyro=df_gyro,
    plot=False,
    use_particle_filter=True,
    save_animation=True,
)

# フロアマップを外部から指定
trajectory = run(
    df_acc=df_acc,
    df_gyro=df_gyro,
    floormap_path="path/to/floormap.png",
    origin_px=(1000, 500),
    scale=0.01,
    initial_direction=90.0,
)

df_acc と df_gyro は両方渡すか、両方省略（CSV から自動読み込み）してください。片方だけ渡すと ValueError になります。

---

主な設定項目（src/rikka/config.py）

設定名	説明	既定値
DATA_DIR	入力データフォルダのパス	"input/..."
FLOORMAP_PATH	フロアマップ画像のパス	"input/Floormap_building14_5floor.png"
FLOORMAP_ORIGIN_PX	軌跡起点のピクセル座標 (x, y)	(2050, 400)
FLOORMAP_SCALE	1ピクセルあたりのメートル数	0.01（1px = 1cm）
INITIAL_DIRECTION	歩行開始方向のオフセット [度]	90.0
STEP_LENGTH_METHOD	歩幅推定手法 "weinberg" or "forward"	"weinberg"
USER_HEIGHT_M	Weinberg モデルの身長補正に使うユーザー身長 [m]	1.65
WEINBERG_REFERENCE_HEIGHT_M	WEINBERG_REFERENCE_K を校正した基準身長 [m]	1.70
WEINBERG_REFERENCE_K	基準身長での Weinberg モデルのスケール係数	0.47
WEINBERG_K	身長補正後の Weinberg モデルのスケール係数	compute_weinberg_k(USER_HEIGHT_M)
PF_NUM_PARTICLES	パーティクル数	500
PF_SIGMA_INIT_HEADING	初期方向ばらつき [rad]	0.15
PF_SIGMA_HEADING	ステップごとの方位角ドリフト [rad]	0.05
PF_SIGMA_STEP_LENGTH_RATIO	ステップ長ノイズ比率	0.08

---

開発コマンド

フォーマット

uv run ruff format

リント

uv run ruff check
# 自動修正
uv run ruff check --fix

型チェック

uv run mypy src/

テスト

uv run pytest

---

コミット前の設定

git commit 時に自動フォーマットを反映したい場合、最初に hook を有効化します。

git config core.hooksPath .githooks

---

CI が落ちたら

uv run pre-commit run --all-files

自動修正された変更を push するだけで解決するケースがほとんどです。