manim-web 0.10.0 → 0.11.0

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

@@ -0,0 +1,122 @@
+import { Vector3Tuple } from '../../core/Mobject';
+import { Mobject3D } from './Mobject3D';
+/**
+ * ModelMobject - import an external 3D model (glTF / .glb / .obj) as a mobject.
+ *
+ * ManimCE has no way to import an external 3D model (see the long-standing
+ * "OBJ Support" request). Three.js ships loaders for the common formats, so
+ * manim-web exposes them through a mobject that drops the loaded
+ * `THREE.Object3D` into the normal Group/Mobject hierarchy. The model then
+ * participates in shift / scale / rotate, z-depth and the 3D camera exactly
+ * like a built-in primitive (Cube, Surface3D, ...).
+ *
+ * Scene-graph wiring (why there are nested groups):
+ *   wrapper      - returned as `_threeObject`; its local transform is written
+ *                  by `Mobject._syncToThree` from the mobject transform, so it
+ *                  must stay under manim's control alone.
+ *     content    - carries the `scale` and `upAxis` options.
+ *       center   - carries the `center` recenter offset.
+ *         model  - the pristine loaded Object3D (never mutated by options, so
+ *                  `copy()` can clone it and re-apply the options cleanly).
+ *
+ * The real Three.js example loaders are pulled in through a lazy dynamic
+ * `import()` on first use, so the base bundle and SSR never load them. Tests
+ * inject a loader (via the `loader` option or `setModelLoaderFactory`), which
+ * bypasses the import and the network entirely - mirroring the
+ * `setTypstCompiler` dependency-injection seam in TypstRenderer.
+ */
+import * as THREE from 'three';
+/** Supported model formats, picked from the URL extension. */
+export type ModelFormat = 'gltf' | 'obj';
+/**
+ * The model's up direction. An axis name, or an explicit vector. The model is
+ * rotated so this direction aligns with the scene up (+Y).
+ */
+export type ModelUpAxis = 'x' | 'y' | 'z' | Vector3Tuple;
+/** A GLTF-style result, whose root Object3D lives on `.scene`. */
+interface GltfLike {
+    scene: THREE.Object3D;
+}
+/**
+ * The minimal loader contract ModelMobject needs. Three.js GLTFLoader and
+ * OBJLoader both satisfy it structurally. Tests implement it with a stub.
+ */
+export interface ModelLoader {
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<THREE.Object3D | GltfLike>;
+}
+/** Builds a loader for a format. The DI seam set by `setModelLoaderFactory`. */
+export type ModelLoaderFactory = (format: ModelFormat) => ModelLoader | Promise<ModelLoader>;
+/** Options for {@link ModelMobject.fromUrl}. */
+export interface ModelMobjectOptions {
+    /** Uniform factor, or per-axis factors, applied to the loaded model. */
+    scale?: number | Vector3Tuple;
+    /** The model's up direction; the model is rotated to the scene up (+Y). */
+    upAxis?: ModelUpAxis;
+    /** Recenter the model's bounding box to the origin. Default: false. */
+    center?: boolean;
+    /** Convenience fill color applied to every mesh material. */
+    color?: string;
+    /** Replace every mesh material with this one. Wins over `color`. */
+    materialOverride?: THREE.Material;
+    /** Progress callback forwarded to the loader. */
+    onProgress?: (event: ProgressEvent) => void;
+    /** Inject a loader directly (bypasses the factory and the network). */
+    loader?: ModelLoader;
+    /**
+     * When false, a load failure resolves to an empty ModelMobject whose
+     * {@link ModelMobject.getLoadError} holds the error instead of rejecting.
+     * Default: true (the returned promise rejects on failure).
+     */
+    throwOnError?: boolean;
+}
+/**
+ * Inject a loader factory, replacing the lazy-loaded Three.js example loaders.
+ * Pass `null` to restore the default. Tests use this to avoid any real loader.
+ */
+export declare function setModelLoaderFactory(factory: ModelLoaderFactory | null): void;
+/** Pick the model format from a URL's extension (ignores query and fragment). */
+export declare function detectModelFormat(url: string): ModelFormat;
+export declare class ModelMobject extends Mobject3D {
+    private readonly _model;
+    private readonly _centerGroup;
+    private readonly _content;
+    private readonly _wrapper;
+    private readonly _format;
+    private readonly _options;
+    private _loadError;
+    /**
+     * Prefer {@link ModelMobject.fromUrl}. This constructor wraps an already
+     * loaded Object3D (or `null` for an empty placeholder) and applies the
+     * geometry options.
+     */
+    constructor(object: THREE.Object3D | null, options?: ModelMobjectOptions, format?: ModelFormat | null);
+    /**
+     * Load a model from a URL and return a ready ModelMobject.
+     *
+     * The loader is chosen from the extension: `.glb` / `.gltf` -> GLTFLoader,
+     * `.obj` -> OBJLoader. Inject a loader with the `loader` option (or
+     * `setModelLoaderFactory`) to avoid the network, e.g. in tests.
+     */
+    static fromUrl(url: string, options?: ModelMobjectOptions): Promise<ModelMobject>;
+    /** Offset the center group so the model's bounding box sits at the origin. */
+    private _recenter;
+    /** Rotate the content group so the model's up axis aligns with +Y. */
+    private _applyUpAxis;
+    private _upAxisVector;
+    /** Scale the content group uniformly or per axis. */
+    private _applyScale;
+    /** Apply a material override, or a fill color, to every mesh in the model. */
+    private _applyMaterials;
+    private _applyColor;
+    private _forEachMesh;
+    /** The loaded model root (an empty Group if the load failed). */
+    getObject(): THREE.Object3D;
+    /** The format this model was loaded as, or null for a bare construction. */
+    getFormat(): ModelFormat | null;
+    /** The load error, or null if the model loaded successfully. */
+    getLoadError(): Error | null;
+    protected _createThreeObject(): THREE.Object3D;
+    copy(): ModelMobject;
+}
+export {};
+//# sourceMappingURL=ModelMobject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModelMobject.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/ModelMobject.ts"],"names":[],"mappings":"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"}

