pygfx.cameras.PerspectiveCamera

class pygfx.cameras.PerspectiveCamera(fov=50, aspect=1, *, width=None, height=None, zoom=1, maintain_aspect=True, depth=None, depth_range=None)

Bases: Camera

A generic 3D camera with a configurable field of view (fov).

Parameters:

fov (float) – The field of view as an angle in degrees. Higher values give a wide-angle lens effect. This value is limited between 0 and 179. If zero, it operates in orthographic mode. Default 50.
aspect (float) – The desired aspect ratio (width divided by height), which determines the vision pyramid’s boundaries. Default 1.
width (float) – The width of the scene to view. If omitted or None, the width is derived from aspect and height.
height (float) – The height of the scene to view. If omitted or None, the height is derived from aspect and width.
zoom (float) – An additional zoom factor, equivalent to attaching a zoom lens.
maintain_aspect (bool) – Whether the aspect ration is maintained as the window size changes. Default True. If false, the dimensions are stretched to fit the window.
depth (float | None) – The reference size of the scene in the depth dimension. By default this value gets set to the average of width and height. This happens on initialization and by show_pos(), show_object() and show_rect(). It is used to calculate a sensible depth range when depth_range is not set.
depth_range (2-tuple | None) – The explicit values for the near and far clip planes. If not given or None (the default), the clip planes ware calculated using fov and depth.

Notes

When the fov is zero, the width and height determine the view of the camera. When the fov is nonzero, the width and height only specify the aspect ratio. However, the width and height still represent the size of the scene, and the controllers uses it to e.g. determine the orbit-point, or the speed of motion.

When you use show_pos(), show_object(), or show_rect(), there is no need to set the width or height.

When you don’t use the show methods, and the fov is zero, you need to set the width and height, and optionally the depth.

property fov: The field of view (in degrees), between 0-179.

property width: The (minimum) width of the view-cube. Changing the width changes the aspect, but not the height.

property height: The (minimum) height of the view-cube. Changing the height changes the aspect, but not the width.

property aspect

The aspect ratio (width divided by height).

The aspect determines the vision pyramid’s boundaries. It can help fit the scene better to the window, and keep it fitting as the window is resized.

Setting the aspect updates width and height such that their mean is unchanged.

Note that show_object(match_aspect=True) also sets the aspect.

property zoom: The camera zoom level.

property maintain_aspect

Whether the aspect ration is maintained as the window size changes.

Default True. Note that it only make sense to set this to False in combination with a panzoom controller.

property depth

The reference size for the scene in the depth dimension.

This is only used if depth_range is not set.

This value is set by show_pos(), show_object() and show_rect(). It can be set by the user, but this is only recommended if you don’t use any of the show methods.

property depth_range

The user-defined values for the near and far clip planes.

By default this is None, causing the near and far planes to be calculated from fov and depth. This is a convenience that works well for simple cases. The automatic depth range calculation assumes that the scene is confined, containing one or more objects to be inspected. The depth range is set quite a bit larger than the scene, so the scene does not disappear as you zoom out, and e.g. grids have a proper horizon.

Cases where explicitly setting depth_range makes sense:

When you know your scene well, and just want to be explicit.
When the scene represents a larger world where there are near and distant objects.
When the automatically calculated depth range is suboptimal.
When the depth of your scene is much smaller/larger than (the average of the) width and height, e.g. in plotting. Although you can also set depth in this case.

property near: float: The location of the near clip plane. Use depth_range so overload the computed value, if necessary.

property far: float: The location of the far clip plane. Use depth_range so overload the computed value, if necessary.

get_state()

Get the state of the camera as a dict.

The fields contain “position”, “rotation”, “scale”, and “reference_up”, representing the camera’s transform. The scale is typically not used, but included for completeness. Further, the following properties are included: “fov”, “width”, “height”, “zoom”, “maintain_aspect”, and “depth_range”.

set_state(state)

Set the state of the camera from a dict.

Accepted fields are the same as in get_state(). In addition, the fields x, y, and z are also accepted to set the position along a singular dimension.

show_pos(target, *, up=None, depth=None)

Look at the given position or object.

This is similar to look_at() but it also sets the width and height (while honoring aspect). The camera’s position is not changed, but it’s ‘reference point’ does. E.g. with an orbit controller, it orbits around the given target.

Parameters:

target (WorldObject or (x, y, z)) – The target to point the camera towards.
up (3-tuple) – If given, set camera.world.reference_up to the given value.
depth (float) – The reference size for the scene in the depth dimension. If not given, the camera.depth is set based on .width and .height.

show_object(target: WorldObject, view_dir=None, *, up=None, scale=1, match_aspect=False, depth=None)

Position and orientate the camera such that the given target in is in view.

Sets the position and rotation of the camera, and adjusts its width and height to the target’s size (while honoring aspect).

The fit is such that as the object is rotated (or as the camera rotates around the object) the object still fits inside the viewport, which is usually good for 3D scenes.

When setting match_aspect, the bounding box of the object is matched to the screen, and the camera’s aspect adjusted accordingly. This gives a tight fit that is usually preferred for 2D scenes (with the panzoom-controller).

Parameters:

target (WorldObject or sphere (x, y, z, r)) – The object to look at.
view_dir (3-tuple of float) – Look at the object from this direction. If not given or None, uses the current view direction.
up (3-tuple) – If given, set camera.world.reference_up to the given value.
scale (float) – Scale the size of what’s shown. Default 1.
match_aspect (bool) – Whether to match the camera’s width and height to the target’s bounding box so it tighly fits the viewport. Useful with a PanZoomController, less so with a 3D scene.
depth (float) – The reference size for the scene in the depth dimension. If not given, the camera.depth is set based on .width and .height.

show_rect(left, right, top, bottom, *, view_dir=None, up=None, depth=None)

Position the camera such that the given rectangle is in view.

The rectangle represents a plane in world coordinates, centered at the origin of the world, and rotated to be orthogonal to the view_dir.

Sets the position and rotation of the camera, and adjusts width and height to the rectangle (thus also changing the aspect).

This method is mainly intended for viewing 2D data, especially when maintain_aspect is set to False, and is convenient for setting the initial view before attaching a PanZoomController.

See show_object(..., match_aspect=True) for a more automatic approach.

Parameters:

left (float) – The left boundary of the plane to show.
right (float) – The right boundary of the plane to show.
top (float) – The top boundary of the plane to show.
bottom (float) – The bottom boundary of the plane to show.
view_dir (3-tuple of float) – Look at the rectangle from this direction. If not given or None, uses the current view direction.
up (3-tuple) – If given, set camera.world.reference_up to the given value.
depth (float) – The reference size for the scene in the depth dimension. If not given, the camera.depth is set based on .width and .height.