supported

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

if (CarrotSearchFoamTree.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 to visualize. The provided value must be an object or null / undefined. The object will be assumed to represent the root group and must contain a non-empty groups property pointing to an array of objects representing individual first-level groups. A null or undefined object clears the visualization.

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, exposure or open state.

label

(required, String) textual description of the group. For best results, use short labels.

FoamTree will handle the following special unicode characters in the label text:

Unbreakable space (\u00a0)

line breaks will not be made on the unbreakable space character

Soft hyphen (\u00ad)

when label needs to be broken into multiple lines, soft hyphen will allow a line break, generating the hyphen character at the end of the line. A soft hyphen will not add any spacing between the characters that surround it.

If you'd like to have your labels hyphenated, you can use an external hyphenation utility, such as Hyphenator.js to insert soft hyphens into your labels.

Zero-width space (\u200b)

when label needs to be broken into multiple lines, zero-width space will allow a line break. A zero-width space will not add any spacing between the characters that surround it.

New line (\n)

Since 3.4.0 forces a line break

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, FoamTree will assume the weight is 1.0.

groups

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

open

(optional, boolean) if true, the group will get open right after the new data is set.

exposed

(optional, boolean) if true, the group will get exposed right after the new data is set. This can be useful to visually highlight a certain group (or groups) as the data is loaded. Please note the limitations when relaxation is visible.

selected

(optional, boolean) if true, the group will get selected right after the new data is set.

description

Since 3.4.9 (optional, boolean) If true, descriptionGroup option is set to always and stacking is hierarchical, allocates extra space inside this group to show the group's label together with the group's child groups.

initialPosition

Since 3.4.10 (optional, object) Determines the initial position of this group. The object must contain two properties: position and distanceFromCenter. Please see the attributionPosition and attributionDistanceFromCenter options for semantics of the properties and the Initial positions demo for a complete code example.

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

foamtree.set({
  dataObject: {
    groups: [
      { label: "Bad news", open: true, groups: [
        { label: "Last penny lost", sentiment: -0.5 },
        { label: "Bazinga doomed",  sentiment: -1 }
        ]},
      { label: "Good news", exposed: true, selected: 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 the Data model and Carrot² models sections for examples of how to convert data that is not in FoamTree format.

hierarchy

Returns hierarchy-related information about a group. The returned object contains the following properties:

group

a reference to the data object representing the related group

parent

a reference to the data object representing the immediate parent of the group or null

level

the nesting level of the group. Level numbers start at 0.

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

hasChildren

true if the group has any child groups

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.

indexByWeight

Since 3.0.2 the position of the group relative to its siblings in the decreasing weight order, 0 index corresponds to the highest-weight group.

description

Since 3.4.0 true if the group represents the extra polygon holding group label in flattened stacking mode.

attribution

Since 3.3.1 true if the group is the attribution group.

To retrieve the information about a group, provide the individual group selector as the second parameter of the get method:

console.log(foamtree.get("hierarchy", "1"));

layout

Determines the general type of layout to generate. Depending on this option, FoamTree will produce polygon-based organic-looking visualization or the traditional rectangular tree map.

The following values are supported:

relaxed

produces polygonal organic-looking arrangements based on Voronoi diagrams. This type of layout tends to visualize groups as near-round polygons leaving plenty of space for the group's label and content. A potential downside of this layout is that it may not very well preserve the original order of groups provided in the data object. See the relaxationInitializer option for various possible representations of the group order in the relaxed layout.

ordered

produces the traditional rectangular treemap using the strip algorithm. The advantage of this layout is that, if layoutByWeightOrder is false, it will arrange groups in the left-to-right top-to-bottom fashion according to the order they were provided in the data object. One disadvantage of this algorithm is that certain groups may be visualized as high-aspect-ratio rectangles, which will leave little useful space for the label and contents of the group. You can use the rectangleAspectRatioPreference option to tune the aspect ratios of the rectangles to some extent.

squarified

produces the traditional treemap using the squarified algorithm. This layout arranges groups along the diagonal of the container. Aspect ratios of the rectangles produced by this method tend to be lower than the ones from the ordered layout. The squarified algorithm, however, does not lay out groups in the left-to-right fashion.

The following table summarizes the possible use cases for the specific layouts.

layoutByWeightOrder

When true, FoamTree will lay out the groups in the order of decreasing weight. When false, FoamTree will lay out the groups in the order they were provided in the dataObject.

Please see the layout option for information about how the order of groups can translate into their position in the visualization.

stacking

Determines how FoamTree will display nested groups. The following values are supported:

hierarchical

produces a layered view of the hierarchy. To be able to interact with lower-level groups, the user will need to open the parent group for browsing.

This is the default stacking mode and it is particularly useful for large deeply-nested hierarchies.

See the large hierarchy demo for an application of the hierarchical stacking mode.

flattened

produces a flattened view of the hierarchy. Groups of all levels are immediately available for interaction. This kind of stacking will work especially well with a rectangular layout.

Labels of parent groups are displayed in the dedicated area (towards the top of the polygon in the screenshot). Please see the descriptionGroup* options to customize that area. You may also need to implement a groupLabelLayoutDecorator to customize the label fitting options when fitting parent group descriptions.

See the FT500 explorer, SCADA dashboard or the Unit test coverage demo for an applications of the flattened stacking mode.

Note: Currently, the flattened stacking has the following limitation: the whole group hierarchy provided initially in the dataObject property is eagerly initialized, which may block the browser for a while when a large hierarchy is provided. To avoid the delay, consider lazy initialization of the lower levels of the hierarchy.

descriptionGroup

Determines when to draw an extra group label area.

auto

The extra label area will be drawn only when stacking is set to flattened.

always

The extra label area will be drawn for all groups when stacking is set to flattened. If stacking is set to hierarchical, each group that sets its description property to true will gets its label drawn both on top of the closed group and inside the group.

foamtree.set({
  descriptionGroup: "always",
  dataObject: {
    groups: [
      {
        label: "Group with a description area", description: true,
        groups: [{}, {}, {}, {}, {}, {}]
      },
      { label: "Group without a description area", groups: [{}, {}, {}] }
    ]
  }
});

You can use the extra area to draw longer group descriptions or to mix flattened and hierarchical stacking.

See the descriptionGroupType for different description area layout styles.

descriptionGroupType

Determines how FoamTree will assign space for the group label area in flattened stacking mode or when extra description space is requested by the descriptionGroup option. Two values are currently supported:

stab

Space for the description group is reserved by cutting a horizontal strip off the top or bottom of the group's polygon.

floating

Space for the description group is reserved among the child groups, following the current layout.

Please see the groupLabelLayoutDecorator option for a way to customize the label layout for the description group.

descriptionGroupSize

Note: applicable only when stacking is set to flattened.

The desired area of the description group, relative to the area of the parent polygon. The value of 1.0 means FoamTree will try to allocate the description group to be half of the area of the polygon.

descriptionGroupMinHeight

Note: applicable only when stacking is set to flattened and descriptionGroupType is stab.

Minimum height of the description group's bounding box, in pixels. Use this option to ensure some minimum height of the description group, so that there's reasonable space to fit the label.

descriptionGroupMaxHeight

Note: applicable only when stacking is set to flattened and descriptionGroupType is stab.

Maximum height of the description group's bounding box, relative to the height of the paren group's bounding box. Use this option to ensure that the description area does not take up too much of the parent polygon's area.

descriptionGroupPosition

Note: applicable only when stacking is set to flattened.

Determines the position of the description group inside the parent polygon. The allowed values for this option depend on the current descriptionGroupType:

stab

Two values are allowed: top and bottom, which will place the description group at the top or bottom of the parent polygon, respectively.

floating

Please see attributionPosition for a description of the allowed values.

descriptionGroupDistanceFromCenter

Note: applicable only when stacking is set to flattened and descriptionGroupType is floating.

Determines the distance of the description group from the center of the parent polygon. Please see attributionDistanceFromCenter for a description of the allowed values.

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.

foamtree.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 }
    ]
  }
});

foamtree.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 }
    ]
  }
});

groupMinDiameter

Minimum estimated diameter child groups must have in order to be drawn. To avoid illegible small labels and to speed up the rendering, FoamTree can be set to skip drawing child groups if their estimated diameter is smaller than groupMinDiameter. Setting the minimum group diameter to 0 will cause FoamTree to draw as many groups as possible groups given the maxGroups limit and the available floating point precision.

The following example sets a very large value for the groupMinDiameter option after a short delay. Observe that once the change is applied, the child groups disappear – their diameters were smaller than the threshold.

var timeout = setTimeout(function() {
  foamtree.set({
    groupMinDiameter: 500,

    // Set the data object again to apply the change
    dataObject: foamtree.get("dataObject")
  });
}, 2000);

maxGroups

The hard limit on the number of groups FoamTree will attempt to include in a single visualization. The limit is there to prevent excessive memory usage when browsing very deep hierarchies. The limit is applied in a breadth-first fashion, which means that if FoamTree needs to skip groups that do not fit within the limit, it will skip the groups at lower levels of the hierarchy.

rectangleAspectRatioPreference

Note: applicable only when layout is set to ordered or squarified.

Determines the desired aspect ratio of rectangles produced in the ordered and squarified layouts.

option value < 0

FoamTree will try to produce rectangles whose width is larger than the height. Such arrangement will make it slightly easier to fit labels into small rectangular groups.

option value > 0

FoamTree will prefer rectangles whose width is smaller than the height.

option value == 0

FoamTree will prefer rectangles of equal width and height.

geometry

Returns information about the geometry of the polygon representing a group or null if the group's polygon is not drawn. The returned object contains the following properties:

polygonCenterX

the X coordinate of the group's polygon. The coordinate is absolute, it does not take into account the transformations resulting from zooming, panning and exposure.

polygonCenterY

the Y coordinate of the group's polygon, absolute

polygonArea

the area of the group's polygon, absolute

boxLeft

the X coordinate of the top-left corner of the group polygon's bounding box, absolute

boxTop

the Y coordinate of the top-left corner of the group polygon's bounding box, absolute

boxWidth

width of the group polygon's bounding box, absolute

boxHeight

height of the group polygon's bounding box, absolute

labelFontSize

size of the font used to draw the group's label

labelBoxLeft

the X coordinate of the top-left corner of the group label's bounding box, absolute

labelBoxTop

the Y coordinate of the top-left corner of the group label's bounding box, absolute

labelBoxWidth

width of the group label's bounding box, absolute

labelBoxHeight

height of the group label's bounding box, absolute

polygon

an array of objects containing the X and Y coordinates of the groups polygon, in the clockwise order. All polygons produced by FoamTree are convex. The array is only returned if true is passed as the third parameter of the get method.

neighbors

Since 3.4.0 an array of references to the group objects corresponding to the neighbors of this group. The array is aligned with the polygon array: at an index corresponding to a polygon vertex, it contains the neighbor that shares the edge starting at the vertex and going clockwise. Please note that that some slots in the neighbor array may be null, which means the corresponding edge is the boundary of the visualization area. For a potential use case of this property, see the Background demo.

Note: The neighbors array is available only when the layout option is set to relaxed. The array is only returned if true is passed as the third parameter of the get method.

To retrieve the information about a group, provide the individual group selector as the second parameter of the get method.

console.log(foamtree.get("geometry", "1"));

To retrieve the full geometry information, including coordinates of the polygon's vertices, pass true as the third parameter of the get method:

console.log(foamtree.get("geometry", "1", true));

Please see the accuracy.html demo for an advanced code example that uses the geometry information to compute the accuracy with which polygon's areas correspond to the group's weights.

containerCoordinates

Converts the the provided visualization-area-relative point coordinates to the coordinates relative to the HTML container in which FoamTree is embedded. You can use this method to position additional HTML elements over specific shapes drawn inside some FoamTree group and ensure that the position will be correct regardless of zooming, panning and group exposure.

Two arguments are required to retrieve the container-relative coordinates:

• Individual group selector, passed as the second argument to the get method, identifying the FoamTree group in which the input point lies. FoamTree group is required because transformations, such as exposure, are applied on per-group basis, so the inverse coordinate transform needs to take into account the scale and offset of the specific transformed group.
• Visualization-area-relative coordinates of the point of interest, as an object with x and y properties, passed as the third argument to the get method. The coordinate space you will use here is the same as the on in which custom group content is drawn in groupContentDecorator.

The following example retrieves the container-relative coordinates of the center of some group.

var geometry = foamtree.get("geometry", "1");
console.log(foamtree.get("containerCoordinates", "1",
  { x: geometry.polygonCenterX, y: geometry.polygonCenterY }));

Tip: If your goal is to use this property to synchronize the position of some HTML element with a specific point inside FoamTree visualization, the best place to perform the synchronization is the onRedraw callback, which is called every time FoamTree is redrawn. This will ensure that you will have the chance to reposition the element on zoom, pan or exposure changes.

Please see the sticky-tooltips.html demo for a real-world usage of this property.

relaxationInitializer

Note: applicable only when layout is set to relaxed.

Determines the initial layout of groups' polygons. The following values are supported:

fisheye

puts large groups in the center of the visualization area and the smaller groups towards the corners

blackhole

puts small groups in the center of the visualization and the larger groups towards the corners

ordered

Since 3.3.0 lays out the groups in a left-to-right lines, in the order the groups were specified in the data object. This initializer creates layouts most similar to the ones generated by FoamTree 2.0.x.

squarified

puts large groups close to the top-left corner of the visualization and the small groups close to the bottom-right corner.

random

puts groups at random positions

The example below demonstrates the available initializers. Note that in order to apply a new initializer to the currently visible data, you need to set the dataObject option to trigger the layout update.

foamtree.set({
  dataObject: {
    groups: (function () {
      var arr = [
        { label: "fisheye", weight: 7 }, { label: "blackhole", weight: 6 },
        { label: "ordered", weight: 5 }, { label: "squarified", weight: 5 },
        { label: "random", weight: 4 }
      ];
      for (var i = 0; i < 100; i++) {
        arr.push({
          label: "",
          weight: 0.1 + Math.random() +
            (Math.random() < 0.2 ? Math.random() * 3 : 0)
        });
      }
      return arr;
    })()
  },

  relaxationVisible: true,         // show relaxation
  wireframeLabelDrawing: "always", // show labels during relaxation

  onGroupClick: function (event) {
    event.preventDefault();
    if (event.group.label) {
      this.set("relaxationInitializer", event.group.label);

      // Set the data object again to trigger layout update
      this.set("dataObject", this.get("dataObject"));
    }
  }
});

