Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

7.0 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project

/**
 * Serves a CORS CSV of points orbiting San Francisco.
 *
 * Positions are a function of wall-clock time: each point completes one full
 * loop every 120 seconds. GET /vehicles.csv returns the current positions at
 * request time (no server-side snapshot timer).
 *
 * Kepler.gl polls this URL as DatasetType.EXTERNALLY_HOSTED.
 */
import http from 'node:http';
import path from 'node:path';
import {fileURLToPath} from 'node:url';

import {attachWebSocketHub} from './websocket.mjs';

const DEFAULT_PORT = Number(process.env.LIVE_DATA_PORT || 4010);
const PERIOD_MS = Number(process.env.LIVE_DATA_PERIOD_MS || 120_000);
const POINT_COUNT = Number(process.env.LIVE_DATA_POINTS || 3);
const WS_INTERVAL_MS = Number(process.env.LIVE_DATA_WS_INTERVAL_MS || 400);
const WS_POINT_COUNT = Number(process.env.LIVE_DATA_WS_POINTS || 3);
const WS_PATH = '/vehicles.ws';
const WS_PERIOD_MS = 20_000;
const SF = {lat: 37.7749, lng: -122.4194};
const COS_LAT = Math.cos((SF.lat * Math.PI) / 180);
const KM_PER_DEG_LAT = 111.32;
const RINGS = 3;
const POINTS_PER_RING = Math.max(1, Math.round(POINT_COUNT / RINGS));

function corsHeaders(extra = {}) {
  return {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS',
    'Access-Control-Allow-Headers': 'If-None-Match, If-Modified-Since, Content-Type',
    'Access-Control-Expose-Headers': 'ETag, Last-Modified',
    'Cache-Control': 'no-store',
    ...extra
  };
}

function orbitProgress(nowMs) {
  const elapsed = ((nowMs % PERIOD_MS) + PERIOD_MS) % PERIOD_MS;
  return elapsed / PERIOD_MS;
}

function pointAt(nowMs, index) {
  const ring = Math.floor(index / POINTS_PER_RING);
  const onRing = index % POINTS_PER_RING;
  const radiusKm = 1.8 + ring * 1.2;
  const radiusLat = radiusKm / KM_PER_DEG_LAT;
  const radiusLng = radiusKm / (KM_PER_DEG_LAT * COS_LAT);
  const direction = ring % 2 === 0 ? 1 : -1;
  const start = (onRing / POINTS_PER_RING) * 2 * Math.PI + ring * 0.35;
  const tau = orbitProgress(nowMs);
  const theta = start + direction * tau * 2 * Math.PI;
  const lat = SF.lat + radiusLat * Math.sin(theta);
  const lng = SF.lng + radiusLng * Math.cos(theta);
  const dLat = direction * radiusLat * Math.cos(theta);
  const dLng = direction * -radiusLng * Math.sin(theta);
  const heading = (Math.atan2(dLng, dLat) * 180) / Math.PI;
  const speedKmh = ((2 * Math.PI * radiusKm) / (PERIOD_MS / 1000)) * 3600;
  return {
    id: `veh-${String(index + 1).padStart(2, '0')}`,
    lat,
    lng,
    heading: (heading + 360) % 360,
    speed: speedKmh,
    ring: ring + 1,
    progress: tau
  };
}

function buildCsv(now = new Date()) {
  const nowMs = now.getTime();
  const tau = orbitProgress(nowMs);
  const updatedAt = now.toISOString();
  const header = 'id,lat,lng,heading,speed,ring,progress,orbit_s,updated_at';
  const rows = Array.from({length: POINT_COUNT}, (_, index) => {
    const point = pointAt(nowMs, index);
    return [
      point.id,
      point.lat.toFixed(6),
      point.lng.toFixed(6),
      point.heading.toFixed(1),
      point.speed.toFixed(1),
      point.ring,
      point.progress.toFixed(4),
      (tau * (PERIOD_MS / 1000)).toFixed(2),
      updatedAt
    ].join(',');
  });
  return `${header}\n${rows.join('\n')}\n`;
}

