b3dUVMapCylindrical

Applies cylindrical UV mapping by wrapping texture around Y axis with seam fixing. Takes mesh (surface-based mesh entity). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and locked. Calculates Y bounding box (minY, maxY) for height. Computes height (maxY - minY). First pass: for each vertex, calculates angle around Y axis (atan2(Z, X)), normalizes to U = (angle/PI + 1) * 0.5 (maps -PI..PI to 0..1), sets V = 1 - (Y-minY)/height. Second pass: fixes seam-crossing triangles - detects triangles with U difference > 0.5 (crossing 0/1 boundary), adjusts UVs to prevent texture wrap mid-triangle. Uses SEAM_THRESHOLD = 0.5 for detection. Silently returns on errors.

This function wraps textures around cylindrical geometry like rolling paper around tube. Cylindrical mapping uses polar coordinates: angle determines U (horizontal wrap), height determines V (vertical). Perfect for: (1) Columns/pillars (architecture), (2) Tree trunks (nature), (3) Cans/bottles (props), (4) Pipes/tubes (mechanical), (5) Character limbs (arms/legs approximated as cylinders). Y-axis alignment: texture wraps around Y (vertical axis) - rotate mesh if different axis needed. Seam handling critical: without fixing, triangles crossing 0 degrees/360 degrees boundary render with texture stretched across entire cylinder. Algorithm detects large U jumps, adjusts vertices to keep triangle coherent. First pass calculates raw UVs, second pass repairs topology. Height normalization: shortest cylinder and tallest cylinder both map V to 0-1 (texture scales to fit). Angle calculation: atan2(Z, X) gives angle in XZ plane, normalized to 0-1 range. Seam typically at -X axis (angle=+/-PI). Common artifacts: pole pinching at top/bottom (all vertices at top converge to single V value), seam visible with non-seamless textures. Workflow: mesh=b3dCreateCylinder(...), b3dLockMesh(mesh), b3dUVMapCylindrical(mesh), b3dUnlockMesh(mesh). Use seamless/tiling textures for best results. Alternative: b3dUVMapSpherical for spheres/domes, b3dUVMapBox for angular geometry, manual UV assignment for precise control.