MobOrientationMixin¶

Qualified name: algan.animatable\_base.mob\_orientation.MobOrientationMixin

class MobOrientationMixin[source]¶

Bases: object

Methods for rotating and orienting Mobs, mixed into Mob.

Methods

`get_forward_basis`	Get the Mob's forward basis vector, scale included.
`get_forward_direction`	Get the direction the Mob is facing.
`get_right_basis`	Get the Mob's rightward basis vector, scale included.
`get_right_direction`	Get the Mob's own rightward direction.
`get_up_basis`	Get the Mob's upward basis vector, scale included.
`get_up_direction`	Get the Mob's own upward direction.
`look`	Turn the Mob so one of its own axes points a given way.
`look_at`	Turn the Mob to face a point in space.
`orbit`	Move the Mob around a point without turning it.
`reset_basis`	Reset the Mob's orientation and scale to the default.
`rotate`	Rotate the Mob about an axis, optionally around a point in space.

Attributes

`forward`	Get the direction the Mob is facing.
`right`	The three direction getters also answer to a bare property, so `mob.up` reads as well as `mob.get_up_direction()`.
`up`	Get the Mob's own upward direction.

property forward: Tensor¶

Get the direction the Mob is facing.

The normalized third row of the Mob’s basis, i.e. its local +z axis in world space – which for an unrotated Mob is OUTWARD, towards the viewer. Scale is divided out, so this is always unit length.

Returns:: Unit forward direction, shape (*, 3).
Return type:: torch.Tensor

get_forward_basis()[source]¶

Get the Mob’s forward basis vector, scale included.

This is the third row of the Mob’s basis matrix, so its length is the Mob’s scale along that axis rather than 1. For a unit-length direction, use get_forward_direction().

Returns:: The forward basis vector, shape (*, 3), not normalized.
Return type:: torch.Tensor

get_forward_direction()[source]¶

Get the direction the Mob is facing.

Returns:: Unit forward direction, shape (*, 3).
Return type:: torch.Tensor

get_right_basis()[source]¶

Get the Mob’s rightward basis vector, scale included.

This is the first row of the Mob’s basis matrix, so its length is the Mob’s scale along that axis rather than 1. For a unit-length direction, use get_right_direction().

Returns:: The rightward basis vector, shape (*, 3), not normalized.
Return type:: torch.Tensor

get_right_direction()[source]¶

Get the Mob’s own rightward direction.

The normalized first row of the Mob’s basis, i.e. its local +x axis in world space. Scale is divided out, so this is always unit length. Note this is the Mob’s right, which is only the screen’s RIGHT while the Mob is unrotated.

Returns:: Unit rightward direction, shape (*, 3).
Return type:: torch.Tensor

get_up_basis()[source]¶

Get the Mob’s upward basis vector, scale included.

This is the second row of the Mob’s basis matrix, so its length is the Mob’s scale along that axis rather than 1. For a unit-length direction, use get_up_direction().

Returns:: The upward basis vector, shape (*, 3), not normalized.
Return type:: torch.Tensor

get_up_direction()[source]¶

Get the Mob’s own upward direction.

The normalized second row of the Mob’s basis, i.e. its local +y axis in world space. Scale is divided out, so this is always unit length.

Returns:: Unit upward direction, shape (*, 3).
Return type:: torch.Tensor

look(direction, with_axis='forward')[source]¶

Turn the Mob so one of its own axes points a given way.

The rotation taken is the shortest one that lines the chosen local axis up with direction; the Mob’s spin about that axis is otherwise left as it was.

Animation

Recorded as an animation: the turn is performed by rotate(), so it sweeps over the current context’s runtime (1 second by default). Applies to this Mob and its descendants.

Parameters:

direction (torch.Tensor) – World-space direction the chosen axis should point along, shape (*, 3); need not be normalized.
with_axis (str) – Which of the Mob’s local axes to aim: 'right', 'up' or 'forward', matched case-insensitively. Defaults to 'forward'.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

.AlganConfigurationError – If with_axis is not one of the three axis names.

