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/LICENSE +21 -662
- package/README.md +44 -29
- package/drawland.darwin-arm64.node +0 -0
- package/drawland.darwin-x64.node +0 -0
- package/drawland.linux-arm64-gnu.node +0 -0
- package/drawland.linux-x64-gnu.node +0 -0
- package/drawland.win32-x64-msvc.node +0 -0
- package/index.d.ts +26 -4
- package/index.js +66 -4
- package/library.d.ts +1536 -0
- package/native.d.ts +37 -0
- package/native.js +60 -56
- package/package.json +25 -6
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
|
+
}
|