API (2.x)

Class: Viz

new Viz([options])

• options <Object>
  • workerURL <string> The URL of the rendering script file to use as a Web Worker.
  • worker <Worker> A Worker instance.
  • Module <function> The Emscripten module function.
  • render <function> The render function.

Constructs a new Viz instance.

If the workerURL option is given, its value must be the URL of one of the rendering script files included in the distribution (full.render.js or lite.render.js).

If the worker option is given, its value must be a Worker instance constructed with the URL or path of one of the rendering script files included in the distribution (full.render.js or lite.render.js).

If the Module and render options are given, they must be the Module and render bindings exported by either of the rendering script files.

If no options are given, one of the rendering script files must be included in the current context. (Usually by including one of them using a <script> tag after the viz.js file.)

See Usage (2.x) for more information.

viz.renderString(src[, options])

• src string The graph to render, as DOT.
• options <Object> See Render Options.
• Returns: <Promise<string>>

Renders the graph as a string. For example:

viz.renderString('digraph { a -> b }')
.then(function(string) {
  console.log(string);
});

If the graph is invalid, or if Graphviz encounters an error, an error will be thrown.

viz.renderSVGElement(src[, options])

• src string The graph to render, as DOT.
• options <Object> See Render Options.
• Returns: <Promise<SVGSVGElement>>

Renders the graph as an SVG element, suitable for inserting into the document. For example:

viz.renderSVGElement('digraph { a -> b }')
.then(function(element) {
  document.body.appendChild(element);
});

When using this function, the format option is ignored.

If the graph is invalid, or if Graphviz encounters an error, an error will be thrown.

viz.renderImageElement(src[, options])

• src string The graph to render, as DOT.
• options <Object> See Render Options. This render function accepts the following additional options:
  • scale <number>
  • mimeType <string>
  • quality <number>
• Returns: <Promise<HTMLImageElement>>

Renders the graph as an HTML image element, suitable for inserting into the document. For example:

viz.renderImageElement('digraph { a -> b }')
.then(function(element) {
  document.body.appendChild(element);
});

When using this function, the format option is ignored.

If the graph is invalid, or if Graphviz encounters an error, an error will be thrown.

viz.renderJSONObject(src[, options])

• src string The graph to render, as DOT.
• options <Object> See Render Options.
• Returns: <Promise<Object>>

Renders the graph as a JSON object.

When using this function, the format option is ignored, unless it is json or json0.

If the graph is invalid, or if Graphviz encounters an error, an error will be thrown.

Render Options

• engine <string> The layout engine. May be one of: "circo", "dot", "fdp", "neato", "osage", "twopi".
• format <string> The desired output format. May be one of: "svg", "dot", "xdot", "plain", "plain-ext", "ps", "ps2", "json", "json0".
• yInvert <boolean> Invert the y coordinate in generic output formats (dot, xdot, plain, plain-ext). This is equivalent to specifying -y when invoking Graphviz from the command-line.
• images <Object[]> Image dimensions to use when rendering nodes with image attributes.
• files <Object[]> Files to make available to Graphviz using Emscripten's in-memory filesystem.
• nop <number> "No layout" mode for the neato engine. This is equivalent to specifying the -n option when invoking Graphviz from the command-line.

images and files options

These options can be used to indicate the dimensions of an image to Graphviz, or to make data available to Graphviz that would normally be accessible via the filesystem. These options use Emscripten's in-memory filesystem.

For example, here's how to indicate to Graphviz that there is a 400px x 300px image called "test.png":

viz.renderSVGElement('digraph { a[image="test.png"]; }', {
  images: [
    { path: 'test.png', width: '400px', height: '300px' }
  ]
}).then(/* ... */);

images objects

• path <string> The path for the image. May be a filename ("example.png"), a relative or absolute path ("/images/example.png"), or a URL ("http://example.com/image.png").
• width <number | string> The width of the image.
• height <number | string> The width of the image.

Image dimensions may be specified with units: in, px, pc, pt, cm, or mm. If no units are given or dimensions are given as numbers, points (pt) are used. Graphviz does not actually load image data when this option is used — images are referenced with the dimensions given, eg, in SVG by an <image> element with width and height attributes.

Note that using a URL for the path is a bit of a hack; "http://example.com/image.png" is equivalent to the path "/http:/example.com/image.png".

files objects

• path <string> The path for the file.
• data <string> The data for the file.

Files are created relative to the root, which is the working directory.