Maskbolt Segment Anything on CPU

Maskbolt

AI エージェントやスクリプト向けに、CPU で Segment Anything（SAM）を実行します。Maskbolt は 1 つの Rust バイナリです。エージェントが画像を開き、すべてのオブジェクトを見つけたり、クリックしたオブジェクトを選択したり、番号付きプレビューを確認したり、誤りを修正したり、切り抜き、輪郭、マスクを書き出したりできる MCP サーバーと、同じ作業を 1 つのコマンドで行える CLI を備えています。Python も GPU も不要です。

• クリック 1 回で、オブジェクトを透明な PNG として切り抜けます。SAM の 3 つの入れ子になったマスク（部分、オブジェクト、グループ）も、引数 1 つで取得できます。
• 「すべてを見つける」では、画像全体または重なり合うタイル上にグリッド状のプロンプトを実行します（各タイルはモデルのフル解像度に再エンコードされるため、小さなオブジェクトも見つかります）。タイルの端で切れたマスク、背景のパッチ、重複、ほかのマスクに含まれるマスクを除外し、その理由も示します。
• マスクを変更するすべての応答には、マスクの数、候補を除外した理由、まだ覆われていないように見えるパッチ（「これらに似たものをもっと見つける」）が示されるため、エージェントは残っているものを把握できます。
• 書き出し形式：オーバーレイ PNG（番号付きマスク、ズーム可能）、切り抜き PNG、SVG（外周と穴、偶奇則、ミリメートル単位に対応）、JSON（穴、面積、ボックス、スコアを含む輪郭）、ラベル PNG（マスクごとに 1 色）。
• マスクはボックスに合わせて切り抜いた状態で保存されるため、候補が数千個ある密な画像でも容量を小さく保てます。

インストール

お使いのコンピューター用のアーカイブを最新リリースからダウンロードします。 maskbolt-v0.1.0-x86_64-pc-windows-msvc.zip、maskbolt-v0.1.0-x86_64-unknown-linux-gnu.tar.gz（glibc 2.35 以降）、maskbolt-v0.1.0-aarch64-apple-darwin.tar.gz、または maskbolt-v0.1.0-x86_64-apple-darwin.tar.gzを使用してください。リリースの SHA256SUMS と照合してから展開し、maskbolt（Windows では maskbolt.exe）を PATH に配置します。maskbolt version を実行すると maskbolt 0.1.0 と表示されます。各アーカイブには、ライセンス、THIRD_PARTY.txt、THIRD_PARTY_NOTICES.md（そのビルドで使用される Rust 依存関係のライセンス文書）も含まれています。または、Rust 1.89 以降でビルドできます。

cargo install --git https://github.com/skulitom/Maskbolt --tag v0.1.0 --locked

Maskbolt は crates.io では公開されていません。

初回実行時にモデルがユーザーキャッシュフォルダーへダウンロードされ、SHA-256 が検証されます。

モデル	フラグ	ダウンロードサイズ	ライセンス
SAM ViT-B (Meta)	デフォルト、--model vit-b	375 MB	Apache-2.0
MobileSAM (TinyViT)	--model tiny	41 MB	Apache-2.0

キャッシュフォルダー：Windows では %LOCALAPPDATA%\maskbolt\models、それ以外では $XDG_CACHE_HOME/maskbolt/models または ~/.cache/maskbolt/models です。別の場所を使うには MASKBOLT_MODEL_DIR を設定してください。maskbolt fetch を実行すると、すぐにダウンロードできます。 Maskbolt は、検証済みの .pth を変換後の safetensors と同じ場所に保存し、変換後のファイルの SHA-256 を <name>.safetensors.sha256 に記録します。ファイルの読み込み時には毎回再検証し、一致しない場合は .pth からファイルを再生成します。 複数の Maskbolt プロセスでフォルダーを共有できます（一意な一時ファイル名とアトミックな名前変更を使用します）。モデルごとのディスク使用量は、チェックポイントと変換後のファイルの合計です（ViT-B は約 750 MB、MobileSAM は約 81 MB）。Rust の最低バージョンは 1.89 です。

