adaptive-motion-preprocessing 1.0.0rc1__tar.gz

adaptive_motion_preprocessing-1.0.0rc1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly

adaptive_motion_preprocessing-1.0.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: python -m pip install ruff
+
+      - name: Ruff check
+        run: ruff check --output-format=github .
+
+      - name: Ruff format
+        run: ruff format --check --diff .
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install OpenCV system libraries
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libgl1 libglib2.0-0
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check metadata
+        run: twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

adaptive_motion_preprocessing-1.0.0rc1/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check metadata
+        run: twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/adaptive-motion-preprocessing
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

adaptive_motion_preprocessing-1.0.0rc1/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / lint caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

adaptive_motion_preprocessing-1.0.0rc1/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.

adaptive_motion_preprocessing-1.0.0rc1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,94 @@
+# 🎞️ 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/examples/custom_background_subtractor.py

@@ -0,0 +1,78 @@
+"""Plug your own background subtractor into the pipeline.
+
+Usage:
+    python examples/custom_background_subtractor.py
+
+Subclass ``BackgroundSubtractor``, implement ``_apply`` and ``reset``, and
+pass an instance by keyword. Nothing else changes: the same motion trigger,
+windowing, sampling and encoding run behind it, and the motion images come
+out in the same shape. The script runs the default pipeline and the custom
+one over the same synthetic clip so the two can be compared.
+"""
+
+import cv2
+import numpy as np
+
+from amprep import AdaptiveMotionPreprocessor, BackgroundSubtractor
+
+
+class FrameDifferenceSubtractor(BackgroundSubtractor):
+    """Foreground is whatever changed since the previous frame.
+
+    Far cruder than the default KNN model, but it is useful from its very
+    first frame, so it has no warm-up to declare.
+
+    ``_apply`` receives a ``uint8`` ``(H, W, 3)`` BGR frame and must return a
+    ``uint8`` ``(H, W)`` mask. ``apply``, which you do not override, checks
+    both. ``reset`` forgets the previous frame when the scene changes.
+    """
+
+    def __init__(self, threshold: int = 25) -> None:
+        self._threshold = threshold
+        self._previous: np.ndarray | None = None
+
+    def _apply(self, frame: np.ndarray) -> np.ndarray:
+        grey = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        if self._previous is None:
+            mask = np.zeros_like(grey)
+        else:
+            changed = cv2.absdiff(grey, self._previous) > self._threshold
+            mask = np.where(changed, np.uint8(255), np.uint8(0))
+        self._previous = grey
+        return mask
+
+    def reset(self) -> None:
+        self._previous = None
+
+
+def synthetic_clip() -> list[np.ndarray]:
+    """Ten still frames, a square sliding right for thirty, ten still again."""
+    frames = []
+    for index in range(50):
+        frame = np.full((120, 240, 3), 90, dtype=np.uint8)
+        if 10 <= index < 40:
+            left = 10 + (index - 10) * 6
+            frame[40:80, left : left + 40] = 200
+        frames.append(frame)
+    return frames
+
+
+def show(title: str, preprocessor: AdaptiveMotionPreprocessor) -> None:
+    print(title)
+    for image in preprocessor.process(synthetic_clip()):
+        print(
+            f"  shape {image.data.shape}, dtype {image.data.dtype}, "
+            f"frames {image.frame_indices}"
+        )
+
+
+def main() -> None:
+    show("Default background subtractor (KNN):", AdaptiveMotionPreprocessor())
+    show(
+        "Custom background subtractor (FrameDifferenceSubtractor):",
+        AdaptiveMotionPreprocessor(background_subtractor=FrameDifferenceSubtractor()),
+    )
+
+
+if __name__ == "__main__":
+    main()

adaptive_motion_preprocessing-1.0.0rc1/examples/from_video_file.py

@@ -0,0 +1,50 @@
+"""Run the preprocessor over a video file.
+
+Usage:
+    python examples/from_video_file.py path/to/clip.mp4
+
+Prints the shape of each motion image the moment it is produced.
+
+Reading video is the caller's job: the package takes any iterable of
+``uint8`` BGR frames and never opens a file or camera itself. ``frames_from``
+below is the few lines that bridge the two. Keep its ``try``/``finally``:
+without it the capture handle leaks whenever the loop is left early.
+"""
+
+import argparse
+import sys
+
+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()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("path", help="video file to read")
+    args = parser.parse_args()
+
+    preprocessor = AdaptiveMotionPreprocessor()
+    try:
+        for number, image in enumerate(preprocessor.process(frames_from(args.path))):
+            print(f"motion image {number}: shape {image.data.shape}", flush=True)
+    except OSError as error:
+        sys.exit(str(error))
+
+
+if __name__ == "__main__":
+    main()

