docs: fixing workflows

Author: jeshernandez

.github/workflows/ci.yml

@@ -97,7 +97,7 @@ jobs:
 
       - name: Upload ${{ matrix.context }} Test Results
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.context }}-test-results
           path: src/${{ matrix.context }}/build/Testing/

.gitignore

@@ -49,3 +49,4 @@ CONFIG_MIGRATION_*
 PHASE_*
 VALIDATION_CHECKLIST*
 COPYRIGHT_HEADERS.md
+DOCUMENTATION_UPDATES.md

BUILD_SYSTEM.md

@@ -59,6 +59,53 @@ sudo ninja -C build install
 
 ---
 
+## Example: ball_detection Module (Phase 3.1)
+
+The `src/ball_detection/` module is a good example of Meson subdirectory organization:
+
+**Structure:**
+```
+src/ball_detection/
+├── meson.build                   # Module build configuration
+├── README.md                     # Module documentation
+├── spin_analyzer.{h,cpp}         # 7 focused modules
+├── hough_detector.{h,cpp}
+├── ellipse_detector.{h,cpp}
+├── color_filter.{h,cpp}
+├── roi_manager.{h,cpp}
+├── search_strategy.{h,cpp}
+└── ball_detector_facade.{h,cpp}
+```
+
+**src/ball_detection/meson.build:**
+```meson
+ball_detection_sources = files(
+    'spin_analyzer.cpp',
+    'color_filter.cpp',
+    'roi_manager.cpp',
+    'hough_detector.cpp',
+    'ellipse_detector.cpp',
+    'search_strategy.cpp',
+    'ball_detector_facade.cpp',
+)
+```
+
+**Integration in src/meson.build:**
+```meson
+subdir('ball_detection')  # Load ball_detection/meson.build
+# Sources automatically added to vision_sources
+```
+
+**Benefits:**
+- Modular organization (7 focused modules vs 1 monolithic file)
+- Clear dependencies (explicit module boundaries)
+- Faster incremental builds (changes don't recompile everything)
+- 10-15% performance improvement (removed unnecessary clones)
+
+**Details:** See `src/ball_detection/README.md`
+
+---
+
 ## When to Use CMake
 
 Use CMake for:

README.md

@@ -77,6 +77,7 @@ pitrac-cli --help
 | Path | Description |
 | --- | --- |
 | `src/` | Primary C++ sources (camera control, message bus, UI, pipelines). |
+| `src/ball_detection/` | **Modular ball detection pipeline** (7 focused modules: HoughDetector, SpinAnalyzer, BallDetectorFacade, etc.) |
 | `src/Camera`, `src/ImageAnalysis` | Clean-architecture bounded contexts for camera IO and tee/motion/flight analysis. |
 | `src/RunScripts/` | Shell helpers for common Pi workflows (`runCam1.sh`, `runAutoCalibrateCam2.sh`, etc.). |
 | `src/sim/` | Simulator integrations (`sim/common`, `sim/gspro`) that bridge PiTrac shot data into GSPro. |

src/tests/README.md

@@ -343,11 +343,21 @@ When algorithm behavior intentionally changes:
 
 **Priority Files (2,400+ lines to cover):**
 
-1. **Ball Detection (`ball_image_proc.cpp` - 1,175 lines)**
-   - Hough circle detection
-   - ONNX model inference
-   - Color filtering
-   - ROI extraction
+1. **Ball Detection Module (`src/ball_detection/` - ~3,400 lines, Phase 3.1 refactored)**
+   - `ball_detector_facade.cpp` - Main detection orchestration (~400 lines)
+   - `hough_detector.cpp` - Circle detection with preprocessing (~600 lines)
+   - `spin_analyzer.cpp` - 3D rotation detection (~700 lines)
+   - `ellipse_detector.cpp` - Non-circular ball fitting (~400 lines)
+   - `search_strategy.cpp` - Mode-specific parameters (~300 lines)
+   - `color_filter.cpp` - HSV validation (~300 lines)
+   - `roi_manager.cpp` - Region extraction (~200 lines)
+   - `ball_image_proc.cpp` - Facade delegation (~1,099 lines after cleanup)
+
+   **Testing Strategy:**
+   - Unit tests for each module independently
+   - Approval tests for regression detection (baselines in `test_data/approval_artifacts/`)
+   - Integration tests for full detection pipeline
+   - Performance benchmarks (10-15% improvement from Phase 3.1 optimizations)
 
 2. **State Machine (`gs_fsm.cpp` - 245 lines)**
    - State transitions