With thanks to Tom MacWright for both the inspiration and the means, my “Bandcamp wrapped” for 2024:

SABLE, by Bon Iver

Public Void by Penelope Scott

Nine Waves by Ye Vagabonds

Kantos by Kishi Bashi

How Long Do You Think It's Gonna Last? by Big Red Machine

Not Before Time...39 Years in the Making by Páraic Mac Donnchadha

Blake & Rice by Norman Blake

Return to Kintail by Alasdair Fraser

A Glint o' Scottish Fiddle by Patsy Reid

The Bright Hollow Fog by Marla Fibish

I'm a Rover by Ye Vagabonds

Psychopomp by Japanese Breakfast

Bright Future by Adrianne Lenker

Inside Problems by Andrew Bird

Salt by Angie McMahon

Vulture Prince by Arooj Aftab

Omoiyari by Kishi Bashi

Outside Problems by Andrew Bird

¹ I overshot this goal somewhat. :)

Emission

Emission models the contribution of light from a surface, in addition to any light already reflected from that surface. In a physically-based path tracer like Blender's Cycles, or a realtime renderer with support for global illumination (GI), emission works as you'd expect: the surface emits light, and illuminates nearby objects like any other light source. But these types of renderers tend to be very advanced, or slow, or both.

Most realtime renderers use local illumination, and emission brightens only the emissive surface itself.

The emissive boxes in the illustration above each have emissive color #59BCF3, intensities increasing from 1 to 256 nits from left to right. Tone mapping causes the brighter boxes to desaturate toward white.^[1] The emissive surfaces are visible in the dimly-lit scene, but they aren't illuminating other objects.

Even limited to local illumination, we can create a much better illusion of brightness than this. We'll first light the scene independently, then create a glow called a bloom effect around the emissive surfaces.

Bloom

Bloom emulates an imaging artifact present in physical cameras, in which fringes surround the brightest areas of the image, “contributing to the illusion of an extremely bright light overwhelming the camera or eye.” (Wikipedia)

Many 3D applications already have the bloom effect available as a post-processing option. But how should emissive surfaces, the surrounding scene, and the bloom effect be configured for best results?

Configuring a scene for emission and bloom

First, create a scene with the lighting, composition, and exposure you prefer. Enable tone mapping from the beginning, so that you're making initial lighting choices based on a fully-formed image. Point lights may be placed at the locations of the emissive objects, or lighting can be baked into surrounding materials.

Emissive surfaces intended to bloom should have higher total luminance than the surrounding scene, often using open domain [0, ∞] linear intensities.^[2][3] We're trying to give the illusion that the emission has overwhelmed a camera sensor with its brightness.

Non-emissive surfaces are under varying lighting conditions, and may have strong reflective highlights. Unless you want to see bloom from reflected highlights — a stylistic choice — make it easy on yourself by using a much higher intensity for the emissive surfaces. When emissive surfaces are sufficiently bright, there's room to adjust lighting and the luminance threshold toward an overall look. If you can't isolate the effect to the intended surfaces, the surfaces are probably not bright enough.

Pixels above the luminance threshold will bloom, creating a glow in screen space. In three.js, the bloom threshold is defined in luminance, measured with weights for the spectral sensitivity of human vision,^[4] also called luma coefficients. With emissive color #FF00FF and an intensity of 100 nits, a luminance threshold of 99 nits will not show visible bloom, due to the luma coefficients.

Luminance = 0.2126 x Red + 0.7152 x Green + 0.0722 x Blue

Finally, remember that tone mapping and conversion to the color space of the HTML canvas context are necessary steps in forming an image from our [0, ∞] linear data, and should be applied after the bloom effect. Other post-processing effects using physically-based units may come before tone mapping.

The 3D scene used throughout this article comes from the glTF Emissive Strength Test model, with modifications. Settings for materials, lighting, and post-processing in the final render, with three.js units:

Thanks for reading, and please reach out with any questions!

¹ Brighter boxes would appear white without tone mapping, too, as their values clip the limits of the [0, 1] drawing buffer. Before reaching white, they would first clip to one of the “Notorious Six”, or #00FFFF in this case. Tone mapping is a necessary step in forming an image from lighting data, and helps to avoid clipping and the Notorious Six.

² I avoid using “HDR” as a synonym for linear [0, ∞] RGB data. HDR has multiple meanings, often used imprecisely, and is not necessarily linear. In three.js, the working color space is Linear sRGB: Rec. 709 primaries, D65 white point, and a linear transfer function.

³ The domain [0, ∞] is theoretical. A 32-bit floating point render target has a maximum value around 3.40 × 10³⁸, with lower precision as values approach that limit. Rendering pipelines may have further limitations, such as 16-bit render targets.

⁴ More precisely, for the CIE Standard Observer.

However, there's more than one way to package a glTF file. One of those ways, often called “glTF Embedded,” uses Data URLs and loses many of those benefits. This might not matter for someone using glTF as an interchange format between two desktop applications, or loading 3D models into a game engine that compiles to engine-specific formats. But for anyone using glTF for last-mile transmission to a realtime application, the “glTF Embedded” packaging method is cursed.

Regularly I've seen developers exporting models to “glTF Embedded,” understandably not knowing why it's any different, and then needing support to diagnose and fix performance issues. This wastes time for everyone — for developers trying to build great 3D experiences, for volunteers providing support on community forums, and for end-users waiting on slow 3D experiences.

Other ways of packaging glTF files are unambiguously better. The “glTF Embedded” method should be avoided except for debugging, if it's supported at all.

Packaging glTF models

.glb models are binary, standalone files. By convention, GLB files are self-contained. Textures and other resources are embedded in the file, as binary data, following a short JSON header. This is the most common glTF packaging method.

.gltf models are human-readable JSON, and should reference external files for binary data and textures. Open a .gltf file in any text editor, and you'll see something like this:

{
    "asset": {
        "version": "2.0",
        "generator": "Khronos glTF Blender I/O v4.0.44",
    },
    "extensionsUsed": ["KHR_materials_unlit"],
    "scenes": [ ... ],
    "nodes": [ ... ],
    "meshes": [ ... ],
    "materials": [{
        "pbrMetallicRoughness": {
            "baseColorFactor": [ 1, 1, 1, 1 ],
            "baseColorTexture": { "index": 0 }
        }
    }],
    "textures": [ ... ],
    "images": [ { "uri": "base_color.png" }, { "uri": "normal.png" } ],
    "buffers": [ { "uri": "geometry.bin", "byteLength": 3240 } ],
    ...
}

JSON is convenient. With JSON, you can edit materials and other non-binary definitions in a text editor.^[2] And notice the URLs for images and buffers above: these are external files with .png, .jpg, .webp, or .ktx2 extensions for textures, or .bin extensions for geometry and animation data.

What if we wanted to embed these images and buffers in the JSON? In a .glb, appending binary chunks to a binary format is no problem. But JSON can't store binary data directly, and we instead need to use Data URLs and Base64:

{
    ...
    "images": [ { "uri": "data:image/png;base64,iVBORw0K..." }],
    "buffers": [ { "uri": "data:application/octet-stream;base64,iVBORw0K..." }],
}

Combining these choices, we get three common presets for packaging glTF files:^[3]

The first two presets are great! Use GLB if you want a self-contained file. Use “glTF Separate” if you want human-readable JSON or external textures. But “glTF Embedded” encodes buffers as Data URLs, taking a heavy performance penalty.

The problem with Data URLs

Data URLs are common enough in web development. HTTP requests cost some overhead, and webpages can have many small resources like icons, stylesheets, and scripts. The overhead adds up, so we might embed the smallest resources — below some size threshold — into the initial HTML page request. Data URLs are fine for that.

But this scenario doesn't translate well to 3D scenes. Performance requires batching resources on the GPU. We only get so many textures per material, we can't have fewer draw calls than we have materials, and so lots of tiny images aren't practical. Instead we have a smaller number of larger 2K-4K images, and heavy binary resources like geometry and animation keyframes. Even properly optimized, these can be much larger than the resources on a traditional webpage.

So here's the first problem: Data URLs increase data size by +33%.

// create binary 'geometry'.
const bytes = new Uint8Array(1024).map(() => Math.random() * 255);
bytes.byteLength; // 1024 bytes

// convert to base64 Data URL.
const base64 = btoa(String.fromCharCode.apply(null, bytes));
const bytesBase64 = new TextEncoder().encode(base64);
bytesBase64.byteLength; // 1368 bytes

Worse, the data is no longer GPU-ready — it's encoded as ASCII characters! On each device that renders the 3D scene, we're going to have to decode every byte on the CPU up front. Peter McLachlan ran the numbers on mobile devices loading images from Data URLs:^[4]

“... you can imagine my surprise to discover, when measuring the performance of hundreds of thousands of mobile page views, that loading images using a data URI is on average 6x slower than using a binary source link such as an img tag with an src attribute!”

