supported

A static property on CarrotSearchCircles equal to true if the browser has a 2D canvas, the baseline the visualization needs. Every supported browser has one, so the property is true wherever the script loads at all.

Deprecated in 3.0.0 This property is kept for backwards compatibility. It cannot tell whether the renderer a page asks for is available; use isSupported() instead, which takes the options the page is about to embed with.

isSupported()

Since 3.0.0 A static function on CarrotSearchCircles that returns true if a visualization with the given options can be displayed in this browser. Pass the options object you are about to give to the constructor; the argument may also be omitted, which checks the defaults.

The function returns false when the browser has no 2D canvas, or when renderer in the options is webgl and WebGL cannot be used. In the latter case the constructor would still embed the visualization, with the canvas renderer, as described under renderer; this function lets a page that insists on hardware accelerated rendering find that out beforehand. With auto, canvas or svg the WebGL check is not made.

Checking WebGL creates a throw-away context and compiles the shaders. This takes a few milliseconds and is repeated on each call, so call the function once, before embedding, rather than in a loop.

  if (CarrotSearchCircles.isSupported({ renderer: "webgl" })) {
    // Put embedding code here.
    console.log("WebGL rendering supported.");
  } else {
    // Display a warning, skip the visualization or embed with another renderer.
    console.log("WebGL rendering not supported.");
  }
                  

defaults

Since 3.0.0 A static, read-only property on CarrotSearchCircles: an object with the default values of all attributes.

  console.log("Default pixel ratio: " + CarrotSearchCircles.defaults.pixelRatio);
  console.log("Default renderer: " + CarrotSearchCircles.defaults.renderer);
                

id

Identifier of the DOM element into which the visualization is to be embedded.

element

The DOM element into which the visualization is to be embedded. Please see the id option for additional considerations.

dataObject

The data model to visualize in JSON format. The top-level object is a root group and must contain a non-empty groups property pointing to an array of objects representing individual first-level groups (this array can be empty). A null model object clears the visualization (removes any current model).

The model must be a tree: a group object may appear in it only once. A group under two parents or among its own descendants is drawn more than once or never finishes the layout. With assertions enabled, such a model is reported in the console, naming the group and where it appears, and ignored, so that the visualization keeps its current model.

Each group can contain the following properties:

id

(optional, String) unique identifier of the group. Group identifiers are required only for programmatic changes of certain group attributes such as selection, zoom state or open state.

label

(required, String) textual description of the group. For best results, use short labels. The groupLabelDecorator callback can also be used to modify labels before they are drawn on the visualization when the model is retrieved from a source that cannot be altered.

weight

(optional, Number >= 0) weight of the group relative to other groups. The larger the weight, the more space the group's polygon will occupy on the screen. Good values for the weight property could be e.g. the number of documents in a cluster or the score of the cluster.

Group weights must be non-negative. Zero-weight groups can receive special treatment, see the showZeroWeightGroups option.

If a group's weight is not specified, Circles will assume the weight is 1.0.

groups

(optional, Array) an array of subgroups of the group.

open

(optional, boolean) if true, all of this group's subgroups will be shown initially. By default a maximum of visibleGroupCount subgroups is shown and then the user needs to click on an expander symbol to open up a group.

zoomed

(optional, boolean) if true, the group is in zoomed state by default. Zoomed groups take a proportionally larger amount of space of the parent group's circle slice (see zoomedFraction parameter).

selected

(optional, boolean) if true, the group will be initially in selected state. This can be useful to visually highlight a certain group (or groups) as the model is loaded.

The data object (and groups) can contain user properties, not required or interpreted by the visualization. These properties may be used in callback hooks (for example for color model tuning). The following example shows a data object with various values of the above properties.

circles.set({
  visibleGroupCount: 2,       // display an expander after the first 2 groups.
  dataObject: {
    open: false,              // keep the top-level group closed.
    groups: [
      { label: "Bad news", groups: [
        { label: "Last penny lost", sentiment: -0.5 },
        { label: "Bazinga doomed",  sentiment: -1 }
        ]},
      { label: "Good news", zoomed: true, groups: [
        { label: "iPads under $100",      sentiment: 0.5, selected: true },
        { label: "Martians are friendly", sentiment: 1 }
        ]},
      { label: "Other news", groups: [
        { label: "Vampires on the loose", sentiment: -2 },
        { label: "Van Helsing to the rescue", sentiment: -3 }
        ]}
    ]
  }
});
                

See this section for hints on how to convert data models that are not in the required format.

pixelRatio

The physical-to-display pixel count ratio to assume when drawing the final visualization. On modern devices with high-density screens (such as the Retina display) one logical pixel can be mapped to more than one physical pixel. You can use this option to increase the resolution at which the visualization is drawn to make the image clearer and labels more legible. You can also decrease this resolution to make rendering faster at the cost of quality.

By default, pixelRatio is auto: the visualization draws at the browser's own pixel ratio (window.devicePixelRatio), so that it is as sharp as the rest of the page. The ratio is read again when the visualization is resized, including resize() called after the window moved to a screen of a different density or the page was zoomed. The pixel ratio in effect is reported as pixelRatio of the layout attribute.

With a number, the width and height of the canvas on which the visualization is drawn are the pixel dimensions of the HTML container element multiplied by that number, and the canvas is stretched to fit in the container's client area. For example, if you set pixelRatio to 2 and if the size of the enclosing HTML element is 400x400 pixels, the size of the canvas will be 800x800 pixels. A value of 1 draws one physical pixel per logical pixel regardless of the screen, which is faster on high-density screens at the cost of sharpness; a value such as Math.min(1.5, window.devicePixelRatio) caps the resolution on the densest screens.

