mipgen

​

Usage

mipgen [options] <input_file> <output_pattern>

mipgen --format=ktx input.png output.ktx

​

Supported Input Formats

• PNG (8 and 16 bits)
• JPEG
• Radiance (.hdr)
• Photoshop (.psd, 16 and 32 bits)
• OpenEXR (.exr)
• And other formats supported by stb_image and tinyexr

​

Options

​

Output Format

• --format, -f <format> - Specify output file format
  • png - PNG (default for LDR)
  • hdr - Radiance HDR
  • exr - OpenEXR
  • psd - Photoshop
  • dds - DirectDraw Surface
  • ktx - KTX1 container
  • ktx2 - KTX2 container (with Basis compression)
  • rgbm - RGBM encoded PNG
  • If omitted, format is inferred from output pattern extension

​

Filter Kernels

• --kernel, -k <filter> - Specify filter kernel type (default: lanczos)
  • box - Box filter (fastest, lowest quality)
  • nearest - Nearest neighbor
  • hermite - Hermite filter
  • gaussian - Gaussian filter
  • normals - Gaussian filter optimized for normal maps
  • mitchell - Mitchell-Netravali filter
  • lanczos - Lanczos filter (default, high quality)
  • min - Minimum filter

​

Compression

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

​

Color Space

• --linear, -l - Specifies that source image is linear
  • Converts to floats without gamma transformation
  • Use for normal maps, metallic/roughness maps, etc.

​

Channel Control

• --grayscale, -g - Create a single-channel image
  • Extracts the first channel only
• --add-alpha - Add a fourth channel filled with 1.0
  • Use when source has 3 channels but you need 4
• --strip-alpha - Ignore the alpha component
  • Use to convert RGBA to RGB

​

Mip Level Control

• --mip-levels, -m <N> - Specifies number of mip levels to generate
  • 0 (default) generates all levels down to 1x1
  • Otherwise generates N-1 levels (excluding the base level)

​

Output Options

• --page, -p - Generate HTML page for review (mipmaps.html)
  • Creates a visual gallery of all mip levels
• --quiet, -q - Suppress console output

​

Examples

​

Generate PNG mipmaps with Lanczos filter

mipgen texture.png mip_%03d.png

​

Generate KTX2 with UASTC compression

mipgen --format=ktx2 --compression=uastc texture.png texture.ktx

​

Normal map processing

mipgen --kernel=normals --linear normal_map.png normal_%02d.png

​

Grayscale mipmaps with Hermite filter

mipgen --grayscale --kernel=hermite heightmap.png height_%02d.png

​

Generate with review page

mipgen --page --kernel=mitchell diffuse.png mip_%02d.png

​

EXR output with compression

mipgen --format=exr --compression=ZIP hdr_texture.exr mip_%02d.exr

​

Limit mip levels

mipgen --mip-levels=4 texture.png mip_%02d.png

​

KTX1 container for deployment

mipgen --format=ktx texture.png texture.ktx

​

Strip alpha channel

mipgen --strip-alpha rgba_texture.png rgb_mip_%02d.png

​

Filter Kernel Guide

​

For Color/Albedo Textures

• Lanczos (default): Best quality, sharp results
• Mitchell: Good balance of sharpness and smoothness
• Hermite: Smoother, less ringing than Lanczos

​

For Normal Maps

• normals: Specially designed for normal maps
  • Normalizes vectors after filtering
  • Prevents normal vectors from losing length

​

For Other Data

• Box: Fast, for non-critical textures
• Gaussian: Smooth falloff
• Min: Preserve minimum values (useful for some masks)

​

KTX2 Compression

​

UASTC (Universal ASTC)

mipgen -f ktx2 -c uastc texture.png output.ktx

• Higher quality
• Larger file size than ETC1S
• Faster encoding
• Best for high-quality assets

​

ETC1S (ETC1 Subset)

mipgen -f ktx2 -c etc1s texture.png output.ktx

• Smaller file size
• Lower quality than UASTC
• Slower encoding (better compression)
• Best for mobile/web deployment

​

Normal Map Compression

mipgen -f ktx2 -c uastc_normals --linear normals.png normals.ktx

• Optimized for normal map data
• Use with --linear flag
• Available for both UASTC and ETC1S

​

Output Pattern

• %d - Decimal number: mip1, mip2, mip3
• %02d - Zero-padded 2 digits: mip01, mip02, mip03
• %03d - Zero-padded 3 digits: mip001, mip002, mip003

mipgen input.png "mip%d.png"           # mip1.png, mip2.png, ...
mipgen input.png "level_%02d.png"      # level_01.png, level_02.png, ...
mipgen input.png "textures/m%03d.exr"  # textures/m001.exr, textures/m002.exr, ...

​

Best Practices

​

For Runtime Textures

1. Use KTX containers for efficient loading
2. Enable compression for reduced memory/bandwidth
3. Choose appropriate filter for texture type

mipgen -f ktx2 -c uastc -k lanczos color.png color.ktx
mipgen -f ktx2 -c uastc_normals -k normals -l normal.png normal.ktx

​

For Normal Maps

1. Always use --linear flag
2. Use --kernel=normals filter
3. Consider normal-specific compression for KTX2

mipgen --linear --kernel=normals normal_map.png normal_%02d.png

​

For Alpha Channels

• Use --add-alpha when you need a fully opaque alpha channel
• Use --strip-alpha to reduce file size when alpha isn’t needed

​

For Web/Mobile

mipgen -f ktx2 -c etc1s texture.png texture.ktx

• Smallest file size
• Good enough quality for most cases
• Fast decode on GPU

​

Troubleshooting

​

”Unable to open image”

​

”Output pattern is too long”

​

Mipmaps look too blurry

​

Normal maps look incorrect

mipgen --kernel=normals --linear normal.png normal_%02d.png

​

Help

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