The pygfx reference

Resources

class pygfx.resources.Resource
class pygfx.resources.Buffer(data=None, *, nbytes=None, nitems=None, format=None)

A buffer object represents a piece of memory to the GPU, that can be used as index buffer, vertex buffer, uniform buffer, or storage buffer. You can provide (and update data for it), or use it as a placeholder for a buffer with no representation on the CPU.

Parameters
  • data (array, optional) – Array data of any type that supports the buffer-protocol, (e.g. a bytes or numpy array). If not given or None, nbytes and nitems must be provided. The data is copied if it’s float64 or not contiguous.

  • nbytes (int) – The number of bytes. If data is given, it is derived.

  • nitems (int) – The number of items. If data is given, it is derived.

  • format (str) – The format to use when used as a vertex buffer. By default this is automatically set from the data. This must be a pygfx format specifier, e.g. “3xf4”, but can also be a format specific to the render backend if necessary (e.g. from wgpu.VertexFormat).

property rev

An integer that is increased when update_range() is called.

property data

The data for this buffer. Can be None if the data only exists on the GPU.

Note: the data is the same reference that was given to instantiate this object, but this may change.

property mem

The data for this buffer as a memoryview. Can be None if the data only exists on the GPU.

property nbytes

The number of bytes in the buffer.

property nitems

The number of items in the buffer.

property format

The vertex format. Usually a pygfx format specifier (e.g. u2 for scalar uint16, or 3xf4 for 3xfloat32), but can also be a overriden to a backend-specific format.

property vertex_byte_range

The offset and size, in bytes, when used as a vertex buffer.

update_range(offset=0, size=1125899906842624)

Mark a certain range of the data for upload to the GPU. The offset and size are expressed in integer number of elements.

class pygfx.resources.Texture(data=None, *, dim, size=None, format=None)

A base texture wrapper that can be implemented for numpy, ctypes arrays, or any other kind of array.

Parameters
  • data (array, optional) – Array data of any type that supports the buffer-protocol, (e.g. a bytes or numpy array). If not given or None, nbytes and nitems must be provided. The data is copied if it’s float64 or not contiguous.

  • dim (int) – The dimensionality of the array (1, 2 or 3).

  • size (3-tuple) – The extent (width, height, depth) of the array. If not given or None, it is derived from dim and the shape of the data. By creating a 2D array with depth > 1, a view can be created with format ‘d2_array’ or ‘cube’.

  • format (str) – the format of texture. By default this is automatically set from the data. This must be a pygfx format specifier, e.g. “3xf4”, but can also be a format specific to the render backend if necessary (e.g. from wgpu.TextureFormat).

property rev

An integer that is increased when update_range() is called.

get_view(**kwargs)

Get a new view on the this texture.

property dim

The dimensionality of the texture (1, 2, or 3).

property data

The data for this texture. Can be None if the data only exists on the GPU.

Note: the data is the same reference that was given to instantiate this object, but this may change.

property mem

The data for this buffer as a memoryview. Can be None if the data only exists on the GPU.

property nbytes

Get the number of bytes in the texture.

property size

The size of the texture as (width, height, depth). (always a 3-tuple, regardless of the dimension).

property format

The texture format as a string. Usually a pygfx format specifier (e.g. u2 for scalar uint16, or 3xf4 for RGB float32), but can also be a overriden to a backend-specific format.

update_range(offset, size)

Mark a certain range of the data for upload to the GPU. The offset and (sub) size should be (width, height, depth) tuples. Numpy users beware that an arrays shape is (height, width)!

class pygfx.resources.TextureView(texture, *, address_mode='clamp', filter='nearest', format=None, view_dim=None, aspect=None, mip_range=None, layer_range=None)

A view on a texture.

The view defines the sampling behavior and can specify a selection/different view on the texture.

Passing no more than address_mode and filter will create a default view on the texture with the given sampling parameters.

