BPCharts

   

Table of Contents

  1. Overview
  2. Getting Started(cht)
  3. Donut/Pie(chvap)
  4. Colors (chco)
  5. Fills (chf)
  6. Line Color (chlco)
  7. Markers (chm)
  8. Label Position (chlp)
  9. Pie Rotation (chp and chpd)
  10. Multi-Depth(chvas)
  11. Exploded(chvax)

Overview

The Donut/Pie Chart is used to display proportional part to whole relationships. The chart type code for this chart is dn.

This chart is an extension of the functionality of Pie charts, allowing the creation of donut and pie charts in both 2D and 3D.

Getting Started(cht)

Description Image
By default, dn chart type will render a 3D pie chart, with the depth and angle determined automatically.
cht=dn


Donut/Pie(chvap)

<%-- --%>

Syntax

chvap=<inner_radius>,<depth>,<angle>,<shadow_mode>
<inner_radius>
The donut inner radius. Based on input parameter, the inner radius is calculated as percentage of outer radius:

values 0 to 4 would result in the inner radius between 0 and 100%, of the calculated outer radius (based on chart dimension)

values 5 and above, would result in the calculated radius (based on chart dimension) becoming the inner radius.

<depth>
The 3D depth of the pie in pixels. -1 means the depth is automatically determined.
<angle>
The 3D view angle in degrees. Must be 0 - 90 for standard 3D mode, and 0 - 360 in shadow 3D mode. -1 means the angle is automatically determined.
<shadow_mode>
Flag to indicate whether the pie is in standard 3D or shadow 3D mode. A true value means shadow 3D mode.A false value means standard 3D mode.
<shadow_style>
Values 0 to 7 to set the sector shading style

3D Pie charts support 0 - 7

3D Donut charts support 0 - 8

  • 0 - DefaultShading
  • 1 - FlatShading
  • 2 - LocalGradientShading
  • 3 - GlobalGradientShading
  • 4 - ConcaveShading
  • 6 - RoundedEdgeShading
  • 7 - RadialShading
  • 8 - RingShading (only supported in donut rings)
NOTE: Theres is no value 5!!!!!
Description Image
2D Donut chart. Just as in Pie charts, values are rendered in order starting from the north and proceeding clockwise.
chvap=2,0,0
2D Pie Chart set by setting inner radius to 0 .
chvap=0,0,0
As with all charts, you can specify data using different data encodings. See data encodings for more information.

Pie with 10pixels depth at 90deg angle
chd=s:sengelha
chvap=0,10,30
Donut chart, 10pixels depth at 170deg angle
chd=s:sengelha
chvap=2,10,170
Donut chart, 10pixels depth at 170deg angle
Inner radius set to value above 4, resulting in calculated radius(based on chart dimensions), becoming the inner radius
chd=s:sengelha
chvap=7,10,170
Pie with 10pixels depth at 90deg angle, shadow mode set to true
chd=s:sengelha
chvap=0,10,30,true
Donut chart, 10pixels depth at 170deg angle, shadow mode set to true, shadow style set to ring shadow
Shadow Mode is only read by charts, when in pie mode. Donut charts will not read this parameter.
chd=s:sengelha
chvap=2,10,170,true,8
Pie with 10pixels depth at 90deg angle, shadow mode set to true, shadow style set to concave shading
chd=s:sengelha
chvap=0,10,30,true,4
As with all charts, you can generate other image types using the chof parameter.
chof=s (SVG)
chvap=2,10,170
chof=s (SVG)
chvap=0,10,170

Colors (chco)

Users can explicitly choose the colors they want to render the individual pie slices using the chco option. By default, BPCharts renders pie slices using an automatically-generated color gradient.

See also Colors.

Syntax

chco=<color_1>,...,<color_n>
<color>
The color, in RRGGBB or RRGGBBAA format, to apply to the pie slice.

Example

Description Image
Donut chart color with Morningstar-like palette.

10pixels depth at 45deg angle
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=2,10,45
Pie chart with Morningstar-like color palette.

20pixels depth at 45deg angle
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=0,20,45
Make all donut slices semi-transparent using an alpha value of E0. Note: You'll generally want to make the chart background transparent as well, see Fills (chf).
chco=9F375FE0|E87B1EE0|
  F2C108E0|88AC2EE0|
  007581E0|789CC2E0|
  4F6688E0