Since 3.1.0 You can also specify different layout initializers for each parent group separately by passing the initializer type in the relaxationInitializer property of the group's data object.

The following example demonstrates all of the available initializers in one visualization.

foamtree.set({
  dataObject: {
    groups: (function () {
      var initializers = [ "fisheye", "random", "ordered", "squarified", "blackhole" ];
      return initializers.map(function (i) {
        return {
          relaxationInitializer: i, // pass the initializer to use for this group
          label: i,
          groups: randomGroups(40)
        }
      });
    })()
  },

  relaxationVisible: true,         // show relaxation
  relaxationMaxDuration: 6000,     // make relaxation last longer
  relaxationQualityThreshold: 0.1,
  fadeDuration: 2000,              // use a simple fade-in
  rolloutDuration: 0,
  pullbackDuration: 0,
  wireframeLabelDrawing: "always"  // show labels during animation
});

relaxationVisible

Note: applicable only when layout is set to relaxed.

When set to true, FoamTree will show the intermediate steps of layout relaxation. For large data sets, when layout computation may take a few seconds, you may want to show the relaxation process to the users, so that they don't see the blank screen while waiting for the final visualization to be computed.

Layout relaxation and rollout animation can run in parallel. Alternatively, to let the user watch the layout stabilize, you may want to disable the rollout by setting rolloutDuration to 0 and fading in the visualization container by setting fadeDuration to 1000, for example.

foamtree.set({
  dataObject: {
    groups: (function () {
      var arr = [];
      for (var i = 0; i < 100; i++) {
        arr.push({
          label: "",
          weight: 0.1 + Math.random() +
            (Math.random() < 0.2 ? Math.random() * 3 : 0)
        });
      }
      return arr;
    })()
  },

  relaxationInitializer: "random",
  relaxationVisible: true,
  fadeDuration: 1000
});

When relaxation is visible, you can report the progress of the process to the user using the relaxation progress utility.

foamtree.set({
  dataObject: { groups: randomGroups(20) },
  relaxationVisible: true,
  fadeDuration: 1000,
  onRolloutComplete: function(progress, complete) {
    foamtree.expose(foamtree.get("dataObject").groups[0]);
  }
});

relaxationMaxDuration

Note: applicable only when layout is set to relaxed.

Determines the maximum duration of relaxation, in milliseconds. Depending on the complexity of the data set and the relaxationQualityThreshold, the relaxation may or may not complete before the specified timeout. If FoamTree needs to stop the relaxation because the alloted time has been exceeded, the quality of the layout may be lowered.

The following example sets a fairly short maximum relaxation duration. Observe how this lowers the quality of the layout by creating non-round, elongated polygons.

foamtree.set({
  dataObject: {
    groups: (function () {
      var arr = [];
      for (var i = 0; i < 100; i++) {
        arr.push({
          label: "",
          weight: 0.1 + Math.random() +
            (Math.random() < 0.2 ? Math.random() * 3 : 0)
        });
      }
      return arr;
    })()
  },

  relaxationInitializer: "random",
  relaxationVisible: true,
  relaxationMaxDuration: 100
});

relaxationQualityThreshold

Note: applicable only when layout is set to relaxed.

The desired layout quality to achieve during relaxation. High-quality layouts will consist of "round" polygons, lower-quality layouts will tend to contain more elongated, irregular shapes. The lower the value of the threshold, the higher the quality of the layout and the longer the layout computation time. If relaxationVisible is true, the desired quality level may not be achieved if the relaxationMaxDuration timeout is exceeded.

Setting relaxationQualityThreshold to 0 and relaxationMaxDuration to Number.MAX_VALUE will create the highest-quality layout possible, at the cost of long relaxation time. Setting relaxationQualityThreshold, regardless of the relaxation duration timeout will disable the relaxation leading to lower-quality layout, but faster computation. The following examples demonstrate the two opposite situations.

foamtree.set({
  dataObject: { groups: randomGroups(80) },
  relaxationInitializer: "fisheye",
  relaxationVisible: true,
  relaxationQualityThreshold: Number.MAX_VALUE
});

foamtree.set({
  dataObject: { groups: randomGroups(80) },
  relaxationInitializer: "fisheye",
  relaxationVisible: true,
  relaxationMaxDuration: Number.MAX_VALUE,
  relaxationQualityThreshold: 0
});

groupGrowingDuration

Note: applicable only when layout is set to relaxed.

The duration of the animation that grows the group to its final weight, in milliseconds. Applicable only when relaxationVisible is true.

foamtree.set({
  dataObject: { groups: randomGroups(80) },
  relaxationInitializer: "fisheye",
  relaxationVisible: true,
  groupGrowingDuration: 3000
});

groupGrowingEasing

Note: applicable only when layout is set to relaxed.

The easing function to use to grow group's weights. Meaningful only when groupGrowingDuration is larger than 0.

groupGrowingDrag

Note: applicable only when layout is set to relaxed.

The amount of delay to apply when growing subsequent groups on the same level of hierarchy. The delay will be computed by multiplying groupGrowingDuration by the value of this option. The first child group will start growing immediately, the second one after the computed delay, the third group will start growing after twice the delay and so on.

foamtree.set({
  dataObject: { groups: randomGroups(80) },
  relaxationInitializer: "fisheye",
  relaxationVisible: true,
  groupGrowingDuration: 2000,
  groupGrowingDrag: 0.2
});

groupResizingBudget

Note: applicable only when layout is set to relaxed.

Determines how many times FoamTree should attempt to set the desired size for the groups polygon. Depending on the characteristics of the input data, FoamTree may not be able to set the desired sizes of the polygons right away. Depending on the groupResizingBudget value, FoamTree will make several attempts to set the desired size during the course of relaxation.

Setting this option to 0 may cause large-weight groups to be rendered smaller than desired. Setting a large value of this option may lead to "jumpy" and time-consuming relaxation.

groupBorderRadius

Determines the amount of rounding to apply to polygon corners. Setting group border radius to 0 will produce straight corners, the value of 1.0 will produce near-to-oval shapes.

groupBorderWidth

Determines the width of the empty space between the sibling group polygons, in pixels.

groupBorderWidthScaling

The scaling factor to apply when drawing borders of child groups. Border with of a child group will be groupBorderWidthScaling smaller than the border width of the immediate parent group. Setting groupBorderWidthScaling to 1.0 will draw borders of equal widths on all levels of the group hierarchy.

groupInsetWidth

Determines the width of the empty space between the parent group's edge and its child groups' edges, in pixels.

groupBorderRadiusCorrection

The correction factor that ensures that the rounded parent group polygon covers all child group's polygons. For large groupBorderRadius values, it may sometimes happen that certain child polygons "stick out" of their parent group. In such cases, you can increase the groupBorderRadiusCorrection value to ensure proper rendering.

groupFillType

Determines the way the group polygons should be filled. The following values are possible:

none

the polygons will not be filled at all

plain

the polygons will be filled with one color; fast to render

gradient

the polygons will be filled with a two-color radial gradient; slower to render

groupFillGradientRadius

Determines the radius of the group-filling gradient.

groupFillGradientCenterHueShift

The amount of hue to add or subtract from the base group color hue to create the polygon-center end of the fill gradient.

groupFillGradientCenterSaturationShift

The amount of saturation to add or subtract from the base group color saturation to create the polygon-center end of the fill gradient.

groupFillGradientCenterLightnessShift

The amount of lightness to add or subtract from the base group color lightness to create the polygon-center end of the fill gradient.

groupFillGradientRimHueShift

The amount of hue to add or subtract from the base group color hue to create the polygon-edge end of the fill gradient.

groupFillGradientRimSaturationShift

The amount of saturation to add or subtract from the base group color saturation to create the polygon-edge end of the fill gradient.

groupFillGradientRimLightnessShift

The amount of lightness to add or subtract from the base group color lightness to create the polygon-edge end of the fill gradient.

groupStrokeType

Determines the way the group polygons edges should be drawn. The following values are possible:

none

the edges will not be drawn at all; fastest to render

plain

the edges will be drawn using one color; slower to render

gradient

the edges will be drawn using a two-color linear gradient; slowest to render

groupStrokeWidth

Determines the width of the group's edge, in pixels.

groupStrokePlainHueShift

The amount of hue to add or subtract from the base group color hue to create the color used for drawing the plain group's edge.

groupStrokePlainSaturationShift

The amount of saturation to add or subtract from the base group color saturation to create the color used for drawing the plain group's edge.

groupStrokePlainLightnessShift

The amount of lightness to add or subtract from the base group color lightness to create the color used for drawing the plain group's edge.

groupStrokeGradientRadius

The size of the linear gradient used to draw the polygon's edges, in relation to the polygon's size.

groupStrokeGradientAngle

The angle of the linear gradient used to draw the polygon's edges.

groupStrokeGradientUpperHueShift

The amount of hue to add or subtract from the base group color hue to create the upper-end color of the polygon edge's gradient.

groupStrokeGradientUpperSaturationShift

The amount of saturation to add or subtract from the base group color saturation to create the upper-end color of the polygon edge's gradient.

groupStrokeGradientUpperLightnessShift

The amount of lightness to add or subtract from the base group color lightness to create the upper-end color of the polygon edge's gradient.

groupStrokeGradientLowerHueShift

The amount of hue to add or subtract from the base group color hue to create the lower-end color of the polygon edge's gradient.

groupStrokeGradientLowerSaturationShift

The amount of saturation to add or subtract from the base group color saturation to create the lower-end color of the polygon edge's gradient.

groupStrokeGradientLowerLightnessShift

The amount of lightness to add or subtract from the base group color lightness to create the lower-end color of the polygon edge's gradient.

groupSelectionOutlineColor

Color of the outline stroke for the selected groups.

groupSelectionOutlineWidth

Width of the selection outline to draw around selected groups.

groupSelectionOutlineShadowSize

The size of the drop shadow to apply to the selection outline.

groupSelectionOutlineShadowColor

The color of the selection outline shadow.

groupSelectionFillHueShift

The amount of hue to add or subtract from the base fill color hue when the group is selected.

groupSelectionFillSaturationShift

The amount of saturation to add or subtract from the base fill color saturation when the group is selected.

groupSelectionFillLightnessShift

The amount of lightness to add or subtract from the base fill color lightness when the group is selected.

groupSelectionStrokeHueShift

The amount of hue to add or subtract from the base stroke color hue when the group is selected.

groupSelectionStrokeSaturationShift

The amount of saturation to add or subtract from the base stroke color saturation when the group is selected.

groupSelectionStrokeLightnessShift

The amount of lightness to add or subtract from the base stroke color lightness when the group is selected.

groupHoverFillHueShift

The amount of hue to add or subtract from the base fill color hue when the group is hovered on.

groupHoverFillSaturationShift

The amount of saturation to add or subtract from the base fill color saturation when the group is hovered on.

groupHoverFillLightnessShift

The amount of lightness to add or subtract from the base fill color lightness when the group is hovered on.

groupHoverStrokeHueShift

The amount of hue to add or subtract from the base stroke color hue when the group is hovered on.

groupHoverStrokeSaturationShift

The amount of saturation to add or subtract from the base stroke color saturation when the group is hovered on.

groupHoverStrokeLightnessShift

The amount of lightness to add or subtract from the base stroke color lightness when the group is hovered on.

groupLabelFontFamily

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

groupLabelFontStyle

Font style to use for drawing group labels. All CSS-compliant font styles are allowed, such as italic.

groupLabelFontWeight

Font weight to use for drawing group labels. All CSS-compliant font weights are allowed, such as bold.

groupLabelFontVariant

Font variant to use for drawing group labels. All CSS-compliant font variants are allowed, such as small-caps.

groupLabelMinFontSize

Minimum font size used for drawing group labels, in pixels.

Note that setting minimum font size to a large value may result in many labels being replaced with an ellipsis ("dots"), as in this example:

foamtree.set({
  dataObject: largeDataSet,
  groupLabelMinFontSize: 30,
  groupLabelMaxFontSize: 40
});

To force FoamTree to draw labels for all groups, set groupLabelMinFontSize to 0. This setting, however, may significantly slow down visualization rendering.

groupLabelMaxFontSize

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

groupLabelDecorator

Allows to customize or completely replace the default text of group labels. When labels are drawn, FoamTree will call the provided function once for each group (parent groups will be processed before children groups). The task of the function is to modify or completely replace the default label text. The custom label text will most likely be based on custom properties passed along with the data model.

The signature of the decorator callback should be the following:

function (options, properties, variables)

where:

options

all current visualization options (keys and values).

properties

an object with properties describing the group being decorated. The object will be a union of objects retrieved from the hierarchy, state and geometry options.

variables

object with label-related variables this function can change.

The following variables are available:

labelText

the default text of the label, equal to the label property of the group's data object.

The following example upper cases all group and adds angle quotes around them. Note how the quotes are separated from the main label by the non-breakable space unicode to ensure the quotes are not left as the only characters in the line. See the documentation for the dataObject option for a list of other special characters supported by FoamTree.

foamtree.set({
  groupLabelDecorator: function(opts, props, vars) {
    vars.labelText = "«\u00a0" + vars.labelText.toLocaleUpperCase() + "\u00a0»";
  }
});

groupLabelLineHeight

The line height to use when rendering labels in multiple lines.

groupLabelHorizontalPadding

The padding to add on the left and right of the label, in current font size unit.

groupLabelVerticalPadding

The padding to add on the top and bottom of the label, in current font size unit.

groupLabelMaxTotalHeight

The maximum total height of the label in relation to the height of the group's polygon.

groupLabelUpdateThreshold

