Mob

Qualified name: algan.mobs.mob.Mob

class Mob(location=tensor([0., 0., 0.]), basis=tensor([1., 0., 0., 0., 1., 0., 0., 0., 1.]), color=None, opacity=1, glow=0, *args, **kwargs)

Bases: Animatable

Base class for all objects that have a location and orientation in 3-D space.

A Mob is an Animatable that exists in a 3-D scene, possessing properties like location, orientation (basis), and color. It can have child Mobs, forming a hierarchy, and supports various transformations and animations.

Parameters:

• location (torch.Tensor) – Initial location in 3-D world space. Shape: (*, 3) where * denotes any number of batch dimensions.

• basis (torch.Tensor) – Flattened 3x3 matrix specifying the Mob’s orientation and scale. The rows represent the right, upwards, and forwards directions, respectively, and the row norms represent the scale in those directions. Defaults to an identity matrix (no rotation, unit scale). Shape: (*, 9) representing (*, 3, 3) flattened.

• color (Color | None) – The color of the Mob. If None, it uses the default color defined by get_default_color() .

• opacity (float) – The maximum opacity of the Mob (0.0 for fully transparent to 1.0 for fully opaque).

• glow (float) – The glow intensity of the Mob.

• *args – Passed to Animatable base class.

• **kwargs – Passed to Animatable base class.

Examples

Create a square and move it to the left:

Example: Example1Mob

from algan import *

square = Square().spawn()
square.move(LEFT)

render_to_file()

from algan import *

square = Square().spawn()
square.move(LEFT)

render_to_file()

Create a mob with a specific color and scale:

Example: Example2Mob

from algan import *

circle = Circle(color=BLUE).scale(2).spawn()

render_to_file()

from algan import *

circle = Circle(color=BLUE).scale(2).spawn()

render_to_file()

Methods

