b3dSplitSurfaces

Splits surface 0 into multiple surfaces by grouping triangles with similar normals. Takes mesh (surface-based mesh entity), angleThreshold (maximum angle difference in degrees for grouping, typically 30-90). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and locked. Only processes surface 0 (most primitives store all geometry in first surface). Calculates face normal for each triangle (cross product of edges, normalized). Groups triangles by comparing normals: two triangles in same group if dot product > cos(angleThreshold). Uses flood-fill algorithm: starts with unassigned triangle, recursively adds connected triangles with similar normals. Creates new surface for each group. Copies vertices and indices for each group into separate surfaces. Replaces original surface 0 with first group, appends additional groups as new surfaces. Silently returns on errors or empty surfaces.

This function separates hard edges from smooth surfaces for proper normal calculation and material assignment. Angle-based splitting identifies distinct geometric features: cube has 6 faces (split at 90 degrees angles), sphere smooth (no splitting), cylinder has sides+caps (split where sides meet caps). Threshold parameter: small angle (10-30 degrees) = many surfaces (splits at slight bends), large angle (60-90 degrees) = few surfaces (only splits at sharp corners). Use cases: (1) Auto-smooth mesh imports (split sharp edges for faceted look), (2) Per-face material assignment (each surface gets different material), (3) Normal calculation (split prevents normal averaging across hard edges), (4) Collision mesh simplification (separate surfaces for physics). Flood-fill grouping: starts at triangle, expands to neighbors with similar normals, creates connected regions. Dot product comparison: dot(n1,n2) = cos(angle) - if > threshold, triangles are similar. cos(30 degrees) ~ 0.866, cos(45 degrees) ~ 0.707, cos(60 degrees) ~ 0.5, cos(90 degrees) = 0. Only processes surface 0 limitation: if mesh already has multiple surfaces, only first is processed - could extend to process all if needed. Must lock mesh before calling. After splitting, unlock to upload. New surfaces share vertices initially (vertices not duplicated unless needed). Triangle grouping preserves connectivity - each group is contiguous region. Common workflow: import smooth OBJ (single surface), split at 45 degrees (creates surfaces for distinct faces), assign materials per surface, render with hard edges. Alternative: manually create surfaces during mesh construction, use modeling software to split before export, normal-based rendering (detect hard edges in shader). Typical values: angleThreshold=30 for mechanical parts, 60 for organic shapes, 89 for only 90 degrees corners.