1 files changed, 221 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a01f268
--- /dev/null
+++ b/README.md
@@ -0,0 +1,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