Skip to content

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.

Guide: Keep Texture, Auto UV moving the paint, merge keeping textures; transfer copies layer settings only

islandmeda152e6329c3c
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 6f99bfee..fe2dd1b2 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -12,7 +12,7 @@ licenses require.
| [GLM](https://github.com/g-truc/glm) | 1.0.1 | MIT License (or The Happy Bunny License) | Vector and matrix math. |
| [stb_image / stb_image_write](https://github.com/nothings/stb) | commit 013ac3be | MIT License or Public Domain (Unlicense), at your choice | Image loading and PNG writing. Vendored in third_party/stb. |
| [ufbx](https://github.com/ufbx/ufbx) | 0.23.1 (commit 5955c5c) | MIT License or Public Domain (Unlicense), at your choice | FBX import. Vendored in third_party/ufbx. |
-| [xatlas](https://github.com/jpcy/xatlas) | commit f700c77 | MIT License | Automatic UV unwrapping (UV > Auto UV) for texture painting. Vendored in third_party/xatlas. |
+| [xatlas](https://github.com/jpcy/xatlas) | commit f700c77 (two local fixes, see third_party/xatlas/SOURCE.txt) | MIT License | Automatic UV unwrapping (UV > Auto UV) for texture painting. Vendored in third_party/xatlas. |
| [MikkTSpace](https://github.com/mmikk/MikkTSpace) | commit 3e895b4 | zlib License | Tangent frames for baked tangent-space normal maps (Tool > Bake), matching Blender, Unreal, Unity and Godot. Vendored in third_party/mikktspace. |
| [Instant Meshes](https://github.com/wjakob/instant-meshes) | formulas only, nothing vendored | BSD 3-Clause License | QRemesh (Tool > Geometry): the field formulas in src/core/QRemesh.cpp (extrinsic 4-RoSy orientation / position compatibility, the middle point of two tangent planes, lattice rounding) follow its reference code. The rest of QRemesh is our own. |
| [Inter typeface](https://github.com/rsms/inter) | 4.1 | SIL Open Font License 1.1 | User interface font, embedded in the desktop app. Vendored in assets/fonts. |
diff --git a/docs/guide/geometry.md b/docs/guide/geometry.md
index ef6523e2..5413aabf 100644
--- a/docs/guide/geometry.md
+++ b/docs/guide/geometry.md
@@ -13,8 +13,8 @@ All of them work on the **active SubTool** and, except the LOD preview, are undo
|---|---|---|---|---|---|---|
| Divide (levels) | **Tool > Geometry > Divide**, <kbd>Ctrl</kbd>+<kbd>D</kbd> | x4 per level, lower levels kept | Each quad becomes four (Catmull-Clark) | Yes | Yes (interpolated) | Yes |
| Subdivide | **Tool > Geometry > Subdivide** | x4 per level | Each quad becomes four | Yes | Yes (interpolated) | Yes |
-| Voxel Remesh | **Tool > Remesh > Voxel Remesh** | Set by resolution | All quads (new ones) | Baked in | Yes (transferred) | No (reset) |
-| QRemesh | **Tool > Geometry > QRemesh** | Set by Target Polygons | All quads, with edge loops | Baked in | Yes (transferred) | Polygroups with Keep Groups; no hidden faces or UVs |
+| Voxel Remesh | **Tool > Remesh > Voxel Remesh** | Set by resolution | All quads (new ones) | Baked in | Yes (transferred) | No (reset); a texture is kept on new UVs with Keep Texture |
+| QRemesh | **Tool > Geometry > QRemesh** | Set by Target Polygons | All quads, with edge loops | Baked in | Yes (transferred) | Polygroups with Keep Groups; no hidden faces; a texture is kept on new UVs with Keep Texture |
| Decimate | **Tool > Geometry > Decimate** | Reduced | No, all triangles | Yes | Yes | Yes |
| LOD chain | **Tool > Export** | One level per ratio step | LOD0 keeps them; lower levels are triangles | Yes, on every level | Yes | Yes |
@@ -75,8 +75,12 @@ What happens to your data:
- Sculpt layers are baked into the surface: the result has no layers.
- Mask and polypaint are transferred from the nearest original vertex.
-- Polygroups, hidden faces and UVs are reset (everything becomes visible, one polygroup, no UVs). Hidden parts are
+- Polygroups, hidden faces and UVs are reset (everything becomes visible, one polygroup). Hidden parts are
remeshed too.
+- A painted texture is kept with **Keep Texture** (on by default, shown next to the button when the SubTool has a
+ texture): the result gets Auto UVs and the texture is projected onto it, every layer included, in the same undo
+ step. This runs in the background (Auto UV of a few hundred thousand triangles takes several seconds) with a
+ progress bar and **Cancel**. Off: the texture is dropped. See [Texture painting](texture-painting.md#uvs-and-geometry).
- Separate pieces that don't touch stay separate pieces; overlapping ones are merged.
- The new surface is made of even quads (the original's quads are rebuilt, not kept).
@@ -156,9 +160,9 @@ heavy sculpt:
| Command | Options |
|---|---|
| `subdivide` | `levels` 1-4 (default 1) |
-| `remesh` | `resolution` 32-512 voxels across the longest side (default 200) |
+| `remesh` | `resolution` 32-512 voxels across the longest side (default 200); `keep_texture` (default true) |
| `decimate` | `ratio` 0.01-1 of the triangles to keep (default 0.5), or `triangles` for an exact target |
-| `qremesh` | `target` quads (default 5000), `adaptive`, `keep_groups`, `detect_edges`, `use_polypaint`, `symmetry`, `keep_original`; see [Quad retopology](retopology.md#scripting) |
+| `qremesh` | `target` quads (default 5000), `adaptive`, `keep_groups`, `detect_edges`, `use_polypaint`, `symmetry`, `keep_original`, `keep_texture`; see [Quad retopology](retopology.md#scripting) |
| `export_lods` | `path` (base name), `levels` 1-8 including LOD0 (default 4), `ratio` 0.1-0.9 (default 0.5) |
```sh
diff --git a/docs/guide/glossary.md b/docs/guide/glossary.md
index 42551f3d..2ed35d25 100644
--- a/docs/guide/glossary.md
+++ b/docs/guide/glossary.md
@@ -100,6 +100,7 @@ for what is planned.
| Bake | Capture a high-poly's detail as images (maps) on a low-poly's UVs. See [Baking](baking.md) |
| Cage (front / rear distance) | How far in front of and behind the low-poly the bake's rays look for the high-poly. See [Baking](baking.md#how-the-bake-works) |
| Displacement map | A map of how far the high-poly lies from the low-poly along its normal; mid-grey = 0. See [Baking](baking.md#displacement-mid-grey-is-zero) |
+| Keep Texture | Remesh option (Voxel Remesh, QRemesh): give the new surface Auto UVs and project the painted texture onto it, so the paint survives. See [Texture painting](texture-painting.md#uvs-and-geometry) |
| 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 |
diff --git a/docs/guide/retopology.md b/docs/guide/retopology.md
index 65b423f9..fb6d5b7a 100644
--- a/docs/guide/retopology.md
+++ b/docs/guide/retopology.md
@@ -38,6 +38,7 @@ Both steps are single undo steps (<kbd>Ctrl</kbd>+<kbd>Z</kbd>).
| **Use Polypaint** | Paint where you want density: red areas get up to four times the quads, blue areas down to a quarter, white areas are unchanged |
| **Symmetry** | Remesh one half and mirror it, welded on the seam, for exactly symmetric topology. It mirrors across the plane through the origin on the axis chosen in the **Transform** palette (X if none) |
| **Keep Original** | Keep the SubTool as it was, hidden, below the new one, ready for ProjectAll. Off: the SubTool is replaced, as in ZBrush (undo brings it back) |
+| **Keep Texture** | Shown when the SubTool has a painted texture (on by default): Auto UV the result and project the texture onto it. Off: the texture is dropped |
What happens to your data:
@@ -47,8 +48,10 @@ What happens to your data:
- Sculpt layers are baked into the surface: the result has no layers.
- Mask and polypaint are interpolated from the closest point of the sculpt (polypaint is blurred to the new
resolution until you project it back onto a divided copy).
-- Polygroups are kept with **Keep Groups**; otherwise the result is one polygroup. UVs and the texture are
- dropped: unwrap again with **Tool > Texture Map > Auto UV**.
+- Polygroups are kept with **Keep Groups**; otherwise the result is one polygroup. The old UVs are dropped. A
+ painted texture is kept with **Keep Texture** (on by default): the result gets Auto UVs and the texture, every
+ layer of it, is projected onto them from the old surface, in the same undo step. See
+ [Texture painting](texture-painting.md#uvs-and-geometry).
- Hidden parts are remeshed too. Very small separate pieces (smaller than a quad or two) can disappear; raise
the target or QRemesh them separately.
@@ -102,7 +105,7 @@ straight along the normal, it takes the closest point within **Dist**.
| Command | Options |
|---|---|
-| `qremesh` | `target` (16 to 2,000,000, default 5000), `adaptive` (0-1, default 0.5), `keep_groups`, `detect_edges` (default true), `use_polypaint`, `symmetry` (`x`, `y` or `z`), `keep_original`, `smooth` (relaxation passes, default 6), `seed` |
+| `qremesh` | `target` (16 to 2,000,000, default 5000), `adaptive` (0-1, default 0.5), `keep_groups`, `detect_edges` (default true), `use_polypaint`, `symmetry` (`x`, `y` or `z`), `keep_original`, `smooth` (relaxation passes, default 6), `seed`, `keep_texture` (default true) |
| `project_all` | `distance` (0.001-1, default 0.02), `mean`, `blur` (0-20), `geometry` (default true), `polypaint` (default true), `source` (one SubTool's name instead of all visible ones) |
```sh
diff --git a/docs/guide/subtools.md b/docs/guide/subtools.md
index b97568e9..39cb8141 100644
--- a/docs/guide/subtools.md
+++ b/docs/guide/subtools.md
@@ -94,6 +94,10 @@ The up and down arrow buttons under the list move the active SubTool one place u
Merging keeps every attribute, gives each original mesh its own polygroups (so you can split them again later) and
matches sculpt layers by name. The merged SubTool starts with an empty undo history.
+Painted textures are kept too: the merged SubTool gets new Auto UVs and one texture, the size of the largest,
+holding each part's paint exactly (texture layers are flattened; parts without a texture are white). On big
+meshes the Auto UV takes a while. Scripts can skip it with `keep_texture=false`, which drops the textures.
+
> **Tip:** Merge first when you want one [voxel remesh](geometry.md#voxel-remesh) to fuse several pieces into a
> single watertight surface.
diff --git a/docs/guide/texture-painting.md b/docs/guide/texture-painting.md
index 948e0e4c..18e82c5b 100644
--- a/docs/guide/texture-painting.md
+++ b/docs/guide/texture-painting.md
@@ -89,12 +89,27 @@ texture after giving it UVs.
## UVs and geometry
-- **Auto UV** replaces any existing UVs. If the SubTool already had a painted texture, the paint no longer lines
- up with the new layout: undo the Auto UV to get the old UVs back.
+- **Auto UV** replaces any existing UVs. If the SubTool already has a painted texture, the paint moves with it:
+ every texel of the new layout takes the colour of the same point of the surface from the old one, for the Base
+ and every texture layer (with their blend modes, opacity and names), and the islands get a padded border. It
+ is one undo step: undo brings back the old UVs and the old texture exactly. Moving a 4K texture takes a fraction
+ of a second on a million triangles (the unwrap itself takes longer; see below). The paint is resampled once,
+ so very fine detail softens slightly (well under one texel).
- [Subdividing](geometry.md#subdivide), [decimating](geometry.md#decimate), [splitting](subtools.md#split-a-subtool)
- and duplicating keep the UVs, so the texture stays on. A [voxel remesh](geometry.md#voxel-remesh) and
- [merging](subtools.md#merge-subtools) SubTools build new surfaces without these UVs, so they drop the texture
- (export it first if you need it).
+ and duplicating keep the UVs, so the texture stays on. Decimate leaves the vertices on UV seams in place, so the
+ texture stays exact across seams.
+- **Keep Texture** (on by default, shown under **Tool > Remesh** and **Tool > Geometry > QRemesh** when the
+ SubTool has a texture): a [voxel remesh](geometry.md#voxel-remesh) or [QRemesh](retopology.md) builds a new
+ surface without UVs, so SculptForge unwraps the result with Auto UV and projects the texture onto it from the
+ old surface (each new texel takes the colour of the closest point of the old one), keeping every layer. It is
+ part of the same undo step. It adds the time of an Auto UV of the result, so a voxel remesh of a painted
+ SubTool runs in the background with a progress bar and **Cancel**. Turn it off to drop the texture instead
+ (the status line says so). Paint finer than the new surface's detail is kept, since it lives in the texture.
+- [Merging](subtools.md#merge-subtools) SubTools keeps their textures: the merged SubTool gets Auto UVs and one
+ texture (the size of the largest) holding each part's paint, with the texture layers flattened. Parts without
+ a texture come out white.
+- Auto UV on dense meshes: the islands are kept to about 4,000 triangles each, so a million-triangle sculpt
+ unwraps 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.
> **ZBrush:** ZBrush paints polypaint and converts it to a texture afterwards (**Texture Map > New From
@@ -105,7 +120,7 @@ texture after giving it UVs.
| Command | What it does |
|---|---|
-| `uv_auto` | Unwrap the active SubTool (xatlas); `resolution=4096` packs the islands for that texture size |
+| `uv_auto` | Unwrap the active SubTool (xatlas); `resolution=4096` packs the islands for that texture size. A painted texture moves onto the new UVs (`keep_texture=false` leaves it as it was) |
| `texture_create size=2048` | Give the SubTool a texture (1024, 2048, 4096, 8192 or `1k`...`8k`) and paint into it; `from_polypaint=true` starts from the polypaint |
| `paint_target target=texture` | Where painting goes: `vertex` or `texture` |
| `texture_from_polypaint` | Bake the polypaint into the active texture layer |
@@ -114,5 +129,8 @@ texture after giving it UVs.
| `texture_import path=skin.png` | Load an image as the texture |
| `texture_delete` | Remove the texture |
+`remesh`, `qremesh`, `subtool_merge_down` and `subtool_merge_visible` keep a texture unless you add
+`keep_texture=false`.
+
`paint_fill`, `paint_from_cavity`, `paint_clear` and every `paint_layer_*` command work on the texture while
`paint_target` is `texture`. See [Scripting and automation](scripting.md).
diff --git a/src/core/TextureTransfer.cpp b/src/core/TextureTransfer.cpp
index 8c5e2815..7f0c7c32 100644
--- a/src/core/TextureTransfer.cpp
+++ b/src/core/TextureTransfer.cpp
@@ -153,8 +153,18 @@ std::shared_ptr<PaintTexture> blankLike(const PaintTexture& like, bool withLayer
auto t = makeTexture(like.width, like.height);
if (withLayers && !like.layers.empty()) {
t->base.assign(t->texelCount() * 4, 255);
- t->layers = like.layers;
- for (auto& l : t->layers) l.rgba.assign(t->texelCount() * 4, 0);
+ t->layers.reserve(like.layers.size());
+ for (const TextureLayer& l : like.layers) { // the settings, not the texels
+ TextureLayer c;
+ c.id = l.id;
+ c.name = l.name;
+ c.opacity = l.opacity;
+ c.blend = l.blend;
+ c.visible = l.visible;
+ c.locked = l.locked;
+ c.rgba.assign(t->texelCount() * 4, 0);
+ t->layers.push_back(std::move(c));
+ }
t->activeLayer = like.activeLayer;
}
return t;