The Temporal Engine - Charton: The Grammar of Graphics in Rust

Precision-Preserving `i128` Math

Mapping a 19-digit nanosecond timestamp directly to a screen pixel via f32 or even f64 introduces Bit-Drift. At large Unix offsets (e.g., year 2026), f64 lacks the sufficient mantissa bits to distinguish between nanosecond intervals, resulting in a "staircase effect" or jittery rendering during high-zoom interactions.

Charton solves this by performing all internal domain calculations in i128 space before converting to a normalized ratio.

Relative Anchoring & Jitter Prevention

To maintain sub-pixel accuracy, the engine utilizes a Local Anchor Strategy. Instead of calculating global coordinates, it calculates positions relative to the current view's minimum value ($T_{anchor}$):

Step	Operation	Logic
1. Anchoring	$Toffset=(Tcurrent−Tanchor)$	Integer subtraction in `i128`
2. Normalizing	$Ratio=Toffset(f64)/Range(f64)$	Safe float division
3. Projecting	$Pixel=Ratio×ViewportSize$	Map to $f32$ for GPU

By subtracting the large epoch offset in the integer domain first, the resulting delta is small enough to be represented with perfect fidelity in an f64 ratio, ensuring a smooth rendering experience even at microsecond-level zoom.

Automatic Scale Degradation (Cosmic Scales)

When the temporal span exceeds the i64 limit or the capabilities of standard calendar libraries (e.g., spans of millions of years), the Temporal Engine undergoes Semantic Degradation:

Calendar Mode: Active for spans fitting within the i64 range. Supports leap years, months, and weekdays via the time crate.
Numerical Mode (Deep Time): Active for cosmic or geological scales. The engine stops attempting to format "Tuesdays" or "Months" and treats the input as a raw numerical axis (e.g., "13.8 Billion Years"), using scientific notation or custom unit-based labels.

Density-Based Interval Selection

The biggest challenge in temporal axes is preventing label overlap while maintaining a "natural" rhythm. Charton utilizes a Heuristic Step-Ladder to choose the most appropriate time interval based on the current zoom level and physical pixel density.

The engine calculates the Required_Seconds_Per_Tick using the formula:

$$Seconds_Per_Tick = \frac{Total_Domain_Seconds}{Viewport_Width / Min_Tick_Spacing}$$

Where Min_Tick_Spacing is typically 50-100 pixels. The engine then snaps to the nearest logical "Human Interval" from a predefined hierarchy:

Sub-second: 1ms, 5ms, 10ms, 100ms, 500ms
Seconds/Minutes: 1s, 5s, 15s, 30s, 1min, 5min, 15min, 30min
Hours/Days: 1hr, 6hr, 12hr, 1day, 1week
Long-term: 1month, 3months, 1year, 5years, 10years

Logical Tick Alignment (The "Clean" Start)

A common pitfall in temporal scaling is starting ticks at arbitrary timestamps (e.g., 12:04:13). To ensure professional aesthetics, Charton performs Calendar Alignment:

Step Calculation: Identify the chosen interval (e.g., 1 hour).
Floor Alignment: The first tick is "floored" to the nearest clean boundary. If the data starts at 12:04:13, the first tick is snapped to 12:00:00 or 13:00:00.
Stride Execution: Ticks are generated by adding the logical Duration (using the time crate) rather than a fixed number of nanoseconds, ensuring that transitions over leap years or varying month lengths (28 vs. 31 days) remain mathematically and visually correct.

Contextual Label Formatting

To save horizontal space, Charton uses a Context-Aware Formatter. The label's level of detail is determined by the span of the visible domain:

Multi-Level Guides (Advanced)

For long-range time series, Charton supports Multi-Level Axes. For instance, an axis might show "Days" as the primary ticks and "Months" as a secondary, bolder category label below them. This prevents the user from losing the "Year/Month" context when zoomed deep into a specific "Hour" range.

Charton: The Grammar of Graphics in Rust

Precision-Preserving i128 Math