angle_analysis

角度データの生成・可視化・解析を行うためのライブラリ。

要件

角度解析ツールを作成するプロジェクト。次の3つを実装する。

1. Generator (角度データ生成)
2. plotツール (時系列マルチプロット)
3. 角度解析 (角度から角速度・回転数・角加速度を算出)

1. angle generator

• 任意のサンプリング間隔で連続の角度データを作成するスクリプトの作成
• 角度は -180 ~ 180 で作成する
• 角速度はランダムだが、停止期間や (-20 ~ 20 rpm) の範囲で動作するなど、オプション設定できる関数
• サンプリングはある一定の確率で誤差を入れる (正規分布に合わせるなど、平均・偏差を指定できる)
• 例えば3日の稼働を模擬したいので、4時間はデータがない (NaN) 区間を作る

→ 実装: generator.angle_generator (generate_angle_series)

2. plotツール

• 同時に time plot ツールを作る
• 入力は df でマルチプロットに対応させる
• 想定シグネチャ:

def timeplot(
    df: pd.DataFrame,
    xplot,      # dfのx軸を示すカラム名
    yplot={...},
    plot_type,  # pyplotかplotlyを選ぶ。選択式。
):

→ 実装: plot_lib.timeplot (timeplot)

3. 角度解析

• 角速度 [deg/s]、回転数 [rpm]、角加速度 [deg/s^2] を角度データから求める

→ 実装: kinematick.kinematics (differentiate_angle)

構成

src/ 以下を ライブラリ として扱う (パッケージインストールして import して使う想定)。

src/
  generator/     # 1. 角度データ生成 (実装済み)
    angle_generator.py
  plot_lib/      # 2. 時系列マルチプロット (実装済み)
    timeplot.py
  kinematick/    # 3. 角度解析 (角速度[deg/s]・回転数[rpm]・角加速度[deg/s^2]) (実装済み)
    kinematics.py
  pandas_lib/    # 共通の DataFrame ユーティリティ置き場 — 未実装
sample/
  demo_pipeline.py    # generator + plot_lib を組み合わせた使用例
  demo_kinematics.py  # generator + kinematick + plot_lib を組み合わせた使用例
docs/
  generator.md       # angle_generator の詳細ドキュメント
  plot_lib.md         # timeplot の詳細ドキュメント
  kinematics.md       # kinematics の詳細ドキュメント

各モジュールは if __name__ == "__main__": に簡易サンプル (動作確認テストを兼ねる) を持つ。

セットアップ (uv)

Python 環境は uv で管理する。

uv sync

pyproject.toml は src/generator, src/plot_lib, src/kinematick を editable なライブラリパッケージとして公開する設定になっている (uv sync で angle-analysis パッケージとして .venv にインストールされる)。

クイックスタート

# 各モジュール単体のサンプル実行 (main() のサンプルを兼ねた動作確認)
uv run python src/generator/angle_generator.py
uv run python src/plot_lib/timeplot.py
uv run python src/kinematick/kinematics.py

# generator + plot_lib を組み合わせた例
uv run python sample/demo_pipeline.py

# generator + kinematick + plot_lib (角度解析パイプライン全体) を組み合わせた例
uv run python sample/demo_kinematics.py

ライブラリとしての利用例:

from generator.angle_generator import generate_angle_series
from plot_lib.timeplot import timeplot
from kinematick.kinematics import differentiate_angle

df = generate_angle_series(duration="3D", sample_interval="1s")
kin = differentiate_angle(df, smoothing_window="5s")

fig = timeplot(df, xplot="time", yplot=["angle_deg"], plot_type="pyplot")
fig.savefig("angle.png")

モジュール

#	モジュール	説明	ドキュメント
1	generator.angle_generator	連続回転を模擬した角度時系列データの生成 (停止期間・rpm範囲・誤差注入・欠測区間に対応)。角加速度が正弦波の厳密解データを作る generate_sine_accel_angle_series (module 3 の検証用) も含む	docs/generator.md
2	plot_lib.timeplot	pandas.DataFrame から matplotlib / plotly でマルチプロット (複数段・重ね書き) を作成	docs/plot_lib.md
3	kinematick.kinematics	角度データから角速度[deg/s]・角加速度[deg/s^2]・回転数[rpm]を算出 (unwrap・外れ値除去・Savitzky-Golay平滑微分でロバストに計算)	docs/kinematics.md

開発メモ

• 日本語ラベルの文字化け対策として、plot_lib.timeplot は Windows/一般的な環境にある日本語フォント (Yu Gothic, Meiryo, MS Gothic, Noto Sans JP 等) を自動検出して matplotlib に設定する。見つからない環境ではデフォルトフォントのまま (英数字表示は問題なし)。
• 角度は常に [-180, 180) deg にラップして扱う (generator.angle_generator.wrap_angle_deg)。