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.

QRemesh: Symmetry on by default; UI test and guide for the model's mirror plane and kept pieces

islandmed995cbc55edc2
diff --git a/docs/guide/glossary.md b/docs/guide/glossary.md
index 42551f3d..0b70d268 100644
--- a/docs/guide/glossary.md
+++ b/docs/guide/glossary.md
@@ -96,6 +96,7 @@ for what is planned.
| Studio brush folder | A shared, read-only brush folder for a team (`SCULPTFORGE_BRUSH_PATH`). See [For studios](studios.md) |
| Paint target (Vertex / Texture) | Where painting goes on a SubTool that has a texture: its vertices (polypaint) or its texture. Top shelf, next to **Rgb**. See [Texture painting](texture-painting.md#vertex-or-texture) |
| QRemesh | SculptForge's automatic quad retopology (ZBrush's ZRemesher), in **Tool > Geometry**. See [Quad retopology](retopology.md) |
+| Mirror plane (QRemesh) | The plane QRemesh's **Symmetry** mirrors across: the model's own middle (the world's centre plane when the model is symmetric about it), found from the model. Like ZBrush's local symmetry. See [Quad retopology](retopology.md#qremesh) |
| Padding (gutter) | The few texels around each UV island that texture painting and baking also fill, so seams don't show. See [Texture painting](texture-painting.md) and [Baking](baking.md) |
| 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) |
diff --git a/docs/guide/retopology.md b/docs/guide/retopology.md
index 65b423f9..1cad6169 100644
--- a/docs/guide/retopology.md
+++ b/docs/guide/retopology.md
@@ -36,7 +36,7 @@ Both steps are single undo steps (<kbd>Ctrl</kbd>+<kbd>Z</kbd>).
| **Keep Groups** | Edge loops run exactly along the polygroup borders, and the result keeps the polygroups |
| **Detect Edges** | Hard edges, where faces meet at more than 50 degrees, get an edge loop, so boxes and bevels stay crisp (on by default) |
| **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) |
+| **Symmetry** | Remesh one half and mirror it, welded on the seam, for exactly symmetric topology (on by default). It mirrors on the axis chosen in the **Transform** palette (X if none), across the model's own middle plane: the world's centre plane when the model is symmetric about it, otherwise the plane through the model's middle, so a model moved away from the centre works too. A model that isn't mirror-symmetric is remeshed whole instead, and the status line says "Symmetry off: the model isn't mirror-symmetric"; one that is nearly symmetric (a bump on one side) gets mirrored topology that follows each side's own surface |
| **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) |
What happens to your data:
@@ -49,8 +49,13 @@ What happens to your data:
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**.
-- Hidden parts are remeshed too. Very small separate pieces (smaller than a quad or two) can disappear; raise
- the target or QRemesh them separately.
+- Hidden parts are remeshed too.
+- Separate pieces stay separate and none is dropped: small ones (eyes, teeth, rivets, anything that would get
+ fewer than about 100 quads) are remeshed on their own with at least 32 quads, more for small round pieces
+ with Adaptive Size. A piece the grid can't cover at all is kept as it was (as triangles).
+- Thin parts (a blade, a fin, a slab thinner than a quad) keep both their sides, and with **Detect Edges** their
+ hard edges keep a loop each and their corners stay put. Their corners can still be cut a little when the
+ part is much thinner than a quad: raise the target, or use polypaint density there.
### Guiding the edge flow
@@ -102,7 +107,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`; off by default in scripts; the mirror plane is found from the model), `symmetry_center` (use this plane instead, e.g. `0` for the world's centre), `keep_original`, `smooth` (relaxation passes, default 6), `seed` |
| `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/tests/ui/qremesh_symmetry.sfui b/tests/ui/qremesh_symmetry.sfui
new file mode 100644
index 00000000..a201af12
--- /dev/null
+++ b/tests/ui/qremesh_symmetry.sfui
@@ -0,0 +1,42 @@
+# QRemesh symmetry and pieces: Symmetry is on by default and mirrors about the model's own plane, so a sculpt
+# moved away from the world centre still comes out mirror-symmetric (about x = 2.5 here); a model that isn't
+# symmetric is remeshed whole (the status line says so) and a small separate piece is kept, not dropped.
+run new_sphere subdivisions=5
+run stroke points="-0.5,0.35,2 0,0.5,2 0.5,0.35,2" brush=Standard radius=0.16 strength=1
+run stroke points="-0.45,-0.35,2 0.45,-0.35,2" brush=Crease radius=0.12 strength=1
+run transform translate=2.5,0,0 masked=false
+expect_value center_x > 2.45
+expect_value center_x < 2.55
+click "Geometry##tool.geometry"
+expect "QRemesh/Symmetry"
+
+# Ctrl-hover help explains the plane.
+hold ctrl
+hover "QRemesh/Symmetry"
+expect_help "model's own"
+hold none
+
+# Off-centre: mirrored about the model's middle, not the world's.
+drag_item "QRemesh/##qtarget" -20 0
+click "QRemesh/QRemesh"
+wait_idle 120
+expect_status "mirrored across X = 2.5"
+expect_value quad_percent == 100
+expect_value center_x > 2.45
+expect_value center_x < 2.55
+click "Frame##view.frame"
+click "PolyF##view.polyf"
+shot offcentre-symmetry-polyf
+click "PolyF##view.polyf"
+
+# A small separate piece beside it: not symmetric any more, so no mirroring; both pieces come out as quads.
+run subtool_append type=sphere size=0.12
+run subtool_merge_visible
+remember triangles merged_tris
+click "QRemesh/QRemesh"
+wait_idle 120
+expect_status "Symmetry off"
+expect_value quad_percent == 100
+click "Frame##view.frame"
+click "PolyF##view.polyf"
+shot small-piece-kept-polyf