SAM2Inpaint 是一个本地运行的图片/视频修复工具，基于当前 SAM2Cut 工作区扩展而来。它复用 SAM2 的点选/框选能力生成 mask，然后把 mask 交给修复后端完成内容填补。
支持的修复后端：
- 图片：LaMa、OpenCV Telea、OpenCV NS。
- 视频：ProPainter、STTN、LaMa 逐帧、OpenCV Telea。
这个工具的定位是本地优先：通过 FastAPI 启动本地 Web 服务，浏览器中完成交互，任务会话保存在当前进程内，运行时帧、mask 和输出结果写入本地目录。
- 图片修复：支持点选和框选生成修复区域。
- 视频修复：支持两种选择模式：
- 固定框选：不初始化 SAM2 视频状态，只加载视频并拖拽一个固定矩形，适合固定位置水印、台标、字幕和静态遮挡。
- 智能选择：初始化 SAM2 视频状态，通过点选/框选提示目标，再在指定帧范围内追踪 mask。
- LaMa 已改为进程内 API 调用，支持原尺寸输入和实时进度回调。
- STTN 已改为进程内 API 调用，支持滑动窗口进度回调，并可在界面调整
neighbor_stride/ref_length。 - ProPainter 作为推荐的视频高质量后端接入，支持宽高、FP16、邻近帧、参考帧和子视频长度参数。
- 视频修复过程中会实时展示当前修复帧，方便发现效果不对时立即停止。
- 界面内置停止当前任务、清理旧进程、关闭所有相关进程和进程监控。
- 支持导出 MP4/GIF，并可下载修复输入帧和 mask 的调试 ZIP。
SAM2Inpaint/
├── sam2inpaint_app.py # FastAPI 服务和浏览器界面
├── sam2inpaint_core.py # 修复流程、帧导出、视频合成
├── lama_api.py # LaMa 进程内推理适配器
├── sttn_api.py # STTN 进程内推理适配器
├── config.py # .env 配置加载
├── check_env.py # 环境检查脚本
├── check_lama_import.py # LaMa 导入检查脚本
├── install_external_models.sh
├── run_inpaint.sh
├── requirements.txt
├── .env.example
└── models/ # 外部模型源码和权重占位说明
当前版本默认作为 SAM2Cut 工作区的一部分运行，需要父目录保留：
../sam2cut_core.py
../sam2/
../checkpoints/ # 可选，本地 SAM2 权重；没有时可按原项目逻辑走 HF fallback
本仓库可以包含 LaMa/STTN 源码快照，但不包含模型权重。
.gitignore 已排除：
SAM2Inpaint/.envSAM2Inpaint/__pycache__/SAM2Inpaint/models/lama-src/.git/SAM2Inpaint/models/lama-src/outputs/SAM2Inpaint/models/sttn-src/.git/SAM2Inpaint/models/sttn-src/checkpoints/*.pt、*.pth、*.ckpt、*.safetensors- 视频、GIF、ZIP 和运行输出目录
上传前建议检查：
git status --short
find SAM2Inpaint -type f -size +10M -print如果看到 .env、权重文件、运行输出、缓存文件或嵌套 .git，不要提交。
在 SAM2Cut 使用的 Python 环境中安装基础依赖：
pip install -r SAM2Inpaint/requirements.txt还需要 PyTorch、SAM2 和 ffmpeg。PyTorch 的安装方式取决于你的系统和设备，例如 CUDA、MPS 或 CPU。
检查环境：
python SAM2Inpaint/check_env.py复制配置模板：
cp SAM2Inpaint/.env.example SAM2Inpaint/.env示例配置：
SAM2_INPAINT_HOST=127.0.0.1
SAM2_INPAINT_PORT=7863
SAM2_DEVICE=mps
SAM2_MODEL_VARIANT=sam2.1_hiera_base_plus
SAM2_CHECKPOINT_DIR=../checkpoints
SAM2_INPAINT_OUTPUT=/tmp/sam2_inpaint_outputs
SAM2_INPAINT_IMAGE_BACKEND=lama
SAM2_INPAINT_VIDEO_BACKEND=propainter
LAMA_REPO=/absolute/path/to/lama-src
LAMA_MODEL=/absolute/path/to/big-lama
LAMA_DEVICE=mps
STTN_REPO=/absolute/path/to/sttn-src
STTN_MODEL=/absolute/path/to/sttn-src/checkpoints/sttn.pth
STTN_DEVICE=mps
STTN_NEIGHBOR_STRIDE=5
STTN_REF_LENGTH=10
PROPAINTER_REPO=/absolute/path/to/ProPainter
PROPAINTER_WIDTH=-1
PROPAINTER_HEIGHT=-1
PROPAINTER_FP16=1
PROPAINTER_NEIGHBOR_LENGTH=10
PROPAINTER_REF_STRIDE=10
PROPAINTER_SUBVIDEO_LENGTH=80
常用设备值：
mps
cuda
cpu
auto
在工作区根目录运行：
bash SAM2Inpaint/run_inpaint.sh也可以直接启动：
SAM2_DEVICE=mps python SAM2Inpaint/sam2inpaint_app.py浏览器打开：
图片修复：http://127.0.0.1:7863/
视频修复：http://127.0.0.1:7863/video
修改端口：
SAM2_INPAINT_PORT=7873 python SAM2Inpaint/sam2inpaint_app.pyLaMa 通过 lama_api.py 在当前 Python 进程内调用，不再使用外部命令模板黑箱调用。
需要的文件：
${LAMA_REPO}/bin/predict.py
${LAMA_MODEL}/config.yaml
${LAMA_MODEL}/models/best.ckpt
处理方式：
- 图片和 mask 以原始尺寸输入。
- 仅启用
pad_out_to_modulo=8作为网络所需 padding。 - 不主动缩放输入图像。
- 输出尺寸会和原图尺寸校验，不一致会直接报错，避免静默产生降质结果。
- 视频模式下 LaMa 是逐帧修复，适合固定水印、小范围遮挡等场景，但不保证时序一致性。
ProPainter 是当前推荐的视频高质量后端。SAM2Inpaint 会先把当前修复片段和 mask 编码成 ProPainter 输入，再通过受控进程调用 ProPainter 官方 inference_propainter.py，运行过程中扫描输出帧用于实时预览。
需要的文件：
${PROPAINTER_REPO}/inference_propainter.py
权重和依赖请按 ProPainter 官方仓库自行安装；SAM2Inpaint 不下载、不提交 ProPainter 权重。
可调参数：
PROPAINTER_WIDTH/PROPAINTER_HEIGHT：处理分辨率，-1表示交给 ProPainter 默认逻辑。PROPAINTER_FP16：是否启用 FP16，通常能显著降低显存占用。PROPAINTER_NEIGHBOR_LENGTH：邻近帧长度。PROPAINTER_REF_STRIDE：参考帧间隔。PROPAINTER_SUBVIDEO_LENGTH：子视频长度，用于降低长视频显存压力。PROPAINTER_MASK_DILATION：mask 膨胀。PROPAINTER_RAFT_ITER：光流迭代次数。
注意：ProPainter 质量通常优于 STTN，但不是“任意分辨率无成本”。分辨率、帧数、参考帧数量都会增加显存压力。固定框选和按 mask 外接框裁剪仍然很重要。
STTN 通过 sttn_api.py 在当前 Python 进程内调用。
需要的文件：
${STTN_REPO}/model/sttn.py
${STTN_MODEL}
滑动窗口参数：
neighbor_stride：当前窗口前后邻近帧跨度。值越小，通常参考更充分，但设备压力更大。ref_length：全局参考帧采样间隔。值越小，可能提升一致性，但设备压力更大。
限制：
当前接入的 researchmm/STTN 原始实现内部固定使用 432x240 推理。SAM2Inpaint 会把修复片段拼回原视频分辨率，并且只替换 mask 区域；但 mask 区域本身仍受 STTN 低分辨率推理限制影响。
OpenCV Telea/NS 是轻量兜底方案，不需要额外模型权重。它速度快、配置简单，但复杂运动视频中容易闪烁，修复质量通常不如深度模型。
辅助脚本可以下载 LaMa 和 STTN 源码：
bash SAM2Inpaint/install_external_models.sh模型权重需要手动放置：
SAM2Inpaint/models/big-lama/
SAM2Inpaint/models/sttn-src/checkpoints/sttn.pth
如果源码或权重放在其他位置，请在 .env 中设置：
LAMA_REPO
LAMA_MODEL
STTN_REPO
STTN_MODEL
- 打开图片修复页面。
- 上传图片并初始化 SAM2。
- 用点选或框选标出要修复的区域。
- 选择 LaMa、OpenCV Telea 或 OpenCV NS。
- 点击修复并下载结果。
- 打开视频修复页面。
- 上传视频。
- 选择
固定框选或智能选择。 - 固定框选：
- 只加载视频信息和首帧。
- 不初始化 SAM2 视频状态。
- 在画布上拖拽矩形，并应用到指定帧范围。
- 可以直接点击确认修复。
- 智能选择：
- 初始化 SAM2 视频状态。
- 在某一帧上添加点选或框选提示。
- 在指定帧范围内追踪 mask。
- 如果追踪偏移，切换到出错帧继续补点/补框，再从该帧重新追踪。
- 选择 ProPainter、STTN、LaMa 逐帧或 OpenCV Telea。
- 修复过程中观察实时修复帧，效果不对可以立即停止。
- 下载 MP4/GIF 或调试用输入帧/mask ZIP。
视频页面底部提供：
- 停止当前任务。
- 清理旧的相关 worker 进程。
- 关闭所有相关进程，包括当前 Web 服务。
- 实时进程监控，显示 PID、父 PID、CPU、内存、RSS、运行时长和命令。
这些控制用于避免本地 AI 进程被遗忘后持续占用 CPU/GPU/内存。
页面：
GET /
GET /video
进程控制：
GET /api/processes
POST /api/processes/cleanup
POST /api/processes/kill_all
POST /api/video/stop
图片接口包含初始化、提示、清空、修复、结果和下载。视频接口包含初始化、帧导航、智能提示、固定框 mask、追踪、修复任务状态、结果和下载。
check_env.py提示缺少LAMA_REPO或STTN_REPO：检查.env，或先使用 OpenCV 后端。check_env.py提示缺少PROPAINTER_REPO：未配置 ProPainter，选择 STTN/LaMa/OpenCV 或配置 ProPainter 源码路径。- 视频修复自动 fallback 到 OpenCV：所选外部后端未配置或执行失败。
- ProPainter 显存不够：降低处理宽高、启用 FP16、增大
subvideo_length控制策略，或改用 LaMa/OpenCV。 - STTN 修复区域发软：当前 STTN 实现内部推理尺寸为
432x240，这是模型实现限制。 - LaMa 视频有闪烁：LaMa 是图片模型逐帧处理，不提供时序一致性。
- 端口被占用：修改
SAM2_INPAINT_PORT，或使用进程监控关闭旧进程。 - 重启后会话消失：当前会话保存在 FastAPI 进程内，重启服务后不会保留。
本目录包含 SAM2Inpaint 的适配和界面代码。SAM2、LaMa、STTN 等外部项目及其模型权重有各自的许可证和使用限制，请以对应官方仓库为准。本仓库不包含大模型权重。