filly 0.1.0__tar.gz

filly-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,135 @@
+name: Build wheels
+
+# Every run builds and tests the wheels and the sdist. A pushed tag vX.Y.Z whose version matches
+# pyproject.toml also publishes them to PyPI. A manual run can publish to TestPyPI instead, to
+# rehearse a release. Publishing uses PyPI trusted publishing: no token is stored here.
+on:
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: Publish the build to TestPyPI
+        type: boolean
+        default: false
+  pull_request:
+  push:
+    branches: [main, master]
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: wheels-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  wheels:
+    name: ${{ matrix.os }} wheels
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-2022]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Cache Linux SDK
+        if: runner.os == 'Linux'
+        uses: actions/cache@v4
+        with:
+          path: .deps/filament-linux
+          key: filament-linux-x86_64-manylinux228-${{ hashFiles('tools/build_filament_linux.py', 'tools/ci_linux.sh') }}
+      - name: Cache Windows SDK
+        if: runner.os == 'Windows'
+        uses: actions/cache@v4
+        with:
+          path: .deps
+          key: filament-windows-x86_64-${{ hashFiles('tools/fetch_filament.py') }}
+      - name: Build, repair, audit, and test wheels
+        uses: pypa/cibuildwheel@v4.2.1
+        env:
+          CIBW_BUILD: 'cp310-* cp311-* cp312-* cp313-* cp314-*'
+          CIBW_SKIP: '*-musllinux* *-win32 *-win_arm64'
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_WINDOWS: AMD64
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL_LINUX: bash {package}/tools/ci_linux.sh
+          CIBW_BEFORE_ALL_WINDOWS: python {package}/tools/fetch_filament.py
+          CIBW_ENVIRONMENT_LINUX: 'CC=clang CXX=clang++ CMAKE_ARGS="-DFILAMENT_ROOT=/project/.deps/filament-linux" LIBGL_ALWAYS_SOFTWARE=1'
+          CIBW_TEST_REQUIRES: 'pytest pillow pyglet==1.4.11'
+          CIBW_TEST_COMMAND_LINUX: 'timeout 600 xvfb-run -a python -m pytest {project}/tests -q -m "not psychopy" -o faulthandler_timeout=60'
+          # Hosted Windows runners do not supply a reliable OpenGL rendering device.
+          CIBW_TEST_COMMAND_WINDOWS: 'python -m pytest {project}/tests/test_stress.py {project}/tests/test_native_imports.py -q'
+      - name: Check extension imports
+        shell: bash
+        run: python tools/check_native_imports.py wheelhouse/*.whl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check that the tag matches the version
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: python
+        run: |
+          import os, tomllib
+          with open("pyproject.toml", "rb") as file:
+              version = tomllib.load(file)["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          if tag != f"v{version}":
+              raise SystemExit(f"Tag {tag} does not match version {version} in pyproject.toml")
+      - name: Build the sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: [wheels, sdist]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/filly
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [wheels, sdist]
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    runs-on: ubuntu-24.04
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/filly
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

filly-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.deps/
+build/
+dist/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+*.pyd
+*.so
+tests/web/node_modules/

filly-0.1.0/CMakeLists.txt

@@ -0,0 +1,95 @@
+cmake_minimum_required(VERSION 3.28...3.31)
+project(filly VERSION 0.1.0 LANGUAGES CXX)
+
+find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module OPTIONAL_COMPONENTS Development.SABIModule)
+find_package(nanobind CONFIG REQUIRED)
+
+set(FILAMENT_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/.deps" CACHE PATH "Filament 1.77.1 SDK directory")
+if(NOT EXISTS "${FILAMENT_ROOT}/include/filament/Engine.h")
+  message(FATAL_ERROR "Filament SDK missing. See docs/how-to/build.md for the platform SDK and FILAMENT_ROOT.")
+endif()
+
+if(NOT CMAKE_SIZEOF_VOID_P EQUAL 8 OR NOT CMAKE_SYSTEM_PROCESSOR MATCHES "^(AMD64|amd64|x86_64)$"
+    OR NOT (WIN32 OR CMAKE_SYSTEM_NAME STREQUAL "Linux"))
+  message(FATAL_ERROR "Supported targets are Windows and Linux x86_64.")
+endif()
+if(WIN32)
+  # Hybrid CRT: static C++ runtime and vcruntime, dynamic UCRT (see the link options below).
+  # Python ships no msvcp140.dll, and a host process that loaded an older one first (MATLAB,
+  # Qt applications) can crash code built with a newer toolset. This applies to nanobind and
+  # libwebp too, because both are built as targets of this project.
+  set(CMAKE_MSVC_RUNTIME_LIBRARY MultiThreaded)
+  set(FILAMENT_LIB_DIR "${FILAMENT_ROOT}/lib/x86_64/mt")
+else()
+  set(FILAMENT_LIB_DIR "${FILAMENT_ROOT}/lib/x86_64")
+  # Keep the system GL dispatch library external to manylinux wheels.
+  set(OpenGL_GL_PREFERENCE LEGACY)
+  find_package(OpenGL REQUIRED)
+  find_package(X11 REQUIRED)
+  find_package(Threads REQUIRED)
+endif()
+set(FILAMENT_LIBRARIES gltfio_core filament-iblprefilter filament backend filabridge filaflat
+  geometry ibl utils bluegl smol-v stb dracodec meshoptimizer
+  mikktspace uberzlib zstd basis_transcoder ktxreader image abseil)
+if(WIN32)
+  list(APPEND FILAMENT_LIBRARIES bluevk)
+endif()
+foreach(name IN LISTS FILAMENT_LIBRARIES)
+  add_library(filament_sdk_${name} STATIC IMPORTED)
+  set_target_properties(filament_sdk_${name} PROPERTIES
+    IMPORTED_LOCATION "${FILAMENT_LIB_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}${name}${CMAKE_STATIC_LIBRARY_SUFFIX}")
+  list(APPEND FILAMENT_LINK_TARGETS filament_sdk_${name})
+endforeach()
+
+include(native/libwebp.cmake)
+
+# The output-pass materials and the material archive are embedded as C arrays.
+enable_language(C)
+set(FILLY_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+include(native/materials/output.cmake)
+
+# glTF materials come from filly's precompiled material archive (native/materials), built here
+# with the SDK's matc and uberz. The module has no material compiler. See
+# docs/explanation/material-precompilation.md.
+include(native/materials/materials.cmake)
+
+add_library(filly_core STATIC native/renderer.cpp native/output_pass.cpp native/gl_interop.cpp native/archive_materials.cpp
+  native/gltf_prepare.cpp native/json.cpp native/shapes.cpp native/webp_provider.cpp native/egl_platform.cpp
+  native/vendor/meshoptimizer/vertexcodec.cpp native/vendor/meshoptimizer/indexcodec.cpp
+  native/vendor/meshoptimizer/vertexfilter.cpp)
+target_compile_features(filly_core PUBLIC cxx_std_20)
+target_link_libraries(filly_core PRIVATE filly_output_materials filly_material_archive)
+set_target_properties(filly_core PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(filly_core PUBLIC native PRIVATE "${FILAMENT_ROOT}/include" "${libwebp_SOURCE_DIR}/src")
+target_link_libraries(filly_core PRIVATE webpdecoder)
+if(MSVC)
+  target_compile_options(filly_core PRIVATE /Zc:__cplusplus /bigobj /EHsc)
+  target_link_libraries(filly_core PRIVATE ${FILAMENT_LINK_TARGETS} opengl32 gdi32 user32 shlwapi ws2_32)
+else()
+  # Filament's static archives contain circular references.
+  target_link_libraries(filly_core PRIVATE -Wl,--start-group ${FILAMENT_LINK_TARGETS} -Wl,--end-group
+    OpenGL::GL X11::X11 Threads::Threads ${CMAKE_DL_LIBS})
+  target_compile_options(filly_core PRIVATE -fvisibility=hidden)
+endif()
+
+nanobind_add_module(_native STABLE_ABI NOSTRIP native/bindings.cpp)
+target_link_libraries(_native PRIVATE filly_core)
+if(MSVC)
+  # The UCRT is part of Windows 10 and later, and one shared copy keeps a single heap and
+  # locale state per process. The static runtime objects request libucrt.lib by default.
+  target_link_options(_native PRIVATE /NODEFAULTLIB:libucrt.lib /DEFAULTLIB:ucrt.lib)
+else()
+  # Filament marks its public API visible, and the C++ template instantiations are visible
+  # regardless of -fvisibility. Exported, they could bind to another copy of Filament, libwebp,
+  # or a different libstdc++ build in the process, so only the module entry point is exported.
+  set(FILLY_EXPORTS "${CMAKE_CURRENT_BINARY_DIR}/_native.map")
+  file(WRITE "${FILLY_EXPORTS}" "{\n  global: PyInit__native;\n  local: *;\n};\n")
+  target_link_options(_native PRIVATE "LINKER:--version-script=${FILLY_EXPORTS}")
+  set_property(TARGET _native APPEND PROPERTY LINK_DEPENDS "${FILLY_EXPORTS}")
+endif()
+install(TARGETS _native LIBRARY DESTINATION filly RUNTIME DESTINATION filly)
+install(FILES "${FILAMENT_ROOT}/LICENSE" DESTINATION filly/licenses RENAME Filament.txt)
+install(FILES native/vendor/meshoptimizer/LICENSE.md DESTINATION filly/licenses RENAME meshoptimizer.txt)
+install(FILES native/vendor/cgltf/LICENSE DESTINATION filly/licenses RENAME cgltf.txt)
+install(FILES "${libwebp_SOURCE_DIR}/COPYING" DESTINATION filly/licenses RENAME libwebp.txt)
+install(FILES "${libwebp_SOURCE_DIR}/PATENTS" DESTINATION filly/licenses RENAME libwebp-PATENTS.txt)

filly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Forrence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filly-0.1.0/NOTES.md

@@ -0,0 +1,8 @@
+Misc things
+ - ~~psychopy frequently operates in floats, even for window sizes. Accept floats
+   for SharedTarget and coerce to ints?~~ Done: target sizes accept integral floats;
+   fractional or non-finite values raise ValueError.
+ - KHR_xmp_json_ld?
+ - Feels like wheel was reinvented unnecessarily, e.g. some of the custom shaders?
+ - FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB seems awkward for user
+ 

filly-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: filly
+Version: 0.1.0
+Summary: A Python 3D renderer for glTF scenes, built on Google Filament
+Author: Alex Forrence
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Homepage, https://github.com/aforren1/filly
+Project-URL: Documentation, https://github.com/aforren1/filly#readme
+Project-URL: Issues, https://github.com/aforren1/filly/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: examples
+Requires-Dist: Pillow>=10; extra == "examples"
+Provides-Extra: psychopy
+Requires-Dist: psychopy-lib==2026.2.4; extra == "psychopy"
+Provides-Extra: pyglet
+Requires-Dist: pyglet>=1.4.11; extra == "pyglet"
+Provides-Extra: moderngl
+Requires-Dist: pyglet>=1.4.11; extra == "moderngl"
+Requires-Dist: moderngl>=5.12; extra == "moderngl"
+Provides-Extra: zengl
+Requires-Dist: pyglet>=1.4.11; extra == "zengl"
+Requires-Dist: zengl>=2.7; extra == "zengl"
+Description-Content-Type: text/markdown
+
+# filly
+
+filly is a Python 3D renderer for glTF scenes, built on
+[Google Filament](https://github.com/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.
+
+![A wooden playground horse rocking on its spring, rendered with filly](docs/images/horse.gif)
+
+*"[Wooden Playground Horse](https://sketchfab.com/3d-models/wooden-playground-horse-aa1c440f48a44e558dcc9097b35a6a6d)" by [Batuhan13](https://sketchfab.com/Batuhan13),
+[CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). See [attribution](examples/assets/ATTRIBUTION.md).*
+
+## Install
+
+filly is not on PyPI yet. [Build it from source](docs/how-to/build.md).
+
+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
+
+```python
+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.
+
+```python
+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](docs/how-to/gl-hosts.md).
+
+## 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](docs/reference/api.md#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](docs/explanation/web.md).
+
+## Examples
+
+See the `examples/` folder.
+
+| Example | Shows |
+| --- | --- |
+| `screenshot.py` | The animation above (`--gif`), or a still image, rendered offscreen. |
+| `psychopy_shared.py` | A model in a PsychoPy window. Pass your own GLB path. |
+| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same in other OpenGL hosts. |
+| `drifting_grating.py` | A texture updated every frame on a tilted plane. |
+| `stereo.py` | Two cameras side by side in one window. |
+| `shapes.py` | Generated and deforming meshes. |
+
+## Documentation
+
+- Tutorial: [render an image](docs/tutorials/offscreen.md)
+- How-to guides: [build and test](docs/how-to/build.md),
+  [use PsychoPy](docs/how-to/psychopy.md), [use other OpenGL hosts](docs/how-to/gl-hosts.md),
+  [measure timing](docs/how-to/stress-test.md), [profile a frame](docs/how-to/profile.md),
+  [compare with Filament's viewer](docs/how-to/reference-comparison.md),
+  [use filly in a web page](docs/how-to/web.md)
+- Reference: [API](docs/reference/api.md), [performance](docs/reference/performance.md),
+  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md)
+- Explanation: [design and limits](docs/explanation/design.md),
+  [tested assumptions](docs/explanation/assumptions.md),
+  [material precompilation](docs/explanation/material-precompilation.md),
+  [the web build](docs/explanation/web.md)
+
+## License
+
+filly is released under the [MIT License](LICENSE).
+
+It links [Filament](https://github.com/google/filament) (Apache 2.0),
+[meshoptimizer](https://github.com/zeux/meshoptimizer) (MIT),
+[libwebp](https://chromium.googlesource.com/webm/libwebp) (BSD), and
+[cgltf](https://github.com/jkuhlmann/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.

filly-0.1.0/README.md

@@ -0,0 +1,133 @@
+# filly
+
+filly is a Python 3D renderer for glTF scenes, built on
+[Google Filament](https://github.com/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.
+
+![A wooden playground horse rocking on its spring, rendered with filly](docs/images/horse.gif)
+
+*"[Wooden Playground Horse](https://sketchfab.com/3d-models/wooden-playground-horse-aa1c440f48a44e558dcc9097b35a6a6d)" by [Batuhan13](https://sketchfab.com/Batuhan13),
+[CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). See [attribution](examples/assets/ATTRIBUTION.md).*
+
+## Install
+
+filly is not on PyPI yet. [Build it from source](docs/how-to/build.md).
+
+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
+
+```python
+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.
+
+```python
+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](docs/how-to/gl-hosts.md).
+
+## 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](docs/reference/api.md#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](docs/explanation/web.md).
+
+## Examples
+
+See the `examples/` folder.
+
+| Example | Shows |
+| --- | --- |
+| `screenshot.py` | The animation above (`--gif`), or a still image, rendered offscreen. |
+| `psychopy_shared.py` | A model in a PsychoPy window. Pass your own GLB path. |
+| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same in other OpenGL hosts. |
+| `drifting_grating.py` | A texture updated every frame on a tilted plane. |
+| `stereo.py` | Two cameras side by side in one window. |
+| `shapes.py` | Generated and deforming meshes. |
+
+## Documentation
+
+- Tutorial: [render an image](docs/tutorials/offscreen.md)
+- How-to guides: [build and test](docs/how-to/build.md),
+  [use PsychoPy](docs/how-to/psychopy.md), [use other OpenGL hosts](docs/how-to/gl-hosts.md),
+  [measure timing](docs/how-to/stress-test.md), [profile a frame](docs/how-to/profile.md),
+  [compare with Filament's viewer](docs/how-to/reference-comparison.md),
+  [use filly in a web page](docs/how-to/web.md)
+- Reference: [API](docs/reference/api.md), [performance](docs/reference/performance.md),
+  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md)
+- Explanation: [design and limits](docs/explanation/design.md),
+  [tested assumptions](docs/explanation/assumptions.md),
+  [material precompilation](docs/explanation/material-precompilation.md),
+  [the web build](docs/explanation/web.md)
+
+## License
+
+filly is released under the [MIT License](LICENSE).
+
+It links [Filament](https://github.com/google/filament) (Apache 2.0),
+[meshoptimizer](https://github.com/zeux/meshoptimizer) (MIT),
+[libwebp](https://chromium.googlesource.com/webm/libwebp) (BSD), and
+[cgltf](https://github.com/jkuhlmann/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.