Every time the geometry of the group's polygon changes, FoamTree needs to decide whether to re-layout the label text. The groupLabelUpdateThreshold determines how much must the area of the polygon change for FoamTree to re-layout the label. For example, if the value of the threshold is 0.05, FoamTree will re-layout the label when the area of the polygon is larger or smaller by 5% or more.

Setting groupLabelUpdateThreshold to 0 will cause FoamTree to re-layout the label on every group polygon change. Depending on the size of the data set, it may significantly slow down visualization rendering when relaxationVisible is true.

groupLabelColorThreshold

Picks the label color automatically depending on the group's color brightness. If the brightness is below this threshold groupLabelLightColor is used, otherwise groupLabelDarkColor 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.

groupLabelDarkColor

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

groupLabelLightColor

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

groupExposureScale

The magnification scale at which exposed groups will be drawn. If you set groupExposureScale to 1.0, exposed groups will be drawn at the same scale as the unexposed groups.

groupExposureShadowColor

The color of drop shadow to apply to exposed groups.

groupExposureShadowSize

The size of drop shadow to apply to exposed groups, in pixels.

groupExposureZoomMargin

The margin size to apply when zooming to the exposed group, relative to the group polygon's bounding box dimensions. If groupExposureZoomMargin is 0, the exposed group will occupy the full height / width of the view port. For larger values, a zoom margin will be added around the exposed group. The larger the value, the larger margin will be applied.

groupUnexposureLightnessShift

The amount of lightness to add or subtract from the groups base color's lightness when the group is unexposed.

groupUnexposureSaturationShift

The amount of saturation to add or subtract from the groups base color's saturation when the group is unexposed.

groupUnexposureLabelColorThreshold

The labelColorThreshold value to use for unexposed groups. When the colors of unexposed groups are significantly modified using the groupUnexposureLightnessShift and groupUnexposureSaturationShift options, you may want to modify this threshold to, for example, always draw the labels of unexposed groups in the dark color.

exposeDuration

The duration of the group exposure and unexposure animation.

exposeEasing

The easing function to use during group exposure and unexposure animations. Meaningful only when exposeDuration is larger than 0.

openCloseDuration

The duration of the group opening or closing animation.

parentFillOpacity

The opacity to use when filling groups that have child groups. By default, the parent group is drawn semi-transparent to indicate that the group has child groups that can be browsed. If you set parentFillOpacity to 1.0, the parent group will be fully opaque and the child groups will not be visible until the group gets open. If you set parentFillOpacity to 0.0, the parent group's polygon will not be filled at all and the child groups will be fully visible at all times.

parentStrokeOpacity

The opacity to use when drawing strokes of groups that have child groups.

parentLabelOpacity

The opacity to use when drawing labels of groups that have child groups.

parentOpacityBalancing

When set to true, FoamTree will try to equalize the opacity of groups' polygons, so that the aggregated opacity of, for example, a group with 3 levels of child groups and a group without child groups will be roughly the same. Opacity equalization will usually lead to a more uniform look of the whole visualization area.

Opacity balancing will only be applied when the base color of the group is not fully opaque, that is when its alpha component is less than 1.

rainbowStartColor

Start color to use if rainbow color model is used for coloring groups. The rainbow color model will radially or linearly spread the color hue among top-level groups, starting at rainbowStartColor and ending at rainbowEndColor. Sub-groups will be painted with the parent group's hue but with varying degrees of saturation and lightness.

For custom coloring of groups, use groupColorDecorator.

rainbowEndColor

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

rainbowColorDistribution

Determines how the rainbow colors will be distributed. You can use one of the following values:

radial

distributes the colors radially around the center of the visualization area

linear

distributes the colors linearly across the whole visualization area

You can use the rainbowColorDistributionAngle option to further tune the color distribution.

rainbowColorDistributionAngle

When rainbowColorDistribution is radial, determines the angle at which the rainbow color will start. Change the the values of this option, to rotate the rainbow around the central point of the visualization area.

When rainbowColorDistribution is linear, determines the angle of the linear gradient formed by the rainbow color transition.

rainbowLightnessDistributionAngle

Determines the angle of the linear gradient formed by the color lightness variations created for lower-level groups.

rainbowSaturationCorrection

When rainbowColorDistribution is radial, FoamTree can desaturate colors of the polygons lying close to the center of the visualization area to make the color transitions smoother.

You can use the rainbowLightnessCorrection option to vary the strength of this correction. The value of 0 will moderately decrease the saturation, the value of -1 will strongly desaturate the center groups. Finally, set the correction to 1 to disable correction decreases completely.

rainbowLightnessCorrection

When rainbowColorDistribution is radial, FoamTree can adjust the lightness of colors of the polygons lying close to the center of the visualization area to make the color transitions smoother.

You can use the rainbowLightnessCorrection option to vary the strength of this adjustment. The value of 0 means no adjustment. The value of -1 will strongly decrease the lightness of the center groups. Finally, the value of 1 will strongly increase the lightness of the central groups.

rainbowLightnessShift

Determines the strength of the color lightness variations applied to lower-level groups.

rainbowLightnessShiftCenter

Determines the central lightness value around which the lightness variations will be applied for the lower-level groups.

groupColorDecorator

A callback function you can use to customize or completely replace the default rainbow color model for groups. During each redraw, the visualization code 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 signature of the decorator callback should be the following:

function (options, properties, variables)

where:

options

all current visualization options (keys and values).

properties

an object with properties describing the group being decorated. The object will be a union of objects retrieved from the hierarchy, state and geometry options.

variables

an object with two properties: groupColor, containing the group color computed by the default rainbow color model, and labelColor always equal to auto. The callback function can either change some of the properties of groupColor or replace any of the colors with a new object representing the color to use.

The callback function can replace these values with a CSS3 color string (hsl, hsla, rgb or rgba color specification) or an 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 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.

Colors defined in the data model

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

foamtree.set({
  dataObject: {
    groups: [
      { label: "C", color: "#00aeef" },
      { label: "M", color: "#ec008c" },
      { label: "Y", color: "#fff200" },
      { label: "K", color: "#231f20" }
    ]
  },
  groupColorDecorator: function (opts, params, vars) {
    vars.groupColor = params.group.color;
    vars.labelColor = "auto";
  }
});

Colors depending on group state

By default, FoamTree modifies the base group color depending on the state of the group. This behaviour is determined by such properties as groupSelectionStrokeLightnessShift or groupHoverFillLightnessShift and usually makes the selected or hovered-on group lighter. To achieve even greater customization, you can use the group state information in the decorator:

foamtree.set({
  dataObject: {
    groups: [
      { label: "C", color: "#00aeef" },
      { label: "M", color: "#ec008c" },
      { label: "Y", color: "#fff200" },
      { label: "K", color: "#231f20" }
    ]
  },
  groupColorDecorator: function (opts, params, vars) {
    if (params.selected) {
      vars.groupColor = "#fff";
      vars.labelColor = params.group.color;
    } else {
      vars.groupColor = params.group.color;
      vars.labelColor = "#fff";
    }
  }
});

Colors derived from custom properties of the data model

Most commonly, polygon colors will depend on some domain-specific properties of the groups. For instance, if FoamTree is used to visualize a group of news stories and each story has been tagged with sentiment information (positive, negative, neutral), the color could reflect the sentiment. In the example shown below, we draw positive news in green, negative in red and neutral in grey.

foamtree.set({
  groupColorDecorator: 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 === undefined) {
      // 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);
      vars.groupColor.a = 0.5;
    }
    // Indicate that we use the HSLA model
    vars.groupColor.model = "hsla";
  },
  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 }
        ]}
    ]
  }
});

Animated colors

Finally, you can create an animated color model by making the color decorator a time-dependant function and periodically redrawing the visualization using the redraw method. The example below creates a simple radar-like animation. For faster drawing, we set groupFillType to plain and groupStrokeType to none.

running = false;

var frame = 0;
var running = true;
foamtree.set({
  groupColorDecorator: function(opts, params, vars) {
    // We change the color only for top-level groups. For child groups,
    // FoamTree will generate brightness variations of the parent group's color.
    if (params.level == 0) {
      var delay = 5;
      var count = 3;
      var frameDiv = Math.floor(frame / delay);
      var mod = frameDiv % params.siblingCount;
      var diff = (mod - params.index + params.siblingCount)
                   % params.siblingCount;
      if (diff < count) {
        vars.groupColor.g = 255 *
          (1 - ((diff * delay + frame % delay) / (delay * count)));
      } else {
        vars.groupColor.g = 40;
      }
      vars.groupColor.r = 40;
      vars.groupColor.b = 40;
      vars.groupColor.model = "rgb";
    }
  },
  dataObject: {
    groups: (function() {
      var arr = [];
      for (var i = 0; i < 50; i++) {
        arr.push({
          label: "",
          weight: Math.pow(Math.random(), 3) * 0.8 + 0.2,
          groups: [ { label: "" }, { label: "" }, { label: "" }]
        });
      }
      return arr;
    })()
  },
  groupFillType: "plain",
  groupStrokeType: "none"
});

// Redraw the visualization periodically. Although we use setTimeout()
// here, use the requestAnimationFrame() when possible.
setTimeout(function redraw() {
  if (!running) { // stopped?
    return;
  }
  foamtree.redraw(true);
  frame++;
  setTimeout(redraw, 16); // next frame
}, 16);

rolloutStartPoint

The point in the visualization container area at which the rollout will start. The following start point values are allowed:

center

rollout will start from the group lying closest to the center of the visualization container

topleft

rollout will start from the group lying closest to the top-left corner of the visualization container

bottomright

rollout will start from the group lying closest to the bottom-right corner of the visualization container

random

rollout will start from a random group

rolloutMethod

FoamTree will start the rollout animation from the group determined using the rolloutStartPoint option. Then, further polygons will be included in the animation, depending on the value of this option:

groups

on each animation step, all neighbors of the groups already being animated will be included in the animation, which will create a sort of ripple effect as shown in the following example.

foamtree.set({
  dataObject: { groups: randomGroups(200) },

  // Roll out in groups
  rolloutMethod: "groups",

  // Create a gentle scaling effect
  rolloutDuration: 6000,
  rolloutEasing: "bounce",
  rolloutScalingStrength: -0.4,
  rolloutRotationStrength: 0,
  rolloutPolygonDrag: 0.08
});

individual

on each animation step only one neighbor of the groups already being animated will be included in the animation. When using this rollout method, you may want to decrease rolloutPolygonDrag to make the animation progress smoother.

foamtree.set({
  dataObject: { groups: randomGroups(200) },

  // Roll out each group individually
  rolloutMethod: "individual",

  // Create a gentle scaling effect
  rolloutDuration: 4000,
  rolloutEasing: "bounce",
  rolloutScalingStrength: -0.4,
  rolloutRotationStrength: 0,
  rolloutPolygonDrag: 0.015
});

rolloutDuration

The duration of the rollout animation at one level of the hierarchy, in milliseconds. The duration of the complete animation is variable and depends on the number of hierarchy levels and the rolloutChildGroupsDrag and rolloutChildGroupsDelay options.

rolloutEasing

The animation easing function to use during rollout animation.

rolloutScalingStrength

Determines the initial scale to set for each polygon at the start of the rollout. During the rollout animation the initial scale will be transitioned to the neutral value.

When rolloutScalingStrength is -1, the initial scale will be minus infinity making the polygon appear at infinite distance in front of the user. When rolloutScalingStrength is 1, the initial scale will be plus infinity making the polygon appear at infinite distance behind the user. All intermediate values are allowed and will set the initial scale to the appropriate proportion between the extremes. When rolloutScalingStrength is 0, the initial scale will be equal to the neutral scale.

The following examples demonstrate the rollout animation for negative and positive values of the rolloutScalingStrength option. Both examples set rolloutTransformationCenter to 0 so that the origin of the scaling is the center of the visualization container.

foamtree.set({
  dataObject: { groups: randomGroups(100) },

  rolloutScalingStrength: -0.5,

  rolloutDuration: 4000,
  rolloutRotationStrength: 0,
  rolloutTransformationCenter: 0
});

foamtree.set({
  dataObject: { groups: randomGroups(100) },

  rolloutScalingStrength: 1,

  rolloutDuration: 4000,
  rolloutRotationStrength: 0,
  rolloutTransformationCenter: 0
});

foamtree.set({
  dataObject: largeDataSet,

  rolloutScalingStrength: 0.5,

  rolloutDuration: 4000,
  rolloutRotationStrength: 0,
  rolloutTransformationCenter: 0
});

rolloutTranslationXStrength

Determines the initial horizontal translation to apply to each polygon at the start of the rollout. The rollout animation will transition the initial translation to the neutral value. The unit of the translation is the width of the parent polygon's bounding box. Fox example, the value of -0.5 means the translation to the left by half of the width of the parent box.

rolloutTranslationYStrength

Determines the initial vertical translation to apply to each polygon at the start of the rollout. The rollout animation will transition the initial translation to the neutral value. The unit of the translation is the height of the parent polygon's bounding box. Fox example, the value of 0.5 means the translation to the bottom by half of the height of the parent box.

rolloutRotationStrength

Determines the initial rotation to apply to each polygon at the start of the rollout. The rollout animation will transition the initial rotation to the neutral value. Rotation of 1.0 means 180 degrees clockwise.

rolloutTransformationCenter

Determines the point relative to which the rollout transformations will be taken. The value of 0.0 means the center of the parent group's polygon, 1.0 means the center of the currently animated polygon. Intermediate values set the transformation center at the appropriate linear combination of the above extremes.

The following examples demonstrate the difference between the rolloutTransformationCenter extremes.

foamtree.set({
  dataObject: { groups: randomGroups(100) },

  rolloutTransformationCenter: 0,

  rolloutDuration: 4000,
  rolloutRotationStrength: -0.3,
  rolloutScalingStrength: 0,
  rolloutEasing: "squareInOut"
});

foamtree.set({
  dataObject: { groups: randomGroups(100) },

  rolloutTransformationCenter: 1,

  rolloutDuration: 4000,
  rolloutRotationStrength: -0.3,
  rolloutScalingStrength: 0,
  rolloutEasing: "squareInOut"
});

rolloutPolygonDrag

