Metadata-Version: 2.4
Name: gltf_ibl_sampler
Version: 0.1.1b0
Summary: glTF-IBL-Sampler
Author: Motphys
Author-email: Motphys <motphys-developers@motphys.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown

# 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

```bash
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:

```bash
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:

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

Use an input cubemap instead of a panorama:

```bash
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

```python
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:

```python
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