add_property_getter_and_setter	Dynamically adds a property with a getter and setter for a given attribute name.
apply_absolute_change	Applies an animated absolute change to an attribute, interpolating to a target value.
apply_absolute_change_two	Applies an animated change to an attribute, interpolating between two target values.
apply_relative_change	Applies an animated relative change to an attribute.
apply_set_value	Sets an attribute's value, interpolating from its current value to the target change.
become	Transforms this Mob into another Mob (other_mob).
clear_cache	Clears cached animation data.
despawn_from_random_direction	Animates the Mob disappearing into a random direction, fading out and optionally rotating.
despawn_tilewise_recursive	Animates the despawning of the Mob and its primitive children in a lagged, "tile-wise" manner.
detach_history	"Detaches" the Mob's current state into a new, independent animation history.
expand_n_batch	Expands the batch size of the Mob's attributes by cloning existing batch elements.
expand_n_children	Expands the number of children by cloning existing ones to reach n additional children.
expand_n_list
expand_n_tensor
get_axis_aligned_lower_corner
get_axis_aligned_upper_corner
get_boundary_edge_point	Finds the point on the Mob's recursive boundary that is furthest in a given direction.
get_boundary_in_direction	Gets the point on the Mob's boundary (including children) that lies along the given direction from its center, and is furthest in that direction.
get_boundary_points	Returns the current location of the Mob, serving as its boundary point.
get_boundary_points_recursive	Recursively collects boundary points from this Mob and all its descendants.
get_bounding_box
get_center	Gets the logical center of the Mob.
get_descendants	Retrieves a list all descendant Mobs in the hierarchy, optionally including itself.
get_displacement_to_boundary	Calculates the vector displacement required to move this Mob's boundary to match another Mob's boundary along a given direction.
get_forward_direction	Gets the Mob's current forward direction vector (normalized).
get_length_along_direction	Calculates the total length of the Mob (and its descendants) when projected onto a given direction.
get_length_in_direction	Calculates the spatial extent of the Mob along a given direction.
get_normal	Alias for get_forward_direction() .
get_parts_as_mobs	Recursively flattens the Mob and its children into a list of individual Mobs.
get_points_evenly_along_direction
get_right_direction	Gets the Mob's current right direction vector (normalized).
get_shader_params
get_upwards_direction	Gets the Mob's current upwards direction vector (normalized).
look	Rotates the Mob so that one of its local axes points in the given direction.
look_and_scale	Rotates the Mob to look in a specific direction and simultaneously scales it.
look_at	Rotates the Mob to face a specific 3-D point.
move	Moves the Mob by a given displacement vector from its current location.
move_inline_with_boundary	Moves this Mob so its boundary aligns with another Mob's boundary along a specific direction.
move_inline_with_center	Moves this Mob so its center is aligned with another Mob's center along a given direction.
move_inline_with_edge	Moves this Mob so its specified edge is aligned with another Mob's edge along a given direction, while maintaining a buffer.
move_inline_with_mob	Moves this Mob to align with another Mob along a specific direction, either by their edges or by their centers.
move_next_to	Moves this Mob to be adjacent to another Mob (or a point) in a given direction.
move_out_of_screen	Animates the Mob moving off-screen in a given edge direction and then optionally despawns it.
move_to	Moves the Mob to a specified location.
move_to_corner	Moves the Mob to a corner of the screen, defined by two intersecting edge directions.
move_to_edge	Moves the Mob to an edge of the screen.
move_to_point_along_arc	Moves the Mob to a target point along a circular arc.
move_to_point_along_square	Moves the Mob to a destination in a two-step "square" path.
orbit_around_point
pulse_color	Animates a color pulse effect.
refresh_history	Resets the modification history and spawn time for this Mob and all its descendants.
register_attrs_as_animatable	Registers attributes as animatable, meaning their changes can be tracked and interpolated over time for animation.
reset_basis	Resets the Mob's basis to the identity matrix (no rotation, unit scale).
rotate	Rotates the Mob by a number of degrees around a given axis passing through the mob's center.
rotate_and_scale	Performs both rotation and scaling simultaneously.
rotate_around_line
rotate_around_point	Rotates the Mob around an arbitrary point in space.
rotate_around_point_non_recursive	Rotates the Mob around an arbitrary point in space without affecting its children.
scale	Scales the Mob by a factor scale_factor relative to its current scale.
set	Sets multiple attributes, applying changes recursively to children by default.
set_basis_inner	Internal method to set the basis of a child Mob relative to its parent, ensuring its global position is maintained despite parent's basis change.
set_basis_interpolated	Wrapper around _set_basis_interpolated to handle recursive flag.
set_data_sub_inds	Sets the sub-indices that this Mob will use when reading and writing from the shared data dictionaries (data.data_dict_active, data.data_dict_materialized).
set_location	Sets the location of the Mob.
set_non_recursive	Sets multiple attributes non-recursively (i.e., only for this Mob, not its children).
set_recursive	Sets multiple attributes for this Mob and then recursively propagates the changes to all its children.
set_recursive_from_parent	Sets attributes recursively for this Mob based on a parent Mob's attributes, handling batching and time synchronization.
set_scale	Sets the absolute scale of the Mob to a specific value.
set_shader	Sets the shader for this mob and all of its descendants.
set_time_inds_to	Synchronizes the animation time indices of this Mob with another Mob.
set_x_coord	Sets the x-coordinate of the Mob's location, preserving y and z.
set_x_y_coord	Sets the x and y coordinates of the Mob's location, preserving z.
set_y_coord	Sets the y-coordinate of the Mob's location, preserving x and z.
setattr_absolute	Sets an attribute to a value absolutely, animating the transition.
setattr_basic	Sets an attribute's value directly without complex animation logic.
setattr_non_recursive	Sets an attribute's value without applying the change to child Mobs.
setattr_relative	Sets an attribute by applying a relative change.
spawn_from_random_direction	Animates the Mob appearing from a random direction, fading in and optionally rotating.
spawn_tilewise_recursive	Animates the spawning of the Mob and its primitive children in a lagged, "tile-wise" manner.
wave_color	Applies a color wave effect across the Mob and its descendants.

Attributes

animation_manager
basis	The flattened 3x3 matrix representing the Mob's orientation and scale.
color
glow
location	The 3-D location of the Mob in world space.
max_opacity
normalized_basis	The Mob's basis matrix with all its row vectors normalized to unit length.
opacity
scale_coefficient	The scaling factor of the Mob along its local axes, derived from the basis.

_become_recursive(other_mob, move_to=False)

Internal recursive helper for the become method. Handles the transformation logic for children mobs.

Parameters:

• other_mob (Mob)

• move_to (bool)

_expand_batch_if_necessary(value)

Internal helper to expand a tensor’s batch dimension if it’s a singleton and the parent has a larger batch size.

Parameters:

value (Tensor)

Return type:

Tensor

_set_basis_interpolated(basis, interpolation=1, relation_key='basis', recursive='True')

Internal method to set the Mob’s basis, interpolating from the current basis to the target.

This method also ensures that child Mobs maintain their positions relative to this Mob during the basis change by adjusting their locations.

Parameters:

• basis (Tensor) – The target 3x3 basis matrix (flattened to 9 elements).

• interpolation (float) – Interpolation factor (0.0 to 1.0). 0.0 means current basis, 1.0 means target basis.

