SAM2Cut 是一个基于 Meta Segment Anything 2 / SAM2.1 的本地 Web 抠图工具，面向图片透明抠图和视频对象追踪抠图。当前版本使用 FastAPI + HTML Canvas 实现交互标注。
核心流程是：上传素材、初始化 SAM2、用点选或框选标注对象、追踪并预览、在问题帧补标、满意后导出透明素材。
- 图片抠图：前景点、背景点、拖拽框选、多对象、按对象导出透明 PNG。
- 视频抠图：点选、框选、多对象、按帧补标、增量追踪、浏览器视频预览。
- 对象管理：新增对象、删除当前对象、删除当前帧当前对象提示、清空全部。
- 预览质检：右侧状态日志、当前对象摘要、本帧点/框数量、追踪后 MP4 预览。
- 导出格式：图片 PNG；视频 PNG 序列 ZIP、GIF、WebM alpha、MOV HEVC alpha、MOV ProRes 4444 alpha、MP4 H.264 无透明。
- 视频导出可选择输出格式、码率、输出缩放、原始尺寸/裁剪/最大宽度策略。
- 设备支持：
auto、cuda、mps、cpu。 - 权重加载：优先使用本地
checkpoints/，缺失时可走 Hugging Face fallback。
.
├── sam2_image_canvas_app.py # 主入口：FastAPI + Canvas Web 版
├── sam2cut_core.py # SAM2 加载、渲染、追踪、导出核心函数
├── check_env.py # 环境检查
├── requirements.txt
├── README.md
├── checkpoints/ # 本地权重目录，不建议提交
└── sam2/ # 本地 SAM2 源码目录，不建议提交
- Python 3.10
- PyTorch / torchvision
- SAM2 Python 包
- FastAPI、Uvicorn、OpenCV、Pillow、NumPy、tqdm、Hugging Face Hub
ffmpeg：用于视频转码、WebM/MOV/MP4 导出和预览视频编码。
Apple Silicon 可用 mps，但速度和结果可能与 CUDA 有差异。长视频建议使用 CUDA。
创建环境：
conda create -n sam2cut python=3.10 -y
conda activate sam2cut安装 PyTorch。请按你的平台选择官方命令，下面只是示例：
pip install torch torchvision安装项目依赖：
pip install -r requirements.txt安装 SAM2：
git clone https://github.com/facebookresearch/sam2.git
cd sam2
pip install -e .
cd ..安装 ffmpeg：
# Conda / Anaconda，推荐在当前环境内安装
conda install -c conda-forge ffmpeg
# macOS
brew install ffmpeg
# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y ffmpeg检查环境：
python check_env.py可以把 SAM2.1 权重放到 checkpoints/：
mkdir -p checkpoints
curl -L -o checkpoints/sam2.1_hiera_tiny.pt \
https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_tiny.pt
curl -L -o checkpoints/sam2.1_hiera_small.pt \
https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_small.pt
curl -L -o checkpoints/sam2.1_hiera_base_plus.pt \
https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_base_plus.pt权重文件较大，默认应被 .gitignore 忽略，不建议提交到 GitHub。
推荐入口：
SAM2_DEVICE=mps python sam2_image_canvas_app.py其他设备：
SAM2_DEVICE=auto python sam2_image_canvas_app.py
SAM2_DEVICE=cuda python sam2_image_canvas_app.py
SAM2_DEVICE=cpu python sam2_image_canvas_app.py浏览器打开：
图片抠图：http://127.0.0.1:7862/
视频抠图：http://127.0.0.1:7862/video
如需换端口：
SAM2_IMAGE_PORT=7870 SAM2_DEVICE=mps python sam2_image_canvas_app.py- 打开
http://127.0.0.1:7862/。 - 上传图片，选择模型和设备，点击
初始化图片。 - 使用
点选添加前景点或背景点。 - 使用
框选时，按住鼠标拖出矩形，松开后提交。 - 需要新对象时点击
新增对象。 - 可用
删除当前对象删除当前对象 ID 的点和框。 - 如只导出部分对象，在
保留对象填写1,3这类 ID 列表。 - 点击
导出 PNG，浏览器会触发下载。
- 打开
http://127.0.0.1:7862/video。 - 上传视频，选择模型和设备，点击
初始化视频。 - 在当前帧用点选或框选标注目标。
- 点击
追踪，右侧会生成 MP4 追踪预览。 - 发现问题帧后，用帧滑块跳转到该帧。
- 继续对当前对象补点或补框，再次点击
追踪。 - 需要修掉某一帧的错误提示时，点击
删除本帧当前对象提示。 - 需要移除整个对象时，点击
删除当前对象。 - 如只导出部分对象，在
保留对象填写对象 ID。 - 选择导出格式、尺寸处理和视频码率。
- 点击
导出，右侧会显示可下载文件。
image_cutout.png：单张图片透明 PNG。transparent_png_frames.zip：视频透明 PNG 序列。cutout_preview.gif：GIF 预览，透明质量受 GIF 格式限制。cutout_alpha.webm：VP9 alpha 视频，需要ffmpeg。cutout_alpha_hevc.mov：HEVC alpha 视频，文件通常比 ProRes 小，主要适合 macOS / iOS / Apple 生态，需要ffmpeg的hevc_videotoolbox支持。cutout_alpha_prores4444.mov：ProRes 4444 alpha 视频，体积大，但后期软件兼容性和透明质量最好，需要ffmpeg。cutout_preview_h264.mp4：H.264 MP4 兼容版，不保留透明通道，透明区域会合成为黑底。
视频导出参数：
尺寸处理：原始尺寸：保持输入视频尺寸。按 mask 外接框裁剪：按所有追踪 mask 的总体外接框裁剪，可设置裁剪边距。限制最大宽度：保持全画面，只按最大宽度等比缩放。裁剪后限制最大宽度：先裁剪，再按最大宽度等比缩放。
输出缩放：提供100%、75%、50%、25%。这是最直接的体积控制方式，分辨率减半通常会显著降低 WebM、MP4、GIF、PNG 序列和 MOV 的体积。最大宽度：在输出缩放后再做宽度上限限制，适合明确要导出 720p、1080p 等宽度的场景。码率方案：提供小体积 2M、标准 4M、高质量 8M、超高质量 16M、编码器默认和自定义。自定义值会传给 ffmpeg 的-b:v，例如6M、12000k。预计文件大小：按视频时长和码率粗略估算，实际大小会受透明通道、画面复杂度、编码器策略和所选格式影响。ProRes 通常远大于 WebM/HEVC/MP4。
通常是从 SAM2 仓库父目录运行导致包名冲突。当前工具已做路径修正，但仍建议：
- 在本项目根目录运行。
- 确认
sam2/已执行pip install -e .。 - 不要从
sam2源码目录的父目录直接导入未安装包。
通常是 ffmpeg 未安装或不在 PATH。安装后重启程序。
MOV HEVC Alpha 依赖 Apple VideoToolbox 的 HEVC alpha 编码能力；如果该格式失败，仍可导出 WebM alpha、MOV ProRes 4444 或 PNG 序列。
GIF 只有索引透明，不支持高质量半透明 alpha。正式视频合成建议用 WebM alpha、MOV HEVC alpha、MOV ProRes 4444 或 PNG 序列。MP4 H.264 不支持透明，只适合预览或普通平台分发。
MPS 可用，但 SAM2 在 CUDA 上通常更稳。MPS/CPU 下建议先用 tiny 或 small 模型验证流程。