The following examples draw the same picture at pixel ratios of 0.5, 1 and 2. Compare the sharpness of the labels and the speed of the animations; on a high-density screen the last example is what the default of auto gives.

circles.set({
  dataObject: largeDataSet,
  titleBar: "inscribed",
  pixelRatio: 0.5
});
                      

circles.set({
  dataObject: largeDataSet,
  titleBar: "inscribed",
  pixelRatio: 1
});
                      

circles.set({
  dataObject: largeDataSet,
  titleBar: "inscribed",
  pixelRatio: 2
});
                      

Changed in 3.0.0 The pixel ratio only affects the resolution of the picture. All attributes that specify sizes in pixels (font sizes, paddings, line widths, the diameter and so on) are in logical (CSS) pixels of the page and the layout does not depend on the pixel ratio. In earlier versions some of these attributes, such as minRadialPadding and minAngularPadding, were in physical pixels and percentage font sizes grew with the pixel ratio; the picture at pixel ratios other than 1 may therefore differ slightly from the previous versions. Changing pixelRatio no longer reloads the data model. The default is now auto, the browser's pixel ratio; set pixelRatio to 1 to get the previous default.

renderer

Since 3.0.0 Selects how the visualization is drawn:

webgl

hardware accelerated rendering using WebGL 2. Groups, outlines and labels are drawn by shaders on the graphics card, which makes animations smooth also at high pixel ratios and for large data sets. If WebGL cannot be used, the visualization falls back to the canvas renderer and reports that through onRendererChanged. This renderer ignores the texture mapping attributes radialTextureStep, angularTextureStep and textureOverlapFudge, and textureMappingMesh shades labels instead of drawing a mesh; see the differences below.

canvas

software rendering using the 2D canvas API, as in the versions before 3.0.0.

svg

the visualization is an SVG document: groups are paths and labels are real text laid along arcs. The picture is resolution independent, so it stays sharp when zoomed or printed, and it can be inspected and copied like any other SVG. This is the slowest renderer for animations and large data sets; it is never chosen automatically.

Heads up!

Safari draws right-to-left scripts on curved labels in reversed order and without Arabic letter joining. This is a WebKit bug in the rendering of text on paths (bug 275313); the other renderers are not affected. Use the canvas or webgl renderer for such labels in Safari.

auto

uses webgl if it is available and hardware accelerated, and canvas otherwise. Because browsers limit the number of WebGL contexts on a page, in this mode only the first eight visualizations on a page use webgl.

The renderer can be changed at any time; the picture stays the same. If the WebGL context is lost and the browser does not restore it, the visualization continues with the canvas renderer. The two renderers produce the same picture up to minor differences in antialiasing. The differences in behavior are:

• radialTextureStep, angularTextureStep and textureOverlapFudge only apply to the canvas renderer, which maps labels using a mesh of triangles. The webgl renderer maps labels exactly, for each pixel.
• textureMappingMesh shades the area of each label with the webgl renderer; there is no mesh to show.
• in onBeforeGroupDrawn, the webgl renderer only accepts CSS color strings.
• the visualization's main canvas has a WebGL context with the webgl renderer, so a 2D context cannot be obtained from it. The canvas element is replaced when the renderer changes. To read the picture, use the onFrameDrawn event or the imageData attribute.
• with the svg renderer there is an svg element in place of the main canvas. pixelRatio has no effect on it (it still applies to the title bar, the attribution and exported images), the texture mapping attributes do not apply, onBeforeGroupDrawn only accepts CSS color strings, and onFrameDrawn provides no canvas. imageData works as usual; the image is drawn by the canvas renderer. Labels are set as text, so they differ slightly in shape from the other renderers, which bend an image of the text.

To diagnose rendering problems, look at the browser's console. The loss and the restoration of the WebGL context and the switch to the canvas renderer are always reported there as warnings, with the time since embedding. With the logging attribute set to true at embedding time, the chosen renderer, the reason for the choice, the graphics hardware and the setup time are logged as well.

circles.set("renderer", "webgl");
console.log("Requested: " + circles.get("renderer") + ", in use: " + circles.get("activeRenderer"));
                

activeRenderer

Since 3.0.0 A read-only attribute that returns the renderer currently in use: webgl, canvas or svg. See the renderer attribute.

console.log("Rendering with: " + circles.get("activeRenderer"));
                

captureMouseEvents

The visualization by default captures mouse, touch and pen presses and prevents their default browser actions. This helps avoid interactions with system features such as scrolling or zooming on touch-based devices. In scenarios where such features should be available to the user this option should be set to false.

Let's capture all mouse events happening on the body object (a parent of the visualization example in the DOM hierarchy).

var hook = window["_loggingHook"] = function(evt) {
  console.log("Mouse event: " + evt.type);
};
$("body").on("mousedown mouseup", hook);
                

$("body").off("mousedown mouseup", window["_loggingHook"]);
                

Compare the following two visualization setups (hover over the visualization and note events printed to the console when mouse buttons are pressed or released).

circles.set({
  captureMouseEvents: false
});
                      

circles.set({
  captureMouseEvents: true
});
                      

autoResize

Since 3.0.0 Whether the visualization follows the size of its container element. When true, the default, a change of the container's size lays out and redraws the visualization, as a call to resize() would: the window was resized, the page's layout changed, the element was shown after being hidden. Set it to false to size the visualization under program control, with resize().

The size is watched with the browser's ResizeObserver; in a browser without it, the visualization needs resize() calls as in earlier versions. See Adjusting size.

circles.set("autoResize", false);
                

backgroundColor

The background color for the canvas behind the visualization. Visualizations with fully opaque or fully transparent backgrounds may be slightly faster to draw. See the Colors section for color specifications.