package/dist/mobjects/video/VideoMobject.d.ts

@@ -0,0 +1,126 @@
+import { Vector3Tuple } from '../../core/Mobject';
+import { TexturedMobject } from '../../core/TexturedMobject';
+import * as THREE from 'three';
+/**
+ * Options for creating a VideoMobject.
+ */
+export interface VideoMobjectOptions {
+    /** Video source URL. Required. */
+    src: string;
+    /** Loop playback when it reaches the end. Default: false */
+    loop?: boolean;
+    /** Mute the audio track. Default: true (needed for browser autoplay policies) */
+    muted?: boolean;
+    /** Start playing as soon as data is available. Default: false */
+    autoplay?: boolean;
+    /** Playback speed multiplier (1 = normal). Default: 1 */
+    playbackRate?: number;
+    /** Width of the video in scene units. Default: auto from aspect ratio */
+    width?: number;
+    /** Height of the video in scene units. Default: auto from aspect ratio */
+    height?: number;
+    /** If both width and height given, fit inside the box preserving aspect. Default: true */
+    scaleToFit?: boolean;
+    /** Center position [x, y, z]. Default: [0, 0, 0] */
+    center?: Vector3Tuple;
+    /** Opacity from 0 to 1. Default: 1 */
+    opacity?: number;
+    /** Render both sides of the plane. Default: false */
+    doubleSided?: boolean;
+    /** crossOrigin attribute for the video element. Default: 'anonymous' */
+    crossOrigin?: string | null;
+}
+/**
+ * VideoMobject - display an HTML `<video>` as a movable, scalable mobject.
+ *
+ * The video is drawn onto a `THREE.PlaneGeometry` through a
+ * `THREE.VideoTexture`, mirroring how {@link ImageMobject} draws images. It
+ * therefore participates in the standard mobject transforms (shift, scale,
+ * rotate), z-index/depth, opacity, and `scene.add`.
+ *
+ * Playback follows the DOM video clock during normal play. When the Player
+ * scrubs or seeks, call {@link syncToTime} so the displayed frame follows the
+ * scene time.
+ *
+ * @example
+ * ```typescript
+ * const clip = new VideoMobject({ src: 'intro.mp4', width: 6, loop: true });
+ * scene.add(clip);
+ * await clip.waitForLoad();
+ * clip.play();
+ * ```
+ */
+export declare class VideoMobject extends TexturedMobject {
+    protected _source: string;
+    protected _loop: boolean;
+    protected _muted: boolean;
+    protected _autoplay: boolean;
+    protected _playbackRate: number;
+    protected _width: number | undefined;
+    protected _height: number | undefined;
+    protected _scaleToFit: boolean;
+    protected _centerPoint: Vector3Tuple;
+    protected _doubleSided: boolean;
+    protected _crossOrigin: string | null;
+    protected _video: HTMLVideoElement | null;
+    protected _texture: THREE.VideoTexture | null;
+    protected _videoLoaded: boolean;
+    protected _loadError: Error | null;
+    protected _naturalWidth: number;
+    protected _naturalHeight: number;
+    private _mesh;
+    private _loadPromise;
+    private _loadResolve;
+    private _loadReject;
+    constructor(options: VideoMobjectOptions);
+    /**
+     * Create the DOM video element and its VideoTexture. Node/SSR-safe: when
+     * `document` is missing, the load fails gracefully instead of throwing.
+     */
+    private _createVideo;
+    /** Record a load error and reject the ready promise once. */
+    private _failLoad;
+    /** Promise that resolves on `loadeddata` and rejects on load error. */
+    waitForLoad(): Promise<void>;
+    /** The captured load error, or null when no error occurred. */
+    getLoadError(): Error | null;
+    /** Whether the first frame of video data is available. */
+    isLoaded(): boolean;
+    /** The video source URL. */
+    getSource(): string;
+    /** Start (or resume) playback. Silently ignores autoplay rejections. */
+    play(): this;
+    /** Pause playback. */
+    pause(): this;
+    /** Seek the video to an absolute time in seconds, clamped to [0, duration]. */
+    seek(seconds: number): this;
+    /** Set the playback speed multiplier. */
+    setPlaybackRate(rate: number): this;
+    /** Duration of the video in seconds (NaN until metadata loads). */
+    get duration(): number;
+    /**
+     * Follow the Player clock: show the frame at `sceneTime`. Use this on scrub
+     * and seek so the displayed frame tracks the timeline position.
+     */
+    syncToTime(sceneTime: number): this;
+    /** Clamp a time to [0, duration]; duration may be NaN before metadata loads. */
+    private _clampTime;
+    /** Display dimensions from width/height options and the natural size. */
+    private _calculateDimensions;
+    protected _createThreeObject(): THREE.Object3D;
+    getDisplayMeshLength(): number;
+    getDisplayMeshes(): THREE.Mesh[];
+    applyTextureFrom(other: TexturedMobject): void;
+    applyVisualSize(width: number, height: number): void;
+    applyContentFrom(other: TexturedMobject): void;
+    protected _updateGeometry(): void;
+    protected _syncMaterialToThree(): void;
+    getBoundingBox(): {
+        width: number;
+        height: number;
+        depth: number;
+    };
+    copy(): VideoMobject;
+    dispose(): void;
+}
+//# sourceMappingURL=VideoMobject.d.ts.map

package/dist/mobjects/video/VideoMobject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VideoMobject.d.ts","sourceRoot":"","sources":["../../../src/mobjects/video/VideoMobject.ts"],"names":[],"mappings":"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"}

package/dist/mobjects/video/index.d.ts

@@ -0,0 +1,2 @@
+export { VideoMobject, type VideoMobjectOptions } from './VideoMobject';
+//# sourceMappingURL=index.d.ts.map

package/dist/mobjects/video/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/video/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}