The amount of delay to apply before starting the rollout of subsequent groups on the same level of hierarchy. The delay will be computed by multiplying rolloutDuration by the value of this option.

rolloutPolygonDuration

Determines the duration of the polygon rollout animation, as a fraction of rolloutDuration.

rolloutLabelDelay

Determines the delay to apply before showing the group's label during rollout, as a fraction of rolloutDuration.

Note that when wireframeLabelDrawing is set to never, group labels will not be drawn at all during rollout. When wireframeLabelDrawing is set to auto, labels may or may not be drawn during the rollout, depending on the performance of the device and the size of the data set. To force FoamTree to draw labels during the rollout animation, set wireframeLabelDrawing to always.

rolloutLabelDrag

The amount of delay to apply before revealing the labels of subsequent groups on the same level of hierarchy. The delay will be computed by multiplying rolloutDuration by the value of this option.

rolloutLabelDuration

Determines the duration of the label fading-in animation, as a fraction of rolloutDuration.

rolloutChildGroupsDelay

The amount of delay to apply before starting the rollout of child groups of a parent group, as a fraction of rolloutDuration. If you set rolloutChildGroupsDelay to 0, groups at all levels will start their rollout animations at the same time.

rolloutChildGroupsDrag

The amount of delay to apply before starting the rollout of child groups of subsequent parent groups groups on the same level of hierarchy. The delay will be computed by multiplying rolloutDuration by the value of this option.

pullbackStartPoint

The point in the visualization container area at which the pullback will start. The following start point values are allowed:

center

pullback will start from the group lying closest to the center of the visualization container

topleft

pullback will start from the group lying closest to the top-left corner of the visualization container

bottomright

pullback will start from the group lying closest to the bottom-right corner of the visualization container

random

pullback will start from a random group

pullbackMethod

FoamTree will start the pullback animation from the group determined using the pullbackStartPoint option. Then, further polygons will be included in the animation, depending on the value of this option:

groups

on each animation step, all neighbors of the groups already being animated will be included in the animation, which will create a sort of ripple effect as shown in the following example.

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(200) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    // Roll out in groups
    pullbackMethod: "groups",

    // Create a gentle scaling effect
    pullbackDuration: 3000,
    pullbackEasing: "quadOut",
    pullbackScalingStrength: -0.4,
    pullbackRotationStrength: 0,
    pullbackPolygonDrag: 0.08
  });
}, 1000);

individual

on each animation step only one neighbor of the groups already being animated will be included in the animation. When using this rollout method, you may want to decrease rolloutPolygonDrag to make the animation progress smoother.

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(200) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    // Roll out in groups
    pullbackMethod: "individual",

    // Create a gentle scaling effect
    pullbackDuration: 3000,
    pullbackEasing: "quadOut",
    pullbackScalingStrength: -0.4,
    pullbackRotationStrength: 0,
    pullbackPolygonDrag: 0.015
  });
}, 1000);

pullbackDuration

The duration of the pullback animation, in milliseconds.

pullbackEasing

The animation easing function to use during pullback animation.

pullbackScalingStrength

Determines the target scale for each polygon to achieve at the end of the pullback animation.

When pullbackScalingStrength is -1, the target scale will be minus infinity making the polygon appear at infinite distance in front of the user. When pullbackScalingStrength is 1, the target scale will be plus infinity making the polygon appear at infinite distance behind the user. All intermediate values are allowed and will set the target scale to the appropriate proportion between the extremes. When pullbackScalingStrength is 0, the target scale will be equal to the neutral scale.

The following examples demonstrate the pullback animation for negative and positive values of the pullbackScalingStrength option. Both examples set pullbackTransformationCenter to 0 so that the origin of the scaling is the center of the visualization container.

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(200) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    pullbackScalingStrength: -0.5,

    pullbackDuration: 2500,
    pullbackEasing: "quadIn",
    pullbackRotationStrength: 0,
    pullbackTransformationCenter: 0
  });
}, 1000);

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(200) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    pullbackScalingStrength: 0.5,

    pullbackDuration: 2500,
    pullbackEasing: "quadOut",
    pullbackRotationStrength: 0,
    pullbackTransformationCenter: 0
  });
}, 1000);

pullbackTranslationXStrength

Determines the target horizontal translation for each polygon to achieve at the end of the pullback animation. The unit of the translation is the width of the parent polygon's bounding box. Fox example, the value of -0.5 means the translation to the left by half of the width of the parent box.

pullbackTranslationYStrength

Determines the target vertical translation for each polygon to achieve at the end of the pullback animation. The unit of the translation is the height of the parent polygon's bounding box. Fox example, the value of 0.5 means the translation to the bottom by half of the height of the parent box.

pullbackRotationStrength

Determines the target rotation for each polygon to achieve at the end of the pullback animation. Rotation of 1.0 means 180 degrees clockwise.

pullbackTransformationCenter

Determines the point relative to which the pullback transformations will be taken. The value of 0.0 means the center of the parent group's polygon, 1.0 means the center of the currently animated polygon. Intermediate values set the transformation center at the appropriate linear combination of the above extremes.

The following examples demonstrate the difference between the pullbackTransformationCenter extremes.

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(100) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    pullbackTransformationCenter: 0,

    pullbackDuration: 4000,
    pullbackRotationStrength: -0.3,
    pullbackScalingStrength: 0,
    pullbackEasing: "cubicInOut"
  });
}, 1000);

// Set initial data
foamtree.set({
  dataObject: { groups: randomGroups(100) }
});

// Pull back after a while
var timeout = setTimeout(function() {
  foamtree.set({
    dataObject: null,

    pullbackTransformationCenter: 1,

    pullbackDuration: 4000,
    pullbackRotationStrength: -0.3,
    pullbackScalingStrength: 0,
    pullbackEasing: "cubicInOut"
  });
}, 1000);

pullbackPolygonDelay

The pullback animation will first start hiding groups labels and after a delay the hiding of the polygons will start. This option determines the delay to apply before hiding of the polygons starts. The delay is specified as a fraction of pullbackDuration.

pullbackPolygonDrag

The amount of delay to apply before starting the pullback of subsequent groups on the same level of hierarchy. The delay will be computed by multiplying pullbackDuration by the value of this option.

pullbackPolygonDuration

Determines the duration of the polygon pullback animation, as a fraction of pullbackDuration.

pullbackLabelDelay

Determines the delay to apply before hiding group labels during pullback, as a fraction of pullbackDuration.

pullbackLabelDrag

The amount of delay to apply before hiding the labels of subsequent groups on the same level of hierarchy. The delay will be computed by multiplying pullbackDuration by the value of this option.

pullbackLabelDuration

Determines the duration of the label fading-out animation, as a fraction of pullbackDuration.

pullbackChildGroupsDuration

Determines the duration of the sub-group fading-out animation, as a fraction of pullbackDuration.

pullbackChildGroupsDelay

Determines the delay to apply before hiding sub-groups during pullback, as a fraction of pullbackDuration.

pullbackChildGroupsDrag

The amount of delay to apply before hiding the subgroups of subsequent parent groups on the same level of hierarchy. The delay will be computed by multiplying pullbackDuration by the value of this option.

fadeDuration

The duration of the fade-in/out animation, in milliseconds. The fading in/out is applied only when rolloutDuration / pullbackDuration is 0, otherwise the value of this option is ignored. Set this option to 0 to disable fading.

fadeEasing

The easing function to use when performing the fading animation.

zoomMouseWheelFactor

The magnification factor to apply when the user zooms in using the mouse wheel. When zooming out, the factor will be 1 /zoomMouseWheelFactor.

zoomMouseWheelDuration

The duration of the zoom-in/out animation, in milliseconds.

zoomMouseWheelEasing

The easing function to apply to the zoom animation.

titleBarFontFamily

Font family for the title bar, 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 groupLabelFontFamily will be used.

This example renders the title bar in monospace font.

foamtree.set({
  dataObject: { groups: [
    { label: "ABC123", selected: true },
    { label: "DEF456" }]},
  titleBar: "inscribed",
  titleBarFontFamily: "monospace",
  maxLabelSizeForTitleBar: Number.MAX_VALUE,
  groupLabelFontFamily: "Arial, sans-serif"
});

titleBarFontStyle

Font style for the title bar, if shown. CSS-compliant font style specifications are supported, such as italic. If not specified, groupLabelFontStyle will be used.

titleBarFontWeight

Font weight for the title bar, if shown. CSS-compliant font weight specifications are supported, such as bold. If not specified, groupLabelFontWeight will be used.

titleBarFontVariant

Font variant for the title bar, if shown. CSS-compliant font variant specifications are supported, such as small-caps. If not specified, groupLabelFontVariant will be used.

titleBarMinFontSize

Minimum font size to use when drawing the title bar's label, in pixels.

Note that setting minimum font size to a large value may result in an empty title bar.

titleBarMaxFontSize

Maximum font size to draw the title bar's label, in pixels.

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.

titleBarDecorator

Allows to customize or completely replace the text displayed in the title bar. By default, FoamTree will display the group's label, but you can use this option to display a different text, e.g. some more details related to the group.

The decorator will be called every time the user's pointer hovers over a group. The signature of the decorator callback should be the following:

function (options, properties, variables)

where:

options

all current visualization options (keys and values).

properties

an object with properties describing the group the user is hovering over. The object will be a union of objects retrieved from the hierarchy, state and geometry options.

Additionally, the following title-bar-specific properties are available:

titleBarWidth

the width of the title bar area, in pixels

titleBarHeight

the height of the title bar area, in pixels

labelFontSize

the font size used to draw the actual group label or 0 if the label is not drawn

viewportScale

Since 3.1.0 the current viewport scale. Values larger than 1 mean the viewport is zoomed-in, values smaller than 1 mean the viewport is zoomed-out, a value of 1 means the viewport is at its neutral zoom level.

variables

object with title-bar-related variables this function can change.

The following variables are available:

titleBarText

the default text for the title bar, equal to the label of the group. If changed to null or undefined, the title bar will not be shown.

titleBarShown

true if the group's label is small enough for the title bar to show, false otherwise. You can change the value of this variable to force showing or hiding of the title bar.

titleBarMaxFontSize

the maximum font size to be used for drawing text in the title bar, by default equal to the titleBarMaxFontSize option. Change this variable to override the the max font size for the currently rendered title bar.

The following example shows how to use the title bar decorator to display more details about the group. A similar complete example can be found in titlebar-details.html.

foamtree.set({
  maxLabelSizeForTitleBar: Number.MAX_VALUE,

  titleBarDecorator: function(options, parameters, variables) {
    variables.titleBarText = "More details about " + parameters.group.label;
  }
});

The following example shows how to force showing of the title bar for specific groups.

foamtree.set({
  titleBarDecorator: function(options, parameters, variables) {
    var groupId = parameters.group.id;
    if (groupId === "1" || groupId === "2") {
      variables.titleBarShown = true;
    }
  }
});

maxLabelSizeForTitleBar

Maximum group label size in pixels whose label to show in the title bar. Small size of a group may cause its label to be drawn in a small font and thus appear illegible. For this reason, when the user hovers the mouse pointer over a group with a small label, the label can be shown in a dedicated title bar.

The maxLabelSizeForTitleBar defines the threshold below which group labels will be shown in the title bar. Setting maxLabelSizeForTitleBar to 0 will disable the title bar completely. Setting the option to Number.MAX_VALUE will cause the title bar to appear for all groups.

attributionText

The label of the attribution group. If attributionText or attributionLogo is not empty, an extra group is added to the visualization with the provided text and logo. If attributionUrl is not empty, clicking the attribution group will open the provided URL in the browser.

attributionLogo

The image to display in the attribution group. The image can be specified as a relative or absolute HTTP URL or a data URI. When using HTTP URLs, the image should to be preloaded before visualization is embedded, otherwise it may not be immediately visible. For this reason, the data URIs are recommended. You can use services like dataurl.net to convert your images to data URIs.

Since version 3.3.1, this option also accepts the Image instances. With this enhancement, you can render an SVG attribution logo that will look well regardless of the zoom level.

var logoImage = new Image();
logoImage.src = "../demos/assets/img/logo-stub.png";
logoImage.addEventListener("load", function() {
  // Trigger a reload to show the logo
  foamtree.set("attributionLogo", logoImage.src);
  foamtree.set("dataObject", foamtree.get("dataObject"));
});

attributionLogoScale

Determines the scale at which FoamTree should draw the attribution logo. The scale is relative to the bounding box of the group's polygon. A scale of 1.0 means the logo will take the whole available width or height.

attributionUrl

The URL to open when the user clicks the attribution group, can be undefined.

attributionWeight

Sets the weight of the attribution group in relation to the total weight of the root-level groups. You can use this option to influence the size of the attribution group.

attributionPosition

Determines the position of the attribution group relative to the visualization container. The following values are supported:

topleft

top-left corner of the visualization container

topright

top-right corner of the visualization container

bottomleft

bottom-left corner of the visualization container

bottomright

bottom-right corner of the visualization container

top

top side of the visualization container

bottom

bottom side of the visualization container

left

left side of the visualization container

right

right side of the visualization container

random

a random point on the perimeter of the visualization container

number in the [0, 360) range

The angle (in degrees) that determines position on the perimeter of the visualization container, clockwise, starting at the right hand side of the container. For example: 0 is the right-hand side of the container, 45 is the bottom-right corner, 90 is the bottom side of the container etc.

Note: When layout is ordered or squarified, only the topleft and bottomright attribution group placement is supported. All other values will result in the group being placed in the bottom-right corner of the visualization area.

Note: when there is a small number of groups in the visualization, FoamTree may not be able to place the attribution group exactly at the required point.

The following example places the attribution group in the top-right corner of the visualization.

foamtree.set("attributionPosition", 360 - 45);
foamtree.set("dataObject", { groups: randomGroups(25, 1) } );

attributionDistanceFromCenter

Note: applicable only when layout is set to relaxed.

Determines the distance of the attribution group from the center of the visualization area. The distance of 0 puts the attribution group in the center of the visualization, the distance of 1 puts the attribution group near the perimeter of the visualization area.

Please note that when there is a small number of groups in the visualization, FoamTree may not be able to place the attribution group exactly at the required point.

