Skip to content

Visualize Your Ideas With Code

feat(2d): use SVG component in Latex and support tweening (#800)

Levi Rizki Saputra92a56590f740
diff --git a/packages/2d/src/lib/components/Latex.ts b/packages/2d/src/lib/components/Latex.ts
index 9acc3035..268dbea3 100644
--- a/packages/2d/src/lib/components/Latex.ts
+++ b/packages/2d/src/lib/components/Latex.ts
@@ -1,8 +1,13 @@
import {
- DependencyContext,
+ lazy,
+ SerializedVector2,
+ Signal,
SignalValue,
SimpleSignal,
+ threadable,
+ TimingFunction,
useLogger,
+ Vector2,
} from '@motion-canvas/core';
import {liteAdaptor} from 'mathjax-full/js/adaptors/liteAdaptor';
import {RegisterHTMLHandler} from 'mathjax-full/js/handlers/html';
@@ -11,8 +16,15 @@ 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 {initial, signal} from '../decorators';
-import {Img, ImgProps} from './Img';
+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);
@@ -24,64 +36,192 @@ const JaxDocument = mathjax.document('', {
OutputJax: new SVG({fontCache: 'local'}),
});
-export interface LatexProps extends ImgProps {
- tex?: SignalValue<string>;
+export interface LatexProps extends Omit<SVGProps, 'svg'> {
+ tex?: SignalValue<string[] | string>;
renderProps?: SignalValue<OptionList>;
}
/**
- * A node for rendering equations with LaTeX.
+ * A node for animating equations with LaTeX.
*
* @preview
* ```tsx editor
* import {Latex, makeScene2D} from '@motion-canvas/2d';
+ * import {createRef, waitFor} from '@motion-canvas/core';
*
* export default makeScene2D(function* (view) {
- * view.add(
- * <Latex
- * // Note how this uses \color to set the color.
- * tex="{\color{white} ax^2+bx+c=0 \implies x=\frac{-b \pm \sqrt{b^2-4ac}}{2a}}"
- * width={600} // height and width can calculate based on each other
- * />,
+ * 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 Img {
+export class Latex extends SVGNode {
+ @lazy(() => {
+ return parseFloat(
+ window.getComputedStyle(SVGNode.containerElement).fontSize,
+ );
+ })
+ private static containerFontSize: number;
private static svgContentsPool: Record<string, string> = {};
-
- private readonly imageElement = document.createElement('img');
+ private static texNodesPool: Record<string, SVGDocumentData> = {};
+ private svgSubTexMap: Record<string, string[]> = {};
@initial({})
@signal()
public declare 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;
+ }, [])
+ .map(sub => sub.trim())
+ .filter(sub => sub.length > 0);
+ })
@signal()
- public declare readonly tex: SimpleSignal<string, this>;
+ public declare readonly tex: Signal<string[] | string, string[], this>;
public constructor(props: LatexProps) {
- super({...props, src: null});
+ super({
+ fontSize: 48,
+ ...props,
+ svg: '',
+ });
+ this.svg(this.latexSVG);
}
- protected override image(): HTMLImageElement {
- // Render props may change the look of the TeX, so we need to cache both
- // source and render props together.
- const src = `${this.tex()}::${JSON.stringify(this.options())}`;
- if (Latex.svgContentsPool[src]) {
- this.imageElement.src = Latex.svgContentsPool[src];
- if (!this.imageElement.complete) {
- DependencyContext.collectPromise(
- new Promise((resolve, reject) => {
- this.imageElement.addEventListener('load', resolve);
- this.imageElement.addEventListener('error', reject);
- }),
- );
+ 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]!;
+ 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;
+
+ 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;
}
- return this.imageElement;
+
+ 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];
}
- // Convert to TeX, look for any errors
- const tex = this.tex();
const svg = Adaptor.innerHTML(JaxDocument.convert(tex, this.options()));
if (svg.includes('data-mjx-error')) {
const errors = svg.match(/data-mjx-error="(.*?)"/);
@@ -89,24 +229,18 @@ export class Latex extends Img {
useLogger().error(`Invalid MathJax: ${errors[1]}`);
}
}
+ Latex.svgContentsPool[src] = svg;
+ return svg;
+ }
- // Encode to raw base64 image format
- const text = `data:image/svg+xml;base64,${btoa(
- `<?xml version="1.0" encoding="UTF-8" standalone="no" ?>\n${svg}`,
- )}`;
- Latex.svgContentsPool[src] = text;
- const image = document.createElement('img');
- image.src = text;
- image.src = text;
- if (!image.complete) {
- DependencyContext.collectPromise(
- new Promise((resolve, reject) => {
- image.addEventListener('load', resolve);
- image.addEventListener('error', reject);
- }),
- );
- }
-
- return image;
+ @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);
}
}
diff --git a/packages/docs/blog/2023-02-11-version-2.3.0.mdx b/packages/docs/blog/2023-02-11-version-2.3.0.mdx
index fa5ec50d..992fc30c 100644
--- a/packages/docs/blog/2023-02-11-version-2.3.0.mdx
+++ b/packages/docs/blog/2023-02-11-version-2.3.0.mdx
@@ -6,7 +6,7 @@ authors: aarthificial
### Features
-- A new [`LaTeX`](/docs/nodes) node!
+- A new [`LaTeX`](/docs/latex) node!
([#228](https://github.com/motion-canvas/motion-canvas/issues/228))
([4c26d2a](https://github.com/motion-canvas/motion-canvas/commit/4c26d2aaf0c697486639aa917cd5c585d3d0ea74))
- CodeBlock themes (documentation coming soon)
diff --git a/packages/docs/docs/components/latex.mdx b/packages/docs/docs/components/latex.mdx
new file mode 100644
index 00000000..fd0decee
--- /dev/null
+++ b/packages/docs/docs/components/latex.mdx
@@ -0,0 +1,145 @@
+---
+sidebar_position: 2
+slug: /latex
+---
+
+# Latex
+
+```tsx editor mode=preview
+import {Latex, makeScene2D} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@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);
+});
+```
+
+The [`Latex`](/api/2d/components/Latex) component is used to show mathematical
+formulas and animate them.
+
+## Defining LaTex
+
+You can specify the LaTex formula to show using the `tex` property. Similarly to
+the [`Txt`](/api/2d/components/Txt) node, you can control the color and size of
+the text using the `fill` and `fontSize` properties respectively.
+
+:::caution
+
+Make sure to always set some `fill` color otherwise nothing will be shown!
+
+:::
+
+```tsx editor
+import {Latex, makeScene2D} from '@motion-canvas/2d';
+
+export default makeScene2D(function* (view) {
+ view.add(
+ <Latex
+ // Try editing the formula below:
+ tex="a^2 + b^2 = c^2"
+ fill="white"
+ fontSize={32}
+ />,
+ );
+});
+```
+
+## Animating LaTex
+
+We can animate LaTex by tweening the `tex` property. To enable deletion,
+insertion and transformation animation you must split the formula into several
+parts. You can do this by providing an array of strings:
+
+```tsx
+<Latex tex={['a^2', '+', 'b^2', '=', 'c^2']} />
+```
+
+Or by using the curly bracket (`{{}}`) syntax:
+
+```tsx
+<Latex tex="{{a^2}} + {{b^2}} = {{c^2}}" />
+// equivalent to
+<Latex tex={['a^2', '+', 'b^2', '=', 'c^2']} />
+```
+
+You can also mix both:
+
+```tsx
+<Latex tex={['{{a}}^2', '+', '{{b}}^2', '=', '{{c}}^2']} />
+// equivalent to
+<Latex tex={['a','^2', '+', 'b', '^2', '=', 'c', '^2']} />
+```
+
+A tex part that only exists in the source formula is considered deleted and gets
+faded out. Analogically, a part that only exists in the target formula is faded
+in. Tex parts that exist in both the source and destination formulas will be
+tweened:
+
+```tsx editor
+import {Latex, makeScene2D} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const tex = createRef<Latex>();
+ view.add(<Latex ref={tex} tex="{{1}} + {{2}}" fill="white" />);
+
+ yield* waitFor(0.5);
+ yield* tex().tex(['2', '+', '3', '+', '4'], 1);
+});
+```
+
+If a given tex part occurs multiple times in the source and target formula, but
+the number of occurrences does not match, the part will duplicated or merged.
+You can see this in action in the example above. The formula starts with only
+one plus sign (`+`), but ends with two.
+
+## Common pitfalls
+
+### Escaping slashes
+
+The backslash character (`\`) is used as an escape character in JavaScript. In
+order to use it as part of a LaTex formula, you need to escape it by doubling
+it:
+
+```tsx
+node().tex('{{\\frac{1}{2}}}');
+```
+
+Note that this does not apply inside JSX string attributes:
+
+```tsx
+// No escape needed:
+<Latex tex="{{\frac{1}{2}}" />
+// Escape necessary:
+<Latex tex={'{{\frac{1}{2}}'} />
+```
+
+### Missing spaces
+
+As of right now, tex parts are put together by joining them with no separator.
+This may break your formula if it depends on a space between two parts. For
+example, the following formula will break:
+
+```tsx
+<Latex tex={['\\Delta', 'y']} />
+```
+
+The node will attempt to parse it as `\\Deltay` instead of the correct
+`\\Delta y`. To prevent it, you should wrap the `y` part in curly brackets:
+
+```tsx
+<Latex tex={['\\Delta', '{y}']} />
+```
+
+This will be parsed as `\\Delta{y}` which is correct.
diff --git a/packages/docs/docs/components/nodes.mdx b/packages/docs/docs/components/nodes.mdx
deleted file mode 100644
index a656ae84..00000000
--- a/packages/docs/docs/components/nodes.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-sidebar_position: 2
-slug: /nodes
----
-
-import AnimationPlayer from '@site/src/components/AnimationPlayer';
-import CodeBlock from '@theme/CodeBlock';
-import texSource from '!!raw-loader!@motion-canvas/examples/src/scenes/tex';
-
-# LaTeX
-
-<CodeBlock language="tsx">{texSource}</CodeBlock>
-
-<AnimationPlayer small name="tex" />
-
-## A note on tweening LaTeX
-
-Because we use a canvas renderer, we're rendering the LaTeX to an image instead
-of using a full graphics backend to render the TeX. This means that for all
-intents and purposes, LaTeX should be treated as if it were an image rather than
-more flexible TeX rendering like you may see in other software.
-
-In other words, opacity, position, size, etc. should be fine to tween, but we do
-not recommend tweening the `tex` signal.
diff --git a/packages/examples/src/scenes/tex.tsx b/packages/examples/src/scenes/tex.tsx
index 8dfdac2e..f9191f59 100644
--- a/packages/examples/src/scenes/tex.tsx
+++ b/packages/examples/src/scenes/tex.tsx
@@ -3,17 +3,16 @@ import {createRef, waitFor} from '@motion-canvas/core';
export default makeScene2D(function* (view) {
const tex = createRef<Latex>();
- view.add(
- <Latex
- ref={tex}
- tex="{\color{white} x = \sin \left( \frac{\pi}{2} \right)}"
- y={0}
- width={400} // height and width can calculate based on each other
- />,
- );
+ view.add(<Latex ref={tex} tex={['y', '=', '{{a}}{{x^2}}']} fill="white" />);
- yield* waitFor(2);
- yield* tex().opacity(0, 1);
- yield* waitFor(2);
- yield* tex().opacity(1, 1);
+ yield* waitFor(0.5);
+ yield* tex().tex(['y', '=', '{{a}}{{x^2}} + {{bx}}'], 1);
+ yield* waitFor(0.5);
+ yield* tex().tex(['y', '=', '{{c}} + {{a}}{{x^2}} + {{bx}}'], 1);
+ yield* waitFor(0.5);
+ yield* tex().tex(['y', '=', '{{a}}{{x^2}} + {{bx}} + {{c}}'], 1);
+ yield* waitFor(0.5);
+ yield* tex().tex(['y', '=', '{{x^2}}'], 1);
+ yield* waitFor(0.5);
+ yield* tex().tex(['y', '=', '{{a}}{{x^2}}'], 1);
});