はじめに#

JSBSimで機体の姿勢制御や座標変換を実装する際、最も重要なのが座標系の正確な理解です。しかし、JSBSimの公式ドキュメントは複数のサイト（SourceForge、GitHub Pages、公式サイト）に分散しており、どこから学習を始めればよいか分かりにくい状況があります。

本記事では、JSBSim座標系・回転系の理解に役立つ23件の公式・コミュニティドキュメントを体系的に紹介します。各リソースにEvidence Level（信頼性レベル）を明記し、学習の順序と活用方法を詳しく解説します。

JSBSim公式ドキュメントの全体像#

ドキュメントの分散状況#

JSBSim関連のドキュメントは、以下の3つの主要サイトに分散しています：

  1. GitHub Pages (https://jsbsim-team.github.io/jsbsim/)

    • 最新版のAPIドキュメント
    • Python APIドキュメント
    • Doxygenで自動生成されたクラスリファレンス

  2. SourceForge (https://jsbsim.sourceforge.net/)

    • 旧版のAPIドキュメント
    • 公式PDF文書（座標系仕様、リファレンスマニュアル等）
    • 歴史的なドキュメント

  3. GitHub リポジトリ (https://github.com/JSBSim-Team/jsbsim)

    • 最新のソースコード
    • Issue、Discussionsでの技術議論
    • Python バインディング定義ファイル

ドキュメントのバージョン管理#

重要: GitHub Pagesが最新版、SourceForgeは旧版の場合があります。特にPython APIドキュメントはGitHub Pages版を参照することを推奨します。

座標系関連の主要ドキュメント紹介#

最重要文書（必読）#

1. JSBSim Development Note: Coordinate Systems (PDF)#

内容: JSBSim座標系の詳細仕様書。以下の重要事項が記載されています：

  • JSBSimで使用される座標系の定義（Body Frame, NED Frame等）
  • 回転順序: 3-2-1 sequence (Z-Y-X, Yaw-Pitch-Roll)
  • Euler角とクォータニオンの変換方法
  • 座標変換行列の定義

推奨用途: 座標系学習の最初のステップとして全体像を把握。学習時間30-60分。

クラスAPIドキュメント（L1: 公式ドキュメント）#

2. FGQuaternion Class Reference (GitHub Pages)#

内容: FGQuaternionクラスの完全なAPI仕様。

  • コンストラクタ、メソッドの詳細
  • Euler角 → クォータニオン変換
  • クォータニオン演算（積、逆クォータニオン等）

推奨用途: FGQuaternionクラスを使用する際のリファレンス。

3. FGPropagate Class Reference (GitHub Pages)#

内容: FGPropagateクラスのAPI仕様。座標変換で最も重要なメソッド：

  • GetTb2l(): Body → NED (Local) 変換行列
  • GetTl2b(): NED (Local) → Body 変換行列
  • GetQuaternion(): 現在の機体姿勢をクォータニオンで取得

推奨用途: 座標変換実装時の必須リファレンス。

4. FGLocation Class Reference (GitHub Pages)#

内容: FGLocationクラスのAPI仕様。位置情報と座標変換：

  • 緯度・経度・高度の取得
  • ECEF座標系との変換
  • 位置ベクトルの座標系変換

ソースコードドキュメント（L1: 公式ソースコード）#

5. FGQuaternion.cpp Source (GitHub Pages)#

内容: FGQuaternion実装コード（最新版）。

推奨用途: APIドキュメントで不明な点がある場合、実装コードを直接確認。特にEuler角からクォータニオンへの変換ロジックの詳細理解に有用。

6. FGQuaternion.h Source#

内容: FGQuaternionヘッダーファイル。クラスの構造、メンバー変数、メソッド宣言の確認に有用。

7. FGPropagate.cpp Source#

内容: FGPropagate実装コード。座標変換行列の計算ロジックが記載されています。

Python APIドキュメント（L1: 公式Python API）#

8. JSBSim Flight Dynamics Model — JSBSim 1.2.3 documentation#

内容: Python APIのトップレベルドキュメント。Pythonから JSBSimを使用する際の最初のリファレンス。

9. FGPropagate — JSBSim 1.2.2 documentation (Python)#

内容: FGPropagate Python APIの詳細。

推奨使用例:

import jsbsim

fdm = jsbsim.FGFDMExec('.')
propagate = fdm.get_propagate()

# Body → NED 変換行列取得
Tb2l = propagate.get_Tb2l()

# クォータニオン取得
quaternion = propagate.get_quat()

10. JSBSim Python Bindings#

内容: Python バインディングの公式情報。インストール方法、基本的な使い方の解説。

11. jsbsim/python/jsbsim.pxd (GitHub)#

内容: Python Cython定義ファイル。Python APIで使用可能なクラス・メソッドの完全リストを確認できます。

12. JSBSim (PyPI)#

内容: PyPIパッケージ情報。インストール方法、バージョン履歴の確認に有用。

補足ドキュメント（L1: 公式）#

13. Quaternion (JSBSim Documentation)#

内容: クォータニオンに関する公式ドキュメント。数学的背景、Euler角との関係、JSBSimでの使用方法を解説。

14-16. SourceForge版APIドキュメント#

Evidence Level: L1（公式API documentation） ライセンス: LGPL-2.1

注意: 旧版の可能性があるため、GitHub Pages版を優先して参照してください。

17. GitHub - JSBSim-Team/jsbsim#

内容: JSBSim公式リポジトリ。最新のソースコード、Issue、Discussionsで技術議論を確認できます。

コミュニティリソース（L3-L4: コミュニティ）#

18. Aircraft rotations in an external program (GitHub Discussion #542)#

内容: 外部プログラムでJSBSimの回転データを使用する際の議論。実装例、トラブルシューティングが共有されています。

19. Euler Angles - Gimbal Lock - Quaternions (Mailing List)#

内容: Euler角とクォータニオンに関するメーリングリストの議論。Gimbal Lock問題の解説。

20. Python documentation? (GitHub Issue #199)#

内容: Python ドキュメンテーションに関する議論。Python APIの不明点を質問する際の参考になります。

21. FlightGear forum - Aircraft coordinate information#

内容: 座標情報に関するFlightGearコミュニティのディスカッション。FlightGear連携時の座標系トラブルシューティング事例。

サードパーティリソース（L3: サードパーティ）#

22. Takeoff tutorial - AeroSim#

内容: JSBSimを使用したシミュレーション例。離陸シミュレーションの実装チュートリアル。

23. Top 5 jsbsim Code Examples (Snyk)#

内容: Python使用例のコレクション。基本的な使い方、座標変換の実装例が含まれます。

学習の順序（推奨）#

JSBSim座標系を効率的に理解するための推奨学習順序を示します。

Step 1: 全体像の把握（学習時間: 30-60分）#

  1. JSBSimCoordinates.pdf (最重要文書) を読み、JSBSimで使用される座標系の定義を理解
  2. 3-2-1 sequence (Z-Y-X) の回転順序を確認

Step 2: APIリファレンスの理解（学習時間: 1-2時間）#

  1. FGQuaternion Class Reference でクォータニオンクラスのメソッドを確認
  2. FGPropagate Class Reference で座標変換メソッド（GetTb2l(), GetTl2b()）を確認
  3. FGLocation Class Reference で位置情報関連のメソッドを確認

Step 3: Python実装の習得（学習時間: 2-3時間）#

  1. JSBSim Flight Dynamics Model (Python) でPython APIの全体像を把握
  2. FGPropagate Python API で具体的な使用方法を学習
  3. PyPI からJSBSimをインストールし、サンプルコード（Snyk、AeroSim）を試す

Step 4: 詳細理解とトラブルシューティング（必要に応じて）#

  1. ソースコード（FGQuaternion.cpp、FGPropagate.cpp）で実装の詳細を確認
  2. GitHub Discussions, Issues でコミュニティの議論を参照
  3. メーリングリスト、フォーラム で過去のトラブルシューティング事例を確認

重要な発見#

回転順序: 3-2-1 Sequence (Z-Y-X)#

JSBSimは 3-2-1 sequence (Z-Y-X, Yaw-Pitch-Roll) を使用します。

これは、以下の順序で回転を適用することを意味します：

  1. Yaw (ψ): Z軸周りの回転（機首方位）
  2. Pitch (θ): Y軸周りの回転（機首上げ下げ）
  3. Roll (φ): X軸周りの回転（ロール）

注意: 他のシミュレータやライブラリ（例: scipy.rotation）と回転順序が異なる場合があるため、座標変換時は必ず確認してください。

座標変換API#

Body → NED変換:

propagate = fdm.get_propagate()
Tb2l = propagate.get_Tb2l()  # Body to Local (NED)

NED → Body変換:

Tl2b = propagate.get_Tl2b()  # Local (NED) to Body

Evidence Levelの重要性#

本記事で紹介した23件のドキュメントには、以下のEvidence Levelが付与されています：

  • L1（公式）: 17件（公式ドキュメント、ソースコード、Python API）
  • L3（コミュニティ）: 5件（GitHub Discussions、Issue、サードパーティ例）
  • L4（コミュニティフォーラム）: 1件（FlightGearフォーラム）

学習時の優先順位: L1 > L3 > L4

まとめ#

本記事では、JSBSim座標系・回転系の理解に役立つ23件の公式・コミュニティドキュメントを紹介しました。

学習のポイント#

  1. JSBSimCoordinates.pdf（最重要文書）から始め、全体像を把握
  2. FGPropagate Class Reference で座標変換メソッド（GetTb2l(), GetTl2b()）を理解
  3. Python API で実装し、実際に座標変換を試す
  4. 不明点はソースコード、GitHub Discussions で確認

次のステップ#

  • 座標系の数学的背景を学習したい場合: 航空宇宙座標系の業界標準（AIAA、Stevens & Lewis）を参照
  • Python実装を試したい場合: scipy.rotationと組み合わせた座標変換チュートリアルを参照

参照資料#

本記事の執筆にあたり、以下の資料を参照しました：

WebSearch実施記録#

  • 調査日: 2025-10-26
  • 調査元: phase7_flight_data_visualization/investigation_20251026_coordinate_transform_research/01_jsbsim_implementation/source.txt
  • WebSearch実施回数: 2回
  • 参照URL総数: 23件

公式ドキュメント（L1）#

  1. JSBSim Development Note: Coordinate Systems. https://jsbsim.sourceforge.net/JSBSimCoordinates.pdf. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  2. FGQuaternion Class Reference. https://jsbsim-team.github.io/jsbsim/classJSBSim_1_1FGQuaternion.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  3. FGPropagate Class Reference. https://jsbsim-team.github.io/jsbsim/classJSBSim_1_1FGPropagate.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  4. FGLocation Class Reference. https://jsbsim-team.github.io/jsbsim/classJSBSim_1_1FGLocation.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  5. FGQuaternion.cpp Source. https://jsbsim-team.github.io/jsbsim/FGQuaternion_8cpp_source.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  6. FGQuaternion.h Source. https://jsbsim-team.github.io/jsbsim/FGQuaternion_8h_source.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  7. FGPropagate.cpp Source. https://jsbsim-team.github.io/jsbsim/FGPropagate_8cpp_source.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  8. JSBSim Flight Dynamics Model — JSBSim 1.2.3 documentation. https://jsbsim-team.github.io/jsbsim/python/index.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  9. FGPropagate — JSBSim 1.2.2 documentation (Python). https://jsbsim-team.github.io/jsbsim/python/FGPropagate.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  10. JSBSim Python Bindings. https://jsbsim-python.sourceforge.net/. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  11. jsbsim/python/jsbsim.pxd (GitHub). https://github.com/JSBSim-Team/jsbsim/blob/master/python/jsbsim.pxd. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  12. JSBSim (PyPI). https://pypi.org/project/JSBSim/. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  13. Quaternion (JSBSim Documentation). https://jsbsim.sourceforge.net/quaternions.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  14. FGQuaternion.cpp Source (SourceForge). https://jsbsim.sourceforge.net/JSBSim/FGQuaternion_8cpp_source.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  15. FGPropagate Class Reference (SourceForge). https://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPropagate.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  16. FGLocation Class Reference (SourceForge). https://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGLocation.html. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.
  17. GitHub - JSBSim-Team/jsbsim. https://github.com/JSBSim-Team/jsbsim. アクセス日: 2025-10-26. ライセンス: LGPL-2.1. Evidence Level: L1.

コミュニティリソース（L3）#

  1. Aircraft rotations in an external program (GitHub Discussion #542). https://github.com/JSBSim-Team/jsbsim/discussions/542. アクセス日: 2025-10-26. Evidence Level: L3.
  2. Euler Angles - Gimbal Lock - Quaternions (Mailing List). https://sourceforge.net/p/jsbsim/mailman/message/7558493/. アクセス日: 2025-10-26. Evidence Level: L3.
  3. Python documentation? (GitHub Issue #199). https://github.com/JSBSim-Team/jsbsim/issues/199. アクセス日: 2025-10-26. Evidence Level: L3.

サードパーティリソース（L3-L4）#

  1. Takeoff tutorial - AeroSim. https://aerosim.readthedocs.io/en/latest/takeoff_tutorial/. アクセス日: 2025-10-26. Evidence Level: L3.
  2. Top 5 jsbsim Code Examples (Snyk). https://snyk.io/advisor/python/JSBSim/example. アクセス日: 2025-10-26. Evidence Level: L3.
  3. FlightGear forum - Aircraft coordinate information. https://forum.flightgear.org/viewtopic.php?f=46&t=36432. アクセス日: 2025-10-26. Evidence Level: L4.

関連記事#

  • 航空宇宙座標系の業界標準 - AIAA, Stevens & Lewis, NASAの資料紹介（記事B-4）
  • scipy.rotationで学ぶ機体姿勢変換 - 公式ドキュメント5件の活用法（記事D-2）

© 2025 Yaaasoh. All Rights Reserved.