@redwilly/anima 0.1.0

package/dist/core/camera/Camera.js

@@ -0,0 +1,175 @@
+import { Vector2 } from '../math/Vector2/Vector2';
+import { Matrix3x3 } from '../math/matrix/Matrix3x3';
+import { CameraFrame } from './CameraFrame';
+import { MANIM_FRAME_HEIGHT } from './types';
+/**
+ * Camera manages the view into the scene.
+ * Uses CameraFrame (a Mobject) to store transform state, enabling camera animations.
+ *
+ * The Camera provides both instant manipulation methods (panTo, zoomTo) and
+ * access to the CameraFrame for fluent animation APIs.
+ *
+ * @example
+ * // Instant camera manipulation
+ * camera.zoomTo(2);
+ * camera.panTo(new Vector2(5, 3));
+ *
+ * @example
+ * // Animated camera movement via frame
+ * this.play(this.frame.zoomIn(2).duration(1));
+ * this.play(this.frame.centerOn(circle).duration(0.5));
+ */
+export class Camera {
+    config;
+    /** The CameraFrame that stores the camera's transform state. Use this for animations. */
+    frame;
+    /**
+     * Creates a new Camera with the specified viewport dimensions.
+     *
+     * @param config - Configuration options
+     * @param config.pixelWidth - Width of the viewport in pixels (default: 1920)
+     * @param config.pixelHeight - Height of the viewport in pixels (default: 1080)
+     */
+    constructor(config = {}) {
+        this.config = {
+            pixelWidth: config.pixelWidth ?? 1920,
+            pixelHeight: config.pixelHeight ?? 1080,
+        };
+        this.frame = new CameraFrame({
+            pixelWidth: this.config.pixelWidth,
+            pixelHeight: this.config.pixelHeight,
+        });
+    }
+    // ========== Frame Dimensions (Manim-compatible) ==========
+    get frameHeight() {
+        return MANIM_FRAME_HEIGHT;
+    }
+    get frameWidth() {
+        const aspectRatio = this.config.pixelWidth / this.config.pixelHeight;
+        return MANIM_FRAME_HEIGHT * aspectRatio;
+    }
+    get frameYRadius() {
+        return this.frameHeight / 2;
+    }
+    get frameXRadius() {
+        return this.frameWidth / 2;
+    }
+    // ========== Pixel Dimensions ==========
+    get pixelWidth() {
+        return this.config.pixelWidth;
+    }
+    get pixelHeight() {
+        return this.config.pixelHeight;
+    }
+    // ========== Camera Transform Properties (read from frame) ==========
+    get position() {
+        return this.frame.position;
+    }
+    get zoom() {
+        return 1 / this.frame.scale.x;
+    }
+    get rotation() {
+        return this.frame.rotation;
+    }
+    // ========== Pan Operations (proxy to frame) ==========
+    pan(delta) {
+        const current = this.frame.position;
+        this.frame.pos(current.x + delta.x, current.y + delta.y);
+        return this;
+    }
+    panTo(position) {
+        this.frame.pos(position.x, position.y);
+        return this;
+    }
+    // ========== Zoom Operations (proxy to frame) ==========
+    zoomTo(level) {
+        if (level <= 0) {
+            throw new Error('Zoom level must be positive');
+        }
+        const frameScale = 1 / level;
+        this.frame.setScale(frameScale, frameScale);
+        return this;
+    }
+    // ========== Rotation Operations (proxy to frame) ==========
+    rotateTo(angle) {
+        this.frame.setRotation(angle);
+        return this;
+    }
+    // ========== View Matrix ==========
+    getViewMatrix() {
+        const framePos = this.frame.position;
+        const frameScale = this.frame.scale;
+        const frameRotation = this.frame.rotation;
+        const zoomX = 1 / frameScale.x;
+        const zoomY = 1 / frameScale.y;
+        const translate = Matrix3x3.translation(-framePos.x, -framePos.y);
+        const rotate = Matrix3x3.rotation(-frameRotation);
+        const scale = Matrix3x3.scale(zoomX, zoomY);
+        return scale.multiply(rotate).multiply(translate);
+    }
+    // ========== Coordinate Transforms ==========
+    /**
+     * Transforms a world-space position to screen-space (pixel) coordinates.
+     *
+     * Screen coordinates have origin at top-left, with x increasing right
+     * and y increasing downward.
+     *
+     * @param pos - Position in world coordinates
+     * @returns Position in screen coordinates (pixels)
+     *
+     * @example
+     * const screenPos = camera.worldToScreen(circle.position);
+     * console.log(`Circle is at pixel (${screenPos.x}, ${screenPos.y})`);
+     */
+    worldToScreen(pos) {
+        const viewMatrix = this.getViewMatrix();
+        const transformed = viewMatrix.transformPoint(pos);
+        const screenX = (transformed.x + 1) * 0.5 * this.config.pixelWidth;
+        const screenY = (1 - transformed.y) * 0.5 * this.config.pixelHeight;
+        return new Vector2(screenX, screenY);
+    }
+    /**
+     * Transforms a screen-space (pixel) position to world coordinates.
+     * This is the inverse of worldToScreen.
+     *
+     * @param pos - Position in screen coordinates (pixels, origin at top-left)
+     * @returns Position in world coordinates
+     *
+     * @example
+     * // Convert a mouse click position to world coordinates
+     * const worldPos = camera.screenToWorld(new Vector2(mouseX, mouseY));
+     */
+    screenToWorld(pos) {
+        const ndcX = (pos.x / this.config.pixelWidth) * 2 - 1;
+        const ndcY = 1 - (pos.y / this.config.pixelHeight) * 2;
+        const viewMatrix = this.getViewMatrix();
+        const inverseView = viewMatrix.inverse();
+        return inverseView.transformPoint(new Vector2(ndcX, ndcY));
+    }
+    /**
+     * Checks if a world-space position is currently visible within the camera frame.
+     *
+     * @param pos - Position in world coordinates to check
+     * @returns True if the position is within the visible frame bounds
+     *
+     * @example
+     * if (camera.isInView(object.position)) {
+     *   console.log('Object is visible');
+     * }
+     */
+    isInView(pos) {
+        const framePos = this.frame.position;
+        const halfWidth = this.frame.width / 2;
+        const halfHeight = this.frame.height / 2;
+        return (pos.x >= framePos.x - halfWidth &&
+            pos.x <= framePos.x + halfWidth &&
+            pos.y >= framePos.y - halfHeight &&
+            pos.y <= framePos.y + halfHeight);
+    }
+    reset() {
+        this.frame.pos(0, 0);
+        this.frame.setScale(1, 1);
+        this.frame.setRotation(0);
+        return this;
+    }
+}

