MobLayoutMixin

Qualified name: algan.animatable\_base.mob\_layout.MobLayoutMixin

class MobLayoutMixin

Bases: object

Bounding boxes, boundary queries, and screen-relative placement (move_to_screen_edge, move_next_to, align_with, …).

Methods

fit_to_screen	Scale and move the Mob to fill a rectangle of the screen.
get_boundary_point	Get the point where the Mob's boundary sits along a direction.
get_boundary_points	Get the points that define this Mob's own outline.
get_boundary_points_recursive	Get the outline points of this Mob and all its descendants.
get_bounding_box	Get the eight corners of the box enclosing this Mob and its children.
get_bounding_box_max	Get the maximum corner of the box enclosing this Mob and its children.
get_bounding_box_min	Get the minimum corner of the box enclosing this Mob and its children.
get_bounding_box_size	Get the Mob's size along the world x, y and z axes.
get_center	Get the center of the box enclosing this Mob and its descendants.
get_coord	Get selected world coordinates of the Mob.
get_depth	Get the Mob's extent along the world z axis, in world units.
get_displacement_to_boundary	Get the displacement that would align this Mob's boundary with another's.
get_edge_point	Get the point on the Mob furthest along a direction.
get_height	Get the Mob's extent along the world y axis, in world units.
get_length_in_direction	Get how far the Mob extends along an arbitrary direction.
get_width	Get the Mob's extent along the world x axis, in world units.
move_center_to	Move the Mob so the middle of its bounding box lands on a point.
move_center_to_screen_position	Move the Mob so it appears centered at a position on the screen.
sample_points_in_direction	Get evenly spaced points spanning the Mob along a direction.
scale_to_height	Resize the Mob uniformly until it is a given height.
scale_to_width	Resize the Mob uniformly until it is a given width.
set_coord	Move the Mob along selected world axes, leaving the others alone.

Attributes

x	The Mob's x coordinate in world units, shape (*, 1).
xy	The Mob's x and y coordinates in world units, shape (*, 2).
y	The Mob's y coordinate in world units, shape (*, 1).
z	The Mob's z coordinate in world units, shape (*, 1).

fit_to_screen(bottom_left=None, top_right=None, *, preserve_aspect_ratio=True)

Scale and move the Mob to fill a rectangle of the screen.

Works on the camera-screen-aligned bounding box of the whole hierarchy, so its near face is parallel to the screen. Calling it on a Group lays out the entire collection at once and keeps its members’ relative positions. Handy for “put this diagram in the left half of the frame” without hand-tuning coordinates.

Animation

Recorded as an animation: the scale and the move run together inside a Sync, over the current context’s runtime (1 second by default). The rectangle is resolved from the camera when the call is recorded.

Parameters:

• bottom_left – (x, y) screen coordinates of the rectangle’s bottom-left corner, where (0, 0) is the bottom-left of the screen. Defaults to None, meaning (0, 0).

• top_right – (x, y) screen coordinates of the rectangle’s top-right corner, where (1, 1) is the top-right of the screen. Defaults to None, meaning (1, 1) – the whole screen.

• preserve_aspect_ratio (bool) – Whether to keep the Mob’s proportions. Defaults to True: the largest uniform scale that still fits inside the rectangle, so the Mob is undistorted but may leave slack on one axis. False stretches the Mob across the camera’s right and up axes independently so its projection fills the rectangle exactly.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

AlganConfigurationError – If the corners are not finite pairs satisfying 0 <= bottom_left < top_right <= 1, if the Mob’s bounding box projects to zero width or height, if any of it sits behind the camera, or if the Scene has no camera.

Notes

The fit is measured on the projection of a camera-screen-aligned AABB, so it holds for a Mob with depth under perspective (the near face of a Cube is bigger on screen than its center slice) and for a rotated camera (the box follows the camera’s right, up and forward axes, not the world axes).

get_boundary_point(direction)

Get the point where the Mob’s boundary sits along a direction.

The outermost boundary point projected back onto the line through the Mob’s center, i.e. how far the Mob reaches that way, measured from its middle. This is what the placement methods use, so mob.move_next_to(other, RIGHT) leaves an even gap for irregular shapes too.

Parameters:

direction (Tensor) – Direction to measure along, shape (*, 3); need not be normalized.