The following example attempts to place the attribution group near the center of the visualization area.

foamtree.set("attributionDistanceFromCenter", 0);
foamtree.set("dataObject", { groups: randomGroups(25, 1) } );

attributionTheme

Determines the color of the attribution group. Currently, two values are supported:

light

Attribution group will be drawn in a light color.

dark

Attribution group will be drawn in a dark color.

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.

If the pixel ratio is changed after FoamTree has initialized, you will need to call redraw for the change to be applied.

The following examples demonstrate the difference between a pixel ratio higher and lower than the pixel resolution.

foamtree.set({
  dataObject: largeDataSet,
  pixelRatio: 0.5
});
foamtree.redraw();

foamtree.set({
  dataObject: largeDataSet,
  pixelRatio: 2
});
foamtree.redraw();

wireframePixelRatio

The pixel ratio to use when drawing animations, such as rollout, pullback, expose or zooming. You can change the default to a higher value (e.g. 2 on Retina displays) to have the animation drawn in more detail, but noticeably slower. You can also set this option to a lower value, e.g. 0.5 to have the animation drawn faster, but with less detail. Please see the pixelRatio option for detailed considerations on how the pixel ratio value affects the sizes of the canvases allocated by FoamTree.

groupContentDecorator

A callback function you can use to customize or completely replace the way group polygons' content is drawn. The task of the function is to render the contents by invoking the appropriate drawing methods on the provided drawing context that behaves like the standard CanvasRenderingContext2D.

The signature of the decorator callback should be the following:

function (options, properties, variables)

where:

options

all current visualization options (keys and values).

properties

an object with properties describing the group being rendered. The object will be a union of objects retrieved from the hierarchy, state and geometry options.

Additionally, a number of shape-decorator-specific properties are available.

variables

object with a number of variables this decorator can change.

The following variables are available:

groupLabelDrawn

set to false to skip rendering of the default group's label; true by default.

groupPolygonDrawn

set to false to skip rendering of the polygon corresponding to the group; true by default.

foamtree.set({
  rolloutDuration: 3000,
  dataObject: largeDataSet,

  // Our custom drawing depends on the group state,
  // therefore we need to use the "onSurfaceDirty" triggering.
  groupContentDecoratorTriggering: "onSurfaceDirty",

  // Our custom drawing is pretty fast, so we can draw it during animations
  wireframeContentDecorationDrawing: "always",

  // Our custom drawing callback
  groupContentDecorator: function (opts, params, vars) {
    var ctx = params.context;
    var centerX = params.polygonCenterX;
    var centerY = params.polygonCenterY;

    // Compute pie chart radius
    var radius = CarrotSearchFoamTree.geometry.circleInPolygon(
      params.polygon, centerX, centerY) * 0.8;

    // Increase opacity of the pie chart on hover
    var baseAlpha = (params.hovered ? 2 : 1);

    // Increase stroke width on selection,
    // use thinner lines on lower hierarchy levels
    ctx.lineWidth = (params.selected ? 3.0 : 1.5) * Math.pow(0.5, params.level);

    // The black part of the pie chart
    ctx.beginPath();
    ctx.moveTo(centerX, centerY);
    ctx.arc(centerX, centerY, radius, 0, 2 * Math.PI * params.group.rank);
    ctx.closePath();
    ctx.strokeStyle = rgba("0, 0, 0", baseAlpha * 0.2);
    ctx.stroke();
    ctx.fillStyle = rgba("0, 0, 0", baseAlpha * 0.1);
    ctx.fill();

    // The white part of the pie chart
    ctx.beginPath();
    ctx.arc(centerX, centerY, radius, 2 * Math.PI * params.group.rank, 0);
    ctx.strokeStyle = rgba("255, 255, 255", baseAlpha * 0.2);
    ctx.stroke();
    ctx.lineTo(centerX, centerY);
    ctx.fillStyle = rgba("255, 255, 255", baseAlpha * 0.2);
    ctx.fill();

    function rgba(rgb, alpha) {
      return "rgba(" + rgb + ", " + alpha + ")";
    }
  },

  // Generates some random data we'll display in the pie chart
  onModelChanged: function (data) {
    enhance(data);

    function enhance(group) {
      group.rank = 0.1 + Math.random() * 0.9;
      if (group.groups) {
        group.groups.forEach(enhance);
      }
    }
  }
});

foamtree.set({
  dataObject: largeDataSet,

  // Our custom drawing callback
  groupContentDecorator: function (opts, params, vars) {
    var ctx = params.context;
    var centerX = params.polygonCenterX;

    // We want to put the extra label inside a semi transparent rectangle.
    // To do this, we need to draw the rectangle first and then the label.
    // The dimensions of the rectangle are returned by the fillPolygonWithText()
    // method, so to get the right drawing order, we need to draw the text
    // to a scratch buffer, draw the rectangle and then draw the text we
    // saved in the scratch buffer.
    var scratch = ctx.scratch();

    var info = scratch.fillPolygonWithText(
      // Fit the extra text inside the main polygon
      params.polygon,

      // Fit the extra text below the main label
      centerX, params.labelBoxTop + params.labelBoxHeight,

      // use non-breakable space to prevent line breaks
      params.group.weight + "\u00a0docs",

      {
        maxFontSize: 0.6 * params.labelFontSize, // restrict max font size
        verticalAlign: "top", // flow the text downwards from the center point
        verticalPadding: 0.1, // use some smaller than default padding
        maxTotalHeight: 1 // use the full available height
      });

    // Draw the rectangle. FoamTree already set for us the color
    // it used to draw the label, we'll use that color.
    if (info.fit) {
      var labelBox = info.box;
      var boxMargin = labelBox.h * 0.1;
      ctx.roundRect(labelBox.x - 2 * boxMargin, labelBox.y - boxMargin,
        labelBox.w + 4 * boxMargin, labelBox.h + 2 * boxMargin, boxMargin * 2);

      ctx.globalAlpha = 0.15;
      ctx.fill();
      ctx.globalAlpha = 0.25;
      ctx.lineWidth = boxMargin * 0.3;
      ctx.stroke();

      // Draw the text from our scratch buffer
      ctx.globalAlpha = 1.0;
      scratch.replay(ctx);
    }
  }
});

groupContentDecoratorTriggering

Determines when the groupContentDecorator will be triggered:

onShapeDirty

The shape decorator will only be triggered if the shape of the group's polygon changes, for example during the relaxation process or after resizing of the visualization area. During redraws in which the shape of the polygon is not changing, such as when zooming or drawing selection outline, FoamTree will "replay" the custom drawing commands issued by the last invocation of the shape decorator, which will improve the rendering performance.

Use this triggering mode when the custom content of the group does not depend on the state of the group (selected, hovered) and thus the group shape decorator does not need to be called when group state changes.

onSurfaceDirty

The shape decorator will be triggered every time the group's polygon needs to be drawn. Use this triggering mode if your custom content drawing depends on the state of the group (selected, hovered). Depending on the complexity of your custom drawing code, using this triggering mode may result in lower rendering performance.

wireframeLabelDrawing

Determines whether FoamTree should draw group labels during animation. The following values are allowed:

auto

FoamTree will try to automatically enable or disable drawing of labels based on the performance of the browser and the size of the data set to meet the limit set in wireframeDrawMaxDuration.

always

labels will always be drawn during animations, regardless of the wireframeDrawMaxDuration limit.

never

labels will never be drawn during animations, regardless of the wireframeDrawMaxDuration limit.

wireframeContentDecorationDrawing

Determines whether FoamTree should draw the group content decorations produced by the groupContentDecorator during animation. The following values are allowed:

auto

FoamTree will try to automatically enable or disable drawing of group content decorations based on the performance of the browser and the size of the data set to meet the limit set in wireframeDrawMaxDuration.

For the purposes of this calculation FoamTree will assume that the custom shapes drawn by the groupContentDecorator are as expensive to draw as labels. If the custom drawing does not contain any text and/or is fast to draw, you can set this option to always.

always

group content decorations will always be drawn during animations, regardless of the wireframeDrawMaxDuration limit.

never

group content decorations will never be drawn during animations, regardless of the wireframeDrawMaxDuration limit.

groupLabelLayoutDecorator

A callback function you can use to customize how the label of a specific group is laid out, including the font, size and paddings.

The signature of the decorator callback should be the following:

function (options, properties, variables)

where:

options

all current visualization options (keys and values).

properties

an object with properties describing the group being rendered. The object will be a union of objects retrieved from the hierarchy, state and geometry options.

variables

object with a number of variables this decorator can change. The following variables are available:

fontFamily

See fontFamily in fillPolygonWithText().

fontStyle

See fontFamily in fillPolygonWithText().

fontVariant

See fontVariant in fillPolygonWithText().

fontWeight

See fontWeight in fillPolygonWithText().

lineHeight

See lineHeight in fillPolygonWithText().

horizontalPadding

See horizontalPadding in fillPolygonWithText().

verticalPadding

See verticalPadding in fillPolygonWithText().

maxTotalTextHeight

See fontFamily in fillPolygonWithText().

maxFontSize

See maxFontSize in fillPolygonWithText().

One use case for this callback is lowering label padding for description groups for flattened stacking as demonstrated by the following example.

foamtree.set({
  dataObject: largeDataSet,
  stacking: "flattened",
  groupLabelLayoutDecorator: function (opts, props, vars) {
    if (props.description) {
      // Lower padding
      vars.verticalPadding = 0.1;

      // Allow the label to take the full
      // height of the description group
      vars.maxTotalTextHeight = 1.0;

      // Render description labels in bold
      vars.fontWeight = "700";
    }
  }
});

descriptionGroupPolygonDrawn

Note: applicable only when stacking is set to flattened.

When true, the polygon corresponding to the description group will be drawn. By default, the polygon is not drawn to make an impression that the description group is linked to the parent polygon.

maxGroupLevelsDrawn

The maximum number of levels of closed groups FoamTree will draw. For hierarchies with more than maxGroupLevelsDrawn levels, the lower-level groups will not be drawn until the appropriate number of their parent groups get open. If your data set contains many levels of groups with many children on each level, you may want to lower the value of this option to speed up layout computation and rendering at the cost of lower amount of visible detail.

The following example generates a random 10-level hierarchy with 2 groups at each level, sets the initial maxGroupLevelsDrawn to 1 so that only the top-level groups are drawn. Then, once a second, the code will increment maxGroupLevelsDrawn to demonstrate that lower-level groups will indeed be drawn. Additionally, the code will gradually lower the parentFillOpacity, so that the lower-level groups are more clearly visible. Finally, the example sets groupMinDiameter to 0 so that as many groups are possible fit on the screen.

foamtree.set({
  // Lower groupMinDiameter to fit as many groups as possible
  groupMinDiameter: 0,

  // Start with drawing just the top-level groups
  maxGroupLevelsDrawn: 1,

  // Generate a 10-level hierarchy
  dataObject: { groups: randomGroups(2, 10 /* levels */) }
});

// Initiate revealing of lower levels
var timeout;
(function reveal() {
  timeout = window.setTimeout(function () {
    var levels = foamtree.get("maxGroupLevelsDrawn") + 1;
    foamtree.set("maxGroupLevelsDrawn", levels);
    foamtree.set("parentFillOpacity", foamtree.get("parentFillOpacity") * 0.8);
    foamtree.redraw();
    if (levels < 10) {
      reveal();
    }
  }, 1000);
})();

maxGroupLabelLevelsDrawn

The maximum number of levels of group labels FoamTree will draw. For hierarchies with more than maxGroupLabelLevelsDrawn levels, only the top specified number of open groups will have their labels drawn. You can lower the default value of this option for faster rendering of the visualization at the cost of lower amount of visible detail.

The following example generates and visualizes a random 10-level hierarchy with 2 groups at each level. Click and hold on the groups to open them and observe how deeper level polygons and labels get revealed.

foamtree.set({
  // Lower groupMinDiameter to fit as many groups as possible
  groupMinDiameter: 0,

  // Draw 2 levels of labels and 4 levels of group polygons
  maxGroupLevelsDrawn: 4,
  maxGroupLabelLevelsDrawn: 2,

  // Tune the border options to make them more visible
  parentFillOpacity: 0.3,
  parentStrokeOpacity: 1.0,
  groupBorderRadius: 0,
  groupBorderWidth: 3,
  groupBorderWidthScaling: 0.8,

  // Generate a 10-level hierarchy
  dataObject: { groups: randomGroups(2, 10 /* levels */) },

  // Always draw the same "label"
  groupLabelDecorator: function (opts, params, vars) {
    vars.labelText = params.level;
  }
});

maxGroupLevelsAttached

The maximum number of group levels for which to compute layout when new dataObject is set. Combined with the attach method, this option can be used to improve the responsiveness of FoamTree when visualizing deeply-nested hierarchies with large numbers of groups on the top level.

For more details and examples, see the attach method and the Deferred layout of child groups demo.

incrementalDraw

Determines how FoamTree decides whether to apply incremental visualization redraws. The following values are supported:

fast

FoamTree will try to redraw as few groups as possible when an incremental update is possible. With typical settings, this procedure will result in quick updates and no visual artifacts.

In case of non-typical settings, such as when groupSelectionOutlineWidth is larger than half the groupBorderWidth, you may occasionally see visual artifacts when using fast incremental updates. If this is the case, consider setting incrementalDraw to accurate.

accurate

FoamTree will apply a more conservative procedure when deciding whether an incremental draw can be performed. In particular, if groupSelectionOutlineWidth is larger than half the groupBorderWidth, FoamTree will always redraw all groups.

none

FoamTree will always redraw all groups, even if the settings permit incremental redraws.

wireframeToFinalFadeDelay

Once animation of the visualization completes, FoamTree will redraw the final image using more detail. This option determines the amount of time that should pass after the last animation frame before the high-quality image is shown.

wireframeToFinalFadeDuration

The duration of the fading animation used to switch between the wireframe and the high-quality visualization image.

finalToWireframeFadeDuration

The duration of the fading animation used to switch between the high-quality and the wireframe visualization image.

wireframeDrawMaxDuration