chf=bg,s,00000000
chvap=2,10,45
Draw a donut with a "missing" slice by using a transparent color (00000000). Note: You'll generally want to make the chart background transparent as well, see Fills (chf).
chd=t:15,20,65
chco=F2C108|00000000|
  F2C108
chf=bg,s,00000000
chvap=2,10,45

Fills (chf)

The background color of the chart can be controlled using the chart fill option. The default fill color for the pie chart is white (FFFFFF).

Syntax

chf=<fill_type>,s,<color>
<fill_type>

The part of the chart being filled. Specify one of the following values:

  • bg - Background fill
s
Indicates a solid fill.
<color>
The fill color, in RRGGBB or RRGGBBAA format.

Example

Description Image
Fill the chart background with pale grey (EFEFEF).
chf=bg,s,EFEFEF
chvap=0,10,45
Fill the chart background with semi-transparent blue (0000FFCC).
chf=bg,s,0000FFCC
chvap=2,10,45

Line Color (chlco)

By default, there are no lines separating pie slices from one another. This can be controlled using the line color (chlco) option.

Syntax

chlco=<line_color>
<line_color>
The color, in RRGGBB or RRGGBBAA format, of the pie slice separating lines.

Example

Description Image
Add white lines separating the pie slices.
chlco=FFFFFF
chvap=0,10,45
Add white lines separating the donut slices.
chlco=FFFFFF
chvap=2,10,45




Chart Markers (chm=N)

You can combine markers with any other chm parameters using a pipe character ( | ) to separate the chm parameters.

Syntax

Specify one set of the following parameters for each series that should be marked. To mark multiple series, create additional parameter sets, delimited by a pipe character. You do not need to mark up all series. If you do not assign markers to a data series, it will not get any markers.

