Error Codes - Object Detection

MLdebuggerのエラーコードは、モデルの間違え方を分類したラベルです。このガイドでは、Object Detectionタスク（2D / 3D共通）におけるエラーコードの定義を説明します。

Issue Categoryについて

エラーコードが属するIssue Category（Stable Coverage、Hotspotなど）の定義はEvaluation と Resultを参照してください。

エラーコードフォーマット

Object Detectionタスクのエラーコードは以下の形式で表現されます。

基本形式

DET:{det_error_code}:CLS{t}->{y}

det_error_code: 検出結果の種別を示す検出エラーコード
t: アノテーションされた正解クラスID
y: 予測クラスID

例: - DET:A:CLS0->0: Aligned検出、クラス0が正解で、クラス0と予測（正解） - DET:M:CLS3->5: 位置誤差あり、クラス3が正解だが、クラス5と予測（誤答）

検出エラーコード (`det_error_code`)

det_error_code	名称	説明
`A`	Aligned	十分なIoUで正しくマッチした検出
`M`	Matched	GTにマッチしたが位置誤差がある検出
`SP`	Separated Preds	1つのGTに対して予測が複数に分割
`SG`	Separated GTs	1つの予測に対して複数のGTがマッチ
`D`	Duplicate	同一GTに対する重複検出
`ON`	Overlap No Pair	GTとマッチしないが他の予測と部分的に重なる検出
`N`	No Pair	GTマッチのない誤検出（No GT Pair）
`U`	Undefined	マッチング結果が不定の検出

GUI上の表示名

モニタリング画面（GUI）では、一部のコードが異なる表示名で表示されます。

N → NG（No GT Pair）
ON → ONG（Overlap No GT Pair）

また、未検出GT（diagnosis: no_prediction）は NP（No Pred Pair）として表示されます。

不確実な検出のサフィックス

単一の検出エラー種別を十分な確信度で決められない場合、det_error_code に * サフィックスが付きます。これは 不確実マーカー です。

エラー確率が閾値未満（1 - error_proba_thresh、デフォルト 0.8）のときに発生します。特に、モデル未学習クラス（エラー確率が常に 0）では常に不確実扱いになります。

DET:N|SP*:CLS1->3

これは検出が No-pair（N）と Separated Pred（SP）のどちらかに絞り切れないことを示します。

予測クラス (`y`)

表記	意味
数字（例: `0`）	予測クラスID
`x`	未検出GT（`FN` — 予測なし）
`**`	予測が正解クラスと一致
`{y1}\\|{y2}`	複数クラス間の揺らぎ（例: `2\\|3`）
`*`	不確実なトップ予測
`?`	不明（正解クラスも不明な場合）
`ODD`	Out-of-Distribution — モデルが未学習のクラス

揺らぎがある場合

DET:{det_error_code}:CLS{t}->{y1}|{y2}

内部特徴量が不安定で予測クラスが複数のクラス間で揺らぐ場合、|で区切って表現します。

例: - DET:M:CLS0->2|3: 位置誤差あり、クラス0が正解だが予測クラスが2と3の間で揺らぎ - DET:A:CLS5->7|1|9: Aligned、クラス5が正解だが予測クラスが7、1、9の間で揺らぎ

Critical/Aleatoricマーカー

DET:{det_error_code}:CLS{t}->{y}**

Critical HotspotまたはAleatoric Hotspotの中で、内部特徴量的に最もらしいクラスが正解クラスと一致している場合、**が付加されます。

例: - DET:D:CLS0->0**: 重複検出、クラス0が正解で予測も正解と一致（高確信度の重複）

未検出GT（no_prediction）

マッチする予測のないGTボックスは、diagnosis フィールドが no_prediction として記録されます。

例: - DET:U:CLS2->x: 正解クラス2が未検出（予測なし）

マッチしない予測

DET:N:CLS?->?

予測がGTとマッチせずクラスを決定できない場合、正解クラスと推定クラスの両方に?が使用されます。

Out-of-Distribution（ODD）

DET:{det_error_code}:CLS{t}->ODD