circles.set("backgroundColor", "#fff");

circles.set("backgroundColor", "rgba(0,0,255,.2)");

circles.set("backgroundColor", "hsla(120, 50%, 50%, 0.8)");

centerx

Horizontal position of the big circle's center. The position can be expressed in any of the following ways:

• a percentage (string) of available container width, where '50%' indicates the center of the container,
• an absolute value (number) interpreted as pixels from the left side of the container,
• a function accepting an object ({width: _, height: _ }) and returning a number interpreted as above.

circles.set("centerx", "25%");

circles.set("centerx", 20);

circles.set({
  centerx: function(box) {
    return box.width * 0.75;
  }});
                    

centery

Vertical position of the big circle's center. The position can be expressed in any of the following ways:

• a percentage (string) of available container height, where '50%' indicates the center of the container,
• an absolute value (number) interpreted as pixels from the top side of the container,
• a function accepting an object ({width: _, height: _ }) and returning a number interpreted as above.

circles.set("centery", "25%");

circles.set("centery", 20);

circles.set({
  centery: function(box) {
    return box.height * 0.75;
  }});
                    

layout

Returns the most recent layout state. The format is identical to the object passed to the callback function of the onLayout event. The returned value may be undefined if no model is displayed or if the layout data is not yet available.

console.log("Current layout.", circles.get("layout"));
                

diameter

Diameter of the big circle (outer ring). The diameter can be expressed in any of the following ways:

• a percentage (string) of available container width or height (whichever is smaller),
• an absolute value (number) interpreted as pixels,
• a function accepting an object ({width: _, height: _ }) and returning a number interpreted as above.

circles.set("diameter", "50%");

circles.set("diameter", 400);

circles.set({
  diameter: function(box) {
    return Math.max(box.height, box.width);
  }});
                    

ringScaling

Child ring sizing multiplier. Each ring's size will be the size of its parent, multiplied by ringScaling. The center space counts as an "invisible" ring in these calculations.

circles.set("ringScaling", 0.5);

circles.set("ringScaling", 1);

circles.set("ringScaling", 1.5);

See the ringShape attribute for defining custom ring shapes.

ringShape

While ringScaling gives pretty good control over ring sizes, sometimes a more fine-grained control is needed. The ringShape attribute lets one use a callback function to modify each group's inner and outer ring properties (and possibly other ring shape properties in the future). The callback function receives an associative array with the following properties.

group

The group for which the ring size should be calculated.

maxRadius

A hint about the maximum radius of the circle. This value may, but need not, be respected.

centerx

The current horizontal center of the circle.

centery

The current vertical center of the circle.

r_inner

The inner radius for the group, as calculated by the default algorithm.

r_outer

The outer radius for the group, as calculated by the default algorithm.

The callback function is expected to modify (or leave unchanged) the r_inner and r_outer properties. Any return value returned by the callback is ignored. Model groups are traversed in-depth, in pre-order (parent first).

The callback function is called once per layout call for performance reasons.

A combination of ringShape and isGroupVisible callbacks can be used to create a "wedge" effect, as the following example shows.

circles.set({
  visibleGroupCount: 0,
  isGroupVisible: function(group) { return !group.gap; },
  ringShape: function(attrs) {
    if (attrs.group.wedge) {
      attrs.r_inner -= 40;
      attrs.r_outer += 40;
    }
  },
  dataObject: { groups: [
    {label: "1"},
    {label: "2"},
    {gap: true, weight: 0.1},
    {label: "3", wedge: true},
    {gap: true, weight: 0.1},
    {label: "4"},
    {label: "5"}
  ]}
});
                

More complex customizations are of course possible. The following example stacks up groups on top of one another, creating a spiky shape that lies pretty far from the visualization's defaults.

// Link up groups with their parents. We will need this
// in the callback hook. Calculate max depth as we go.
var model = dataSets["full-3-level.jsonp"].data;
var depth = 0;
var assignParent = function(parent, level) {
  depth = Math.max(level, depth);
  parent.groups && parent.groups.forEach(function(e) {
    e.parent = parent;
    assignParent(e, level + 1);
  });
};
assignParent(model, 0);

var variance = 30;  // Randomize each group's ring by this value.
circles.set({
  dataObject: model,
  rolloutTime: 2,
  rolloutAnimation: "implode",
  visibleGroupCount: 8,
  // Decrease the diameter by max. ring size variation
  diameter: function(box) {
    return Math.min(box.height, box.width) - 2 * variance * depth;
  },
  // Calculate ring sizes varying them randomly and stacking each
  // on top of its parent (relies on depth-first preorder traversal).
  ringShape: function(attrs) {
    var group = attrs.group;
    if (group.parent) {
      var r_width = attrs.r_outer - attrs.r_inner;
      group.r_inner = attrs.r_inner = group.parent.r_outer;
      group.r_outer = attrs.r_outer = group.r_inner + r_width + Math.random() * variance;
    } else {
      group.r_inner = attrs.r_inner;
      group.r_outer = attrs.r_outer;
    }
  }
});
                

angleStart

Start angle of the big circle's first group. The angles are expressed in degrees, clockwise, starting from zero angle on the right, as shown in the illustration below.

The following examples show groups laid out in semi-circles. Note the direction indicated by angleWidth.

circles.set({
  angleStart: 0,
  angleWidth: 180
});
                    

circles.set({
  angleStart: 180,
  angleWidth: -180
});
                    

angleWidth

Maximum angular "width" assigned for all top-level groups. A full clockwise circle will have a width of 360; a counter-clockwise layout will have a width of -360. The following example animates both angleStart and angleWidth.

