PRACTICE_GUIDE.md

🎓 Vision Logistics Practice Guide

Hands-on learning guide for mastering the Vision Logistics tracking system

This guide provides structured exercises, experiments, and learning activities to help you understand and practice with the warehouse logistics tracking system. Perfect for developers, analysts, and anyone wanting to explore the system's capabilities.

🎯 Learning Objectives

By completing this guide, you will:

• ✅ Master system setup and troubleshooting
• ✅ Understand data flow from cameras to analytics
• ✅ Create custom animations and scenarios
• ✅ Analyze movement patterns and operational insights
• ✅ Integrate APIs and build custom solutions
• ✅ Optimize system performance for production use

📚 Prerequisites

Required Knowledge

• Basic command line familiarity
• Understanding of JSON data format
• Basic web development concepts (HTML, JavaScript)

Required Software

• Node.js 18+ and npm
• Text editor (VS Code recommended)
• Web browser (Chrome/Firefox)
• Terminal/Command Prompt

🚀 Module 1: System Fundamentals

Exercise 1.1: Basic Setup (15 minutes)

Goal: Get the system running and understand the architecture

# 1. Clone and start the system
git clone <repository-url>
cd vision-logistics
npm start

# 2. Verify all services are running
npm run system:health

# 3. Open the dashboard
open http://localhost:3000

Questions to answer:

1. How many services are running?
2. What ports do they use?
3. Which service handles the UI?
4. What happens if you refresh the page?

Expected output: All services healthy, animated heatmap visible

Exercise 1.2: API Exploration (20 minutes)

Goal: Understand the data APIs and their responses

# 1. Check service health
curl http://localhost:3001/health
curl http://localhost:3002/health

# 2. Get heatmap data
curl http://localhost:3002/heatmap | jq '.' > heatmap.json

# 3. Get cell statistics
curl http://localhost:3002/stats/cells | jq '.' > stats.json

# 4. Get active objects
curl http://localhost:3002/objects/active | jq '.' > objects.json

# 5. Get recent events
curl http://localhost:3002/events/recent | jq '.' > events.json

Analysis tasks:

1. Count how many cells are in the heatmap
2. Find the cell with highest dwell time
3. Identify all active object types
4. Calculate average intensity across all cells

Deliverable: Create a summary report of the API responses

Exercise 1.3: Data Generation (25 minutes)

Goal: Learn to generate test data and observe effects

# 1. Generate a single test frame
curl -X POST http://localhost:3001/generate-test-frame \
  -H "Content-Type: application/json" \
  -d '{"camera_id": "test-cam", "object_count": 5}'

# 2. Generate a batch of frames
curl -X POST http://localhost:3001/simulate-batch \
  -H "Content-Type: application/json" \
  -d '{"camera_ids": ["test-cam"], "frames_per_camera": 10, "interval_ms": 500}'

# 3. Run continuous data generation
npm run generate-test-data

Observation tasks:

1. Monitor the dashboard while generating data
2. Note which areas of the heatmap change
3. Watch the event log for new entries
4. Record the object counts before and after

Challenge: Generate data for 3 different cameras simultaneously

🔬 Module 2: Animation and Visualization

Exercise 2.1: Understanding Animation Patterns (30 minutes)

Goal: Analyze the built-in animation patterns

Task: Open the demo and observe for 5 complete animation cycles (75 seconds)

Tracking sheet:

Cycle 1 (0-15s):
- Forklift position: Start=___, End=___
- Worker position: Start=___, End=___
- Pallet position: Start=___, End=___
- Cart position: Start=___, End=___

Cycle 2 (15-30s):
[Repeat tracking]

Analysis questions:

1. Which object moves fastest?
2. Which path covers the most distance?
3. Which object creates the highest intensity?
4. How do the paths avoid collision?

Exercise 2.2: Custom Animation Creation (45 minutes)

Goal: Create your own animation pattern

Steps:

1. Copy the mock API: cp mock-api.js custom-mock-api.js
2. Edit the animation: Modify the movingObjects array
3. Add a new object: Create a fifth moving object
4. Test your changes: Stop the current API and start yours

