MobMovementMixin

Qualified name: algan.animatable\_base.mob\_movement.MobMovementMixin

class MobMovementMixin

Bases: object

Methods for moving Mobs around, mixed into Mob.

Methods

align_with	Line this Mob up with another along one axis.
move	Move the Mob by a displacement from wherever it currently is.
move_between	Move the Mob to the midpoint between two locations.
move_next_to	Move this Mob so it sits just beside another Mob or point.
move_off_screen	Slide the Mob off the screen, and by default despawn it there.
move_to	Move the Mob to an absolute location.
move_to_point_with_displacement	Move the Mob to a destination along a right-angled, three-leg path.
move_to_screen_corner	Move the Mob into a corner of the screen.
move_to_screen_edge	Move the Mob against one edge of the screen.
move_to_screen_position	Move the Mob so it appears at a given position on the screen.

align_with(mob, direction, anchor='center', buffer=None, from_mob=None)

Line this Mob up with another along one axis.

Only the component of the movement along direction is applied, so the two end up aligned on that axis with their positions on the other axes untouched: a.align_with(b, UP) puts them at the same height without changing how far apart they are horizontally.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). Applies to this Mob and its descendants.

Parameters:

• mob (Mob) – The Mob to align with.

• direction (torch.Tensor) – Axis to align along, and which of mob’s sides to measure from (e.g. RIGHT, UP); need not be normalized.

• anchor (str) – Which point on each Mob is brought into line, matched case-insensitively. 'center' (the default) aligns the two anchors. 'boundary' aligns the two direction-side boundaries, so the Mobs end up flush – sharing a bottom edge, say. 'edge' brings this Mob’s opposite side up against mob’s direction side, so the two abut rather than overlap.

• buffer (float | None) – Extra gap along direction, in world units. Defaults to None, which means SETTINGS.style.buffer (0.6) for anchor='edge' and no gap for the other two.

• from_mob (Mob | None) – Mob supplying the reference point that is moved into alignment, useful when aligning a group by one of its members. Defaults to None, meaning use this Mob.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

.AlganConfigurationError – If anchor is not one of the three names above.

move(displacement, **kwargs)

Move the Mob by a displacement from wherever it currently is.

Animation

Recorded as an animation: the Mob travels the displacement over the current context’s runtime (1 second by default). Retime it with with Seq(runtime=2): mob.move(RIGHT), or apply it instantly with with Off(): mob.move(RIGHT). Applies to this Mob and its descendants.

Parameters:

• displacement (torch.Tensor) – How far and in which direction to move, shape (*, 3), in world units. The spatial constants (RIGHT, UP, OUT, …) are unit vectors, so mob.move(RIGHT * 3) moves three units right.

• **kwargs – Passed to move_to() – notably arc_angle to travel along a curve rather than a straight line.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Examples

Example: Example1MobMove

from algan import *

square = Square().spawn()
square.move(RIGHT)
square.move(UP * 2 + LEFT)
square.move(DOWN, arc_angle=120)

Scene.save_video()

move_between(start, end)

Move the Mob to the midpoint between two locations.

Animation

Recorded as an animation: the Mob travels to the midpoint over the current context’s runtime (1 second by default). Applies to this Mob and its descendants.

Parameters:

• start (Mob | torch.Tensor) – First endpoint: a 3-D point of shape (*, 3), or a Mob, in which case its center is used.

• end (Mob | torch.Tensor) – Second endpoint, in the same forms as start.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

move_next_to(target_mob, direction, buffer=None, align_edge=None, **kwargs)

Move this Mob so it sits just beside another Mob or point.

Placement is edge-to-edge, not center-to-center: this Mob’s near boundary is set buffer away from the target’s boundary, so shapes of different sizes end up with an even gap between them.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). Applies to this Mob and its descendants.

Parameters:

• target_mob (Mob | torch.Tensor) – The Mob to sit beside, or a point of shape (*, 3) to treat as the target. A Mob contributes its boundary, a point only itself.

• direction (torch.Tensor) – Which side of target_mob to move to (e.g. RIGHT, UP); need not be normalized.

• buffer (float | None) – Gap to leave between the two boundaries, in world units. Defaults to SETTINGS.style.buffer (0.6).

• align_edge – Direction along which to additionally align the two Mobs’ boundaries (see align_with()), so e.g. two Mobs placed side by side can also share a bottom edge. Defaults to None, meaning no secondary alignment.

• **kwargs – Passed to move_to().

Returns:

This Mob, so calls can be chained.

Return type:

Mob

See also

align_with()

Align centers, edges or boundaries along one axis without changing the others.

move_off_screen(direction, buffer=None, despawn=True)

Slide the Mob off the screen, and by default despawn it there.

The Mob travels far enough that its whole bounding box clears the border, so nothing is left poking into frame.

Animation

Recorded as an animation: the slide takes the current context’s runtime (1 second by default), and the despawn follows it in a Seq without an extra fade, so the Mob is simply gone once it is out of sight. Applies to this Mob and its descendants.

