Registry / serialization / ktx-parse

ktx-parse

JSON →
library1.1.0jsnpmunverified

ktx-parse is a JavaScript/TypeScript library designed for parsing and serializing KTX 2.0 (`.ktx2`) container files. It provides programmatic access to the structure and metadata within KTX 2.0 files, including mipmap levels, data format descriptors, and key/value data. Crucially, this library focuses solely on the KTX 2.0 container format and does not include functionality for decompressing or compressing the actual texture data (e.g., Basis Universal, ETC1S, UASTC). Users must integrate separate transcoding libraries (like those from BinomialLLC or KhronosGroup) to handle the compressed GPU texture formats found inside the KTX 2.0 containers. The package is currently at version 1.1.0 and is actively maintained by Don McCurdy, known for his work on glTF-Transform. It offers robust type definitions for TypeScript users and is frequently adopted in 3D graphics and web applications that require efficient GPU texture streaming.

npm install ktx-parse
INSTALL
IMPORT
SIG · KTX-PARSE
K
ktx-parse
serializationjavascriptv1.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

read
import { read } from 'ktx-parse';
const { read } = require('ktx-parse');
Primary function for parsing a KTX 2.0 byte array. While CommonJS `require` is currently supported, ESM `import` is the idiomatic approach for modern TypeScript/JavaScript projects using this library.
write
import { write } from 'ktx-parse';
const { write } = require('ktx-parse');
Function for serializing a KTX2Container instance back into a KTX 2.0 byte array.
KTX2Container
import type { KTX2Container } from 'ktx-parse';
This is a TypeScript type import for the parsed KTX 2.0 container object. It is generally used for type hinting rather than direct runtime import.

This quickstart demonstrates how to fetch a KTX 2.0 file, parse its binary data using `ktx-parse`, access key properties like dimensions and mipmap levels, and then serialize the container back into a byte array. It highlights that the raw texture data from `container.levels` requires external transcoders for decoding.

import { read, write } from 'ktx-parse'; import type { KTX2Container } from 'ktx-parse'; async function processKtx2File(url: string) { try { // Simulate fetching a .ktx2 file (e.g., from a server or local path) console.log(`Fetching KTX2 file from ${url}...`); const response = await fetch(url); if (!response.ok) { throw new Error(`Failed to fetch ${url}: ${response.statusText}`); } const arrayBuffer = await response.arrayBuffer(); const ktx2Bytes = new Uint8Array(arrayBuffer); // Parse the KTX 2.0 file console.log('Parsing KTX2 data...'); const container: KTX2Container = read(ktx2Bytes); console.log('KTX2 Container parsed successfully:'); console.log(` File format version: ${container.vkFormat}`); // vkFormat is one of the many header properties console.log(` Pixel Width: ${container.pixelWidth}`); console.log(` Pixel Height: ${container.pixelHeight}`); console.log(` Number of mip levels: ${container.levels.length}`); console.log(` Has Supercompression: ${container.supercompressionScheme !== null}`); // Example: Accessing a mip level (level 0 is the largest) if (container.levels.length > 0) { const level0 = container.levels[0]; console.log(` Mip Level 0 data size: ${level0.byteLength} bytes`); // To actually use this data for rendering, you would need a transcoder. // For example, if it's Basis Universal, use a Basis Universal WebAssembly transcoder. } // Example: Serialize the container back to bytes (e.g., after modifying metadata) const modifiedKtx2Bytes = write(container); console.log(`Serialized container back to ${modifiedKtx2Bytes.byteLength} bytes.`); } catch (error) { console.error('Error processing KTX2 file:', error); } } // Replace with a real KTX2 file URL for testing // A common test asset could be a KTX2 file from glTF-Sample-Models or a similar source. processKtx2File('https://raw.githubusercontent.com/KhronosGroup/KTX-Sample-Assets/main/KTX-Software/images/test_images_ktx2/astc_8x8_rgba_ldr.ktx2');
Debug
Known issues
gotchaktx-parse is a container parser and serializer; it does not include functionality to decompress or compress the actual GPU texture data (e.g., Basis Universal, ETC1S, UASTC, ASTC) contained within the KTX 2.0 file. To display or process the texture pixels, you must integrate a separate WebAssembly-based texture transcoder (e.g., `basisu_wasm`, `ktx2decoder`, or a custom solution).
fix
Integrate an appropriate texture transcoder (e.g., KhronosGroup/Universal-Texture-Transcoders) alongside ktx-parse to handle the compressed texture data. First, parse the KTX2 container, then pass the relevant mip level data to your chosen transcoder.
affects: >=1.0.0
gotchaWhen accessing mip levels or other binary data from a parsed `KTX2Container`, the returned `Uint8Array`s are direct views into the original source `ArrayBuffer`. Modifying the underlying source buffer after parsing can lead to unexpected behavior or data corruption in the `KTX2Container` object.
fix
If modifications to the original source buffer are necessary, ensure that a deep copy of the `KTX2Container` data (especially mip levels and other binary fields) is made before performing any write operations on the source buffer.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Missing KTX 2.0 identifier.
The provided `Uint8Array` or `ArrayBuffer` does not start with the magic identifier bytes for a KTX 2.0 file, indicating it's either not a KTX 2.0 file, is corrupted, or is an unsupported KTX 1.x file.
fix
Verify that the input data is a valid KTX 2.0 file. Check the file extension (`.ktx2`) and ensure the file is not corrupted during transfer or loading. If it's a KTX 1.x file, `ktx-parse` is not the correct library.
TypeError: Cannot read properties of undefined (reading 'byteLength') or similar when accessing texture data.
This often occurs when attempting to access `container.levels[x].byteLength` or `container.levels[x].data` for a mip level that does not exist or if the `levels` array is empty, which can happen with malformed KTX2 files or if basic validation wasn't performed.
fix
Always check `container.levels.length` before attempting to access individual mip levels. Ensure the KTX2 file is well-formed and contains the expected number of mip levels.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
ktx-parse — npm install ktx-parse · libregistry