gltf_ibl_sampler 0.1.1b0

glTF-IBL-Sampler

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

Option	Python argument	Description
-inputPath	input_path	Input panorama or cubemap path.
-outCubeMap	out_cube_map	Output path for the filtered cubemap.
-outLUT	out_lut	Output path for the BRDF LUT.
-distribution	distribution	Sampling distribution: Lambertian, GGX, or Charlie.
-sampleCount	sample_count	Number of samples used for filtering. Default: 1024.
-mipLevelCount	mip_level_count	Number of mip levels for the specular cubemap.
-cubeMapResolution	cube_map_resolution	Output cubemap resolution.
-targetFormat	target_format	Output texture format.
-lodBias	lod_bias	LOD bias applied during filtering. Default: 0.0.
-inputIsCubeMap	input_is_cube_map	Treat the input as a cubemap instead of a panorama.

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