API Reference

ImageRoute Component

The main component for displaying an interactive route overlay on a map image.

Props

Prop	Type	Default	Description
`src`required	`string`	-	Source URL of the map image
`route`required	`Point[]`	-	Array of route points (see Point type)
`progress`	`number`	`undefined`	Current progress timestamp for video sync (in seconds)
`minZoom`	`number`	`1`	Minimum zoom level allowed
`maxZoom`	`number`	`5`	Maximum zoom level allowed
`zoomSensitivity`	`number`	`0.001`	Mouse wheel zoom sensitivity
`animationDuration`	`number`	`300`	Animation duration in milliseconds
`animationDelay`	`number`	`0`	Animation delay in milliseconds
`tapThreshold`	`number`	`10`	Maximum movement (in pixels) to detect a tap gesture
`snapThreshold`	`number`	`0.02`	Click proximity threshold for snapping to points (normalized units)
`renderPoint`	`(props: RenderPointProps) => ReactNode`	`undefined`	Custom renderer for route points (see Custom Renderers)
`renderPath`	`(props: RenderPathProps) => ReactNode`	`undefined`	Custom renderer for path segments (see Custom Renderers)
`renderExtra`	`(props: RenderExtraProps) => ReactNode`	`undefined`	Custom renderer for additional overlays
`onProgressChange`	`(time: number) => void`	`undefined`	Callback when user clicks on route to change progress
`style`	`CSSProperties`	`{}`	CSS styles for the container
`className`	`string`	`undefined`	CSS class name for the container

Example

<ImageRoute
  src="/map.jpg"
  route={routeData}
  progress={currentTime}
  minZoom={0.5}
  maxZoom={10}
  zoomSensitivity={0.002}
  animationDuration={400}
  onProgressChange={(time) => console.log('Seek to:', time)}
  style={{ width: '100%', height: '600px' }}
/>

useRouteVideoSync Hook

Hook for synchronizing route visualization with video playback.

Parameters

Parameter	Type	Description
`videoRef`required	`RefObject<HTMLVideoElement>`	React ref to the video element
`route`required	`Point[]`	Array of route points with timestamps
`onProgressChange`	`(time: number) => void`	Callback when video time updates

Returns

Property	Type	Description
`progress`	`number`	Current video time (in seconds)
`setProgress`	`(time: number) => void`	Function to update video time (seeks video)

Example

const videoRef = useRef(null);

const { progress, setProgress } = useRouteVideoSync({
  videoRef,
  route: routeData,
  onProgressChange: (time) => console.log('Video at:', time)
});

// Use progress in ImageRoute
<ImageRoute
  src="/map.jpg"
  route={routeData}
  progress={progress}
  onProgressChange={setProgress}
/>

TypeScript Types

Point

Defines a single point in the route with optional timestamp information.

type Point = {
  x: number;           // Normalized X coordinate (0-1, left to right)
  y: number;           // Normalized Y coordinate (0-1, top to bottom)
  marked?: number;     // Single timestamp for standalone points (seconds)
  start?: number;      // Segment start time for path segments (seconds)
  end?: number;        // Segment end time for path segments (seconds)
  data?: string;       // Optional custom data
};

Coordinate System: All coordinates are normalized (0-1 range). This makes routes responsive and independent of actual image dimensions.

Spot

Represents a point on the map with interpolation information.

type Spot = {
  point: Point;        // The route point
  time: number;        // Current time (seconds)
  visited: boolean;    // Whether this point has been passed
  active: boolean;     // Whether this point is currently active
};

Custom Renderer Props

RenderPointProps

type RenderPointProps = {
  spot: Spot;          // The spot being rendered
  index: number;       // Index in the route array
  route: Point[];      // Full route data
};

RenderPathProps

type RenderPathProps = {
  from: Spot;          // Starting spot
  to: Spot;            // Ending spot
  index: number;       // Index of the starting point
  route: Point[];      // Full route data
};

RenderExtraProps

type RenderExtraProps = {
  spots: Spot[];       // All spots in the route
  route: Point[];      // Full route data
  progress?: number;   // Current progress time
};

Utility Functions & Hooks

calculateOptimalZoom

Calculate the optimal zoom level to fit a route within the viewport.

function calculateOptimalZoom(
  route: Point[],
  containerWidth: number,
  containerHeight: number,
  padding?: number
): number;

Parameters

route - Array of route points
containerWidth - Container width in pixels
containerHeight - Container height in pixels
padding - Optional padding factor (default: 0.1 = 10%)

Example

const zoom = calculateOptimalZoom(route, 800, 600, 0.15);

Exported Utility Hooks

The following hooks are available for advanced use cases:

useBoundingClientRect - Track element dimensions
useControlledState - Controlled/uncontrolled state pattern
useEventListener - Declarative event listener management
useHistory - Undo/redo state management
useResizeObserver - Observe element resize events

Note: These hooks are primarily used internally but exported for advanced customization scenarios. Refer to the source code for detailed usage.