occtl_mesh.h File Reference

OCCT-Light: mesh (triangulation) module public API. More...

#include <stddef.h>
#include <stdint.h>
#include "occtl_core.h"
#include "occtl_geom.h"
#include "occtl_topo.h"

Include dependency graph for occtl_mesh.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	occtl_aabb3
struct	occtl_mesh_options
struct	occtl_mesh_from_buffers_options
struct	occtl_triangulation_view
struct	occtl_polygon3d_view
struct	occtl_polygon_on_tri_view
struct	occtl_mesh_triangle_buffers_view
struct	occtl_mesh_triangle_analysis_view
struct	occtl_mesh_triangle_components_options
struct	occtl_mesh_triangle_components_view
struct	occtl_mesh_triangle_component_triangles_view
struct	occtl_mesh_triangle_component_boundary_edge
struct	occtl_mesh_triangle_component_boundary_chain
struct	occtl_mesh_component_boundary_polyline
struct	occtl_mesh_triangle_component_boundary_view
struct	occtl_mesh_triangle_component_boundary_chains_view
struct	occtl_mesh_component_boundary_polylines_view
struct	occtl_mesh_triangle_component_summary
struct	occtl_mesh_triangle_component_summaries_view
struct	occtl_mesh_triangle_plane_components_options
struct	occtl_mesh_triangle_plane_component
struct	occtl_mesh_triangle_plane_components_view
struct	occtl_mesh_triangle_sphere_components_options
struct	occtl_mesh_triangle_sphere_component
struct	occtl_mesh_triangle_sphere_components_view
struct	occtl_mesh_triangle_cylinder_components_options
struct	occtl_mesh_triangle_cylinder_component
struct	occtl_mesh_triangle_cylinder_components_view

Macros
#define	OCCTL_MESH_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_OPTIONS_INIT
#define	OCCTL_MESH_FROM_BUFFERS_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_FROM_BUFFERS_OPTIONS_INIT    {OCCTL_MESH_FROM_BUFFERS_OPTIONS_VERSION_1, NULL, NULL, 0, NULL, 0, 0.0}
#define	OCCTL_MESH_TRIANGLE_ADJACENCY_BOUNDARY   UINT32_MAX
#define	OCCTL_MESH_TRIANGLE_COMPONENTS_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_TRIANGLE_COMPONENTS_OPTIONS_INIT
#define	OCCTL_MESH_TRIANGLE_PLANE_COMPONENTS_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_TRIANGLE_PLANE_COMPONENTS_OPTIONS_INIT
#define	OCCTL_MESH_TRIANGLE_SPHERE_COMPONENTS_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_TRIANGLE_SPHERE_COMPONENTS_OPTIONS_INIT
#define	OCCTL_MESH_TRIANGLE_CYLINDER_COMPONENTS_OPTIONS_VERSION_1   1u
#define	OCCTL_MESH_TRIANGLE_CYLINDER_COMPONENTS_OPTIONS_INIT

Typedefs
typedef struct occtl_aabb3	occtl_aabb3_t
typedef struct occtl_mesh_options	occtl_mesh_options_t
typedef struct occtl_mesh_from_buffers_options	occtl_mesh_from_buffers_options_t
typedef struct occtl_triangulation_view	occtl_triangulation_view_t
typedef struct occtl_polygon3d_view	occtl_polygon3d_view_t
typedef struct occtl_polygon_on_tri_view	occtl_polygon_on_tri_view_t
typedef struct occtl_mesh_triangle_buffers_view	occtl_mesh_triangle_buffers_view_t
typedef struct occtl_mesh_triangle_analysis_view	occtl_mesh_triangle_analysis_view_t
typedef struct occtl_mesh_triangle_components_options	occtl_mesh_triangle_components_options_t
typedef struct occtl_mesh_triangle_components_view	occtl_mesh_triangle_components_view_t
typedef struct occtl_mesh_triangle_component_triangles_view	occtl_mesh_triangle_component_triangles_view_t
typedef struct occtl_mesh_triangle_component_boundary_edge	occtl_mesh_triangle_component_boundary_edge_t
typedef struct occtl_mesh_triangle_component_boundary_chain	occtl_mesh_triangle_component_boundary_chain_t
typedef struct occtl_mesh_component_boundary_polyline	occtl_mesh_component_boundary_polyline_t
typedef struct occtl_mesh_triangle_component_boundary_view	occtl_mesh_triangle_component_boundary_view_t
typedef struct occtl_mesh_triangle_component_boundary_chains_view	occtl_mesh_triangle_component_boundary_chains_view_t
typedef struct occtl_mesh_component_boundary_polylines_view	occtl_mesh_component_boundary_polylines_view_t
typedef struct occtl_mesh_triangle_component_summary	occtl_mesh_triangle_component_summary_t
typedef struct occtl_mesh_triangle_component_summaries_view	occtl_mesh_triangle_component_summaries_view_t
typedef struct occtl_mesh_triangle_plane_components_options	occtl_mesh_triangle_plane_components_options_t
typedef struct occtl_mesh_triangle_plane_component	occtl_mesh_triangle_plane_component_t
typedef struct occtl_mesh_triangle_plane_components_view	occtl_mesh_triangle_plane_components_view_t
typedef struct occtl_mesh_triangle_sphere_components_options	occtl_mesh_triangle_sphere_components_options_t
typedef struct occtl_mesh_triangle_sphere_component	occtl_mesh_triangle_sphere_component_t
typedef struct occtl_mesh_triangle_sphere_components_view	occtl_mesh_triangle_sphere_components_view_t
typedef struct occtl_mesh_triangle_cylinder_components_options	occtl_mesh_triangle_cylinder_components_options_t
typedef struct occtl_mesh_triangle_cylinder_component	occtl_mesh_triangle_cylinder_component_t
typedef struct occtl_mesh_triangle_cylinder_components_view	occtl_mesh_triangle_cylinder_components_view_t

