drawland 0.0.0-stage → 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pietro Leoni
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # drawland for Node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ OpenStreetMap drawn as layered pen-plotter SVGs. A style says what is drawn
4
+ and how: buildings hatched, parks stippled, water in waves, roads at their
5
+ real width, contours, names in single-stroke fonts. `drawland` runs it at a
6
+ place, downloads what it reads (vector tiles, Overpass, elevation, fonts,
7
+ datasets; cached on disk) and returns one SVG in paper millimetres, a group
8
+ per pen.
9
+
10
+ ![City Grain](https://raw.githubusercontent.com/piLeoni/drawland/main/docs/gallery/city-grain.webp)
11
+
12
+ ```sh
13
+ npm install drawland
14
+ ```
15
+
16
+ ## Draw a profile
17
+
18
+ A profile is a JavaScript or TypeScript file: every style in the gallery at
19
+ [draw.land](https://draw.land) is one, saved from its editor.
20
+
21
+ ```js
22
+ import drawland from 'drawland'
23
+
24
+ const map = await drawland.draw({ profile: 'city-grain.js', lat: 37.8053, lng: -122.4436, progress: true })
25
+ console.log(map.title, map.groups) // [{ id, strokes }]: a group is a pen
26
+ map.save('marina.svg', { perLayer: true }) // marina.svg, marina-roads.svg, …
27
+ ```
28
+
29
+ ## Or build the style in Node
30
+
31
+ The library a profile calls, as an object, typed (the package ships the
32
+ TypeScript types of every function):
33
+
34
+ ```ts
35
+ import drawland from 'drawland'
36
+
37
+ const g = new drawland.Graph()
38
+ g.output({ lat: 37.802, lng: -122.263, width: '6in', height: '4in', scale: '1:8000' })
39
+ const water = g.areas.polygons(g.features.tiles('water'))
40
+ const buildings = g.areas.polygons(g.features.tiles('buildings'))
41
+ g.draw({ id: 'water', from: g.fills.fill({ in: water, pattern: 'waves', spacing: '0.8mm' }) })
42
+ g.draw({ id: 'buildings', from: g.lines.rings(buildings) })
43
+ g.compose.mask({ from: buildings, occludes: ['water'] })
44
+
45
+ ;(await drawland.draw({ profile: g })).save('lake.svg')
46
+ ```
47
+
48
+ `g.view(spec, () => { … })` and a `remap` warp take Node functions; a view
49
+ can name a JavaScript style beside `new Graph({ dir })`.
50
+
51
+ ## Reference
52
+
53
+ | | |
54
+ |---|---|
55
+ | `draw({ profile, script, typescript, dir, lat, lng, address, cache, offline, refresh, progress })` | Draw a file (`.js`, `.ts`, `.json`), a `Graph`, a script's text, or the postcard, off the main thread: a `Promise<Map>` |
56
+ | `graph({ … })` | The graph a profile builds, as an object; nothing downloaded |
57
+ | `new Graph({ lat, lng, dir })` | A graph built in Node; `.finish()` for the graph |
58
+ | `map.svg`, `.title`, `.groups`, `.slices` | The whole SVG; the title; `{ id, strokes }` per pen; `{ suffix, svg }` per sheet |
59
+ | `map.save(path, { perLayer, slices, decimals })` / `map.files({ … })` | Write the files (their paths) / the same, unwritten |
60
+ | `POSTCARD`, `FUNCTIONS`, `cli(argv)` | The built-in profile; every function of the library; the command line |
61
+
62
+ The package has the command line too: `npx drawland map city-grain.js --lat 37.8053 --lng -122.4436`.
63
+ Prebuilt for macOS (arm64, x64), Linux (x64, arm64, glibc) and Windows (x64).
64
+ How to write a style, every pattern and the full reference:
65
+ [draw.land/docs](https://draw.land/docs). Source:
66
+ [github.com/piLeoni/drawland](https://github.com/piLeoni/drawland). MIT.
package/cli.js ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ // `npx drawland map …`: the command line, the same one `cargo install drawland-cli` installs.
3
+ process.exitCode = require('./native.js').cli(process.argv.slice(2))
Binary file
Binary file
Binary file
Binary file
Binary file
package/index.d.ts ADDED
@@ -0,0 +1,34 @@
1
+ import type { DrawOptions, ExportFiles, Group, Map, SvgFile } from './native'
2
+ import type { Library } from './library'
3
+
4
+ export type { DrawOptions, ExportFiles, Group, Map, SvgFile, Library }
5
+
6
+ /**
7
+ * A graph built in Node, with the same library a profile calls: `g.features`,
8
+ * `g.areas`, `g.lines`, `g.fills`, `g.modules`, `g.compose`, `g.page`,
9
+ * `g.world`, `g.output(…)`, `g.draw(…)`, `g.view(…)`. Draw it with
10
+ * `drawland.draw({ profile: g })`.
11
+ */
12
+ export declare class Graph {
13
+ /** `lat`/`lng`: the place `world` answers for, over `output`'s; `dir`: where views read the styles they name. */
14
+ constructor(options?: { lat?: number; lng?: number; dir?: string })
15
+ /** The graph built, as the engine reads it. The graph is finished. */
16
+ finish(): Record<string, unknown>
17
+ }
18
+ export interface Graph extends Library {}
19
+
20
+ export interface Draw extends Omit<DrawOptions, 'profile' | 'graph'> {
21
+ /** A profile file (`.js`, `.ts`, `.json`) or a `Graph` built here. */
22
+ profile?: string | Graph
23
+ }
24
+
25
+ /** Draw a profile at a place: a file or a `Graph` (`profile`), a script's text (`script`), or the built-in postcard. */
26
+ export declare function draw(options?: Draw): Promise<Map>
27
+ /** The graph a profile builds, as an object; no map data is downloaded. */
28
+ export declare function graph(options?: Draw): Record<string, unknown>
29
+ /** The command line, `drawland map …`, on `argv` (without the program's name); the exit code. */
30
+ export declare function cli(argv: string[]): number
31
+ /** The built-in postcard's script: the profile drawn when none is given. */
32
+ export declare const POSTCARD: string
33
+ /** Every function of the library, as a script names it (`areas.union`). */
34
+ export declare const FUNCTIONS: readonly string[]
package/index.js ADDED
@@ -0,0 +1,83 @@
1
+ // draw.land for Node: a profile and a place in, the layered pen-plotter SVG
2
+ // out, downloading and caching what the map reads.
3
+ //
4
+ // const drawland = require('drawland')
5
+ // const map = await drawland.draw({ profile: 'city-grain.js', lat: 37.8053, lng: -122.4436 })
6
+ // map.save('map.svg')
7
+ //
8
+ // or a graph built here, with the same library a profile calls:
9
+ //
10
+ // const g = new drawland.Graph()
11
+ // g.output({ lat: 37.802, lng: -122.263, width: '6in', height: '4in', scale: '1:8000' })
12
+ // const water = g.areas.polygons(g.features.tiles('water'))
13
+ // g.draw({ id: 'water', from: g.fills.fill({ in: water, pattern: 'waves', spacing: '0.8mm' }) })
14
+ // ;(await drawland.draw({ profile: g })).save('lake.svg')
15
+
16
+ const native = require('./native.js')
17
+
18
+ // The library's JavaScript face, the very file a profile's interpreter runs:
19
+ // a function of the library's calls, here a NativeGraph's.
20
+ const makeLibrary = new Function(`return (\n${native.LIBRARY}\n)`)()
21
+
22
+ const J = (v) => JSON.stringify(v === undefined ? null : v)
23
+ const P = (s) => JSON.parse(s)
24
+
25
+ class Graph {
26
+ /** A graph built in Node. `lat`/`lng`: the place `world` answers for; `dir`: where views read the styles they name. */
27
+ constructor({ lat, lng, dir } = {}) {
28
+ const n = new native.NativeGraph(lat, lng, dir)
29
+ const dl = {
30
+ functions: () => native.functions(),
31
+ properties: () => native.properties(),
32
+ call: (name, args) => P(n.call(name, J(args))),
33
+ prop: (name) => P(n.prop(name)),
34
+ get: (of, part) => P(n.get(J(of), part)),
35
+ describe: (v) => n.describe(v === undefined ? '' : J(v)),
36
+ outputBegin: (spec) => n.outputBegin(J(spec)),
37
+ outputWarps: (done) => n.outputWarps(J(done)),
38
+ remapGrid: (warp, k) => P(n.remapGrid(J(warp), k)),
39
+ remapMesh: (k, columns, rows, points, went) => P(n.remapMesh(k, columns, rows, J(points), J(went))),
40
+ viewBegin: (spec) => n.viewBegin(J(spec)),
41
+ viewEnd: (ok) => P(n.viewEnd(ok)),
42
+ viewStyle: (spec, name) => P(n.viewStyle(J(spec), name)),
43
+ burin: () => {
44
+ throw new Error("burin.terrain((b) => …) is burin's script builder, which runs in a profile; from Node, pass the burin document's JSON")
45
+ },
46
+ fail: (message) => {
47
+ throw new Error(message)
48
+ },
49
+ }
50
+ Object.defineProperty(this, 'native', { value: n })
51
+ Object.assign(this, makeLibrary(dl))
52
+ }
53
+
54
+ /** The graph built, as the engine reads it. The graph is finished. */
55
+ finish() {
56
+ return P(this.native.finish())
57
+ }
58
+ }
59
+
60
+ /** Draw a profile at a place: a file (`profile`), a `Graph`, a script's text (`script`), or the built-in postcard. */
61
+ function draw(options = {}) {
62
+ if (options.profile instanceof Graph) {
63
+ const { profile, ...rest } = options
64
+ return native.draw({ ...rest, graph: profile.native.finish() })
65
+ }
66
+ return native.draw(options)
67
+ }
68
+
69
+ /** The graph a profile builds, as an object; no map data is downloaded. */
70
+ function graph(options = {}) {
71
+ if (options.profile instanceof Graph) return options.profile.finish()
72
+ return P(native.graph(options))
73
+ }
74
+
75
+ module.exports = {
76
+ draw,
77
+ graph,
78
+ Graph,
79
+ cli: native.cli,
80
+ Map: native.Map,
81
+ POSTCARD: native.POSTCARD,
82
+ FUNCTIONS: Object.freeze(native.functions()),
83
+ }