pixelflow 0.1.1__tar.gz → 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. pixelflow-0.1.3/PKG-INFO +379 -0
  2. pixelflow-0.1.3/README.md +341 -0
  3. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/__init__.py +34 -13
  4. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/__init__.py +12 -7
  5. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/anchors.py +2 -2
  6. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/box.py +3 -3
  7. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/crossing.py +6 -6
  8. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/filled_box.py +4 -4
  9. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/fps_counter.py +9 -6
  10. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/grid_overlay.py +4 -4
  11. pixelflow-0.1.3/pixelflow/annotators/keypoint.py +134 -0
  12. pixelflow-0.1.3/pixelflow/annotators/keypoint_skeleton.py +165 -0
  13. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/label.py +4 -4
  14. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/mask.py +3 -3
  15. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/oval.py +4 -10
  16. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/polygon.py +4 -4
  17. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/utils.py +9 -9
  18. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/zones.py +1 -1
  19. pixelflow-0.1.3/pixelflow/assets.py +364 -0
  20. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/buffer.py +24 -25
  21. pixelflow-0.1.3/pixelflow/classes.py +86 -0
  22. pixelflow-0.1.3/pixelflow/colors.py +100 -0
  23. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/detections/__init__.py +20 -9
  24. pixelflow-0.1.3/pixelflow/detections/converters.py +1072 -0
  25. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/detections/detections.py +261 -46
  26. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/detections/filters.py +32 -48
  27. pixelflow-0.1.3/pixelflow/media.py +458 -0
  28. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/slicer.py +6 -6
  29. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/smoother.py +14 -9
  30. pixelflow-0.1.3/pixelflow/transforms/__init__.py +136 -0
  31. pixelflow-0.1.3/pixelflow/transforms/detections.py +911 -0
  32. pixelflow-0.1.3/pixelflow/transforms/image.py +468 -0
  33. pixelflow-0.1.3/pixelflow/transforms/inverse.py +440 -0
  34. pixelflow-0.1.3/pixelflow.egg-info/PKG-INFO +379 -0
  35. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow.egg-info/SOURCES.txt +7 -1
  36. pixelflow-0.1.3/pixelflow.egg-info/requires.txt +10 -0
  37. {pixelflow-0.1.1 → pixelflow-0.1.3}/pyproject.toml +13 -5
  38. pixelflow-0.1.1/PKG-INFO +0 -144
  39. pixelflow-0.1.1/README.md +0 -111
  40. pixelflow-0.1.1/pixelflow/annotators/keypoint.py +0 -11
  41. pixelflow-0.1.1/pixelflow/annotators/keypoint_skeleton.py +0 -11
  42. pixelflow-0.1.1/pixelflow/colors.py +0 -100
  43. pixelflow-0.1.1/pixelflow/detections/converters.py +0 -693
  44. pixelflow-0.1.1/pixelflow/media.py +0 -427
  45. pixelflow-0.1.1/pixelflow.egg-info/PKG-INFO +0 -144
  46. pixelflow-0.1.1/pixelflow.egg-info/requires.txt +0 -4
  47. {pixelflow-0.1.1 → pixelflow-0.1.3}/LICENSE +0 -0
  48. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/blur.py +0 -0
  49. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/dot.py +0 -0
  50. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/heatmap.py +0 -0
  51. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/motion_dots.py +0 -0
  52. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/motion_trails.py +0 -0
  53. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/pixelate.py +0 -0
  54. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/annotators/scale_bar.py +0 -0
  55. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/crossings.py +0 -0
  56. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/strategies.py +0 -0
  57. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/timer.py +0 -0
  58. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/tracker/__init__.py +0 -0
  59. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/tracker/bytetrack.py +0 -0
  60. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/tracker/kalman_filter.py +0 -0
  61. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/tracker/matching.py +0 -0
  62. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/tracker/track.py +0 -0
  63. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/validators.py +0 -0
  64. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow/zones.py +0 -0
  65. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow.egg-info/dependency_links.txt +0 -0
  66. {pixelflow-0.1.1 → pixelflow-0.1.3}/pixelflow.egg-info/top_level.txt +0 -0
  67. {pixelflow-0.1.1 → pixelflow-0.1.3}/setup.cfg +0 -0
