map-routing

Interactive route visualization with pan/zoom and video synchronization for React

Installation

Install the package using npm or yarn:

npm install map-routing

Or with yarn:

yarn add map-routing

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom styled-components

Note: This package supports React 18.x and 19.x.

Quick Start

Basic Usage

Here's a simple example of displaying a route on a map image:

import { ImageRoute } from 'map-routing';

function App() {
  const route = [
    { x: 0.2, y: 0.3, marked: 0 },    // Start point at t=0s
    { x: 0.5, y: 0.4, start: 0, end: 10 },  // Segment from 0-10s
    { x: 0.7, y: 0.6, start: 10, end: 20 }, // Segment from 10-20s
    { x: 0.8, y: 0.8, marked: 20 }    // End point at t=20s
  ];

  return (
    <ImageRoute
      src="/path/to/map.jpg"
      route={route}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

With Video Synchronization

Synchronize the route visualization with a video player:

import { ImageRoute, useRouteVideoSync } from 'map-routing';
import { useRef, useState } from 'react';

function VideoMapSync() {
  const videoRef = useRef(null);
  const [currentTime, setCurrentTime] = useState(0);

  const route = [
    { x: 0.2, y: 0.3, marked: 0 },
    { x: 0.5, y: 0.4, start: 0, end: 10 },
    { x: 0.7, y: 0.6, start: 10, end: 20 },
    { x: 0.8, y: 0.8, marked: 20 }
  ];

  // Sync route progress with video
  const { progress } = useRouteVideoSync({
    videoRef,
    route,
    onProgressChange: setCurrentTime
  });

  return (
    <div>
      <video
        ref={videoRef}
        src="/path/to/video.mp4"
        controls
        style={{ width: '100%', maxWidth: '800px' }}
      />

      <ImageRoute
        src="/path/to/map.jpg"
        route={route}
        progress={progress}
        style={{ width: '100%', height: '600px' }}
      />

      <p>Current time: {currentTime.toFixed(2)}s</p>
    </div>
  );
}

Tip: The route coordinates use normalized values (0-1 range). x: 0 is the left edge, x: 1 is the right edge. Same for y-axis (top to bottom).

Key Features

🖱️ Interactive Navigation

Right-click and drag to pan around the map
Mouse wheel to zoom in and out
Touch support: pinch-to-zoom and drag gestures

🎥 Video Synchronization

Sync route progress with video playback
Click on route points to seek video
Real-time highlighting of active route segments

🎨 Fully Customizable

Custom point and path renderers
Configurable zoom levels and sensitivity
Animation timing controls
TypeScript support with full type definitions

📐 Normalized Coordinates

Define routes using 0-1 coordinate system
Responsive across all screen sizes
No need to worry about pixel dimensions

Interactive Tools

Try out these interactive tools to explore map-routing features:

🎨 Route Creator

Visual editor for creating route data files with video synchronization

Launch Tool →

🧪 Examples

Interactive examples and test cases

View Examples →

Next Steps

Explore more about what map-routing can do:

API Reference - Complete documentation of all props, hooks, and types
Features & Customizations - Learn about advanced features and customization options
Route Creator Tool - Visual editor for creating route data with video synchronization