{"id":9703,"library":"dracopy","title":"DracoPy - Draco Mesh Compression Wrapper","description":"DracoPy is a Python wrapper for Google's Draco Mesh Compression Library, enabling efficient encoding and decoding of 3D mesh data. It supports common formats like OBJ and PLY (via in-memory mesh objects). The current version is 2.0.0, with releases occurring infrequently, often coinciding with upstream Draco library updates or significant API overhauls.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/seung-lab/DracoPy","tags":["3d","mesh","compression","draco","numpy"],"install":[{"cmd":"pip install dracopy","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Commonly imported directly for encoding operations.","wrong":"import dracopy.encode","symbol":"encode","correct":"from dracopy import encode"},{"note":"Commonly imported directly for decoding operations.","wrong":"import dracopy.decode","symbol":"decode","correct":"from dracopy import decode"},{"note":"The primary class for representing mesh data.","wrong":"import dracopy.DracoMesh","symbol":"DracoMesh","correct":"from dracopy import DracoMesh"}],"quickstart":{"code":"import dracopy\nimport numpy as np\n\n# 1. Create a dummy mesh (a simple triangle)\n# Vertices and faces must be NumPy arrays in DracoPy 2.0.0+\nvertices = np.array([\n    [0.0, 0.0, 0.0],\n    [1.0, 0.0, 0.0],\n    [0.0, 1.0, 0.0]\n], dtype=np.float32)\n\nfaces = np.array([\n    [0, 1, 2]\n], dtype=np.int32)\n\n# Create a DracoMesh object\nmesh_to_encode = dracopy.DracoMesh(vertices=vertices, faces=faces)\n\n# 2. Encode the mesh to Draco bytes\nprint(\"Encoding mesh...\")\ndraco_bytes = dracopy.encode(mesh_to_encode, compression_level=7)\nprint(f\"Encoded bytes length: {len(draco_bytes)}\")\n\n# 3. Decode the Draco bytes back to a DracoMesh\nprint(\"Decoding mesh...\")\ndecoded_mesh = dracopy.decode(draco_bytes)\n\n# 4. Access decoded data (still NumPy arrays)\nprint(f\"Decoded vertices shape: {decoded_mesh.vertices.shape}\")\nprint(f\"Decoded faces shape: {decoded_mesh.faces.shape}\")\n\n# Optional: Verify data equality\nassert np.array_equal(vertices, decoded_mesh.vertices)\nassert np.array_equal(faces, decoded_mesh.faces)\nprint(\"Encoding and decoding successful!\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure all mesh data passed to `DracoMesh` or assigned to its attributes are NumPy arrays. Convert existing lists using `np.array(your_list)`.","message":"`DracoMesh` attributes (`vertices`, `faces`, `normals`, `colors`, `uvs`) now strictly require NumPy arrays instead of Python lists.","severity":"breaking","affected_versions":"2.0.0+"},{"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)`.","message":"The helper functions `dracopy.decode_file` and `dracopy.encode_file` have been removed.","severity":"breaking","affected_versions":"2.0.0+"},{"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.","message":"Installation can fail if pre-compiled wheels are not available for your specific Python/OS/architecture combination, requiring local compilation.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"The `vertex_features` and `face_features` parameters in the `DracoMesh` constructor have been removed.","severity":"deprecated","affected_versions":"2.0.0+"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to create a `DracoMesh` or set its attributes with Python lists instead of NumPy arrays after upgrading to version 2.0.0.","error":"TypeError: expected ndarray, got list"},{"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.","cause":"Using the `decode_file` or `encode_file` helper functions, which were removed in version 2.0.0.","error":"AttributeError: module 'dracopy' has no attribute 'decode_file'"},{"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.","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.","error":"ImportError: DLL load failed while importing _dracopy (Windows) / ImportError: ... undefined symbol: ... (Linux)"},{"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)`.","cause":"`DracoMesh` requires at least `vertices` and `faces` to be provided when initialized.","error":"ValueError: Missing required mesh data (vertices and faces)"}]}