glTF-IBL-Sampler

Python wrapper and command-line entry point for generating image-based lighting (IBL) textures with the bundled glTF-IBL-Sampler native binaries.

The package can filter a panorama or cubemap into a prefiltered environment cubemap and can generate a BRDF lookup texture for glTF/PBR workflows.

Installation

pip install gltf-ibl-sampler

The wheel includes the native sampler binaries and runtime libraries for the supported desktop platforms, so no Python dependencies are required at runtime.

Supported Platforms

Bundled binaries are provided for:

• macOS x86_64
• Linux x86_64
• Windows x86_64

The sampler uses Vulkan. Make sure the target machine has a working Vulkan-compatible runtime and GPU driver.

Command Line Usage

Generate a prefiltered cubemap and BRDF LUT from a panorama:

gltf-ibl-sampler \
  -inputPath studio.hdr \
  -outCubeMap studio_ggx.ktx \
  -outLUT studio_lut.ktx \
  -distribution GGX \
  -cubeMapResolution 512 \
  -sampleCount 1024

Generate a complete IBL set with generated output names:

gltf-ibl-sampler \
  -inputPath studio.hdr \
  --generate-full-ibl \
  --output-dir ./output \
  --base-name studio

Use an input cubemap instead of a panorama:

gltf-ibl-sampler \
  -inputPath input_cubemap.ktx \
  -inputIsCubeMap \
  -outCubeMap filtered.ktx

At least one output must be specified with -outCubeMap, -outLUT, or --generate-full-ibl.

Python API

from gltf_ibl_sampler import sample_ibl

log = sample_ibl(
    input_path="studio.hdr",
    out_cube_map="studio_ggx.ktx",
    out_lut="studio_lut.ktx",
    distribution="GGX",
    cube_map_resolution=512,
    sample_count=1024,
)

print(log)

Generate both outputs into a directory:

from gltf_ibl_sampler import generate_ibl_from_panorama

result = generate_ibl_from_panorama(
    input_panorama="studio.hdr",
    output_dir="./output",
    base_name="studio",
    distribution="GGX",
    cube_map_resolution=512,
)

print(result["cube_map"])
print(result["lut"])

Options

Supported target formats:

• R8G8B8A8_UNORM
• R16G16B16A16_SFLOAT
• R32G32B32A32_SFLOAT

Troubleshooting

Bundled glTF-IBL-Sampler binary not found

The installed package is missing the native sampler executable. Reinstall the package or rebuild the wheel from a checkout that contains the bundled binaries.

Failed to create Vulkan instance

The native sampler could not initialize Vulkan. Check that the machine has a compatible GPU driver and Vulkan runtime. On macOS, this usually requires a working Vulkan-over-Metal runtime such as MoltenVK.

Unsupported CPU architecture

The bundled binaries are currently x86_64 builds. On machines with a different architecture, use an x86_64-compatible environment or provide a native build of the sampler binary and libraries.

License

Apache-2.0