anki_vector.opengl.opengl¶

This module provides 3D support classes for OpenGL, used by opengl_viewer.py.

It uses PyOpenGL, a Python OpenGL 3D graphics library which is available on most platforms. It also depends on the Pillow library for image processing.

Warning

This package requires Python to have the PyOpenGL package installed, along with an implementation of GLUT (OpenGL Utility Toolkit).

To install the Python packages on Mac and Linux do python3 -m pip install --user "anki_vector[3dviewer]"

To install the Python packages on Windows do py -3 -m pip install --user "anki_vector[3dviewer]"

On Windows and Linux you must also install freeglut (macOS / OSX has one preinstalled).

On Linux: sudo apt-get install freeglut3

On Windows: Go to http://freeglut.sourceforge.net/ to get a freeglut.dll file. It’s included in any of the Windows binaries downloads. Place the DLL next to your Python script, or install it somewhere in your PATH to allow any script to use it.”

Functions

raise_opengl_or_pillow_import_error(…)

Classes

`Camera`(look_at, up, distance, pitch, yaw)	Class containing the state of a 3d camera, used to transform all object in a scene with relation to a particular point of view.
`DynamicTexture`()	Wrapper around An OpenGL Texture that can be dynamically updated.
`Light`(ambient_color, diffuse_color, …[, …])	Configuration for a light in the OpenGL scene that effects the shading of 3d geometry.
`MaterialLibrary`(resource_context, asset_key)	Load a .mtl material asset, and return the contents as a dictionary.
`MeshData`(resource_manager, asset_key)	The loaded / parsed contents of a 3D Wavefront OBJ file.
`MeshFace`(position_ids, normal_ids, tex_ids, …)	A face polygon in 3d space - the basic building block of 3D models.
`MeshGroup`(name)	A colletions of face polygons which can be rendered as a group by name.
`OpenGLWindow`(x, y, width, height, window_name)	A Window displaying an OpenGL viewport.
`PrecomputedView`()	A collection of static 3D object which are pre-computed on the graphics card, so they can be quickly drawn when needed.
`Projector`(fov, near_clip_plane, far_clip_plane)	Configuration for how 3d objects are projected onto the 2d window.
`ResourceManager`(context_id)	Handles returning file resources by keys.

Exceptions

InvalidOpenGLGlutImplementation

Raised by OpenGLViewer if no valid GLUT implementation available.

class anki_vector.opengl.opengl.Camera(look_at, up, distance, pitch, yaw)¶

Class containing the state of a 3d camera, used to transform all object in a scene with relation to a particular point of view.

This class is meant to be mutated at run time.

Parameters

look_at (Vector3) – The initial target of the camera.
up (Vector3) – The initial up vector of the camera.
distance (float) – The initial distance between the camera and it’s target.
pitch (float) – The camera’s current rotation about its X axis
yaw (float) – The camera’s current rotation about its up axis

apply()¶: Applies the transform this camera represents to the active OpenGL context.

property look_at¶

The target position of the camera

Return type: Vector3

move(forward_amount=0.0, right_amount=0.0, up_amount=0.0)¶

Offsets the camera’s position incrementally.

Parameters

forward_amount (float) – distance to move along the camera’s current forward heading.
right_amount (float) – distance to move along a right angle to the camera’s current forward heading.
up_amount (float) – distance to move along the camera’s up vector.

turn(yaw_delta, pitch_delta)¶

Incrementally turns the camera.

Parameters

yaw_delta (float) – Amount to rotate around the camera’s up axis.
pitch_delta (float) – Amount to rotate around the camera’s X axis. This is automatically capped between +/- pi/2

zoom(amount)¶

Moves the camera closer or further from it’s target point.

Parameters: amount (float) – distance to zoom in or out, automatically minimized at 0.1

class anki_vector.opengl.opengl.DynamicTexture¶

Wrapper around An OpenGL Texture that can be dynamically updated.

bind()¶: Bind the texture for rendering.

update(pil_image)¶

Update the texture to contain the provided image.

Parameters: pil_image (Image) – The image to write into the texture.

class anki_vector.opengl.opengl.MaterialLibrary(resource_context, asset_key)¶

Load a .mtl material asset, and return the contents as a dictionary.

Supports the subset of MTL required for the Vector 3D Viewer assets.

Parameters

resource_manager – Manager to load resources from.
asset_key (str) – The key of the asset to load.

get_material_by_name(name)¶

Returns a dict of material attributes

Return type: dict

class anki_vector.opengl.opengl.MeshData(resource_manager, asset_key)¶

The loaded / parsed contents of a 3D Wavefront OBJ file.

This is the intermediary step between the file on the disk, and a renderable 3D object. It supports the subset of the OBJ file that was used in the Vector and Cube assets, and does not attempt to exhaustively support every possible setting.

Parameters

resource_manager (ResourceManager) – The resource manager to load this mesh from.
asset_key (str) – The key of the OBJ file to load from the resource manager.

property groups¶

