Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
UV Editor: guide chapter with screenshots, What's New and CHANGELOG, glossary and ZBrush mapping, shortcuts; face group wording, selection tint keeps the heat colours, trim strip labels
islandmedbd9b07b25933
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 53b7bd75..23e70d6f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,23 @@ All notable changes to SculptForge are listed here. The format follows## [0.10.5] - 2026-11-01### Added+- **UV Editor** (Tool > Texture Map > UV Editor, Shift+U): a window with the active Part's UV layout over the UDIM+ tile grid, drawn on the GPU (pan, zoom, a checker or the painted texture behind). Select vertices, edges, faces or+ islands (1-4) by click or box, or on the model with **Select in 3D**; move, rotate and scale with the selection's+ handles or G / R / S (X / Y lock an axis, Ctrl snaps). **Seam Tool**: drag on the model to mark seams along the+ shortest edge paths (Alt clears); seams also from face groups, island borders or sharp edges, and show in red on+ the model. **Unwrap**: Least Stretch (LSCM, then as-rigid-as-possible), Conformal (LSCM), By Face Groups, Planar,+ Unfold Islands (keeps pins) and Auto Seams (xatlas), solved with a multigrid preconditioner (a 1.3M-triangle+ sphere unwraps in seconds); closed, looped and tangled pieces get cut automatically; selected faces unwrap in+ place. **Pack** into one tile or across UDIM tiles with a margin, rotation and equal texel density, by island+ outline or box (whichever fits larger), or at a fixed texel density spilling into more tiles. **Texel density**:+ set, match and pick, with a density heat map. **Trim sheets**: lay islands into horizontal strips (count, heights+ or v ranges), fitted to the width or keeping proportions. **Pin**, **Weld**, **Split**, **Straighten**, **Flip**,+ **Rotate 90**. The model shows islands, stretch or density colours and a UDIM-tinted checker live during edits, and+ **Paint stays on the model** re-projects a painted texture (every layer) onto each new layout in the same undo+ step. Seams and pins are saved in projects. Commands: `uv_unwrap`, `uv_pack`, `uv_seam`, `uv_select`,+ `uv_transform`, `uv_edit`, `uv_density`, `uv_trim`, `uv_info` (scripts, CLI, Python, MCP); guide chapter UV+ Editor.- **Preferences > Input > Start strokes off the model** (#62, off by default) and **Toggle strokes off the model**(<kbd>Shift</kbd>+<kbd>L</kbd>): a left-drag that starts on the background begins a stroke, which touches the modelonce the cursor reaches it (Lazy Stroke and the stroke path start there, so nothing jumps). Ctrl (mask) and Shiftdiff --git a/docs/guide/coming-from-zbrush.md b/docs/guide/coming-from-zbrush.mdindex 440dca6b..a56839d7 100644--- a/docs/guide/coming-from-zbrush.md+++ b/docs/guide/coming-from-zbrush.md@@ -41,7 +41,7 @@ Features use SculptForge's own names. The ideas are the ones you know; here is w| SelectRect, SelectLasso | **Select Rectangle**, **Select Lasso** | **Tool > Visibility** || FiberMesh, LightCap | Not yet | || ZScript, ZPlugin | Script commands and the Python module | See [Scripting](scripting.md) |-| Decimation Master, UV Master, Projection Master | **Decimate**, **Auto UV**, **Generate > Stamp** | See [Geometry](geometry.md#decimate) and [Texture painting](texture-painting.md) |+| Decimation Master, UV Master, Projection Master | **Decimate**, the **UV Editor** (and **Auto UV**), **Generate > Stamp** | See [Geometry](geometry.md#decimate), [UV Editor](uv-editor.md) and [Texture painting](texture-painting.md) |The command palette (<kbd>F3</kbd>) finds every feature by its ZBrush name too: type `SubTool`, `ZSphere`,`Polypaint` or `MatCap` and it shows the SculptForge command, as in "Forge Spheres (ZBrush users: ZSpheres)". Thediff --git a/docs/guide/glossary.md b/docs/guide/glossary.mdindex 24969a5e..66b42ba3 100644--- a/docs/guide/glossary.md+++ b/docs/guide/glossary.md@@ -68,7 +68,7 @@ for what is planned.| Texture palette | Not yet as a palette of texture images. **Tool > Texture Map > Import Texture** loads an image onto the UVs || Transpose, Gizmo 3D (Move W, Scale E, Rotate R) | **Gizmo**: same keys, arrows, rings and boxes; masked parts stay, Falloff softens the joint. See [Gizmo](gizmo.md) || Transpose All | **All Parts** in the Gizmo panel. See [Gizmo](gizmo.md#all-parts) |-| UV Master (Unwrap) | **Tool > Texture Map > Auto UV** (`uv_auto`). UVs that come in with a model are kept. Seams and UV editing not yet. See [Texture painting](texture-painting.md) |+| UV Master (Unwrap), UV editing | The **UV Editor** (<kbd>Shift</kbd>+<kbd>U</kbd>): seams on the model, Least Stretch, Conformal, By Face Groups, Planar and Unfold unwraps, UDIM packing, texel density, trim sheets (`uv_unwrap`, `uv_pack`...). **Tool > Texture Map > Auto UV** (`uv_auto`) is the one-click unwrap. See [UV Editor](uv-editor.md) || VDM brush, 3D alpha, Create VDM brush from the VDM plane | The **VDM** brush and **Brush > Vector Displacement**: built-in maps, **Load VDM...** (EXR), **New VDM Plane**, **Create VDM**, **Export EXR...**. See [Vector displacement brushes](sculpting.md#vector-displacement-brushes) || Zadd / Zsub | **Add** / **Sub** on the top shelf; <kbd>Alt</kbd> flips for one stroke || ZPlugin | No in-app plugin system yet. Automate with the Python module, `sculptforge-cli` and MCP ([Scripting](scripting.md)) |@@ -114,7 +114,10 @@ for what is planned.| MikkTSpace | The standard way of computing tangents that game engines share, so tangent-space normal maps look the same everywhere. See [Baking](baking.md) || Normal map | A map of surface directions that makes a low-poly shade like the high-poly. Tangent-space maps are relative to the surface (for engines), object-space maps to the model. See [Baking](baking.md) || Texel | One pixel of a texture. Texture painting paints texels; their 3D position on the model decides the brush falloff |-| UV island | A piece of the surface flattened into the texture square. Auto UV cuts the model into islands along seams |+| UV island | A piece of the surface flattened into the texture square. Unwrap and Auto UV cut the model into islands along seams. See [UV Editor](uv-editor.md) |+| UDIM tile | One unit square of UV space, numbered 1001 (u and v between 0 and 1), 1002 to its right, ten per row: a Part's islands can spread over several, each its own texture. See [UV Editor](uv-editor.md#packing-and-udim-tiles) |+| Texel density | Texels of the texture per unit of surface length: equal density makes detail look the same size everywhere. See [UV Editor](uv-editor.md#texel-density) |+| Trim sheet | A texture of horizontal strips that repeat left to right; islands are laid into a strip. See [UV Editor](uv-editor.md#trim-sheets) || Antialiasing (AA) | Smoothing the 3D view's edges with several samples per pixel (Off, 2x, 4x, 8x in **Preferences > Performance**). See [Performance](performance.md) || BVH | Bounding volume hierarchy: the structure SculptForge uses to find the surface under the cursor and the vertices under a brush. Its update time is shown per dab in **Preferences > Performance** || Dab | One step of a brush along a stroke. Its cost per dab decides whether a stroke keeps up with the display (under 16 ms at 60 Hz). See [Performance](performance.md) |diff --git a/docs/guide/images/uv-editor-seams.jpg b/docs/guide/images/uv-editor-seams.jpgnew file mode 100644index 00000000..271bc5d1Binary files /dev/null and b/docs/guide/images/uv-editor-seams.jpg differdiff --git a/docs/guide/images/uv-editor-stretch.jpg b/docs/guide/images/uv-editor-stretch.jpgnew file mode 100644index 00000000..8abccd77Binary files /dev/null and b/docs/guide/images/uv-editor-stretch.jpg differdiff --git a/docs/guide/images/uv-editor-trim.jpg b/docs/guide/images/uv-editor-trim.jpgnew file mode 100644index 00000000..2b3a5f62Binary files /dev/null and b/docs/guide/images/uv-editor-trim.jpg differdiff --git a/docs/guide/images/uv-editor-udim.jpg b/docs/guide/images/uv-editor-udim.jpgnew file mode 100644index 00000000..13d0998eBinary files /dev/null and b/docs/guide/images/uv-editor-udim.jpg differdiff --git a/docs/guide/images/uv-editor.jpg b/docs/guide/images/uv-editor.jpgnew file mode 100644index 00000000..712c9b17Binary files /dev/null and b/docs/guide/images/uv-editor.jpg differdiff --git a/docs/guide/index.md b/docs/guide/index.mdindex cff364ed..0c3524fe 100644--- a/docs/guide/index.md+++ b/docs/guide/index.md@@ -31,42 +31,43 @@ You can read it inside SculptForge (**Help > User Guide**, or <kbd>Shift</kbd>+<13. [Forge Spheres](forge-spheres.md)14. [Vertex Paint and materials](vertex-paint.md)15. [Texture painting](texture-painting.md)-16. [Material painting (PBR)](pbr-painting.md)-17. [Sculpt layers and blend shapes](layers.md)-18. [Facial shapes and live face](facial-shapes.md)-19. [Subdivision levels](subdivision-levels.md)-20. [Micro levels: hundreds of millions of polygons](micro-levels.md)-21. [Dynamic topology](dynamic-topology.md)-22. [Sculpt Timeline and timelapse](timeline.md)-23. [Moving, rotating and posing (Gizmo)](gizmo.md)-24. [Subdivide, remesh, decimate and LODs](geometry.md)-25. [Quad retopology and detail projection](retopology.md)+16. [UV Editor](uv-editor.md)+17. [Material painting (PBR)](pbr-painting.md)+18. [Sculpt layers and blend shapes](layers.md)+19. [Facial shapes and live face](facial-shapes.md)+20. [Subdivision levels](subdivision-levels.md)+21. [Micro levels: hundreds of millions of polygons](micro-levels.md)+22. [Dynamic topology](dynamic-topology.md)+23. [Sculpt Timeline and timelapse](timeline.md)+24. [Moving, rotating and posing (Gizmo)](gizmo.md)+25. [Subdivide, remesh, decimate and LODs](geometry.md)+26. [Quad retopology and detail projection](retopology.md)## AI and capture-26. [Image and text to 3D](generate-3d.md)-27. [Gaussian splats](splats.md)-28. [Scan an object into a splat](scan-to-splat.md)-29. [From scan to sculptable mesh](scan-to-sculptable.md)-30. [Phone capture and AR](phone-capture.md)+27. [Image and text to 3D](generate-3d.md)+28. [Gaussian splats](splats.md)+29. [Scan an object into a splat](scan-to-splat.md)+30. [From scan to sculptable mesh](scan-to-sculptable.md)+31. [Phone capture and AR](phone-capture.md)## Files and pipelines-31. [Baking normal and displacement maps](baking.md)-32. [Exporting, Unreal and ZBrush](exporting.md)-33. [Export presets](export-presets.md)-34. [Working with Blender](blender.md)-35. [Working with Maya](maya.md)-36. [Projects, autosave and Snapshots](projects.md)-37. [Scripting and automation](scripting.md)-38. [SculptForge for studios](studios.md)+32. [Baking normal and displacement maps](baking.md)+33. [Exporting, Unreal and ZBrush](exporting.md)+34. [Export presets](export-presets.md)+35. [Working with Blender](blender.md)+36. [Working with Maya](maya.md)+37. [Projects, autosave and Snapshots](projects.md)+38. [Scripting and automation](scripting.md)+39. [SculptForge for studios](studios.md)## Reference-39. [Keyboard and mouse](shortcuts.md)-40. [Performance and big meshes](performance.md)-41. [Troubleshooting and FAQ](troubleshooting.md)-42. [Glossary](glossary.md)+40. [Keyboard and mouse](shortcuts.md)+41. [Performance and big meshes](performance.md)+42. [Troubleshooting and FAQ](troubleshooting.md)+43. [Glossary](glossary.md)## Getting helpdiff --git a/docs/guide/shortcuts.md b/docs/guide/shortcuts.mdindex ba84c594..b6177bf7 100644--- a/docs/guide/shortcuts.md+++ b/docs/guide/shortcuts.md@@ -172,6 +172,12 @@ generated from SculptForge's action registry, the same source as the Controls wi| Zoom in | <kbd>Numpad Plus</kbd> | Move the view closer. || Zoom out | <kbd>Numpad Minus</kbd> | Move the view back. |+### UV Editor++| Action | Keys | What it does |+|---|---|---|+| UV Editor | <kbd>Shift</kbd>+<kbd>U</kbd> | Open the UV Editor: the Part's UV layout in 2D over the UDIM tiles. Select vertices, edges, faces or islands (here or on the model), move, rotate and scale them, mark seams, unwrap, pack, set texel density and lay islands into trim sheet strips. Stretch and texel density show live on the model while you edit. |+<!-- END GENERATED: shortcuts -->## Mouse and pen gesturesdiff --git a/docs/guide/texture-painting.md b/docs/guide/texture-painting.mdindex 128552e9..76c649e9 100644--- a/docs/guide/texture-painting.md+++ b/docs/guide/texture-painting.md@@ -32,7 +32,8 @@ by hand, with more choices.4. Press <kbd>P</kbd> and paint. Draw Size, RGB Intensity, pen pressure, the stroke type, the alpha, symmetry and themask work as they do for vertex paint.-Click **Show UVs** to see the texture with the UV layout drawn over it, below the buttons. Paint on the model and+Click **Show UVs** to see the texture with the UV layout drawn over it, below the buttons, or open the+[UV Editor](uv-editor.md) (<kbd>Shift</kbd>+<kbd>U</kbd>) to cut seams, unwrap, pack and edit the UVs. Paint on the model andwatch the texture fill in.## Vertex or Texture@@ -125,7 +126,7 @@ texture after giving it UVs.a texture come out white.- Auto UV on dense meshes: the islands are kept to about 4,000 triangles each, so a million-triangle sculptunwraps in a quarter of a minute or so and gets a few hundred islands.-- UVs outside the 0-1 square (tiles, UDIMs) aren't painted.+- UVs outside the 0-1 square (other UDIM tiles) aren't painted yet; the [UV Editor](uv-editor.md) lays them out.> **ZBrush:** ZBrush paints polypaint and converts it to a texture afterwards (**Texture Map > New From> Polypaint**). SculptForge can do both: paint the texture directly, or bake vertex paint with **Vertex Paint >diff --git a/docs/guide/uv-editor.md b/docs/guide/uv-editor.mdnew file mode 100644index 00000000..c72b2982--- /dev/null+++ b/docs/guide/uv-editor.md@@ -0,0 +1,196 @@+# UV Editor++The UV Editor shows a Part's UVs flat, over the texture's tiles, and gives you everything to make them: seams drawn on+the model, unwrapping that keeps the surface's shape, packing into one tile or across UDIM tiles, texel density,+trim sheets, and hand editing of vertices, edges, faces and islands. While you work, the model shows the same+colours and a checker, so stretch and density show up on the surface the moment they appear, and a painted texture+can move with every edit so the model keeps its look.++Open it with **Tool > Texture Map > UV Editor**, or <kbd>Shift</kbd>+<kbd>U</kbd>. It opens over the right of the+canvas with the model moved to the left; drag its title bar or its edges to place it anywhere.++++## The window++- **Select** (top left): what clicks pick, **Vertex**, **Edge**, **Face** or **Island** (<kbd>1</kbd>-<kbd>4</kbd>+ while the pointer is over the view). The selection converts when you switch.+- **Colours**: what the faces show, in the view and on the model: **Islands** (a colour each), **Stretch**,+ **Density** (texel density) or **Plain**.+- **Image**: what's behind the layout: nothing, a **Checker**, or the Part's painted **Texture** (tile 1001).+- **On model**: **Colours** shows the same colours on the model, **Checker** lays a checker on its UVs (a square+ per 32 texels of the texture, tinted per UDIM tile). Squares that stay square mean no stretch.+- **Frame** (<kbd>F</kbd> over the view) fits the selection, or the whole layout, in the view; <kbd>Home</kbd>+ shows tile 1001.+- The status line under the view: islands, what's selected, the mean stretch, the texel density and the UDIM+ tiles in use.+- The sections on the right: **Unwrap** (with the seams), **Pack**, **Texel Density**, **Trim Sheet**, **Edit**+ and **Display**.++The view is drawn by the graphics card, so a million-triangle layout pans, zooms and moves as smoothly as a small+one. Scroll to zoom (around the pointer); drag with the right or middle button to pan. The UDIM tile numbers are written in each tile's corner.++## Selecting++- Click to select (<kbd>Shift</kbd> adds, <kbd>Ctrl</kbd> removes); drag on an empty spot for a box. In Island mode+ the box picks every island it touches; in Face mode the faces inside it.+- <kbd>A</kbd> selects everything, <kbd>Alt</kbd>+<kbd>A</kbd> nothing, <kbd>Ctrl</kbd>+<kbd>I</kbd> inverts.+- **Select in 3D** (Unwrap section): click or drag over the model to select there, in the current mode;+ <kbd>Shift</kbd> adds, <kbd>Alt</kbd> removes. The selection shows orange in both views.++Moving a vertex moves all of its corners that are joined in UV space, so islands stay in one piece while you edit+them; edges along a seam move each side on its own.++## Moving, rotating and scaling++The selection has a box with handles: drag inside it to move, a corner to scale, the knob above it to rotate.+Or press <kbd>G</kbd> (move), <kbd>R</kbd> (rotate) or <kbd>S</kbd> (scale) over the view, move the mouse, and+click (or <kbd>Enter</kbd>) to finish; a right click or <kbd>Esc</kbd> puts it back. During <kbd>G</kbd> and+<kbd>S</kbd>, <kbd>X</kbd> or <kbd>Y</kbd> locks to one axis; <kbd>Ctrl</kbd> snaps (1/64 of a tile, 15 degrees,+tenths of the size). The model's stretch colours and checker follow the drag live. Each drag is one undo step.++## Seams++Seams are the edges Unwrap cuts along. They show in red on the model while the UV Editor is open, and in red in the+view.++- **Seam Tool**: drag along the model over the edges you want cut. Each stretch follows the shortest edge path+ from where the last one ended, so you can draw a loop around an arm in a few strokes. <kbd>Alt</kbd>+drag clears+ seams the same way. A ring under the pointer shows the vertex the next stretch starts from.+- **Mark Seam** / **Clear Seam**: the selected edges, or the border of the selected faces.+- **Face Groups**: every face group border becomes a seam.+- **Island Borders**: the borders of the current UV islands become seams (keeps an imported layout's cuts).+- **Sharp Edges**: every edge sharper than the angle beside it (hard-surface models).+- **Clear All**.++++## Unwrapping++Pick a method and click **Unwrap**. With faces selected it says **Unwrap Selected**: only those are unwrapped, and+their new islands are fitted where the old ones were; otherwise the whole Part is unwrapped and packed.++| Method | What it does |+| --- | --- |+| **Least Stretch** (the default) | Cuts along the marked seams and flattens each piece keeping both angles and lengths (a conformal start, then as-rigid-as-possible steps). The best all-round choice |+| **Conformal (LSCM)** | Keeps angles exactly; big curved pieces get smaller towards their ends |+| **By Face Groups** | Least Stretch, also cut along every face group border: group the model, then unwrap |+| **Planar** | Projects each piece flat along its mean direction: for flat panels and decals |+| **Unfold Islands** | Flattens the current islands again where they are, keeping pinned UVs in place: relax after editing |+| **Auto Seams** | Finds its own seams (as **Auto UV** does), for models you don't want to cut by hand |++**Refine** sets how many least-stretch steps run (more keeps lengths better; 0 is plain conformal).++You don't have to cut everything yourself: a piece that is closed (a sphere), a tube or has holes gets the extra+cuts it needs automatically, a closed shell split across its middle and a tangled piece cut into charts the way+Auto Seams would. Without marked seams, a Part that already has UVs is cut along its current island borders.+Unwraps of big meshes run in the background with their progress over the view; a million triangles take a few+seconds.++## Packing and UDIM tiles++**Pack** lays the selected islands (or all) out as large as they fit: each turned to its smallest box, scaled to one+texel density (**Equal density**; off keeps their sizes relative to each other), with **Margin** texels between+them. **Rotate** also allows quarter turns. SculptForge tries packing by the islands' outlines and by their boxes+and keeps whichever holds them larger.++**UDIM Tiles** spreads the islands over that many tiles, 1001, 1002 and on (ten per row, as UDIM numbers go), each+island at the same texel density: more tiles, more texels for everything. **Pack at Density** instead keeps exactly+the target texel density and opens as many tiles as it needs.++++## Texel density++Texel density is how many texels of the texture cover a unit of the surface. The **Texel Density** section shows the+selected islands' density (or the mean) at the texture's size (or the size you choose when there is no texture yet),+and the **Density** colours show it on every face: green is the mean, blue fewer texels, red more.++- **Set**: scale the selected islands (or all) to the target density (texels per unit).+- **Match**: give them all their mean density, so a detail looks the same size everywhere.+- **Pick**: take the target from the selection.+- **Pack at Density**: pack at exactly the target (see above).++++## Trim sheets++A trim sheet is a texture made of horizontal strips (a moulding, a belt, a seam of rivets), each repeating left to+right. In **Trim Sheet**, describe the strips: a count (`4` equal strips), heights from the top (`0.5,0.25,0.25`)+or v ranges (`0-0.5;0.5-1`); they show over tile 1001 while the section is open. Pick a strip and click **Assign to+Strip**: the selected islands are turned lengthwise, scaled to the strip's height and lined up along it from the+left. **Fit width** squeezes or stretches the row to fill the strip exactly; off, it keeps its proportions and may+run past the right edge, which is fine on a trim that repeats.++The texture doesn't move for trims: the islands take on the strip's look.++++## Editing++| Button | Over the view | What it does |+| --- | --- | --- |+| **Pin** / **Unpin** | <kbd>P</kbd> / <kbd>Alt</kbd>+<kbd>P</kbd> | Pinned UVs (blue dots) stay where they are when you Unwrap or Unfold |+| **Weld** | <kbd>W</kbd> | Selected vertices that meet across a seam become one UV each, and the seam between them goes |+| **Split** | <kbd>Y</kbd> | The selected edges, or the border of the selected faces, become seams, so those faces move on their own |+| **Straighten** | | The selected vertices (a border, an edge loop) line up on one horizontal or vertical line |+| **Rotate 90** | | A quarter turn of the selection (or everything) |+| **Flip U** / **Flip V** | | Mirror the selected islands left to right or top to bottom |++A good relax workflow: straighten or move the borders you care about, pin them, then **Unfold Islands**.++## Paint stays on the model++**Paint stays on the model** (at the bottom of the sections, on by default): when the Part has a painted texture,+every UV edit (unwrap, pack, a drag, density, weld...) moves the paint onto the new layout in the same undo step, every+texture layer with it, so the model looks exactly the same. Undo brings back the old UVs and the old texels. Turn it+off when you want the UVs to pick a different part of the texture (as trim sheets do); the trim command leaves it+off by default.++## Undo++Every UV operation is one undo step (<kbd>Ctrl</kbd>+<kbd>Z</kbd>), drags included: the UVs, seams and pins, and the+texture when it moved with them. Seams and pins are saved with the project.++## Scripting++Every operation is a command, for scripts, `sculptforge-cli`, Python (`sf.run(doc, "uv_unwrap", method="isometric")`)+and the AI assistant. "The selection" is the UV Editor's (set it with `uv_select`); with nothing selected the+commands work on the whole Part.++| Command | What it does |+| --- | --- |+| `uv_unwrap` | Unwrap: `method=isometric` (Least Stretch), `conformal`, `polygroups` (By Face Groups), `planar`, `unfold` or `auto`; `iterations=`, `selected=`, `tiles=`, `margin=`, `rotate=`, `density=`, `pack=false` (fit in place), `keep_texture=` |+| `uv_pack` | Pack: `margin=` (texels), `tiles=` (UDIM tiles), `first_tile=`, `rotate=`, `equal_density=`, `density=` (texels per unit, as many tiles as needed), `resolution=`, `keep_texture=` |+| `uv_seam` | Seams: `op=mark` / `clear` (the selection), `path from= to=` (shortest edge path between two vertices; `clear=true`), `polygroups`, `islands`, `angle angle=60`, `clear_all` |+| `uv_select` | `op=all`, `none`, `invert`, `island face=`, `face face=`, `polygroup group=`, `rect u0= v0= u1= v1=`, `seams`, `mode`; `mode=vertex/edge/face/island`, `add=true` |+| `uv_transform` | `move_u=`, `move_v=`, `rotate=` (degrees), `scale=`, `scale_u=`, `scale_v=` about the selection's centre |+| `uv_edit` | `op=pin`, `unpin`, `clear_pins`, `weld`, `split`, `straighten`, `flip_u`, `flip_v` |+| `uv_density` | `op=set value=`, `op=match` (`match=mean` or `first`), `op=info`; `resolution=` |+| `uv_trim` | `strip=2 strips=4` (or `0.5,0.25,0.25` or `0-0.5;0.5-1`), `fit_width=`, `margin=` |+| `uv_info` | Islands, seams, pins, texel density, the UDIM tiles in use and the mean stretch |++```+uv_seam op=polygroups+uv_unwrap method=isometric+uv_pack tiles=2 margin=8+uv_density op=match+uv_info+```++## Limits++- Texture painting paints tile 1001 (UVs between 0 and 1); islands in other UDIM tiles are laid out, measured and+ exported, but painting them comes later.+- Packing works on islands' outlines when there are enough of them and the mesh isn't huge; otherwise on their boxes+ (a little less tight).++> **Coming from ZBrush?** The UV Editor does what ZBrush 2027's UV editing and UV Master do: seams on the model,+> several unwraps, UDIM packing, texel density and trim sheets, plus live stretch and density on the model while you+> edit and paint that stays put when the UVs change.++## See also++- [Texture painting](texture-painting.md): paint on the UVs+- [Baking](baking.md): bake maps onto them+- [Exporting](exporting.md): UVs go out with OBJ, glTF, FBX and USDdiff --git a/docs/guide/welcome.md b/docs/guide/welcome.mdindex 7e85aa88..dddae79d 100644--- a/docs/guide/welcome.md+++ b/docs/guide/welcome.md@@ -58,7 +58,7 @@ SculptForge is young (version 0.8; see [What's new](whats-new.md)). Some thingsstill on the roadmap:- Quad Remesh curve guides.-- UV editing (seams, relax) and UDIM tiles.+- Painting across UDIM tiles (the [UV Editor](uv-editor.md) lays them out; painting covers tile 1001).- Booleans and stencils.Others are not on the roadmap: ZModeler, the 2.5D canvas, and reading ZBrush's own `.ZTL` and `.ZPR`diff --git a/docs/guide/whats-new.md b/docs/guide/whats-new.mdindex 7aaca7be..5836c212 100644--- a/docs/guide/whats-new.md+++ b/docs/guide/whats-new.md@@ -7,6 +7,16 @@ chapter opens by itself the first time you start a new version; you can always f## Version 0.10.5+- **UV Editor** (**Tool > Texture Map > UV Editor**, <kbd>Shift</kbd>+<kbd>U</kbd>): the Part's UVs flat over the UDIM+ tiles, drawn by the graphics card so a million triangles stay smooth. Draw seams on the model with the **Seam+ Tool** (or take them from face groups, island borders or sharp edges), then **Unwrap**: **Least Stretch**,+ **Conformal**, **By Face Groups**, **Planar**, **Unfold Islands** or **Auto Seams**, with closed and tangled pieces+ cut for you. **Pack** into one tile or across UDIM tiles, **Set** and **Match** texel density, lay islands into+ **trim sheet** strips, and select vertices, edges, faces or islands (in the view or on the model) to move, rotate,+ scale, pin, weld, split, straighten and flip them. The model shows stretch, texel density, islands and a checker+ live while you edit, and a painted texture moves with every change so the model keeps its look. Every step is one+ undo step and a `uv_*` command for scripts. See [UV Editor](uv-editor.md).+- **Selection sets** (**Tool > Selection Sets**): store as many named snapshots of a Part's mask, face groups,visibility, vertex paint, UVs and shape as you like, and restore them at any subdivision level, not only the onethey were stored at. Combine two sets (union, intersect, subtract), restore one onto the current mask ordiff --git a/src/app/PanelUvEditor.cpp b/src/app/PanelUvEditor.cppindex 218b78c3..a6dd18e8 100644--- a/src/app/PanelUvEditor.cpp+++ b/src/app/PanelUvEditor.cpp@@ -6,8 +6,8 @@//// - Select vertices, edges, faces or islands (1-4) by clicking or dragging a box (Shift adds, Ctrl removes), or// on the model with Select in 3D; move, rotate and scale them with the box's handles or G / R / S.-// - Mark and clear seams on the model with the Seam tool (drag along edges; Alt clears), or from polygroups,-// island borders or sharp edges; Unwrap (least stretch, conformal, by polygroups, planar, unfold, auto seams),+// - Mark and clear seams on the model with the Seam tool (drag along edges; Alt clears), or from face groups,+// island borders or sharp edges; Unwrap (least stretch, conformal, by face groups, planar, unfold, auto seams),// Pack into one tile or across UDIM tiles, set or match texel density, lay islands into trim sheet strips,// pin, weld, split, straighten and flip.// - The model shows the same colours live: islands, stretch or texel density, the selection and a checker, so@@ -45,7 +45,7 @@ constexpr int kSizes[] = {1024, 2048, 4096, 8192};constexpr const char* kSizeLabels[] = {"1K", "2K", "4K", "8K"};constexpr UvUnwrapMethod kMethods[] = {UvUnwrapMethod::Isometric, UvUnwrapMethod::Conformal, UvUnwrapMethod::Polygroups,UvUnwrapMethod::Planar, UvUnwrapMethod::Unfold, UvUnwrapMethod::Auto};-constexpr const char* kColorLabels[] = {"Islands", "Stretch", "Texel Density", "Plain"};+constexpr const char* kColorLabels[] = {"Islands", "Stretch", "Density", "Plain"};constexpr const char* kImageLabels[] = {"No Image", "Checker", "Texture"};bool ctrlKey(SDL_Keymod mod) { return (mod & (SDL_KMOD_CTRL | SDL_KMOD_GUI)) != 0; }@@ -323,7 +323,7 @@ struct UvEditorUi {default: break;}glm::vec3 model = c;- if (s.faceSel[t] == 1) c = kSelect, a = 0.62f, model = glm::mix(c, kSelect, 1.0f);+ if (s.faceSel[t] == 1) model = glm::mix(c, kSelect, s.color == 1 || s.color == 2 ? 0.55f : 0.85f), c = model, a = 0.66f;else if (s.faceSel[t] == 2) model = glm::mix(model, kSelect, 0.45f);const uint32_t fc = pack(c, a);s.faceCol[t * 3] = s.faceCol[t * 3 + 1] = s.faceCol[t * 3 + 2] = fc;@@ -569,7 +569,7 @@ struct UvEditorUi {s.stretch[t] = uvTriangleStretchAt(m, uint32_t(t), s.topo, s.stretchCache);const glm::vec3 c = s.stretch[t] < 0.0f ? glm::vec3(0.85f, 0.2f, 0.85f) : uvHeatColor(std::clamp(s.stretch[t] * 3.0f, 0.0f, 1.0f));if (s.faceSel[t] != 1) s.faceCol[t * 3] = s.faceCol[t * 3 + 1] = s.faceCol[t * 3 + 2] = pack(c, 0.72f);- if (!s.overlay.colors.empty()) s.overlay.colors[t] = pack(s.faceSel[t] ? glm::mix(c, kSelect, s.faceSel[t] == 1 ? 1.0f : 0.45f) : c, 1.0f) & 0x00FFFFFFu;+ if (!s.overlay.colors.empty()) s.overlay.colors[t] = pack(s.faceSel[t] ? glm::mix(c, kSelect, s.faceSel[t] == 1 ? 0.55f : 0.45f) : c, 1.0f) & 0x00FFFFFFu;}}, 1 << 14);s.gpu.setColors(s.faceCol, s.edgeCol, s.moving);@@ -828,8 +828,8 @@ void App::registerUvEditorActions() {add("uv.unwrap", "Unwrap", ICON_LC_UNFOLD_HORIZONTAL, "", [this] { uvUi(*this, uvEditor_).unwrap(); }, nullptr,[this] { return doc_.mesh.triangleCount() > 0 && !(uvEditor_ && uvEditor_->job); },"Unwrap with the chosen method: the selected faces (fitted where they were), or the whole Part (packed). Least "- "Stretch keeps angles and lengths along the marked seams; Conformal keeps angles; By Polygroups cuts along the "- "polygroup borders too; Planar projects each piece; Unfold flattens the current islands again in place, keeping "+ "Stretch keeps angles and lengths along the marked seams; Conformal keeps angles; By Face Groups cuts along the "+ "face group borders too; Planar projects each piece; Unfold flattens the current islands again in place, keeping ""pins; Auto Seams finds its own. Closed pieces get cut automatically. Big meshes unwrap in the background.","uv_unwrap");add("uv.pack", "Pack", ICON_LC_PACKAGE, "", [this] { uvUi(*this, uvEditor_).run("uv_pack", uvUi(*this, uvEditor_).packArgs()); },@@ -841,9 +841,9 @@ void App::registerUvEditorActions() {selected, "Mark the selected edges (or the border of the selected faces) as seams: Unwrap cuts there.", "uv_seam");add("uv.seam_clear", "Clear Seam", nullptr, "", [runUv] { runUv("uv_seam", {{"op", std::string("clear")}}); }, nullptr,selected, "Clear the seams on the selected edges (or the border of the selected faces).", "uv_seam");- add("uv.seam_polygroups", "From Polygroups", nullptr, "", [runUv] { runUv("uv_seam", {{"op", std::string("polygroups")}}); },- nullptr, nullptr, "Mark every polygroup border as a seam.", "uv_seam");- add("uv.seam_islands", "From Islands", nullptr, "", [runUv] { runUv("uv_seam", {{"op", std::string("islands")}}); }, nullptr,+ add("uv.seam_polygroups", "Face Groups", nullptr, "", [runUv] { runUv("uv_seam", {{"op", std::string("polygroups")}}); },+ nullptr, nullptr, "Mark every face group border as a seam.", "uv_seam");+ add("uv.seam_islands", "Island Borders", nullptr, "", [runUv] { runUv("uv_seam", {{"op", std::string("islands")}}); }, nullptr,uvs, "Mark every current UV island border as a seam (keeps an imported layout's cuts for Unwrap).", "uv_seam");add("uv.seam_angle", "Sharp Edges", nullptr, "",[this, runUv] { runUv("uv_seam", {{"op", std::string("angle")}, {"angle", double(uvEditor_ ? uvEditor_->seamAngle : 60.0f)}}); },@@ -988,7 +988,7 @@ void App::drawUvEditor() {if (ImGui::Combo("##uvcolor", &s.color, kColorLabels, 4)) s.colorsDirty = true;ui::HelpText("Colours", nullptr,"What the faces show, here and on the model: Islands (a colour each), Stretch (green: true to the surface; "- "yellow to red: stretched or squashed; magenta: folded over), Texel Density (blue: fewer texels than the "+ "yellow to red: stretched or squashed; magenta: folded over), Density (texel density; blue: fewer texels than the ""mean, red: more) or Plain.",kPath);nextOnLine(110 * scale, style.ItemSpacing.x);@@ -1138,7 +1138,7 @@ void App::drawUvEditor() {const bool on = int(i) == s.strip;dl->AddRectFilled(a, b, on ? IM_COL32(240, 136, 46, 38) : IM_COL32(120, 160, 255, 14));dl->AddRect(a, b, on ? IM_COL32(240, 136, 46, 200) : IM_COL32(150, 180, 255, 90), 0, 0, on ? 2.0f : 1.0f);- dl->AddText(ImVec2(b.x + 6 * scale, a.y + 2 * scale), on ? IM_COL32(255, 180, 110, 255) : IM_COL32(160, 180, 220, 200),+ dl->AddText(ImVec2(b.x - ImGui::CalcTextSize(strips[i].name.c_str()).x - 6 * scale, a.y + 3 * scale), on ? IM_COL32(255, 180, 110, 255) : IM_COL32(160, 180, 220, 200),strips[i].name.c_str());}}@@ -1240,7 +1240,7 @@ void App::drawUvEditor() {ImGui::Combo("##uvmethod", &s.method, labels, 6);ui::HelpText("Method", nullptr,"Least Stretch: angles and lengths, along the marked seams (the default). Conformal (LSCM): angles only. "- "By Polygroups: also cuts along the polygroup borders. Planar: each piece projected flat. Unfold Islands: "+ "By Face Groups: also cuts along the face group borders. Planar: each piece projected flat. Unfold Islands: ""the current islands flattened again where they are, keeping pins. Auto Seams: finds its own seams.",kPath);if (kMethods[std::clamp(s.method, 0, 5)] == UvUnwrapMethod::Isometric || kMethods[s.method] == UvUnwrapMethod::Polygroups ||diff --git a/src/core/UvCommands.cpp b/src/core/UvCommands.cppindex cff6a6e0..1bd70d03 100644--- a/src/core/UvCommands.cpp+++ b/src/core/UvCommands.cpp@@ -130,7 +130,7 @@ void registerUvCommands(CommandRegistry& reg) {reg.add({"uv_unwrap","Unwrap the active Part's UVs (UV Editor > Unwrap). Methods: isometric (least stretch: angles and lengths, ""along the marked seams; the default), conformal (LSCM: angles, along the seams), polygroups (cut along "- "the polygroup borders and the seams), planar (each piece projected flat), unfold (flatten the current "+ "the face group borders and the seams), planar (each piece projected flat), unfold (flatten the current ""islands again in place, keeping pinned corners), auto (finds its own seams, xatlas). Pieces that are ""closed or looped get extra cuts. The result is packed into the 0-1 tile, or across UDIM tiles. With a UV ""selection only the selected faces are unwrapped (fitted where they were). A painted texture moves onto "@@ -211,7 +211,7 @@ void registerUvCommands(CommandRegistry& reg) {reg.add({"uv_seam","Mark or clear UV seams on the active Part (seams are where Unwrap cuts). op: mark / clear (the UV ""Editor's selected edges, or the border of its selected faces), path (mark the shortest edge path from "- "vertex `from` to vertex `to`; clear=true clears it), polygroups (every polygroup border), islands (every "+ "vertex `from` to vertex `to`; clear=true clears it), polygroups (every face group border), islands (every ""current UV island border), angle (edges sharper than `angle` degrees), clear_all. One undo step.",{{"op", T::String, "mark, clear, path, polygroups, islands, angle or clear_all", true},{"from", T::Number, "path: the vertex to start at", false},@@ -246,7 +246,7 @@ void registerUvCommands(CommandRegistry& reg) {const std::vector<uint32_t> path = uvEdgePath(m, uint32_t(from), uint32_t(to));if (path.empty()) return {false, "Those vertices aren't connected"};uvSetSeams(m, twin, path, !argBool(a, "clear", false));- } else if (op == "polygroups") {+ } else if (op == "polygroups" || op == "face_groups") {uvSeamsFromPolygroups(m, twin);} else if (op == "islands") {if (!m.hasUvs()) return {false, kNoUvs};@@ -266,13 +266,13 @@ void registerUvCommands(CommandRegistry& reg) {reg.add({"uv_select","Set the UV Editor's selection on the active Part (what the other uv_* commands work on). op: all, none, "- "invert, island (the island of triangle `face`), face (triangle `face`), polygroup (every face of polygroup "+ "invert, island (the island of triangle `face`), face (triangle `face`), polygroup (every face of face group ""`group`), rect (faces touching u0 v0 u1 v1), seams (the marked seam edges), mode (just switch to `mode`). ""`mode` (vertex, edge, face, island) converts the selection; `add` adds to it instead of replacing it.",{{"op", T::String, "all, none, invert, island, face, polygroup, rect, seams or mode", true},{"mode", T::String, "vertex, edge, face or island", false},{"face", T::Number, "island / face: a triangle index", false},- {"group", T::Number, "polygroup: its id", false},+ {"group", T::Number, "polygroup: the face group id", false},{"u0", T::Number, "rect: lower u", false},{"v0", T::Number, "rect: lower v", false},{"u1", T::Number, "rect: upper u", false},diff --git a/src/core/UvUnwrap.cpp b/src/core/UvUnwrap.cppindex 6777dc8a..12b6f889 100644--- a/src/core/UvUnwrap.cpp+++ b/src/core/UvUnwrap.cpp@@ -3,7 +3,7 @@//// Unwrapping (UV Editor > Unwrap, uv_unwrap)://-// 1. The surface is cut into pieces along the marked seams (with Polygroups, the polygroup borders too; Unfold+// 1. The surface is cut into pieces along the marked seams (By Face Groups: the face group borders too; Unfold// keeps the current islands). Without marked seams, a mesh that has UVs is cut along its island borders.// 2. A piece that isn't a topological disk (a closed shell, a tube, a handle) gets extra cuts: the edges no dual// spanning tree crosses, pruned back to the loops that matter; a closed shell is first split across its middle.@@ -55,7 +55,7 @@ const char* uvUnwrapMethodLabel(UvUnwrapMethod m) {case UvUnwrapMethod::Auto: return "Auto Seams";case UvUnwrapMethod::Conformal: return "Conformal (LSCM)";case UvUnwrapMethod::Isometric: return "Least Stretch";- case UvUnwrapMethod::Polygroups: return "By Polygroups";+ case UvUnwrapMethod::Polygroups: return "By Face Groups";case UvUnwrapMethod::Planar: return "Planar";case UvUnwrapMethod::Unfold: return "Unfold Islands";}@@ -72,6 +72,7 @@ bool parseUvUnwrapMethod(const std::string& id, UvUnwrapMethod& m) {if (id == "lscm" || id == "angle") return m = UvUnwrapMethod::Conformal, true;if (id == "arap" || id == "stretch" || id == "least_stretch") return m = UvUnwrapMethod::Isometric, true;if (id == "xatlas") return m = UvUnwrapMethod::Auto, true;+ if (id == "face_groups" || id == "groups") return m = UvUnwrapMethod::Polygroups, true;return false;}