feat: add seconds-based Occlusion.during_seconds() schedule (#19)

Adds a seconds-based occlusion schedule alongside the frame-based .during(). Closes #15.

Author: Nitjsefnie

src/multicam_sim/dsl/builder.py

@@ -78,6 +78,13 @@ def build(self) -> Scene:
 
         occluders: list[OccluderUnion] = []
         for occ in self._occlusions:
+            if occ.frames is not None and occ.seconds is not None:
+                raise ValueError("occlusion has both frames and seconds windows; use one schedule")
+            if occ.seconds is not None:
+                t0, t1 = occ.seconds
+                f0 = int(round(t0 * self.fps))
+                f1 = int(round(t1 * self.fps))
+                occ = occ.model_copy(update={"frames": (f0, f1), "seconds": None})
             target_id = occ.entity if occ.entity is not None else self._entities[0].id
             if target_id not in frames_by_id:
                 raise ValueError(f"occlusion targets unknown entity {target_id!r}")

src/multicam_sim/dsl/occlusion.py

@@ -49,6 +49,7 @@ class Occlusion(BaseModel):
     offset: float = 0.15  # fraction from the point toward the camera centre
     camera: int | None = None
     frames: tuple[int, int] | None = None
+    seconds: tuple[float, float] | None = None
     entity: str | None = None  # default: the scene's first entity
     point_name: str = "center"
 
@@ -81,11 +82,25 @@ def blocks(self, camera: int) -> Occlusion:
 
     def during(self, frames: tuple[int, int]) -> Occlusion:
         """Aim the occlusion at the frame window ``(frame0, frame1)`` inclusive."""
+        if self.seconds is not None:
+            raise ValueError("occlusion already has a seconds window; use .during_seconds(...)")
         f0, f1 = frames
         if f0 > f1:
             raise ValueError("during(frames): frame0 must be <= frame1")
         return self.model_copy(update={"frames": frames})
 
+    def during_seconds(self, t0: float, t1: float) -> Occlusion:
+        """Aim the occlusion at the seconds window ``(t0, t1)`` inclusive.
+
+        The window is converted to frames by :meth:`SceneBuilder.build` using the
+        scene ``fps``, rounding to the nearest frame.
+        """
+        if self.frames is not None:
+            raise ValueError("occlusion already has a frames window; use .during(...)")
+        if t0 > t1:
+            raise ValueError("during_seconds(t0, t1): t0 must be <= t1")
+        return self.model_copy(update={"seconds": (t0, t1)})
+
     def on(self, entity: str, point_name: str = "center") -> Occlusion:
         """Target a named entity/point (default: first entity, point ``center``)."""
         return self.model_copy(update={"entity": entity, "point_name": point_name})

tests/test_dsl_scene.py

@@ -172,3 +172,54 @@ def mid_occ_frac(coverage: float) -> float:
     fracs = [mid_occ_frac(c) for c in (0.5, 1.0, 2.0)]
     assert fracs == sorted(fracs)  # monotonic non-decreasing
     assert fracs[-1] > 0.0
+
+
+def _scene_with_occlusion(occ: Occlusion, *, num_frames: int = 50) -> dict:
+    scene = (
+        SceneBuilder(fps=30.0, num_frames=num_frames)
+        .cameras(
+            CameraRig.ring(
+                n=3,
+                radius=4.0,
+                height=1.5,
+                look_at=(0.0, 0.0, 0.5),
+                focal=800.0,
+                width=640,
+                height_px=480,
+            )
+        )
+        .entity("obj", Path.linear((0.0, -0.6, 0.5), (0.0, 0.6, 0.5)))
+        .occlude(occ)
+        .build()
+    )
+    return build_manifest(scene)
+
+
+def test_during_seconds_matches_during_frames() -> None:
+    """seconds window (0.5, 1.5) @ 30fps rounds to frames (15, 45) and produces
+    the identical per-frame visible pattern for the occluded point."""
+    by_frames = _scene_with_occlusion(Occlusion.sphere(size=0.15).blocks(camera=1).during((15, 45)))
+    by_seconds = _scene_with_occlusion(
+        Occlusion.sphere(size=0.15).blocks(camera=1).during_seconds(0.5, 1.5)
+    )
+    vis_frames = [
+        fr["points"]["center"]["per_cam"][1]["visible"] for fr in by_frames["entities"][0]["frames"]
+    ]
+    vis_seconds = [
+        fr["points"]["center"]["per_cam"][1]["visible"]
+        for fr in by_seconds["entities"][0]["frames"]
+    ]
+    assert vis_frames == vis_seconds
+
+
+def test_during_seconds_rejects_inverted_window() -> None:
+    with pytest.raises(ValueError):
+        Occlusion.sphere(size=0.15).during_seconds(1.5, 0.5)
+
+
+def test_occlusion_rejects_both_frames_and_seconds_windows() -> None:
+    """An occlusion must declare exactly one schedule: frames or seconds."""
+    with pytest.raises(ValueError):
+        Occlusion.sphere(size=0.15).during((3, 7)).during_seconds(0.5, 1.5)
+    with pytest.raises(ValueError):
+        Occlusion.sphere(size=0.15).during_seconds(0.5, 1.5).during((3, 7))