meshopt 0.1.0__tar.gz

meshopt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+# On a version tag: a wheel for each system, tested where it is built, published to PyPI by trusted publishing, no token
+# stored anywhere, and attached to a GitHub release. One wheel a system serves every Python from 3.12 through the stable
+# ABI; 3.11 and free-threaded 3.14 get their own.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  wheels:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, macos-15-intel, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: The tag must be the version in pyproject.toml
+        shell: bash
+        run: test "v$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)" = "${GITHUB_REF_NAME}"
+      - uses: pypa/cibuildwheel@v3.2
+        env:
+          CIBW_BUILD: "cp311-* cp312-* cp314t-*"
+          CIBW_SKIP: "*-musllinux_* *-win32 *-manylinux_i686"
+          CIBW_ENABLE: cpython-freethreading
+          CIBW_TEST_REQUIRES: pytest
+          CIBW_TEST_COMMAND: pytest -q {project}/tests
+          MACOSX_DEPLOYMENT_TARGET: "10.14"  # nanobind's aligned allocation needs 10.14; arm64 builds start at 11 regardless
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  release:
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --notes "meshoptimizer 1.3"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  publish:
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

meshopt-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+# On every push and pull request: built from source and tested on each system, with the oldest and newest Python and
+# free-threaded Python, which must keep its lock off.
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
+        python: ["3.11", "3.14", "3.14t"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run pytest -q
+      - name: Free-threaded Python keeps its lock off
+        if: matrix.python == '3.14t'
+        run: uv run python -c "import sys, meshopt; assert not sys._is_gil_enabled(), 'meshopt turned the lock back on'"

meshopt-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+build/

meshopt-0.1.0/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.18...3.31)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+find_package(Python 3.11 REQUIRED COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
+find_package(nanobind CONFIG REQUIRED)
+
+# The binding and meshoptimizer's own sources, the files the encoder and decoder need, in one module.
+nanobind_add_module(_core STABLE_ABI FREE_THREADED NB_STATIC LTO
+    src/meshopt.cpp
+    vendor/meshoptimizer/allocator.cpp
+    vendor/meshoptimizer/vertexcodec.cpp
+    vendor/meshoptimizer/indexcodec.cpp
+    vendor/meshoptimizer/vertexfilter.cpp
+    vendor/meshoptimizer/vcacheoptimizer.cpp
+    vendor/meshoptimizer/vfetchoptimizer.cpp
+    vendor/meshoptimizer/spatialorder.cpp
+)
+
+install(TARGETS _core LIBRARY DESTINATION meshopt)

meshopt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aidan Newsome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meshopt-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: meshopt
+Version: 0.1.0
+Summary: meshoptimizer's encoder and decoder for Python, shaped like its JavaScript module.
+Author-Email: Aidan Newsome <aidan.newsome@me.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: vendor/meshoptimizer/LICENSE.md
+Project-URL: Source, https://github.com/aidannewsome/meshopt
+Project-URL: Releases, https://github.com/aidannewsome/meshopt/releases
+Project-URL: meshoptimizer, https://github.com/zeux/meshoptimizer
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# meshopt
+
+An independent Python binding for [meshoptimizer](https://github.com/zeux/meshoptimizer)'s encoder and decoder, modelled
+on its JavaScript module. Not affiliated with the meshoptimizer project.
+
+## Use
+
+```python
+import meshopt
+
+indices, remap, unique = meshopt.reorder_mesh(indices, triangles=True, optsize=False)
+vertices = vertices[np.argsort(remap)[:unique]]                  # each vertex moved to its new place
+
+data = meshopt.encode_gltf_buffer(vertices, "ATTRIBUTES")        # bytes for an EXT_meshopt_compression bufferView
+rows = meshopt.decode_gltf_buffer(data, len(vertices), vertices.itemsize * vertices.shape[1], "ATTRIBUTES")
+```
+
+The functions are the JavaScript module's (`MeshoptEncoder` and `MeshoptDecoder`), in snake case, with counts and sizes
+taken from the arrays where they can be. Encoders give bytes; filters give rows of bytes as an array; decoders give rows
+of bytes, or indices for an index buffer. The tests are the JavaScript module's tests, one for one.
+
+Every call releases Python's lock, and the module runs on free-threaded Python with the lock off.
+
+## Build
+
+A short C++ binding made with nanobind over meshoptimizer's own sources, vendored from release 1.3 in `vendor/meshoptimizer`.
+`uv sync` builds it and `uv run pytest` tests it. Releases are a wheel for each system, so installing needs no compiler.
+
+## Licence
+
+MIT, as meshoptimizer is. meshoptimizer is Arseny Kapoulkine's; its licence is in `vendor/meshoptimizer/LICENSE.md`.

meshopt-0.1.0/README.md

@@ -0,0 +1,31 @@
+# meshopt
+
+An independent Python binding for [meshoptimizer](https://github.com/zeux/meshoptimizer)'s encoder and decoder, modelled
+on its JavaScript module. Not affiliated with the meshoptimizer project.
+
+## Use
+
+```python
+import meshopt
+
+indices, remap, unique = meshopt.reorder_mesh(indices, triangles=True, optsize=False)
+vertices = vertices[np.argsort(remap)[:unique]]                  # each vertex moved to its new place
+
+data = meshopt.encode_gltf_buffer(vertices, "ATTRIBUTES")        # bytes for an EXT_meshopt_compression bufferView
+rows = meshopt.decode_gltf_buffer(data, len(vertices), vertices.itemsize * vertices.shape[1], "ATTRIBUTES")
+```
+
+The functions are the JavaScript module's (`MeshoptEncoder` and `MeshoptDecoder`), in snake case, with counts and sizes
+taken from the arrays where they can be. Encoders give bytes; filters give rows of bytes as an array; decoders give rows
+of bytes, or indices for an index buffer. The tests are the JavaScript module's tests, one for one.
+
+Every call releases Python's lock, and the module runs on free-threaded Python with the lock off.
+
+## Build
+
+A short C++ binding made with nanobind over meshoptimizer's own sources, vendored from release 1.3 in `vendor/meshoptimizer`.
+`uv sync` builds it and `uv run pytest` tests it. Releases are a wheel for each system, so installing needs no compiler.
+
+## Licence
+
+MIT, as meshoptimizer is. meshoptimizer is Arseny Kapoulkine's; its licence is in `vendor/meshoptimizer/LICENSE.md`.

meshopt-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "meshopt"
+version = "0.1.0"
+description = "meshoptimizer's encoder and decoder for Python, shaped like its JavaScript module."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "vendor/meshoptimizer/LICENSE.md"]
+authors = [{ name = "Aidan Newsome", email = "aidan.newsome@me.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.26",
+]
+
+[project.urls]
+Source = "https://github.com/aidannewsome/meshopt"
+Releases = "https://github.com/aidannewsome/meshopt/releases"
+meshoptimizer = "https://github.com/zeux/meshoptimizer"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[build-system]
+requires = ["scikit-build-core>=0.11", "nanobind>=2.9"]
+build-backend = "scikit_build_core.build"
+
+[tool.scikit-build]
+minimum-version = "build-system.requires"
+build-dir = "build/{wheel_tag}"
+wheel.packages = ["python/meshopt"]
+wheel.py-api = "cp312"  # one wheel a system for every Python from 3.12, through the stable ABI; 3.11 and free-threaded Python get their own
+
+[tool.ruff]
+line-length = 160
+
+[tool.ruff.lint.isort]
+known-first-party = ["meshopt"]
+
+[tool.ruff.format]
+exclude = ["tests/test_decoder.py"]  # its numbers stay in rows, as the JavaScript test has them

meshopt-0.1.0/python/meshopt/__init__.py

@@ -0,0 +1,168 @@
+"""meshoptimizer's encoder and decoder, shaped like its JavaScript module: the same functions in the same order,
+counts and sizes read from the arrays where they can be. Codecs give bytes; filters and decoders give arrays."""
+
+from typing import Literal
+
+import numpy as np
+
+from . import _core
+
+__all__ = [
+    "reorder_mesh",
+    "reorder_points",
+    "encode_vertex_buffer",
+    "encode_vertex_buffer_level",
+    "encode_index_buffer",
+    "encode_index_sequence",
+    "encode_gltf_buffer",
+    "encode_filter_oct",
+    "encode_filter_quat",
+    "encode_filter_exp",
+    "encode_filter_color",
+    "decode_vertex_buffer",
+    "decode_index_buffer",
+    "decode_index_sequence",
+    "decode_gltf_buffer",
+]
+
+Mode = Literal["ATTRIBUTES", "TRIANGLES", "INDICES"]
+Filter = Literal["NONE", "OCTAHEDRAL", "QUATERNION", "EXPONENTIAL", "COLOR"]
+ExpMode = Literal["Separate", "SharedVector", "SharedComponent", "Clamped"]
+EXP_MODES = {"Separate": 0, "SharedVector": 1, "SharedComponent": 2, "Clamped": 3}
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def rows(data: np.ndarray) -> tuple[np.ndarray, int, int]:
+    """An array as its bytes, with a row each element: the bytes, the count and each row's size."""
+    data = np.ascontiguousarray(data)
+    check(data.ndim >= 1 and len(data) > 0, "data must have a row for each element")
+    return data.view(np.uint8).reshape(-1), len(data), data.nbytes // len(data)
+
+
+def index32(indices: np.ndarray) -> np.ndarray:
+    indices = np.asarray(indices)
+    check(indices.dtype in (np.uint16, np.uint32, np.int32), "indices must be 16 or 32 bit integers")
+    return np.ascontiguousarray(indices.reshape(-1), dtype=np.uint32)
+
+
+def reorder_mesh(indices: np.ndarray, triangles: bool, optsize: bool) -> tuple[np.ndarray, np.ndarray, int]:
+    """Indices renumbered so vertices come in the order they are first used, the triangles first put in the order a
+    GPU's vertex cache likes, or a strip's when optsize. The new indices, each vertex's new place, and how many are used."""
+    check(np.asarray(indices).dtype in (np.uint32, np.int32), "indices must be 32 bit integers")
+    indices = index32(indices)
+    check(not triangles or len(indices) % 3 == 0, "triangles need indices in threes")
+    if triangles:
+        indices = _core.optimize_vertex_cache(indices, optsize)
+    remap, unique = _core.optimize_vertex_fetch_remap(indices)
+    return remap[indices], remap, unique
+
+
+def reorder_points(positions: np.ndarray) -> np.ndarray:
+    """The order to put points in so near ones are near in the list: each place's point."""
+    positions = np.ascontiguousarray(positions, dtype=np.float32)
+    check(positions.ndim == 2 and positions.shape[1] >= 3, "positions must be n by 3 or more")
+    return _core.spatial_sort_remap(positions.reshape(-1), *positions.shape)
+
+
+def encode_vertex_buffer(data: np.ndarray) -> bytes:
+    return encode_vertex_buffer_level(data, 2)
+
+
+def encode_vertex_buffer_level(data: np.ndarray, level: int, version: int | None = None) -> bytes:
+    """Rows of any type, each a multiple of four bytes, compressed harder from level 0 to 3."""
+    data, count, size = rows(data)
+    check(0 < size <= 256 and size % 4 == 0, "a row must be 4 to 256 bytes, in fours")
+    check(0 <= level <= 3, "level must be 0 to 3")
+    check(version in (None, 0, 1), "version must be 0 or 1")
+    return _core.encode_vertex_buffer(data, count, size, level, -1 if version is None else version)
+
+
+def encode_index_buffer(indices: np.ndarray) -> bytes:
+    indices = index32(indices)
+    check(len(indices) % 3 == 0, "triangles need indices in threes")
+    return _core.encode_index_buffer(indices)
+
+
+def encode_index_sequence(indices: np.ndarray) -> bytes:
+    return _core.encode_index_sequence(index32(indices))
+
+
+def encode_gltf_buffer(data: np.ndarray, mode: Mode, version: int = 0) -> bytes:
+    """Data as EXT_meshopt_compression stores it, for a bufferView of the mode."""
+    check(mode in ("ATTRIBUTES", "TRIANGLES", "INDICES"), "mode must be ATTRIBUTES, TRIANGLES or INDICES")
+    if mode == "ATTRIBUTES":
+        return encode_vertex_buffer_level(data, 2, version)
+    return encode_index_buffer(data) if mode == "TRIANGLES" else encode_index_sequence(data)
+
+
+def encode_filter(filter: str, values: np.ndarray, stride: int, bits: int, mode: int = 0, width: int = 4) -> np.ndarray:
+    values = np.ascontiguousarray(values, dtype=np.float32)
+    check(values.ndim == 2 and values.shape[1] == width, f"values must be n by {width}")
+    return _core.encode_filter(filter, values.reshape(-1), len(values), stride, bits, mode).reshape(-1, stride)
+
+
+def encode_filter_oct(values: np.ndarray, stride: int, bits: int) -> np.ndarray:
+    """Unit vectors, n by 4 with w kept as a sign, in octahedral form: n rows of stride bytes."""
+    check(stride in (4, 8), "stride must be 4 or 8")
+    check(2 <= bits <= 16, "bits must be 2 to 16")
+    return encode_filter("OCTAHEDRAL", values, stride, bits)
+
+
+def encode_filter_quat(values: np.ndarray, stride: int, bits: int) -> np.ndarray:
+    """Unit quaternions, n by 4, in their smallest three components: n rows of 8 bytes."""
+    check(stride == 8, "stride must be 8")
+    check(4 <= bits <= 16, "bits must be 4 to 16")
+    return encode_filter("QUATERNION", values, stride, bits)
+
+
+def encode_filter_exp(values: np.ndarray, bits: int, mode: ExpMode = "SharedVector") -> np.ndarray:
+    """Floats, n by k, as a mantissa of the bits and an exponent each, shared as the mode says: n rows of 4k bytes."""
+    check(mode in EXP_MODES, "mode must be Separate, SharedVector, SharedComponent or Clamped")
+    check(1 <= bits <= 24, "bits must be 1 to 24")
+    values = np.asarray(values)
+    check(values.ndim == 2 and values.shape[1] > 0, "values must be n by k")
+    return encode_filter("EXPONENTIAL", values, 4 * values.shape[1], bits, EXP_MODES[mode], values.shape[1])
+
+
+def encode_filter_color(values: np.ndarray, stride: int, bits: int) -> np.ndarray:
+    """Colours, n by 4 from 0 to 1, as YCoCg with alpha: n rows of stride bytes."""
+    check(stride in (4, 8), "stride must be 4 or 8")
+    check(2 <= bits <= 16, "bits must be 2 to 16")
+    return encode_filter("COLOR", values, stride, bits)
+
+
+def source(data: bytes | np.ndarray) -> np.ndarray:
+    return np.frombuffer(data, dtype=np.uint8) if isinstance(data, (bytes, bytearray, memoryview)) else np.ascontiguousarray(data, dtype=np.uint8).reshape(-1)
+
+
+def decode_vertex_buffer(data: bytes, count: int, size: int, filter: Filter | None = None) -> np.ndarray:
+    """Encoded rows back as count rows of size bytes, the filter undone if one is named."""
+    check(0 < size <= 256 and size % 4 == 0, "a row must be 4 to 256 bytes, in fours")
+    check(filter in (None, "NONE", "OCTAHEDRAL", "QUATERNION", "EXPONENTIAL", "COLOR"), "filter must be NONE, OCTAHEDRAL, QUATERNION, EXPONENTIAL or COLOR")
+    check(filter not in ("OCTAHEDRAL", "COLOR") or size in (4, 8), "this filter's rows are 4 or 8 bytes")
+    check(filter != "QUATERNION" or size == 8, "quaternion rows are 8 bytes")
+    return _core.decode_vertex_buffer(source(data), count, size, filter).reshape(count, size)
+
+
+def decode_index_buffer(data: bytes, count: int, size: int) -> np.ndarray:
+    """Encoded triangles back as count indices of size bytes, 2 or 4."""
+    check(size in (2, 4), "size must be 2 or 4")
+    check(count % 3 == 0, "triangles need indices in threes")
+    return _core.decode_index_buffer(source(data), count, size).view(np.uint16 if size == 2 else np.uint32)
+
+
+def decode_index_sequence(data: bytes, count: int, size: int) -> np.ndarray:
+    check(size in (2, 4), "size must be 2 or 4")
+    return _core.decode_index_sequence(source(data), count, size).view(np.uint16 if size == 2 else np.uint32)
+
+
+def decode_gltf_buffer(data: bytes, count: int, size: int, mode: Mode, filter: Filter | None = None) -> np.ndarray:
+    """An EXT_meshopt_compression bufferView back as plain data: rows of bytes, or indices."""
+    check(mode in ("ATTRIBUTES", "TRIANGLES", "INDICES"), "mode must be ATTRIBUTES, TRIANGLES or INDICES")
+    if mode == "ATTRIBUTES":
+        return decode_vertex_buffer(data, count, size, filter)
+    return decode_index_buffer(data, count, size) if mode == "TRIANGLES" else decode_index_sequence(data, count, size)

meshopt-0.1.0/src/meshopt.cpp

@@ -0,0 +1,164 @@
+// meshoptimizer's C functions, each called once on whole arrays with Python's lock let go. The checks that keep a call
+// in bounds are here; what makes a call sensible, as the JavaScript module asserts it, is in python/meshopt.
+
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/optional.h>
+#include <nanobind/stl/pair.h>
+#include <nanobind/stl/string.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "../vendor/meshoptimizer/meshoptimizer.h"
+
+namespace nb = nanobind;
+
+template <typename T> using In = nb::ndarray<const T, nb::ndim<1>, nb::c_contig, nb::device::cpu>;
+template <typename T> using Out = nb::ndarray<nb::numpy, T, nb::ndim<1>>;
+
+template <typename T> Out<T> out(std::vector<T>&& values)
+{
+	auto* held = new std::vector<T>(std::move(values));
+	nb::capsule owner(held, [](void* p) noexcept { delete static_cast<std::vector<T>*>(p); });
+	return Out<T>(held->data(), {held->size()}, owner);
+}
+
+static void sized(const char* name, size_t length, size_t count, size_t size)
+{
+	if (size != 0 && count > SIZE_MAX / size)
+		throw nb::value_error("too many values");
+	if (count * size != length)
+		throw nb::value_error((std::string(name) + " holds " + std::to_string(length) + " values, not " + std::to_string(count) + " by " + std::to_string(size)).c_str());
+}
+
+static size_t vertices(const unsigned int* indices, size_t count)
+{
+	return count ? size_t(*std::max_element(indices, indices + count)) + 1 : 0;
+}
+
+// Triangles reordered for a GPU's vertex cache, as a strip likes them when strip is set.
+static Out<uint32_t> optimize_vertex_cache(In<uint32_t> indices, bool strip)
+{
+	std::vector<uint32_t> result(indices.size());
+	{
+		nb::gil_scoped_release release;
+		size_t count = vertices(indices.data(), indices.size());
+		if (strip)
+			meshopt_optimizeVertexCacheStrip(result.data(), indices.data(), indices.size(), count);
+		else
+			meshopt_optimizeVertexCache(result.data(), indices.data(), indices.size(), count);
+	}
+	return out(std::move(result));
+}
+
+// Each vertex's new place, in the order the indices first use them, and how many are used.
+static std::pair<Out<uint32_t>, size_t> optimize_vertex_fetch_remap(In<uint32_t> indices)
+{
+	std::vector<uint32_t> remap;
+	size_t unique;
+	{
+		nb::gil_scoped_release release;
+		remap.resize(vertices(indices.data(), indices.size()));
+		unique = meshopt_optimizeVertexFetchRemap(remap.data(), indices.data(), indices.size(), remap.size());
+	}
+	return {out(std::move(remap)), unique};
+}
+
+// The points' order along a space-filling curve.
+static Out<uint32_t> spatial_sort_remap(In<float> positions, size_t count, size_t stride)
+{
+	sized("positions", positions.size(), count, stride);
+	if (stride < 3)
+		throw nb::value_error("a point has three coordinates at least");
+	std::vector<uint32_t> remap(count);
+	{
+		nb::gil_scoped_release release;
+		meshopt_spatialSortRemap(remap.data(), positions.data(), count, stride * sizeof(float));
+	}
+	return out(std::move(remap));
+}
+
+static nb::bytes encode_vertex_buffer(In<uint8_t> data, size_t count, size_t size, int level, int version)
+{
+	sized("data", data.size(), count, size);
+	std::vector<unsigned char> buffer;
+	{
+		nb::gil_scoped_release release;
+		buffer.resize(meshopt_encodeVertexBufferBound(count, size));
+		buffer.resize(meshopt_encodeVertexBufferLevel(buffer.data(), buffer.size(), data.data(), count, size, level, version));
+	}
+	return nb::bytes(buffer.data(), buffer.size());
+}
+
+template <size_t (*Bound)(size_t, size_t), size_t (*Encode)(unsigned char*, size_t, const unsigned int*, size_t)>
+static nb::bytes encode_indices(In<uint32_t> indices)
+{
+	std::vector<unsigned char> buffer;
+	{
+		nb::gil_scoped_release release;
+		buffer.resize(Bound(indices.size(), vertices(indices.data(), indices.size())));
+		buffer.resize(Encode(buffer.data(), buffer.size(), indices.data(), indices.size()));
+	}
+	return nb::bytes(buffer.data(), buffer.size());
+}
+
+// Floats in a filter's form: count elements of stride bytes, each read from four floats, or stride / 4 for exponents.
+static Out<uint8_t> encode_filter(const std::string& filter, In<float> data, size_t count, size_t stride, int bits, int mode)
+{
+	sized("data", data.size(), count, filter == "EXPONENTIAL" ? stride / 4 : 4);
+	std::vector<uint8_t> result(count * stride);
+	{
+		nb::gil_scoped_release release;
+		if (filter == "OCTAHEDRAL")
+			meshopt_encodeFilterOct(result.data(), count, stride, bits, data.data());
+		else if (filter == "QUATERNION")
+			meshopt_encodeFilterQuat(result.data(), count, stride, bits, data.data());
+		else if (filter == "EXPONENTIAL")
+			meshopt_encodeFilterExp(result.data(), count, stride, bits, data.data(), meshopt_EncodeExpMode(mode));
+		else
+			meshopt_encodeFilterColor(result.data(), count, stride, bits, data.data());
+	}
+	return out(std::move(result));
+}
+
+template <int (*Decode)(void*, size_t, size_t, const unsigned char*, size_t)>
+static Out<uint8_t> decode(In<uint8_t> source, size_t count, size_t size, std::optional<std::string> filter)
+{
+	if (size != 0 && count > SIZE_MAX / size)
+		throw nb::value_error("too many values");
+	std::vector<uint8_t> result(count * size);
+	int status;
+	{
+		nb::gil_scoped_release release;
+		status = Decode(result.data(), count, size, source.data(), source.size());
+		if (status == 0 && filter == "OCTAHEDRAL")
+			meshopt_decodeFilterOct(result.data(), count, size);
+		else if (status == 0 && filter == "QUATERNION")
+			meshopt_decodeFilterQuat(result.data(), count, size);
+		else if (status == 0 && filter == "EXPONENTIAL")
+			meshopt_decodeFilterExp(result.data(), count, size);
+		else if (status == 0 && filter == "COLOR")
+			meshopt_decodeFilterColor(result.data(), count, size);
+	}
+	if (status != 0)
+		throw nb::value_error(("Malformed buffer data: " + std::to_string(status)).c_str());
+	return out(std::move(result));
+}
+
+NB_MODULE(_core, m)
+{
+	m.def("optimize_vertex_cache", &optimize_vertex_cache);
+	m.def("optimize_vertex_fetch_remap", &optimize_vertex_fetch_remap);
+	m.def("spatial_sort_remap", &spatial_sort_remap);
+	m.def("encode_vertex_buffer", &encode_vertex_buffer);
+	m.def("encode_index_buffer", &encode_indices<meshopt_encodeIndexBufferBound, meshopt_encodeIndexBuffer>);
+	m.def("encode_index_sequence", &encode_indices<meshopt_encodeIndexSequenceBound, meshopt_encodeIndexSequence>);
+	m.def("encode_filter", &encode_filter);
+	m.def("decode_vertex_buffer", &decode<meshopt_decodeVertexBuffer>, nb::arg("source"), nb::arg("count"), nb::arg("size"), nb::arg("filter") = nb::none());
+	m.def("decode_index_buffer", [](In<uint8_t> source, size_t count, size_t size) { return decode<meshopt_decodeIndexBuffer>(source, count, size, std::nullopt); });
+	m.def("decode_index_sequence", [](In<uint8_t> source, size_t count, size_t size) { return decode<meshopt_decodeIndexSequence>(source, count, size, std::nullopt); });
+}