adaptive_motion_preprocessing-1.0.0rc1/examples/live_camera.py

@@ -0,0 +1,120 @@
+"""Watch the preprocessor work on your webcam, live.
+
+Usage:
+    python examples/live_camera.py
+    python examples/live_camera.py --camera 1 --window-frames 15
+
+One window shows the camera on the left and the latest motion image on
+the right. Move in front of the camera: while you keep moving, a new
+motion image appears every ``window_frames`` frames. Press q or Esc, or
+close the window, to quit.
+
+The first few frames only teach the background, so stay out of shot for
+a moment after starting.
+"""
+
+import argparse
+import sys
+
+import cv2
+import numpy as np
+
+from amprep import AdaptiveMotionPreprocessor, MotionImage
+
+WINDOW = "amprep live: camera | motion image"
+QUIT_KEYS = {ord("q"), 27}  # q, Esc
+MAX_DISPLAY_WIDTH = 1600
+"""Wider views are shrunk for the screen. Only the display, never the input."""
+
+
+def compose(frame: np.ndarray, image: MotionImage | None, count: int) -> np.ndarray:
+    """Put the camera frame and the latest motion image side by side."""
+    left = frame.copy()
+    if image is None:
+        right = np.zeros_like(frame)
+        caption = "waiting for motion..."
+    else:
+        right = cv2.cvtColor(image.data, cv2.COLOR_GRAY2BGR)
+        caption = f"motion image #{count}  frames {image.frame_indices}"
+    _label(left, "camera")
+    _label(right, caption)
+    return np.hstack([left, right])
+
+
+def _label(canvas: np.ndarray, text: str) -> None:
+    cv2.rectangle(canvas, (0, 0), (canvas.shape[1], 28), (0, 0, 0), thickness=-1)
+    cv2.putText(
+        canvas, text, (8, 20), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 1
+    )
+
+
+class LiveView:
+    """The on-screen window, plus the latest motion image to draw in it."""
+
+    def __init__(self) -> None:
+        self.image: MotionImage | None = None
+        self.count = 0
+
+    def show(self, frame: np.ndarray) -> bool:
+        """Draw one frame. Returns ``False`` once the user wants to quit."""
+        view = compose(frame, self.image, self.count)
+        if view.shape[1] > MAX_DISPLAY_WIDTH:
+            scale = MAX_DISPLAY_WIDTH / view.shape[1]
+            view = cv2.resize(view, None, fx=scale, fy=scale)
+        cv2.imshow(WINDOW, view)
+
+        if cv2.waitKey(1) & 0xFF in QUIT_KEYS:
+            return False
+        # Closing the window with its X button makes it invisible.
+        return cv2.getWindowProperty(WINDOW, cv2.WND_PROP_VISIBLE) >= 1
+
+
+def camera_frames(index: int, view: LiveView):
+    """Yield webcam frames, drawing each one after the pipeline has seen it.
+
+    Drawing happens here rather than in the loop over ``process()``,
+    because that loop only runs when a motion image comes out, while the
+    live video has to update on every frame.
+    """
+    capture = cv2.VideoCapture(index)
+    try:
+        if not capture.isOpened():
+            raise OSError(f"cannot open camera {index}")
+        while True:
+            ok, frame = capture.read()
+            if not ok:
+                return
+            yield frame
+            # By now the pipeline has processed this frame, and any motion
+            # image it produced is already in the view.
+            if not view.show(frame):
+                return
+    finally:
+        capture.release()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--camera", type=int, default=0, help="camera index")
+    parser.add_argument("--window-frames", type=int, default=10)
+    parser.add_argument("--threshold", type=float, default=0.01)
+    args = parser.parse_args()
+
+    preprocessor = AdaptiveMotionPreprocessor(
+        motion_threshold=args.threshold, window_frames=args.window_frames
+    )
+    view = LiveView()
+    try:
+        for image in preprocessor.process(camera_frames(args.camera, view)):
+            view.image = image
+            view.count += 1
+    except OSError as error:
+        sys.exit(str(error))
+    finally:
+        cv2.destroyAllWindows()
+
+    print(f"{view.count} motion images")
+
+
+if __name__ == "__main__":
+    main()