Example custom object:

{
  // Object 5: zigzag pattern
  path: (progress) => ({
    x: Math.floor(2 + progress * 16),
    y: Math.floor(7 + Math.sin(progress * Math.PI * 8) * 3),
    intensity: 0.5 + Math.sin(progress * Math.PI * 4) * 0.2,
    size: 1
  })
}

Challenge objectives:

• Create a spiral pattern
• Make an object that pauses at corners
• Add acceleration/deceleration effects
• Create collision avoidance between objects

Exercise 2.3: Data Analysis (40 minutes)

Goal: Extract insights from movement patterns

Data collection script:

#!/bin/bash
# collect_data.sh
for i in {1..20}; do
  curl -s http://localhost:3002/heatmap | jq '.timestamp, .cells[].intensity' >> intensity_data.txt
  sleep 3
done

Analysis tasks:

1. Plot intensity over time for top 3 cells
2. Calculate movement speed for each object type
3. Identify peak activity zones during animation cycle
4. Measure coverage area for each movement pattern

Tools you can use:

• Excel/Google Sheets for basic plotting
• Python with matplotlib for advanced analysis
• Online JSON viewers for data exploration

🛠️ Module 3: System Customization

Exercise 3.1: UI Customization (60 minutes)

Goal: Modify the user interface

Tasks:

1. Change refresh interval:

   // Edit ui/src/App.tsx
   const [refreshInterval, setRefreshInterval] = useState(10000); // 10 seconds

2. Add new UI elements:

   • Add a "Speed" display showing current animation progress
   • Create an "Object Count" widget
   • Add buttons to pause/resume animation

3. Modify heatmap colors:

   /* Edit ui/src/components/HeatmapGrid.tsx */
   /* Find the color calculation and adjust */

Verification: Your changes should be visible in the browser

Exercise 3.2: API Extension (90 minutes)

Goal: Add new API endpoints

Add to mock-api.js:

// New endpoint: Get object speed
else if (pathname === '/objects/speed') {
  // Calculate and return speed data for each object
  const speedData = calculateObjectSpeeds(now);
  res.writeHead(200);
  res.end(JSON.stringify(speedData));
}

// New endpoint: Get zone statistics
else if (pathname === '/zones/stats') {
  // Divide grid into zones and return stats
  const zoneStats = calculateZoneStatistics();
  res.writeHead(200);
  res.end(JSON.stringify(zoneStats));
}

Integration tasks:

1. Create functions to calculate the new data
2. Update the UI to display the new information
3. Add error handling for the new endpoints
4. Test with curl commands

Exercise 3.3: Performance Optimization (45 minutes)

Goal: Improve system performance

Measurement baseline:

# Measure current performance
time curl http://localhost:3002/heatmap
time curl http://localhost:3002/stats/cells

Optimization targets:

1. Reduce API response time by optimizing calculations
2. Minimize data transfer by filtering unnecessary fields
3. Implement caching for expensive calculations
4. Optimize UI updates to reduce re-renders

Verification: Compare before/after performance measurements

🏗️ Module 4: Production Scenarios

Exercise 4.1: Multi-Camera Setup (75 minutes)

Goal: Simulate a multi-camera warehouse

Setup:

# Start multiple collector instances
COLLECTOR_ID=collector-01 PORT=3001 npm run dev:collector &
COLLECTOR_ID=collector-02 PORT=3011 npm run dev:collector &
COLLECTOR_ID=collector-03 PORT=3021 npm run dev:collector &

Data generation:

# Generate data for each collector
for port in 3001 3011 3021; do
  curl -X POST http://localhost:$port/simulate-batch \
    -H "Content-Type: application/json" \
    -d '{"camera_ids": ["cam-A", "cam-B"], "frames_per_camera": 20}'
done

Analysis objectives:

1. Compare activity patterns across cameras
2. Identify correlations between different areas
3. Calculate total warehouse utilization
4. Design optimal camera placement strategies

Exercise 4.2: Load Testing (60 minutes)

