Visualize Your Ideas With Code
docs: add positioning section
aarthificiald3c67dad8bc4
diff --git a/packages/2d/src/components/Node.ts b/packages/2d/src/components/Node.tsindex 6abe50e2..2a614fa3 100644--- a/packages/2d/src/components/Node.ts+++ b/packages/2d/src/components/Node.ts@@ -19,6 +19,7 @@ import {PossibleVector2,Vector2Signal,ColorSignal,+ SimpleVector2Signal,} from '@motion-canvas/core/lib/types';import {DetailedError, ReferenceReceiver} from '@motion-canvas/core/lib/utils';import type {ComponentChild, ComponentChildren, NodeConstructor} from './types';@@ -75,11 +76,7 @@ export class Node implements Promisable<Node> {@wrapper(Vector2)@cloneable(false)@signal()- public declare readonly absolutePosition: Signal<- PossibleVector2,- Vector2,- this- >;+ public declare readonly absolutePosition: SimpleVector2Signal<this>;protected getAbsolutePosition(): Vector2 {const matrix = this.localToWorld();@@ -122,7 +119,7 @@ export class Node implements Promisable<Node> {@wrapper(Vector2)@cloneable(false)@signal()- public declare readonly absoluteScale: Signal<PossibleVector2, Vector2, this>;+ public declare readonly absoluteScale: SimpleVector2Signal<this>;protected getAbsoluteScale(): Vector2 {const matrix = this.localToWorld();diff --git a/packages/core/src/transitions/slideTransition.ts b/packages/core/src/transitions/slideTransition.tsindex 8dc39d34..17f36b54 100644--- a/packages/core/src/transitions/slideTransition.ts+++ b/packages/core/src/transitions/slideTransition.ts@@ -1,24 +1,24 @@import {Direction, Vector2} from '../types';-import {easeInOutCubic, tween} from '../tweening';import {useScene} from '../utils';import {useTransition} from './useTransition';+import {all} from '../flow';-export function slideTransition(direction: Direction = Direction.Top) {+export function* slideTransition(+ direction: Direction = Direction.Top,+ duration = 0.6,+) {const size = useScene().getSize();const position = size.getOriginOffset(direction).scale(2);- const inverse = position.scale(-1);- let ppos = new Vector2();- let cpos = new Vector2();+ const previousPosition = Vector2.createSignal();+ const currentPosition = Vector2.createSignal(position);const endTransition = useTransition(- ctx => ctx.translate(cpos.x, cpos.y),- ctx => ctx.translate(ppos.x, ppos.y),+ ctx => ctx.translate(currentPosition.x(), currentPosition.y()),+ ctx => ctx.translate(previousPosition.x(), previousPosition.y()),);- return tween(- 0.6,- value => {- ppos = Vector2.lerp(Vector2.zero, inverse, easeInOutCubic(value));- cpos = Vector2.lerp(position, Vector2.zero, easeInOutCubic(value));- },- endTransition,++ yield* all(+ previousPosition(position.scale(-1), duration),+ currentPosition(Vector2.zero, duration),);+ endTransition();}diff --git a/packages/core/src/types/Vector.ts b/packages/core/src/types/Vector.tsindex 28f60682..e7e6ab7d 100644--- a/packages/core/src/types/Vector.ts+++ b/packages/core/src/types/Vector.ts@@ -2,7 +2,12 @@ import {arcLerp, InterpolationFunction} from '../tweening';import {map} from '../tweening/interpolationFunctions';import {Direction, Origin} from './Origin';import {Type} from './Type';-import {CompoundSignal, CompoundSignalContext, SignalValue} from '../signals';+import {+ CompoundSignal,+ CompoundSignalContext,+ Signal,+ SignalValue,+} from '../signals';export type SerializedVector2<T = number> = {x: T;@@ -23,6 +28,8 @@ export type Vector2Signal<T> = CompoundSignal<T>;+export type SimpleVector2Signal<T> = Signal<PossibleVector2, Vector2, T>;+/*** Represents a two-dimensional vector.*/diff --git a/packages/docs/docs/getting-started/hierarchy.mdx b/packages/docs/docs/getting-started/hierarchy.mdxindex c74de615..94e98074 100644--- a/packages/docs/docs/getting-started/hierarchy.mdx+++ b/packages/docs/docs/getting-started/hierarchy.mdx@@ -1,5 +1,5 @@----sidebar_position: 2+sidebar_position: 3slug: /hierarchy---diff --git a/packages/docs/docs/getting-started/positioning.mdx b/packages/docs/docs/getting-started/positioning.mdxnew file mode 100644index 00000000..efd4883c--- /dev/null+++ b/packages/docs/docs/getting-started/positioning.mdx@@ -0,0 +1,136 @@+---+sidebar_position: 4+slug: /positioning+---++import AnimationPlayer from '@site/src/components/AnimationPlayer';+import ApiSnippet from '@site/src/components/Api/ApiSnippet';++# Positioning++<AnimationPlayer name="positioning" banner />++Motion Canvas uses a Cartesian coordinate system. Its origin is located in the+center of the scene, with the x-axis going to the right and the y-axis going+down.++## Transform++All nodes are positioned relatively to their parents. This means that any+transformations applied to the parent are also applied to its children. The+transform of each node consists of the following properties:++### `Node.position`++<ApiSnippet url={'/api/2d/components/Node#position'} />+<hr />++### `Node.scale`++<ApiSnippet url={'/api/2d/components/Node#scale'} />+<hr />++### `Node.rotation`++<ApiSnippet url={'/api/2d/components/Node#rotation'} />+<hr />++## Absolute Transform++Each of the basic transform properties has a dedicated helper method that+operates in world space.++This can be helpful, for instance, when we need to match the transforms of two+nodes located within different parents. Consider the following example:++```tsx+const circleA = createRef<Node>();+const circleB = createRef<Node>();++view.add(+ <>+ <Node position={[200, 100]}>+ <Circle+ position={[0, 100]}+ ref={circleA}+ width={20}+ height={20}+ fill={'white'}+ />+ </Node>+ <Circle ref={circleB} width={10} height={10} fill={'red'} />+ </>,+);++circleB().absolutePosition(circleA().absolutePosition());+```++We access the absolute position (position in world space) of `circleA` and+assign it as the absolute position of `circleB`. This will move the `circleB`+right on top of `circleA`.++:::info++Note that we still need to set the `absolutePosition` of `circleB` and not just+the `position`. It may seem redundant since `circleB` is a direct child of the+scene view. But the local space of the scene view is **not** the same as the+world space.++:::++All available world-space properties are listed below:++### `Node.absolutePosition`++<ApiSnippet url={'/api/2d/components/Node#absolutePosition'} />+<hr />++### `Node.absoluteScale`++<ApiSnippet url={'/api/2d/components/Node#absoluteScale'} />+<hr />++### `Node.absoluteRotation`++<ApiSnippet url={'/api/2d/components/Node#absoluteRotation'} />+<hr />++## Matrices++For more advanced uses, nodes expose all the matrices necessary to map vectors+from one space to another. For example, the helper properties described above+could be reimplemented using the `worldToParent` and `localToWorld` matrices:++```ts+// getting the absolute position:+node.absolutePosition();+// same as:+Vector2.zero.transformAsPoint(node.localToWorld());++// setting the absolute position:+node.absolutePosition(vector);+// same as:+node.position(vector.transformAsPoint(node.worldToParent()));+```++The available matrices include:++### `Node.localToWorld`++<ApiSnippet url={'/api/2d/components/Node#localToWorld'} />+<hr />++### `Node.worldToLocal`++<ApiSnippet url={'/api/2d/components/Node#worldToLocal'} />+<hr />++### `Node.localToParent`++<ApiSnippet url={'/api/2d/components/Node#localToParent'} />+<hr />++### `Node.worldToParent`++<ApiSnippet url={'/api/2d/components/Node#worldToParent'} />+<hr />diff --git a/packages/docs/docs/getting-started/references.mdx b/packages/docs/docs/getting-started/references.mdxindex ef94d4ff..4dfbd25f 100644--- a/packages/docs/docs/getting-started/references.mdx+++ b/packages/docs/docs/getting-started/references.mdx@@ -1,5 +1,5 @@----sidebar_position: 5+sidebar_position: 7slug: /references---diff --git a/packages/docs/docs/getting-started/rendering.mdx b/packages/docs/docs/getting-started/rendering.mdxindex 261df9d2..2b1026ef 100644--- a/packages/docs/docs/getting-started/rendering.mdx+++ b/packages/docs/docs/getting-started/rendering.mdx@@ -1,5 +1,5 @@----sidebar_position: 9+sidebar_position: 11---import {VideoSettings} from '@site/src/Icon/VideoSettings';diff --git a/packages/docs/docs/getting-started/signals.mdx b/packages/docs/docs/getting-started/signals.mdxindex 3c3ec83c..99ea1483 100644--- a/packages/docs/docs/getting-started/signals.mdx+++ b/packages/docs/docs/getting-started/signals.mdx@@ -1,5 +1,5 @@----sidebar_position: 3+sidebar_position: 5slug: /signals---diff --git a/packages/docs/docs/getting-started/time-events.mdx b/packages/docs/docs/getting-started/time-events.mdxindex de8a8f17..84dce356 100644--- a/packages/docs/docs/getting-started/time-events.mdx+++ b/packages/docs/docs/getting-started/time-events.mdx@@ -1,5 +1,5 @@----sidebar_position: 6+sidebar_position: 8slug: /time-events---diff --git a/packages/docs/docs/getting-started/transitions.mdx b/packages/docs/docs/getting-started/transitions.mdxindex 05e356af..5bac7e56 100644--- a/packages/docs/docs/getting-started/transitions.mdx+++ b/packages/docs/docs/getting-started/transitions.mdx@@ -1,5 +1,5 @@----sidebar_position: 7+sidebar_position: 9slug: /transitions---diff --git a/packages/docs/docs/getting-started/tweening.mdx b/packages/docs/docs/getting-started/tweening.mdxindex a3a40f3a..4ef8419c 100644--- a/packages/docs/docs/getting-started/tweening.mdx+++ b/packages/docs/docs/getting-started/tweening.mdx@@ -1,5 +1,5 @@----sidebar_position: 4+sidebar_position: 6slug: /tweening---diff --git a/packages/docs/src/components/Api/Item/PropertyItem.tsx b/packages/docs/src/components/Api/Item/PropertyItem.tsxindex ef7b4831..bb249378 100644--- a/packages/docs/src/components/Api/Item/PropertyItem.tsx+++ b/packages/docs/src/components/Api/Item/PropertyItem.tsx@@ -11,18 +11,21 @@ import type {JSONOutput} from 'typedoc';export default function PropertyItem({reflection,+ headless,}: {reflection: JSONOutput.DeclarationReflection;+ headless?: boolean;}) {return (<>- {reflection.hasOwnPage ? (- <h1>{reflection.name}</h1>- ) : (- <Heading as="h3" id={reflection.anchor}>- <code>{reflection.name}</code>- </Heading>- )}+ {!headless &&+ (reflection.hasOwnPage ? (+ <h1>{reflection.name}</h1>+ ) : (+ <Heading as="h3" id={reflection.anchor}>+ <code>{reflection.name}</code>+ </Heading>+ ))}<Container><CodeBlock link={reflection.sources?.[0]?.url}><Line>diff --git a/packages/examples/src/layout.meta b/packages/examples/src/layout.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/layout.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/layout.ts b/packages/examples/src/layout.tsnew file mode 100644index 00000000..fa0335bd--- /dev/null+++ b/packages/examples/src/layout.ts@@ -0,0 +1,10 @@+import {Project} from '@motion-canvas/core/lib';++import layout from './scenes/layout?scene';+import {Vector2} from '@motion-canvas/core/lib/types';++export default new Project({+ scenes: [layout],+ size: new Vector2(960, 540),+ background: '#141414',+});diff --git a/packages/examples/src/positioning.meta b/packages/examples/src/positioning.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/positioning.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/positioning.ts b/packages/examples/src/positioning.tsnew file mode 100644index 00000000..d16d0081--- /dev/null+++ b/packages/examples/src/positioning.ts@@ -0,0 +1,10 @@+import {Project} from '@motion-canvas/core/lib';++import node from './scenes/positioning?scene';+import {Vector2} from '@motion-canvas/core/lib/types';++export default new Project({+ scenes: [node],+ size: new Vector2(960, 540),+ background: '#141414',+});diff --git a/packages/examples/src/scenes/layout.meta b/packages/examples/src/scenes/layout.metanew file mode 100644index 00000000..c9164b55--- /dev/null+++ b/packages/examples/src/scenes/layout.meta@@ -0,0 +1,4 @@+{+ "version": 1,+ "seed": 2835047788+}\ No newline at end of filediff --git a/packages/examples/src/scenes/layout.tsx b/packages/examples/src/scenes/layout.tsxnew file mode 100644index 00000000..a43bfd25--- /dev/null+++ b/packages/examples/src/scenes/layout.tsx@@ -0,0 +1,40 @@+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';+import {Circle, Rect, Layout} from '@motion-canvas/2d/lib/components';+import {createRef} from '@motion-canvas/core/lib/utils';+import {all} from '@motion-canvas/core/lib/flow';++const RED = '#ff6470';++export default makeScene2D(function* (view) {+ const colA = createRef<Layout>();+ const colB = createRef<Layout>();+ const rowA = createRef<Layout>();++ view.add(+ <>+ <Layout layout gap={10} padding={10} width={440} height={240}>+ <Rect ref={colA} grow={1} fill={'#242424'} radius={4} />+ <Layout gap={10} direction="column" grow={3}>+ <Rect+ ref={rowA}+ grow={8}+ fill={RED}+ radius={4}+ stroke={'#fff'}+ lineWidth={4}+ margin={2}+ >+ <Circle layout={false} width={20} height={20} fill={'#fff'} />+ </Rect>+ <Rect grow={2} fill={'#242424'} radius={4} />+ </Layout>+ <Rect ref={colB} grow={3} fill={'#242424'} radius={4} />+ </Layout>+ </>,+ );++ yield* all(colB().grow(1, 0.8), colA().grow(2, 0.8));+ yield* rowA().grow(1, 0.8);+ yield* all(colB().grow(3, 0.8), colA().grow(1, 0.8));+ yield* rowA().grow(8, 0.8);+});diff --git a/packages/examples/src/scenes/positioning.meta b/packages/examples/src/scenes/positioning.metanew file mode 100644index 00000000..0972fdbb--- /dev/null+++ b/packages/examples/src/scenes/positioning.meta@@ -0,0 +1,4 @@+{+ "version": 1,+ "seed": 3423079105+}\ No newline at end of filediff --git a/packages/examples/src/scenes/positioning.tsx b/packages/examples/src/scenes/positioning.tsxnew file mode 100644index 00000000..da08c2c5--- /dev/null+++ b/packages/examples/src/scenes/positioning.tsx@@ -0,0 +1,58 @@+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';+import {Node, Circle, Grid, Line} from '@motion-canvas/2d/lib/components';+import {all} from '@motion-canvas/core/lib/flow';+import {Vector2} from '@motion-canvas/core/lib/types';+import {createRef} from '@motion-canvas/core/lib/utils';+import {createSignal} from '@motion-canvas/core/lib/signals';++const RED = '#ff6470';+const GREEN = '#99C47A';+const BLUE = '#68ABDF';++export default makeScene2D(function* (view) {+ const group = createRef<Node>();+ const scale = createSignal(1);++ view.add(+ <Node ref={group} x={-100}>+ <Grid+ width={1920}+ height={1920}+ spacing={() => scale() * 60}+ stroke={'#444'}+ lineWidth={1}+ lineCap="square"+ cache+ />+ <Circle+ width={() => scale() * 120}+ height={() => scale() * 120}+ stroke={BLUE}+ lineWidth={4}+ startAngle={110}+ endAngle={340}+ />+ <Line+ stroke={RED}+ lineWidth={4}+ endArrow+ arrowSize={10}+ points={[Vector2.zero, () => Vector2.right.scale(scale() * 70)]}+ />+ <Line+ stroke={GREEN}+ lineWidth={4}+ endArrow+ arrowSize={10}+ points={[Vector2.zero, () => Vector2.up.scale(scale() * 70)]}+ />+ <Circle width={20} height={20} fill="#fff" />+ </Node>,+ );++ yield* group().position.x(100, 0.8);+ yield* group().rotation(30, 0.8);+ yield* scale(2, 0.8);+ yield* group().position.x(-100, 0.8);+ yield* all(group().rotation(0, 0.8), scale(1, 0.8));+});diff --git a/packages/examples/vite.config.ts b/packages/examples/vite.config.tsindex 6148b6d0..ca0651c0 100644--- a/packages/examples/vite.config.ts+++ b/packages/examples/vite.config.ts@@ -12,6 +12,8 @@ export default defineConfig({'./src/tweening-vector.ts','./src/node-signal.ts','./src/random.ts',+ './src/layout.ts',+ './src/positioning.ts',],}),],