#0231（2025/09/01）SAM2Base コンストラクタパラメータ早見表

SAM2Base __init__ パラメータ早見表

対象ファイル: sam2/modeling/sam2_base.py

SAM2 の基底クラス SAM2Base が __init__ で受け取るパラメータを、意味・デフォルト・型・推奨値（目安）付きで整理しました。実装コメントと後段の使用箇所から実務目線の推奨も付記しています。

---

コアモジュール／画像サイズ系

パラメータ名	意味	デフォルト	型	推奨値・目安
image_encoder	画像バックボーン（特徴抽出器）	なし	torch.nn.Module	重みに合ったものを使用（チェックポイント依存）。
memory_attention	メモリアテンション（過去メモリ+現在特徴を融合）	なし	torch.nn.Module	既定の実装を利用。置き換えは高度な改造時のみ。
memory_encoder	予測マスクを空間メモリ特徴にエンコード	なし	torch.nn.Module	既定の実装を利用。
image_size	入力画像の辺長（正方形）	512	int	モデル重みに合わせる。高精細なら 768 / 1024、速度優先は 512。
backbone_stride	バックボーン出力のストライド	16	int	重みに依存。通常変更しない。

---

メモリバンク／時系列制御

パラメータ名	意味	デフォルト	型	推奨値・目安
num_maskmem	利用するメモリフレーム数（条件フレーム+過去）	7	int	画質↔速度トレードオフ。3–7 が現実的。静止画SAM再現なら 0。
memory_temporal_stride_for_eval	評価時のメモリ間ストライド r	1	int	長尺ビデオ・省メモリで 2–5。追跡安定重視は 1。
max_cond_frames_in_attn	アテンションに入れる条件フレーム数上限（近傍優先）	-1 (無制限)	int	多数アノテ時のOOM回避に 2–8 程度。少数なら -1 のまま。
directly_add_no_mem_embed	初期条件フレームで Transformer を使わず no‑mem 埋め込みを直接加算	False	bool	微速化。通常は False のまま。

---

メモリエンコード時のマスク前処理／制約

パラメータ名	意味	デフォルト	型	推奨値・目安
sigmoid_scale_for_mem_enc	メモリエンコーダへ入れるマスク確率のスケール	1.0	float	既定のまま。特殊分布でのみ調整。
sigmoid_bias_for_mem_enc	同バイアス	0.0	float	既定のまま。
binarize_mask_from_pts_for_mem_enc	クリック由来フレームを二値化してメモリ化（評価時）	False	bool	クリック誤差が小さい環境で True 検討。通常は False。
non_overlap_masks_for_mem_enc	メモリエンコーダ入力マスクに非重なり制約を適用（評価時）	False	bool	多物体で重畳しやすい場合 True。計算安全策として有用。
use_mask_input_as_output_without_sam	マスク入力があるフレームは SAM を通さずそのまま出力扱い	False	bool	GTマスク前提の高速化に有効。通常は False。

---

SAMヘッド出力（解像度・マルチマスク）

パラメータ名	意味	デフォルト	型	推奨値・目安
use_high_res_features_in_sam	SAM デコーダで高解像特徴（L0/L1）も使用	False	bool	細部重視・余力ありなら True（メモリ増）。通常 False。
multimask_output_in_sam	初回クリック等で候補マスクを3枚出力	False	bool	対話時の探索性向上に True 推奨。バッチ追跡は False。
multimask_min_pt_num	マルチマスク適用の最小クリック数	1	int	デフォルトでOK。ボックスは2点扱い。
multimask_max_pt_num	マルチマスク適用の最大クリック数	1	int	1–2 程度。クリック増で単一化したいなら 1 のまま。
multimask_output_for_tracking	追跡中フレームでもマルチマスクを出す	False	bool	通常 False。探索重視の特殊ワークフローで True。
iou_prediction_use_sigmoid	IoU 予測を [0,1] に制限	False	bool	安全側に倒すなら True 可。既定は False。

---

オブジェクトポインタ（ObjPtr）とクロスアテンション

パラメータ名	意味	デフォルト	型	推奨値・目安
use_obj_ptrs_in_encoder	エンコーダで他フレームの ObjPtr をクロス参照	False	bool	品質↑だが計算増。余力があり学習設定が対応なら True。
max_obj_ptrs_in_encoder	参照する ObjPtr の最大数	16	int	8–32 で調整。長尺は控えめに。
add_tpos_enc_to_obj_ptrs	ObjPtr に時間位置埋め込みを付与	True	bool	基本 True。
proj_tpos_enc_in_obj_ptrs	時間PEに追加線形投影（空間PEと干渉回避）	False	bool	干渉が疑われる時のみ True。
use_signed_tpos_enc_to_obj_ptrs	時間PEを符号付き距離で与える	False	bool	時間方向性を持たせたい場合に検討。
only_obj_ptrs_in_the_past_for_eval	評価時、過去の ObjPtr のみ参照	False	bool	未来情報リーク回避に True 推奨（特に冒頭区間）。
use_multimask_token_for_obj_ptr	マルチマスクのトークンを ObjPtr に利用	False	bool	use_obj_ptrs_in_encoder かつ multimask_output_for_tracking を使う高度設定時のみ。
use_mlp_for_obj_ptr_proj	ObjPtr の線形投影を MLP 化	False	bool	非線形性を足したいときに True。効果はドメイン依存。

---

物体存在スコア（出現/非出現の推定）

パラメータ名	意味	デフォルト	型	推奨値・目安
pred_obj_scores	フレーム内に物体が存在するかを推定	False	bool	対応学習済み重みなら True 検討。未対応なら False。
pred_obj_scores_mlp	上記を MLP で予測	False	bool	pred_obj_scores=True のときのみ関連。
fixed_no_obj_ptr	非出現時に固定 no‑obj ポインタを使用（加算でなく置換寄り）	False	bool	pred_obj_scores かつ use_obj_ptrs_in_encoder 必須。通常は False。
soft_no_obj_ptr	非出現時に no‑obj ポインタをソフト混合	False	bool	エラー回復性を上げたい場合に True 検討。
no_obj_embed_spatial	非出現時、空間メモリに no‑obj 埋め込みを加える	False	bool	オクルージョン多発で有効。pred_obj_scores と併用が自然。

---

その他

パラメータ名	意味	デフォルト	型	推奨値・目安
sam_mask_decoder_extra_args	MaskDecoder への追加引数（辞書）	None	`dict	None`	既定のまま。特殊用途でパラメータ上書き。
compile_image_encoder	画像エンコーダを torch.compile	False	bool	初回遅いが以降高速化。実運用はウォームアップ可なら True。

---

依存関係・注意点

• fixed_no_obj_ptr を使うには pred_obj_scores=True かつ use_obj_ptrs_in_encoder=True が必要。
• use_multimask_token_for_obj_ptr は use_obj_ptrs_in_encoder かつ multimask_output_for_tracking が前提。
• メモリ・速度調整の基本順序：num_maskmem → memory_temporal_stride_for_eval → max_cond_frames_in_attn → use_high_res_features_in_sam。
• 画質改善の基本順序：use_high_res_features_in_sam → non_overlap_masks_for_mem_enc → ObjPtr 系（余力があれば）→ multimask_output_in_sam。