adaptive-motion-preprocessing 1.0.0rc1__py3-none-any.whl

adaptive_motion_preprocessing-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: adaptive-motion-preprocessing
+Version: 1.0.0rc1
+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
+Project-URL: Issues, https://github.com/sdrfsh/adaptive-motion-preprocessing/issues
+Author: Sahar Darafsh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: computer-vision,motion-detection,opencv,preprocessing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🎞️ Adaptive Motion Preprocessing
+
+Turn video into motion images your neural network can read. 
+
+While something moves, each window of frames becomes one grayscale picture:
+older frames dim, newer ones bright, so a single image shows where the
+subject went and how fast. Every image has the same shape, so your model
+never gets a surprise. 
+
+## 📦 Install
+
+```sh
+pip install adaptive-motion-preprocessing
+```
+
+Then `import amprep`.
+
+## 🚀 Quick start
+
+You bring the frames (any iterable of `uint8` BGR arrays) and the package
+does the rest:
+
+```python
+import cv2
+
+from amprep import AdaptiveMotionPreprocessor
+
+
+def frames_from(path):
+    capture = cv2.VideoCapture(path)
+    try:
+        if not capture.isOpened():
+            raise OSError(f"cannot open video: {path}")
+        while True:
+            ok, frame = capture.read()
+            if not ok:
+                return
+            yield frame
+    finally:
+        capture.release()
+
+
+for image in AdaptiveMotionPreprocessor().process(frames_from("clip.mp4")):
+    print(image.data.shape)
+```
+
+## 🎥 Try it on your webcam
+
+See your camera and the motion images side by side, live:
+
+```sh
+git clone https://github.com/sdrfsh/adaptive-motion-preprocessing
+cd adaptive-motion-preprocessing
+pip install -e .
+python examples/live_camera.py
+```
+
+Stay out of shot for a second while it learns the background, then move.
+Press `q` or `Esc` to quit. Add `--camera 1` for an external webcam, or
+`--threshold 0.03` if it triggers when nothing is moving.
+
+## ⚙️ Settings
+
+All optional keyword arguments of `AdaptiveMotionPreprocessor(...)`:
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `motion_threshold` | `0.01` | Share of the frame that must be moving before frames are collected |
+| `window_frames` | `10` | Frames per window, and one image per full window |
+| `sample_frames` | `4` | Frames painted into each image (at most `window_frames`) |
+| `width`, `height` | `None` | Output size; leave unset to keep the frame size, or set both |
+| `noise_reducer` | median filter | Your own `NoiseReducer` subclass |
+| `background_subtractor` | KNN | Your own `BackgroundSubtractor` subclass |
+
+## 💡 Good to know
+
+- ⏱️ **Frames, not seconds.** 10 frames is about 0.33 s at 30 fps and 1 s at
+  10 fps. The package never reads the frame rate, so that math is yours.
+- 🔁 **A steady stream.** While motion lasts you get one image every
+  `window_frames` frames. A half-full window is dropped when motion stops.
+- 🌱 **Warm-up.** The default subtractor spends its first 4 frames learning
+  the background, so they never produce images. Change it with
+  `KNNBackgroundSubtractor(warmup_frames=...)`.
+- 🎬 **New scene?** Call `reset()`. It forgets the background, any half-built
+  window and the frame size. Otherwise state carries over between
+  `process()` calls.
+- 📐 **One frame size per scene.** Frames that change size mid-stream raise a
+  `ValueError`. Call `reset()` first if the change is on purpose.
+
+## 📚 Examples
+
+- [examples/live_camera.py](examples/live_camera.py): watch it live on your webcam, camera and motion image side by side
+- [examples/from_video_file.py](examples/from_video_file.py): run it on a video file
+- [examples/custom_background_subtractor.py](examples/custom_background_subtractor.py): plug in your own stage

adaptive_motion_preprocessing-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,14 @@
+amprep/__init__.py,sha256=Lh-D9z9J9WdWF6Aotn28ZdGb9rIFswtcyAWT7wA0hlY,442
+amprep/adaptive_sampler.py,sha256=t7HRXr_tMeq08GQujbizxhVtlotfx_YgBPWGXkVdREM,8599
+amprep/background_subtractor.py,sha256=Q7KSirUW05xnBAIOYqiAP6yR8vVfhiRmIu-n29EieMY,8273
+amprep/frame_window.py,sha256=k1V5cdMrvH45kEdZXQfw3XkCkYhnNrna3nYv_FZRwyA,5008
+amprep/motion_history_encoder.py,sha256=N8t7bf7jIHKvCkbbpvoTmCqVmGYTk7kscrSStH1rEP4,5471
+amprep/motion_trigger.py,sha256=K1p_FBLSMQb_gW7U4vL5L-ye10BH7KUHkBbtfN2Fefo,2222
+amprep/noise_reducer.py,sha256=KGq-N70B2uooDk7W-vKjFylbcUTdwiWWzcvITLsPoYU,2935
+amprep/preprocessor.py,sha256=BV8oMLTwVbSsdtoYgidZPZGrRcrUCWskM0PB3CbQ9cQ,7258
+amprep/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amprep/types.py,sha256=9y4CgymT5YCs5q-3MWE_-hfrpxCMItIAOVrwxp_Aruc,3579
+adaptive_motion_preprocessing-1.0.0rc1.dist-info/METADATA,sha256=R4t1lXdR4gI21Uh_qOZ8idpYLpXZCbHdlWaXoHcK5Hw,4601
+adaptive_motion_preprocessing-1.0.0rc1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+adaptive_motion_preprocessing-1.0.0rc1.dist-info/licenses/LICENSE,sha256=xq9lXmM9Cd-IZcyzZ7_QGeHpNSTeDARC2MaH-Rpiwrc,1070
+adaptive_motion_preprocessing-1.0.0rc1.dist-info/RECORD,,

