matlab-import-tracking-data

データインポートの追跡

Sensor Fusion and Tracking Toolbox で使用するため、未加工データを MATLAB にインポートします。正解軌跡とセンサー検出データを処理します。プレーンな MATLAB コードを生成します。

使用する場合

• ユーザーが記録した軌跡／位置データを持っており、再生、フィルターの調整、またはトラッカーの評価を行いたい場合
• ユーザーがセンサー計測値（レーダー、IR、ライダー、カメラ、ソナー）を持っており、トラッカーに入力したい場合
• ユーザーが飛行ログ、GPS ログ、ADS-B、AIS、レーダー記録、ライダー点群、カメラ検出について言及した場合
• ユーザーが trackingDataImporter、objectDetection、trackerSensorSpec、dataFormat、またはトラッカー用のデータインポートについて質問した場合

使用しない場合

• ユーザーがゼロから合成シナリオを生成している場合（trackingScenario を使用）
• ユーザーがすでに正しい SFTT 形式のデータを持っている場合
• ユーザーがトラッカーの設計や追跡アルゴリズムの作成を必要としている場合（multi-object-tracking スキルを使用）
• ユーザーが未加工の信号処理（波形設計、距離ドップラーマップ）に取り組んでいる場合

---

ルーティング：データの種類は？

手順 1：データの種類を特定する

「どのような種類のデータをインポートしますか？」と尋ねます。

ユーザーのデータ	ルート
記録された位置／軌跡（正解データ、GPS、飛行ログ）	正解データ経路
センサー計測値（レーダー検出、IR 方位、ライダーボックス、カメラボックス）	センサー経路

列の確認から推測する際の手がかり：

• 正解データの特徴：オブジェクト ID ごとに時間経過に伴う連続した位置があり、ノイズ／精度の列がない
• センサーの特徴：計測量（距離、方位角、RCS）、精度の列があり、ID の連続性が保証されないまま各タイムステップで複数の検出がある

手順 2（センサーデータのみ）：センサーの種類と対象アプリケーションを特定する

重要： 手順 1 でデータが正解データ／軌跡データ（時間経過に伴うプラットフォームごとの位置）と判定された場合は、正解データ経路を使用します。ユーザーが IMM、UKF、またはフィルター調整について言及しただけで、この手順に進んではいけません。これらは調整器が生成するものを指しており、入力データの形式を指すものではありません。正解データ → timetable。センサーデータ → objectDetection または dataFormat 構造体。

「このデータを生成したセンサーは何ですか？」と「何を追跡していますか？」と尋ねます。

次に、API を内部で選択します（API についてユーザーに尋ねてはいけません）。

次の場合は、タスク指向の方法（推奨）を使用します。

• 既成の trackerSensorSpec が一致する、または
• 計測値が sensorMeasurementModel（az/el/range/rr、位置、位置・速度の任意の組み合わせ）に適合する
• かつ、ユーザーが TOMHT／PHD／GridRFS トラッカーまたは EKF 以外のフィルターを必要としていない

次の場合は、従来の objectDetection 方法を使用します。

• ユーザーが TOMHT、PHD、または GridRFS トラッカーを必要としている（タスク指向の方法では GNN／JIPDA のみをサポート）
• ユーザーが UKF、CKF、IMM、粒子フィルターを必要としている（タスク指向の方法では内部的に EKF を使用）
• 計測値がどの sensorMeasurementModel にも適合しない（TDOA、カスタムジオメトリ）
• ユーザーが trackingFilterTuner または既存コードのために objectDetection を明示的に要求している

---

正解データ経路

正解データ／軌跡データ（時間経過に伴うプラットフォームごとの位置、速度）から生成するのは、常に timetable または構造体配列です。objectDetection を生成することはありません。ユーザーがフィルター調整、IMM、UKF、その他のフィルタータイプに言及した場合も同様です。調整の場合、正解データ経路では Time（duration）と Position、Velocity の列（または単一の State ベクトル）を含む timetable を生成します。調整器の検出入力は、別のセンサー計測データから取得する必要があります。正解位置から objectDetection を捏造してはいけません。

手順 1：ユーザーに尋ねる（質問は 2 つのみ）

1. 必要な出力は何ですか？（記録／調整データ／正解ログ／変換後のテーブル）
2. データはどこにありますか？（ファイルパスまたはワークスペース変数名）

ステップ 2：データを確認する

ユーザーが実際に提供したファイルを読み込みます。ユーザーがファイルパスを指定している場合、合成データは決して生成しないでください。readtable または同等の方法でファイルを読み込み、列とサンプル行を表示します。データモデルを推定します。まだ質問はしないでください。

• 地理座標か直交座標か、カテゴリ、時刻列と形式、プラットフォーム／クラス ID 列
• 位置、速度、姿勢、寸法の列
• 単位（デフォルトは度／メートル／m/s。列名から別の単位が示唆される場合は調整します）