Returns:

The boundary point in that direction, shape (*, 1, 3).

Return type:

torch.Tensor

See also

get_edge_point()

The true extreme point, which may be off-axis.

get_boundary_points()

Get the points that define this Mob’s own outline.

The base implementation returns the Mob’s location, which is the whole outline of a point-like Mob. Shape classes override this to return their real silhouette, and that is what the placement methods measure against.

Returns:

Boundary points, shape (*, N, 3).

Return type:

torch.Tensor

get_boundary_points_recursive()

Get the outline points of this Mob and all its descendants.

Children marked exclude_from_boundary contribute nothing, so helper geometry does not enlarge a Mob’s apparent extent.

Returns:

All boundary points concatenated, shape (*, N, 3).

Return type:

torch.Tensor

get_bounding_box()

Get the eight corners of the box enclosing this Mob and its children.

The box is axis-aligned in world space, and children marked exclude_from_boundary (labels, helper geometry) are left out of it.

Returns:

The eight corner points, shape (*, 8, 3).

Return type:

torch.Tensor

get_bounding_box_max()

Get the maximum corner of the box enclosing this Mob and its children.

Returns:

Per-axis maximum, shape (*, 1, 3).

Return type:

torch.Tensor

get_bounding_box_min()

Get the minimum corner of the box enclosing this Mob and its children.

The same box get_bounding_box() returns the corners of, and the box get_center() is the middle of.

Returns:

Per-axis minimum, shape (*, 1, 3).

Return type:

torch.Tensor

get_bounding_box_size()

Get the Mob’s size along the world x, y and z axes.

Measured from the bounding box of this Mob and its descendants, in world units. Because the box is world-axis-aligned, a rotated Mob reports the size of its footprint, not of the shape itself.

Returns:

Width, height and depth, shape (*, 1, 3).

Return type:

torch.Tensor

get_center()

Get the center of the box enclosing this Mob and its descendants.

This is the midpoint of the bounding box, not the average of the Mob’s points and not necessarily its location – the location is an anchor that can sit anywhere, while this is the middle of what the viewer sees.

Returns:

The bounding-box center, shape (*, 1, 3).

Return type:

torch.Tensor

get_coord(indices, centered=False)

Get selected world coordinates of the Mob.

Parameters:

• indices (int | list[int]) – Which axes to read: 0 for x, 1 for y, 2 for z, or a list of them.

• centered (bool) – Whether to read the bounding-box center rather than the Mob’s anchor location. Defaults to False, meaning the anchor.

Returns:

A copy of the requested coordinates, safe to keep and modify.

Return type:

torch.Tensor

get_depth()

Get the Mob’s extent along the world z axis, in world units.

Returns:

Depth of this Mob and its descendants, shape (*, 1, 1).

Return type:

torch.Tensor

get_displacement_to_boundary(mob, direction)

Get the displacement that would align this Mob’s boundary with another’s.

The vector align_with() applies with anchor='boundary'; useful when you want the number rather than the movement.

Parameters:

• mob (Mob) – The Mob whose boundary is the target.

• direction (torch.Tensor) – Which boundary to align, e.g. DOWN for bottom edges.

Returns:

Displacement from this Mob’s boundary to mob’s, shape (*, 1, 3).

Return type:

torch.Tensor

get_edge_point(direction, recursive=True)

Get the point on the Mob furthest along a direction.

The actual outermost point of the geometry, which for an irregular shape is off to one side rather than straight out from the center. For the point straight out from the center, use get_boundary_point().

Parameters:

• direction (Tensor) – Direction to search along, shape (*, 3); need not be normalized.

• recursive (bool) – Whether to search this Mob’s descendants as well, so a Group reports the extreme point of whichever member reaches furthest. Defaults to True; pass False to search only this Mob’s own points.

Returns:

The extreme boundary point, shape (*, 1, 3).

Return type:

torch.Tensor

get_height()

Get the Mob’s extent along the world y axis, in world units.

Returns:

Height of this Mob and its descendants, shape (*, 1, 1).

Return type:

torch.Tensor

get_length_in_direction(direction)

Get how far the Mob extends along an arbitrary direction.

The distance between its two boundary points along that axis, so mob.get_length_in_direction(RIGHT) is its width and any other vector measures a diagonal extent.

