Quickly compress textures and meshes to KTX2
When you inspect a 3D scene in the browser, the textures are often the heaviest asset. A .glb file with 3 2k textures can already be a few megabyte on the disk. For which you also have to consider the time that the user is waiting to download them. The model that we are going to test, for example, contains 5 textures and each texture takes 22MB of video memory, meaning 100MB for a single model. Once they are downloaded, the browser has to decode the JPG/PNG file and upload it to the GPU uncompressed.
KTX2 with Basis Universal compression it is what you should use when dealing with models in the browsers. A KTX2 texture it is like a small JPG, and it can be transcoded at runtime to a format that a GPU can understand. So, basically is like uploading a compressed texture to the GPU and that texture can stay compressed.
Actually, at a more closer level, there is an intermediate step in between. The Basis Universal format cannot be read by the GPU directly; it needs to be converted to the format that the physical GPU supports, and that format depends on the device:
| Device | Compressed format |
|---|---|
| Desktop | BC7, BC1/BC2 |
| Android | ETC2 |
| iOS | ASTC |
3D libraries and framework have their own solution to match the right compressed format for the right device. In three.js, KTX2Loader is the piece of code responsible of this.
So, converting our textures to the Basis Universal format solves a lot of problems. How do we apply this conversion?
The problem: installing the tools
The best tool to compress texture, but also to compress 3D meshes, is glTF-Transform. It is a CLI tool that can convert images to KTX2, and can also prune, resize, depublicate and compress meshes with Draco. It is really the swiss knife for 3D asset compression. The problem is that if you want to run it locally you need to install first ktx, that requires CMake, Ninja, etc…, and then you need Node.js for glTF-Transform. And the 2 need to work together.
Some months ago I have packaged the tool in a container image edap/gltf-transform-ktx2 ready to use, to save me some time the next time that I need to optimize some assets. It is built on node:20-slim and contains:
gltf-transform4.3.0ktxv4.4.2, compiled from source
Here below I explain how to use it.
Pull the image with Podman
I am using podman, but if you prefer Docker, just replace the word podman with docker and it works.
podman pull docker.io/edap/gltf-transform-ktx2:v1.0.0
Check that both tools (ktx and gltf-transform) are working:
podman run --rm docker.io/edap/gltf-transform-ktx2:v1.0.0 ktx --version
# ktx version: v4.4.2
podman run --rm docker.io/edap/gltf-transform-ktx2:v1.0.0 gltf-transform --version
# 4.3.0
Now you can run the tools on some of your assets. In order to do so, the container needs access to them. You have to mount the current folder into /workspace, and use this one as your working directory. Here below I assume that the current directory is where you assets are
podman run --rm -v "$PWD":/workspace:rw -w /workspace \
docker.io/edap/gltf-transform-ktx2:v1.0.0 <command>
--rmdeletes the container when the command finishes.-v "$PWD":/workspace:rwmounts the current folder inside the container, with read and write access.-w /workspaceruns the command from that folder, so you can use relative paths.
With rootless Podman, the files created inside the container belong to your user on the host, not to root. On distributions with SELinux enabled (Fedora, RHEL), add :Z to the volume (-v "$PWD":/workspace:rw,Z), otherwise the container cannot read the folder.
I define an alias for this line because is too long for my lazy soul:
alias gltfktx='podman run --rm -v "$PWD":/workspace:rw -w /workspace docker.io/edap/gltf-transform-ktx2:v1.0.0'
And I use this alias in all the next examples. The mesh example uses the DamagedHelmet model from the Khronos glTF samples repository.
Compress a single image
Let’s see how to convert a single image example.png to KTX2 with ktx create:.
gltfktx ktx create \
--format R8G8B8A8_SRGB \
--encode basis-lz \
--generate-mipmap \
example.png example.ktx2
--format R8G8B8A8_SRGB: the format of the input data, an RGBA color image in sRGB.--encode basis-lz: use ETC1S compression, which gives very small files. The alternative isuastc, which has better quality but produces bigger files.--generate-mipmap: generate the mipmaps now, so they don’t have to be generated at runtime.
You now have your example.ktx2 texture ready to use.
Compress a mesh
When compressing a .glb mesh that contains materials with textures, gltf-transform convert to KTX2 the textures contained in the material.
This is the chain of commands that I use in my conversion script:
gltfktx sh -c '
gltf-transform prune DamagedHelmet.glb out.glb &&
gltf-transform dedup out.glb out.glb &&
gltf-transform weld out.glb out.glb &&
gltf-transform resize out.glb out.glb --width 1024 --height 1024 &&
gltf-transform etc1s out.glb out.glb --quality 75 --verbose
'
Here we run sh -c inside the container, so the whole chain runs in a single container.
pruneremoves unused nodes, materials, textures and accessors.dedupremoves duplicated accessors, meshes, materials and textures.weldmerges the vertices that are identical and adds an index buffer.resizelimits the textures to 1024x1024, keeping the aspect ratio. It never upscales.etc1sconverts all the textures to KTX2 with ETC1S compression.--qualityis the same as--qlevelabove, from 1 to 255. glTF-Transform also has auastccommand, if you need higher quality. With--verboseyou see thektx createcommands that it runs for each texture.
In my personal experience, sometime models brakes when they are complex, with a lot of materials and when I try to compress them too much. My suggestion is to do this optimization iteratively. Start by using only etc1s, than add the rest. The weld option is that one that in my personal experience, caused more trouble.
Once we are done, we can also compress the mesh using Google’s Draco:
gltfktx gltf-transform draco out.glb out_draco.glb
These are the results for the helmet:
| step | file size | GPU memory per texture |
|---|---|---|
| original (JPEG) | 3.77 MB | 22.37 MB |
| resize to 1024 | 1.24 MB | 5.6 MB |
| + KTX2 (ETC1S) | 1.00 MB | 0.70 MB |
| + Draco | 0.53 MB | 0.70 MB |
As you see, the file is 7 times smaller, and the VRAM usage goes fomr ~112MB to 3.5 MB. In my opinion, there is no need to use Draco for small meshes, that’s why I have put Draco compression as optional.
It is possible to inspect the textures of a glb file with gltfktx gltf-transform inspect out.glb.
Additional steps when loading the compressed assets in three.js
To load an asset with KTX2 compressed texture in Three.js, we have to pass the KTX2Loader to the GLTFLoader.
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
const ktx2Loader = new KTX2Loader()
.setTranscoderPath('three/examples/jsm/libs/basis/')
.detectSupport(renderer);
const loader = new GLTFLoader().setKTX2Loader(ktx2Loader);
If the assets has also been compressed with draco, you need to pass the DRACOLoader
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
const dracoLoader = new DRACOLoader()
.setDecoderPath('three/examples/jsm/libs/draco/');
const ktx2Loader = new KTX2Loader()
.setTranscoderPath('three/examples/jsm/libs/basis/')
.detectSupport(renderer);
const loader = new GLTFLoader()
.setDRACOLoader(dracoLoader)
.setKTX2Loader(ktx2Loader);