Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elzackarias/Hackaton3B-Reto1/llms.txt

Use this file to discover all available pages before exploring further.

Anaquel Inteligente 3B is designed for local or intranet deployment where the camera and the server machine share the same network. The backend is a single Python process that streams video, runs YOLOv8 inference, and serves both a REST API and a Socket.IO WebSocket — all on port 8000. The React dashboard can be served as a Vite dev server on port 3000, or built into a static bundle and hosted anywhere.

​
Requirements

Before installing, verify that your environment meets the following prerequisites:
  • Python 3.10 or later (3.11 recommended)
  • Node.js 18 or later (for the React frontend)
  • Camera: USB webcam (device index 0 or 1) or an IP camera with a valid RTSP URL
  • RAM: 4 GB minimum; 8 GB recommended when running YOLO inference continuously
  • CPU: AVX2 instruction support required by PyTorch / YOLOv8
  • GPU: Optional — YOLOv8 via Ultralytics will automatically use CUDA if a compatible NVIDIA GPU and driver are present; falls back to CPU otherwise
The backend dependencies include opencv-python-headless, which does not require a display server. The system can run on a headless server and stream video to remote dashboard clients.

​
Installation

1
Clone the repository
2
git clone https://github.com/elzackarias/Hackaton3B-Reto1.git
cd Hackaton3B-Reto1
3
Install backend Python dependencies
4
Create and activate a virtual environment, then install from requirements.txt:
5
macOS / Linux
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Windows
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
6
The requirements.txt installs:
7
PackageVersionPurposefastapi0.115.0REST API frameworkuvicorn[standard]0.30.6ASGI serverpython-socketio5.11.4WebSocket (Socket.IO)ultralytics8.3.0YOLOv8 model loading and inferenceopencv-python-headless4.10.0.84Frame capture and image processingnumpy>=1.26, <2.0Array operationspydantic>=2.0, <3.0Data validationaiofiles24.1.0Async file I/O
8
Install frontend Node.js dependencies
9
cd frontend
npm install
10
Verify the YOLOv8 model file
11
The detection engine expects the trained model at:
12
models/best3.pt
13
relative to the repository root. Verify it exists:
14
ls models/best3.pt
15
If the file is missing, obtain it from your team (it is the output of training with backend/dataset.yaml) or retrain using:
16
python backend/train_model.py
17
The backend will fail to start if models/best3.pt is absent. This is the first thing to confirm before launching the server.

​
Starting the System

​
Using the Setup Scripts

The repository ships with convenience scripts that install all dependencies in a single step: 
# From the repository root:
./scripts/setup-all.sh

​
Starting the Backend

cd backend
source .venv/bin/activate
uvicorn main:combined_app --host 0.0.0.0 --port 8000
On startup the DetectionEngine performs three dummy warm-up inferences so the first real frame is processed without latency spikes.

​
Starting the Frontend

cd frontend
npm run dev
# Dashboard available at http://localhost:3000
The frontend gracefully falls back to built-in mock data if it cannot connect to the backend within 3 seconds. You can demo the UI without a running backend for presentation purposes.

​
Camera Setup

​
USB Webcam

The default CameraCapture() constructor uses an RTSP URL as the primary source and automatically falls back to USB device 0 if the RTSP connection fails. To use a USB camera directly, pass the device index when instantiating CameraCapture in your code: 
cam = CameraCapture(source=0)   # first USB webcam
cam = CameraCapture(source=1)   # second USB webcam

​
RTSP IP Camera

Provide a full RTSP URL as the source string: 
cam = CameraCapture(source="rtsp://user:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=0")
The capture module opens RTSP streams via cv2.CAP_FFMPEG with a TCP transport and a 5-second open/read timeout. It retries up to 5 times before falling back to USB.

​
Testing Camera Access

Before launching the full server, confirm the camera is accessible: 
python -c "import cv2; cap = cv2.VideoCapture(0); print('Camera open:', cap.isOpened()); cap.release()"
Expected output: Camera open: True. If it prints False, try device index 1 or 2, or check USB connection and driver installation.
On Linux, camera devices appear as /dev/video0, /dev/video1, etc. Run ls /dev/video* to list available devices, then map them to integer indices (0 → /dev/video0).

​
Demo Checklist

