usda-vision/README.md

USDA Vision

A unified monorepo combining the camera API service and the web dashboard for USDA vision experiments.

Project Structure

• api/ - Python API service for camera management (USDA-Vision-Cameras)
• web/ - React web dashboard for experiment management (pecan_experiments)

Quick Start (Docker Compose)

1. Copy env template and set values (for web/Supabase):

cp .env.example .env
# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env

2. Start the stack:

docker compose up --build

• Web: http://localhost:5173
• API: http://localhost:8000
• MQTT broker: localhost:1883

To stop: docker compose down

Services

API Service (Port 8000)

• Camera management endpoints
• Video recording controls
• File management

Web Dashboard (Port 5173)

• User authentication via Supabase
• Experiment definition and management
• Camera control interface
• Video playback and analysis

MQTT Broker (Port 1883)

• Local Mosquitto broker for development and integration testing

Git Subtree Workflow

This repo vendors two upstream projects using git subtree, preserving their histories under api/ and web/.

Configured remotes:

• cameras → https://github.com/salirezav/USDA-Vision-Cameras.git (branch: master)
• web-origin → https://github.com/salirezav/pecan_experiments.git (branch: master)

Pull latest upstream changes into subtrees:

# API (USDA-Vision-Cameras)
git subtree pull --prefix=api cameras master

# Web (pecan_experiments)
git subtree pull --prefix=web web-origin master

Push your changes back upstream (optional):

# API (push changes made under api/ back to USDA-Vision-Cameras)
git subtree push --prefix=api cameras master

# Web (push changes made under web/ back to pecan_experiments)
git subtree push --prefix=web web-origin master

Notes:

• Subtrees keep a single working copy with full history; no submodule init/update required.
• If you prefer a lighter top-level history, you can use --squash when adding/pulling, but pushing back becomes trickier.

Development Tips

• API

  • Code lives under api/. The compose service runs uvicorn usda_vision_system.api.server:app --reload by default.
  • Camera SDK access from inside Docker on Windows may be limited; for hardware work you might run the API directly on the host.
  • Configuration: api/config.json (see api/docs for details).
  • Storage (recordings) is mapped to api/storage/ and ignored by git.

• Web

  • Code lives under web/ with a Vite dev server on port 5173.
  • Environment: set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env (not committed).
  • Common scripts: npm run dev, npm run build (executed inside the container by compose).

Troubleshooting

• Port already in use: change the mapped ports in docker-compose.yml or stop the conflicting process.
• File watching issues on Docker Desktop: CHOKIDAR_USEPOLLING=true is already set for the web container.
• API not starting: check container logs and verify Python deps (compose installs from requirements.txt or pyproject.toml).