RPIC

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
Marco Zero Recife
examples/geo/callout.pic — the same source, rendered as SVG.
… and on the map, exactly as drawn: the dot on Marco Zero, the box 520 m × 200 m north-east of it, the arrow from its south-west corner. Click a shape for its id.
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.

Open in Studio
The engine loads when you scroll here or click into the editor.
Marco Zero Recife
loading engine…

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).

Recife Olinda 6.3 km
examples/geo/arrow-between-features.pic — Recife_lon/_lat and Olinda_lon/_lat are control points.
The arrow is a 62-vertex geodesic of 6.3 km between the two control points; labels are symbol layers from geopic:text.

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.

2 km
examples/geo/radius.pic — a 2 km radius.
Every vertex of the polygon is 2 000 m from the centre along the ellipsoid; the dashed stroke comes from geopic:dash.
shed tank A B
examples/geo/two-control-points.pic — a site plan drawn in metres, registered by two surveyed corners.
The plan lands on the map rotated to true north on its own: scale and bearing come out of the two-point fit.

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, …).

Note

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.

Marco Zero Porto do Recife Bairro do Recife ilha, centro histórico 200 m
examples/geo/label-faces.pic — a bold place name, the water in italics, a bold box title.
The same faces on the map, in the basemap's own Noto Sans Bold and Italic.

@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

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.