# UV Unwrap (LSCM) for OBJ, STL and PLY

> Cut seams, flatten charts with least-squares conformal maps and pack them into an OBJ with UVs. Upload a triangle mesh to get texture coordinates: seams at sharp edges or along your own vertex paths, charts flattened with least-squares conformal maps (LSCM), packed into the unit square with padding, and a distortion report per chart (angle error, quasi-conformal ratio, area distortion, L² stretch). Download an OBJ with vt coordinates and the UV layout as SVG. Runs on the same engine as Renderloom Sculpt Lab.

Part of usefulweb.app (https://usefulweb.app/). Part of [Renderloom](https://renderloom.usefulweb.app/) (ownerApp: renderloom). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://renderloomuvunwrap.usefulweb.app/ (interactive tool at https://renderloomuvunwrap.usefulweb.app/tool)
- JSON API: POST https://renderloomuvunwrap.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://renderloomuvunwrap.usefulweb.app/api/v1/tool)
- OpenAPI: https://renderloomuvunwrap.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://renderloomuvunwrap.usefulweb.app/mcp - tool `renderloom_uv_unwrap`

## Inputs
- file (file): Mesh file (STL, OBJ or PLY) - A triangle mesh up to 200000 triangles. Coincident vertices are welded and faces oriented before unwrapping.
- seamMode (select): Automatic seams
- seamAngle (number): Seam angle (°) - Edges whose neighbouring faces bend by at least this angle become seams.
- seams (textarea): Manual seams (vertex numbers) - Paths of vertex numbers (1-based, as in OBJ, after welding). Consecutive vertices are joined along the shortest edge path. Separate paths with a semicolon or a new line.
- maxAreaDistortion (number): Split charts above this area distortion (0 = off) - Mean |ln(area ratio)| of a chart. Lower values give more, flatter charts.
- maxCharts (integer): Maximum number of charts
- resolution (integer): Texture resolution for the padding (px)
- padding (integer): Padding between charts (px)
- rotate (boolean): Rotate charts to their smallest bounding rectangle

## Method
- The mesh is welded (tolerance 1e-6 × bounding-box diagonal), degenerate and duplicate faces are dropped and faces are oriented consistently; a half-edge structure then gives edges and neighbours.
- Seams: edges whose faces bend by at least the seam angle, manual vertex paths (shortest edge path between consecutive vertices) and the mesh border. Faces connected across non-seam edges form charts; inside a chart, corners are merged across non-seam edges, so a seam inside a chart becomes a cut.
- Every chart must be a topological disk (Euler characteristic 1 with a border). Closed charts, charts with holes, charts with flipped triangles and charts above the area-distortion limit are split in two by growing regions from two far-apart faces, up to the chart limit.
- LSCM (Lévy et al. 2002): the Cauchy–Riemann residual of each triangle, weighted by √area, is minimised in the least-squares sense with two far-apart vertices pinned. The normal equations AᵀA·x = Aᵀb are assembled per triangle and solved with the shared Proofline sparse solver: envelope Cholesky after reverse Cuthill–McKee ordering, or SSOR-preconditioned conjugate gradients above 12000 unknowns.
- Each chart is scaled so its UV area equals its surface area, rotated to its minimum-area bounding rectangle (rotating calipers on the convex hull) and shelf-packed into the unit square with the padding gutter. Distortion uses the singular values σ₁ ≥ σ₂ of each triangle’s Jacobian: σ₁/σ₂ (1 = angles kept), √((σ₁² + σ₂²)/2) (Sander’s L² stretch) and σ₁σ₂ (area ratio, chart scale normalised).

## Limits
- LSCM keeps angles, not areas: curved charts (spheres, organic shapes) show area distortion, which the report quantifies. Packing is a simple shelf packer, not an optimal atlas. Vertex numbers for manual seams refer to the welded mesh.