API Reference

Sub-Packages

Internally, pygfx is structured into several sub-packages that provide the functionality exposed in the top-level namespace. At times, you may wish to search the docs of these sub-packages for additional information. In that case, you can read more about them here:

pygfx.cameras

Objects to view a scene.

pygfx.controllers

Objects to control cameras.

pygfx.geometries

Containers for geometry data.

pygfx.helpers

Helpers for visual debugging of scenes.

pygfx.materials

Containers for Material data.

pygfx.objects

World Objects and Events.

pygfx.renderers

The purpose of a renderer is to render (i.e. draw) a scene to a canvas or texture.

pygfx.resources

Containers for buffers and textures.

pygfx.utils

Utility functions for pygfx.

Public API

The primary way of accessing pygfx is by using the members of its top-level namespace. Currently this includes the following classes, which comprise the public API:

Camera()

Abstract base camera.

NDCCamera()

A Camera operating in NDC coordinates.

ScreenCoordsCamera()

A Camera operating in screen coordinates.

PerspectiveCamera([fov, aspect, width, ...])

A generic 3D camera with a configurable field of view (fov).

OrthographicCamera([width, height, zoom, ...])

An orthographic camera, useful for orthograpic views and 2D content.

Controller([camera, enabled, damping, ...])

The base camera controller.

PanZoomController([camera, enabled, ...])

A controller to pan and zoom a camera in a 2D plane parallel to the screen.

OrbitController([camera, enabled, damping, ...])

A controller to move a camera in an orbit around a center position.

TrackballController([camera, enabled, ...])

A controller to freely rotate a camera around a center position.

FlyController(camera, *[, speed])

A controller to fly around a scene as if it's a flight simulator.

box_geometry([width, height, depth, ...])

Generate a box (rectangular cuboid).

cylinder_geometry([radius_bottom, ...])

Generate a cylinder or a cylinder segment.

cone_geometry([radius, height, ...])

Generate a cone or a cone segment.

sphere_geometry([radius, width_segments, ...])

Generate a sphere.

plane_geometry([width, height, ...])

Generate a plane.

Geometry(**kwargs)

Generic container for Geometry data.

TextGeometry([text, markdown, screen_space, ...])

Geometry specific for representing text.

TextItem(text[, font_props, ws_before, ...])

A formatted piece of text.

geometry_from_trimesh(mesh)

Convert a Trimesh geometry object to pygfx geometry.

octahedron_geometry([radius, subdivisions])

Generate a octahedron.

icosahedron_geometry([radius, subdivisions])

Generate a icosahedron.

dodecahedron_geometry([radius, subdivisions])

Generate a dodecahedron.

tetrahedron_geometry([radius, subdivisions])

Generate a tetrahedron.

torus_knot_geometry([scale, tube, ...])

Generate a torus knot.

klein_bottle_geometry([scale, stitch])

Generate a Klein bottle.

AxesHelper([size, thickness])

A WorldObject to indicate the scene's axes.

GridHelper([size, divisions, color1, ...])

A WorldObject that shows a grid-shaped wireframe.

BoxHelper([size, thickness, color])

A WorldObject that shows a box-shaped wireframe.

TransformGizmo([object, screen_size])

Gizmo to manipulate a WorldObject.

PointLightHelper([size, geometry, color])

Light source indicator for point lights.

DirectionalLightHelper([ray_length, color, ...])

Light source indicator for directional lights.

SpotLightHelper([color])

Light source indicator for spot lights.

Material(*[, opacity, clipping_planes, ...])

Material base class.

material_from_trimesh(x)

Convert a Trimesh object into a pygfx material.

MeshAbstractMaterial([color, color_mode, ...])

Abstract mesh material.

MeshBasicMaterial([env_map, wireframe, ...])

Basic mesh material.

MeshPhongMaterial([shininess, emissive, ...])

Phong mesh material.

MeshNormalMaterial([color, color_mode, map, ...])

Color from Mesh normals.

MeshNormalLinesMaterial([line_length])

Render surface normals as lines.

