Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
Merge remote-tracking branch 'origin/feat/timeline-proof' into integration/next
islandmed3bbb22e6804e
diff --cc CHANGELOG.mdindex fd586086,64d707d0..db046662--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -7,71 -7,29 +7,94 @@@ All notable changes to SculptForge are## [Unreleased]### Added+- **Micro levels: hundreds of millions of sculptable polygons** (**Tool > Geometry > Micro**, `micro_*`+ commands). Above the highest subdivision level a SubTool can carry a micro level: per triangle a regular grid of+ 16-bit heights along the interpolated normal of the smooth (Phong-tessellated) base, instead of a mesh.+ 300 million micro triangles take 374 MB (1.25 bytes each; the whole app about 0.8 GB), where a mesh of that size+ would need about 27 GB. Unlike ZBrush's HD Geometry the whole model is sculptable at once.+ - Brushes: Standard, Clay, Clay Buildup, Smooth, Inflate, Flatten, Trim, Layer, Pinch / Crease / Dam Standard+ (as height sharpening), Mask; symmetry, Focal Shift, pressure and the mask apply. Big brushes are evaluated on+ a coarser grid and interpolated (scale-adaptive). Move reshapes the base below the micro level and the detail+ rides along (dual scale); "Move along normals" moves the micro surface itself.+ - Viewport: the micro surface is evaluated on the GPU per frame, with a level of detail per cluster and a+ triangle budget (2M on a laptop profile, 8M on a workstation, `RenderSettings::renderTriangleBudget`), crack+ free; the shading keeps every micro detail. 300M micro triangles orbit at 70+ fps with 4x antialiasing (M1 Pro).+ - Bake Micro (to a mesh), Export Displacement (32-bit EXR or 16-bit PNG, scalar or vector, over the base UVs).+ - Undo: a packed journal per stroke (tiles in Morton order, each tile's change predicted and packed).+ - Very large levels stay out of core in a sparse memory-mapped file (only what you touch is in memory).+ - Projects: format 7 when a SubTool has a micro level (others stay format 6 for older versions).+ - `sculptforge --bench-micro --bench-sizes 33,100,300` measures it. Guide chapter "Micro levels".+- Automatic hardware detection and calibration. On first launch, and again when the graphics card, its driver or+ the version changes, SculptForge spends about a second or two (under a small overlay; Esc skips) measuring+ triangle throughput, upload bandwidth, brush speed and memory bandwidth, and probes the GPU (OpenGL strings,+ video memory through GL_NVX_gpu_memory_info, GL_ATI_meminfo, GLX_MESA_query_renderer, amdgpu sysfs, DXGI or+ CGL), RAM, threads, SIMD and OS. The result picks a profile: **Laptop / Budget**, **Workstation** (64 GB+ RAM+ with a 16 GB+ discrete GPU, or Apple Silicon Max / Ultra and big APUs, that measure fast) or a **Software** safe+ mode for llvmpipe, with a render triangle budget, motion proxy+ threshold, GPU memory and upload budgets, texture, subdivision and micro-triangle limits and the thread count.+ Cached in the settings folder; no network use. A one-line status bar message says what was found.+- Preferences > Performance shows what was detected and measured ("Detected <GPU>, <memory> -> Workstation"),+ the settings in effect, **Re-calibrate** and manual overrides (kept across re-calibrations).+- An adaptive frame governor holds the view at 60 fps (120 / 144 on a fast display) while it moves, by switching+ big scenes to their motion proxy sooner or later, with hysteresis; it changes only what is drawn, never the+ model. Fast Navigation's 10 million triangle threshold now comes from the profile.+- On battery (laptops), brushes switch to draft mode, uploads per frame halve and the target is 60 Hz.+- `sculptforge --calibrate` prints the profile as JSON (schema sculptforge.calibration/1); commands+ `performance_profile`, `calibrate` and `set_performance_override` for the console, scripts and MCP.+- For developers: `core/TierConfig.h` (resident cache cap, active-triangle budget, upload budget, draft brush+ mode, zero-copy UMA, target Hz) and `renderTriangleBudget()` for the renderer and micro-displacement+ (docs/performance.md, "Hardware profile").+- Material painting (PBR): a painted texture can carry Roughness, Metallic, Normal, Height (16-bit), Ambient+ Occlusion, Emissive and Opacity besides its colour, all painted in the same strokes. Turn channels on in+ **Tool > Texture Map > Material Channels** (`texture_channels`); a channel costs no memory until it is painted+ (64x64 copy-on-write tiles; untouched tiles aren't stored). **Color > Material** sets what the brush lays on+ each channel (material swatches, per-channel value swatches and sliders; `paint_material`), and **C** picks the+ whole material under the cursor. Paint layers hold every channel: channel chips on each layer row turn a+ channel on or off for that layer, and give it its own blend mode and opacity, including **Normal Combine** for+ normals (`texture_layer_channel`). Height also yields a normal combined onto the Normal channel. One undo step+ per stroke, kept per layer and channel. Auto UV, Voxel Remesh, QRemesh and merging SubTools carry every channel.+ See the guide's Material painting page.+- Solo channel view: **Tool > Texture Map** shows one channel on the model (roughness and the other scalars in+ grey, the normal as colours, emission in colour), live while painting (`channel_view`).+- Export Maps with presets (`export_maps`): Unreal (`T_*_BC`, `T_*_N` in DirectX, `T_*_ORM`), Unity URP and HDRP+ (mask map), glTF, Godot, Blender (one file per channel) and USD, plus your own JSON presets (the guide's Export+ presets page). Height maps are 16-bit PNG.+- Model exports wire the channels into their materials: glTF metal-rough slots (packed occlusion / roughness /+ metallic, normal, emissive, alpha from opacity), UsdPreviewSurface inputs, the MTL PBR keys and FBX material+ maps. Send to Unreal imports `T_<Name>_BC / _N / _ORM` and builds an `M_<Name>` material from them.+- Preferences > Performance and `perf_info` show the memory of textures and their material channels.++### Changed+- Texture painting on dense meshes costs the texels a dab reaches instead of the triangles under it: the brush+ finds the texture tiles under it from the BVH and paints each texel from a cached triangle-and-barycentrics+ map, tiles in parallel. A 0.35-radius dab with X symmetry on a 21M-triangle sphere: 4K 150-360 ms -> 24-39 ms,+ 8K 240-350 ms -> 39-55 ms (M1 Pro, ranges over a busy and a quiet machine); results match the old dab within+ 1/255. Lighter meshes keep the per-triangle dab.+- Project format 7 stores material channels. It is written only when a texture has them: other projects are+ still saved as format 6, and every older project opens as before.+ - **Sculpt Timeline**: every stroke and operation is a tick on a strip along the bottom of the canvas. Drag the+ scrubber to see the model at any point of the session, click a step to go there. Sculpting from an earlier+ point no longer throws the later steps away: they stay as a branch (a lane above the track) you can switch+ back to, with undo / redo working on the active branch as before. Right-click a stroke to re-tune its strength+ (0 removes it, 2 doubles it) without redoing the strokes after it; where later strokes overlap it they keep+ their own displacement on top (they aren't sculpted again; see the guide's Sculpt Timeline chapter). Seeking+ reuses undo's per-stroke deltas, swaps runs of strokes at once with one normal / BVH / GPU update, and jumps+ from full checkpoints every 16 steps (within 1 GB; fewer on huge meshes) for long seeks. Each SubTool keeps+ its own timeline. Commands `timeline_info`, `timeline_seek`, `timeline_select`, `timeline_retune`,+ `timeline_save`, `timeline_load`; UI test timeline.+ - **Save with project** (in the timeline's header) also writes the history beside the project as+ `<name>.sfhist` (strokes, masks, polypaint, visibility, polygroups, branches, re-tuned strengths; a topology+ change cuts it). Opening the project brings it back when the mesh matches. The project format is unchanged.+ - **Export timelapse**: the history rendered as a turntable video, the model building up stroke by stroke while+ the camera goes once around it (1080p or 4K MP4, no captions; needs ffmpeg). Also+ `sculptforge project.sfproj --timelapse out.mp4 [--size 3840x2160] [--timelapse-seconds 20]`.+ - **Proof mode** (**Help > Benchmark**, `sculptforge --benchmark`): a scripted 240 Hz pen stroke through the+ same input handlers a real pen uses, with a 60 px and a 240 px brush and a turn of the view, on 5, 20 and 33+ million triangle meshes (100 million when free memory allows). A live HUD shows fps, frame time p50 / p95 /+ p99, how far the stroke trails the pointer (ms and px) and memory; the run is recorded to an MP4 with the HUD in+ it and written as a JSON result with the processor, graphics card, memory, OS, version and commit.+ `docs/benchmark.md` describes the format, `tools/benchmark/submit.py` checks results and adds them to+ `website/benchmarks/results.json`, which the new benchmarks page lists.## [0.9.7] - 2026-10-31diff --cc docs/guide/index.mdindex b0a90d55,b8cc4d8b..424c5aa5--- a/docs/guide/index.md+++ b/docs/guide/index.md@@@ -30,40 -30,38 +30,41 @@@ You can read it inside SculptForge (**H12. [ZSpheres](zspheres.md)13. [Polypaint and materials](polypaint.md)14. [Texture painting](texture-painting.md)-15. [Sculpt layers and blend shapes](layers.md)-16. [Facial shapes and live face](facial-shapes.md)-17. [Subdivision levels](subdivision-levels.md)-18. [Dynamic topology](dynamic-topology.md)-19. [Sculpt Timeline and timelapse](timeline.md)-20. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)-21. [Subdivide, remesh, decimate and LODs](geometry.md)-22. [Quad retopology and detail projection](retopology.md)+15. [Material painting (PBR)](pbr-painting.md)+16. [Sculpt layers and blend shapes](layers.md)+17. [Facial shapes and live face](facial-shapes.md)+18. [Subdivision levels](subdivision-levels.md)+19. [Micro levels: hundreds of millions of polygons](micro-levels.md)+20. [Dynamic topology](dynamic-topology.md)- 21. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)- 22. [Subdivide, remesh, decimate and LODs](geometry.md)- 23. [Quad retopology and detail projection](retopology.md)++21. [Sculpt Timeline and timelapse](timeline.md)++22. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)++23. [Subdivide, remesh, decimate and LODs](geometry.md)++24. [Quad retopology and detail projection](retopology.md)## AI and capture- 24. [Image and text to 3D](generate-3d.md)- 25. [Gaussian splats](splats.md)- 26. [Scan an object into a splat](scan-to-splat.md)- 27. [From scan to sculptable mesh](scan-to-sculptable.md)- 28. [Phone capture and AR](phone-capture.md)-23. [Image and text to 3D](generate-3d.md)-24. [Gaussian splats](splats.md)-25. [Scan an object into a splat](scan-to-splat.md)-26. [From scan to sculptable mesh](scan-to-sculptable.md)-27. [Phone capture and AR](phone-capture.md)++25. [Image and text to 3D](generate-3d.md)++26. [Gaussian splats](splats.md)++27. [Scan an object into a splat](scan-to-splat.md)++28. [From scan to sculptable mesh](scan-to-sculptable.md)++29. [Phone capture and AR](phone-capture.md)## Files and pipelines- 29. [Baking normal and displacement maps](baking.md)- 30. [Exporting, Unreal and ZBrush](exporting.md)- 31. [Export presets](export-presets.md)- 32. [Working with Blender](blender.md)- 33. [Projects, autosave and QuickSave](projects.md)- 34. [Scripting and automation](scripting.md)- 35. [SculptForge for studios](studios.md)-28. [Baking normal and displacement maps](baking.md)-29. [Exporting, Unreal and ZBrush](exporting.md)-30. [Working with Blender](blender.md)-31. [Projects, autosave and QuickSave](projects.md)-32. [Scripting and automation](scripting.md)-33. [SculptForge for studios](studios.md)++30. [Baking normal and displacement maps](baking.md)++31. [Exporting, Unreal and ZBrush](exporting.md)++32. [Export presets](export-presets.md)++33. [Working with Blender](blender.md)++34. [Projects, autosave and QuickSave](projects.md)++35. [Scripting and automation](scripting.md)++36. [SculptForge for studios](studios.md)## Reference- 36. [Keyboard and mouse](shortcuts.md)- 37. [Performance and big meshes](performance.md)- 38. [Troubleshooting and FAQ](troubleshooting.md)- 39. [Glossary](glossary.md)-34. [Keyboard and mouse](shortcuts.md)-35. [Performance and big meshes](performance.md)-36. [Troubleshooting and FAQ](troubleshooting.md)-37. [Glossary](glossary.md)++37. [Keyboard and mouse](shortcuts.md)++38. [Performance and big meshes](performance.md)++39. [Troubleshooting and FAQ](troubleshooting.md)++40. [Glossary](glossary.md)## Getting helpdiff --cc src/app/App.cppindex da88ea04,cbb8c50b..561369d9--- a/src/app/App.cpp+++ b/src/app/App.cpp@@@ -819,7 -812,7 +822,8 @@@ int App::run()perf_.samplesUsed = renderer_.drawView(camera_, fbW, fbH, renderSettings_, canvasViewport(fbW, fbH), samples);renderSettings_.motionProxy = false; // (other renders, e.g. project thumbnails, draw in full)ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());+ hardwareProfileFrameEnd();+ if (proof_) proofBeforeSwap(fbW, fbH); // Help > Benchmark: timing, video capture, the scripted pointerSDL_GL_SwapWindow(window_);++framesDrawn;if (sm.started && !sm.moving) { // the press is on screen: start moving round the circlediff --cc src/app/main.cppindex 2a201740,c6c296a7..e6892501--- a/src/app/main.cpp+++ b/src/app/main.cpp@@@ -52,11 -51,18 +52,22 @@@ void usage()" --bench-no-project Skip the project save / open (it needs twice the memory)\n"" --bench-view Benchmark only what the viewport costs (uploads, orbit)\n"" --bench-dyntopo Benchmark dynamic topology strokes (e.g. --bench-sizes 0.25,1,4)\n"+ " --bench-micro Benchmark micro-displacement levels (sizes = micro triangles, e.g. 33,100,300)\n"+ " --bench-micro-level N Micro level for --bench-micro (default 4: 256 per base triangle)\n"" --bench-out FILE Write the benchmark report (Markdown) to FILE\n"+ " --calibrate Measure this computer (GPU, CPU, memory; about 2-3 s), print the hardware\n"+ " profile as JSON and save it (add --calibrate-quick, --calibrate-no-save)\n"+ " --timelapse out.mp4 Render the opened project's history (saved beside it as .sfhist) as a\n"+ " turntable timelapse and exit (--size 3840x2160 for 4K, --fps N)\n"+ " --timelapse-seconds S Length of the timelapse (default 20)\n"+ " --benchmark Proof mode: a scripted stroke on 5M / 20M / 33M (and 100M when memory\n"+ " allows) triangle meshes through the input handlers, with a live HUD; writes a\n"+ " JSON result and an MP4 of the run and exits (docs/benchmark.md)\n"+ " --benchmark-sizes 5,20 Proof mode mesh sizes in millions of triangles\n"+ " --benchmark-out FILE Where the JSON result goes (default: sculptforge-benchmark-<time>.json here)\n"+ " --benchmark-video FILE Where the MP4 goes; --benchmark-no-video records none\n"+ " --benchmark-vsync Keep vertical sync on (default off: frame times are not capped)\n"+ " --benchmark-seconds S Length of each scripted stroke (default 6)\n"" --log-dir DIR Write sculptforge.log to DIR instead of the user data folder\n"" --crash-test KIND Crash on purpose (segv, abort or throw) to test the crash note in the log");}diff --cc src/core/Commands.cppindex dfcfe4c9,bda7341e..e536890a--- a/src/core/Commands.cpp+++ b/src/core/Commands.cpp@@@ -777,7 -775,7 +778,8 @@@ CommandRegistry::CommandRegistry()registerTransformCommands(*this); // transform (core/MeshTransform.h)registerExtractMirrorCommands(*this); // extract, mirror_and_weld, mirror (core/ExtractMirror.h)registerPerformanceCommands(*this); // perf_info, set_multithreading (core/Benchmark.cpp)+ registerHardwareProfileCommands(*this); // performance_profile, calibrate, set_performance_override (core/HardwareProfile.cpp)+ registerTimelineCommands(*this); // timeline_info / seek / select / retune / save / load (core/Timeline.h)registerPaintCommands(*this); // core/Polypaint.cppregisterGozCommands(*this); // goz_import/export/send/receive, export_stl (io/GozCommands.cpp)registerBlenderCommands(*this); // blender_send/receive (io/BlenderCommands.cpp)diff --cc src/core/Project.cppindex 895112d4,2506a4ef..477849f5--- a/src/core/Project.cpp+++ b/src/core/Project.cpp@@@ -1,7 -1,7 +1,8 @@@// SculptForge - open source digital sculpting// SPDX-License-Identifier: GPL-3.0-or-later#include "core/Project.h"+#include "core/Micro.h"+ #include "core/Timeline.h"#include "core/Multires.h"@@@ -1156,7 -1049,9 +1157,9 @@@ bool loadProjectThumbnail(const std::stCommandResult openProjectCommand(Document& doc, const std::string& path) {std::string err;if (!loadProject(path, doc, err)) return {false, err};+ std::string msg = "Opened project " + std::filesystem::path(path).filename().string() + " (";+ // The Sculpt Timeline saved beside it, if it matches (only into the app's own scene: not thumbnails, scratch opens).+ const int histories = &doc == Timeline::historyDocument ? loadHistorySidecar(doc, path) : 0;- std::string msg = "Opened project " + path + " (";if (doc.subtoolCount() > 1) msg += std::to_string(doc.subtoolCount()) + " SubTools, ";size_t tris = 0, layers = 0;for (int i = 0; i < doc.subtoolCount(); ++i) {