モデルが特定のクラスを学習していない場合（その pred_class_id のエラー確率モデルが存在しない場合）、エラー確率はすべて 0 になります。この場合、予測クラスは ODD（Out-of-Distribution Detection）に設定されます。単一のエラー種別を確定できないため、これらの検出は必ず不確実（det_error_code に * サフィックス）になります。

例: - DET:N*:CLS?->ODD: 未学習クラスに対する不確実な No-pair 検出 - DET:A*:CLS3->ODD: モデルがクラス3を学習していない不確実な Aligned 検出

エラーコードの解釈例

例1: `DET:M:CLS0->2|3`（Hotspot）

検出エラーコード: Loc Error（マッチしたが位置誤差あり）
正解クラス: 0
予測クラス: 2と3の間で揺らぎ
Issue Category: hotspot（Unstable）
解釈: 正解クラス0は検出されたが位置精度が低く、クラス推定も不安定
対処: クラス0のより明確な境界を持つ学習データを追加、アンカー設定の見直し

例2: `DET:D:CLS0->0**`（Critical Hotspot）

検出エラーコード: Duplicate（重複検出）
正解クラス: 0
予測クラス: 0（正解と一致）
Issue Category: critical_hotspot（NMS問題）
解釈: クラス0の重複検出で、モデルは確信度が高いがNMSで抑制できていない
対処: NMS閾値の調整、後処理パイプラインの見直し

例3: `DET:U:CLS2->x`（Recessive Hotspot / no_prediction）

検出エラーコード: Undefined（未検出GT）
正解クラス: 2
予測クラス: 検出なし
diagnosis: no_prediction
Issue Category: recessive_hotspot（Under-Confidence）
解釈: クラス2のオブジェクトが完全に見逃されている
対処: クラス2の学習データ追加、スコア閾値の調整

例4: `DET:N:CLS?->?`（Critical Hotspot / Aleatoric）

検出エラーコード: No-pair（誤検出）
正解クラス: 不明
予測クラス: 不明
Issue Category: critical_hotspot（Aleatoric）
解釈: 対応するGTのない誤検出、データの曖昧さに起因する可能性
対処: アノテーションの確認、Hard Negativeサンプルの追加

例5: `DET:N*:CLS?->ODD`（Critical Hotspot / ODD）

検出エラーコード: No-pair、不確実（*）
正解クラス: 不明
予測クラス: ODD（out-of-distribution）
Issue Category: critical_hotspot
解釈: モデルが未学習のクラス。エラー確率がすべて 0 のため常に不確実。学習データに含まれていないクラスの可能性が高い
対処: 不足クラスの学習データ追加、またはそのクラスがスコープ内か確認

デバッグコード

各エラーコードには、デバッグの方向性を示すdebug_codeが付与されます。

debug_code	説明	対処法
`model_epistemic`	モデルの知識不足に起因	データ追加、再学習
`postprocess_nms`	NMS関連の問題（D, SP, SG等）	NMS/IoU閾値の調整
`postprocess_threshold`	スコア閾値の問題	確信度閾値の調整
`annotation_review`	アノテーションの確認が必要（N, ON等で推定上は正常）	アノテーションの見直し
`aleatoric`	データ自体の曖昧さに起因	アノテーション確認、タスク定義見直し

3D Object Detectionのdebug_code

3D Object Detectionでは model_epistemic と aleatoric のみが使用されます。postprocess_nms、postprocess_threshold、annotation_review は2D OD固有です。

Result APIでの使用

# Issue一覧の取得
issues_df = result.get_issues()

# エラーコード別の分布
error_distribution = issues_df.groupby("error_code")["counts"].sum()

# debug_code別の分布
debug_distribution = issues_df.groupby("debug_code")["counts"].sum()

# NMS関連のIssueのみ抽出
nms_issues = issues_df[issues_df["debug_code"] == "postprocess_nms"]

可視化例

# カテゴリ別の分布を取得
category_view = result.get_view(
    groupby=["category"],
)

# Hotspotの詳細なエラーコード分布
hotspot_detail = result.get_view(
    query="category == 'hotspot'",
    groupby=["error_code"],
)

# debug_code別の分布
debug_view = result.get_view(
    groupby=["debug_code", "category"],
)

次のステップ

Evaluation と Result - Result APIの詳細