Functions
void	occtl_mesh_options_init (occtl_mesh_options_t *options)
occtl_status_t	occtl_mesh_model_metadata_set (occtl_graph_t *graph, const char *key, size_t keyLen, const char *value, size_t valueLen)
occtl_status_t	occtl_mesh_model_metadata_get (const occtl_graph_t *graph, const char *key, size_t keyLen, char *buf, size_t bufSize, size_t *out_required)
occtl_status_t	occtl_mesh_model_metadata_keys (const occtl_graph_t *graph, occtl_metadata_key_view_t *out_keys, size_t cap, size_t *out_count)
occtl_status_t	occtl_mesh_model_metadata_unset (occtl_graph_t *graph, const char *key, size_t keyLen)
void	occtl_mesh_from_buffers_options_init (occtl_mesh_from_buffers_options_t *options)
occtl_status_t	occtl_mesh_from_buffers (const occtl_mesh_from_buffers_options_t *options, occtl_graph_t **out_graph, occtl_node_id_t *out_root)
occtl_status_t	occtl_mesh_generate (occtl_graph_t *graph, const occtl_node_id_t *nodes, size_t n_nodes, const occtl_mesh_options_t *options)
occtl_status_t	occtl_mesh_face_triangulation (const occtl_graph_t *graph, occtl_node_id_t face, occtl_triangulation_view_t *out_view)
occtl_status_t	occtl_mesh_face_triangulation_count (const occtl_graph_t *graph, occtl_node_id_t face, uint32_t *out_count)
occtl_status_t	occtl_mesh_face_triangulation_indexed (const occtl_graph_t *graph, occtl_node_id_t face, uint32_t index, occtl_triangulation_view_t *out_view)
occtl_status_t	occtl_mesh_edge_polygon3d (const occtl_graph_t *graph, occtl_node_id_t edge, occtl_polygon3d_view_t *out_view)
occtl_status_t	occtl_mesh_coedge_polygon_on_tri (const occtl_graph_t *graph, occtl_node_id_t coedge, occtl_polygon_on_tri_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_buffers (const occtl_graph_t *graph, occtl_node_id_t root, occtl_mesh_triangle_buffers_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_analysis (const occtl_graph_t *graph, occtl_node_id_t root, occtl_mesh_triangle_analysis_view_t *out_view)
void	occtl_mesh_triangle_components_options_init (occtl_mesh_triangle_components_options_t *options)
occtl_status_t	occtl_mesh_triangle_components (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, occtl_mesh_triangle_components_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_component_triangles (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, uint32_t component_id, occtl_mesh_triangle_component_triangles_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_component_boundary (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, uint32_t component_id, occtl_mesh_triangle_component_boundary_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_component_boundary_chains (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, uint32_t component_id, occtl_mesh_triangle_component_boundary_chains_view_t *out_view)
occtl_status_t	occtl_mesh_component_boundary_polylines (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, uint32_t component_id, occtl_mesh_component_boundary_polylines_view_t *out_view)
occtl_status_t	occtl_mesh_triangle_component_summaries (const occtl_graph_t *graph, const occtl_mesh_triangle_components_options_t *options, occtl_mesh_triangle_component_summaries_view_t *out_view)
void	occtl_mesh_triangle_plane_components_options_init (occtl_mesh_triangle_plane_components_options_t *options)
occtl_status_t	occtl_mesh_triangle_plane_components (const occtl_graph_t *graph, const occtl_mesh_triangle_plane_components_options_t *options, occtl_mesh_triangle_plane_components_view_t *out_view)
void	occtl_mesh_triangle_sphere_components_options_init (occtl_mesh_triangle_sphere_components_options_t *options)
occtl_status_t	occtl_mesh_triangle_sphere_components (const occtl_graph_t *graph, const occtl_mesh_triangle_sphere_components_options_t *options, occtl_mesh_triangle_sphere_components_view_t *out_view)
void	occtl_mesh_triangle_cylinder_components_options_init (occtl_mesh_triangle_cylinder_components_options_t *options)
occtl_status_t	occtl_mesh_triangle_cylinder_components (const occtl_graph_t *graph, const occtl_mesh_triangle_cylinder_components_options_t *options, occtl_mesh_triangle_cylinder_components_view_t *out_view)
occtl_status_t	occtl_mesh_make_sphere_component_solid (occtl_graph_t *graph, const occtl_mesh_triangle_sphere_components_options_t *options, uint32_t component_id, occtl_node_id_t *out_solid)
occtl_status_t	occtl_mesh_make_cylinder_component_solid (occtl_graph_t *graph, const occtl_mesh_triangle_cylinder_components_options_t *options, uint32_t component_id, occtl_node_id_t *out_solid)
occtl_status_t	occtl_mesh_make_sphere_component_solids (occtl_graph_t *graph, const occtl_mesh_triangle_sphere_components_options_t *options, occtl_node_id_t *out_buf, size_t cap, size_t *out_count)
occtl_status_t	occtl_mesh_make_cylinder_component_solids (occtl_graph_t *graph, const occtl_mesh_triangle_cylinder_components_options_t *options, occtl_node_id_t *out_buf, size_t cap, size_t *out_count)
occtl_status_t	occtl_mesh_make_plane_component_face (occtl_graph_t *graph, const occtl_mesh_triangle_plane_components_options_t *options, uint32_t component_id, occtl_node_id_t *out_face)
occtl_status_t	occtl_mesh_make_plane_component_faces (occtl_graph_t *graph, const occtl_mesh_triangle_plane_components_options_t *options, occtl_node_id_t *out_buf, size_t cap, size_t *out_count)

Detailed Description

OCCT-Light: mesh (triangulation) module public API.

Generates surface tessellations and edge polylines for a graph and exposes the cached results — face triangulations, edge polygons, coedge polygons-on-triangulation — as POD views into library-owned memory.

Indexing convention.

Triangle vertex indices and polygon-on-triangulation node indices are 0-indexed in this ABI (matching NumPy / WASM / C# conventions). View pointers expose the converted buffers directly.

Lifetime.

Mesh views borrow from the source graph. Their pointers remain valid until the graph is mutated (any builder call, any subsequent occtl_mesh_generate, or graph free) — see each accessor for the exact contract.

See also

occtl_topo_face_has_triangulation (in occtl_topo.h) — predicate for whether a face has a cached triangulation.

../../docs/design/MODULES.md §8 for the module charter.

Macro Definition Documentation

OCCTL_MESH_OPTIONS_INIT

#define OCCTL_MESH_OPTIONS_INIT

Value:

  {OCCTL_MESH_OPTIONS_VERSION_1,                                                                   \
   NULL,                                                                                           \
   0.001,                                                                                          \
   0.5,                                                                                            \
   -1.0,                                                                                           \
   -1.0,                                                                                           \
   -1.0,                                                                                           \
   0,                                                                                              \
   0,                                                                                              \
   1,                                                                                              \
   1,                                                                                              \
   0,                                                                                              \
   1,                                                                                              \
   0,                                                                                              \
   0,                                                                                              \
   0,                                                                                              \
   0,                                                                                              \
   {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}},                                                             \
   0.001,                                                                                          \
   OCCTL_ANGLE_20_DEG_RAD}

Static initialiser for occtl_mesh_options_t. Suitable for

occtl_mesh_options_t opts = OCCTL_MESH_OPTIONS_INIT; 

The angular-deflection default uses OCCTL_ANGLE_20_DEG_RAD (20 degrees).

OCCTL_MESH_OPTIONS_VERSION_1

#define OCCTL_MESH_OPTIONS_VERSION_1   1u

Current options struct version. Bumped only on a binary-incompatible change. New fields are appended via p_next-chained extension structs.

OCCTL_MESH_TRIANGLE_COMPONENTS_OPTIONS_INIT

#define OCCTL_MESH_TRIANGLE_COMPONENTS_OPTIONS_INIT

Value:

  {OCCTL_MESH_TRIANGLE_COMPONENTS_OPTIONS_VERSION_1,                                               \
   NULL,                                                                                           \
   OCCTL_NODE_ID_INVALID,                                                                          \
   OCCTL_ANGLE_1_DEG_RAD,                                                                          \
   1}

OCCTL_MESH_TRIANGLE_CYLINDER_COMPONENTS_OPTIONS_INIT

#define OCCTL_MESH_TRIANGLE_CYLINDER_COMPONENTS_OPTIONS_INIT

Value:

  {OCCTL_MESH_TRIANGLE_CYLINDER_COMPONENTS_OPTIONS_VERSION_1,                                      \
   NULL,                                                                                           \
   OCCTL_NODE_ID_INVALID,                                                                          \
   OCCTL_ANGLE_30_DEG_RAD,                                                                         \
   1,                                                                                              \
   1.0e-3,                                                                                         \
   0.0,                                                                                            \
   4u,                                                                                             \
   1.0e-9}

OCCTL_MESH_TRIANGLE_PLANE_COMPONENTS_OPTIONS_INIT

#define OCCTL_MESH_TRIANGLE_PLANE_COMPONENTS_OPTIONS_INIT

Value:

  {OCCTL_MESH_TRIANGLE_PLANE_COMPONENTS_OPTIONS_VERSION_1,                                         \
   NULL,                                                                                           \
   OCCTL_NODE_ID_INVALID,                                                                          \
   OCCTL_ANGLE_1_DEG_RAD,                                                                          \
   1,                                                                                              \
   1.0e-6,                                                                                         \
   0.0,                                                                                            \
   1u}

OCCTL_MESH_TRIANGLE_SPHERE_COMPONENTS_OPTIONS_INIT

#define OCCTL_MESH_TRIANGLE_SPHERE_COMPONENTS_OPTIONS_INIT

Value:

  {OCCTL_MESH_TRIANGLE_SPHERE_COMPONENTS_OPTIONS_VERSION_1,                                        \
   NULL,                                                                                           \
   OCCTL_NODE_ID_INVALID,                                                                          \
   OCCTL_ANGLE_30_DEG_RAD,                                                                         \
   1,                                                                                              \
   1.0e-3,                                                                                         \
   0.0,                                                                                            \
   4u,                                                                                             \
   1.0e-9}

Typedef Documentation

occtl_aabb3_t

typedef struct occtl_aabb3 occtl_aabb3_t

Axis-aligned bounding box in 3D.

Math-POD per ABI_PATTERNS.md §15: passed by value, not versioned. Used only by occtl_mesh_options_t today; if a second consumer appears in another module, promote this declaration to occtl_geom.h in a follow-up.

occtl_mesh_component_boundary_polyline_t

typedef struct occtl_mesh_component_boundary_polyline occtl_mesh_component_boundary_polyline_t

Ordered boundary polyline descriptor for one triangle component.

Polylines index into the ordered point array returned by occtl_mesh_component_boundary_polylines. Closed polylines repeat the first point as the final point so consumers can draw or build closed loops without consulting the edge array.

occtl_mesh_component_boundary_polylines_view_t

typedef struct occtl_mesh_component_boundary_polylines_view occtl_mesh_component_boundary_polylines_view_t

Borrowed graph-owned ordered boundary-polyline view for one triangle component.

Points are copied from the aggregate triangle-buffer node coordinates and ordered according to occtl_mesh_triangle_component_boundary_chains. The buffer remains valid until graph is mutated, freed, or occtl_mesh_component_boundary_polylines is called again on the same graph.

occtl_mesh_from_buffers_options_t

typedef struct occtl_mesh_from_buffers_options occtl_mesh_from_buffers_options_t

Input buffers for occtl_mesh_from_buffers.

Nodes are xyz-interleaved doubles. Triangles are 0-indexed triplets into nodes, matching the rest of the public mesh ABI. The library copies the buffers into an OCCT #Poly_Triangulation owned by a new graph, so the caller may free the input arrays after the function returns.

occtl_mesh_options_t

typedef struct occtl_mesh_options occtl_mesh_options_t

Tunable parameters for occtl_mesh_generate.

Two parameter sources are supported, selected by the use_bbox field: explicit deflection / angle controls, or bbox-derived where the linear deflection is recomputed from a caller-supplied bounding box and a relative coefficient.

Defaults (see OCCTL_MESH_OPTIONS_INIT and occtl_mesh_options_init) are the conservative ones: linear deflection 0.001, angular deflection 0.5 rad, interior fields = -1.0 (inherit from boundary), single threaded, control-surface deflection on, model cleanup on.

Cancellation and algorithm selection.

Cooperative cancellation and a tessellation-algorithm enum will be added behind p_next when a binding asks for them; this v1 surface is locked to the default algorithm and runs to completion.

occtl_mesh_triangle_analysis_view_t

typedef struct occtl_mesh_triangle_analysis_view occtl_mesh_triangle_analysis_view_t

Borrowed graph-owned analysis buffers over aggregate triangulations.

This view uses the same root traversal as occtl_mesh_triangle_buffers, then materialises per-triangle normals and triangle adjacency into the graph-owned mesh cache. Normals are xyz interleaved doubles, one normal per triangle. Adjacency is three uint32_t entries per triangle; entry 3*i+0 is the neighbouring triangle across edge (v0,v1), 3*i+1 across edge (v1,v2), and 3*i+2 across edge (v2,v0). Boundary edges use OCCTL_MESH_TRIANGLE_ADJACENCY_BOUNDARY.

The buffers remain valid until graph is mutated, freed, or occtl_mesh_triangle_analysis is called again on the same graph.

occtl_mesh_triangle_buffers_view_t

typedef struct occtl_mesh_triangle_buffers_view occtl_mesh_triangle_buffers_view_t

Borrowed aggregate triangle-soup view over cached face triangulations.

The view copies all included face triangulations into graph-owned ABI buffers. Nodes are xyz interleaved doubles; triangle indices are 0-indexed into nodes. The buffers remain valid until graph is mutated, freed, or occtl_mesh_triangle_buffers is called again on the same graph.

When a Product / Occurrence hierarchy is traversed, accumulated graph locations are applied to copied vertices. The buffer is intentionally a triangle soup: vertices shared by neighboring faces may appear more than once.

occtl_mesh_triangle_component_boundary_chain_t

typedef struct occtl_mesh_triangle_component_boundary_chain occtl_mesh_triangle_component_boundary_chain_t

Ordered boundary chain descriptor for one triangle component.

Chains index into the ordered edge array returned by occtl_mesh_triangle_component_boundary_chains. A closed chain has matching end/start nodes; an open chain represents a non-manifold or open mesh boundary.

occtl_mesh_triangle_component_boundary_chains_view_t

typedef struct occtl_mesh_triangle_component_boundary_chains_view occtl_mesh_triangle_component_boundary_chains_view_t

Borrowed graph-owned ordered boundary-chain view for one triangle component.

Edges are oriented so edges[i].node1 equals edges[i+1].node0 inside each chain. Chain descriptors provide contiguous ranges into edges. The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_component_boundary_chains is called again on the same graph.

occtl_mesh_triangle_component_boundary_edge_t

typedef struct occtl_mesh_triangle_component_boundary_edge occtl_mesh_triangle_component_boundary_edge_t

Boundary edge of one normal-connected triangle component.

node0 and node1 are aggregate triangle-buffer node indices in the edge orientation of triangle. adjacent_triangle is either OCCTL_MESH_TRIANGLE_ADJACENCY_BOUNDARY for an open mesh edge, or the neighbouring triangle that belongs to a different component across a sharp component boundary.

occtl_mesh_triangle_component_boundary_view_t

typedef struct occtl_mesh_triangle_component_boundary_view occtl_mesh_triangle_component_boundary_view_t

Borrowed graph-owned boundary-edge view for one triangle component.

The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_component_boundary is called again on the same graph.

occtl_mesh_triangle_component_summaries_view_t

typedef struct occtl_mesh_triangle_component_summaries_view occtl_mesh_triangle_component_summaries_view_t

Borrowed graph-owned component summaries over aggregate triangulations.

Summaries are ordered by component ID and use the same component labelling rules as occtl_mesh_triangle_components for the supplied options.

The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_component_summaries is called again on the same graph.

occtl_mesh_triangle_component_summary_t

typedef struct occtl_mesh_triangle_component_summary occtl_mesh_triangle_component_summary_t

Summary statistics for one normal-connected triangle component.

Area, centroid, average normal, and bounds are computed from the graph-owned aggregate triangle buffers. The centroid and normal are area-weighted. Degenerate components report zero area and a zero normal.

occtl_mesh_triangle_component_triangles_view_t

typedef struct occtl_mesh_triangle_component_triangles_view occtl_mesh_triangle_component_triangles_view_t

Borrowed graph-owned triangle-index view for one component.

Triangle indices refer to the aggregate triangle order returned by occtl_mesh_triangle_buffers for the same root/options. The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_component_triangles is called again on the same graph.

occtl_mesh_triangle_components_options_t

typedef struct occtl_mesh_triangle_components_options occtl_mesh_triangle_components_options_t

Options for occtl_mesh_triangle_components.

Components are grown across triangle adjacency when neighbouring triangle normals differ by no more than max_normal_angle. When include_opposite_normals is non-zero, normals with opposite signs are treated as equivalent by comparing abs(dot(n0,n1)); this is useful for imported triangle soups with inconsistent winding.

occtl_mesh_triangle_components_view_t

typedef struct occtl_mesh_triangle_components_view occtl_mesh_triangle_components_view_t

Borrowed graph-owned connected-component labels over aggregate triangulations.

triangle_component_ids has one entry per triangle. IDs are dense and 0-indexed in first-discovery order. component_sizes has one entry per component and counts how many triangles carry that component ID.

The buffers remain valid until graph is mutated, freed, or occtl_mesh_triangle_components is called again on the same graph.

occtl_mesh_triangle_cylinder_component_t

typedef struct occtl_mesh_triangle_cylinder_component occtl_mesh_triangle_cylinder_component_t

Cylinder-like normal-connected triangle component.

The cylinder axis passes through axis_origin in unit direction axis_direction. height_min and height_max are the minimum and maximum vertex projections along that axis relative to axis_origin. max_distance is the largest absolute radial residual among all component triangle vertices.

occtl_mesh_triangle_cylinder_components_options_t

typedef struct occtl_mesh_triangle_cylinder_components_options occtl_mesh_triangle_cylinder_components_options_t

Options for occtl_mesh_triangle_cylinder_components.

Components are first built with the same normal-angle rules as occtl_mesh_triangle_components. A component is accepted as cylinder-like when an OCCT eigen / least-squares cylinder fit satisfies the minimum size filters and every triangle vertex is within max_distance of the fitted cylinder.

occtl_mesh_triangle_cylinder_components_view_t

typedef struct occtl_mesh_triangle_cylinder_components_view occtl_mesh_triangle_cylinder_components_view_t

Borrowed graph-owned cylinder-like component view.

The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_cylinder_components is called again on the same graph.

occtl_mesh_triangle_plane_component_t

typedef struct occtl_mesh_triangle_plane_component occtl_mesh_triangle_plane_component_t

Plane-like normal-connected triangle component.

The plane passes through origin with unit normal. max_distance is the largest absolute OCCT plane distance among all component triangle vertices.

occtl_mesh_triangle_plane_components_options_t

typedef struct occtl_mesh_triangle_plane_components_options occtl_mesh_triangle_plane_components_options_t

Options for occtl_mesh_triangle_plane_components.

Components are first built with the same normal-angle rules as occtl_mesh_triangle_components. A component is accepted as plane-like when it satisfies the minimum size filters and every triangle vertex is within max_distance of the component plane.

occtl_mesh_triangle_plane_components_view_t

typedef struct occtl_mesh_triangle_plane_components_view occtl_mesh_triangle_plane_components_view_t

Borrowed graph-owned plane-like component view.

The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_plane_components is called again on the same graph.

occtl_mesh_triangle_sphere_component_t

typedef struct occtl_mesh_triangle_sphere_component occtl_mesh_triangle_sphere_component_t

Sphere-like normal-connected triangle component.

The sphere is represented by center and positive radius. max_distance is the largest absolute radial residual among all component triangle vertices.

occtl_mesh_triangle_sphere_components_options_t

typedef struct occtl_mesh_triangle_sphere_components_options occtl_mesh_triangle_sphere_components_options_t

Options for occtl_mesh_triangle_sphere_components.

Components are first built with the same normal-angle rules as occtl_mesh_triangle_components. A component is accepted as sphere-like when an OCCT least-squares sphere fit satisfies the minimum size filters and every triangle vertex is within max_distance of the fitted sphere.

occtl_mesh_triangle_sphere_components_view_t

typedef struct occtl_mesh_triangle_sphere_components_view occtl_mesh_triangle_sphere_components_view_t

Borrowed graph-owned sphere-like component view.

The buffer remains valid until graph is mutated, freed, or occtl_mesh_triangle_sphere_components is called again on the same graph.

occtl_polygon3d_view_t

typedef struct occtl_polygon3d_view occtl_polygon3d_view_t

Zero-copy view of a 3D polyline cached on an edge.

Zero-copy span/view per ABI §10.2; pointers borrow from a per-graph internal cache; lifetime matches occtl_triangulation_view_t.

parameters carries the curve parameter at each polyline node when one was stored alongside the polyline, NULL otherwise.

occtl_polygon_on_tri_view_t

typedef struct occtl_polygon_on_tri_view occtl_polygon_on_tri_view_t

Zero-copy view of a coedge polyline indexed onto its parent face's triangulation.

node_indices entries are 0-indexed into the nodes array of the parent face's triangulation. Buffers are materialised on first read into a per-coedge cache.

Zero-copy span/view per ABI §10.2; pointer fields borrow from a per-graph internal cache; lifetime matches occtl_triangulation_view_t.

occtl_triangulation_view_t

typedef struct occtl_triangulation_view occtl_triangulation_view_t

Zero-copy view of a face triangulation.

Math-POD per ABI_PATTERNS.md §15 — not versioned (re-shape via a new type if the field set ever changes).

All pointer fields borrow from a per-graph internal cache. Each cache slot remembers the source node's version stamp; the next fetch after any mutation (builder, boolean op, compact, occtl_mesh_generate) sees the slot as stale and re-materialises into a fresh allocation. Existing pointers remain valid until this graph mutates and another fetch on the same face triggers re-materialisation, so callers that straddle a mutation must copy out or refetch.

Triangle indices are 0-indexed into nodes — buffers are materialised on first read into a per-face cache.

normals and uvs are NULL when the underlying triangulation carries no per-vertex normals / UV nodes; check before dereferencing.

Function Documentation

occtl_mesh_coedge_polygon_on_tri()

occtl_status_t occtl_mesh_coedge_polygon_on_tri	(	const occtl_graph_t *	graph,
		occtl_node_id_t	coedge,
		occtl_polygon_on_tri_view_t *	out_view
	)

Returns the cached polygon-on-triangulation for coedge.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	coedge	NodeId of a coedge in graph.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	coedge is invalid / removed, or it has no cached polygon-on-triangulation.
OCCTL_WRONG_KIND	coedge is not OCCTL_KIND_COEDGE.

\par Thread Safety Yes.

occtl_mesh_component_boundary_polylines()

occtl_status_t occtl_mesh_component_boundary_polylines	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		uint32_t	component_id,
		occtl_mesh_component_boundary_polylines_view_t *	out_view
	)

Returns ordered 3D boundary polylines for one triangle component.

This computes ordered boundary chains and materialises their aggregate node indices as 3D points. Closed chains repeat their first point at the end of the polyline.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Component ID to select.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives borrowed ordered polyline buffers owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_component_boundary_chains, occtl_mesh_triangle_buffers

occtl_mesh_edge_polygon3d()

occtl_status_t occtl_mesh_edge_polygon3d	(	const occtl_graph_t *	graph,
		occtl_node_id_t	edge,
		occtl_polygon3d_view_t *	out_view
	)

Returns the cached 3D polygon on edge.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	edge	NodeId of an edge in graph.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	edge is invalid / removed, or it has no cached 3D polygon.
OCCTL_WRONG_KIND	edge is not OCCTL_KIND_EDGE.

\par Thread Safety Yes.

occtl_mesh_face_triangulation()

occtl_status_t occtl_mesh_face_triangulation	(	const occtl_graph_t *	graph,
		occtl_node_id_t	face,
		occtl_triangulation_view_t *	out_view
	)

Returns the active cached triangulation of face.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	face	NodeId of a face in graph.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. On success populated with a borrowed view; on failure left untouched.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	face is invalid / removed, or it has no cached triangulation (run occtl_mesh_generate first).
OCCTL_WRONG_KIND	face is not OCCTL_KIND_FACE.
OCCTL_INTERNAL	Internal failure.

\par Thread Safety Yes (read-only on graph).

See also

occtl_topo_face_has_triangulation, occtl_mesh_face_triangulation_count, occtl_mesh_face_triangulation_indexed

occtl_mesh_face_triangulation_count()

occtl_status_t occtl_mesh_face_triangulation_count	(	const occtl_graph_t *	graph,
		occtl_node_id_t	face,
		uint32_t *	out_count
	)

Returns the number of cached triangulations on face.

Faces may carry several LOD-style triangulations; this accessor reports how many. Most workflows use the active triangulation (occtl_mesh_face_triangulation) and ignore the multi-mesh case.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	face	NodeId of a face in graph.
[out]	out_count	Borrows it. Must be non-NULL.

Return values

OCCTL_OK	Success; out_count receives the count (0 when there is no cached mesh).
OCCTL_INVALID_ARGUMENT	graph or out_count is NULL.
OCCTL_NOT_FOUND	face is invalid or removed.
OCCTL_WRONG_KIND	face is not OCCTL_KIND_FACE.

\par Thread Safety Yes.

See also

occtl_mesh_face_triangulation, occtl_mesh_face_triangulation_indexed

occtl_mesh_face_triangulation_indexed()

occtl_status_t occtl_mesh_face_triangulation_indexed	(	const occtl_graph_t *	graph,
		occtl_node_id_t	face,
		uint32_t	index,
		occtl_triangulation_view_t *	out_view
	)

Returns the index-th cached triangulation of face.

index ranges over [0, occtl_mesh_face_triangulation_count(graph, face)).

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	face	NodeId of a face in graph.
[in]	index	0-based triangulation index.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	face is invalid or has no cached mesh.
OCCTL_OUT_OF_RANGE	index is past the number of cached triangulations.
OCCTL_WRONG_KIND	face is not OCCTL_KIND_FACE.

\par Thread Safety Yes.

See also

occtl_mesh_face_triangulation

occtl_mesh_from_buffers()

occtl_status_t occtl_mesh_from_buffers	(	const occtl_mesh_from_buffers_options_t *	options,
		occtl_graph_t **	out_graph,
		occtl_node_id_t *	out_root
	)

Creates a graph containing one triangulated Face from caller buffers.

This is the inverse of the triangle-soup extraction helper for workflows that receive mesh data from engines, WASM, or 3D-print pipelines. The implementation copies caller buffers into OCCT #Poly_Triangulation and attaches that triangulation to a Face using OCCT topology builders before ingesting the result through BRepGraph. No wrapper-local mesh store is kept.

Parameters

[in]	options	Borrows it. Must be non-NULL and fully initialised.
[out]	out_graph	Owns it. Receives a new graph handle. Must be released with occtl_graph_free.
[out]	out_root	Borrows it. Receives the triangulated Face root.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	options, out_graph, or out_root is NULL; p_next is non-NULL; buffers are inconsistent; coordinates are not finite; an index is out of range; or deflection is negative / non-finite.
OCCTL_VERSION_MISMATCH	options->struct_version is unsupported.
OCCTL_GEOMETRY_INVALID	OCCT could not construct a triangulated face from the buffers.
OCCTL_TOPOLOGY_INVALID	The triangulated face could not be ingested into BRepGraph.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (allocates a new graph; does not touch shared state).

See also

occtl_mesh_triangle_buffers, occtl_mesh_face_triangulation

occtl_mesh_from_buffers_options_init()

void occtl_mesh_from_buffers_options_init

(

occtl_mesh_from_buffers_options_t *

options

)

Runtime initialiser for occtl_mesh_from_buffers_options_t.

Sets all fields to OCCTL_MESH_FROM_BUFFERS_OPTIONS_INIT.

Parameters

[out]

options

Borrows it. NULL-tolerant; no-op when NULL.

\par Thread Safety Yes.

See also

occtl_mesh_from_buffers

occtl_mesh_generate()

occtl_status_t occtl_mesh_generate	(	occtl_graph_t *	graph,
		const occtl_node_id_t *	nodes,
		size_t	n_nodes,
		const occtl_mesh_options_t *	options
	)

Tessellates the graph (or a node subset).

Three modes folded into a single entry point through nodes / n_nodes:

• nodes == NULL && n_nodes == 0 — mesh every active face and free edge in graph (whole-graph dispatch).
• nodes != NULL && n_nodes == 1 — mesh the subtree rooted at that node (single-root dispatch).
• nodes != NULL && n_nodes > 1 — mesh the deduplicated set of faces reachable from any of the given nodes (multi-node dispatch).

If options->use_bbox is non-zero the algorithm derives parameters from options->bbox / options->deviation_coefficient / options->deviation_angle; otherwise the explicit deflection / angle / ... fields are used directly.

On success, any cached mesh views over graph are invalidated; re-fetch via the accessor functions below before reading.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Mutated: receives generated mesh data on its faces / edges / coedges.
[in]	nodes	Borrows it. May be NULL when n_nodes is 0. When non-NULL must point to at least n_nodes valid occtl_node_id_t entries that already live in graph.
[in]	n_nodes	Number of node IDs. 0 selects the whole-graph dispatch. Must be 0 when nodes is NULL.
[in]	options	Borrows it. Must be non-NULL with a recognised struct_version.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or options is NULL, or nodes / n_nodes is inconsistent.
OCCTL_VERSION_MISMATCH	options->struct_version is unrecognised.
OCCTL_NOT_FOUND	A NodeId in nodes is invalid or has been removed from graph.
OCCTL_NOT_DONE	The tessellation algorithm reported failure.
OCCTL_OUT_OF_MEMORY	Allocation failed.
OCCTL_INTERNAL	A C++ exception was caught at the ABI boundary.

\par Thread Safety No — mutates graph.

See also

occtl_mesh_face_triangulation, occtl_mesh_edge_polygon3d

occtl_mesh_make_cylinder_component_solid()

occtl_status_t occtl_mesh_make_cylinder_component_solid	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_cylinder_components_options_t *	options,
		uint32_t	component_id,
		occtl_node_id_t *	out_solid
	)

Rebuilds one cylinder-like triangle component as an analytic cylinder Solid.

This detects cylinder-like components using options, builds an OCCT analytic cylinder Solid from the selected fitted component, then inserts it into graph as a new topology root. The source mesh component is not removed or modified.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives the new Solid root on success.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Cylinder-like component ID to rebuild.
[out]	out_solid	Borrows it (caller-allocated). Must be non-NULL. Receives the new Solid node ID.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_solid is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, no cached face triangulation was found, or component_id is not cylinder-like.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_GEOMETRY_INVALID	OCCT could not build the analytic cylinder.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest the rebuilt Solid.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. Mutates graph by inserting a new Solid.

See also

occtl_mesh_triangle_cylinder_components

occtl_mesh_make_cylinder_component_solids()

occtl_status_t occtl_mesh_make_cylinder_component_solids	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_cylinder_components_options_t *	options,
		occtl_node_id_t *	out_buf,
		size_t	cap,
		size_t *	out_count
	)

Rebuilds all detected cylinder-like triangle components as analytic Solids.

This is the bulk form of occtl_mesh_make_cylinder_component_solid. It first detects cylinder-like components using options, then builds OCCT analytic cylinder Solids and inserts them into graph. The source mesh components are not removed or modified.

Uses the two-call buffer pattern: pass out_buf as NULL with cap 0 to query out_count without mutating graph, then call again with an array of at least that many entries to receive the new Solid node IDs.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives new Solid roots on the fill call.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_buf	Owns it (caller-allocated). May be NULL to query the required count. Receives out_count Solid node IDs on success.
[in]	cap	Capacity of out_buf in elements.
[out]	out_count	Borrows it (caller-allocated). Must be non-NULL. Receives the number of cylinder-like components.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_count is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_BUFFER_TOO_SMALL	out_buf is non-NULL and cap is too small.
OCCTL_GEOMETRY_INVALID	OCCT could not build an analytic cylinder.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest a rebuilt Solid.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. The fill call mutates graph by inserting new Solids. The sizing call is read-only except for cache materialisation.

See also

occtl_mesh_make_cylinder_component_solid, occtl_mesh_triangle_cylinder_components

occtl_mesh_make_plane_component_face()

occtl_status_t occtl_mesh_make_plane_component_face	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_plane_components_options_t *	options,
		uint32_t	component_id,
		occtl_node_id_t *	out_face
	)

Rebuilds one plane-like triangle component as a planar BRepGraph Face.

This is a first mesh-to-BRep recovery bridge. It detects plane-like components using options, materialises ordered boundary polylines for component_id, builds OCCT wires and a planar Face, then inserts that Face into graph as a new topology root. The source mesh component is not removed or modified.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives the new Face root on success.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Plane-like component ID to rebuild.
[out]	out_face	Borrows it (caller-allocated). Must be non-NULL. Receives the new Face node ID.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_face is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, no cached face triangulation was found, or component_id is not plane-like.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_GEOMETRY_INVALID	OCCT could not build wires / Face from the component boundary.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest the rebuilt Face.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. Mutates graph by inserting a new Face.

See also

occtl_mesh_triangle_plane_components, occtl_mesh_component_boundary_polylines

occtl_mesh_make_plane_component_faces()

occtl_status_t occtl_mesh_make_plane_component_faces	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_plane_components_options_t *	options,
		occtl_node_id_t *	out_buf,
		size_t	cap,
		size_t *	out_count
	)

