JSBSimプロパティシステムの基礎：階層構造とパス表記を理解する

JSBSimやFlightGearを使用する際、「プロパティが見つからない」「値が取得できない」といったトラブルに遭遇することがあります。これらの多くはプロパティシステムの階層構造やパス表記の誤りが原因です。

本記事では、JSBSimのプロパティシステムの基礎を解説します。

この記事で学べること#

プロパティツリーとは何か
プロパティパスの表記法（スラッシュ区切り）
階層構造の理解
よく使うプロパティカテゴリ
プロパティの単位

対象読者#

JSBSimを初めて使う方
プロパティパス誤りでトラブルに遭遇した方
FlightGearとの連携でプロパティを使う方

プロパティシステムとは#

プロパティシステム（Property System）は、JSBSimが提供する階層構造のデータストアです。

基本概念#

プロパティツリー (Property Tree)
├─ position/
│  ├─ altitude-ft
│  ├─ lat-geod-deg
│  └─ long-gc-deg
├─ velocities/
│  ├─ u-fps
│  ├─ v-fps
│  └─ w-fps
└─ attitude/
   ├─ phi-rad
   ├─ theta-rad
   └─ psi-rad

すべてのシミュレーション状態量（位置、速度、姿勢等）は、階層構造で管理されています。

プロパティの役割#

FDM（Flight Dynamics Model）の状態を公開
外部プログラム（FlightGear、Python等）とのデータ交換
ログ出力・デバッグ

プロパティパスの表記法#

プロパティはパス（Path）で指定します。

基本ルール#

スラッシュ（/）で階層を区切る

position/altitude-ft
velocities/u-fps
attitude/phi-rad

大文字小文字を区別する
- position/altitude-ft ✅ 正しい
- Position/Altitude-Ft ❌ 間違い（大文字小文字が異なる）
ハイフン（-）とスラッシュ（/）を混同しない
- altitude-ft ✅ 正しい（ハイフンは単語の区切り）
- altitude/ft ❌ 間違い（スラッシュは階層の区切り）

よくある間違い#

誤ったパス	正しいパス	問題
`altitude-ft`	`position/altitude-ft`	階層が欠けている
`position/Altitude-Ft`	`position/altitude-ft`	大文字小文字が違う
`position\altitude-ft`	`position/altitude-ft`	バックスラッシュ（Windows形式）

主要なプロパティカテゴリ#

JSBSimのプロパティは、以下のカテゴリに分類されます。

1. position/ - 位置情報#

プロパティ	説明	単位
`position/altitude-ft`	高度（海面上）	ft
`position/lat-geod-deg`	緯度（測地系）	deg
`position/long-gc-deg`	経度（地心系）	deg
`position/h-agl-ft`	対地高度	ft

使用例: 高度確認、位置ログ出力

2. velocities/ - 速度情報#

プロパティ	説明	単位
`velocities/u-fps`	機体X軸方向速度（前方）	ft/s
`velocities/v-fps`	機体Y軸方向速度（右方）	ft/s
`velocities/w-fps`	機体Z軸方向速度（下方）	ft/s
`velocities/v-north-fps`	北方向速度（NED系）	ft/s
`velocities/v-east-fps`	東方向速度（NED系）	ft/s
`velocities/v-down-fps`	下方向速度（NED系）	ft/s

使用例: 速度モニタリング、運動解析

3. attitude/ - 姿勢情報#

プロパティ	説明	単位
`attitude/phi-rad`	ロール角	rad
`attitude/theta-rad`	ピッチ角	rad
`attitude/psi-rad`	ヨー角	rad
`attitude/roll-rad`	ロール角（エイリアス）	rad
`attitude/pitch-rad`	ピッチ角（エイリアス）	rad
`attitude/heading-true-rad`	真方位	rad

使用例: 姿勢制御、オートパイロット

4. forces/ - 力情報#

プロパティ	説明	単位
`forces/fbx-lbs`	機体X軸方向の力	lbs
`forces/fby-lbs`	機体Y軸方向の力	lbs
`forces/fbz-lbs`	機体Z軸方向の力	lbs

5. moments/ - モーメント情報#

プロパティ	説明	単位
`moments/l-lbsft`	ロールモーメント	lbs·ft
`moments/m-lbsft`	ピッチモーメント	lbs·ft
`moments/n-lbsft`	ヨーモーメント	lbs·ft

単位系の理解#

JSBSimは**英国単位系（Imperial Units）**を使用します。

主要単位#

物理量	JSBSim単位	SI単位への変換
長さ	ft（フィート）	1 ft = 0.3048 m
速度	fps（フィート毎秒）	1 fps = 0.3048 m/s
角度	rad（ラジアン）, deg（度）	1 rad = 57.2958 deg
力	lbs（ポンド）	1 lbs = 4.44822 N
モーメント	lbs·ft	1 lbs·ft = 1.35582 N·m

単位変換の注意点#

FlightGearとの連携: FlightGearも英国単位系を使用（そのまま渡せる）
Python等での解析: SI単位系に変換が必要
プロパティ名に単位が含まれる: altitude-ft（単位: ft）、v-north-fps（単位: fps）

プロパティアクセスの実例#

Pythonからのアクセス例#

import jsbsim

# JSBSimインスタンス作成
fdm = jsbsim.FGFDMExec('.')
fdm.load_model('Rascal')

# 初期条件設定
fdm['ic/h-sl-ft'] = 1000.0  # 高度1000ft
fdm['ic/vc-kts'] = 40.0     # 速度40kt

# 初期化
fdm.run_ic()

# プロパティ取得
altitude = fdm['position/altitude-ft']
u_velocity = fdm['velocities/u-fps']
roll_angle = fdm['attitude/phi-rad']

print(f"高度: {altitude} ft")
print(f"前方速度: {u_velocity} fps")
print(f"ロール角: {roll_angle} rad")

よくあるエラー#

# ❌ 間違い: 階層が欠けている
altitude = fdm['altitude-ft']  # KeyError

# ✅ 正しい: 完全パス
altitude = fdm['position/altitude-ft']

プロパティパスの探し方#

プロパティパスがわからない場合の調べ方：

1. JSBSim Reference Manualを参照#

公式ドキュメント[@jsbsim_refman_2024]の"Property Catalog"セクションにすべてのプロパティが記載されています。

2. ソースコード検索#

JSBSimのソースコード[@jsbsim_github_main_2025]から、該当する物理量のプロパティ定義を確認できます。

例: FGPropagate.cpp（位置・速度）、FGAuxiliary.cpp（補助情報）

3. JSBSim XML Generator#

自作ツール[@xmlgen_github_main_2025]のソースコードにも、よく使うプロパティパスが記載されています。

まとめ#

プロパティシステムは階層構造のデータストア
パス表記はスラッシュ（/）区切り、大文字小文字を区別
主要カテゴリ：position/, velocities/, attitude/, forces/, moments/
単位系は英国単位系（ft, fps, rad, lbs等）
プロパティパスがわからない場合は公式ドキュメントを参照

次のステップ:

B-9: JSBSim座標系の種類と使い分けでNED系・Body系等の座標系を理解
B-3: JSBSim座標系リソースガイドで公式ドキュメントを参照

参照資料#

本記事の執筆にあたり、以下の資料を参照しました [@jsbsim_refman_2024; @jsbsim_github_main_2025; @xmlgen_github_main_2025]。