Skip to content

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.ts
index 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.ts
index 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.ts
index 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.mdx
index 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: 3
slug: /hierarchy
---
diff --git a/packages/docs/docs/getting-started/positioning.mdx b/packages/docs/docs/getting-started/positioning.mdx
new file mode 100644
index 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.mdx
index 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: 7
slug: /references
---
diff --git a/packages/docs/docs/getting-started/rendering.mdx b/packages/docs/docs/getting-started/rendering.mdx
index 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.mdx
index 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: 5
slug: /signals
---
diff --git a/packages/docs/docs/getting-started/time-events.mdx b/packages/docs/docs/getting-started/time-events.mdx
index 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: 8
slug: /time-events
---
diff --git a/packages/docs/docs/getting-started/transitions.mdx b/packages/docs/docs/getting-started/transitions.mdx
index 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: 9
slug: /transitions
---
diff --git a/packages/docs/docs/getting-started/tweening.mdx b/packages/docs/docs/getting-started/tweening.mdx
index 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: 6
slug: /tweening
---
diff --git a/packages/docs/src/components/Api/Item/PropertyItem.tsx b/packages/docs/src/components/Api/Item/PropertyItem.tsx
index 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.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/layout.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/layout.ts b/packages/examples/src/layout.ts
new file mode 100644
index 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.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/positioning.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/positioning.ts b/packages/examples/src/positioning.ts
new file mode 100644
index 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.meta
new file mode 100644
index 00000000..c9164b55
--- /dev/null
+++ b/packages/examples/src/scenes/layout.meta
@@ -0,0 +1,4 @@
+{
+ "version": 1,
+ "seed": 2835047788
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/layout.tsx b/packages/examples/src/scenes/layout.tsx
new file mode 100644
index 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.meta
new file mode 100644
index 00000000..0972fdbb
--- /dev/null
+++ b/packages/examples/src/scenes/positioning.meta
@@ -0,0 +1,4 @@
+{
+ "version": 1,
+ "seed": 3423079105
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/positioning.tsx b/packages/examples/src/scenes/positioning.tsx
new file mode 100644
index 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.ts
index 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',
],
}),
],