CLI

maskbolt cutout examples/chelsea.png --point 200,150 --out cat.png
maskbolt cutout examples/coffee.png --point 300,225 --level largest --fill-holes --out cup-set.png
maskbolt cutout photo.jpg --point 410,220 --exclude 380,300 --box 300,120,520,340 --out thing.png
maskbolt find examples/corn.png --out kernels.json --overlay kernels.png
maskbolt find examples/corn.png --tiles 400 --fill-gaps --out kernels.json --overlay kernels.png
maskbolt find examples/bed.png --grid 12 --min-area 0.01 --max-area 0.3 --drop-hole-views \
    --out offcuts.json --svg offcuts.svg --mm-per-px 0.5
maskbolt mcp --root C:\work\images
maskbolt version

--force を指定しない限り、すでに存在する出力ファイルへの書き込みは拒否されます。入力画像が上書きされることはありません。 1 回の find で使用できるタイルは最大 64 個、グリッドは 48x48 です。これを超える設定では、タイル数と所要時間の目安、および適切なタイルサイズが表示されます。タイル分割した find では画像全体の処理は行われません。タイルの約 3 分の 1 より大きなオブジェクトは除外されるため、大きなオブジェクトを検出する場合は、先に通常の find を実行してください。画像は拡張子ではなく内容に基づいて認識され、EXIF の向きが適用されます。上限は 1 億メガピクセルです。

--level：best（デフォルト。予測 IoU が最も高いもの）、smallest（一部分）、middle（オブジェクト）、largest（中に含まれるものも含めたオブジェクト）。find は JSON レポート（検出数、除外理由、処理時間、未検出領域）を出力します。

MCP

{"mcpServers": {"maskbolt": {"command": "maskbolt", "args": ["mcp", "--root", "C:\\work\\images"]}}}

• **Claude Code：**プラグインは、Claude Code の実行フォルダーをルートとするこのサーバーと、以下のループを実行する maskbolt スキルを登録します。PATH に maskbolt が必要です（「インストール」を参照）。

  claude plugin marketplace add skulitom/Maskbolt
  claude plugin install maskbolt@maskbolt
  

  または、Claude Code 2.1.275 以降では、次の 1 ステップで実行できます：/plugin install maskbolt --marketplace skulitom/Maskbolt。

• **Claude Desktop（Windows x64）：**リリースから maskbolt-windows-x64.mcpb をダウンロードしてダブルクリックするか（Settings > Extensions > Advanced settings > Install Extension）、画像フォルダーを選択します。

• MCP Registry：io.github.skulitom/maskbolt として登録されており、Windows バンドルとその SHA-256 も掲載されています。

時間のかかるタイル分割 find には数分かかります。プラグインは Maskbolt のツールに 10 分のタイムアウトを設定しますが、他のクライアントはそれより早く待機を終了する場合があります（「制限」を参照）。

ツール：maskbolt_open、maskbolt_find、maskbolt_click、maskbolt_view、maskbolt_remove、maskbolt_gaps（add: true を指定すると候補をクリックします）、maskbolt_fill_holes、maskbolt_export。find と view の応答には番号付き PNG が含まれます。click の応答には、新しいマスクの拡大画像が含まれます。サーバーが読み書きするのは --root の内側だけです（デフォルトは起動フォルダーです。ドライブまたはファイルシステムのルート、あるいはホームフォルダーを指定すると起動を拒否します）。ファイルにアクセスする前にパスを検査します。UNC パスおよびデバイスパス（\\server\share、\\?\、\\.\、//host）、別のドライブ、および .. によってルートの外に出るパスは、エラーメッセージとともに拒否されます。エクスポートでは、呼び出しに overwrite: true が指定されない限り既存ファイルを上書きしません。また、開いている画像が上書きされることもありません。view の応答では image_x = region.x + preview_x / scale となります。プレビューの長辺は最大 1568 px です。初回使用時にはモデルがバックグラウンドでダウンロードされます。25 秒以内に完了しない場合、maskbolt_open がサイズを表示し、再度呼び出すよう案内します。

