CLI Snapshot Tool
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Snapshot Tool, implemented as DitherKitSnapshotCommand, is a macOS-specific command-line utility designed to generate high-resolution image galleries of dithered SwiftUI charts. It serves as a development and documentation aid, allowing developers to render the SwiftDitherKit chart gallery using SwiftUI's ImageRenderer without requiring an active iOS Simulator or a live application environment.
The tool aggregates various chart types—including area, line, bar, pie, donut, and radar charts—into a single structured layout. It specifically leverages a specialized rendering mode to ensure that asynchronous dithered pixels are correctly captured during offscreen evaluation.
Sources: Sources/DitherKitSnapshot/main.swift:6-14, README.md:143-149
Command Execution and Architecture
The tool is structured as a Swift @main entry point. It processes command-line arguments to determine the output file destination, defaulting to a file named dither-kit-snapshot.png in the current directory if no path is provided. The core rendering logic utilizes the ImageRenderer class to transform a SwiftUI view hierarchy into a PNG image.
Execution Flow
The following diagram illustrates the sequence of operations from command invocation to file output:
Offscreen Rendering Requirements
A critical technical requirement for the CLI tool is the use of .ditherRenderingMode(.immediate). Standard ImageRenderer instances do not execute asynchronous view tasks. Because SwiftDitherKit usually renders and caches pixels away from the main actor, immediate mode is mandatory for offscreen snapshots to ensure pixels are available during the view evaluation phase.
Sources: README.md:151-154, Sources/SwiftDitherKit/SwiftDitherKit.docc/GettingStarted.md:46-52
Gallery Components and Configuration
The tool renders a view called DitherKitGallery, which organizes charts into a header followed by three distinct rows of cards. Each card demonstrates a specific combination of chart type and dither options.
Snapshot Configuration
| Parameter | Value | Description |
|---|---|---|
| Canvas Width | 1120 | Total width of the rendered gallery frame. |
| Canvas Height | 920 | Total height of the rendered gallery frame. |
| Scale | 2 | Rendering scale (Retina/2x). |
| Color Scheme | .dark | Forces the gallery into Dark Mode. |
| Background | RGB(0.035, 0.04, 0.055) | Deep dark blue background color. |
Sources: Sources/DitherKitSnapshot/main.swift:16-21, Sources/DitherKitSnapshot/main.swift:44-50
Gallery Layout
The gallery is composed of GalleryCard structures that encapsulate individual chart views:
- Header: Displays the "SwiftDitherKit" title and tagline.
- First Row: Stacked area chart with
aurabloom and a grouped bar chart demonstrating negative values. - Second Row: Line chart with a controlled marker and a donut chart featuring four different textures.
- Third Row: Radar chart with overlapping series and a vertical stack of sparklines.
Sources: Sources/DitherKitSnapshot/main.swift:53-128
Data Models and Chart Constants
The CLI tool utilizes a private GalleryData enum to provide stable identifiers and sample values for the snapshots. This ensures the output is deterministic.
Sample Data Types
The tool exercises the core data structures defined in the library:
DitherDatum: Used for Cartesian and Radar charts to define categories (e.g., months "Jan", "Feb") and series values.DitherSeries: Defines visual configurations like colors (e.g.,.blue,.purple) and variants (e.g.,.hatched,.dotted).DitherSlice: Used for the Pie/Donut charts.
Sources: Sources/DitherKitSnapshot/main.swift:150-188, Sources/SwiftDitherKit/DitherTypes.swift:85-139
Chart Rendering Options
The tool explicitly disables animations (animate: false) for snapshot stability and sets specific bloom levels to showcase the library's visual capabilities.
DitherAreaChart(
data: GalleryData.traffic,
series: GalleryData.trafficSeries,
options: DitherCartesianOptions(
stacking: .stacked,
bloom: .aura,
animate: false,
showsLegend: false
)
)
Sources: Sources/DitherKitSnapshot/main.swift:70-76
Summary
The CLI Snapshot Tool is a specialized utility that bridges SwiftUI's declarative UI with low-level image generation for the SwiftDitherKit project. By enforcing .immediate rendering mode and providing a comprehensive suite of gallery cards, it allows for the automated generation of documentation assets and visual regression testing on macOS.
Sources: Sources/DitherKitSnapshot/main.swift:6-14, README.md:143-154