adaptive_motion_preprocessing-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adaptive_motion_preprocessing-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahar Darafsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amprep/__init__.py

@@ -0,0 +1,14 @@
+from amprep.background_subtractor import BackgroundSubtractor, KNNBackgroundSubtractor
+from amprep.noise_reducer import MedianNoiseReducer, NoiseReducer
+from amprep.preprocessor import AdaptiveMotionPreprocessor
+from amprep.types import Frame, MotionImage
+
+__all__ = [
+    "AdaptiveMotionPreprocessor",
+    "BackgroundSubtractor",
+    "Frame",
+    "KNNBackgroundSubtractor",
+    "MedianNoiseReducer",
+    "MotionImage",
+    "NoiseReducer",
+]

amprep/adaptive_sampler.py

@@ -0,0 +1,198 @@
+import logging
+
+import numpy as np
+
+from amprep.types import Window
+
+_log = logging.getLogger(__name__)
+
+DEFAULT_SAMPLE_FRAMES = 4
+"""Frames kept from every window, whatever the motion did.
+
+Fixed on purpose. The encoder behind this stage has to emit one shape
+every time, and a constant number of frames going in is the cheapest way
+to get there: it has nothing to pad or drop. Keep it at or below
+``window_frames`` or short windows will yield fewer.
+"""
+
+DEFAULT_FULL_SPEED = 0.35
+"""Change rate at which the samples sit on consecutive frames.
+
+A share of the subject changing per frame. Normal walking measures about
+0.17 and running about 0.55, so 0.35 puts walking mid-range and running
+at the tightest spacing. Measured on synthetic masks.
+
+Not a setting for users: a share of the subject changing per frame is
+not a quantity anyone can choose sensibly by hand, so the preprocessor
+does not ask for it.
+"""
+
+
+class AdaptiveFrameSampler:
+    """Picks which frames of a window to keep, closer together when motion is fast.
+
+    Always the same number of frames; what velocity changes is how far
+    apart they sit. The aim is to hold the *amount of change* between
+    consecutive samples roughly steady rather than the time between
+    them::
+
+        window of 10:   0 1 2 3 4 5 6 7 8 9
+
+        slow motion     X . . X . . X . . X    spread across the window
+        fast motion     . . . . . . X X X X    packed at the newest frames
+
+    Both extremes are there for the same reason. Sampling a slow scene
+    tightly gives four near-identical frames, which describe no motion at
+    all; sampling a fast one across the whole window gives four frames
+    the subject has jumped between, which describe motion that looks
+    discontinuous. Moving the spacing keeps the step between samples in a
+    useful middle band either way.
+
+    The cost is that fast motion is sampled from the end of the window
+    and the opening frames are not represented. That is the trade the
+    fixed count buys: with a constant number of frames, coverage and
+    density cannot both be held. Density is what carries the shape of the
+    movement, and when it has to be bought, it is bought from the oldest
+    frames rather than the freshest: the samples always reach the most
+    recent frame in the window.
+
+    Velocity is read from the masks rather than the frames: a mask is
+    already "what is moving", so the share of it that changes between one
+    frame and the next is a rate of change needing no optical flow.
+
+    ``full_speed`` is the change rate at which the spacing bottoms out,
+    and it is fixed for the life of the sampler. That makes the sampler
+    stateless: each window is judged on its own, nothing carries from one
+    window to the next, and there is nothing to reset between scenes.
+
+    Args:
+        sample_frames: Frames kept from every window. At least 2, so
+            there is always a before and an after. A window holding
+            fewer frames than this yields only what it has, so keep it
+            at or below the collector's ``window_frames``.
+        full_speed: Change rate at which the samples are packed onto
+            consecutive frames, as a share of the subject changing per
+            frame. Defaults to ``DEFAULT_FULL_SPEED``.
+    """
+
+    def __init__(
+        self,
+        sample_frames: int = DEFAULT_SAMPLE_FRAMES,
+        full_speed: float = DEFAULT_FULL_SPEED,
+    ) -> None:
+        # bool is an int subclass, so it is refused by name before the
+        # range check, where True would otherwise read as 1.
+        if isinstance(sample_frames, bool) or not isinstance(sample_frames, int):
+            raise ValueError(f"sample_frames must be an integer, got {sample_frames!r}")
+        if sample_frames < 2:
+            raise ValueError(f"sample_frames must be at least 2, got {sample_frames}")
+        if isinstance(full_speed, bool) or not isinstance(full_speed, (int, float)):
+            raise ValueError(f"full_speed must be a number, got {full_speed!r}")
+        if not full_speed > 0:
+            raise ValueError(f"full_speed must be positive, got {full_speed!r}")
+
+        self._sample_frames = sample_frames
+        self._full_speed = float(full_speed)
+
+    @property
+    def sample_frames(self) -> int:
+        """Frames kept from every window."""
+        return self._sample_frames
+
+    @property
+    def full_speed(self) -> float:
+        """Change rate at which the samples sit on consecutive frames."""
+        return self._full_speed
+
+    def velocity(self, window: Window) -> float:
+        """Return how fast the foreground changes, over the second half of ``window``.
+
+        For each pair of consecutive masks, the share of the subject that
+        flipped between them: pixels that changed, over pixels foreground
+        in either. The result is the mean of those shares, so it stays in
+        ``[0, 1]`` whatever the window length or the resolution: an
+        average over pairs rather than a total divided by the number of
+        steps, which would shrink as the window grew.
+
+        The second half is measured because that is the half the samples
+        are taken from when motion is fast.
+
+        Unlike tracking the centre of the foreground, this sees a subject
+        approaching the camera, which grows without moving sideways, and
+        two subjects moving apart, whose combined centre stays put.
+
+        It is relative to the subject's size: a small, distant subject
+        reads faster than a large, close one moving at the same speed,
+        because the same displacement flips a larger share of it.
+
+        Args:
+            window: The window to measure. See ``Window``.
+
+        Returns:
+            Mean share of the foreground changing between consecutive
+            frames, in ``[0, 1]``. Zero when no measured pair holds any
+            foreground at all.
+        """
+        start = (len(window) - 1) // 2
+        shares = []
+        for earlier, later in zip(
+            window.masks[start:-1], window.masks[start + 1 :], strict=True
+        ):
+            was, now = earlier > 0, later > 0
+            # Pixels foreground in either frame. Dividing by this rather
+            # than by the frame area is what makes the reading relative
+            # to the subject instead of to the picture.
+            union = np.count_nonzero(was | now)
+            if union:
+                shares.append(np.count_nonzero(was ^ now) / union)
+        return float(np.mean(shares)) if shares else 0.0
+
+    def select(self, window: Window) -> tuple[int, ...]:
+        """Return the indices of the frames worth keeping from ``window``.
+
+        Args:
+            window: The window to sample. See ``Window``.
+
+        Returns:
+            Exactly ``sample_frames`` indices, or every index the window
+            has if it holds fewer. Strictly increasing, within the
+            window, and always reaching its last frame.
+        """
+        count = min(self._sample_frames, len(window))
+        if count < 2:
+            return (0,)
+
+        speed = self.velocity(window)
+        # Saturating rather than proportional: past full_speed the
+        # samples are already on consecutive frames and cannot tighten
+        # further, and an outlier reading must not reach past it.
+        fraction = min(1.0, speed / self._full_speed)
+
+        # The span is how much of the window the samples cover. At its
+        # widest they reach back to the first frame; at its narrowest
+        # they sit on consecutive frames, which needs exactly count - 1
+        # steps. Using a span rather than an integer stride is what keeps
+        # the choice fine-grained: a stride of 1 or 2 is all a ten-frame
+        # window can offer, while the span moves through every value
+        # between.
+        widest = len(window) - 1
+        narrowest = count - 1
+        span = round(widest - fraction * (widest - narrowest))
+
+        # Anchored at the newest frame and reaching backwards, so
+        # tightening the spacing drops the oldest frames rather than the
+        # freshest. Spacing stays at least one frame because span is
+        # never below count - 1, so rounding cannot collapse two samples
+        # onto the same index.
+        last = len(window) - 1
+        indices = np.linspace(last - span, last, count).round().astype(int)
+
+        _log.debug(
+            "change rate %.4f (full speed %.4f) -> %d frames spanning %d of %d",
+            speed,
+            self._full_speed,
+            count,
+            span,
+            len(window),
+        )
+        return tuple(int(index) for index in indices)

