panel/docs/features/ROUTE_PLANNING.md

Route Planning Feature with Optimization

This feature allows you to plan routes between multiple project locations using OpenRouteService API, with automatic optimization to find the fastest route regardless of point addition order.

🌟 Overview

The route planning system integrates with your project map to help optimize field visits. It supports:

• Multi-point routing through project locations
• Automatic route optimization for 3+ points
• Visual route display on the map
• Distance and time estimation
• Hybrid optimization approach (API + permutation testing)

---

🚀 Setup

1. Get an API Key:

   • Visit OpenRouteService
   • Sign up for a free account
   • Generate an API key

2. Configure Environment:

   • Copy .env.example to .env.local
   • Add your API key: NEXT_PUBLIC_ORS_API_KEY=your_actual_api_key

3. Install Dependencies:

   npm install @mapbox/polyline
   

4. Restart Development Server:

   npm run dev
   

How to Use

Basic Routing (2 Points)

1. Select Route Tool: Click the route icon in the tool panel (looks like a path)
2. Add Projects: Click on project markers to add them to your route
3. Calculate Route: Click "Calculate Route" to get directions
4. View Results: See distance, duration, and route path on the map

Optimized Routing (3+ Points)

1. Select Route Tool: Click the route icon in the tool panel
2. Add Projects: Click on project markers (order doesn't matter)
3. Find Optimal Route: Click "Find Optimal Route" - system automatically finds fastest path
4. View Optimization Results: See which route order was selected and performance stats

Features

Core Features

• Multi-point routing: Plan routes through multiple project locations
• Visual route display: Blue dashed line shows the calculated route
• Route markers: Green start marker, red end marker
• Route information: Distance and estimated travel time
• Interactive management: Add/remove projects from route
• Map auto-fit: Automatically adjusts map view to show entire route

Optimization Features ✨

• Hybrid Optimization: Uses ORS Optimization API first, falls back to permutation testing
• Smart Fallback: Automatically switches to proven permutation method if ORS fails
• Order Detection: Clearly shows when route order was actually optimized vs unchanged
• Large Point Support: Can handle up to 50+ points with ORS API
• Performance Monitoring: Detailed logging of optimization approach and results
• Real-time Progress: Shows "Finding Optimal Route..." during calculation

Technical Implementation

Core Functions

calculateRoute()

Main function that handles both basic and optimized routing with hybrid approach:

const calculateRoute = async () => {
    // For 2 points: direct calculation
    if (coordinates.length === 2) {
        const routeData = await calculateRouteForCoordinates(coordinates);
        setRouteData({...routeData, optimized: false});
        return;
    }

    // For 3+ points: try ORS Optimization API first
    let optimizationRequest = {
        jobs: coordinates.map((coord, index) => ({
            id: index,
            location: coord,
            service: 0
        })),
        vehicles: [{
            id: 0,
            profile: 'driving-car',
            // No fixed start/end for true optimization
            capacity: [coordinates.length]
        }],
        options: { g: true }
    };

    try {
        const optimizationResponse = await fetch('https://api.openrouteservice.org/optimization', {
            method: 'POST',
            headers: {
                'Authorization': process.env.NEXT_PUBLIC_ORS_API_KEY,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(optimizationRequest)
        });
        const optimizationData = await optimizationResponse.json();
        
        // Extract optimized order from ORS response
        const optimizedCoordinates = extractOptimizedOrder(optimizationData, coordinates);
        
        // Check if order actually changed
        const orderChanged = detectOrderChange(coordinates, optimizedCoordinates);
        
        if (orderChanged) {
            // Use optimized order
            const routeData = await calculateRouteForCoordinates(optimizedCoordinates);
            setRouteData({...routeData, optimized: true, optimizationStats: {
                method: 'ORS_Optimization_API',
                totalJobs: coordinates.length,
                duration: optimizationData.routes[0].duration,
                distance: optimizationData.routes[0].distance
            }});
        } else {
            // Fallback to permutation testing
            console.log('ORS optimization did not change order, trying permutations...');
            const bestRoute = await findOptimalRouteByPermutations(coordinates);
            const routeData = await calculateRouteForCoordinates(bestRoute);
            setRouteData({...routeData, optimized: true, optimizationStats: {
                method: 'Permutation_Testing',
                totalJobs: coordinates.length,
                duration: routeData.summary.total_duration,
                distance: routeData.summary.total_distance
            }});
        }
    } catch (error) {
        // Complete fallback to permutations
        console.log('ORS optimization failed, using permutation fallback...');
        const bestRoute = await findOptimalRouteByPermutations(coordinates);
        const routeData = await calculateRouteForCoordinates(bestRoute);
        setRouteData({...routeData, optimized: true, optimizationStats: {
            method: 'Permutation_Testing',
            totalJobs: coordinates.length,
            duration: routeData.summary.total_duration,
            distance: routeData.summary.total_distance
        }});
    }
};

calculateRouteForCoordinates(coordinates)

Handles individual OpenRouteService Directions API calls:

const calculateRouteForCoordinates = async (coordinates) => {
    const requestBody = {
        coordinates: coordinates,
        format: 'geojson',
        instructions: true,
        geometry_simplify: false,
        continue_straight: false,
        roundabout_exits: true,
        attributes: ['avgspeed', 'percentage']
    };

    const response = await fetch('https://api.openrouteservice.org/v2/directions/driving-car', {
        method: 'POST',
        headers: {
            'Authorization': process.env.NEXT_PUBLIC_ORS_API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestBody)
    });

    return await response.json();
};

UI Components

Dynamic Button Text

{routeProjects.length > 2 ? 'Find Optimal Route' : 'Calculate Route'}

Optimization Status Display

{routeData.optimized && (
    <div className="mb-2 p-2 bg-green-50 border border-green-200 rounded">
        <div className="flex items-center gap-1 font-medium">
            ✅ Route Optimized
        </div>
        <div className="mt-1">
            Tested {routeData.optimizationStats.totalPermutations} routes
        </div>
    </div>
)}

Performance Considerations

Optimization Limits

• Maximum Points: Limited to 50 points (ORS can handle 100+ in some cases)
• Algorithm: Advanced TSP solver instead of brute-force permutations
• API Calls: Only 2 API calls (1 optimization + 1 detailed route)
• Processing Time: ~1-2 seconds for 50 points (much faster than permutation testing)

Memory Usage

• Each route response contains detailed geometry data
• Large numbers of points can consume significant memory
• Automatic cleanup of unused route data

API Integration

OpenRouteService Optimization API

{
    jobs: [
        { id: 0, location: [lng, lat], service: 0 },
        { id: 1, location: [lng, lat], service: 0 }
    ],
    vehicles: [{
        id: 0,
        profile: 'driving-car',
        start: [lng, lat],
        end: [lng, lat],
        capacity: [point_count]
    }],
    options: { g: true }
}

Directions API Parameters

{
    coordinates: [[lng, lat], [lng, lat], ...],
    format: 'geojson',
    instructions: true,
    geometry_simplify: false,
    continue_straight: false,
    roundabout_exits: true,
    attributes: ['avgspeed', 'percentage']
}

Response Handling

• Optimization API: data.routes[0].steps[] for optimized order
• Directions API: data.routes[0].summary for route details
• Fallback Path: data.features[0].properties.segments[0]
• Geometry: Supports both encoded polylines and direct coordinates
• Error Handling: Graceful fallback for failed calculations

Troubleshooting

Common Issues

"Failed to calculate route"

• Cause: Invalid API key or network issues
• Solution: Verify NEXT_PUBLIC_ORS_API_KEY in .env.local

"Too many points for optimization"

• Cause: Selected more than 50 points
• Solution: Reduce to 50 or fewer points, or use manual routing

Optimization taking too long

• Cause: Large number of points or slow API responses
• Solution: Reduce points or wait for completion (much faster than before)

Optimization API unavailable

• Cause: ORS Optimization API temporarily unavailable
• Solution: Falls back to direct routing without optimization

Route order not optimized

• Cause: ORS Optimization API returned same order or failed
• Solution: System automatically falls back to permutation testing for guaranteed optimization

Optimization shows "Order unchanged"

• Cause: Points may already be in optimal order, or API returned original sequence
• Solution: Check browser console for detailed optimization logs

Permutation fallback activated

• Cause: ORS API unavailable or returned suboptimal results
• Solution: This is normal behavior - permutation testing ensures optimization

---

🔧 Troubleshooting

Common Issues

1. "API Key Missing" Error

Symptom: Route calculation fails with authentication error

Solutions:

• Check .env.local file has NEXT_PUBLIC_ORS_API_KEY=your_key
• Verify no extra spaces around the key
• Ensure development server was restarted after adding the key
• Confirm your OpenRouteService API key is active

# Verify environment variable
echo $env:NEXT_PUBLIC_ORS_API_KEY
# Should output your API key

---

2. Route Not Displaying on Map

Symptom: Calculation succeeds but no route visible

Solutions:

• Check browser console for coordinate transformation errors
• Verify all projects have valid coordinates in database
• Confirm map is zoomed to appropriate level
• Check if route layer is enabled in layer control

Debug:

// Check route data in browser console
console.log('Route GeoJSON:', routeData.geojson);
console.log('Route bounds:', routeData.bounds);

---

3. Optimization Takes Too Long

Symptom: "Find Optimal Route" hangs or times out for many points

Current Limits:

• 8+ points: May take 30+ seconds
• 10+ points: Not recommended (factorial growth)

Solutions:

• Split route into multiple segments
• Use manual point selection for 8+ locations
• Consider implementing A* or genetic algorithm for large routes

Permutation Growth:

3 points = 6 routes to test
4 points = 24 routes
5 points = 120 routes
6 points = 720 routes
7 points = 5,040 routes
8 points = 40,320 routes

---

4. API Rate Limit Exceeded

Symptom: Error 429 or "Too many requests"

Solutions:

• OpenRouteService free tier: 40 requests/minute, 500/day
• Wait 1 minute and try again
• Consider upgrading to paid plan for higher limits
• Implement request queuing with delays

// Add rate limiting check
if (routeProjects.length > 5) {
  alert('Large route may hit rate limits. Consider breaking into segments.');
}

---

5. Incorrect Route Order

Symptom: Optimization doesn't select expected fastest route

Causes:

• Road network topology (one-way streets, traffic restrictions)
• API routing preferences (avoid highways, ferries)
• Distance vs time optimization trade-offs

Verification:

// Check all tested routes in console
routeData.optimizationStats.testedRoutes.forEach(route => {
  console.log(`Route ${route.order}: ${route.distance}m in ${route.duration}s`);
});

---

6. Map Coordinate Transformation Errors

Symptom: "Failed to transform coordinates" in console

Solutions:

• Verify Proj4 definitions are loaded
• Check project coordinates are in valid EPSG:2180 format
• Confirm transformation libraries are properly initialized

// Test coordinate transformation
import proj4 from 'proj4';
const wgs84 = proj4('EPSG:2180', 'EPSG:4326', [x, y]);
console.log('Transformed:', wgs84);

---

Performance Tips

1. Batch Route Calculations: Group nearby projects before calculating routes
2. Cache Routes: Store frequently used routes in localStorage
3. Limit Points: Use max 7 points for real-time optimization
4. Debounce Updates: Wait for user to finish selecting points
5. Progressive Loading: Calculate partial routes while building full path

---

API Limitations

Tier	Requests/Minute	Requests/Day	Cost
Free	40	500	$0
Starter	300	10,000	Contact ORS
Business	Custom	Custom	Contact ORS

Best Practices:

• Avoid unnecessary recalculations
• Implement client-side caching
• Show loading states during API calls
• Handle errors gracefully with user feedback

---

Quick Reference

Enable Route Planning:

# 1. Get API key from openrouteservice.org
# 2. Add to .env.local
NEXT_PUBLIC_ORS_API_KEY=your_key_here
# 3. Restart dev server
npm run dev

Debug Mode:

// Enable in RoutePanel.js
const DEBUG = true;
// Logs all tested routes and optimization stats

Performance Monitoring:

console.time('Route Optimization');
await optimizeRoute();
console.timeEnd('Route Optimization');
// Shows exact optimization duration

---

Debug Information

Check browser console for detailed logs:

• Coordinate parsing details
• API request/response structures
• Optimization approach used (ORS API vs permutation fallback)
• Order change detection (whether optimization actually improved the route)
• Performance timing information
• Original vs optimized coordinate sequences

---

---

📁 File Structure

src/app/projects/map/page.js          # Main map page with routing logic
src/components/ui/LeafletMap.js       # Map component with route rendering
src/components/ui/mapLayers.js        # Map layer configurations

---

📦 Dependencies

• @mapbox/polyline: For decoding route geometry
• leaflet: Map rendering library
• react-leaflet: React integration for Leaflet
• proj4: Coordinate system transformations
• OpenRouteService API key (free tier available)

---

🚀 Future Enhancements

• Advanced Vehicle Constraints: Multiple vehicles, capacity limits, time windows
• Route Preferences: Allow users to prioritize distance vs time vs fuel efficiency
• Real-time Traffic: Integration with live traffic data
• Route History: Save and compare previously optimized routes
• Mobile Optimization: Optimize routes considering current location
• Multi-stop Services: Add service times at each location
• Advanced Optimization: Implement A* or genetic algorithms for 8+ points
• Multi-Day Routes: Break long routes into segments with overnight stops
• Export Options: Export routes to GPS devices or Google Maps
• Cost Estimation: Calculate fuel costs and travel expenses

---

📚 Additional Resources

• OpenRouteService API Documentation
• Directions API Reference
• Polyline Encoding
• Leaflet Routing Integration

---

Last Updated: January 2025
Maintainer: Panel Development Team