• relation_key (str) – Key for the relation function, typically ‘basis’ or ‘scale_coefficient’.

• recursive (str) – If “True”, applies the rotation recursively to children, maintaining their relative positions.

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

add_property_getter_and_setter(property_name, class_to_attach_to=None)

Dynamically adds a property with a getter and setter for a given attribute name.

The getter will retrieve the current (potentially animated) value of the attribute from the AnimatableData dict. The setter will set the value of the attribute in the AnimatableData dict, recording the change in the ModificationHistory for animation.

Parameters:

• property_name (str) – The name of the property to create (e.g., ‘location’, ‘color’).

• class_to_attach_to ((type, optional)) – The class to which this property will be added. Defaults to the instance’s own class.

apply_absolute_change(key, change, interpolation=1.0, recursive='True')

Applies an animated absolute change to an attribute, interpolating to a target value.

This method smoothly transitions the attribute’s value from its current state to the specified change value over time, according to the interpolation factor.

Parameters:

• (str) (key)

• (Any) (change)

• (float (interpolation) – 0.0 means no change from the current value; 1.0 means the attribute becomes change. Defaults to 1.0.

• optional) (If equal to "True", applies the change recursively) – 0.0 means no change from the current value; 1.0 means the attribute becomes change. Defaults to 1.0.

• (str (recursive) – to all child Mobs. Defaults to “True”.

• optional) – to all child Mobs. Defaults to “True”.

• key (str)

• change (any)

• interpolation (float)

• recursive (str)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

apply_absolute_change_two(key, change1, change2, interpolation=1.0, recursive='True')

Applies an animated change to an attribute, interpolating between two target values.

The interpolation first moves from the current value towards change1 from t=0 to 0.5, then moves from change1 to change2 from t=0.5 to 1.

Parameters:

• (str) (key)

• (Any) (change2)

• (Any)

• (float (interpolation)

• optional) (If equal to "True", applies the change recursively)

• (str (recursive) – to all child Mobs. Defaults to “True”.

• optional) – to all child Mobs. Defaults to “True”.

• key (str)

• change1 (any)

• change2 (any)

• interpolation (float)

• recursive (str)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

apply_relative_change(key, change, interpolation=1.0, recursive='True', relation_key='None')

Applies an animated relative change to an attribute.

The change is scaled by interpolation and then combined with the current attribute value using a predefined relation (e.g., addition for location, multiplication for scale).

Parameters:

• (str) (key)

• (Any) (change)

• (float (interpolation) – A value of 0.0 means no change; 1.0 applies the full change. Defaults to 1.0.

• optional) (The key to look up the specific relation function) – A value of 0.0 means no change; 1.0 applies the full change. Defaults to 1.0.

• (str (relation_key) – to all child Mobs. Defaults to “True”.

• optional) – to all child Mobs. Defaults to “True”.

• (str – (how the change is combined with the current value). If “None”, key is used as the relation key. Defaults to “None”.

• optional) – (how the change is combined with the current value). If “None”, key is used as the relation key. Defaults to “None”.

• key (str)

• change (any)

• interpolation (float)

• recursive (str)

• relation_key (str)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

apply_set_value(key, change, interpolation=1.0)

Sets an attribute’s value, interpolating from its current value to the target change.

This is a direct linear interpolation (lerp) from the current value to the target, rather than applying a relative change.

Parameters:

• (str) (key)

• (Any) (change)

• (float (interpolation) – 0.0 means the attribute remains its current value; 1.0 means it becomes change. Defaults to 1.0.

• optional) (The interpolation factor.) – 0.0 means the attribute remains its current value; 1.0 means it becomes change. Defaults to 1.0.

• key (str)

• change (any)

• interpolation (float)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

property basis: Tensor

The flattened 3x3 matrix representing the Mob’s orientation and scale.

The rows of the unflattened matrix correspond to the right, upwards, and forwards directions of the Mob’s local coordinate system. Their norms indicate the scaling along those axes. When accessed, When set, it triggers an animated interpolation to the new basis, maintaining child Mob positions relative to the parent.

become(other_mob, move_to=False, detach_history=True, minimize_movement=False)

Transforms this Mob into another Mob (other_mob).

This involves animating changes in location, opacity, color, basis, etc., to match other_mob. It intelligently attempts to match parts of this Mob to parts of other_mob for a smoother transition, especially for complex Mobs with multiple children or batched primitive points.

Parameters:

• other_mob (Mob) – The Mob to transform into. The type of this Mob must be compatible with the current Mob (e.g., both should be Mob or derived from it, and have the same num_points_per_object if applicable).

• detach_history (bool) – If True, the original Mob’s animation history is “detached” and this Mob starts a fresh animation history from its transformed state. If False, the transformation is recorded within the existing history.