And here's the second problem: That's entirely unnecessary work. We took binary GPU-ready data, encoded it in a larger plaintext format, sent that larger data over the network, and then made each viewer's device spend time translating it back to something the GPU understands.

Conclusion

Arguably, Data URLs should not have been included in the glTF specification. I don't recall the reasons for allowing them, but based on recent feedback to Blender removing the “glTF Embedded” export option (and later reverting that change) the convenience of human-readable, self-contained JSON is a big factor.

Unfortunately I see a lot of people in the WebGL and WebGPU communities taken by surprise with performance problems caused by Data URLs in their applications, then understandably not knowing what's wrong. In some cases Data URLs have lead to negative perceptions of the entire glTF format. glTF isn't the only cause. Popular JavaScript bundlers with the wrong configuration can inline binary resources — of any format — into large Data URLs, too. It's a footgun, and explaining details of file formats to users doesn't scale. Tooling needs better guard rails, and warnings when Data URLs exceed some size threshold.

As general rules for performance-sensitive applications:

• For a self-contained binary file, use .glb.
• For a human-readable JSON file, use .gltf with external resources (“glTF Separate”).
• DO NOT use self-contained .gltf files with embedded resources (“glTF Embedded”), outside of debugging.

If you have glTF files already using “glTF Embedded” and want to losslessly convert to another glTF packaging method, you can. Install Node.js, and then open a terminal.

# one-time installation
npm install --global @gltf-transform/cli

# glb
gltf-transform cp input.gltf output.glb

# gltf separate
gltf-transform cp input.gltf output.gltf

¹ I'm using the term “GPU-ready” somewhat optimistically when referring to images. Some image formats are GPU-compatible, others are not. See my previous post, Choosing texture formats for WebGL and WebGPU applications, for more on image formats in 3D models.

² Optionally, there's a great VSCode plugin.

³ Technically, exporters could mix and match. A binary .glb could contain Data URLs; a .gltf could contain some Data URLs but also have external binary resources. But these presets cover 99% of use cases.

⁴ On Mobile, Data URIs are 6x Slower than Source Linking, July 2013.

Image formats (PNG, JPEG, WebP, AVIF)

Most image formats used on the web are optimized for two goals:

1. minimize file size transferred over a network
2. maximize image quality

As of 2024, that generally means using WebP and AVIF for modern browsers, or PNG and JPEG for older browsers.^[1] But when building for WebGL and WebGPU APIs, where high framerates and memory budgets are hard constraints, several more goals should be considered:

1. avoid framerate stalls when the texture loads
2. minimize memory cost
3. maximize application performance

When users can do more than just look at an image, spending significant time in a 2D or 3D application — games, immersive AR/VR experiences, or interactive storytelling — framerate stalls can be disastrous. Most image formats (including all formats mentioned above) must be decompressed on the CPU, then uploaded without compression to GPU memory. One 4096x4096px image with mipmaps consumes 90 MB of memory, regardless of how small the original file might have been.

uncompressedSize = <width> ⨉ <height> ⨉ 4 ⨉ 1.333

On many platforms, RGB textures are expanded to RGBA for compatibility reasons, so it's safer to assume all four channels are stored in memory. Multiply by 1.333 to include mipmaps.

Decompression and upload prevent WebGL from doing other work, a very common source of dropped frames. In WebXR, users experience dropped frames as an unexpected lurch and a major cause of motion sickness.

Specialized GPU texture formats (ETC, ASTC, BC1–7, PVRTC)

To avoid these issues, GPUs are designed with built-in support for specialized image formats, called “GPU texture formats.” In these formats, pixel data remains compressed on the GPU, and each pixel is decompressed (with no meaningful performance cost) each time a shader samples the texture. No decompression is required before GPU upload, memory cost is reduced by 4–8x, and uploads complete 4–8x faster.

Inconveniently, different platforms and GPUs require different GPU texture formats. Historically, game developers supporting multiple platforms ship different compressed texture formats — ETC, ASTC, BC1–7, or PVRTC — for different platforms.

While this strategy would also work on the web, it can be burdensome for individual developers and small teams, and these textures tend to be larger files. And while GPU texture formats can provide excellent quality with the right format choices and compression settings, they're much less forgiving about configuration and quality than traditional image formats. Careful tuning of compression parameters should be expected.

Universal GPU texture formats (Basis ETC1S and UASTC)

Texture compression became far more practical in 2019, when Binomial (in partnership with Google) released the open source Basis Universal family of compression codecs. These codecs are designed to be efficiently transcoded (not decompressed) at runtime into a variety of GPU texture formats. Any modern device receiving Basis Universal textures can load and display them efficiently.^[2]

The Basis Universal family includes two codecs:

• ETC1S: Also called “BasisLZ.” Low/medium quality, with small file sizes comparable to JPEG. Default choice in most cases. ETC1S works well on color textures, but not as well on data textures like normal maps.
• UASTC: Higher quality, comparable to BC7. Quality is sufficient for both color and data textures, including normal maps. UASTC data is larger than ETC1S, but benefits from an additional pass of lossless compression (”supercompression”). Most KTX2 compressions apply Zstandard compression^[3] on top of UASTC, producing compressed files 1-2x larger than JPEG or ETC1S textures with the same resolution.

ETC1S and UASTC are low-level codecs, not file formats. To create files using either codec, use the KTX2 file format.^[4] KTX2 is a thin container, carrying required metadata like texture dimensions and color spaces along with compressed or uncompressed pixel data. KTX2 supports Basis Universal codecs and many GPU texture formats.

Like GPU texture formats, Basis Universal formats require more careful compression settings than traditional image formats. The same options will not work for all models, but do generalize per material slot. For example, one set of compression options works well for diffuse color textures, another set of options works well for normal maps.

To get started with KTX2 and Basis Universal, see the KTX2 Artist Guide and KTX-Software project from the Khronos Group.

How to choose

When First Contentful Paint is the top priority, minimize file size by using modern image formats like WebP and AVIF. Simple 2D/3D visuals, like a landing page graphic, will probably fall into this category.

When users will spend more time with the application, or the application is loading a lot of textures interactively, then the advantages of KTX2 textures with Basis Universal compression are significant. In this situation, KTX2 should often be preferred over traditional image formats.

When it's most important for textures be compatible with many different applications, or to keep original image quality, stick to JPEG and PNG. Libraries of reusable textures and 3D models are good examples of this situation.

For more help choosing among common texture formats, refer to glTF Texture Formats from the KTX2 Artist Guide.

¹ Often we use SVGs and icon fonts instead of images, too. But that's less applicable with 3D graphics APIs, and outside the scope of this article.

² Basis Universal transcoders select a target GPU texture format based on the current device's capabilities. The specific target format chosen is generally an implementation detail, but if you're looking for those details, see the Khronos Group's KTX2 WebGL Developer Guide.

³ Loaders can decode Zstandard supercompression off the main thread, and UASTC pixel data is still 4x smaller than JPEG or PNG, so Zstandard doesn't significantly reduce the memory benefits of Basis Universal formats.

⁴ When working with Basis Universal compression, you may see .basis file extensions. This is a similar container format to KTX2, specifically for Basis Universal, and the compressed texture data will be identical. KTX2 is the standardized container format, provides additional texture formats and supercompression, and is required to use Basis Universal in glTF files.

Basics

• 📬 Mail Client: Spark Mail
• 📮 Mail Server: FastMail and Gmail
• 🗒️ Notes: Obsidian (slowly migrating from Notion)
• ✅ To-Do: Moleskine Actions
• 🌅 Photo Management: Adobe Lightroom
• 📆 Calendar: Moleskine Timepage
• 📦 Cloud file storage: iCloud and Google Drive
• 📖 RSS: Readwise Reader
• 👥 Contacts: Apple Contacts
• 🌐 Browser: Arc
• 💬 Chat: too many things
• 🔖 Bookmarks: Readwise Reader
• 📑 Read It Later: Readwise Reader
• 📝 Word Processing: iA Writer
• 📈 Spreadsheets: Google Sheets
• 📊 Presentations: iA Presenter
• 🛒 Shopping Lists: Moleskine Actions
• 🥘 Meal Planning: Paprika
• 💸 Budgeting & Personal Finance: Soulver and Google Sheets
• 🗞️ News: The New York Times, Rest of World, and RSS
• 🎹 Music: Bandcamp and Doppler
• 🎙️ Podcasts: Overcast
• 🔑 Password Management: 1Password

Prompts above are from the App Defaults template, with icons from micro maique.

Other

• Backups: Backblaze and macOS Time Machine (my setup)
• Code Editor: VSCode and Sublime Text
• Git: Graphite
• Graphic Design: Affinity Designer
• Maps: Transit and Google Maps
• Music Organization: Meta and Mp3Tag
• Social Media: Ivory for Mastodon
• Terminal: iTerm2
• Web Hosting: Vercel and Google Cloud Storage

