pixelflow 0.3.1__tar.gz → 0.5.0__tar.gz

{pixelflow-0.3.1 → pixelflow-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixelflow
-Version: 0.3.1
+Version: 0.5.0
 Summary: Computer vision processing library for visualizing and analyzing detection results from ML models
 Author-email: Emrah Nazif <emrah@datamarkin.com>, Datamarkin <support@datamarkin.com>
 License: MIT
@@ -52,12 +52,13 @@ import pixelflow as pf
 from ultralytics import YOLO
 
 model = YOLO("yolo11n.pt")
-video = pf.VideoReader("traffic.mp4", width=640)
+video = pf.VideoReader("traffic.mp4")
 tracker = pf.tracker.ByteTracker()
 zones = pf.Zones()
 zones.add_zone([(100, 400), (500, 400), (500, 600), (100, 600)], zone_id="entrance")
 
 for frame in video:
+    frame = pf.transform.resize(frame, width=640)
     detections = pf.from_ultralytics(model.predict(frame))
     detections = tracker.update(detections)
     zones.update(detections)
@@ -66,8 +67,7 @@ for frame in video:
     frame = pf.annotate.label(frame, detections)
     frame = pf.annotate.zones(frame, zones)
 
-    if pf.show_frame("Live", frame) == ord('q'):
-        break
+    pf.display_video(frame, "Live")   # raises DisplayExit when 'q' is pressed
 ```
 
 ## Installation
@@ -200,34 +200,64 @@ english_text = detections.filter_by_text_language("en")
 
 ### Media Handling
 
-Purpose-built classes for videos, cameras, and images:
+A source is anything that yields RGB `uint8` `HxWx3` arrays. `VideoReader` and
+`CameraStream` are conveniences, not gates — a list, a generator, or your own reader
+for the one camera that needs special handling all work identically everywhere else.
 
 ```python
 import pixelflow as pf
 
 # Read a video file
-video = pf.VideoReader("video.mp4", width=640)
-print(f"{video.width}x{video.height}, {video.fps}fps, {len(video)} frames")
+video = pf.VideoReader("video.mp4")
+print(f"{video.width}x{video.height}, {video.fps}fps, {video.frames} frames")
 
-for frame in video:       # Replayable — resets on each iteration
-    if pf.show_frame("Preview", frame) == ord('q'):
-        break
+for frame in video:
+    pf.display_video(frame, "Preview")
+
+video.seek(0)             # replay is explicit; iteration never rewinds on its own
 
-# Load a single image
-image = pf.read_image("photo.jpg", width=640)
+# Every 5th frame. fps and frames are divided to match, so a writer built from
+# this source stays correct.
+video = pf.VideoReader("video.mp4", stride=5)
 
-# Webcam / network stream
-cam = pf.CameraStream(0, width=640)
+# Load a single image (EXIF orientation applied, always RGB uint8 HxWx3)
+image = pf.read_image("photo.jpg")
+
+# Webcam / network stream — same facts, same iteration, is_live is True
+cam = pf.CameraStream(0)
 cam = pf.CameraStream("rtsp://camera.local/stream")
+```
 
-# Write processed video
-writer = pf.VideoWriter("output.mp4", fps=video.fps)
+Reading and resizing are two jobs — compose them:
+
+```python
 for frame in video:
-    processed = process(frame)
-    writer.write(processed)
-writer.close()
+    frame = pf.transform.resize(frame, width=640)   # or height=
 ```
 
+**Writing.** `like=` carries the frame rate across from a source, which is the one
+value that has to and the one that is easy to get wrong — a strided reader yields
+fewer frames per second than its file contains. Size is *not* carried: it comes from
+the first frame written, because the loop in between is allowed to resize.
+
+```python
+video = pf.VideoReader("input.mp4", stride=2)
+
+with pf.VideoWriter("output.mp4", like=video) as writer:
+    for frame in video:
+        writer.write(process(frame))
+```
+
+Every source reports the same facts, so consumers never branch on the source type:
+
+| | `VideoReader` | `CameraStream` |
+|---|---|---|
+| `width` / `height` | from the file | from a frame decoded at open |
+| `fps` | rate yielded, `None` if unknown | usually `None` — devices report 0 |
+| `frames` | estimate, divided by stride | always `None` |
+| `duration` | seconds, unaffected by stride | always `None` |
+| `is_live` | `False` | `True` |
+
 ### Zone-Based Analytics
 
 Define spatial regions and track what enters them:
@@ -280,7 +310,7 @@ import pixelflow as pf
 
 tracker = pf.tracker.ByteTracker()
 
-for frame in media.frames:
+for frame in video:
     detections = pf.from_ultralytics(model.predict(frame))
     detections = tracker.update(detections)
 
@@ -383,7 +413,7 @@ crossings.add_line(
     direction="down"  # Only count downward crossings
 )
 
-for frame in media.frames:
+for frame in video:
     detections = tracker.update(pf.from_ultralytics(model.predict(frame)))
     crossings.update(detections)
 

{pixelflow-0.3.1 → pixelflow-0.5.0}/README.md

@@ -14,12 +14,13 @@ import pixelflow as pf
 from ultralytics import YOLO
 
 model = YOLO("yolo11n.pt")
-video = pf.VideoReader("traffic.mp4", width=640)
+video = pf.VideoReader("traffic.mp4")
 tracker = pf.tracker.ByteTracker()
 zones = pf.Zones()
 zones.add_zone([(100, 400), (500, 400), (500, 600), (100, 600)], zone_id="entrance")
 
 for frame in video:
+    frame = pf.transform.resize(frame, width=640)
     detections = pf.from_ultralytics(model.predict(frame))
     detections = tracker.update(detections)
     zones.update(detections)
@@ -28,8 +29,7 @@ for frame in video:
     frame = pf.annotate.label(frame, detections)
     frame = pf.annotate.zones(frame, zones)
 
-    if pf.show_frame("Live", frame) == ord('q'):
-        break
+    pf.display_video(frame, "Live")   # raises DisplayExit when 'q' is pressed
 ```
 
 ## Installation
@@ -162,34 +162,64 @@ english_text = detections.filter_by_text_language("en")
 
 ### Media Handling
 
-Purpose-built classes for videos, cameras, and images:
+A source is anything that yields RGB `uint8` `HxWx3` arrays. `VideoReader` and
+`CameraStream` are conveniences, not gates — a list, a generator, or your own reader
+for the one camera that needs special handling all work identically everywhere else.
 
 ```python
 import pixelflow as pf
 
 # Read a video file
-video = pf.VideoReader("video.mp4", width=640)
-print(f"{video.width}x{video.height}, {video.fps}fps, {len(video)} frames")
+video = pf.VideoReader("video.mp4")
+print(f"{video.width}x{video.height}, {video.fps}fps, {video.frames} frames")
 
-for frame in video:       # Replayable — resets on each iteration
-    if pf.show_frame("Preview", frame) == ord('q'):
-        break
+for frame in video:
+    pf.display_video(frame, "Preview")
+
+video.seek(0)             # replay is explicit; iteration never rewinds on its own
 
-# Load a single image
-image = pf.read_image("photo.jpg", width=640)
+# Every 5th frame. fps and frames are divided to match, so a writer built from
+# this source stays correct.
+video = pf.VideoReader("video.mp4", stride=5)
 
-# Webcam / network stream
-cam = pf.CameraStream(0, width=640)
+# Load a single image (EXIF orientation applied, always RGB uint8 HxWx3)
+image = pf.read_image("photo.jpg")
+
+# Webcam / network stream — same facts, same iteration, is_live is True
+cam = pf.CameraStream(0)
 cam = pf.CameraStream("rtsp://camera.local/stream")
+```
 
-# Write processed video
-writer = pf.VideoWriter("output.mp4", fps=video.fps)
+Reading and resizing are two jobs — compose them:
+
+```python
 for frame in video:
-    processed = process(frame)
-    writer.write(processed)
-writer.close()
+    frame = pf.transform.resize(frame, width=640)   # or height=
 ```
 
+**Writing.** `like=` carries the frame rate across from a source, which is the one
+value that has to and the one that is easy to get wrong — a strided reader yields
+fewer frames per second than its file contains. Size is *not* carried: it comes from
+the first frame written, because the loop in between is allowed to resize.
+
+```python
+video = pf.VideoReader("input.mp4", stride=2)
+
+with pf.VideoWriter("output.mp4", like=video) as writer:
+    for frame in video:
+        writer.write(process(frame))
+```
+
+Every source reports the same facts, so consumers never branch on the source type:
+
+| | `VideoReader` | `CameraStream` |
+|---|---|---|
+| `width` / `height` | from the file | from a frame decoded at open |
+| `fps` | rate yielded, `None` if unknown | usually `None` — devices report 0 |
+| `frames` | estimate, divided by stride | always `None` |
+| `duration` | seconds, unaffected by stride | always `None` |
+| `is_live` | `False` | `True` |
+
 ### Zone-Based Analytics
 
 Define spatial regions and track what enters them:
@@ -242,7 +272,7 @@ import pixelflow as pf
 
 tracker = pf.tracker.ByteTracker()
 
-for frame in media.frames:
+for frame in video:
     detections = pf.from_ultralytics(model.predict(frame))
     detections = tracker.update(detections)
 
@@ -345,7 +375,7 @@ crossings.add_line(
     direction="down"  # Only count downward crossings
 )
 
-for frame in media.frames:
+for frame in video:
     detections = tracker.update(pf.from_ultralytics(model.predict(frame)))
     crossings.update(detections)
 

{pixelflow-0.3.1 → pixelflow-0.5.0}/pixelflow/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.1"
+__version__ = "0.5.0"
 __author__ = "Datamarkin"
 
 # Import core modules
@@ -9,8 +9,6 @@ from . import colors
 from . import slicer
 from . import smoother
 from . import timer
-from . import tracker
-from . import assets
 
 # Result types and their converters. Every model output PixelFlow understands becomes
 # one of two things: Detections for anything that localises, Classifications for
@@ -28,7 +26,7 @@ from .classifications import __all__ as _CLASSIFICATION_EXPORTS
 # Import specific functions for top-level access
 from .media import (
     DisplayExit, VideoReader, CameraStream, VideoWriter,
-    read_image, read_video, display_video, display_image, save_image,
+    read_image, read_video, encode_image, display_video, display_image, save_image,
     close_display, to_pil, from_pil,
 )
 from .zones import Zones
@@ -38,6 +36,36 @@ from .buffer import Buffer
 from .smoother import smooth
 from .timer import TimeTracker
 
+# ByteTrack is the only thing in PixelFlow that needs SciPy, and SciPy is most of what importing
+# PixelFlow costs: 436 ms of 631 ms, from scipy.linalg in the Kalman filter and scipy.optimize in
+# the assignment step. Every caller that only draws boxes or converts a model's output paid it.
+#
+# So `tracker` loads on first use instead of at import. This is PEP 562, the language feature for
+# exactly this, and it is what SciPy and NumPy do with their own subpackages -- `pf.tracker`,
+# `from pixelflow import tracker` and `import pixelflow.tracker` all still work, and the module is
+# cached in globals() after the first access so the cost is paid once.
+#
+# Nothing else in PixelFlow imports tracker, and it publishes no top-level names of its own, which
+# is what makes this a one-line deferral rather than a lazy-name table.
+_LAZY = {"tracker"}
+
+
+def __getattr__(name):
+    """Load a deferred subpackage on first access. See the note above."""
+    if name in _LAZY:
+        import importlib
+
+        module = importlib.import_module(f".{name}", __name__)
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """Keep the deferred subpackages visible to `dir()` and to tab completion."""
+    return sorted(set(globals()) | _LAZY)
+
+
 # Define the public API
 __all__ = [
     # Result types and converters, declared by the subpackages that own them
@@ -59,6 +87,7 @@ __all__ = [
     "VideoWriter",
     "read_image",
     "read_video",
+    "encode_image",
     "display_video",
     "display_image",
     "save_image",
@@ -73,7 +102,6 @@ __all__ = [
     "Crossings",
 
     # Processing utilities
-    "assets",
     "slicer",
     "SlicedInference",
     "auto_slice_size",

{pixelflow-0.3.1 → pixelflow-0.5.0}/pixelflow/detections/detections.py

@@ -9,6 +9,7 @@ different ML frameworks and visualization tools.
 
 import copy as copy_module
 import io
+import math
 import json
 import base64
 import numpy as np
@@ -661,13 +662,18 @@ class Detections:
         Appends a Detection instance to the internal collection, enabling batch
         processing and filtering operations on the complete detection set.
         
+        A detection that does not describe an object is dropped rather than stored:
+        one whose `bbox` is None -- never set, or rejected by `validate_bbox` as
+        non-finite, inverted or enclosing no pixels -- and one whose confidence is
+        NaN, which no threshold can compare against and which strict JSON parsers
+        refuse. Dropping at the boundary is what lets every consumer downstream
+        assume a detection has a box, rather than each re-deciding what to do
+        about one that does not.
+
         Args:
             detection (Detection): Detection object to add to the collection.
                                  Must be a valid Detection instance.
         
-        Raises:
-            TypeError: If detection is not a Detection instance.
-        
         Example:
             >>> import pixelflow as pf
             >>> 
@@ -681,8 +687,32 @@ class Detections:
             >>> detections.add_detection(detection2)
             >>> print(f"Total detections: {len(detections)}")
         """
+        # Geometry was already judged by validate_bbox on assignment, which leaves
+        # None for anything that does not enclose pixels.
+        if detection.bbox is None:
+            return
+        if detection.confidence is not None and math.isnan(detection.confidence):
+            return
+
         self.detections.append(detection)
     
+    def _drop_boxless(self) -> "Detections":
+        """
+        Remove detections whose box was invalidated by an in-place update.
+
+        `add_detection` judges a detection on the way in, but a transform rewrites
+        `bbox` on detections already stored, where nothing re-checks them. One that
+        shrinks a box to nothing - padding by a negative fraction, a box rebuilt
+        from a single keypoint - leaves it None, and the detection would otherwise
+        stay in the collection: still counted, with no geometry, and fatal to any
+        consumer that assumes it has one.
+
+        Returns:
+            Detections: This collection, for chaining.
+        """
+        self.detections = [d for d in self.detections if d.bbox is not None]
+        return self
+
     def update_zones(self, zone_manager: Any) -> 'Detections':
         """
         Update all detections with zone intersection information for spatial analytics.