Introduction

Kinesis.js is a TypeScript-first, framework-agnostic interpolation engine that smoothly animates any stream of live positions across any map — vehicles, vessels, drones, field assets, anything you track — turning sparse, periodic pings into continuous motion at your display's refresh rate.

The problem

Real-time position feeds are sparse. A backend sends each point's position every one, five, or ten seconds — but a map redraws at the display's refresh rate, sixty or more times a second. Apply each update directly and every marker teleports: it sits still, then jumps to the next coordinate, then sits still again. On a dashboard that stays open all day, the jitter is exhausting and makes positions hard to read.

The solution

Kinesis.js sits between your feed and your map. It keeps the last couple of points per object and, on every animation frame, computes where that object should be right now — interpolating along the path between two known positions. The marker glides instead of jumping.

import { Tracker } from '@kinesisjs/core';
import { OpenLayersAdapter } from '@kinesisjs/openlayers';

const tracker = new Tracker({
adapter: new OpenLayersAdapter(map),
interpolation: 'adaptive',
});

tracker.start();
ws.onmessage = (e) => tracker.ingest(JSON.parse(e.data));

The 30-second mental model

Two facts explain almost everything about how the engine behaves:

• The engine only fills the gap between two known points. It interpolates; it does not predict the future. Until a second ping arrives, there is nothing to move between.
• Display stays behind real time by roughly one feed period. A small render-lag buffer (renderLagMs, default 1000) guarantees there are always two points to interpolate between, so motion is continuous rather than snapping on arrival.

Architecture at a glance

Kinesis.js ships as small, composable packages across three layers. You depend only on what your stack needs.

Alongside the layers there's one optional plugin: @kinesisjs/route-aware, a drop-in CustomInterpolator that snaps interpolation to the road network via OSRM.

See Architecture & concepts for the full responsibility model and data pipeline.

Versioning & migration

Kinesis.js follows semantic versioning, and every package is versioned independently. Milestones so far:

• 0.6 — the @kinesisjs/maplibre adapter: the first GL renderer, drawing the whole fleet from one GeoJSON source in a single GPU pass.
• 0.5 — smooth (Catmull-Rom) interpolation and the opt-in playout buffer for jittery feeds.
• 0.4 — OSRM road-snapping via the @kinesisjs/route-aware custom interpolator.
• 0.3 — the @kinesisjs/leaflet adapter.
• 0.2 — Web Worker mode and gap visualization.
• 0.1 — core engine, OpenLayers adapter, Angular wrapper; the renderLagMs buffer landed in 0.1.1.

Next steps

• Quick start — install and render your first live map.
• Interpolation modes — pick the right curve for your feed.
• API reference — every option, method and event.