効果的なループ：開く、find（小さいオブジェクトや密集したオブジェクトには tile: 400 を追加）または click を実行する、view（region で拡大する）、誤ったマスクを削除する、見落としたオブジェクトをクリックする、応答に未検出領域が表示された場合は add: true を指定して gaps を実行する、エクスポートする。

速度（Ryzen 9 7950X3D、16 コア、64 GB、CPU のみ、リリースビルド、2026-10-23）

手順	SAM ViT-B	MobileSAM（--model tiny）
モデルの読み込み	0.2 s	0.05-0.2 s
画像 1 枚のエンコード（サイズ不問。SAM は 1024 px で動作）	6.3-6.8 s	4.2-4.3 s
クリック 1 回（デコード + 3 つのマスクのアップサンプリング）	0.11-0.12 s	0.13-0.14 s
cutout を chelsea.png に実行した場合（コマンド全体）	6.8 s、ピーク時 2.0 GB	5.1 s、ピーク時 0.5 GB
find を 1200x1198 の corn.png に 32x32 グリッドで実行	実時間 30.8 s（エンコード後 23.5 s）、228 個のマスク、ピーク時 3.3 GB	実時間 29.4 s、234 個のマスク、ピーク時 3.0 GB
find --tiles 400（25 タイル、各 16x16）	実時間 221 s、247 個のマスク、ピーク時 7.0 GB	未計測
find --tiles 400 --fill-gaps	実時間 246 s、256 個のマスク	未計測

タイルは一度に 4 枚ずつエンコードされます（MASKBOLT_ENCODE_THREADS、デフォルトは 4。各タイルはピーク時に約 1.2 GB を使用します。1 にするとピーク時の使用量は約 3.3 GB、タイル分割した corn の実行時間は 332 s になります）。プロンプトは最大 16 スレッドでデコードされます（MASKBOLT_DECODE_THREADS）。比較として、Node のプロトタイプ（8-bit ONNX）では、corn を 32x32 で実行するのに 199 s、タイル分割では 416 s かかりました。

制限事項

• CPU のみです。時間のかかる処理はエンコードです（ViT-B では画像またはタイル 1 枚あたり約 6.5 s）。この環境では MobileSAM のエンコードに約 4.2 s かかり、わずか 1.5 倍の高速化にとどまります。これは candle の CPU 畳み込み処理が遅いためです。画像 1 枚ではメモリ使用量がピーク時に 2～3.3 GB、4 並列エンコードでタイル分割検索を行うと約 7 GB になります。
• タイル分割検索には時間がかかり、MCP クライアントのツールタイムアウトを超える場合があります（400 px の corn の実行では 25 タイルで 3.5 分かかります。上限の 64 タイルでは約 4～10 分です）。進行状況の通知にはまだ対応していません。
• SAM のマスクでは細い部分が欠落したり、穴が残ったりします。level、追加の包含／除外ポイント、fill_holes を使用してください。
• 輪郭は Douglas-Peucker で簡略化されます（デフォルトは 1.2 px、MCP エクスポートでは simplify_px）。エッジはこの許容誤差の範囲内で移動します。座標は画像の左上を原点とするピクセル単位です（ピクセル x の範囲は [x, x+1]）。
• 隙間の検出には色のヒューリスティックを使用します。新しい種類のオブジェクトではなく、すでにマスクされている対象に似たものを検出します。

ライセンス

MIT。モデルの重み：Apache-2.0（Meta の SAM、MobileSAM）。src/sam_decoder.rs は candle（MIT OR Apache-2.0）を元にしています。candle のライセンステキストは THIRD_PARTY.txt にあります。リリースアーカイブと MCPB バンドルには、そのビルドに含まれるすべての Rust 依存関係のライセンステキストを記載した THIRD_PARTY_NOTICES.md が追加されます。リリースについては、mcpb/PUBLISHING.md を参照してください。