How pyresearch/pyresearch works
Project type and purpose
• It’s a Python package (“pyresearch”) providing multiple real-time computer-vision and tracking modules (e.g. face detection, hand tracking, pose estimation, segmentation, object tracking/heatmap).
• The README shows usage examples built atop OpenCV and models like MediaPipe, YOLOv8, ByteTrack, Supervison.
File structure
Top-level:
• setup.py, MANIFEST, LICENSE, README.md
• Folder “pyresearch/” containing:
– ClassificationModule.py, ColorModule.py, FPS.py, FaceDetectionModule.py, FaceMeshModule.py,
HandTrackingModule.py, PIDModule.py, PlotModule.py, PoseModule.py, SelfiSegmentationModule.py,
SerialModule.py, Utils.py, heatmap_and_track.py, objectron.py, __init__.py
No “frontend/backend”—it’s a library. However, there is a clear layering:
• Data-acquisition (Camera, Video file, Serial port)
• Preprocessing & Utilities (ColorModule, Utils, PlotModule, FPS, PIDModule)
• CV-modules (Face…, Hand…, Pose…, SelfiSegmentation, Objectron, Classification)
• Pipeline (heatmap_and_track orchestrating YOLOv8 → ByteTrack → heatmap generation)
README for tech stack & flow
• External dependencies: OpenCV, MediaPipe, Ultralytics YOLOv8, ByteTrack, Supervision, NumPy, plus possible serial devices.
Main components & interactions
a. External Entities (outside the package)
• Input sources: Camera/Webcam, Video file, Background image file, Serial device
• Output sinks: OpenCV imshow window, VideoWriter/file, Serial device (for control signals)
• Utilities layer
– Utils (common helper functions)
– PlotModule (drawing utilities)
– FPS (frame-rate calculator)
– PIDModule (feedback/control logic)
– SerialModule (UART/serial I/O)
• CV Modules layer
– FaceDetectionModule
– FaceMeshModule
– HandTrackingModule
– PoseModule
– SelfiSegmentationModule
– Objectron (3D object detection)
– ClassificationModule (generic classifier wrappers)
• Pipeline layer
– heatmap_and_track.py (glues YOLOv8 detection + ByteTrack tracking + heatmap via Supervision API)
c. Dependencies & flows
• Each CV Module calls MediaPipe or an ML model for inference
• Utilities modules are leveraged by both CV modules and by user scripts (stackImages lives in Utils)
• setup.py assembles the package for pip distribution
Architectural patterns / design principles
• Modular layering: separate utilities, individual CV features, orchestration/pipelines
• Single responsibility: each module wraps one kind of detection or transformation
• Plugin-like: users import only the modules they need
• Pipeline composition: heatmap_and_track wires multiple sub-modules into an end-to-end workflow