SAM Particle Counter マニュアル（日本語版）

English version is available here: SAM Particle Counter Manual (English)

はじめに

SAM Particle Counter のマニュアルへようこそ。

本ページは、画像読み込みから粒のカウント結果の出力まで、解析手順を説明する日本語版マニュアルです。

このアプリでできること

SAM Particle Counter は、napari ベースのデスクトップツールで、以下の作業を支援します。

  • 矩形 ROI（region of interest; 関心領域）の作成
  • SAM2 を用いた自動セグメンテーション
  • ポイントプロンプトやラベル編集による補正
  • オーバーレイ画像、CSV、実行メタデータの出力

典型的な流れは次のとおりです。

  1. 画像を読み込む
  2. ROI を描く
  3. ROI でクロップする
  4. SAM2 自動セグメンテーションを実行する
  5. 必要に応じて結果を修正する
  6. 成果物をエクスポートする

事前準備

環境セットアップ

詳細なセットアップ手順は README.md を参照してください。 最低限、次を満たしてください。

  • uv で依存関係をインストール済み
  • OS に対応した SAM2 セットアップスクリプトを実行済み
  • 次のコマンドでアプリが起動できる
Terminal
uv run main.py
Note入力画像の推奨条件

セグメンテーション精度を安定させるため、以下を推奨します。

  • 粒子と背景のコントラストが十分にある画像
  • 強いブレや圧縮ノイズが少ない画像

詳細な解析手順

Step 1. 画像の読み込み

napari に画像を読み込みます（ドラッグ＆ドロップ、または File > Open...）。

File を選択する

Open File(s)… を選択する

最初の画像レイヤーが追加されると、対応する ROI（region of interest）レイヤー（<image_name>_ROI）が自動作成されます。

読み込まれた画像
Cautionレイヤ名は変更しないでください

このアプリはレイヤー名の規則を使って処理対象を解決します。 レイヤー名は手動で変更しないようにしてください。

Step 2. *_ROI レイヤーに ROI を描画

  1. ROI レイヤー（<image_name>_ROI）を選択（デフォルトで選択されています）
  2. Add Rectangles ツール で矩形を描画（デフォルトで選択されています）
  3. ROI が複数ある場合は 最後に描いた矩形 が使用される
  4. 右のウィジェットの Crop to ROI ボタンを実行する
  5. <image_name>_cropped レイヤーが作成され、元画像の ROI 部分が切り出される

ROI を描いて Crop to ROI を実行

クロップされた画像
Tip実務中のコツ
  • 対象粒子を取りこぼさないよう少し余裕を持たせる
  • 無関係な領域は可能な限り除外する
  • 処理が重い場合は小さい ROI から開始する
  • スペースキーを押しながらドラッグすることで、表示を移動できます

Step 3. Run SAM2 auto segmentation を実行

  1. <image_name>_cropped レイヤーを選択（デフォルトで選択されています）
  2. 右のウィジェットの Run SAM2 auto segmentation ボタンを実行する（必要に応じてパラメータを調整）
  3. SAM2 のセグメンテーション結果が新しいレイヤーに出力される。
    • <image_name>_cropped_sam2_auto（ポリゴン）
    • <image_name>_cropped_sam2_auto_labels（編集可能ラベル）
    • <image_name>_cropped_sam2_auto_labels_original（編集不可の参照コピー）
    • ラベル番号を示すオーバーレイ（編集しない）

SAM2 セグメンテーション

SAM2 のパラメータ

パラメータ 説明 初期値（おすすめ設定）
points_per_side 画像全体に配置する自動プロンプト点の密度を指定します。 値を大きくすると、より細かく探索され、小さい粒子も検出されやすくなりますが、処理時間とメモリ使用量が増えます。 56
pred iou thresh SAM2 が予測したマスク品質スコアのしきい値です。 値を高くすると、信頼度の高いマスクだけが残り、誤検出は減りやすくなりますが、検出漏れが増える可能性があります。 0.84
stability score thresh マスクの安定性スコアのしきい値です。 値を高くすると、境界が安定したマスクだけが残ります。 輪郭が不安定な粒子や小さい粒子は除外されやすくなります。 0.90
crop n layers 画像を段階的にクロップして再探索する回数を指定します。 値を大きくすると、局所領域でより細かくマスクを検出できますが、処理時間が増えます。 2
crop n points downscale factor クロップ領域で使用するプロンプト点密度の調整係数です。 値を大きくすると、クロップ領域での点密度が下がり、処理は軽くなりますが、小さい対象の検出力は低下する可能性があります。 1
deduplicate masks 重複して検出されたマスクを削除するかどうかを指定します。 有効にすると、同じ粒子に対して複数のマスクが作成された場合に、重複マスクを除去します。 詳細は 重複マスク削除の仕組み を参照してください。 True
contain thresh 片方のマスクがもう片方のマスクにどの程度含まれていれば重複とみなすかを指定します。 値を低くすると重複判定が厳しくなりすぎず、多くのマスクが削除されやすくなります。 値を高くすると、ほぼ内包されている場合だけ削除されます。 0.90
iou thresh 2つのマスクの重なり具合を IoU（Intersection over Union）で評価するしきい値です。 値を低くすると、少し重なったマスクも重複として削除されやすくなります。 値を高くすると、強く重なっている場合だけ削除されます。 0.70
score key 重複マスクのうち、どちらを残すか判断するときに使うスコアを指定します。 通常は predicted_iou を用い、品質スコアが高いマスクを残します。 predicted_iou
output mode SAM2 の結果をどの形式で出力するかを指定します。
  • labels: 編集可能なラベルレイヤーを出力します。通常はこちらを選択します。
  • shapes: ポリゴンレイヤーを出力します。セグメンテーション結果を塗り分けしたくない場合はこちらを選択します。通常こちらは編集しません。
  • both: 両方のレイヤーを出力します。
 labels

