manim-web 0.18.0 → 0.19.0

package/dist/mobjects/three-d/InstancedMobject.d.ts

@@ -0,0 +1,130 @@
+import { Mobject, Vector3Tuple } from '../../core/Mobject';
+import { Mobject3D } from './Mobject3D';
+import * as THREE from 'three';
+/**
+ * A single instance of the shared template geometry.
+ *
+ * `position` is required. `rotation` is a Euler tuple in radians (`XYZ` order).
+ * `scale` is a uniform factor or a per-axis tuple. `color` is a CSS color string
+ * applied to this instance only; omit it to keep the material color.
+ */
+export interface InstanceTransform {
+    /** Instance position [x, y, z]. */
+    position: Vector3Tuple;
+    /** Euler rotation [x, y, z] in radians (XYZ order). Default: no rotation. */
+    rotation?: Vector3Tuple;
+    /** Uniform scale, or per-axis [x, y, z] scale. Default: 1. */
+    scale?: number | Vector3Tuple;
+    /** Per-instance CSS color. Default: inherit the material color. */
+    color?: string;
+}
+/**
+ * Options for creating an {@link InstancedMobject}.
+ *
+ * Provide a template as either an explicit `geometry` + `material`, or a
+ * `template` mobject to derive both from. If none is given, a unit box with a
+ * standard material is used.
+ */
+export interface InstancedMobjectOptions {
+    /** Geometry shared by every instance. Cloned on {@link InstancedMobject.copy}. */
+    geometry?: THREE.BufferGeometry;
+    /** Material shared by every instance. Cloned on {@link InstancedMobject.copy}. */
+    material?: THREE.Material;
+    /** Template mobject to derive geometry and material from (cloned, not kept). */
+    template?: Mobject;
+    /** Per-instance transforms. Default: empty (no instances). */
+    instances?: InstanceTransform[];
+    /** Base material color as a CSS color string. Default: '#ffffff'. */
+    color?: string;
+    /** Material opacity from 0 to 1. Default: 1. */
+    opacity?: number;
+}
+/**
+ * InstancedMobject - renders many copies of one template via `THREE.InstancedMesh`.
+ *
+ * This is a safe, opt-in mobject for large scenes. It draws `count` copies of a
+ * single geometry + material in ONE draw call, instead of one mesh per copy.
+ * It does not change the default render path: scenes that do not use it are
+ * unaffected.
+ *
+ * Each instance has its own transform (position, optional rotation and scale)
+ * and an optional per-instance color. Use {@link setInstances} to replace the
+ * whole set, or {@link setInstanceTransform} / {@link setInstanceColor} to
+ * update one instance in place.
+ *
+ * @example
+ * ```typescript
+ * const dots = new InstancedMobject({
+ *   geometry: new THREE.SphereGeometry(0.1, 16, 16),
+ *   material: new THREE.MeshStandardMaterial(),
+ *   instances: [
+ *     { position: [0, 0, 0], color: '#ff0000' },
+ *     { position: [1, 0, 0], scale: 2 },
+ *   ],
+ * });
+ * scene.add(dots);
+ * ```
+ */
+export declare class InstancedMobject extends Mobject3D {
+    private _geometry;
+    private _material;
+    private _instances;
+    /** The single InstancedMesh; null until the Three.js object is built. */
+    private _mesh;
+    constructor(options?: InstancedMobjectOptions);
+    /**
+     * Resolve the shared geometry and material from the options.
+     * Order: explicit geometry/material, then a template mobject, then a default
+     * unit box. A geometry or material derived from a template is cloned so the
+     * template is never mutated or disposed by this mobject.
+     */
+    private static _resolveTemplate;
+    /** Find the first Mesh in a Three.js subtree, or null if there is none. */
+    private static _findMesh;
+    /** Deep-copy one instance transform so callers cannot alias our state. */
+    private static _cloneTransform;
+    /**
+     * Build the InstancedMesh with `count = instances.length` and fill its matrix
+     * and color buffers. Wrapped in a Group so a later count change can swap the
+     * mesh without touching the scene-graph parent.
+     */
+    protected _createThreeObject(): THREE.Object3D;
+    /** Create a fresh InstancedMesh for the current instances and populate it. */
+    private _buildMesh;
+    /** Write every instance matrix (and color, when present) into `mesh`. */
+    private _writeAllInstances;
+    /** Compose a transform matrix for one instance into `out`. */
+    private static _composeMatrix;
+    /** Sync base material color and opacity onto the shared material. */
+    protected _syncMaterialToThree(): void;
+    /**
+     * Replace all instances. Reuses the existing mesh when the count is unchanged;
+     * otherwise rebuilds the InstancedMesh (its count is fixed at construction).
+     */
+    setInstances(instances: InstanceTransform[]): this;
+    /** Update one instance transform in place and flag the matrix buffer. */
+    setInstanceTransform(index: number, transform: Partial<InstanceTransform>): this;
+    /** Update one instance color in place and flag the color buffer. */
+    setInstanceColor(index: number, color: string): this;
+    private _assertIndex;
+    /** Number of instances this mobject draws. */
+    getInstanceCount(): number;
+    /** The single backing InstancedMesh, building the Three.js object if needed. */
+    getInstancedMesh(): THREE.InstancedMesh;
+    /** The transform of instance `index` as a Matrix4 (reads back from the mesh). */
+    getInstanceMatrix(index: number, out?: THREE.Matrix4): THREE.Matrix4;
+    /** The shared geometry used by every instance. */
+    getGeometry(): THREE.BufferGeometry;
+    /** The shared material used by every instance. */
+    getMaterial(): THREE.Material;
+    /**
+     * An instance cloud is empty only when it has no instances. The base
+     * {@link Mobject.getCenter} / {@link Mobject.getBounds} then skip the bounding
+     * box, which would be empty and throw.
+     */
+    isEmpty(): boolean;
+    /** Dispose the InstancedMesh buffers, geometry, and material. No leaks. */
+    dispose(): void;
+    copy(): InstancedMobject;
+}
+//# sourceMappingURL=InstancedMobject.d.ts.map

