Skip to main content

🎞️ 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

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:

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:

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.
  • 🎚️ 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.

📚 Examples

Metadata

Release files for adaptive-motion-preprocessing 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adaptive-motion-preprocessing 1.1.0
File Size Uploaded Provenance Actions
adaptive_motion_preprocessing-1.1.0.tar.gz 46.1 kB With provenance Details for adaptive_motion_preprocessing-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adaptive-motion-preprocessing 1.1.0
File Interpreter ABI Platform Actions
adaptive_motion_preprocessing-1.1.0-py3-none-any.whl Python 3 none any Details for adaptive_motion_preprocessing-1.1.0-py3-none-any.whl

Total release size: 68.3 kB

Release files / adaptive_motion_preprocessing-1.1.0.tar.gz

Download URL adaptive_motion_preprocessing-1.1.0.tar.gz
Size 46.1 kB
Tags Source
SHA-256 checksum
How to use checksums
69016f93ad4ae88d589bd7c384fa94bf5731799cf06c49f4cd2c19af5bf913ea
BLAKE2b-256 checksum
How to use checksums
ee38e66170baa7b75acd1b3bda39763f41a9d6ce53a6c86f3c40c3d531de4bde
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / adaptive_motion_preprocessing-1.1.0-py3-none-any.whl

Download URL adaptive_motion_preprocessing-1.1.0-py3-none-any.whl
Size 22.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
13b49a1122cce5211b4156561890f2790965e518d6293968fc6a2a68fd6bc932
BLAKE2b-256 checksum
How to use checksums
37165b9bcaa85d8fea022bf4ac10a6a1048842e3c7d70b7c10dca81a3026280b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for adaptive-motion-preprocessing 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for adaptive_motion_preprocessing-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page