wmap-renderer-canvas

A Canvas-based renderer for wmap formatted wardley maps parsed with wmap-parser.

Features

Can render to canvas, raster images (PDF / JPEG), or vector (PDF)
Rendering logic attempts to replicate [map][map]'s output.

Installation

npm install wmap-renderer-canvas

yarn add wmap-renderer-canvas

pnpm add wmap-renderer-canvas

Usage

Browser

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

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

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.

{
    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:

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

make test

Or to see coverage

make coverage

Regenerating Types

If you change the JSDocs, you'll need to regenerate the types

make types

License

AGPL-3.0