Camera

class nvisii.camera(*args, **kwargs)

The “Camera” component describes the perspective of an entity. It lens properties, like depth of field, focal length, field of view, and so on. It also describes the target render resolution. By connecting a camera component to an entity with a transform, that entity can be used to render the scene from a position in space.

static are_any_dirty(): Indicates whether or not any cameras are “out of date” and need to be updated through the “update components” function

static clear_all(): Clears any existing camera components.

static create(name, field_of_view=0.785398, aspect=1.0): Constructs a camera component. :type name: string :param name: A unique name for this camera. :type field_of_view: float, optional :param field_of_view: Specifies the field of view angle in the y direction. Expressed in radians. :type aspect: float, optional :param aspect: Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is a ratio of x (width) to y (height) :rtype: Camera :return: a reference to a camera component

static create_from_focal_length(name, focal_length, sensor_width, sensor_height)

Constructs a camera component from a focal length. The focal length controls the amount of zoom, i.e. the amount of the scene which is visible all at once. Longer focal lengths result in a smaller field of view (more zoom), while short focal lengths allow you to see more of the scene at once (larger FOV, less zoom)

Parameters

name (string) – A unique name for this camera.
focal_length (float) – Specifies the focal length of the camera lens (in millimeters).
sensor_width (float) – Specifies the width of the camera sensor (in millimeters).
sensor_height (float) – Specifies the height of the camera sensor (in millimeters).

Return type

Camera

Returns

a reference to a camera component

static create_from_fov(name, field_of_view, aspect)

Constructs a camera component from a field of view. The field of view controls the amount of zoom, i.e. the amount of the scene which is visible all at once. A smaller field of view results in a longer focal length (more zoom), while larger field of view allow you to see more of the scene at once (shorter focal length, less zoom)

Parameters

name (string) – A unique name for this camera.
field_of_view (float) – Specifies the field of view angle in the y direction. Expressed in radians.
aspect (float) – Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is a ratio of x (width) to y (height)

Return type

Camera

Returns

a reference to a camera component

static create_from_intrinsics(name, fx, fy, cx, cy, width, height, near=0.05, far=100.0)

Constructs a camera component from a set of intrinsic properties. These properties are common in computer-vision setups.

Parameters

name (string) – A unique name for this camera.
fx (float) – X-axis focal length in meters.
fy (float) – Y-axis focal length in meters.
cx (float) – X-axis optical center in pixels.
cy (float) – Y-axis optical center in pixels.
width (float) – Width of the current viewport, in pixels.
height (float) – Height of the current viewport, in pixels.
znear – The floating-point distance to the near clipping plane. If not specified, defaults to 0.05.
zfar – The floating-point distance to the far clipping plane. zfar must be greater than znear. If not specified, defaults to 100.0.

Return type

Camera

Returns

a reference to a camera component

static create_perspective_from_focal_length(name, focal_length, sensor_width, sensor_height): Deprecated in favor of create_from_focal_length

static create_perspective_from_fov(name, field_of_view, aspect): Deprecated in favor of either create or create_from_fov

static get(name)

Parameters: name (string) – The name of the camera to get
Return type: Camera
Returns: a Camera who’s name matches the given name

static get_count()

Return type: int
Returns: the number of allocated cameras.

static get_edit_mutex(): For internal use. Returns the mutex used to lock cameras for processing by the renderer.

static get_front()

Return type: Camera
Returns: a pointer to the list of Camera components.

static get_front_struct()

Return type: CameraStruct
Returns: a pointer to the table of CameraStructs

get_intrinsic_matrix(width, height): The intrinsic matrix is a 3x3 matrix that transforms 3D (non-homogeneous) cooordinates in camera space into 2D (homogeneous) image coordinates. These types of matrices are commonly used for computer vision applications, but are less common in computer graphics. :type width: float :param width: The width of the image (not tracked internally by the camera) :type height: float :param height: The height of the image (not tracked internally by the camera) :rtype: mat3 :return: An intrinsic matrix representation of the camera’s perspective.

