tmb-codec 0.2.0__py3-none-win_amd64.whl

tmb_codec/__init__.py

@@ -0,0 +1,23 @@
+"""Python bindings for the TMB1 triangle mesh codec."""
+
+from .codec import (
+    CORNER_ROTATION,
+    FACE_IDS,
+    VERTEX_IDS,
+    MeshInfo,
+    decode,
+    encode,
+    inspect,
+)
+
+__all__ = [
+    "CORNER_ROTATION",
+    "FACE_IDS",
+    "VERTEX_IDS",
+    "MeshInfo",
+    "decode",
+    "encode",
+    "inspect",
+]
+
+__version__ = "0.2.0"

tmb_codec/codec.py

@@ -0,0 +1,230 @@
+"""NumPy API for the native TMB1 codec."""
+
+from __future__ import annotations
+
+import ctypes as ct
+import os
+import struct
+import sys
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+import numpy as np
+import numpy.typing as npt
+import zstandard as zstd
+
+VERTEX_IDS = 1 << 0
+FACE_IDS = 1 << 1
+CORNER_ROTATION = 1 << 2
+
+_MAGIC = 0x31424D54
+_VERSION = 1
+_QUANTIZED = 1 << 8
+_BITS_SHIFT = 16
+_HEADER = struct.Struct("<10I")
+_MAX_RAW = 128 * 1024 * 1024
+_LIBRARY: ct.CDLL | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MeshInfo:
+    vertex_count: int
+    face_count: int
+    bits: int | None
+    flags: int
+    compressed: bool
+
+    @property
+    def lossless(self) -> bool:
+        return self.bits is None
+
+
+def _library_name() -> str:
+    if os.name == "nt":
+        return "tmb_codec.dll"
+    if sys.platform == "darwin":
+        return "libtmb_codec.dylib"
+    return "libtmb_codec.so"
+
+
+def _library() -> ct.CDLL:
+    global _LIBRARY
+    if _LIBRARY is not None:
+        return _LIBRARY
+    override = os.environ.get("TMB_CODEC_LIBRARY")
+    path = Path(override) if override else Path(str(files("tmb_codec") / "_native" / _library_name()))
+    if not path.is_file():
+        raise ModuleNotFoundError(f"TMB native library is not installed: {path}")
+    library = ct.CDLL(str(path.resolve()))
+    encode_base = [ct.c_void_p, ct.c_uint32, ct.c_void_p, ct.c_uint32, ct.c_uint32]
+    decode_base = [
+        ct.c_void_p,
+        ct.c_size_t,
+        ct.c_void_p,
+        ct.c_void_p,
+        ct.c_uint32,
+        ct.c_uint32,
+        ct.c_uint32,
+    ]
+    library.tmb_encode_lossless.argtypes = encode_base + [
+        ct.POINTER(ct.c_void_p),
+        ct.POINTER(ct.c_size_t),
+        ct.c_void_p,
+    ]
+    library.tmb_encode_lossless.restype = ct.c_int
+    library.tmb_encode_quantized.argtypes = encode_base + [
+        ct.c_uint32,
+        ct.POINTER(ct.c_void_p),
+        ct.POINTER(ct.c_size_t),
+        ct.c_void_p,
+    ]
+    library.tmb_encode_quantized.restype = ct.c_int
+    library.tmb_decode_lossless.argtypes = decode_base + [ct.c_void_p]
+    library.tmb_decode_lossless.restype = ct.c_int
+    library.tmb_decode_quantized.argtypes = decode_base + [ct.c_uint32, ct.c_void_p]
+    library.tmb_decode_quantized.restype = ct.c_int
+    library.tmb_free.argtypes = [ct.c_void_p]
+    library.tmb_free.restype = None
+    _LIBRARY = library
+    return library
+
+
+def _arrays(
+    vertices: npt.ArrayLike, faces: npt.ArrayLike
+) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.uint32]]:
+    vertex_array = np.ascontiguousarray(vertices, dtype=np.float32)
+    original_faces = np.asarray(faces)
+    if (
+        vertex_array.ndim != 2
+        or vertex_array.shape[1] != 3
+        or not len(vertex_array)
+        or not np.isfinite(vertex_array).all()
+    ):
+        raise ValueError("vertices must be a finite float32 array with shape [V,3]")
+    if (
+        original_faces.ndim != 2
+        or original_faces.shape[1] != 3
+        or not len(original_faces)
+        or original_faces.dtype.kind not in "iu"
+        or original_faces.min() < 0
+        or original_faces.max() >= len(vertex_array)
+    ):
+        raise ValueError("faces must contain valid triangle vertex indices")
+    return vertex_array, np.ascontiguousarray(original_faces, dtype=np.uint32)
+
+
+def encode(
+    vertices: npt.ArrayLike,
+    faces: npt.ArrayLike,
+    *,
+    bits: int | None = 14,
+    flags: int = VERTEX_IDS,
+    compress: bool = True,
+    compression_level: int = 2,
+) -> bytes:
+    """Encode a triangle mesh; ``bits=None`` preserves float32 positions exactly."""
+    if flags not in range(8):
+        raise ValueError("flags must be in [0,7]")
+    if bits is not None and not 1 <= bits <= 31:
+        raise ValueError("bits must be None or in [1,31]")
+    vertex_array, face_array = _arrays(vertices, faces)
+    library = _library()
+    output = ct.c_void_p()
+    output_size = ct.c_size_t()
+    timings = np.empty(3, dtype=np.float64)
+    common = (
+        vertex_array.ctypes.data,
+        len(vertex_array),
+        face_array.ctypes.data,
+        len(face_array),
+        flags,
+    )
+    code = (
+        library.tmb_encode_lossless(
+            *common, ct.byref(output), ct.byref(output_size), timings.ctypes.data
+        )
+        if bits is None
+        else library.tmb_encode_quantized(
+            *common, bits, ct.byref(output), ct.byref(output_size), timings.ctypes.data
+        )
+    )
+    if code:
+        raise ValueError(f"TMB1 encode failed ({code})")
+    try:
+        raw = ct.string_at(output, output_size.value)
+    finally:
+        library.tmb_free(output)
+    return zstd.ZstdCompressor(level=compression_level).compress(raw) if compress else raw
+
+
+def _raw(data: bytes | bytearray | memoryview, compressed: bool) -> bytes:
+    body = bytes(data)
+    if not compressed:
+        return body
+    try:
+        size = zstd.frame_content_size(body)
+        if size < 0 or size == zstd.CONTENTSIZE_UNKNOWN or size > _MAX_RAW:
+            raise ValueError("invalid decompressed size")
+        return zstd.ZstdDecompressor(max_window_size=128 * 1024).decompress(
+            body, max_output_size=_MAX_RAW, allow_extra_data=False
+        )
+    except zstd.ZstdError as exc:
+        raise ValueError("invalid Zstd frame") from exc
+
+
+def _info(raw: bytes, compressed: bool) -> MeshInfo:
+    if len(raw) < _HEADER.size:
+        raise ValueError("truncated TMB1 header")
+    header = _HEADER.unpack_from(raw)
+    magic, version, wire_flags, vertex_count, face_count = header[:5]
+    flags = wire_flags & 7
+    quantized = bool(wire_flags & _QUANTIZED)
+    bits = (wire_flags >> _BITS_SHIFT) & 31
+    expected = flags | (_QUANTIZED if quantized else 0) | (bits << _BITS_SHIFT)
+    if magic != _MAGIC or version != _VERSION or wire_flags != expected:
+        raise ValueError("unsupported TMB1 version or flags")
+    if not 0 < vertex_count <= 2_000_000 or not 0 < face_count <= 4_000_000:
+        raise ValueError("TMB1 mesh exceeds supported limits")
+    if quantized != bool(bits):
+        raise ValueError("invalid TMB1 precision")
+    if sum(header[5:]) != len(raw) - _HEADER.size:
+        raise ValueError("invalid TMB1 section lengths")
+    return MeshInfo(vertex_count, face_count, bits if quantized else None, flags, compressed)
+
+
+def inspect(data: bytes | bytearray | memoryview, *, compressed: bool = True) -> MeshInfo:
+    """Read validated public metadata without decoding the mesh."""
+    raw = _raw(data, compressed)
+    return _info(raw, compressed)
+
+
+def decode(
+    data: bytes | bytearray | memoryview, *, compressed: bool = True
+) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.uint32]]:
+    """Decode TMB1 bytes into contiguous ``vertices`` and ``faces`` arrays."""
+    raw = _raw(data, compressed)
+    info = _info(raw, compressed)
+    vertices = np.empty((info.vertex_count, 3), dtype=np.float32)
+    faces = np.empty((info.face_count, 3), dtype=np.uint32)
+    timings = np.empty(2, dtype=np.float64)
+    common = (
+        raw,
+        len(raw),
+        vertices.ctypes.data,
+        faces.ctypes.data,
+        info.vertex_count,
+        info.face_count,
+        info.flags,
+    )
+    library = _library()
+    code = (
+        library.tmb_decode_lossless(*common, timings.ctypes.data)
+        if info.lossless
+        else library.tmb_decode_quantized(*common, info.bits, timings.ctypes.data)
+    )
+    if code:
+        raise ValueError(f"TMB1 decode failed ({code})")
+    if not np.isfinite(vertices).all() or faces.max() >= info.vertex_count:
+        raise ValueError("invalid decoded mesh")
+    return vertices, faces