All supported mesh groups, indexed by group name.

Return type: Dict[str, MeshGroup]

load_from_obj_asset(asset_key)¶

Loads all mesh data from a specified resource.

Parameters: asset_key (str) – Key for the desired OBJ asset in the resource_manager.

property material_library¶

A container that MTL material attribute dicts can be fetched from by string key.

Return type: MaterialLibrary

property normals¶

All directional vertex normals in this mesh.

Return type: List[List[float]]

property tex_coords¶

All texture coordinates in this mesh.

Return type: List[List[float]]

property vertices¶

All worldspace vertex positions in this mesh.

Return type: List[List[float]]

class anki_vector.opengl.opengl.MeshFace(position_ids, normal_ids, tex_ids, active_material)¶

A face polygon in 3d space - the basic building block of 3D models.

The actual coordinate data is stored in tables on the host mesh, the face contains indexes to those table denoting which values should be used in rendering.

Parameters

position_ids (List[int]) – Worldspace position ids on the host mesh for this face’s vertices.
normal_ids (List[int]) – Normal direction ids on the host mesh for this face’s vertices.
tex_ids (List[int]) – Texture coordinate ids on the host mesh for this face’s vertices.
active_material (str) – Material name used to render this face.

property material¶

Material name used to render this face.

Return type: str

property normal_ids¶

Normal direction ids on the host mesh for this face’s vertices.

Return type: List[int]

property position_ids¶

Worldspace position ids on the host mesh for this face’s vertices.

Return type: List[int]

property tex_ids¶

Texture coordinate ids on the host mesh for this face’s vertices.

Return type: List[int]

property vertex_count¶

The number of vertices on this face - will be either 3 for a triangle, or 4 for a quad

Return type: int

class anki_vector.opengl.opengl.MeshGroup(name)¶

A colletions of face polygons which can be rendered as a group by name.

Parameters: name (str) – The name associated with this part of the 3d mesh collection.

add_face_by_obj_data(source_values, active_material)¶

Adds a new face to the mesh group.

Face source data is made up of 3 or 4 vertices

e.g. f v1 v2 v3 or f v1 v2 v3 v4

where each vertex definition is multiple indexes seperated by slashes and can follow the following formats:

position_index position_index/tex_coord_index position_index/tex_coord_index/normal_index position_index//normal_index

Parameters

source_values (list) – obj data to parse for this face
active_material (str) – the material used to render this face

property faces¶

All faces associated with the mesh group.

Return type: List[MeshFace]

property name¶

The name associated with the mesh group.

Return type: str

class anki_vector.opengl.opengl.OpenGLWindow(x, y, width, height, window_name)¶

A Window displaying an OpenGL viewport.

Parameters

x (int) – The initial x coordinate of the window in pixels.
y (int) – The initial y coordinate of the window in pixels.
width (int) – The initial height of the window in pixels.
height (int) – The initial height of the window in pixels.
window_name (str) – The name / title for the window.

static display_rendered_content()¶: Swaps buffers once rendering is finished.

property height¶: The vertical height of the window:

initialize(display_function)¶: Initialze the OpenGL display parts of the Window.

Warning

Must be called on the same thread as OpenGL (usually the main thread),

prepare_for_rendering(projector, camera, lights)¶

Selects the window, clears buffers, and sets up the scene transform and lighting state.

Parameters

projector (Projector) – The projector configuration to use for this rendering pass.
camera (Camera) – The camera object to use for this rendering pass.
lights (List[Light]) – The light list to use for this rendering pass.

property width¶: The horizontal width of the window

class anki_vector.opengl.opengl.PrecomputedView¶

A collection of static 3D object which are pre-computed on the graphics card, so they can be quickly drawn when needed.

build_from_mesh_data(mesh_data)¶

Uses a loaded mesh to create 3d geometry to store in the view.

All groups in the mesh will pre-computed and stored by name.

Parameters: mesh_data (MeshData) – the source data that 3d geometry will be pre-computed from.

build_from_render_function(name, f, *args)¶

Uses an externally provided function to create 3d geometry to store in the view.

Parameters

name (str) – the key this pre-computed geometry can be draw from.
f (callable) – the function used to create the 3d geometry.
args – any parameters the supplied function is expecting.

display_all()¶: Renders all pre-computed geometry in the view collection.

display_by_key(key)¶

Renders a specific piece of geometry from the view collection.

Parameters: key (str) – The pre-computed object to render.

class anki_vector.opengl.opengl.ResourceManager(context_id)¶

Handles returning file resources by keys. The current implementation delegates to resource_stream directly.

Parameters: context_id (str) – Key used for identifying this context

property context_id¶

Key used for identifying this context.

Return type: str

load(*args)¶

Loads a resource given a groups of key arguments.

Since the resource_stream path is non_stantard with os.path.join, this resolve is encapsulated inside the resource manager. The context that these resources are files on disk is similarly encapsulated. All client classes only need match keys with returned data.

Parameters: args (str) – string keys for identifying the asset.