zoom-lod-engine

A lightweight, engine-agnostic library for resolving stable zoom- or distance-based levels of detail (LOD) using hysteresis and temporal smoothing.

This library converts a continuous scalar signal (e.g., camera distance, zoom level, scale) into discrete, semantic levels (such as TINY, MICRO, MACRO, FAR) while avoiding flicker and unstable state transitions near threshold boundaries.

---

Why this library exists

Many visualization and rendering systems rely on simple threshold-based logic to decide levels of detail. While easy to implement, this approach often produces unstable behavior when input values fluctuate near boundaries, causing rapid oscillation between states.

zoom-lod-engine formalizes a common but often reimplemented pattern by combining:

• Hysteresis to prevent rapid state switching
• Temporal smoothing to reduce noise in the input signal
• Semantic level abstraction decoupled from rendering engines

The result is a deterministic and reusable logic layer that can be embedded in a wide range of systems.

---

Key features

• Engine-agnostic (no rendering or framework dependencies)
• Hysteresis-based level resolution
• Optional temporal smoothing (low-pass filter)
• Deterministic and testable behavior
• Semantic labels and numeric indices
• Suitable for real-time and interactive systems

---

Installation

npm install zoom-lod-engine

Basic usage

1. Create a zoom resolver

import { createZoomResolver } from "zoom-lod-engine"

const zoom = createZoomResolver({
  levels: {
    TINY:  { enter: 0, exit: 12000 },
    MICRO: { enter: 9000, exit: 45000 },
    MACRO: { enter: 38000, exit: 110000 },
    FAR:   { enter: 100000, exit: Infinity },
  },
  order: ["TINY", "MICRO", "MACRO", "FAR"],
  initial: "FAR",
  smoothing: 0.12
})

2. Update with a zoom or distance value

Call update whenever your zoom, camera distance, or scale changes.

const snapshot = zoom.update(cameraZ)

3. React to level changes

if (snapshot.changed) {
  console.log("LOD changed to:", snapshot.level)
}

How it works (high level)

At each update step:

The raw input signal is optionally clamped.

Temporal smoothing is applied to reduce noise.

The current level is retained if the smoothed value remains within its hysteresis band.

Otherwise, the next level is resolved deterministically based on band boundaries.

This approach avoids rapid oscillation while remaining responsive to meaningful changes in the input signal.

Output snapshot

Each update returns a snapshot describing the current resolver state:

{
  raw: number
  smoothed: number
  level: string
  levelIndex: number
  changed: boolean
  direction: "in" | "out" | "flat"
}

Example use cases

Map and GIS visualization

Scientific and data visualization

Simulation environments

Game logic layers

Scale-aware UI layout systems

Engine-agnostic design

The reference implementation is written in TypeScript, but the library is intentionally designed as a pure logic layer with no assumptions about rendering engines, graphics APIs, or runtime environments. The algorithm can be straightforwardly reimplemented in other programming languages or engines.