Prompts here are my own additions.

Thanks for reading! If you have questions or want to start a fight over any of these, I'm on Mastodon.

Founded in 2012 as “CartoDB”, CARTO originally made open source tools for building maps on PostGIS. The product has since evolved well beyond that — integrating with data warehouses including Google BigQuery, Amazon Redshift, Snowflake, and Databricks — and offers a suite of tools and applications for geospatial analysis, visualization, and data science.

As a software developer at CARTO, my work impacts first-party applications like CARTO Builder, and popular open source libraries for large-scale geospatial visualization, including deck.gl and luma.gl.

This will be a short, technical post explaining how to create a glTF 3D model programmatically, using the glTF Transform (gltf-transform.dev) JavaScript library. The library weighs about 20kb minzipped, and is much smaller than a full 3D engine like three.js or babylon.js.

First, we're going to need some vertex data! glTF supports points, lines, and triangle meshes. The details here depend entirely on what you're trying to create, but let's start with a torus (a.k.a. “donut”). three.js has open-source implementations of many common 3D shapes, and I've copied the relevant section of THREE.TorusGeometry below, removing dependencies on three.js itself.

// MIT License. Copyright © 2010-2023 three.js authors.

function createTorus(radius = 1, tube = 0.4, radialSegments = 12,tubularSegments = 48, arc = Math.PI * 2) {

    const indicesArray = [];
    const positionArray = [];
    const uvArray = [];

    const vertex = [0, 0, 0];

    // generate positions and uvs
    for (let j = 0; j <= radialSegments; j++) {
        for (let i = 0; i <= tubularSegments; i++) {
            const u = (i / tubularSegments) * arc;
            const v = (j / radialSegments) * Math.PI * 2;

            // position
            vertex[0] = (radius + tube * Math.cos(v)) * Math.cos(u);
            vertex[1] = (radius + tube * Math.cos(v)) * Math.sin(u);
            vertex[2] = tube * Math.sin(v);
            positionArray.push(vertex[0], vertex[1], vertex[2]);

            // uv
            uvArray.push(i / tubularSegments);
            uvArray.push(j / radialSegments);
        }
    }

    // generate indices
    for (let j = 1; j <= radialSegments; j++) {
        for (let i = 1; i <= tubularSegments; i++) {
            // indices

            const a = (tubularSegments + 1) * j + i - 1;
            const b = (tubularSegments + 1) * (j - 1) + i - 1;
            const c = (tubularSegments + 1) * (j - 1) + i;
            const d = (tubularSegments + 1) * j + i;

            // faces

            indicesArray.push(a, b, d);
            indicesArray.push(b, c, d);
        }
    }

    return { indicesArray, positionArray, uvArray };
}

The createTorus() function above provides arrays of vertex positions and UVs, and indices for triangles connecting those vertices. Replace all this with your own geometry, if you want.

Next we need to assemble the vertex data into a glTF 2.0 file. First we'll create a new glTF Transform document, and a buffer to store our data.

import { Document } from '@gltf-transform/core';

const document = new Document();
const buffer = document.createBuffer();

Next we'll take the vertex data we generated above, and use it to create a mesh.

const { indicesArray, positionArray, uvArray } = createTorus();

// indices and vertex attributes
const indices = document
    .createAccessor()
    .setArray(new Uint16Array(indicesArray))
    .setType('SCALAR')
    .setBuffer(buffer);
const position = document
    .createAccessor()
    .setArray(new Float32Array(positionArray))
    .setType('VEC3')
    .setBuffer(buffer);
const texcoord = document
    .createAccessor()
    .setArray(new Float32Array(texcoordArray))
    .setType('VEC2')
    .setBuffer(buffer);

// material
const material = document.createMaterial()
    .setBaseColorHex(0xD96459)
    .setRoughnessFactor(1)
    .setMetallicFactor(0);

// primitive and mesh
const prim = document
    .createPrimitive()
    .setMaterial(material)
    .setIndices(indices)
    .setAttribute('POSITION', position)
    .setAttribute('TEXCOORD_0', texcoord);
const mesh = document.createMesh('MyMesh')
    .addPrimitive(prim);

While glTF can be used to store a mesh all by itself, it's far more common to place the mesh within a default scene. This ensures everything shows up as expected in various 3D viewers. We'll add the mesh to a node, and put that node in a scene. If we had multiple meshes, we might assign different position/rotation/scale to each node.

const node = document.createNode('MyNode')
    .setMesh(mesh)
    .setTranslation([0, 0, 0]);

const scene = document.createScene('MyScene')
    .addChild(node);

Finally, we're ready to save the result as a new glTF file. I/O depends on the environment where we're running the code, so select the appropriate option below.

import { NodeIO } from '@gltf-transform/core';

const io = new NodeIO();
await io.write('./torus.glb', document);

import { DenoIO } from '@gltf-transform/core';

const io = new DenoIO();
await io.write('./torus.glb', document);

import { WebIO } from '@gltf-transform/core';

const io = new WebIO();
const bytes = await io.writeBinary(document); // → Uint8Array

That's it — you've got a shiny new glTF 2.0 file:

The glTF Transform library, as the name hints, can do a lot more than create new files. It's more often used for optimizing existing glTF files, and we could do the same here by adding Draco compression to our model. Consider that an exercise for the reader.

Thanks for reading, and please reach out with any questions!

That's a loss — not because maintainers of free software owe anyone commitments, but because the unstated status quo presumes this support. Maintainers will consciously understand that no such obligation exists, but still feel a presure to provide indefinite and unsustainable support. And that dynamic contributes to an extractive open source ecosystem.

A series of kindnesses

While open source can be funded well and sustainably maintained, it usually isn't: valuable work is created in someone's free time, given away, and used in commercial and non-commercial pursuits alike, without compensation or reciprocation.

Open source is “a series of kindnesses,”^[2] and maintainers are under no obligation to provide support. We are not suppliers.^[3] Writing software and giving it away is a kindness. Answering a question is a kindness. Fixing a bug is a kindness. Building a new feature and contributing it back to a project is a kindness. Accepting a pull request, then maintaining that code indefinitely, is a kindness.

I've been wondering: would open source work better for maintainers if expectations on support were stated up front? The clarity could directly benefit maintainers and users, and studies based on these statements could spark conversations about compensation and business models in open source.

Categories

I'm aware of few attempts to categorize open source lifecycles, and no detailed studies.^[4] I have not found any formal definition of open source support, or of its varying degrees. So I've made the attempt here, for myself.

My categorization covers three areas: Maturity, Development, and Support. Each is value-neutral. We'd all prefer more support than less from projects we depend on, but can't disparage the choice to give one's time and work away, or the boundaries of the gift.

Projects that afford incentives and income to maintainers tend to provide more in all three categories. While it's not uncommon for high-quality open source projects to begin as a labor of love, sustaining development and support over a long period is difficult without meaningful support for maintainers, and these projects inevitably shift into less-active modes without support and incentives.

Maturity

Status or phase in project's lifecycle. Indicative of maturity, quality, and stability.

• Stable: Project achieves its stated goals with a high level of quality and reliability. While certain areas of the project may remain experimental, the project as a whole is more mature, and the authors have some degree of confidence in its correctness and stability.
• Experimental: Exploration, idea generation, early development, or research. May solve a particular use case for the maintainer, while remaining unstable for broader use. Creation of experimental software does not necessarily represent a commitment to bring that software to maturity.
• Deprecated: Previously stable or experimental projects may become deprecated, indicating that a project's use is no longer recommended. Deprecation usually implies inactive development and support. Causes for deprecation may include lack of time and incentives for development and support, degradation in the codebase, or wider changes in the software ecosystem.

Development

Current level of maintainer activity on the project.

• Active: Frequent contributions toward feature and maintenance goals.
• Maintenance: Bugs, compatibility issues, and security risks are addressed periodically, but new feature development is not expected. Projects may enter maintenance development due to limited developer time and incentives, or because the project is feature-complete within its intended scope.
• Unmaintained: Neither new features nor maintenance are planned. Most projects cannot remain both unmaintained and stable indefinitely, as dependencies shift and bitrot accumulates. Unmaintained status is common for older experimental projects, and implicit for archived projects.

Support

Level of support (for bug reports, feature requests, and help tickets^[5]) provided to users of the project.

• Active: Project provides a place to file tickets. Maintainers welcome these discussions, and intend to read and respond regularly.^[6]
• Limited: Project provides a place to file tickets. Maintainers welcome these discussions, but cannot review tickets regularly. Delays should be expected, and some tickets may not receive a response.
• Self-service: Project is provided as-is. Maintainers decline to provide support. Questions should be directed to Stack Overflow or similar websites.