The desired maximum duration of drawing one frame of animation. Decreasing the value, possibly to 0, will make the animation more smooth at the cost of lower number of details. Increasing the value will increase the number of details, but may slow down the animation.

finalCompleteDrawMaxDuration

The desired maximum duration of a complete high-quality redraw of the visualization. Please see the Visualization rendering performance section for a detailed discussion.

finalIncrementalDrawMaxDuration

The desired maximum duration of an incremental high-quality redraw of the visualization. Please see the Visualization rendering performance section for a detailed discussion.

androidStockBrowserWorkaround

There is a bug in Android stock browsers, that affects the incremental updates of the visualization as well as cross-fading between the wireframe and final visualization images. Setting this option to true will enable a workaround for the bug. As a side effect, cross fading between the wireframe and final images will be disabled, regardless of the wireframeToFinalFadeDuration amd finalToWireframeFadeDuration options.

The default value of this option is true on all Android browsers and false on all other browsers.

viewport

A read-only option that returns the parameters of the current viewport. This option returns an object with the following properties:

x

The horizontal offset of the viewport.

y

The vertical offset of the viewport.

scale

The scale of the viewport. Values larger than 1.0 mean the viewport is magnified. A value of 1.0 means the viewport is in its neutral state. Values lower than 1.0 mean the viewport is demagnified, which may happen when some groups are exposed.

The following example renders the current viewport parameters inside each group's polygon.

foamtree.set({
  dataObject: { groups: randomGroups(10) },

  groupLabelDecorator: function (opts, params, vars) {
    var viewport = this.get("viewport");
    vars.labelText =
      "x\u00a0=\u00a0" + viewport.x.toFixed(2) + " " +
      "y\u00a0=\u00a0" + viewport.y.toFixed(2) + " " +
      "scale\u00a0=\u00a0" + viewport.scale.toFixed(2);
  }
});

The example below shows how to prevent panning of the visualization area if the viewport is not zoomed-in.

foamtree.set({
  dataObject: { groups: randomGroups(10) },

  onGroupDragStart: function (e) {
    if (this.get("viewport").scale <= 1.0) {
      return false;
    }
  }
});

imageData

Returns the current state of the visualization as an image in the data URL format. Unlike most attributes, this one accepts an optional object which can specify the image format details. This object can contain the following keys:

format

format of the image data: image/png or image/jpeg

quality

if format is image/jpeg, specifies the desired quality of JPEG compression in the 0..1 range, where 1 means the highest quality and largest image data. Note that JPEG images are always opaque, even if the background color is specified as transparent. Use PNG images to handle background transparency.

pixelRatio

the pixel ratio to use when producing the export image. Use a value larger than 1, such as 2 to create a higher-resolution image.

backgroundColor

if specified, the background of the exported image will be filled in with the provided color. This option is especially useful when exporting images in the JPEG format.

The visualization image can be used by your application in many different ways. On certain browsers, it is possible to trigger a dialog allowing the user to save the image to the local disk. The image data can be also sent to a server that will do further processing (for example save it or send it via e-mail somewhere).

The following example logs the size of the visualization image (the data URL string, not actual bytes) in various formats to console.

foamtree.set({
  dataObject: largeDataSet,
  onRolloutComplete: function() {
    var opts = [
      { format: "image/png" },
      { format: "image/jpeg", quality: 0.2 },
      { format: "image/jpeg", quality: 0.4 },
      { format: "image/jpeg", quality: 0.6 },
      { format: "image/jpeg", quality: 0.8 },
      { format: "image/jpeg", quality: 1 }
    ];
    $(opts).each(function(i, format) {
      console.log(format, "Image takes: " +
                  (foamtree.get("imageData", format).length / 1024).toFixed(0) + "kB");
    });
  }
});

selection

You can use this option to obtain or alter the current selection.

getter

Calling get("selection") returns an object with the currently selected groups. The object contains one property, groups, containing an array of references to the data objects corresponding to the selected groups.

foamtree.set({
  groupSelectionOutlineColor: "red",
  groupSelectionOutlineWidth: 6,
  groupSelectionOutlineShadowSize: 4
})

foamtree.set("dataObject", { groups: [
  { label: "Group 1", selected: true },
  { label: "Group 2" },
  { label: "Group 3", selected: true },
  { label: "Group 4" }]});

console.log(foamtree.get("selection").groups);

setter

You can set the selection option to alter the current selection. The provided value must be a multiple group selector designating the groups to select or deselect.

• If the selector is an individual selector or an array of individual selectors, the designated groups will get selected, the state of the other groups will remain unchanged.

  foamtree.set("selection", "1");
  var timeout = window.setTimeout(function() {
    foamtree.set("selection", "2");
  }, 2000);

• If the selector is an object, two additional properties are supported, apart from the common groups and all properties:

  selected

  If true or not provided, the designated groups will get selected. If false, the designated groups will get deselected.

  keepPrevious

  If true or not provided, only the state of the designated groups will be altered. If false, the state of the designated groups will be altered, the other groups will get closed.

  To deselect all groups, you can use the selector with the all property:

  foamtree.set("selection", ["1", "2"]);
  var timeout = window.setTimeout(function() {
    foamtree.set("selection", { all: true, selected: false });
  }, 2000);

Note: when selection state is changed by setting this option, the event listeners will not be called.

open

You can use this option to obtain or alter the set of open groups.

getter

Calling get("open") returns an object with the currently open groups. The object contains one property, groups, containing an array of references to the data objects corresponding to the open groups.

foamtree.set("dataObject", { groups: [
  { label: "Group 1", groups: [ { label: "Group 1.1" }, {label: "Group 1.2" } ], open: true },
  { label: "Group 2" },
  { label: "Group 3", groups: [ { label: "Group 3.1" }, {label: "Group 3.2" } ], open: true },
  { label: "Group 4" }]});

console.log(foamtree.get("open").groups);

setter

You can set this option to alter the currently open groups. The provided value must be a multiple group selector designating the groups to open or close.

• If the selector is an individual selector or an array of individual selectors, the designated groups will get open, the state of the other groups will remain unchanged.

  foamtree.set("open", "1");
  var timeout = window.setTimeout(function() {
    foamtree.set("open", "2");
  }, 2000);

• If the selector is an object, two additional properties are supported, apart from the common groups and all properties:

  open

  If true or not provided, the designated groups will get open. If false, the designated groups will get closed.

  keepPrevious

  If true or not provided, only the state of the designated groups will be altered. If false, the state of the designated groups will be altered, the other groups will get closed.

  To close all groups, you can use the selector with the all property:

  foamtree.set("open", ["1", "2"]);
  var timeout = window.setTimeout(function() {
    foamtree.set("open", { all: true, open: false });
  }, 2000);

Note: when open state is changed by setting this option, the event listeners will not be called.

Tip: to get a notification of the completed open/close animation, you can use the open method instead.

exposure

You can use this option to obtain or alter the set of exposed groups.

getter

Calling get("exposure") returns an object with the currently exposed groups. The object contains one property, groups, containing an array of references to the data objects corresponding to the exposed groups.

foamtree.set("dataObject", { groups: [
  { label: "Group 1", exposed: true },
  { label: "Group 2" },
  { label: "Group 3", exposed: true },
  { label: "Group 4" }]});

console.log(foamtree.get("exposure").groups);

setter

You can set this option to alter the currently open groups. The provided value must be a multiple group selector designating the groups to expose or unexpose.

• If the selector is an individual selector or an array of individual selectors, the designated groups will be exposed, all other groups will get unexposed.

  foamtree.set("exposure", "1");
  var timeout = window.setTimeout(function() {
    foamtree.set("exposure", "2");
  }, 2000);

  The following example shows how to unexpose all groups.

  foamtree.set("exposure", ["1", "2"]);
  var timeout = window.setTimeout(function() {
    foamtree.set("exposure", []);
  }, 2000);

  A similar effect could be achieved using the reset method.

• If the selector is an object, two additional properties are supported, apart from the common groups and all properties:

  exposed

  If true or not provided, the designated groups will get exposed. If false, the designated groups will be unexposed.

  keepPrevious

  If true, only the exposure of the designated groups will be altered. If false or not provided, the exposure of the designated groups will be altered, the other groups will get unexposed.

  The following example uses the keepExpose property of the group selector to expose one more group in addition to the already exposed ones. Notice that if the parent group of the group to be exposed is closed (groups 3 and 4 in the example), the parents will be automatically opened as part of the exposure process.

  foamtree.set("exposure", ["1", "2"]);
  var timeout = window.setTimeout(function() {
    foamtree.set("exposure", { groups: ["3.1", "4.1"], keepPrevious: true });
  }, 2000);

Note: when exposure is changed by setting this option, the event listeners will not be called.

Note: there are some limitations when relaxation is visible.

Tip: to get a notification of the completed expose animation, you can use the expose method instead.

state

Returns information about the state of the group. The returned object contains the following properties:

selected

true if the group is currently selected

hovered

true if the group is currently hovered over

open

true if the group is currently open

openness

the progress of the opening/closing animation on the 0..1 scale

exposed

true if the group is currently exposed

exposure

the progress of the expose animation on the 0..1 scale

transitionProgress

the progress of the rollout/pullback animation on the 0..1 scale

revealed

true if the group is being drawn on the screen, also when the group is currently invisible due to zooming/panning; false when the group is not being drawn on the screen, due to, for example, too small size or because the relaxation process has not yet revealed it.

browseable

Since 3.2.0 This property can assume three states:

true

FoamTree has computed the layout for the direct children of this group and the group can be opened for browsing.

false

FoamTree has attempted to compute the layout for the direct children of this group, but the layout could not be computed for any of the following reasons: a. the diameter of the child groups would not exceed groupMinDiameter, b. the total limit of maxGroups would have been exceeded if the layouts got computed, c. JavaScript standard floating point precision is not enough to compute the layout, which can happen for very deeply nested groups.

When the group is not browseable, you may want to allow the user to reload the visualization passing the non-browseable group as the dataObject, and possibly allow the user to get back to the original top-level data.

undefined

FoamTree has not yet attempted to compute the layout for the direct children of this group. FoamTree will attempt to compute the layout when at most maxGroupLevelsDrawn above this groups are open.

visible

true if the group is visible in the current viewport

labelDrawn

true if the group's label is being drawn; false if the label is not being drawn due to, for example, to small area of the polygon.

To retrieve the information about a group, provide the individual group selector as the second parameter of the get method:

var timeout = window.setTimeout(function() {
  console.log(foamtree.get("state", "1"));
}, 500);

interactionHandler

Determines which use interaction capture mechanism FoamTree should be using:

builtin

the built-in mechanism, suitable mostly for desktop devices

hammerjs

use Hammer.js to capture the interactions, see the Touch devices section for details.

external

all interaction events will be triggered externally, please see the Externally triggered interaction section for details.

The default value of this option is builtin on desktop browsers and hammerjs on touch-enabled devices.

logging

Enables logging of some debug information to console.

times

Execution times and statistics. The details of the returned object are not guaranteed to work between versions but it may turn useful for debugging performance problems.

window.setTimeout(function() {
  console.log("Execution time stats: ", foamtree.get("times"));
}, 500);

onModelChanging

Called after the pullback animation of the previous data model has completed, but before the visualization has parsed the new data model provided in the dataObject option and before the new data has been rendered. The listeners will be called with one argument – the new data object the visualization is about to parse and show.

You can use this event to modify and enhance the data model. For example, you can add or remove groups and sub-groups at this stage, as in the following example:

foamtree.set({
  onModelChanging: function (data) {
    data.groups.forEach(function (group) {
      group.label = "Group with " + group.count + " child groups";
      group.weight = group.count;

      // Generate the child groups
      group.groups = [];
      for (var i = 0; i < group.count; i++) {
        group.groups.push({ label: "Group " + i });
      }
    });
  }
});

foamtree.set("dataObject", { groups: [
  { count: 8  },
  { count: 12 },
  { count: 5  },
  { count: 4  },
  { count: 7  }
]});

In the context of each callback, this points to the involved instance of CarrotSearchFoamTree.

onModelChanged

Called after the pullback animation of the previous data model has completed and the visualization has parsed the new data model provided in the dataObject option, but before the new data has been rendered. The listeners will be called with one argument – the new data object the visualization is about to show.

You can use this event to enhance the data model. For example, if the computation of the group's polygon color is expensive, you may want to perform the computation once in the onModelChanged listener, store it in the data object and then use it in the groupColorDecorator, as shown in the following example.

foamtree.set({
  onModelChanged: function (data) {
    data.groups.forEach(function (group) {
      group.color = "hsl(" + (-60 * (group.sentiment - 1)) + ", 100%, 50%)";
    });
  },
  groupColorDecorator: function (opts, props, vars) {
    vars.groupColor = props.group.color;
  }
});

foamtree.set("dataObject", { groups: [
  { label: "Positive", sentiment: 1 },
  { label: "Negative", sentiment: -1 },
  { label: "Neutral",  sentiment: 0 }
]});

Note: group hierarchy changes, such as adding or removing groups or sub-groups, will not be taken into account in the onModelChanged. You can make such changes in the onModelChanging listener.

In the context of each callback, this points to the involved instance of CarrotSearchFoamTree.

onRolloutStart

Called just before the visualization starts the animated rollout. If the application implements some sort of loading indicator, the indicator should be hidden once this event is fired.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onRolloutComplete

Called after the rollout animation has completed. Please note that this listener will not be called when an empty dataObject is set, see onRolloutStart for an alternative for such cases.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onRelaxationStep

Invoked once per layout relaxation step, but only when relaxationVisible is true. The signature of the listener function should be the following:

function (relaxationProgress, relaxationComplete, relaxationTimeout)

where:

relaxationProgress

the progress of the relaxation process on the 0..1 scale

relaxationComplete

When true, this is the last step of relaxation because the requested relaxationQualityThreshold has been achieved.

relaxationTimeout

When true, this is the last step of relaxation because the relaxationMaxDuration has been exceeded.

You can use this event to create a progress indicator for the relaxation, just as the relaxation progress utility does.

onRedraw

Called after the internal- or API-triggered redraw of the visualization. The listener will be called with one boolean parameter set to true if the redraw as an incremental one.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

