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.

Facial shapes UI: Tool > Facial Shapes (Generate, landmarks, Face test presets and sliders, takes), new_head, UI test on the template head and a CC0 marble bust, 52-shape grid renders

islandmede7c453acc5fa
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 84e17efc..3d919c76 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -191,6 +191,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/Selection.cpp
src/app/PanelBrushes.cpp
src/app/PanelVdm.cpp
+ src/app/PanelFace.cpp
src/app/PanelBrushLibrary.cpp
src/app/PanelBrushGallery.cpp
src/app/PanelPolypaint.cpp
diff --git a/docs/guide/images/face-landmarks.jpg b/docs/guide/images/face-landmarks.jpg
new file mode 100644
index 00000000..bf222fb7
Binary files /dev/null and b/docs/guide/images/face-landmarks.jpg differ
diff --git a/docs/guide/images/face-shapes-bust.jpg b/docs/guide/images/face-shapes-bust.jpg
new file mode 100644
index 00000000..10997013
Binary files /dev/null and b/docs/guide/images/face-shapes-bust.jpg differ
diff --git a/docs/guide/images/face-shapes-head.jpg b/docs/guide/images/face-shapes-head.jpg
new file mode 100644
index 00000000..5cd2a2d1
Binary files /dev/null and b/docs/guide/images/face-shapes-head.jpg differ
diff --git a/docs/guide/images/facial-shapes-panel.jpg b/docs/guide/images/facial-shapes-panel.jpg
new file mode 100644
index 00000000..90d5abb7
Binary files /dev/null and b/docs/guide/images/facial-shapes-panel.jpg differ
diff --git a/sf_ui_face.glb b/sf_ui_face.glb
new file mode 100644
index 00000000..e52e99f9
Binary files /dev/null and b/sf_ui_face.glb differ
diff --git a/src/app/App.cpp b/src/app/App.cpp
index c9ee75b9..bd159c8b 100644
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@ -689,6 +689,7 @@ void App::onMouseDown(float x, float y, Uint8 button) {
if (maskSelectMouseDown(x, y, mod)) return;
if (gizmoMouseDown(x, y, mod)) return; // Gizmo 3D handles, pivot clicks (Gizmo.cpp)
if (guideMouseDown(x, y, mod)) return; // the QRemesh Guides brush (PanelRetopo.cpp)
+ if (faceMouseDown(x, y, mod)) return; // placing facial landmarks (PanelFace.cpp)
// Alt+click on another SubTool selects it (ZBrush); Alt+drag stays an inverted stroke or a pan.
// Shift+Alt+click selects and frames it (ZBrush), the active one too.
const bool frameClick = (mod & SDL_KMOD_ALT) && (mod & SDL_KMOD_SHIFT) && !ctrlDown(mod);
@@ -1058,14 +1059,15 @@ void App::runCommand(const std::string& name, const Args& args) {
if (r.ok && name != "export_glb" && name != "export_lods" && name != "export_usd" && name != "export_fbx" &&
name != "export_unreal" && name.rfind("unreal_", 0) != 0 && name != "save_obj" && name != "save_project" &&
name != "mesh_info" && name.rfind("brush_", 0) != 0 && name.rfind("splat_", 0) != 0 && name != "mesh_to_splats" &&
- name != "set_color" && name != "set_material" && name != "export_ply") {
+ name != "set_color" && name != "set_material" && name != "export_ply" && name != "face_weights" &&
+ name != "face_preset" && name.rfind("face_take", 0) != 0 && name != "face_landmarks_detect") {
clearLods();
playingLayer_ = -1;
}
if (r.ok && name == "save_obj" && !doc_.mesh.layers.empty())
status_ += " (OBJ stores the current blend; export GLB to keep layers as blend shapes)";
if (!r.ok) SDL_Log("%s failed: %s", name.c_str(), r.message.c_str());
- if (r.ok && (name == "new_sphere" || name == "new_plane" || name == "open_obj" || name == "open" ||
+ if (r.ok && (name == "new_sphere" || name == "new_plane" || name == "new_head" || name == "open_obj" || name == "open" ||
name == "image_relief" || name == "image_inflate" || name == "splat_to_mesh" ||
(name == "splat_transform" && args.contains("fit"))))
camera_.frame(sceneBounds());
@@ -1076,7 +1078,8 @@ void App::runCommand(const std::string& name, const Args& args) {
afterVdmCommand(name, r); // the VDM brush after vdm_set / vdm_capture, the top view after vdm_new_plane
watchActiveBrush();
updateTitle();
- consoleEcho(name, args, r); // the console shows every command as a script line
+ // The console shows every command as a script line (but not a live face feed, 30 times a second).
+ if (name != "face_weights" || !r.ok) consoleEcho(name, args, r);
}
namespace {
@@ -1245,6 +1248,7 @@ void App::setLayerWeight(int index, float weight) {
}
void App::animateLayers(float dt) {
+ animateFaceTake(dt); // (PanelFace.cpp)
if (playingLayer_ < 0 || playingLayer_ >= int(doc_.mesh.layers.size())) {
playingLayer_ = -1;
return;
@@ -1306,6 +1310,7 @@ void App::drawUi() {
const ImVec2 mouse(mouseX_, mouseY_);
drawGizmo(); // Gizmo 3D handles and panel (Gizmo.cpp)
drawQRemeshGuides(); // QRemesh Guides curves (PanelRetopo.cpp)
+ drawFaceOverlay(); // facial landmarks (PanelFace.cpp)
// In Gizmo mode (and with the QRemesh Guides brush) the brush ring shows only while Ctrl masks or Shift smooths.
const bool ringOff = gizmoActive() || (guidesMode_ && !(inputMods() & SDL_KMOD_SHIFT));
if (((!ImGui::GetIO().WantCaptureMouse && canvasRect().contains(mouse.x, mouse.y)) || drag_ == Drag::Stroke) &&
diff --git a/src/app/App.h b/src/app/App.h
index b61b7661..cfa5e2ae 100644
--- a/src/app/App.h
+++ b/src/app/App.h
@@ -19,6 +19,7 @@
#include "core/Commands.h"
#include "core/Image.h"
#include "core/Document.h"
+#include "core/Face.h"
#include "core/MeshTransform.h"
#include "core/AutoUv.h"
#include "core/QRemesh.h"
@@ -369,6 +370,28 @@ private:
void registerVdmActions();
void pollVdm(); // every frame: file dialog results, and the stroke follows the brush
void afterVdmCommand(const std::string& name, const CommandResult& r);
+ // Facial shapes (PanelFace.cpp, core/Face.h): Tool > Facial Shapes (Generate, landmarks clicked on the canvas,
+ // the Face test, takes played with the frame clock).
+ void drawFaceContents();
+ void registerFaceUiActions();
+ void generateFaceShapesUi();
+ bool hasFaceShapes() const;
+ bool faceMouseDown(float x, float y, SDL_Keymod mod);
+ void drawFaceOverlay();
+ void animateFaceTake(float dt); // every frame (from animateLayers): file dialog results, take playback
+ static void SDLCALL onFaceTakeChosen(void* userdata, const char* const* files, int filter);
+ FaceLandmarks faceLandmarks_;
+ bool facePlacing_ = false;
+ int facePlaceIndex_ = 0;
+ int faceSymmetry_ = 0; // 0 Auto, 1 On, 2 Off
+ bool faceSubtools_ = true;
+ float facePresetAmount_ = 1.0f;
+ MorphAnimation faceTake_;
+ std::string faceTakePath_;
+ bool faceTakePlaying_ = false, faceTakeLoop_ = true;
+ float faceTakeTime_ = 0.0f;
+ std::mutex faceTakeMutex_;
+ std::string pendingFaceTake_; // set by the file dialog thread
static void SDLCALL onVdmChosen(void* userdata, const char* const* files, int filter);
static void SDLCALL onVdmExportChosen(void* userdata, const char* const* files, int filter);
friend void drawVdmGrid(App&, GridMode);
diff --git a/src/app/Config.cpp b/src/app/Config.cpp
index cfe48b64..61d7f8e7 100644
--- a/src/app/Config.cpp
+++ b/src/app/Config.cpp
@@ -366,6 +366,7 @@ void App::initActions() {
registerBakeUiActions(); // Tool > Bake (PanelBake.cpp)
registerRetopoUiActions(); // Geometry > QRemesh, SubTool > ProjectAll (PanelRetopo.cpp)
registerVdmActions(); // Brush > Vector Displacement (PanelVdm.cpp)
+ registerFaceUiActions(); // Tool > Facial Shapes, face_take_play / face_take_stop (PanelFace.cpp)
registerPerformanceUiActions(); // Preferences > Performance (PanelPerformance.cpp)
registerInputActions(); // ZBrush keys: U I O, Space, L, V, Ctrl+A / I / H / W..., the input style (Input.cpp)
diff --git a/src/app/Palettes.cpp b/src/app/Palettes.cpp
index 6b5baf47..dce8195d 100644
--- a/src/app/Palettes.cpp
+++ b/src/app/Palettes.cpp
@@ -380,6 +380,11 @@ void App::drawPalette_Tool() {
drawLayersContents();
Demo::popScope();
}
+ if (subpalette("tool.face", "Facial Shapes")) {
+ Demo::pushScope("Facial Shapes");
+ drawFaceContents(); // PanelFace.cpp
+ Demo::popScope();
+ }
if (subpalette("tool.paint_layers", "Paint Layers")) {
Demo::pushScope("Paint Layers");
drawPaintLayersContents();
diff --git a/src/app/PanelFace.cpp b/src/app/PanelFace.cpp
new file mode 100644
index 00000000..afc99700
--- /dev/null
+++ b/src/app/PanelFace.cpp
@@ -0,0 +1,376 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Tool > Facial Shapes (core/Face.h): Generate Facial Shapes (the 52 ARKit blend shapes), landmarks clicked on the
+// canvas to guide the fit, the Face test (expression presets and a slider per shape), and recorded takes (play,
+// bake for export).
+#include "app/App.h"
+#include "app/Demo.h"
+#include "app/Ui.h"
+#include "core/Face.h"
+
+#include <IconsLucide.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <filesystem>
+
+namespace sf {
+
+namespace {
+
+constexpr const char* kFacePath = "Tool > Facial Shapes";
+const SDL_DialogFileFilter kTakeFilters[] = {{"Face takes (JSON)", "json;jsonl"}, {"All files", "*"}};
+
+void dimText(const char* text) {
+ ImGui::PushStyleColor(ImGuiCol_Text, ImGui::GetStyleColorVec4(ImGuiCol_TextDisabled));
+ ImGui::TextWrapped("%s", text);
+ ImGui::PopStyleColor();
+}
+
+bool ctrlHeld(SDL_Keymod mod) { return (mod & (SDL_KMOD_CTRL | SDL_KMOD_GUI)) != 0; }
+
+void runAction(const ActionRegistry& actions, const char* id) {
+ if (const Action* a = actions.find(id); a && a->run && (!a->enabled || a->enabled())) a->run();
+}
+
+void actionButton(App& app, const char* id, float width = -1.0f) {
+ ui::ActionButton(app, id, ImVec2(width < 0.0f ? ImGui::GetContentRegionAvail().x : width, 0));
+}
+
+// The shapes grouped for the sliders.
+struct ShapeGroup {
+ const char* title;
+ std::vector<const char*> prefixes;
+};
+const ShapeGroup kGroups[] = {{"Eyes", {"eye"}}, {"Brows", {"brow"}}, {"Jaw", {"jaw"}},
+ {"Mouth", {"mouth"}}, {"Cheeks & nose", {"cheek", "nose"}}, {"Tongue", {"tongue"}}};
+
+} // namespace
+
+void SDLCALL App::onFaceTakeChosen(void* userdata, const char* const* files, int) {
+ if (!files || !files[0]) return;
+ auto* app = static_cast<App*>(userdata);
+ std::lock_guard lock(app->faceTakeMutex_);
+ app->pendingFaceTake_ = files[0];
+}
+
+bool App::hasFaceShapes() const {
+ for (const auto& l : doc_.mesh.layers)
+ if (arkitBlendShapeIndex(l.name) >= 0) return true;
+ return false;
+}
+
+void App::registerFaceUiActions() {
+ auto add = [this](const char* id, const char* label, const char* icon, std::function<void()> run,
+ std::function<bool()> enabled, const char* description, const char* command) {
+ Action a;
+ a.id = id;
+ a.label = label;
+ a.icon = icon;
+ a.palette = kFacePath;
+ a.run = std::move(run);
+ a.enabled = std::move(enabled);
+ a.description = description;
+ a.command = command;
+ actions_.add(std::move(a));
+ };
+ add("face.generate", "Generate Facial Shapes", ICON_LC_SMILE, [this] { generateFaceShapesUi(); },
+ [this] { return doc_.mesh.triangleCount() > 0; },
+ "Give the active SubTool (a humanoid head, looking down +Z in the front view) the 52 Apple ARKit blend shapes "
+ "as sculpt layers: eyeBlinkLeft, jawOpen, mouthSmileRight and the rest, fitted to this head's proportions. "
+ "Then fix any of them by sculpting into its layer (Tool > Layers), test them with the presets below, export "
+ "them as morph targets (GLB, USD, FBX, Blender) or drive them live from your phone. The landmarks you placed "
+ "(at least 3) guide the fit; otherwise it finds the face by itself. Eyes, teeth and tongue SubTools (by name) "
+ "and SubTools on the face get the shapes they need. Running it again replaces the 52 layers (undo brings back "
+ "the old ones and the fixes sculpted into them).",
+ "face_shapes_generate");
+ add("face.landmarks", "Place Landmarks", ICON_LC_CROSSHAIR,
+ [this] {
+ facePlacing_ = !facePlacing_;
+ if (facePlacing_) {
+ facePlaceIndex_ = 0;
+ while (facePlaceIndex_ < kFaceLandmarkCount && faceLandmarks_.set[size_t(facePlaceIndex_)]) ++facePlaceIndex_;
+ if (facePlaceIndex_ >= kFaceLandmarkCount) facePlaceIndex_ = 0;
+ status_ = std::string("Click the ") + faceLandmarkLabel(facePlaceIndex_) + " (the character's own side)";
+ } else {
+ status_ = std::to_string(faceLandmarks_.count()) + " landmarks placed";
+ }
+ },
+ nullptr,
+ "Guide the fit for heads it gets wrong (stylised proportions, a turned head, a bust with big shoulders): click "
+ "the eye corners, the nose tip, the mouth corners and the chin on the sculpt, in the order the canvas asks. "
+ "Right and left are the character's own (its right eye is on your left in the front view). Click a dot again "
+ "later to move it. 3 are enough to start; all 8 fit best. Auto places them all for you to check.",
+ "");
+ add("face.landmarks_auto", "Auto Landmarks", ICON_LC_SCAN_FACE,
+ [this] {
+ std::vector<glm::uvec3> tris;
+ for (uint32_t t = 0; t < doc_.mesh.triangleCount(); ++t)
+ if (!doc_.mesh.triangleHidden(t)) tris.push_back(doc_.mesh.triangles[t]);
+ FaceFit fit;
+ std::string error;
+ if (!fitFaceTemplate(doc_.mesh.basePositions(), tris, nullptr, fit, error)) {
+ status_ = "Auto landmarks: " + error;
+ return;
+ }
+ faceLandmarks_ = fit.landmarks;
+ char buf[160];
+ std::snprintf(buf, sizeof buf, "Landmarks found (%.0f%% of the template's face on the sculpt): check them, "
+ "click Place Landmarks to move any",
+ double(fit.coverage * 100.0f));
+ status_ = buf;
+ },
+ [this] { return doc_.mesh.triangleCount() > 0; },
+ "Find the landmarks automatically (the same fit Generate makes without landmarks) and show them, so you can "
+ "check where the eye and mouth corners landed and move any that are off before generating.",
+ "face_landmarks_detect");
+ add("face.landmarks_clear", "Clear Landmarks", ICON_LC_ERASER,
+ [this] {
+ faceLandmarks_ = FaceLandmarks{};
+ facePlacing_ = false;
+ status_ = "Landmarks cleared: Generate fits automatically";
+ },
+ [this] { return faceLandmarks_.count() > 0; }, "Remove the landmarks: Generate then finds the face by itself.", "");
+ add("face.take_load", "Load Take...", ICON_LC_FOLDER_OPEN,
+ [this] { SDL_ShowOpenFileDialog(onFaceTakeChosen, this, window_, kTakeFilters, 2, nullptr, false); }, nullptr,
+ "Play a recorded face take on the facial shapes: the JSON frames the phone link records ({\"type\":\"face\", "
+ "\"t\":ms, \"weights\":{...}} as an array, {\"frames\":[...]} or JSON Lines).",
+ "face_take_play");
+ add("face.take_play", "Play Take", ICON_LC_PLAY,
+ [this] {
+ faceTakePlaying_ = !faceTakePlaying_;
+ if (faceTakePlaying_ && faceTakeTime_ >= faceTake_.duration()) faceTakeTime_ = 0.0f;
+ },
+ [this] { return !faceTake_.empty(); }, "Play or pause the loaded take (it loops while Loop is on).", "");
+ add("face.take_bake", "Bake Take", ICON_LC_FILM,
+ [this] { runCommand("face_take_bake", {{"path", faceTakePath_}}); },
+ [this] { return !faceTakePath_.empty(); },
+ "Bake the loaded take into keyframes at 30 fps: Export GLB writes them as a glTF animation of the morph target "
+ "weights, Export USD as time samples (Blender, Maya, Unreal, Omniverse play them). Saved with the project.",
+ "face_take_bake");
+ add("face.take_clear", "Clear Baked Take", ICON_LC_TRASH_2, [this] { runCommand("face_take_clear"); },
+ [this] {
+ MorphAnimation a;
+ return bakedFaceAnimation(doc_, a);
+ },
+ "Remove the baked take, so exports are a still pose again.", "face_take_clear");
+
+ // Commands the app adds: playback needs the frame clock.
+ commands_.add({"face_take_play",
+ "Plays a recorded face take (JSON frames from the phone link) on the facial shapes in the viewport, "
+ "looping. Needs the app (not the CLI).",
+ {{"path", ParamSpec::Type::String, "The take file.", true},
+ {"loop", ParamSpec::Type::Bool, "Loop (default true).", false}},
+ [this](Document&, const Args& a) -> CommandResult {
+ MorphAnimation take;
+ std::string error;
+ const std::string path = argString(a, "path");
+ if (!loadFaceTake(path, take, error)) return {false, error};
+ faceTake_ = std::move(take);
+ faceTakePath_ = path;
+ faceTakeTime_ = 0.0f;
+ faceTakeLoop_ = argBool(a, "loop", true);
+ faceTakePlaying_ = true;
+ char buf[96];
+ std::snprintf(buf, sizeof buf, " (%.1f s, %zu frames)", double(faceTake_.duration()), faceTake_.times.size());
+ return {true, "Playing take '" + faceTake_.name + "'" + buf};
+ }});
+ commands_.add({"face_take_stop", "Stops the face take playing in the viewport.", {},
+ [this](Document&, const Args&) -> CommandResult {
+ faceTakePlaying_ = false;
+ return {true, "Take stopped"};
+ }});
+}
+
+void App::generateFaceShapesUi() {
+ Args args;
+ if (faceLandmarks_.count() >= 3) args["landmarks"] = faceLandmarks_.toJson().dump();
+ args["symmetry"] = std::string(faceSymmetry_ == 1 ? "on" : faceSymmetry_ == 2 ? "off" : "auto");
+ args["subtools"] = faceSubtools_;
+ facePlacing_ = false;
+ runCommand("face_shapes_generate", args);
+}
+
+void App::animateFaceTake(float dt) {
+ std::string pending;
+ {
+ std::lock_guard lock(faceTakeMutex_);
+ pending.swap(pendingFaceTake_);
+ }
+ if (!pending.empty()) runCommand("face_take_play", {{"path", pending}});
+ if (!faceTakePlaying_ || faceTake_.empty()) return;
+ faceTakeTime_ += dt;
+ if (faceTakeTime_ > faceTake_.duration()) {
+ if (faceTakeLoop_ && faceTake_.duration() > 0.0f) {
+ faceTakeTime_ = std::fmod(faceTakeTime_, faceTake_.duration());
+ } else {
+ faceTakeTime_ = faceTake_.duration();
+ faceTakePlaying_ = false;
+ }
+ }
+ std::vector<std::pair<std::string, float>> w;
+ sampleMorphAnimation(faceTake_, faceTakeTime_, w);
+ applyFaceWeights(doc_, w);
+}
+
+bool App::faceMouseDown(float x, float y, SDL_Keymod mod) {
+ if (!facePlacing_ || (mod & (SDL_KMOD_ALT | SDL_KMOD_SHIFT)) || ctrlHeld(mod)) return false;
+ RayHit hit;
+ if (previewLod_ >= 0 || !pick(x, y, hit)) return false; // the background navigates
+ // Clicking near a placed dot picks that one up to move it; otherwise the next one is placed.
+ const float grab = 10.0f * uiScale_;
+ for (int i = 0; i < kFaceLandmarkCount; ++i) {
+ ImVec2 sp;
+ if (faceLandmarks_.set[size_t(i)] && i != facePlaceIndex_ && gizmoProject(faceLandmarks_.position[size_t(i)], sp) &&
+ std::hypot(sp.x - x, sp.y - y) < grab) {
+ facePlaceIndex_ = i;
+ status_ = std::string("Click the new place for the ") + faceLandmarkLabel(i);
+ return true;
+ }
+ }
+ faceLandmarks_.position[size_t(facePlaceIndex_)] = hit.position;
+ faceLandmarks_.set[size_t(facePlaceIndex_)] = true;
+ int next = -1;
+ for (int k = 1; k <= kFaceLandmarkCount; ++k) {
+ const int i = (facePlaceIndex_ + k) % kFaceLandmarkCount;
+ if (!faceLandmarks_.set[size_t(i)]) {
+ next = i;
+ break;
+ }
+ }
+ if (next < 0) {
+ facePlacing_ = false;
+ status_ = "All 8 landmarks placed: Generate Facial Shapes uses them";
+ } else {
+ facePlaceIndex_ = next;
+ status_ = std::to_string(faceLandmarks_.count()) + "/8 placed. Click the " + faceLandmarkLabel(next);
+ }
+ return true;
+}
+
+void App::drawFaceOverlay() {
+ if (faceLandmarks_.count() == 0 && !facePlacing_) return;
+ ImDrawList* dl = ImGui::GetForegroundDrawList();
+ const CanvasRect cr = canvasRect();
+ dl->PushClipRect(ImVec2(cr.x, cr.y), ImVec2(cr.x + cr.w, cr.y + cr.h), true);
+ const float s = uiScale_;
+ for (int i = 0; i < kFaceLandmarkCount; ++i) {
+ if (!faceLandmarks_.set[size_t(i)]) continue;
+ ImVec2 p;
+ if (!gizmoProject(faceLandmarks_.position[size_t(i)], p)) continue;
+ const bool current = facePlacing_ && i == facePlaceIndex_;
+ dl->AddCircleFilled(p, 5.0f * s, current ? IM_COL32(255, 196, 64, 255) : IM_COL32(80, 200, 255, 255));
+ dl->AddCircle(p, 5.0f * s, IM_COL32(0, 0, 0, 200), 0, 1.5f * s);
+ char num[4];
+ std::snprintf(num, sizeof num, "%d", i + 1);
+ dl->AddText(ImVec2(p.x + 7.0f * s, p.y - 8.0f * s), IM_COL32(255, 255, 255, 230), num);
+ }
+ if (facePlacing_) {
+ char banner[160];
+ std::snprintf(banner, sizeof banner, "Landmark %d/8: click the %s (the character's own side; its right is on "
+ "your left from the front)",
+ facePlaceIndex_ + 1, faceLandmarkLabel(facePlaceIndex_));
+ const ImVec2 size = ImGui::CalcTextSize(banner);
+ const ImVec2 at(cr.x + (cr.w - size.x) * 0.5f, cr.y + 12.0f * s);
+ dl->AddRectFilled(ImVec2(at.x - 8 * s, at.y - 4 * s), ImVec2(at.x + size.x + 8 * s, at.y + size.y + 4 * s),
+ IM_COL32(20, 20, 24, 210), 4.0f * s);
+ dl->AddText(at, IM_COL32(255, 196, 64, 255), banner);
+ }
+ dl->PopClipRect();
+}
+
+void App::drawFaceContents() {
+ const float s = uiScale_;
+ dimText("The 52 Apple ARKit blend shapes for rigs and live face capture, fitted to this head.");
+ actionButton(*this, "face.generate");
+ ImGui::SetNextItemWidth(ImGui::GetContentRegionAvail().x * 0.5f);
+ const char* symmetry[] = {"Auto", "On", "Off"};
+ ImGui::Combo("Symmetry##face", &faceSymmetry_, symmetry, 3);
+ ui::HelpText("Symmetry", nullptr,
+ "Auto: Left and Right shapes are made exact mirror images when the sculpt is symmetric about X = 0. "
+ "On: always (asymmetric spots take the average). Off: each side as fitted.",
+ kFacePath);
+ ImGui::Checkbox("SubTools too##face", &faceSubtools_);
+ ui::HelpText("SubTools too", nullptr,
+ "Eyes (SubTools named Eye...) turn for the eyeLook shapes, Teeth / Tongue follow the jaw below the "
+ "bite (and tongueOut), and other SubTools on the face (brows, lashes, a beard) follow the skin.",
+ kFacePath);
+
+ // Landmarks.
+ ImGui::SeparatorText("Landmarks");
+ const float half = (ImGui::GetContentRegionAvail().x - ImGui::GetStyle().ItemSpacing.x) * 0.5f;
+ actionButton(*this, "face.landmarks", half);
+ ImGui::SameLine();
+ actionButton(*this, "face.landmarks_auto", half);
+ char placed[64];
+ std::snprintf(placed, sizeof placed, "%d/8 placed%s", faceLandmarks_.count(),
+ faceLandmarks_.count() >= 3 ? " (guiding the fit)" : faceLandmarks_.count() ? " (need 3)" : " (automatic fit)");
+ ImGui::TextDisabled("%s", placed);
+ if (faceLandmarks_.count()) {
+ ImGui::SameLine(ImGui::GetContentRegionAvail().x - 40 * s);
+ if (ImGui::SmallButton("Clear##facelm")) runAction(actions_, "face.landmarks_clear");
+ ui::HelpAction(*this, "face.landmarks_clear");
+ }
+
+ // Face test.
+ ImGui::SeparatorText("Face test");
+ const bool shapes = hasFaceShapes();
+ if (!shapes) dimText("Generate the shapes first.");
+ ImGui::BeginDisabled(!shapes);
+ const auto& presets = facePresets();
+ const float cell = (ImGui::GetContentRegionAvail().x - 3 * ImGui::GetStyle().ItemSpacing.x) / 4.0f;
+ for (size_t i = 0; i < presets.size(); ++i) {
+ if (i % 4) ImGui::SameLine();
+ if (ImGui::Button(presets[i].name, ImVec2(cell, 0)))
+ runCommand("face_preset", {{"name", std::string(presets[i].name)}, {"amount", double(facePresetAmount_)}});
+ ui::HelpText(presets[i].name, nullptr, presets[i].help, kFacePath);
+ }
+ ImGui::SetNextItemWidth(-1);
+ ImGui::SliderFloat("##faceamount", &facePresetAmount_, 0.0f, 1.0f, "preset amount %.2f");
+ ui::HelpText("Preset amount", nullptr, "How strongly the presets above are applied (click a preset again to see it).",
+ kFacePath);
+ // A slider per shape, by region.
+ for (const ShapeGroup& g : kGroups) {
+ if (!ImGui::TreeNode(g.title)) continue;
+ for (auto& l : doc_.mesh.layers) {
+ if (arkitBlendShapeIndex(l.name) < 0) continue;
+ const bool mine = std::any_of(g.prefixes.begin(), g.prefixes.end(),
+ [&](const char* p) { return l.name.rfind(p, 0) == 0; });
+ if (!mine) continue;
+ float w = l.weight;
+ ImGui::SetNextItemWidth(-1);
+ if (ImGui::SliderFloat(("##" + l.name).c_str(), &w, 0.0f, 1.0f, (l.name + " %.2f").c_str())) {
+ faceTakePlaying_ = false;
+ applyFaceWeights(doc_, {{l.name, w}});
+ }
+ ui::HelpText(l.name.c_str(), nullptr,
+ "This ARKit shape's weight (it drives the same-named layer on every SubTool). To fix the shape, "
+ "select its layer in Tool > Layers, set the weight to 1 and sculpt.",
+ kFacePath);
+ }
+ ImGui::TreePop();
+ }
+ ImGui::EndDisabled();
+
+ // Takes.
+ ImGui::SeparatorText("Take");
+ actionButton(*this, "face.take_load");
+ if (!faceTake_.empty()) {
+ ImGui::TextDisabled("%s: %.1f / %.1f s", faceTake_.name.c_str(), double(faceTakeTime_), double(faceTake_.duration()));
+ if (ImGui::Button(faceTakePlaying_ ? "Pause##facetake" : "Play##facetake", ImVec2(half, 0))) runAction(actions_, "face.take_play");
+ ui::HelpAction(*this, "face.take_play");
+ ImGui::SameLine();
+ ImGui::Checkbox("Loop##facetake", &faceTakeLoop_);
+ ui::HelpText("Loop", nullptr, "Play the take again from the start when it ends.", kFacePath);
+ actionButton(*this, "face.take_bake");
+ }
+ MorphAnimation baked;
+ if (bakedFaceAnimation(doc_, baked)) {
+ ImGui::TextDisabled("Baked: %s (%.1f s, exports with GLB / USD)", baked.name.c_str(), double(baked.duration()));
+ actionButton(*this, "face.take_clear");
+ }
+}
+
+} // namespace sf
diff --git a/src/app/UiTest.cpp b/src/app/UiTest.cpp
index d559a97d..d5adb0f5 100644
--- a/src/app/UiTest.cpp
+++ b/src/app/UiTest.cpp
@@ -26,7 +26,8 @@
// gizmo_hover HANDLE move the mouse onto a Gizmo 3D handle (it lights up, for screenshots)
// orbit DX DY right-drag on the background, in pixels (with the held modifiers)
// camera YAW PITCH set the view's angles in degrees (0 0 = the front view), e.g. for guide screenshots
-// run COMMANDS sculptforge-cli commands, e.g. run new_sphere subdivisions=4
+// zoom FACTOR / look X Y Z move the camera FACTOR times closer / turn it about (and look at) the point X Y Z
+// run COMMANDS sculptforge-cli commands, e.g. run new_sphere subdivisions=4 ($SCRIPT_DIR: the script's folder)
// drop FILE as if FILE were dropped onto the window (relative to the script's folder)
// env NAME VALUE set an environment variable; $SCRIPT_DIR is the script's folder
// copy SRC DST copy a file or folder (SRC relative to the script's folder, DST to the working
@@ -293,6 +294,15 @@ double Demo::query(const std::string& name, bool& known) const {
if (name == "lazy_mouse") return app_.strokeType_ == StrokeType::LazyMouse ? 1.0 : 0.0;
if (name == "stroke_type") return double(int(app_.strokeType_)); // 0 Dots, 1 DragRect, 2 DragDot, 3 Spray, 4 LazyMouse
if (name == "vdms") return double(app_.doc_.vdms.size());
+ // Facial shapes (PanelFace.cpp): landmarks placed, placing them, a take playing, and face_<shape>: that layer's weight.
+ if (name == "face_landmarks") return double(app_.faceLandmarks_.count());
+ if (name == "face_placing") return app_.facePlacing_ ? 1.0 : 0.0;
+ if (name == "face_take_playing") return app_.faceTakePlaying_ ? 1.0 : 0.0;
+ if (name.rfind("face_", 0) == 0) {
+ for (const auto& l : m.layers)
+ if (l.name == name.substr(5)) return double(l.weight);
+ return -1.0; // no such layer
+ }
if (name == "input_style") return double(app_.uiPrefs_.inputStyle);
if (name == "mask_shape") return double(int(app_.maskShape_)); // 0 MaskPen, 1 MaskLasso, 2 MaskRect
if (name == "hide_shape") return double(int(app_.hideShape_)); // 1 SelectLasso, 2 SelectRect
@@ -783,6 +793,14 @@ bool Demo::parseStep(int line, const std::vector<std::string>& w, std::string& e
app_.camera_.roll = 0.0f;
});
wait(0.1f);
+ } else if (verb == "zoom") { // zoom FACTOR: the camera's distance divided by FACTOR
+ if (!need(1)) return false;
+ run([this, f = num(1, 1)] { app_.camera_.distance /= std::max(float(f), 1e-3f); });
+ wait(0.1f);
+ } else if (verb == "look") { // look X Y Z: the camera turns about (and looks at) this point
+ if (!need(3)) return false;
+ run([this, x = num(1, 0), y = num(2, 0), z = num(3, 0)] { app_.camera_.target = glm::vec3(float(x), float(y), float(z)); });
+ wait(0.1f);
} else if (verb == "drop") {
if (!need(1)) return false;
auto file = std::filesystem::path(std::u8string(w[1].begin(), w[1].end()));
@@ -815,7 +833,12 @@ bool Demo::parseStep(int line, const std::vector<std::string>& w, std::string& e
} else if (verb == "run") {
if (!need(1)) return false;
std::vector<ScriptStatement> statements;
- if (!parseScript(restOf(lineText_, 1), statements, error)) return false;
+ std::string text = restOf(lineText_, 1);
+ for (size_t at = text.find("$SCRIPT_DIR"); at != std::string::npos; at = text.find("$SCRIPT_DIR", at)) {
+ text.replace(at, 11, scriptDir_);
+ at += scriptDir_.size();
+ }
+ if (!parseScript(text, statements, error)) return false;
run([this, line, statements] {
for (const auto& st : statements) {
app_.runCommand(st.command, st.args);
diff --git a/src/core/FaceCommands.cpp b/src/core/FaceCommands.cpp
index 0f2206e3..146521c0 100644
--- a/src/core/FaceCommands.cpp
+++ b/src/core/FaceCommands.cpp
@@ -3,7 +3,9 @@
#include "core/Commands.h"
#include "core/Face.h"
#include "core/Multires.h"
+#include "core/Primitives.h"
+#include <algorithm>
#include <cmath>
#include <cstdio>
@@ -28,8 +30,65 @@ std::string presetNames() {
} // namespace
+Mesh faceTemplateHeadMesh(Mesh* eyes) {
+ const FaceTemplate& t = faceTemplate();
+ Mesh m;
+ for (const auto& p : t.neutral) m.positions.push_back(p * 0.01f); // centimetres -> metres
+ m.triangles = t.triangles;
+ // The template's quads were split (a, b, c) + (a, c, d), one after the other: pair them again.
+ for (uint32_t i = 0; i + 1 < m.triangles.size(); ++i) {
+ const glm::uvec3 a = m.triangles[i], b = m.triangles[i + 1];
+ if (a.x == b.x && a.z == b.y) {
+ m.pairQuad(i, i + 1);
+ ++i;
+ }
+ }
+ // Polygroups: skin, mouth, eye sockets.
+ m.ensurePolygroups();
+ for (uint32_t i = 0; i < m.triangles.size(); ++i) {
+ const uint32_t v = std::min({m.triangles[i].x, m.triangles[i].y, m.triangles[i].z});
+ m.polygroups[i] = v < t.skinEnd ? 0u : v < t.mouthEnd ? 1u : 2u;
+ }
+ m.rebuildTopology();
+ m.recomputeAllNormals();
+ if (eyes) {
+ // An eyeball in each socket: centred on the socket's opening, its radius the socket's.
+ *eyes = Mesh();
+ for (int side = 0; side < 2; ++side) {
+ glm::vec3 lo(1e9f), hi(-1e9f);
+ for (uint32_t v = t.mouthEnd; v < t.neutral.size(); ++v)
+ if ((t.neutral[v].x > 0.0f) == (side == 1)) {
+ lo = glm::min(lo, t.neutral[v]);
+ hi = glm::max(hi, t.neutral[v]);
+ }
+ const float r = 0.5f * std::max(hi.x - lo.x, hi.y - lo.y);
+ const glm::vec3 c(0.5f * (lo.x + hi.x), 0.5f * (lo.y + hi.y), hi.z - r);
+ Mesh ball = makeIcosphere(4, r * 0.01f);
+ const uint32_t first = uint32_t(eyes->positions.size());
+ for (const auto& p : ball.positions) eyes->positions.push_back(p + c * 0.01f);
+ for (const auto& tri : ball.triangles) eyes->triangles.push_back(tri + glm::uvec3(first));
+ }
+ eyes->rebuildTopology();
+ eyes->recomputeAllNormals();
+ }
+ return m;
+}
+
void registerFaceCommands(CommandRegistry& registry) {
using T = ParamSpec::Type;
+ registry.add({"new_head",
+ "New scene with a human head to sculpt a face on (the ICT-FaceKit template head, MIT licence: face, "
+ "neck, mouth and eye sockets, about 14,000 vertices, life size in metres) and its eyes as a second "
+ "SubTool. Generate Facial Shapes fits it exactly.",
+ {},
+ [](Document& doc, const Args&) -> CommandResult {
+ Mesh eyes;
+ Mesh head = faceTemplateHeadMesh(&eyes);
+ doc.setMesh(std::move(head), "Head");
+ doc.addSubtool(std::move(eyes), "Eyes", false);
+ doc.path.clear();
+ return {true, "New head (" + std::to_string(doc.mesh.vertexCount()) + " vertices) with Eyes"};
+ }});
registry.add({"face_shapes_generate",
"Generate Facial Shapes: gives the active SubTool (a sculpted humanoid head looking down +Z, Y up) "
"the 52 Apple ARKit blend shapes (eyeBlinkLeft, jawOpen, mouthSmileRight, ...) as sculpt layers at "
diff --git a/tests/data/CREDITS.md b/tests/data/CREDITS.md
new file mode 100644
index 00000000..bee41b1e
--- /dev/null
+++ b/tests/data/CREDITS.md
@@ -0,0 +1,7 @@
+# Test data credits
+
+| File | Source | Licence |
+|---|---|---|
+| `marble-bust.glb` | "Marble Bust 01" by Rico Cilliers, [Poly Haven](https://polyhaven.com/a/marble_bust_01) (the 1k glTF's mesh only, no textures, converted to GLB by SculptForge). A real sculpted human head for the facial shapes tests (tests/ui/face_shapes.sfui, tools/face/shape_grid.py). | [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) |
+
+The other files here were made for SculptForge's tests (GPL-3.0-or-later, like the rest of the repository).
diff --git a/tests/data/marble-bust.glb b/tests/data/marble-bust.glb
new file mode 100644
index 00000000..99685616
Binary files /dev/null and b/tests/data/marble-bust.glb differ
diff --git a/tests/ui/data/face/take.json b/tests/ui/data/face/take.json
new file mode 100644
index 00000000..afd65a7a
--- /dev/null
+++ b/tests/ui/data/face/take.json
@@ -0,0 +1 @@
+[{"type": "face", "t": 1700000000000, "weights": {"jawOpen": 0.0, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.0, "mouthSmileRight": 0.0, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000033, "weights": {"jawOpen": 0.042, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.016, "mouthSmileRight": 0.016, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000067, "weights": {"jawOpen": 0.084, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.031, "mouthSmileRight": 0.031, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000100, "weights": {"jawOpen": 0.125, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.047, "mouthSmileRight": 0.047, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000133, "weights": {"jawOpen": 0.165, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.062, "mouthSmileRight": 0.062, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000167, "weights": {"jawOpen": 0.205, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.078, "mouthSmileRight": 0.078, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000200, "weights": {"jawOpen": 0.244, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.093, "mouthSmileRight": 0.093, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000233, "weights": {"jawOpen": 0.282, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.109, "mouthSmileRight": 0.109, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000267, "weights": {"jawOpen": 0.318, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.124, "mouthSmileRight": 0.124, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000300, "weights": {"jawOpen": 0.353, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.14, "mouthSmileRight": 0.14, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000333, "weights": {"jawOpen": 0.386, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.156, "mouthSmileRight": 0.156, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000367, "weights": {"jawOpen": 0.417, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.171, "mouthSmileRight": 0.171, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000400, "weights": {"jawOpen": 0.446, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.187, "mouthSmileRight": 0.187, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000433, "weights": {"jawOpen": 0.473, "eyeBlinkLeft": 1.0, "eyeBlinkRight": 1.0, "mouthSmileLeft": 0.202, "mouthSmileRight": 0.202, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000467, "weights": {"jawOpen": 0.497, "eyeBlinkLeft": 1.0, "eyeBlinkRight": 1.0, "mouthSmileLeft": 0.218, "mouthSmileRight": 0.218, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000500, "weights": {"jawOpen": 0.52, "eyeBlinkLeft": 1.0, "eyeBlinkRight": 1.0, "mouthSmileLeft": 0.233, "mouthSmileRight": 0.233, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000533, "weights": {"jawOpen": 0.539, "eyeBlinkLeft": 1.0, "eyeBlinkRight": 1.0, "mouthSmileLeft": 0.249, "mouthSmileRight": 0.249, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000567, "weights": {"jawOpen": 0.556, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.264, "mouthSmileRight": 0.264, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000600, "weights": {"jawOpen": 0.571, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.28, "mouthSmileRight": 0.28, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000633, "weights": {"jawOpen": 0.582, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.296, "mouthSmileRight": 0.296, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000667, "weights": {"jawOpen": 0.591, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.311, "mouthSmileRight": 0.311, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000700, "weights": {"jawOpen": 0.597, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.327, "mouthSmileRight": 0.327, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000733, "weights": {"jawOpen": 0.6, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.342, "mouthSmileRight": 0.342, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000767, "weights": {"jawOpen": 0.6, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.358, "mouthSmileRight": 0.358, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000800, "weights": {"jawOpen": 0.597, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.373, "mouthSmileRight": 0.373, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000833, "weights": {"jawOpen": 0.591, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.389, "mouthSmileRight": 0.389, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000867, "weights": {"jawOpen": 0.582, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.404, "mouthSmileRight": 0.404, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000900, "weights": {"jawOpen": 0.571, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.42, "mouthSmileRight": 0.42, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000933, "weights": {"jawOpen": 0.556, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.436, "mouthSmileRight": 0.436, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000000967, "weights": {"jawOpen": 0.539, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.451, "mouthSmileRight": 0.451, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001000, "weights": {"jawOpen": 0.52, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.467, "mouthSmileRight": 0.467, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001033, "weights": {"jawOpen": 0.497, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.482, "mouthSmileRight": 0.482, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001067, "weights": {"jawOpen": 0.473, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.498, "mouthSmileRight": 0.498, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001100, "weights": {"jawOpen": 0.446, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.513, "mouthSmileRight": 0.513, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001133, "weights": {"jawOpen": 0.417, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.529, "mouthSmileRight": 0.529, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001167, "weights": {"jawOpen": 0.386, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.544, "mouthSmileRight": 0.544, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001200, "weights": {"jawOpen": 0.353, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.56, "mouthSmileRight": 0.56, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001233, "weights": {"jawOpen": 0.318, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.576, "mouthSmileRight": 0.576, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001267, "weights": {"jawOpen": 0.282, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.591, "mouthSmileRight": 0.591, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001300, "weights": {"jawOpen": 0.244, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.607, "mouthSmileRight": 0.607, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001333, "weights": {"jawOpen": 0.205, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.622, "mouthSmileRight": 0.622, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001367, "weights": {"jawOpen": 0.165, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.638, "mouthSmileRight": 0.638, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001400, "weights": {"jawOpen": 0.125, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.653, "mouthSmileRight": 0.653, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001433, "weights": {"jawOpen": 0.084, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.669, "mouthSmileRight": 0.669, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001467, "weights": {"jawOpen": 0.042, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.684, "mouthSmileRight": 0.684, "_neutral": 0.1}, "head": [0, 0, 0, 1]}, {"type": "face", "t": 1700000001500, "weights": {"jawOpen": 0.0, "eyeBlinkLeft": 0.0, "eyeBlinkRight": 0.0, "mouthSmileLeft": 0.7, "mouthSmileRight": 0.7, "_neutral": 0.1}, "head": [0, 0, 0, 1]}]
\ No newline at end of file
diff --git a/tests/ui/face_shapes.sfui b/tests/ui/face_shapes.sfui
new file mode 100644
index 00000000..fe73fefa
--- /dev/null
+++ b/tests/ui/face_shapes.sfui
@@ -0,0 +1,107 @@
+# Facial shapes (Tool > Facial Shapes): Generate Facial Shapes on the template head and on a real marble bust (Poly
+# Haven, CC0), the Face test presets and sliders, landmarks clicked on the canvas, Ctrl help, a take that plays and
+# bakes, and face_weights from the console (the phone link's command).
+run new_head
+expect_value layers == 0
+camera 0 0
+key f
+wait 0.5
+look 0 0.02 0.08
+zoom 1.6
+click "Facial Shapes##tool.face"
+expect_text "Generate the shapes first"
+hold ctrl
+hover "Facial Shapes/Generate Facial Shapes"
+expect_help "52 Apple ARKit blend shapes"
+hold none
+click "Facial Shapes/Generate Facial Shapes"
+expect_status "Generated 52 facial shapes on Head"
+expect_status "Left/Right mirrored"
+expect_status "Eyes: eye rotations"
+expect_value layers == 52
+expect_value face_jawOpen == 0
+shot head-neutral
+click "Facial Shapes/Smile"
+expect_value face_mouthSmileLeft == 0.8
+shot head-smile
+click "Facial Shapes/Surprise"
+expect_value face_mouthSmileLeft == 0
+expect_value face_jawOpen == 0.45
+shot head-surprise
+click "Facial Shapes/Blink"
+shot head-blink
+click "Facial Shapes/Kiss"
+shot head-kiss
+click "Facial Shapes/Look left"
+shot head-look-left
+click "Facial Shapes/Neutral"
+expect_value face_eyeLookOutLeft == 0
+# A slider per shape, by region.
+click "Facial Shapes/Jaw"
+drag_item "Facial Shapes/##jawOpen" 400 0
+expect_value face_jawOpen == 1
+shot head-jaw-slider
+drag_item "Facial Shapes/##jawOpen" -400 0
+expect_value face_jawOpen == 0
+# The phone link's command, from the console: no undo step.
+run face_weights json={"mouthSmileLeft":1,"eyeBlinkRight":1}
+expect_value face_mouthSmileLeft == 1
+expect_value face_eyeBlinkRight == 1
+shot head-wink-console
+run face_preset name=Neutral
+
+# A take recorded by the phone link plays, and bakes for export.
+run face_take_play path=$SCRIPT_DIR/data/face/take.json
+expect_status "Playing take 'take'"
+expect_value face_take_playing == 1
+wait 0.75
+expect_value face_jawOpen > 0.3
+shot head-take
+run face_take_stop
+click "Facial Shapes/Bake Take"
+expect_status "Baked take 'take'"
+expect_text "Baked: take"
+run export_glb path=sf_ui_face.glb
+expect_status "with the take 'take'"
+click "Facial Shapes/Clear Baked Take"
+expect_no_text "Baked: take"
+
+# A real head: the marble bust (different topology, a little turned, closed mouth, blank eyes).
+run open path=$SCRIPT_DIR/../data/marble-bust.glb
+expect_value layers == 0
+camera 0 0
+key f
+wait 0.5
+look -0.03 0.36 0.1
+zoom 2.5
+click "Facial Shapes/Auto Landmarks"
+expect_status "Landmarks found"
+expect_value face_landmarks == 8
+shot bust-landmarks
+# Place one by hand: the canvas asks for each in turn.
+click "Facial Shapes/Clear"
+expect_value face_landmarks == 0
+click "Facial Shapes/Place Landmarks"
+expect_value face_placing == 1
+expect_status "Click the Right eye, outer corner"
+stroke 0.32 0.42 0.32 0.42 0.05
+expect_value face_landmarks == 1
+expect_status "1/8 placed. Click the Right eye, inner corner"
+shot bust-placing
+click "Facial Shapes/Place Landmarks"
+expect_value face_placing == 0
+click "Facial Shapes/Clear"
+click "Facial Shapes/Generate Facial Shapes"
+expect_status "Generated 52 facial shapes on marble-bust"
+expect_value layers == 52
+shot bust-neutral
+click "Facial Shapes/Grin"
+shot bust-grin
+click "Facial Shapes/Anger"
+shot bust-anger
+click "Facial Shapes/Blink"
+shot bust-blink
+click "Facial Shapes/Aah"
+shot bust-aah
+key ctrl+z
+expect_value layers == 0
diff --git a/tools/face/shape_grid.py b/tools/face/shape_grid.py
new file mode 100644
index 00000000..b863ff8a
--- /dev/null
+++ b/tools/face/shape_grid.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Renders every ARKit facial shape Generate Facial Shapes makes, one tile per shape, into a labelled grid
+(docs/guide/images/face-shapes-<head>.jpg, 1400 pixels wide), to look at them all at once.
+
+ python3 tools/face/shape_grid.py --app build/sculptforge --out docs/guide/images [--heads head,bust]
+
+Heads: `head` is the template head (new_head), `bust` the CC0 marble bust in tests/data. Needs ImageMagick
+(`magick`). It writes a UI test script per head into a temporary folder, runs the app on it and crops and labels
+the screenshots.
+"""
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, os.path.join(ROOT, "tools", "face"))
+from build_ict_template import ARKIT # noqa: E402
+
+HEADS = {
+ # name: (commands that load it, camera look-at point, zoom, crop WxH+X+Y of the 1600x960 shot)
+ "head": ("run new_head", "0 0.0 0.08", "2.8", "600x700+400+150"),
+ "bust": ("run open path=%s" % os.path.join(ROOT, "tests", "data", "marble-bust.glb"), "-0.03 0.335 0.1", "2.8",
+ "600x700+400+150"),
+}
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--app", default=os.path.join(ROOT, "build", "sculptforge"))
+ ap.add_argument("--out", default=os.path.join(ROOT, "docs", "guide", "images"))
+ ap.add_argument("--heads", default="head,bust")
+ ap.add_argument("--tile", type=int, default=220)
+ a = ap.parse_args()
+ work = tempfile.mkdtemp(prefix="sf_face_grid_")
+ for head in a.heads.split(","):
+ load, look, zoom, crop = HEADS[head]
+ lines = [load, "camera 0 0", "key f", "wait 0.5", "look " + look, "zoom " + zoom,
+ "run face_shapes_generate", "run face_preset name=Neutral", "wait 0.2", "shot 00-neutral"]
+ for i, name in enumerate(ARKIT):
+ # ARKit's mouthClose closes the lips while the jaw is open: on its own it pushes them through each other.
+ weights = '{"%s":1%s}' % (name, ',"jawOpen":1' if name == "mouthClose" else "")
+ lines += ["run face_preset name=Neutral", "run face_weights json=" + weights, "wait 0.1",
+ "shot %02d-%s" % (i + 1, name)]
+ script = os.path.join(work, head + ".sfui")
+ with open(script, "w") as f:
+ f.write("\n".join(lines) + "\n")
+ shots = os.path.join(work, head)
+ subprocess.run([a.app, "--ui-test", script, "--ui-out", shots], check=True)
+ tiles = []
+ for i, name in enumerate(["neutral"] + ARKIT):
+ src = os.path.join(shots, "%02d-%s.png" % (i, name))
+ tile = os.path.join(work, "%s-%02d.png" % (head, i))
+ subprocess.run(["magick", src, "-crop", crop, "+repage", "-resize", "%dx" % a.tile, tile], check=True)
+ tiles.append((name, tile))
+ os.makedirs(a.out, exist_ok=True)
+ out = os.path.join(work, "face-shapes-%s.png" % head)
+ cmd = ["magick", "montage"]
+ for name, tile in tiles:
+ cmd += ["-label", name + (" + jawOpen" if name == "mouthClose" else ""), tile]
+ cmd += ["-tile", "9x", "-geometry", "+4+4", "-pointsize", "14", "-background", "#1b1d22", "-fill", "#e8e8e8", out]
+ subprocess.run(cmd, check=True)
+ jpg = os.path.join(a.out, "face-shapes-%s.jpg" % head)
+ subprocess.run(["magick", out, "-resize", "1400x", "-quality", "82", jpg], check=True)
+ print("wrote", jpg)
+
+
+if __name__ == "__main__":
+ main()