There's room for exploration in Support — the three levels above are not exhaustive! Find creative ways to support open source work. Maybe reserve help tickets for noncommercial users, sponsors, and paying customers.^[7] Consider selling SLAs. More experimentation on open source business models would be a healthy thing.^[8]

Applying the definitions

I'm in the process of reviewing my own open source projects, and plan to categorize each project in the three areas above. Badges may be created with Shields.io, and a project's README may include details or exceptions.

Examples:

I'm curious how these definitions resonate with open source maintainers, and users of open source software. Are the categories missing something important? Is something gained — or lost^[9] — in stating a support policy for an open source project? I am active on Mastodon these days, and welcome questions and ideas.

¹ The Software Package Data Exchange (SPDX). I'm no longer sure whether this is a good thing. On one hand, SPDX encourages corporations to choose use open licenses, and prevents license-compatibility nightmares. On the other hand, SPDX takes away tools that could benefit indie developers, like non-commercial licenses. SPDX does not generally grant these licenses identifiers for use in package registries.

² Setting expectations for open source participation, by Brett Cannon.

³ I am not a supplier, by Thomas Depierre.

⁴ Inspired by the Linux Foundation's The Life Cycles of Open Source Projects and Formidable's OSS Maintenance Levels.

⁵ I've intentionally avoided distinguishing between “bugs”, “feature requests”, and “support”. The difference is often known only to a project's maintainers, and accepting one kind of support ticket means dealing with them all.

⁶ I've intentionally avoided defining “regularly”. This is a hint about maintainer intention — not an obligation. Fixed support schedules are not a reasonable expectation, outside the context of a paid Service Level Agreement (SLA).

⁷ OSI's The Open Source Definition states — controversially — that licenses containing restrictions against “fields of endeavour” cannot be considered open source. Even so, maintainers can certainly be selective about time spent on support.

⁸ See Indie Open Source.

⁹ One real fear I have is that maintainers will — wanting others to choose their software — promise levels of support they cannot sustain, that users will prefer those projects until their maintainers burn out, and that the status quo will deepen. Meaningful incentives are required to sustain support, and problems of support and compensation are closely linked.

WebAssembly (WASM) is a compilation target for other programming languages. It runs in many computing environments, and it runs fast. Typically a WebAssembly module begins life as C/C++, Rust, or AssemblyScript source code. A toolchain compiles the source code to a .wasm binary, and that binary is loaded into environments like web browsers and Node.js.

AssemblyScript — heavily inspired by TypeScript — will be more approachable to web developers than C/C++ or Rust, and we'll focus on AssemblyScript here.

This post explains how to set up a new AssemblyScript project, compile that project as a WebAssembly module, write unit tests, and publish the package to npm. We'll spend some time on compatibility, so that the same npm package works well in web pages, Node.js, and bundlers.

If you're new to AssemblyScript, reading an introduction to the language may be worthwhile. While I've claimed above that WebAssembly is fast, new code still needs to be optimized, and this requires thinking about issues that web developers typically don't. Read Surma's excellent post, Is WebAssembly magic performance pixie dust?, for an introduction to optimizing AssemblyScript code.

Setting up a new project

NOTE: This section mirrors AssemblyScript's own tutorials. If my post falls out of date, prefer the official documentation.

With a recent version of Node.js installed, run the following steps in a new directory:

# Initialize an empty npm package.
npm init

# Install the AssemblyScript compiler.
npm install --save-dev assemblyscript

# Generate AssemblyScript project structure
npx asinit .

The last step creates several folders and files in the project directory. These are worth mentioning:

• ./assembly/index.ts — Our AssemblyScript entry point. Functions exported here will be available through our WASM module.
• ./build/ — WASM modules and JavaScript bindings will be compiled into this folder. Don't hand-edit these files. You may include them in Git, but I typically don't.
• ./asconfig.json — Configuration for the AssemblyScript compiler.

The files below can be deleted. We'll set up more helpful unit tests later.

• ./tests/index.js
• ./index.html

Then, create a src/ folder and two empty source files, which we'll use to load our WASM module and create a clean TypeScript API around it. If you'd prefer to use JavaScript instead of TypeScript, feel free.

• ./src/index.ts
• ./src/wasm.ts

Compile AssemblyScript to WebAssembly

The default assembly/index.ts defines a simple function adding two integers:

// The entry file of your WebAssembly module.

export function add(a: i32, b: i32): i32 {
    return a + b;
}

Let's leave that alone and compile it. An asbuild script is already defined in our package.json file, which we can execute:

npm run asbuild

The compiler builds our WebAssembly binaries and JavaScript bindings, and puts release and debug builds in the build/ folder. Open the release bindings in build/release.js, and you'll see something like this toward the end of the file:

export const { ... } = await (async url => instantiate(
    await (async () => {
        try { return await globalThis.WebAssembly.compileStreaming(globalThis.fetch(url)); }
        catch { return globalThis.WebAssembly.compile(await (await import("node:fs/promises")).readFile(url)); }
    })(), {
    }
))(new URL("release.wasm", import.meta.url));

If we only wanted drop these files into a web or Node.js application, this might be fine. But when publishing a package for npm, there are a few problems above. While an application might happily ignore the import("node:fs/promises") code unless it hits the catch block, our users' bundlers might not. Moreover, older bundlers don't support import.meta.url, and cannot manage static binary resources.

We'll dive deeper into both of those compatibility issues in a later section, but for now let's just strip out the problematic bindings by changing the AssemblyScript configuration. In asconfig.json, set "bindings": "raw" under the compiler options:

{
    ...
    "options": {
        "bindings": "raw"
    }
}

Now run "npm run asbuild" again, and the problematic parts of our build/release.js bindings should be gone.

Writing the wrapper

Wrapping AssemblyScript's output with hand-written code isn't strictly necessary, but I'd encourage it when publishing the package to npm. Wrapping allows us to:

1. Make the package easier to import for our users
2. Display documentation with JSDoc
3. Provide more specific TypeScript hints
4. Perform input validation before data is passed into the WASM module^[1]
5. Implement features that would be difficult or slow in WASM^[2]

WebAssembly and its various toolchains will improve, and I expect this list to be shorter in a few years.

Let's start by writing a simple wrapper that supports only Node.js, and in the next section we'll adapt it for other environments. Without modifying ./assembly/tsconfig.json (which affects our AssemblyScript compilation), we'll add a new file, ./tsconfig.json, for our TypeScript wrapper. Replace "my-package" with whatever package name you prefer.

{
    "compilerOptions": {
        "paths": {
            "my-package": ["./"]
        },
        "typeRoots": ["node_modules/@types"],
        "moduleResolution": "node",
        "module": "ESNext",
        "lib": ["ESNext", "DOM"],
        "target": "ESNext",
        "declaration": true,
        "strict": true
    },
}

In src/wasm.ts, write:

// src/wasm.ts — Placeholder WASM loader.
import { readFile } from 'node:fs/promises';
const wasmURL = /* #__PURE__ */ new URL('./release.wasm', import.meta.url);
const wasm = /* #__PURE__ */ readFile(wasmURL);
export default wasm;

Here, we're loading the WASM binary from a TypeScript module^[3] we define, which we'll override for different environments later. The #__PURE__ */ annotations allow bundlers to strip away (or "tree-shake") our WASM binary if the application never uses it. While optional, this will be important if our package has multiple WASM modules, or becomes an optional dependency of other downstream packages.

In src/index.ts (not assembly/index.ts), add the wrapper:

// src/index.ts
import wasm from './wasm';
import { instantiate, __AdaptedExports } from '../build/release';

// Initialization.

let exports: typeof __AdaptedExports;

/* Promise resolving when WebAssembly is ready. */
export const ready = /* #__PURE__ */ new Promise<void>(async (resolve, reject) => {
    try {
        const module = await WebAssembly.compile(await wasm);
        exports = await instantiate(module as BufferSource, {});
        resolve();
    } catch (e) {
        reject(e);
    }
});

// Wrapper API.

/**
 * Returns the sum of two 32-bit signed integers.
 * param a Integer in the range -2,147,483,648 to +2,147,483,647.
 * param b Integer in the range -2,147,483,648 to +2,147,483,647.
 */
export function add(a: number, b: number): number {
    if (!exports) {
        throw new Error('WebAssembly not yet initialized: await "ready" export.');
    }
    return exports.add(a, b);
}

The instantiate function provided by the AssemblyScript compiler takes the WASM binary and returns an instantiated, ready-to-use WASM module. Our wrapper includes any documentation, type definitions, and input validation we'll want for the public API.

Loading and instantiating the WASM module can take a while, and we don't want to block the entire application during that time. We'll export a ready promise, and users of our package should await that promise:

import { ready, add } from 'my-package';

await ready;
add(2, 2); // → 4

Bundling the package

