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.

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.
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.
material_library

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

Return type:MaterialLibrary
normals

All directional vertex normals in this mesh.

Return type:List[List[float]]
tex_coords

All texture coordinates in this mesh.

Return type:List[List[float]]
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.
material

Material name used to render this face.

Return type:str
normal_ids

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

Return type:List[int]
position_ids

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

Return type:List[int]
tex_ids

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

Return type:List[int]
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
faces

All faces associated with the mesh group.

Return type:List[MeshFace]
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.

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.
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 (<built-in function 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
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.