telperion 0.0.1 → 0.1.0

package/dist/browser/specimen.d.ts

@@ -0,0 +1,106 @@
+import type { Family } from './core';
+import type { LeafReference, LeafWords } from './leaf';
+export interface NodeIdentity {
+    birth: number;
+    key: {
+        idx: number;
+        version: number;
+    };
+}
+export interface PlacementIdentity {
+    shoot: NodeIdentity;
+    station: number;
+}
+/** The three packed words of one leaf; `./leaf` decodes them. */
+export interface Placement {
+    identity: PlacementIdentity;
+    leaf: LeafWords;
+}
+export interface Run {
+    identity: NodeIdentity;
+    nodes: {
+        identity: NodeIdentity;
+        parent: NodeIdentity | null;
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        radii: number[];
+        kind: string;
+        stem: boolean;
+    }[];
+}
+export interface ChangeRecord {
+    born_runs: Run[];
+    resized_runs: Run[];
+    shed_runs: NodeIdentity[];
+    born_placements: Placement[];
+    moved_placements: Placement[];
+    shed_placements: PlacementIdentity[];
+}
+export interface SpecimenRead {
+    age: number;
+    envelope: Family['skeleton']['envelope'];
+    surfaceHeight: number;
+    diagnostics: {
+        node_capped: boolean;
+        level_capped: boolean;
+        attraction_capped: boolean;
+    };
+    crossover: number;
+    shed: NodeIdentity[];
+    nodes: NodeIdentity[];
+    placements: PlacementIdentity[];
+    structure: {
+        values: Float64Array;
+        topology: Uint32Array;
+    };
+    /** Three u32 words a leaf, in placement order, and the box they decode
+     * against - one box for the family, so every age reads the same one. */
+    leaves: Uint32Array;
+    foliageReference: LeafReference;
+}
+/** Owned schema-3 little-endian chronicle and writer frontiers, without meshes.
+ * Caller mutation never reaches a retained specimen. */
+export interface SpecimenSnapshot {
+    schema: 3;
+    data: Uint8Array;
+}
+export interface SpecimenHandle {
+    readonly frontier: number;
+    readonly historyCap: number;
+    read(age?: number): SpecimenRead;
+    advance(years: number): {
+        frontier: number;
+        changes: ChangeRecord;
+    };
+    changes(from: number, to: number): ChangeRecord;
+    setNodeCeiling(limit: number): void;
+    setHistoryCap(years: number): void;
+    snapshot(): SpecimenSnapshot;
+    release(): void;
+}
+export interface SpecimenExports {
+    memory: WebAssembly.Memory;
+    request_alloc(n: number): number;
+    request_ptr(): number;
+    buffer_ptr(slot: number): number;
+    buffer_len(slot: number): number;
+    specimen_node_ceiling(handle: number, limit: number): number;
+    specimen_history_cap(handle: number, years: number): number;
+    specimen_build(cap: number): number;
+    specimen_frontier(handle: number): number;
+    specimen_read(handle: number, age: number): number;
+    specimen_advance(handle: number, years: number): number;
+    specimen_changes(handle: number, from: number, to: number): number;
+    specimen_snapshot(handle: number): number;
+    specimen_snapshot_alloc(length: number): number;
+    specimen_snapshot_release(): void;
+    specimen_import(): number;
+    specimen_release(handle: number): number;
+}
+export declare function specimenBinding(get: () => SpecimenExports, check: (code: number) => void, metadata: () => unknown): {
+    build(family: Family | string, cap: number): SpecimenHandle;
+    import(snapshot: SpecimenSnapshot): SpecimenHandle;
+};

package/dist/field/index.d.ts

