filly

filly is a Python 3D renderer for glTF scenes, built on Google Filament.

Filly can load a glTF model, light it, pose it, and render it. You get the result as a NumPy image, or filly draws it into an OpenGL texture that your own window shows. Your program keeps control of the window and of frame timing, so filly fits into applications that already own a display loop, such as PsychoPy experiments or pyglet, moderngl, and zengl programs.

"Wooden Playground Horse" by Batuhan13, CC BY 4.0. See attribution.

Install

filly is not on PyPI yet. Build it from source.

It needs Python 3.10 or later, Windows or Linux on x86_64, and an OpenGL 4.1 driver. On Linux, offscreen rendering works without a display. macOS is not supported at this time.

Render an image

import filly
from PIL import Image  # only to save the image

with filly.Renderer() as renderer:
    scene = renderer.create_scene()
    horse = scene.load("examples/assets/wooden_playground_horse.glb")
    horse.apply_animation(0, 1.25) # a pose from its spring animation

    camera = scene.create_camera()
    camera.set_perspective(fov_y=30, near=0.1, far=100)
    camera.frame(horse, direction=(-1, -0.3, -1), aspect=800 / 600)
    scene.camera = camera
    scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)

    target = renderer.create_render_target(width=800, height=600)
    renderer.render(scene, target)
    Image.fromarray(target.read()).save("horse.png") # (600, 800, 4) uint8 RGBA

Draw in a PsychoPy window

filly renders into a texture that PsychoPy draws directly, with no copy through the CPU.

from psychopy import core, visual
from filly.integrations.psychopy import SharedTarget, create_renderer

win = visual.Window((1024, 768), units="pix")
renderer = create_renderer(win) # shares the window's OpenGL context
scene = renderer.create_scene()
horse = scene.load("examples/assets/wooden_playground_horse.glb")
camera = scene.create_camera()
camera.set_perspective(fov_y=30, near=0.1, far=100)
camera.frame(horse, aspect=1)
scene.camera = camera
scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)

target = SharedTarget(renderer, win, 512, 512)
stim = target.as_psychopy_texture() # an ImageStim
clock = core.Clock()
while clock.getTime() < 3:
    horse.apply_animation(0, clock.getTime())
    renderer.render(scene, target)
    stim.draw()
    win.flip()

target.close()
renderer.close()
win.close()

Close the target, then the renderer, then the window. The same pattern works with a pyglet, moderngl, or zengl window.

Features

• glTF 2.0: GLB and glTF files, skinning, morph targets, animation, material variants, and the common material extensions, such as clearcoat, sheen, transmission, and iridescence. See asset compatibility.
• Cameras and lights: perspective and orthographic cameras, camera framing, and directional, sun, point, and spot lights with optional shadows. Image-based lighting comes from an HDR panorama or prefiltered KTX files.
• Stimuli from arrays: textures and meshes from NumPy arrays, updated in place each frame, for gratings, noise, or deforming shapes.
• Predictable output: sRGB (default) or linear. Effects such as antialiasing, fog, and bloom are off until you enable them. With default settings, the same scene gives the same pixels on every frame.
• Several views per frame: each render() call can take its own camera and viewport, for example for side-by-side stereo.
• Browsers: the same core compiles to WebAssembly for WebGL2. It renders into a texture that the page's own renderer draws, such as PIXI in PsychoJS. See the web build.

Examples

See the examples/ folder.

Documentation

• Tutorial: render an image
• How-to guides: build and test, use PsychoPy, use other OpenGL hosts, measure timing, profile a frame, compare with Filament's viewer, use filly in a web page
• Reference: API, performance, validation, sample assets
• Explanation: design and limits, tested assumptions, material precompilation, the web build

License

filly is released under the MIT License.

It links Filament (Apache 2.0), meshoptimizer (MIT), libwebp (BSD), and cgltf (MIT). Their licenses are installed with the package. The sample model filly.samples.SUZANNE is modified from Suzanne by Norbert Nopper (UX3D), from the Khronos glTF Sample Assets, under CC0 1.0.