Panda3D glTF Utilities

1.3.0 · active · verified Fri Apr 17

`panda3d-gltf` provides utilities to load glTF (GL Transmission Format) 3D models into the Panda3D engine. It handles parsing glTF files and converting their data (meshes, materials, textures, animations, scenes) into Panda3D's native scene graph format, simplifying the process of integrating glTF assets. The current version is 1.3.0, with releases occurring as needed for fixes and feature enhancements, rather than on a fixed schedule.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'your_model.gltf'
```
cause The glTF file specified in `gltf_loader.load_gltf()` does not exist at the given path, or Panda3D's Virtual File System cannot find it.

fix Verify the file path. Ensure the file exists relative to your script or add the directory containing the model to Panda3D's search path using `loader.mountFileSys` or similar VFS methods.
```
AttributeError: module 'panda3d_gltf' has no attribute 'load_gltf'
```
cause Attempting to call `panda3d_gltf.load_gltf()` directly. The `load_gltf` function is part of the `gltf_loader` submodule.

fix Correct the import and call: `from panda3d_gltf import gltf_loader` then `gltf_loader.load_gltf('your_model.gltf')`.
```
Model loads but appears completely dark or as a solid, untextured color.
```
cause The Panda3D scene might be missing proper lighting. glTF models often rely on PBR (Physically Based Rendering) and require lights (e.g., `DirectionalLight`, `AmbientLight`) to be visible.

fix Add appropriate light sources to your Panda3D scene and ensure they are parented to `render`. For example, add `self.render.setShaderAuto()` and `self.render.setLight(some_light_node_path)`.

Warnings

breaking Version 1.0.0 introduced a complete rewrite of the API. Code written for pre-1.0 versions is not compatible with 1.x and will require significant updates.
Fix: Refer to the `panda3d-gltf` GitHub README for updated import paths and usage patterns for versions 1.0.0 and newer.
gotcha Panda3D's Virtual File System (VFS) handles asset paths, and it might not automatically resolve relative paths as expected without `addDirectory` calls or using Panda3D's `Filename` object. This can lead to `FileNotFoundError` for models or textures.
Fix: Ensure that the directory containing your glTF model and its dependencies (textures, bins) is added to Panda3D's VFS using `loader.mountFileSys` or `Filename.setModuleDir(os.path.abspath(os.path.dirname(__file__)))` at the start of your application, or provide absolute paths.
gotcha Not all glTF extensions are fully supported by `panda3d-gltf`. Models using advanced or custom extensions (e.g., specific PBR material extensions not common in core glTF, or complex animation nodes) may not load correctly or might lose certain features.
Fix: Check the `panda3d-gltf` documentation for supported extensions. If an extension isn't supported, you may need to preprocess the glTF file to bake down unsupported features or manually implement custom loading logic.

Install

pip install panda3d-gltf Install stable version

Imports

gltf_loader
wrong:
```
from panda3d_gltf.gltf_loader import gltf_loader
```
correct:
```
from panda3d_gltf import gltf_loader
```
The `gltf_loader` module is exposed directly at the top level for convenience, avoid importing it from its submodule path unless directly referencing its classes.
GLTFLoader
```
from panda3d_gltf.gltf_loader import GLTFLoader
```
Use this to access the lower-level GLTFLoader class for more control over the loading process.
Converter
```
from panda3d_gltf.converter import Converter
```
For converting glTF models into Panda3D's native BAM format for faster loading.

Quickstart

This quickstart demonstrates how to initialize a basic Panda3D application and load a glTF model using `panda3d-gltf`. It sets up a camera and a dark background for visibility. Users must replace `'models/box.gltf'` with the actual path to their glTF file. It also includes basic error handling for file loading issues.

from direct.showbase.ShowBase import ShowBase
from panda3d_gltf import gltf_loader

class MyApp(ShowBase):
    def __init__(self):
        ShowBase.__init__(self)

        self.disableMouse() # Disable default camera control
        self.cam.setPos(0, -10, 0)
        self.cam.lookAt(0, 0, 0)
        self.setBackgroundColor(0.1, 0.1, 0.1)

        # --- User provided glTF model is required ---
        # Replace 'path/to/your_model.gltf' with an actual glTF file path.
        # For a runnable example, ensure this file exists or use a known sample.
        # Example: a simple 'box.gltf' in a 'models' directory.
        model_path = 'models/box.gltf' 
        
        try:
            model = gltf_loader.load_gltf(model_path)
            if model:
                model.reparent_to(self.render)
                model.setPos(0, 0, 0) # Adjust position as needed
                model.setScale(1)    # Adjust scale as needed
                print(f"Successfully loaded {model_path}")
            else:
                print(f"Failed to load {model_path}. Model object is None.")
        except Exception as e:
            print(f"Error loading glTF model from {model_path}: {e}")
            print("Please ensure the glTF file exists and is valid.")

app = MyApp()
app.run()

view raw JSON →