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/README.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # drawland for Node
2
2
 
3
- OpenStreetMap drawn as layered pen-plotter SVGs. A short JavaScript
4
- **profile** says what is drawn and how; `drawland` runs it at a place,
5
- downloads what it reads (vector tiles, Overpass, elevation, fonts, datasets;
6
- cached on disk) and returns one SVG in paper millimetres, a group per pen.
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.
7
9
 
8
10
  ![City Grain](https://raw.githubusercontent.com/piLeoni/drawland/main/docs/gallery/city-grain.webp)
9
11
 
@@ -11,41 +13,54 @@ cached on disk) and returns one SVG in paper millimetres, a group per pen.
11
13
  npm install drawland
12
14
  ```
13
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
+
14
21
  ```js
15
- const drawland = require('drawland') // or: import drawland from 'drawland'
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
+ ```
16
28
 
17
- // The built-in postcard, at a place.
18
- const map = await drawland.draw({ lat: 37.8771, lng: -122.2562 })
19
- map.save('berkeley.svg')
29
+ ## Or build the style in Node
20
30
 
21
- // A profile of your own, or a style saved from https://draw.land
22
- const bologna = await drawland.draw({ profile: 'city-grain.js', address: 'Piazza Maggiore, Bologna', progress: true })
23
- console.log(bologna.title, bologna.groups) // [{ id, strokes }]: a group is a pen
24
- bologna.save('bologna.svg', { perLayer: true }) // and one file per pen
31
+ The library a profile calls, as an object, typed (the package ships the
32
+ TypeScript types of every function):
25
33
 
26
- // A script's text; what it reads beside it comes from dir.
27
- await drawland.draw({ script: 'output({ lat: 45.07, lng: 7.69 })\n…', dir: '.' })
34
+ ```ts
35
+ import drawland from 'drawland'
28
36
 
29
- // The graph only: no download.
30
- const graph = drawland.graph({ profile: 'city-grain.js', lat: 45.07, lng: 7.69 })
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')
31
46
  ```
32
47
 
33
- The package has the command line too: `npx drawland map city-grain.js
34
- --lat 37.8771 --lng -122.2562 -o map.svg`.
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
35
52
 
36
53
  | | |
37
54
  |---|---|
38
- | `draw({ profile, script, dir, lat, lng, address, cache, offline, refresh, progress })` | Draw, off the main thread: a `Promise<Map>` |
39
- | `graph({ … })` | The graph the profile builds, as an object |
40
- | `map.svg`, `.title`, `.groups`, `.slices` | The whole SVG; the profile's title; `{ id, strokes }` per pen; `{ suffix, svg }` per sheet |
41
- | `map.save(path, { perLayer, slices, decimals })` | Write the files; their paths |
42
- | `map.files({ … })` | The same as `{ suffix, svg }` |
43
- | `POSTCARD` | The built-in profile's script |
44
- | `cli(argv)` | The command line; its exit code |
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 |
45
61
 
62
+ The package has the command line too: `npx drawland map city-grain.js --lat 37.8053 --lng -122.4436`.
46
63
  Prebuilt for macOS (arm64, x64), Linux (x64, arm64, glibc) and Windows (x64).
47
-
48
- How to write a profile, every pattern and the full reference:
64
+ How to write a style, every pattern and the full reference:
49
65
  [draw.land/docs](https://draw.land/docs). Source:
50
- [github.com/piLeoni/drawland](https://github.com/piLeoni/drawland).
51
- AGPL-3.0-only.
66
+ [github.com/piLeoni/drawland](https://github.com/piLeoni/drawland). MIT.
Binary file
Binary file
Binary file
Binary file
Binary file
package/index.d.ts CHANGED
@@ -1,12 +1,34 @@
1
1
  import type { DrawOptions, ExportFiles, Group, Map, SvgFile } from './native'
2
+ import type { Library } from './library'
2
3
 
3
- export type { DrawOptions, ExportFiles, Group, Map, SvgFile }
4
+ export type { DrawOptions, ExportFiles, Group, Map, SvgFile, Library }
4
5
 
5
- /** Draw a profile at a place: a file (`profile`), a script's text (`script`), or the built-in postcard. */
6
- export declare function draw(options?: DrawOptions): Promise<Map>
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>
7
27
  /** The graph a profile builds, as an object; no map data is downloaded. */
8
- export declare function graph(options?: DrawOptions): Record<string, unknown>
28
+ export declare function graph(options?: Draw): Record<string, unknown>
9
29
  /** The command line, `drawland map …`, on `argv` (without the program's name); the exit code. */
10
30
  export declare function cli(argv: string[]): number
11
31
  /** The built-in postcard's script: the profile drawn when none is given. */
12
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 CHANGED
@@ -2,20 +2,82 @@
2
2
  // out, downloading and caching what the map reads.
3
3
  //
4
4
  // const drawland = require('drawland')
5
- // const map = await drawland.draw({ profile: 'city-grain.js', lat: 37.8771, lng: -122.2562 })
5
+ // const map = await drawland.draw({ profile: 'city-grain.js', lat: 37.8053, lng: -122.4436 })
6
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')
7
15
 
8
16
  const native = require('./native.js')
9
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
+
10
69
  /** The graph a profile builds, as an object; no map data is downloaded. */
11
- function graph(options) {
12
- return JSON.parse(native.graph(options))
70
+ function graph(options = {}) {
71
+ if (options.profile instanceof Graph) return options.profile.finish()
72
+ return P(native.graph(options))
13
73
  }
14
74
 
15
75
  module.exports = {
16
- draw: native.draw,
76
+ draw,
17
77
  graph,
78
+ Graph,
18
79
  cli: native.cli,
19
80
  Map: native.Map,
20
81
  POSTCARD: native.POSTCARD,
82
+ FUNCTIONS: Object.freeze(native.functions()),
21
83
  }