Rebuilds all detected plane-like triangle components as planar Face roots.

This is the bulk form of occtl_mesh_make_plane_component_face. It first detects plane-like components using options, then builds OCCT planar Faces from each component boundary and inserts them into graph. The source mesh components are not removed or modified.

Uses the two-call buffer pattern: pass out_buf as NULL with cap 0 to query out_count without mutating graph, then call again with an array of at least that many entries to receive the new Face node IDs.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives new Face roots on the fill call.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_buf	Owns it (caller-allocated). May be NULL to query the required count. Receives out_count Face node IDs on success.
[in]	cap	Capacity of out_buf in elements.
[out]	out_count	Borrows it (caller-allocated). Must be non-NULL. Receives the number of plane-like components.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_count is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_BUFFER_TOO_SMALL	out_buf is non-NULL and cap is too small.
OCCTL_GEOMETRY_INVALID	OCCT could not build wires / Faces from a component boundary.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest a rebuilt Face.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. The fill call mutates graph by inserting new Faces. The sizing call is read-only except for cache materialisation.

See also

occtl_mesh_make_plane_component_face, occtl_mesh_triangle_plane_components

occtl_mesh_make_sphere_component_solid()

occtl_status_t occtl_mesh_make_sphere_component_solid	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_sphere_components_options_t *	options,
		uint32_t	component_id,
		occtl_node_id_t *	out_solid
	)

