This is Charming1. For Charming2, go to charmingjs.org. This is v1. For v2, go to charmingjs.org.

Shape

Appending geometric elements to canvas, most of shapes support the following attributes:

  • fill - the fill color
  • fillOpacity - fill opacity (a number between 0 and 1)
  • stroke - stroke color
  • strokeWidth - stroke width (in pixels)
  • strokeOpacity - stroke opacity (a number between 0 and 1)

cm.point

Appends dots positioned in x and y. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal position, in pixels or in cells
  • y - the vertical position, in pixels or in cells
app.append(cm.point, { x: 10, y: 10 });

Appends straight lines between two points [x, y] and [x1, y1]. In addition to the standard shape attributes, the following attributes are supported:

  • x - the starting horizontal position, in pixels or in cells
  • y - the starting vertical position, in pixels or in cells
  • x1 - the ending horizontal position, in pixels or in cells
  • y1 - the ending vertical position, in pixels or in cells
  • rotate - the rotation angle in degrees clockwise
  • strokeCap - the shape of end points, defaults to butt; round and square
  • transformOrigin - the position of the origin point for rotation, defaults to start; center and end
app.append(cm.link, { x: 0, y: 0, x1: 100, y1: 100 });

cm.rect

Appends rectangles defined by x, y, width and height. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal position, in pixels or cells
  • y - the vertical position, in pixels or cells
  • width - the rectangle width, in pixels or cells
  • height - the rectangle height, in pixels or cells
  • anchor - how to position the rectangle, defaults to start; center
  • rotate - the rotation angle in degrees clockwise
app.append(cm.rect, { x: 10, y: 10, width: 50, height: 40 });

cm.circle

Appends circles positioned in x and y. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal position, in pixels or cells
  • y - the vertical position, in pixels or cells
  • r - the circle radius, in pixels or cells
app.append(cm.circle, { x: 50, y: 50, r: 30 });

cm.triangle

Appends triangles defined by x, y, x1, y1, x2, y2. In addition to the standard shape attributes, the following attributes are supported:

  • x - the first horizontal position, in pixels or cells
  • y - the first vertical position, in pixels or cells
  • x1 - the second horizontal position, in pixels or cells
  • y1 - the second vertical position, in pixels or cells
  • x2 - the third horizontal position, in pixels or cells
  • y2 - the third vertical position, in pixels or cells
app.append(cm.triangle, { x: 0, y: 0, x1: 10, y1: 0, x2: 10, y2: 10 });

cm.polygon

Appends polygons defined by x and y. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal positions of control points, in pixels or cells clockwise
  • y - the vertical positions of control points, in pixels or cells clockwise

If appends one polygon defined by a column of x and a of y, assigns columns to its x and y attribute respectively.

app.append(cm.polygon, {
  x: [0, 10, 10],
  y: [0, 0, 10],
});

If only appends one polygon defined by an array of points [x, y] or objects, assigns accessors return number to its x and y attribute respectively.

const polygon = [
  [0, 0],
  [10, 0],
  [10, 10],
];

app.data(polygon).append(cm.polygon, {
  d => d[0],
  d => d[1],
})

If appends multiple polygons defined by an array of objects, assigns accessors returns an array of numbers to its x and y attribute respectively.

const polygons = [
  { X: [0, 10, 10], Y: [0, 0, 10] },
  { X: [20, 30, 30], Y: [0, 0, 10] },
];

app.data(polygons).append(cm.polygon, {
  d => d.X,
  d => d.Y,
})

cm.line

Appends draw two-dimensional lines defined by x and y. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal positions of control points, in pixels or cells
  • y - the vertical positions of control points, in pixels or cells

If appends one line defined by a column of x and a of y, assigns columns to its x and y attribute respectively.

app.append(cm.line, {
  x: [0, 10, 20],
  y: [10, 5, 15],
});

If only appends one line defined by an array of points [x, y] or objects, assigns accessors return number to its x and y attribute respectively.

const line = [
  [0, 10],
  [10, 5],
  [20, 15],
];

app.data(line).append(cm.line, {
  d => d[0],
  d => d[1],
})

If appends multiple lines defined by an array of objects, assigns accessors returns an array of numbers to its x and y attribute respectively.

const lines = [
  { X: [0, 10, 20], Y: [10, 5, 15] },
  { X: [20, 40, 35], Y: [10, 5, 15] },
];

app.data(lines).append(cm.line, {
  d => d.X,
  d => d.Y,
})

cm.path

Appends path defined by d. In addition to the standard shape attributes, the following attributes are supported:

  • d: an array or string of [path commands](path commands)

If appends one path, assigns the specified path commands to its d attribute.

app.append(cm.path, {
  d: [["M", 0, 0], ["L", 10, 0], ["L", 10, 10], ["Z"]],
});

If appends multiple paths, assigns accessors returns an array of path commands to its d attribute.

const paths = [
  [["M", 0, 0], ["L", 10, 0], ["L", 10, 10], ["Z"]],
  [["M", 10, 0], ["L", 20, 10], ["L", 20, 10], ["Z"]],
];

app.data(paths).append(cm.path, { d: (d) => d });

cm.text

Appends texts at given position in x and y. In addition to the standard shape attributes, the following attributes are supported:

  • x - the horizontal position
  • y - the vertical position
  • text - the text contents (a string)
  • fontSize - the font size in pixels; defaults to 10
  • fontFamily - the font name
  • fontWeight - the [font weight](font weight), defaults to normal
  • textBaseline - the line anchor for vertical position; top, bottom, or middle
  • textAlign - the [text align](text align) for horizontal position; start, end, or middle

cm.group

Appends groups at given position in x and y. In addition to the standard shape attributes, the following attributes are supported:

  • y - the horizontal position
  • x - the vertical position
  • rotate - the rotation angle in degrees clockwise

All the child shapes are applied translate(x, y) and rotate(rotate) transformations.

const group = app.group({
  width: 100,
  height: 100,
});

group.append(cm.point, {
  x: 0,
  y: 0,
  r: 10,
});

cm.clear

Appends clear shape to clear the canvas background with the specified color. The following attributes are supported:

  • fill - the clear color

function(flow, value)

Defines a composite shape by a function, passing the current flow(flow) and attribute value(value).

// Defines a composite shape.
function arrow(flow, { length, angle, x, y, rotate, ...options }) {
  const group = flow.append(cm.group, { x, y, rotate });
  const l1 = length.map((d) => d / 2);
  const l2 = length.map((d) => -d / 2);
  const a1 = angle.map((d) => d);
  const a2 = angle.map((d) => -d);
  group.append(cm.link, { x: l2, y: 0, x1: l1, y1: 0, ...options });
  group.append(cm.link, { x: 0, y: 0, x1: l1, y1: 0, rotate: a2, transformOrigin: "end", ...options });
  group.append(cm.link, { x: 0, y: 0, x1: l1, y1: 0, rotate: a1, transformOrigin: "end", ...options });
}

// Uses a composite shape.
app
  .data(fields)
  .append(arrow, {
    x: (d) => d.x * size + size / 2,
    y: (d) => d.y * size + size / 2,
    length: size * 0.8,
    angle: Math.PI / 6,
    rotate: (d) => d.value,
  })
  .transform(cm.mapAttrs, {
    rotate: {
      domain: [0, 1],
      range: [0, cm.TWO_PI],
    },
  });