Camera

Qualified name: algan.rendering.camera.Camera

class Camera(orthographic=False, screen_distance=5, screen_half_height=2.5, fov=None, near=0.0, far=0.0, *args, **kwargs)

Bases: Mob

The Scene’s viewpoint. A Mob, so it animates like one.

Positioning

Use move_to() (or move for a relative step) – they set the camera’s own location and carry its screen along. Do not use move_center_to(): that centres a bounding box, and a Camera’s box spans it and its internal screen plane, so the camera lands half the screen distance behind where you asked.

Field of view and aspect ratio

fov / set_fov() are vertical, matching Three.js’s PerspectiveCamera. The horizontal field of view is derived from it and the output aspect ratio, so changing the resolution’s shape changes how wide the camera sees while the vertical stays put. The default 53 degree vertical fov gives about 82 degrees horizontally at 16:9, but about 119 degrees on a 3.4:1 banner – wide enough that an off-axis sphere is visibly projected as an ellipse (stretched by 1 / cos(angle off axis), so ~1.9x at that frame’s edge). That is correct perspective, not a bug, but it is rarely what a wide still is after: for the near-orthographic look of a long lens, narrow the fov and pull back by the same factor, keeping distance * tan(fov / 2) constant:

camera = Scene.get_camera()
camera.set_fov(math.degrees(2 * math.atan(3.5 / 70)))
camera.move_to(OUT * 70)  # was OUT * 7, so 10x the distance

Alternatively set_near_orthographic() flattens it almost completely – it is an approximation, not true parallel projection; see Renderer Limitations.

Methods

center_on	Move the camera so a Mob fills the frame, centred.
get_corner_pixels	Get the four corners of the visible frame, in world space.
get_far	Far clip distance (world units of ray travel from the camera); geometry farther than this shows the background/environment instead.
get_fov	The camera's vertical field of view in degrees (like Three.js's PerspectiveCamera.fov), derived from the screen size and the camera-to-screen distance.
get_near	Near clip distance (world units from the camera along its forward axis); geometry closer than this is not rendered.
project_point_onto_screen_border	Find where a point would leave the frame travelling in a direction.
set_distance_to_screen	Moves the camera focus to be the given distance away from its screen, thereby changing the perspective.
set_euler_angles	Point the camera using three Euler rotations about the origin.
set_far	Set the far clip distance (0 disables far clipping).
set_fov	Set the vertical field of view (degrees).
set_near	Set the near clip plane distance (0 disables near clipping).
set_near_orthographic	Flatten perspective by moving the camera far from its screen.

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.
draws_descendants	Whether get_render_primitives returns geometry belonging to this Mob's DESCENDANTS as well as its own.
far	Far clip distance (world units of ray travel from the camera); geometry farther than this shows the background/environment instead.
forward	Get the direction the Mob is facing.
fov	The camera's vertical field of view in degrees (like Three.js's PerspectiveCamera.fov), derived from the screen size and the camera-to-screen distance.
lifespan	This mob's [spawn, despawn) interval on its Scene timeline (a Lifespan).
location	The Mob's position in world space, shape (*, 3).
near	Near clip distance (world units from the camera along its forward axis); geometry closer than this is not rendered.
normalized_basis	The Mob's orientation with scale divided out, shape (*, 9).
parents	The Mobs this one is attached to, in attachment order.
pixel_height	Current normalized screen height represented by one output pixel.
pixel_width	Current normalized screen width represented by one output pixel.
receives_shadows	Whether this Mob's surfaces are darkened by shadows cast onto them.
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.
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).

center_on(mob, buffer_portion=0.7)

Move the camera so a Mob fills the frame, centred.

The camera slides sideways to centre the Mob and in or out until the Mob just fits, leaving buffer_portion of margin. It does not rotate, so the viewing angle you set is preserved.

Animation

Recorded as an animation: the moves run together inside a Sync, over the current context’s runtime (1 second by default). The Mob’s extent is measured when the call is recorded, so a Mob that changes size afterwards will not stay framed.

Parameters:

• mob – The Mob to frame.

• buffer_portion (float) – Extra margin around the Mob, as a fraction of its size. Defaults to 0.7, i.e. the framed area is 1.7 times the Mob’s extent.

Returns:

This camera, so calls can be chained.

Return type:

Camera

property far

Far clip distance (world units of ray travel from the camera); geometry farther than this shows the background/environment instead. 0 = disabled.

property fov

The camera’s vertical field of view in degrees (like Three.js’s PerspectiveCamera.fov), derived from the screen size and the camera-to-screen distance.

get_corner_pixels()

Get the four corners of the visible frame, in world space.

The corners of the camera’s screen plane, accounting for the current aspect ratio, ordered around the frame. Screen-relative layout is built on these.

Returns:

The four corner points, shape (4, *, 3).

Return type:

torch.Tensor

get_far()

Far clip distance (world units of ray travel from the camera); geometry farther than this shows the background/environment instead. 0 = disabled.

get_fov()

The camera’s vertical field of view in degrees (like Three.js’s PerspectiveCamera.fov), derived from the screen size and the camera-to-screen distance.

get_near()

Near clip distance (world units from the camera along its forward axis); geometry closer than this is not rendered. 0 = disabled.

property near

Near clip distance (world units from the camera along its forward axis); geometry closer than this is not rendered. 0 = disabled.

property pixel_height

Current normalized screen height represented by one output pixel.

property pixel_width

Current normalized screen width represented by one output pixel.

project_point_onto_screen_border(point, direction)

Find where a point would leave the frame travelling in a direction.

Casts from point along direction and returns the intersection with the edge of the visible frustum. This is what the screen-edge placement methods use to know where “against the edge” is.

Parameters:

• point (Tensor) – Starting point, shape (*, 3).

• direction (Tensor) – Direction to travel, shape (*, 3), e.g. RIGHT or UP.

Returns:

The point on the frame border, shape (*, 3).

Return type:

torch.Tensor

set_distance_to_screen(distance)

Moves the camera focus to be the given distance away from its screen, thereby changing the perspective.

Parameters:

distance – The camera focus will be set to be this distance away from the screen.

set_euler_angles(yaw, pitch, roll, *, degrees=True)

Point the camera using three Euler rotations about the origin.

The rotations are applied about the world x, y and z axes and are performed together, so the camera swings around the origin rather than turning in place. Note these are added to the camera’s current orientation rather than replacing it, despite the name.

Animation

Recorded as an animation: all three rotations run inside a Sync, over the current context’s runtime (1 second by default).

Parameters:

• yaw (float | Tensor) – Rotation about the world x axis (RIGHT).

• pitch (float | Tensor) – Rotation about the world y axis (UP).

• roll (float | Tensor) – Rotation about the world z axis (OUTWARD).

• degrees (bool) – Whether the three angles are in degrees. Defaults to True; pass False to give them in radians.

Returns:

This camera, so calls can be chained.

Return type:

Camera

set_far(far)

Set the far clip distance (0 disables far clipping).

set_fov(fov)

Set the vertical field of view (degrees). The camera stays where it is; its screen moves along the forward axis so that the given angle is spanned (small fov = telephoto, large fov = wide angle). Animatable.

The horizontal field of view follows from this and the output aspect ratio, so a wide frame sees much wider than this angle – see the Camera class docstring.

Parameters:

fov – Vertical field of view in degrees, in (0, 180).

set_near(near)

Set the near clip plane distance (0 disables near clipping).

set_near_orthographic(distance=100000.0)

Flatten perspective by moving the camera far from its screen.