MergeIndexOutOfBounds

Diagnostic signature

MergeIndexOutOfBounds

The Manifold geometry library emits MergeIndexOutOfBounds when a provided MeshGL structure specifies merge indices that exceed the declared number of property vertices (numProp).

What it means

When constructing a Manifold object from a raw mesh representation (such as MeshGL or MeshGL64), the mergeFromVert and mergeToVert arrays dictate which property vertices should be topologically merged into a single geometric vertex. This allows sudden property changes (like hard edges or varying UV coordinates) without sacrificing topological manifoldness. This diagnostic indicates that one or more indices within these merge arrays are greater than or equal to the total number of property vertices (numProp), attempting to reference non-existent vertex data.

Why it happens

This error most commonly occurs when procedural meshes are being programmatically generated or during the manual stitching of non-manifold input geometry. If a mesh is split to duplicate vertices for distinct properties (such as color or normals) and the final vertex deduplication offsets are miscalculated, the merge arrays can point out of bounds. It also happens if numProp is mistakenly set to the number of distinct geometric coordinates (e.g., numVerts) rather than the total number of property vertices (which may be larger due to duplicated physical vertices), causing trailing merge indices to fall outside the [0, numProp - 1] range.

Minimal reproduction

#include <manifold.h>
#include <iostream>

using namespace manifold;

int main() {
    MeshGL mesh;
    mesh.numProp = 3; // Declaring 3 property vertices
    
    // Positions for a single triangle (3 properties * 3 floats/pos = 9 floats)
    mesh.vertProperties = {
        0.0f, 0.0f, 0.0f,
        1.0f, 0.0f, 0.0f,
        0.0f, 1.0f, 0.0f
    };
    mesh.triVerts = {0, 1, 2};
    
    // Invalid merge indexing: 3 is out of bounds for numProp = 3 (valid indices are 0, 1, 2)
    mesh.mergeFromVert = {3};
    mesh.mergeToVert = {0};
    
    Manifold m(mesh);
    
    if (m.Status() == Manifold::Error::MergeIndexOutOfBounds) {
        std::cout << "Expected diagnostic caught." << std::endl;
    }
    
    return 0;
}

How to fix it

Ensure all indices in the mergeFromVert and mergeToVert arrays are strictly less than numProp.

```c++
#include <manifold.h>
#include <iostream>

using namespace manifold;

int main() {
    MeshGL mesh;
    // Adding an extra property vertex for demonstration (numProp = 4)
    mesh.numProp = 4; 
    
    mesh.vertProperties = {
        0.0f, 0.0f, 0.0f,
        1.0f, 0.0f, 0.0f,
        0.0f, 1.0f, 0.0f,
        0.0f, 0.0f, 0.0f  // Duplicated geometric vertex for a property boundary
    };
    mesh.triVerts = {3, 1, 2}; // Triangle uses the duplicated vertex
    
    // Valid merge indexing: telling the kernel that property vertices 3 and 0 share the same geometric location
    mesh.mergeFromVert = {3};
    mesh.mergeToVert = {0};
    
    Manifold m(mesh);
    
    if (m.Status() == Manifold::Error::NoError) {
        std::cout << "Mesh properly converted to Manifold!" << std::endl;
    }
    
    return 0;
}
```

Step 1

• Verify that the numProp field accurately reflects the total number of property vertices in the array, rather than just the number of unique geometric locations.

Step 2

• Check the logic generating the mergeFromVert and mergeToVert arrays to ensure indices correctly map to property vertices in the range of 0 to numProp - 1.

Step 3

• If indices are based on a 1-based index or the length of a pre-split geometry array, recalculate them as 0-based offsets relative to the fully populated vertProperties array.

Upstream references

SplitByPlane() doesn't handle empty Manifold objects · Issue #1515 · elalish/manifold

Manifold is merging coplanar faces despite unique vertex properties · Issue #1316 · elalish/manifold

Using Manifold in Unity causes normals errors · Issue #1151 · elalish/manifold