Data Models
Relevant source files
The following files were used as context for generating this wiki page:
Data models in SwiftDitherKit define the structure and behavior of chart components, ranging from raw input data to visual configuration and layout parameters. These models are designed to be stable, identifiable, and portable, facilitating a rendering pipeline that converts abstract data into dithered raster images.
The architecture relies on a clear separation between domain data (the categories and values) and visual metadata (colors, variants, and stacking logic). This ensures that charts remain consistent across different platforms and accessible to assistive technologies.
Input Data Structures
The primary unit of information in SwiftDitherKit is the DitherDatum, which represents a single category or point along an axis. For polar charts, DitherSlice is used to represent individual wedges.
DitherDatum
A DitherDatum acts as a container for values associated with specific series identifiers. It is identified by a stable id and includes a label for display purposes.
| Field | Type | Description |
|---|---|---|
id | String | Unique, stable identifier for the datum. |
label | String | Display name for the category. |
values | [String: Double] | Dictionary mapping series IDs to numeric values. |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:85-103
DitherSeries and DitherSlice
DitherSeries configures the visual appearance of a data series across multiple data points, while DitherSlice combines data and appearance for single-value wedges in pie charts.
The diagram shows the relationship between data points and the series configurations that style them.
Sources: Sources/SwiftDitherKit/DitherTypes.swift:106-144
Visual and Layout Configuration
Configuration models manage the aesthetics and structural layout of the charts, including color handling, margins, and dither patterns.
DitherColor
A portable RGB representation. It includes static presets matching the original Dither Kit palette and support for hex-based initialization. Components are automatically clamped to the 0...1 range.
Sources: Sources/SwiftDitherKit/DitherTypes.swift:8-41
DitherMargins
Defines the safe area around the pixel raster reserved for labels and chrome. It provides standard presets for different chart families.
| Preset | Top | Trailing | Bottom | Leading |
|---|---|---|---|---|
cartesian | 10 | 12 | 24 | 38 |
sparkline | 0 | 0 | 0 | 0 |
polar | 14 | 14 | 14 | 14 |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:59-81
Enums for Rendering Logic
DitherVariant: Controls texture patterns (gradient,dotted,hatched,solid).DitherStacking: Determines how series share the value axis (overlaid,stacked,percent).DitherBloom: Specifies the intensity of the glow effect behind the raster (off,low,high,aura).
Sources: Sources/SwiftDitherKit/DitherTypes.swift:44-56
Internal Mathematical Models
To transform input data into screen coordinates, the library uses internal geometry and scale models.
DitherBand and DitherBandResult
These structures represent the calculated vertical range (lower and upper bounds) for every series at every data point after applying stacking logic.
struct DitherBand: Equatable, Sendable {
let lower: Double
let upper: Double
}
struct DitherBandResult: Equatable, Sendable {
let bands: [String: [DitherBand]]
let minimum: Double
let maximum: Double
}
Sources: Sources/SwiftDitherKit/DitherMath.swift:4-13
DitherLinearScale
A model that maps numeric values to the coordinate system of the plot rectangle. It automatically calculates "nice" numbers for axis ticks and handles diverging values (positive and negative).
Sources: Sources/SwiftDitherKit/DitherMath.swift:233-271
Metadata and Accessibility
Semantic information is stored in models that inform assistive technologies and interactive components.
DitherAccessibility
Provides localized labels for the chart title, summary, and axis descriptions. These are consumed by Apple's chart accessibility descriptor APIs.
Sources: Sources/SwiftDitherKit/DitherAccessibility.swift:1-24
DitherCartesianOptions
A comprehensive model that bundles stacking, margins, bloom, motion settings, and accessibility labels into a single configuration object for Cartesian charts.
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:4-51
Motion and Animation State
State models are used to track whether a chart should animate or crossfade during data changes.
DitherRasterMotionState
Tracks the state of a rendered raster to decide on the appropriate transition (none, replace, crossfade, or replay).
The flow shows how motion states are compared to determine rendering transitions.
Sources: Sources/SwiftDitherKit/DitherMotion.swift:42-88
DitherSparkleField
Represents a collection of DitherSparkle points. This model is generated based on the series geometry and is used to render the idle "sparkle" animation found in area and line charts.
Sources: Sources/SwiftDitherKit/DitherSparkles.swift:11-18
Summary
The data models in SwiftDitherKit provide a robust framework for chart definition. By separating categorical data (DitherDatum) from visual styling (DitherSeries, DitherColor) and layout logic (DitherLinearScale, DitherMargins), the system ensures that complex dithered visualizations remain performant, accessible, and easy to configure via a declarative SwiftUI-like API.