Flocc

Agent-based modeling in JavaScript in the browser or on the server. [v0.4.8]

CanvasRenderer

Overview

The flocc.CanvasRenderer class (from here on, just CanvasRenderer) renders a Environment with spatial agents into an HTML <canvas> element on a web page. After mounting, it automatically updates the view every time its environment ticks.

IMPORTANT:

  • CanvasRenderer expects that all the agents in the environment have x and y values associated with them. If the environment has agents that do not have these spatial coordinates, the renderer will not work correctly.
  • Agents will be drawn differently depending on other values. The most important one is the shape value (see the .render() method below).

Instantiating

CanvasRenderer requires an Environment to render:

const environment = new Environment();
const renderer = new CanvasRenderer(environment);

Options

CanvasRenderer can also be instantiated with configuration options, which affect the output.

const opts = {
    autoPosition: boolean = false,
    background: string = 'transparent',
    height: number = 500,
    origin: Point = {
      x: 0,
      y: 0
    },
    scale: number = 1,
    width: number = 500,
    trace: boolean = false
};

const renderer = new CanvasRenderer(environment, opts);

width / height

The width and height (in pixels) of the canvas. Defaults to 500 each.

background

The background color of the canvas. Defaults to a transparent background. Can be a color name ("gray""pink"), a hex value ("#eee""#ffe2e2"), or an rgb string ("rgb(255, 200, 220)").

autoPosition

If the renderer’s environment is using a network as a helper structure, then setting this to true automatically positions all the agents in the network in a circle, contained within the bounds of the canvas.

origin

The x/y coordinates of the upper-left point (the origin) of the canvas. This defaults to { x: 0, y: 0}. If you include a value for the origin, both x and y coordinates must be included. The origin x and y coordinates should be in environment space (relative to width and height), not screen space (relative to pixel values).

scale

The scale of the canvas. This defaults to 1, so that one unit corresponds to one pixel on the canvas. If the space the agents are moving in is particularly small or large, you may want to set a correspondingly smaller (i.e. 0.01) or higher (i.e. 100) value, so that visualization meaningfully depicts the agents in the environment.

trace

If trace is set to true, the CanvasRenderer won’t clear the canvas with every tick of the simulation. Instead, you will see agent paths “tracing” over time, which can be useful for visualizing movement over time.

Methods

.mount(selector or element)

Calling .mount specifies where on the page the renderer should render the environment. If passed a CSS selector (like #id or .class), the renderer will look for the first matching element on the page, and use that as a container. If passed an element directly, the renderer will use that element as a container.

<div id="some-element"></div>
renderer.mount('#some-element');
// or...
const element = document.getElementById('some-element');
renderer.mount(element);

.render()

Renders a view of the renderer’s Environment into the HTML element that was mounted previously.

By default, the renderer draws a black circle for each Agent in the Environment at the ordered pair (agent.get('x')agent.get('y')). The radius of the circle defaults to 1, but can be set with agent.set('radius', 5) (for example).

The renderer can also draw agents as the following shapes:

  • Arrow (see the Flocking example). Use agent.set('shape', 'arrow') to render an agent as an arrow. Also expects numbers for agent.set('vx') and agent.set('vy') to determine the direction the arrow points (with respect to the agent’s velocity in the x and y directions).
  • Rectangle (see the Forest Fire example). Use agent.set('shape', 'rect') to render an agent as a rectangle. Also expects numbers for agent.set('width') and agent.set('height') to determine the dimensions of the rectangle.

Each time the renderer’s Environment ticks, this method is automatically called, but you still might want to call it manually (for example, if making manual changes to agents).