window.clearTimeout(window['_animHookId']);
delete window['_animHookId'];
                

var angleStart = 0;
var angleWidth = 0;
var hook = function() {
  angleStart = (angleStart + 10) % 360;
  angleWidth = (angleWidth + 15) % (360 * 2);
  circles.set({
    angleStart: angleStart,
    angleWidth: angleWidth - 360
  });
  window['_animHookId'] = window.setTimeout(hook, 200);
};
hook();
                

angleEnd

An attribute providing the end angle of the big circle's first-level groups. When this attribute is provided the groups will always start at angleStart and end at angleEnd, always clockwise. If angleEnd is smaller than angleStart their values are swapped. For this reason it is not possible to render certain shapes with angleEnd, for instance display groups in counter-clockwise order. This constraint is lifted when angleWidth is used. Compare the following examples and their group order.

circles.set({
  angleStart: 30,
  angleEnd:   330
});
                    

circles.set({
  angleStart: 330,
  angleEnd:   30
});
                    

circles.set({
  angleStart: 330,
  angleWidth: -300
});
                    

showZeroWeightGroups

If true, groups whose weight is zero will be visible, with their weight slightly smaller than the smallest non-zero weight of the sibling groups.

circles.set({
  showZeroWeightGroups: true,
  dataObject: {
    groups: [
      { label: "Group 1", weight: 1 },
      { label: "Group 2", weight: 1 },
      { label: "Group 3", weight: 1 },
      { label: "Group 4", weight: 0 },
    ]
  },
});
                    

circles.set({
  showZeroWeightGroups: false,
  dataObject: {
    groups: [
      { label: "Group 1", weight: 1 },
      { label: "Group 2", weight: 1 },
      { label: "Group 3", weight: 1 },
      { label: "Group 4", weight: 0 },
    ]
  },
});
                    

visibleGroupCount

Maximum number of groups to display in a sub-level of a parent group. If there are more children than visibleGroupCount, an expander widget is shown, allowing the user to open up a group manually. A visibleGroupCount equal to zero means all child groups will be displayed.

circles.set({
  visibleGroupCount: 2,
  dataObject: {
    groups: [
      {label: "G1"}, {label: "G2"},
      {label: "G3"}, {label: "G4"}
    ]
  },
});
                    

circles.set({
  visibleGroupCount: 4,
  dataObject: {
    groups: [
      {label: "G1"}, {label: "G2"},
      {label: "G3"}, {label: "G4"}
    ]
  },
});
                    

zoomedFraction

For zoomed-in groups, specifies the fraction of their parent group's current angle. This fraction is evenly distributed among all zoomed-in groups belonging to one parent. See the example below.

circles.set({
  zoomedFraction: 0.5,
  dataObject: {
    groups: [
      {label: "G1"}, {label: "G2"},
      {label: "G3"},
      {label: "G4", zoomed: true}
    ]
  },
});
                    

circles.set({
  zoomedFraction: 0.5,
  dataObject: {
    groups: [
      {label: "G1"}, {label: "G2"},
      {label: "G3", zoomed: true},
      {label: "G4", zoomed: true}
    ]
  },
});
                    

isGroupVisible

A callback used to determine whether a given group should be displayed or not. The callback function will receive a single argument: the group object from the dataObject model.

An invisible group still occupies space in the visualization but will not be rendered and will not receive mouse events (hover, clicks). It is effectively a blank space between the surrounding siblings (if any). This function can be used to implement visual separators (spaces) between groups, as in the following example.

circles.set({
  zoomedFraction: 0.5,
  isGroupVisible: function(group) { return group.visible; },
  visibleGroupCount: 0,
  dataObject: {
    groups: (function() {
      var v = [];
      for (var i = 1; i <= 50; i++) {
        var visible = i & 1;
        v.push({label: "G" + i, visible: visible, weight: 1 / i});
      }
      return v;
    })()
  }
});
                

A more practical use for the gap groups is to insert a visual space between parent groups so that their children are separated. The following example inserts such spaces into the current model.

circles.set({
  isGroupVisible: function(group) { return !group.gap; },
  dataObject: { groups: [
    {label: "1", groups: [{label: "1"}, {label: "2"}, {label: "3"}]},
    {gap: true, weight: 0.1},
    {label: "2", groups: [{label: "1"}, {label: "2"}, {label: "3"}]},
    {gap: true, weight: 0.1},
    {label: "3", groups: [
      {label: "1"},
        {gap: true, weight: 0.1},
      {label: "2"},
        {gap: true, weight: 0.1},
      {label: "3"}]},
    {gap: true, weight: 0.1}
  ]}
});
                

isGroupHoverable

Since 3.0.0 A callback used to determine whether a given group reacts to the pointer hovering over it. The callback function will receive a single argument: the group object from the dataObject model, and should return true for groups that can be hovered. When the callback is not set, all groups can be hovered.

A group excluded by this callback gets no hover outline and is not reported by onGroupHover, as if the pointer was over empty space. With groupHoverHierarchy enabled, excluded ancestors of the hovered group are left out of the outline. Clicks and double clicks are not affected. To turn hovering off for all groups, set the hover colors to transparent instead.

The following example lets only the groups without children be hovered.

circles.set({
  dataObject: {
    groups: [
      {label: "1", groups: [{label: "1.1"}, {label: "1.2"}]},
      {label: "2", groups: [{label: "2.1"}, {label: "2.2", groups: [{label: "2.2.1"}]}]},
      {label: "3"}
    ]
  },
  isGroupHoverable: function(group) { return !group.groups; }
});
                

groupOutlineWidth

Width of the outline stroke. A stroke width of zero means no outline is drawn. The outline is painted with groupOutlineColor.