• move_to (bool)

Returns:

The new (transformed) Mob instance,

Return type:

Mob

Raises:

NotImplementedError – If attempting to transform between mobs with different underlying primitive types (e.g., changing a triangle-based mob to a bezier-circuit-based mob).

clear_cache()

Clears cached animation data.

This is typically used internally when animation states are reset or recalculated, ensuring that subsequent rendering uses fresh data.

despawn_from_random_direction(travel_distance=0.1)

Animates the Mob disappearing into a random direction, fading out and optionally rotating. This animates the opacity to 0 and then marks the Mob as destroyed.

Parameters:

travel_distance (float)

despawn_tilewise_recursive()

Animates the despawning of the Mob and its primitive children in a lagged, “tile-wise” manner. Each tile/primitive disappears into a random direction with an ease-out-exponential effect.

detach_history()

“Detaches” the Mob’s current state into a new, independent animation history. This is useful when you want to take a snapshot of a Mob’s state and start animating it independently, without its previous history affecting new animations. The original history is effectively “frozen” and the new Mob begins a fresh history. #TODO explain why we use this (changing tensor dimensions isn’t inerpolable).

expand_n_batch(n)

Expands the batch size of the Mob’s attributes by cloning existing batch elements. This is used internally by become to match the batch dimensions when transforming between Mobs with different numbers of primitive points.

Parameters:

n (int) – The number of additional batch elements to add.

expand_n_children(n)

Expands the number of children by cloning existing ones to reach n additional children. This is used internally by become for smooth transformations between Mobs with different numbers of sub-parts.

Parameters:

n (int) – The number of additional children to add.

get_boundary_edge_point(direction)

Finds the point on the Mob’s recursive boundary that is furthest in a given direction.

Parameters:

direction (Tensor) – The 3-D vector indicating the direction along which to find the extreme boundary point.

Returns:

The 3-D coordinate of the boundary point furthest in direction.

Return type:

torch.Tensor

get_boundary_in_direction(direction)

Gets the point on the Mob’s boundary (including children) that lies along the given direction from its center, and is furthest in that direction.

Parameters:

• (torch.Tensor) (direction)

• direction (Tensor)

Returns:

torch.Tensor

Return type:

The 3-D coordinate of the boundary point.

get_boundary_points()

Returns the current location of the Mob, serving as its boundary point. For more complex Mobs, this should be overridden to provide actual boundary points.

Return type:

Tensor

get_boundary_points_recursive()

Recursively collects boundary points from this Mob and all its descendants.

Returns:

torch.Tensor – relevant Mobs in the hierarchy.

Return type:

A concatenated tensor of boundary points from all

get_center()

Gets the logical center of the Mob. Currently, this is simply the location attribute.

Return type:

Tensor

get_descendants(include_self=True)

Retrieves a list all descendant Mobs in the hierarchy, optionally including itself.

Parameters:

include_self (bool) – If True, the current Mob instance is included in the returned list.

Returns:

A flat list containing the Mob and all its children, grandchildren, and so on.

Return type:

list[Mob]

get_displacement_to_boundary(mob, direction)

Calculates the vector displacement required to move this Mob’s boundary to match another Mob’s boundary along a given direction.

Parameters:

• (Mob) (mob)

• (torch.Tensor) (direction)

• mob (Mob)

• direction (Tensor)

Returns:

torch.Tensor

Return type:

The displacement vector.

get_forward_direction()

Gets the Mob’s current forward direction vector (normalized). This corresponds to the third column of its normalized basis matrix.

Returns:

A 3-D vector representing the forward direction.

Return type:

torch.Tensor

get_length_along_direction(direction)

Calculates the total length of the Mob (and its descendants) when projected onto a given direction.

Parameters:

direction (Tensor) – The 3-D direction vector.

Returns:

The length of the Mob along the specified direction.

Return type:

torch.Tensor

get_length_in_direction(direction)

Calculates the spatial extent of the Mob along a given direction. This is the distance between the furthest points on its boundary in that direction and its opposite.

Parameters:

• (torch.Tensor) (direction)

• direction (Tensor)

Returns:

torch.Tensor

Return type:

The length of the Mob along the specified direction.

get_normal()

Alias for get_forward_direction() .

Return type:

the normalized forward direction vector of the Mob.

get_parts_as_mobs()

Recursively flattens the Mob and its children into a list of individual Mobs.

Returns:

A list containing this Mob and all its descendant Mobs.

Return type:

list[Mob]

get_right_direction()

Gets the Mob’s current right direction vector (normalized). This corresponds to the first column of its normalized basis matrix.