Rebuilds one sphere-like triangle component as an analytic sphere Solid.

This detects sphere-like components using options, builds an OCCT analytic sphere Solid from the selected fitted component, then inserts it into graph as a new topology root. The source mesh component is not removed or modified.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives the new Solid root on success.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Sphere-like component ID to rebuild.
[out]	out_solid	Borrows it (caller-allocated). Must be non-NULL. Receives the new Solid node ID.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_solid is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, no cached face triangulation was found, or component_id is not sphere-like.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_GEOMETRY_INVALID	OCCT could not build the analytic sphere.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest the rebuilt Solid.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. Mutates graph by inserting a new Solid.

See also

occtl_mesh_triangle_sphere_components

occtl_mesh_make_sphere_component_solids()

occtl_status_t occtl_mesh_make_sphere_component_solids	(	occtl_graph_t *	graph,
		const occtl_mesh_triangle_sphere_components_options_t *	options,
		occtl_node_id_t *	out_buf,
		size_t	cap,
		size_t *	out_count
	)

Rebuilds all detected sphere-like triangle components as analytic Solids.

This is the bulk form of occtl_mesh_make_sphere_component_solid. It first detects sphere-like components using options, then builds OCCT analytic sphere Solids and inserts them into graph. The source mesh components are not removed or modified.