カテゴリの選択と列名のパターンについては、references/interpreter-categories.md を参照してください。

ステップ 3：マッピングを提案する — ユーザーに確認・編集してもらう

マッピングが明らかな場合でも、変換コードを書く前に必ずデータの概要を提示します。次の項目をすべて含めてください。

• データ内で見つかった列名
• 検出した単位（列名のヒントまたはデフォルト値に基づく）
• プラットフォーム／オブジェクトの数
• 時間範囲（最初／最後のタイムスタンプ、合計時間）
• 提案する列とフィールドの対応表（未マッピングの列も表示）

推定したマッピングは表で提示します。確認が取れるまで繰り返し調整してください。

ステップ 4：出力座標系について確認する（地理データのみ）

選択肢：直交座標 ECEF、直交座標 Fixed NED/ENU（原点が必要）、測地座標 Local NED/ENU。デフォルトは入力と同じです。references/coordinate-transforms.md を参照してください。

ステップ 5：コードを生成して実行する

コードを生成する前に**references/output-formats.md を読み込んでください**。欠損状態に必要なフィールドとデフォルト値が定義されています。references/code-patterns.md のパターンに従ってください。主な手順：

1. データを読み込む → 列を抽出する → 単位を変換する → 時刻を解析する
2. プラットフォーム ID を連番の整数に再割り当てする
3. 必要に応じて座標を変換する
4. 出力構造を構築する（references/output-formats.md を参照）
5. 出力を構築する前に時刻順に並べ替える

ステップ 6：可視化する

references/visualization.md を参照してください。地理データ → trackingGlobeViewer、非地理データ → theaterPlot。

ここで停止してください。下流のツール（トラッカー、trackOSPAMetric、trackingFilterTuner など）は実行しないでください。ユーザーのデータは正しい形式になりました。どのようなデータが用意できたかを伝え、想定されるユースケースでの呼び出し方を示してください。

---

センサー経路：タスク指向（推奨）

測定値が既成またはカスタムの trackerSensorSpec に適合する場合に使用します。重要なポイント：dataFormat は動的です。センサー仕様のプロパティに応じて変化します。構造体をハードコードせず、必ず問い合わせてください。

ステップ 1：センサー仕様を選択する

センサーの説明	仕様
航空宇宙用単基地レーダー	trackerSensorSpec('aerospace','radar','monostatic')
航空宇宙用バイスタティックレーダー	trackerSensorSpec('aerospace','radar','bistatic')
ESM／方向探知機	trackerSensorSpec('aerospace','radar','direction-finder')
航空宇宙用赤外線（角度のみ）	trackerSensorSpec('aerospace','infrared','angle-only')
自動車用レーダー（クラスタ化された検出）	trackerSensorSpec('automotive','radar','clustered-points')
自動車用カメラ（2D バウンディングボックス）	trackerSensorSpec('automotive','camera','bounding-boxes')
自動車用ライダー（3D バウンディングボックス）	trackerSensorSpec('automotive','lidar','bounding-boxes')
その他の標準的な測定値	trackerSensorSpec('custom') — ステップ 2b を参照

ステップ 2a：データから仕様プロパティを設定する

ユーザーのデータを調べ、dataFormat に影響するプロパティを設定します。

航空宇宙モノスタティック／ESM／IR：

• HasElevation — データに仰角の測定値が含まれていますか？
• HasRangeRate — データに距離変化率／ドップラーが含まれていますか？（レーダーのみ）
• IsPlatformStationary — センサーの位置は固定ですか、それとも移動しますか？（false にすると、各観測に PlatformPosition/Orientation/Velocity が追加されます）
• MaxNumLooksPerUpdate — データ内の更新あたりの最大スキャン滞留数
• MaxNumMeasurementsPerUpdate — データ内の更新あたりの最大検出数

航空宇宙バイスタティック：

• HasElevation、HasRangeRate — 上記と同じです
• MeasurementMode — "range-angle" または "range-only"
• IsReceiverStationary、IsEmitterStationary — false にするとプラットフォームフィールドが追加されます

自動車用レーダー：

• HasElevation、MaxNumMeasurements
• ReferenceFrame — 'ego'（車体座標系の測定値）または 'global'（グローバル座標系での自車姿勢が利用可能）

自動車用カメラ／LiDAR：

• MaxNumMeasurements
• ReferenceFrame — 'ego' または 'global'

ステップ 2b：カスタムセンサー仕様（既製の仕様が合わない場合）

標準的な測定タイプを使用するものの、既製の仕様がないセンサー（例：船舶用レーダー、ソナー）の場合：

