1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
# wmap-renderer-canvas
A Canvas-based renderer for `wmap` formatted wardley maps parsed with [`wmap-parser`][wmap-parser-js].
## Features
- Can render to canvas, raster images (PDF / JPEG), or vector (PDF)
- Rendering logic attempts to replicate [map][map]'s output.
## Installation
```bash
npm install wmap-renderer-canvas
```
```bash
yarn add wmap-renderer-canvas
```
```bash
pnpm add wmap-renderer-canvas
```
## Usage
### Browser
```javascript
import { parse } from "wmap-parser";
import { renderToCanvas } from "wmap-renderer-canvas";
const wmapSource = `
Tea (0.9, 0.5)
Cup (0.8, 0.4)
Tea -> Cup
`;
const map = parse(wmapSource);
const canvas = document.getElementById("myCanvas");
await renderToCanvas(map, canvas);
```
### Node.js - Render to Canvas
```javascript
import { createCanvas } from "canvas";
import { parse } from "wmap-parser";
import { renderToCanvas, StageType } from "wmap-renderer-canvas";
const map = parse(wmapSource);
const canvas = createCanvas(1384, 1084);
// No overrides
await renderToCanvas(map, canvas);
// Stage Type override
await renderToCanvas(map, canvas, StageType.DECISION_DRIVERS);
```
### Node.js - Render to Image File
```javascript
import { parse } from "wmap-parser";
import { renderToImage, ImageType, StageType } from "wmap-renderer-canvas";
import fs from "fs";
const map = parse(wmapSource);
// PNG
const pngStream = await renderToImage(map, ImageType.PNG);
pngStream.pipe(fs.createWriteStream("map.png"));
// JPEG, with a stage type override
const jpegStream = await renderToImage(map, ImageType.JPEG, StageType.UBIQUITY);
jpegStream.pipe(fs.createWriteStream("map.jpeg"));
// PDF, with a stage type override
const pdfStream = await renderToImage(map, ImageType.PDF, StageType.PUBLICATION_TYPES);
pdfStream.pipe(fs.createWriteStream("map.pdf"));
```
### Configuration
All functions accept an optional configuration object that can override
how the map is rendered. See the type definitions for more info on each
value. Here's all the defaults.
```javascript
{
options: {
showBackground: true,
smartLabelPositioning: true,
},
theme: {
colors: {
background: "#FFFFFF",
axis: "#0F261F",
vertex: "#0F261F",
label: "#0F261F",
stageForeground: "#DAE6E3",
stageBackground: "#FFFFFF",
inertia: "#FA2B00",
evolution: "#4F8FE6",
groups: [
"#4F8FE6",
"#FA2B00",
"#23C17C",
"#FAED8F",
"#FFB3F0",
],
},
sizes: {
mapWidth: 1300,
mapHeight: 1000,
padding: 42,
lineWidth: 0.5,
vertexWidth: 25,
vertexHeight: 25,
arrowheadSize: 10,
stageHeight: 100,
},
fonts: {
family: '"Helvetica Neue", Helvetica, Arial, sans-serif',
axisLabel: 14,
vertexLabel: 12,
note: 12,
},
lineHeights: {
vertexLabel: 18,
note: 18,
},
opacity: {
groups: 0.1,
},
},
}
```
## API
### `renderToCanvas(map, canvas, stageType, overrides)`
Renders a parsed Wardley map to a canvas element.
**Parameters:**
- `map` (Map): Parsed map object from `wmap-parser`
- `canvas` (HTMLCanvasElement|Canvas): Canvas element (browser) or Canvas instance (Node.js)
- `stageType` (StageType): The type of stage to use. See StageType for all possible values. Defaults to `StageType.ACTIVITIES`
- `overrides` (tConfiguration, optional):
**Returns:** `Promise<void>`
**Canvas Size:** The canvas will be automatically sized to 1384×1084 pixels (1300×1000 map + 42px padding on each side).
### `renderToImage(map, imageType, stageType, overrides)`
Renders a parsed Wardley map to an image stream. **Node.js only**.
**Parameters:**
- `map` (Map): Parsed map object from `wmap-parser`
- `imageType` (ImageType): The image type to use. Can be: `ImageType.PNG`, `ImageType.JPEG`, or `ImageType.PDF`
- `stageType` (StageType): The type of stage to use. See StageType for all possible values. Defaults to `StageType.ACTIVITIES`
- `overrides` (tConfiguration, optional):
**Returns:** `Promise<Stream>` - Stream of the rendered image
**Throws:**
- Error if not in Node.js environment
- Error if `canvas` module cannot be imported.
- Error if `imageType` is not supported
## Performance
The drawing is not optimized for live-editing. It's relatively quick to
generate a single image. On an M1 Pro mac, ouexample map renders in about ~7ms,
while a larger map with slightly under 2000 entities does so in ~210ms.
You can run the benchmarks by using:
```bash
make benchmark
```
## Development
This project uses a Makefile to run all commands. This is to keep the
commands uniform with the other wmap-parser projects.
### Running Tests
```bash
make test
```
Or to see coverage
```bash
make coverage
```
### Regenerating Types
If you change the JSDocs, you'll need to regenerate the types
```bash
make types
```
## License
AGPL-3.0
## See Also
- [Wardley Maps](https://wardleymaps.com/) - Learn about Wardley Mapping
[wmap-parser-js]: https://www.npmjs.com/package/wmap-parser
|