Uses the two-call buffer pattern: pass out_buf as NULL with cap 0 to query out_count without mutating graph, then call again with an array of at least that many entries to receive the new Solid node IDs.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL. Receives new Solid roots on the fill call.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_buf	Owns it (caller-allocated). May be NULL to query the required count. Receives out_count Solid node IDs on success.
[in]	cap	Capacity of out_buf in elements.
[out]	out_count	Borrows it (caller-allocated). Must be non-NULL. Receives the number of sphere-like components.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_count is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_BUFFER_TOO_SMALL	out_buf is non-NULL and cap is too small.
OCCTL_GEOMETRY_INVALID	OCCT could not build an analytic sphere.
OCCTL_TOPOLOGY_INVALID	BRepGraph could not ingest a rebuilt Solid.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety No. The fill call mutates graph by inserting new Solids. The sizing call is read-only except for cache materialisation.

See also

occtl_mesh_make_sphere_component_solid, occtl_mesh_triangle_sphere_components

occtl_mesh_model_metadata_get()

occtl_status_t occtl_mesh_model_metadata_get	(	const occtl_graph_t *	graph,
		const char *	key,
		size_t	keyLen,
		char *	buf,
		size_t	bufSize,
		size_t *	out_required
	)

Retrieves mesh-model metadata from the owning graph.