amprep/background_subtractor.py

@@ -0,0 +1,202 @@
+from abc import ABC, abstractmethod
+
+import cv2
+import numpy as np
+
+from amprep.types import Frame
+
+
+def _validate(array: Frame, label: str, ndim: int) -> None:
+    """Raise when ``array`` is not a ``uint8`` array of ``ndim`` dimensions.
+
+    A three-dimensional array is additionally required to be BGR, i.e. to
+    have exactly three channels.
+    """
+    if not isinstance(array, np.ndarray):
+        raise TypeError(f"Expected {label} to be a NumPy array, got {type(array)}")
+    if array.dtype != np.uint8:
+        raise TypeError(f"Expected {label} to be uint8, got {array.dtype}")
+    if array.ndim != ndim:
+        raise ValueError(
+            f"Expected {label} to be {ndim}-dimensional, got {array.shape}"
+        )
+    if ndim == 3 and array.shape[2] != 3:
+        raise ValueError(f"Expected {label} to be (H, W, 3), got {array.shape}")
+
+
+class BackgroundSubtractor(ABC):
+    """Separates moving foreground from a learned background model.
+
+    Subclass this and implement ``_apply`` and ``reset`` to plug in your
+    own subtractor. Do not override ``apply``: it validates the input
+    frame and the returned mask against the contract below. Pass an
+    instance to ``AdaptiveMotionPreprocessor(background_subtractor=...)``;
+    leave it unset and the package's default implementation is used
+    instead.
+
+    Contract:
+        ``_apply`` takes a ``uint8`` ``(H, W, 3)`` BGR frame and must
+        return a **single-channel** ``uint8`` mask of shape ``(H, W)``,
+        the same height and width as its input. Implementations are
+        stateful: consecutive calls are expected to come from the same
+        video, in order, so the background model can adapt.
+
+        ``reset`` discards that accumulated state. It is the caller's way
+        of saying the next frame belongs to a different scene, so a model
+        learned from the preceding frames describes a background that is
+        no longer there.
+
+        ``warmup_frames`` says how many frames a subtractor needs before
+        its masks mean anything. It is concrete and defaults to 0, so a
+        subclass that is useful from its first frame writes nothing;
+        override it only if yours is not.
+    """
+
+    @abstractmethod
+    def _apply(self, frame: Frame) -> Frame:
+        """Return the foreground mask for ``frame``.
+
+        Args:
+            frame: The input frame to process. See ``Frame`` for its
+                contract.
+
+        Returns:
+            A single-channel ``uint8`` mask of shape ``(H, W)`` matching
+            the input frame's height and width.
+        """
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Discard the learned background model.
+
+        Called when the scene changes (a cut, a camera move, or the
+        start of a different video), so that state accumulated from the
+        preceding frames does not leak into the next one. Implementations
+        that hold no state between frames should implement this as a
+        no-op.
+        """
+
+    @property
+    def warmup_frames(self) -> int:
+        """Frames before this subtractor's masks are meaningful. Default 0."""
+        return 0
+
+    def apply(self, frame: Frame) -> Frame:
+        """Return the foreground mask for ``frame``."""
+        _validate(frame, "the input frame", ndim=3)
+
+        mask = self._apply(frame)
+
+        _validate(mask, "the mask returned by _apply", ndim=2)
+        if mask.shape != frame.shape[:2]:
+            raise ValueError(
+                f"_apply must preserve frame H×W: {frame.shape[:2]} -> {mask.shape}"
+            )
+
+        return mask
+
+
+class KNNBackgroundSubtractor(BackgroundSubtractor):
+    """Separates foreground with OpenCV's KNN background subtractor.
+
+    The package default. KNN models each pixel's recent history as a
+    cloud of samples and calls a new value foreground when too few of its
+    neighbours sit close to it. That copes with the swaying leaves and
+    rippling water a single-Gaussian model keeps flagging as motion,
+    which matters here because every false foreground pixel becomes
+    spurious motion in the encoded output.
+
+    The mask is strictly binary: 0 for background, 255 for foreground.
+    OpenCV marks shadows with an intermediate grey, and a downstream
+    stage that thresholds a mask at anything other than 0 would silently
+    treat those pixels as half-present, so they are folded into one of
+    the two labels here instead.
+
+    Args:
+        history: Number of recent frames the model is built from. Longer
+            tolerates slower background change but takes longer to
+            forget an object that stops moving and becomes scenery.
+        dist2_threshold: Squared distance between a pixel and a sample
+            for that sample to count as its neighbour. Larger admits
+            more variation as background, so the mask keeps less noise
+            and fewer faint edges.
+        detect_shadows: Whether to recognise shadows and exclude them
+            from the foreground. Shadows move with their subject, so
+            leaving this on keeps them out of the silhouette at a modest
+            cost in speed. Turn it off and they are foreground like any
+            other change.
+        warmup_frames: Frames to ignore at the start, while the model
+            has too few samples to judge against and marks most of the
+            image as motion. 4 settles a clean source at the default
+            ``dist2_threshold``. A strict threshold needs more, and how
+            much more is set by how far the source itself flickers rather
+            than by the threshold alone: at 100 a lightly noisy scene
+            takes 5, while a threshold strict enough for its own noise
+            never settles and reads every frame as motion.
+    """
+
+    def __init__(
+        self,
+        history: int = 500,
+        dist2_threshold: float = 400.0,
+        detect_shadows: bool = True,
+        warmup_frames: int = 4,
+    ) -> None:
+        if not isinstance(history, int) or isinstance(history, bool) or history <= 0:
+            raise ValueError(f"history must be a positive integer, got {history!r}")
+        if (
+            isinstance(dist2_threshold, bool)
+            or not isinstance(dist2_threshold, (int, float))
+            or dist2_threshold <= 0
+        ):
+            raise ValueError(
+                f"dist2_threshold must be a positive number, got {dist2_threshold!r}"
+            )
+        if not isinstance(detect_shadows, bool):
+            raise ValueError(
+                f"detect_shadows must be a boolean, got {detect_shadows!r}"
+            )
+        # Zero is allowed, and means the very first mask is trusted; only
+        # a negative count is meaningless.
+        if (
+            not isinstance(warmup_frames, int)
+            or isinstance(warmup_frames, bool)
+            or warmup_frames < 0
+        ):
+            raise ValueError(
+                f"warmup_frames must be a non-negative integer, got {warmup_frames!r}"
+            )
+
+        self._history = history
+        self._dist2_threshold = float(dist2_threshold)
+        self._detect_shadows = detect_shadows
+        self._warmup_frames = warmup_frames
+        self._subtractor = self._build()
+
+    def _build(self) -> cv2.BackgroundSubtractorKNN:
+        """Return a freshly constructed subtractor with no learned model."""
+        return cv2.createBackgroundSubtractorKNN(
+            history=self._history,
+            dist2Threshold=self._dist2_threshold,
+            detectShadows=self._detect_shadows,
+        )
+
+    @property
+    def warmup_frames(self) -> int:
+        """Frames to ignore at the start, as given to the constructor."""
+        return self._warmup_frames
+
+    def _apply(self, frame: Frame) -> Frame:
+        mask = self._subtractor.apply(frame)
+        # OpenCV labels foreground 255 and everything else (background,
+        # and shadows when detect_shadows is on) below it.
+        return np.where(mask == 255, np.uint8(255), np.uint8(0))
+
+    def reset(self) -> None:
+        """Discard the learned background model.
+
+        OpenCV exposes no way to clear a subtractor in place, so the
+        model is thrown away and rebuilt. The next frame is treated as
+        the opening frame of a new scene.
+        """
+        self._subtractor = self._build()