With our TypeScript wrapper written, we're ready to bundle and test the package. We'll use a few more dependencies. The typescript and ts-node dependencies can be skipped if you're writing plain JavaScript. The test framework, ava, is optional. Use another test framework that supports TypeScript and ES Modules^[4] if you prefer, or none at all.

npm install --save-dev microbundle ava typescript ts-node

I strongly recommend using Microbundle — an opinionated Rollup wrapper — for reasons that will be apparent when we start adapting the package for different environments. While it isn't a common bundler for building web applications, it's an exceptional choice for building libraries.

In package.json, under the scripts section, we'll define our build and test commands:

{
    "scripts": {
        "build": "npm run asbuild && npm run build:node",
        "build:node": "microbundle build --target node --format modern,cjs --raw --no-compress --output build/my-package-node.js --external node:fs/promises",
        "test": "ava test/*.test.ts",
        ...
    },

    ...

Define the entry points to the compiled package, as our users and unit tests will need that information. Remove any existing versions of these entries in package.json, then add the entries below:

{
    "name": "my-package",
    "type": "module",
    "sideEffects": false,
    "types": "./build/index.d.ts",
    "exports": "./build/my-package-node.modern.js",

    ...

Careful readers may notice a small mismatch in our exports path and the --output flag given to Microbundle. That's intentional: the .modern.js suffix is added by Microbundle automatically.

When we build the package, our script will compile the AssemblyScript module and then the TypeScript wrapper to the build/ directory.

npm run build

We now have a compiled JavaScript bundle in ./build/my-package-node.modern.js, type declarations in ./build/index.d.ts, and a WASM binary in ./build/release.wasm. Let's test the code.

Testing the package

NOTICE: As of this writing, Ava needs additional configuration to support ES Modules and TypeScript together. In package.json, add the options below:

{
    "ava": {
        "extensions": {
            "ts": "module"
        },
        "nodeArguments": [
            "--loader=ts-node/esm"
        ]
    },

    ...

We'll write a simple unit test, test/index.test.ts:

// index.test.ts
import test from 'ava';
import { ready, add } from 'my-package';

test('add', async (t) => {
    await ready;
    t.is(add(2, 2), 4, '2 + 2 = 4');
    t.is(add(5, 0), 5, '5 + 0 = 5');
    t.is(add(10, -3), 7, '10 - 3 = 7');
});

Then, run the test.

npm test

With any luck, the test should pass!^[5]

Compatibility concerns

If you've made it this far, nice work! You may be wondering why this blog post couldn't have been written with half the words and half the dependencies. Here's why.

Our package is now working in a Node.js test environment, but it's not going to run in a web browser, and could easily cause failures in our users' build systems. These environments have incompatible requirements, and our challenge here is to provide builds that work for everyone without creating a maintenance nightmare for ourselves.

Replacing the src/wasm.ts loader with a stub, we're going to create three new loaders and a build target for each:

// src/wasm.ts — Stub, replaced at compile-time.
const wasm = new Uint8Array(0);
export default wasm;

// src/wasm-compat.ts — Legacy bundler WASM loader.
const WASM_BASE64 = '';
const wasm = /* #__PURE__ */ fetch('data:application/wasm;base64' + WASM_BASE64);
export default wasm;

// src/wasm-node.ts — Node.js WASM loader.
import { readFile } from 'node:fs/promises';
const wasmURL = /* #__PURE__ */ new URL('./release.wasm', import.meta.url);
const wasm = /* #__PURE__ */ readFile(wasmURL);
export default wasm;

// src/wasm-default.ts — Web & modern bundler WASM loader.
const wasm = /* #__PURE__ */ fetch(/* #__PURE__ */ new URL('./release.wasm', import.meta.url));
export default wasm;

We'll extend our package.json#exports entries to list each of these options:

{
    "type": "module",
    "sideEffects": false,
    "source": "./src/index.ts",
    "types": "./build/index.d.ts",
    "main": "./build/my-package-node.cjs",
    "module": "./build/my-package-default.modern.js",
    "exports": {
        "compat": {
            "types": "./build/index.d.ts",
            "require": "./build/my-package-compat.cjs",
            "default": "./build/my-package-compat.modern.js"
        },
        "node": {
            "types": "./build/index.d.ts",
            "require": "./build/my-package-node.cjs",
            "default": "./build/my-package-node.modern.js"
        },
        "default": {
            "types": "./build/index.d.ts",
            "require": "./build/my-package-default.cjs",
            "default": "./build/my-package-default.modern.js"
        }
    },

    ...

And finally, update package.json#scripts to create the necessary builds:

{
    "scripts": {
        "build": "npm run asbuild && npm run build:compat && npm run build:node && npm run build:default",
        "build:compat": "microbundle build --target web --format modern,cjs --raw --no-compress --no-sourcemap --output build/my-package-compat.js --external ./release.wasm --alias ./wasm=./wasm-compat --define WASM_BASE64=`base64 -i build/release.wasm`",
        "build:node": "microbundle build --target node --format modern,cjs --raw --no-compress --no-sourcemap --output build/my-package-node.js --external node:fs/promises --alias ./wasm=./wasm-node",
        "build:default": "microbundle build --target web --format modern,cjs --raw --no-compress --output build/my-package-default.js --external ./release.wasm --alias ./wasm=./wasm-default",
        "clean": "rm build/*",
        ...
    },

    ...

NOTICE: If you chose to use JavaScript instead of TypeScript, the --alias flag should include ".js" extensions.

Running "npm run build" now, Microbundle compiles each variation into the build/ folder. Inspect my-package-*.modern.js and notice that each variation is bundled into a single JavaScript file containing the appropriate WASM loader.

Node.js, Web applications, and modern bundlers should find the right version of the package by default. Users with older bundlers should explicitly import from my-package/compat to get a self-contained module, with the WASM binary embedded as a base64 string. This embedding adds +33% file size and some parsing overhead, so it's just a fallback for these older tools.

We now have a fully-functional package, ready for npm, with basic support for all major JavaScript platforms. If the package will require different implementations or functionality on each platform, the same approach can be extended without further duplication.

Complete code from this tutorial is available on GitHub:

• donmccurdy/assemblyscript-library-template

The articles below offer a deeper look at writing and optimizing AssemblyScript code:

• Porting JavaScript (or TypeScript) to AssemblyScript
• Is WebAssembly magic performance pixie dust?

Thanks for reading, and feel free to reach out with any questions!

¹ Not a security concern, but error handling in WASM is sometimes opaque, and tends to increase the size of the WASM binary more than equivalent error handling in JavaScript would require.

² As of this writing, DOM manipulation or calling external JavaScript dependencies would be common examples.

³ Or JavaScript modules. Add ".js" extensions to your import statements, if so.

⁴ As much as I wish that support for ES Modules and TypeScript were table stakes for a testing framework, my dear reader, it is not.

⁵ You may see a warning, "ExperimentalWarning: Custom ESM Loaders is an experimental feature". Node.js support for anything related to ES Modules continues to not be great, and we're including CommonJS fallbacks in our published package to deal with that. We'll ignore this warning from the test suite though, and hope for better support in upcoming Node.js versions.

In this article I’ll discuss gaps in current documentation tools for TypeScript libraries, and where I hope the TypeScript ecosystem might go from here.

function createWidget(widgetType: string, gizmoCount = 4): Widget {
  // ...
}

{
  name: 'createWidget'
    params: [
        {name: 'widgetType', type: 'string'},
        {name: 'gizmoCount', type: 'number', optional: true, defaultValue: 4}
    ],
    returns: {type: 'Widget'}
}

What’s missing

Existing TypeScript documentation tools^{[3] [4] [5]} share two fundamental limitations.

1. No standard, stable, serializable, and type-safe representation of an API model exists.
2. Without such an API model, mature and flexible formatting tools cannot exist.

TypeScript needs a representation of an API model that is type-safe and semantically versioned. The model should provide enough information to render formatted API documentation with simple templates, and should allow a developer to “bring your own framework”, without being tied to a particular web stack.

Creating such an API model doesn’t necessarily mean throwing out current tools — parsing TypeScript code to construct an API model is pretty complicated. While they don’t offer this today, existing projects like API Extractor or TypeDoc might be used to produce a generic API model with these characteristics.

But it’s unrealistic to expect maintainers of projects like API Extractor and TypeDoc to produce formatting tools compatible with many web frameworks. Add requirements of flexible styling for small and large projects, and that’s an open-ended, ecosystem-sized task. Without a stable API model that independent projects can depend on, it’s not going to happen.

This wishlist could go on. Documentation appearing alongside source code in GitHub and GitLab repositories. Better integrations with IDEs and commandlines . Internationalization (i18n) support for libraries with global communities. Live examples running alongside API documentation. These are not impossible goals today, but they’re much harder than they need to be.

Next steps

TypeScript needs better ways to represent packaged APIs. Those could be built on existing tools, like API Extractor. From there, adding API documentation into websites built and deployed with [your favorite web framework] becomes a whole lot easier.

I have ideas about where to go from here, but it’s a large project and I’d love to hear from others: Does this describe your experience with TypeScript API documentation? Have I missed anything important about the problem? Would you like to be involved?

Reach out, or look for Part 2 in a future post.

¹ Source: Stack Overflow Developer Survey, 2022.

² Source: State of the Union: npm, 2017.

³ TypeDoc: The generated JSON API model seems intended for use by the theming system (untyped; built on Handlebars), and available themes are a mixed bag. Moreover, I’ve experienced serious quality control issues here. The project began in 2014 and remains pre-1.0.0, maintained on weekends and without any obvious financial sponsorship (which I think it both needs and deserves). TypeDoc is the most popular tool for documentation in TypeScript, but it’s not easy to recommend without adding major caveats.

⁴ documentation.js: I’ve enjoyed using documentation.js for smaller JavaScript libraries, and would fully recommend it in that context. However, its TypeScript support is not really advertised, and appears to be limited to JavaScript-compatible constructs: no generics, type aliases, etc.

⁵ API Extractor: Part of Microsoft’s Rush Stack, API Extractor is the “heavy artillery” on this list. Though more difficult to configure than others, it appears well designed and well maintained. The API model (packaged separately as @microsoft/api-extractor-model) is mostly a 1:1 reflection of the source code, and would require further processing to use in an HTML template. Inherited members and generics are not resolved on child classes, for example, and JSDoc comments are unparsed. HTML formatting is mostly left as an exercise left to the reader. Still, the extractor and other components would be great foundations for other tools.

• Background
• Updates for three.js
• Converting spec/gloss to metal/rough

Background

When the Khronos Group ratified glTF 2.0 in 2017, the format included a PBR shading model based on the metallic roughness (“metal/rough”) workflow, and an extension (KHR_materials_pbrSpecularGlossiness) for the specular glossiness (“spec/gloss”) workflow.^[1] Differences between the metal/rough and spec/gloss workflows are mostly subtle.^[2] Broadly, the metal/rough workflow tends to be slightly more memory-efficient and performance-friendly for realtime, and the spec/gloss workflow provides slightly more artistic control.

In the following years, new glTF extensions — KHR_materials_ior and KHR_materials_specular — bridged the gap between these PBR workflows. Bringing artistic control over dielectric F0 into metal/rough, allow artists gain flexibility. At the same time, engines can enable these features conditionally and keep the performance advantages of the metal/rough workflow by default.

The metal/rough workflow has been understandably more popular in the years since, even outside of the glTF ecosystem. glTF 2.0 has continued to evolve, launching an excellent series of advanced PBR features: clearcoat, thin-surface transmission, volumetric transmission, iridescence, sheen, and more. These extensions have been widely adopted by 3D viewers and engines in the years since, improving PBR capabilites on many platforms.

Bringing nascent PBR features into a single, well-defined standard is complex: complex to define clearly and fully, and complex to implement correctly and efficiently. Requiring that these features support two PBR workflows, and wrangling the entire ecosystem to implement everyting twice, would have been painful for everyone involved.

Thankfully, Khronos didn’t do that. Recent PBR features have been designed for the metal/rough workflow, and in late 2021 the KHR_materials_pbrSpecularGlossiness extension was archived with the statement below:

Archived extensions may be useful for reading older glTF files, but they are no longer recommended for creating new files.

Updates for three.js

With three.js r147, in November 2022, support for the extension KHR_materials_pbrSpecularGlossiness will be dropped. This allows important cleanup for THREE.GLTFLoader. three.js has always used metal/rough as its PBR shading model, and the loader has historically needed to build a custom ShaderMaterial to support spec/gloss materials.

Most glTF 2.0 files already use metal/rough, and in those cases no changes are needed. However, certain sources^[3] may provide spec/gloss glTF downloads for some files. When that happens, three.js users will need to convert their models from the spec/gloss workflow to metal/rough.

Converting spec/gloss to metal/rough

Fortunately, conversion from spec/gloss to metal/rough is lossless in any engine that supports KHR_materials_specular and KHR_materials_ior extensions.^[4] Using the glTF Transform library, here are three ways to convert existing assets from the spec/gloss workflow.

Web

Go to gltf.report/ and drag your model into the viewer. You’ll see a warning that the materials are about to be converted to metal/rough. After that, just download the result with the Export button on the right hand side. That’s it!

Commandline

With Node.js ≥14 installed, open a terminal run the following commands:

# install
npm install --global @gltf-transform/cli

# convert
gltf-transform metalrough input.glb output.glb

These steps will convert any spec/gloss materials in the file to metal/rough.

Script

If you’re using JavaScript or TypeScript to process glTF models as part of a Node.js server or frontend web application, then you can use glTF Transform’s scripting API to do this conversion. After choosing the appropriate platform I/O service, run:

import { WebIO, NodeIO } from '@gltf-transform/core';
import { KHRONOS_EXTENSIONS } from '@gltf-transform/extensions';
import { metalRough } from '@gltf-transform/functions';

// configure I/O
const io = new WebIO().registerExtensions(KHRONOS_EXTENSIONS); // web
const io = new NodeIO().registerExtensions(KHRONOS_EXTENSIONS); // node.js

// read
const document = await io.read('path/to/model.glb');

// convert
await document.transform(metalRough());

// write
const glb = io.writeBinary(document); // → Uint8Array

Cleaning up

In some situations you may find that file size increases as a result of the conversion. Larger size isn’t a result of the metal/rough workflow (files originally authored for metal/rough will generally be smaller) but can be a side effect of conservative choices made during material conversion. If that happens, here are some ways to clean things up.

First, try removing the IOR and Specular extensions from the converted file by opening it in gltf.report/, going to the script tab in the sidebar, and running the following script:

import { prune } from '@gltf-transform/functions';

const DENYLIST = ['KHR_materials_ior', 'KHR_materials_specular'];

for (const extension of document.getRoot().listExtensionsUsed()) {
    if (DENYLIST.includes(extension.extensionName)) {
        extension.dispose();
    }
}

await document.transform(prune());

If your model still looks correct, then congrats! You didn’t need some of the spec/gloss features anyway, and your model will be smaller as a result. If things don’t look right anymore, then discard your changes. Either way, you can continue to the next step.

Next, we’ll try optimizing textures, using the glTF Transform CLI.

# install
npm install --global @gltf-transform/cli

# optimize
gltf-transform mozjpeg tmp.glb tmp.glb
gltf-transform oxipng tmp.glb output.glb

The CLI will attempt to optimize textures using the mozjpeg and oxipng utilities, bundled by squoosh. Customizing compression settings (use the --help flag) may allow you to go further. Finally, you may also want to convert textures to the KTX2 format. KTX2 offers major advantages over PNG and JPEG in 3D scenes, but also requires a bit more work to manage size/quality tradeoffs in compression.

Conclusion

For three.js users affected by the r147 release, and anyone else interested in converting your glTF 2.0 files to the metal/rough shading model, I hope this guide has been helpful. If not, please reach out on the issue trackers for any of the projects linked.

¹ Later extensions also provided a shadeless (“unlit”) model, KHR_materials_unlit.

² I recommend Allegorithmic’s PBR Guide if you’re interested in those details.

³ Notably, Sketchfab.

⁴ Conversion is often lossless even without those extensions, but you’ll need to test whether the results are acceptable for your content without them.

“Lookup tables (LUTs) are a technique for optimizing the evaluation of functions that are expensive to compute and inexpensive to cache, ... By precomputing the evaluation of a function over a domain of common inputs, expensive runtime operations can be replaced with inexpensive table lookups. ... LUTs are also useful when wanting to separate the calculation of a transform from its application. For example, in color pipelines it is often useful to “bake” a series of color transforms into a single lookup table, which is then suitable for distribution and re-use.”

~ Nick Shaw, Cinematic Color 2: LUTs and Transforms

2D and 3D renderers use LUTs to transform pixel values very flexibly and very quickly. LUTs achieve technical or stylistic goals like custom tone mapping, color gradients for scientific visualization, day/night transitions, baking results of a simulation, and so on. LUTs can enhance both photorealistic rendering and stylized graphics.

The three minute video above, by EightyEightGames, gives a short and clear introduction to LUTs in games. A quick search for “gamedev LUT” on Twitter should offer some other interesting ideas.

What follows is a guide — for web developers, or anyone else — to compressing LUTs for faster loading in realtime applications. With KTX 2.0, we'll reduce both file size and parsing time by ~99% compared to traditional formats like .cube.

What's in a LUT

Simpler operations like contrast or saturation can be applied with small 1D LUTs. For more sophisticated operations, larger 3D LUTs are required. Complete 3D LUTs, containing possible mappings on an 8-bit sRGB [0,1] input domain, would store 256x256x256 = 16,777,216 values. Fortunately, that's rarely necessary — we interpolate between values when sampling from the table, and a smaller 3D LUT containing only 65⨉65⨉65 = 275K values is often enough.

Common LUT file formats, like .cube or .spi3d, store these values in plaintext rows:

LUT_3D_SIZE 65
0.000176 0.000176 0.000176
0.015625 0.000176 0.000176
0.031250 0.000176 0.000176
... <274,622 more rows>

This is not an efficient way to store data, and 275K values in plaintext add up fast: each 3D LUT might easily be 5-10 MB. For desktop applications, this might be fine. But on the web, most use cases would benefit from much smaller files.

Lossless compression (gzip, brotli, or zstd) reduces the download size of these files pretty well. But we don't just need to download the files — we also need to parse them and upload them to the GPU as textures, for fast parallel lookups in a fragment shader. After decompressing a compressed text file, we're still stuck with 5-10 MB of text to process and convert to a texture, before we can draw any pixels. On a 2021 M1 Pro chip, JavaScript might spend 100–200ms just parsing a 5–10MB LUT in these plaintext formats, but we can do much better.

GPU-optimized compression with KTX 2.0

With KTX 2.0, a flexible texture container format defined by the Khronos Group in 2021, we can store the GPU texture directly instead of using plain text. We'll avoid nearly all of that parsing overhead: in binary formats like KTX 2.0, loaders only need to parse a small header to learn what's in the file. After that the loader can slice views out of the larger payload, without parsing any pixel data.

KTX 2.0 supports a lot of GPU texture formats, and a few other “universal” formats. glTF 2.0 models (.gltf, .glb) often use KTX 2.0 with Basis Universal texture compression. We aren't going to use Basis Universal in this case¹ — LUTs work best with other types of compression. We'll instead use uncompressed texture formats (u8, f16, and f32), with some lossless compression applied to the container (“supercompression”).

To convert a LUT to KTX2 in your own software, you'd do something like this:

1. Parse the original LUT, allocating an array of 8-bit, 16-bit, or 32-bit values
2. Write the array to a KTX2 container, perhaps using KTX-Software or ktx-parse
3. Apply supercompression, perhaps using KTX-Software's ktxsc command

Using JavaScript and three.js, we could also define a LUT programmatically:

const customLUT1D = new THREE.DataTexture(
    new Float32Array([0, 0.1, ..., 1.0]),
    NUM_VALUES,
    1,
    THREE.RedFormat,
    THREE.FloatType,
    THREE.UVMapping,
    THREE.ClampToEdgeWrapping,
    THREE.ClampToEdgeWrapping,
    THREE.LinearFilter,
    THREE.LinearFilter
);

Because three.js also includes utilities like LUTCubeLoader.js, LUT3dlLoader.js, KTX2Exporter.js, and KTX2Loader.js, we can use these to convert LUT-specific formats (.cube, .3dl) to KTX 2.0. To make this easier, I made a small Glitch application for loading .cube LUTs and converting them to KTX2. Try it out here:

🔗 https://lut-to-texture.donmccurdy.com/

This tool encodes the LUT to a more compact binary representation, but doesn't yet include supercompression. I haven't been able to find a Zstandard encoder that works in a web browser — if you know of one, please let me know. In the meantime, add supercompression in a separate step with KTX-Software's ktxsc utility:

ktxsc --zcmp 19 lut.ktx2

Results

Testing KTX 2.0 compression with a 3D LUT, the results are dramatic. The KTX 2.0 file is just 1% the size of the original, parses in a fraction of the time, and loses none of the original precision.

Using the LUT

Using a .ktx2 LUT in three.js is no different than using .cube. Just replace THREE.LUTCubeLoader with THREE.KTX2Loader. While some KTX 2.0 files must be encoded for particular GPUs using WASM transcoders, these LUTs do not require transcoding. If the LUT is being applied to the full viewport, that's done in post-processing — either three/postprocessing or pmndrs/postprocessing will work.

// three.js post-processing
const lut = await loader.loadAsync( './lut.ktx2' );

// pmndrs post-processing
import { LookupTexture } from 'postprocessing';
const lut = LookupTexture.from( await loader.loadAsync( './lut.ktx2' ) );

In other engines, you may need to ask about support for 3D textures in KTX2 files. This is a newer and less widely-supported pattern for now. I'd love to hear if you found this article useful, and how you're using LUTs in your projects. Please reach out on Twitter!

More technical details

Input domain: Every LUT is defined only for a certain range of input values. Often that range is RGB ∈ [0,1], but another input domain might be defined at the top of the file. Inputs outside this range are clamped, so it's important to get the range right. Custom input domains are not embedded in the KTX 2.0 texture, and would need to be assigned manually before using the KTX 2.0 LUT in an application².

Color spaces: Like its input domain, every LUT makes assumptions about the color space of input values. Output values may be in the same color space, or the LUT may include conversion to another color space. Unfortunately, color space information is typically not defined in the LUT file. The output color space can be included in a KTX 2.0 file, if you know it.

KTX 2.0 vs. PNG: We've discussed .cube and other LUT-specific formats, but not traditional image formats like PNG. PNG can store 1D LUTs in some cases, and 3D LUTs that are flattened (24⨉24⨉24px → 24⨉576px). PNG compression works well, but it has two major limitations in this context. First, output values are constrained to the [0,1] range in PNG, while KTX 2.0 supports unbounded floating point values. Second, precision of output values is limited to 8 bits by PNG — that's just enough for a final pixel color, and is likely to cause banding if any additional processing (tone mapping, color space conversion, etc.) is applied after the LUT later in the post processing stack. While PNG has a 16-bit mode, no web browser currently supports it.

Other LUT formats: If you have LUTs in a format other than those discussed here, tools like ociobakelut may be helpful to convert or reformat the LUT. I'm not aware of any LUT-specific formats that are both (1) open, and (2) as efficient as the KTX 2.0 approach described here.

¹ Basis Universal, by Binomial LLC, is an outstanding technology for compressing textures used in 3D models and materials, reducing GPU memory usage, and generally improving performance in GPU-based applications. Learn more about Basis Universal, if you aren't using it for material textures yet.

² KTX 2.0 does support key/value data and an extension-like mechanism, so formal or informal ways of embedding the LUT domain could be added in the future.

With its release in 2017, glTF 2.0 created a baseline metal/rough physically-based-rendering (PBR) material workflow — the first of its kind to become widely-adopted in web and realtime applications. Since then, Khronos has published multiple advanced extensions for newer PBR effects like transmission, volumetric refraction, and clearcoat, IOR, and more. These extensions push the capabilities of realtime web viewers, in a good way.

Support for reading and writing these extensions in modeling tools generally lags behind the standards a bit. Blender can render refraction with its Principled BSDF material, but can only export transmission — not volumetric refraction — as of this writing.

In the meantime, one workaround is to write a short script adding the latest PBR material extensions to an existing glTF 2.0 asset. The same general approach should work for other upcoming extensions too, not just volumetric refraction. I'll use glTF Report as a sandbox for quickly previewing changes, and glTF Transform as the scripting API. The script could just as easily be used in a Node.js environment or a custom web application.

import {
    MaterialsIOR,
    MaterialsSpecular,
    MaterialsTransmission,
    MaterialsVolume
} from '@gltf-transform/extensions';

// Register extensions, and define extension material properties.

const transmissionExt = document.createExtension(MaterialsTransmission);
const transmission = transmissionExt.createTransmission()
    .setTransmissionFactor(1.0);

const volumeExt = document.createExtension(MaterialsVolume);
const volume = volumeExt.createVolume()
    .setThicknessFactor(1.0)
    .setAttenuationDistance(1.0)
    .setAttenuationColorHex(0x4285f4);

const iorExt = document.createExtension(MaterialsIOR);
const ior = iorExt.createIOR()
    .setIOR(1.75);

const specularExt = document.createExtension(MaterialsSpecular);
const specular = specularExt.createSpecular()
    .setSpecularFactor(1.0);

// Update material.

const material = document.getRoot()
    .listMaterials()
    .find((mat) => mat.getName() === 'MyMaterial');

material
    .setAlphaMode('OPAQUE')
    .setMetallicFactor(0.0)
    .setRoughnessFactor(0.2)
    .setExtension('KHR_materials_transmission', transmission)
    .setExtension('KHR_materials_volume', volume)
    .setExtension('KHR_materials_ior', ior)
    .setExtension('KHR_materials_specular', specular);

Note that metallicFactor is set to 0.0. Fully-metallic materials are never transmissive, and disabling the metallic factor entirely is a quick way to ensure we don't have that problem. Materials with metallicRoughnessTexture controlling the metal/rough effect could keep it at 1.0 and let the texture do the rest.

Additionally, most realtime renderers today cannot display a transmissive material through another transmissive material. This may change as renderers improve over time, but for now it's important to keep it in mind and ensure that transmissive objects and opaque objects use separate materials. Transmission is also a fairly expensive effect — costing more GPU time for every pixel affected — so this separation should improve performance.

For testing, I've provided a sample .blend and .glb model, exported without any material extensions. Running the script should give the result shown below.

Resources: SuzanneInBox.zip

For now I plan to rest, build a few side projects, and freelance part time. I remain very interested in environmental data and policy, and expect to do more of that in the future. Recent reading includes Saul Griffith's Rewiring America — a short, memorable handbook for the next ten years — and Elizabeth Kolbert's Under a White Sky, a thoughtful but sobering look at the reshaping of our planet.

While I won't be considering full-time employment much for the next few months, I'll continue to be active in the open source community, and spending more time writing. If you're interested in helping me make those into sustainable parts of my work, I'm also opening a GitHub Sponsors page. To get in touch about freelance work or other questions, please reach out to contact@donmccurdy.com.

NEW POST, OLD TRIP: The past year hasn't been one for travel, thanks to COVID-19. But in reminiscing about going places, I've finally found the motivation to write about a trip I took two years ago.

I visited Scotland during the summer of 2019, taking a solo bikepacking trip along parts of NCN78 (“The Caledonia Way”). The trip began in Glasgow, where I rented a Whyte Friston gravel bike from Billy Bilsland Cycles before taking a train to Inverness. Travel by train was quiet, scenic, and relatively easy.

Arrival — Train to Inverness

Leaving Glasgow early and reaching Inverness by mid-afternoon, I checked into an Airbnb and spent some time exploring town. The Women's World Cup (U.S. vs. Netherlands) was showing that day, so I found a pub, ordered food, and settled in to watch. That evening I visited another pub for live music.

Day 1 — Inverness to Fort William

Leaving early for the longest day of riding (66mi), I went south from Inverness, first along quiet side roads, then along Loch Ness and B852. Lunch in Fort Augustus, then continued to Fort William. Fort William would have been the place to stop and hike Ben Nevis, spending an extra day, but I hadn't made plans for this and the weather wasn't cooperative.

Day 2 — Fort William to Oban

The route from Fort William to Oban included ferries, and was much easier than the previous day's ride, at 41mi. This left plenty of time for exploring Oban, which is worthwhile. My original plan had included some camping along the route. However, rain was coming and hostels were plentiful, so I took the more comfortable option and the hot showers.

Day 3 — Oban / Benderloch Loop

While the official route continues south from Oban, there isn't an easy train back to Glagow further along. I only wanted to spend one more day on the trail, so instead of going south I did a 30mi loop out of Oban. This route featured more gravel than the other days, and more challenging navigation as it wasn't on a well-established cycling route.

Return — Train to Glasgow

Train back to Glasgow, returned the rental bike, and continued on to Edinburgh for a couple days of free time. The Scottish National Gallery of Modern Art and live music at Sandy Bells were two highlights in Edinburgh.

Conclusion

The NCN78 is a well-planned route, quiet and unhurried. It was also my first try at solo bikepacking, so I was grateful for never being too far from a warm bed and hot meal along the way. A few practical notes:

• July provided plenty of daylight — sunset was around 9:30pm — and allowed more time to explore. It also brought unpredictable weather, and I rode through some amount of rain and fog on all days of the trip. I didn't mind the rain, but the fog was a bit much on the last day of the ride.
• If you're planning to take your bike on the train, reserve that in advance. There were limited spaces for bikes, although the bicycle compartment didn't appear to fill up on my trip.
• The route was probably 70% paved, 25% firm dirt/gravel, and one short section, just a few miles, of chunky gravel. On a gravel bike with ~45mm tires this was all fine, although I did get a flat on the chunkier section. A road bike with 35-40mm tires would have been fine on most of it, but that loose gravel wouldn't have been much fun.

Both repositories are up for adoption¹ under the donmccurdy-up-for-adoption account. I prefer this to archiving them as I've done with more outdated projects: there are still plenty of active users here, and I'd be glad to see them continue. If you're interested in maintaining either project yourself or with others, please reach out with a GitHub issue. Until (and unless) someone else takes over, both will be unmaintained indefinitely.

I have a few personal and practical reasons for this decision:

1. I don't have a Facebook account, and I don't plan on creating one. With recent announcements, I have limited time before Facebook disables my Oculus Quest and I lose the ability to develop and test with my own VR hardware.
2. Bug fixes for WebXR projects are unusually time-consuming. In a traditional software library, a public API can be unit tested, providing some confidence that a new change works correctly. With WebXR interaction and physics simulation, I haven't found a real alternative to manually testing on lots of devices. Perhaps there's a better way to automate testing for this type of project, but that's not something I'm personally excited to spend time inventing.
3. Limited time / other interests. The free time I'm willing to spend on OSS is finite — it isn't a day job and probably won't become one. I don't want to give the impression that these projects are actively supported when they're not, while leaving issues and PRs unanswered.

I will continue working on other things, building out glTF-Transform and contributing to three.js and glTF. I'm also taking online classes in probability and statistics, and generally trying to do the best I can with an unusually challenging year.

A particularly clear example of gamma correct (left) and incorrect (right) rendering. Source.

Updated November 9, 2022: With three.js ≥r139, I contributed a more comprehensive guide to color management in the official three.js documentation. I've maintained and updated this post as a short tl;dr, but I recommend reading the full guide for a stronger understanding.

Definitions

• Linear-sRGB / THREE.LinearEncoding: Linear transfer functions, Rec. 709 primaries, D65 white point.
• sRGB / THREE.sRGBEncoding: sRGB transfer functions, Rec. 709 primaries, D65 white point.

Best practices

1. Textures with color data (.map, .emissiveMap, …) should be configured with .encoding = sRGBEncoding. Non-color textures use LinearEncoding. Exceptions exist for some formats (like OpenEXR), which typically use LinearEncoding for color data.
2. Vertex colors should be stored in Linear-sRGB.
3. Materials and lights require RGB components in Linear-sRGB. Hexadecimal and CSS colors are generally sRGB, and must be converted.¹
4. Renderer should have .outputEncoding = sRGBEncoding when not using post-processing. With three.js default post-processing, use LinearEncoding and apply a GammaCorrectionShader as the last pass in post.²

THREE.GLTFLoader provides (1), (2), and (3) out of the box. Other file formats vary.

Motivation

The goal of all that is a "linear workflow" — lighting calculations are done on linear values. When values are in gamma space (or "gamma workflow"), instead, surfaces will respond inconsistently to lighting, appearing too bright in places and too dark in others, or somewhat washed out. And obviously, light and color values brought from other PBR programs would not match as expected. You can tune your lights carefully and eventually get consistent results with a gamma workflow, too, but the lighting will be more fragile to future changes.

John Novak describes the problem well:

[With gamma workflows, or incorrectly-configured linear workflows] the material and lighting parameters we would need to choose would be completely devoid of any physical meaning whatsoever; they’ll be just a random set of numbers that happen to produce an OK looking image for that particular scene, and thus not transferable to other scenes or lighting conditions. It’s a lot of wasted energy to work like that. ... It’s also important to point out that incorrect gamma handling in 3D rendering is one of the main culprits behind the “fake plasticky CGI look” in some (mostly older) games.

References

• Unity • Linear or gamma workflow
• What every coder should know about gamma

• Original visualization: Unpaid work: Allocation of time and time-use
• Data source: UN Stats

Source code in Observable: observablehq.com/@donmccurdy/unpaid-work

With the new backup plan I had three goals:

1. Backups should be automatic and silent.
2. Backups should be replicated in the cloud.
3. Larger files (RAW photos, music) should move off my laptop to free up space, but should still be backed up.

I bought an internal SSD and separate enclosure. This works out a little cheaper than buying an external SSD, and it's dead simple to assemble the two. If you don't care about noise, a 2TB 3.5" HDD (currently $65) would be much cheaper, or you could get a larger drive.

• Western Digital Blue SSD (2TB) – $220
• ORICO 2.5" Enclosure – $15

I partitioned the drive (0.8TB for Time Machine, 1.2TB for media). Including my laptop's drive, that's three volumes:

• Primary – laptop SSD (0.5TB)
• Time Machine – external SSD (0.8TB)
• Media – external SSD (1.2TB)

For cloud backups, I'm using Backblaze and paying $6/month for unlimited storage. The primary drive is backed up to the external SSD and Backblaze. Media on the external SSD is backed up only to Backblaze. Both happen automatically. The idea of self-hosting backups on Google Cloud Storage or S3 was tempting, but no.

My laptop has plenty of free space again, and it's nice having my Lightroom photo library on a separate drive with enough storage for future needs. And of course, backups are no longer dependent on my physical apartment.