Uses the two-call string buffer pattern: call once with buf == NULL to learn out_required, then call again with a buffer of at least that many bytes. The written value is NUL-terminated; out_required includes the NUL terminator.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	key	Metadata key bytes. Borrowed; must be non-NULL and non-empty.
[in]	keyLen	Length of key in bytes.
[out]	buf	Owns it (caller-allocated). May be NULL to query required size.
[in]	bufSize	Size of buf in bytes.
[out]	out_required	Borrows it. Must be non-NULL. Receives required size including NUL.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	graph or out_required is NULL, or key is NULL/empty.
OCCTL_NOT_FOUND	key is not set on graph.
OCCTL_BUFFER_TOO_SMALL	buf is non-NULL and bufSize is too small.

\par Thread Safety Yes (read-only on graph metadata).

See also

occtl_mesh_model_metadata_set, occtl_mesh_model_metadata_keys

occtl_mesh_model_metadata_keys()

occtl_status_t occtl_mesh_model_metadata_keys	(	const occtl_graph_t *	graph,
		occtl_metadata_key_view_t *	out_keys,
		size_t	cap,
		size_t *	out_count
	)

Lists mesh-model metadata keys.

Uses the two-call buffer pattern: pass out_keys as NULL with cap 0 to learn the key count, then call again with an array of at least that many entries. Returned key pointers borrow from the graph metadata storage and are not necessarily NUL-terminated; use key_len.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[out]	out_keys	Borrows it (caller-allocated). Length cap; may be NULL to query count.
[in]	cap	Capacity of out_keys in elements.
[out]	out_count	Borrows it. Must be non-NULL. Receives total count.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	graph or out_count is NULL.
OCCTL_BUFFER_TOO_SMALL	out_keys is non-NULL and cap is too small.

