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.tsindex 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.mdxindex 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.mdxnew file mode 100644index 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.mdxdeleted file mode 100644index 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.tsxindex 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);});