DracoPy - Draco Mesh Compression Wrapper

Common errors

• TypeError: expected ndarray, got list

  cause Attempting to create a `DracoMesh` or set its attributes with Python lists instead of NumPy arrays after upgrading to version 2.0.0.
  fix Convert your mesh data (vertices, faces, etc.) to NumPy arrays before passing them to `DracoMesh` or `encode`/`decode`. E.g., `vertices=np.array(my_vertex_list, dtype=np.float32)`.

• AttributeError: module 'dracopy' has no attribute 'decode_file'

  cause Using the `decode_file` or `encode_file` helper functions, which were removed in version 2.0.0.
  fix Manually handle file reading/writing. Read the file into bytes, then pass to `dracopy.decode()`. Write the bytes returned by `dracopy.encode()` to a file. See warnings for an example.

• ImportError: DLL load failed while importing _dracopy (Windows) / ImportError: ... undefined symbol: ... (Linux)

  cause The underlying C++ Draco library failed to load or compile correctly, often due to missing system dependencies, incompatible architecture, or a broken wheel installation.
  fix Try reinstalling `dracopy`. If issues persist, ensure your system has C++ build tools if wheels aren't used. Check `pip` output for specific errors. For Linux, ensure `libstdc++` is up to date. Consider creating a new virtual environment.

• ValueError: Missing required mesh data (vertices and faces)

  cause `DracoMesh` requires at least `vertices` and `faces` to be provided when initialized.
  fix Ensure both `vertices` and `faces` NumPy arrays are passed to the `DracoMesh` constructor. E.g., `dracopy.DracoMesh(vertices=my_verts_array, faces=my_faces_array)`.

Warnings

• breaking `DracoMesh` attributes (`vertices`, `faces`, `normals`, `colors`, `uvs`) now strictly require NumPy arrays instead of Python lists.
  Fix: Ensure all mesh data passed to `DracoMesh` or assigned to its attributes are NumPy arrays. Convert existing lists using `np.array(your_list)`.
• breaking The helper functions `dracopy.decode_file` and `dracopy.encode_file` have been removed.
  Fix: Users must now handle file I/O explicitly. Read file content into bytes before passing to `dracopy.decode()` and write `dracopy.encode()` output bytes to a file manually. For example: `with open('mesh.drc', 'rb') as f: mesh_bytes = f.read(); decoded_mesh = dracopy.decode(mesh_bytes)`.
• gotcha Installation can fail if pre-compiled wheels are not available for your specific Python/OS/architecture combination, requiring local compilation.
  Fix: Ensure your system has the necessary build tools (e.g., C++ compiler, CMake) if wheels are not provided. Check the official GitHub repository for more specific build requirements for your platform. Consider using a common Python version (3.8-3.10) for which wheels are typically provided.
• deprecated The `vertex_features` and `face_features` parameters in the `DracoMesh` constructor have been removed.
  Fix: These parameters are no longer supported. If you were using them, re-evaluate how you are representing and handling custom attributes. The current `DracoMesh` structure focuses on standard mesh components (vertices, faces, normals, colors, uvs).

Install

• pip install dracopy Install stable version

Imports

• encode
  wrong:

  import dracopy.encode

  correct:

  from dracopy import encode

  Commonly imported directly for encoding operations.
• decode
  wrong:

  import dracopy.decode

  correct:

  from dracopy import decode

  Commonly imported directly for decoding operations.
• DracoMesh
  wrong:

  import dracopy.DracoMesh

  correct:

  from dracopy import DracoMesh

  The primary class for representing mesh data.

Quickstart

This quickstart demonstrates how to create a simple 3D mesh using NumPy arrays, encode it into Draco compressed bytes, and then decode it back into a `DracoMesh` object. It highlights the use of NumPy for mesh data, which is standard in version 2.0.0 and above.

import dracopy
import numpy as np

# 1. Create a dummy mesh (a simple triangle)
# Vertices and faces must be NumPy arrays in DracoPy 2.0.0+
vertices = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0]
], dtype=np.float32)

faces = np.array([
    [0, 1, 2]
], dtype=np.int32)

# Create a DracoMesh object
mesh_to_encode = dracopy.DracoMesh(vertices=vertices, faces=faces)

# 2. Encode the mesh to Draco bytes
print("Encoding mesh...")
draco_bytes = dracopy.encode(mesh_to_encode, compression_level=7)
print(f"Encoded bytes length: {len(draco_bytes)}")

# 3. Decode the Draco bytes back to a DracoMesh
print("Decoding mesh...")
decoded_mesh = dracopy.decode(draco_bytes)

# 4. Access decoded data (still NumPy arrays)
print(f"Decoded vertices shape: {decoded_mesh.vertices.shape}")
print(f"Decoded faces shape: {decoded_mesh.faces.shape}")

# Optional: Verify data equality
assert np.array_equal(vertices, decoded_mesh.vertices)
assert np.array_equal(faces, decoded_mesh.faces)
print("Encoding and decoding successful!")