\par Thread Safety Yes (read-only on graph metadata).

See also

occtl_mesh_model_metadata_get, occtl_graph_metadata_keys

occtl_mesh_model_metadata_set()

occtl_status_t occtl_mesh_model_metadata_set	(	occtl_graph_t *	graph,
		const char *	key,
		size_t	keyLen,
		const char *	value,
		size_t	valueLen
	)

Sets mesh-model metadata on the owning graph.

This is a mesh-module spelling for graph-level document/model metadata used by mesh exchange formats such as 3MF, glTF, OBJ, and VRML. The data is stored in the graph metadata storage, so it survives graph clone and native graph snapshots and is visible through occtl_graph_metadata_get.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL.
[in]	key	Metadata key bytes. Borrowed; copied internally. Must be non-NULL and non-empty.
[in]	keyLen	Length of key in bytes.
[in]	value	Metadata value bytes. Borrowed; copied internally. May be NULL only when valueLen is 0.
[in]	valueLen	Length of value in bytes.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	graph is NULL; key is NULL/empty; or value is NULL when valueLen > 0.

\par Thread Safety No (mutates graph metadata).

See also

occtl_mesh_model_metadata_get, occtl_graph_metadata_set

occtl_mesh_model_metadata_unset()

occtl_status_t occtl_mesh_model_metadata_unset	(	occtl_graph_t *	graph,
		const char *	key,
		size_t	keyLen
	)

Removes one mesh-model metadata key.

Idempotent: removing a missing key is a successful no-op.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL.
[in]	key	Metadata key bytes. Borrowed; must be non-NULL and non-empty.
[in]	keyLen	Length of key in bytes.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	graph is NULL, or key is NULL/empty.

\par Thread Safety No (mutates graph metadata).

See also

occtl_mesh_model_metadata_set, occtl_mesh_model_metadata_get

occtl_mesh_options_init()

void occtl_mesh_options_init

(

occtl_mesh_options_t *

options

)

Runtime initialiser for occtl_mesh_options_t.

Sets all fields to OCCTL_MESH_OPTIONS_INIT.

Parameters

[out]

options

Borrows it. NULL-tolerant; no-op when NULL.

\par Thread Safety Yes.

occtl_mesh_triangle_analysis()

occtl_status_t occtl_mesh_triangle_analysis	(	const occtl_graph_t *	graph,
		occtl_node_id_t	root,
		occtl_mesh_triangle_analysis_view_t *	out_view
	)

Computes cached per-triangle normals and adjacency for mesh buffers.

root may be OCCTL_NODE_ID_INVALID to include every active face in graph. Otherwise root must name an active graph node; all faces reachable below that root are included. Run occtl_mesh_generate first. Triangle normals are computed with OCCT vector operations from the cached triangulation coordinates; adjacency is built from shared triangle edges.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	root	Root node to analyse, or OCCTL_NODE_ID_INVALID for whole-graph analysis.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives borrowed buffers owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_buffers, occtl_mesh_generate

occtl_mesh_triangle_buffers()

occtl_status_t occtl_mesh_triangle_buffers	(	const occtl_graph_t *	graph,
		occtl_node_id_t	root,
		occtl_mesh_triangle_buffers_view_t *	out_view
	)

Aggregates cached face triangulations into engine-friendly buffers.

root may be OCCTL_NODE_ID_INVALID to include every active face in graph. Otherwise root must name an active graph node; all faces reachable below that root are included. Run occtl_mesh_generate first.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	root	Root node to extract, or OCCTL_NODE_ID_INVALID for whole-graph extraction.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives borrowed buffers owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph or out_view is NULL.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_generate, occtl_mesh_face_triangulation

