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.

34.0 KB
Raw Blame
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
//
// uv_* commands: the UV Editor's operations (app/PanelUvEditor.cpp) for scripts, the CLI, Python and the AI
// assistant. Each is one undo step holding the old UVs and seams (UvUndo) and, when a painted texture is moved
// onto the new layout (keep_texture), the texture too (core/TextureTransfer.h). Operations that work on "the
// selection" use the UV Editor's (Document::uvSelection, set with uv_select) and the whole Part when nothing is
// selected.
#include "core/Commands.h"
#include "core/Texture.h"
#include "core/TextureTransfer.h"
#include "core/Undo.h"
#include "core/Uv.h"
#include "core/UvEdit.h"

#include <algorithm>
#include <cmath>
#include <cstdio>

namespace sf {

namespace {

using T = ParamSpec::Type;

const char* kNoUvs = "The Part has no UVs: unwrap it first (UV Editor > Unwrap, or uv_unwrap)";

int resolutionArg(const Document& doc, const Args& a) {
    if (a.contains("resolution")) return std::clamp(int(argNumber(a, "resolution", kDefaultTextureSize)), 64, 16384);
    return doc.mesh.texture ? std::max(doc.mesh.texture->width, doc.mesh.texture->height) : kDefaultTextureSize;
}

std::string fmt(const char* f, double x) {
    char buf[64];
    std::snprintf(buf, sizeof buf, f, x);
    return buf;
}

std::string plural(size_t n, const char* word) { return std::to_string(n) + " " + word + (n == 1 ? "" : "s"); }

// The islands to work on: the selection's, or every island when nothing is selected.
std::vector<uint8_t> targetIslands(const Document& doc, const UvTopology& topo) {
    return uvSelectedIslands(doc.mesh, topo, doc.uvSelection, true);
}

// The corners to move: the selection's, or every corner.
std::vector<uint32_t> targetCorners(const Document& doc, const UvTopology& topo) {
    if (doc.uvSelection.valid(doc.mesh) && !doc.uvSelection.empty()) return uvSelectedCorners(doc.mesh, topo, doc.uvSelection);
    std::vector<uint32_t> all(doc.mesh.uvs.size());
    for (uint32_t c = 0; c < all.size(); ++c) all[c] = c;
    return all;
}

// A fit pack that left part of the grid empty says why first (the status line may cut the rest off).
std::string gridNote(const UvPackResult& p, const UvPackOptions& o) {
    if (o.density > 0.0f || o.tiles <= 1 || p.tilesUsed <= 0 || p.tilesUsed >= o.tiles) return {};
    return std::to_string(p.tilesUsed) + " of " + std::to_string(o.tiles) +
           " tiles used: the largest island limits the scale; Pack at Density fills more. ";
}

} // namespace

UvPackOptions uvPackOptions(const Document& doc, const Args& a) {
    UvPackOptions o;
    o.resolution = resolutionArg(doc, a);
    o.marginPx = float(std::clamp(argNumber(a, "margin", 8.0), 0.0, 256.0));
    o.rotate = argBool(a, "rotate", true);
    o.tiles = std::clamp(int(argNumber(a, "tiles", 1)), 1, 100);
    // A Columns x Rows grid (the UV Editor's Pack target): `columns` wide, `rows` high (or `tiles` in that width).
    if (a.contains("columns") || a.contains("rows")) {
        o.columns = std::clamp(int(argNumber(a, "columns", 10)), 1, 10);
        if (a.contains("rows")) o.tiles = o.columns * std::clamp(int(argNumber(a, "rows", 1)), 1, 10);
        else if (!a.contains("tiles")) o.tiles = o.columns;
    }
    o.equalDensity = argBool(a, "equal_density", true);
    o.density = float(std::max(argNumber(a, "density", 0.0), 0.0));
    o.firstTile = std::clamp(int(argNumber(a, "first_tile", 1001)), 1001, 1100);
    return o;
}

std::string uvPackNote(const UvPackResult& p, const UvPackOptions& o) {
    std::string s = gridNote(p, o) + plural(p.islands, "island") + " packed";
    if (p.tilesUsed > 1) s += " into " + std::to_string(p.tilesUsed) + " UDIM tiles";
    s += ", " + fmt("%.0f", double(p.coverage) * 100.0) + "% of the space used, " + fmt("%.1f", double(p.density)) +
         " texels per unit";
    return s;
}

UvEditStep::UvEditStep(Document& doc, std::string label, bool keepTexture) : doc_(doc), texture_(keepTexture && hasTexture(doc.mesh)) {
    if (texture_) record_ = captureTexture(doc.mesh, label);
    else record_.label = std::move(label);
    record_.uv = UvUndo::capture(doc.mesh);
}

std::string UvEditStep::commit() {
    Mesh& m = doc_.mesh;
    if (!record_.uv) return {};
    if (m.uvs == record_.uv->uvs && m.uvFlags == record_.uv->flags) {
        if (texture_) record_.texture->swapWith(m); // (put back the untouched original)
        record_.uv.reset();
        return {};
    }
    std::string note;
    if (texture_ && m.uvs.size() == record_.uv->uvs.size() && m.uvs != record_.uv->uvs) {
        std::vector<glm::vec2> fresh = std::move(m.uvs);
        m.uvs = record_.uv->uvs;
        note = setUvsKeepingTexture(m, std::move(fresh), true);
    }
    m.facesDirty = true;
    record_.uv->commit(m);
    if (texture_) finishTextureUndo(record_, m);
    doc_.undo.push(std::move(record_));
    record_.uv.reset();
    return note;
}

std::string uvInfoText(const Mesh& m, int resolution) {
    if (!m.hasUvs()) {
        const size_t seams = uvSeamCount(m);
        return "No UVs" + (seams ? "; " + plural(seams, "seam edge") + " marked" : std::string());
    }
    const UvTopology topo = buildUvTopology(m);
    size_t pins = 0;
    for (uint8_t f : m.uvFlags) pins += (f & kUvPin) != 0;
    std::vector<int> tiles;
    for (uint32_t i = 0; i < topo.islandCount; ++i) {
        const uint32_t t = topo.islandTriangles[topo.islandOffsets[i]];
        const glm::vec2 c = (m.uvs[t * 3] + m.uvs[t * 3 + 1] + m.uvs[t * 3 + 2]) / 3.0f;
        tiles.push_back(udimTile(c));
    }
    std::sort(tiles.begin(), tiles.end());
    tiles.erase(std::unique(tiles.begin(), tiles.end()), tiles.end());
    const UvStretchStats st = uvStretchStats(m);
    std::string s = plural(topo.islandCount, "island") + ", " + plural(uvSeamCount(m), "seam edge") + ", " +
                    plural(pins, "pinned corner") + "; " + fmt("%.1f", double(uvMeshDensity(m, resolution))) +
                    " texels per unit at " + std::to_string(resolution) + "; tiles";
    for (int t : tiles) s += " " + std::to_string(t);
    s += "; stretch " + fmt("%.3f", double(st.mean)) + " mean, " + fmt("%.2f", double(st.flipped) * 100.0) + "% flipped";
    return s;
}

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), facegroups (cut along "
             "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 "
             "the new UVs (keep_texture). One undo step.",
             {{"method", T::String, "isometric (default), conformal, facegroups, planar, unfold or auto", false},
              {"selected", T::Bool, "Only the UV Editor's selected faces (default true when something is selected)", false},
              {"iterations", T::Number, "Least-stretch refinement steps (default 10; 0 = conformal)", false},
              {"resolution", T::Number, "Texture size the margin is measured in (default: the texture's, or 2048)", false},
              {"margin", T::Number, "Texels between packed islands (default 8)", false},
              {"tiles", T::Number, "UDIM tiles to pack across (default 1)", false},
              {"columns", T::Number, "Pack into a grid this many tiles wide (1-10; with rows, columns x rows tiles)", false},
              {"rows", T::Number, "Rows of the grid (1-10): fills columns x rows tiles", false},
              {"rotate", T::Bool, "Turn islands to fit better when packing (default true)", false},
              {"density", T::Number, "Pack at exactly this texel density (texels per unit; uses as many tiles as needed)", false},
              {"pack", T::Bool, "Pack the result (default true; false fits each island where its old UVs were)", false},
              {"keep_texture", T::Bool, "Move a painted texture onto the new UVs (default true)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (m.triangleCount() == 0) return {false, "There is no mesh to unwrap"};
                 UvUnwrapOptions o;
                 if (a.contains("method") && !parseUvUnwrapMethod(argString(a, "method"), o.method))
                     return {false, "method must be isometric, conformal, facegroups, planar, unfold or auto"};
                 o.resolution = resolutionArg(doc, a);
                 o.iterations = std::clamp(int(argNumber(a, "iterations", 10)), 0, 100);
                 o.packing = uvPackOptions(doc, a);
                 o.pack = argBool(a, "pack", o.method != UvUnwrapMethod::Unfold);
                 const bool haveSel = doc.uvSelection.valid(m) && !doc.uvSelection.empty();
                 std::vector<uint8_t> faces;
                 if (argBool(a, "selected", haveSel) && haveSel && m.hasUvs()) {
                     const UvTopology topo = buildUvTopology(m);
                     faces.assign(m.triangleCount(), 0);
                     const std::vector<uint32_t> corners = uvSelectedCorners(m, topo, doc.uvSelection);
                     if (doc.uvSelection.mode == UvSelectMode::Face || doc.uvSelection.mode == UvSelectMode::Island) {
                         faces = doc.uvSelection.faces;
                     } else {
                         for (uint32_t c : corners) faces[c / 3] = 1;
                     }
                     o.faces = &faces;
                 }
                 UvUnwrapResult r;
                 std::string err;
                 if (!uvUnwrap(m, o, r, err)) return {false, err};
                 UvEditStep edit(doc, std::string("Unwrap (") + uvUnwrapMethodLabel(o.method) + ")", argBool(a, "keep_texture", true));
                 m.uvs = std::move(r.uvs);
                 const std::string note = edit.commit();
                 std::string msg = (o.faces ? std::string() : gridNote(r.packing, o.packing)) + "Unwrapped (" + uvUnwrapMethodLabel(o.method) + "): " + plural(r.islands, "island");
                 if (r.extraCuts) msg += ", " + plural(r.extraCuts, "edge") + " cut automatically to flatten closed pieces";
                 if (r.packing.tilesUsed > 1) msg += ", " + std::to_string(r.packing.tilesUsed) + " UDIM tiles";
                 const UvStretchStats st = uvStretchStats(m);
                 msg += "; stretch " + fmt("%.3f", double(st.mean));
                 return {true, msg + note};
             }});

    reg.add({"uv_pack",
             "Pack the active Part's UV islands (the selected ones, or all) into the 0-1 tile or across UDIM tiles: "
             "each island turned to its smallest box, scaled to one texel density (equal_density) and laid out with a "
             "margin, as large as fits. With density, keeps that texel density and uses as many tiles as it needs. "
             "One undo step; a painted texture moves with the islands (keep_texture).",
             {{"margin", T::Number, "Texels between islands (default 8)", false},
              {"resolution", T::Number, "Texture size the margin and density are measured in (default: the texture's, or 2048)", false},
              {"rotate", T::Bool, "Turn islands to fit better (default true)", false},
              {"tiles", T::Number, "UDIM tiles to fill, 1001 onwards, ten per row (default 1)", false},
              {"columns", T::Number, "Fill a grid this many tiles wide (1-10): 1001 + column + 10 x row, never past it; "
                                     "with density, the spill stays in it too", false},
              {"rows", T::Number, "Rows of the grid (1-10): fills columns x rows tiles (e.g. columns=10 rows=2: 1001-1020)", false},
              {"first_tile", T::Number, "The UDIM tile to start at (default 1001)", false},
              {"equal_density", T::Bool, "Scale islands to one texel density first (default true; false keeps their sizes relative)", false},
              {"density", T::Number, "Keep exactly this texel density (texels per unit) and spill into more tiles", false},
              {"keep_texture", T::Bool, "Move a painted texture with the islands (default true)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 const UvTopology topo = buildUvTopology(m);
                 const std::vector<uint8_t> islands = targetIslands(doc, topo);
                 UvEditStep edit(doc, "Pack UVs", argBool(a, "keep_texture", true));
                 UvPackResult r;
                 std::string err;
                 const UvPackOptions po = uvPackOptions(doc, a);
                 if (!uvPack(m, topo, islands, po, r, err)) return {false, err};
                 const std::string note = edit.commit();
                 return {true, uvPackNote(r, po) + note};
             }});

    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), facegroups (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, facegroups, islands, angle or clear_all", true},
              {"from", T::Number, "path: the vertex to start at", false},
              {"to", T::Number, "path: the vertex to end at", false},
              {"clear", T::Bool, "path: clear the seams along it instead of marking them", false},
              {"angle", T::Number, "angle: the dihedral angle in degrees above which edges become seams (default 60)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (m.triangleCount() == 0) return {false, "There is no mesh"};
                 const std::string op = argString(a, "op");
                 const size_t before = uvSeamCount(m);
                 UvEditStep edit(doc, "UV Seams", false);
                 const std::vector<uint32_t> twin = cornerTwins(m);
                 if (op == "mark" || op == "clear") {
                     const UvSelection& sel = doc.uvSelection;
                     if (!sel.valid(m) || sel.empty()) return {false, "Select edges or faces in the UV Editor first"};
                     std::vector<uint32_t> corners;
                     if (sel.mode == UvSelectMode::Edge) {
                         for (uint32_t c = 0; c < sel.corners.size(); ++c)
                             if (sel.corners[c]) corners.push_back(c);
                     } else if (sel.mode == UvSelectMode::Vertex) {
                         for (uint32_t c = 0; c < sel.corners.size(); ++c)
                             if (sel.corners[c] && sel.corners[cornerNext(c)]) corners.push_back(c);
                     } else {
                         corners = uvFaceSetBorder(m, twin, sel.faces);
                     }
                     uvSetSeams(m, twin, corners, op == "mark");
                 } else if (op == "path") {
                     const double from = argNumber(a, "from", -1), to = argNumber(a, "to", -1);
                     if (from < 0 || to < 0 || from >= double(m.vertexCount()) || to >= double(m.vertexCount()))
                         return {false, "Give the path's `from` and `to` vertices (0-" + std::to_string(m.vertexCount() - 1) + ")"};
                     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 == "facegroups" || op == "face_groups") {
                     uvSeamsFromFaceGroups(m, twin);
                 } else if (op == "islands") {
                     if (!m.hasUvs()) return {false, kNoUvs};
                     uvSeamsFromIslands(m, buildUvTopology(m, twin));
                 } else if (op == "angle") {
                     uvSeamsFromAngle(m, twin, float(argNumber(a, "angle", 60.0)));
                 } else if (op == "clear_all") {
                     uvClearSeams(m);
                 } else {
                     return {false, "op must be mark, clear, path, facegroups, islands, angle or clear_all"};
                 }
                 edit.commit();
                 const size_t after = uvSeamCount(m);
                 return {true, plural(after, "seam edge") + " (" + (after >= before ? "+" : "-") +
                                   std::to_string(after >= before ? after - before : before - after) + ")"};
             }});

    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`), facegroup (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, facegroup, 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, "facegroup: 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},
              {"v1", T::Number, "rect: upper v", false},
              {"add", T::Bool, "Add to the selection (default false)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 UvSelection& sel = doc.uvSelection;
                 const UvTopology topo = buildUvTopology(m);
                 if (!sel.valid(m)) {
                     const UvSelectMode mode = sel.mode;
                     sel.clear();
                     sel.mode = mode;
                 }
                 if (a.contains("mode")) {
                     UvSelectMode mode;
                     if (!parseUvSelectMode(argString(a, "mode"), mode)) return {false, "mode must be vertex, edge, face or island"};
                     uvConvertSelection(m, topo, sel, mode);
                 }
                 const size_t nt = m.triangleCount();
                 const bool faceMode = sel.mode == UvSelectMode::Face || sel.mode == UvSelectMode::Island;
                 if (faceMode && sel.faces.size() != nt) sel.faces.assign(nt, 0);
                 if (!faceMode && sel.corners.size() != nt * 3) sel.corners.assign(nt * 3, 0);
                 const std::string op = argString(a, "op");
                 const bool add = argBool(a, "add", false);
                 // Faces picked by the op, converted to the mode.
                 auto pickFaces = [&](const std::vector<uint8_t>& faces) {
                     UvSelection pick;
                     pick.mode = UvSelectMode::Face;
                     pick.faces = faces;
                     uvConvertSelection(m, topo, pick, sel.mode);
                     std::vector<uint8_t>& dst = faceMode ? sel.faces : sel.corners;
                     const std::vector<uint8_t>& src = faceMode ? pick.faces : pick.corners;
                     if (!add) std::fill(dst.begin(), dst.end(), uint8_t(0));
                     for (size_t i = 0; i < src.size(); ++i) dst[i] = dst[i] || src[i];
                 };
                 std::vector<uint8_t>& flags = faceMode ? sel.faces : sel.corners;
                 if (op == "all") {
                     std::fill(flags.begin(), flags.end(), uint8_t(1));
                 } else if (op == "none") {
                     std::fill(flags.begin(), flags.end(), uint8_t(0));
                 } else if (op == "invert") {
                     for (uint8_t& f : flags) f = !f;
                 } else if (op == "island" || op == "face") {
                     const double f = argNumber(a, "face", -1);
                     if (f < 0 || f >= double(nt)) return {false, "Give `face`, a triangle index (0-" + std::to_string(nt - 1) + ")"};
                     std::vector<uint8_t> faces(nt, 0);
                     if (op == "island") {
                         const uint32_t isl = topo.island[uint32_t(f)];
                         for (uint32_t k = topo.islandOffsets[isl]; k < topo.islandOffsets[isl + 1]; ++k) faces[topo.islandTriangles[k]] = 1;
                     } else {
                         faces[uint32_t(f)] = 1;
                     }
                     pickFaces(faces);
                 } else if (op == "facegroup") {
                     const uint32_t g = uint32_t(std::max(argNumber(a, "group", 0), 0.0));
                     std::vector<uint8_t> faces(nt, 0);
                     for (uint32_t t = 0; t < nt; ++t) faces[t] = m.facegroupAt(t) == g;
                     pickFaces(faces);
                 } else if (op == "rect") {
                     const glm::vec2 p0(float(argNumber(a, "u0", 0)), float(argNumber(a, "v0", 0)));
                     const glm::vec2 p1(float(argNumber(a, "u1", 1)), float(argNumber(a, "v1", 1)));
                     std::vector<uint32_t> list;
                     uvFacesInRect(m, glm::min(p0, p1), glm::max(p0, p1), true, list);
                     std::vector<uint8_t> faces(nt, 0);
                     for (uint32_t t : list) faces[t] = 1;
                     pickFaces(faces);
                 } else if (op == "seams") {
                     uvConvertSelection(m, topo, sel, UvSelectMode::Edge);
                     sel.corners.assign(nt * 3, 0);
                     if (m.uvFlags.size() == nt * 3)
                         for (uint32_t c = 0; c < nt * 3; ++c) sel.corners[c] = (m.uvFlags[c] & kUvSeam) != 0;
                 } else if (op != "mode") {
                     return {false, "op must be all, none, invert, island, face, facegroup, rect, seams or mode"};
                 }
                 if (sel.mode == UvSelectMode::Island) uvConvertSelection(m, topo, sel, UvSelectMode::Island);
                 const size_t n = sel.count();
                 const char* what = sel.mode == UvSelectMode::Vertex ? "corner" : sel.mode == UvSelectMode::Edge ? "edge" : "face";
                 const std::vector<uint8_t> touched = uvSelectedIslands(m, topo, sel, false);
                 const size_t islands = size_t(std::count(touched.begin(), touched.end(), uint8_t(1)));
                 return {true, std::string("UV selection (") + uvSelectModeId(sel.mode) + "s): " + plural(n, what) + " in " +
                                   plural(islands, "island")};
             }});

    reg.add({"uv_transform",
             "Move, rotate and scale the UV Editor's selection (or every UV of the active Part when nothing is "
             "selected) about its centre. One undo step; a painted texture follows the surface (keep_texture).",
             {{"move_u", T::Number, "Offset in u", false},
              {"move_v", T::Number, "Offset in v", false},
              {"rotate", T::Number, "Degrees, counter-clockwise", false},
              {"scale", T::Number, "Uniform scale (default 1)", false},
              {"scale_u", T::Number, "Scale in u (times scale)", false},
              {"scale_v", T::Number, "Scale in v (times scale)", false},
              {"keep_texture", T::Bool, "Move a painted texture with the UVs, so the model looks the same (default true)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 const UvTopology topo = buildUvTopology(m);
                 const std::vector<uint32_t> corners = targetCorners(doc, topo);
                 const float s = float(argNumber(a, "scale", 1.0));
                 const float su = s * float(argNumber(a, "scale_u", 1.0)), sv = s * float(argNumber(a, "scale_v", 1.0));
                 const float ang = glm::radians(float(argNumber(a, "rotate", 0.0)));
                 const glm::mat2 rot(std::cos(ang), std::sin(ang), -std::sin(ang), std::cos(ang));
                 const glm::mat2 mat = rot * glm::mat2(su, 0.0f, 0.0f, sv);
                 UvEditStep edit(doc, "Transform UVs", argBool(a, "keep_texture", true));
                 uvTransform(m.uvs, corners, mat, uvCenter(m.uvs, corners),
                             glm::vec2(float(argNumber(a, "move_u", 0.0)), float(argNumber(a, "move_v", 0.0))));
                 const std::string note = edit.commit();
                 return {true, "Transformed " + plural(corners.size(), "UV corner") + note};
             }});

    reg.add({"uv_edit",
             "UV Editor operations on its selection (the whole Part when nothing is selected, where that makes sense). "
             "op: pin / unpin (selected corners keep their UVs on Unfold), clear_pins, weld (selected vertices, or the "
             "edges between them, become one UV each, removing the seam), split (the selected edges, or the border of "
             "the selected faces, become seams), straighten (selected vertices line up horizontally or vertically), "
             "flip_u / flip_v (mirror the selected islands). One undo step.",
             {{"op", T::String, "pin, unpin, clear_pins, weld, split, straighten, flip_u or flip_v", true},
              {"keep_texture", T::Bool, "Move a painted texture with the UVs (default true)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 const std::string op = argString(a, "op");
                 const UvTopology topo = buildUvTopology(m);
                 const bool haveSel = doc.uvSelection.valid(m) && !doc.uvSelection.empty();
                 const std::vector<uint32_t> corners = targetCorners(doc, topo);
                 UvEditStep edit(doc, "UV " + op, argBool(a, "keep_texture", true));
                 std::string msg;
                 if (op == "pin" || op == "unpin") {
                     if (!haveSel) return {false, "Select the UVs to " + op + " first"};
                     uvSetPins(m, corners, op == "pin");
                     msg = (op == "pin" ? "Pinned " : "Unpinned ") + plural(corners.size(), "corner");
                 } else if (op == "clear_pins") {
                     std::vector<uint32_t> all(m.uvs.size());
                     for (uint32_t c = 0; c < all.size(); ++c) all[c] = c;
                     uvSetPins(m, all, false);
                     msg = "Cleared every pin";
                 } else if (op == "weld") {
                     if (!haveSel) return {false, "Select the vertices or edges to weld first"};
                     msg = "Welded " + plural(uvWeld(m, topo, corners), "vertex");
                 } else if (op == "split") {
                     if (!haveSel) return {false, "Select the edges or faces to split off first"};
                     msg = "Split along " + plural(uvSplit(m, topo, doc.uvSelection), "edge");
                 } else if (op == "straighten") {
                     if (!haveSel) return {false, "Select the vertices to straighten first (an edge loop)"};
                     msg = "Straightened " + plural(uvStraighten(m, topo, corners), "UV vertex");
                 } else if (op == "flip_u" || op == "flip_v") {
                     uvFlipIslands(m, topo, targetIslands(doc, topo), op == "flip_u");
                     msg = op == "flip_u" ? "Flipped horizontally" : "Flipped vertically";
                 } else {
                     return {false, "op must be pin, unpin, clear_pins, weld, split, straighten, flip_u or flip_v"};
                 }
                 return {true, msg + edit.commit()};
             }});

    reg.add({"uv_density",
             "Texel density of the active Part's UV islands (the selected ones, or all), in texels per unit at the "
             "texture's resolution. op: set (scale them to `value`), match (scale them all to their mean, or to the "
             "first selected island's with match=first), info. One undo step.",
             {{"op", T::String, "set, match or info", true},
              {"value", T::Number, "set: texels per unit", false},
              {"match", T::String, "match: mean (default) or first", false},
              {"resolution", T::Number, "Texture size (default: the texture's, or 2048)", false},
              {"keep_texture", T::Bool, "Move a painted texture with the UVs (default true)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 const int res = resolutionArg(doc, a);
                 const UvTopology topo = buildUvTopology(m);
                 const std::vector<uint8_t> islands = targetIslands(doc, topo);
                 const std::vector<float> d = uvIslandDensity(m, topo, res);
                 double sum = 0.0, area = 0.0;
                 float lo = 1e30f, hi = 0.0f;
                 int first = -1;
                 for (uint32_t i = 0; i < topo.islandCount; ++i) {
                     if (!islands[i] || d[i] <= 0.0f) continue;
                     if (first < 0) first = int(i);
                     const double w = double(topo.islandOffsets[i + 1] - topo.islandOffsets[i]);
                     sum += double(d[i]) * w, area += w;
                     lo = std::min(lo, d[i]), hi = std::max(hi, d[i]);
                 }
                 if (area <= 0.0) return {false, "The islands have no area"};
                 const float mean = float(sum / area);
                 const std::string op = argString(a, "op");
                 if (op == "info")
                     return {true, "Texel density at " + std::to_string(res) + ": " + fmt("%.1f", double(mean)) + " mean, " +
                                       fmt("%.1f", double(lo)) + " - " + fmt("%.1f", double(hi)) + " texels per unit"};
                 float target = 0.0f;
                 if (op == "set") target = float(argNumber(a, "value", 0.0));
                 else if (op == "match") target = argString(a, "match", "mean") == "first" ? d[size_t(first)] : mean;
                 else return {false, "op must be set, match or info"};
                 if (!(target > 0.0f)) return {false, "Give the texel density: value (texels per unit)"};
                 UvEditStep edit(doc, "Texel Density", argBool(a, "keep_texture", true));
                 const size_t n = uvSetDensity(m, topo, islands, target, res);
                 const std::string note = edit.commit();
                 return {true, plural(n, "island") + " at " + fmt("%.1f", double(target)) + " texels per unit" + note};
             }});

    reg.add({"uv_trim",
             "Trim sheets: lay the selected UV islands (or all) into one horizontal strip of the texture. Each island "
             "is turned lengthwise and scaled to the strip's height, and they line up along u from 0 (fit_width "
             "squeezes the row to 0-1; otherwise it keeps its proportions and may run past 1, as trim textures repeat "
             "in u). The texture stays put (keep_texture is off by default: the islands pick up the strip's look).",
             {{"strip", T::Number, "Which strip, 1 = the top one (default 1)", false},
              {"strips", T::String, "The sheet: a count (4, the default), heights from the top (0.5,0.25,0.25), or v ranges (0-0.5;0.5-1)", false},
              {"fit_width", T::Bool, "Fit the row to u 0-1 exactly (default false)", false},
              {"margin", T::Number, "Texels kept free above and below inside the strip (default 4)", false},
              {"resolution", T::Number, "Texture size the margin is measured in", false},
              {"keep_texture", T::Bool, "Move a painted texture with the islands (default false)", false}},
             [](Document& doc, const Args& a) -> CommandResult {
                 Mesh& m = doc.mesh;
                 if (!m.hasUvs()) return {false, kNoUvs};
                 std::vector<TrimStrip> strips;
                 std::string err;
                 const std::string spec = a.contains("strips") ? argString(a, "strips", "") : "4";
                 if (!parseTrimStrips(spec.empty() ? std::to_string(int(argNumber(a, "strips", 4))) : spec, strips, err))
                     return {false, err};
                 const int k = int(argNumber(a, "strip", 1));
                 if (k < 1 || k > int(strips.size())) return {false, "strip must be 1-" + std::to_string(strips.size())};
                 const UvTopology topo = buildUvTopology(m);
                 const std::vector<uint8_t> islands = targetIslands(doc, topo);
                 const float margin = float(std::max(argNumber(a, "margin", 4.0), 0.0)) / float(resolutionArg(doc, a));
                 UvEditStep edit(doc, "Trim Sheet", argBool(a, "keep_texture", false));
                 const size_t n = uvTrimIslands(m, topo, islands, strips[size_t(k - 1)], argBool(a, "fit_width", false), margin);
                 if (!n) return {false, "Nothing to lay into the strip (it may be too thin for the margin)"};
                 const std::string note = edit.commit();
                 const TrimStrip& s = strips[size_t(k - 1)];
                 return {true, plural(n, "island") + " in " + s.name + " (v " + fmt("%.3f", double(s.v0)) + " - " +
                                   fmt("%.3f", double(s.v1)) + ")" + note};
             }});

    reg.add({"uv_info",
             "Describe the active Part's UVs: islands, seams, pins, texel density, the UDIM tiles used, stretch.",
             {{"resolution", T::Number, "Texture size for the texel density (default: the texture's, or 2048)", false}},
             [](Document& doc, const Args& a) -> CommandResult { return {true, uvInfoText(doc.mesh, resolutionArg(doc, a))}; }});
}

} // namespace sf