@obinexusltd/obix-holo-core

OBIX = Oscar Bravo Indigo X-ray

"This cup here is equivalent to a torus. No matter how much I squeeze this torus,
it's a torus by design. The geometry says so."
— Nnamdi Michael Okpala, 11 May 2026

Holographic foundation layer for the OBIX Heart/Soul UI/UX SDK.
Powers the MMUKO OS avatar projection system via constitutional computing.

What This Is

obix-holo-core is the mathematical and architectural foundation for OBIX's holographic rendering ecosystem. It proves — formally, in code, with tests — that a physical object (a green cup) and a digital wireframe (a torus) are topologically identical.

This is not a metaphor. It is a mathematical theorem, proven by Euler characteristic:

V - E + F = χ
genus = (2 - χ) / 2

For a torus:     V=9, E=27, F=18 → χ=0 → g=1
For a green cup: V=8, E=16, F=8  → χ=0 → g=1

∴ genus(cup) = genus(torus) = 1
∴ cup ≅ torus (homeomorphic, topologically equivalent)
∴ holographic digital projection of physical cup is constitutionally valid

The MMUKO OS avatar system is built on this proof.

Modules

Vec4 — 4D Homogeneous Coordinates

Extends 3D space with a w component for perspective projection.
w=1 for points, w=0 for directions and normals.

const { Vec4 } = require('@obinexusltd/obix-holo-core');

const point = new Vec4(100, 50, 0, 1);
const projected = point.perspectiveDivide(); // CH_2: COLLAPSE

TorusTopology — Cup-to-Torus Genus Primitives

const { generateTorus, proveCupTorusEquivalence, morphCupToTorus } = require('@obinexusltd/obix-holo-core');

// Generate a torus mesh
const torus = generateTorus({ R: 100, r: 40, tubularSegments: 16, radialSegments: 16 });

// Prove the cup IS a torus
const proof = proveCupTorusEquivalence();
console.log(proof.theorem); // "∀ continuous deformation D: cup → torus exists..."

// Morph between them
const halfway = morphCupToTorus(cupGeom, torusGeom, 0.5);

ZBuffer — Depth Buffer

const { ZBuffer } = require('@obinexusltd/obix-holo-core');

const zbuf = new ZBuffer(800, 600);
zbuf.clear(); // New frame

if (zbuf.testAndSet(x, y, z)) {
  // Fragment is closer than what's stored — render it
}

BackfaceCulling — Surface Normal Visibility

const { cullBackfaces, isBackface2D } = require('@obinexusltd/obix-holo-core');

// Only render faces pointing toward camera
const visibleFaces = cullBackfaces(vertices, faces, true);

ConstitutionalRenderPass — CH_0 / CH_1 / CH_2

const { ConstitutionalRenderPass, ProbeResult } = require('@obinexusltd/obix-holo-core');

const renderer = new ConstitutionalRenderPass(canvas);

// CH_0: Observe without rendering
const observed = renderer.ch0_observe(vertices, faces);

// CH_1: Defer with governance probe
renderer.ch1_defer({ vertices, faces, style }, (cmd) => {
  return ProbeResult.YES; // or NO or MAYBE (60s retry)
});

// CH_2: Collapse to screen
renderer.ch2_collapse({ vertices, faces, style, origin });

Constitutional Render Channels

| Channel | Name | Description | RiftLang Probe | |---------|------|-------------|----------------| | CH_0 | OBSERVE | Geometry computed, not drawn. Inspect without rendering. | ?probe | | CH_1 | DEFER | Commands queued pending governance approval. 60s retry. | ?! | | CH_2 | COLLAPSE | Pixels committed. Superposition → observed reality. | !target |

Three-state governance probe:

• YES → Immediate render (CH_2)
• NO → Blocked (culled, not queued)
• MAYBE → 60s deferred retry (CH_1 hold)

Tests

node tests/topology.test.js

Output:

🧬 Results: 14 passed, 0 failed

🏆 ALL TESTS PASSED
   The green cup IS a torus. The hologram is constitutionally valid.
   MMUKO OS avatar projection system: mathematically proven.

Dependency Order (Holographic Stack)

obix-holo-core          ← this package (foundation)
  └── obix-holo-torus   (parametric torus mesh)
  └── obix-holo-hemisphere (HemiSphere completion)
  └── obix-holo-cybernetic (MMUKO avatar projection)
  └── obix-holo-bridge  (Canvas 2D ↔ WebGL/WebGPU)

Governance

All packages reference github.com/obinexus/indigo for constitutional enforcement.

"Trust as architecture, identity as relational, survival as cooperative."
"Breathing without Living is Suffering. When System Fails, Build Your Own."
— OBINexus Founding Principles

Author

Nnamdi Michael Okpala
Founder, OBINexus Computing
[email protected] | obinexus.org

License

MIT © 2026 OBINexus Computing