JSBSim XML Generator for RC UAV

RC機体からJSBSim用XMLファイルを自動生成するツールです。2つの入力方式をサポート:

Excel→JSBSim変換: Excelテンプレートで機体パラメータを入力
FMS→JSBSim変換: Flying Model Simulator (.par) ファイルから変換

特徴

共通機能

✅ 自動単位変換: mm/g/degree → m/kg/rad等、JSBSim標準単位系へ自動変換
✅ 典型的な空力係数: 小型固定翼機の標準的な値をデフォルト提供
✅ 動的安定性対応: Cmq, CLq, CLadot等をサポート
✅ JSBSim統合検証済み: トリム収束・10秒間安定飛行を確認

Excel変換 (推奨: 新規機体作成時)

✅ 直感的な入力: Excelテンプレートで機体パラメータを入力
✅ ガイド付き: 各セルに入力ガイドと典型値を記載

FMS変換 (Legacy: 既存FMSデータ移植時)

✅ FMS .parファイル対応: Flying Model Simulator形式の機体データを変換
✅ 3段階パイプライン: パース → 微係数計算 → XML生成
✅ Evidence Level記録: データ信頼性レベルを自動記録 (L1/L2/L3/L6)

⚠️ 重要: デフォルト値について

サンプル機体のデフォルト値は参考値です:

Evidence Level: L2 (理論値/文献値)
情報源: 航空工学文献・小型固定翼機の典型値
⚠️ 飛行試験未実施: デフォルト値は飛行試験による検証を受けていません

ユーザーは必ず:

自分の機体パラメータに置き換えてください
飛行試験でパラメータ調整を行ってください
パラメータ調整にはPARAMETER_TUNING_GUIDE.mdを参照してください

クイックスタート

必要な環境

Python 3.8以上
JSBSim 1.1.0以上
FlightGear（オプション、可視化に使用）

インストール

# リポジトリをクローン
git clone https://github.com/[username]/jsbsim-xml-generator.git
cd jsbsim-xml-generator

# 依存パッケージをインストール
pip install -r requirements.txt

# 環境設定（初回のみ）
python setup.py

setup.pyの機能:

✅ 自動環境検出（OS, Python, FlightGear）
✅ 設定ファイル生成（config.yaml）
✅ 必要ディレクトリ作成（output/, logs/ 等）

詳細は config/README.md を参照してください。

使用方法

このツールは2つの入力方式をサポートしています。用途に応じて選択してください。

方式1: Excel→JSBSim変換 (推奨: 新規機体作成時)

1. テンプレートをコピー

cp templates/Aircraft_Input_Template.xlsx my_aircraft.xlsx

2. 機体パラメータを入力

Excelでファイルを開き、以下のシートに機体パラメータを記入:

T_01_Basic_Info: 機体名、質量、翼面積、翼幅
T_02_Mass_Balance: 重心位置、慣性モーメント
T_03_Propulsion: モーター、プロペラ、バッテリー
T_04_Control: 操縦面（エルロン、エレベーター、ラダー）

3. JSBSim XMLを生成

python src/excel_to_jsbsim/generate_jsbsim_from_gsheet.py --input my_aircraft.xlsx --output aircraft/MyAircraft/

4. JSBSimで動作確認

import jsbsim

fdm = jsbsim.FGFDMExec('.')
fdm.load_model('MyAircraft')
fdm.run_ic()

print("Aircraft loaded successfully!")

方式2: FMS→JSBSim変換 (Legacy: 既存FMSデータ移植時)

Flying Model Simulator (.par) 形式の機体データがある場合はこの方式を使用します。

1. FMS .parファイルを準備

# 既存の.parファイルを examples/ディレクトリに配置
# または任意のパスを指定

2. 変換を実行

python src/fms_to_jsbsim/run_full_pipeline.py examples/my_aircraft.par output/MyAircraft_FMS

出力ファイル:

output/MyAircraft_FMS/MyAircraft_FMS.xml - JSBSim XML
output/MyAircraft_FMS/parsed_data.json - パース済みデータ
output/MyAircraft_FMS/derived_parameters.json - 計算済み微係数
output/MyAircraft_FMS/*.txt - 変換レポート

3. JSBSim用にコピー

mkdir -p aircraft/MyAircraft_FMS
cp output/MyAircraft_FMS/MyAircraft_FMS.xml aircraft/MyAircraft_FMS/

4. JSBSimで動作確認

python tests/test_jsbsim_load.py MyAircraft_FMS

サンプル機体

Excel変換サンプル

examples/ExampleAircraft_Excel/ に200g級RC UAVのサンプルがあります:

python tests/test_jsbsim_load.py ExampleAircraft_Excel

詳細はexamples/README.mdを参照してください。

テスト

このプロジェクトには10種類のテストスクリプトが含まれています:

基本テスト

test_jsbsim_load.py: JSBSim XML読み込みテスト（両方式対応）
test_unit_conversion.py: 単位変換正確性テスト（27テストケース）

Excel変換テスト (8 tests)

test_xml_generation.py: Excel → XML生成テスト
test_e2e_flight.py: E2Eフライトテスト (Excel → XML → Flight)
test_e2e.py: レガシーE2Eテスト
test_trim_manual.py: 手動トリム探索（External Reactions対応）
test_trim_stability.py: トリム・安定性テスト（Traditional Engine用）
test_trim_diagnostic.py: トリム診断ツール

Test Coverage: 100% (8/8 critical tests implemented)

詳細はtests/README.mdを参照してください。

ドキュメント

ユーザー向け

技術ドキュメント

技術ドキュメント

プロジェクト構成

jsbsim-xml-generator/
├── README.md                    ← 本ファイル
├── LICENSE                      ← ライセンス
├── requirements.txt             ← 依存パッケージ（2つの入力方式対応）
├── setup.py                     ← 環境セットアップスクリプト（初回実行）
├── config.yaml                  ← ユーザー環境設定（自動生成）
├── config/                      ← 設定管理
│   ├── config.default.yaml      ← デフォルト設定テンプレート
│   ├── README.md                ← 設定ガイド
│   ├── examples/                ← プラットフォーム別設定例
│   ├── excel_to_jsbsim/         ← Excel変換設定（空）
│   └── fms_to_jsbsim/           ← FMS変換設定
│       └── aerodynamic_assumptions.yaml  ← 空力係数推定設定
├── src/                         ← Pythonスクリプト
│   ├── excel_to_jsbsim/         ← Excel→JSBSim変換
│   │   ├── generate_jsbsim_from_gsheet.py  ← メイン生成スクリプト
│   │   ├── config_manager.py    ← 設定管理モジュール
│   │   ├── unit_conversion.py   ← 単位変換モジュール
│   │   └── set_default_values.py ← デフォルト値設定
│   └── fms_to_jsbsim/           ← FMS→JSBSim変換
│       ├── run_full_pipeline.py ← フルパイプライン実行
│       ├── parse_par_file.py    ← .parファイルパーサー
│       ├── calculate_derivatives.py  ← 空力微係数計算
│       ├── generate_xml.py      ← XML生成
│       └── jsbsim_trim_wrapper.py   ← トリム計算支援
├── templates/                   ← 入力テンプレート
│   └── Aircraft_Input_Template.xlsx  ← Excel入力テンプレート
├── examples/                    ← サンプル機体
│   └── ExampleAircraft_Excel/   ← Excel変換サンプル（200g級RC UAV）
├── aircraft/                    ← 生成されたJSBSim XMLファイル
├── output/                      ← FMS変換出力（中間ファイル含む）
├── engines/                     ← エンジンファイル（空）
├── tests/                       ← テストスクリプト
│   ├── test_jsbsim_load.py      ← 基本テスト（両方式共通）
│   ├── test_unit_conversion.py  ← 単位変換テスト
│   ├── excel_to_jsbsim/         ← Excel変換テスト（移行予定）
│   └── fms_to_jsbsim/           ← FMS変換テスト（サンプルなし、ユーザー提供 .par ファイルで使用可能）
└── docs/                        ← ドキュメント
    ├── user_guide/              ← ユーザーガイド
    ├── technical/               ← 技術ドキュメント
    └── development/             ← 開発者向け

動作確認環境

項目	バージョン
Python	3.8以上
JSBSim	1.1.0以上
openpyxl	3.0.0以上
pandas	1.3.0以上
numpy	1.21.0以上
scipy	1.7.0以上

ライセンス

このプロジェクトは二重ライセンス構造を採用しています：

📄 ドキュメント・記事コンテンツ

本README含むすべてのドキュメント（docs/, README.md等）は、日本の著作権法により保護されています。

❌ 商用利用禁止
❌ 無断転載禁止
❌ 改変禁止
ℹ️ 適切な引用のみ可能

💻 ソースコード・スクリプト

Licensed under CC BY-NC-SA 4.0

本プロジェクトのソースコード・スクリプト（src/, scripts/等）は、CC BY-NC-SA 4.0 ライセンスの下で提供されています。

✅ 非商用利用可能
✅ 改変可能（同一ライセンス継承必須）
✅ クレジット表示必須
❌ 商用利用禁止

詳細: https://creativecommons.org/licenses/by-nc-sa/4.0/

依存パッケージライセンス

パッケージ	ライセンス	互換性
openpyxl	MIT License	✅ Compatible
pandas	BSD 3-Clause License	✅ Compatible
numpy	BSD License	✅ Compatible
scipy	BSD License	✅ Compatible
JSBSim	LGPL 2.1+	✅ Compatible*

*JSBSim互換性注記: JSBSim（LGPL 2.1+）は外部ライブラリとして動的リンクで使用します。ユーザーは JSBSim を別途インストールし、LGPL条項に従う必要があります。

外部データソース

このプロジェクトは以下の外部データを参照しています:

JSBSim公式ドキュメント (LGPL 2.1+)
- 使用形態: XMLフォーマット仕様の参照
航空工学文献: 公開ドメインの空力係数理論値
- 使用形態: 典型的な小型固定翼機の値を参考

詳細はLICENSEおよびPROJECT_RULES.mdを参照してください。

トラブルシューティング

JSBSimがモデルを読み込めない

症状: Could not open file: MyAircraft.xml

解決策:

カレントディレクトリがaircraft/の親ディレクトリにあるか確認
aircraft/MyAircraft/MyAircraft.xmlが存在するか確認

トリムが収束しない（Manual Trim Search使用時）

症状: test_trim_manual.pyでもwdot/qdotが目標値に収束しない

主要原因:

1. 空力係数の妥当性確認（最重要・Priority 1）

自動計算テンプレートの生成値が過度に強い安定性を持つ場合があります。

診断方法:

python tests/test_trim_diagnostic.py MyAircraft

典型的な問題:

CL0が高すぎる: 一般的な範囲 0.0-0.1（翼型による）
Cmalphaが強すぎる: 一般的な範囲 -0.3 to -0.8（縦安定性）
Cm_deが強すぎる: 一般的な範囲 -0.3 to -0.6（昇降舵効き）
CLalphaが高すぎる: 一般的な範囲 4.0-5.5（揚力傾斜）

対策: 航空工学の標準的な範囲と比較し、過度に大きな値がないか確認してください。特にCmalpha（縦安定微係数）が強すぎると、trim時にpitch momentが釣り合いません。

2. テスト時の推力設定（Priority 2）

問題: 初期値throttle 50-100%からテスト → 推力支援飛行モード

対策: テスト時に絞った値（10-30%）から開始

# test_trim_manual.py は自動的に10-50%の範囲でテスト
python tests/test_trim_manual.py MyAircraft 15

推力と揚力のバランス (JSBSimシミュレーション上):

推力/重量比が0.05-0.15程度で純粋な空力飛行モデルとして動作
T/W > 0.5の場合でも、テスト時に適切な推力範囲（10-30%）を使用することで正しいtrim pointを探索可能
注: 実機では風・乱流等の影響があるため、シミュレーション結果と実機の挙動は異なる場合があります

注: 高いT/W比（>0.5）自体は問題ではありません。重要なのはテスト時に適切な推力範囲を使用することです。

⚠️ JSBSim Built-in Trimが失敗する（External Reactions使用時）

症状: fdm.do_trim(2) が Trim Failed を返す

原因:

このテンプレートで生成されたXMLは External Reactions 方式を使用
JSBSim built-in trim (FGTrim) は External Reactions と互換性がありません

これは既知の制約であり、バグではありません。

解決策: Manual Trim Search（手動トリム探索）を使用

# tests/test_trim_manual.py を使用
python tests/test_trim_manual.py MyAircraft 15

# または scipy.optimize で手動実装
from scipy.optimize import fsolve

def trim_cost(x, fdm, target_speed):
    elevator, throttle = x
    fdm['fcs/elevator-cmd-norm'] = elevator
    fdm['fcs/throttle-cmd-norm'] = throttle
    fdm.run()

    wdot = fdm['accelerations/wdot-ft_sec2']
    qdot = fdm['accelerations/qdot-rad_sec2']

    return [wdot, qdot]

# トリム探索
result = fsolve(trim_cost, [0.0, 0.5], args=(fdm, 15.0))

背景:

JSBSim trim algorithmは traditional engine/propeller を想定
External Reactionsの推力モデルでtrim solverが混乱
6軸完全モデル実現のためExternal Reactions採用

詳細はexamples/README.mdのトラブルシューティングセクションを参照してください。

コントリビューション

プルリクエスト歓迎！Issue報告やプルリクエストはGitHubリポジトリまでお願いします。

謝辞

このプロジェクトは以下のツールを使用しています:

JSBSim: オープンソース飛行力学シミュレーター
FlightGear: オープンソースフライトシミュレーター（オプション）

参考資料

バージョン: 1.0 最終更新: 2025-10-20 入力方式: Excel→JSBSim + FMS→JSBSim 対応JSBSim: 1.1.0以上

本README及びドキュメントの著作権はYaaasohに帰属します。ソースコードはCC BY-NC-SA 4.0ライセンスの下で提供されています。詳細はLICENSEを参照してください。

Name		Name	Last commit message	Last commit date
aircraft		aircraft
config		config
docs		docs
engines		engines
examples		examples
scripts		scripts
src		src
templates		templates
tests		tests
.gitignore		.gitignore
AI_BEHAVIOR_FAILURE_ANALYSIS.md		AI_BEHAVIOR_FAILURE_ANALYSIS.md
COPYRIGHT_LESSONS.md		COPYRIGHT_LESSONS.md
INCIDENTS_UNIFIED.md		INCIDENTS_UNIFIED.md
INCIDENT_REPORT_20251005.md		INCIDENT_REPORT_20251005.md
LICENSE		LICENSE
PROJECT_GUIDELINES.md		PROJECT_GUIDELINES.md
PROJECT_RULES.md		PROJECT_RULES.md
README.md		README.md
README_FOR_CLAUDE.md		README_FOR_CLAUDE.md
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

JSBSim XML Generator for RC UAV

特徴

共通機能

Excel変換 (推奨: 新規機体作成時)

FMS変換 (Legacy: 既存FMSデータ移植時)

⚠️ 重要: デフォルト値について

クイックスタート

必要な環境

インストール

使用方法

方式1: Excel→JSBSim変換 (推奨: 新規機体作成時)

1. テンプレートをコピー

2. 機体パラメータを入力

3. JSBSim XMLを生成

4. JSBSimで動作確認

方式2: FMS→JSBSim変換 (Legacy: 既存FMSデータ移植時)

1. FMS .parファイルを準備

2. 変換を実行

3. JSBSim用にコピー

4. JSBSimで動作確認

サンプル機体

Excel変換サンプル

テスト

基本テスト

Excel変換テスト (8 tests)

ドキュメント

ユーザー向け

技術ドキュメント

プロジェクト構成

動作確認環境

ライセンス

📄 ドキュメント・記事コンテンツ

💻 ソースコード・スクリプト

依存パッケージライセンス

外部データソース

トラブルシューティング

JSBSimがモデルを読み込めない

トリムが収束しない（Manual Trim Search使用時）

1. 空力係数の妥当性確認（最重要・Priority 1）

2. テスト時の推力設定（Priority 2）

⚠️ JSBSim Built-in Trimが失敗する（External Reactions使用時）

コントリビューション

謝辞

参考資料

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages