Advanced Camera Features

class arcade.camera.data_types.ZeroProjectionDimension[source]

Bases: ValueError

A projection’s dimensions were zero along at least one axis.

This usually happens because code tried to set one of the following:

  • left equal to right

  • bottom equal to top

You can handle this error as a ValueError.

class arcade.camera.data_types.CameraData(position: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 0.0, 0.0), up: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 1.0, 0.0), forward: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 0.0, -1.0), zoom: float = 1.0)[source]

Bases:

Stores position, orientation, and zoom for a camera.

This is like where a camera is placed in 3D space.

Parameters:
  • position – The camera’s location in 3D space.

  • up – The direction which is considered “up” for the camera.

  • forward – The direction the camera is facing.

  • zoom – How much the camera is zoomed in or out.

forward: tuple[float, float, float]

A scalar which describes which direction the camera is pointing.

While this affects the projection matrix, it also allows camera controllers to access zoom functionality without interacting with projection data.

position: tuple[float, float, float]

A 3D vector which describes where the camera is located.

up: tuple[float, float, float]

A 3D vector which describes which direction is up (+y).

zoom: float

A scalar which describes how much the camera is zoomed in or out.

class arcade.camera.data_types.OrthographicProjectionData(left: float, right: float, bottom: float, top: float, near: float, far: float)[source]

Bases:

Describes an Orthographic projection.

This is by default a Left-handed system. with the X axis going from left to right, The Y axis going from bottom to top, and the Z axis going from towards the screen to away from the screen. This can be made right-handed by making the near value greater than the far value.

Parameters:
  • left – Left limit of the projection

  • right – Right limit of the projection

  • bottom – Bottom limit of the projection

  • top – Top limit of the projection

  • near – Near plane

  • far – Far plane

property bottom: float

The bottom-side cutoff value, which gets mapped to -y = 1.0.

Anything to the left of this value is not visible.

far: float

The ‘farthest’ visible position along the forward direction.

It will get mapped to z = 1.0. Anything father than this value is not visible.

property left: float

The left-side cutoff value, which gets mapped to x = -1.0.

Anything to the left of this value is not visible.

property lrbt: tuple[float, float, float, float]

The left, right, bottom, and top values of the projection.

near: float

The ‘closest’ visible position along the forward direction.

It will get mapped to z = -1.0. Anything closer than this value is not visible.

rect: Rect

Rectangle defining the projection area.

property right: float

The right-side cutoff value, which gets mapped to x = 1.0.

Anything to the left of this value is not visible.

property top: float

The top-side cutoff value, which gets mapped to y = 1.0.

Anything to the left of this value is not visible.

class arcade.camera.data_types.PerspectiveProjectionData(aspect: float, fov: float, near: float, far: float)[source]

Bases:

Data for perspective projection.

Parameters:
  • aspect – The aspect ratio of the screen (width over height).

  • fov – The field of view in degrees.

  • near – The ‘closest’ visible position along the forward direction.

  • far – The ‘farthest’ visible position along the forward

aspect: float

The aspect ratio of the screen (width over height).

far: float

” The ‘farthest’ visible position along the forward direction.

It will get mapped to z = 1.0. Anything father than this value is not visible.

fov: float

The field of view in degrees.

Together with the aspect ratio, it defines the size of the perspective projection for any given depth.

near: float

The ‘closest’ visible position along the forward direction.

It will get mapped to z = -1.0. Anything closer than this value is not visible.

class arcade.camera.data_types.Projection(*args, **kwargs)[source]

Bases: Protocol

Matches the data universal in Arcade’s projection data objects.

There are multiple types of projections used in games, but all the common ones share key features. This Protocol:

  1. Defines those shared elements

  2. Annotates these in code for both humans and automated type checkers

The specific implementations which match it are used inside of implementations of Arcade’s Projector behavior. All of these projectors rely on a viewport as well as near and far values.

The viewport is measured in screen pixels. By default, the conventions for this are the same as the rest of Arcade and OpenGL:

  • X is measured rightward from left of the screen

  • Y is measured up from the bottom of the screen

Although the near and far values are describe the cutoffs for what the camera sees in world space, the exact meaning differs between projection type.

Common Projection Type

Meaning of near & far

Simple Orthographic

The Z position in world space

Perspective & Isometric

Where the rear and front clipping planes sit along a camera’s CameraData.forward vector.

far: float
near: float
class arcade.camera.data_types.Projector(*args, **kwargs)[source]

Bases: Protocol

Projects from world coordinates to viewport pixel coordinates.

Projectors also support converting in the opposite direction from screen pixel coordinates to world space coordinates.

The two key spatial methods which do this are:

Method

Action

project()

Turn world coordinates into pixel coordinates relative to the origin (bottom left by default).

unproject()

Convert screen pixel coordinates into world space.

The other required methods are for helping manage which camera is currently used to draw.

activate() Generator[Self, None, None][source]
project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2[source]

Take a Vec2 or Vec3 of coordinates and return the related screen coordinate

unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3[source]

Take in a pixel coordinate and return the associated world coordinate

Essentially reverses the effects of the projector.

Parameters:

screen_coordinate – A 2D position in pixels should generally be inside the range of the active viewport.

Returns:

A 3D vector in world space.

use() None[source]

Set the GL context to use this projector and its settings.

Warning

You may be looking for:py:meth:.activate!

This method only sets rendering state for a given projector. Since it doesn’t restore any afterward, it’s easy to misuse in ways which can cause bugs or temporarily break a game’s rendering until relaunch. For reliable, automatic clean-up see the activate() method instead.

If you are implementing your own custom projector, this method should only:

  1. Set the Arcade Window’s current_camera to this object

  2. Calculate any required view and projection matrices

  3. Set any resulting values on the current ArcadeContext, including the:

    • viewport

    • view_matrix

    • projection_matrix

This method should never handle cleanup. That is the responsibility of activate.

arcade.camera.data_types.duplicate_camera_data(origin: CameraData)[source]

Clone camera data

Parameters:

origin – The camera data to clone

arcade.camera.data_types.constrain_camera_data(data: CameraData, forward_priority: bool = False)[source]

Ensure that the camera data forward and up vectors are length one, and are perpendicular

Parameters:
  • data – the camera data to constrain

  • forward_priority – whether up or forward gets constrained

arcade.camera.data_types.orthographic_from_rect(rect: Rect, near: float, far: float) OrthographicProjectionData[source]

Create an orthographic projection from a rectangle.

Parameters:
  • rect – The rectangle to create the projection from.

  • near – The near plane of the projection.

  • far – The far plane of the projection.

arcade.camera.projection_functions.generate_view_matrix(camera_data: CameraData) Mat4[source]

Using the ViewData it generates a view matrix from the pyglet Mat4 look at function

arcade.camera.projection_functions.generate_orthographic_matrix(perspective_data: OrthographicProjectionData, zoom: float = 1.0) Mat4[source]

Using the OrthographicProjectionData a projection matrix is generated where the size of an object is not affected by depth.

Generally keep the scale value to integers or negative powers of integers (2^-1, 3^-1, 2^-2, etc.) to keep the pixels uniform in size. Avoid a zoom of 0.0.

arcade.camera.projection_functions.generate_perspective_matrix(perspective_data: PerspectiveProjectionData, zoom: float = 1.0) Mat4[source]

Using the OrthographicProjectionData a projection matrix is generated where the size of the objects is not affected by depth.

Generally keep the scale value to integers or negative powers of integers (2^-1, 3^-1, 2^-2, etc.) to keep the pixels uniform in size. Avoid a zoom of 0.0.

