Trillium EXTENSION

Trillium is the three.js connector for WildflowerJS. It draws your stores, pools and queries in a three.js scene. It installs as @wildflowerjs/three and is used in code as wildflower.three. A view is a store, so the entity under the pointer, the one selected, the canvas size and the frame cost are fields you bind in markup like any other.

What a data page in three.js needs

three.js draws a scene. A page that shows changing data in one also needs code around it, which you write yourself:

• A render loop, run once per frame.
• For each kind of marker, an InstancedMesh and the code that writes every entity's position, size and colour into it when the data changes.
• Resizing: the renderer, the pixel ratio and the camera's aspect, kept in step with the container.
• Picking: a raycaster, the code that turns a hit back into your data, and the rule for which hit wins when markers overlap.
• State for what is hovered and selected, and the code that shows it in the page.
• Labels placed over 3D points every frame, and hidden when something is in front of them.
• Cleanup: three.js frees no GPU memory by itself, so every geometry, material and texture needs a dispose() call.

What the extension adds

• Bindings. view.instanced(source, mesh, spec) writes a pool, a query's rows or any array into an InstancedMesh every frame. view.buffer() does the same for a flat array, such as the frame a Threads worker sends.
• A view that is a store. hovered, selected, size and stats are store fields. Markup binds $globe.selected.entity.name, and a component watches 'store:globe.selected', with nothing to wire up.
• The frame loop. The view draws once per frame, after every tick() and pool update, on the framework's own loop.
• Sizing. fit keeps the renderer and the camera matched to an element, and inset centres the scene beside a fixed panel.
• Picking. Clicks set selected, and pick() returns what is under any pointer event, ordered the way three.js draws it.
• Labels. follow() keeps an element over an entity, and an occluder hides what is behind a globe, a box or any mesh.
• Cleanup. wildflower.unregister('globe') frees the scene's geometries, materials and textures.
• Diagnostics with codes. Wrong arguments throw with a 3D- code, and each code has an entry on the error codes page.

You create the renderer, the camera, the meshes and the materials with three.js as usual, and the extension never imports three.js itself.

A short example

This draws earthquakes from a query as dots on a globe, and shows the one you click in a card.

import * as THREE from 'three';

wildflower.three.use(THREE);

const renderer = new THREE.WebGLRenderer({ antialias: true });
const container = document.getElementById('globe');
container.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, 1, 0.01, 100);
camera.position.set(0, 0, 3);

const globe = wildflower.three.view('globe', {
    renderer, scene, camera,
    fit: container,
    occluder: new THREE.Sphere(new THREE.Vector3(), 0.999)
});

const dots = new THREE.InstancedMesh(new THREE.CircleGeometry(0.01, 12), new THREE.MeshBasicMaterial(), 5000);
scene.add(dots);
const quakes = wildflower.getQuery('quakes');   // getQuery also starts the query fetching
globe.instanced(() => quakes.rows, dots, {
    name: 'quakes', position: ['x', 'y', 'z'], color: 'color'
});

<div class="card" data-show="$globe.selected">
    <h3 data-bind="$globe.selected.entity.place"></h3>
</div>

When the query refreshes, the dots move. A click on a dot fills the card, and a click on empty space clears it.

Compared with other three.js libraries

React Three Fiber and Threlte describe the whole scene as components, and A-Frame describes it as HTML elements. Trillium leaves the scene to three.js and binds your data into it, so a page that already uses three.js keeps its code and adds bindings.

For picking, all of them cast rays from the pointer, and Trillium does too. Their HTML labels hide behind objects by casting a ray to each label against the scene's meshes. Trillium's occluder accepts meshes in the same way, and a three.js Sphere or Box3 for shapes that are simple enough to test directly.

Requirements

WildflowerJS 1.5.4 or later, on the tiers with pools: mini-pool, lite, core, spa and full. The frame loop is part of the pool module, so nano and mini have none to draw from. three.js 0.160 or later.

Next

• Using Trillium: loading the extension, views, drawing data, sizing and cleanup.
• Picking and Labels: hover and selection, picking, labels and occluders.