Parameters
  • address_mode (str) – How to sample beyond the edges. Use “clamp”, “mirror” or “repeat”. Default “clamp”. Can also use e.g. “clamp,clamp,repeat” to specify for u, v and w.

  • filter (str) – Interpolation filter. Use “nearest” or “linear”. Default “nearest”. Can also use e.g. “linear,linear,nearest” to set mag, min and mipmap filters.

  • format (str) – Omit or pass None to use the texture’s format.

  • view_dim (str) – Omit or pass None to use the texture’s format. Or e.g. get a “2d” slice view from a 3d texture, or e.g. “cube” or “2d-array”.

  • aspect (str) – Omit or pass None to use the default.

  • mip_range (range) – A range object to specify what mip levels to view.

  • layer_range (range) – A range object to specify what array layers to view.

property texture

The Texture object holding the data for this texture view.

property format

The texture format.

property view_dim

“1d”, “2d” or “3d”.

Type

The dimensionality of this view

property address_mode

How to sample beyond the edges. Use “clamp”, “mirror” or “repeat”. Default “clamp”.

property filter

Interpolation filter. Use “nearest” or “linear”.

World objects

class pygfx.WorldObject(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

The base class for objects present in the “world”, i.e. the scene graph.

Each WorldObject has geometry to define it’s data, and material to define its appearance. The object itself is only responsible for defining object hierarchies (parent / children) and its position and orientation in the world.

This is considered a base class. Use Group to collect multiple world objects into a single empty world object.

property id

An integer id smaller than 2**31 (read-only).

property visible

Wheter is object is rendered or not. Default True.

property render_order

This value allows the default rendering order of scene graph objects to be controlled. Default 0. See Renderer.sort_objects for details.

property render_mask

Indicates in what render passes to render this object:

  • “auto”: try to determine the best approach (default).

  • “opaque”: only in the opaque render pass.

  • “transparent”: only in the transparent render pass(es).

  • “all”: render in both opaque and transparent render passses.

If “auto” (the default), the renderer attempts to determine whether all fragments will be either opaque or all transparent, and only apply the needed render passes. If this cannot be determined, it falls back to “all”.

Some objects may contain both transparent and opaque fragments, and should be rendered in all passes - the object’s contribution to each pass is determined on a per-fragment basis.

For clarity, rendering objects in all passes even though they are fully opaque/transparent yields correct results and is generally the “safest” option. The only cost is performance. Rendering transparent fragments in the opaque pass makes them invisible. Rendering opaque fragments in the transparent pass blends them as if they are transparent with an alpha of 1.

property geometry

The object’s geometry, the data that defines (the shape of) this object.

property material

Wheter is object is rendered or not. Default True.

property parent

Object’s parent in the scene graph (read-only). An object can have at most one parent.

property children

The child objects of this wold object (read-only tuple). Use .add() and .remove() to change this list.

add(*objects, before=None)

Adds object as child of this object. Any number of objects may be added. Any current parent on an object passed in here will be removed, since an object can have at most one parent. If before argument is given (and present in children), then the items are inserted before the given element.

remove(*objects)

Removes object as child of this object. Any number of objects may be removed. If a given object is not a child, it is ignored.

clear()

Removes all children.

traverse(callback, skip_invisible=False)

Executes the callback on this object and all descendants.

If skip_invisible is given and True, objects whose visible property is False - and their children - are skipped. Note that modifying the scene graph inside the callback is discouraged.

property matrix

The (settable) transformation matrix.

property matrix_world

The world matrix (local matrix composed with any parent matrices).

property matrix_auto_update

Whether or not the matrix auto-updates.

property matrix_world_dirty

Whether or not the matrix needs updating (readonly).

get_world_bounding_box()

Updates all parent and children world matrices, and returns a single world-space axis-aligned bounding box for this object’s geometry and all of its children (recursively).

get_world_bounding_sphere()

Returns a world-space bounding sphere by converting an axis-aligned bounding box to a sphere.

See WorldObject.get_world_bounding_box.

class pygfx.Group(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

A Group is almost identical to a WorldObject. Its purpose is to make working with groups of objects syntactically clearer.

class pygfx.Scene(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

The scene is a WorldObject that represents the root of a scene graph. It hold certain attributes that relate to the scene, such as the background color, fog, and environment map. Camera’s and lights can also be part of a scene.

Camera objects

class pygfx.Camera

Abstract base camera.

The purpose of a camera is to define the viewpoint for rendering a scene. This viewpoint consists of its position (in the world) and its projection.

In other words, it covers the projection of world coordinates to normalized device coordinates (NDC), by the (inverse of) the camera’s own world matrix and the camera’s projection transform. The former represent the camera’s position, the latter is specific to the type of camera.

Note that we follow the NDC coordinate system of WGPU, where x and y are in the range 0..1, z is in the range 0..1, and (-1, -1, 0) represents the bottom left corner.

show_object(target: WorldObject, view_dir=(- 1, - 1, - 1), distance_weight=2)

Utility function to position and rotate the camera to ensure a particular world object is in view.

Parameters
  • target – WorldObject The object to look at

  • view_dir – 3-tuple of float Look at the object in this direction

  • distance_weight – float The camera distance to the object’s world position is its bounding sphere radius multiplied by this weight

Returns

Vector3

The world coordinate the camera is looking at

Return type

pos

property flips_winding

Get whether the camera flips any dimensions causing the winding of faces to be flipped. Note that if an even number of dimensions are flipped, the winding is not affected.

class pygfx.NDCCamera

A Camera operating in NDC coordinates: its projection matrix is the identity transform (but its matrix_world can still be set).

In the NDC coordinate system of WGPU (and pygfx), x and y are in the range 0..1, z is in the range 0..1, and (-1, -1, 0) represents the bottom left corner.

class pygfx.ScreenCoordsCamera

A Camera operating in screen coordinates. The depth range is the same as in NDC (0 to 1).

class pygfx.OrthographicCamera(width=1, height=1, near=- 1000, far=1000)

An orthographic camera, useful for non-perspective views and visualizing 2D content. You may also want to set the position of the camera.

Parameters
  • width (float) – The (minimum) width of the view-cube. The actual view may be wider if the viewport is wide.

  • height (float) – The (minimum) height of the view-cube.

  • near (float) – The near clipping plane. Default -1000.

  • far (float) – The far clipping plane. Must be larger than near. Default +1000.

property flips_winding

Get whether the camera flips any dimensions causing the winding of faces to be flipped. Note that if an even number of dimensions are flipped, the winding is not affected.

class pygfx.PerspectiveCamera(fov=50, aspect=1, near=0.1, far=2000)

A 3D perspective camera.

Parameters
  • fov (float) – The field of view as an angle. Higher values give a wide-angle lens effect. The default is 50.

  • aspect (float) – The desired aspect ratio, which is used to determine the vision pyramid’s boundaries depending on the viewport size. Common values are 16/9 or 4/3. Default 1.

  • near (float) – The near clipping plane. Must be larger than zero. Default 0.1.

  • far (float) – The far clipping plane. Must be larger than near. Default 2000.

property flips_winding

Get whether the camera flips any dimensions causing the winding of faces to be flipped. Note that if an even number of dimensions are flipped, the winding is not affected.

Specific world objects

class pygfx.Background(geometry=None, material=None, **kwargs)

An object representing a scene background. Can be e.g. a gradient, a static image or a skybox.

class pygfx.Line(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

An object consisting of a line represented by a list of vertices (3D positions). Some materials will render the line as a continuous line, while other materials will consider each pair of points a segment.

The picking info of a Line (the result of renderer.get_pick_info()) will for most materials include vertex_index (int) and segment_coord (float, sub-segment coordinate).

class pygfx.Mesh(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

An object consisting of triangular faces, represented by vertices (3D positions) and an index that defines the connectivity.

The picking info of a Mesh (the result of renderer.get_pick_info()) will for most materials include instance_index (int), face_index (int), and face_coord (tuple of 3 floats). The latter are the barycentric coordinates for each vertex of the face (with values 0..1).

class pygfx.InstancedMesh(geometry, material, count, **kwargs)

An instanced mesh with a matrix for each instance.

set_matrix_at(index: int, matrix)

set the matrix for the instance at the given index.

class pygfx.Points(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

An object consisting of points represented by vertices (3D positions).

The picking info of a Points object (the result of renderer.get_pick_info()) will for most materials include vertex_index (int) and point_coord (tuple of 2 float coordinates in logical pixels).

class pygfx.Image(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

An object representing a 2D image in space.

The geometry for this object consists only of geometry.grid: a texture with the 2D data.

The picking info of an Image (the result of renderer.get_pick_info()) will for most materials include index (tuple of 2 int), and pixel_coord (tuple of float subpixel coordinates).

class pygfx.Volume(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto')

An object representing a 3D image in space (a volume).

The geometry for this object consists only of geometry.grid: a texture with the 3D data.

The picking info of a Volume (the result of renderer.get_pick_info()) will for most materials include index (tuple of 3 int), and voxel_coord (tuple of float subpixel coordinates).

Helper objects

class pygfx.AxesHelper(size=1.0, thickness=2)

An object indicating the axes directions.

Parameters
  • size (float) – The length of the lines (default 1).

  • thickness (float) – The thickness of the lines (default 2 px).

class pygfx.BoxHelper(size=1.0, thickness=1)

A line box object. Commonly used to visualize bounding boxes.

Parameters
  • size (float) – The length of the box’ edges (default 1).

  • thickness (float) – the thickness of the lines (default 1 px).

__init__(size=1.0, thickness=1)
set_transform_by_aabb(aabb)

Set the position and scale attributes based on a given bounding box.

Parameters

aabb (ndarray) – The position and scale attributes will be configured such that the helper will match the given bounding box. The array is expected to have shape (2, 3), where the two vectors represent the minimum and maximum coordinates of the axis-aligned bounding box.

set_transform_by_object(object, space='world')

Set the position and scale attributes based on the bounding box of another object.

Parameters
  • object (WorldObject) – The position and scale attributes will be configured such that the helper will match the bounding box of the given object.

  • space (string, optional) – If set to “world” (the default) the world space bounding box will be used as reference. If equal to “local”, the object’s local space bounding box of its geometry will be used instead.

Examples

World-space bounding box visualization:

box = gfx.BoxHelper()
box.set_transform_by_object(mesh)
scene.add(box)

Local-space bounding box visualization:

box = gfx.BoxHelper()
box.set_transform_by_object(mesh, space="local")
mesh.add(box)
class pygfx.GridHelper(size=10.0, divisions=10, color1=(0.35, 0.35, 0.35, 1), color2=(0.1, 0.1, 0.1, 1), thickness=1)

An object indicating the z=0 plane.

class pygfx.TransformGizmo(object=None, screen_size=100)

A gizmo object that can be used to manipulate (i.e. transform) a world object.

Aguments:

object (WorldObject): the object to transform with the gizmo. screen_size (float): the approximate size of the widget in logical pixels. Default 100.

To control the Gizmo: * Click the center sphere to toggle between object-space, world-space and screen-space. * Grab the center sphere for uniform scaling. * Grab the cubes for one-directional scaling (only in object-space). * Grab the arrows to translate in one direction. * Grab the planes to translate in two directions. * Grab the spheres to rotate.

set_object(object)

Set the WorldObject to control with the gizmo.

toggle_mode(mode=None)

Toggle between modes. If the mode is omitted, will move to the next mode. Must be one of “object”, “world”, or “screen”.

update_matrix_world(*args, **kwargs)

We overload this method, which gets called by the renderer just before rendering. This allows us to prep the gizmo just in time.

process_event(event)

The event handler.

Geometries

class pygfx.geometries.Geometry(**kwargs)

A Geomerty object is a container for geometry data of a WorldObject.

A geometry object contains the data that defines (the shape of) the object, such as positions, plus data associated with these positions (normals, texcoords, colors, etc.).

Its attributes are Buffer and Texture(View) objects. The data can be provided as keyword arguments, which are converted to numpy arrays and wrapped in a Buffer if necessary.

The names for these attributes are standardized so that the renderers know what to expect. Each material requires certain attributes to be present, and may support optional attributes. Optional attributes must always be “turned on” on the material; their presence on the geometry does not mean that they’re used.

The standardized names are:

  • indices: An index into per-vertex data. Typically Nx3 for mesh geometry.

  • positions: Nx3 positions (xyz), defining the location of e.g. vertices or points.

  • normals: Nx3 normal vectors. These may or may not be unit.

  • texcoords: Texture coordinates used to lookup the color for a vertex. Can be Nx1, Nx2 or Nx3, corresponding to a 1D, 2D and 3D texture map.

  • colors: Per-vertex colors. Must be NxM, with M 1-4 for gray, gray+alpha, rgb, rgba, respectively.

  • sizes: Scalar size per-vertex.

  • grid: A 2D or 3D Texture/TextureView that contains a regular grid of data. I.e. for images and volumes.

Example

g = Geometry(positions=[[1, 2], [2, 4], [3, 5], [4, 1]])
g.positions.data  # numpy array
bounding_box()

Compute the axis-aligned bounding box based on either positions or the shape of the grid buffer.

If both are present, the bounding box will be computed based on the positions buffer.

bounding_sphere()

Compute the bounding sphere based on the axis-aligned bounding box.

Note: not the optimal fit.

pygfx.geometries.box_geometry(width=1, height=1, depth=1, width_segments=1, height_segments=1, depth_segments=1)

Create geometry respresenting a box.

The box has its center at the origin. The normals for each side all point in the same direction; the corners are actually square. Texture coordinates for each side run from 0 to 1.

Parameters
  • width (int) – The size in the x-dimension, default 1.

  • height (int) – The size in the y-dimension, default 1.

  • depth (int) – The size in the z-dimension, default 1.

  • width_segments (int) – The number of segments to use in x.

  • height_segments (int) – The number of segments to use in y.

  • depth_segments (int) – The number of segments to use in z.

pygfx.geometries.cone_geometry(radius=1.0, height=1.0, radial_segments=8, height_segments=1, theta_start=0.0, theta_length=6.283185307179586, open_ended=False)

Create geometry representing a cone.

pygfx.geometries.cylinder_geometry(radius_bottom=1.0, radius_top=1.0, height=1.0, radial_segments=8, height_segments=1, theta_start=0.0, theta_length=6.283185307179586, open_ended=False)

Create geometry representing a cylinder.

pygfx.geometries.dodecahedron_geometry(radius=1.0, subdivisions=0)

Create geometry representing a dodecahedron, centered around the origin.

The vertices lie on the surface of a sphere of the given radius. The faces are optionally subdivided if subdivisions>0.

Parameters
  • radius (float) – The vertices lie on the surface of a sphere with this radius.

  • subdivisions (int) – The amount of times the faces will be subdivided, where 0 (the default) means no subdivision.

pygfx.geometries.icosahedron_geometry(radius=1.0, subdivisions=0)

Create geometry representing a icosahedron, centered around the origin.

The vertices lie on the surface of a sphere of the given radius. The faces are optionally subdivided if subdivisions>0.

Parameters
  • radius (float) – The vertices lie on the surface of a sphere with this radius.

  • subdivisions (int) – The amount of times the faces will be subdivided, where 0 (the default) means no subdivision.

pygfx.geometries.klein_bottle_geometry(scale=1.0)

The Klein bottle is a surface for which the inside and outside are the same, similar to a Möbius strip. In fact, a Klein bottle can be constructed by glueing together two Möbius strips.

More technically: the Klein bottle is an example of a non-orientable surface; it is a two-dimensional manifold against which a system for determining a normal vector cannot be consistently defined.

pygfx.geometries.octahedron_geometry(radius=1.0, subdivisions=0)

Create geometry representing a octahedron, centered around the origin.

The vertices lie on the surface of a sphere of the given radius. The faces are optionally subdivided if subdivisions>0.

Parameters
  • radius (float) – The vertices lie on the surface of a sphere with this radius.

  • subdivisions (int) – The amount of times the faces will be subdivided, where 0 (the default) means no subdivision.

pygfx.geometries.plane_geometry(width=1, height=1, width_segments=1, height_segments=1)

Create a geometry that represents a 2D plane in a 3D world.

pygfx.geometries.sphere_geometry(radius=1, width_segments=32, height_segments=16, phi_start=0, phi_length=6.283185307179586, theta_start=0, theta_length=3.141592653589793)

Create geometry representing a sphere.

pygfx.geometries.tetrahedron_geometry(radius=1.0, subdivisions=0)

Create geometry representing a tetrahedron, centered around the origin.

The vertices lie on the surface of a sphere of the given radius. The faces are optionally subdivided if subdivisions>0.

Parameters
  • radius (int) – The vertices lie on the surface of a sphere with this radius.

  • subdivisions (int) – The amount of times the tetrahedron faces will be subdivided, where 0 (the default) means no subdivision.

pygfx.geometries.torus_knot_geometry(scale=1.0, tube=0.4, tubular_segments=64, radial_segments=8, p=2, q=3)

Create geometry representing a torus knot, the particular shape of which is defined by a pair of coprime integers, p and q. If p and q are not coprime, the result will be a torus link.

Parameters
  • scale (float) – the scale of the torus, default 1.

  • tube (float) – the radius of the tube. Default 0.4.

  • tubular_segments (int) – default is 64.

  • radial_segments (int) – default is 8.

  • p (int) – how many times the geometry winds around its axis of rotational symmetry. Default 2.

  • q (int) – how many times the geometry winds around a circle in the interior of the torus. Default 3.

pygfx.geometries.trimesh_geometry(mesh)

Create geometry from a trimesh Mesh.

Materials

class pygfx.materials.Material(*, opacity=1, clipping_planes=None, clipping_mode='any')

The base class for all materials. Materials define how an object is rendered, subject to certain properties.

property opacity

The opacity (a.k.a. alpha value) applied to this material, expressed as a value between 0 and 1. If the material contains any non-opaque fragments, their alphas are simply scaled by this value.

property is_transparent

Whether this material is (semi) transparent because of its opacity value. If False the object can still appear transparent because of its color.

property clipping_planes

A tuple of planes (abcd tuples) in world space. Points in space whose signed distance to the plane is negative are clipped (not rendered). Applies to the object to which this material is attached.

property clipping_mode

“ANY” or “ALL”. If this is “ANY” (the default) a fragment is discarded if it is clipped by any clipping plane. If this is “ALL”, a fragment is discarded only if it is clipped by all of the clipping planes.

Type

Set the behavior for multiple clipping planes

class pygfx.materials.BackgroundImageMaterial(map=None, **kwargs)

A background material that displays an image. If map is a 2D texture view, it is used as a static background. If it is a cube texture view, (on a NxMx6 texture) it is used as a skybox. Use the Background object’s transform to orient the image.

property map

The texture map specifying the background image

class pygfx.materials.BackgroundMaterial(*colors, **kwargs)

A background material that draws the background is a uniform color or in a gradient. The positional arguments are passed to set_colors().

set_colors(*colors)

Set the background colors. If one color is given, it will be used as a uniform color. If two colors are given, it will be used for the botton and top. If four colors are given, it will be used for the four corners.

property color_bottom_left

The color in the bottom left corner.

property color_bottom_right

The color in the bottom right corner.

property color_top_left

The color in the top left corner.

property color_top_right

The color in the top right corner.

class pygfx.materials.GaussianPointsMaterial(color=(1, 1, 1, 1), size=1, vertex_colors=False, vertex_sizes=False, map=None, **kwargs)

A material for points, renders Gaussian blobs with a standard deviation of 1/6 of the size.

class pygfx.materials.ImageBasicMaterial(clim=None, map=None, **kwargs)
property map

The colormap to turn the image values into its final color. If not given or None, the values themselves represents the color. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of channels in the image.

property clim

The contrast limits to scale the data values with. Default (0, 1).

class pygfx.materials.LineArrowMaterial(color=(1, 1, 1, 1), thickness=2.0, vertex_colors=False, map=None, aa=True, **kwargs)

A material that renders line segments that look like little vectors.

class pygfx.materials.LineMaterial(color=(1, 1, 1, 1), thickness=2.0, vertex_colors=False, map=None, aa=True, **kwargs)

The default material to draw lines.

property color

The uniform color of the line.

property color_is_transparent

Whether the color is (semi) transparent (i.e. not fully opaque).

property aa

Whether or not the line should be anti-aliased. Aliasing gives prettier results, but may affect performance for very large datasets. Default True.

property vertex_colors

Whether to use the vertex colors provided in the geometry.

property thickness

The line thickness expressed in logical pixels.

property map

The texture map specifying the color for each texture coordinate. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of columns in the geometry’s texcoords.

class pygfx.materials.LineSegmentMaterial(color=(1, 1, 1, 1), thickness=2.0, vertex_colors=False, map=None, aa=True, **kwargs)

A material that renders line segments between each two subsequent points.

class pygfx.materials.LineThinMaterial(color=(1, 1, 1, 1), thickness=2.0, vertex_colors=False, map=None, aa=True, **kwargs)

A simple line, drawn with line_strip primitives that has a thickness of one physical pixel (the thickness property is ignored).

class pygfx.materials.LineThinSegmentMaterial(color=(1, 1, 1, 1), thickness=2.0, vertex_colors=False, map=None, aa=True, **kwargs)

Simple line segments, drawn with line primitives that has a thickness of one physical pixel (the thickness property is ignored).

class pygfx.materials.MeshBasicMaterial(color=(1, 1, 1, 1), vertex_colors=False, map=None, wireframe=False, wireframe_thickness=1, side='BOTH', **kwargs)

A material for drawing geometries in a simple shaded (flat or wireframe) way. This material is not affected by lights.

property color

The uniform color of the mesh, as an rgba tuple. This value is ignored if a texture map is used.

property color_is_transparent

Whether the color is (semi) transparent (i.e. not fully opaque).

property vertex_colors

Whether to use the vertex colors provided in the geometry.

property map

The texture map specifying the color for each texture coordinate. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of columns in the geometry’s texcoords.

property side

“FRONT”, “BACK”, or “BOTH”. By default this is “BOTH”. Setting to “FRONT” or “BACK” will only render faces from that side, hiding the other. A feature also known as culling.

Which side of the mesh is the front is determined by the winding of the faces. Counter-clockwise (CCW) winding is assumed. If this is not the case, adjust your geometry (using e.g. np.fliplr() on geometry.indices).

Type

Defines which side of faces will be rendered

property wireframe

Render geometry as a wireframe. Default is False (i.e. render as polygons).

property wireframe_thickness

The thickness of the lines when rendering as a wireframe.

class pygfx.materials.MeshFlatMaterial(shininess=30, emissive=(0, 0, 0, 0), **kwargs)

A material that applies lighting per-face (non-interpolated). This gives a “pixelated” look, but can also be usefull if one wants to show the (size of) the triangle faces. The shading and reflectance model is the same as for MeshPhongMaterial.

class pygfx.materials.MeshNormalLinesMaterial(color=(1, 1, 1, 1), vertex_colors=False, map=None, wireframe=False, wireframe_thickness=1, side='BOTH', **kwargs)

A material that shows surface normals as lines sticking out of the mesh.

class pygfx.materials.MeshNormalMaterial(color=(1, 1, 1, 1), vertex_colors=False, map=None, wireframe=False, wireframe_thickness=1, side='BOTH', **kwargs)

A material that maps the normal vectors to RGB colors.

class pygfx.materials.MeshPhongMaterial(shininess=30, emissive=(0, 0, 0, 0), **kwargs)

A material affected by light, diffuse and with specular highlights. This material uses the Blinn-Phong reflectance model. If the specular color is turned off, Lambertian shading is obtained.

property emissive

The emissive (light) color of the mesh, as an rgba tuple. This color is added to the final color and is unaffected by lighting. The alpha channel of this color is ignored.

property shininess

How shiny the specular highlight is; a higher value gives a sharper highlight. Default is 30.

class pygfx.materials.MeshSliceMaterial(plane=(0, 0, 1, 0), thickness=2.0, **kwargs)

A material that displays a slice of the mesh.

property plane

The plane to slice at, represented with 4 floats (a, b, c, d), which make up the equation: ax + by + cz + d = 0 The plane definition applies to the world space (of the scene).

property thickness

The thickness of the line to draw the edge of the mesh.

class pygfx.materials.PointsMaterial(color=(1, 1, 1, 1), size=1, vertex_colors=False, vertex_sizes=False, map=None, **kwargs)

The default material used by Points. Renders (antialiased) disks of the given size and color.

property color

The color of the points (if map is not set).

property color_is_transparent

Whether the color is (semi) transparent (i.e. not fully opaque).

property vertex_colors

Whether to use the vertex colors provided in the geometry.

property size

The size (diameter) of the points, in logical pixels.

property vertex_sizes

Whether to use the vertex sizes provided in the geometry.

property map

The texture map specifying the color for each texture coordinate. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of columns in the geometry’s texcoords.

class pygfx.materials.VolumeBasicMaterial(clim=None, map=None, **kwargs)

Base volume material.

property map

The colormap to turn the volume values into its final color. If not given or None, the values themselves represents the color. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of channels in the volume.

property clim

The contrast limits to scale the data values with. Default (0, 1).

class pygfx.materials.VolumeMipMaterial(clim=None, map=None, **kwargs)

A material rendering a volume using MIP rendering.

class pygfx.materials.VolumeRayMaterial(clim=None, map=None, **kwargs)

A material for rendering volumes using raycasting.

class pygfx.materials.VolumeSliceMaterial(plane=(0, 0, 1, 0), **kwargs)

A material for rendering a slice through a 3D texture at the surface of a mesh. This material is not affected by lights.

property plane

The plane to slice at, represented with 4 floats (a, b, c, d), which make up the equation: ax + by + cz + d = 0 The plane definition applies to the world space (of the scene).

Controllers

Controllers define how cameras can be interacted with. They are independent of any GUI toolkits.

class pygfx.controllers.Controller

Base camera controller.

update_camera(camera: Camera) Controller

Update the transform of the camera with the internal transform.

add_default_event_handlers(viewport: Union[Viewport, Renderer], camera: Camera)

Apply the default interaction mechanism to a wgpu autogui canvas. Needs either a viewport or renderer, pus the camera.

class pygfx.controllers.PanZoomController(eye: Optional[Vector3] = None, target: Optional[Vector3] = None, up: Optional[Vector3] = None, zoom: float = 1.0, min_zoom: float = 0.0001)

A class implementing two-dimensional pan-zoom camera controller.

pan(vec3: Vector3) Controller

Pan in 3D world coordinates.

pan_move(pos: Tuple[float, float]) Controller

Pan the camera, based on a (2D) screen location. Call pan_start first.

handle_event(event, viewport, camera)

Implements a default interaction mode that consumes wgpu autogui events (compatible with the jupyter_rfb event specification).

class pygfx.controllers.OrbitController(eye: Optional[Vector3] = None, target: Optional[Vector3] = None, up: Optional[Vector3] = None, *, zoom_changes_distance=True, min_zoom: float = 0.0001)

A class implementing an orbit camera controller, where the camera is rotated around a center position (orbiting around it).

pan(vec3: Vector3) Controller

Pan in 3D world coordinates.

pan_start(pos: Tuple[float, float], viewport: Viewport, camera: Camera) Controller

Start a panning operation based (2D) screen coordinates.

pan_move(pos: Tuple[float, float]) Controller

Pan the center of rotation, based on a (2D) screen location. Call pan_start first.

rotate(theta: float, phi: float) Controller

Rotate using angles (in radians). theta and phi are also known as azimuth and elevation.

rotate_start(pos: Tuple[float, float], viewport: Viewport, camera: Camera) Controller

Start a rotation operation based (2D) screen coordinates.

rotate_move(pos: Tuple[float, float], speed: float = 0.0175) Controller

Rotate, based on a (2D) screen location. Call rotate_start first. The speed is 1 degree per pixel by default.

handle_event(event, viewport, camera)

Implements a default interaction mode that consumes wgpu autogui events (compatible with the jupyter_rfb event specification).

class pygfx.controllers.OrbitOrthoController(eye: Optional[Vector3] = None, target: Optional[Vector3] = None, up: Optional[Vector3] = None, *, min_zoom: float = 0.0001)

An orbit controller for orthographic camera’s (zooming is done by projection, instead of changing the distance.