tmb_codec/licenses/CORTO_LICENSE.txt

@@ -0,0 +1,21 @@
+Corto
+Copyright (c) 2015-2022, Visual Computing Lab, ISTI - CNR
+All rights reserved.
+
+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.

tmb_codec/py.typed

@@ -0,0 +1 @@
+

tmb_codec-0.2.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: tmb-codec
+Version: 0.2.0
+Summary: Fast Triangle Mesh Binary encoding and decoding
+Author: Tyndall-log
+License-Expression: MIT
+License-File: LICENSE
+License-File: licenses/CORTO_LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Project-URL: Documentation, https://github.com/Tyndall-log/tmb-codec#readme
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: zstandard>=0.23
+Description-Content-Type: text/markdown
+
+# TMB Codec
+
+TMB1 (Triangle Mesh Binary) is a compact general-purpose triangle-mesh codec. The
+library provides one C ABI across Windows, macOS, Linux, and WebAssembly.
+Native CI builds use Clang (`clang-cl` on Windows and `clang++` elsewhere).
+
+## Features
+
+- Float32 bit-exact lossless positions
+- Quantized positions from 1 through 31 bits
+- Optional restoration of vertex IDs, face IDs, and triangle corner rotation
+- Single-file C++17 implementation
+- No runtime dependency on Zstd; compress the completed TMB1 bundle once outside
+  the codec when using `tmb1-zstd-v1`
+
+Applications that require stable per-vertex data use `TMB_VERTEX_IDS` (`flags=1`). This restores
+vertex rows and triangle references to original vertex IDs while allowing face
+row order and cyclic starting corners to remain in traversal order.
+
+## Python
+
+Install a prebuilt native wheel:
+
+```bash
+pip install tmb-codec
+```
+
+```python
+from tmb_codec import decode, encode
+
+data = encode(vertices, faces, bits=14)
+decoded_vertices, decoded_faces = decode(data)
+
+lossless = encode(vertices, faces, bits=None)
+```
+
+Wheels contain the Python API, the platform-native shared library, and license
+notices. They do not contain `src/tmb_codec.cpp` or an sdist.
+
+## Native build
+
+Windows:
+
+```powershell
+cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang-cl -DTMB_BUILD_TESTS=ON
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+macOS and Linux:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release -DTMB_BUILD_TESTS=ON
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+WebAssembly with Emscripten:
+
+```bash
+emcmake cmake -S . -B build-wasm -DCMAKE_BUILD_TYPE=Release -DTMB_BUILD_TESTS=OFF
+cmake --build build-wasm --parallel
+node tests/wasm_smoke.mjs build-wasm/tmb_codec.js
+```
+
+The WASM build emits `tmb_codec.js` and `tmb_codec.wasm` with
+memory growth enabled and exports the five public TMB functions plus malloc/free.
+
+Every push and pull request builds and installs native wheels on Windows, macOS,
+and Linux and runs the Python tests against those installed wheels. WASM has a
+separate Node.js round-trip test. Pushing a `v*` tag publishes wheels to PyPI and
+then creates a GitHub Release only after every required job succeeds.
+
+## C API
+
+```cpp
+#include <tmb_codec.h>
+
+unsigned char* bytes = nullptr;
+size_t byte_count = 0;
+double timings[3] = {};
+int result = tmb_encode_quantized(
+    vertices, vertex_count,
+    faces, face_count,
+    TMB_VERTEX_IDS, 14,
+    &bytes, &byte_count, timings);
+if (result == TMB_OK) {
+    // Send zstd(bytes[0:byte_count]) or store the raw TMB1 bundle.
+    tmb_free(bytes);
+}
+```
+
+Inputs are contiguous `float[V][3]` positions and `uint32_t[F][3]` triangle
+indices. Encoder output is allocated by the codec and must be released with
+`tmb_free`. Decoder output arrays are allocated by the caller.
+
+## Format
+
+TMB1 starts with ten little-endian uint32 values:
+
+1. Magic `TMB1`
+2. Format version `1`
+3. Flags
+4. Vertex count
+5. Face count
+6. Topology section size
+7. Position section size
+8. Vertex-ID section size
+9. Face-ID section size
+10. Corner-rotation section size
+
+Quantized streams set flag bit 8 and store the coordinate bit count in flag bits
+16 through 20. Their position section begins with four little-endian float64
+values: origin x/y/z and a common extent. Coordinates from 1 through 16 bits use
+one integer component per axis. Coordinates from 17 through 31 bits use low/high
+16-bit components to keep prediction residuals inside signed 32-bit range.
+
+The topology and position entropy streams are defined by the reference source in
+`src/tmb_codec.cpp`. Consumers should use the provided encoder and decoder
+unless they also maintain compatibility tests against the reference implementation.
+
+## License
+
+The codec incorporates and modifies MIT-licensed Corto code. Preserve
+`licenses/CORTO_LICENSE.txt` with source and binary distributions. Project-level
+terms are in `LICENSE`; third-party attribution is in `THIRD_PARTY_NOTICES.md`.

tmb_codec-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tmb_codec/__init__.py,sha256=E5_bzkk2CHCqBtpNyEsj-YmUAku82AMxqKZhuH7IAUk,359
+tmb_codec/_native/tmb_codec.dll,sha256=pmrdN5Pz7oktD_cOzCMfAMIk4sDGFDpVECdPqXsUn4o,211968
+tmb_codec/codec.py,sha256=ig7lmaUve7BpgSaOS8XgxBtuObF9rZiV6sIc9gJjv1o,7840
+tmb_codec/licenses/CORTO_LICENSE.txt,sha256=pO8euBMldLQyYyiVVpDkqp9wRdOd4fJzbyB9OtrobIo,1130
+tmb_codec/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+tmb_codec-0.2.0.dist-info/METADATA,sha256=moKzgWEHJ4O80UszveDqi68Tg9E_Px4MQ-FBpOwfnRc,4669
+tmb_codec-0.2.0.dist-info/WHEEL,sha256=7cuQBrKlgrMjywT6nmSZIIhuOog1xNCTkMyVVbw2aow,103
+tmb_codec-0.2.0.dist-info/licenses/LICENSE,sha256=cQwMShNEo-Ae_Kix_mPphGFiM4tPRJe5fxVbnIa_lC0,1089
+tmb_codec-0.2.0.dist-info/licenses/licenses/CORTO_LICENSE.txt,sha256=pO8euBMldLQyYyiVVpDkqp9wRdOd4fJzbyB9OtrobIo,1130
+tmb_codec-0.2.0.dist-info/RECORD,,

tmb_codec-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.6
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

tmb_codec-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyndall-log
+
+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.

tmb_codec-0.2.0.dist-info/licenses/licenses/CORTO_LICENSE.txt

@@ -0,0 +1,21 @@
+Corto
+Copyright (c) 2015-2022, Visual Computing Lab, ISTI - CNR
+All rights reserved.
+
+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.