Update SnapForm to version 0.10.10 and add technical documentation

- Bump SnapForm version in uv.lock from 0.9.30 to 0.10.10.
- Introduce comprehensive technical documentation for SnapForm, detailing features, usage instructions, and development guidelines.
This commit is contained in:
2026-08-08 19:05:42 +08:00
parent d08d0e9c1a
commit aee460fe7f
22 changed files with 3905 additions and 1472 deletions

View File

@@ -1,5 +1,4 @@
import importlib.util
import inspect
import json
import os
import sys
@@ -42,27 +41,11 @@ class WorkerTest(unittest.TestCase):
self.assertEqual([path.name for path in images], ["a.jpg", "b.PNG"])
def test_reconstruct_reports_status_before_loading_torch(self):
source = inspect.getsource(self.worker.reconstruct)
self.assertLess(
source.index('"Starting AI runtime"'),
source.index("import torch"),
)
def test_ai_tasks_support_cooperative_cancellation(self):
with self.assertRaises(self.worker.TaskCancelled):
self.worker.check_cancelled(lambda: True)
self.worker.check_cancelled(lambda: False)
self.assertIn(
"cancel_check=cancel_check",
inspect.getsource(self.worker.reconstruct),
)
self.assertIn(
"cancel_check=cancel_check",
inspect.getsource(self.worker.remove_background),
)
def test_select_device_supports_mps_and_auto_fallback(self):
mps_torch = SimpleNamespace(
@@ -115,13 +98,7 @@ class WorkerTest(unittest.TestCase):
with self.assertRaisesRegex(RuntimeError, "MPS was requested"):
self.worker.select_device("mps", cpu_only_torch)
def test_optional_background_removal_runs_before_da3_model_load(self):
source = inspect.getsource(self.worker.reconstruct)
self.assertLess(
source.index("infer_foreground("),
source.index("DepthAnything3.from_pretrained"),
)
def test_reconstruct_parser_accepts_background_model_directory(self):
args = self.worker.parser().parse_args(
[
"reconstruct",
@@ -175,6 +152,199 @@ class WorkerTest(unittest.TestCase):
self.assertEqual(images, [image_path])
self.assertIsNone(temporary_directory)
def test_prepares_a_frame_directory(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
(root / "frame-0001.jpg").touch()
(root / "frame-0002.png").touch()
(root / "notes.txt").touch()
images, temporary_directory = self.worker.prepare_input(
root,
16,
directory,
)
self.assertEqual(
[path.name for path in images],
["frame-0001.jpg", "frame-0002.png"],
)
self.assertIsNone(temporary_directory)
def test_prepares_first_frames_of_a_frame_directory(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
for index in range(1, 6):
(root / f"frame-{index:04d}.jpg").touch()
images, temporary_directory = self.worker.prepare_input(
root,
3,
directory,
)
self.assertEqual(
[path.name for path in images],
["frame-0001.jpg", "frame-0002.jpg", "frame-0003.jpg"],
)
self.assertIsNone(temporary_directory)
def test_prepares_first_frames_after_offset_in_a_frame_directory(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
for index in range(1, 6):
(root / f"frame-{index:04d}.jpg").touch()
images, temporary_directory = self.worker.prepare_input(
root,
3,
directory,
start_frame=2,
)
self.assertEqual(
[path.name for path in images],
["frame-0002.jpg", "frame-0003.jpg", "frame-0004.jpg"],
)
self.assertIsNone(temporary_directory)
def test_extract_video_frames_reads_frames_sequentially(self):
class FakeCapture:
def __init__(self):
self.position = 0
def isOpened(self):
return True
def read(self):
if self.position >= 100:
return False, None
frame = self.position
self.position += 1
return True, frame
def release(self):
return None
class FakeCv2:
def __init__(self):
self.captures = []
def VideoCapture(self, _path):
capture = FakeCapture()
self.captures.append(capture)
return capture
def imwrite(self, path, frame):
Path(path).write_text(str(frame), encoding="utf-8")
return True
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
fake_cv2 = FakeCv2()
image_paths = self.worker.extract_video_frames(
root / "clip.mkv",
root / "out",
10,
fake_cv2,
)
self.assertEqual(
[path.name for path in image_paths],
[f"frame.{index:04d}.jpg" for index in range(1, 11)],
)
self.assertEqual(len(fake_cv2.captures), 1)
self.assertEqual(fake_cv2.captures[0].position, 10)
def test_extract_video_frames_starts_after_offset(self):
class FakeCapture:
def __init__(self):
self.position = 0
def isOpened(self):
return True
def read(self):
if self.position >= 100:
return False, None
frame = self.position
self.position += 1
return True, frame
def release(self):
return None
class FakeCv2:
def __init__(self):
self.captures = []
def VideoCapture(self, _path):
capture = FakeCapture()
self.captures.append(capture)
return capture
def imwrite(self, path, frame):
Path(path).write_text(str(frame), encoding="utf-8")
return True
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
fake_cv2 = FakeCv2()
image_paths = self.worker.extract_video_frames(
root / "clip.mkv",
root / "out",
10,
fake_cv2,
start_frame=71,
)
extracted = [
Path(path).read_text(encoding="utf-8")
for path in image_paths
]
self.assertEqual(extracted, [str(frame) for frame in range(70, 80)])
self.assertEqual(fake_cv2.captures[0].position, 80)
def test_extract_video_frames_tolerates_short_video_tail(self):
class ShortCapture:
def __init__(self):
self.position = 0
def isOpened(self):
return True
def read(self):
if self.position >= 99:
return False, None
frame = self.position
self.position += 1
return True, frame
def release(self):
return None
class FakeCv2:
def VideoCapture(self, _path):
return ShortCapture()
def imwrite(self, path, frame):
Path(path).write_text(str(frame), encoding="utf-8")
return True
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
image_paths = self.worker.extract_video_frames(
root / "clip.mkv",
root / "out",
10,
FakeCv2(),
)
self.assertEqual(
[path.name for path in image_paths],
[f"frame.{index:04d}.jpg" for index in range(1, 11)],
)
def test_npz_is_complete_requires_readable_archive(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
@@ -235,10 +405,6 @@ class WorkerTest(unittest.TestCase):
self.worker,
"create_download_progress_class",
return_value=object,
), patch.object(
self.worker,
"resolve_hf_endpoint",
return_value=(self.worker.HF_ENDPOINT, False),
):
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
@@ -248,13 +414,17 @@ class WorkerTest(unittest.TestCase):
calls[0]["allow_patterns"],
["config.json", "model.safetensors"],
)
self.assertEqual(calls[0]["endpoint"], self.worker.HF_ENDPOINT)
def test_download_model_switches_to_mirror_before_hf_import(self):
def test_download_model_falls_back_to_modelscope_when_direct_fails(self):
calls = []
fake_hugging_face = ModuleType("huggingface_hub")
fake_hugging_face.snapshot_download = lambda **options: calls.append(
options
)
def fake_snapshot_download(**options):
calls.append(options)
raise OSError("Connection reset by peer")
fake_hugging_face.snapshot_download = fake_snapshot_download
args = SimpleNamespace(
repository="PramaLLC/BEN2",
model_dir="model",
@@ -269,23 +439,151 @@ class WorkerTest(unittest.TestCase):
self.worker,
"create_download_progress_class",
return_value=object,
), patch.object(
self.worker,
"resolve_hf_endpoint",
return_value=("https://hf-mirror.com", True),
), patch.dict(os.environ, {"HF_ENDPOINT": ""}), patch.object(
self.worker,
"write_status",
) as mocked_write:
"download_from_modelscope",
) as mocked_modelscope:
def fake_download_from_modelscope(*args, **kwargs):
model_dir = Path(args[1])
model_dir.mkdir(parents=True, exist_ok=True)
(model_dir / "config.json").write_text("{}")
(model_dir / "model.safetensors").write_bytes(b"x")
mocked_modelscope.side_effect = fake_download_from_modelscope
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
self.worker.download_model(args)
self.assertEqual(
os.environ["HF_ENDPOINT"],
"https://hf-mirror.com",
)
messages = [call.args[2] for call in mocked_write.call_args_list]
self.assertTrue(any("(mirror)" in message for message in messages))
self.assertEqual(len(calls), 1)
self.assertEqual(calls[0]["endpoint"], self.worker.HF_ENDPOINT)
self.assertEqual(mocked_modelscope.call_count, 1)
def test_download_model_skips_unreachable_endpoint(self):
calls = []
fake_hugging_face = ModuleType("huggingface_hub")
fake_hugging_face.snapshot_download = lambda **options: calls.append(
options
)
args = SimpleNamespace(
repository="depth-anything/DA3-SMALL",
model_dir="model",
status="status.json",
allow_pattern=[],
)
with tempfile.TemporaryDirectory() as directory, patch.dict(
sys.modules,
{"huggingface_hub": fake_hugging_face},
), patch.object(
self.worker,
"create_download_progress_class",
return_value=object,
), patch.dict(os.environ, {"HF_ENDPOINT": ""}), patch.object(
self.worker,
"hf_endpoint_reachable",
return_value=False,
), patch.object(
self.worker,
"download_from_modelscope",
) as mocked_modelscope, patch.object(
self.worker,
"_verify_model_complete",
return_value=None,
):
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
self.worker.download_model(args)
self.assertEqual(calls, [])
self.assertEqual(mocked_modelscope.call_count, 1)
def test_download_model_refuses_success_when_files_missing(self):
fake_hugging_face = ModuleType("huggingface_hub")
fake_hugging_face.snapshot_download = lambda **options: None
args = SimpleNamespace(
repository="PramaLLC/BEN2",
model_dir="model",
status="status.json",
allow_pattern=[],
)
with tempfile.TemporaryDirectory() as directory, patch.dict(
sys.modules,
{"huggingface_hub": fake_hugging_face},
), patch.object(
self.worker,
"create_download_progress_class",
return_value=object,
), patch.dict(os.environ, {"HF_ENDPOINT": ""}), patch.object(
self.worker,
"download_from_modelscope",
):
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
with self.assertRaisesRegex(
RuntimeError,
"All download sources failed",
):
self.worker.download_model(args)
def test_download_model_reports_all_failed_sources(self):
fake_hugging_face = ModuleType("huggingface_hub")
def fake_snapshot_download(**options):
raise OSError("direct down")
fake_hugging_face.snapshot_download = fake_snapshot_download
args = SimpleNamespace(
repository="depth-anything/DA3-SMALL",
model_dir="model",
status="status.json",
allow_pattern=[],
)
with tempfile.TemporaryDirectory() as directory, patch.dict(
sys.modules,
{"huggingface_hub": fake_hugging_face},
), patch.object(
self.worker,
"create_download_progress_class",
return_value=object,
), patch.dict(os.environ, {"HF_ENDPOINT": ""}), patch.object(
self.worker,
"download_from_modelscope",
side_effect=OSError("mirror down"),
):
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
with self.assertRaisesRegex(RuntimeError, "modelscope.cn"):
self.worker.download_model(args)
def test_download_from_modelscope_downloads_selected_files(self):
args = SimpleNamespace(
repository="depth-anything/DA3-SMALL",
model_dir="model",
status="status.json",
allow_pattern=["config.json"],
)
downloaded = []
with tempfile.TemporaryDirectory() as directory, patch.object(
self.worker,
"modelscope_file_list",
return_value=[
("config.json", 100),
("model.safetensors", 200),
(".gitattributes", 10),
],
), patch.object(
self.worker,
"_download_modelscope_file",
side_effect=lambda *args, **kwargs: downloaded.append(args[1]),
), patch.object(self.worker, "write_status"):
args.model_dir = str(Path(directory) / "model")
args.status = str(Path(directory) / "status.json")
self.worker.download_from_modelscope(args, args.model_dir)
self.assertEqual(downloaded, ["config.json"])
def test_ben2_background_removal_writes_fast_transparent_png(self):
inference_options = []
@@ -368,6 +666,166 @@ class WorkerTest(unittest.TestCase):
)
self.assertIn("Background removed in", status["message"])
def test_ben2_background_removal_processes_each_frame(self):
inference_options = []
class FakeImage:
def __enter__(self):
return self
def __exit__(self, *_args):
return None
def convert(self, mode):
self.mode = mode
return self
def save(self, path, **options):
Path(path).touch()
class FakeModel:
@classmethod
def from_pretrained(cls, model_dir):
return cls()
def to(model_self, device):
return model_self
def eval(self):
return None
def inference(self, image, **options):
inference_options.append((image, options))
return FakeImage()
fake_torch = ModuleType("torch")
fake_torch.cuda = SimpleNamespace(
is_available=lambda: False,
synchronize=lambda: None,
)
fake_torch.device = lambda device_type: SimpleNamespace(type=device_type)
fake_torch.inference_mode = nullcontext
fake_ben2 = ModuleType("ben2")
fake_ben2.BEN_Base = FakeModel
fake_pil = ModuleType("PIL")
fake_pil.Image = SimpleNamespace(open=lambda _path: FakeImage())
with tempfile.TemporaryDirectory() as directory, patch.dict(
sys.modules,
{
"torch": fake_torch,
"ben2": fake_ben2,
"PIL": fake_pil,
},
):
root = Path(directory)
input_directory = root / "frames"
input_directory.mkdir()
(input_directory / "frame-0001.jpg").touch()
(input_directory / "frame-0002.jpg").touch()
args = SimpleNamespace(
input=str(input_directory),
model_dir="model",
output_dir=str(root / "result"),
status=str(root / "status.json"),
device="cpu",
video_frames=8,
)
self.worker.remove_background(args)
result_directory = Path(args.output_dir)
self.assertTrue(
(result_directory / "foreground.0001.png").is_file()
)
self.assertTrue(
(result_directory / "foreground.0002.png").is_file()
)
self.assertTrue(
(result_directory / "frame.0001.jpg").is_file()
)
self.assertTrue(
(result_directory / "frame.0002.jpg").is_file()
)
self.assertEqual(len(inference_options), 2)
for _image, options in inference_options:
self.assertEqual(options, {"refine_foreground": False})
def test_remove_background_parser_accepts_video_frames(self):
args = self.worker.parser().parse_args(
[
"remove-background",
"--input",
"input.mp4",
"--model-dir",
"ben2",
"--output-dir",
"result",
"--status",
"status.json",
"--device",
"auto",
"--video-frames",
"24",
]
)
self.assertEqual(args.command, "remove-background")
self.assertEqual(args.video_frames, 24)
def test_extract_frames_parser_accepts_frame_range(self):
args = self.worker.parser().parse_args(
[
"extract-frames",
"--input",
"frames",
"--output-dir",
"result",
"--status",
"status.json",
"--video-frames",
"24",
"--start-frame",
"70",
]
)
self.assertEqual(args.command, "extract-frames")
self.assertEqual(args.video_frames, 24)
self.assertEqual(args.start_frame, 70)
def test_extract_frames_copies_selected_frames(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
input_directory = root / "frames"
input_directory.mkdir()
for index in range(1, 6):
(input_directory / f"frame-{index:04d}.jpg").touch()
args = SimpleNamespace(
input=str(input_directory),
output_dir=str(root / "result"),
status=str(root / "status.json"),
video_frames=3,
start_frame=2,
)
self.worker.extract_frames(args)
result_directory = Path(args.output_dir)
self.assertEqual(
sorted(
path.name
for path in result_directory.iterdir()
if path.is_file()
),
["frame.0001.jpg", "frame.0002.jpg", "frame.0003.jpg"],
)
status = json.loads(
Path(args.status).read_text(encoding="utf-8")
)
self.assertEqual(status["progress"], 1.0)
self.assertIn("3 frame", status["message"])
def test_uses_official_da3_export_parameters_for_all_four_formats(self):
inference_options = []
export_calls = []
@@ -500,6 +958,95 @@ class WorkerTest(unittest.TestCase):
infer_gs_values = [options["infer_gs"] for _, options in inference_options]
self.assertEqual(infer_gs_values, [False, True, False, False])
def test_reconstruct_copies_frames_for_multi_frame_input(self):
class FakeModel:
@classmethod
def from_pretrained(cls, model_dir):
return cls()
def to(self, device):
return self
def eval(self):
return None
def inference(self, images, **options):
return SimpleNamespace()
def fake_export(prediction, export_format, export_dir, **options):
mini_directory = Path(export_dir) / "exports" / "mini_npz"
mini_directory.mkdir(parents=True)
np.savez_compressed(
mini_directory / "results.npz",
depth=np.zeros((2, 14, 14)),
)
fake_torch = ModuleType("torch")
fake_torch.device = lambda device_type: SimpleNamespace(
type=device_type,
)
fake_torch.inference_mode = nullcontext
fake_api = ModuleType("depth_anything_3.api")
fake_api.DepthAnything3 = FakeModel
fake_export_module = ModuleType("depth_anything_3.utils.export")
fake_export_module.export = fake_export
fake_utils = ModuleType("depth_anything_3.utils")
fake_utils.__path__ = []
fake_package = ModuleType("depth_anything_3")
fake_package.__path__ = []
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
input_directory = root / "frames"
input_directory.mkdir()
(input_directory / "frame-0001.jpg").touch()
(input_directory / "frame-0002.jpg").touch()
with patch.dict(
sys.modules,
{
"torch": fake_torch,
"depth_anything_3": fake_package,
"depth_anything_3.api": fake_api,
"depth_anything_3.utils": fake_utils,
"depth_anything_3.utils.export": fake_export_module,
},
):
args = SimpleNamespace(
input=str(input_directory),
video_frames=16,
output_dir=str(root / "result"),
export_format="mini_npz",
status=str(root / "status.json"),
device="cpu",
model_dir="model",
process_res=518,
process_res_method="upper_bound_resize",
use_ray_pose=1,
ref_view_strategy="first",
conf_thresh_percentile=40.0,
num_max_points=1000,
show_cameras=0,
gs_views_interval=1,
remove_background_model_dir="",
)
self.worker.reconstruct(args)
result_directory = Path(args.output_dir)
self.assertTrue(
(result_directory / "frame.0001.jpg").is_file()
)
self.assertTrue(
(result_directory / "frame.0002.jpg").is_file()
)
self.assertTrue(
(result_directory / "results.npz").is_file()
)
self.assertFalse(
(result_directory / "exports").exists()
)
status = json.loads(Path(args.status).read_text(encoding="utf-8"))
self.assertEqual(status["progress"], 1.0)
if __name__ == "__main__":
unittest.main()