Hunyuan 3D 2.1 Meshlib Decimation

Your decoded mesh has 400k triangles. Your game engine wants 40k. Something has to give, and Hy3D21MeshlibDecimate is the thing that gives - it reduces a mesh's face count using the open-source MeshLib library's decimation, preserving the shape as well as any decimator is going to. The pack actually ships two meshlib decimators; this is the one with every dial exposed, the one you reach for when the simple version isn't enough and you need control.

The inputs that matter

Despite the wall of optional parameters, you will realistically touch two:

• target_face_num - the absolute face count you want to land on. If your mesh has 200k faces and you set this to 40k, that's your output count. The node computes how many faces to delete and lets MeshLib do it.
• target_face_ratio - an alternative: the fraction of faces to keep. 0.25 keeps a quarter. You must set one or the other - if both are 0, the node raises target_face_num or target_face_ratio must be set.

The one required input is subdivideParts (default 16) - the tooltip is refreshingly honest: "Should be the number of CPU/Core." MeshLib decimates in parallel parts, so set it to your core count for speed.

The knobs you can ignore (and one you can't)

The optional list is long: strategy (None, MinimizeError, ShortestEdgeFirst), maxError, maxEdgeLen, maxBdShift, maxTriangleAspectRatio, criticalTriAspectRatio, tinyEdgeLength, stabilizer, angleWeightedDistToPlane, optimizeVertexPos, collapseNearNotFlippable, touchNearBdEdges, maxAngleChange, decimateBetweenParts, minFacesInPart. These map directly to MeshLib's DecimateSettings - they're quality guards and heuristics for pathological meshes. For a beginner, leave them all alone. The one worth knowing: strategy changes the deletion order - MinimizeError prioritizes geometric fidelity (the default-ish pick for quality), ShortestEdgeFirst is faster and rougher.

How it works

The node builds a DecimateSettings with your targets, sets packMesh = True, hands it to the pack's postprocessmesh, and returns a new TRIMESH. It prints the before/after face counts to the console, which is a nice touch when you're iterating. Under the hood it's MeshLib's quadratic-error decimation - solid, battle-tested, and much faster than trimesh's own simplify for big meshes.

Installing it

Needs meshlib, which is the very last line of the pack's requirements.txt - so a normal install gets it:

cd ComfyUI/custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1
cd ComfyUI-Hunyuan3d-2-1
pip install -r requirements.txt

If the node errors with "meshlib not found," that line didn't install - pip install meshlib manually.

Common issues

If you set target_face_num higher than the current count, the node just returns the mesh unchanged (it guards against negative deletions). If decimation produces cracks or holes, that's aggressive target_face_ratio - keep above ~0.2 for organic shapes. And if you need textures preserved through decimation, be careful: the plain meshlib path here doesn't re-project UVs. For that workflow, the pack's HighPoly to LowPoly node is the one that handles baking textures onto decimated LODs properly.