Maps — pic drawings as GeoJSON
A pic drawing is a plane of inches. geopic places that plane on the Earth
with a four-parameter similarity — an anchor, a scale in metres per inch and
a bearing — and carries every shape to longitude/latitude: boxes and circles
become polygons, lines and arrows line strings, labels points, all with their
style as simplestyle properties
plus a geopic:* namespace. The result is a standard GeoJSON
FeatureCollection (WGS84) that Leaflet, MapLibre, QGIS, geopandas or sf read
directly.
Nothing about the pic language changes: the placement is a few variables in the source (or options on the call), and the same drawing still renders to SVG, PNG and PDF as before.
Declare where the origin is
geo_lon = -34.8711 # WGS84 position of the pic origin (0, 0)
geo_lat = -8.0631
geo_scale = 400 # metres per inch of the drawing
geo_bearing = 0 # azimuth of +y, clockwise from north (default)
dot at (0, 0) rad 0.04
B: box "Marco Zero" "Recife" wid 1.3 ht 0.5 at (1.4, 0.9) fill 0.95 class "screen"
arrow from B.sw to (0.06, 0.06) thick 1.2
rpic --geojson callout.pic > callout.geojson
{ "type": "FeatureCollection", "features": [
{ "type": "Feature",
"geometry": { "type": "Point", "coordinates": [-34.8711, -8.0631] },
"properties": { "geopic:schema": 1, "geopic:id": "s0", "geopic:kind": "dot",
"geopic:placement": "screen", "fill": "#000000", "…": "…" } },
{ "type": "Feature",
"geometry": { "type": "Polygon", "coordinates": [[[-34.868, -8.0616], "…"]] },
"properties": { "geopic:kind": "box", "title": "Marco Zero\nRecife",
"fill": "#f2f2f2", "stroke": "#000000", "stroke-width": 0.8,
"geopic:label": "B", "geopic:class": "screen",
"geopic:placement": "screen", "…": "…" } },
{ "type": "Feature",
"geometry": { "type": "Point", "coordinates": [-34.86602, -8.05984] },
"properties": { "geopic:kind": "title", "geopic:for": "s1",
"geopic:text": "Marco Zero\nRecife", "geopic:anchor": "c", "…": "…" } }
] }
Try it live
Edit the source below: the SVG and the map follow every keystroke. Nothing leaves your browser — the drawing is compiled and georeferenced on the page by the same engine as the CLI, through the npm package’s geo build (a 665 KB WebAssembly module, fetched only once you scroll here or click into the editor). Pick another example, switch the projection frame, or break the source to see the diagnostics.
Or let two known points fix everything
Name two places and say where they are: scale and bearing follow from how they sit on the canvas versus on the Earth (three or more points give a least-squares fit with the residual reported).
Geodesic geometry
Straight segments are densified in the plane before being carried to the ellipsoid, so a long line follows the geodesic and a circle is a true circle in metres — not in degrees.
From Python
import rpic
fc = rpic.geo.to_geojson(src) # dict: a FeatureCollection
out = rpic.geo.compile(src, frame="mercator") # {"geojson", "warnings", "registration"}
gdf = rpic.geo.to_geodataframe(src) # geopandas, EPSG:4326 — pip install "rpiclang[geo]"
# name features the source may refer to without defining them:
fc = rpic.geo.to_geojson(
'geo_lon = -34.8711\ngeo_lat = -8.0631\ngeo_scale = 1000\narrow from Recife to Olinda',
features={"Recife": (-34.8711, -8.0631), "Olinda": (-34.8553, -8.0089)},
)
features also takes a GeoDataFrame indexed by name (centroid as the point,
bounds as the bbox, so Name.n, Name.e … follow its extent). Warnings are
raised as rpic.geo.GeoWarning and returned structured; errors are
rpic.geo.GeoError with exc.info["kind"] (no_registration,
invalid_anchor, …).
Reproducibility is at the millimetre, not the byte: the platform’s sin/cos
differ in their last bits between operating systems, and a control-point fit
can carry that into the ninth decimal of a coordinate. The repository’s own
example guard compares within 1e-8°.
Use it on your own map
The maps on this page are not styled by hand: the engine emits the MapLibre
style-spec layers that draw a collection — fills, solid and dashed strokes,
dots, labels and shape titles, every size true to the ground from the
collection’s registration — and the site just adds them. Any MapLibre map can
do the same. The layers read one GeoJSON source named pic:
import maplibregl from 'maplibre-gl';
import { ready, compileGeoJSON } from '@strategicprojects/rpic';
import { attach } from '@strategicprojects/rpic/maplibre';
await ready(undefined, { geo: true });
// textScale: every label 1.5× its ground-true size (default 1)
const { geojson, layers } = compileGeoJSON(src, { layers: { textScale: 1.5 } });
const map = new maplibregl.Map({ container: 'map', style: 'https://tiles.openfreemap.org/styles/positron' });
// source "pic" + six layers, once loaded, under the basemap's labels
const pic = attach(map, geojson, { layers, fit: true, before: 'labels' });
// on every edit: pic.setGeoJSON(next.geojson, next.layers); pic.fitTo();
layers: true gives the ground-true sizes; layers: { textScale } multiplies
every label’s font size (up to 16×) and still keeps the largest one under
MapLibre’s 255 px symbol limit. before is where the layers go on your
map: a layer id, or 'labels' for the start of the style’s trailing block of
symbol layers (the first layer after its last road, building or other
geometry layer), so city and street names stay on top of a filled shape and
roads and buildings below it — as on this page. Only
the shapes go there; the drawing’s own labels always stay on top.
Labels keep their face. "Marco Zero" bold and "Porto do Recife" italic
travel as geopic:font_weight and geopic:font_style, and the layers’
text-font picks a Bold or Italic stack for them; attach takes those faces
from your style’s own symbol layers (its default, font: 'style'), so the
glyphs are ones your basemap already serves — a style with no bold face draws
the label regular. mono and font "…" are carried as geopic:font_family
but drawn in the regular family: basemap glyph servers rarely have more.
@strategicprojects/rpic/maplibre has no imports at all — no wasm, no
maplibre-gl dependency — so it costs a few kilobytes on a page that already
has MapLibre. createGeoMap(maplibregl, container, { style, cooperativeGestures, navigation, before }) builds a ready map like the ones above. With a collection from
elsewhere (the CLI, Python), attach(map, fc) without layers computes the
same ones in JS. On the command line, rpic --geojson --maplibre map.pic
prints { "geojson": …, "layers": […] } (--text-scale 1.5 for larger
labels); in Python, rpic.geo.maplibre_layers(fc, text_scale=1.5) or
rpic.geo.compile(src, layers=True, text_scale=1.5).
In R, rpic-r’s rpic_geojson(), rpic_sf() and rpic_mapgl() put the same
layers on a mapgl map. The before and
text_scale arguments arrive with the next rpic-r release:
library(mapgl)
maplibre(style = carto_style("positron")) |>
rpic_mapgl(src, before = "labels", text_scale = 1.5) # next rpic-r release
The sizing formulas and the layer table are in docs/geopic.md § 6.
Frames, caps and the contract
geo_frame = 0(default) isenu: a local tangent plane at the anchor, geodesics by Karney’s algorithms (geographiclib-rs).geo_frame = 1ismercator: a similarity in EPSG:3857 metres, so straight lines stay straight on a web map.- Assign
geo_*(and<Label>_lon/_lat) at the top level: as in dpic, a=inside[ … ]is local to the block, so[ geo_lon = … ]givesno_registration;:=onto an existing top-level variable propagates. geo_px = 1reads lengths as pixels at aview_scale(px per inch); the scene’srescale(.PS <width>) is folded in automatically.- Hostile input cannot amplify the output: 100 000 vertices per segment,
2 000 000 per scene (warning
densification_budget), effective scale ≤ 10⁹ m/in. - Everything the GeoJSON cannot represent — gradients, typeset math, animation timelines — raises a structured warning, never silence.
The full contract (registration rules, kind table, property vocabulary, JSON
Schema, warnings, versioning) is
docs/geopic.md;
the crate is geopic-core and the
engine does not depend on it.