arcade.camera.projection_functions.project_orthographic(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec2[source]
arcade.camera.projection_functions.unproject_orthographic(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec3[source]
arcade.camera.projection_functions.project_perspective(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec2[source]
arcade.camera.projection_functions.unproject_perspective(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec3[source]
class arcade.camera.orthographic.OrthographicProjector(*, window: Window | None = None, view: CameraData | None = None, projection: OrthographicProjectionData | None = None, viewport: Rect | None = None, scissor: Rect | None = None)[source]

Bases: Projector

The simplest from of an orthographic camera. Using ViewData and OrthographicProjectionData PoDs (Pack of Data) it generates the correct projection and view matrices. It also provides methods and a context manager for using the matrices in glsl shaders.

This class provides no methods for manipulating the PoDs.

The current implementation will recreate the view and projection matrices every time the camera is used. If used every frame or multiple times per frame this may be inefficient. If you suspect this is causing slowdowns profile before optimizing with a dirty value check.

Initialize a Projector which produces an orthographic projection matrix using a CameraData and PerspectiveProjectionData PoDs.

Parameters:
  • window – The window to bind the camera to. Defaults to the currently active camera.

  • view – The CameraData PoD. contains the viewport, position, up, forward, and zoom.

  • projection – The OrthographicProjectionData PoD. contains the left, right, bottom top, near, and far planes.

activate() Generator[Self, None, None][source]

Set this camera as the current one, then undo it after.

This method is a context manager you can use inside with blocks. Using it this way guarantees that the old camera and its settings will be restored, even if an exception occurs:

# Despite an Exception, the previous camera and its settings
# will be restored at the end of the with block below:
with projector_instance.activate():
     sprite_list.draw()
     _ = 1 / 0  # Guaranteed ZeroDivisionError
generate_projection_matrix() Mat4[source]

alias of arcade.camera.get_orthographic_matrix method

generate_view_matrix() Mat4[source]

alias of arcade.camera.get_view_matrix method

project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2[source]

Take a Vec2 or Vec3 of coordinates and return the related screen coordinate

property projection: OrthographicProjectionData

The OrthographicProjectionData. Is a read only property.

unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3[source]

Take in a pixel coordinate from within the range of the window size and returns the world space coordinates.

Essentially reverses the effects of the projector.

Parameters:

screen_coordinate – A 2D position in pixels from the bottom left of the screen. This should ALWAYS be in the range of 0.0 - screen size.

Returns:

A 3D vector in world space.

use() None[source]

Sets the active camera to this object. Then generates the view and projection matrices. Finally, the gl context viewport is set, as well as the projection and view matrices.

property view: CameraData

The CameraData. Is a read only property.

class arcade.camera.perspective.PerspectiveProjector(*, window: Window | None = None, view: CameraData | None = None, projection: PerspectiveProjectionData | None = None, viewport: Rect | None = None, scissor: Rect | None = None)[source]

Bases: Projector

The simplest from of a perspective camera.

Warning

Near cutoffs for perspective projection must be greater than zero.

This prevents division by zero errors since perspective involves dividing by distance.

Using ViewData and PerspectiveProjectionData PoDs (Pack of Data) it generates the correct projection and view matrices. It also provides methods and a context manager for using the matrices in glsl shaders.

This class provides no methods for manipulating the PoDs.

The current implementation will recreate the view and projection matrices every time the camera is used. If used every frame or multiple times per frame this may be inefficient. If you suspect this is causing slowdowns profile before optimizing with a dirty value check.

Initialize a Projector which produces a perspective projection matrix using a CameraData and PerspectiveProjectionData PoDs.

Parameters:
  • window – The window to bind the camera to. Defaults to the currently active camera.

  • view – The CameraData PoD. contains the viewport, position, up, forward, and zoom.

  • projection – The PerspectiveProjectionData PoD. contains the field of view, aspect ratio, and then near and far planes.

activate() Generator[Self, None, None][source]

Set this camera as the current one, then undo it after.

This method is a context manager you can use inside with blocks. Using it this way guarantees that the old camera and its settings will be restored, even if an exception occurs:

# Despite an Exception, the previous camera and its settings
# will be restored at the end of the with block below:
with projector_instance.activate():
     sprite_list.draw()
     _ = 1 / 0  # Guaranteed ZeroDivisionError
generate_projection_matrix() Mat4[source]

Generates a projection matrix.

This is an alias of arcade.camera.get_perspective_matrix.

generate_view_matrix() Mat4[source]

Generates a view matrix.

This is an alias of= arcade.camera.get_view_matrix.

project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2[source]

Convert world coordinates to pixel screen coordinates.

If a 2D Vec2 is provided instead of a 3D Vec3, then one will be calculated to the best of the method’s ability.

Parameters:

world_coordinate – A Vec2 or Vec3 as world coordinates.

Returns:

A 2D screen pixel coordinate.

property projection: PerspectiveProjectionData

Get the PerspectiveProjectionData.

This is a read-only property.

unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3[source]

Convert a pixel coordinate into world space.

This reverses the effects of project().

Parameters:

screen_coordinate – A 2D position in pixels from the bottom left of the screen. This should ALWAYS be in the range of 0.0 - screen size.

Returns: A 3D vector in world space.

use() None[source]

Set the active camera to this object and apply other config.

This includes the following steps:

  1. Set the window’s current camera to this one

  2. Generate appropriate view and projection matrices

  3. Set the GL context’s viewport and scissorbox values

  4. Apply the relevant matrices to Arcade’s Window object

property view: CameraData

Get the internal CameraData.

This is a read-only property. The CameraData. Is a read only property.

class arcade.camera.default.ViewportProjector(viewport: Rect | None = None, *, context: ArcadeContext | None = None)[source]

Bases:

A simple Projector which does not rely on any camera PoDs.

Does not have a way of moving, rotating, or zooming the camera. perfect for something like UI or for mapping to an offscreen framebuffer.

Parameters:
  • viewport – The viewport to project to.

  • context – The window context to bind the camera to. Defaults to the currently active window.

activate() Generator[Self, None, None][source]

The context manager version of the use method.

usable with the ‘with’ block. e.g. ‘with ViewportProjector.activate() as cam: …’

project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2[source]

Take a Vec2 or Vec3 of coordinates and return the related screen coordinate

unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3[source]

Map the screen pos to screen_coordinates.

Due to the nature of viewport projector this does not do anything.

use() None[source]

Set the window’s projection and view matrix. Also sets the projector as the windows current camera.

property viewport: Rect

The viewport use to derive projection and view matrix.

class arcade.camera.default.DefaultProjector(*, context: ArcadeContext | None = None)[source]

Bases: ViewportProjector

An extremely limited projector which lacks any kind of control. This is only here to act as the default camera used internally by Arcade. There should be no instance where a developer would want to use this class.

Parameters:

context – The window context to bind the camera to. Defaults to the currently active window.

use() None[source]

Set the window’s Projection and View matrices.

cache’s the window viewport to determine the projection matrix.

arcade.camera.static.static_from_orthographic(view: CameraData, orthographic: OrthographicProjectionData, viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera[source]

Create a static camera from a CameraData and OrthographicProjectionData

Parameters:
  • view – The view matrix to use

  • orthographic – The orthographic projection to use

  • viewport – The viewport to use

  • window – The window to use

arcade.camera.static.static_from_perspective(view: CameraData, perspective: OrthographicProjectionData, viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera[source]

Create a static camera from a CameraData and PerspectiveProjectionData

Parameters:
  • view – The view matrix to use

  • perspective – The perspective projection to use

  • viewport – The viewport to use

  • window – The window

arcade.camera.static.static_from_raw_orthographic(projection: tuple[float, float, float, float], near: float = -100.0, far: float = 100.0, zoom: float = 1.0, position: Point3 = (0.0, 0.0, 0.0), up: Point3 = (0.0, 1.0, 0.0), forward: Point3 = (0.0, 0.0, -1.0), viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera[source]

Create a static camera from raw orthographic data.

Parameters:
  • projection – The orthographic projection to use

  • near – The near plane

  • far – The far plane

  • zoom – The zoom level

  • position – The position of the camera

  • up – The up vector

  • forward – The forward vector

  • viewport – The viewport

  • window – The window

arcade.camera.static.static_from_raw_perspective(aspect: float, fov: float, near: float = -100.0, far: float = 100.0, zoom: float = 1.0, position: Point3 = (0.0, 0.0, 0.0), up: Point3 = (0.0, 1.0, 0.0), forward: Point3 = (0.0, 0.0, -1.0), viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera[source]

Create a static camera from raw perspective data.

Parameters:
  • aspect – The aspect ratio

  • fov – The field of view

  • near – The near plane

  • far – The far plane

  • zoom – The zoom level

  • position – The position of the camera

  • up – The up vector

  • forward – The forward vector

  • viewport – The viewport

  • window – The window

arcade.camera.static.static_from_matrices(view: Mat4, projection: Mat4, viewport: tuple[int, int, int, int] | None, *, window: Window | None = None, project_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec2] | None = None, unproject_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec3] | None = None) _StaticCamera[source]

Create a static camera from raw matrices.

Parameters:
  • view – The view matrix

  • projection – The projection matrix

  • viewport – The viewport

  • window – The window

  • project_method – The project method

  • unproject_method – The unproject method