gltf - glTF library and viewer for Nim.

nimby install gltf

API reference

About

gltf is a small glTF 2.0 toolkit for Nim. It can load .gltf and .glb files into a Node tree, render that tree with a small OpenGL PBR pipeline, write simple scenes back out as .glb, and read or write basic KTX2 textures for OpenGL workflows.

The project is still growing, but it is already useful for:

• Loading glTF models in Nim code.
• Inspecting models with a local viewer.
• Rendering models with a simple PBR path.
• Exporting simple scenes back to binary glTF.

Documentation

• API reference: treeform.github.io/gltf
• Source entry point: src/gltf.nim
• Example program: examples/load_model.nim
• Viewer tool: tools/gltf_viewer.nim

Installation

Install the package with:

nimby install gltf

The package depends on:

• vmath
• chroma
• pixie
• flatty
• opengl
• webby
• windy
• silky

Support

The table below reflects the current code, not the full glTF 2.0 spec.

KHR_texture_basisu and KTX2

The library declares support for the glTF extension KHR_texture_basisu, which lets materials reference KTX 2.0 (.ktx2) images instead of PNG or JPEG. That path is aimed at runtime performance (smaller on-disk size and direct compressed uploads to the GPU), not at general authoring workflows.

Extension

• Textures can use extensions.KHR_texture_basisu.source to point at an image that carries KTX2 payload (mimeType: image/ktx2), including sidecar .ktx2 URIs, data:image/ktx2 data URIs, and buffer views with mimeType: image/ktx2.

Embedded KTX2 reader/writer

The embedded KTX2 code can load supported files into OpenGL 2D textures and can also write supported textures back out from live OpenGL texture objects. Supported inputs and outputs match what the code accepts today:

Anything outside that (3D/volume KTX2, texture arrays beyond a single layer, cubemaps, supercompressed payloads, or other vkFormat values) is not supported and will fail with a clear error.

Supported KTX2 writing

• writeKtx2TextureFile() writes 2D textures directly from a live OpenGL texture object.
• Uncompressed writes include VK_FORMAT_R32_SFLOAT.
• Compressed writes include BC1-BC5 when OpenGL can provide or create those compressed levels.
• The low-level KTX2 module itself does not require ktx.exe for these direct texture writes.

Writing KTX2 with KTX Software

Exporting glTF that uses KHR_texture_basisu and external .ktx2 sidecars still does not fully reimplement the higher-level image encoding pipeline inside Nim. That glTF export path shells out to the official KTX-Software command-line tool: the ktx executable must be on PATH (see findExe("ktx") in the writer). If it is missing, writing those encoded KTX2 sidecars raises an error explaining that requirement.

That pipeline is for optimization and shipping builds, not something most users should hand-roll as their default content workflow. Typical authoring still uses PNG or JPEG; you then convert to KTX2 when you care about load time and size in a game or similar runtime. As a developer of this library or of tools built on it, you will usually want KTX-Software installed so tests and writeGLB paths that emit KTX2 can run locally and in CI.

Why use KTX2 at all? The practical reason in this context is faster loads and smaller packages for texture-heavy games: GPU-native block formats avoid decoding PNG/JPEG at runtime and map cleanly to compressed texture uploads.

Usage

For simple loading:

import gltf

let gltfFile = readGltfFile("model.glb")
let root = gltfFile.root

echo root.name
echo root.walkNodes().len
echo root.getBoundingSphere().radius

Useful helpers on Node include:

• walkNodes()
• getAABounds()
• getBoundingSphere()
• updateAnimation()
• dumpTree()

To write a simple scene back to binary glTF:

import gltf

writeGLB(root, "out.glb")

Examples

The repository includes a small example loader:

nim r examples/load_model.nim path/to/model.glb

It uses readGltfFile() and prints:

• The source file path.
• The root node name.
• The root child count.

This is the simplest way to verify that loading works.

Viewer

The interactive viewer lives in tools/gltf_viewer.nim:

nim r tools/gltf_viewer.nim path/to/model.glb

It sets up the PBR renderer, loads the file, prints the node tree, computes bounds, and opens a window for inspection.

Current controls:

• Middle mouse drag, or Command plus left drag, orbit the camera.
• Mouse wheel dollies in and out.
• 3 toggles light follow camera.
• 4 sets the light to the current camera position.

Project Layout

• src/ contains the library modules.
• examples/ contains small runnable examples.
• tools/ contains helper programs such as the viewer.
• tests/ contains simple doAssert based tests.
• experiments/ contains rendering experiments and shader work.

Development

The project includes standard build and docs workflows:

• .github/workflows/build.yml
• .github/workflows/docs.yml

Run the checks locally with:

nim check src/gltf.nim
nim r tests/tests.nim

License

This project uses the MIT license. See LICENSE.