@@ -0,0 +1,379 @@
1
+ Metadata-Version: 2.4
2
+ Name: pixelflow
3
+ Version: 0.1.3
4
+ Summary: Computer vision processing library for visualizing and analyzing detection results from ML models
5
+ Author-email: Emrah Nazif <emrah@datamarkin.com>, Datamarkin <support@datamarkin.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/datamarkin/pixelflow
8
+ Project-URL: Repository, https://github.com/datamarkin/pixelflow
9
+ Project-URL: Issues, https://github.com/datamarkin/pixelflow/issues
10
+ Project-URL: Documentation, https://pixelflow.datamarkin.com
11
+ Keywords: computer-vision,visualization,annotation,post-processing,tracking,opencv,yolo,detectron2,ml-results
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
23
+ Classifier: Topic :: Scientific/Engineering :: Image Recognition
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: shapely>=2.0.0
29
+ Requires-Dist: numpy>=1.21.0
30
+ Requires-Dist: opencv-python>=4.8.0
31
+ Requires-Dist: scipy>=1.10.0
32
+ Requires-Dist: Pillow>=9.0.0
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
35
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
36
+ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # PixelFlow
40
+
41
+ [![PyPI version](https://badge.fury.io/py/pixelflow.svg)](https://badge.fury.io/py/pixelflow)
42
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
43
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
44
+
45
+ **The computer vision library that gets out of your way.**
46
+
47
+ PixelFlow provides a unified, intuitive API for object detection, tracking, annotation, and video processing. Write clean, readable pipelines that work with any ML framework.
48
+
49
+ ```python
50
+ import pixelflow as pf
51
+ from ultralytics import YOLO
52
+
53
+ model = YOLO("yolo11n.pt")
54
+ video = pf.VideoReader("traffic.mp4", width=640)
55
+ tracker = pf.tracker.ByteTracker()
56
+ zones = pf.Zones()
57
+ zones.add_zone([(100, 400), (500, 400), (500, 600), (100, 600)], zone_id="entrance")
58
+
59
+ for frame in video:
60
+ detections = pf.detections.from_ultralytics(model.predict(frame))
61
+ detections = tracker.update(detections)
62
+ zones.update(detections)
63
+
64
+ frame = pf.annotate.box(frame, detections)
65
+ frame = pf.annotate.label(frame, detections)
66
+ frame = pf.annotate.zones(frame, zones)
67
+
68
+ if pf.show_frame("Live", frame) == ord('q'):
69
+ break
70
+ ```
71
+
72
+ ## Installation
73
+
74
+ ```bash
75
+ pip install pixelflow
76
+ ```
77
+
78
+ ## Core Concepts
79
+
80
+ ### Detections - One Format, Every Framework
81
+
82
+ Convert outputs from any ML framework into a unified format:
83
+
84
+ ```python
85
+ import pixelflow as pf
86
+
87
+ # Ultralytics YOLO
88
+ from ultralytics import YOLO
89
+ model = YOLO("yolo11n.pt")
90
+ detections = pf.detections.from_ultralytics(model.predict(image))
91
+
92
+ # Detectron2
93
+ from detectron2.engine import DefaultPredictor
94
+ predictor = DefaultPredictor(cfg)
95
+ detections = pf.detections.from_detectron2(predictor(image), class_names=["person", "car"])
96
+
97
+ # HuggingFace Transformers
98
+ from transformers import pipeline
99
+ detector = pipeline("object-detection")
100
+ detections = pf.detections.from_transformers(detector(image))
101
+
102
+ # Florence-2
103
+ detections = pf.detections.from_florence2(model_output)
104
+
105
+ # SAM (Segment Anything)
106
+ detections = pf.detections.from_sam(masks, scores)
107
+
108
+ # OCR Engines
109
+ detections = pf.detections.from_tesseract(tesseract_output)
110
+ detections = pf.detections.from_paddleocr(paddleocr_output)
111
+ detections = pf.detections.from_easyocr(easyocr_output)
112
+ ```
113
+
114
+ ### Powerful Filtering
115
+
116
+ Chain filters for complex queries with zero overhead:
117
+
118
+ ```python
119
+ # Get high-confidence people in the parking zone, tracked for 5+ seconds
120
+ results = (detections
121
+ .filter_by_confidence(min_confidence=0.7)
122
+ .filter_by_class_id("person")
123
+ .filter_by_zones(["parking_lot"])
124
+ .filter_by_tracking_duration(min_seconds=5.0))
125
+
126
+ # Size-based filtering
127
+ large_objects = detections.filter_by_size(min_area=10000)
128
+ tall_objects = detections.filter_by_dimensions(min_height=200)
129
+ squares = detections.filter_by_aspect_ratio(min_ratio=0.9, max_ratio=1.1)
130
+
131
+ # Spatial filtering
132
+ left_side = detections.filter_by_position(max_x=frame_width // 2)
133
+
134
+ # Remove overlapping detections
135
+ unique = detections.remove_duplicates(iou_threshold=0.5)
136
+
137
+ # OCR-specific filters
138
+ titles = detections.filter_by_text_level("title")
139
+ english_text = detections.filter_by_text_language("en")
140
+ ```
141
+
142
+ ### Media Handling
143
+
144
+ Purpose-built classes for videos, cameras, and images:
145
+
146
+ ```python
147
+ import pixelflow as pf
148
+
149
+ # Read a video file
150
+ video = pf.VideoReader("video.mp4", width=640)
151
+ print(f"{video.width}x{video.height}, {video.fps}fps, {len(video)} frames")
152
+
153
+ for frame in video: # Replayable — resets on each iteration
154
+ if pf.show_frame("Preview", frame) == ord('q'):
155
+ break
156
+
157
+ # Load a single image
158
+ image = pf.read_image("photo.jpg", width=640)
159
+
160
+ # Webcam / network stream
161
+ cam = pf.CameraStream(0, width=640)
162
+ cam = pf.CameraStream("rtsp://camera.local/stream")
163
+
164
+ # Write processed video
165
+ writer = pf.VideoWriter("output.mp4", fps=video.fps)
166
+ for frame in video:
167
+ processed = process(frame)
168
+ writer.write(processed)
169
+ writer.close()
170
+ ```
171
+
172
+ ### Zone-Based Analytics
173
+
174
+ Define spatial regions and track what enters them:
175
+
176
+ ```python
177
+ import pixelflow as pf
178
+
179
+ zones = pf.Zones()
180
+
181
+ # Define zones with different trigger strategies
182
+ zones.add_zone(
183
+ polygon=[(100, 400), (300, 400), (300, 600), (100, 600)],
184
+ zone_id="entrance",
185
+ name="Main Entrance",
186
+ trigger_strategy="bottom_center" # Trigger when bottom-center of bbox enters
187
+ )
188
+
189
+ zones.add_zone(
190
+ polygon=[(500, 200), (700, 200), (700, 500), (500, 500)],
191
+ zone_id="restricted",
192
+ trigger_strategy="percentage",
193
+ overlap_threshold=0.3 # Trigger when 30% of bbox is inside
194
+ )
195
+
196
+ # Update detections with zone info
197
+ zones.update(detections)
198
+
199
+ # Access zone statistics
200
+ print(zones.get_zone_counts()) # {'entrance': 3, 'restricted': 1}
201
+ print(zones.get_zone_stats()) # Detailed stats including total_entered
202
+
203
+ # Filter by zone
204
+ entrance_only = zones.filter_by_zones(detections, ["entrance"])
205
+ not_restricted = zones.filter_by_zones(detections, ["restricted"], exclude=True)
206
+ ```
207
+
208
+ **Trigger Strategies:**
209
+ - `center` - Bounding box center point (default)
210
+ - `bottom_center` - Bottom-center point (great for people/vehicles)
211
+ - `percentage` - Percentage of bbox overlap
212
+ - `overlap` - Any intersection
213
+ - Multiple strategies with `mode="any"` or `mode="all"`
214
+
215
+ ### Object Tracking
216
+
217
+ Built-in ByteTrack for multi-object tracking:
218
+
219
+ ```python
220
+ import pixelflow as pf
221
+
222
+ tracker = pf.tracker.ByteTracker()
223
+
224
+ for frame in media.frames:
225
+ detections = pf.detections.from_ultralytics(model.predict(frame))
226
+ detections = tracker.update(detections)
227
+
228
+ for det in detections:
229
+ print(f"Track ID: {det.tracker_id}, Class: {det.class_name}")
230
+ print(f"First seen: {det.first_seen_time}, Duration: {det.total_time}s")
231
+ ```
232
+
233
+ ### Rich Annotations
234
+
235
+ Beautiful, customizable visualizations:
236
+
237
+ ```python
238
+ import pixelflow as pf
239
+
240
+ # Bounding boxes and labels
241
+ frame = pf.annotate.box(frame, detections, thickness=2)
242
+ frame = pf.annotate.label(frame, detections, font_scale=0.6)
243
+
244
+ # Segmentation masks
245
+ frame = pf.annotate.mask(frame, detections, opacity=0.4)
246
+
247
+ # Keypoints and skeletons (pose estimation)
248
+ frame = pf.annotate.keypoint(frame, detections)
249
+ frame = pf.annotate.keypoint_skeleton(frame, detections)
250
+
251
+ # Zone visualization
252
+ frame = pf.annotate.zones(frame, zones)
253
+ frame = pf.annotate.crossings(frame, crossings)
254
+
255
+ # Privacy protection
256
+ frame = pf.annotate.blur(frame, detections, kernel_size=51)
257
+ frame = pf.annotate.pixelate(frame, detections, pixel_size=15)
258
+
259
+ # Shapes
260
+ frame = pf.annotate.oval(frame, detections)
261
+ frame = pf.annotate.polygon(frame, detections)
262
+ ```
263
+
264
+ ### Image Transforms
265
+
266
+ Comprehensive image and detection-aware transformations:
267
+
268
+ ```python
269
+ import pixelflow as pf
270
+
271
+ # Image-only transforms
272
+ rotated = pf.transform.rotate(image, 45)
273
+ flipped = pf.transform.flip_horizontal(image)
274
+ cropped = pf.transform.crop(image, [100, 50, 500, 400])
275
+
276
+ # Enhancement
277
+ enhanced = pf.transform.clahe(image)
278
+ gray = pf.transform.to_grayscale(image)
279
+ corrected = pf.transform.gamma_correction(image, gamma=1.2)
280
+
281
+ # Detection-aware transforms (coordinates update automatically)
282
+ rotated_img, rotated_dets = pf.transform.rotate_detections(image, detections, 45)
283
+ flipped_img, flipped_dets = pf.transform.flip_horizontal_detections(image, detections)
284
+ cropped_img, cropped_dets = pf.transform.crop_detections(image, detections, bbox=[100, 50, 500, 400])
285
+
286
+ # Automatic inverse transforms (undo all transforms)
287
+ original_coords = pf.transform.inverse_transforms(transformed_detections)
288
+ ```
289
+
290
+ ### Sliced Inference for Large Images
291
+
292
+ Detect small objects in high-resolution images:
293
+
294
+ ```python
295
+ import pixelflow as pf
296
+
297
+ slicer = pf.SlicedInference(
298
+ slice_height=640,
299
+ slice_width=640,
300
+ overlap_ratio_h=0.2,
301
+ overlap_ratio_w=0.2
302
+ )
303
+
304
+ def detector(image):
305
+ return pf.detections.from_ultralytics(model.predict(image))
306
+
307
+ # Run on 4K image - automatically slices, detects, and merges
308
+ large_image = cv2.imread("satellite.jpg") # 4000x3000
309
+ detections = slicer.predict(large_image, detector)
310
+ ```
311
+
312
+ ### Line Crossing Detection
313
+
314
+ Track objects crossing defined lines:
315
+
316
+ ```python
317
+ import pixelflow as pf
318
+
319
+ crossings = pf.Crossings()
320
+ crossings.add_line(
321
+ start=(100, 300),
322
+ end=(500, 300),
323
+ line_id="entry_line",
324
+ direction="down" # Only count downward crossings
325
+ )
326
+
327
+ for frame in media.frames:
328
+ detections = tracker.update(pf.detections.from_ultralytics(model.predict(frame)))
329
+ crossings.update(detections)
330
+
331
+ print(f"Crossed: {crossings.get_counts()}")
332
+ frame = pf.annotate.crossings(frame, crossings)
333
+ ```
334
+
335
+ ### Serialization
336
+
337
+ Export and import detection data:
338
+
339
+ ```python
340
+ # To JSON
341
+ json_str = detections.to_json()
342
+
343
+ # To dictionary (for pandas, etc.)
344
+ data = detections.to_dict()
345
+ df = pd.DataFrame(data)
346
+
347
+ # With metrics
348
+ report = detections.to_json_with_metrics()
349
+ ```
350
+
351
+ ## Supported Frameworks
352
+
353
+ | Framework | Converter | Features |
354
+ |-----------|-----------|----------|
355
+ | Ultralytics (YOLO) | `from_ultralytics()` | Boxes, masks, keypoints |
356
+ | Detectron2 | `from_detectron2()` | Boxes, masks, keypoints |
357
+ | HuggingFace Transformers | `from_transformers()` | Boxes, scores |
358
+ | Florence-2 | `from_florence2()` | Boxes, phrases |
359
+ | SAM | `from_sam()` | Masks, scores |
360
+ | Tesseract OCR | `from_tesseract()` | Text, boxes, confidence |
361
+ | PaddleOCR | `from_paddleocr()` | Text, boxes, structure |
362
+ | EasyOCR | `from_easyocr()` | Text, boxes |
363
+ | PP-Structure | `from_ppstructure()` | Tables, formulas, layouts |
364
+
365
+ ## Documentation
366
+
367
+ Full documentation available at [https://datamarkin.com/docs/pixelflow/](https://datamarkin.com/docs/pixelflow/)
368
+
369
+ ## Contributing
370
+
371
+ Contributions welcome! Please read our contributing guidelines.
372
+
373
+ ## License
374
+
375
+ MIT License - see LICENSE file for details.
376
+
377
+ ---
378
+
379
+ Built with love by [Datamarkin](https://datamarkin.com)
@@ -0,0 +1,341 @@
1
+ # PixelFlow
2
+
3
+ [![PyPI version](https://badge.fury.io/py/pixelflow.svg)](https://badge.fury.io/py/pixelflow)
4
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ **The computer vision library that gets out of your way.**
8
+
9
+ PixelFlow provides a unified, intuitive API for object detection, tracking, annotation, and video processing. Write clean, readable pipelines that work with any ML framework.
10
+
11
+ ```python
12
+ import pixelflow as pf
13
+ from ultralytics import YOLO
14
+
15
+ model = YOLO("yolo11n.pt")
16
+ video = pf.VideoReader("traffic.mp4", width=640)
17
+ tracker = pf.tracker.ByteTracker()
18
+ zones = pf.Zones()
19
+ zones.add_zone([(100, 400), (500, 400), (500, 600), (100, 600)], zone_id="entrance")
20
+
21
+ for frame in video:
22
+ detections = pf.detections.from_ultralytics(model.predict(frame))
23
+ detections = tracker.update(detections)
24
+ zones.update(detections)
25
+
26
+ frame = pf.annotate.box(frame, detections)
27
+ frame = pf.annotate.label(frame, detections)
28
+ frame = pf.annotate.zones(frame, zones)
29
+
30
+ if pf.show_frame("Live", frame) == ord('q'):
31
+ break
32
+ ```
33
+
34
+ ## Installation
35
+
36
+ ```bash
37
+ pip install pixelflow
38
+ ```
39
+
40
+ ## Core Concepts
41
+
42
+ ### Detections - One Format, Every Framework
43
+
44
+ Convert outputs from any ML framework into a unified format:
45
+
46
+ ```python
47
+ import pixelflow as pf
48
+
49
+ # Ultralytics YOLO
50
+ from ultralytics import YOLO
51
+ model = YOLO("yolo11n.pt")
52
+ detections = pf.detections.from_ultralytics(model.predict(image))
53
+
54
+ # Detectron2
55
+ from detectron2.engine import DefaultPredictor
56
+ predictor = DefaultPredictor(cfg)
57
+ detections = pf.detections.from_detectron2(predictor(image), class_names=["person", "car"])
58
+
59
+ # HuggingFace Transformers
60
+ from transformers import pipeline
61
+ detector = pipeline("object-detection")
62
+ detections = pf.detections.from_transformers(detector(image))
63
+
64
+ # Florence-2
65
+ detections = pf.detections.from_florence2(model_output)
66
+
67
+ # SAM (Segment Anything)
68
+ detections = pf.detections.from_sam(masks, scores)
69
+
70
+ # OCR Engines
71
+ detections = pf.detections.from_tesseract(tesseract_output)
72
+ detections = pf.detections.from_paddleocr(paddleocr_output)
73
+ detections = pf.detections.from_easyocr(easyocr_output)
74
+ ```
75
+
76
+ ### Powerful Filtering
77
+
78
+ Chain filters for complex queries with zero overhead:
79
+
80
+ ```python
81
+ # Get high-confidence people in the parking zone, tracked for 5+ seconds
82
+ results = (detections
83
+ .filter_by_confidence(min_confidence=0.7)
84
+ .filter_by_class_id("person")
85
+ .filter_by_zones(["parking_lot"])
86
+ .filter_by_tracking_duration(min_seconds=5.0))
87
+
88
+ # Size-based filtering
89
+ large_objects = detections.filter_by_size(min_area=10000)
90
+ tall_objects = detections.filter_by_dimensions(min_height=200)
91
+ squares = detections.filter_by_aspect_ratio(min_ratio=0.9, max_ratio=1.1)
92
+
93
+ # Spatial filtering
94
+ left_side = detections.filter_by_position(max_x=frame_width // 2)
95
+
96
+ # Remove overlapping detections
97
+ unique = detections.remove_duplicates(iou_threshold=0.5)
98
+
99
+ # OCR-specific filters
100
+ titles = detections.filter_by_text_level("title")
101
+ english_text = detections.filter_by_text_language("en")
102
+ ```
103
+
104
+ ### Media Handling
105
+
106
+ Purpose-built classes for videos, cameras, and images:
107
+
108
+ ```python
109
+ import pixelflow as pf
110
+
111
+ # Read a video file
112
+ video = pf.VideoReader("video.mp4", width=640)
113
+ print(f"{video.width}x{video.height}, {video.fps}fps, {len(video)} frames")
114
+
115
+ for frame in video: # Replayable — resets on each iteration
116
+ if pf.show_frame("Preview", frame) == ord('q'):
117
+ break
118
+
119
+ # Load a single image
120
+ image = pf.read_image("photo.jpg", width=640)
121
+
122
+ # Webcam / network stream
123
+ cam = pf.CameraStream(0, width=640)
124
+ cam = pf.CameraStream("rtsp://camera.local/stream")
125
+
126
+ # Write processed video
127
+ writer = pf.VideoWriter("output.mp4", fps=video.fps)
128
+ for frame in video:
129
+ processed = process(frame)
130
+ writer.write(processed)
131
+ writer.close()
132
+ ```
133
+
134
+ ### Zone-Based Analytics
135
+
136
+ Define spatial regions and track what enters them:
137
+
138
+ ```python
139
+ import pixelflow as pf
140
+
141
+ zones = pf.Zones()
142
+
143
+ # Define zones with different trigger strategies
144
+ zones.add_zone(
145
+ polygon=[(100, 400), (300, 400), (300, 600), (100, 600)],
146
+ zone_id="entrance",
147
+ name="Main Entrance",
148
+ trigger_strategy="bottom_center" # Trigger when bottom-center of bbox enters
149
+ )
150
+
151
+ zones.add_zone(
152
+ polygon=[(500, 200), (700, 200), (700, 500), (500, 500)],
153
+ zone_id="restricted",
154
+ trigger_strategy="percentage",
155
+ overlap_threshold=0.3 # Trigger when 30% of bbox is inside
156
+ )
157
+
158
+ # Update detections with zone info
159
+ zones.update(detections)
160
+
161
+ # Access zone statistics
162
+ print(zones.get_zone_counts()) # {'entrance': 3, 'restricted': 1}
163
+ print(zones.get_zone_stats()) # Detailed stats including total_entered
164
+
165
+ # Filter by zone
166
+ entrance_only = zones.filter_by_zones(detections, ["entrance"])
167
+ not_restricted = zones.filter_by_zones(detections, ["restricted"], exclude=True)
168
+ ```
169
+
170
+ **Trigger Strategies:**
171
+ - `center` - Bounding box center point (default)
172
+ - `bottom_center` - Bottom-center point (great for people/vehicles)
173
+ - `percentage` - Percentage of bbox overlap
174
+ - `overlap` - Any intersection
175
+ - Multiple strategies with `mode="any"` or `mode="all"`
176
+
177
+ ### Object Tracking
178
+
179
+ Built-in ByteTrack for multi-object tracking:
180
+
181
+ ```python
182
+ import pixelflow as pf
183
+
184
+ tracker = pf.tracker.ByteTracker()
185
+
186
+ for frame in media.frames:
187
+ detections = pf.detections.from_ultralytics(model.predict(frame))
188
+ detections = tracker.update(detections)
189
+
190
+ for det in detections:
191
+ print(f"Track ID: {det.tracker_id}, Class: {det.class_name}")
192
+ print(f"First seen: {det.first_seen_time}, Duration: {det.total_time}s")
193
+ ```
194
+
195
+ ### Rich Annotations
196
+
197
+ Beautiful, customizable visualizations:
198
+
199
+ ```python
200
+ import pixelflow as pf
201
+
202
+ # Bounding boxes and labels
203
+ frame = pf.annotate.box(frame, detections, thickness=2)
204
+ frame = pf.annotate.label(frame, detections, font_scale=0.6)
205
+
206
+ # Segmentation masks
207
+ frame = pf.annotate.mask(frame, detections, opacity=0.4)
208
+
209
+ # Keypoints and skeletons (pose estimation)
210
+ frame = pf.annotate.keypoint(frame, detections)
211
+ frame = pf.annotate.keypoint_skeleton(frame, detections)
212
+
213
+ # Zone visualization
214
+ frame = pf.annotate.zones(frame, zones)
215
+ frame = pf.annotate.crossings(frame, crossings)
216
+
217
+ # Privacy protection
218
+ frame = pf.annotate.blur(frame, detections, kernel_size=51)
219
+ frame = pf.annotate.pixelate(frame, detections, pixel_size=15)
220
+
221
+ # Shapes
222
+ frame = pf.annotate.oval(frame, detections)
223
+ frame = pf.annotate.polygon(frame, detections)
224
+ ```
225
+
226
+ ### Image Transforms
227
+
228
+ Comprehensive image and detection-aware transformations:
229
+
230
+ ```python
231
+ import pixelflow as pf
232
+
233
+ # Image-only transforms
234
+ rotated = pf.transform.rotate(image, 45)
235
+ flipped = pf.transform.flip_horizontal(image)
236
+ cropped = pf.transform.crop(image, [100, 50, 500, 400])
237
+
238
+ # Enhancement
239
+ enhanced = pf.transform.clahe(image)
240
+ gray = pf.transform.to_grayscale(image)
241
+ corrected = pf.transform.gamma_correction(image, gamma=1.2)
242
+
243
+ # Detection-aware transforms (coordinates update automatically)
244
+ rotated_img, rotated_dets = pf.transform.rotate_detections(image, detections, 45)
245
+ flipped_img, flipped_dets = pf.transform.flip_horizontal_detections(image, detections)
246
+ cropped_img, cropped_dets = pf.transform.crop_detections(image, detections, bbox=[100, 50, 500, 400])
247
+
248
+ # Automatic inverse transforms (undo all transforms)
249
+ original_coords = pf.transform.inverse_transforms(transformed_detections)
250
+ ```
251
+
252
+ ### Sliced Inference for Large Images
253
+
254
+ Detect small objects in high-resolution images:
255
+
256
+ ```python
257
+ import pixelflow as pf
258
+
259
+ slicer = pf.SlicedInference(
260
+ slice_height=640,
261
+ slice_width=640,
262
+ overlap_ratio_h=0.2,
263
+ overlap_ratio_w=0.2
264
+ )
265
+
266
+ def detector(image):
267
+ return pf.detections.from_ultralytics(model.predict(image))
268
+
269
+ # Run on 4K image - automatically slices, detects, and merges
270
+ large_image = cv2.imread("satellite.jpg") # 4000x3000
271
+ detections = slicer.predict(large_image, detector)
272
+ ```
273
+
274
+ ### Line Crossing Detection
275
+
276
+ Track objects crossing defined lines:
277
+
278
+ ```python
279
+ import pixelflow as pf
280
+
281
+ crossings = pf.Crossings()
282
+ crossings.add_line(
283
+ start=(100, 300),
284
+ end=(500, 300),
285
+ line_id="entry_line",
286
+ direction="down" # Only count downward crossings
287
+ )
288
+
289
+ for frame in media.frames:
290
+ detections = tracker.update(pf.detections.from_ultralytics(model.predict(frame)))
291
+ crossings.update(detections)
292
+
293
+ print(f"Crossed: {crossings.get_counts()}")
294
+ frame = pf.annotate.crossings(frame, crossings)
295
+ ```
296
+
297
+ ### Serialization
298
+
299
+ Export and import detection data:
300
+
301
+ ```python
302
+ # To JSON
303
+ json_str = detections.to_json()
304
+
305
+ # To dictionary (for pandas, etc.)
306
+ data = detections.to_dict()
307
+ df = pd.DataFrame(data)
308
+
309
+ # With metrics
310
+ report = detections.to_json_with_metrics()
311
+ ```
312
+
313
+ ## Supported Frameworks
314
+
315
+ | Framework | Converter | Features |
316
+ |-----------|-----------|----------|
317
+ | Ultralytics (YOLO) | `from_ultralytics()` | Boxes, masks, keypoints |
318
+ | Detectron2 | `from_detectron2()` | Boxes, masks, keypoints |
319
+ | HuggingFace Transformers | `from_transformers()` | Boxes, scores |
320
+ | Florence-2 | `from_florence2()` | Boxes, phrases |
321
+ | SAM | `from_sam()` | Masks, scores |
322
+ | Tesseract OCR | `from_tesseract()` | Text, boxes, confidence |
323
+ | PaddleOCR | `from_paddleocr()` | Text, boxes, structure |
324
+ | EasyOCR | `from_easyocr()` | Text, boxes |
325
+ | PP-Structure | `from_ppstructure()` | Tables, formulas, layouts |
326
+
327
+ ## Documentation
328
+
329
+ Full documentation available at [https://datamarkin.com/docs/pixelflow/](https://datamarkin.com/docs/pixelflow/)
330
+
331
+ ## Contributing
332
+
333
+ Contributions welcome! Please read our contributing guidelines.
334
+
335
+ ## License
336
+
337
+ MIT License - see LICENSE file for details.
338
+
339
+ ---
340
+
341
+ Built with love by [Datamarkin](https://datamarkin.com)