Camera Debug Infrastructure

Debug-only features for field testing and refining camera arrow detection. Added in PR #374 to support iterative improvement of the ML-based arrow detection system.

Overview

The camera debug infrastructure provides tools for:

• Detection metrics tracking - Raw → confidence → NMS filtering stats
• Image picker from gallery - Test detection without going to the range
• Detection overlay preview - Visualize bounding boxes before adjustment
• Verbose logging - Detailed pipeline debugging

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    CameraDebugFeatureFlags                  │
│              (Controls all debug feature toggles)           │
└─────────────────────────────┬───────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Source Select  │  │  Detection      │  │  Verbose        │
│  (Camera/       │  │  Overlay        │  │  Logging        │
│   Gallery)      │  │  Preview        │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Components

CameraDebugFeatureFlags

Location: app/src/main/java/com/archeryapprentice/domain/flags/CameraDebugFeatureFlags.kt

Singleton controlling all debug features:

object CameraDebugFeatureFlags {
    // Master switch for all debug features
    var isDebugModeEnabled: Boolean = BuildConfig.DEBUG
 
    // Individual feature toggles
    var showDetectionOverlay: Boolean = true
    var enableGalleryPicker: Boolean = true
    var verboseLogging: Boolean = false
    var showConfidenceScores: Boolean = true
    var showNmsStats: Boolean = true
 
    fun reset() {
        isDebugModeEnabled = BuildConfig.DEBUG
        showDetectionOverlay = true
        enableGalleryPicker = true
        verboseLogging = false
        showConfidenceScores = true
        showNmsStats = true
    }
}

Important: All debug features are automatically disabled in release builds via BuildConfig.DEBUG.

---

DetectionMetrics

Location: app/src/main/java/com/archeryapprentice/domain/camera/ArrowDetectionResult.kt

Tracks the detection pipeline statistics:

data class DetectionMetrics(
    val rawDetections: Int,           // Total detections from ML model
    val afterConfidenceFilter: Int,   // After confidence threshold
    val afterNmsFilter: Int,          // After Non-Maximum Suppression
    val processingTimeMs: Long,       // Total processing time
    val confidenceThreshold: Float,   // Applied confidence threshold
    val nmsIouThreshold: Float        // Applied NMS IoU threshold
)

---

DetectionOverlayScreen

Location: app/src/main/java/com/archeryapprentice/ui/camera/DetectionOverlayScreen.kt

Displays detection results with visual debugging:

@Composable
fun DetectionOverlayScreen(
    imageUri: Uri,
    detections: List<ArrowDetection>,
    metrics: DetectionMetrics,
    onConfirm: () -> Unit,
    onRetake: () -> Unit
)

Features:

• Bounding boxes color-coded by confidence (green → yellow → red)
• Confidence percentage displayed on each box
• Pipeline statistics overlay (raw → confidence → NMS)
• Processing time display
• Retake/Confirm buttons

---

Debug Flow

Debug Mode Enabled

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Source Select  │ ──► │  Capture/Pick   │ ──► │  Detection      │
│  - Camera       │     │  Image          │     │  Overlay        │
│  - Gallery      │     │                 │     │  Preview        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Arrow          │
                                                │  Adjustment     │
                                                └─────────────────┘

Release Mode (Unchanged)

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Camera         │ ──► │  Detection      │ ──► │  Arrow          │
│  Permission     │     │  (Background)   │     │  Adjustment     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

---

Usage

Enable Debug Mode

Debug mode is automatically enabled on debug builds. For testing specific features:

// In a debug session or test
CameraDebugFeatureFlags.apply {
    isDebugModeEnabled = true
    showDetectionOverlay = true
    enableGalleryPicker = true
    verboseLogging = true  // For detailed logging
}

Using Gallery Picker

1. Start camera scoring flow
2. Select “Pick from Gallery” (debug only)
3. Choose test image with arrows
4. View detection overlay with bounding boxes
5. Confirm or retake

Reading Detection Metrics

The overlay displays:

┌────────────────────────────┐
│  Detection Pipeline        │
│  Raw: 15 detections        │
│  After confidence (0.5): 8 │
│  After NMS (0.4): 5        │
│  Processing: 127ms         │
└────────────────────────────┘

---

Confidence Color Coding

Confidence	Color	Meaning
> 0.8	Green	High confidence detection
0.5 - 0.8	Yellow	Medium confidence
< 0.5	Red	Low confidence (may be filtered)

---

Verbose Logging

When enabled, detailed logs are output:

D/ArrowDetection: Starting detection on image 1920x1080
D/ArrowDetection: ML model returned 15 raw detections
D/ArrowDetection: Detection 1: conf=0.92 bbox=[120,340,180,400]
D/ArrowDetection: Detection 2: conf=0.87 bbox=[450,320,510,380]
...
D/ArrowDetection: After confidence filter: 8 detections
D/ArrowDetection: After NMS (IoU=0.4): 5 detections
D/ArrowDetection: Total processing time: 127ms

---

Testing with Gallery Images

For consistent testing, maintain a set of test images:

1. Good lighting conditions - Outdoor range photos
2. Poor lighting - Indoor/overcast scenarios
3. Partial visibility - Arrows at edge of frame
4. Dense grouping - Multiple arrows close together
5. Various distances - Close-up to full target

---

Test Coverage

Component	Tests	Coverage
CameraDebugFeatureFlags	10	100%
DetectionMetrics	5	100%
ArrowDetectionResult	8	100%

---

Related Documentation

• camera-based-arrow-scoring - Main camera scoring feature
• apk-size-optimization - Build configuration changes

---