package/dist/mobjects/three-d/InstancedMobject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstancedMobject.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/InstancedMobject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,UAAU,CAAsB;IACxC,yEAAyE;IACzE,OAAO,CAAC,KAAK,CAAoC;gBAErC,OAAO,GAAE,uBAA4B;IAsBjD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAiC/B,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,SAAS;IAQxB,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,eAAe;IAQ9B;;;;OAIG;IACH,SAAS,CAAC,kBAAkB,IAAI,KAAK,CAAC,QAAQ;IAO9C,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAMlB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAe1B,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B,qEAAqE;cAClD,oBAAoB,IAAI,IAAI;IAQ/C;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAgBlD,yEAAyE;IACzE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAiBhF,oEAAoE;IACpE,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAWpD,OAAO,CAAC,YAAY;IAQpB,8CAA8C;IAC9C,gBAAgB,IAAI,MAAM;IAI1B,gFAAgF;IAChF,gBAAgB,IAAI,KAAK,CAAC,aAAa;IAQvC,iFAAiF;IACjF,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,KAAK,CAAC,OAA6B,GAAG,KAAK,CAAC,OAAO;IAMzF,kDAAkD;IAClD,WAAW,IAAI,KAAK,CAAC,cAAc;IAInC,kDAAkD;IAClD,WAAW,IAAI,KAAK,CAAC,QAAQ;IAI7B;;;;OAIG;IACM,OAAO,IAAI,OAAO;IAI3B,2EAA2E;IAClE,OAAO,IAAI,IAAI;IAOf,IAAI,IAAI,gBAAgB;CAWlC"}

package/dist/mobjects/three-d/index.d.ts

@@ -20,4 +20,5 @@ export { Prism, Dot3D, ThreeDVMobject, type PrismOptions, type Dot3DOptions, typ
 export { ConvexHull3D, type ConvexHull3DOptions } from './ConvexHull3D';
 export { marchingCubes, type MarchingCubesOptions, type MarchingCubesResult, type ScalarField3D, } from './marchingCubes';
 export { ImplicitSurface, type ImplicitSurfaceOptions } from './ImplicitSurface';
+export { InstancedMobject, type InstancedMobjectOptions, type InstanceTransform, } from './InstancedMobject';
 //# sourceMappingURL=index.d.ts.map

package/dist/mobjects/three-d/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,KAAK,wBAAwB,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EACL,KAAK,EACL,KAAK,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,KAAK,wBAAwB,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EACL,KAAK,EACL,KAAK,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAGjF,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC"}