adaptive-motion-preprocessing 1.0.0rc2__tar.gz → 1.1.0__tar.gz

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/.github/workflows/ci.yml

@@ -23,9 +23,9 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -49,9 +49,9 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -73,9 +73,9 @@ jobs:
     name: Build distributions
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -90,7 +90,7 @@ jobs:
       - name: Check metadata
         run: twine check --strict dist/*
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/.github/workflows/publish.yml

@@ -27,9 +27,9 @@ jobs:
       is-new: ${{ steps.version.outputs.is-new }}
       prerelease: ${{ steps.version.outputs.prerelease }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -79,9 +79,9 @@ jobs:
     if: needs.check-version.outputs.is-new == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -94,7 +94,7 @@ jobs:
       - name: Check metadata
         run: twine check --strict dist/*
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -110,7 +110,7 @@ jobs:
     permissions:
       id-token: write  # required for PyPI trusted publishing
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -126,7 +126,7 @@ jobs:
     permissions:
       contents: write  # create the tag and release
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: adaptive-motion-preprocessing
-Version: 1.0.0rc2
+Version: 1.1.0
 Summary: Adaptive motion preprocessing: video frames in, encoded motion images out.
 Project-URL: Homepage, https://github.com/sdrfsh/adaptive-motion-preprocessing
 Project-URL: Repository, https://github.com/sdrfsh/adaptive-motion-preprocessing
@@ -114,6 +114,10 @@ All optional keyword arguments of `AdaptiveMotionPreprocessor(...)`:
 - 🎬 **New scene?** Call `reset()`. It forgets the background, any half-built
   window and the frame size. Otherwise state carries over between
   `process()` calls.
+- 🎚️ **Tuning the threshold.** `preprocessor.last_motion_fraction` is the
+  share of the latest frame that was moving. Read it once with the scene
+  still and once with something moving, and set `motion_threshold`
+  between the two.
 - 📐 **One frame size per scene.** Frames that change size mid-stream raise a
   `ValueError`. Call `reset()` first if the change is on purpose.
 

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/README.md

@@ -84,6 +84,10 @@ All optional keyword arguments of `AdaptiveMotionPreprocessor(...)`:
 - 🎬 **New scene?** Call `reset()`. It forgets the background, any half-built
   window and the frame size. Otherwise state carries over between
   `process()` calls.
+- 🎚️ **Tuning the threshold.** `preprocessor.last_motion_fraction` is the
+  share of the latest frame that was moving. Read it once with the scene
+  still and once with something moving, and set `motion_threshold`
+  between the two.
 - 📐 **One frame size per scene.** Frames that change size mid-stream raise a
   `ValueError`. Call `reset()` first if the change is on purpose.
 

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "adaptive-motion-preprocessing"
-version = "1.0.0rc2"
+version = "1.1.0"
 description = "Adaptive motion preprocessing: video frames in, encoded motion images out."
 readme = "README.md"
 license = "MIT"

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/src/amprep/frame_window.py

@@ -15,8 +15,8 @@ the two is the caller's arithmetic.
 MIN_WINDOW_FRAMES = 2
 """Fewest frames a window can be asked to hold.
 
-The adaptive sampler compares the first frame of a window against the
-middle one, which needs two distinct frames to be a comparison at all.
+The adaptive sampler measures change between consecutive masks, which
+needs at least one pair of frames to be a comparison at all.
 """
 
 
@@ -32,9 +32,9 @@ class FrameWindowCollector:
         trigger:  idle   ACTIVE x 10        ACTIVE x 10        idle
         window:          [1..10] -> out     [1..10] -> out     (partial, dropped)
 
-    Frames and their masks are kept together, because the two stages
-    downstream need different halves of the same moment: the sampler
-    reads frames, the encoder reads masks.
+    Only the foreground masks are kept. Both stages downstream, the
+    sampler and the encoder, read masks alone, so holding on to the
+    full-colour frames as well would cost memory for nothing.
 
     A partial window is discarded when motion stops. Velocity is measured
     across a window, so a window cut short describes a slower movement
@@ -74,7 +74,7 @@ class FrameWindowCollector:
         Zero between windows as well as while idle: a window that is
         handed over leaves nothing behind it.
         """
-        return len(self._frames)
+        return len(self._masks)
 
     def reset(self) -> None:
         """Drop whatever was being collected and start again empty.
@@ -93,15 +93,14 @@ class FrameWindowCollector:
         just handed a full one over. Should ``reset`` ever grow behaviour
         that belongs to a new scene, it must not fire on those.
         """
-        self._frames: list[Frame] = []
         self._masks: list[Frame] = []
 
-    def update(self, frame: Frame, mask: Frame, active: bool) -> Window | None:
-        """Take one frame, and return a window if this frame completed one.
+    def update(self, mask: Frame, active: bool) -> Window | None:
+        """Take one frame's mask, and return a window if it completed one.
 
         Args:
-            frame: The frame captured at this moment. See ``Frame``.
-            mask: Its foreground mask, from the background subtractor.
+            mask: The foreground mask of the frame captured at this
+                moment, from the background subtractor.
             active: The trigger's verdict on this frame. ``False`` drops
                 this frame and discards anything part-collected with it.
 
@@ -111,18 +110,17 @@ class FrameWindowCollector:
             so consecutive windows share no frames.
         """
         if not active:
-            if self._frames:
-                _log.debug("motion ended, dropping %d frames", len(self._frames))
+            if self._masks:
+                _log.debug("motion ended, dropping %d frames", len(self._masks))
                 self._clear()
             return None
 
-        self._frames.append(frame)
         self._masks.append(mask)
 
-        if len(self._frames) < self._window_frames:
+        if len(self._masks) < self._window_frames:
             return None
 
-        window = Window(frames=tuple(self._frames), masks=tuple(self._masks))
+        window = Window(masks=tuple(self._masks))
         # Emptied rather than kept, so the next frame opens the next
         # window: that is what "no cooldown" means here.
         self._clear()

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/src/amprep/motion_trigger.py

@@ -41,6 +41,7 @@ class MotionTrigger:
 
     @property
     def is_active(self) -> bool:
+        """Whether the last mask counted as motion."""
         return self._active
 
     @property

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/src/amprep/preprocessor.py

@@ -88,6 +88,20 @@ class AdaptiveMotionPreprocessor:
         self._frames_seen = 0
         self._frame_shape: tuple[int, ...] | None = None
 
+    @property
+    def last_motion_fraction(self) -> float:
+        """Share of the most recent frame that was moving, in ``[0, 1]``.
+
+        The reading ``motion_threshold`` is compared against, so this is
+        the number to watch when tuning it on real footage: print it while
+        the scene is still and while something moves, and set the
+        threshold between the two.
+
+        Zero before the first frame is measured, during the background
+        subtractor's warm-up, and after ``reset()``.
+        """
+        return self._trigger.last_fraction
+
     def process(self, frames: Iterable[Frame]) -> Iterator[MotionImage]:
         """Turn a stream of frames into encoded motion images.
 
@@ -135,7 +149,7 @@ class AdaptiveMotionPreprocessor:
                 continue
 
             active = self._trigger.update(mask)
-            window = self._collector.update(frame, mask, active)
+            window = self._collector.update(mask, active)
             if window is not None:
                 yield self._encoder.encode(window, self._sampler.select(window))
 

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/src/amprep/types.py

@@ -54,41 +54,32 @@ class MotionImage:
 
 @dataclass(frozen=True)
 class Window:
-    """A full run of consecutive frames, collected while motion lasted.
+    """A full run of consecutive foreground masks, collected while motion lasted.
 
     The handover between the collector and the two stages that read it:
-    the adaptive sampler measures how fast things moved from ``masks``,
-    where the foreground centroid is trivially locatable, and the encoder
-    stacks the ``frames`` the sampler picked. Both are carried because
-    neither can be recovered from the other, and they are carried
-    together because a mask is only meaningful beside the frame it came
-    from.
+    the adaptive sampler measures how fast the foreground changes across
+    ``masks``, and the encoder paints the masks the sampler picked. Both
+    work on masks alone, so the frames themselves are not carried: a
+    window of full-colour frames would cost memory and nothing would
+    read it.
 
     Contract:
-        ``frames`` and ``masks`` are the same length, and the entries at
-        any index were captured at the same moment. A window is never
-        empty and never partial: the collector emits one only once it is
-        full, so a stage reading this never has to ask whether it got a
-        whole one.
+        ``masks`` is in capture order, one per frame, each a ``uint8``
+        ``(H, W)`` array. A window is never empty and never partial: the
+        collector emits one only once it is full, so a stage reading this
+        never has to ask whether it got a whole one.
 
     Attributes:
-        frames: The frames, in capture order. See ``Frame``.
-        masks: The foreground mask for each frame, in the same order.
+        masks: The foreground mask of each frame, in capture order.
     """
 
-    frames: tuple[Frame, ...]
     masks: tuple[Frame, ...]
 
     def __post_init__(self) -> None:
-        """Ensure every frame kept its mask, and that there is anything here."""
-        if len(self.frames) != len(self.masks):
-            raise ValueError(
-                f"Window needs one mask per frame, got {len(self.frames)} "
-                f"frames and {len(self.masks)} masks"
-            )
-        if not self.frames:
+        """Ensure there is anything here."""
+        if not self.masks:
             raise ValueError("Window must not be empty")
 
     def __len__(self) -> int:
         """The number of frames in the window."""
-        return len(self.frames)
+        return len(self.masks)

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/tests/test_adaptive_sampler.py

@@ -27,9 +27,8 @@ standing still: a property of the scaffold, not of the sampler.
 
 
 def _window(masks: list[np.ndarray]) -> Window:
-    """Wrap masks in a window, with blank frames the sampler never reads."""
-    blanks = tuple(np.zeros((*mask.shape, 3), np.uint8) for mask in masks)
-    return Window(frames=blanks, masks=tuple(masks))
+    """Wrap masks in a window."""
+    return Window(masks=tuple(masks))
 
 
 def _moving_window(frames: int, pixels_per_frame: float) -> Window:

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/tests/test_frame_window.py

@@ -13,27 +13,19 @@ SHAPE = (4, 4)
 """Small enough to be free, large enough to be a real array."""
 
 
-def _frame(value: int) -> Frame:
-    """A frame carrying ``value``, so its place in a window is readable."""
-    return np.full((*SHAPE, 3), value, dtype=np.uint8)
-
-
 def _mask(value: int) -> Frame:
-    """The matching mask for ``_frame(value)``, carrying the same value."""
+    """A mask carrying ``value``, so its place in a window is readable."""
     return np.full(SHAPE, value, dtype=np.uint8)
 
 
 def _feed(collector: FrameWindowCollector, count: int, active: bool = True, start=0):
     """Push ``count`` numbered frames through and return what came out."""
-    return [
-        collector.update(_frame(i), _mask(i), active)
-        for i in range(start, start + count)
-    ]
+    return [collector.update(_mask(i), active) for i in range(start, start + count)]
 
 
 def _values(window: Window) -> list[int]:
-    """The numbers the window's frames were built from, in order."""
-    return [int(frame[0, 0, 0]) for frame in window.frames]
+    """The numbers the window's masks were built from, in order."""
+    return [int(mask[0, 0]) for mask in window.masks]
 
 
 def test_default_window_is_ten_frames():
@@ -102,15 +94,21 @@ def test_the_window_carries_its_frames_in_order():
     assert _values(window) == [0, 1, 2, 3]
 
 
-def test_every_frame_keeps_its_mask():
-    """Frames and masks line up by index, which is the whole point of pairing."""
-    collector = FrameWindowCollector(window_frames=4)
+def test_the_window_holds_the_masks_it_was_given():
+    """The very arrays handed in come out, not copies or derivations."""
+    collector = FrameWindowCollector(window_frames=3)
+    masks = [_mask(i) for i in range(3)]
 
-    window = _feed(collector, 4)[-1]
+    window = [collector.update(mask, True) for mask in masks][-1]
 
-    assert len(window.frames) == len(window.masks) == 4
-    for frame, mask in zip(window.frames, window.masks, strict=True):
-        assert int(mask[0, 0]) == int(frame[0, 0, 0])
+    assert all(a is b for a, b in zip(window.masks, masks, strict=True))
+
+
+def test_the_window_carries_no_frames():
+    """Nothing downstream reads frames, so none are held in memory."""
+    window = _feed(FrameWindowCollector(window_frames=2), 2)[-1]
+
+    assert not hasattr(window, "frames")
 
 
 def test_the_next_window_starts_on_the_very_next_frame():
@@ -151,7 +149,7 @@ def test_a_partial_window_is_discarded_when_motion_stops():
 
     assert collector.pending == 6
 
-    assert collector.update(_frame(99), _mask(99), active=False) is None
+    assert collector.update(_mask(99), active=False) is None
     assert collector.pending == 0
 
 
@@ -159,7 +157,7 @@ def test_a_discarded_window_is_never_emitted_later():
     """The dropped fragment does not reappear at the front of the next window."""
     collector = FrameWindowCollector(window_frames=4)
     _feed(collector, 3)
-    collector.update(_frame(99), _mask(99), active=False)
+    collector.update(_mask(99), active=False)
 
     window = _feed(collector, 4, start=10)[-1]
 
@@ -179,7 +177,7 @@ def test_motion_stopping_on_a_full_window_loses_nothing():
     collector = FrameWindowCollector(window_frames=3)
 
     results = _feed(collector, 3)
-    after = collector.update(_frame(99), _mask(99), active=False)
+    after = collector.update(_mask(99), active=False)
 
     assert isinstance(results[-1], Window)
     assert after is None
@@ -190,7 +188,7 @@ def test_bursts_are_collected_independently():
     collector = FrameWindowCollector(window_frames=3)
 
     _feed(collector, 2)
-    collector.update(_frame(99), _mask(99), active=False)
+    collector.update(_mask(99), active=False)
     window = _feed(collector, 3, start=20)[-1]
 
     assert _values(window) == [20, 21, 22]
@@ -229,21 +227,15 @@ def test_the_properties_are_read_only(name):
         setattr(collector, name, 3)
 
 
-def test_window_rejects_a_mask_count_that_does_not_match():
-    """A window with a frame missing its mask is not constructible."""
-    with pytest.raises(ValueError, match="one mask per frame"):
-        Window(frames=(_frame(0), _frame(1)), masks=(_mask(0),))
-
-
 def test_window_rejects_being_empty():
     """An empty window describes nothing and is never emitted."""
     with pytest.raises(ValueError, match="must not be empty"):
-        Window(frames=(), masks=())
+        Window(masks=())
 
 
 def test_window_is_frozen():
     """A window is a handover, not a workspace for the stage that gets it."""
-    window = Window(frames=(_frame(0),), masks=(_mask(0),))
+    window = Window(masks=(_mask(0),))
 
     with pytest.raises(AttributeError):
-        window.frames = ()
+        window.masks = ()

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/tests/test_motion_history_encoder.py

@@ -6,8 +6,7 @@ from amprep.types import Window
 
 
 def _window(masks):
-    frames = tuple(np.zeros((*m.shape, 3), np.uint8) for m in masks)
-    return Window(frames=frames, masks=tuple(masks))
+    return Window(masks=tuple(masks))
 
 
 def _full(h, w, count):

{adaptive_motion_preprocessing-1.0.0rc2 → adaptive_motion_preprocessing-1.1.0}/tests/test_pipeline.py

@@ -173,3 +173,58 @@ def test_reset_allows_a_new_frame_size():
     preprocessor.reset()
 
     list(preprocessor.process([np.zeros((30, 40, 3), np.uint8)] * 3))  # no error
+
+
+# ---- last_motion_fraction ----
+
+
+def test_last_motion_fraction_starts_at_zero():
+    assert AdaptiveMotionPreprocessor().last_motion_fraction == 0.0
+
+
+def test_last_motion_fraction_reads_the_latest_frame():
+    """The block is 20x20 of a 60x80 frame, so about a twelfth of it moves.
+
+    About, because the default median filter rounds the block's corners
+    off before the mask is taken.
+    """
+    preprocessor = AdaptiveMotionPreprocessor(background_subtractor=_Threshold())
+    moving = _scene(0, 1, 0)
+
+    list(preprocessor.process(moving))
+
+    assert preprocessor.last_motion_fraction == pytest.approx(
+        20 * 20 / (H * W), rel=0.05
+    )
+
+
+def test_last_motion_fraction_drops_to_zero_on_a_still_frame():
+    preprocessor = AdaptiveMotionPreprocessor(background_subtractor=_Threshold())
+
+    list(preprocessor.process(_scene(0, 1, 0)))
+    list(preprocessor.process([np.full((H, W, 3), 120, np.uint8)]))
+
+    assert preprocessor.last_motion_fraction == 0.0
+
+
+def test_last_motion_fraction_is_untouched_during_warmup():
+    """Warm-up masks are not trusted, so they are not reported either."""
+    preprocessor = AdaptiveMotionPreprocessor()
+
+    list(preprocessor.process(_scene(0, 4, 0)))  # all four are warm-up
+
+    assert preprocessor.last_motion_fraction == 0.0
+
+
+def test_reset_clears_last_motion_fraction():
+    preprocessor = AdaptiveMotionPreprocessor(background_subtractor=_Threshold())
+    list(preprocessor.process(_scene(0, 1, 0)))
+
+    preprocessor.reset()
+
+    assert preprocessor.last_motion_fraction == 0.0
+
+
+def test_last_motion_fraction_is_read_only():
+    with pytest.raises(AttributeError):
+        AdaptiveMotionPreprocessor().last_motion_fraction = 0.5