Documentation

Technical reference for the Hieronymus observation engine, domain encoders, and shader pipeline.

Engine API

The ObservationEngine class, useObservation hook, worker message protocol, and result types.

•ObservationEngine — WebGL2 pipeline manager
•useObservation() — React hook for observation lifecycle
•WorkerInput / WorkerOutput — typed message protocol
•ObservationResult / MatchResult — output types

Writing Encoders

How to write a domain encoder that maps raw data to partition coordinates for the GPU pipeline.

•CPU preprocessor (TypeScript) — data normalization
•GPU shader (GLSL) — per-pixel encoding
•The S-entropy contract: S_k + S_t + S_e = 1
•Example: microscopy encoder walkthrough

Shader Reference

Complete reference for the 6-pass GPU shader pipeline with GLSL code and uniforms.

•Pass 1: Encode — raw data to partition features
•Pass 2: Partition — feature map to (n,l,m,s) coordinates
•Pass 3: Interference — cross-modal consistency check
•Pass 4: Entropy — S_k, S_t, S_e computation
•Pass 5: Display — false-colour visualization
•Uniforms reference table

Engine API

ObservationEngine

The core class that manages the WebGL2 pipeline. It compiles all shaders, creates framebuffers, and runs the multi-pass observation sequence.

class ObservationEngine {
  constructor(canvas: OffscreenCanvas | HTMLCanvasElement, width?: number, height?: number)
  observe(imageData: ArrayBuffer, width: number, height: number): ObservationResult
  match(imageDataA: ArrayBuffer, imageDataB: ArrayBuffer, w: number, h: number): MatchResult
  setUniforms(uniforms: Record<string, number>): void
  destroy(): void
}

useObservation Hook

React hook that manages the Web Worker lifecycle. Initialises the observation engine in a worker thread and provides methods to observe images and match image pairs.

const {
  ready,           // boolean — engine initialised
  loading,         // boolean — observation in progress
  result,          // ObservationResult | null
  matchResult,     // MatchResult | null
  error,           // string | null
  observe,         // (imageData: ArrayBuffer, w: number, h: number, encoder?: string) => void
  match,           // (dataA: ArrayBuffer, dataB: ArrayBuffer, w: number, h: number) => void
} = useObservation();

Result Types

interface ObservationResult {
  S_k: number;           // Kinetic entropy component
  S_t: number;           // Thermal entropy component
  S_e: number;           // Emission entropy component
  conservation: number;  // |S_k + S_t + S_e - 1| (should be ~0)
  partitionDepth: number;
  sharpness: number;
  noise: number;
  coherence: number;
  visibility: number;
  elapsed_ms: number;
}

interface MatchResult {
  score: number;         // Overall match score [0,1]
  visibility: number;    // Interference visibility
  circuits: number;      // Number of matching circuits detected
  S_distance: number;    // Distance on entropy simplex
  elapsed_ms: number;
  imageA: { S_k: number; S_t: number; S_e: number };
  imageB: { S_k: number; S_t: number; S_e: number };
}

Default Uniforms

Uniform	Default	Description
epsilon	0.15	Consistency threshold for dual-pixel agreement
J	1.0	Coupling constant for inter-modal interaction
beta	2.0	Inverse temperature for Boltzmann weighting
nmax	8	Maximum principal quantum number for partition depth
Aeg	2.58	Einstein A coefficient for spontaneous emission
alpha	0.5	Information transfer efficiency between modalities