Splitting sprites (texture atlases) into tiles with three.js - three.js

Question

The goal is to create many thumbnails from a given set of pictures, assuming all thumbnails have same dimensions.
https://threejs.org/examples/#misc_ubiquity_test2 is a nice example showing the texture.wrapS/texture.wrapT + texture.offset approach, but it means cloning a texture for each thumbnail, that has performance implications. A question is: how to reuse a single texture?
Having the 16384x16384px limit in mind, another aspect to cover is: how to prepare multiple sprites, load corresponding textures and distribute them among tiles (thumbnails)?

Answer 1

Preparing the sprites
Assumptions:
original assets have the same aspect ratio, e.g. ~1.485 (2894x1949px)
we're about to render 128 thumbnails in the end
imagemagic is installed
./assets/images/thumbnails/ is a working directory for manipulations
./assets/images/sprite-0.jpg, ..., ./assets/images/sprite-<n>.jpg will be actual sprites - horizontal atlases (single rows of tiles)
First off, let's define desired thumbnail dimensions. Since three.js requires each texture dimension to be a power of 2, a height could be set to 256px, making a width equal 380px. This means 43 tiles per sprite (43*380=16340, where 16384 is a limit for the total width).
Building a single sprite
Cleanup ./assets/images/thumbnails/original-selected/ and copy a portion of 43 original assets there.
Execute a set of steps listed below.
Rename a resulting sprite.jpg into sprite-<iteration>.jpg.
Steps
Generate small assets:
$ mogrify -path ./assets/images/thumbnails/small/ -resize 380x256 ./assets/images/thumbnails/original-selected/*.png
Build a sprite out of small assets:
$ convert +append ./assets/images/thumbnails/small/*.png ./assets/images/sprite.png
Note that the sprite now is 16340x256, so it has to be resized to 16384x256 for
both dimensions to be a power of 2 (otherwise three.js will do that on the fly):
$ convert -resize 16384x256\! ./assets/images/sprite.png ./assets/images/sprite.png
Finally, convert the sprite to JPEG, reducing the size:
$ convert -quality 85 ./assets/images/sprite.png ./assets/images/sprite.jpg
Loading textures and creating thumbnails
Tiling itself (setting the geometry.faceVertexUvs value) is inspired by https://solutiondesign.com/blog/-/sdg/webgl-and-three-js-texture-mappi-1/19147
import {Scene, Texture, TextureLoader, Vector2, PlaneGeometry, BufferGeometry, MeshBasicMaterial, Mesh} from 'three';
const thumbnailWidth = 380;
const thumbnailHeight = 256;
const thumbnailsCount = 128;
const spriteLength = 43;
const spriteUrlPattern = 'assets/images/sprite-<index>.jpg';
const scene = new Scene();
const loader = new TextureLoader();
loadAllTextures()
.then(initializeAllThumbnails);
function loadAllTextures(): Promise<Texture[]> {
const spritesCount = Math.ceil(thumbnailsCount / spriteLength);
const singlePromises = [];
for (let i = 0; i < spritesCount; i += 1) {
singlePromises.push(loadSingleTexture(i));
}
return Promise.all(singlePromises);
}
function loadSingleTexture(index: number): Promise<Texture> {
const url = spriteUrlPattern.replace('<index>', String(index));
return new Promise((resolve) => {
loader.load(url, resolve);
});
}
// Tiles are taken from different sprites,
// so thumbnail meshes are built using corresponding textures.
// E.g. given 128 tiles packed into 3 sprites,
// thumbnails 0..43 take the 1st texture, 44..86 - the 2nd one and so on.
function initializeAllThumbnails(allTextures: Texture[]) {
const baseGeometry = new PlaneGeometry(thumbnailWidth, thumbnailHeight);
const materials = allTextures.map((texture) => new MeshBasicMaterial({
map: texture,
}));
for (let thumbnailIndex = 0; thumbnailIndex < thumbnailsCount; thumbnailIndex += 1) {
const geometry = getThumbnailGeometry(thumbnailIndex, baseGeometry);
const materialIndex = Math.floor(thumbnailIndex / spriteLength);
const material = materials[materialIndex]; // could be cloned in here, if each material will need individual transformations, e.g. opacity
const mesh = new Mesh(geometry, material);
scene.add(mesh);
}
}
function getThumbnailGeometry(thumbnailIndex: number, baseGeometry: PlaneGeometry): BufferGeometry {
const tileWidth = 1 / spriteLength;
const tileIndex = thumbnailIndex % spriteLength;
const offset = tileIndex * tileWidth;
// +---+---+---+
// | 3 | . | 2 |
// +---+---/---+
// | . | / | . |
// +---/---+---+
// | 0 | . | 1 |
// +---+---+---+
const tile = [
new Vector2(offset, 0),
new Vector2(offset + tileWidth, 0),
new Vector2(offset + tileWidth, 1),
new Vector2(offset, 1),
];
const plainGeometry = baseGeometry.clone();
const bufferGeometry = new BufferGeometry();
// a face consists of 2 triangles, coords defined counterclockwise
plainGeometry.faceVertexUvs[0] = [
[tile[3], tile[0], tile[2]],
[tile[0], tile[1], tile[2]],
];
bufferGeometry.fromGeometry(plainGeometry);
return bufferGeometry;
}