circles.set("groupOutlineWidth", 5);
                

groupOutlineColor

Color of the outline stroke; groupOutlineWidth controls the stroke's width.

circles.set({
  groupOutlineWidth: 5,
  groupOutlineColor: "#fff"
});
                

Note that transparent outlines will not remove the underlying group's fill (this is a technical limitation of HTML5 canvases). Unless this is the desired effect, transparencies should be avoided.

circles.set({
  groupOutlineWidth: 10,
  groupOutlineColor: "rgba(0,0,0,0.2)"
});
                

rainbowStartColor

Start color to use if the rainbow color model is used for coloring groups. A rainbow color model will proportionally spread the color hue among top-level groups (starting at rainbowStartColor and ending at rainbowEndColor). Any sub-groups will be painted with the parent group's hue but with varying degrees of saturation and lightness.

circles.set("dataObject", largeDataSet);
circles.set("open", {all: true});
                

For custom coloring groupColorDecorator should be used.

rainbowEndColor

End color to use if the rainbow color model is used for coloring groups. See rainbowStartColor for a description of how the rainbow color model works.

groupColorDecorator

A callback function to customize or completely replace the default rainbow color model for groups. During each redraw, the visualization core will call the provided function once for each group. The task of the function is to modify or completely replace the default color of the group and its label. New colors can be derived from various properties of the group, such as its nesting level, number of siblings, or custom properties passed along with the data model.

The callback function receives three arguments: options, properties and variables.

options

all current visualization options (keys and values).

properties

a hash object with properties describing the current group. The object contains the following properties:

• group: the data object corresponding to the group, exactly as passed in the dataObject option.
• weightNormalized: the weight of the group normalized to the 0..1 range in relation to the group's siblings (the raw weight of the group can be retrieved from the original data model if it was present there).
• index: the position of the group relative to its siblings in the input data object. Position indices start at 0.
• siblingCount: the number of immediate siblings of the group.
• level: the nesting level of the group. Level numbers start with 0.

variables

a hash with two keys (groupColor, labelColor) and values computed by the default rainbow model. The callback function can either change some of the properties of these values or replace them with new ones.

The callback function can replace these values with a CSS3 color string (hsl, hsla, rgb or rgba color specification) or a hash object containing the following properties:

• model: rgba for the RGBA model, hsla for the HSLA model. When adding or changing the values of other properties, it is important to set this property to reflect the desired color model.
• r, g, b, a: RGBA values (integers in the 0..255 range).
• h, s, l, a: HSLA values, hue is an angle (0..359), saturation and lightness are percentages (0..100) and transparency is a range between 0 and 1.

The default values computed by the rainbow color model are always passed to the callback in the HSLA hash format described above.

The labelColor variable can be set to a string value of auto which will recompute the label color again depending on the updated groupColor and visualization options controlling dark/ light label colors: labelColorThreshold, labelLightColor and labelDarkColor.

The simplest color model could just use explicit color values provided as part of the model.

var customAttributes = function(opts, params, vars) {
  console.log("Color decorator callback.", params, vars);
  vars.groupColor = params.group.gcolor;
  vars.labelColor = "auto";
};

circles.set({
  groupColorDecorator: customAttributes,
  dataObject: {
    groups: [
      { label: "C", gcolor: "#00aeef" },
      { label: "M", gcolor: "#ec008c" },
      { label: "Y", gcolor: "#fff200" },
      { label: "K", gcolor: "#231f20" }
    ]
  }
});
                

A more complex example is shown below. Here we compute HSLA values depending on the sentiment attribute of each group.

var sentimentPainter = function(opts, params, vars) {
  // Sentiment is a custom property with values in the -1..+1 range, -1 means negative sentiment,
  // +1 -- positive, 0 -- neutral
  var sentiment = params.group.sentiment;
  if (!sentiment) {
    // Make neutral groups gray
    vars.groupColor.s = 0;
    vars.groupColor.l = 0;
    vars.groupColor.a = 0.2;
  } else {
    if (sentiment > 0) {
      // Make positive groups green
      vars.groupColor.h = 120;
    } else {
      // Make negative groups red
      vars.groupColor.h = 0;
    }

    // Make saturation and lightness depend on
    // the strength of the sentiment.
    vars.groupColor.s = 50 * (1 + Math.abs(sentiment));
    vars.groupColor.l = Math.abs(60 * sentiment);

    // Indicate that we use the HSL model
    vars.groupColor.model = "hsl";
  }
};

circles.set({
  groupColorDecorator: sentimentPainter,
  dataObject: {
    groups: [
      { label: "Bad news", groups: [
        { label: "Last penny lost", sentiment: -0.5 },
        { label: "Bazinga doomed",  sentiment: -1 }
        ]},
      { label: "Good news", groups: [
        { label: "iPads under $100",      sentiment: 0.5 },
        { label: "Martians are friendly", sentiment: 1 }
        ]},
      { label: "Other news", groups: [
        { label: "Vampires on the loose", sentiment: 0 },
        { label: "Van Helsing to the rescue", sentiment: 0 }
        ]}
    ]
  }
});
                

labelColorThreshold

Picks the label color automatically depending on the group's color brightness. If the brightness is below this threshold labelLightColor is used, otherwise labelDarkColor is used. Setting the threshold to either 0 or 1 will pick dark or light labels, respectively.

Automatic choice of label colors is also provided as part of groupColorDecorator's functionality.

labelDarkColor

The label color to use on bright groups (see labelColorThreshold).

labelLightColor

The label color to use on dark groups (see labelColorThreshold).

zoomDecorationFillColor

Color of the zoomed-in group's decoration. Note that transparency may be used to remove the decoration entirely.

