candy pie: a configurable, interactive 3d pie chart in your browser

Let's break down that sentence ..

• candy: don't take it that seriously. Pie charts are not always loved.. One should not use 3d for charts.. Negative times negative equals positive?
• pie: yes indeed, a pie chart. See above.
• configurable: all options are described below. Curious which other options will prove to be interesting later on.
• interactive: the result is not a static image, but a 3d object one can rotate. Or click on a slice for more info via a hover effect.
• 3d: standing on the shoulders of
  
• browser: works in a modern browser, desktop & mobile.
• and open source.

Load first the babylon.js code into your page, and add the candy-pie script.

            <script src="https://cdn.babylonjs.com/babylon.js"></script>
            <script src="https://cdn.babylonjs.com/gui/babylon.gui.js"></script>
            <script src="https://thierryvergult.github.io/CandyPie/candy-pie-babylon.js"></script>
          

Define a canvas element in your html page, and call one single javascript function to place the 3d pie chart on that canvas element. All data and configuration options are defined in one single javascript object.

            <canvas id='candy-pie-canvas-id' class='candy-pie-babylon-canvas'></canvas>

            let my_pie3d = {
               htmlCanvasId: 'candy-pie-canvas-id',
               slices: [ ..],
               ..
            };
            
            candyPie.babylon( my_pie3d);

          

Set the width, height or aspect ratio of the canvas element as desired.

some additional css can help

            .candy-pie-babylon-canvas {
              /* Disables all pan and zoom interactions */
              touch-action: none; 
              /* remove outline when clicking on canvas */
              outline: none; 
            }
          

A pie chart with 3 equal slices. Each slice is specified by

• a height number, which maps to the relative height of each slice
• a color, which can be specified in several formats (see later)

All other options are defaulted, except the id of the canvas where one wants the 3d pie chart to show up.

              let pie3d_default = {
                htmlCanvasId: 'candy-pie-babylon-canvas-id-default',
                slices: [
                   { height: 100, color: 'indianred'},
                   { height: 100, color: 'steelblue'},
                   { height: 100, color: 'olive'}
                ]
              };
                          
              // call the 3d pie function with the above settings
              candyPie.babylon( pie3d_default);
            

The same pie chart, but with some extra space between the slices, and a donut hole. And a lightgrey background. Simply set the following options in the pie3d object:

• spaceBetweenSlices: default false, set to true in case
• innerRadiusPct: default 0, set to a higher number to have a donut
• backgroundColor: set the color of the background of the canvas

              let pie3d_2 = {
                htmlCanvasId: 'candy-pie-id01',
                slices: [
                   { height: 100, color: 'indianred'},
                   { height: 100, color: 'steelblue'},
                   { height: 100, color: 'olive'}
                ],
                spaceBetweenSlices: true,
                innerRadiusPct: 40,
                backgroundColor: 'lightgrey'
              };
            

The same pie chart, but now without vertical rotation, the initial camera angle position is a little lower, so the donut shows more flat:

• allowVerticalRotation: default true, here set to false. So now only horizontal rotation is possible.
• cameraDegreesY: the camera position is set to 30 degrees, a little lower than the default of 45 degrees. Camera position starts at the ground plane.

              
                cameraDegreesY: 30,
                allowVerticalRotation: false
              
            

Until now, all pie charts had slices with the same size. Changing the height of the slices changes the relative height. And setting the arc percentage drives the "width" of each slice.

The first slice of this example below takes 50%, the other 2 slices take each 25%.

The height increases from 100, to 125, to 150. This influences the relative height of the slices.

              
              slices: [
                  { height: 100, arcPct: 50, ..},
                  { height: 125, arcPct: 25, ..},
                  { height: 150, arcPct: 25, ..}
                ],
              
            

A few options for the labels shown on the slice surface:

• sliceShowLabel: boolean, default false.
• labelFontFactor: default 1. In case a greater font is desired, increase here the font factor.
• labelExtraTopMargin: default 0. Increment this figure in case the labels should show up a little lower within each slice.
• labelColor: default empty. If so, the scripts uses black or white labels, depending of the color of the slice. If not, this color is used for all slices.

More info about a slice can be seen when clicking on a slice. That pops up a hover box, which will contain details in line with the configuration below:

• hoverShowLabel: boolean, default false. Adds the slice label to the hover box, when set.
• hoverShowHeight: boolean, default false. Adds the slice's height to the hover box, when set.
• hoverShowArcPct: boolean, default false. Adds the slice's arc percentage to the hover box, when set.

Here a pie chart with 5 slices and labels. The slices have a variable height and a variable arc : slice 4 is smaller, applepie is larger than the others.

            slices: [
              { height: 10, arcPct: 20, label: 'one'},
              { height: 12, arcPct: 20, label: 'two'},
              { height: 14, arcPct: 20, label: 'three'},
              { height: 16, arcPct: 10, label: 'four'},
              { height: 18, arcPct: 30, label: 'apples'}
            ],
            ..
            sliceShowLabel: true,
            labelFontFactor: 1.5,
            hoverShowLabel: true,
            hoverShowHeight: true,
            hoverShowArcPct: true,
            
          

ps: the background color of the pie chart is dynamically taken from the code snippet above. Can be handy when you want to reuse colors of your site in the pie.

This pie chart has also 5 slices, all with same width (arc), but the slices are all made higher than in the previous pie chart. This is done via the verticalFactor configuration option, which stretches the slices vertically.

Add a legend, with an item for each slice with a label. Clicking on the item brings the slice in front.

            
            verticalFactor: 4,
            addLegend: true
            
          

This pie chart has 4 equal slices. Some label-configuration options are used to position & color the labels on the pie.

And the chart does a full rotation in 5 seconds at the beginning, slowing downn

              labelFontFactor: 2.5,
              labelExtraTopMargin: 20,
              labelColor: 'rgb(155, 102, 102)',
              backgroundColor: 'rgb(196,238,216)', // green-ish
              verticalFactor: 2,
              allowVerticalRotation : false,
              cameraDegreesY: 60,
              secondsPerRotation: 5,
              rotationSlowDown: true

            

The color of the slices and the canvas background are always set via a string.

Such string can be:

• a named color, like red. Some more color names.
• a hexadecimal value, like #f8f6e1
• a rgb function call, like rgb(196,238,216)
• a javascript function returning such color string

You can try out all candy pie configuration options in this online playground.

This playground allows also to set the number of slices and all data for each slice.

• renderOnce
• extraStartDegrees