MeshSliceMaterial([plane, thickness])

Display a mesh slice.

MeshStandardMaterial([emissive, metalness, ...])

PBR shaded material.

PointsMaterial([size, size_space, ...])

Point default material.

PointsGaussianBlobMaterial([size, ...])

A material to render points as Gaussian blobs.

LineMaterial([thickness, thickness_space, ...])

Basic line material.

LineThinMaterial([thickness, ...])

Thin line material.

LineThinSegmentMaterial([thickness, ...])

Thin line segment material.

LineSegmentMaterial([thickness, ...])

Line segment material.

LineArrowMaterial([thickness, ...])

Arrow (vector) line material.

ImageBasicMaterial([clim, map, ...])

Rasterized image material.

VolumeBasicMaterial([clim, map, ...])

Basic volume material.

VolumeSliceMaterial([plane])

A material for rendering a slice through a 3D texture at the surface of a mesh.

VolumeRayMaterial([clim, map, ...])

A material for rendering volumes using raycasting.

VolumeMipMaterial([clim, map, ...])

A material rendering a volume using MIP rendering.

BackgroundMaterial(*colors, **kwargs)

Solid/Gradient background color.

BackgroundImageMaterial([map])

Image/Skybox background.

BackgroundSkyboxMaterial([map])

Skybox background.

TextMaterial([color, outline_color, ...])

Basic text material.

WorldObject([geometry, material, visible, ...])

Base class for objects.

Group(*[, visible])

A group of objects.

Scene()

Root of the scene graph.

Background([geometry, material, render_mask])

The scene's background.

Points([geometry, material, visible, ...])

A point cloud.

Line([geometry, material, visible, ...])

An object representing a line using a list of vertices (3D positions).

Mesh([geometry, material, visible, ...])

A mesh.

Image([geometry, material, visible, ...])

A 2D image.

Volume([geometry, material, visible, ...])

A 3D image.

Text([geometry, material, visible, ...])

A text.

InstancedMesh(geometry, material, count, ...)

Display a mesh multiple times using instances.

Light([color, intensity, cast_shadow])

Light Base Class.

PointLight([color, intensity, cast_shadow, ...])

Radial point light source.

DirectionalLight([color, intensity, ...])

Directional light source.

AmbientLight([color, intensity])

Ambient light source.

SpotLight([color, intensity, cast_shadow, ...])

Directional point light source.

LightShadow(camera)

Shadow map utility base class.

DirectionalLightShadow()

Shadow map utility for directional lights.

SpotLightShadow()

Shadow map utility for spot light sources.

PointLightShadow()

Shadow map utility for point light sources.

Renderer()

Base (abstract) renderer class that all renderers inherit from.

WgpuRenderer(target, *args[, pixel_ratio, ...])

Turns Scenes into rasterized images using wgpu.

SvgRenderer(width, height, filename)

Turns scenes into SVG images.

Resource()

Base class for Buffer and Texture.

Buffer([data, nbytes, nitems, format, usage])

A contiguous piece of GPU memory.

Texture([data, size, format, colorspace, ...])

Texture object containing structured 1D, 2D or 3D data.

Color(*args)

A representation of color (in the sRGB colorspace).

load_gltf(path)

Load a gltf file and return the content.

load_gltf_mesh(path[, materials])

Load meshes from a gltf file, without skeletons, and no transformations applied.

print_tree(obj[, show_pos, show_rot, show_scale])

Print the tree structure of the scene, including the optional position, rotation, and scale of each object.

load_mesh(path[, remote_ok])

Load mesh(es) from a file.

load_meshes(path[, remote_ok])

Load meshes from a file.

load_scene(path[, flatten, meshes, ...])

Load file into a scene.

show(object[, up, canvas, renderer, ...])

Display a WorldObject

Display([canvas, renderer, controller, ...])

A Helper to display an object or scene

Viewport(renderer[, rect])

A rectangular area on a renderer.

font_manager

Storage and discovery of text glyphs.

cm

Predefined Colormaps.

logger

Instances of the Logger class represent a single logging channel.