circles.set({
  zoomDecorationFillColor: "rgba(0,0,0,0)",
  zoomDecorationStrokeColor: "#fff"
});
circles.set("zoom", "1");
                

zoomDecorationStrokeColor

Color of the zoomed-in group's decoration stroke. See zoomDecorationFillColor.

groupFontFamily

Font family to use for drawing group labels. CSS-compliant font family specifications are supported, including webfonts imported using the @font-face syntax.

Study the source code of the mobile demo for an example of using Google web fonts.

groupMinFontSize

Minimum font size used for drawing group labels. Two font sizing strategies are supported:

• absolute: when the property is set to a numeric value, such as 27, the value will be interpreted as the number of pixels,
• relative: when the property is set to a percentage, such as 40%, the font size will be calculated as a percentage of the group's maximum allowed label height.

Note that setting the minimum font size to a large value may result in empty labels (unlabeled groups) or very unclear labels ending in an ellipsis, as in this example:

circles.set({
  dataObject: largeDataSet,
  groupMinFontSize: 30,
  groupMaxFontSize: 40
});
                

groupMaxFontSize

Maximum font size used for drawing group labels. See the groupMinFontSize attribute for details.

groupLinePadding

This attribute has been removed. Please take a look at groupLinePaddingRatio for a size-relative replacement.

groupLinePaddingRatio

Extra vertical padding added between lines in multi-line labels. The value of this attribute is a ratio multiplied by the label's line height. The ratio can be negative, for example groupLinePaddingRatio of -0.1 will shrink the space between lines by 10%. Note that doing so may cause glyphs from different lines to overlap.

groupLabelDecorator

A callback function to customize the label of each group. The function will be called on each layout() operation (which is a consequence of most calls to resize).

The callback function receives three arguments: options, properties and variables. Options and properties are identical to those passed to groupColorDecorator (see their description there). The variables argument is a hash with a single key labelText that the callback function can overwrite with a decorated value (or may leave as-is if the current label should be used).

The following example reverses all group labels and adds angle quotes around them.

circles.set({
  groupLabelDecorator: function(opts, props, vars) {
    vars.labelText = "«" + vars.labelText.split("").reverse().join("") + "»";
  }
});
                

ratioAngularPadding

How much padding space to leave on the left and right of the group's circle slice. The value is a ratio (percentage) of the entire angle assigned for the group.

This attribute is useful in combination with minAngularPadding, ratioRadialPadding and minRadialPadding as they all affect the visual padding applied to the label fit box before the label is rendered. The following figure illustrates these concepts (note the radial and angular dimensions; the grayed area within the group is the allowed fit box for the label).

minAngularPadding

Minimum angular padding for group labels. In logical (CSS) pixels. See ratioAngularPadding for an explanation of how paddings work.

ratioRadialPadding

How much padding space to leave at the top and bottom of the group's circle slice. The value is a ratio (percentage) of the entire group's height (a difference between the inner and outer radii). See ratioAngularPadding for an explanation of how paddings work.

minRadialPadding

Minimum radial padding space, in logical (CSS) pixels. See ratioAngularPadding for an explanation of how paddings work.

radialTextureStep

Specifies the radial interval between "tiles" which are used to map a rectangular label image onto the slice of the circle. Smaller numbers will result in higher quality.

Changed in 3.0.0 This attribute, like the other texture mapping attributes, applies to the canvas renderer only. The webgl renderer maps labels exactly and needs no tuning.

Texture mapping is an expensive operation that requires a trade-off: more subdivision polygons will result in higher quality but will take longer to render. When high interactivity is expected (or on slower devices) poorer textures may be a better choice instead of long delays required to render labels. In addition, the noTexturingCurvature attribute allows one to define the threshold when the texture should not be applied at all (when the curvature of the label is small enough that it can be drawn as a straight box).

textureMappingMesh is helpful in debugging and estimating the needed value of this parameter. The following examples show different texture mapping settings and how they affect label quality. They select the canvas renderer explicitly, since with the webgl renderer these options have no effect.

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0,
  radialTextureStep: 15,
  angularTextureStep: 15,
  textureMappingMesh: true
});
                    

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0,
  radialTextureStep: 30,
  angularTextureStep: 30,
  textureMappingMesh: true
});
                    

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0,
  radialTextureStep: 50,
  angularTextureStep: 50,
  textureMappingMesh: true
});
                    

The following example sets noTexturingCurvature to different thresholds so that near-straight labels are not textured at all (fully grayed boxes).

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0.2,
  radialTextureStep: 15,
  angularTextureStep: 15,
  textureMappingMesh: true
});
                    

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0.4,
  radialTextureStep: 15,
  angularTextureStep: 15,
  textureMappingMesh: true
});
                    

circles.set({
  dataObject: largeDataSet,
  renderer: "canvas",
  noTexturingCurvature: 0.8,
  radialTextureStep: 15,
  angularTextureStep: 15,
  textureMappingMesh: true
});
                    

angularTextureStep

Specifies the angular interval (in pixels) between "tiles" which are used to map a rectangular label image onto the slice of the circle. See the description and examples accompanying the radialTextureStep attribute for more. Applies to the canvas renderer only.

noTexturingCurvature

Sets the threshold between normal label rendering and texture-mapping onto a slice of a circle. See the description and examples accompanying the radialTextureStep attribute for more.

textureOverlapFudge

Texture mapping may result in empty gap pixels between triangles on certain browsers (due to anti-aliasing of images). This parameter controls how much triangles overlap, which to some extent solves the problem. The default value of this parameter is determined depending on the current browser. Applies to the canvas renderer only.

deferLabelRedraws