chm=
      [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>
        |...|
      [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>
<marker_type>
The type of marker to use. Specify one of the following types:
  • N<opt_format_string> - The value of the data at this point, with optional formatting.

    The formatting string syntax is as follows:
           N<preceding_text>*<number_type><decimal_places>zs<x or y>*<following_text>

    Here is the meaning of each element:
    • <preceding_text> - Literal text to precede each value.
    • *...* - An optional block wrapped in literal asterisks, in which you can specify formatting details for numbers. The following values are supported, and are all optional:
      • <number_type> - The number format, for numeric values. Choose one of the following:
        • f - [Default] Floating point format.
        • p - Percentage format. A % sign is appended automatically. Note: When using this format, data values from 0.0 — 1.0 map to 0 — 100% (for example, 0.43 will be shown as 43%).
        • e - Scientific notation format.
        • c<CUR> - Format the number in the currency specified, with the appropriate currency marker. Replace <CUR> with a three-letter currency code. Example: cEUR for Euros. You can find a list of codes on the ISO web site, although not all symbols are supported.
      • <decimal_places> - An integer specifying how many decimal places to show. The value is rounded (not truncated) to this length. Default is 2.
      • z - Display trailing zeros. Default is no.
      • s - Display group separators. Default is no.
      • x or y - This parameter is not currently supported - its content will be ignored.
    • <following_text> - Literal text to follow each value.

<color>
The color of the markers for this series, in RRGGBBAA hexadecimal format - where AA Alpha Channel (transparency) is optional.
<series_index>
The zero-based index of the data series on which to draw the markers. This parameter is ignored when <marker_type> is set to 'N'.
<opt_which_points>
[Optional] Which point(s) to draw markers on. Default is all markers. Ignored when <marker_type> is set to 'N'
<size>
The size of the marker, in pixels (or Font size when <marker_type> is set to 'N'). The H marker supports the syntax <size>[:width] where the optional second part specifies the line or marker length. Where this second part is omitted, the horizontal line will span the entire chart.
<opt_z_order>
[Optional] When supplied, any negative integer will cause the layer on which the marker is drawn, to be sent to the back of the Z Order.

Example

Description Image
Add value markers as percentages at each sector.
chlco=FFFFFF
chvap=0,10,45
chm=N*f1*%25,000000,0,-1,10
Add value markers as GBP at each sector, with £ml notation.
chlco=FFFFFF
chvap=2,10,45
chm=N*cGBP*£ml,000000,0,-1,10


Label Position (chlp)

The distance between the sector perimeter and the sector label. A negative value means the sector label will be drawn in the interior of the sector.

Syntax

chlp=<distance>,<joinlineColor>,<layout>
<distance>
A integer value assining distance, in pixels, between the sector perimeter and the sector label. A negative value means the sector label will be drawn in the interior of the sector.
<joinlineColor>
The color, in RRGGBB or RRGGBBAA format, that joins the sector perimeter with the sector label.
<layout>
A integer value describing layout type. values: 0 or 1
  • 0 - Side Label Layout, there is an invisible rectangle containing the pie, where the rectangle can be wider than the diameter of the pie.The sector labels are positioned on the left and right sides outside the rectangle. Because the labels can be quite far away from the sectors, join lines are typically used to connect the labels to the sectors.
  • 1 - Circular Label Layout, the sector labels are positioned around the perimeter of the pie

Example

Description Image
Add value markers inside each sector.
chlco=FFFFFF
chvap=0,10,45
chm=N*f1*%25,000000,0,-1,10
chlp=-120
chlco=FFFFFF
chvap=0,0,0
chm=N*f1*%25,000000,0,-1,10
chlp=-120
Add value markers outside chart, in side layout mode
chlco=FFFFFF
chvap=2,10,45
chm=N*f1*%25,000000,0,-1,10
chlp=20,0B6138,0
Add value markers outside chart, in circular layout mode
chlco=FFFFFF
chvap=2,10,45
chm=N*f1*%25,000000,0,-1,10
chlp=20,0B6138,1


Pie Rotation (chp and chpd)

By default, the pie chart pieces are rendered in order starting from the north and proceeding clockwise. You can change the starting orientation by using the pie rotation (chp) or pie rotation in degrees (chpd) parameter.

Syntax

chp=<radians>
chpd=<degrees>
<radians>
A floating point value describing how many radians to rotate the chart clockwise.
<degrees>
A floating point value describing how many degrees to rotate the chart clockwise.

Example

Description Image
Rotate the donut chart 90 degrees clockwise.
chvap=2,10,45
chpd=90
Rotate the pie chart 90 degrees counter clockwise.
chvap=0,10,45
chpd=-90

Multi-Depth (chvas)

This setting adds 3D effects to the pie/donut, where each sector can have a different 3D depth

Syntax

chvas=<sector_0>,...,<sector_n+1>|<depth_0>,...,<depth_n+1>
<sector_n>
Index of chart sector
<depth_n>
Integer value as depth in pixels

Example

Description Image
Donut chart with Morningstar-like color palette.

10pixels depth at 45deg angle

Multi depth set at each sector
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=2,10,45
chvas=0,8,10,15,20,25,35
Pie chart with Morningstar-like palette color scheme.

20pixels depth at 45deg angle

Multi depth set at each sector

With 45deg rotation

chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=0,20,45
chvas=0,8,10,15,20,25,35
chpd=45

Exploded(chvax)

This "explodes" a sector/s from the pie/donut.

Syntax

chvas=<sector_0>,...,<sector_n+1>|<distance_0>,...,<distance_n+1>
<sector_n>
Index of chart sector
<distance_n>
Integer value as distance in pixels

Example

Description Image
Donut chart with Morningstar-like color palette.

10pixels depth at 45deg angle

Explode all sectors by 20 pixels
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=2,10,45
chvax=-1|20
Pie chart with Morningstar-like color palette.

20pixels depth at 45deg angle

Multi depth set at each sector

With 15deg rotation

Explode sectors 1 and 3 by 30 and 15 pixels
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=0,20,45
chpd=15
chvax=1,3|20,15
Pie chart with Morningstar-like color palette.

20pixels depth at 45deg angle

Multi depth set at each sector

With 45deg rotation

Explode all sectors, with distance set by chart engine
chco=9F375F|E87B1E|F2C108|
  88AC2E|007581|789CC2|
  4F6688
chvap=0,20,45
chpd=45
chvax=-1