Any code in this callback should be minimal and ultra fast to keep the transition animations smooth.

The following example uses the onRedraw listener to count incremental and complete redraws. The data object contains two special groups that hold the counters. The example also defines a simple groupColorDecorator that draws the complete redraws group in red and the incremental redraws group in yellow.

foamtree.set({
  onRedraw: function (incremental) {
    var group = this.get("dataObject").groups[incremental ? 0 : 1];
    group.redraws++;
    group.label = group.redraws.toString();
  },
  groupColorDecorator: function(opts, props, vars) {
    switch (props.group.type) {
      case "complete":    vars.groupColor = "hsl(0, 65%, 75%)"; break;
      case "incremental": vars.groupColor = "hsl(60, 65%, 75%)"; break;
      default:            vars.groupColor = "hsl(0, 0%, 85%)";
    }
  },
  rolloutDuration: 1000
});

foamtree.set("dataObject", { groups: [
  { label: "0", redraws: 0, weight: 2, type: "incremental" },
  { label: "0", redraws: 0, weight: 2, type: "complete" },
  { label: "" }, { label: "" },
  { label: "" }, { label: "" },
  { label: "" }, { label: "" },
  { label: "" }, { label: "" }
]});

onViewReset

Invoked after the view has been reset by a user interaction. See the reset method for more details.

onGroupSelectionChanging

Called during group selection changes. For each selected or deselected group, the listener will be invoked with one parameter containing the following properties:

group

Reference to the data object which is subject to selection state change.

selected

true if the group has just been selected, false otherwise

Note that one user action may result in many events of this type, for example deselection of currently selected groups and selection of another group. The global selection state is easier to track using onGroupSelectionChanged event.

When multiple callbacks are present the entire, set will be invoked, even if one or more callbacks changes the selection via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupSelectionChanged

Called once after the selection has changed. The callback receives one parameter: an object containing the groups property with an array of references to the data objects representing the groups that are currently selected.

When multiple callbacks are present, the entire set will be invoked, even if one or more callbacks changes the selection via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

foamtree.set({
  onGroupSelectionChanged: function(info) {
    console.log(info);
  }
});

onGroupExposureChanging

Called during group exposure changes. For each exposed or unexposed group, the listener will be invoked with one parameter containing the following properties:

group

Reference to the data object which is subject to exposure state change.

exposed

true if the group has just been exposed, false otherwise

indirect

true if the exposure change is a side effect of some other user interaction, such as view reset.

Note that one user action may result in many events of this type, for example unexposure of currently exposed groups and exposure of another group. The global exposure state is easier to track using onGroupExposureChanged event.

When multiple callbacks are present the entire, set will be invoked, even if one or more callbacks changes the exposure via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupExposureChanged

Called once after the exposure has changed. The callback receives one parameter: an object containing the following properties:

groups

an array of references to the data objects representing the groups that are currently exposed

indirect

true if the exposure change is a side effect of some other user interaction, such as view reset.

When multiple callbacks are present, the entire set will be invoked, even if one or more callbacks changes the exposure via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

foamtree.set({
  onGroupExposureChanged: function(info) {
    console.log(info);
  }
});

onGroupOpenOrCloseChanging

Called during group opening state changes. For each opened or closed group, the listener will be invoked with one parameter containing the following properties:

group

Reference to the data object which is subject to opening state change.

open

true if the group has just been opened, false otherwise

indirect

true if the state change is a side effect of some other user interaction, such as group exposure change or view reset.

Note that one user action may result in many events of this type, for example closing of currently opened groups and opening of another group. The global state is easier to track using onGroupOpenOrCloseChanged event.

When multiple callbacks are present the entire, set will be invoked, even if one or more callbacks changes the state via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupOpenOrCloseChanged

Called once after some groups have been opened or closed. The callback receives one parameter: an object containing the following properties:

groups

an array of references to the data objects representing the groups that are currently open

indirect

true if the state change is a side effect of some other user interaction, such as group exposure change or view reset.

When multiple callbacks are present, the entire set will be invoked, even if one or more callbacks changes the exposure via an API call.

The listener will not be invoked for API-initiated state changes, only for user interactions. In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

foamtree.set({
  onGroupOpenOrCloseChanged: function(info) {
    console.log(info);
  }
});

onGroupClick

Called after a mouse click (or tap gesture) was detected on a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

The following example shows how to make certain group unselectable.

foamtree.set({
  dataObject: { groups: [
    { label: "Selectable" },
    { label: "Selectable" },
    { label: "Selectable" },
    { label: "Unselectable", unselectable: true },
    { label: "Unselectable", unselectable: true }
  ]},
  onGroupClick: function (event) {
    if (event.group.unselectable) {
      event.preventDefault();
    }
  },
  groupColorDecorator: function (opts, props, vars) {
    vars.groupColor = props.group.unselectable ? "#aaa" : "#77ff00";
    vars.labelColor = props.group.unselectable ? "#888" : "auto";
  }
});

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupDoubleClick

Called after a double click (or double tap gesture) was detected on a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupHold

Called after a click-and-hold (or tap-and-hold gesture) was detected on a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupHover

Called after the mouse pointer enters the area covered by a group or leaves the visualization area completely. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action, which is highlighting of the hovered-on group.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupMouseMove

Called when the mouse pointer moves over the area of some group. The provided callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group and screen- and visualization-relative coordinates of the mouse pointer.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

You can use this event in combination with groupContentDecorator to make the custom-drawn elements of each group interactive. See the Interactive custom content demo for some example implementation.

onGroupMouseWheel

Called after the mouse wheel is rotated over a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupMouseDown

Called after the mouse pointer is pressed. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupMouseUp

Called after the mouse pointer is released. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupDragStart

Called after the user starts dragging a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupDrag

Called when the user is dragging a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupDragEnd

Called when group dragging is complete. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupTransformStart

Called after the user starts touch-based zooming over a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupTransform

Called when the user is performing touch-based zooming over a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onGroupTransformEnd

Called when the user has completed touch-based zooming over a group. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

onKeyUp

Called when the user pressed a key. The callback will be invoked with one parameter – the event details object. You can use that object to get more information about the affected group. You can also use it to prevent the default action.

In the context of the callback, this points to the involved instance of CarrotSearchFoamTree.

boundingBox(points)

Given an array of points, returns the bounding box of the points.

The method is available statically as:

CarrotSearchFoamTree.geometry.boundingBox(points)

where:

points

the array of point coordinates. Each element of the array must be an object containing the x and y properties representing the coordinates of the point.

<return value>

an object representing the bounding box. The object contains the x and y properties denoting the coordinates of the top-left corner of the rectangle, as well as the w and h properties denoting the width and height of the rectangle, respectively.

polygonCentroid(polygon)

Computes the centroid (center of mass) and area of the provided polygon.

The method is available statically as:

CarrotSearchFoamTree.geometry.polygonCentroid(polygon)

where:

polygon

the input polygon. The polygon must be specified as an array of objects, each object containing the x and y property representing the coordinates of the polygon's vertex.

The polygon must be non-self-intersecting, vertex coordinates must be enumerated in clockwise or anti-clockwise order. For performance reasons, this method will not verify if the criteria are met. If the provided polygon does not satisfy the criteria, the result will be unspecified. Note that the polygons returned when getting the geometry option meet both criteria.

<return value>

an object containing the x and y properties denoting the coordinates of the centroid as well as the area property containing the area of the polygon in pixels.

rectangleInPolygon(polygon, cx, cy, wTH, scale, fx, fy)

Given a convex polygon, finds the largest inscribed rectangle of given aspect ratio wTH, centered around the provided center point (cx, cy). Additionally, the resulting rectangle can be scaled by the provided scale factor. Also, the alignment of the center point relative to the rectangle can be defined by the (fx, fy) point.

The method is available statically as:

CarrotSearchFoamTree.geometry.rectangleInPolygon(polygon, cx, cy, wTH, scale, fx, fy)

where:

polygon

the polygon to inscribe the rectangle into. The polygon must be specified as an array of objects, each object containing the x and y property representing the coordinates of the polygon's vertex.

The polygon must be convex, vertex coordinates must be enumerated in clockwise or anti-clockwise order. For performance reasons, this method will not verify if the criteria are met. If the provided polygon does not satisfy the criteria, the result will be unspecified. Note that the polygons returned when getting the geometry option meet both criteria.

cx, cy

coordinates of the point inside the polygon around which the rectangle should be centered. For performance reasons, this method will not verify if the point lies inside the polygon. For points outside or on the boundary of the polygon, the result is not specified.

wTH

(optional) the aspect ratio of the polygon to inscribe, the ratio is assumed to be the polygons width divided by the polygon's height. If not provided, the ratio of 1.0 will be used, which will produce a square.

scale

(optional) the scale factor to apply to the resulting rectangle. The rectangle will be scaled relative to the alignment point determined by (fx, fy). If not provided, the scale of 1.0 will be used, which will produce the largest possible rectangle that fits inside the polygon and meets the center and alignment criteria.

fx, fy

(optional) defines what the the position of the center point (cx, cy) should be relative to the rectangle. The default value is (0.5, 0.5), which will position the rectangle in such a way that the center point is at the center of the rectangle. For (fx, fy) = (0.0, 0.0), the center point will overlap with the top-left corner of the rectangle. Similarly, when (fx, fy) = (1.0, 1.0), the center point will be at the bottom-right corner of the rectangle. Values larger than 1.0 or lower than 0.0 are also supported, in which case the center point will lie outside of the rectangle.

<return value>

an object representing the produced rectangle. The object contains the x and y properties denoting the coordinates of the top-left corner of the rectangle, as well as the w and h properties denoting the width and height of the rectangle, respectively.

The following example demonstrates the usage and results of this method.

foamtree.set({
  dataObject: { groups: [
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.0, scale: 0.7, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.0, scale: 0.5, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 0.0, fy: 0.0 },
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 1.0, fy: 1.0 },
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 0.2, fy: 0.7 },
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 0.2, fy: -0.5 },
    { ratio: 1.0, shift: 0.0, scale: 1.0, fx: 0.5, fy: 1.5 },
    { ratio: 2.0, shift: 0.0, scale: 1.0, fx: 0.5, fy: 0.5 },
    { ratio: 0.5, shift: 0.0, scale: 1.0, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.2, scale: 1.0, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.5, scale: 1.0, fx: 0.5, fy: 0.5 },
    { ratio: 1.0, shift: 0.7, scale: 1.0, fx: 0.5, fy: 0.5 }
  ]},
  groupContentDecorator: function (opts, params, vars) {
    // Prepare some variables
    var centerX = params.polygonCenterX;
    var centerY = params.polygonCenterY;
    var polygon = params.polygon;
    var scale = params.group.scale;
    var shift = params.group.shift;
    var fx = params.group.fx, fy = params.group.fy;

    if (shift > 0) {
      // Shift towards one vertex to make sure the point stays within the polygon
      centerX = centerX * (1 - shift) + polygon[0].x * shift;
      centerY = centerY * (1 - shift) + polygon[0].y * shift;
    }

    // Compute the inscribed rectangle
    var box = CarrotSearchFoamTree.geometry.rectangleInPolygon(
      polygon, centerX, centerY, params.group.ratio, scale, fx, fy);

    // Draw the rectangle
    var ctx = params.context;
    ctx.strokeStyle = "rgba(0, 0, 0, 0.5)";
    ctx.lineWidth = 2;
    ctx.strokeRect(box.x, box.y, box.w, box.h);

    // Draw the center point
    ctx.beginPath();
    ctx.arc(centerX, centerY, 5, 0, 2 * Math.PI);
    ctx.fill();

    // Draw the parameters too
    var fontSize = (params.boxHeight / 30);
    ctx.font = fontSize.toFixed(2) + "px Tahoma, sans-serif";
    ctx.textAlign = "center";
    ctx.fillText("(fx, fy) = (" + fx + ", " + fy + ")", centerX + 0.5 * fontSize, centerY - fontSize);
    ctx.fillText("scale = " + scale, centerX + 0.5 * fontSize, centerY - fontSize * 2);
  },
  titleBarDecorator: function (opts, params, vars) {
    // Display the details in the title bar on hover
    vars.titleBarShown = true;
    vars.titleBarText =
      "widthToHeight = " + params.group.ratio + "   " +
        "shiftFromCenter = " + params.group.shift + "   " +
        "margin = " + params.group.margin;
  }
});

circleInPolygon(polygon, cx, cy)

Given a convex polygon, finds the largest inscribed circle centered around the provided point.

The method is available statically as:

CarrotSearchFoamTree.geometry.circleInPolygon(polygon, cx, cy)

where:

polygon

the polygon to inscribe the circle into. The polygon must be specified as an array of objects, each object containing the x and y property representing the coordinates of the polygon's vertex.

The polygon must be convex, vertex coordinates must be enumerated in clockwise or anti-clockwise order. For performance reasons, this method will not verify if the criteria are met. If the provided polygon does not satisfy the criteria, the result will be unspecified. Note that the polygons returned when getting the geometry option meet both criteria.

cx, cy

coordinates of the point inside the polygon around which the circle should be centered. For performance reasons, this method will not verify if the point lies inside the polygon. For points outside or on the boundary of the polygon, the result is not specified.

<return value>

the radius of the inscribed circle in pixels.

The following example demonstrates the usage and results of this method.