Defers redrawing of labels for a given number of seconds after a layout. In case any changes are made to the visualization in the meantime that would result in another layout operation, redrawing of labels will be further delayed. This is a trick to speed up interactions on slower devices.

Compare how labels are drawn in the following examples (resize the window once the example is visible).

circles.set({
  dataObject: largeDataSet,
  deferLabelRedraws: 0,
  labelRedrawFadeInTime: 0
});
                    

circles.set({
  dataObject: largeDataSet,
  deferLabelRedraws: 1,
  labelRedrawFadeInTime: 0
});
                    

circles.set({
  dataObject: largeDataSet,
  deferLabelRedraws: 1,
  labelRedrawFadeInTime: 1
});
                    

labelRedrawFadeInTime

Duration of fade-in effect for labels after they are redrawn from scratch. The value is expressed in seconds. Used in combination with deferLabelRedraws.

ratioAspectSwap

Provides control over a group label's direction (angular or radial). The aspect ratio of a label is computed by dividing the width of the label box by its height (see ratioAngularPadding for an explanation). If the computed value is smaller than ratioAspectSwap the label is rotated and printed along the radial direction.

This parameter can be used to enforce directionality of labels by passing extreme ratios, as in the following example.

// Only radial labels.
circles.set({
  dataObject: largeDataSet,
  ratioAspectSwap: 10000
});
                    

// Only angular labels.
circles.set({
  dataObject: largeDataSet,
  ratioAspectSwap: 0.0001
});
                    

expanderAngle

An angle (in degrees) to reserve for an expander widget if a group has sub-groups and their number exceeds visibleGroupCount. The expander space will be either expanderAngle or half of the group's available angle, whichever value is smaller.

minExpanderAngle

If the angle assigned for a group is smaller than minExpanderAngle, the expander widget will not be displayed at all (due to lack of space).

expanderOutlineWidth

Expander widget's outline stroke width in pixels.

expanderOutlineColor

Expander widget's outline color.

expanderColor

Expander widget's fill color.

titleBar

A title bar is a text label component inscribed into the center of the circle or overlaid at the top/ bottom of the visualization area. A title bar shows the label of the group under the cursor or label(s) of currently selected groups.

The title bar was introduced in version 2.2.0 of Circles.

The following snippets demonstrate each type of the title bar component and combinations of attributes which may be handy to achieve certain effects.

circles.set({
  dataObject: largeDataSet,
  titleBar: "none"
});
                    

circles.set({
  dataObject: largeDataSet,
  titleBar: "inscribed"
});
                    

circles.set({
  dataObject: largeDataSet,
  titleBar: "topbottom",
  titleBarBackgroundColor: "rgba(0,0,0,.2)",
  titleBarTextColor: "#fff",
  titleBarTextPaddingTopBottom: 10
});
                    

var padding = 5;
var fraction = 10 / 100;
circles.set({
  dataObject: largeDataSet,
  titleBar: "bottom",
  titleBarTextColor: "#fff",
  titleBarTextPaddingTopBottom: 5,
  titleBarMinFontSize:  "5%",
  titleBarMaxFontSize:  "8%",
  diameter: function(box) {
    return (box.height - padding * 2) * (1 - fraction);
  },
  centery: function(box) {
    var h = box.height - padding - box.height * fraction;
    return h / 2;
  }
});
                    

titleBarFontFamily

Font family for the titleBar, if shown. CSS-compliant font family specifications are supported, including webfonts imported using the @font-face syntax. If not specified, the same font as specified for the groupFontFamily will be used.

This example renders the title bar in a monospace font.

circles.set({
  dataObject: { groups: [
    { label: "ABC123", selected: true },
    { label: "DEF456" }]},
  titleBar: "inscribed",
  titleBarFontFamily: "monospace",
  groupFontFamily: "Arial, sans-serif"
});
                

titleBarMinFontSize

Minimum font size to draw the title bar's label. Two font sizing strategies are supported:

• absolute: when the property is set to a numeric value, such as 27, the value will be interpreted as the number of pixels,
• relative: when the property is set to a percentage, such as 40%, the font size will be calculated as a percentage of the title bar's maximum allowed height. This makes sense for the inscribed title bar type since the height of the inscribed box will depend on the size of the visualization.

Note that setting the minimum font size to a large value may result in an empty title bar label or a very unclear label ending in an ellipsis.

titleBarMaxFontSize

Maximum font size to draw the title bar's label. See the titleBarMinFontSize attribute for details.

titleBarBackgroundColor

The background color of the title bar area.

titleBarTextColor

The text color for drawing labels in the title bar area.

titleBarTextPaddingLeftRight

Left and right (horizontal) padding to leave inside the title bar's area.

titleBarTextPaddingTopBottom

Top and bottom (vertical) padding to leave inside the title bar's area.

titleBarLabelDecorator

A callback decorator function to transform the label displayed by the titleBar component.

The callback function receives a hash with the following properties:

hoverGroup

The group the cursor currently hovers over or undefined if none.

selectedGroups

An array of currently selected groups or an empty array.

label

Suggested label for the title bar. Changing this value will override the defaults.

The callback function may leave the default label as-is or it may change it. An undefined label will hide the title bar.

circles.set({
  dataObject: largeDataSet,
  titleBar: "topbottom",
  diameter: "80%",
  titleBarLabelDecorator: function(attrs) {
    if (attrs.hoverGroup) {
       attrs.label = "Hovering over: " + attrs.hoverGroup.label;
    } else if (attrs.selectedGroups.length > 0) {
       attrs.label = "Selected: " + attrs.selectedGroups.length + " group(s)";
    } else {
       attrs.label = "[hover or select something]";
    }
  }
});
                