Use this checklist to verify the end-to-end system is fully functional before a live demonstration:
  • Camera connected and streaming live video to the dashboard
  • YOLOv8 detecting all 7 products on the shelf (agua_burst, burst_energetica_roja, burst_energy, nachos_naturasol, nebraska_mango, sisi_cola, sun_paradise_naranja)
  • Dashboard showing real-time stock counts per SKU
  • Product removal triggers automatic stock count decrement visible on the dashboard
  • Alerts appear when a SKU’s stock drops below 20 % of initial stock (MIN_THRESHOLD = 0.20)
  • Prediction panel shows estimated time to stockout (requires ≥ 2 removal events per SKU)
  • Heatmap panel highlights active shelf slots
  • Narrative messages (in Spanish) appearing in the dashboard feed
  • Video overlay with bounding boxes and stock-level colour coding (green / yellow / red) visible on the live feed panel

​
Ports & Endpoints Summary

ServicePortURLNotes
Backend API8000http://localhost:8000FastAPI + Socket.IO combined ASGI app
API Docs (Swagger)8000http://localhost:8000/docsAuto-generated interactive API documentation
Embedded Dashboard8000http://localhost:8000/dashboardMinimal HTML dashboard served directly by FastAPI
Frontend Dev Server3000http://localhost:3000React + Vite development server

​
Troubleshooting

  1. Confirm the USB cable is securely connected and the camera powers on.
  2. Run the quick test: python -c "import cv2; cap = cv2.VideoCapture(0); print(cap.isOpened())". Try indices 0, 1, and 2 if the first fails.
  3. On Linux, ensure your user is in the video group: sudo usermod -aG video $USER (log out and back in).
  4. On Windows, check Device Manager to confirm the camera driver is installed and the device is not in an error state.
  5. If using an RTSP camera, verify the URL, credentials, and that the camera is on the same network. Use VLC (Media > Open Network Stream) to test the RTSP URL independently.
  1. Confirm models/best3.pt exists at the repository root: ls models/best3.pt.
  2. If missing, obtain the trained weights from your team or retrain: python backend/train_model.py. Training requires the dataset described in backend/dataset.yaml.
  3. Do not rename the file — the path is hardcoded in detection_engine.py as ROOT / "models" / "best3.pt".
  4. If you have a different model file, update the MODEL_PATH constant in detection_engine.py before starting.
  1. Confirm the backend is running: curl http://localhost:8000/api/health should return {"status":"ok",...}.
  2. Check that the backend is bound to 0.0.0.0 (not 127.0.0.1) if the frontend runs on a different machine.
  3. Open browser developer tools (F12 → Console) and look for WebSocket or CORS errors.
  4. Verify BACKEND_URL in frontend/src/hooks/useSocket.ts matches the backend’s actual address and port.
  5. In production, update allow_origins in main.py’s CORSMiddleware and cors_allowed_origins in the socketio.AsyncServer call to include your frontend’s exact origin.
  1. Increase the YOLO confidence threshold by editing conf in DetectionEngine.__init__ (default 0.1). Try 0.3 or 0.4.
  2. Increase cooldown_seconds on the DetectionEngine instance (default 3.0). A value of 5.0–10.0 suppresses repeated events from the same shelf slot.
  3. Increase consistency_frames (default 3) to require more consecutive frames of agreement before an event is emitted. Try 5.
  4. If removal events fire twice per product pick, the consistency_frames anti-flicker filter may not be catching the oscillation fast enough — increase both cooldown_seconds and consistency_frames together.
  1. Reduce imgsz from 640 to 416 or 320 in the DetectionEngine constructor. Smaller images run significantly faster at a slight accuracy cost.
  2. Set detect_every=3 or detect_every=4 in the stream_loop call in _run_camera_loop (default is 2) to run YOLO on fewer frames.
  3. If a CUDA-capable GPU is available, ensure the correct CUDA toolkit and PyTorch GPU build are installed. Ultralytics will use cuda:0 automatically when available.
  4. Reduce max_fps in the stream_loop call if you only need a slower update rate (e.g., max_fps=2).
  5. On CPU-only machines, consider using a smaller YOLOv8 variant (yolov8n nano) for retraining if latency is critical.

Build docs developers (and LLMs) love

Get started for freeTalk to us