get_name()

Return type: string
Returns: the name of this component

static get_name_to_id_map()

Return type: std::map< std::string,uint32_t,std::less< std::string >,std::allocator< std::pair< std::string const,uint32_t > > >
Returns: A map whose key is a camera name and whose value is the ID for that camera

get_projection()

Return type: mat4
Returns: the camera to projection matrix. This transform can be used to achieve perspective (eg a vanishing point), or for scaling an orthographic view.

get_struct(): Returns the simplified struct used to represent the current component

static initialize_factory(max_components): Allocates the tables used to store all Camera components

is_clean()

Return type: boolean
Returns: True if the camera has not been modified since the previous frame, and False otherwise

is_dirty()

Return type: boolean
Returns: True if the camera has been modified since the previous frame, and False otherwise

static is_factory_initialized()

Return type: boolean
Returns: True if the tables used to store all Camera components have been allocated, and False otherwise

is_initialized()

Return type: boolean
Returns: True the current camera is a valid, initialized camera, and False if the camera was cleared or removed.

mark_clean(): Tags the current component as being unmodified since the previous frame.

mark_dirty(): Tags the current component as being modified since the previous frame.

static remove(name)

Parameters: name (string) – The name of the camera to remove

set_aperture_diameter(diameter)

Real-world cameras transmit light through a lens that bends and focuses it onto the sensor. Because of this, objects that are a certain distance away are in focus, but objects in front and behind that are blurred.

Parameters: diameter (float) – Defines the amount of blurring by setting the diameter of the aperture (in millimeters).

set_focal_distance(distance)

Real-world cameras transmit light through a lens that bends and focuses it onto the sensor. Because of this, objects that are a certain distance away are in focus, but objects in front and behind that are blurred.

Parameters: distance (float) – The distance to the camera focal position. Note that this is different from focal length, and has no effect on the perspective of a camera.

NOTE: not to be confused with set_focal_length

set_focal_length(focal_length, sensor_width, sensor_height)

Tells the current camera component to use a projection matrix constructed from a focal length. The focal length controls the amount of zoom, i.e. the amount of the scene which is visible all at once. Longer focal lengths result in a smaller field of view (more zoom), while short focal lengths allow you to see more of the scene at once (larger FOV, less zoom)

Parameters

focal_length (float) – Specifies the focal length of the camera lens (in millimeters).
sensor_width (float) – Specifies the width of the camera sensor (in millimeters).
sensor_height (float) – Specifies the height of the camera sensor (in millimeters). NOTE: not to be confused with set_focal_distance

set_fov(field_of_view, aspect)

Tells the current camera component to use a projection matrix constructed from a field of view. The field of view controls the amount of zoom, i.e. the amount of the scene which is visible all at once. A smaller field of view results in a longer focal length (more zoom), while larger field of view allow you to see more of the scene at once (shorter focal length, less zoom)

Parameters

field_of_view (float) – Specifies the field of view angle in the y direction. Expressed in radians.
aspect (float) – Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is a ratio of x (width) to y (height)

set_intrinsics(fx, fy, cx, cy, width, height, near=0.05, far=100.0)

Constructs a projection matrix using custom intrinsics.

Parameters

fx (float) – X-axis focal length in meters.
fy (float) – Y-axis focal length in meters.
cx (float) – X-axis optical center in pixels.
cy (float) – Y-axis optical center in pixels.
width (float) – Width of the current viewport, in pixels.
height (float) – Height of the current viewport, in pixels.
znear – The floating-point distance to the near clipping plane. If not specified, defaults to 0.05.
zfar – The floating-point distance to the far clipping plane. zfar must be greater than znear. If not specified, defaults to 100.0.

set_projection(projection): Sets the projection matrix used to achieve a perspective (eg a vanishing point), or for scaling

an orthographic view

property thisown: The membership flag

to_string()

Return type: string
Returns: a string representation of the current component

static update_components(): Iterates through all components, updating any component struct fields and marking components as clean.