amprep/frame_window.py

@@ -0,0 +1,130 @@
+import logging
+
+from amprep.types import Frame, Window
+
+_log = logging.getLogger(__name__)
+
+DEFAULT_WINDOW_FRAMES = 10
+"""Frames gathered into one window.
+
+Counts frames, not seconds: ten is about 0.33 s at 30 fps and 1 s at
+10 fps. The package never reads the frame rate, so converting between
+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.
+"""
+
+
+class FrameWindowCollector:
+    """Gathers frames into fixed-size windows while motion lasts.
+
+    Fed one frame at a time along with the trigger's verdict on it. While
+    the trigger says moving, frames are collected; on the frame that
+    fills the window, that window is handed back and the next one begins
+    immediately. There is no cooldown, so a long burst of motion produces
+    back-to-back windows with no frame skipped between them::
+
+        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.
+
+    A partial window is discarded when motion stops. Velocity is measured
+    across a window, so a window cut short describes a slower movement
+    than actually happened: a stage cannot tell "the object slowed" from
+    "the recording stopped". Dropping the remainder loses a fragment of
+    real motion; keeping it would report a false one, which is worse.
+
+    Args:
+        window_frames: Frames per window, at least ``MIN_WINDOW_FRAMES``.
+            Defaults to ``DEFAULT_WINDOW_FRAMES`` (10).
+    """
+
+    def __init__(self, window_frames: int = DEFAULT_WINDOW_FRAMES) -> None:
+        # bool is an int subclass, so it is turned away by name before the
+        # range check, where True would otherwise read as 1.
+        if (
+            isinstance(window_frames, bool)
+            or not isinstance(window_frames, int)
+            or window_frames < MIN_WINDOW_FRAMES
+        ):
+            raise ValueError(
+                f"window_frames must be an integer of at least "
+                f"{MIN_WINDOW_FRAMES}, got {window_frames!r}"
+            )
+        self._window_frames = window_frames
+        self._clear()
+
+    @property
+    def window_frames(self) -> int:
+        """Frames per window, as given to the constructor."""
+        return self._window_frames
+
+    @property
+    def pending(self) -> int:
+        """Frames collected so far towards the window being built.
+
+        Zero between windows as well as while idle: a window that is
+        handed over leaves nothing behind it.
+        """
+        return len(self._frames)
+
+    def reset(self) -> None:
+        """Drop whatever was being collected and start again empty.
+
+        The caller's way of saying the next frame belongs to a different
+        scene, so frames gathered before a cut cannot end up in a window
+        beside frames from after it.
+        """
+        self._clear()
+
+    def _clear(self) -> None:
+        """Empty the buffers, saying nothing about why they were emptied.
+
+        Kept separate from ``reset`` because the two internal callers are
+        not scene changes: one abandons a partial window, the other has
+        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.
+
+        Args:
+            frame: The frame captured at this moment. See ``Frame``.
+            mask: Its foreground mask, from the background subtractor.
+            active: The trigger's verdict on this frame. ``False`` drops
+                this frame and discards anything part-collected with it.
+
+        Returns:
+            The completed ``Window`` if this frame filled one, otherwise
+            ``None``. Collecting resumes from empty on the next frame,
+            so consecutive windows share no frames.
+        """
+        if not active:
+            if self._frames:
+                _log.debug("motion ended, dropping %d frames", len(self._frames))
+                self._clear()
+            return None
+
+        self._frames.append(frame)
+        self._masks.append(mask)
+
+        if len(self._frames) < self._window_frames:
+            return None
+
+        window = Window(frames=tuple(self._frames), 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()
+        _log.debug("window complete at %d frames", len(window))
+        return window

amprep/motion_history_encoder.py

@@ -0,0 +1,120 @@
+import cv2
+import numpy as np
+
+from amprep.types import MotionImage, Window
+
+
+class MotionHistoryEncoder:
+    """Paints sampled masks into one gray image: old = dim, new = bright.
+
+    The last stage. The sampled masks go in and one picture comes out,
+    each mask painted at its own brightness so the result reads as a
+    trail.
+
+    A frame's brightness is how late in the window it was captured: the
+    newest frame is 255, the first frame of a ten-frame window is 26. Fast
+    motion is sampled from the end of the window, so its whole trail is
+    bright; slow motion spans the window, so its trail fades. The picture
+    shows both how far the subject moved and how long that took.
+
+    Where the masks overlap the brighter value wins, so the subject's
+    current position is always on top and the dimmer trail shows where it
+    came from.
+
+    Size is the caller's business. Given no size the masks are painted at
+    the size they arrive in, untouched: a 100x200 source yields a
+    100x200 image, and a model built for that source needs nothing done
+    to it. The shape stays fixed across windows because the source
+    resolution does, not because anything here enforces it.
+
+    Give a size and every mask is scaled to it instead, for a model whose
+    input differs from the camera. Scaling uses ``INTER_AREA``, which
+    averages the pixels it merges rather than picking one of them, so a
+    subject two pixels wide still leaves a small nonzero value after a
+    large reduction instead of disappearing at most positions. Any
+    nonzero mask pixel counts as foreground, so that value is painted at
+    its frame's full brightness, not dimmed by the averaging.
+
+    Args:
+        width: Output width in pixels, or ``None`` to keep the source
+            width. Must be given together with ``height``.
+        height: Output height in pixels, or ``None`` to keep the source
+            height. Must be given together with ``width``.
+    """
+
+    def __init__(self, *, width: int | None = None, height: int | None = None) -> None:
+        if (width is None) != (height is None):
+            raise ValueError(
+                "width and height must be given together, or neither: "
+                f"got width={width!r}, height={height!r}"
+            )
+        for name, value in (("width", width), ("height", height)):
+            if value is None:
+                continue
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError(f"{name} must be a positive integer, got {value!r}")
+        self._width = width
+        self._height = height
+
+    @property
+    def width(self) -> int | None:
+        """Output width in pixels, or ``None`` to keep the source width."""
+        return self._width
+
+    @property
+    def height(self) -> int | None:
+        """Output height in pixels, or ``None`` to keep the source height."""
+        return self._height
+
+    def encode(self, window: Window, indices: tuple[int, ...]) -> MotionImage:
+        """Paint the masks at ``indices`` into one motion image.
+
+        Args:
+            window: The window the masks come from. See ``Window``.
+            indices: Which of its frames to paint, strictly increasing
+                and within the window, oldest first. The sampler
+                produces them in exactly that form.
+
+        Returns:
+            A ``MotionImage`` whose ``data`` is ``uint8`` and is either
+            the configured size or the size of the first painted mask.
+
+        Raises:
+            ValueError: If ``indices`` is empty, not strictly increasing,
+                or reaches outside the window. Brightness encodes time,
+                so an out-of-order index would silently paint the past
+                on top of the present.
+        """
+        if not indices:
+            raise ValueError("indices must not be empty")
+        if list(indices) != sorted(set(indices)):
+            raise ValueError(f"indices must be strictly increasing, got {indices}")
+        if indices[0] < 0 or indices[-1] >= len(window):
+            raise ValueError(f"indices out of range for a window of {len(window)}")
+
+        if self._height is None or self._width is None:
+            # No size asked for, so the first mask sets it and nothing is
+            # scaled. Later masks are only touched if the source somehow
+            # changed resolution mid-window.
+            shape = window.masks[indices[0]].shape[:2]
+        else:
+            shape = (self._height, self._width)
+
+        image = np.zeros(shape, dtype=np.uint8)
+        for index in indices:
+            # By when the frame was captured, not by its place in the
+            # sample: the same frame paints the same grey however the
+            # sampler spaced the frames around it.
+            brightness = np.uint8(round(255 * (index + 1) / len(window)))
+            mask = window.masks[index]
+            if mask.shape[:2] != shape:
+                # cv2 wants (width, height). numpy shapes are (height, width).
+                mask = cv2.resize(
+                    mask, (shape[1], shape[0]), interpolation=cv2.INTER_AREA
+                )
+            painted = np.where(mask > 0, brightness, np.uint8(0))
+            # Brighter wins, and brighter means newer, so the newest mask
+            # ends up on top wherever the trail crosses itself.
+            np.maximum(image, painted, out=image)
+
+        return MotionImage(data=image, frame_indices=tuple(indices))

amprep/motion_trigger.py

@@ -0,0 +1,64 @@
+import logging
+
+import numpy as np
+
+from amprep.types import Frame
+
+_log = logging.getLogger(__name__)
+
+DEFAULT_THRESHOLD = 0.01
+"""Fraction of the frame that must be foreground to count as motion.
+
+Sits between a speck (about 0.25%) and a small object (about 2%) on
+synthetic scenes. Tune it on real footage using ``last_fraction``.
+"""
+
+
+class MotionTrigger:
+    """Says whether something is moving, one mask at a time.
+
+    Active when the foreground fraction is at or above ``threshold``,
+    idle below it. Reacts from the very first mask; warm-up is decided
+    by the background subtractor, not here.
+
+    Args:
+        threshold: Fraction of the frame, in (0, 1]. Defaults to
+            ``DEFAULT_THRESHOLD`` (1%).
+    """
+
+    def __init__(self, threshold: float = DEFAULT_THRESHOLD) -> None:
+        if isinstance(threshold, bool) or not isinstance(threshold, (int, float)):
+            raise ValueError(f"threshold must be a number, got {threshold!r}")
+        if not 0 < threshold <= 1:
+            raise ValueError(f"threshold must be in (0, 1], got {threshold!r}")
+        self._threshold = float(threshold)
+        self.reset()
+
+    @property
+    def threshold(self) -> float:
+        """The threshold in use."""
+        return self._threshold
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    @property
+    def last_fraction(self) -> float:
+        """Last measured fraction. Look at this to tune ``threshold``."""
+        return self._last_fraction
+
+    def reset(self) -> None:
+        self._active = False
+        self._last_fraction = 0.0
+
+    def update(self, mask: Frame) -> bool:
+        # ``count_nonzero`` hands back a NumPy integer, which would make
+        # the fraction a ``float64`` and the comparison below a
+        # ``np.bool_``, and ``np.bool_`` is not a ``bool``, so a caller
+        # writing ``if trigger.update(mask) is True`` would silently
+        # never match. Coercing here keeps both annotations honest.
+        self._last_fraction = float(np.count_nonzero(mask) / mask.size)
+        self._active = self._last_fraction >= self._threshold
+        _log.debug("foreground %.4f -> %s", self._last_fraction, self._active)
+        return self._active

amprep/noise_reducer.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+
+import cv2
+import numpy as np
+
+from amprep.types import Frame
+
+
+def _validate(frame: Frame, label: str) -> None:
+    """Raise ``TypeError`` when ``frame`` is not a valid video frame."""
+    if not isinstance(frame, np.ndarray):
+        raise TypeError(f"Expected {label} to be a NumPy array, got {type(frame)}")
+    if frame.dtype != np.uint8:
+        raise TypeError(f"Expected {label} to be uint8, got {frame.dtype}")
+
+
+class NoiseReducer(ABC):
+    """Removes sensor noise from a frame before background subtraction.
+
+    Subclass this and implement ``_apply`` to plug in your own denoising.
+    Do not override ``apply``: it validates the input and the returned
+    frame against the contract below. Pass an instance to
+    ``AdaptiveMotionPreprocessor(noise_reducer=...)``; leave it unset and
+    the package's default implementation is used instead.
+
+    Contract:
+        ``_apply`` must return a frame with the **same shape and dtype**
+        as its input: ``uint8``, ``(H, W, 3)``, BGR. Downstream stages
+        size their buffers from the first frame they see, so a stage that
+        changes shape mid-stream breaks them silently.
+    """
+
+    @abstractmethod
+    def _apply(self, frame: Frame) -> Frame:
+        """Return a denoised copy of ``frame``.
+
+        Args:
+            frame: The frame to denoise. See ``Frame`` for its contract.
+
+        Returns:
+            A frame of the same shape and dtype as the input.
+        """
+
+    def apply(self, frame: Frame) -> Frame:
+        """Return a denoised copy of ``frame``."""
+        _validate(frame, "the input frame")
+
+        result = self._apply(frame)
+
+        _validate(result, "the frame returned by _apply")
+        if result.shape != frame.shape:
+            raise ValueError(
+                f"_apply must preserve shape: {frame.shape} -> {result.shape}"
+            )
+
+        return result
+
+
+class MedianNoiseReducer(NoiseReducer):
+    """Removes sensor noise with a median filter.
+
+    The package default. A median discards extreme pixel values instead
+    of averaging them in, which suits the salt-and-pepper noise that
+    would otherwise become phantom foreground in the mask, and it blurs
+    edges far less than a Gaussian, so the silhouette the sampler and
+    encoder depend on stays sharp.
+
+    Args:
+        ksize: Aperture size, an odd integer greater than 1. Larger
+            removes more noise and costs more time. ``3`` is roughly
+            seven times faster with sharper edges, at about twice the
+            residual noise.
+    """
+
+    def __init__(self, ksize: int = 5) -> None:
+        if not isinstance(ksize, int) or ksize <= 1 or ksize % 2 == 0:
+            raise ValueError(
+                f"ksize must be an odd integer greater than 1, got {ksize!r}"
+            )
+        self._ksize = ksize
+
+    def _apply(self, frame: Frame) -> Frame:
+        return cv2.medianBlur(frame, self._ksize)

amprep/preprocessor.py

@@ -0,0 +1,163 @@
+from collections.abc import Iterable, Iterator
+
+from amprep.adaptive_sampler import DEFAULT_SAMPLE_FRAMES, AdaptiveFrameSampler
+from amprep.background_subtractor import BackgroundSubtractor, KNNBackgroundSubtractor
+from amprep.frame_window import DEFAULT_WINDOW_FRAMES, FrameWindowCollector
+from amprep.motion_history_encoder import MotionHistoryEncoder
+from amprep.motion_trigger import DEFAULT_THRESHOLD, MotionTrigger
+from amprep.noise_reducer import MedianNoiseReducer, NoiseReducer
+from amprep.types import Frame, MotionImage
+
+
+class AdaptiveMotionPreprocessor:
+    """Turns video frames into encoded motion images.
+
+    The public entry point: one class holding the whole pipeline, with
+    each stage swappable for your own implementation.
+
+    Every stage argument defaults to ``None``, which is replaced here
+    with the packaged implementation of that stage. Resolving the
+    default inside ``__init__`` (rather than behind a factory or at the
+    first frame) means an assembled preprocessor always holds real
+    stage objects, so there is no second code path in which a stage is
+    still missing.
+
+    While motion lasts, one ``MotionImage`` comes out every
+    ``window_frames`` frames. A subject that lingers produces a
+    continuous stream, so a caller wiring this to a network should expect
+    that.
+
+    State carries across ``process()`` calls: splitting one stream into
+    chunks gives the same result as one call. Call ``reset()`` when the
+    scene changes. Frames must keep one size until then.
+
+    Args:
+        noise_reducer: Removes sensor noise before subtraction. Defaults
+            to ``MedianNoiseReducer``.
+        background_subtractor: Separates moving foreground from the
+            learned background. Defaults to ``KNNBackgroundSubtractor``.
+        motion_threshold: Share of the frame that must move. Default 1%.
+        window_frames: Frames per window. Default 10.
+        sample_frames: Frames kept per window. Default 4.
+        width: Output width, or ``None`` to keep the frame width.
+        height: Output height, or ``None`` to keep the frame height.
+    """
+
+    def __init__(
+        self,
+        noise_reducer: NoiseReducer | None = None,
+        background_subtractor: BackgroundSubtractor | None = None,
+        *,
+        motion_threshold: float = DEFAULT_THRESHOLD,
+        window_frames: int = DEFAULT_WINDOW_FRAMES,
+        sample_frames: int = DEFAULT_SAMPLE_FRAMES,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> None:
+        if noise_reducer is None:
+            noise_reducer = MedianNoiseReducer()
+        elif not isinstance(noise_reducer, NoiseReducer):
+            raise TypeError(
+                f"noise_reducer must be a NoiseReducer, got {type(noise_reducer)}"
+            )
+
+        if background_subtractor is None:
+            background_subtractor = KNNBackgroundSubtractor()
+        elif not isinstance(background_subtractor, BackgroundSubtractor):
+            raise TypeError(
+                "background_subtractor must be a BackgroundSubtractor, "
+                f"got {type(background_subtractor)}"
+            )
+
+        self._noise_reducer = noise_reducer
+        self._background_subtractor = background_subtractor
+
+        # Each stage checks its own setting.
+        self._trigger = MotionTrigger(threshold=motion_threshold)
+        self._collector = FrameWindowCollector(window_frames=window_frames)
+        self._sampler = AdaptiveFrameSampler(sample_frames=sample_frames)
+        self._encoder = MotionHistoryEncoder(width=width, height=height)
+
+        # The one check no single stage can do.
+        if self._sampler.sample_frames > self._collector.window_frames:
+            raise ValueError(
+                f"sample_frames ({sample_frames}) cannot exceed "
+                f"window_frames ({window_frames})"
+            )
+
+        self._frames_seen = 0
+        self._frame_shape: tuple[int, ...] | None = None
+
+    def process(self, frames: Iterable[Frame]) -> Iterator[MotionImage]:
+        """Turn a stream of frames into encoded motion images.
+
+        The input side of the pipeline, and the whole of it: the package
+        does no video I/O. Any iterable of frames is accepted (a list, a
+        generator, a custom iterator, a loop around a camera the caller
+        opened) because by the time a frame arrives here it is a
+        ``uint8`` BGR array, and where it came from is neither recoverable
+        nor needed. Capture stays outside the package on purpose: nothing
+        in here owns a device handle, so nothing in here can leak one.
+        The README carries the few lines that read frames from a file.
+
+        The stream is consumed lazily, one frame at a time, and is never
+        materialised. An unbounded source is therefore fine: a live
+        camera can be handed over and abandoned whenever the caller
+        likes. Because this is a generator, it does not touch the
+        input at all until it is iterated.
+
+        Frames must arrive in capture order. The stages behind this one
+        accumulate state across consecutive frames, so a shuffled stream
+        describes motion that never happened.
+
+        Args:
+            frames: The frames to process, in capture order. ``Frame``
+                gives the contract each one must satisfy; it is enforced
+                by ``NoiseReducer.apply`` on every frame, so it is not
+                re-checked here.
+
+        Yields:
+            One ``MotionImage`` per completed window.
+
+        Raises:
+            ValueError: If the frame size changes mid-stream. Call
+                ``reset()`` first when it is meant to.
+        """
+        for frame in frames:
+            denoised = self._noise_reducer.apply(frame)  # also validates the frame
+            self._check_frame_shape(denoised)
+            mask = self._background_subtractor.apply(denoised)
+
+            # The model still learns from these frames; only its verdict
+            # is ignored.
+            self._frames_seen += 1
+            if self._frames_seen <= self._background_subtractor.warmup_frames:
+                continue
+
+            active = self._trigger.update(mask)
+            window = self._collector.update(frame, mask, active)
+            if window is not None:
+                yield self._encoder.encode(window, self._sampler.select(window))
+
+    def reset(self) -> None:
+        """Start over for a new scene.
+
+        Forgets the background, motion, any half-full window, the warm-up
+        count and the frame size. Never called automatically: a fixed
+        camera fed in chunks should keep what it has learned.
+        """
+        self._background_subtractor.reset()
+        self._trigger.reset()
+        self._collector.reset()
+        self._frames_seen = 0
+        self._frame_shape = None
+
+    def _check_frame_shape(self, frame: Frame) -> None:
+        """Raise if the frame size changed since the stream began."""
+        if self._frame_shape is None:
+            self._frame_shape = frame.shape
+        elif frame.shape != self._frame_shape:
+            raise ValueError(
+                f"frame size changed from {self._frame_shape} to {frame.shape}; "
+                "call reset() before processing frames of a different size"
+            )

amprep/types.py

@@ -0,0 +1,94 @@
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+Frame = NDArray[np.uint8]
+"""A single video frame.
+
+Contract:
+    dtype:          ``numpy.uint8`` (values 0-255)
+    shape:          ``(H, W, 3)``
+    channel order:  **BGR**, the order OpenCV decodes a frame into
+
+BGR is not a bug to be fixed. Frames are consumed by OpenCV operations
+throughout the pipeline; converting to RGB here would silently change
+what every downstream stage sees.
+"""
+
+
+@dataclass(frozen=True)
+class MotionImage:
+    """The encoded output handed to a downstream neural network.
+
+    Contract:
+        ``data`` dtype:  ``numpy.uint8``
+        ``data`` shape:  ``(H, W)``, one channel. The ``width`` and
+                         ``height`` the preprocessor was given, or the
+                         size of the incoming frames when it was given
+                         none. Nothing is padded. It does not depend on
+                         how many frames were sampled or how fast the
+                         motion was, and the frame size cannot change
+                         mid-stream without ``reset()``, so it holds for
+                         every ``MotionImage`` of a stream.
+
+    A fixed shape is the point of this type: a downstream model declares
+    one input size, so a pipeline that sometimes emits a different shape
+    must fail loudly rather than at inference time.
+
+    Attributes:
+        data: The encoded motion image.
+        frame_indices: Indices, within the source window, of the frames
+            the adaptive sampler selected. Kept so the sampler's
+            behaviour is inspectable from its output alone.
+    """
+
+    data: Frame
+    frame_indices: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        """Ensure the image data uses 8-bit unsigned integer values."""
+        if self.data.dtype != np.uint8:
+            raise TypeError(f"MotionImage.data must be uint8, got {self.data.dtype}")
+
+
+@dataclass(frozen=True)
+class Window:
+    """A full run of consecutive frames, 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.
+
+    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.
+
+    Attributes:
+        frames: The frames, in capture order. See ``Frame``.
+        masks: The foreground mask for each frame, in the same 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:
+            raise ValueError("Window must not be empty")
+
+    def __len__(self) -> int:
+        """The number of frames in the window."""
+        return len(self.frames)