pixelflow 0.3.2__tar.gz → 0.6.0__tar.gz

{pixelflow-0.3.2 → pixelflow-0.6.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 datamarkin
+Copyright (c) 2025 Emrah NAZIF
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{pixelflow-0.3.2 → pixelflow-0.6.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: pixelflow
-Version: 0.3.2
+Version: 0.6.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>
+Author-email: Emrah Nazif <emrah@datamarkin.com>
 License: MIT
-Project-URL: Homepage, https://github.com/datamarkin/pixelflow
-Project-URL: Repository, https://github.com/datamarkin/pixelflow
-Project-URL: Issues, https://github.com/datamarkin/pixelflow/issues
-Project-URL: Documentation, https://pixelflow.datamarkin.com
+Project-URL: Homepage, https://github.com/emrahnazif/pixelflow
+Project-URL: Repository, https://github.com/emrahnazif/pixelflow
+Project-URL: Issues, https://github.com/emrahnazif/pixelflow/issues
+Project-URL: Documentation, https://emrah.fr/pixelflow/
 Keywords: computer-vision,visualization,annotation,post-processing,tracking,opencv,yolo,detectron2,mayaku,ml-results
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -15,14 +15,13 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Image Recognition
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: shapely>=2.0.0
@@ -39,8 +38,8 @@ Dynamic: license-file
 # PixelFlow
 
 [![PyPI version](https://badge.fury.io/py/pixelflow.svg)](https://badge.fury.io/py/pixelflow)
-[![CI](https://github.com/datamarkin/pixelflow/actions/workflows/ci.yml/badge.svg)](https://github.com/datamarkin/pixelflow/actions/workflows/ci.yml)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/emrahnazif/pixelflow/actions/workflows/ci.yml/badge.svg)](https://github.com/emrahnazif/pixelflow/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **The computer vision library that gets out of your way.**
@@ -52,12 +51,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 +66,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
@@ -132,6 +131,17 @@ detections = pf.from_easyocr(reader.readtext("sign.jpg"))
 detections = pf.from_arrays(boxes, scores, class_ids, labels=model.class_names)
 ```
 
+Segmentation models answer with raster masks. One call turns them into polygons,
+whichever model they came from:
+
+```python
+detections = pf.from_arrays(boxes, scores, masks=masks)   # boolean (N, H, W)
+detections.masks_to_segments()                            # fills det.segments
+detections.masks_to_segments(keep_masks=False)            # ...and drops the rasters
+
+polygon = pf.mask_to_polygon(mask)                        # or one mask at a time
+```
+
 ### Classifications - When the Model Only Names
 
 A classifier localises nothing, so its result carries no geometry at all:
@@ -200,34 +210,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
+
+# 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)
 
-# Load a single image
-image = pf.read_image("photo.jpg", width=640)
+# Load a single image (EXIF orientation applied, always RGB uint8 HxWx3)
+image = pf.read_image("photo.jpg")
 
-# Webcam / network stream
-cam = pf.CameraStream(0, width=640)
+# Webcam / network stream — same facts, same iteration, is_live is True
+cam = pf.CameraStream(0)
 cam = pf.CameraStream("rtsp://camera.local/stream")
+```
+
+Reading and resizing are two jobs — compose them:
 
-# Write processed video
-writer = pf.VideoWriter("output.mp4", fps=video.fps)
+```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 +320,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 +423,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)
 
@@ -427,7 +467,7 @@ report = detections.to_json_with_metrics()
 
 ## Documentation
 
-Full documentation available at [https://datamarkin.com/docs/pixelflow/](https://datamarkin.com/docs/pixelflow/)
+Full documentation available at [https://emrah.fr/pixelflow/](https://emrah.fr/pixelflow/)
 
 ## Contributing
 
@@ -439,4 +479,4 @@ MIT License - see LICENSE file for details.
 
 ---
 
-Built with love by [Datamarkin](https://datamarkin.com)
+Built with love by [Emrah Nazif](https://emrah.fr)

{pixelflow-0.3.2 → pixelflow-0.6.0}/README.md

@@ -1,8 +1,8 @@
 # PixelFlow
 
 [![PyPI version](https://badge.fury.io/py/pixelflow.svg)](https://badge.fury.io/py/pixelflow)
-[![CI](https://github.com/datamarkin/pixelflow/actions/workflows/ci.yml/badge.svg)](https://github.com/datamarkin/pixelflow/actions/workflows/ci.yml)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/emrahnazif/pixelflow/actions/workflows/ci.yml/badge.svg)](https://github.com/emrahnazif/pixelflow/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **The computer vision library that gets out of your way.**
@@ -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
@@ -94,6 +94,17 @@ detections = pf.from_easyocr(reader.readtext("sign.jpg"))
 detections = pf.from_arrays(boxes, scores, class_ids, labels=model.class_names)
 ```
 
+Segmentation models answer with raster masks. One call turns them into polygons,
+whichever model they came from:
+
+```python
+detections = pf.from_arrays(boxes, scores, masks=masks)   # boolean (N, H, W)
+detections.masks_to_segments()                            # fills det.segments
+detections.masks_to_segments(keep_masks=False)            # ...and drops the rasters
+
+polygon = pf.mask_to_polygon(mask)                        # or one mask at a time
+```
+
 ### Classifications - When the Model Only Names
 
 A classifier localises nothing, so its result carries no geometry at all:
@@ -162,34 +173,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
+
+# 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)
 
-# Load a single image
-image = pf.read_image("photo.jpg", width=640)
+# Load a single image (EXIF orientation applied, always RGB uint8 HxWx3)
+image = pf.read_image("photo.jpg")
 
-# Webcam / network stream
-cam = pf.CameraStream(0, width=640)
+# Webcam / network stream — same facts, same iteration, is_live is True
+cam = pf.CameraStream(0)
 cam = pf.CameraStream("rtsp://camera.local/stream")
+```
+
+Reading and resizing are two jobs — compose them:
 
-# Write processed video
-writer = pf.VideoWriter("output.mp4", fps=video.fps)
+```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 +283,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 +386,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)
 
@@ -389,7 +430,7 @@ report = detections.to_json_with_metrics()
 
 ## Documentation
 
-Full documentation available at [https://datamarkin.com/docs/pixelflow/](https://datamarkin.com/docs/pixelflow/)
+Full documentation available at [https://emrah.fr/pixelflow/](https://emrah.fr/pixelflow/)
 
 ## Contributing
 
@@ -401,4 +442,4 @@ MIT License - see LICENSE file for details.
 
 ---
 
-Built with love by [Datamarkin](https://datamarkin.com)
+Built with love by [Emrah Nazif](https://emrah.fr)

{pixelflow-0.3.2 → pixelflow-0.6.0}/pixelflow/__init__.py

@@ -1,5 +1,5 @@
-__version__ = "0.3.2"
-__author__ = "Datamarkin"
+__version__ = "0.6.0"
+__author__ = "Emrah NAZIF"
 
 # Import core modules
 from . import media
@@ -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,9 +26,10 @@ 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 .masks import mask_to_polygon
 from .zones import Zones
 from .crossings import Crossings
 from .slicer import SlicedInference, auto_slice_size
@@ -38,6 +37,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 +88,7 @@ __all__ = [
     "VideoWriter",
     "read_image",
     "read_video",
+    "encode_image",
     "display_video",
     "display_image",
     "save_image",
@@ -66,6 +96,9 @@ __all__ = [
     "to_pil",
     "from_pil",
 
+    # Mask geometry
+    "mask_to_polygon",
+
     # Spatial analysis
     "zones",
     "Zones",
@@ -73,7 +106,6 @@ __all__ = [
     "Crossings",
 
     # Processing utilities
-    "assets",
     "slicer",
     "SlicedInference",
     "auto_slice_size",