function wsVehicleAt(nowMs, index) {
  const tau = (((nowMs % WS_PERIOD_MS) + WS_PERIOD_MS) % WS_PERIOD_MS) / WS_PERIOD_MS;
  const radiusKm = 6.4 + index * 0.45;
  const radiusLat = radiusKm / KM_PER_DEG_LAT;
  const radiusLng = radiusKm / (KM_PER_DEG_LAT * COS_LAT);
  const theta = tau * 2 * Math.PI + index * 1.7;
  const lat = SF.lat + radiusLat * Math.sin(theta);
  const lng = SF.lng + radiusLng * Math.cos(theta);
  const heading = (((Math.atan2(-radiusLng * Math.sin(theta), radiusLat * Math.cos(theta)) * 180) /
    Math.PI) +
    360) %
    360;
  return {
    id: `ws-${String(index + 1).padStart(2, '0')}`,
    lat,
    lng,
    heading,
    speed: ((2 * Math.PI * radiusKm) / (WS_PERIOD_MS / 1000)) * 3600,
    ring: 8 + index,
    progress: tau,
    orbit_s: tau * (WS_PERIOD_MS / 1000),
    updated_at: new Date(nowMs).toISOString()
  };
}

function websocketPayload(nowMs = Date.now()) {
  return {
    op: 'upsert',
    upsertBy: 'id',
    rows: Array.from({length: WS_POINT_COUNT}, (_, index) => wsVehicleAt(nowMs, index))
  };
}

function serveCsv(req, res) {
  const now = new Date();
  const csv = buildCsv(now);
  const lastModifiedHttp = now.toUTCString();
  // Unique per request so If-None-Match never 304s: each fetch is a new time sample.
  const etag = `"t-${now.getTime()}"`;
  res.writeHead(
    200,
    corsHeaders({
      'Content-Type': 'text/csv; charset=utf-8',
      'Content-Length': Buffer.byteLength(csv),
      ETag: etag,
      'Last-Modified': lastModifiedHttp
    })
  );
  if (req.method !== 'HEAD') {
    res.end(csv);
    return;
  }
  res.end();
}

function serveIndex(res, port) {
  const tau = orbitProgress(Date.now());
  const body = `<!DOCTYPE html>
<html>
  <head><title>kepler.gl live-data</title></head>
  <body style="font-family: sans-serif; max-width: 42em; padding: 24px">
    <h1>Live orbit CSV</h1>
    <p>${POINT_COUNT} points circle San Francisco. One full loop every ${
    PERIOD_MS / 1000
  }s (currently ${(tau * 100).toFixed(1)}% through the orbit).</p>
    <ul>
      <li><a href="/vehicles.csv">/vehicles.csv</a> — paste this into Kepler.gl Add Data → URL, then set Refresh to Custom (0.3s)</li>
      <li><code>ws://localhost:${port}${WS_PATH}</code> — JSON upserts for the live-data <strong>host app</strong> (not Add Data)</li>
    </ul>
    <p>The WebSocket URL is not a Kepler dataset source. Only the CSV belongs in Add Data → URL.</p>
  </body>
</html>`;
  res.writeHead(200, corsHeaders({'Content-Type': 'text/html; charset=utf-8'}));
  res.end(body);
}

export function startLiveDataServer(port = DEFAULT_PORT) {
  const server = http.createServer((req, res) => {
    const url = new URL(req.url || '/', `http://127.0.0.1:${port}`);
    if (req.method === 'OPTIONS') {
      res.writeHead(204, corsHeaders());
      res.end();
      return;
    }
    if (url.pathname === '/vehicles.csv') {
      serveCsv(req, res);
      return;
    }
    if (url.pathname === '/' || url.pathname === '/index.html') {
      serveIndex(res, port);
      return;
    }
    res.writeHead(404, corsHeaders({'Content-Type': 'text/plain'}));
    res.end('Not found\n');
  });

  attachWebSocketHub(server, {
    pathname: WS_PATH,
    intervalMs: WS_INTERVAL_MS,
    getPayload: () => websocketPayload()
  });

  server.listen(port, () => {
    console.info(
      `Live CSV at http://localhost:${port}/vehicles.csv (${POINT_COUNT} points, ${
        PERIOD_MS / 1000
      }s orbit)`
    );
    console.info(
      `Live WebSocket at ws://localhost:${port}${WS_PATH} (${WS_POINT_COUNT} points, ${
        WS_INTERVAL_MS
      }ms upsert)`
    );
  });

  return server;
}

const isDirectRun =
  Boolean(process.argv[1]) && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);

if (isDirectRun) {
  startLiveDataServer();
}