@efxlab/motion-canvas-2d 4.0.0

package/src/lib/components/Img.ts

@@ -0,0 +1,305 @@
+import {
+  BBox,
+  Color,
+  DependencyContext,
+  DetailedError,
+  PossibleVector2,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+  Vector2,
+  useLogger,
+  viaProxy,
+} from '@efxlab/motion-canvas-core';
+import {computed, initial, nodeName, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {drawImage} from '../utils';
+import {Rect, RectProps} from './Rect';
+import imageWithoutSource from './__logs__/image-without-source.md';
+
+export interface ImgProps extends RectProps {
+  /**
+   * {@inheritDoc Img.src}
+   */
+  src?: SignalValue<string | null>;
+  /**
+   * {@inheritDoc Img.alpha}
+   */
+  alpha?: SignalValue<number>;
+  /**
+   * {@inheritDoc Img.smoothing}
+   */
+  smoothing?: SignalValue<boolean>;
+}
+
+/**
+ * A node for displaying images.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Img} from '@efxlab/motion-canvas-2d';
+ * import {all, waitFor} from '@efxlab/motion-canvas-core';
+ * import {createRef} from '@efxlab/motion-canvas-core';
+ * import {makeScene2D} from '@efxlab/motion-canvas-2d';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const ref = createRef<Img>();
+ *   yield view.add(
+ *     <Img
+ *       ref={ref}
+ *       src="https://images.unsplash.com/photo-1679218407381-a6f1660d60e9"
+ *       width={300}
+ *       radius={20}
+ *     />,
+ *   );
+ *
+ *   // set the background using the color sampled from the image:
+ *   ref().fill(ref().getColorAtPoint(0));
+ *
+ *   yield* all(
+ *     ref().size([100, 100], 1).to([300, null], 1),
+ *     ref().radius(50, 1).to(20, 1),
+ *     ref().alpha(0, 1).to(1, 1),
+ *   );
+ *   yield* waitFor(0.5);
+ * });
+ * ```
+ */
+@nodeName('Img')
+export class Img extends Rect {
+  private static pool: Record<string, HTMLImageElement> = {};
+
+  static {
+    if (import.meta.hot) {
+      import.meta.hot.on('motion-canvas:assets', ({urls}) => {
+        for (const url of urls) {
+          if (Img.pool[url]) {
+            delete Img.pool[url];
+          }
+        }
+      });
+    }
+  }
+
+  /**
+   * The source of this image.
+   *
+   * @example
+   * Using a local image:
+   * ```tsx
+   * import image from './example.png';
+   * // ...
+   * view.add(<Img src={image} />)
+   * ```
+   * Loading an image from the internet:
+   * ```tsx
+   * view.add(<Img src="https://example.com/image.png" />)
+   * ```
+   */
+  @signal()
+  declare public readonly src: SimpleSignal<string, this>;
+
+  /**
+   * The alpha value of this image.
+   *
+   * @remarks
+   * Unlike opacity, the alpha value affects only the image itself, leaving the
+   * fill, stroke, and children intact.
+   */
+  @initial(1)
+  @signal()
+  declare public readonly alpha: SimpleSignal<number, this>;
+
+  /**
+   * Whether the image should be smoothed.
+   *
+   * @remarks
+   * When disabled, the image will be scaled using the nearest neighbor
+   * interpolation with no smoothing. The resulting image will appear pixelated.
+   *
+   * @defaultValue true
+   */
+  @initial(true)
+  @signal()
+  declare public readonly smoothing: SimpleSignal<boolean, this>;
+
+  public constructor(props: ImgProps) {
+    super(props);
+    if (!('src' in props)) {
+      useLogger().warn({
+        message: 'No source specified for the image',
+        remarks: imageWithoutSource,
+        inspect: this.key,
+      });
+    }
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    const custom = super.desiredSize();
+    if (custom.x === null && custom.y === null) {
+      const image = this.image();
+      return {
+        x: image.naturalWidth,
+        y: image.naturalHeight,
+      };
+    }
+
+    return custom;
+  }
+
+  @computed()
+  protected image(): HTMLImageElement {
+    const rawSrc = this.src();
+    let src = '';
+    let key = '';
+    if (rawSrc) {
+      key = viaProxy(rawSrc);
+      const url = new URL(key, window.location.origin);
+      if (url.origin === window.location.origin) {
+        const hash = this.view().assetHash();
+        url.searchParams.set('asset-hash', hash);
+      }
+      src = url.toString();
+    }
+
+    let image = Img.pool[key];
+    if (!image) {
+      image = document.createElement('img');
+      image.crossOrigin = 'anonymous';
+      image.src = src;
+      Img.pool[key] = image;
+    }
+
+    if (!image.complete) {
+      DependencyContext.collectPromise(
+        new Promise((resolve, reject) => {
+          image.addEventListener('load', resolve);
+          image.addEventListener('error', () =>
+            reject(
+              new DetailedError({
+                message: `Failed to load an image`,
+                remarks: `\
+The <code>src</code> property was set to:
+<pre><code>${rawSrc}</code></pre>
+...which resolved to the following url:
+<pre><code>${src}</code></pre>
+Make sure that source is correct and that the image exists.<br/>
+<a target='_blank' href='https://motioncanvas.io/docs/media#images'>Learn more</a>
+about working with images.`,
+                inspect: this.key,
+              }),
+            ),
+          );
+        }),
+      );
+    }
+
+    return image;
+  }
+
+  @computed()
+  protected imageCanvas(): CanvasRenderingContext2D {
+    const canvas = document
+      .createElement('canvas')
+      .getContext('2d', {willReadFrequently: true});
+    if (!canvas) {
+      throw new Error('Could not create an image canvas');
+    }
+
+    return canvas;
+  }
+
+  @computed()
+  protected filledImageCanvas() {
+    const context = this.imageCanvas();
+    const image = this.image();
+    context.canvas.width = image.naturalWidth;
+    context.canvas.height = image.naturalHeight;
+    context.imageSmoothingEnabled = this.smoothing();
+    context.drawImage(image, 0, 0);
+
+    return context;
+  }
+
+  protected override draw(context: CanvasRenderingContext2D) {
+    this.drawShape(context);
+    const alpha = this.alpha();
+    if (alpha > 0) {
+      const box = BBox.fromSizeCentered(this.computedSize());
+      context.save();
+      context.clip(this.getPath());
+      if (alpha < 1) {
+        context.globalAlpha *= alpha;
+      }
+      context.imageSmoothingEnabled = this.smoothing();
+      drawImage(context, this.image(), box);
+      context.restore();
+    }
+
+    if (this.clip()) {
+      context.clip(this.getPath());
+    }
+
+    this.drawChildren(context);
+  }
+
+  protected override applyFlex() {
+    super.applyFlex();
+    const image = this.image();
+    this.element.style.aspectRatio = (
+      this.ratio() ?? image.naturalWidth / image.naturalHeight
+    ).toString();
+  }
+
+  /**
+   * Get color of the image at the given position.
+   *
+   * @param position - The position in local space at which to sample the color.
+   */
+  public getColorAtPoint(position: PossibleVector2): Color {
+    const size = this.computedSize();
+    const naturalSize = this.naturalSize();
+
+    const pixelPosition = new Vector2(position)
+      .add(this.computedSize().scale(0.5))
+      .mul(naturalSize.div(size).safe);
+
+    return this.getPixelColor(pixelPosition);
+  }
+
+  /**
+   * The natural size of this image.
+   *
+   * @remarks
+   * The natural size is the size of the source image unaffected by the size
+   * and scale properties.
+   */
+  @computed()
+  public naturalSize() {
+    const image = this.image();
+    return new Vector2(image.naturalWidth, image.naturalHeight);
+  }
+
+  /**
+   * Get color of the image at the given pixel.
+   *
+   * @param position - The pixel's position.
+   */
+  public getPixelColor(position: PossibleVector2): Color {
+    const context = this.filledImageCanvas();
+    const vector = new Vector2(position);
+    const data = context.getImageData(vector.x, vector.y, 1, 1).data;
+
+    return new Color({
+      r: data[0],
+      g: data[1],
+      b: data[2],
+      a: data[3] / 255,
+    });
+  }
+
+  protected override collectAsyncResources() {
+    super.collectAsyncResources();
+    this.image();
+  }
+}

package/src/lib/components/Knot.ts

@@ -0,0 +1,156 @@
+import {
+  PossibleVector2,
+  Signal,
+  SignalValue,
+  Vector2,
+  Vector2Signal,
+} from '@efxlab/motion-canvas-core';
+import {KnotInfo} from '../curves';
+import {
+  cloneable,
+  compound,
+  computed,
+  initial,
+  parser,
+  signal,
+  wrapper,
+} from '../decorators';
+import {Node, NodeProps} from './Node';
+
+export interface KnotProps extends NodeProps {
+  /**
+   * {@inheritDoc Knot.startHandle}
+   */
+  startHandle?: SignalValue<PossibleVector2>;
+  /**
+   * {@inheritDoc Knot.endHandle}
+   */
+  endHandle?: SignalValue<PossibleVector2>;
+  /**
+   * {@inheritDoc Knot.auto}
+   */
+  auto?: SignalValue<PossibleKnotAuto>;
+  startHandleAuto?: SignalValue<number>;
+  endHandleAuto?: SignalValue<number>;
+}
+
+export type KnotAuto = {startHandle: number; endHandle: number};
+export type PossibleKnotAuto = KnotAuto | number | [number, number];
+export type KnotAutoSignal<TOwner> = Signal<
+  PossibleKnotAuto,
+  KnotAuto,
+  TOwner
+> & {
+  endHandle: Signal<number, number, TOwner>;
+  startHandle: Signal<number, number, TOwner>;
+};
+
+/**
+ * A node representing a knot of a {@link Spline}.
+ */
+export class Knot extends Node {
+  /**
+   * The position of the knot's start handle. The position is provided relative
+   * to the knot's position.
+   *
+   * @remarks
+   * By default, the position of the start handle will be the mirrored position
+   * of the {@link endHandle}.
+   *
+   * If neither an end handle nor a start handle is provided, the positions of
+   * the handles gets calculated automatically to create smooth curve through
+   * the knot. The smoothness of the resulting curve can be controlled via the
+   * {@link Spline.smoothness} property.
+   *
+   * It is also possible to blend between a user-defined position and the
+   * auto-calculated position by using the {@link auto} property.
+   *
+   * @defaultValue Mirrored position of the endHandle.
+   */
+  @wrapper(Vector2)
+  @signal()
+  declare public readonly startHandle: Vector2Signal<this>;
+
+  /**
+   * The position of the knot's end handle. The position is provided relative
+   * to the knot's position.
+   *
+   * @remarks
+   * By default, the position of the end handle will be the mirrored position
+   * of the {@link startHandle}.
+   *
+   * If neither an end handle nor a start handle is provided, the positions of
+   * the handles gets calculated automatically to create smooth curve through
+   * the knot. The smoothness of the resulting curve can be controlled via the
+   * {@link Spline.smoothness} property.
+   *
+   * It is also possible to blend between a user-defined position and the
+   * auto-calculated position by using the {@link auto} property.
+   *
+   * @defaultValue Mirrored position of the startHandle.
+   */
+  @wrapper(Vector2)
+  @signal()
+  declare public readonly endHandle: Vector2Signal<this>;
+
+  /**
+   * How much to blend between the user-provided handles and the auto-calculated
+   * handles.
+   *
+   * @remarks
+   * This property has no effect if no explicit handles are provided for the
+   * knot.
+   *
+   * @defaultValue 0
+   */
+  @cloneable(false)
+  @initial(() => ({startHandle: 0, endHandle: 0}))
+  @parser((value: PossibleKnotAuto) => {
+    if (typeof value === 'object' && !Array.isArray(value)) {
+      return value;
+    }
+    if (typeof value === 'number') {
+      value = [value, value];
+    }
+    return {startHandle: value[0], endHandle: value[1]};
+  })
+  @compound({startHandle: 'startHandleAuto', endHandle: 'endHandleAuto'})
+  declare public readonly auto: KnotAutoSignal<this>;
+  public get startHandleAuto() {
+    return this.auto.startHandle;
+  }
+  public get endHandleAuto() {
+    return this.auto.endHandle;
+  }
+
+  public constructor(props: KnotProps) {
+    super(
+      props.startHandle === undefined && props.endHandle === undefined
+        ? {auto: 1, ...props}
+        : props,
+    );
+  }
+
+  @computed()
+  public points(): KnotInfo {
+    const hasExplicitHandles =
+      !this.startHandle.isInitial() || !this.endHandle.isInitial();
+    const startHandle = hasExplicitHandles ? this.startHandle() : Vector2.zero;
+    const endHandle = hasExplicitHandles ? this.endHandle() : Vector2.zero;
+
+    return {
+      position: this.position(),
+      startHandle: startHandle.transformAsPoint(this.localToParent()),
+      endHandle: endHandle.transformAsPoint(this.localToParent()),
+      auto: {start: this.startHandleAuto(), end: this.endHandleAuto()},
+    };
+  }
+
+  private getDefaultEndHandle() {
+    return this.startHandle().flipped;
+  }
+
+  private getDefaultStartHandle() {
+    return this.endHandle().flipped;
+  }
+}

package/src/lib/components/Latex.ts

@@ -0,0 +1,249 @@
+import {
+  lazy,
+  SerializedVector2,
+  Signal,
+  SignalValue,
+  SimpleSignal,
+  threadable,
+  TimingFunction,
+  useLogger,
+  Vector2,
+} from '@efxlab/motion-canvas-core';
+import {liteAdaptor} from 'mathjax-full/js/adaptors/liteAdaptor';
+import {RegisterHTMLHandler} from 'mathjax-full/js/handlers/html';
+import {TeX} from 'mathjax-full/js/input/tex';
+import {AllPackages} from 'mathjax-full/js/input/tex/AllPackages';
+import {mathjax} from 'mathjax-full/js/mathjax';
+import {SVG} from 'mathjax-full/js/output/svg';
+import {OptionList} from 'mathjax-full/js/util/Options';
+import {computed, initial, parser, signal} from '../decorators';
+import {Node} from './Node';
+import {
+  SVGDocument,
+  SVGDocumentData,
+  SVG as SVGNode,
+  SVGProps,
+  SVGShapeData,
+} from './SVG';
+
+const Adaptor = liteAdaptor();
+RegisterHTMLHandler(Adaptor);
+
+const JaxDocument = mathjax.document('', {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  InputJax: new TeX({packages: AllPackages}),
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  OutputJax: new SVG({fontCache: 'local'}),
+});
+
+export interface LatexProps extends Omit<SVGProps, 'svg'> {
+  tex?: SignalValue<string[] | string>;
+  renderProps?: SignalValue<OptionList>;
+}
+
+/**
+ * A node for animating equations with LaTeX.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Latex, makeScene2D} from '@efxlab/motion-canvas-2d';
+ * import {createRef, waitFor} from '@efxlab/motion-canvas-core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const tex = createRef<Latex>();
+ *   view.add(<Latex ref={tex} tex="{{y=}}{{a}}{{x^2}}" fill="white" />);
+ *
+ *   yield* waitFor(0.2);
+ *   yield* tex().tex('{{y=}}{{a}}{{x^2}} + {{bx}}', 1);
+ *   yield* waitFor(0.2);
+ *   yield* tex().tex(
+ *     '{{y=}}{{\\left(}}{{a}}{{x^2}} + {{bx}}{{\\over 1}}{{\\right)}}',
+ *     1,
+ *   );
+ *   yield* waitFor(0.2);
+ *   yield* tex().tex('{{y=}}{{a}}{{x^2}}', 1);
+ * });
+ * ```
+ */
+export class Latex extends SVGNode {
+  @lazy(() => {
+    return parseFloat(
+      window.getComputedStyle(SVGNode.containerElement).fontSize,
+    );
+  })
+  private static containerFontSize: number;
+  private static svgContentsPool: Record<string, string> = {};
+  private static texNodesPool: Record<string, SVGDocumentData> = {};
+  private svgSubTexMap: Record<string, string[]> = {};
+
+  @initial({})
+  @signal()
+  declare public readonly options: SimpleSignal<OptionList, this>;
+
+  @initial('')
+  @parser(function (this: SVGNode, value: string[] | string): string[] {
+    const array = typeof value === 'string' ? [value] : value;
+    return array
+      .reduce<string[]>((prev, current) => {
+        prev.push(...current.split(/{{(.*?)}}/));
+        return prev;
+      }, [])
+      .filter(sub => sub.trim().length > 0);
+  })
+  @signal()
+  declare public readonly tex: Signal<string[] | string, string[], this>;
+
+  public constructor(props: LatexProps) {
+    super({
+      fontSize: 48,
+      ...props,
+      svg: '',
+    });
+    this.svg(this.latexSVG);
+  }
+
+  protected override calculateWrapperScale(
+    documentSize: Vector2,
+    parentSize: SerializedVector2<number | null>,
+  ): Vector2 {
+    if (parentSize.x || parentSize.y) {
+      return super.calculateWrapperScale(documentSize, parentSize);
+    }
+    return new Vector2(this.fontSize() / Latex.containerFontSize);
+  }
+
+  @computed()
+  protected latexSVG() {
+    return this.texToSvg(this.tex());
+  }
+
+  private getNodeCharacterId({id}: SVGShapeData) {
+    if (!id.includes('-')) return id;
+    return id.substring(id.lastIndexOf('-') + 1);
+  }
+
+  protected override parseSVG(svg: string): SVGDocument {
+    const subTexs = this.svgSubTexMap[svg]!.map(sub => sub.trim());
+    const key = `[${subTexs.join(',')}]::${JSON.stringify(this.options())}`;
+    const cached = Latex.texNodesPool[key];
+    if (cached && (cached.size.x > 0 || cached.size.y > 0)) {
+      return this.buildDocument(Latex.texNodesPool[key]);
+    }
+    const oldSVG = SVGNode.parseSVGData(svg);
+    const oldNodes = [...oldSVG.nodes];
+
+    const newNodes: SVGShapeData[] = [];
+    for (const sub of subTexs) {
+      const subSvg = this.subTexToSVG(sub);
+      const subNodes = SVGNode.parseSVGData(subSvg).nodes;
+
+      if (subNodes.length === 0) {
+        continue;
+      }
+
+      const firstId = this.getNodeCharacterId(subNodes[0]);
+      const spliceIndex = oldNodes.findIndex(
+        node => this.getNodeCharacterId(node) === firstId,
+      );
+      const children = oldNodes.splice(spliceIndex, subNodes.length);
+
+      if (children.length === 1) {
+        newNodes.push({
+          ...children[0],
+          id: sub,
+        });
+        continue;
+      }
+
+      newNodes.push({
+        id: sub,
+        type: Node,
+        props: {},
+        children,
+      });
+    }
+    if (oldNodes.length > 0) {
+      useLogger().error({
+        message: 'Matching between Latex SVG and tex parts failed',
+        inspect: this.key,
+      });
+    }
+
+    const newSVG: SVGDocumentData = {
+      size: oldSVG.size,
+      nodes: newNodes,
+    };
+    Latex.texNodesPool[key] = newSVG;
+    return this.buildDocument(newSVG);
+  }
+
+  private texToSvg(subTexs: string[]) {
+    const singleTex = subTexs.join('');
+    const svg = this.singleTexToSVG(singleTex);
+    this.svgSubTexMap[svg] = subTexs;
+    return svg;
+  }
+
+  private subTexToSVG(subTex: string) {
+    let tex = subTex.trim();
+    if (
+      ['\\overline', '\\sqrt', '\\sqrt{'].includes(tex) ||
+      tex.endsWith('_') ||
+      tex.endsWith('^') ||
+      tex.endsWith('dot')
+    ) {
+      tex += '{\\quad}';
+    }
+
+    if (tex === '\\substack') tex = '\\quad';
+
+    const numLeft = tex.match(/\\left[()[\]|.\\]/g)?.length ?? 0;
+    const numRight = tex.match(/\\right[()[\]|.\\]/g)?.length ?? 0;
+    if (numLeft !== numRight) {
+      tex = tex.replace(/\\left/g, '\\big').replace(/\\right/g, '\\big');
+    }
+
+    const bracesLeft = tex.match(/((?<!\\)|(?<=\\\\)){/g)?.length ?? 0;
+    const bracesRight = tex.match(/((?<!\\)|(?<=\\\\))}/g)?.length ?? 0;
+
+    if (bracesLeft < bracesRight) {
+      tex = '{'.repeat(bracesRight - bracesLeft) + tex;
+    } else if (bracesRight < bracesLeft) {
+      tex += '}'.repeat(bracesLeft - bracesRight);
+    }
+
+    const hasArrayBegin = tex.includes('\\begin{array}');
+    const hasArrayEnd = tex.includes('\\end{array}');
+    if (hasArrayBegin !== hasArrayEnd) tex = '';
+
+    return this.singleTexToSVG(tex);
+  }
+
+  private singleTexToSVG(tex: string): string {
+    const src = `${tex}::${JSON.stringify(this.options())}`;
+    if (Latex.svgContentsPool[src]) {
+      return Latex.svgContentsPool[src];
+    }
+
+    const svg = Adaptor.innerHTML(JaxDocument.convert(tex, this.options()));
+    if (svg.includes('data-mjx-error')) {
+      const errors = svg.match(/data-mjx-error="(.*?)"/);
+      if (errors && errors.length > 0) {
+        useLogger().error(`Invalid MathJax: ${errors[1]}`);
+      }
+    }
+    Latex.svgContentsPool[src] = svg;
+    return svg;
+  }
+
+  @threadable()
+  protected *tweenTex(
+    value: string[],
+    time: number,
+    timingFunction: TimingFunction,
+  ) {
+    const newSVG = this.texToSvg(this.tex.context.parse(value));
+    yield* this.svg(newSVG, time, timingFunction);
+    this.svg(this.latexSVG);
+  }
+}