Parameters:

• direction (torch.Tensor) – Which way to leave, in the camera’s frame: RIGHT, LEFT, UP or DOWN, meaning the sides of the screen whatever angle the camera is posed at.

• buffer (float | None) – Extra distance to travel beyond the screen border, in world units. Defaults to SETTINGS.style.buffer (0.6).

• despawn (bool) – Whether to despawn the Mob once it is off-screen. Defaults to True; pass False to keep it alive out of frame so it can slide back in later.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

move_to(location, arc_angle=None, **kwargs)

Move the Mob to an absolute location.

The path is a straight line unless arc_angle is given, in which case the Mob swings to the target along a circular arc.

Animation

Recorded as an animation: the Mob travels from where it is to location over the current context’s runtime (1 second by default). Use with Off(): mob.move_to(...) to teleport it instead. Applies to this Mob and its descendants.

Parameters:

• location (torch.Tensor) – The target location, shape (*, 3).

• arc_angle (float | None) – Signed sweep of the curved path, in degrees. Defaults to None, meaning travel in a straight line.

• **kwargs – Passed to set_location() (notably recursive), or to move_to_point_along_arc() when arc_angle is given (notably arc_normal).

Returns:

This Mob, so calls can be chained.

Return type:

Mob

See also

move()

Move by a relative displacement instead.

move_to_screen_position()

Place the Mob in screen space.

move_to_point_with_displacement(destination, displacement)

Move the Mob to a destination along a right-angled, three-leg path.

The Mob first travels along displacement, then along the component of the remaining distance orthogonal to it, then closes any remainder – tracing a bracket-shaped route instead of a diagonal. Useful for routing a Mob around something in the way.

Animation

Recorded as an animation. All three legs run inside a Seq(runtime=1), so the whole path takes 1 second regardless of the current context’s runtime. Applies to this Mob and its descendants.

Parameters:

• destination (torch.Tensor) – The final location, shape (*, 3).

• displacement (torch.Tensor) – Direction and length of the first leg, shape (*, 3); this is what decides which way the path bends.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

move_to_screen_corner(directions, buffer=None)

Move the Mob into a corner of the screen.

The corner is named by the edges that meet there, e.g. mob.move_to_screen_corner((UP, RIGHT)) for the top-right.

Animation

Recorded as an animation. The two edge moves run inside a Sync, so they happen simultaneously and the whole call still takes the current context’s runtime (1 second by default) rather than two seconds. Applies to this Mob and its descendants.

Parameters:

• directions – The screen edges meeting at the corner, as an iterable of direction vectors in the camera’s frame – (UP, RIGHT) for the top-right, whatever angle the camera is posed at.

• buffer (float | None) – Gap to leave from every screen border named, in world units. Defaults to SETTINGS.style.buffer (0.6).

Returns:

This Mob, so calls can be chained.

Return type:

Mob

move_to_screen_edge(direction, buffer=None)

Move the Mob against one edge of the screen.

The Mob’s own boundary is what comes to rest buffer inside the border, so a large and a small shape both end up looking equally inset. Where the Mob starts makes no difference: one that is already off-screen past that edge is brought back in, and calling this twice leaves it where the first call put it.

direction is read in the camera’s frame, not the world’s, so RIGHT means the right of the screen whatever angle the camera is posed at, and the Mob travels in the plane parallel to the screen rather than towards or away from the viewer.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). The edge position is resolved from the camera when the call is recorded. Applies to this Mob and its descendants.

Parameters:

• direction (torch.Tensor) – Which screen edge to move to, in the camera’s frame: RIGHT, LEFT, UP or DOWN. x runs across the screen, y up it and z out of it towards the viewer, so OUT is the camera’s -forward; RIGHT + OUT casts along the diagonal of the two and stops where that ray leaves the frustum.

• buffer (float | None) – Gap to leave between the Mob’s boundary and the screen border, in world units. Defaults to SETTINGS.style.buffer (0.6).

Returns:

This Mob, so calls can be chained.

Return type:

Mob

See also

move_to_screen_corner()

Move against two edges at once.

move_off_screen()

Move all the way off-screen.

move_to_screen_position(x, y)

Move the Mob so it appears at a given position on the screen.

The world location is worked out from the current camera, so this places the Mob where the viewer sees it rather than where it sits in 3-D space. The Mob keeps its distance from the camera; only its apparent position changes.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). The screen position is resolved once, when the call is recorded – a later camera move will not keep the Mob pinned there (use an updater for that). Applies to this Mob and its descendants.

Parameters:

• x (float | torch.Tensor) – Horizontal position in screen units: 0 is the left edge, 1 the right edge, 0.5 the middle. Values outside [0, 1] are off-screen.

• y (float | torch.Tensor) – Vertical position in screen units: 0 is the bottom edge, 1 the top edge.

Returns:

This Mob, so calls can be chained.

Return type:

Mob