Returns:

A 3-D vector representing the right direction.

Return type:

torch.Tensor

get_upwards_direction()

Gets the Mob’s current upwards direction vector (normalized). This corresponds to the second column of its normalized basis matrix.

Returns:

A 3-D vector representing the upwards direction.

Return type:

torch.Tensor

property location: Tensor

The 3-D location of the Mob in world space.

When set, it triggers an animated change to the new location, maintaining child Mob positions relative to the parent..

look(direction, axis=2)

Rotates the Mob so that one of its local axes points in the given direction.

Parameters:

• direction (Tensor) – The target 3-D direction vector that the specified local axis should point towards. This vector does not need to be normalized.

• axis (int) – The index of the local axis to align. 0 for right (X-axis), 1 for up (Y-axis), 2 for forward (Z-axis). Defaults to 2 (forward vector).

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

look_and_scale(direction, scale, axis=2)

Rotates the Mob to look in a specific direction and simultaneously scales it.

Parameters:

• (torch.Tensor) (direction)

• torch.Tensor) (scale (float or)

• (int (axis) – Defaults to 2 (forward).

• optional) (The index of the local axis to align (0: right, 1: up, 2: forward).) – Defaults to 2 (forward).

• direction (Tensor)

• scale (float | Tensor)

• axis (int)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

look_at(point, axis=2)

Rotates the Mob to face a specific 3-D point. The Mob’s “forward” direction (or the specified axis) will be oriented towards the point.

Parameters:

• point (Tensor) – The 3-D point to look at.

• axis (int) – The index of the local axis to align (0: right, 1: up, 2: forward). Defaults to 2 (forward vector).

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move(displacement, **kwargs)

Moves the Mob by a given displacement vector from its current location.

Parameters:

• (torch.Tensor) (displacement)

• **kwargs (Additional arguments passed to move_to (e.g., path_arc_angle).)

• displacement (Tensor)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

move_inline_with_boundary(mob, direction)

Moves this Mob so its boundary aligns with another Mob’s boundary along a specific direction.

Parameters:

• mob (Mob) – The target Mob whose boundary will be aligned with.

• direction (Tensor) – The direction along which to align the boundaries.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move_inline_with_center(mob, direction, buffer=0.6)

Moves this Mob so its center is aligned with another Mob’s center along a given direction.

Parameters:

• (Mob) (mob)

• (torch.Tensor) (direction)

• (float (buffer) – implementation, as it aligns centers, not edges). Defaults to DEFAULT_BUFFER.

• optional) (Buffer distance (currently seems unused in this specific) – implementation, as it aligns centers, not edges). Defaults to DEFAULT_BUFFER.

• mob (Mob)

• direction (Tensor)

• buffer (float)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

move_inline_with_edge(mob, direction, edge=None, buffer=0.6, **kwargs)

Moves this Mob so its specified edge is aligned with another Mob’s edge along a given direction, while maintaining a buffer.

Parameters:

• (Mob) (mob)

• (torch.Tensor) (direction) – should occur (e.g., RIGHT, UP).

• (torch.Tensor (edge) – to determine “which side” of this Mob to use for alignment. If None, direction is used for both. Defaults to None.

• optional) (The buffer distance to maintain between the edges.) – to determine “which side” of this Mob to use for alignment. If None, direction is used for both. Defaults to None.

• (float (buffer) – Defaults to DEFAULT_BUFFER.

• optional) – Defaults to DEFAULT_BUFFER.

• **kwargs (Additional arguments for move().)

• mob (Mob)

• direction (Tensor)

• edge (Tensor | None)

• buffer (float)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

move_inline_with_mob(mob, align_direction, center=False, from_mob=None, buffer=0.6)

Moves this Mob to align with another Mob along a specific direction, either by their edges or by their centers.

Parameters:

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

• align_direction (torch.Tensor) – The 3-D vector defining the direction along which alignment should occur.

• center (bool) – If True, aligns the centers of the Mobs. If False, aligns their edges.

• from_mob ('Mob' | None) – The Mob whose edge/center is considered the starting point for calculating displacement. If None, this Mob itself is used.

• buffer (float) – Buffer distance between aligned edges (only relevant if center is False). Defaults to DEFAULT_BUFFER.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move_next_to(target_mob, direction, buffer=0.6, **kwargs)

Moves this Mob to be adjacent to another Mob (or a point) in a given direction.

Parameters:

• target_mob ('Mob' | torch.Tensor) – The target Mob or a 3-D point (torch.Tensor) to move next to.

• direction (torch.Tensor) – The 3-D vector indicating the direction from target_mob towards where this Mob should be placed. This vector does not need to be normalized.

