MeshLib SDK Documentation

API values (meshes, bit sets, settings, etc.) hold WebAssembly memory that is not reclaimed by the JavaScript garbage collector. You must free these objects explicitly to avoid memory leaks.

Recommended: Explicit Resource Management (using)

For Node.js 24+ or modern browsers, use the using keyword. This automatically calls the disposal logic when the variable goes out of scope.

using mesh = ml.Mesh.fromTriangles(coords, tris);
// mesh is automatically freed at the end of this scope

Handling dynamic numbers of objects (DisposableStack)

If you are creating many objects in a loop, use a DisposableStack to manage them collectively:

using stack = new DisposableStack();
for (const path of inputPaths) {
  const cloud = stack.use(ml.PointsLoad.fromAnySupportedFormat(path));
  // ... use cloud
}
// All handles in the stack are freed here in reverse order

Legacy: Manual .delete()

On older runtimes, you must manually call the .delete() method on each object when finished:

const mesh = ml.Mesh.fromTriangles(coords, tris);
// ... use mesh
mesh.delete();

To ensure C++ code is correctly parsed and exported to bindings, follow these rules:

1. Use Export Macros

Every function in a header within a parsed project must have its corresponding export macro (e.g., MRMESH_API for MRMesh). Failure to do this results in undefined reference errors in the bindings. For internal functions, move them to namespace MR::detail instead of omitting the macro.

2. Avoid Incomplete Types

Bindings require types to be "complete" (the full definition must be visible). Unlike standard C++, you cannot use a forward declaration alone if the type is required for the function signature.

• Fix: Add the necessary #include that defines the type.
• Exception: If you cannot include the header, wrap the code in #if MR_PARSING_FOR_PB11_BINDINGS.

3. Pointer Semantics

All pointer types (function parameters, return values, or class fields) are assumed to point to single objects, not arrays. To pass arrays, use std::vector or std::array instead of raw pointers or std::span (until supported).

To prevent dangling pointers or references in C# and Python, MeshLib uses a 'keep-alive' mechanism. Each managed object maintains a list of other objects it must keep alive. To ensure these relationships are correctly tracked, you must annotate C++ functions that store references or return class references using specific macros from <MRMesh/MRMacros.h>.

When to annotate manually:

• When a function returns a class reference (unless it's a global).
• When a function takes a class reference (or raw pointer) and stores it (e.g., in this or in a member variable).

Annotation Logic

Annotations are stored as pairs (a, b), performing a._KeepAlive.push_back(b).

• a can be a function parameter, this, or the return value.
• b can be a function parameter or this (but not the return value).

Macro Types

1. MR_LIFETIMEBOUND: Used when the return value depends on a parameter or this.
2. MR_LIFETIME_CAPTURE_BY(param_name): Used when a parameter is stored in this or another parameter.
3. MR_THIS_LIFETIME_CAPTURE_BY(param_name): Used when a parameter is stored in this (specifically for this as the target).
4. ..._NESTED variants: Used when you are copying an object rather than storing a reference, but want to copy its internal keep-alive list into the target object (e.g., in container push_back methods).

// Example: Returning a reference (Return value depends on parameter)
MR::Mesh& foo( MR::Mesh& m MR_LIFETIMEBOUND )
{
    return m;
}

// Example: Storing a reference in 'this'
struct B
{
    std::vector<A> vec;
    void add( MR::Mesh& mesh MR_LIFETIME_CAPTURE_BY(this) )
    {
        vec.add( A{mesh} );
    }
};

Objects returned by the MeshLib API (such as meshes, bit sets, and result objects) hold WebAssembly memory that is not managed by the JavaScript garbage collector. You must explicitly free these objects to prevent memory leaks.

Option 1: Explicit Resource Management (Recommended)

If you are using Node.js 24+ or a modern browser, use the using keyword. This automatically calls the cleanup logic when the variable goes out of scope.

using mesh = ml.Mesh.fromTriangles(coords, tris);
// mesh is automatically freed here

For dynamic numbers of handles (e.g., inside a loop), use a DisposableStack:

using stack = new DisposableStack();
for (const path of inputPaths) {
  const cloud = stack.use(ml.PointsLoad.fromAnySupportedFormat(path));
  // ... use cloud
}
// All handles in the stack are freed here in reverse order

Option 2: Manual Deletion (Legacy/Older Runtimes)

On older runtimes that do not support using or DisposableStack, you must manually call the .delete() method on every object when you are finished with it.

// Manual cleanup for older runtimes
const mesh = ml.Mesh.fromTriangles(coords, tris);
// ... use mesh
mesh.delete();

Templates require specific handling because the bindings parser attempts to instantiate every template it encounters.

Use requires for constrained members

If a member function is only valid for certain template arguments, you must annotate it with requires. To maintain compatibility across platforms that may not support C++20, use the MR_REQUIRES_IF_SUPPORTED macro from MRMesh/MRMacros.h.

template <typename T>
struct Pair
{
    T first, second;

    T sum() const MR_REQUIRES_IF_SUPPORTED( std::is_arithmetic_v<T> )
    {
        return first + second;
    }
};

Manually instantiate templates

Non-member template functions and class templates must be manually instantiated for the desired types using the MR_BIND_TEMPLATE macro, unless an extern template already exists.

template <typename T> T foo(T t) {...}
MR_BIND_TEMPLATE( int foo(int t) )
MR_BIND_TEMPLATE( float foo(float t) )

Prefer friend definitions

Instead of free functions, use friend definitions inside classes (e.g., for overloaded operators or begin()/end()). The parser automatically instantiates friend functions, whereas free functions require manual MR_BIND_TEMPLATE calls.

template <typename T>
struct Pair
{
    T first, second;

    T sum() const MR_REQUIRES_IF_SUPPORTED( std::is_arithmetic_v<T> )
    {
        return first + second;
    }
};

// Manual instantiation for free functions
template <typename T> T foo(T t) {...}
MR_BIND_TEMPLATE( int foo(int t) )
MR_BIND_TEMPLATE( float foo(float t) )

// Preferred approach for operators
template <typename T>
struct A
{
    friend A operator+(A, A) {...}
};

Rules are applied in the order they appear in the rules input. Each rule can optionally be guarded by an if: condition.

include — Extend matching rows or add new ones

1. Splits rule keys into axis keys (existing in base) and extra keys.
2. Merges extra keys into all existing entries that match the axis-key criteria.
3. If no entry matches and there is at least one axis key, it appends the rule as a new entry.
4. If there are no axis keys, it appends the rule as a new entry unconditionally.

extend — Extend matching rows only (never adds)

1. Splits rule keys into axis keys and extra keys.
2. Merges extra keys into existing entries matching the axis-key criteria.
3. If no entry matches, it is a silent no-op. It never appends new entries.
4. If there are no axis keys, it merges the extra keys into every entry (useful for setting defaults).

exclude — Drop matching rows

Removes every entry where every key/value pair in the rule matches the entry. Keys not present in an entry do not match.