refactor: separate traffic and bikeshare components

This commit is contained in:
Sameh Khamis committed 2026-09-13 14:10:38 -07:00
1 parent 3143d00c90
commit 903fe6ba37
45 files changed
+6159 -4363

No files matched your search

+46
View File
@@ -0,0 +1,46 @@
import { STATUS_POLL_MS } from './policy.js';
export function createControls({ state: layerState, services, parts, source }) {
const methods = {
id: 'bikeshare',
name: 'Bikeshare',
icon: '🚲',
source: 'GBFS',
updateInterval: STATUS_POLL_MS,
/**
* Return a sampled array of detectable station objects for HUD overlay rendering.
* @param {Object} [options] - Sampling options (maxCount, seed).
* @returns {Array<{ position: Cesium.Cartesian3, id: string, type: string, skipLabel: boolean }>}
*/
getDetectableObjects(options = {}) {
return parts.queries.collectDetectableStations(options);
},
/**
* Return current layer statistics for the UI status display.
* @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string }}
*/
getStats() {
const stats = {
count: layerState._count,
lastUpdate: layerState._lastUpdate,
loading: layerState._loading,
};
if (layerState._loading) {
stats.loadingLabel =
layerState._activeCityIds.size > 0
? `syncing ${layerState._activeCityIds.size} city feeds...`
: 'scanning nearby systems...';
}
if (layerState._error) stats.error = layerState._error;
return stats;
},
};
return { methods };
}
+50
View File
@@ -0,0 +1,50 @@
import { createIngestion } from './ingestion.js';
import { createModel } from './model.js';
import { createViewport } from './viewport.js';
import { createRendering } from './rendering.js';
import { createSelection } from './selection.js';
import { createQueries } from './queries.js';
import { createTesting } from './testing.js';
import { createControls } from './controls.js';
import { createLifecycle } from './lifecycle.js';
import { createState } from './state.js';
/** Construct one layer with its own scene state and supplied application services. */
export function createBikeshareLayer({ services, source }) {
if (typeof source?.getStations !== 'function')
throw new TypeError('A bikeshare source is required');
const state = createState({ services });
const parts = {};
const context = { state, services, parts, source };
parts.ingestion = createIngestion(context);
parts.model = createModel(context);
parts.viewport = createViewport(context);
parts.rendering = createRendering(context);
parts.selection = createSelection(context);
parts.queries = createQueries(context);
parts.testing = createTesting(context);
parts.controls = createControls(context);
parts.lifecycle = createLifecycle(context);
return Object.assign(
{},
parts.controls.methods,
parts.lifecycle.methods,
parts.ingestion?.methods,
{
createBikeshareSelectedOverlayEntry:
parts.selection.createBikeshareSelectedOverlayEntry,
_setBikeshareSelectionStateForTest:
parts.testing._setBikeshareSelectionStateForTest,
_selectBikeshareStationForTest:
parts.testing._selectBikeshareStationForTest,
_clearBikeshareSelectionForTest:
parts.testing._clearBikeshareSelectionForTest,
},
);
}
export {
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
BIKESHARE_SELECTED_OVERLAY_SOURCE_OPTIONS,
} from './policy.js';
export { createBikeshareSource } from './source.js';
+212
View File
@@ -0,0 +1,212 @@
import { CITY_BY_ID } from './registry.js';
export function createIngestion({
state: layerState,
services,
parts,
source,
}) {
/**
* Convert an upstream GBFS URL into a local proxy URL.
* The dev server proxies /api/gbfs/* to avoid CORS issues with third-party feeds.
* @param {string} upstreamUrl - Full HTTPS GBFS endpoint URL.
* @returns {string} Relative proxy URL.
*/
function toProxyUrl(upstreamUrl) {
return `/api/gbfs/${encodeURIComponent(upstreamUrl)}`;
}
/** Increment the loading reference count and mark loading state active. */
function beginLoading() {
layerState._loadingOps++;
layerState._loading = true;
}
/** Decrement the loading reference count; clear loading flag when zero. */
function endLoading() {
layerState._loadingOps = Math.max(0, layerState._loadingOps - 1);
layerState._loading = layerState._loadingOps > 0;
}
/**
* Fetch and parse JSON from a GBFS endpoint via the local proxy.
* @param {string} upstreamUrl - Full HTTPS GBFS endpoint URL.
* @param {Object} [options]
* @param {AbortSignal} [options.signal] - Optional abort signal for cancellation.
* @returns {Promise<Object>} Parsed JSON payload.
* @throws {Error} On non-OK HTTP status or malformed JSON.
*/
async function fetchGbfsJson(upstreamUrl, options) {
return source.getStations(upstreamUrl, options);
}
/**
* Abort an in-flight GBFS request for a specific city and remove it from the map.
* @param {Map<string, { controller: AbortController }>} map - In-flight request map.
* @param {string} cityId - City whose request should be cancelled.
*/
function abortInFlight(map, cityId) {
const entry = map.get(cityId);
if (!entry) return;
try {
entry.controller?.abort();
} catch {
// no-op
}
map.delete(cityId);
}
/** Abort all in-flight station info and status requests across all cities. */
function abortAllInFlight() {
for (const cityId of layerState._inFlightInfo.keys())
abortInFlight(layerState._inFlightInfo, cityId);
for (const cityId of layerState._inFlightStatus.keys())
abortInFlight(layerState._inFlightStatus, cityId);
}
/**
* Load station information for a city. Returns cached data if available,
* deduplicates concurrent requests, and caches the result on success.
* Station info is static metadata (location, name, capacity) and is
* fetched once per city per session.
* @param {string} cityId - City identifier.
* @param {number} generation - Proximity generation to detect stale requests.
* @returns {Promise<Map<string, Object>>} Map of stationId to station info.
* @throws {Error} On unknown city, fetch failure, or empty station list.
*/
async function loadCityStationInfo(cityId, generation) {
if (layerState._stationInfoCache.has(cityId))
return layerState._stationInfoCache.get(cityId);
const inFlight = layerState._inFlightInfo.get(cityId);
if (inFlight) return inFlight.promise;
const city = CITY_BY_ID.get(cityId);
if (!city) throw new Error(`Unknown GBFS city "${cityId}"`);
const controller = new AbortController();
const promise = (async () => {
beginLoading();
try {
const payload = await fetchGbfsJson(city.stationInformationUrl, {
signal: controller.signal,
});
const stationMap = parts.model.parseStationInformation(payload);
if (stationMap.size === 0) {
throw new Error(`No station information for ${city.city}`);
}
layerState._stationInfoCache.set(cityId, stationMap);
return stationMap;
} finally {
endLoading();
}
})().finally(() => {
// Clean up in-flight entry only if it is still ours (not replaced by a newer request)
const current = layerState._inFlightInfo.get(cityId);
if (current && current.controller === controller)
layerState._inFlightInfo.delete(cityId);
});
layerState._inFlightInfo.set(cityId, { promise, controller, generation });
return promise;
}
/**
* Load real-time station status for a city (bike/dock counts, operational flags).
* Unlike station info, status is NOT served from cache — it is always re-fetched
* to keep availability data current. Concurrent requests are deduplicated.
* @param {string} cityId - City identifier.
* @param {number} generation - Proximity generation to detect stale requests.
* @returns {Promise<Map<string, Object>>} Map of stationId to status objects.
* @throws {Error} On unknown city or fetch failure.
*/
async function loadCityStationStatus(cityId, generation) {
const inFlight = layerState._inFlightStatus.get(cityId);
if (inFlight) return inFlight.promise;
const city = CITY_BY_ID.get(cityId);
if (!city) throw new Error(`Unknown GBFS city "${cityId}"`);
const controller = new AbortController();
const promise = (async () => {
beginLoading();
try {
const payload = await fetchGbfsJson(city.stationStatusUrl, {
signal: controller.signal,
});
const statusMap = parts.model.parseStationStatus(payload);
layerState._statusCache.set(cityId, {
statusMap,
timestamp: Date.now(),
});
return statusMap;
} finally {
endLoading();
}
})().finally(() => {
const current = layerState._inFlightStatus.get(cityId);
if (current && current.controller === controller)
layerState._inFlightStatus.delete(cityId);
});
layerState._inFlightStatus.set(cityId, { promise, controller, generation });
return promise;
}
const methods = {
/**
* Periodic update tick — re-fetches station status for all active cities
* and refreshes point colors/sizes. Called by the layer manager at
* STATUS_POLL_MS intervals.
* @returns {Promise<void>}
*/
async update() {
if (!layerState._enabled || layerState._activeCityIds.size === 0) return;
const generation = layerState._proximityGeneration;
const cityIds = Array.from(layerState._activeCityIds);
await Promise.all(
cityIds.map(async (cityId) => {
try {
const statusMap = await loadCityStationStatus(cityId, generation);
if (
!layerState._enabled ||
!layerState._activeCityIds.has(cityId) ||
generation !== layerState._proximityGeneration
)
return;
parts.rendering.applyStatusToPoints(cityId, statusMap);
} catch (error) {
if (error?.name === 'AbortError') return;
console.warn(
`[Data:Bikeshare] ${cityId} status update error:`,
error,
);
layerState._error = 'GBFS status update failed';
}
}),
);
layerState._count = layerState._stationRenderMap.size;
if (layerState._count > 0) layerState._lastUpdate = Date.now();
},
};
return {
toProxyUrl,
beginLoading,
endLoading,
fetchGbfsJson,
abortInFlight,
abortAllInFlight,
loadCityStationInfo,
loadCityStationStatus,
methods,
};
}
+171
View File
@@ -0,0 +1,171 @@
import * as Cesium from 'cesium';
import { GBFS_CITY_REGISTRY } from './registry.js';
import { BIKESHARE_SELECTED_OVERLAY_SOURCE_ID } from './policy.js';
export function createLifecycle({
state: layerState,
services,
parts,
source,
}) {
const { registerSpriteCollection, restoreSpriteOrder } = services.sprites;
const { registerPickOwner, unregisterPickOwner } = services.picking;
const methods = {
/**
* Initialize the bikeshare layer. Creates the point primitive collection,
* resets all internal state, and installs the click handler.
* Called once during app bootstrap.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
*/
init(viewer) {
layerState._viewer = viewer;
layerState._pointCollection = new Cesium.PointPrimitiveCollection({
blendOption: Cesium.BlendOption.TRANSLUCENT,
});
viewer.scene.primitives.add(layerState._pointCollection);
registerSpriteCollection('bikeshare', layerState._pointCollection);
layerState._pointCollection.show = false;
layerState._enabled = false;
layerState._cameraDebounceTimer = null;
layerState._cameraChangedAttached = false;
layerState._altitudeGateEnabled = false;
layerState._proximityGeneration = 0;
layerState._activeCityIds = new Set();
layerState._cityRuntime = new Map();
layerState._stationInfoCache = new Map();
layerState._statusCache = new Map();
layerState._inFlightInfo = new Map();
layerState._inFlightStatus = new Map();
layerState._stationRenderMap = new Map();
layerState._clickHandler = null;
layerState._selectedKey = null;
layerState._selectedEntity = null;
layerState._count = 0;
layerState._lastUpdate = null;
layerState._loading = false;
layerState._loadingOps = 0;
layerState._error = null;
layerState._limitWarned = false;
layerState._overlayHost.setVisible(
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
false,
);
parts.selection._installClickHandler(viewer);
restoreSpriteOrder(viewer);
console.log(
`[Data:Bikeshare] Initialized with ${GBFS_CITY_REGISTRY.length} cities`,
);
},
/**
* Enable the bikeshare layer. Shows points, attaches the camera listener,
* and triggers an initial proximity check.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
*/
enable(viewer) {
layerState._enabled = true;
layerState._error = null;
layerState._pointCollection.show = true;
layerState._overlayHost.setVisible(
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
true,
);
parts.selection._installClickHandler(viewer);
// Pick-ownership (H2): station point ids are string render-map keys.
registerPickOwner('bikeshare', (pickedId) =>
layerState._stationRenderMap.has(pickedId),
);
if (!layerState._cameraChangedAttached) {
viewer.camera.changed.addEventListener(parts.viewport.onCameraChanged);
viewer.camera.percentageChanged = Math.min(
viewer.camera.percentageChanged || 1,
0.05,
);
layerState._cameraChangedAttached = true;
}
void parts.viewport.runProximityCheck();
restoreSpriteOrder(viewer);
},
/**
* Disable the bikeshare layer. Hides points, removes event listeners,
* aborts all pending fetches, and tears down all city data.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
*/
disable(viewer) {
layerState._enabled = false;
layerState._proximityGeneration++;
layerState._altitudeGateEnabled = false;
clearTimeout(layerState._cameraDebounceTimer);
layerState._cameraDebounceTimer = null;
parts.selection._clearSelection();
layerState._overlayHost.setVisible(
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
false,
);
if (layerState._clickHandler) {
layerState._clickHandler.destroy();
layerState._clickHandler = null;
}
document.removeEventListener('keydown', parts.selection._onKeyDown);
unregisterPickOwner('bikeshare');
if (layerState._cameraChangedAttached) {
viewer.camera.changed.removeEventListener(
parts.viewport.onCameraChanged,
);
layerState._cameraChangedAttached = false;
}
parts.ingestion.abortAllInFlight();
parts.viewport.deactivateAllCities();
layerState._cityRuntime.clear();
layerState._pointCollection.show = false;
layerState._count = 0;
layerState._loading = false;
layerState._loadingOps = 0;
},
/** Permanently release primitives, handlers, and the selected host source. */
destroy(viewer) {
if (layerState._enabled) this.disable(viewer);
else {
parts.selection._clearSelection();
layerState._overlayHost.setVisible(
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
false,
);
if (layerState._clickHandler) {
layerState._clickHandler.destroy();
layerState._clickHandler = null;
}
document.removeEventListener('keydown', parts.selection._onKeyDown);
unregisterPickOwner('bikeshare');
}
if (layerState._cameraChangedAttached) {
viewer.camera.changed.removeEventListener(
parts.viewport.onCameraChanged,
);
layerState._cameraChangedAttached = false;
}
parts.ingestion.abortAllInFlight();
if (layerState._pointCollection) {
viewer.scene.primitives.remove(layerState._pointCollection);
layerState._pointCollection = null;
}
layerState._viewer = null;
},
};
return { methods };
}
+162
View File
@@ -0,0 +1,162 @@
export function createModel({ state: layerState, services, parts, source }) {
/**
* Coerce a GBFS boolean field to a native boolean.
* GBFS feeds are inconsistent — some use booleans, others use 0/1 or strings.
* @param {*} value - Raw field value from GBFS JSON.
* @param {boolean} [fallback=true] - Default when value is null/undefined/unrecognized.
* @returns {boolean}
*/
function normalizeGbfsBool(value, fallback = true) {
if (value == null) return fallback;
if (typeof value === 'boolean') return value;
const num = Number(value);
if (Number.isFinite(num)) return num !== 0;
const text = String(value).trim().toLowerCase();
if (text === 'true' || text === 'yes') return true;
if (text === 'false' || text === 'no') return false;
return fallback;
}
/**
* Parse a value as a non-negative integer, returning fallback on failure.
* @param {*} value - Raw numeric value.
* @param {number|null} [fallback=null] - Returned when value is not a valid non-negative number.
* @returns {number|null}
*/
function toNonNegativeInteger(value, fallback = null) {
const n = Number(value);
if (!Number.isFinite(n) || n < 0) return fallback;
return Math.round(n);
}
/**
* Build a globally unique render key for a station.
* @param {string} cityId - City identifier.
* @param {string} stationId - Station identifier within the city.
* @returns {string} Composite key in "cityId:stationId" format.
*/
function stationKey(cityId, stationId) {
return `${cityId}:${stationId}`;
}
/**
* Compute the great-circle distance between two points using the Haversine formula.
* @param {number} aLat - Latitude of point A in degrees.
* @param {number} aLon - Longitude of point A in degrees.
* @param {number} bLat - Latitude of point B in degrees.
* @param {number} bLon - Longitude of point B in degrees.
* @returns {number} Distance in kilometers.
*/
function haversineKm(aLat, aLon, bLat, bLon) {
const toRad = (value) => (value * Math.PI) / 180;
const dLat = toRad(bLat - aLat);
const dLon = toRad(bLon - aLon);
const p1 = toRad(aLat);
const p2 = toRad(bLat);
const a =
Math.sin(dLat / 2) ** 2 +
Math.cos(p1) * Math.cos(p2) * Math.sin(dLon / 2) ** 2;
return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}
/**
* Extract the stations array from a GBFS JSON payload.
* Handles multiple response shapes: { data: { stations: [...] } },
* { data: [...] }, and nested objects with a stations sub-key.
* @param {Object} payload - Parsed GBFS JSON response.
* @returns {Object[]} Array of raw station objects (may be empty).
*/
function extractStationsArray(payload) {
const data = payload?.data;
if (Array.isArray(data?.stations)) return data.stations;
if (Array.isArray(data)) return data;
// Some feeds nest stations under an additional key (e.g. locale wrappers)
if (data && typeof data === 'object') {
for (const value of Object.values(data)) {
if (Array.isArray(value?.stations)) return value.stations;
}
}
return [];
}
/**
* Parse a GBFS station_information payload into a Map of station metadata.
* Handles field-name variations across different GBFS providers
* (station_id vs id, lat vs latitude, etc.). Stations with missing or
* invalid coordinates are silently skipped.
* @param {Object} payload - Parsed station_information.json response.
* @returns {Map<string, Object>} Map of stationId to station info objects.
*/
function parseStationInformation(payload) {
const stations = extractStationsArray(payload);
const stationMap = new Map();
for (const raw of stations) {
// Accept both GBFS 2.x (station_id) and alternate (id) field names
const stationId = String(raw?.station_id ?? raw?.id ?? '').trim();
const lat = Number(raw?.lat ?? raw?.latitude);
const lon = Number(raw?.lon ?? raw?.longitude);
if (!stationId || !Number.isFinite(lat) || !Number.isFinite(lon))
continue;
stationMap.set(stationId, {
stationId,
name: String(raw?.name || raw?.short_name || '').trim(),
lat,
lon,
capacity: toNonNegativeInteger(raw?.capacity),
isInstalled: normalizeGbfsBool(raw?.is_installed, true),
isRenting: normalizeGbfsBool(raw?.is_renting, true),
isReturning: normalizeGbfsBool(raw?.is_returning, true),
});
}
return stationMap;
}
/**
* Parse a GBFS station_status payload into a Map of real-time availability.
* @param {Object} payload - Parsed station_status.json response.
* @returns {Map<string, Object>} Map of stationId to status objects containing
* bikesAvailable, docksAvailable, and operational flags.
*/
function parseStationStatus(payload) {
const stations = extractStationsArray(payload);
const statusMap = new Map();
for (const raw of stations) {
const stationId = String(raw?.station_id ?? raw?.id ?? '').trim();
if (!stationId) continue;
const bikes = toNonNegativeInteger(raw?.num_bikes_available);
const docks = toNonNegativeInteger(raw?.num_docks_available);
statusMap.set(stationId, {
stationId,
bikesAvailable: bikes,
docksAvailable: docks,
isInstalled: normalizeGbfsBool(raw?.is_installed, true),
isRenting: normalizeGbfsBool(raw?.is_renting, true),
isReturning: normalizeGbfsBool(raw?.is_returning, true),
lastReported: toNonNegativeInteger(raw?.last_reported),
});
}
return statusMap;
}
return {
normalizeGbfsBool,
toNonNegativeInteger,
stationKey,
haversineKm,
extractStationsArray,
parseStationInformation,
parseStationStatus,
};
}
+85
View File
@@ -0,0 +1,85 @@
import * as Cesium from 'cesium';
export const BIKESHARE_SELECTED_OVERLAY_SOURCE_ID = 'bikeshare-selected';
export const BIKESHARE_SELECTED_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 0,
moving: false,
});
// --- Activation / display thresholds ---
/** Altitude (m) at which bikeshare layer becomes eligible for display. */
export const ACTIVATION_ALTITUDE_M = 50000;
/** Hysteresis enter threshold — layer activates when camera drops below this. */
export const ACTIVATION_ENTER_ALTITUDE_M = ACTIVATION_ALTITUDE_M - 2000;
/** Hysteresis exit threshold — layer deactivates when camera rises above this. */
export const ACTIVATION_EXIT_ALTITUDE_M = ACTIVATION_ALTITUDE_M + 2000;
/** Debounce interval (ms) for camera-change proximity checks. */
export const CAMERA_DEBOUNCE_MS = 340;
/** Default radius (km) for determining whether a city is in camera range. */
export const CITY_RANGE_BASE_KM = 100;
/** Polling interval (ms) for refreshing station status data. */
export const STATUS_POLL_MS = 60000;
// --- Point rendering constants ---
/** Minimum rendered point size in pixels. */
export const POINT_SIZE_MIN = 4;
/** Maximum rendered point size in pixels. */
export const POINT_SIZE_MAX = 12;
/** Fallback station capacity when real data is unavailable. */
export const DEFAULT_CAPACITY = 15;
/** Vertical offset (m) above terrain for station points. */
export const POINT_HEIGHT_OFFSET_M = 2.0;
/** Hard cap on total rendered station points across all cities. */
export const MAX_TOTAL_POINTS = 8000;
// --- Availability color palette ---
/** Station has >60% bikes available. */
export const COLOR_GREEN =
Cesium.Color.fromCssColorString('#00ff88').withAlpha(0.95);
/** Station has 30-60% bikes available. */
export const COLOR_YELLOW =
Cesium.Color.fromCssColorString('#ffaa00').withAlpha(0.94);
/** Station has <30% bikes available. */
export const COLOR_RED =
Cesium.Color.fromCssColorString('#ff4444').withAlpha(0.94);
/** No status data available for station. */
export const COLOR_NEUTRAL =
Cesium.Color.fromCssColorString('#91a4b4').withAlpha(0.62);
/** Station is offline (not installed, not renting, or not returning). */
export const COLOR_MUTED =
Cesium.Color.fromCssColorString('#687581').withAlpha(0.48);
/** Outline color for all station points. */
export const COLOR_OUTLINE = Cesium.Color.BLACK.withAlpha(0.25);
+75
View File
@@ -0,0 +1,75 @@
export function createQueries({ state: layerState, services, parts, source }) {
/**
* Build a compact HUD detection ID string for a station.
* Truncates long names to 24 chars for readability.
* @param {Object} record - Render record from _stationRenderMap.
* @returns {string} Formatted label like "Station Name [5/20]".
*/
function buildDetectionId(record) {
const bikes = Number.isFinite(record.bikesAvailable)
? record.bikesAvailable
: '?';
const capacity = Number.isFinite(record.capacity) ? record.capacity : '?';
// Render record stores the station name under `stationName` (see the render-map
// shape), so `record.name` was always undefined → every label read "Dock N".
const label = record.stationName || `Dock ${record.stationId}`;
// Truncate long station names to keep HUD readable
const short = label.length > 24 ? label.slice(0, 22) + '…' : label;
return `🚲 ${short} [${bikes}/${capacity}]`;
}
/**
* Collect a sampled subset of visible stations for HUD detection overlay rendering.
* Uses a deterministic stride pattern controlled by options.seed and options.maxCount
* to avoid overcrowding the HUD while still providing broad coverage.
* @param {Object} [options]
* @param {number} [options.maxCount] - Maximum number of detectable objects to return.
* @param {number} [options.seed] - Seed for deterministic stride offset selection.
* @returns {Array<{ position: Cesium.Cartesian3, id: string, type: string, skipLabel: boolean }>}
*/
function collectDetectableStations(options = {}) {
if (
!layerState._enabled ||
!layerState._pointCollection ||
!layerState._pointCollection.show ||
layerState._stationRenderMap.size === 0
)
return [];
// Gather all visible station records (include selected even though its point is hidden)
const records = [];
for (const record of layerState._stationRenderMap.values()) {
const isSelected = record.key === layerState._selectedKey;
if ((!record.point?.show && !isSelected) || !record.point?.position)
continue;
records.push(record);
}
if (records.length === 0) return [];
// Deterministic subsampling: pick every Nth station, offset by seed
const maxCount = Number.isFinite(options.maxCount)
? Math.max(1, Math.floor(options.maxCount))
: records.length;
const seed = Number.isFinite(options.seed) ? Math.floor(options.seed) : 0;
const stride = Math.max(1, Math.ceil(records.length / maxCount));
const start = ((seed % stride) + stride) % stride;
const result = [];
for (let i = start; i < records.length; i += stride) {
const record = records[i];
result.push({
position: record.point.position,
sourceId: record.key,
id: buildDetectionId(record),
type: 'VEH',
skipLabel: record.key === layerState._selectedKey,
});
if (result.length >= maxCount) break;
}
return result;
}
return { buildDetectionId, collectDetectableStations };
}
+394
View File
@@ -0,0 +1,394 @@
function buildBcycleUrls(systemId) {
return {
stationInformationUrl: `https://gbfs.bcycle.com/${systemId}/station_information.json`,
stationStatusUrl: `https://gbfs.bcycle.com/${systemId}/station_status.json`,
};
}
function bcycleEntry({
id,
city,
centerLat,
centerLon,
systemId,
loadRadiusKm = 100,
provider = 'BCycle',
}) {
return {
id,
city,
centerLat,
centerLon,
loadRadiusKm,
provider,
...buildBcycleUrls(systemId),
};
}
const RAW_GBFS_CITY_REGISTRY = [
{
id: 'nyc-citibike',
city: 'New York, NY',
centerLat: 40.7484,
centerLon: -73.9967,
loadRadiusKm: 140,
stationInformationUrl:
'https://gbfs.lyft.com/gbfs/2.3/bkn/en/station_information.json',
stationStatusUrl:
'https://gbfs.lyft.com/gbfs/2.3/bkn/en/station_status.json',
provider: 'Citi Bike',
},
{
id: 'chicago-divvy',
city: 'Chicago, IL',
centerLat: 41.8781,
centerLon: -87.6298,
loadRadiusKm: 120,
stationInformationUrl:
'https://gbfs.lyft.com/gbfs/2.3/chi/en/station_information.json',
stationStatusUrl:
'https://gbfs.lyft.com/gbfs/2.3/chi/en/station_status.json',
provider: 'Divvy',
},
{
id: 'dc-capital-bikeshare',
city: 'Washington, DC',
centerLat: 38.9072,
centerLon: -77.0369,
loadRadiusKm: 120,
stationInformationUrl:
'https://gbfs.lyft.com/gbfs/2.3/dca-cabi/en/station_information.json',
stationStatusUrl:
'https://gbfs.lyft.com/gbfs/2.3/dca-cabi/en/station_status.json',
provider: 'Capital Bikeshare',
},
{
id: 'sf-bay-wheels',
city: 'San Francisco, CA',
centerLat: 37.7749,
centerLon: -122.4194,
loadRadiusKm: 110,
stationInformationUrl:
'https://gbfs.lyft.com/gbfs/2.3/bay/en/station_information.json',
stationStatusUrl:
'https://gbfs.lyft.com/gbfs/2.3/bay/en/station_status.json',
provider: 'Bay Wheels',
},
{
id: 'boston-bluebikes',
city: 'Boston, MA',
centerLat: 42.3601,
centerLon: -71.0589,
loadRadiusKm: 100,
stationInformationUrl:
'https://gbfs.bluebikes.com/gbfs/en/station_information.json',
stationStatusUrl: 'https://gbfs.bluebikes.com/gbfs/en/station_status.json',
provider: 'Blue Bikes',
},
{
id: 'philadelphia-indego',
city: 'Philadelphia, PA',
centerLat: 39.9526,
centerLon: -75.1652,
loadRadiusKm: 100,
stationInformationUrl:
'https://gbfs.bcycle.com/bcycle_indego/station_information.json',
stationStatusUrl:
'https://gbfs.bcycle.com/bcycle_indego/station_status.json',
provider: 'Indego',
},
{
id: 'portland-biketown',
city: 'Portland, OR',
centerLat: 45.5152,
centerLon: -122.6784,
loadRadiusKm: 95,
stationInformationUrl:
'https://gbfs.biketownpdx.com/gbfs/2.3/en/station_information.json',
stationStatusUrl:
'https://gbfs.biketownpdx.com/gbfs/2.3/en/station_status.json',
provider: 'BIKETOWN',
},
{
id: 'la-metro-bike',
city: 'Los Angeles, CA',
centerLat: 34.0522,
centerLon: -118.2437,
loadRadiusKm: 120,
stationInformationUrl:
'https://gbfs.bcycle.com/bcycle_lametro/station_information.json',
stationStatusUrl:
'https://gbfs.bcycle.com/bcycle_lametro/station_status.json',
provider: 'Metro Bike',
},
{
id: 'austin-capmetro',
city: 'Austin, TX',
centerLat: 30.2672,
centerLon: -97.7431,
loadRadiusKm: 90,
stationInformationUrl:
'https://austin.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
stationStatusUrl:
'https://austin.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
provider: 'CapMetro',
},
{
id: 'honolulu-biki',
city: 'Honolulu, HI',
centerLat: 21.3069,
centerLon: -157.8583,
loadRadiusKm: 90,
stationInformationUrl:
'https://hon.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
stationStatusUrl:
'https://hon.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
provider: 'Biki',
},
{
id: 'columbus-cogo',
city: 'Columbus, OH',
centerLat: 39.9612,
centerLon: -82.9988,
loadRadiusKm: 90,
stationInformationUrl:
'https://gbfs.cogobikeshare.com/gbfs/2.3/en/station_information.json',
stationStatusUrl:
'https://gbfs.cogobikeshare.com/gbfs/2.3/en/station_status.json',
provider: 'CoGo',
},
{
id: 'chattanooga-bikechatt',
city: 'Chattanooga, TN',
centerLat: 35.0456,
centerLon: -85.3097,
loadRadiusKm: 90,
stationInformationUrl:
'https://chat.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
stationStatusUrl:
'https://chat.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
provider: 'Bike Chattanooga',
},
bcycleEntry({
id: 'boulder-bcycle',
city: 'Boulder, CO',
centerLat: 40.015,
centerLon: -105.2705,
systemId: 'bcycle_boulder',
}),
bcycleEntry({
id: 'milwaukee-bublr',
city: 'Milwaukee, WI',
centerLat: 43.0389,
centerLon: -87.9065,
systemId: 'bcycle_bublr',
provider: 'Bublr',
}),
bcycleEntry({
id: 'madison-bcycle',
city: 'Madison, WI',
centerLat: 43.0731,
centerLon: -89.4012,
systemId: 'bcycle_madison',
}),
bcycleEntry({
id: 'nashville-bcycle',
city: 'Nashville, TN',
centerLat: 36.1627,
centerLon: -86.7816,
systemId: 'bcycle_nashville',
}),
bcycleEntry({
id: 'salt-lake-greenbike',
city: 'Salt Lake City, UT',
centerLat: 40.7608,
centerLon: -111.891,
systemId: 'bcycle_greenbikeslc',
provider: 'GREENbike',
}),
bcycleEntry({
id: 'san-antonio-bcycle',
city: 'San Antonio, TX',
centerLat: 29.4241,
centerLon: -98.4936,
systemId: 'bcycle_sanantonio',
}),
bcycleEntry({
id: 'cincinnati-red-bike',
city: 'Cincinnati, OH',
centerLat: 39.1031,
centerLon: -84.512,
systemId: 'bcycle_cincyredbike',
provider: 'Red Bike',
}),
bcycleEntry({
id: 'el-paso-bcycle',
city: 'El Paso, TX',
centerLat: 31.7619,
centerLon: -106.485,
systemId: 'bcycle_elpaso',
}),
bcycleEntry({
id: 'indianapolis-pacers',
city: 'Indianapolis, IN',
centerLat: 39.7684,
centerLon: -86.1581,
systemId: 'bcycle_pacersbikeshare',
provider: 'Pacers Bikeshare',
}),
bcycleEntry({
id: 'fort-lauderdale-broward',
city: 'Fort Lauderdale, FL',
centerLat: 26.1224,
centerLon: -80.1373,
systemId: 'bcycle_broward',
provider: 'Broward B-cycle',
}),
bcycleEntry({
id: 'memphis-bcycle',
city: 'Memphis, TN',
centerLat: 35.1495,
centerLon: -90.049,
systemId: 'bcycle_memphis',
}),
bcycleEntry({
id: 'des-moines-bcycle',
city: 'Des Moines, IA',
centerLat: 41.5868,
centerLon: -93.625,
systemId: 'bcycle_desmoines',
}),
bcycleEntry({
id: 'tucson-tugo',
city: 'Tucson, AZ',
centerLat: 32.2226,
centerLon: -110.9747,
systemId: 'bcycle_tugo',
provider: 'Tugo',
}),
bcycleEntry({
id: 'fort-worth-trinity',
city: 'Fort Worth, TX',
centerLat: 32.7555,
centerLon: -97.3308,
systemId: 'bcycle_fortworth',
provider: 'Trinity Metro',
}),
bcycleEntry({
id: 'omaha-heartland',
city: 'Omaha, NE',
centerLat: 41.2565,
centerLon: -95.9345,
systemId: 'bcycle_heartland',
provider: 'Heartland B-cycle',
}),
bcycleEntry({
id: 'lincoln-bikelnk',
city: 'Lincoln, NE',
centerLat: 40.8136,
centerLon: -96.7026,
systemId: 'bcycle_bikelnk',
provider: 'BikeLNK',
}),
bcycleEntry({
id: 'greenville-sc-bcycle',
city: 'Greenville, SC',
centerLat: 34.8526,
centerLon: -82.394,
systemId: 'bcycle_greenville',
}),
bcycleEntry({
id: 'buffalo-reddy',
city: 'Buffalo, NY',
centerLat: 42.8864,
centerLon: -78.8784,
systemId: 'bcycle_reddy',
provider: 'Reddy Bikeshare',
}),
bcycleEntry({
id: 'las-vegas-rtc-bike-share',
city: 'Las Vegas, NV',
centerLat: 36.1699,
centerLon: -115.1398,
systemId: 'bcycle_rtcbikeshare',
provider: 'RTC Bike Share',
}),
bcycleEntry({
id: 'santa-barbara-bcycle',
city: 'Santa Barbara, CA',
centerLat: 34.4208,
centerLon: -119.6982,
systemId: 'bcycle_santabarbara',
}),
];
function normalizeRegistryEntry(entry) {
const id = String(entry?.id || '')
.trim()
.toLowerCase();
const city = String(entry?.city || '').trim();
const centerLat = Number(entry?.centerLat);
const centerLon = Number(entry?.centerLon);
const loadRadiusKm = Number(entry?.loadRadiusKm);
const stationInformationUrl = new URL(
String(entry?.stationInformationUrl || '').trim(),
);
const stationStatusUrl = new URL(
String(entry?.stationStatusUrl || '').trim(),
);
if (!id) throw new Error('GBFS entry id is required');
if (!city) throw new Error(`GBFS entry "${id}" city is required`);
if (!Number.isFinite(centerLat) || !Number.isFinite(centerLon)) {
throw new Error(`GBFS entry "${id}" has invalid center coordinates`);
}
// Enforce HTTPS-only for GBFS feeds
if (
stationInformationUrl.protocol !== 'https:' ||
stationStatusUrl.protocol !== 'https:'
) {
throw new Error(`GBFS entry "${id}" must use https URLs`);
}
// Validate that URLs end with expected GBFS endpoint filenames
if (!/\/station_information\.json$/i.test(stationInformationUrl.pathname)) {
throw new Error(`GBFS entry "${id}" station_information URL is invalid`);
}
if (!/\/station_status\.json$/i.test(stationStatusUrl.pathname)) {
throw new Error(`GBFS entry "${id}" station_status URL is invalid`);
}
// Deduplicate hostnames across both feed URLs for proxy allowlisting
const hosts = Array.from(
new Set([
stationInformationUrl.hostname.toLowerCase(),
stationStatusUrl.hostname.toLowerCase(),
]),
);
return {
id,
city,
centerLat,
centerLon,
loadRadiusKm:
Number.isFinite(loadRadiusKm) && loadRadiusKm > 0
? loadRadiusKm
: CITY_RANGE_BASE_KM,
stationInformationUrl: stationInformationUrl.toString(),
stationStatusUrl: stationStatusUrl.toString(),
provider: String(entry?.provider || 'GBFS').trim() || 'GBFS',
hosts,
};
}
const GBFS_CITY_REGISTRY = (() => {
const seen = new Set();
return RAW_GBFS_CITY_REGISTRY.map((entry) => {
const normalized = normalizeRegistryEntry(entry);
if (seen.has(normalized.id)) {
throw new Error(`Duplicate GBFS city id: ${normalized.id}`);
}
seen.add(normalized.id);
return normalized;
});
})();
const CITY_BY_ID = new Map(
GBFS_CITY_REGISTRY.map((entry) => [entry.id, entry]),
);
export { GBFS_CITY_REGISTRY, CITY_BY_ID };
+282
View File
@@ -0,0 +1,282 @@
import * as Cesium from 'cesium';
import {
DEFAULT_CAPACITY,
POINT_SIZE_MIN,
POINT_SIZE_MAX,
COLOR_NEUTRAL,
COLOR_MUTED,
COLOR_GREEN,
COLOR_YELLOW,
COLOR_RED,
POINT_HEIGHT_OFFSET_M,
MAX_TOTAL_POINTS,
COLOR_OUTLINE,
} from './policy.js';
export function createRendering({
state: layerState,
services,
parts,
source,
}) {
const { governorRequestRender } = services.render;
/**
* Resolve the effective dock capacity for a station.
* Prefers the explicit capacity from station_information; falls back to
* bikes+docks from status data; uses DEFAULT_CAPACITY as last resort.
* @param {number|null} capacityFromInfo - Capacity from station_information, or null.
* @param {Object|null} status - Station status object with bikesAvailable/docksAvailable.
* @returns {number} Resolved capacity (always > 0).
*/
function resolveCapacity(capacityFromInfo, status) {
const fromInfo = parts.model.toNonNegativeInteger(capacityFromInfo);
if (fromInfo && fromInfo > 0) return fromInfo;
// Derive capacity from current bikes + available docks
const bikes = parts.model.toNonNegativeInteger(status?.bikesAvailable, 0);
const docks = parts.model.toNonNegativeInteger(status?.docksAvailable, 0);
const derived = bikes + docks;
if (derived > 0) return derived;
return DEFAULT_CAPACITY;
}
/**
* Map station capacity to a point pixel size using a sqrt scale.
* Larger-capacity stations render as bigger dots; clamped to [POINT_SIZE_MIN, POINT_SIZE_MAX].
* @param {number} capacity - Station dock capacity.
* @returns {number} Point size in pixels.
*/
function capacityToPixelSize(capacity) {
const c = Math.max(1, Math.min(80, Number(capacity) || DEFAULT_CAPACITY));
// sqrt scale so large stations don't dominate visually
const normalized = Math.sqrt(c) / Math.sqrt(80);
const size =
POINT_SIZE_MIN + normalized * (POINT_SIZE_MAX - POINT_SIZE_MIN);
return Math.max(POINT_SIZE_MIN, Math.min(POINT_SIZE_MAX, size));
}
/**
* Determine the display color for a station based on its availability ratio.
* - No status data: neutral gray.
* - Offline (not installed/renting/returning): muted gray.
* - >60% bikes available: green.
* - 30-60% bikes available: yellow.
* - <30% bikes available: red.
* @param {Object|null} status - Station status object.
* @param {number} capacity - Resolved station capacity.
* @returns {Cesium.Color} Color to apply to the station point.
*/
function statusToColor(status, capacity) {
if (!status) return COLOR_NEUTRAL;
if (!status.isInstalled || !status.isRenting || !status.isReturning)
return COLOR_MUTED;
const bikes = parts.model.toNonNegativeInteger(status.bikesAvailable);
if (!Number.isFinite(bikes)) return COLOR_NEUTRAL;
const cap = Math.max(1, Number(capacity) || DEFAULT_CAPACITY);
const ratio = bikes / cap;
if (ratio > 0.6) return COLOR_GREEN;
if (ratio >= 0.3) return COLOR_YELLOW;
return COLOR_RED;
}
/**
* Create a Cartesian3 position for a station, terrain-clamped when possible.
* Falls back to a fixed small height offset if terrain sampling is unsupported.
* @param {Object} station - Station info object with lat/lon.
* @returns {Cesium.Cartesian3|null} World position, or null if coordinates are invalid.
*/
function createStationPosition(station) {
const lon = Number(station?.lon);
const lat = Number(station?.lat);
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
let height = POINT_HEIGHT_OFFSET_M;
// Sample terrain height so points sit on ground rather than at ellipsoid level
if (layerState._viewer?.scene?.sampleHeightSupported) {
const carto = Cesium.Cartographic.fromDegrees(lon, lat);
const sampled = layerState._viewer.scene.sampleHeight(carto);
if (Number.isFinite(sampled)) {
height = sampled + POINT_HEIGHT_OFFSET_M;
}
}
return Cesium.Cartesian3.fromDegrees(lon, lat, height);
}
/**
* Get or create the runtime tracking object for a city.
* @param {string} cityId - City identifier.
* @returns {{ stationKeys: Set<string> }} City runtime object.
*/
function ensureCityRuntime(cityId) {
if (layerState._cityRuntime.has(cityId))
return layerState._cityRuntime.get(cityId);
const runtime = { stationKeys: new Set() };
layerState._cityRuntime.set(cityId, runtime);
return runtime;
}
/**
* Ensure point primitives exist for all stations in a city.
* Creates new points for stations not yet rendered; skips existing ones.
* Respects the MAX_TOTAL_POINTS global cap to prevent GPU overload.
* @param {string} cityId - City identifier.
* @param {Map<string, Object>} stationMap - Parsed station info map for the city.
*/
function ensureCityPoints(cityId, stationMap) {
// Deferred debounce/fetch completions mutate point primitives after the
// camera settled — each commit needs one frame in idle mode. (perf wave 2 fix)
governorRequestRender('bikeshare-points');
const runtime = ensureCityRuntime(cityId);
for (const station of stationMap.values()) {
const key = parts.model.stationKey(cityId, station.stationId);
if (layerState._stationRenderMap.has(key)) {
runtime.stationKeys.add(key);
continue;
}
// Enforce global point cap
if (layerState._stationRenderMap.size >= MAX_TOTAL_POINTS) {
if (!layerState._limitWarned) {
layerState._limitWarned = true;
console.warn(
`[Data:Bikeshare] Point cap reached (${MAX_TOTAL_POINTS}).`,
);
}
break;
}
const position = createStationPosition(station);
if (!position) continue;
// Add a point primitive with distance-based scale and translucency falloff
const point = layerState._pointCollection.add({
position,
pixelSize: capacityToPixelSize(station.capacity),
color: COLOR_NEUTRAL,
outlineColor: COLOR_OUTLINE,
outlineWidth: 1,
scaleByDistance: new Cesium.NearFarScalar(200, 1.35, 130000, 0.4),
translucencyByDistance: new Cesium.NearFarScalar(
200,
1.0,
180000,
0.15,
),
disableDepthTestDistance: 2500,
id: key,
});
layerState._stationRenderMap.set(key, {
key,
cityId,
stationId: station.stationId,
stationName: station.name,
point,
capacity: parts.model.toNonNegativeInteger(station.capacity),
bikesAvailable: null,
docksAvailable: null,
isInstalled: station.isInstalled,
isRenting: station.isRenting,
isReturning: station.isReturning,
});
runtime.stationKeys.add(key);
}
layerState._count = layerState._stationRenderMap.size;
}
/**
* Remove all rendered point primitives for a city and clean up runtime state.
* Also clears any active selection if it belongs to this city.
* @param {string} cityId - City identifier to remove.
*/
function removeCityPoints(cityId) {
const runtime = layerState._cityRuntime.get(cityId);
if (!runtime) return;
// Clear selection if it belongs to the city being removed
if (
layerState._selectedKey &&
runtime.stationKeys.has(layerState._selectedKey)
) {
parts.selection._clearSelection();
}
for (const key of runtime.stationKeys) {
const record = layerState._stationRenderMap.get(key);
if (!record) continue;
layerState._pointCollection.remove(record.point);
layerState._stationRenderMap.delete(key);
}
layerState._cityRuntime.delete(cityId);
layerState._count = layerState._stationRenderMap.size;
}
/**
* Apply real-time status data to rendered station points for a city.
* Updates each point's color (availability ratio) and pixel size (capacity),
* and refreshes the render record's cached availability fields.
* @param {string} cityId - City identifier.
* @param {Map<string, Object>} statusMap - Parsed station status map.
*/
function applyStatusToPoints(cityId, statusMap) {
governorRequestRender('bikeshare-status');
const runtime = layerState._cityRuntime.get(cityId);
if (!runtime) return;
for (const key of runtime.stationKeys) {
const record = layerState._stationRenderMap.get(key);
if (!record) continue;
const status = statusMap.get(record.stationId) || null;
const capacity = resolveCapacity(record.capacity, status);
record.capacity = capacity;
record.bikesAvailable = parts.model.toNonNegativeInteger(
status?.bikesAvailable,
);
record.docksAvailable = parts.model.toNonNegativeInteger(
status?.docksAvailable,
);
record.isInstalled = parts.model.normalizeGbfsBool(
status?.isInstalled,
true,
);
record.isRenting = parts.model.normalizeGbfsBool(status?.isRenting, true);
record.isReturning = parts.model.normalizeGbfsBool(
status?.isReturning,
true,
);
// Update visual properties based on current status
record.point.pixelSize = capacityToPixelSize(capacity);
record.point.color = statusToColor(status, capacity);
}
}
return {
resolveCapacity,
capacityToPixelSize,
statusToColor,
createStationPosition,
ensureCityRuntime,
ensureCityPoints,
removeCityPoints,
applyStatusToPoints,
};
}
+206
View File
@@ -0,0 +1,206 @@
import * as Cesium from 'cesium';
import {
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
BIKESHARE_SELECTED_OVERLAY_SOURCE_OPTIONS,
} from './policy.js';
export function createSelection({
state: layerState,
services,
parts,
source,
}) {
/**
* Build a multi-line text label for the selected station popup.
* Shows station name, availability counts, and any abnormal operational flags.
* @param {Object} record - Render record from _stationRenderMap.
* @returns {string} Newline-delimited source text for the selected host card.
*/
function buildSelectionLabel(record) {
const stationName = String(record?.stationName || '').trim();
const stationLabel =
stationName ||
(record?.stationId ? `Station ${record.stationId}` : 'Station');
const bikes = Number.isFinite(record?.bikesAvailable)
? record.bikesAvailable
: '?';
const docks = Number.isFinite(record?.docksAvailable)
? record.docksAvailable
: '?';
const capacity = Number.isFinite(record?.capacity) ? record.capacity : '?';
const lines = [
stationLabel,
`🚲 ${bikes} avail · ${docks} docks · ${capacity} cap`,
];
// Append warnings for stations that are offline or partially non-operational
const abnormal = [];
if (record?.isInstalled === false) abnormal.push('⚠️ Not installed');
if (record?.isRenting === false) abnormal.push('⚠️ Not renting');
if (record?.isReturning === false) abnormal.push('⚠️ Not returning');
if (abnormal.length > 0) {
lines.push(abnormal.join(' · '));
}
return lines.join('\n');
}
/**
* Build the protected selected-station entry from source-owned copy.
* @param {string} key Stable city/station composite key.
* @param {Object} record Bikeshare render record.
* @returns {Object|null}
*/
function createBikeshareSelectedOverlayEntry(key, record) {
const position = record?.point?.position;
if (!key || !position) return null;
const [title, ...details] = buildSelectionLabel(record).split('\n');
return {
id: String(key),
position,
variant: 'selected',
selected: true,
protected: true,
paintLane: 'selected',
collisionGroup: 'ambient-card',
priority: Number.MAX_SAFE_INTEGER,
title,
details,
accent: '#00ffff',
interactive: false,
anchorRadiusPx: 9,
minAnchorGapPx: 11,
verticalOnly: true,
placement: 'above',
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
};
}
/**
* Clear the current station selection.
* Re-shows the hidden point primitive and removes the highlight entity.
*/
function _clearSelection() {
if (layerState._selectedKey) {
const record = layerState._stationRenderMap.get(layerState._selectedKey);
if (record?.point) {
record.point.show = true;
}
}
if (layerState._selectedEntity && layerState._viewer) {
layerState._viewer.entities.remove(layerState._selectedEntity);
}
layerState._selectedKey = null;
layerState._selectedEntity = null;
layerState._overlayHost.clearSource(BIKESHARE_SELECTED_OVERLAY_SOURCE_ID);
}
/**
* Select a station by key: hides the original point primitive and adds a
* highlighted cyan entity plus a protected shared-host availability card.
* @param {string} key - Composite "cityId:stationId" key.
*/
function _selectStation(key) {
_clearSelection();
const record = layerState._stationRenderMap.get(key);
if (!record || !record.point?.position || !layerState._viewer) return;
layerState._selectedKey = key;
// Hide the base point so the highlight entity replaces it visually
record.point.show = false;
layerState._selectedEntity = layerState._viewer.entities.add({
position: record.point.position,
point: {
pixelSize: 14,
color: Cesium.Color.CYAN,
outlineColor: Cesium.Color.BLACK,
outlineWidth: 2,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
},
});
const entry = createBikeshareSelectedOverlayEntry(key, record);
if (entry) {
layerState._overlayHost.setEntries(
BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
[entry],
BIKESHARE_SELECTED_OVERLAY_SOURCE_OPTIONS,
);
}
}
/**
* Install a screen-space click handler for station selection/deselection.
* Also registers a global keydown listener for Escape-to-deselect.
* Idempotent — does nothing if a handler is already installed.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
*/
function _installClickHandler(viewer) {
if (layerState._clickHandler) return;
layerState._clickHandler = new Cesium.ScreenSpaceEventHandler(
viewer.scene.canvas,
);
layerState._clickHandler.setInputAction((click) => {
const picked = viewer.scene.pick(click.position);
if (picked) {
// Clicking selected entity itself — ignore (don't deselect).
if (picked.id === layerState._selectedEntity) return;
// Check if the picked primitive or entity id matches a station key
const primitive = picked.primitive;
if (
primitive &&
typeof primitive.id === 'string' &&
layerState._stationRenderMap.has(primitive.id)
) {
_selectStation(primitive.id);
return;
}
if (
typeof picked.id === 'string' &&
layerState._stationRenderMap.has(picked.id)
) {
_selectStation(picked.id);
return;
}
}
// Clicked empty space — deselect.
if (layerState._selectedKey) _clearSelection();
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
document.addEventListener('keydown', _onKeyDown);
}
/**
* Global keydown handler — deselects the current station on Escape.
* @param {KeyboardEvent} e - Keyboard event.
*/
function _onKeyDown(e) {
if (e.key === 'Escape' && layerState._selectedKey) {
_clearSelection();
}
}
return {
buildSelectionLabel,
createBikeshareSelectedOverlayEntry,
_clearSelection,
_selectStation,
_installClickHandler,
_onKeyDown,
};
}
+23
View File
@@ -0,0 +1,23 @@
/** Read a GBFS station document through the existing bounded server proxy. */
export function createBikeshareSource({
fetchImpl = (...args) => globalThis.fetch(...args),
} = {}) {
return {
async getStations(upstreamUrl, { signal } = {}) {
const url = new URL(upstreamUrl);
if (url.protocol !== 'https:' || url.username || url.password || url.hash)
throw new TypeError('A public HTTPS GBFS URL is required');
signal?.throwIfAborted();
const response = await fetchImpl(
'/api/gbfs?url=' + encodeURIComponent(url.href),
{ method: 'GET', headers: { Accept: 'application/json' }, signal },
);
if (!response.ok) throw new Error('GBFS HTTP ' + response.status);
const payload = await response.json();
signal?.throwIfAborted();
if (!payload || typeof payload !== 'object')
throw new Error('Malformed GBFS payload');
return payload;
},
};
}
+44
View File
@@ -0,0 +1,44 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createBikeshareSource } from './source.js';
test('station source keeps upstream URLs behind the fixed GBFS endpoint', async () => {
const calls = [];
const source = createBikeshareSource({
fetchImpl: async (...args) => {
calls.push(args);
return new Response('{"data":{"stations":[]}}');
},
});
for (const url of [
'file:///etc/passwd',
'http://example.test/stations',
'https://user:[email protected]/stations',
])
await assert.rejects(source.getStations(url), /HTTPS GBFS/);
assert.equal(calls.length, 0);
await source.getStations('https://example.test/stations.json');
const url = new URL(calls[0][0], 'https://app.example');
assert.equal(url.pathname, '/api/gbfs');
assert.equal(
url.searchParams.get('url'),
'https://example.test/stations.json',
);
});
test('cancelled station parsing never publishes the response', async () => {
const controller = new AbortController();
const source = createBikeshareSource({
fetchImpl: async () => ({
ok: true,
json: async () => {
controller.abort();
return { data: { stations: [] } };
},
}),
});
await assert.rejects(
source.getStations('https://example.test/stations', {
signal: controller.signal,
}),
{ name: 'AbortError' },
);
});
+110
View File
@@ -0,0 +1,110 @@
export function createState({ services }) {
const { setOverlayEntries, setOverlaySourceVisible, clearOverlaySource } =
services.overlays;
const layerState = {};
layerState.DEFAULT_OVERLAY_HOST = Object.freeze({
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
clearSource: clearOverlaySource,
});
layerState._overlayHost = layerState.DEFAULT_OVERLAY_HOST;
// ---------------------------------------------------------------------------
// Module-level mutable state
// ---------------------------------------------------------------------------
/** @type {Cesium.Viewer|null} Active Cesium viewer instance. */
layerState._viewer = null;
/** @type {Cesium.PointPrimitiveCollection|null} Primitive collection for station dots. */
layerState._pointCollection = null;
/** Whether the bikeshare layer is currently enabled. */
layerState._enabled = false;
/** Timer handle for camera-move debounce. */
layerState._cameraDebounceTimer = null;
/** Whether the camera.changed listener is currently attached. */
layerState._cameraChangedAttached = false;
/** Hysteresis flag for altitude-based activation. */
layerState._altitudeGateEnabled = false;
/** Monotonic generation counter; incremented on each proximity check to cancel stale work. */
layerState._proximityGeneration = 0;
/** @type {Set<string>} City ids currently considered in-range. */
layerState._activeCityIds = new Set();
/** @type {Map<string, { stationKeys: Set<string> }>} Per-city runtime tracking of rendered station keys. */
layerState._cityRuntime = new Map();
/** @type {Map<string, Map<string, Object>>} Cached station information per city (cityId -> stationId -> StationInfo). */
layerState._stationInfoCache = new Map();
/** @type {Map<string, { timestamp: number, statusMap: Map<string, Object> }>} Cached station status per city. */
layerState._statusCache = new Map();
/** @type {Map<string, { promise: Promise, controller: AbortController, generation: number }>} In-flight station info requests. */
layerState._inFlightInfo = new Map();
/** @type {Map<string, { promise: Promise, controller: AbortController, generation: number }>} In-flight station status requests. */
layerState._inFlightStatus = new Map();
/** @type {Map<string, Object>} Render records keyed by "cityId:stationId". */
layerState._stationRenderMap = new Map();
/** @type {Cesium.ScreenSpaceEventHandler|null} Click handler for station selection. */
layerState._clickHandler = null;
/** @type {string|null} Key of the currently selected station, or null. */
layerState._selectedKey = null;
/** @type {Cesium.Entity|null} Entity used to display the selected-station point highlight. */
layerState._selectedEntity = null;
/** Total number of currently rendered station points. */
layerState._count = 0;
/** Timestamp (ms) of the last successful status update. */
layerState._lastUpdate = null;
/** Whether any GBFS fetch is currently in progress. */
layerState._loading = false;
/** Reference count of concurrent loading operations. */
layerState._loadingOps = 0;
/** Most recent error message string, or null. */
layerState._error = null;
/** Whether the MAX_TOTAL_POINTS cap warning has already been logged. */
layerState._limitWarned = false;
return layerState;
}
+34
View File
@@ -0,0 +1,34 @@
export function createTesting({ state: layerState, services, parts, source }) {
/** Seed a selected-station runtime record while still exercising real select/clear paths. */
function _setBikeshareSelectionStateForTest({
viewer,
key,
record,
overlayHost,
}) {
layerState._viewer = viewer;
layerState._stationRenderMap = new Map([[key, record]]);
layerState._selectedKey = null;
layerState._selectedEntity = null;
layerState._overlayHost = overlayHost || layerState.DEFAULT_OVERLAY_HOST;
}
/** Exercise the production selection path in focused runtime tests. */
function _selectBikeshareStationForTest(key) {
parts.selection._selectStation(key);
}
/** Exercise the production clear path and restore the production host seam. */
function _clearBikeshareSelectionForTest() {
parts.selection._clearSelection();
layerState._overlayHost = layerState.DEFAULT_OVERLAY_HOST;
}
return {
_setBikeshareSelectionStateForTest,
_selectBikeshareStationForTest,
_clearBikeshareSelectionForTest,
};
}
+257
View File
@@ -0,0 +1,257 @@
import * as Cesium from 'cesium';
import { GBFS_CITY_REGISTRY } from './registry.js';
import {
ACTIVATION_EXIT_ALTITUDE_M,
ACTIVATION_ENTER_ALTITUDE_M,
CITY_RANGE_BASE_KM,
CAMERA_DEBOUNCE_MS,
} from './policy.js';
export function createViewport({ state: layerState, services, parts, source }) {
const { governorRequestRender } = services.render;
/**
* Get the camera's current altitude in meters above the ellipsoid.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
* @returns {number} Altitude in meters, or Infinity if unavailable.
*/
function getCameraAltitude(viewer) {
const carto = viewer?.camera?.positionCartographic;
return carto && Number.isFinite(carto.height) ? carto.height : Infinity;
}
/**
* Determine the lat/lon the camera is currently looking at.
* Prefers the center of the computed view rectangle; falls back to the
* camera's own cartographic position when the rectangle is unavailable.
* @param {Cesium.Viewer} viewer - Cesium viewer instance.
* @returns {{ lat: number, lon: number }|null} Center coordinates in degrees, or null.
*/
function getCameraCenterLatLon(viewer) {
// Try view rectangle center first (more accurate for tilted views)
const rect = viewer?.camera?.computeViewRectangle?.(
viewer.scene.globe?.ellipsoid,
);
if (rect) {
const center = Cesium.Rectangle.center(rect);
return {
lat: Cesium.Math.toDegrees(center.latitude),
lon: Cesium.Math.toDegrees(center.longitude),
};
}
// Fallback: use the camera's own position
const carto = viewer?.camera?.positionCartographic;
if (carto) {
return {
lat: Cesium.Math.toDegrees(carto.latitude),
lon: Cesium.Math.toDegrees(carto.longitude),
};
}
return null;
}
/**
* Determine whether the layer should be active at the given camera altitude.
* Uses hysteresis (separate enter/exit thresholds) to avoid rapid toggling
* when the camera hovers near the activation boundary.
* @param {number} altitude - Camera altitude in meters.
* @returns {boolean} True if the layer should remain/become active.
*/
function shouldActivateAtAltitude(altitude) {
if (!Number.isFinite(altitude)) {
layerState._altitudeGateEnabled = false;
return false;
}
if (layerState._altitudeGateEnabled) {
// Deactivate only after crossing the higher exit threshold
if (altitude >= ACTIVATION_EXIT_ALTITUDE_M)
layerState._altitudeGateEnabled = false;
} else if (altitude <= ACTIVATION_ENTER_ALTITUDE_M) {
// Activate when dropping below the lower enter threshold
layerState._altitudeGateEnabled = true;
}
return layerState._altitudeGateEnabled;
}
/**
* Determine which cities are close enough to the camera to warrant loading.
* Compares haversine distance from the camera center to each city's center
* against the city's configured load radius.
* @param {{ lat: number, lon: number }} center - Camera center in degrees.
* @returns {Set<string>} Set of city ids currently within load range.
*/
function computeInRangeCities(center) {
const active = new Set();
if (!center) return active;
for (const city of GBFS_CITY_REGISTRY) {
const distance = parts.model.haversineKm(
center.lat,
center.lon,
city.centerLat,
city.centerLon,
);
const radius = Math.max(CITY_RANGE_BASE_KM, city.loadRadiusKm);
if (distance <= radius) active.add(city.id);
}
return active;
}
/**
* Fully deactivate a single city: abort pending fetches and remove rendered points.
* @param {string} cityId - City identifier to deactivate.
*/
function deactivateCity(cityId) {
governorRequestRender('bikeshare-deactivate');
parts.ingestion.abortInFlight(layerState._inFlightInfo, cityId);
parts.ingestion.abortInFlight(layerState._inFlightStatus, cityId);
parts.rendering.removeCityPoints(cityId);
}
/** Deactivate all currently active cities and clear the active set. */
function deactivateAllCities() {
const cityIds = Array.from(layerState._activeCityIds);
for (const cityId of cityIds) deactivateCity(cityId);
layerState._activeCityIds.clear();
}
/**
* Activate a city: fetch station info, create point primitives, fetch status,
* and apply availability colors. Checks generation at each async boundary
* to bail out if the proximity context has changed.
* @param {string} cityId - City identifier to activate.
* @param {number} generation - Proximity generation at time of invocation.
*/
async function activateCity(cityId, generation) {
if (!layerState._enabled || !layerState._activeCityIds.has(cityId)) return;
try {
const stationMap = await parts.ingestion.loadCityStationInfo(
cityId,
generation,
);
// Bail if context changed during fetch
if (
!layerState._enabled ||
!layerState._activeCityIds.has(cityId) ||
generation !== layerState._proximityGeneration
)
return;
parts.rendering.ensureCityPoints(cityId, stationMap);
// Apply any cached status immediately for snappier initial rendering
const cachedStatus = layerState._statusCache.get(cityId)?.statusMap;
if (cachedStatus) {
parts.rendering.applyStatusToPoints(cityId, cachedStatus);
}
const statusMap = await parts.ingestion.loadCityStationStatus(
cityId,
generation,
);
if (
!layerState._enabled ||
!layerState._activeCityIds.has(cityId) ||
generation !== layerState._proximityGeneration
)
return;
parts.rendering.applyStatusToPoints(cityId, statusMap);
layerState._lastUpdate = Date.now();
layerState._error = null;
} catch (error) {
if (error?.name === 'AbortError') return;
console.warn(`[Data:Bikeshare] ${cityId} activate error:`, error);
layerState._error = 'GBFS fetch error';
deactivateCity(cityId);
layerState._activeCityIds.delete(cityId);
} finally {
layerState._count = layerState._stationRenderMap.size;
}
}
/**
* Core proximity check: determines which cities are in camera range at the
* current altitude, deactivates out-of-range cities, and activates newly
* in-range ones. Increments the generation counter to invalidate stale work.
* @returns {Promise<void>}
*/
async function runProximityCheck() {
if (!layerState._enabled || !layerState._viewer) return;
const generation = ++layerState._proximityGeneration;
const altitude = getCameraAltitude(layerState._viewer);
// Altitude gate: disable all cities when camera is too high
if (!shouldActivateAtAltitude(altitude)) {
deactivateAllCities();
return;
}
const center = getCameraCenterLatLon(layerState._viewer);
if (!center) return;
// Diff active set against newly computed in-range set
const nextActive = computeInRangeCities(center);
for (const cityId of layerState._activeCityIds) {
if (!nextActive.has(cityId)) {
deactivateCity(cityId);
}
}
layerState._activeCityIds = nextActive;
if (layerState._activeCityIds.size === 0) {
layerState._count = 0;
return;
}
// Only activate cities that don't already have rendered points
const toActivate = [];
for (const cityId of layerState._activeCityIds) {
if (!layerState._cityRuntime.has(cityId)) toActivate.push(cityId);
}
if (toActivate.length === 0) return;
await Promise.all(
toActivate.map((cityId) => activateCity(cityId, generation)),
);
}
/** Schedule a debounced proximity check after camera movement. */
function scheduleProximityCheck() {
clearTimeout(layerState._cameraDebounceTimer);
layerState._cameraDebounceTimer = setTimeout(() => {
void runProximityCheck();
}, CAMERA_DEBOUNCE_MS);
}
/** Camera change event handler — triggers a debounced proximity check. */
function onCameraChanged() {
if (!layerState._enabled) return;
scheduleProximityCheck();
}
return {
getCameraAltitude,
getCameraCenterLatLon,
shouldActivateAtAltitude,
computeInRangeCities,
deactivateCity,
deactivateAllCities,
activateCity,
runProximityCheck,
scheduleProximityCheck,
onCameraChanged,
};
}