sensorSpec = trackerSensorSpec('custom');
sensorSpec.MeasurementModel = sensorMeasurementModel('<modelName>');
sensorSpec.DetectabilityModel = sensorDetectabilityModel('<modelName>');
sensorSpec.ClutterModel = sensorClutterModel('<modelName>');
sensorSpec.BirthModel = sensorBirthModel('<modelName>');

モデルカタログとプロパティの詳細については、references/sensor-data-formats.md を参照してください。

移動するセンサーの場合は、UpdateModels = true を設定します。これにより、Time、TimeVaryingModelData、MeasurementVaryingModelData が dataFormat に追加されます。

ステップ 3：データを調べる — 単位、時刻、座標系を推定する

ユーザーが指定した実際のファイルを読み取ってください — ユーザーがファイルパスを指定した場合、合成データを生成してはいけません。次の項目を特定します。

1. 時刻列と形式 — 真値の経路と同じヒューリスティックを使って検出します（references/time-and-units.md を参照）。最初のタイムスタンプからの経過秒数に変換します。
2. 測定単位 — 列名の接尾辞（_deg、_rad、_km、_kts など）から推定するか、ユーザーに確認します。dataFormat の目標単位：
   • 角度：度
   • 距離：メートル
   • 距離変化率：m/s
   • 位置：メートル
   • 速度：m/s
3. 座標系 — 測定値がセンサーのネイティブ座標系にない場合は、変換を計画します。
   • センサーネイティブとは、センサーが通常報告する座標系です（レーダー／ESM／IR では球面座標、自動車用では車体相対座標、カメラでは画像ピクセル）。
   • ユーザーのデータがワールド座標系にある場合（例：統合トラッカーの NED 直交座標位置）で、センサー仕様が球面座標の測定値を想定している場合は、センサー姿勢を使ってセンサーネイティブ座標系に戻します。
   • ユーザーのデータが異なる車体座標系の規約（例：NED と ENU）にある場合は、それに応じて回転します。
   • すでにセンサーネイティブ座標系にある場合（一般的なケース）、変換は不要です。

ステップ 4：dataFormat を照会してマッピングを提案する

fmt = dataFormat(sensorSpec);
disp(fmt)

ユーザーの確認用に、マッピング表を提示します。

Your column          →  dataFormat field        Action
"azimuth_deg"        →  LookAzimuth (1×N)      direct (deg→deg)
"range_km"           →  Range (M×N)            convert km→m (×1000)
"doppler_mps"        →  RangeRate (M×N)        direct
"timestamp_epoch"    →  MeasurementTime (1×N)  parse epoch→elapsed sec
"elev_rad"           →  LookElevation (1×N)    convert rad→deg
[unmapped: "snr"]    →  (not used)

「Action」列に単位変換と座標変換を含めます。マッピングされていない列も表示します。ユーザーが確認するまで繰り返します。

ステップ 5：センサー性能プロパティを設定する

ユーザー入力から設定するか、デフォルト値を使用します：MountingLocation、MountingAngles、FieldOfView、RangeLimits、DetectionProbability、FalseAlarmRate/NumFalsePositivesPerScan。

ステップ 6：コードを生成する

ループ内で各時間ステップの dataFormat 構造体に値を設定するコードを記述します。出力は、トラッカーに渡す準備ができた、更新ごとに 1 つの構造体を持つ配列です。ここで停止してください — トラッカーを作成したり実行したりしてはいけません。 データの準備ができたことをユーザーに伝え、呼び出し方を示します：tracker = multiSensorTargetTracker(targetSpec, sensorSpec, algorithm); tracks = tracker(sensorData(iUpdate))

オイラー角からの回転行列： データにヨー／ピッチ／ロールがあり、3×3 の回転行列（例：PlatformOrientation 用）が必要な場合は、クォータニオンから作成します。

R = rotmat(quaternion([yaw pitch roll], 'eulerd', 'ZYX', 'frame'), 'frame');

前処理フラグ

データの特徴	対応
生のレーダー点群（1スキャンあたりの点が多く、オブジェクトとの関連付けがない）	フラグ：クラスタリングが必要です。ツール：dbscan、clusterDBSCAN（Radar Toolbox）、partitionDetections。動作する例を作成することを提案します。
生のライダー XYZ 点群（バウンディングボックスなし）	フラグ：バウンディングボックスの抽出が必要です。例を提案します。
生のカメラ画像（検出結果なし）	対象範囲外です。まずオブジェクト検出器が必要です。

---

センサーパスウェイ：Legacy objectDetection

タスク指向 API が適さない場合（TOMHT/PHD トラッカー、非 EKF フィルター、カスタム測定値、またはユーザーから明示的な要望がある場合）に使用します。

標準サブパス（組み込み測定モデル）

cvmeas／cameas／ctmeas に適合する測定値（球面座標系での az／el／range／rr の任意の組み合わせ、または直交座標系での位置／速度）に使用します。