occtl_mesh_triangle_component_boundary()

occtl_status_t occtl_mesh_triangle_component_boundary	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		uint32_t	component_id,
		occtl_mesh_triangle_component_boundary_view_t *	out_view
	)

Returns boundary edges for one normal-connected triangle component.

Uses the same traversal and component labelling as occtl_mesh_triangle_components for options. An edge is reported when it has no adjacent triangle, or when the adjacent triangle belongs to a different component. Returned node indices refer to the aggregate triangle buffers for the same root/options.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Component ID to select.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed boundary-edge buffer owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_components, occtl_mesh_triangle_analysis

occtl_mesh_triangle_component_boundary_chains()

occtl_status_t occtl_mesh_triangle_component_boundary_chains	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		uint32_t	component_id,
		occtl_mesh_triangle_component_boundary_chains_view_t *	out_view
	)

Returns ordered boundary chains for one normal-connected triangle component.

This first computes occtl_mesh_triangle_component_boundary, then orders the component perimeter edges into contiguous head-to-tail chains. Closed mesh patches normally return one or more closed chains; open or non-manifold patches may return open chains.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Component ID to select.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives borrowed ordered chain buffers owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_component_boundary, occtl_mesh_triangle_components

occtl_mesh_triangle_component_summaries()

occtl_status_t occtl_mesh_triangle_component_summaries	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		occtl_mesh_triangle_component_summaries_view_t *	out_view
	)

Computes summaries for normal-connected triangle components.

This uses the same traversal, normal-angle grouping, and graph-owned buffers as occtl_mesh_triangle_components, then computes one summary per component. Geometry accumulation uses OCCT point/vector primitives over the cached triangulation buffers.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed summary array owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_components, occtl_mesh_triangle_analysis

occtl_mesh_triangle_component_triangles()

occtl_status_t occtl_mesh_triangle_component_triangles	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		uint32_t	component_id,
		occtl_mesh_triangle_component_triangles_view_t *	out_view
	)

Returns aggregate triangle indices belonging to one component.

Uses the same traversal and normal-connected component labelling as occtl_mesh_triangle_components for options, then filters the dense triangle labels for component_id.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[in]	component_id	Component ID to select.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed triangle-index buffer owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_RANGE	component_id is not present.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_components, occtl_mesh_triangle_buffers

occtl_mesh_triangle_components()

occtl_status_t occtl_mesh_triangle_components	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_components_options_t *	options,
		occtl_mesh_triangle_components_view_t *	out_view
	)

Groups adjacent triangles into normal-connected components.

This is a graph-owned cache view intended as a deterministic substrate for mesh reverse-engineering and primitive patch detection. It first builds the same aggregate triangle soup as occtl_mesh_triangle_buffers, computes normals/adjacency as occtl_mesh_triangle_analysis does, then runs a BFS over adjacent triangles whose normals satisfy options.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives borrowed buffers owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_analysis, occtl_mesh_triangle_buffers

occtl_mesh_triangle_components_options_init()

void occtl_mesh_triangle_components_options_init

(

occtl_mesh_triangle_components_options_t *

options

)

Initialises options to default triangle-component settings.

NULL-tolerant.

Parameters

[out]

options

Borrows it. May be NULL (no-op).

\par Thread Safety Yes.

See also

occtl_mesh_triangle_components

occtl_mesh_triangle_cylinder_components()

occtl_status_t occtl_mesh_triangle_cylinder_components	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_cylinder_components_options_t *	options,
		occtl_mesh_triangle_cylinder_components_view_t *	out_view
	)

Detects cylinder-like normal-connected triangle components.

This reverse-engineering primitive detector groups triangles by normal connectivity, computes component summaries, fits each component to a cylinder with OCCT math_Jacobi and math_SVD, and validates radial residuals with OCCT point-to-line distance calculations.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed component array owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_component_summaries, occtl_mesh_triangle_sphere_components

occtl_mesh_triangle_cylinder_components_options_init()

void occtl_mesh_triangle_cylinder_components_options_init

(

occtl_mesh_triangle_cylinder_components_options_t *

options

)

Initialises options to default cylinder-component detector settings.

NULL-tolerant.

Parameters

[out]

options

Borrows it. May be NULL (no-op).

\par Thread Safety Yes.

See also

occtl_mesh_triangle_cylinder_components

occtl_mesh_triangle_plane_components()

occtl_status_t occtl_mesh_triangle_plane_components	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_plane_components_options_t *	options,
		occtl_mesh_triangle_plane_components_view_t *	out_view
	)

Detects plane-like normal-connected triangle components.

This is a first reverse-engineering primitive detector over graph-owned mesh buffers. It groups triangles by normal connectivity, computes component summaries, and validates each component against an OCCT #gp_Pln plane using max_distance.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed component array owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_component_summaries, occtl_mesh_triangle_components

occtl_mesh_triangle_plane_components_options_init()

void occtl_mesh_triangle_plane_components_options_init

(

occtl_mesh_triangle_plane_components_options_t *

options

)

Initialises options to default plane-component detector settings.

NULL-tolerant.

Parameters

[out]

options

Borrows it. May be NULL (no-op).

\par Thread Safety Yes.

See also

occtl_mesh_triangle_plane_components

occtl_mesh_triangle_sphere_components()

occtl_status_t occtl_mesh_triangle_sphere_components	(	const occtl_graph_t *	graph,
		const occtl_mesh_triangle_sphere_components_options_t *	options,
		occtl_mesh_triangle_sphere_components_view_t *	out_view
	)

Detects sphere-like normal-connected triangle components.

This reverse-engineering primitive detector groups triangles by normal connectivity, computes component summaries, fits each component to a sphere with OCCT math_SVD, and validates radial residuals with OCCT point-distance calculations.

Parameters

[in]	graph	Borrows it. Must be non-NULL.
[in]	options	Borrows it. Must be non-NULL and carry a supported struct_version.
[out]	out_view	Borrows it (caller-allocated). Must be non-NULL. Receives a borrowed component array owned by graph.

Return values

OCCTL_OK	Success.
OCCTL_INVALID_ARGUMENT	graph, options, or out_view is NULL; p_next is non-NULL; or an option value is invalid.
OCCTL_VERSION_MISMATCH	options has an unsupported struct_version.
OCCTL_NOT_FOUND	root is invalid / removed, or no cached face triangulation was found.
OCCTL_OUT_OF_MEMORY	Allocation failed.

\par Thread Safety Yes (read-only on graph; serialises cache materialisation).

See also

occtl_mesh_triangle_component_summaries, occtl_mesh_triangle_plane_components

occtl_mesh_triangle_sphere_components_options_init()

void occtl_mesh_triangle_sphere_components_options_init

(

occtl_mesh_triangle_sphere_components_options_t *

options

)

Initialises options to default sphere-component detector settings.

NULL-tolerant.

Parameters

[out]

options

Borrows it. May be NULL (no-op).

\par Thread Safety Yes.

See also

occtl_mesh_triangle_sphere_components