foamtree.set({
  dataObject: { groups: [
    { shift: 0.0, margin: 0.0 },
    { shift: 0.0, margin: 0.2 },
    { shift: 0.0, margin: 0.4 },
    { shift: 0.0, margin: 0.6 },
    { shift: 0.2, margin: 0.0 },
    { shift: 0.4, margin: 0.0 },
    { shift: 0.6, margin: 0.0 }
  ]},
  groupContentDecorator: function (opts, params, vars) {
    // Prepare some variables
    var centerX = params.polygonCenterX;
    var centerY = params.polygonCenterY;
    var polygon = params.polygon;
    var margin = params.group.margin;
    var shift = params.group.shift;

    if (shift > 0) {
      // Shift towards one vertex to make sure the point stays within the polygon
      centerX = centerX * (1 - shift) + polygon[0].x * shift;
      centerY = centerY * (1 - shift) + polygon[0].y * shift;
    }

    // Compute the inscribed circle
    var radius = CarrotSearchFoamTree.geometry.circleInPolygon(
      polygon, centerX, centerY) * (1 - margin);

    // Draw the circle
    params.context.lineWidth = 2;
    params.context.beginPath();
    params.context.arc(centerX, centerY, radius, 0, 2 * Math.PI);
    params.context.stroke();

    // Draw the center point
    params.context.beginPath();
    params.context.arc(centerX, centerY, 5, 0, 2 * Math.PI);
    params.context.fill();
  },
  titleBarDecorator: function (opts, params, vars) {
    // Display the details in the title bar on hover
    vars.titleBarShown = true;
    vars.titleBarText =
      "shiftFromCenter = " + params.group.shift + "   " +
        "margin = " + params.group.margin;
  }
});

stabPolygon(polygon, cx, cy, angle)

Splits the given convex polygon into two polygons along the line defined by the provided point and angle.

The method is available statically as:

CarrotSearchFoamTree.geometry.stabPolygon(polygon, cx, cy, angle)

where:

polygon

the polygon to split. The polygon must be specified as an array of objects, each object containing the x and y property representing the coordinates of the polygon's vertex.

The polygon must be convex, vertex coordinates must be enumerated in clockwise or anti-clockwise order. For performance reasons, this method will not verify if the criteria are met. If the provided polygon does not satisfy the criteria, the result will be unspecified. Note that the polygons returned when getting the geometry option meet both criteria.

cx, cy

coordinates of the point that defines the splitting line.

angle

the angle defining the splitting line, in radians.

<return value>

an array of two polygons being the result of the split or undefined if the provided line does not intersect the provided polygon.

An example result is shown in the figure, where one of the resulting polygons (drawn in white dashed line) has 4 vertices and the other (drawn in black dashed line) has 5 vertices.

Please note the following properties of the returned polygons:

• Each polygon is represented by an array of objects representing the polygon's vertices; each such object has the x and y properties defining the coordinates of the vertex.
• Both returned polygons are convex with vertices enumerated in the clockwise order.
• The returned polygons have one edge in common as shown by the black-white dashed in the figure. The two points defining the common edge in both polygons are always at indices 0 and 1 in the corresponding arrays, although not in the same order to preserve the clockwise enumeration order of the vertices.
• The order of the two resulting polygons in the returned array is deterministic. For example, if angle = 0, the polygon at index 0 will be the upper one, polygon at index 1 will be the lower one. When the angle becomes 90 degrees, polygon at index 0 will be on the left, polygon at index 1 will be on the right.
• If the provided line overlaps with any edge of the provided polygon or contains any vertex of the provided polygon, the returned polygons may be degenerate (e.g. have zero area and duplicated vertices).

The following example demonstrates the usage and results of this method.

foamtree.set({
  dataObject: {
    groups: (function () {
      var groups = [];
      for (var i = 0; i < 24; i++) {
        groups.push({ angle: Math.PI * i / 24 });
      }
      return groups;
    })()
  },
  relaxationInitializer: "squarified",
  groupBorderRadius: 0,

  groupContentDecorator: function (opts, params, vars) {
    // Split the polygon along its center
    var split = CarrotSearchFoamTree.geometry.stabPolygon(params.polygon,
      params.polygonCenterX, params.polygonCenterY, params.group.angle);

    // If splitting was successful, draw both polygons
    if (split) {
      var j;
      var ctx = params.context;
      ctx.setLineDash([8, 8]);

      ctx.fillStyle = "blue";
      ctx.beginPath();
      ctx.arc(params.polygonCenterX, params.polygonCenterY, 5, 0, Math.PI * 2);
      ctx.fill();

      // Draw the first polygon
      ctx.lineWidth = 3;
      ctx.strokeStyle = "white";
      ctx.beginPath();
      ctx.moveTo(split[0][0].x, split[0][0].y);
      for (j = 1; j < split[0].length; j++) {
        ctx.lineTo(split[0][j].x, split[0][j].y);
      }
      ctx.closePath();
      ctx.stroke();

      // Draw the second polygon. We set a line dash offset
      // and the use unusual iteration order to draw the common
      // edge of the two polygons in a coherent way (start and end
      // the line in at the same points). This will ensure that
      // the dashed elements don't overlap.
      ctx.lineDashOffset = 8;
      ctx.strokeStyle = "black";
      ctx.beginPath();
      ctx.moveTo(split[1][1].x, split[1][1].y);
      var len = split[1].length;
      for (var i = len - 1; i >= 1; i--) {
        var p = split[1][(i + 1) % len];
        ctx.lineTo(p.x, p.y);
      }
      ctx.closePath();
      ctx.stroke();
    }
  }
});

roundRect(x, y, w, h, r)

Prepares a path of a rectangle with rounded corners. The path can then be filled and/or stroked depending on the needs.

This method accepts the following parameters:

x, y

coordinates of the top-left corner of the rectangle.

w, h

width and height of the rectangle, in pixels.

r

radius of the corners, in pixels.

The following example demonstrates the this method.

foamtree.set({
  dataObject: { groups: randomGroups(30) },

  groupContentDecorator: function (opts, params, vars) {
    var box = CarrotSearchFoamTree.geometry.rectangleInPolygon(
      params.polygon, params.polygonCenterX, params.polygonCenterY,
      4, 0.8);

    var ctx = params.context;
    ctx.roundRect(box.x, box.y, box.w, box.h, box.h * 0.1);
    ctx.fillStyle = "rgba(255, 255, 255, 0.4)";
    ctx.fill();
    ctx.strokeStyle = "rgba(255, 255, 255, 0.7)";
    ctx.stroke();
  }
});

fillPolygonWithText(polygon, cx, cy, text, options)

Fills the provided polygon with text. If needed, this method will split the text into multiple lines and then record the appropriate fillText() calls to the context on which the method was called.

Please note that it may happen that the method is unable to fill the polygon with text given the provided set of options. Therefore, the callers must check the information object returned by this method to ensure the text was actually fit in the polygon.

This method accepts the following parameters:

polygon

the polygon to fill the text with. The polygon must be specified as an array of objects, each object containing the x and y property representing the coordinates of the polygon's vertex.

The polygon must be convex, vertex coordinates must be enumerated in the clockwise order. For performance reasons, this method will not verify if the criteria are met. If the provided polygon does not satisfy the criteria, the result will be unspecified. Note that the polygons returned when getting the geometry option meet both criteria.

cx, cy

the center point that determines the location of the text within the polygon.

text

the text to fill the polygon with. This method supports a number of special characters in the text.

options

Additional options for this method:

fontFamily

the font family to assume when filling the polygon with text, sans-serif by default.

fontWeight

Since 3.2.2 the font weight (e.g. bold) to assume when filling the polygon with text, normal by default.

fontStyle

Since 3.2.2 the font style (e.g. italic) to assume when filling the polygon with text, normal by default.

fontVariant

Since 3.2.2 the font variant (e.g. small-caps) to assume when filling the polygon with text, normal by default.

minFontSize

the minimum font size in pixels to use for filling the text, 0 by default.

maxFontSize

the maximum font size in pixels to use for filling the text, 72 by default.

lineHeight

the line height to assume when splitting the text into mulitple lines, 1.05 by default. Line heights smaller than 1.0 are currently not supported.

verticalAlign

the vertical align of the text relative to the center point (cx, cy), center by default. The following allignments are supported:

top

the top line of the text will be at the cy coordinate of the center point

bottom

the bottom line of the text will be at the cy coordinate of the center point

center

the text will be centered vertically around the center point

Please note that currently the horizontal align option is not available, the text will always be centered horizontally.

horizontalPadding

the horizontal padding to apply to each line of text. The unit of this option is the font size used to render the text. Default value: 1.0.

verticalPadding

the vertical padding to apply to the whole block of text. The unit of this option is the font size used to render the text. Default value: 0.5.

maxTotalTextHeight

The maximum total height of the text block as a fraction of the polygon's bounding box height, 0.95 by default.

allowEllipsis

if true and the complete text does not fit in the polygon, fill as much text as possible and append the ellipsis to replace the non-fitting part of the text, false by default.

allowForcedSplit

if true the text can be split at arbitrary points, such as inside words, during the filling process, false by default.

cache

if a non-null object is provided, this method will use it to cache some geometry information to speed up the text filling process. When another text filling request is made and the same cache object is presented, this method will try to reuse the cached information to speed up the layout process. If, however, the geometry of the polygon changes a lot, the cache will not be used and a complete filling process will be performed.

For caching to work properly, dedicated cache objects need to be provided for each logical polygon. For example, each group polygon will require a separate cache object. Moreover, to perform caching, the area option must also be provided.

Default value: undefined, meaning no caching will be performed.

area

the current area of the polygon for which the filling is performed. The area must only be provided if layout caching is desired.

cacheInvalidationThreshold

determines how much the area of the polygon must change in order to discard the cached layout and invoke the complete text fitting process, 0.05 by default.

invalidate

if true, the cache will be invalidated and full text filling process will be performed, regardless of whether the geometry of the polygon changed or not. If the label text or font has changed, you must set the invalidate option to true to ensure the text fitting is correctly performed.

<return value>

an object summarizing the text filling process:

fit

true when the text fit in the polygon. If this property is false, then no text drawing commands were issued and the returned summary object does not have any other properties.

lineCount

the number of lines into which the text was split.

fontSize

the font size, in pixels, in which the text was drawn.

box

the bounding box of the complete text block, an object with the x, y, w and h properties representing the top-left corner coordinates, width and height, respectively.

ellipsis

true if the ellipsis was applied at the end of the text.

The following example demonstrates the results of invoking this method with different options.

foamtree.set({
  dataObject: { groups: [
    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Some short text" },

    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Some italic text", style: "italic" },
    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Some bold text", weight: "bold" },
    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Some small-caps text", variant: "small-caps" },

    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Some text longer by a small bit" },

    { align: "center", minFontSize: 0, ellipsis: false,
      text: "A rather long text which should still fit the polygon pretty comfortably" },

    { align: "center", minFontSize: 40, ellipsis: false,
      text: "A rather long text that will most likely not fit the polygon with some " +
            "large minFontSize. A rather long text that will most likely not fit " +
            "the polygon with some minFontSize."},

    { align: "center", minFontSize: 40, ellipsis: true,
      text: "A rather long text that will most likely require an ellipsis to fit the " +
            "polygon at some large minFontSize. A rather long text that will most likely " +
            "require an ellipsis to fit the polygon at some large minFontSize." },

    { align: "center", minFontSize: 0, ellipsis: false,
      text: "Testing vertical align of 'center'" },

    { align: "top",    minFontSize: 0, ellipsis: false,
      text: "Testing vertical align of 'top'" },

    { align: "bottom", minFontSize: 0, ellipsis: false,
      text: "Testing vertical align of 'bottom'" }
  ]},

  groupContentDecorator: function (opts, params, vars) {
    var ctx = params.context;

    var group = params.group;
    var fillTextInfo = ctx.fillPolygonWithText(
      params.polygon,
      params.polygonCenterX, params.polygonCenterY,
      group.text, {
        fontWeight: group.weight || "normal",
        fontStyle: group.style || "normal",
        fontVariant: group.variant || "normal",
        minFontSize: group.minFontSize,
        allowEllipsis: group.ellipsis,
        verticalAlign: group.align
      });

    if (!fillTextInfo.fit) {
      // Draw a red cross instead
      var box = CarrotSearchFoamTree.geometry.rectangleInPolygon(params.polygon,
        params.polygonCenterX, params.polygonCenterY, 1.0, 0.8);
      ctx.lineWidth = 3;
      ctx.strokeStyle = "red";
      ctx.moveTo(box.x, box.y);
      ctx.lineTo(box.x + box.w, box.y + box.h);
      ctx.moveTo(box.x + box.w, box.y);
      ctx.lineTo(box.x, box.y + box.h);
      ctx.stroke();
    }
  }
});

scratch()

Creates and returns a temporary drawing context buffer. Combined with the replay() method, the temporary contexts can be useful in the following scenarios:

1. Drawing a rectangle beneath the text that was fitted in a polygon. The fillPolygonWithText() method issues the drawing commands immediately, but in order to draw a rectangle beneath the text, we need to know the bounding box of the text in advance. The solution is to invoke the text filling on the temporary context, draw the rectangle based on the text filling info returned by fillPolygonWithText() and finally replay the temporary text buffer buffer to draw the text on top of the rectangle. The following example demonstrates this approach.

     foamtree.set({
       dataObject: { groups: randomGroups(20) },
   
       groupContentDecorator: function (opts, params, vars) {
         var ctx = params.context;
         var group = params.group;
   
         var scratch = ctx.scratch();
         var fillTextInfo = ctx.fillPolygonWithText(
           params.polygon,
           params.polygonCenterX, params.polygonCenterY,
           "Group\u00a0" + (params.index + 1));
   
         if (fillTextInfo.fit) {
           // Draw the rectangle first
           var box = fillTextInfo.box;
           var padding = box.h * 0.15;
           ctx.lineWidth = 2;
           ctx.roundRect(box.x - padding, box.y - padding,
             box.w + 2 * padding, box.h + 2 * padding, padding);
           ctx.globalAlpha = 0.2;
           ctx.fill();
           ctx.globalAlpha = 0.6;
           ctx.stroke();
           scratch.replay(ctx);
         }
       }
     });

2. Caching expensive layout computations. When groupContentDecoratorTriggering is onSurfaceDirty, the content decorator will be invoked each time the visualization needs to be redrawn. During most of those calls, the geometry of the groups' polygons will remain the same, so there may be no need recompute the layout of the custom content. One way to cache the layout in such cases would be to create one or more drawing context buffers per group, fill the buffers only when the shapeDirty property of the decorator is true and when shapeDirty is false, replay the previously buffered drawing commands. Please see the GitHub search example for this pattern applied in practice.

replay(targetContext)

Replays the content of the drawing context buffer to the targetContext. The target context can either be another context buffer of the actual native drawing context. For usage scenarios and examples, please see the scratch() method.