Pie and Donut Charts
Relevant source files
The following files were used as context for generating this wiki page:
Pie and Donut charts in SwiftDitherKit provide a specialized way to visualize categorical data proportions using ordered-dither textures. These charts are part of the library's polar chart family, sharing common configuration and interaction patterns with radar charts. A pie chart represents data as wedges of a circle, while a donut chart is achieved by specifying an innerRadiusRatio to create a central hole.
The system utilizes asynchronous rendering to generate dithered rasters away from the main thread, supporting animations for entrances and data changes. It integrates with SwiftUI’s environment, respecting locale settings for value formatting and accessibility descriptions.
Sources: SwiftDitherKit.docc/GettingStarted.md, Sources/SwiftDitherKit/DitherPolarCharts.swift:65-110
Architecture and Components
The pie chart implementation is divided into the public-facing view, a specialized plot for rendering the dithered raster, and an interaction layer for handling gestures.
Component Hierarchy
The DitherPieChart acts as a container that manages the state for selection and hovering. It embeds the DitherPiePlot for visual representation and a DitherLegend for series identification.
The diagram shows the internal view hierarchy of a pie chart, illustrating the separation between the rendering raster and the interactive overlay.
Sources: Sources/SwiftDitherKit/DitherPolarCharts.swift:112-140
Key Data Structures
The system uses specific types to define slices and configuration options.
| Type | Description |
|---|---|
DitherSlice | Represents a single wedge, containing an ID, label, value, color, and dither variant. |
DitherPolarOptions | Configures margins, bloom effects, animation settings, and interaction toggles. |
DitherPieGeometry | Internal utility that calculates start, end, and middle angles for each slice. |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:138-160, Sources/SwiftDitherKit/DitherPolarCharts.swift:4-40, Sources/SwiftDitherKit/DitherMath.swift:415-440
Visual Rendering and Geometry
Wedge geometry is calculated based on a starting angle at the top of the circle (-Double.pi / 2). The renderer treats negative or non-finite values (NaN, Infinity) as zero to ensure visual stability.
Geometry Calculation
The flow represents how raw slice values are transformed into circular coordinates for the dither renderer.
Sources: Sources/SwiftDitherKit/DitherMath.swift:425-440
Donut Hole Configuration
A donut chart is created by setting the innerRadiusRatio property. This value is clamped between 0 and 0.9. During rendering and hit testing, the inner radius is calculated as a fraction of the outer radius.
Sources: Sources/SwiftDitherKit/DitherPolarCharts.swift:85-88, Sources/SwiftDitherKit/DitherPolarCharts.swift:305-310
Interaction and Selection
Interaction is handled via a transparent overlay (DitherPieInteractionLayer) that captures taps and hovers.
- Taps: A
SpatialTapGesturedetermines which wedge was hit. Tapping the currently selected slice clears the selection. - Hovers: Pointer movement updates the
hoverIndex, triggering aDitherTooltipthat displays the slice's label and formatted value. - Legend: Selecting an item in the
DitherLegendalso updates the chart's selection state.
Accessibility
Pie charts utilize AXChartDescriptorRepresentable to expose data to assistive technologies. The DitherPieChartDescriptor maps slices to categorical data points on a radial axis.
- Axis Description: The category axis defaults to "Slice" and the value axis to "Value", unless overridden in
DitherAccessibility. - Content Direction: Set to
.radialClockwiseto match the visual layout. - Summary: Includes the number of slices and mentions if a specific slice is currently selected.
Sources: Sources/SwiftDitherKit/DitherPieAccessibility.swift:5-40
Configuration Options
The DitherPolarOptions struct provides extensive control over the chart's behavior and appearance.
| Parameter | Type | Default | Description |
|---|---|---|---|
margins | DitherMargins | .polar (14pt) | Padding around the chart raster. |
bloom | DitherBloom | .off | The intensity of the glow effect (low, high, aura). |
animate | Bool | true | Enables entrance and data change animations. |
interactive | Bool | true | Determines if the chart responds to taps/hovers. |
valueFormat | DitherValueFormat | .automatic | Formatting for tooltips and accessibility. |
Sources: Sources/SwiftDitherKit/DitherPolarCharts.swift:4-40, Sources/SwiftDitherKit/DitherTypes.swift:101-105