Converts a 2:1 equirectangular panorama into mipmapped, 6-face KTX2 cubemaps ready to use as a skybox/environment in any engine or tool that consumes KTX2. Every run produces both compressed formats:
out/astc.ktx2—ASTC_4x4_SRGB_BLOCKout/bc7.ktx2—BC7_SRGB_BLOCK
Two things are needed: Python with Pillow + numpy, and the KTX-Software ktx CLI.
1. Python deps (Python 3.9+):
pip3 install pillow numpy2. The ktx CLI (KTX-Software, used to encode/pack the KTX2 files):
-
macOS — run the bundled fetcher, which downloads KTX-Software and installs
ktxintotools/with no sudo (thetools/binaries are not committed, so do this after cloning):sh tools/fetch-ktx.sh # -> tools/ktx version: v4.4.2 -
Linux / Windows — install KTX-Software from its releases (
.deb/.rpm/.tar.bz2/ installer). That putsktxon yourPATH;convert.shuses it automatically whentools/ktxis absent.
convert.sh prefers tools/ktx and otherwise falls back to a ktx on PATH.
See tools/README.md for what the fetcher does under the hood.
sh convert.sh <input-image> [face_size] [brightness] [tilt] [sharpen]input-image— equirectangular (2:1) source image, requiredface_size— cubemap face size in px (default256)brightness— linear-light multiplier applied to every face (default1.0);<1darkens,>1brightens. Dimming is done in linear light so colors stay true. (equirect_to_faces.py --brightnessif calling Python directly.)tilt— pitch the whole cubemap about the horizontal X axis,0..90degrees (default0). Rotation is applied to the sample directions, so the result stays seamless. (equirect_to_faces.py --tilt.)sharpen— unsharp-mask amount applied after downscaling (default0= off).~0.5-1.5tightens fine detail; higher adds more ringing around bright highlights. Done in linear light. (equirect_to_faces.py --sharpen.)
Output: out/astc.ktx2 (plus intermediate face PNGs in out/faces/).
sh convert.sh panorama.tif # 256² cubemap, full brightness, no tilt
sh convert.sh panorama.tif 512 # 512²
sh convert.sh panorama.tif 256 0.4 # 256², dimmed to 40%
sh convert.sh panorama.tif 256 0.4 30 # 256², dimmed, tilted 30°
sh convert.sh panorama.tif 512 1.0 0 1.0 # 512², sharpenedequirect_to_faces.py(Python, PIL + numpy) renders 6 square faces from the panorama, using the KTX2/Vulkan cubemap convention (left-handed, +Y up, +Z forward, top-left origin), face order +X, −X, +Y, −Y, +Z, −Z. The whole sample → downscale → brightness pipeline runs in linear light: each face is 6× supersampled then area-averaged in linear space. This preserves the energy of sub-pixel bright points — averaging in gamma/sRGB space collapses faint highlights toward black and makes them vanish. Supersample is tunable (--supersample); lower it if memory is tight at large--size.tools/ktx createencodes the faces toASTC_4x4_SRGB_BLOCK, marks the result as a cubemap (--cubemap), tags sRGB (--assign-tf srgb), and generates the full mip chain (--generate-mipmap).- BC7 has no direct encoder in
ktx create, so it is produced by encoding the same faces to UASTC and thenktx transcode --target bc7→out/bc7.ktx2.
tools/ktx info out/astc.ktx2 # vkFormat VK_FORMAT_ASTC_4x4_SRGB_BLOCK, faceCount 6
tools/ktx info out/bc7.ktx2 # vkFormat VK_FORMAT_BC7_SRGB_BLOCK, faceCount 6Use out/astc.ktx2 / out/bc7.ktx2 as cubemap assets in your renderer. Engines
typically select the format their GPU supports — ASTC on mobile and Apple Silicon
(Metal), BC7 on most desktop Vulkan/D3D12 GPUs.