pygfx.cameras.PerspectiveCamera

class pygfx.cameras.PerspectiveCamera(fov=50, aspect=1, *, width=None, height=None, zoom=1, maintain_aspect=True, 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, which is used to determine the vision pyramid’s boundaries depending on the viewport size. Common values are 16/9 or 4/3. 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_range (2-tuple) – The values for the near and far clipping planes. If not given or None, the clip planes will be calculated automatically based on the fov, width, and height.

Note

The width and/or height should be set when using a fov of zero, when you want to manipulate the camera with a controller, or when you want to make use of the automatic depth_range. However, if you also call show_pos, show_object, or show_rect you can omit width and height, because these methods set them for you.

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 (the ratio between width and height). Setting the aspect updates width and height such that their mean is unchanged.

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_range

The values for the near and far clip planes. If None, these values are calculated from fov, width, amd heiht.

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)

Look at the given position or object.

This is similar to look_at(), but it also sets the width and height (while honoring aspect). So if you e.g. use an orbit controller on this camera, it rotates 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.

show_object(target: WorldObject, view_dir=None, *, up=None, scale=1)

Orientate the camera such that the given target in is in view.

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

This method is mainly intended for viewing 3D data. For 2D data it is not uncommon that the margins may feel somewhat large. Also see show_rect().

Parameters:

  • target (WorldObject or a 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.

show_rect(left, right, top, bottom, *, view_dir=None, up=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.

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.

property frustum

Corner positions of the viewing frustum in world space.

Returns:

frustum – The coordinates of the frustum. The first axis corresponds to the frustum’s plane (near, far), the second to the corner within the plane ((left, bottom), (right, bottom), (right, top), (left, top)), and the third to the world position of that corner.

Return type:

ndarray, [2, 4, 3]