encryption-wave

A configurable WebGL "encryption wave" hero effect. A coloured wave sweeps across a 3D-looking object (built from an image + a depth map), drawing a glitchy matrix overlay in and wiping it back out, with depth-driven ripples, selective bloom, and an optional ground reflection. Framework-agnostic — it mounts into any DOM element.

Install

npm i encryption-wave three

three is a peer dependency (so your app controls the version). Requires three ≥ 0.160.

Usage

import { EncryptionWave } from 'encryption-wave';

const wave = new EncryptionWave(document.getElementById('hero'), {
  color: '/gpu.png',        // the object — cut out via its alpha channel
  depth: '/gpu-depth.png',  // matching depth map (white = near)
  config: {
    waveColor: '#9d4bff',
    fullscreen: false,      // windowed -> shows the ground reflection
    size: 0.7,
    holdDrawn: 1.5,         // seconds the surface stays encrypted before the removal wave
    holdClean: 1.2,         // seconds clean before the next spawn wave
    crossSecs: 1.5,         // seconds for a wave to cross the object
  },
});

// later
wave.update({ waveColor: '#39ffd0', reflect: true });
wave.pause();  wave.play();
wave.setImages('/other.png', '/other-depth.png');
wave.destroy();

The effect sizes itself to the container (and follows it via ResizeObserver), so give the container a width/height:

<div id="hero" style="position:relative; width:100%; aspect-ratio:16/9;"></div>

Providing the graphic + depth map

• color — a PNG/WebP of the object with a transparent background (the alpha channel is the cutout). Any image dimensions/aspect work.
• depth — a matching grayscale depth map (e.g. from Depth Anything V2); white = near.

Both accept a URL string, a decoded HTMLImageElement / HTMLCanvasElement / ImageBitmap, or a ready THREE.Texture.

A ready-to-try pair lives in sample/ (color.png + depth.png).

API

| Member | Description | | --- | --- | | new EncryptionWave(container, options) | Mount the effect. options: { color, depth, config?, autoStart?, maxPixelRatio? }. | | .update(partialConfig) | Merge & apply config changes live. | | .setImages(color, depth) | Swap the model. | | .play() / .pause() | Start/stop the animation clock. | | .resize() | Re-read container size (also automatic). | | .destroy() | Stop the loop and release all GPU/DOM resources. | | .config | The current resolved EncryptionWaveConfig. |

DEFAULT_CONFIG and the full EncryptionWaveConfig / EncryptionWaveOptions types are exported. Every config field is documented in the type definitions.

Tuning a look

The repo ships a visual editor (the index.html / main.js at the root — not part of the npm package) with a live control panel for every parameter. Dial in a look there, export the preset JSON, and pass those values straight into config. (The model, scopes, shared, and per-model models fields of an exported preset map onto this library's flat config.)

Build from source

npm install
npm run build      # -> dist/ (ESM + CJS + types)
npm run typecheck

Editor / playground

The repo includes a live editor (index.html + main.js) — *not part of the npm package_ — for dialling in a look. It renders through the built package and adds a control panel, per-model config scoping, preset export/import, and local model upload (pick a colour + depth file at once, name it, test it). Its built-in models (NVIDIA HGX, H200) and default-preset.json stay in the repo only.

npm run build          # the editor imports ./dist
python3 _serve.py      # http://localhost:8137  (no-cache static server)

Tune a look, export preset, and feed those values into the library's config.

License

MIT