• buffer (float) – The minimum distance to maintain between the closest edges of the two Mobs. Defaults to DEFAULT_BUFFER.

• **kwargs – Passed to move_to() .

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move_out_of_screen(edge, buffer=0.6, despawn=True)

Animates the Mob moving off-screen in a given edge direction and then optionally despawns it.

Parameters:

• edge (Tensor) – Vector indicating the direction to move off-screen.

• buffer (float) – Additional distance beyond the screen edge to move the Mob. Defaults to DEFAULT_BUFFER.

• despawn (bool) – If True, the Mob is despawned immediately after moving off-screen.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

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

Moves the Mob to a specified location.

If path_arc_angle is provided, the Mob moves along a circular arc. Otherwise, it moves in a straight line.

Parameters:

• (torch.Tensor) (location)

• (float (path_arc_angle) – for curved movement. If None, movement is linear. Defaults to None.

• optional) (The angle of the arc in degrees) – for curved movement. If None, movement is linear. Defaults to None.

• **kwargs (Additional arguments passed to set_location or) – move_to_point_along_arc.

• location (Tensor)

• path_arc_angle (float | None)

Returns:

Mob

Return type:

The Mob instance itself.

move_to_corner(edge1, edge2, buffer=0.6)

Moves the Mob to a corner of the screen, defined by two intersecting edge directions.

Parameters:

• edge1 (Tensor) – Vector for the first screen edge.

• edge2 (Tensor) – Vector for the second screen edge.

• buffer (float) – Distance to maintain from both screen borders. Defaults to DEFAULT_BUFFER.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move_to_edge(edge, buffer=0.6)

Moves the Mob to an edge of the screen.

Parameters:

• edge (Tensor) – A 3-D vector indicating the screen edge direction (e.g., RIGHT, LEFT, UP, DOWN).

• buffer (float) – Distance to maintain from the screen border after moving. Defaults to DEFAULT_BUFFER.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

move_to_point_along_arc(point, arc_angle_degrees, arc_normal=tensor([-0., -0., -1.]), recursive=True)

Moves the Mob to a target point along a circular arc. *Currently bugged*

Parameters:

• (torch.Tensor) (point)

• torch.Tensor) (arc_angle_degrees (float or) – The sign determines the direction of rotation along the arc (clockwise/counter-clockwise).

• (torch.Tensor (arc_normal) – of the arc. Defaults to OUT (positive Z-axis).

• optional) (If True, applies the rotation recursively) – of the arc. Defaults to OUT (positive Z-axis).

• (bool (recursive) – to children, maintaining their relative positions. Defaults to True.

• optional) – to children, maintaining their relative positions. Defaults to True.

• point (Tensor)

• arc_angle_degrees (float | Tensor)

• arc_normal (Tensor)

• recursive (bool)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

move_to_point_along_square(destination, displacement)

Moves the Mob to a destination in a two-step “square” path. First, it moves by the displacement vector. Then, it moves orthogonally to align with the destination point, and finally reaches the destination. This creates an L-shaped or Z-shaped path.

Parameters:

• destination (Tensor) – The final target 3-D location.

• displacement (Tensor) – The initial 3-D displacement vector for the first segment of the path.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

property normalized_basis: Tensor

The Mob’s basis matrix with all its row vectors normalized to unit length. This represents only the orientation (rotation) without any scaling.

pulse_color(color, opacity=None)

Animates a color pulse effect.

The Mob’s color changes to the target color and then animates back to its original color. This uses apply_absolute_change_two internally for the two-stage color change.

Parameters:

• (torch.Tensor) (color)

• (bool (set_opaque) – during the pulse. Defaults to False.

• optional) (If True, also animates opacity to 1.0) – during the pulse. Defaults to False.

• color (Tensor)

• opacity (bool)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

refresh_history()

Resets the modification history and spawn time for this Mob and all its descendants. This effectively clears all animation data and makes them behave as if newly created.

register_attrs_as_animatable(attrs, my_class=None)

Registers attributes as animatable, meaning their changes can be tracked and interpolated over time for animation.

This method dynamically creates property getters and setters for the specified attributes if they don’t already exist, allowing them to be controlled by the animation system. When an animatable attribute is modified, the change is recorded in the mob’s ModificationHistory.

Parameters:

• str) (attrs (set[str] or) – attribute name) to register as animatable.

• (type (my_class) – and setters should be attached. Defaults to the current Mob’s class.

• optional) (The class to which the property getters) – and setters should be attached. Defaults to the current Mob’s class.

• attrs (list[str])

reset_basis()

Resets the Mob’s basis to the identity matrix (no rotation, unit scale).

