Skip to content

Types¤

Type Conversion¤

Matching C++/Python types often takes the most of the time and requires careful attention. When implementing C++/Python bindings, follow these key patterns from the existing files or implement your own. If there are specific types you want to implement, review the nanobind tests . Ask questions in discussion section for nanobind typing or follow previous issues. Current implementation provides examples for the following types:

  • C++:
  • Use Eigen::Ref for matrix parameters, e.g. to transfer mesh vertex coordinates.
  • Return complex data as std::tuple<type, ...> types.
  • Use std::vector<type> for list copies otherwise use const std::vector<type> &.

  • Use Eigen Matrix types in vectors const std::vector<Eigen::Matrix<type, ...>> & instead of reference type const std::vector<Eigen::Ref<...>> &.

  • Python:

  • Use float64 for vertices and int32 for faces in numpy arrays
  • Enforce row-major (C-contiguous) order for matrices

Type Conversion Patterns¤

When implementing C++/Python bindings, follow these established patterns:

Matrix Operations¤

Use Eigen::Ref for efficient matrix passing:

void my_function(const Eigen::Ref<const RowMatrixXd>& vertices,
                const Eigen::Ref<const RowMatrixXi>& faces);

Return complex mesh data as tuples:

return std::tuple<RowMatrixXd, RowMatrixXi> my_function();

Enforce proper numpy array types using float64 and int32 in C-contiguous order:

import numpy as np
from compas_cgal.compas_cgal_ext import my_submodule

# Convert mesh vertices and faces to proper numpy arrays
vertices1 = np.asarray(mesh1.vertices, dtype=np.float64)
faces1 = np.asarray(mesh1.faces, dtype=np.int32)

# Pass to C++ function
V, F = my_submodule.my_function(vertices1, faces1)

Vector Types¤

For list data, choose between std::vector for value copies, const std::vector& for references, and std::vector<Eigen::Matrix<type, ...>> for matrix vectors.

Bind vector types explicitly:

// In module initialization
nb::bind_vector<std::vector<double>>(m, "VectorDouble");

Access in Python:

# Get vector result
vector_result = my_function()
# Access elements by index
x, y, z = vector_result[0], vector_result[1], vector_result[2]

Follow existing patterns: booleans.cpp: Matrix and tuple handling, measure.cpp: Array type validation, reconstruction.cpp: Complex data structures, skeletonization.cpp: Point cloud data, slicer.cpp: Geometry validation

Type Conversion Best Practices¤

When implementing new functionality:

  • Matrix Operations:
// GOOD: Use Eigen::Ref for matrix parameters
void my_function(Eigen::Ref<const RowMatrixXd> vertices);

// BAD: Don't use raw matrices
void my_function(Eigen::MatrixXd vertices);
  • Return Types:
// GOOD: Return complex data as tuples
std::tuple<RowMatrixXd, RowMatrixXi> my_mesh_operation();

// BAD: Don't use output parameters
void my_mesh_operation(RowMatrixXd& out_vertices);
  • Vector Handling:
// GOOD: Use const references for input vectors
void my_function(const std::vector<double>& input);

// GOOD: Return vectors by value
std::vector<double> MyOperation();

// BAD: Don't use non-const references
void my_function(std::vector<double>& input);
  • Matrix Vectors:
// GOOD: Use Matrix types in vectors
std::vector<Eigen::Matrix<double, 3, 1>> points;

// BAD: Don't use Ref types in vectors
std::vector<Eigen::Ref<Eigen::Vector3d>> points;
  • Python Integration:
# GOOD: Enforce proper types
vertices = np.array(points, dtype=np.float64)
faces = np.array(indices, dtype=np.int32)

# BAD: Don't rely on automatic conversion
vertices = points  # type not enforced
faces = indices   # type not enforced
  • Error Handling:
// GOOD: Validate and throw with clear messages
if (!IsMeshClosed(vertices, faces)) {
    throw std::runtime_error(
        "Mesh must be closed for boolean operations"
    );
}

// BAD: Don't silently handle errors
if (!IsMeshClosed(vertices, faces)) {
    return std::make_tuple(vertices, faces);  // original input
}