See also

look_at(): Aim at a point rather than along a direction.

look_at(point, with_axis='forward')[source]¶

Turn the Mob to face a point in space.

Equivalent to look() along the direction from the Mob to point, so the Mob’s location is unchanged – only where it is aimed.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). The direction is resolved when the call is recorded, so a Mob aimed at a moving target will not track it (use an updater for that). Applies to this Mob and its descendants.

Parameters:

point (torch.Tensor) – World-space point to face, shape (*, 3).
with_axis (str) – Which of the Mob’s local axes to aim at point: 'right', 'up' or 'forward', matched case-insensitively. Defaults to 'forward'.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

.AlganConfigurationError – If with_axis is not one of the three axis names.

orbit(angle, axis=tensor([0., 0., 1.]), about=None, *, degrees=True)[source]¶

Move the Mob around a point without turning it.

The Mob’s location swings around the axis while its orientation is left unchanged. For an orbit that also turns the object as it moves, use rotate() with an about point.

Animation

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

Parameters:

angle (float | torch.Tensor) – How far around to travel, counter-clockwise when looking down axis, in degrees unless degrees is False.
axis (torch.Tensor) – Axis to orbit around; need not be normalized. Defaults to OUTWARD (the +z axis, out of the screen).
about (torch.Tensor | None) – Point to orbit around, shape (*, 3). Defaults to None, which makes the call a no-op – orbiting the Mob’s own center would not move it, since its orientation is held fixed.
degrees (bool) – Whether angle is in degrees. Defaults to True; pass False to give it in radians.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

reset_basis()[source]¶

Reset the Mob’s orientation and scale to the default.

The basis is set back to the identity matrix, which undoes every rotate() and every scale() applied so far. The Mob’s location is unaffected.

Animation

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

Returns:: This Mob, so calls can be chained.
Return type:: Mob

property right: Tensor¶: The three direction getters also answer to a bare property, so mob.up reads as well as mob.get_up_direction(). This is the one place Mob carries a deliberate alias (see CLAUDE.md); the basis getters have no property spelling on purpose, because they carry the Mob’s scale and a scaled vector reads wrongly as mob.up.

rotate(angle, axis=tensor([0., 0., 1.]), about=None, *, degrees=True)[source]¶

Rotate the Mob about an axis, optionally around a point in space.

With the default about=None only the Mob’s orientation changes and it stays where it is. Given an about point, the Mob also travels around the axis through that point, like a planet spinning as it orbits. To move around a point without re-orienting the Mob, use orbit().

Animation

Recorded as an animation: the rotation sweeps from 0 to angle over the current context’s runtime (1 second by default), so the Mob turns rather than snapping. Retime it with with Seq(runtime=3): mob.rotate(90), or apply it instantly with with Off(): mob.rotate(90). Applies to this Mob and its descendants.

Parameters:

angle (float | torch.Tensor) – How far to rotate, counter-clockwise when looking down axis, in degrees unless degrees is False. Accepts a tensor of shape (*, 1) to give each Mob of a batch its own angle.
axis (torch.Tensor) – Axis to rotate around; need not be normalized. Defaults to OUTWARD (the +z axis, pointing out of the screen), which spins a flat 2-D shape in the screen plane.
about (torch.Tensor | None) – Point to rotate around, shape (*, 3). Defaults to None, meaning rotate in place about the Mob’s own location, which for a shape is its centroid.
degrees (bool) – Whether angle is in degrees. Defaults to True; pass False to give it in radians.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Examples

Example: Example1MobRotate ¶

from algan import *

square = Square().spawn()
square.rotate(90)
square.rotate(180, axis=UP)
square.rotate(90, about=RIGHT * 2)

Scene.save_video()

property up: Tensor¶

Get the Mob’s own upward direction.

The normalized second row of the Mob’s basis, i.e. its local +y axis in world space. Scale is divided out, so this is always unit length.

Returns:: Unit upward direction, shape (*, 3).
Return type:: torch.Tensor