package/dist/core/camera/CameraFrame.d.ts

@@ -0,0 +1,242 @@
+import { Mobject } from '../../mobjects/Mobject';
+import { Parallel } from '../animations/composition';
+import type { Animation } from '../animations/Animation';
+/**
+ * Configuration options for CameraFrame.
+ */
+interface CameraFrameConfig {
+    /** Width of the viewport in pixels. Defaults to 1920. */
+    pixelWidth?: number;
+    /** Height of the viewport in pixels. Defaults to 1080. */
+    pixelHeight?: number;
+}
+/**
+ * Camera bounds that limit how far the camera can pan.
+ */
+interface Bounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * CameraFrame represents the viewport window in world space.
+ * Extends Mobject (not VMobject - no visual representation).
+ * Its transform properties define what the camera shows:
+ * - scale(2) = zoom OUT (larger frame = see more)
+ * - scale(0.5) = zoom IN (smaller frame = see less)
+ *
+ * The CameraFrame is the primary way to control camera animations in Anima.
+ * Access it via `scene.frame` or `scene.camera.frame`.
+ *
+ * @example
+ * // Zoom in over 1 second
+ * this.play(this.frame.zoomIn(2).duration(1));
+ *
+ * @example
+ * // Pan to center on an object
+ * this.play(this.frame.centerOn(circle).duration(0.5));
+ *
+ * @example
+ * // Fit multiple objects in view
+ * this.play(this.frame.fitTo([obj1, obj2, obj3]).duration(1));
+ */
+export declare class CameraFrame extends Mobject {
+    private readonly baseWidth;
+    private readonly baseHeight;
+    private bounds?;
+    /**
+     * Creates a new CameraFrame with the specified viewport dimensions.
+     *
+     * @param config - Configuration options
+     * @param config.pixelWidth - Width of the viewport in pixels (default: 1920)
+     * @param config.pixelHeight - Height of the viewport in pixels (default: 1080)
+     *
+     * @example
+     * const frame = new CameraFrame({ pixelWidth: 1920, pixelHeight: 1080 });
+     */
+    constructor(config?: CameraFrameConfig);
+    /**
+     * The current width of the frame in world units, accounting for scale.
+     * @returns The frame width multiplied by the current scale.x
+     */
+    get width(): number;
+    /**
+     * The current height of the frame in world units, accounting for scale.
+     * @returns The frame height multiplied by the current scale.y
+     */
+    get height(): number;
+    /**
+     * Sets the scale of the camera frame.
+     * Overrides Mobject.setScale to prevent zero or negative scales.
+     *
+     * @param sx - Scale factor for the x-axis (must be positive)
+     * @param sy - Scale factor for the y-axis (must be positive)
+     * @returns This CameraFrame for method chaining
+     * @throws Error if sx or sy is zero or negative
+     *
+     * @example
+     * frame.setScale(2, 2); // Zoom out 2x
+     * frame.setScale(0.5, 0.5); // Zoom in 2x
+     */
+    setScale(sx: number, sy: number): this;
+    /**
+     * Sets bounds that limit how far the camera can pan.
+     * When bounds are set, the camera position is clamped to stay within them,
+     * accounting for the frame size so edges don't go outside bounds.
+     *
+     * @param minX - Minimum x coordinate
+     * @param minY - Minimum y coordinate
+     * @param maxX - Maximum x coordinate
+     * @param maxY - Maximum y coordinate
+     * @returns This CameraFrame for method chaining
+     *
+     * @example
+     * // Limit camera to a 100x100 world area
+     * frame.setBounds(0, 0, 100, 100);
+     */
+    setBounds(minX: number, minY: number, maxX: number, maxY: number): this;
+    /**
+     * Removes any bounds restrictions on camera movement.
+     *
+     * @returns This CameraFrame for method chaining
+     *
+     * @example
+     * frame.clearBounds(); // Camera can now pan freely
+     */
+    clearBounds(): this;
+    /**
+     * Checks if the camera has bounds set.
+     *
+     * @returns True if bounds are set, false otherwise
+     */
+    hasBounds(): boolean;
+    /**
+     * Gets the current bounds configuration.
+     *
+     * @returns The bounds object or undefined if no bounds are set
+     */
+    getBounds(): Bounds | undefined;
+    /**
+     * Sets the position of the camera frame.
+     * Overrides Mobject.pos to clamp position within bounds if set.
+     *
+     * @param x - The x coordinate in world space
+     * @param y - The y coordinate in world space
+     * @returns This CameraFrame for method chaining
+     *
+     * @example
+     * frame.pos(5, 3); // Move camera center to (5, 3)
+     */
+    pos(x: number, y: number): this;
+    /**
+     * Smoothly zoom the camera in by the given factor.
+     * Internally scales the frame down, which makes objects appear larger.
+     *
+     * @param factor - Zoom multiplier. 2 = objects appear 2x larger (default: 2)
+     * @returns FluentAnimation that can be chained with .duration() and .ease()
+     * @throws Error if factor is zero or negative
+     *
+     * @example
+     * // Zoom in 2x over 1 second
+     * this.play(this.frame.zoomIn(2).duration(1));
+     *
+     * @example
+     * // Zoom in 3x with easing
+     * this.play(this.frame.zoomIn(3).duration(1.5).ease(easeInOutQuad));
+     */
+    zoomIn(factor?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    /**
+     * Smoothly zoom the camera out by the given factor.
+     * Internally scales the frame up, which makes objects appear smaller.
+     *
+     * @param factor - Zoom multiplier. 2 = objects appear 2x smaller (default: 2)
+     * @returns FluentAnimation that can be chained with .duration() and .ease()
+     * @throws Error if factor is zero or negative
+     *
+     * @example
+     * // Zoom out 2x over 1 second
+     * this.play(this.frame.zoomOut(2).duration(1));
+     *
+     * @example
+     * // Zoom out to show more of the scene
+     * this.play(this.frame.zoomOut(4).duration(2).ease(easeOutCubic));
+     */
+    zoomOut(factor?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    /**
+     * Move the camera to center on a target Mobject.
+     * The camera will smoothly pan so the target is at the center of the frame.
+     *
+     * @param target - The Mobject to center on
+     * @returns FluentAnimation that can be chained with .duration() and .ease()
+     * @throws Error if target is null or undefined
+     *
+     * @example
+     * // Center on a circle over 0.5 seconds
+     * this.play(this.frame.centerOn(circle).duration(0.5));
+     *
+     * @example
+     * // Pan to focus on different objects in sequence
+     * await this.play(this.frame.centerOn(obj1).duration(1));
+     * await this.play(this.frame.centerOn(obj2).duration(1));
+     */
+    centerOn(target: Mobject): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    /**
+     * Zoom in/out while keeping a specific world point fixed on screen.
+     * Like pinch-to-zoom behavior where the pinch point stays stationary.
+     *
+     * Uses the formula: C' = P * (1 - factor) + C * factor
+     * Where P = point, C = current center, factor = zoom factor.
+     *
+     * @param factor - Scale multiplier. Less than 1 for zoom in, greater than 1 for zoom out
+     * @param point - World coordinates to keep fixed on screen
+     * @returns Parallel animation combining move and scale
+     * @throws Error if factor is zero or negative
+     *
+     * @example
+     * // Zoom in 2x on a specific point
+     * this.play(frame.zoomToPoint(0.5, { x: 5, y: 5 }).duration(1));
+     *
+     * @example
+     * // Zoom out while keeping an object's position fixed
+     * this.play(frame.zoomToPoint(2, circle.position).duration(1));
+     */
+    zoomToPoint(factor: number, point: {
+        x: number;
+        y: number;
+    }): Parallel;
+    /**
+     * Automatically frame one or more objects with optional margin.
+     * Calculates the bounding box of all targets and animates the camera
+     * to show them all with the specified margin around them.
+     *
+     * @param targets - Single Mobject or array of Mobjects to frame
+     * @param margin - Padding around the objects in world units (default: 0.5)
+     * @returns FluentAnimation that can be chained with .duration() and .ease()
+     * @throws Error if targets array is empty
+     *
+     * @example
+     * // Fit a single object with default margin
+     * this.play(this.frame.fitTo(circle).duration(1));
+     *
+     * @example
+     * // Fit multiple objects with custom margin
+     * this.play(this.frame.fitTo([obj1, obj2, obj3], 1.0).duration(1.5));
+     *
+     * @example
+     * // Show all objects in the scene
+     * this.play(this.frame.fitTo(allObjects, 0).duration(2));
+     */
+    fitTo(targets: Mobject | Mobject[], margin?: number): this & {
+        toAnimation(): Animation<Mobject>;
+    };
+    private calculateBounds;
+    private hasGetBoundingBox;
+}
+export {};