Sphere

Qualified name: algan.mobs.shapes\_3d.Sphere

class Sphere(center=tensor([0., 0., 0.]), radius=1, resolution=None, u_range=(0, 360), v_range=(0, 180), *args, **kwargs)

Bases: Surface

A 3-D sphere, tessellated from a Surface.

Because it is a curved Surface rather than a fixed mesh, its silhouette is refined per frame to whatever the camera needs, so it stays round as you move in.

Parameters:

• center – World-space location of the sphere’s center, shape (*, 3) where * denotes zero or more batch dimensions. Python lists and floats are cast to tensors. Defaults to ORIGIN (the world origin).

• radius – Radius in world units. Defaults to 1.

• resolution – Manim-style grid resolution as (u_patches, v_patches), or one int for both. Manim counts patches and Algan counts sampled vertices, so each value is used as grid_width/grid_height plus one. Defaults to None, meaning Algan sizes the grid itself from geometry_tolerance.

• u_range – Azimuthal sweep around the sphere’s own up axis, in degrees. The sweep starts at the sphere’s LEFT and turns through OUTWARD, RIGHT and INWARD, so (0, 180) builds the OUTWARD half – the one facing the camera. Defaults to (0, 360), all the way round.

• v_range – Pole-to-pole sweep, in degrees: 0 is the DOWN pole and 180 the UP one. (0, 90) builds the bottom hemisphere, (45, 135) a band around the equator. Defaults to (0, 180), pole to pole.

• *args – Passed to Surface – notably color, grid_width/grid_height and the texture maps – notably color_texture, which get_checkerboard() and its siblings build.

• **kwargs – Passed to Surface – notably color, grid_width/grid_height and the texture maps – notably color_texture, which get_checkerboard() and its siblings build.

Notes

A partial u_range or v_range builds an open shell. The cut edges are not capped, so the inside of the surface shows through them, and the shape is re-tessellated from scratch rather than carved out of the whole sphere’s grid. The tessellation search only promises geometry_tolerance, and a sweep that still reaches a pole needs a finer grid there than a closed sphere does – so a partial sphere is not automatically the cheaper one.

Examples

A blue sphere, sized in world units:

Example: Example1Sphere

from algan import *

Sphere(radius=0.8, color=BLUE).spawn()

Scene.save_video()

A hemisphere, and a band around the equator:

Example: Example2Sphere

from algan import *

Sphere(radius=0.7, v_range=(0, 90), color=BLUE).move(LEFT * 0.9).spawn()
Sphere(radius=0.7, v_range=(60, 120),
       color=YELLOW).move(RIGHT * 0.9).spawn()

Scene.save_video()

Methods

coord_function

Map the surface's (u, v) parameters to positions in space.

Attributes

animation_manager	This mob's scene-owned animation manager.
basis	The Mob's orientation and scale, as a flattened 3x3 matrix of shape (*, 9).
casts_shadows	Whether this Mob's geometry blocks light on its way from a light source to another surface -- whether it casts a shadow.
children	The Mobs attached below this one, in attachment order.
closed_shell	Whether this Mob's triangles form a CLOSED shell -- every camera ray that enters the geometry crosses a second time on its way out.
color_texture	An image painted across the surface, as an [W, H, 5] RGBA+glow tensor.
draws_descendants	Whether get_render_primitives returns geometry belonging to this Mob's DESCENDANTS as well as its own.
forward	Get the direction the Mob is facing.
geometry_tolerance	How far this surface's mesh may sit from the exact shape, in world units.
lifespan	This mob's [spawn, despawn) interval on its Scene timeline (a Lifespan).
location	The Mob's position in world space, shape (*, 3).
normalized_basis	The Mob's orientation with scale divided out, shape (*, 9).
parents	The Mobs this one is attached to, in attachment order.
receives_shadows	Whether this Mob's surfaces are darkened by shadows cast onto them.
render_tolerance_pixels	How far a drawn triangle may sit from the true surface, in pixels.
right	Get the Mob's own rightward direction.
scale_coefficient	The Mob's scale along its own right, up and forward axes, shape (*, 3).
two_sided	Whether this Mob's geometry should be lit from whichever side the ray arrives on.
up	Get the Mob's own upward direction.
vertices	The surface's vertex positions, shape (*, grid_width * grid_height, 3).
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).

coord_function(coords_2d)

Map the surface’s (u, v) parameters to positions in space.

This is what defines the surface’s shape, and what each 3-D shape class overrides: Sphere maps the unit square onto a sphere, Torus onto a torus, and so on. The base implementation gives a flat plane spanning [-1, 1] on both axes.

Parameters:

uv – Parameter coordinates to map, shape (*, 2), with both components in [0, 1].

Returns:

Positions relative to the surface’s location, shape (*, 3).

Return type:

torch.Tensor

two_sided = False

Whether this Mob’s geometry should be lit from whichever side the ray arrives on. True (the default) is for geometry with no meaningful outside – a 2-D shape, Text, a parametric Surface, an imported mesh whose winding nobody has checked – where a back-facing hit is shaded with its normal flipped toward the viewer, so the surface is lit from behind instead of coming out black.

The built-in solids set it False: their normals face out (see tests/unit_tests/test_normal_orientation.py), so a back-facing hit is genuinely the inside of the solid and is shaded as such. That is what stops a half-transparent solid’s far shell from being lit like a second front shell – the bright and dark “planes” through a fading Octahedron. Set it True on an instance to get the old two-sided lighting back (an open Cone you want lit inside, say); it must be set before the Mob is spawned, since the render primitive reads it once.