Motion Logic Computer Vision

Production-ready computer vision service for American Football field detection and Position State (PoS) fact generation

Motion Logic CV is a gRPC-based microservice that detects field boundaries, lines of scrimmage, and ball locations from video. It integrates seamlessly with the Motion Logic Platform's SOA architecture, streaming structured PoS facts to the IKB (Neo4j) for Sequent Logic reasoning.

🎯 Features

Core Detection

• Field Detection: HSV-based green field segmentation with convex hull extraction
• Line of Scrimmage: Hough line transform for parallel yard line detection
• Ball Location: Edge density centroid method for ball tracking
• Coordinate Transformation: Homography-based pixel-to-field coordinate mapping

Production Architecture

• gRPC Service: High-performance streaming RPC for real-time processing
• Protocol Buffers: Type-safe data contracts for PoS facts
• SOA Integration: Designed for Motion Logic Platform (API Gateway → CV Service → IKB → Sequent Logic)
• Docker Deployment: Containerized service with docker-compose orchestration

Data Structures (PoS Facts)

• LineOfScrimmageState: Yard line, pixel coordinates, confidence
• BallLocationState: Pixel position, field position, in-play status
• FieldState: Complete field state with all detections
• FieldLine: Individual field line with classification

🏗️ SOA Architecture

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  SDK Client  │ ───▶ │ API Gateway  │ ───▶ │  CV Service  │
│  (Python/C#) │      │   (nginx)    │      │  (gRPC)      │
└──────────────┘      └──────────────┘      └──────┬───────┘
                                                    │
                                                    ▼
                      ┌──────────────┐      ┌──────────────┐
                      │   Sequent    │ ◀─── │     IKB      │
                      │    Logic     │      │   (Neo4j)    │
                      └──────────────┘      └──────────────┘

Data Flow:

1. SDK clients send video frames to API Gateway
2. Gateway routes to CV Service (this repo)
3. CV Service processes frames and extracts PoS facts
4. Facts streamed to IKB for graph storage
5. Sequent Logic performs declarative reasoning on facts

🚀 Quick Start

Installation from Source

# Clone repository
git clone https://github.com/motionlogic/motionlogic-computer-vision.git
cd motionlogic-computer-vision

# Install dependencies
pip install -r requirements.txt

# Generate Protocol Buffer code
python -m grpc_tools.protoc \
  -I./protos \
  --python_out=./motionlogic_cv/generated \
  --grpc_python_out=./motionlogic_cv/generated \
  protos/field_facts.proto

Standalone Usage (No gRPC)

from motionlogic_cv import AmericanFootballDetector
import cv2

# Initialize detector
detector = AmericanFootballDetector()

# Load frame
frame = cv2.imread('football_frame.jpg')

# Detect field state
field_state = detector.detect_field_state(frame, frame_id=0)

# Access PoS facts
if field_state.line_of_scrimmage:
    print(f"Line of scrimmage: {field_state.line_of_scrimmage.yard_line} yards")
    print(f"Confidence: {field_state.line_of_scrimmage.confidence:.2%}")

if field_state.ball_location:
    ball = field_state.ball_location
    print(f"Ball at pixel ({ball.pixel_position.x}, {ball.pixel_position.y})")

gRPC Server

# Start gRPC server
python src/server.py --port 50051

# With custom configuration
python src/server.py --config config/detection_params.yaml

gRPC Client

import grpc
from motionlogic_cv.generated import field_facts_pb2, field_facts_pb2_grpc

# Connect to service
channel = grpc.insecure_channel('localhost:50051')
stub = field_facts_pb2_grpc.FieldDetectionServiceStub(channel)

# Stream field states from video
request = field_facts_pb2.StreamFieldStatesRequest(
    video_id='path/to/game.mp4',
    max_frames=100,
)

for response in stub.StreamFieldStates(request):
    if response.success:
        state = response.field_state
        print(f"Frame {state.frame_id}: {state.line_of_scrimmage.yard_line} yards")

🐳 Docker Deployment

Build and Run

# Build image
docker build -t motionlogic-cv:latest .

# Run container
docker run -p 50051:50051 motionlogic-cv:latest

# Using docker-compose (full stack)
docker-compose up -d

# With IKB and Sequent Logic
docker-compose --profile full-stack up -d

Docker Compose Services

• cv-service: gRPC field detection service (port 50051)
• api-gateway: nginx reverse proxy (port 8080)
• ikb-neo4j: Neo4j graph database (ports 7474, 7687)
• sequent-engine: Sequent Logic reasoning engine

📊 Examples

Process Video and Export to CSV

python examples/standalone_detection.py \
  --input game.mp4 \
  --output results.csv \
  --visualize

Stream via gRPC

# Start server
python src/server.py

# In another terminal, run client
python examples/grpc_client.py --video game.mp4 --max-frames 100

Health Check

python examples/grpc_client.py --health

🔧 Configuration

Detection Parameters (config/detection_params.yaml)

field_detector:
  min_line_length: 50          # Hough line minimum length
  max_line_gap: 25             # Maximum gap in line segments
  hough_threshold: 80          # Line detection threshold
  canny_threshold1: 100        # Edge detection low threshold
  canny_threshold2: 200        # Edge detection high threshold

  green_lower_hsv: [35, 40, 40]   # Green field HSV range
  green_upper_hsv: [85, 255, 255]

  white_lower_hsv: [0, 0, 200]    # White line HSV range
  white_upper_hsv: [180, 30, 255]

📦 Repository Structure

motionlogic-computer-vision/
├── motionlogic_cv/              # Core package
│   ├── field_detection.py       # Generic field detector
│   ├── line_detection.py        # Line detection (Hough)
│   ├── american_football_detector.py  # American Football specialization
│   ├── models/                  # PoS fact data models
│   │   └── field_facts.py
│   ├── services/                # gRPC service implementation
│   │   └── field_detection_service.py
│   └── generated/               # Auto-generated Protocol Buffer code
│       ├── field_facts_pb2.py
│       └── field_facts_pb2_grpc.py
├── protos/                      # Protocol Buffer definitions
│   └── field_facts.proto
├── src/
│   └── server.py                # gRPC server entry point
├── examples/
│   ├── demo.py                  # Generic demo (multi-sport)
│   ├── standalone_detection.py  # Standalone American Football detection
│   └── grpc_client.py           # gRPC client example
├── config/
│   └── detection_params.yaml    # Configuration file
├── Dockerfile                   # Production container
├── docker-compose.yml           # Full stack orchestration
└── requirements.txt             # Python dependencies

🔌 Protocol Buffer API

Services

service FieldDetectionService {
  // Detect field in single frame (unary RPC)
  rpc DetectField(DetectFieldRequest) returns (DetectFieldResponse);

  // Stream field states from video (server-streaming RPC)
  rpc StreamFieldStates(StreamFieldStatesRequest) returns (stream StreamFieldStatesResponse);

  // Health check
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

Key Messages

message FieldState {
  int32 frame_id = 1;
  LineOfScrimmageState line_of_scrimmage = 3;
  BallLocationState ball_location = 4;
  repeated FieldLine field_lines = 6;
  repeated double homography_matrix = 7;  // 3x3 matrix
}

message LineOfScrimmageState {
  int32 yard_line = 1;              // 0-100 yards
  repeated FieldCoordinate pixel_coords = 2;
  float confidence = 3;             // 0.0-1.0
  int32 frame_id = 4;
}

message BallLocationState {
  FieldCoordinate pixel_position = 1;
  FieldCoordinate field_position = 2;  // Transformed to meters
  float confidence = 3;
  bool is_in_play = 7;
}

📊 Performance

Tested on Intel i7-10700K, 16GB RAM, no GPU:

Metric	Value
Field Detection	~30 FPS (1080p)
Line of Scrimmage	~28 FPS
Ball Location	~25 FPS
gRPC Overhead	<5ms per frame
Memory Usage	~200MB

Optimization Tips:

• Use skip_frames parameter to process every Nth frame
• Enable GPU with OpenCV CUDA build for 2-3x speedup
• Adjust Hough threshold for speed/accuracy tradeoff

🧪 Development

Generate Protocol Buffers

python -m grpc_tools.protoc \
  -I./protos \
  --python_out=./motionlogic_cv/generated \
  --grpc_python_out=./motionlogic_cv/generated \
  protos/field_facts.proto

Run Tests (Coming Soon)

pytest tests/ --cov=motionlogic_cv

Code Style

black motionlogic_cv/
flake8 motionlogic_cv/

🔗 Integration with Motion Logic Platform

IKB (Neo4j) Ingestion

PoS facts are automatically ingested into Neo4j graph database:

// Example Cypher query to retrieve line of scrimmage states
MATCH (f:FieldState)-[:HAS_LOS]->(los:LineOfScrimmage)
WHERE f.video_id = 'game_001' AND f.frame_id > 1000
RETURN los.yard_line, los.confidence, f.timestamp_ms
ORDER BY f.frame_id

Sequent Logic Queries

// Example: Detect first downs
rule FirstDown(frame, old_los, new_los) :-
  LineOfScrimmage(frame, new_los),
  LineOfScrimmage(frame-N, old_los),
  new_los.yard_line - old_los.yard_line >= 10.

🤝 Contributing

We welcome contributions! Areas where you can help:

• Accuracy Improvements: Better yard line estimation, calibration
• 3D Tracking: Add Z-coordinate for ball height
• Multi-Camera: Fuse detections from multiple camera angles
• GPU Acceleration: CUDA optimizations
• Documentation: Tutorials, API guides

See CONTRIBUTING.md for guidelines.

📄 License

Apache License 2.0 - See LICENSE for details.

🙏 Acknowledgments

• OpenCV - Computer vision algorithms
• gRPC - High-performance RPC framework
• Protocol Buffers - Data serialization
• Neo4j - Graph database for PoS facts
• Sequent Logic - Declarative spatiotemporal reasoning

📧 Contact

• GitHub: https://github.com/motionlogic
• Email: hello@motionlogic.org
• Kaggle: @analyzemyteam

---

Built with ❤️ by the Motion Logic community