drawland 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/library.d.ts ADDED
@@ -0,0 +1,1536 @@
1
+ // Generated by make-types.mjs from drawland.d.ts: do not edit.
2
+ // The draw.land library: everything a profile script can call.
3
+ //
4
+ // This file is the library's description. The web editor checks scripts
5
+ // against it (autocomplete, argument docs, and lines passed where an area
6
+ // goes are underlined); `docs/library.md` is written from it; the crate's
7
+ // tests keep it in step with `library.js`, with penfill's patterns and with
8
+ // terramask's presets.
9
+
10
+ /** Features picked from the map data: they are not drawn, areas and lines are made from them. */
11
+ declare class Features {
12
+ private readonly __features: never
13
+ }
14
+ /** Polygons in output millimetres: what fills go in, masks hide with, and rings outline. */
15
+ declare class Area {
16
+ private readonly __area: never
17
+ }
18
+ /** Lines in output millimetres: what `draw` puts on paper. */
19
+ declare class Lines {
20
+ private readonly __lines: never
21
+ }
22
+
23
+ /** A length: a number of millimetres, or a string with a unit (`"0.5mm"`, `"6in"`, `"2cm"`). */
24
+ type Length = number | `${number}mm` | `${number}cm` | `${number}in` | `${number}m`
25
+
26
+ /** One value or several, or `true` for any value and `false` for none. */
27
+ type TagValue = string | string[] | boolean
28
+
29
+ /** OSM tags, any of which selects a feature: `{ building: true }`, `{ leisure: ["park", "garden"] }`. */
30
+ interface Tags {
31
+ [tag: string]: TagValue | Record<string, TagValue> | undefined
32
+ /** Tags that drop a feature even when another tag selected it. */
33
+ except?: Record<string, TagValue>
34
+ /** Keep features below ground (tunnels, `layer < 0`); dropped by default. */
35
+ underground?: boolean
36
+ }
37
+
38
+ /** A terramask preset, or a rule `layer:class,class` on the OpenMapTiles layers (`landcover:park,garden`). */
39
+ type TilePreset =
40
+ | "water" | "ocean" | "lakes" | "rivers" | "land" | "forest" | "glacier" | "wetland" | "sand" | "rock"
41
+ | "grass" | "farmland" | "parks" | "urban" | "buildings" | "roads" | "paths" | "road_names" | "rail"
42
+ | `${string}:${string}`
43
+
44
+ /** What every fill takes, whatever its pattern. */
45
+ interface FillBase {
46
+ /** The area to fill. */
47
+ in: Area
48
+ /** `"feature"`: one pattern per polygon (each building hatched on its own) instead of one over the union. */
49
+ per?: "feature"
50
+ /**
51
+ * Distance between neighbouring elements, centre to centre: the pitch of
52
+ * lines, of marks, the size of cells. Every pattern has its own default;
53
+ * giving one to a material scales the whole recipe.
54
+ */
55
+ spacing?: Length
56
+ /** Degrees: the pattern turned on the page. A material turns all its layers together. */
57
+ angle?: number
58
+ /** For the patterns with randomness: the same seed draws the same lines. */
59
+ seed?: number
60
+ /** Shrink the area first. */
61
+ inset?: Length
62
+ /** How the pattern meets the edge: `clip` cuts at the border, `inside` keeps every mark whole inside it, `overflow` lets it bulge past. Default `clip`. */
63
+ edge?: "clip" | "inside" | "overflow"
64
+ /** With `edge: "overflow"`: how far past the border. Default 0.4 × spacing. */
65
+ overflow?: Length
66
+ /** A fading edge this wide: lines break into shorter pieces and marks thin out before the border. */
67
+ fray?: Length
68
+ /** `"global"` (default): one lattice for the whole page, so neighbouring areas meet without a seam and a moved card keeps its marks. `"local"`: each shape on its own. */
69
+ anchor?: "global" | "local"
70
+ /** Move the lattice, across and down. */
71
+ shift?: [Length, Length]
72
+ /** Screen-style flat colour under the hatch (SVG fill, not pen ink). */
73
+ background?: string
74
+ }
75
+
76
+ /**
77
+ * A fill: a pattern and its options (`pattern: "gravel"`, or a generator
78
+ * such as `pattern: "scatter"` with every option open), lines made
79
+ * elsewhere (`content`), or an SVG (`source`).
80
+ */
81
+ type FillOptions = FillBase &
82
+ (
83
+ | PatternOptions
84
+ | { pattern?: undefined; content: Lines }
85
+ | { pattern?: undefined; source: { file: string; size?: string; position?: string; repeat?: string } }
86
+ | { pattern: "none" }
87
+ )
88
+
89
+ /** A fill's options without its area: what a style keeps in a constant, `/** @type {FillStyle} *\/`. */
90
+ type FillStyle = FillOptions extends infer F ? (F extends unknown ? Omit<F, "in"> : never) : never
91
+
92
+ // ── catalog:begin (generated by `cargo run -p drawland-script --example write_dts`; do not edit) ──
93
+
94
+ /** A pattern: a material (a named recipe, chosen by what it is for) or a generator (the algorithm, every option open). */
95
+ type Pattern = Material | Generator | "none"
96
+
97
+ /** The materials, group by group. Each is a recipe over one or more generators; `spacing` scales the whole recipe. */
98
+ type Material =
99
+ // Water: Seas, lakes, rivers and wet ground.
100
+ | "waves" | "scallops" | "curls" | "currents" | "wave-net" | "swells" | "eddies" | "ripples" | "shore-lines" | "shallows" | "marsh"
101
+ // Vegetation: Grass, woods, crops and gardens, in the symbols maps use for them.
102
+ | "grass" | "meadow" | "scrub" | "woodland" | "forest" | "conifers" | "orchard" | "vineyard" | "fields" | "garden" | "sprouts" | "leaves" | "isoline-stack" | "canopy" | "doodle-trees" | "twigs" | "growth"
103
+ // Ground and soil: Sand, soil, gravel and bare earth.
104
+ | "sand" | "dunes" | "soil" | "gravel" | "pebbles" | "boulders" | "scree" | "cracked-earth" | "dry-mud" | "clay" | "silt" | "peat" | "layered-soil" | "chalky-soil"
105
+ // Rock: Rock in the conventions of geological maps: the symbols a geologist reads at a glance.
106
+ | "sandstone" | "siltstone" | "shale" | "limestone" | "chalk" | "conglomerate" | "breccia" | "coal" | "granite" | "basalt" | "tuff" | "gneiss" | "schist" | "salt" | "marble"
107
+ // Built: Paving, brickwork, tiles and the textures of built surfaces.
108
+ | "brick" | "herringbone" | "basket" | "parquet" | "setts" | "flagstones" | "tiles" | "hexagons" | "stairs" | "grate" | "chess" | "cobbles" | "terrazzo" | "cemetery" | "wood"
109
+ // Sky: Clouds seen from above, and their shadows.
110
+ | "clouds"
111
+ // Plain hatches: Lines, grids, dots and rings: abstract hatches for anything.
112
+ | "lines" | "crosshatch" | "triad" | "serpentine" | "dashes" | "dots" | "stipple" | "concentric" | "offsets" | "spiral" | "scribble" | "hilbert" | "truchet" | "honeycomb" | "scales" | "sunburst" | "isoline-blobs" | "solid"
113
+
114
+ /** The generators: the algorithms under every material. */
115
+ type Generator = "hatch" | "scatter" | "cells" | "tile" | "waves" | "rings" | "scribble" | "hilbert" | "truchet" | "honeycomb" | "scales" | "sunburst" | "wood" | "marble" | "swells" | "eddies" | "ripples" | "canopy" | "twigs" | "doodle-trees" | "growth" | "isoline-stack" | "isoline-blobs" | "clouds" | "solid"
116
+
117
+ /** A symbol `scatter` can place by name. */
118
+ type Mark = "dot" | "tick" | "dash" | "plus" | "cross" | "ring" | "ring-dot" | "pebble" | "blob" | "shard" | "rock" | "tee" | "vee" | "bracket" | "tuft" | "reed" | "tree" | "conifer" | "shrub" | "sprout" | "leaf" | "vine" | "flower" | "grave"
119
+
120
+ /** Polylines in mm around the origin, for your own motif: one `[[x, y], …]` or several. */
121
+ type Polylines = [number, number][] | [number, number][][]
122
+
123
+ /** `hatch`: Parallel lines; crossed into a grid or a triad, joined into serpentines, dashed, bent, unevenly spaced, or thinned by tone. */
124
+ interface HatchOptions {
125
+ /** Families of lines: 1 parallel lines, 2 a grid (crossing at right angles), 3 a triad (at 60°). Default 1. */
126
+ cross?: 1 | 2 | 3
127
+ /** Join the lines end to end into serpentines, so the pen lifts as little as possible (one family, no dashes). Default false. */
128
+ join?: boolean
129
+ /** Break the lines into dashes: `[on, off]` in mm. */
130
+ dash?: Length | [Length, Length]
131
+ /** How much dash and gap lengths differ, and how far each row's dashes are offset, 0 to 1. Default 0. */
132
+ dash_jitter?: number
133
+ /** How far the lines bend away from straight, in mm. Neighbouring lines bend together, like bedding. Default 0. */
134
+ wobble?: Length
135
+ /** The length of one bend along the lines, in mm. Default 14 × spacing. */
136
+ wobble_length?: Length
137
+ /** How uneven the gaps between lines are, 0 (even) to 1: layered soil, worn bedding. Default 0. */
138
+ vary?: number
139
+ /** The tone across the area: even, denser toward the edge, toward the centre, in noisy patches, or along a gradient toward `toward` degrees. Default `"even"`. */
140
+ density?: "even" | "edge" | "centre" | "noise" | "gradient"
141
+ /** How far the tone swings, 0 (none) to 1 (from full to nothing). Default 0.8. */
142
+ contrast?: number
143
+ /** The scale of the tone: the width of the edge band, the size of noise patches, in mm. Default 8 × spacing. */
144
+ feature?: Length
145
+ /** With `density: "gradient"`: the direction the tone gets denser, in page degrees (90: down the page). Default 90. */
146
+ toward?: number
147
+ }
148
+
149
+ /** `scatter`: One mark at each of many places: dots, strokes, stones, plants or a symbol of your own, evenly scattered, on a lattice, in rows or in clusters, thinned by tone. */
150
+ interface ScatterOptions {
151
+ /** Where the marks go: blue (even but irregular, like a stipple by hand), hex or square (a lattice; add jitter to loosen it), rows (along the angle, wandering only along their row: an orchard, a vineyard), clusters (small groups). Default `"blue"`. */
152
+ arrange?: "blue" | "hex" | "square" | "rows" | "clusters"
153
+ /** The mark: a symbol by name, or your own polylines in mm around the origin (up is negative y), drawn at their own size. Default `"dot"`. */
154
+ motif?: Mark | Lines | Polylines
155
+ /** The size of one element: a dot's length, a symbol's height, in mm. Default 0.35 × spacing. */
156
+ mark?: Length
157
+ /** How marks turn: random (every mark its own way), aligned (with the pattern's angle), upright (standing up on the page whatever the angle: trees, reeds, crosses), or a number of degrees added to the pattern's angle. Default `"random"`. */
158
+ rotate?: number | "random" | "aligned" | "upright"
159
+ /** How much element sizes differ, 0 (all alike) to 1. Default 0. */
160
+ vary?: number
161
+ /** How far elements wander from their place, 0 to 1. Default 0. */
162
+ jitter?: number
163
+ /** Let marks overlap their neighbours. Off, a mark that would touch a neighbour gives way to it, as an engraver leaves symbols apart. Default false. */
164
+ overlap?: boolean
165
+ /** The tone across the area: even, denser toward the edge, toward the centre, in noisy patches, or along a gradient toward `toward` degrees. Default `"even"`. */
166
+ density?: "even" | "edge" | "centre" | "noise" | "gradient"
167
+ /** How far the tone swings, 0 (none) to 1 (from full to nothing). Default 0.8. */
168
+ contrast?: number
169
+ /** The scale of the tone: the width of the edge band, the size of noise patches, in mm. Default 8 × spacing. */
170
+ feature?: Length
171
+ /** With `density: "gradient"`: the direction the tone gets denser, in page degrees (90: down the page). Default 90. */
172
+ toward?: number
173
+ }
174
+
175
+ /** `cells`: Irregular cells: rounded stones apart from each other, a net of shared walls, or plates with wide cracks; with marks inside, sizes from even to mixed, thinned by tone. */
176
+ interface CellsOptions {
177
+ /** `stones`: every cell its own rounded outline, apart from its neighbours (gravel, cobbles, pebble beds). `net`: the shared walls, drawn once (cell nets, mud cracks seen from above, crazing). `cracks`: angular plates with wide cracks between them (dry cracked earth). Default `"stones"`. */
178
+ style?: "stones" | "net" | "cracks"
179
+ /** The space between neighbouring cells, in mm. Unset: 0.14 × spacing for stones, 0.24 × spacing for cracks; for a net, the break left where walls meet (unset: none, the walls join). */
180
+ gap?: Length
181
+ /** How rounded the corners are, 0 (sharp) to 1 (as round as the cell allows). Unset: 0.7 for stones, 0.25 for cracks. */
182
+ round?: number
183
+ /** How much element sizes differ, 0 (all alike) to 1. Default 0. */
184
+ vary?: number
185
+ /** How far elements wander from their place, 0 to 1. Default 0. */
186
+ jitter?: number
187
+ /** A mark inside each cell: `dots` (a few specks: chalky soil), `hatch` (lines at each stone's own angle), `ring` (an inner outline: a rimmed pebble), `mixed` (terrazzo: some chips hatched, a few dense, most left plain). Default `"none"`. */
188
+ inner?: "none" | "dots" | "hatch" | "ring" | "mixed"
189
+ /** The tone across the area: even, denser toward the edge, toward the centre, in noisy patches, or along a gradient toward `toward` degrees. Default `"even"`. */
190
+ density?: "even" | "edge" | "centre" | "noise" | "gradient"
191
+ /** How far the tone swings, 0 (none) to 1 (from full to nothing). Default 0.8. */
192
+ contrast?: number
193
+ /** The scale of the tone: the width of the edge band, the size of noise patches, in mm. Default 8 × spacing. */
194
+ feature?: Length
195
+ /** With `density: "gradient"`: the direction the tone gets denser, in page degrees (90: down the page). Default 90. */
196
+ toward?: number
197
+ }
198
+
199
+ /** `tile`: A motif laid on a lattice: brick, herringbone, basket weave, parquet, setts, flagstones, tiles, hexagons, stairs, grating, chess; your own polylines; or a CAD .pat hatch. */
200
+ interface TileOptions {
201
+ /** What is laid: `brick` (running bond), `herringbone` (pavers at right angles in a zigzag), `basket` (pairs of pavers, alternating direction), `parquet` (square blocks of boards, alternating), `setts` (small stones in staggered courses), `flagstones` (random rectangular paving: course heights and stone lengths vary, joints staggered), `tiles` (square tiles with a grout joint), `hexagons` (hexagonal pavers), `stairs` (stone steps seen from above), `grate` (bar grating), `chess` (squares, alternate ones hatched); or your own polylines in mm around the origin. Default `"brick"`. */
202
+ motif?: "brick" | "herringbone" | "basket" | "parquet" | "setts" | "flagstones" | "tiles" | "hexagons" | "stairs" | "grate" | "chess" | Lines | Polylines
203
+ /** One piece, `[length, width]` in mm. Unset, at spacing s: brick [3s, s], herringbone and basket [2s, s], parquet [4s, 0.8s] (a block of five boards), setts [1.15s, s], flagstones [3s, 2s], tiles and chess [3s, 3s], hexagons 2.5s across, stairs [6s, 1.5s] (slab length, tread depth), grate [3s, 0.5s] (cross bar pitch, bar pitch). For your own polylines: the tile box, centred on the origin (unset: the lines' extent). */
204
+ size?: Length | [Length, Length]
205
+ /** For your own motif: how far each row is shifted along, as a share of the tile width (0.5: brick bond). Default 0. */
206
+ stagger?: number
207
+ /** The joint between pieces, in mm: 0 draws single joint lines, each once; more draws every piece as its own outline, this far from its neighbours. Unset: 0.18 × width for setts, 0.1 × width for tiles, 0 for the rest. */
208
+ gap?: Length
209
+ /** How far elements wander from their place, 0 to 1. Default 0. */
210
+ jitter?: number
211
+ /** A CAD hatch instead of a motif: a built-in name (ANSI31, ANSI32, ANSI33, ANSI37, BRICK, HERRINGBONE, BASKET, PARQUET, EARTH, CROSS, DASH, STAIRS, GRATE, ANGLE) or the text of a `.pat` definition. One pattern unit is `spacing` mm. */
212
+ pat?: string
213
+ }
214
+
215
+ /** `waves`: Wavy parallel lines: sine, scallops, zigzag teeth, curling crests or a flowing swell; doubled into a net with `cross: 2`. */
216
+ interface WavesOptions {
217
+ /** How the lines wave: `sine`, the smooth classic; `scallop`, shallow arcs dipping between sharp cusps; `zigzag`, sharp straight teeth (amphibolite, schist); `curl`, crests that roll over into a spiral hook; `flow`, long swells the lines bunch and spread over, broken into strokes like a printed textile. Default `"sine"`. */
218
+ shape?: "sine" | "scallop" | "zigzag" | "curl" | "flow"
219
+ /** The length of one wave along the line, in mm. Default by shape, × spacing: sine 4 (3.6 with `cross: 2`), scallop 1.35, zigzag 1, curl 1.35, flow 13. */
220
+ wavelength?: Length
221
+ /** How far a line swings away from its row, in mm: a sine's or zigzag's peak, a scallop's dip, a curl's crest, a swell's height. Default by shape, × spacing: sine 0.25 (0.5 with `cross: 2`, so the net closes), scallop 0.35, zigzag 0.3, curl 0.27, flow 2.6. */
222
+ amplitude?: Length
223
+ /** 1 one family of lines; 2 a net. Sine, zigzag and scallop add every row's mirror image, so crest meets trough and the lines close into cells (the ogee net, diamonds, eyes); curl and flow add a second family at right angles. Default 1. */
224
+ cross?: 1 | 2
225
+ /** Sine, scallop, zigzag and curl: shift every other row along by this share of a wavelength (0.5 sets the cusps of one row over the middles of the next). Default 0. */
226
+ stagger?: number
227
+ /** Turn the waves over: curls break the other way, scallops bulge up between downward cusps. Default false. */
228
+ flip?: boolean
229
+ /** Scallop: the arc's shape, below 1 fuller and rounder, above 1 drawn to a point. Default 0.8. */
230
+ round?: number
231
+ /** Curl: the size of the hook as a share of the amplitude. 1 rolls down onto the next wave's trough; smaller hooks hang above it. Default 1. */
232
+ curl?: number
233
+ /** Curl: how far each hook winds in, in turns (1 is one full turn). Default 0.95. */
234
+ turns?: number
235
+ /** Flow: how fast the swell's height and phase change from line to line across the sea (0 keeps one swell everywhere). Default 1. */
236
+ drift?: number
237
+ /** Flow: how broken the lines are, 0 (unbroken) to 1 (short strokes). Default 0.5. */
238
+ breaks?: number
239
+ }
240
+
241
+ /** `rings`: Rings from the boundary inward, a spacing apart: concentric with the outline, offset from every edge, or one continuous spiral. */
242
+ interface RingsOptions {
243
+ /** What the rings follow: `outline`, the outer edge inset again and again (holes stop the rings; thin parts get a centreline); `edges`, every edge, holes included, each pushing rings of its own (a network of streets round blocks fills evenly). Default `"outline"`. */
244
+ from?: "outline" | "edges"
245
+ /** One continuous path winding inward a spacing per lap, instead of closed rings: the fewest pen lifts. Follows the outline; holes cut it. Default false. */
246
+ spiral?: boolean
247
+ }
248
+
249
+ /** `scribble`: Hand shading with a fine pen: loose zigzag strokes with rounded turns, in overlapping patches, layered at different angles. */
250
+ interface ScribbleOptions {
251
+ /** Layers of scribble, each turned about 50° from the first: 1 a light shade, 3 the darkest. Default 2. */
252
+ layers?: 1 | 2 | 3
253
+ /** How messy, 0 (tidy, even zigzags) to 1 (wandering ends, uneven passes, tilted patches). Default 0.5. */
254
+ loose?: number
255
+ /** The length of one pass of the pen, end to end, in mm. Default 9 × spacing. */
256
+ length?: Length
257
+ /** The tone across the area: even, denser toward the edge, toward the centre, in noisy patches, or along a gradient toward `toward` degrees. Default `"even"`. */
258
+ density?: "even" | "edge" | "centre" | "noise" | "gradient"
259
+ /** How far the tone swings, 0 (none) to 1 (from full to nothing). Default 0.8. */
260
+ contrast?: number
261
+ /** The scale of the tone: the width of the edge band, the size of noise patches, in mm. Default 8 × spacing. */
262
+ feature?: Length
263
+ /** With `density: "gradient"`: the direction the tone gets denser, in page degrees (90: down the page). Default 90. */
264
+ toward?: number
265
+ }
266
+
267
+ /** `hilbert`: One unbroken space-filling Hilbert curve visiting the whole area cell by cell; cells between half a spacing and a spacing. */
268
+ interface HilbertOptions {
269
+ }
270
+
271
+ /** `truchet`: Truchet tiles: square cells a spacing wide, each with two quarter arcs turned at random, chaining into long winding paths. */
272
+ interface TruchetOptions {
273
+ }
274
+
275
+ /** `honeycomb`: Hexagonal cells a spacing across (flat to flat), each wall drawn once, or doubled `walls` apart. */
276
+ interface HoneycombOptions {
277
+ /** Draw every wall twice, this far apart, in mm (0: single walls, the hexagons touching). Default 0. */
278
+ walls?: Length
279
+ }
280
+
281
+ /** `scales`: Fish scales: rows of half circles a spacing apart, each row resting on the tips of the one below; roof tiles and drawn water. */
282
+ interface ScalesOptions {
283
+ }
284
+
285
+ /** `sunburst`: Rays from a centre, about a spacing apart at every radius: new rays join in rings where the gaps open, so the centre never crowds. */
286
+ interface SunburstOptions {
287
+ /** Where the rays come from, `[x, y]` in page mm. Default: the middle of the shape. Give the same centre to neighbouring areas and they share one burst. */
288
+ centre?: Length | [Length, Length]
289
+ }
290
+
291
+ /** `wood`: Wood grain: long lines a spacing apart running along the angle, wandering slowly and flowing round knots. */
292
+ interface WoodOptions {
293
+ /** How many knots the grain flows round, on average per square of 30 spacings (0: straight grain). Default 1. */
294
+ knots?: number
295
+ }
296
+
297
+ /** `marble`: Marble: veins about a spacing apart drifting across the slab at the angle, warped by turbulence, each drawn as its two edges so it pinches and swells. */
298
+ interface MarbleOptions {
299
+ }
300
+
301
+ /** `swells`: Overlapping swells or dunes: crest lines layered back to front, each hiding the ones behind and filled with lines that follow its slope. */
302
+ interface SwellsOptions {
303
+ }
304
+
305
+ /** `eddies`: Currents: evenly spaced streamlines of a flow that undulates and winds into spiral eddies. */
306
+ interface EddiesOptions {
307
+ }
308
+
309
+ /** `ripples`: Ripples: rows of broken wavy strokes a spacing apart, their crests bending together over a slow swell. */
310
+ interface RipplesOptions {
311
+ }
312
+
313
+ /** `canopy`: Tree canopies from above: clusters of wobbly lobes, a dot at each lobe's heart, trees a spacing apart. */
314
+ interface CanopyOptions {
315
+ }
316
+
317
+ /** `twigs`: Scattered twigs a spacing apart: a kinked stick with short side shoots at acute angles; brushwood, scrub, forest litter. */
318
+ interface TwigsOptions {
319
+ }
320
+
321
+ /** `doodle-trees`: Trees as a hand doodles them on a sketch map: each crown (a spacing across) one curly stroke round a lumpy circle, with a crescent of shade; nearer crowns hide those behind. */
322
+ interface DoodleTreesOptions {
323
+ /** The share of places that get a tree, 0 to 1: lower leaves clearings. Default 0.85. */
324
+ coverage?: number
325
+ /** How many curls run round each crown's rim, as a multiple of the usual count. Default 1. */
326
+ loops?: number
327
+ /** The share of crowns with a crescent of shade on the side away from the light. Default 0.8. */
328
+ shadow?: number
329
+ /** Where the light comes from, in page degrees (0: from the right, 90: from below; 225, the map maker's top left). Default 225. */
330
+ light_angle?: number
331
+ }
332
+
333
+ /** `growth`: Branches grown toward the space they have to fill (space colonisation): river deltas, veins, roots, cracks, lichen; twigs a spacing apart. */
334
+ interface GrowthOptions {
335
+ /** How many roots the branches grow from (0: one per `root_spacing`). Default 0. */
336
+ roots?: number
337
+ /** Roots about this far apart, each draining its own basin, in mm. Default 12 × spacing. */
338
+ root_spacing?: Length
339
+ /** How far a branch advances per step, in mm. Default 0.16 × spacing. */
340
+ step?: Length
341
+ /** A point farther than this from every branch tip pulls nothing, in mm. Default 3.2 × spacing. */
342
+ reach?: Length
343
+ /** A point this close to a tip is reached and stops pulling, in mm. Default 0.4 × spacing. */
344
+ kill?: Length
345
+ /** How much each step wobbles off its course, 0 (straight) up. Default 0.1. */
346
+ jitter?: number
347
+ /** The pen's width in mm: a trunk's extra passes sit this far apart, side by side (0 draws every branch as one line). Default 0.15. */
348
+ pen?: Length
349
+ /** Most extra passes either side of a trunk: thick near the roots, a hairline at the twigs. Default 3. */
350
+ trunk?: number
351
+ /** How far each tree reaches toward its neighbours, 0 to 1: below 1 leaves gaps between them. Default 1. */
352
+ coverage?: number
353
+ /** How much trees differ in size, 0 (alike) to 1 (saplings beside big crowns). Default 0.35. */
354
+ variation?: number
355
+ /** A cap on growth steps, so a pathological shape cannot hang. Default 20000. */
356
+ max_steps?: number
357
+ }
358
+
359
+ /** `isoline-stack`: Tree crowns drawn as stacked contour tiers, lit from one side; `spacing` is a crown's diameter, and the crowns are the mask. */
360
+ interface IsolineStackOptions {
361
+ /** Shade the crowns with hatching on the side away from the light, for an engraved look. Changes the defaults: `light` 0.85, `hatch` 0.45 mm, `ticks` 0.65. Default false. */
362
+ hatched?: boolean
363
+ /** How patchy the crowns are, 0 to 1: low leaves clearings, 1 fills everywhere the shape allows. Default 0.6. */
364
+ coverage?: number
365
+ /** The size of a leaf cluster on a crown's rim, in mm: smaller is lumpier. Default 0.15 × spacing. */
366
+ bubble?: Length
367
+ /** Contour tiers through a crown: more draws more rings. Default 9. */
368
+ slices?: number
369
+ /** How ragged the contours are: 0 smooth boughs, 1.1 crisp leaves, 1.5 and up deep serrations. Default 1.1. */
370
+ jitter?: number
371
+ /** The length of the contours' serration: lower is finer teeth, higher broad reaches. Default 0.68. */
372
+ jitter_period?: number
373
+ /** Short slope ticks across the contours at bough clefts and in shade, 0 (none) to 1.5. Default 0.42; 0.65 when `hatched` or with a `hatch`. */
374
+ ticks?: number
375
+ /** How drawn out the crowns are, as if wind-swept, 0 (round) to 1. Default 0.18. */
376
+ elongation?: number
377
+ /** How deep the clefts between boughs are, and how much a crown splits into sub-crowns. Default 1. */
378
+ lobes?: number
379
+ /** How strong the sunlight is, 0 (none: every side alike) to 1: lit sides open up, shaded sides close in. Default 0.82; 0.85 when `hatched`. */
380
+ light?: number
381
+ /** Where the light comes from, in page degrees (0: from the right, 90: from below; 225, the map maker's top left). Default 225. */
382
+ light_angle?: number
383
+ /** How high the sun stands, in degrees: lower casts longer shade. Default 35. */
384
+ light_elevation?: number
385
+ /** The shading hatch's spacing in mm, 0 for none. Default 0; 0.45 when `hatched`. */
386
+ hatch?: Length
387
+ }
388
+
389
+ /** `isoline-blobs`: Blobs a spacing apart, each filled with nested contour rings like a height map; the blobs are the mask. */
390
+ interface IsolineBlobsOptions {
391
+ /** The distance between nested contour lines inside a blob, in mm. Default 0.045 × spacing. */
392
+ contour?: Length
393
+ /** How much the field curls and drifts, 0 (round blobs) up. Default 0.45. */
394
+ warp?: number
395
+ /** The size of the warp's waves: lower is finer, higher broader. Default 1. */
396
+ warp_period?: number
397
+ /** Where ink begins on the field: higher keeps only the tallest blobs, lower fuses them into larger masses. Default 0.15. */
398
+ threshold?: number
399
+ }
400
+
401
+ /** `clouds`: Cumulus seen from above: puffs a spacing across heaped on bodies that rise and fall, shaded away from the sun; the clouds are the mask. */
402
+ interface CloudsOptions {
403
+ /** The size of the cloud masses and the clear sky between them, in mm. Default 8 × spacing. */
404
+ cell?: Length
405
+ /** The share of the sky that is cloud. Default 0.5. */
406
+ coverage?: number
407
+ /** How much the masses curl and drift, 0 (plain blobs) to 1. Default 0.25. */
408
+ warp?: number
409
+ /** How closely the puffs crowd: about 0.6 few and round, 2 many and lumpy. Default 1. */
410
+ puffs?: number
411
+ /** How drawn out each puff is along the run of its cloud, 0 (round) to 1. Default 0.35. */
412
+ elongate?: number
413
+ /** How far the masses are drawn out along the wind (toward cloud streets). Default 0.25. */
414
+ stretch?: number
415
+ /** The wind's direction on the page, in degrees (0: left to right). Default 15. */
416
+ wind?: number
417
+ /** Where the sun is, in page degrees (0: from the right, 90: from below; 225, the top left). Default 225. */
418
+ light_angle?: number
419
+ /** How high the sun stands, in degrees: lower shades more of each heap. Default 30. */
420
+ light_elevation?: number
421
+ /** How tall the clouds heap up against their width: 1 a cumulus, 0.3 a flat sheet. Default 1. */
422
+ height?: number
423
+ /** How much of the cloud is shaded, 0 (none) to 1. Default 0.45. */
424
+ shade?: number
425
+ /** The shade's spacing at its deepest, between dots or lines, in mm. Default 0.45. */
426
+ hatch?: Length
427
+ /** Shade in stippled `dots` (denser where deeper) or hatched `lines`. Default `"dots"`. */
428
+ shading?: "dots" | "lines"
429
+ /** Each shading dot's length, in mm (a pen's dot is a short stroke). Default 0.12. */
430
+ dot?: Length
431
+ }
432
+
433
+ /** `solid`: A flat fill with no pen strokes: the host paints the area (an SVG fill, a screen preview); plotters draw nothing. Its mask is the whole area. */
434
+ interface SolidOptions {
435
+ }
436
+
437
+ /** Each pattern with the options it takes. */
438
+ type PatternOptions =
439
+ | ({ pattern: "scallops" } & WavesOptions)
440
+ | ({ pattern: "curls" } & WavesOptions)
441
+ | ({ pattern: "currents" } & WavesOptions)
442
+ | ({ pattern: "wave-net" } & WavesOptions)
443
+ | ({ pattern: "shore-lines" } & HatchOptions)
444
+ | ({ pattern: "shallows" } & ScatterOptions)
445
+ | ({ pattern: "marsh" } & ScatterOptions)
446
+ | ({ pattern: "grass" } & ScatterOptions)
447
+ | ({ pattern: "meadow" } & ScatterOptions)
448
+ | ({ pattern: "scrub" } & ScatterOptions)
449
+ | ({ pattern: "woodland" } & ScatterOptions)
450
+ | ({ pattern: "forest" } & ScatterOptions)
451
+ | ({ pattern: "conifers" } & ScatterOptions)
452
+ | ({ pattern: "orchard" } & ScatterOptions)
453
+ | ({ pattern: "vineyard" } & ScatterOptions)
454
+ | ({ pattern: "fields" } & HatchOptions)
455
+ | ({ pattern: "garden" } & ScatterOptions)
456
+ | ({ pattern: "sprouts" } & ScatterOptions)
457
+ | ({ pattern: "leaves" } & ScatterOptions)
458
+ | ({ pattern: "sand" } & ScatterOptions)
459
+ | ({ pattern: "dunes" } & ScatterOptions)
460
+ | ({ pattern: "soil" } & ScatterOptions)
461
+ | ({ pattern: "gravel" } & CellsOptions)
462
+ | ({ pattern: "pebbles" } & ScatterOptions)
463
+ | ({ pattern: "boulders" } & CellsOptions)
464
+ | ({ pattern: "scree" } & ScatterOptions)
465
+ | ({ pattern: "cracked-earth" } & CellsOptions)
466
+ | ({ pattern: "dry-mud" } & CellsOptions)
467
+ | ({ pattern: "clay" } & HatchOptions)
468
+ | ({ pattern: "silt" } & HatchOptions)
469
+ | ({ pattern: "peat" } & HatchOptions)
470
+ | ({ pattern: "layered-soil" } & HatchOptions)
471
+ | ({ pattern: "chalky-soil" } & CellsOptions)
472
+ | ({ pattern: "sandstone" } & ScatterOptions)
473
+ | ({ pattern: "siltstone" } & HatchOptions & ScatterOptions)
474
+ | ({ pattern: "shale" } & HatchOptions)
475
+ | ({ pattern: "limestone" } & TileOptions)
476
+ | ({ pattern: "chalk" } & TileOptions & ScatterOptions)
477
+ | ({ pattern: "conglomerate" } & ScatterOptions)
478
+ | ({ pattern: "breccia" } & ScatterOptions)
479
+ | ({ pattern: "coal" } & HatchOptions)
480
+ | ({ pattern: "granite" } & ScatterOptions)
481
+ | ({ pattern: "basalt" } & ScatterOptions)
482
+ | ({ pattern: "tuff" } & ScatterOptions)
483
+ | ({ pattern: "gneiss" } & HatchOptions)
484
+ | ({ pattern: "schist" } & WavesOptions)
485
+ | ({ pattern: "salt" } & HatchOptions)
486
+ | ({ pattern: "brick" } & TileOptions)
487
+ | ({ pattern: "herringbone" } & TileOptions)
488
+ | ({ pattern: "basket" } & TileOptions)
489
+ | ({ pattern: "parquet" } & TileOptions)
490
+ | ({ pattern: "setts" } & TileOptions)
491
+ | ({ pattern: "flagstones" } & TileOptions)
492
+ | ({ pattern: "tiles" } & TileOptions)
493
+ | ({ pattern: "hexagons" } & TileOptions)
494
+ | ({ pattern: "stairs" } & TileOptions)
495
+ | ({ pattern: "grate" } & TileOptions)
496
+ | ({ pattern: "chess" } & TileOptions)
497
+ | ({ pattern: "cobbles" } & CellsOptions)
498
+ | ({ pattern: "terrazzo" } & CellsOptions)
499
+ | ({ pattern: "cemetery" } & ScatterOptions)
500
+ | ({ pattern: "lines" } & HatchOptions)
501
+ | ({ pattern: "crosshatch" } & HatchOptions)
502
+ | ({ pattern: "triad" } & HatchOptions)
503
+ | ({ pattern: "serpentine" } & HatchOptions)
504
+ | ({ pattern: "dashes" } & HatchOptions)
505
+ | ({ pattern: "dots" } & ScatterOptions)
506
+ | ({ pattern: "stipple" } & ScatterOptions)
507
+ | ({ pattern: "concentric" } & RingsOptions)
508
+ | ({ pattern: "offsets" } & RingsOptions)
509
+ | ({ pattern: "spiral" } & RingsOptions)
510
+ | ({ pattern: "hatch" } & HatchOptions)
511
+ | ({ pattern: "scatter" } & ScatterOptions)
512
+ | ({ pattern: "cells" } & CellsOptions)
513
+ | ({ pattern: "tile" } & TileOptions)
514
+ | ({ pattern: "waves" } & WavesOptions)
515
+ | ({ pattern: "rings" } & RingsOptions)
516
+ | ({ pattern: "scribble" } & ScribbleOptions)
517
+ | ({ pattern: "hilbert" } & HilbertOptions)
518
+ | ({ pattern: "truchet" } & TruchetOptions)
519
+ | ({ pattern: "honeycomb" } & HoneycombOptions)
520
+ | ({ pattern: "scales" } & ScalesOptions)
521
+ | ({ pattern: "sunburst" } & SunburstOptions)
522
+ | ({ pattern: "wood" } & WoodOptions)
523
+ | ({ pattern: "marble" } & MarbleOptions)
524
+ | ({ pattern: "swells" } & SwellsOptions)
525
+ | ({ pattern: "eddies" } & EddiesOptions)
526
+ | ({ pattern: "ripples" } & RipplesOptions)
527
+ | ({ pattern: "canopy" } & CanopyOptions)
528
+ | ({ pattern: "twigs" } & TwigsOptions)
529
+ | ({ pattern: "doodle-trees" } & DoodleTreesOptions)
530
+ | ({ pattern: "growth" } & GrowthOptions)
531
+ | ({ pattern: "isoline-stack" } & IsolineStackOptions)
532
+ | ({ pattern: "isoline-blobs" } & IsolineBlobsOptions)
533
+ | ({ pattern: "clouds" } & CloudsOptions)
534
+ | ({ pattern: "solid" } & SolidOptions)
535
+
536
+ // ── catalog:end ──
537
+
538
+ /** `solid`, `dash`, `dotted`, `none`, or an object: the dashes' sizes and the ink (`color`, `width` in mm, `cap`). */
539
+ type Stroke =
540
+ | "solid" | "dash" | "dotted" | "none"
541
+ | { style?: "solid" | "dash" | "dotted" | "none"; dash?: Length; gap?: Length; mark?: Length; color?: string; width?: Length; cap?: "round" | "square" | "butt"; join?: "round" | "miter" | "bevel" }
542
+
543
+ interface DrawOptions {
544
+ /** The SVG group's id; a plotter can give each group its own pen. */
545
+ id?: string
546
+ /** The lines to draw. */
547
+ from: Lines
548
+ /** How the lines are inked. Without one, as they are (fills are already lines). */
549
+ stroke?: Stroke
550
+ }
551
+
552
+ interface OutputOptions {
553
+ /** Where: looked up with Nominatim when there is no `lat`/`lng`. */
554
+ address?: string
555
+ lat?: number
556
+ lng?: number
557
+ /** The paper. Default 6in × 4in. */
558
+ width?: Length
559
+ height?: Length
560
+ /** `"1:10000"`, or the denominator. */
561
+ scale?: `1:${number}` | number
562
+ /** Degrees clockwise. */
563
+ bearing?: number
564
+ /** `"webmercator"` (the web map, north up), `"utm"` (true distances), or a PROJ string with `{lat}` and `{lng}`. */
565
+ projection?: "webmercator" | "utm" | `+proj=${string}`
566
+ /** Blank margin inside the paper's edge (and round every sheet when cut): one length, or across and down. */
567
+ padding?: Length | [Length, Length]
568
+ /**
569
+ * The output cut into sheets. `padding` is the margin round the card's
570
+ * outside edge only; `gutter` is the gap between two sheets' drawings, half
571
+ * of it on each side of every cut (none: the drawings meet at the cut).
572
+ *
573
+ * `overlap` is the opposite, for a poster printed in tiles: every sheet is
574
+ * the same size and runs this far over its neighbour, so both carry the
575
+ * same strip of drawing to line them up by. With no gutter the drawing
576
+ * runs to every cut, so at twice the printer's unprintable edge or more,
577
+ * that blank edge trimmed off one sheet and laid on the next, the drawing
578
+ * runs on with no gap.
579
+ */
580
+ slices?: { columns?: number; rows?: number; gutter?: Length | [Length, Length]; overlap?: Length | [Length, Length] }
581
+ /**
582
+ * Bend the ground before drawing, in order. `fisheye`, `twirl` and `wave`
583
+ * keep the paper's edge; a `remap` may move it (the paper clips the rest).
584
+ */
585
+ warp?: Warp | Warp[]
586
+ /**
587
+ * The vector tiles' zoom, up to 14: deeper holds every building (none below
588
+ * 13), shallower downloads fewer tiles. Unset, the deepest under the cap.
589
+ */
590
+ tileZoom?: number
591
+ }
592
+
593
+ type Warp =
594
+ | { fisheye: number }
595
+ | { twirl: number }
596
+ | { wave: { amplitude: Length; wavelength: Length } }
597
+ | Remap
598
+
599
+ /**
600
+ * Any bend of the page, or a projection of your own: `remap` takes a point
601
+ * where the projection (and the warps before it) put it, `[x, y]` in page mm,
602
+ * and returns where it goes. Inside it, `page.toWorld` reads the ground under
603
+ * the point, so `remap: (p) => myProjection(page.toWorld(p))` draws the map
604
+ * in `myProjection`. It is sampled on a `grid` of cells over the page
605
+ * (default 48; `[across, down]` for each way) and smoothly interpolated
606
+ * between. It may move the page's edge: the page's ground is drawn where the
607
+ * remap puts it, and the paper clips the rest.
608
+ */
609
+ interface Remap {
610
+ remap: (point: [number, number]) => [number, number]
611
+ grid?: number | [number, number]
612
+ }
613
+
614
+ /** What the roads module publishes. */
615
+ interface Roads {
616
+ /** Every road's surface, and the strip each trail and railway covers: a mask for what roads cover. */
617
+ readonly area: Area
618
+ /** The roads' edges. */
619
+ readonly outlines: Lines
620
+ /** The centre lines and the seams together. */
621
+ readonly details: Lines
622
+ /** Paths and tracks, as single lines. */
623
+ readonly trails: Lines
624
+ /** The centre lines of the roads, to dash. */
625
+ readonly centerlines: Lines
626
+ /** Where a bridge's edges meet the roads under it. */
627
+ readonly seams: Lines
628
+ /**
629
+ * Railways, as single lines: only when the features include them,
630
+ * `modules.roads({ from: features.tiles("roads", "rail") })`. Their track
631
+ * bed is part of `area`, so whatever `area` masks keeps clear of them.
632
+ */
633
+ readonly rails: Lines
634
+ }
635
+
636
+ /** Map data to build from. */
637
+ declare const features: {
638
+ /** OSM features with any of these tags, from Overpass. */
639
+ osm(tags: Tags): Features
640
+ /** Features from OpenFreeMap's vector tiles: presets (`"buildings"`) or rules (`"landcover:park,garden"`). No Overpass. */
641
+ tiles(...items: (TilePreset | TilePreset[])[]): Features
642
+ /**
643
+ * Every feature of a GeoJSON dataset: a URL (fetched and cached; `--refresh`
644
+ * fetches again) or a file path beside the profile. Each feature's
645
+ * `properties` become its tags, so `features.where` bands it by a number
646
+ * and `modules.labels({ keys })` names it:
647
+ *
648
+ * const quakes = features.geojson("https://earthquake.usgs.gov/…/2.5_week.geojson")
649
+ * features.where(quakes, { mag: { min: 6 } })
650
+ *
651
+ * Or a GeoJSON object written in the profile (a graticule, a route, points
652
+ * of its own). Coordinates are lon/lat (RFC 7946); a point's third
653
+ * coordinate (a quake's depth) is the tag `geom:z`. In the browser a URL
654
+ * must allow CORS, and a file is one dropped on the page (by its name).
655
+ */
656
+ geojson(source: string | { type: string; [key: string]: unknown }): Features
657
+ /**
658
+ * Points from plain JSON — a transit API, a live feed — read like a GeoJSON
659
+ * URL (cached 15 min; in the browser the URL must allow CORS). `items` is
660
+ * the dot-path to the array of items (empty or left out: the reply is the
661
+ * array); `lat` and `lng` the dot-paths to each item's position. Every
662
+ * other field becomes a tag under its dotted path:
663
+ *
664
+ * const vehicles = features.json("https://api-v3.mbta.com/vehicles",
665
+ * { items: "data", lat: "attributes.latitude", lng: "attributes.longitude" })
666
+ * features.where(vehicles, { "relationships.route.data.id": "Red" })
667
+ */
668
+ json(url: string, paths: { items?: string; lat: string; lng: string }): Features
669
+ /**
670
+ * Contour lines from the elevation, every `step` metres, as features whose
671
+ * heights are tags — so `features.where` picks them, `ink.ramp` colours
672
+ * them and `modules.labels` writes their heights along them:
673
+ *
674
+ * const iso = features.contours({ step: 20 })
675
+ * // the index contours (every 5th) labelled along the line
676
+ * const named = modules.labels({ from: features.where(iso, { index: true }), keys: ["ele"] })
677
+ * // coloured by height on this map, low to high
678
+ * for (let i = 0; i < 8; i++) {
679
+ * const band = features.where(iso, { t: { min: i / 8, max: (i + 1) / 8 } })
680
+ * draw({ id: `iso_${i}`, from: lines.clip(lines.of(band), named.area, { invert: true }), stroke: { color: ink.ramp(["#2b6", "#a52"], i / 7) } })
681
+ * }
682
+ *
683
+ * Tags: `ele` (metres, negative under the sea), `depth` (under the sea),
684
+ * `index` (on every `index`th step), and `t`: 0 at the lowest contour on
685
+ * this map, 1 at the highest, so a ramp fits any place. Traced from the
686
+ * heights smoothed as `areas.band` smooths them, so a contour runs along
687
+ * the edge of the band that starts at its height. Reads the terrain tiles.
688
+ */
689
+ contours(options: ContoursFeatureOptions): Features
690
+ /**
691
+ * The height or depth at points `every` apart on a staggered lattice: a
692
+ * chart's soundings (`on: "sea"`, the default) or spot heights
693
+ * (`on: "land"`). Points tagged as contours are (`ele`, `depth`, `t`):
694
+ *
695
+ * const depths = features.soundings({ every: "9mm" })
696
+ * const s = modules.labels({ from: depths, keys: ["depth"], size: "1.4mm", marker: "0.25mm" })
697
+ */
698
+ soundings(options: SoundingsOptions): Features
699
+ /**
700
+ * The features whose tags pass every test: a value, a list of them, `true`
701
+ * or `false` for present or absent, or a numeric range, `min` included and
702
+ * `max` not. Ranges side by side split a set into bands, each drawn with
703
+ * its own ink:
704
+ *
705
+ * features.where(buildings, { render_height: { min: 20, max: 40 } })
706
+ *
707
+ * Tile features carry the vector tile's attributes (`render_height`,
708
+ * `class`, `rank`, `brunnel`); OSM features their tags (`building:levels`).
709
+ */
710
+ where(of: Features, tags: Record<string, TagValue | number | { min?: number; max?: number }>): Features
711
+ }
712
+
713
+ /** What `features.contours` traces. */
714
+ interface ContoursFeatureOptions {
715
+ /** Metres between contours. */
716
+ step: number
717
+ /** The lowest contour, in metres; unset, the lowest the map reaches. */
718
+ from?: number
719
+ /** The highest contour, in metres; unset, the highest the map reaches. */
720
+ to?: number
721
+ /** Every `index`th contour is tagged `index` (the ones a map labels). Default 5. */
722
+ index?: number
723
+ /** Smoothing of the heights, in elevation pixels (as `areas.band`). Default 4. */
724
+ blur?: number
725
+ /** Pieces shorter than this are dropped: specks and pits. Default `"3mm"`. */
726
+ minLength?: Length
727
+ }
728
+
729
+ /** What `features.soundings` reads. */
730
+ interface SoundingsOptions {
731
+ /** The distance between points. */
732
+ every: Length
733
+ /** Keep points on the sea (soundings), the land (spot heights) or both. Default `"sea"`. */
734
+ on?: "sea" | "land" | "all"
735
+ /** Smoothing of the heights, in elevation pixels. Default 2. */
736
+ blur?: number
737
+ /** How far each point strays from the lattice, 0 (a lattice) to 1 (half the distance between points), so they look read by hand. Fixed for a map. Default 0. */
738
+ jitter?: number
739
+ }
740
+
741
+ /** Ink worked out from data, for a stroke's `color` and `width`. */
742
+ declare const ink: {
743
+ /** The colour at `t` (0 to 1) along evenly spaced `stops`: `ink.ramp(["#fde68a", "#7c2d12"], 0.5)`. */
744
+ ramp(stops: string[], t: number): string
745
+ /** The width at `t` (0 to 1) between `thin` and `thick`: `ink.width(0.1, 0.6, 0.5)` is `"0.35mm"`. */
746
+ width(thin: number | `${number}mm`, thick: number | `${number}mm`, t: number): `${number}mm`
747
+ /** Where `v` sits between `lo` and `hi`, kept to 0 to 1: what `ramp` and `width` take. */
748
+ at(v: number, lo: number, hi: number): number
749
+ }
750
+
751
+ /** Polygons, and what can be done with them. */
752
+ declare const areas: {
753
+ /**
754
+ * A band of the elevation as an area: between two heights (`elevMin`,
755
+ * `elevMax`), or two depths below the sea (`depthMin`, `depthMax`), in
756
+ * metres; unset limits are open. The belts an atlas tints — fill it with
757
+ * `pattern: "solid"`. `blur` (px, default 4) smooths the heights before the cut — raise it (15–20) for the sea floor, whose coarse source data otherwise shows as rows of specks; `in`
758
+ * keeps it to an area.
759
+ */
760
+ band(where: TerrainWhere, options?: { in?: Area; blur?: number }): Area
761
+ /** The features' polygons, merged into one area. */
762
+ polygons(of: Features): Area
763
+ /** Everything in any of the areas. */
764
+ union(...areas: (Area | Area[])[]): Area
765
+ /** `base` without the parts in any of `cut`; with nothing to cut, `base` itself. */
766
+ difference(base: Area, ...cut: (Area | Area[])[]): Area
767
+ /** The part of `base` inside `keep`. */
768
+ intersect(base: Area, keep: Area): Area
769
+ /** The area with its holes closed (lakes inside parks, yards inside blocks). */
770
+ fillHoles(of: Area): Area
771
+ /** Grown by a length; a negative one shrinks it. */
772
+ grow(of: Area, by: Length): Area
773
+ /** The area moved across the page by `[across, down]`: a cloud's shadow cast off its footprint. */
774
+ move(of: Area, by: [Length, Length]): Area
775
+ /** A disc of radius `by` around every point feature (mapped trees), merged; lines and polygons are ignored. */
776
+ around(of: Features, by: Length): Area
777
+ /** A shape you write: `circle`, `rect`, regular polygon (`sides` + `r`), or `points` in mm from `at`. */
778
+ shape(spec: ShapeSpec): Area
779
+ /** What `lines.text(spec)` covers (for masks). */
780
+ text(spec: TextSpec): Area
781
+ /** A strip around lines, merged into one area: `by` is the half-width. Joins are round; caps round unless `cap: "flat"`. */
782
+ buffer(of: Lines, by: Length, options?: { cap?: "round" | "flat" }): Area
783
+ /**
784
+ * Close the thin gaps between `of` and the edges of `within` (vector-tile
785
+ * water that stops just short of the card border): parts of `of` within
786
+ * `gapMm` (default 1 mm) of an edge are stretched out to it, nothing else.
787
+ */
788
+ extendToFrame(of: Area, within: Area, options?: { gapMm?: Length }): Area
789
+ }
790
+
791
+ /** Areas the engine makes, not OSM. */
792
+ declare const engine: {
793
+ /**
794
+ * Open sea from `features.tiles("ocean")`, buffered and extended to the card.
795
+ * Prefer building the same chain yourself with `areas.extendToFrame`.
796
+ */
797
+ ocean(): Area
798
+ }
799
+
800
+ /** A place on the ground, in degrees. */
801
+ interface LatLng {
802
+ lat: number
803
+ lng: number
804
+ }
805
+
806
+ /**
807
+ * The paper, as this script's `output` set it: millimetres from the top left,
808
+ * x across and y down. Inside a view, the view's rectangle. Like a web page's
809
+ * `window`, it is there to lay out what goes round the map — a title, a
810
+ * scale bar, a key — for whatever paper the output is given. Call `output`
811
+ * first.
812
+ *
813
+ * draw({ from: lines.text({ at: [page.width / 2, page.height - 8], text: "BOSTON" }) })
814
+ */
815
+ declare const page: {
816
+ /** The paper's width in mm (`"6in"` is 152.4). */
817
+ readonly width: number
818
+ /** The paper's height in mm. */
819
+ readonly height: number
820
+ /** The middle of the paper, `[x, y]` in mm: where the output's centre is drawn. */
821
+ readonly center: [number, number]
822
+ /** The paper's rectangle, as an area. */
823
+ readonly frame: Area
824
+ /** The place drawn at `[x, y]` (mm), through the output's projection, bearing and warp. */
825
+ toWorld(at: [Length, Length]): LatLng
826
+ }
827
+
828
+ /**
829
+ * The ground under the page, as this script's `output` puts it (or the
830
+ * command line, when it gives a place). Inside a view, the view's place.
831
+ * Everything here follows from the output alone, never from the map's data:
832
+ * a script runs before anything is downloaded. Call `output` first.
833
+ *
834
+ * // a line and a label at every whole degree of latitude on the map
835
+ * const { south, north } = world.bounds
836
+ * for (let lat = Math.ceil(south); lat <= north; lat++) {
837
+ * const [, y] = world.toPage({ lat, lng: world.center.lng })
838
+ * draw({ id: `lat_${lat}`, from: lines.shape({ at: [0, y], points: [[0, 0], [page.width, 0]], closed: false }) })
839
+ * }
840
+ */
841
+ declare const world: {
842
+ /**
843
+ * The scale denominator (`10000` for `"1:10000"`), to size things on the
844
+ * ground: `metres * 1000 / world.scale` is millimetres on paper.
845
+ */
846
+ readonly scale: number
847
+ /** Degrees clockwise. */
848
+ readonly bearing: number
849
+ /** `"webmercator"`, `"utm"`, or the PROJ string, as the output gives it. */
850
+ readonly projection: string
851
+ /** The place at the middle of the page. Needs the output's `lat` and `lng`. */
852
+ readonly center: LatLng
853
+ /**
854
+ * The ground's extremes round the page's edge, in degrees (at any bearing,
855
+ * in any projection). Needs the output's `lat` and `lng`.
856
+ */
857
+ readonly bounds: { north: number; south: number; east: number; west: number }
858
+ /** Where the map draws `{ lat, lng }`: `[x, y]` in page mm, through the projection, bearing and warp. */
859
+ toPage(at: LatLng): [number, number]
860
+ }
861
+
862
+ /** Line sets. */
863
+ declare const lines: {
864
+ /** The outlines of an area's polygons. */
865
+ rings(of: Area, options?: {
866
+ /** Only the outer edge, not the holes. */
867
+ exteriorOnly?: boolean
868
+ }): Lines
869
+ /** The features' own lines (roads, walls drawn as lines). */
870
+ of(features: Features): Lines
871
+ /** Every edge of every polygon, and the lines: shared walls appear twice. */
872
+ segments(features: Features): Lines
873
+ /** The same segment drawn twice, once. */
874
+ dedupe(of: Lines): Lines
875
+ /** Lines that touch end to end, joined. */
876
+ merge(of: Lines): Lines
877
+ /** Several line sets as one. */
878
+ join(...sets: (Lines | Lines[])[]): Lines
879
+ /** The parts inside `within`, or outside with `invert`. */
880
+ clip(of: Lines, within: Area, options?: { invert?: boolean }): Lines
881
+ /**
882
+ * Pen-and-ink terrain in `in`, drawn by burin from the elevation under the
883
+ * output: streamlines along the slope, coloured and weighted per dash, or a
884
+ * flat fill of a height band with `draw: "fill"` and `where`. Needs the
885
+ * terrain tiles, which the host reads on its own when a script draws terrain.
886
+ */
887
+ terrain(options?: TerrainOptions): Lines
888
+ /**
889
+ * One contour belt between two heights, as a flat fill of the band:
890
+ * `lines.contours({ from: 200, to: 400 })`. Call it in a loop over heights
891
+ * to stack the belts, each drawn as its own layer.
892
+ */
893
+ contours(options?: ContoursOptions): Lines
894
+ /** Like `areas.shape`, as strokes; closed unless you pass `points` with `closed: false`. */
895
+ shape(spec: ShapeSpec & { closed?: boolean }): Lines
896
+ /** One line of text centred on `at`; same fonts as `modules.labels`. */
897
+ text(spec: TextSpec): Lines
898
+ }
899
+
900
+ /** Page mm, lengths, or `"50%"`; or `{ lat, lng }` on the ground. */
901
+ type ShapeAt = [Length | `${number}%`, Length | `${number}%`] | { lat: number; lng: number }
902
+
903
+ interface ShapeSpec {
904
+ at?: ShapeAt
905
+ circle?: Length
906
+ rect?: [Length, Length]
907
+ sides?: number
908
+ r?: Length
909
+ points?: [number, number][]
910
+ rotate?: number
911
+ }
912
+
913
+ interface TextSpec {
914
+ at?: ShapeAt
915
+ text: string
916
+ size?: Length
917
+ font?: LabelFont
918
+ rotate?: number
919
+ /**
920
+ * `areas.text` with an outline (Google) font: `"open"` keeps the letters'
921
+ * counters (the holes in A, B, O) out of the area, to fill the letters with
922
+ * a pattern; `"closed"` (default) covers them, for a mask.
923
+ */
924
+ counters?: "open" | "closed"
925
+ }
926
+
927
+ /** Burin's terrain line styles: how the streamlines are drawn, and stippled. */
928
+ type TerrainStroke = "lines" | "curls" | "waves" | "dots"
929
+
930
+ /** What `lines.terrain` draws: hatching, a fill of a band, or stippling. */
931
+ type TerrainMode = "lines" | "fill" | "dots"
932
+
933
+ /** The heights or depths a batch keeps to, in metres; unset limits are open. */
934
+ type TerrainWhere = {
935
+ /** The lowest height to draw, in metres. */
936
+ elevMin?: number
937
+ /** The highest height to draw, in metres. */
938
+ elevMax?: number
939
+ /** The deepest water to draw, in metres below the surface. */
940
+ depthMin?: number
941
+ /** The shallowest water to draw, in metres below the surface. */
942
+ depthMax?: number
943
+ }
944
+
945
+ /** What `lines.terrain` draws, and how, as burin names the parameters. */
946
+ type TerrainOptions = {
947
+ /** The area to draw in; the whole output without one. */
948
+ in?: Area
949
+ /** The field the streamlines run along, in degrees. Default 0. */
950
+ angle?: number
951
+ /** The layer name; `terrain` without one. */
952
+ layer?: string
953
+ /** Draw the shore, the zero contour. Default false. */
954
+ shore?: boolean
955
+ /** Hatching (the default), a fill of `where`, or stippling. */
956
+ draw?: TerrainMode
957
+ /** The heights or depths to keep to. A fill usually wants one. */
958
+ where?: TerrainWhere
959
+ /**
960
+ * The colour at each dash, as burin reads one: a hex string, a grey, an rgb
961
+ * triple, or a tree over the fields (`["lerp", …]`). A constant is `"#000"`.
962
+ */
963
+ color?: unknown
964
+ /**
965
+ * The line width at each dash, as a multiple of the batch's stroke: a
966
+ * number, or a tree over the fields.
967
+ */
968
+ width?: unknown
969
+ /** Style parameters, by burin's names (`line_space`, `stroke`, …). */
970
+ style?: Record<string, number>
971
+ } & Record<string, unknown>
972
+
973
+ /** What `lines.contours` draws: one belt of heights, as a fill. */
974
+ type ContoursOptions = Omit<TerrainOptions, "draw" | "where"> & {
975
+ /** The lowest height of the belt, in metres. */
976
+ from?: number
977
+ /** The highest height of the belt, in metres. */
978
+ to?: number
979
+ /** Other bands, if you need a depth instead of a height. */
980
+ where?: TerrainWhere
981
+ }
982
+
983
+ /** Patterns inside areas, by penfill. */
984
+ declare const fills: {
985
+ /** The area filled with a pattern: lines, ready to draw. */
986
+ fill(options: FillOptions): Lines
987
+ /**
988
+ * What `fill(options)` covers on paper, to mask other layers with. The area
989
+ * itself for most patterns; for `isoline-blobs` and `isoline-stack` their
990
+ * footprint (clearings left out, `edge: "overflow"` spill included). The
991
+ * same options run the pattern once for both.
992
+ */
993
+ cover(options: FillOptions): Area
994
+ }
995
+
996
+ /** Where a burin document is clipped, and the regions its batches name. */
997
+ type BurinTerrainOptions = {
998
+ /** Clip the drawing to this area (a hard edge after the mask). */
999
+ in?: Area
1000
+ /**
1001
+ * Polygons batches name in `within` / `outside`, by name — the same
1002
+ * `mask_*` easing as burin-map's engraved sea at the coast.
1003
+ */
1004
+ regions?: Record<string, Area>
1005
+ /**
1006
+ * Where the water is (sea, lakes): burin's water mask, so `burin.shore` and
1007
+ * `burin.water` follow this outline. Without it burin takes the sea from the
1008
+ * elevation (at or below 0.5 m), which detailed terrain tiles can miss.
1009
+ */
1010
+ water?: Area
1011
+ }
1012
+
1013
+ /**
1014
+ * A burin document, built by burin's own language inside this profile. The
1015
+ * callback is a real function and runs in the same interpreter, so it is
1016
+ * linted and its errors carry this script's positions. The document is burin's
1017
+ * own (`burin.batch`, `burin.water`, `burin.shore`, `burin.fill`, the trees);
1018
+ * the engine draws it later, from the elevation the host fetched.
1019
+ */
1020
+ declare const burin: {
1021
+ /**
1022
+ * Draw a burin document in the terrain: streamlines down the slope, the
1023
+ * stippled sea, contour belts, the shore — whatever the callback builds.
1024
+ *
1025
+ * const natural = burin.terrain((b) => {
1026
+ * b.batch({ angle: 90, style: { space: 3, space_dark: 0.8 } })
1027
+ * b.water("dots", { follow: "shore", style: { space: 10 } })
1028
+ * b.shore({ lines: 2 })
1029
+ * })
1030
+ * draw({ id: "land", from: natural, stroke: "solid" })
1031
+ *
1032
+ * It covers the whole output. `in` clips it to an area; to put it under
1033
+ * other layers, draw it first and mask it like any other group; to fill a
1034
+ * shape with it, `fills.fill({ in: shape, content: natural })`.
1035
+ */
1036
+ terrain(build: (burin: BurinBuilder) => void, options?: BurinTerrainOptions): Lines
1037
+ /** The same: a burin document, whatever it draws. */
1038
+ script(build: (burin: BurinBuilder) => void, options?: BurinTerrainOptions): Lines
1039
+ }
1040
+
1041
+ /** The `burin` object a burin document sees, the same one as at burin's own front ends. */
1042
+ interface BurinBuilder {
1043
+ /** A batch of hatching, stippling or a fill. */
1044
+ batch(options?: Record<string, unknown>): unknown
1045
+ /** A fill of a height or depth band: what a contour belt is. */
1046
+ fill(options?: Record<string, unknown>): unknown
1047
+ /** Lines on water: `"lines"`, `"ripples"` or `"dots"`. */
1048
+ water(kind?: "lines" | "ripples" | "dots", options?: Record<string, unknown>): unknown
1049
+ /** The shore, the zero contour. */
1050
+ shore(options?: Record<string, unknown>): unknown
1051
+ /** A colour between two others, by `t`. */
1052
+ lerp(a: unknown, b: unknown, t: unknown): unknown
1053
+ /** An rgb colour from three trees. */
1054
+ rgb(r: unknown, g: unknown, b: unknown): unknown
1055
+ /** `x` kept between `lo` and `hi`. */
1056
+ clamp(x: unknown, lo: unknown, hi: unknown): unknown
1057
+ /** A smooth step between two edges. */
1058
+ smoothstep(edge0: unknown, edge1: unknown, x: unknown): unknown
1059
+ /** 0 below `edge`, 1 above. */
1060
+ step(edge: unknown, x: unknown): unknown
1061
+ abs(x: unknown): unknown
1062
+ floor(x: unknown): unknown
1063
+ ceil(x: unknown): unknown
1064
+ round(x: unknown): unknown
1065
+ min(a: unknown, b: unknown): unknown
1066
+ max(a: unknown, b: unknown): unknown
1067
+ /** `t` as a plain fraction, for a colour. */
1068
+ mix(a: unknown, b: unknown, t: unknown): unknown
1069
+ /** The elevation at the dash. */
1070
+ elev: unknown
1071
+ /** The tone at the dash: 0 where light, 1 where dark. */
1072
+ tone: unknown
1073
+ /** The distance to the shore. */
1074
+ dist: unknown
1075
+ /** The depth below the surface. */
1076
+ depth: unknown
1077
+ }
1078
+
1079
+ /**
1080
+ * A road measurement: a bare number (interpreted via `widthMode`: metres on the
1081
+ * ground or millimetres on paper), or an explicit `{ ground: number }` (metres)
1082
+ * or `{ paper: number }` (millimetres on the sheet).
1083
+ */
1084
+ type RoadMeasure = number | { ground: number } | { paper: number }
1085
+
1086
+ /**
1087
+ * Per-class road configuration in `modules.roads({ classes })`.
1088
+ * Either a 2-sided road (`ground` / `paper` / `width`, `lanes`, `centerline`, `clearance`)
1089
+ * or a single-line path/rail (`singleLine: true`, `clearance`).
1090
+ */
1091
+ interface RoadClassObject {
1092
+ /** Base width in ground metres (per lane when `multiplyByLanes: true`). */
1093
+ ground?: number
1094
+ /** Base width in paper millimetres (per lane when `multiplyByLanes: true`). */
1095
+ paper?: number
1096
+ /** Base width in the top-level `widthMode` coordinate space. */
1097
+ width?: number
1098
+ /** Default lane count when the feature has no `lanes` tag and `inferLanesByClass: true`. */
1099
+ lanes?: number
1100
+ /** Emit a centre line on `roads.centerlines` when at least `centerlineMinWidth` wide. */
1101
+ centerline?: boolean
1102
+ /** Draw as a single line on `roads.trails` (or `roads.rails` for `rail`) instead of a 2-sided outline. */
1103
+ singleLine?: boolean
1104
+ /**
1105
+ * For `singleLine: true`: total mask corridor width in `roads.area`.
1106
+ * For 2-sided roads: extra mask margin outside the carriageway in `roads.area`.
1107
+ */
1108
+ clearance?: RoadMeasure
1109
+ }
1110
+
1111
+ type RoadClassSpec = number | RoadClassObject
1112
+
1113
+ interface RoadOptions {
1114
+ /** Road & rail features (e.g. `features.tiles("roads", "rail")`). Default: all OSM features. */
1115
+ from?: Features
1116
+ /** Coordinate space for bare numbers: `"ground"` (metres scaled by map scale, default) or `"paper"` (mm on sheet). */
1117
+ widthMode?: "ground" | "paper"
1118
+ /** Global multiplier applied to 2-sided road widths. Default: `1.0`. */
1119
+ widthMultiplier?: number
1120
+ /** Honour explicit OSM `width` / `width:lanes` tags when present. Default: `true`. */
1121
+ useWidthTag?: boolean
1122
+ /** Multiply each class's base width by the lane count. Default: `true`. */
1123
+ multiplyByLanes?: boolean
1124
+ /** When `multiplyByLanes` is `true` and the feature has no `lanes` tag, use the class's `lanes` count. Default: `true`. */
1125
+ inferLanesByClass?: boolean
1126
+ /** Minimum carriageway width required to emit `roads.centerlines`. Default: `{ ground: 7.0 }`. */
1127
+ centerlineMinWidth?: RoadMeasure
1128
+ /** Morphological close radius for smoothing road intersections (`0` disables). Default: `{ ground: 3.0 }`. */
1129
+ jointClose?: RoadMeasure
1130
+ /** Default extra mask clearance added around 2-sided roads in `roads.area`. Default: `0`. */
1131
+ clearance?: RoadMeasure
1132
+ /** Per-class road configuration keyed by class name (`"motorway"`, `"primary"`, `"residential"`, `"footway"`, `"rail"`, `"default"`, …). */
1133
+ classes?: Record<string, RoadClassSpec>
1134
+ }
1135
+
1136
+ /** Compiled recipes. */
1137
+ declare const modules: {
1138
+ /** Roads with their widths, crossings and bridges; from OSM `highway` unless given features. Call once. */
1139
+ roads(options?: RoadOptions): Roads
1140
+ /**
1141
+ * Names written on the map, in a single-stroke (Hershey) font or an outline
1142
+ * font, placed so that none covers another: along each road, bent with it
1143
+ * where it curves, and level inside areas. Larger the more the feature
1144
+ * matters (a road's class, an area's size); the most important are placed
1145
+ * first.
1146
+ */
1147
+ labels(options: LabelOptions): Labels
1148
+ /**
1149
+ * An atlas plate's graticule round the page rectangle `in` (its bounds):
1150
+ * meridians and parallels, a border of black-and-white keys, and degree
1151
+ * labels — through the output's projection, so true wherever the plate is
1152
+ * moved, at any bearing.
1153
+ *
1154
+ * const g = modules.graticule({ in: plate, step: 30, ticks: 10, band: "1.4mm", gap: "1mm", size: "1.8mm" })
1155
+ * draw({ from: g.lines, … }); draw({ from: fills.fill({ in: g.keys, pattern: "solid" }), … })
1156
+ */
1157
+ graticule(options: GraticuleOptions): Graticule
1158
+ }
1159
+
1160
+ interface GraticuleOptions {
1161
+ /** The map's rectangle on the page; the border goes just outside it. */
1162
+ in: Area
1163
+ /** Minutes of arc between lines, and between labels (30: every half degree). */
1164
+ step: number
1165
+ /** Minutes of arc per border key; leave out for no keys. */
1166
+ ticks?: number
1167
+ /** The key band's width, outside `in`. */
1168
+ band?: Length
1169
+ /** Paper between the band and the labels. */
1170
+ gap?: Length
1171
+ /** The labels' capital height. Default 1.8mm. */
1172
+ size?: Length
1173
+ font?: LabelFont
1174
+ }
1175
+
1176
+ interface Graticule {
1177
+ /** Meridians and parallels, cut to `in`. */
1178
+ readonly lines: Lines
1179
+ /** The border band's inked keys (every other `ticks` minutes). */
1180
+ readonly keys: Area
1181
+ /** Degree labels round the border (`70°30′W`), as pen strokes. */
1182
+ readonly labels: Lines
1183
+ /** What the labels cover, to fill them or clear paper round them. */
1184
+ readonly labelArea: Area
1185
+ }
1186
+
1187
+ interface LabelOptions {
1188
+ /** The named features, `features.tiles("road_names")`, or several sets placed together. */
1189
+ from: Features | Features[]
1190
+ /** Area to keep labels inside (default: the drawable sheet area after `output.padding`). */
1191
+ in?: Area
1192
+ /**
1193
+ * An area the letters keep off — the lines of a transit map, the roads
1194
+ * under a park's name. A place's point and dot may still sit on it, so a
1195
+ * station on a line gets its name beside the line, never across it.
1196
+ */
1197
+ avoid?: Area
1198
+ /** Capital height of the most important labels. Default `"2mm"`. */
1199
+ size?: Length
1200
+ /** Capital height of the least important. Default `"1.1mm"`. */
1201
+ minSize?: Length
1202
+ /** Clear space kept around every letter. Default `"0.5mm"`. */
1203
+ padding?: Length
1204
+ /** Distance between two labels of the same name. Default `"70mm"`. */
1205
+ spacing?: Length
1206
+ /** Bend text along curving roads; `false` labels straight stretches only. Default `true`. */
1207
+ curved?: boolean
1208
+ /** Write the names in capitals. */
1209
+ upper?: boolean
1210
+ /** The tags the text is read from, the first present. Default `["name", "ref"]`. */
1211
+ keys?: string | string[]
1212
+ /** Draw.land Hershey font or a Google outline font. Default `"futural"`. */
1213
+ font?: LabelFont
1214
+ /**
1215
+ * Concentric outlines around each placed name (0 = the letters' strokes only).
1216
+ * Each pass adds an outline at `bufferStep`, `2× bufferStep`, … Default `0`.
1217
+ */
1218
+ buffer?: number
1219
+ /** Half-width per buffer pass. Default `"0.1mm"`. */
1220
+ bufferStep?: Length
1221
+ /** With `buffer` > 0, keep the letters' own strokes. Default `true`; `false` = outlines only. */
1222
+ keepCenterline?: boolean
1223
+ /**
1224
+ * A dot at each place's point (radius, scaled 60–100 % by the place's
1225
+ * importance), its name set beside it — right, left, the diagonals, above or
1226
+ * below, whichever is free. The dot is part of the label's `area`. Default 0
1227
+ * (no dot, name centred on the point).
1228
+ */
1229
+ marker?: Length
1230
+ /**
1231
+ * Overrides for features that match `tags` (same syntax as `features.where`).
1232
+ * First matching rule wins; unset fields keep the defaults above.
1233
+ */
1234
+ rules?: LabelRule[]
1235
+ }
1236
+
1237
+ /** One style override inside `modules.labels({ rules: [...] })`. */
1238
+ interface LabelRule {
1239
+ /**
1240
+ * When set, labels placed under this rule are also exposed as
1241
+ * `labels.<id>.lines` and `labels.<id>.area` for separate ink afterward.
1242
+ */
1243
+ id?: string
1244
+ /** Tag tests, e.g. `{ class: ["motorway", "primary"] }` or `{ "tiles:layer": "park" }`. */
1245
+ tags: Tags
1246
+ font?: LabelFont
1247
+ size?: Length
1248
+ minSize?: Length
1249
+ padding?: Length
1250
+ spacing?: Length
1251
+ curved?: boolean
1252
+ upper?: boolean
1253
+ buffer?: number
1254
+ bufferStep?: Length
1255
+ keepCenterline?: boolean
1256
+ marker?: Length
1257
+ }
1258
+
1259
+ /**
1260
+ * `modules.labels` / `lines.text` font: built-in Hershey, EMS/Hershey catalog,
1261
+ * custom stroke URL, or Google outline.
1262
+ */
1263
+ type LabelFont =
1264
+ | DrawlandFontId
1265
+ | DrawlandCatalogFontId
1266
+ | DrawlandFont
1267
+ | StrokeFont
1268
+ | GoogleFont
1269
+
1270
+ /** Built-in single-stroke font (Greek/Cyrillic/Latin-ext fallback in WASM). */
1271
+ type DrawlandFontId = "futural"
1272
+
1273
+ /**
1274
+ * Evil Mad Scientist / Hershey SVG fonts (downloaded at render time; same URLs
1275
+ * as the [oskay/svg-fonts](https://gitlab.com/oskay/svg-fonts) catalog).
1276
+ */
1277
+ type DrawlandCatalogFontId =
1278
+ | "ems-readability"
1279
+ | "ems-readability-italic"
1280
+ | "ems-swiss"
1281
+ | "ems-tech"
1282
+ | "ems-casual-hand"
1283
+ | "ems-allure"
1284
+ | "ems-osmotron"
1285
+ | "ems-nixish"
1286
+ | "ems-bird"
1287
+ | "ems-capitol"
1288
+ | "hershey-serif-med"
1289
+ | "hershey-script"
1290
+ | "hershey-goth-english"
1291
+
1292
+ interface DrawlandFont {
1293
+ origin: "drawland"
1294
+ id: DrawlandFontId | DrawlandCatalogFontId | string
1295
+ /** Override catalog URL or load a custom Hershey/EMS SVG/JHF file. */
1296
+ url?: string
1297
+ }
1298
+
1299
+ /** Any single-stroke SVG or `.jhf` font by URL (`fetch` in browser/CLI). */
1300
+ interface StrokeFont {
1301
+ origin: "stroke"
1302
+ url: string
1303
+ }
1304
+
1305
+ interface GoogleFont {
1306
+ origin: "google"
1307
+ family: string
1308
+ weight?: number
1309
+ italic?: boolean
1310
+ }
1311
+
1312
+ /** Strokes and covered area for one `rules[].id` bucket. */
1313
+ interface LabelBucket {
1314
+ readonly lines: Lines
1315
+ readonly area: Area
1316
+ /** The dots of this rule's places (with a `marker`). */
1317
+ readonly dots: Area
1318
+ }
1319
+
1320
+ /**
1321
+ * What the labels module publishes. Each `rules[].id` adds a property with the
1322
+ * same name (`labels.park`, …) whose value is a `LabelBucket`.
1323
+ */
1324
+ type Labels = {
1325
+ readonly lines: Lines
1326
+ /**
1327
+ * The ink every label puts on the paper, counters closed: an outline font's
1328
+ * letters, a single-stroke font's strokes a nib wide. Grow it for clear paper
1329
+ * round the names: `areas.grow(labels.area, 0.8)`. A rule's own `.area` keeps
1330
+ * the counters open, to fill the letters.
1331
+ */
1332
+ readonly area: Area
1333
+ /**
1334
+ * The dot at each place set with a `marker`, apart from the letters: fill
1335
+ * it, or draw its outline, as its own pen (`lines.rings(labels.dots)`).
1336
+ */
1337
+ readonly dots: Area
1338
+ } & Record<string, LabelBucket>
1339
+
1340
+ /** Put lines on paper; returns the group id. Later draws go on top. */
1341
+ declare function draw(options: DrawOptions): string
1342
+
1343
+ type LayerTargets = string | string[]
1344
+
1345
+ interface DeoverlapOptions {
1346
+ /** Corridor half-width (typically the pen width). Default: `"0.3mm"`. */
1347
+ tolerance?: Length
1348
+ /** Dedup segments within a single polyline too. Default: `true`. */
1349
+ selfOverlap?: boolean
1350
+ /** Propagate the drawn corridor mask to subsequent layers in this call. Default: `false`. */
1351
+ acrossLayers?: boolean
1352
+ /** Maximum angular difference in degrees (`0..=90`), or omit to disable angle check. */
1353
+ angle?: number
1354
+ /** Which overlapping polyline keeps the shared section. Default: `"longest"`. */
1355
+ prefer?: "longest" | "first" | "shortest"
1356
+ /** Drop remnants shorter than this after clipping. Default: `tolerance`. */
1357
+ minLength?: Length
1358
+ /** Drop polylines whose retained length is below this fraction (`0..=1`) of their original length. */
1359
+ drop?: number
1360
+ /** Exclude these layer ids when `layers` is omitted. */
1361
+ except?: string[]
1362
+ }
1363
+
1364
+ interface ToleranceOptimizeOptions {
1365
+ tolerance?: Length
1366
+ except?: string[]
1367
+ }
1368
+
1369
+ interface FilterOptimizeOptions {
1370
+ minLength?: Length
1371
+ except?: string[]
1372
+ }
1373
+
1374
+ interface ReloopOptimizeOptions {
1375
+ except?: string[]
1376
+ }
1377
+
1378
+ /** Starting point for `compose.hand`; any key below overrides it. */
1379
+ type HandPreset = "steady" | "sketch"
1380
+
1381
+ interface HandOptions {
1382
+ /** `"steady"` (default): tremble, bowed edges, loose ends. `"sketch"`: also crossing corners and long lines in several strokes. */
1383
+ preset?: HandPreset
1384
+ /** Slow tremble shared by every stroke, so joins stay joined. Default `"0.25mm"` (sketch `"0.35mm"`). */
1385
+ wobble?: Length
1386
+ /** Wavelength of that tremble. Default `"15mm"`. */
1387
+ wavelength?: Length
1388
+ /** Fine tremor along each stroke. Default `"0.04mm"`. */
1389
+ tremor?: Length
1390
+ /** Sideways sag of straight runs, as a fraction of their length (capped at 0.9mm). Default `0.012`. */
1391
+ bow?: number
1392
+ /** Open strokes overshoot (or stop short of) their ends by up to this. Default `"0.3mm"`. */
1393
+ overshoot?: Length
1394
+ /** Closed rings miss closing by up to this (gap or drifting overlap). Default `"0.7mm"`. */
1395
+ close?: Length
1396
+ /** Longest single pen stroke; longer lines are drawn in several. `0` = off (default; sketch `"40mm"`). */
1397
+ reach?: Length
1398
+ /** Sharp corners drawn as crossing lines running past by up to this. `0` = off (default; sketch `"0.8mm"`). */
1399
+ corners?: Length
1400
+ /** Share (0–1) of strokes gone over a second time with their own bows and ends. Default `0` (sketch `0.3`). */
1401
+ retrace?: number
1402
+ /** How far apart a second pass is set down, at most. Default `"0.25mm"`. */
1403
+ retraceOffset?: Length
1404
+ /** Seed for the hand's randomness. Default `1`. */
1405
+ seed?: number
1406
+ /** Exclude these layer ids when `layers` is omitted. */
1407
+ except?: string[]
1408
+ }
1409
+
1410
+ /**
1411
+ * Preferred drawing direction for pen strokes:
1412
+ * - A compass preset (`"lr"`, `"rl"`, `"tb"`, `"bt"`, `"tl-br"`, `"tr-bl"`, `"bl-tr"`, `"br-tl"`, `"e"`, `"se"`, `"s"`, `"sw"`, `"w"`, `"nw"`, `"n"`, `"ne"`)
1413
+ * - Or a numeric angle in degrees (`0` = East / left-to-right, `45` = South-East / top-left to bottom-right, `90` = South / top-to-bottom).
1414
+ */
1415
+ type OrientDirection =
1416
+ | number
1417
+ | "lr" | "left-to-right" | "e" | "east"
1418
+ | "tl-br" | "nw-se" | "se" | "southeast"
1419
+ | "tb" | "top-to-bottom" | "s" | "south"
1420
+ | "tr-bl" | "ne-sw" | "sw" | "southwest"
1421
+ | "rl" | "right-to-left" | "w" | "west"
1422
+ | "br-tl" | "se-nw" | "nw" | "northwest"
1423
+ | "bt" | "bottom-to-top" | "n" | "north"
1424
+ | "bl-tr" | "sw-ne" | "ne" | "northeast"
1425
+
1426
+ interface OrientOptions {
1427
+ /** Preferred stroke direction (compass preset or angle in degrees). Default: `"lr"` (`0`). */
1428
+ direction?: OrientDirection
1429
+ /** Alias for `direction` when specifying an angle in degrees. */
1430
+ angle?: OrientDirection
1431
+ /** Leave strokes longer than `maxLength` untouched. */
1432
+ maxLength?: Length
1433
+ /** Split multi-segment strokes (such as zigzags) where they reverse against `direction` before orienting. Default: `false`. */
1434
+ splitReversals?: boolean
1435
+ /** Exclude these layer ids when `layers` is omitted. */
1436
+ except?: string[]
1437
+ }
1438
+
1439
+ interface LinesortOptions {
1440
+ /** Run 2-opt swaps after nearest-neighbour pass. Default: `true`. */
1441
+ twoOpt?: boolean
1442
+ /** Maximum 2-opt passes. Default: `250`. */
1443
+ passes?: number
1444
+ /** Do not flip stroke directions during sorting (connect `end -> start` only). Default: `false` (automatically `true` when `direction`/`angle` is set or after `compose.orient`). */
1445
+ follow?: boolean
1446
+ /** Orient strokes along this preferred direction before sorting, and lock their direction (`follow: true`). */
1447
+ direction?: OrientDirection
1448
+ /** Alias for `direction`. */
1449
+ angle?: OrientDirection
1450
+ /** When `direction`/`angle` is set, leave strokes longer than `maxLength` untouched. */
1451
+ maxLength?: Length
1452
+ /** When `direction`/`angle` is set, split strokes at sharp reversals against `direction` before orienting. Default: `false`. */
1453
+ splitReversals?: boolean
1454
+ /** Exclude these layer ids when `layers` is omitted. */
1455
+ except?: string[]
1456
+ }
1457
+
1458
+ /** How the drawn groups stack, cover each other, and are optimized for the plotter. */
1459
+ declare const compose: {
1460
+ /** Group ids, bottom first; groups left out go on top in draw order. Default: draw order. */
1461
+ order(...ids: (string | string[])[]): void
1462
+ /** `from` hides exactly the listed groups, wherever they are in the order. */
1463
+ mask(options: { name?: string; from: Area; occludes: string[] }): void
1464
+ /** Which masks cut: `"auto"` (default), `"none"`, or exactly these areas. */
1465
+ clip(value: "auto" | "none" | Area[]): void
1466
+ /** Remove overlapping stroke segments within or across layers. */
1467
+ deoverlap(layers?: LayerTargets | Length | DeoverlapOptions, options?: Length | DeoverlapOptions): void
1468
+ /** Join polylines whose endpoints are within `tolerance` (default `"0.1mm"`). */
1469
+ linemerge(layers?: LayerTargets | Length | ToleranceOptimizeOptions, options?: Length | ToleranceOptimizeOptions): void
1470
+ /** Ramer-Douglas-Peucker simplification within `tolerance` (default `"0.05mm"`). */
1471
+ simplify(layers?: LayerTargets | Length | ToleranceOptimizeOptions, options?: Length | ToleranceOptimizeOptions): void
1472
+ /** Drop strokes shorter than `minLength` (default `"0.05mm"`). */
1473
+ filter(layers?: LayerTargets | Length | FilterOptimizeOptions, options?: Length | FilterOptimizeOptions): void
1474
+ /** Randomize seam vertex on closed loops to avoid ink blobs. */
1475
+ reloop(layers?: LayerTargets | ReloopOptimizeOptions): void
1476
+ /** Redraw strokes as if by hand: tremble, bowed edges, loose ends, unclosed rings. Runs where it is called in the sequence — usually after `linemerge`, before `simplify`/`linesort`. */
1477
+ hand(layers?: LayerTargets | HandPreset | HandOptions, options?: HandPreset | HandOptions): void
1478
+ /** Flip open strokes so they flow toward a preferred direction (e.g. `"tl-br"` or `45` degrees) to avoid pen skipping on reversals. */
1479
+ orient(layers?: LayerTargets | OrientDirection | OrientOptions, options?: OrientDirection | OrientOptions): void
1480
+ /** Nearest-neighbour + 2-opt stroke ordering to minimize pen-up travel. */
1481
+ linesort(layers?: LayerTargets | OrientDirection | LinesortOptions, options?: OrientDirection | LinesortOptions): void
1482
+ }
1483
+
1484
+ /** Where the map is and on what paper. The page edits this call when its values are written literally. */
1485
+ declare function output(options: OutputOptions): void
1486
+
1487
+ /** The profile's name. */
1488
+ declare function title(text: string): void
1489
+
1490
+ /** Where a view goes on the page, and what place it shows. */
1491
+ interface ViewSpec {
1492
+ /** A name for the view: `compose.mask({ occludes: [id] })` cuts it. */
1493
+ id: string
1494
+ /** Top-left corner on the page, in mm. */
1495
+ at: [number, number]
1496
+ /** Width and height on the page, in mm. */
1497
+ size: [number, number]
1498
+ lat?: number
1499
+ lng?: number
1500
+ scale?: string | number
1501
+ bearing?: number
1502
+ tileZoom?: number
1503
+ projection?: OutputOptions["projection"]
1504
+ /** One colour for every stroke of the view: it becomes one SVG group named `id`, a pen of its own. */
1505
+ ink?: string
1506
+ }
1507
+
1508
+ /**
1509
+ * Another place, at its own scale, drawn into a rectangle of this page: a
1510
+ * postcard of four corners of a city, an inset. The style is a script by
1511
+ * name (`"city-grain"`: on the command line, `city-grain.js` beside the
1512
+ * profile) or a function whose calls build the view's own graph. The view is drawn under the page's own groups; a page mask that
1513
+ * names it in `occludes` cuts it (a title knocked out of all four). Returns
1514
+ * the view's id.
1515
+ */
1516
+ declare function view(spec: ViewSpec, style: string | (() => void)): string
1517
+
1518
+
1519
+ /** The library, as a `Graph` built in Node carries it. */
1520
+ export interface Library {
1521
+ features: typeof features
1522
+ areas: typeof areas
1523
+ engine: typeof engine
1524
+ page: typeof page
1525
+ world: typeof world
1526
+ lines: typeof lines
1527
+ fills: typeof fills
1528
+ burin: typeof burin
1529
+ ink: typeof ink
1530
+ modules: typeof modules
1531
+ compose: typeof compose
1532
+ draw: typeof draw
1533
+ output: typeof output
1534
+ title: typeof title
1535
+ view: typeof view
1536
+ }