ワークフロー：

1. データ列から測定要素を特定します
2. 単位、時刻、基準座標系を推定します（タスク指向のステップ 3 と同じです）：
   • 時刻列を解析して、経過秒数に変換します（references/time-and-units.md を参照）
   • 列名から単位を検出して、角度を度、距離をメートル、速度を m/s に変換します
   • 測定値がワールド座標系にあり、センサー固有座標系（センサーに対する球面座標系または直交座標系）に変換する必要がある場合は、センサー姿勢を使って変換します
3. Has* フラグを設定します：HasAzimuth、HasElevation、HasRange、HasVelocity
4. Frame を決定します：'spherical' または 'rectangular'
5. 各時間ステップのセンサー姿勢（位置、速度、向き）を取得します。センサーが静止している場合は固定値を使用します
6. マッピング表を提案します — 列から objectDetection フィールドへの対応と、単位／座標系に関する処理を示します。ユーザーが確認するまで調整します
7. 標準の MeasurementParameters 構造体を作成します（references/objectDetection-patterns.md を参照）
8. 正しい順序で測定ベクトルを構成します：
   • 球面座標系：[az, el, range, rr]（欠損要素は除外）
   • 直交座標系：[x, y, z, vx, vy, vz]（欠損要素は除外）
9. 精度列またはユーザー指定値から MeasurementNoise を設定します
10. objectDetection セル配列を生成します
11. フィルターチューニング用データ（ユーザーが trackingFilterTuner 用のセンサー測定データを持っている場合）： チューナーには、検出結果とターゲットの関連付けが必要です。センサーデータにターゲット ID 列（例：TargetID、PlatformID、ObjectID）が含まれている場合：
    • ターゲットごとに検出結果を分けます。検出ログのセル配列を（プラットフォームごとに 1 つ）作成します。
    • チューナーには真値タイムテーブルも必要ですが、これは Truth Pathway 経由の別の真値データソースから取得します。センサー測定値から真値を捏造したり、その逆を行ったりしないでください。
    • ターゲット ID 列がない場合：trackingFilterTuner には検出結果とターゲットの関連付けが必要であることをユーザーに伝え、どのように進めるか（ID を提供するか、単一ターゲットのサブセットを使用するか）を確認します
12. ここで終了します。トラッカーは作成も実行もしないでください。 ユーザーに次のように伝えます：「これらの検出結果は、組み込みフィルター初期化関数で使用できます：initcvekf、initcaukf、initctekf、initcvukf など。」

カスタムサブパス（標準外の測定値）

組み込みモデルに適合しない測定値（TDOA、カスタムジオメトリなど）の場合：

1. 測定値が標準外であることを特定します
2. 単位、時刻、基準座標系を推定します — 時刻を解析し、単位を変換し、必要に応じてセンサー固有の座標系に変換します（上記と同じルールに従います）
3. 状態ベクトルは何か、運動モデルは何かを確認します
4. カスタムの MeasurementParameters を設計します — 測定関数に必要な情報を持たせ、マルチセンサーの場合は識別フィールドを含める必要があります
5. 状態を期待される測定値に対応付けるカスタムの measurementFcn(state, mp) を記述します
6. 逆測定モデルを使用するカスタムの filterInitFcn(detection) を記述します
7. カスタムの MeasurementParameters を含む objectDetection 配列を生成します
8. 測定関数とフィルター初期化関数を対応するペアとして提供します
9. ここで停止します。トラッカーを作成または実行しないでください。 検出データの準備ができたことをユーザーに伝えます。

標準の構造体、測定値の順序、マルチセンサー設計パターンについては、references/objectDetection-patterns.md を参照してください。カスタム関数のテンプレートについては、references/custom-measurement-models.md を参照してください。

---

参考ドキュメント

詳細が必要なときに、必要に応じて読みます。

• references/output-formats.md — Truth 出力の構造体／テーブルスキーマ（recording、tuning、truthlog）
• references/code-patterns.md — Truth のエンドツーエンドのインポートコード例
• references/coordinate-transforms.md — 座標系変換（LLA→ECEF、NED→ECEF など）
• references/visualization.md — trackingGlobeViewer と theaterPlot の使用方法
• references/interpreter-categories.md — Truth データのカテゴリ、状態要素、列名のパターン
• references/time-and-units.md — 時刻の解析と単位変換
• references/sensor-data-formats.md — タスク別の内容：組み込み／カスタムのすべてのセンサー仕様プロパティ、モデルカタログ、dataFormat の動作
• references/objectDetection-patterns.md — レガシー：MeasurementParameters 構造体、測定ベクトルの順序、マルチセンサーのパターン
• references/custom-measurement-models.md — カスタムの measurementFcn と filterInitFcn のテンプレート

---

Copyright 2026 The MathWorks, Inc.