rotate(num_degrees, axis=tensor([-0., -0., -1.]))

Rotates the Mob by a number of degrees around a given axis passing through the mob’s center.

Parameters:

• num_degrees (float | Tensor) – The angle of rotation in degrees.

• axis (Tensor) – 3-D axis of rotation (e.g., OUT for Z-axis, UP for Y-axis). This vector does not need to be normalized. Defaults to OUT.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

rotate_and_scale(num_degrees, axis, scale, interpolation=1)

Performs both rotation and scaling simultaneously.

Parameters:

• torch.Tensor) (scale (float or)

• (torch.Tensor) (axis)

• torch.Tensor)

• (float (interpolation) – Defaults to 1.

• optional) (The interpolation factor for the animation.) – Defaults to 1.

• num_degrees (float | Tensor)

• axis (Tensor)

• scale (float | Tensor)

• interpolation (float)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

rotate_around_point(point, num_degrees, axis=tensor([-0., -0., -1.]))

Rotates the Mob around an arbitrary point in space.

Parameters:

• point (Tensor) – The 3-D point to rotate around.

• num_degrees (float | Tensor) – The angle of rotation in degrees.

• axis (Tensor) – The 3-D axis of rotation (passing through point). This vector does not need to be normalized. Defaults to OUT.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

rotate_around_point_non_recursive(point, num_degrees, axis=tensor([-0., -0., -1.]))

Rotates the Mob around an arbitrary point in space without affecting its children.

Parameters:

• point (Tensor) – The 3-D point to rotate around.

• num_degrees (float | Tensor) – The angle of rotation in degrees.

• axis (Tensor) – The 3-D axis of rotation (passing through point). Defaults to OUT.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

scale(scale_factor, recursive=True)

Scales the Mob by a factor scale_factor relative to its current scale.

Parameters:

• scale_factor (float | Tensor) – The scaling factor. For example, 2 for double size, 0.5 for half size.

• recursive (bool) – If True, applies scaling recursively to all descendant Mobs.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

property scale_coefficient: Tensor

The scaling factor of the Mob along its local axes, derived from the basis. It is the norm of the basis vectors.

set(**kwargs)

Sets multiple attributes, applying changes recursively to children by default. This is the primary method for changing a Mob’s properties and triggering animations for those changes.

Parameters:

**kwargs – Keyword arguments where keys are attribute names (e.g., ‘location’, ‘color’) and values are the new values for those attributes. These changes will be animated and propagated to children unless recursing is set to False (via setattr_non_recursive() or _set_recursing_state).

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

Examples

Move a square to the right and change its color to blue:

Example: Example1MobSet

from algan import *

mob = Square().spawn()
mob.set(location=RIGHT, color=BLUE)

render_to_file()

from algan import *

mob = Square().spawn()
mob.set(location=RIGHT, color=BLUE)

render_to_file()

set_basis_inner(parent_location, old_basis, new_basis)

Internal method to set the basis of a child Mob relative to its parent, ensuring its global position is maintained despite parent’s basis change.

Parameters:

• parent_location (Tensor)

• old_basis (Tensor)

• new_basis (Tensor)

Return type:

Mob

set_basis_interpolated(*args, **kwargs)

Wrapper around _set_basis_interpolated to handle recursive flag. Sets the Mob’s basis, interpolating from the current basis to the target.

Return type:

Mob

set_data_sub_inds(data_sub_inds)

Sets the sub-indices that this Mob will use when reading and writing from the shared data dictionaries (data.data_dict_active, data.data_dict_materialized). This is used for implementing indexing of batched mobs to retrieve sub-mobs that share the same underlying data.

Parameters:

data_sub_inds (list[int] or slice): The indices or slice to apply to the

batch dimension of the shared data tensors.

Parameters:

data_sub_inds (list[int] | slice)

set_location(location, recursive=True)

Sets the location of the Mob.

Parameters:

• (torch.Tensor) (location)

• (bool (recursive) – to maintain their relative positions. Defaults to True.

• optional) (If True, also affects the locations of child Mobs) – to maintain their relative positions. Defaults to True.

• location (Tensor)

• recursive (bool)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

set_non_recursive(**kwargs)

Sets multiple attributes non-recursively (i.e., only for this Mob, not its children). This is useful for applying changes that should not propagate down the hierarchy.

Parameters:

**kwargs – Keyword arguments where keys are attribute names (e.g., ‘color’, ‘opacity’) and values are the new values for those attributes.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

set_recursive(**kwargs)

Sets multiple attributes for this Mob and then recursively propagates the changes to all its children.

Parameters:

**kwargs – Keyword arguments for attributes to set.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

