supported

A static property on CarrotSearchCircles equal to true if visualization is supported on the current browser environment.

  if (CarrotSearchCircles.supported) {
    // Put embedding code here.
    console.log("Visualization supported.");
  } else {
    // Display a warning or skip visualization.
    console.log("Visualization not supported.");
  }
                  

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). An null model object clears the visualization (removes any 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. 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 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 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 1. In such cases, the width and height of the canvas on which the visualization is drawn will be equal to the pixel dimensions of the HTML container element. For pixelRatio values greater/smaller than 1, the pixel dimensions of the canvas will be smaller/larger than the dimensions of the enclosing HTML element and the canvas will be 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. Such a configuration will better utilize the extra pixels available on Retina displays, for example.

On most modern browsers you can retrieve the device-specific pixel ratio from the window.devicePixelRatio property.

The following examples demonstrate the difference between a pixel ratio higher and lower than the pixel resolution. Note the performance drop when pixel ratio is set to a large value.

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
});
                      

captureMouseEvents

The visualization by default captures all mouse events and prevents them from bubbling up the DOM hierarchy. 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
});
                      

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 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 in onLayout method. 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 ringShape attribute for defining custom ring shapes.

ringShape

While ringScaling gives 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 can but needs not to 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) r_inner and r_outer properties. Any return value returned by the callback is ignored. Model groups are traversed in-depth, in post-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 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 counterclockwise 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 children 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 automatically to 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}
  ]}
});
                

groupOutlineWidth

Width of the outline stroke. Stroke 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 desirable effect, transparencies should be avoided.

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

rainbowStartColor

Start color to use if 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

Start color to use if rainbow color model is used for coloring groups. See rainbowStartColor for a description of how 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 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 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 grey
    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, correspondingly.

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 minimum font size to a large value may result in empty labels (unlabeled groups) or very unclear labels ending in 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 it.

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 pixels. See ratioAngularPadding for an explanation 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 how paddings work.

minRadialPadding

Minimum radial padding space, in pixels. See ratioAngularPadding for an explanation how paddings work.

radialTextureStep

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

Texture mapping is an expensive operation that requires a trade-off: more subdivision polygons will result in high quality but will render longer. 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, 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 labels quality.

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

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

circles.set({
  dataObject: largeDataSet,
  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,
  noTexturingCurvature: 0.2,
  radialTextureStep: 15,
  angularTextureStep: 15,
  textureMappingMesh: true
});
                    

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

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

angularTextureStep

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

noTexturingCurvature

Sets the threshold between normal label rendering and texture-mapping onto a slice of a circle. See the description and examples accompanying 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.

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 mean time 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 on 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 group label's direction (angular or radial). The aspect ratio of a label is computed by dividing the width and height of the label box (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 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 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 minimum font size to a large value may result in an empty title bar label or very unclear label ending in ellipsis

titleBarMaxFontSize

Maximum font size to draw the title bar's label. See 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 covers 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 rollout a new model into view. The value should be any of the following strings: implode, rollout, tumbler, fadein, random.

The following example demonstrates each of these effects.

var model = {groups: [
  { label: "implode" },
  { label: "rollout" },
  { label: "tumbler" },
  { label: "fadein" },
  { 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 pullback the current model from view. The value should be any of the following strings: explode, rollin, tumbler, fadeout, random.

The following example demonstrates each of these effects.

var model = {groups: [
  { label: "explode" },
  { label: "rollin" },
  { label: "tumbler" },
  { label: "fadeout" },
  { 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 sequential setting does not imply 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"
});