@@ -0,0 +1,43 @@
+export interface Bounds {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/** One batch query's answers, one entry per cell, as the core's field answers
+ * them. `flags` bits: wood = 1, foliage = 2. `woodRadius` is the thickest
+ * wood sweep reaching the cell, in metres, zero without wood. `leaves`
+ * estimates the leaf stations in the cell before the crown cull. `limbs` is
+ * the owning limb system, `NO_LIMB` where no foliage reaches. */
+export interface FieldAnswer {
+    flags: Uint8Array;
+    woodRadius: Float32Array;
+    leaves: Float32Array;
+    limbs: Uint32Array;
+}
+export declare const NO_LIMB = 4294967295;
+/** A grown tree's field. `query` takes packed cells, four f64 each: centre
+ * x, y, z and the half extent of a closed cube; touching counts and a zero
+ * half extent is a point. A batch with a length that is not a multiple of
+ * four, a non-finite centre or a negative half extent is refused whole.
+ * `release` drops the tree; a released tree refuses every query. */
+export interface FieldTree {
+    readonly species: string;
+    readonly seed: number;
+    readonly bounds: Bounds;
+    query(cells: Float64Array): FieldAnswer;
+    release(): void;
+}
+export type FieldSource = BufferSource | Response | WebAssembly.Module;
+export interface GrowOptions {
+    /** The lateral order whose systems name limbs; the family's own when left
+     * out. A higher order parts the crown into more and smaller systems. */
+    limbOrder?: number;
+    /** Where the slim Wasm comes from. Left out, it is fetched from
+     * `telperion-field.wasm` beside this module. */
+    source?: FieldSource;
+}
+/** Compiles the slim Wasm once; a source given to every `growField` call is
+ * compiled each time, so a caller that grows many trees passes a Module. */
+export declare function compileField(source?: FieldSource): Promise<WebAssembly.Module>;
+/** Grows `species` at `seed` and answers its field. An unknown species id,
+ * or one the catalogue does not serve, is refused with the core's error. */
+export declare function growField(species: string, seed: number, options?: GrowOptions): Promise<FieldTree>;

package/dist/field/voxelize.d.ts

@@ -0,0 +1,44 @@
+import type { Bounds, FieldAnswer } from "./index";
+/** A cubic grid of `n` cells a side, `cell` metres each, `n - 2` of them
+ * spanning the field's longest axis, centred on the bounds with one empty
+ * cell below the lowest point. `cells` is the packed batch the field
+ * queries; cell `i + n * (j + n * k)` is at `origin + (i + 0.5, j + 0.5,
+ * k + 0.5) * cell`. */
+export interface Grid {
+    n: number;
+    cell: number;
+    origin: [number, number, number];
+    cells: Float64Array;
+}
+export declare function grid(bounds: Bounds, n: number): Grid;
+/** The centre of cell `index` in metres. */
+export declare function centre({ n, cell, origin }: Grid, index: number): [number, number, number];
+/** How foliage cells thin to the keep fraction. `coin` drops whole limb
+ * systems by a stable coin per limb id. `density` keeps the cells with the
+ * most leaf stations. `mass` keeps the cells nearest to drawn wood. `tuft`
+ * keeps each limb system's rounded mass about its own centre. `gap` erodes
+ * each system where it meets a neighbouring one, so the crown's outer
+ * surface stays and a hanging curtain stays a curtain. */
+export type ThinRule = "coin" | "density" | "mass" | "tuft" | "gap";
+export interface Thinning {
+    rule: ThinRule;
+    keep: number;
+}
+export interface Dials {
+    /** Wood draws where the cell's thickest wood radius is at least this, in
+     * metres; the owner's reading was about 2 cm for a broadleaf and 1 cm
+     * for the spruce. */
+    woodCutoff: number;
+    /** Left out, no foliage draws: the wood alone. */
+    thin?: Thinning;
+}
+/** Cell indices to draw as wood and as foliage, and the number of distinct
+ * limb systems the foliage was thinned over. */
+export interface Cubes {
+    wood: Uint32Array;
+    foliage: Uint32Array;
+    clumps: number;
+}
+export declare function voxelize(grid: Grid, answer: FieldAnswer, dials: Dials): Cubes;
+/** A stable coin per limb id: the same limb always answers the same. */
+export declare function coin(limb: number, keep: number): boolean;

package/dist/field.js

@@ -0,0 +1,62 @@
+var m = Object.defineProperty;
+var w = (r, e, t) => e in r ? m(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
+var s = (r, e, t) => w(r, typeof e != "symbol" ? e + "" : e, t);
+import { w as y } from "./wasm-source.js";
+const _ = 4294967295, h = 4294967295, f = 2 ** 32;
+let c;
+function b(r) {
+  return r instanceof WebAssembly.Module ? Promise.resolve(r) : r !== void 0 ? d(r) : (c ?? (c = d(y(new URL("./telperion-field.wasm", import.meta.url))).catch((e) => {
+    throw c = void 0, e;
+  })), c);
+}
+async function d(r) {
+  const e = await r;
+  if (e instanceof Response) {
+    if (!e.ok) throw Error(`Field core load failed: HTTP ${e.status}`);
+    return WebAssembly.compile(await e.arrayBuffer());
+  }
+  return WebAssembly.compile(e);
+}
+function u(r, e, t = f) {
+  if (!Number.isInteger(r) || r < 0 || r >= t) throw RangeError(`${e} is an unsigned 32-bit integer`);
+  return r;
+}
+async function x(r, e, t = {}) {
+  u(e, "seed");
+  const o = t.limbOrder === void 0 ? h : u(t.limbOrder, "limbOrder", f - 1), n = new TextEncoder().encode(r), l = await b(t.source), { exports: i } = await WebAssembly.instantiate(l, {});
+  return new p(i, r, e, n, o);
+}
+class p {
+  constructor(e, t, o, n, l) {
+    s(this, "species");
+    s(this, "seed");
+    s(this, "bounds");
+    s(this, "exports");
+    s(this, "revision");
+    this.species = t, this.seed = o, this.exports = e, a(e, e.species_alloc(n.length)), new Uint8Array(e.memory.buffer, e.species_ptr(), n.length).set(n), a(e, e.grow(o, l)), this.revision = e.revision();
+    const i = new Float64Array(e.memory.buffer, e.bounds_ptr(), e.bounds_len());
+    if (i.length !== 6) throw Error("Field core: the field is empty");
+    this.bounds = { min: [i[0], i[1], i[2]], max: [i[3], i[4], i[5]] };
+  }
+  query(e) {
+    const t = this.exports;
+    if (!t) throw Error("Field tree is released");
+    if (!(e instanceof Float64Array) || e.length % 4) throw Error("Field cells require packed Float64Array x,y,z,halfExtent");
+    a(t, t.query_alloc(e.length / 4)), new Float64Array(t.memory.buffer, t.query_ptr(), e.length).set(e), a(t, t.query(this.revision));
+    const o = (n) => t.memory.buffer.slice(t.answer_ptr(n), t.answer_ptr(n) + t.answer_len(n) * A[n]);
+    return { flags: new Uint8Array(o(0)), woodRadius: new Float32Array(o(1)), leaves: new Float32Array(o(2)), limbs: new Uint32Array(o(3)) };
+  }
+  release() {
+    var e;
+    (e = this.exports) == null || e.release(), this.exports = void 0;
+  }
+}
+const A = [1, 4, 4, 4];
+function a(r, e) {
+  if (e) throw Error(`Field core: ${new TextDecoder().decode(new Uint8Array(r.memory.buffer, r.error_ptr(), r.error_len()))}`);
+}
+export {
+  _ as NO_LIMB,
+  b as compileField,
+  x as growField
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { TreeEngine, initializeTreeCore, ORDINARY, OREGON_WHITE_OAK, NORWAY_SPRUCE, SILVER_BIRCH, presetById, TELPERION, LAURELIN, TWO_TREES, PRESETS } from "./browser/core";
+export type { FoliageAnatomy, Family, TreePreset, Outputs, Bounds, Timings, Diagnostics, TreeOutput } from "./browser/core";
+export { LEAF_WORDS, leafWords, leafPosition, leafScale, leafRotation, leafTransform } from "./browser/leaf";
+export type { LeafReference, LeafWords, Vector } from "./browser/leaf";
+export { createRenderer } from "./browser/render";
+export type { FrameStats, Point, Pose, Renderer, Submitted, TimingReport, View } from "./browser/render";
+export type { SpecimenHandle, SpecimenSnapshot, SpecimenRead, ChangeRecord, NodeIdentity, PlacementIdentity, Placement } from "./browser/specimen";