expandTime

Duration of the open/close group animation (in seconds).

zoomTime

Duration of the zoom/unzoom group animation (in seconds).

rolloutAnimation

Sets the effect used to roll out a new model into view. The value should be any of the following strings: implode, rollout, tumbler, fadein, implode3d, random.

The implode3d effect Since 3.0.0 flies groups into place in three dimensions, from behind the viewer. It requires the webgl renderer; the other renderers play implode instead. random never picks it.

The following example demonstrates each of these effects.

var model = {groups: [
  { label: "implode" },
  { label: "rollout" },
  { label: "tumbler" },
  { label: "fadein" },
  { label: "implode3d" },
  { label: "random" }]};

circles.set({
  modelChangeAnimations: "sequential",
  rolloutTime: 1,
  rolloutAnimation: "implode",
  dataObject: model,
  onBeforeZoom: function() { return false; },
  onBeforeSelection: function() { return false; },
  onGroupClick: function(info) {
    // Reset the model to replay the animation.
    circles.set("dataObject", null);
    circles.set("rolloutAnimation", info.group.label);
    circles.set("dataObject", model);
  }
});
                

rolloutTime

Duration (in seconds) of the rolloutAnimation sequence. To skip the animation sequence entirely, set the rolloutTime to zero.

pullbackAnimation

Sets the effect used to pull back the current model from view. The value should be any of the following strings: explode, rollin, tumbler, fadeout, explode3d, random.

The explode3d effect Since 3.0.0 breaks the visualization into tiles that fly towards the viewer in three dimensions. It requires the webgl renderer; the other renderers play explode instead. random never picks it.

The following example demonstrates each of these effects.

var model = {groups: [
  { label: "explode" },
  { label: "rollin" },
  { label: "tumbler" },
  { label: "fadeout" },
  { label: "explode3d" },
  { label: "random" }]};

circles.set({
  modelChangeAnimations: "sequential",
  pullbackTime: 1,
  pullbackAnimation: "explode",
  dataObject: model,
  onBeforeZoom:      function() { return false; },
  onBeforeSelection: function() { return false; },
  onGroupClick:      function(info) {
    circles.set("pullbackAnimation", info.group.label);
    circles.set("dataObject", null);
    circles.set("dataObject", model);
  }
});
                

pullbackTime

Duration (in seconds) of the pullbackAnimation sequence. To skip the animation sequence entirely, set the pullbackTime to zero.

updateTime

Duration of the group weights' tween when update is called.

modelChangeAnimations

Controls how effects played on model changes are ordered and replayed with respect to one another. The following values are possible:

auto

the concurrency is chosen automatically depending on the target browser speed.

sequential

pullback animation runs fully before the rollout animation of the new model.

parallel

pullback animation and rollout animation run at the same time (concurrently). This may require more computational and graphic resources.

Note that the sequential setting does not imply that a rapid succession of several model changes will be reflected on screen (some of the intermediate changes may be skipped and never displayed). The following example shows a rapid succession of model changes in sequential mode.

circles.set({
  modelChangeAnimations: "sequential",
  rolloutAnimation: "implode",
  pullbackAnimation: "explode",
  pullbackTime: 1,
  rolloutTime: 1
});
window.setTimeout(function() {
  circles.set("dataObject", {groups: [{label: "g1"}]});
  circles.set("dataObject", {groups: [{label: "g2"}]});
  circles.set("dataObject", null);
  circles.set("dataObject", {groups: [{label: "g3"}]});
  circles.set("dataObject", {groups: [{label: "g4"}]});
  circles.set("dataObject", null);
  circles.set("dataObject", {groups: [{label: "g5"}]});
  circles.set("dataObject", {groups: [{label: "final"}]});
}, 500);
                

And a corresponding example in parallel mode.

circles.set({
  modelChangeAnimations: "parallel",
  rolloutAnimation: "implode",
  pullbackAnimation: "explode",
  pullbackTime: 1,
  rolloutTime: 1
});
window.setTimeout(function() {
  circles.set("dataObject", {groups: [{label: "g1"}]});
  circles.set("dataObject", {groups: [{label: "g2"}]});
  circles.set("dataObject", {groups: [{label: "g3"}]});
  circles.set("dataObject", {groups: [{label: "g4"}]});
  circles.set("dataObject", null);
  circles.set("dataObject", {groups: [{label: "g5"}]});
  circles.set("dataObject", {groups: [{label: "final"}]});
}, 500);
                

groupSelectionColor

Overlay color for selected groups.

groupSelectionOutlineColor

Color of the outline stroke for the selected groups.

groupSelectionOutlineWidth

Outline stroke width (in pixels) for the selected groups.

groupSelectionOutlineStyle

Since 2.3.9 Selects the type of overlay painted over the selected group. The following values are supported:

• slice (default): a pie slice (wedge) outlining the group and going to the circle's center.
• group: only the group (outline shape).
• none: no outline is drawn.

The following example demonstrates the slice and group outline types. Note groupHoverHierarchy is turned off to limit the outline to just the selected groups.

circles.set({
  groupSelectionColor: "#f00",
  groupSelectionOutlineWidth: 3,
  groupSelectionOutlineColor: "rgba(0,0,255,0.5)",
  dataObject: largeDataSet,
  groupHoverHierarchy: false,
  groupSelectionOutlineStyle: "slice"
});
                    

circles.set({
  groupSelectionColor: "#f00",
  groupSelectionOutlineWidth: 3,
  groupSelectionOutlineColor: "rgba(0,0,255,0.5)",
  dataObject: largeDataSet,
  groupHoverHierarchy: false,
  groupSelectionOutlineStyle: "group"
});