Step 4. 手動補正（必要に応じて）

最終カウント精度を高めるため、必要に応じて補正します。

(A) ラベルの手動編集

  1. <image_name>_cropped_sam2_auto_labels レイヤーを選択（デフォルトで選択されています）
  2. napari のラベル編集機能で次を編集します。

基本的なラベルの修正方法については、napari の公式ドキュメント を参照してください。

ラベル編集例
Tip手動編集のポイント

粒を追加したいとき

粒が見落とされている場合は、左上の label の番号を一つ増やし、ペンツール で新たな粒のマスクを作成します。 brush size からペンの太さを調整できます。

粒を分割したいとき

複数の粒が連結してしまっている場合は、片方を消しゴムツール で消去した後、label の番号を増やしてペンツール で新たな粒のマスクを作成します。

広範囲を消去したいとき

背景がマスクとして誤検出されている場合は、スポイトツール で何もない場所をクリックして背景色を選択し、塗りつぶしツール で背景マスクをクリックすると、まとめて消去できます。

同様に、かたまり単位で粒を消去したいときは、スポイトツール で粒子の色をクリックして選択し、塗りつぶしツール でその粒子をクリックすると、まとめて消去できます。

誤検出された粒を消去したいとき

ホコリなどのノイズが粒として誤検出されている場合は、消しゴムツール で消去します。

マスクごとに確認したい場合

show selected にチェックを入れると、選択したラベル ID のマスクだけが表示されるようになります。 この状態で label を変更すると、次々にマスクを確認できます。

(B) ポイントプロンプト補正

  1. Create prompt points layer を実行
  2. Foreground / Background を選択
  3. クロップ画像上に点を配置
  4. Run SAM2 point prompt を実行

*_sam2_points レイヤーに候補ポリゴンが出力され、補正の判断に使えます。

Warning注意点

現在、こちらの機能は実験的な段階であり、すべてのケースで安定して動作するわけではありません。 粒が小さい場合はうまくいかないことが多いため、通常の手動編集の方が確実です。 今後、機能が変更になる可能性が高いことに留意してください。

Step 5. 結果のエクスポート

  1. 手動編集が完了したら、Export segmentation artifacts を実行して成果物を出力します。 出力先のディレクトリはデフォルトで ./outputs ですが、任意の場所を選択できます。 出力先のディレクトリは自動で作成されます。
  2. 出力が完了すると、example_02_20260426T044227Z のようなタイムスタンプ付きのフォルダが生成されます。

出力されたフォルダには、以下のファイルが含まれます。

ファイル名 説明
source_with_roi.png 元画像に ROI ボックスを重ねた画像
cropped_image.png クロップされた分析対象領域の画像
sam2_only_overlay.png SAM2 の自動セグメンテーション結果のオーバーレイ画像
final_overlay.png 最終的に採用したラベルのオーバーレイ画像
sam2_blobs.csv SAM2 の自動セグメンテーション結果に基づく粒マスクのデータ
final_blobs.csv 最終的に採用したラベルに基づく粒マスクのデータ
run_metadata.json 実行時のパラメータ、件数、環境情報などをまとめた JSON ファイル

Step 6. レイヤの消去

出力が完了したら、Delete all layers for current image を実行すると、現在の画像だけでなく、ビューアに読み込まれている全レイヤー が削除されます。 確認のダイアログは表示されますが、別画像で進めていた作業も失われる可能性があるため、十分注意してください。

すべてのレイヤーが消去されると、次の画像を読み込む準備ができます。 Step 1 に戻って、次の画像を読み込んでください。

レイヤの消去

QA チェックリスト

最終結果として採用する前に、少なくとも次を確認してください。

  • ROI が必要領域を過不足なく含んでいる
  • 代表箇所でマスク境界が妥当である
  • 大きな merge / split エラーが補正されている
  • オーバーレイ表示と CSV 件数に不整合がない
  • run_metadata.json を画像成果物と一緒に保存している

トラブルシューティング

クロップレイヤーが作成されない

  • アクティブレイヤーが *_ROI か確認
  • 有効な矩形 ROI が描画されているか確認

SAM2 自動セグメンテーションが失敗する

  • SAM2 セットアップとモデル配置を再確認
  • ROI を小さくして再試行
  • points_per_side を下げて再試行

エクスポートが失敗する

  • *_cropped レイヤーが存在するか確認
  • SAM2 ラベルレイヤーが存在するか確認
  • 出力先ディレクトリに書き込み権限があるか確認

アイコンのクレジット

本マニュアルで使用している一部のインターフェースアイコン（fill.svg, paint.svg, erase.svg, picker.svg, rectangle.svg）は、napari プロジェクトからコピーまたは改変したものです。

正準の出典（コミット固定）: src/napari/resources/icons @ c3e6c4ab549eaeb67c6f98502851dd99e4804522。 これらのアイコンファイルは Napari および napari contributors の著作物であり、BSD 3-Clause License に従って再配布しています。ライセンス全文は LICENSES/napari-BSD-3-Clause.txt を参照してください。