Goal: Test system limits and scalability

Load generation script:

#!/bin/bash
# load_test.sh
for i in {1..100}; do
  (
    curl -X POST http://localhost:3001/generate-test-frame \
      -H "Content-Type: application/json" \
      -d "{\"camera_id\": \"cam-$i\", \"object_count\": 10}" &
  )
done
wait

Monitoring:

# Monitor system resources
top -p $(pgrep node)
netstat -an | grep :3002
curl http://localhost:3002/health

Analysis questions:

1. At what load does the system slow down?
2. Which component becomes the bottleneck?
3. How does memory usage change with load?
4. What's the maximum sustainable throughput?

Exercise 4.3: Error Handling (45 minutes)

Goal: Test system resilience and recovery

Failure scenarios to test:

# 1. Kill the API server
pkill -f "mock-api"
# Observe UI behavior, then restart

# 2. Flood with invalid data
curl -X POST http://localhost:3001/frames \
  -H "Content-Type: application/json" \
  -d '{"invalid": "data"}'

# 3. Overload with requests
for i in {1..1000}; do
  curl http://localhost:3002/heatmap > /dev/null 2>&1 &
done

Recovery procedures:

1. Document error messages and behaviors
2. Implement graceful degradation strategies
3. Create health check automation
4. Design fallback mechanisms

🎯 Module 5: Advanced Projects

Project 5.1: Custom Dashboard (3-5 hours)

Goal: Build a specialized monitoring dashboard

Requirements:

• Display custom KPIs (efficiency, utilization, bottlenecks)
• Add alerts for unusual patterns
• Create historical trend analysis
• Implement export functionality

Technologies:

• React for frontend
• Chart.js for visualizations
• Express.js for custom backend
• SQLite for data storage

Project 5.2: Machine Learning Integration (5-8 hours)

Goal: Add predictive analytics

Objectives:

• Predict object movement patterns
• Identify anomalous behavior
• Forecast warehouse utilization
• Optimize path planning

Tools:

• Python with scikit-learn
• TensorFlow.js for browser ML
• Node.js for model serving
• REST APIs for integration

Project 5.3: Mobile Application (8-12 hours)

Goal: Create a mobile monitoring app

Features:

• Live heatmap view
• Push notifications for alerts
• QR code integration for object tracking
• Offline mode support

Technologies:

• React Native or Flutter
• WebSocket for real-time updates
• Push notification services
• Local storage for offline data

📊 Assessment and Certification

Knowledge Check Questions

1. Explain the data flow from camera detection to heatmap visualization
2. What are the benefits of grid-based position tracking?
3. How would you optimize the system for 1000+ concurrent objects?
4. Design a warehouse layout optimization algorithm using the available data

Practical Skills Test

1. Setup Challenge: Deploy the system on a new machine in under 5 minutes
2. Customization Challenge: Add a new movement pattern in under 30 minutes
3. Integration Challenge: Connect a new data source to the API
4. Performance Challenge: Optimize response time by 50%

Portfolio Projects

Create and document at least one substantial project:

• Custom animation library
• Advanced analytics dashboard
• Integration with warehouse management system
• Mobile application for field workers

🎓 Next Steps

Beginner Path

1. Complete Modules 1-2 thoroughly
2. Focus on understanding data structures
3. Practice API interactions daily
4. Join community discussions

Intermediate Path

1. Complete all modules
2. Build custom integrations
3. Contribute to system improvements
4. Mentor other learners

Advanced Path

1. Design production deployments
2. Implement enterprise features
3. Create training materials
4. Lead development initiatives

📚 Additional Resources

Documentation

• Demo Guide - Presentation and demonstration
• README - System overview and quick start
• Troubleshooting - Common issues and solutions

Community

• GitHub Issues for technical questions
• Discussion forums for best practices
• Code review submissions
• Regular virtual meetups

Tools and Extensions

• VS Code extensions for better development
• Browser devtools for debugging
• Postman collections for API testing
• Docker configurations for deployment

---

🎯 Ready to start learning? Begin with Module 1 and progress at your own pace!