Drum Gauge

Drum Gauge is a parametric 3D drum-style gauge component built on top of Three.js. It renders a rotating cylindrical scale where the current value is visually centered.

The component is intended for industrial dashboards, HMI panels, monitoring tools, and technical visualizations.

Features

• 3D cylindrical (drum-style) scale
• Smooth animated value transitions
• Supports negative values and decimal values
• Configurable numeric range
• Configurable major / minor / micro ticks
• Configurable numeric formatting
• Configurable font for scale labels
• TypeScript definitions included
• No CDN dependencies inside the library
• Works with modern bundlers (Vite, Webpack, Rollup, Parcel, Electron)

Installation

This package is distributed via npm.

Three.js is a peer dependency and must be installed by the consuming project.

npm install cak-drum-gauge three

Basic Usage (npm / bundler)

import { DrumGauge } from "cak-drum-gauge";

const container = document.getElementById("gauge");

const gauge = new DrumGauge(container, {
  minValue: -10,
  maxValue: 40,

  labelStep: 1,
  minorStep: 0.5,
  microStep: 0.25,
  decimals: 1,

  scaleFont: {
    family: "Helvetica Neue, Arial, system-ui, sans-serif",
    size: 70,
    weight: "normal"
  }
});

gauge.setValue(18.3);

API

Constructor

new DrumGauge(container: HTMLElement, options: DrumGaugeOptions)

Creates a new gauge instance.

Options

interface DrumGaugeOptions {
  minValue: number;
  maxValue: number;

  labelStep?: number;
  minorStep?: number;
  microStep?: number;

  decimals?: number;

  scaleFont?: {
    family?: string;
    size?: number;
    weight?: string | number;
  };
}

setValue(value: number)

Animates the gauge to the given value.

gauge.setValue(25.7);

destroy()

Releases renderer resources and removes DOM elements.

gauge.destroy();

Browser Usage Without a Bundler

When using Drum Gauge directly in the browser without a bundler, an import map must be provided for the Three.js dependency.

Example:

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js"
  }
}
</script>

<script type="module">
  import { DrumGauge } from "../dist/index.js";

  const gauge = new DrumGauge(
    document.getElementById("gauge"),
    { minValue: -10, maxValue: 40 }
  );
</script>

ES modules cannot be loaded from file:// URLs. Files must be served over HTTP.

A simple local server can be started with:

python3 -m http.server

Notes

• The library itself never loads dependencies from a CDN.
• CDN usage is limited strictly to the demo for browser-only testing.
• Dependency versions are always controlled by the consuming project.

License

MIT