Skip to main content
cmgen is a command-line tool for generating spherical harmonics and mipmap levels from environment maps. It processes HDR images to create the data needed for Image-Based Lighting (IBL) in Filament.

​
Usage

cmgen [options] <input-file>
cmgen [options] <uv[N]>
Cubemaps and equirectangular formats are both supported, automatically detected according to the aspect ratio of the source image.

​
Supported Input Formats

  • PNG (8 and 16 bits)
  • Radiance (.hdr)
  • Photoshop (.psd, 16 and 32 bits)
  • OpenEXR (.exr)

​
Supported Aspect Ratios

  • 2:1 - Latitude/longitude or equirectangular
  • 3:4 - Vertical cross (height must be power of two)
  • 4:3 - Horizontal cross (width must be power of two)

​
Common Options

​
Output Configuration

  • --type, -t <type> - Specify output type (default: cubemap)
    • cubemap - Individual cubemap faces
    • ktx - KTX container format
    • equirect - Equirectangular projection
    • octahedron - Octahedral projection
  • --format, -f <format> - Specify output file format
    • png, hdr, rgbm, rgb32f, exr, psd, dds, ktx
    • KTX files are always KTX1 (not KTX2), encoded with 3-channel RGB_10_11_11_REV data
    • ktx format implies --type=ktx
  • --size, -s <power-of-two> - Size of output cubemaps (base level), default is 256
    • Also applies to DFG LUT

​
Compression

  • --compression, -c <compression> - Format-specific compression:
    • KTX: Ignored
    • PNG: Ignored
    • Radiance: Ignored
    • Photoshop: 16 (default), 32
    • OpenEXR: RAW, RLE, ZIPS, ZIP, PIZ (default)
    • DDS: 8, 16 (default), 32

​
IBL Generation

​
Deployment

  • --deploy, -x <dir> - Generate everything needed for deployment into specified directory
    • Automatically generates: SH coefficients, cubemap faces, and pre-filtered reflections

​
Roughness Pre-filtering

  • --ibl-ld <dir> - Generate roughness pre-filtered reflection maps into directory
    • Creates mipmaps for different roughness levels

​
Spherical Harmonics

  • --sh-shader - Generate irradiance SH coefficients for shader code
    • Outputs pre-scaled spherical harmonics suitable for real-time rendering

​
Sampling

  • --ibl-samples <numSamples> - Number of samples for IBL integrations (default: 1024)
    • Higher values produce better quality but take longer

​
Minimum LOD Size

  • --ibl-min-lod-size <size> - Minimum LOD size (default: 16)
    • Must be a power of two

​
Face Extraction

  • --extract <dir> - Extract cubemap faces into specified directory
  • --extract-blur <roughness> - Blur the cubemap before saving faces using roughness parameter (0.0 to 1.0)

​
Processing Options

  • --clamp - Clamp environment before processing
    • By default, environments are not clamped
  • --no-mirror - Skip mirroring of generated cubemaps
    • Use for assets with mirroring already baked in
    • By default, cubemaps are mirrored
  • --quiet, -q - Suppress all non-error output

​
Advanced Options

​
Spherical Harmonics (Advanced)

  • --sh <bands> - SH decomposition of input cubemap with specified number of bands
  • --sh-output <filename> - SH output filename (extension determines format)
    • Supported: .exr, .hdr, .psd, .rgbm, .rgb32f, .png, .dds, .txt, .bin
  • --sh-irradiance, -i - Generate irradiance SH coefficients
  • --sh-window <cutoff|no|auto> - SH windowing to reduce ringing (default: auto)

​
IBL Processing (Advanced)

  • --ibl-is-mipmap <dir> - Generate mipmaps for pre-filtered importance sampling
  • --ibl-irradiance <dir> - Generate diffuse irradiance into directory
  • --ibl-no-prefilter - Use importance sampling instead of pre-filtered importance sampling
  • --ibl-dfg <filename> - Compute the IBL DFG LUT (for internal use)
  • --ibl-dfg-multiscatter - Compute DFG for multi-scattering GGX
  • --ibl-dfg-cloth - Add 3rd channel to DFG for cloth shading

​
Debug

  • --debug, -d - Generate extra data for debugging

​
Examples

​
Generate IBL for deployment

cmgen --deploy=./output --format=ktx --size=256 environment.hdr
This creates:
  • Pre-filtered reflection maps at various roughness levels
  • Spherical harmonics coefficients for diffuse lighting
  • Cubemap faces for skybox

​
Create pre-filtered reflections with custom settings

cmgen --ibl-ld=./reflections --size=512 --ibl-samples=2048 environment.exr

​
Extract blurred cubemap faces

cmgen --extract=./faces --extract-blur=0.3 --format=png environment.hdr

​
Generate KTX output with spherical harmonics

cmgen --type=ktx --format=ktx --sh-shader --size=256 environment.hdr

​
Process with specific compression

cmgen --format=exr --compression=ZIP --ibl-ld=./ibl environment.exr

​
Generate from equirectangular with deployment

cmgen --deploy=./assets/ibl --format=rgb32f --size=512 latlong.hdr

​
UV Grid Generation

If the input file doesn’t exist, cmgen can generate UV grid patterns: 
cmgen uv4      # 4x4 UV grid
cmgen u8       # 8x1 horizontal UV grid
cmgen v8       # 8x1 vertical UV grid

​
Output Structure

When using --deploy, the tool creates: 
output/
├── environment_name/
│   ├── m0_nx.png      # Mip level 0, negative X face
│   ├── m0_px.png      # Mip level 0, positive X face
│   ├── m0_ny.png      # (and other faces...)
│   ├── m1_*.png       # Mip level 1 faces
│   ├── m2_*.png       # (and other mip levels...)
│   └── sh.txt         # Spherical harmonics coefficients
For KTX output: 
output/
└── environment_ibl.ktx  # Single file with all mip levels

​
Help

  • --help, -h - Print help message
  • --license - Print copyright and license information

Build docs developers (and LLMs) love

Get started for freeTalk to us