Frames — Geo Frame — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/frames/geo-frame

StreamGeoFrame

frames

import { StreamGeoFrame, resolveReferenceGeography } from "semiotic/geo"

StreamGeoFrame is the foundational frame for all geographic visualization. It renders GeoJSON areas, projected points, and connecting lines on canvas with d3-geo projections. Use it when the HOC charts (ChoroplethMap, FlowMap, etc.) do not expose the control you need — custom area styling, mixed data layers, streaming geo data, or projection transforms.

Use resolveReferenceGeography("world-110m") to load built-in world map basemaps asynchronously. The data comes from Natural Earth via the world-atlas package and is cached after first load.

Quick Start

At minimum, provide a projection and one data source (areas, points, or lines). For real-world maps, load areas fromresolveReferenceGeography() and overlay your own point and line data.

Loading world map...

Examples

World Map with Earthquakes and Routes

Combine all three data layers on a real world basemap: areas as country boundaries, points as notable earthquake locations, and lines as connecting routes. Set zoomable to enable mouse/touch zoom and pan.

Loading world map...

Projections

StreamGeoFrame supports six built-in projections: mercator,equalEarth, naturalEarth,equirectangular, orthographic, andalbersUsa. You can also pass a d3 projection function or a config object. Here the world map is shown with an orthographic (globe) projection.

Loading world map...

Graticule

Enable graticule to render a latitude/longitude grid. The graticule is non-interactive and renders behind all data layers. Earthquake locations are plotted on top.

Loading world map...

Push API (Streaming)

Set runtimeMode="streaming" and use the ref to push data incrementally. Combine with decay and pulsefor realtime geographic visualization. The streaming demo above simulates earthquake events along real tectonic plate boundaries.

JSX

import { useRef, useEffect, useState } from "react" import { StreamGeoFrame, resolveReferenceGeography } from "semiotic/geo" function StreamingMap() { const chartRef = useRef() const [worldAreas, setWorldAreas] = useState(null) useEffect(() => { resolveReferenceGeography("world-110m").then(features => { setWorldAreas(features) }).catch(err => console.error("Failed to load world map:", err)) }, []) useEffect(() => { if (!worldAreas) return const ws = new WebSocket("wss://events.example.com/earthquakes") ws.onmessage = (e) => { const { lon, lat, magnitude } = JSON.parse(e.data) chartRef.current?.push({ lon, lat, magnitude }) } return () => ws.close() }, [worldAreas]) if (!worldAreas) return <div>Loading world map...</div> return ( <StreamGeoFrame ref={chartRef} projection="equalEarth" areas={worldAreas} xAccessor="lon" yAccessor="lat" runtimeMode="streaming" pointStyle={(d) => ({ fill: d.magnitude > 5 ? "#ef4444" : "#6366f1", r: Math.max(2, d.magnitude), })} decay={{ type: "exponential", minOpacity: 0.05 }} pulse={{ duration: 1000, color: "rgba(239,68,68,0.6)" }} size={[800, 500]} /> ) }

Ref methods:

ref.current.push(datum) — push one point
ref.current.pushMany(data) — push an array of points
ref.current.clear() — clear all data
ref.current.getProjection() — get the d3 projection
ref.current.getGeoPath() — get the d3 geoPath generator

Reference Geography

The resolveReferenceGeography function loads built-in map data asynchronously and caches the result. Available references:

world-110m — 110m resolution world countries (~108KB)
world-50m — 50m resolution world countries (~540KB)
land-110m — 110m land mass (no country boundaries)
land-50m — 50m land mass

JSX

import { resolveReferenceGeography } from "semiotic/geo" // Load once, cache automatically const features = await resolveReferenceGeography("world-110m") // features is GeoJSON.Feature[] — pass directly to areas prop

Distance Cartogram Transform

The projectionTransform prop applies a post-projection distortion that repositions points by cost rather than geographic distance. See DistanceCartogram for the simplified HOC.

JSX

<StreamGeoFrame projection="mercator" points={cities} xAccessor="lon" yAccessor="lat" pointIdAccessor="id" projectionTransform={{ center: "Rome", centerAccessor: "id", costAccessor: "travelDays", strength: 0.8, lineMode: "straight", }} size={[600, 400]} />

Props

Prop	Type	Required	Default	Description
`projection`	string \| object \| function	Yes	—	Projection: name string ("mercator", "equalEarth", etc.), config object { type, rotate, center }, or d3 projection function.
`projectionExtent`	[[number, number], [number, number]]	—	—	Geographic bounding box to constrain projection fit.
`areas`	GeoJSON.Feature[]	—	—	GeoJSON features rendered as filled polygons. Use resolveReferenceGeography() to load built-in basemaps.
`points`	array	—	—	Point data with lon/lat coordinates.
`lines`	array	—	—	Line data with coordinate arrays.
`xAccessor`	string \| function	—	`"lon"`	Longitude accessor for points.
`yAccessor`	string \| function	—	`"lat"`	Latitude accessor for points.
`lineDataAccessor`	string \| function	—	—	Accessor to extract coordinate arrays from line objects.
`pointIdAccessor`	string \| function	—	—	Accessor for point IDs (used by cartogram).
`lineType`	"geo" \| "line"	—	`"line"`	"geo" renders great-circle arcs; "line" renders straight lines.
`areaStyle`	Style \| function	—	—	Style object or function for area features.
`pointStyle`	function	—	—	Function returning style + optional r for each point.
`lineStyle`	Style \| function	—	—	Style for line features.
`colorScheme`	string \| string[]	—	—	Color scheme.
`graticule`	boolean \| object	—	`false`	Latitude/longitude grid overlay.
`zoomable`	boolean	—	`false`	Enable mouse/touch zoom and pan on the map.
`projectionTransform`	DistanceCartogramConfig	—	—	Distance cartogram transform config: { center, centerAccessor, costAccessor, strength, lineMode }.
`size`	[number, number]	—	—	Chart dimensions [width, height].
`width`	number	—	`600`	Chart width.
`height`	number	—	`400`	Chart height.
`margin`	object	—	—	Chart margins.
`background`	string	—	—	Background color.
`runtimeMode`	"bounded" \| "streaming"	—	`"bounded"`	Data mode. Streaming enables push API.
`enableHover`	boolean	—	`true`	Enable hover interaction.
`tooltipContent`	function	—	—	Custom tooltip render function.
`customClickBehavior`	function	—	—	Click handler receiving { type, data, x, y }.
`customHoverBehavior`	function	—	—	Hover handler receiving { type, data, x, y } or null.
`decay`	DecayConfig	—	—	Decay encoding for streaming points: { type, minOpacity }.
`pulse`	PulseConfig	—	—	Pulse glow on new data: { duration, color, glowRadius }.
`transition`	TransitionConfig	—	—	Animated position transitions: { duration }.
`annotations`	array	—	—	Annotation overlay objects.
`title`	string \| ReactNode	—	—	Chart title.
`legend`	object	—	—	Legend configuration (usually set by HOC).
`responsiveWidth`	boolean	—	`false`	Auto-resize to container width.
`responsiveHeight`	boolean	—	`false`	Auto-resize to container height.

ChoroplethMap — simplified Chart for color-encoded areas
ProportionalSymbolMap — simplified Chart for sized symbols
FlowMap — simplified Chart for geographic flows
DistanceCartogram — simplified Chart for cost-distance distortion
StreamXYFrame — for continuous x/y data
StreamNetworkFrame — for network/hierarchy data