Parameters:

direction (Tensor) – Direction to measure along, shape (*, 3); need not be normalized.

Returns:

Length along that direction in world units, shape (*, 1, 1).

Return type:

torch.Tensor

get_width()

Get the Mob’s extent along the world x axis, in world units.

Returns:

Width of this Mob and its descendants, shape (*, 1, 1).

Return type:

torch.Tensor

move_center_to(point)

Move the Mob so the middle of its bounding box lands on a point.

Unlike move_to(), which places the Mob’s anchor, this places what the viewer perceives as the middle – the right choice for centering text or a Group whose anchor is off to one side.

Animation

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

Parameters:

point (Tensor) – Where the bounding-box center should end up, shape (*, 3).

Returns:

This Mob, so calls can be chained.

Return type:

Mob

move_center_to_screen_position(screen_position=(0.5, 0.5))

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

The Mob keeps its distance from the camera, so this slides it across the view rather than towards or away from the viewer.

Animation

Recorded as an animation over the current context’s runtime (1 second by default). The screen position is resolved from the camera when the call is recorded, so a later camera move will not keep the Mob pinned there.

Parameters:

screen_position – Target (x, y) in screen units, from (0, 0) at the bottom-left to (1, 1) at the top-right. Defaults to (0.5, 0.5), the middle of the screen.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

AlganConfigurationError – If screen_position is not two finite coordinates within [0, 1], or if the Scene has no camera.

sample_points_in_direction(direction, count=3)

Get evenly spaced points spanning the Mob along a direction.

The points are strictly inside the Mob’s extent – the two boundary points themselves are excluded – which makes this convenient for hanging labels or ticks off a shape without landing on its edges.

Parameters:

• direction (Tensor) – Direction to space the points along, shape (*, 3).

• count (int) – How many points to return. Defaults to 3.

Returns:

count points, each of shape (*, 1, 3), ordered from the direction end towards the opposite end.

Return type:

list[torch.Tensor]

scale_to_height(height)

Resize the Mob uniformly until it is a given height.

The scale is uniform, so width and depth change by the same factor and the Mob keeps its proportions.

Animation

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

Parameters:

height (float | Tensor) – Target height along the world y axis, in world units. Must be positive.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

AlganConfigurationError – If height is not positive, or if the Mob’s current height is zero and no scale factor could produce the target.

scale_to_width(width)

Resize the Mob uniformly until it is a given width.

The scale is uniform, so height and depth change by the same factor and the Mob keeps its proportions.

Animation

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

Parameters:

width (float | Tensor) – Target width along the world x axis, in world units. Must be positive.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

Raises:

AlganConfigurationError – If width is not positive, or if the Mob’s current width is zero and no scale factor could produce the target.

set_coord(indices, value)

Move the Mob along selected world axes, leaving the others alone.

The general form of the x, y, z and xy properties; pass a list to set several axes at once.

Animation

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

Parameters:

• indices (int | list[int]) – Which axes to write: 0 for x, 1 for y, 2 for z, or a list such as [0, 2].

• value (Mob | torch.Tensor | float) – New coordinate values in world units, or a Mob whose location supplies them. A multi-component value is indexed with indices, so a full 3-D point can be passed and only the selected axes taken from it.

Returns:

This Mob, so calls can be chained.

Return type:

Mob

property x: Tensor

The Mob’s x coordinate in world units, shape (*, 1).

Animation

Assignment is recorded like any other Mob attribute: mob.x = 3 slides the Mob over the current context’s runtime, and with Off(): mob.x = 3 teleports it. Reading is not animated.

property xy: Tensor

The Mob’s x and y coordinates in world units, shape (*, 2).

Writing it moves the Mob in the screen plane and leaves z – its distance from the camera – alone. A value with more than two components may be assigned; the extra components are ignored.

Animation

Assignment is recorded, exactly as for x.

property y: Tensor

The Mob’s y coordinate in world units, shape (*, 1).

Animation

Assignment is recorded, exactly as for x.

property z: Tensor

The Mob’s z coordinate in world units, shape (*, 1).

The z axis runs out of the screen, so this is how far the Mob is from the camera.

Animation

Assignment is recorded, exactly as for x.