set_recursive_from_parent(parent, **kwargs)

Sets attributes recursively for this Mob based on a parent Mob’s attributes, handling batching and time synchronization. This is used internally for propagating changes down a hierarchy.

Parameters:

• parent (Mob) – The parent Mob from which attribute values might be derived or synced.

• **kwargs – Attributes to set, typically passed from the parent.

set_scale(scale, recursive=True)

Sets the absolute scale of the Mob to a specific value.

Parameters:

• scale (float | Tensor) – The target absolute scaling factor.

• recursive (bool) – If True, applies scaling recursively to all descendant Mobs.

Returns:

The Mob instance itself, allowing for method chaining.

Return type:

Mob

set_shader(shader)

Sets the shader for this mob and all of its descendants. This MUST be called before the mob is spawned, once spawned the shader cannot be changed. If you need to change the shader for a spawned mob, create a new clone of it with clone(spawn=False) and set the shader of the clone, and despawn the original.

Parameters:

shader – The function to use for shading at render time.

Returns:

The mob instance itself, allowing for method chaining.

Return type:

Mob

Raises:

.ModifiedProtectedAttributeError – If set_shader is used on an already spawned mob.

set_time_inds_to(mob)

Synchronizes the animation time indices of this Mob with another Mob.

This is used internally to ensure consistent animation states between mobs at animation time.

Parameters:

• (Mob) (mob)

• mob (Mob)

set_x_coord(x_coord)

Sets the x-coordinate of the Mob’s location, preserving y and z.

Parameters:

x_coord (Tensor)

set_x_y_coord(xy_coords)

Sets the x and y coordinates of the Mob’s location, preserving z.

Parameters:

xy_coords (Tensor)

set_y_coord(y_coord)

Sets the y-coordinate of the Mob’s location, preserving x and z.

Parameters:

y_coord (Tensor)

setattr_absolute(key, value)

Sets an attribute to a value absolutely, animating the transition.

This method directly interpolates the attribute’s value from its current state to the specified value.

Parameters:

• key (str) – The name of the attribute to set.

• value (any) – The target absolute value.

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

setattr_basic(key, value)

Sets an attribute’s value directly without complex animation logic.

If the attribute is animatable and an animation context is active, this will still record the change as a step-change (instantaneous transition). This method does not support recursive application to children. For animated or recursive changes, use setattr_absolute or setattr_relative.

Parameters:

• (str) (key)

• (Any) (value)

• key (str)

• value (any)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

setattr_non_recursive(key, value)

Sets an attribute’s value without applying the change to child Mobs.

This temporarily disables the recursive behavior of attribute setting for the duration of this specific attribute modification.

Parameters:

• (str) (key)

• (Any) (value)

• key (str)

• value (any)

setattr_relative(key, value, relation_key=None)

Sets an attribute by applying a relative change.

This method calculates the change needed to transition from the current value to the target value based on the inverse of the predefined relation. It then applies this change relatively to all children.

Parameters:

• key (str) – The name of the attribute to set.

• value (any) – The target value for the attribute.

• relation_key (str | None) – The key to use for looking up the relation functions. If None, key itself is used.

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.

spawn_from_random_direction(travel_distance=0.1)

Animates the Mob appearing from a random direction, fading in and optionally rotating. This sets the initial opacity to 0 and then animates it to 1.

Parameters:

travel_distance (float)

spawn_tilewise_recursive()

Animates the spawning of the Mob and its primitive children in a lagged, “tile-wise” manner. Each tile/primitive appears from a random direction with an ease-out-exponential effect.

wave_color(color, wave_length=2, reverse=False, direction=None, lag_duration=1, **kwargs)

Applies a color wave effect across the Mob and its descendants.

The color change propagates spatially across the mob’s constituent parts.

Parameters:

• (torch.Tensor) (color)

• (float (wave_length) – A smaller value means a faster-propagating or more compressed wave. Defaults to 1.

• optional) (The 3-D vector defining the) – A smaller value means a faster-propagating or more compressed wave. Defaults to 1.

• (bool (reverse) – opposite direction. Defaults to False.

• optional) – opposite direction. Defaults to False.

• (torch.Tensor (direction) – direction of wave propagation. If None, uses the Mob’s upwards direction. Defaults to None.

• optional) – direction of wave propagation. If None, uses the Mob’s upwards direction. Defaults to None.

• **kwargs (Additional keyword arguments passed to pulse_color) – for each individual part of the wave animation.

• color (Tensor)

• wave_length (float)

• reverse (bool)

• direction (Tensor | None)

Returns:

Mob

Return type:

The Mob instance itself, allowing for method chaining.