Sharpen Hard — manual

A Blender add-on that turns soft, mushy AI-generated meshes into crisp hard-surface geometry with flat n-gon panels — then re-unwraps the result and bakes the textures back from the untouched original.

Version 0.20.0. Blender 4.2 or newer. Panel: 3D viewport → N sidebar → ♥SH tab → “Sharpen Hard”, with the version and a ? in the panel’s header bar.

Source: D:\GitHub\sharpen_hard\


Contents


What it fixes

Image-to-3D generators (TRELLIS.2 in this repo) hand back a dense triangle soup. A 90-degree corner is not one sharp edge — it is a chamfer spread over several triangles, each turning 10-25 degrees. Measured on two subjects, the median dihedral angle of a whole model is 0.009 degrees (a locker) and 0.098 degrees (a crate). Nothing on the mesh is flat and nothing is sharp.

Sharpen Hard alternates two operations to fix that:

  1. Limited dissolve merges near-coplanar faces into single n-gon panels.
  2. The planar walk pulls each vertex toward the best-fit plane of the faces around it, so vertices on a panel boundary converge to the intersection line of two planes and corner vertices to the corner point — a CAD-like snap.

Each planar pass makes more faces truly coplanar, which lets the next dissolve merge further. That is why the pair repeats — see The Sharpen slider and Sharpen Cycles.

Sharpening destroys the UV atlas by design. Steps 11-14 rebuild it: a fresh unwrap, a triangulation, the shading, and a bake that pulls colour, normal, roughness and metallic off the hidden original.


Quick start

Install, short version

  1. Zip D:\GitHub\sharpen_hard\ and install it with Preferences → Add-ons → Install from Disk.
  2. On Windows, if you want the Make Manifold step, open Preferences → Add-ons → Sharpen Hard and press Install Repair Support (about 3.5 MB, once per Python version).

Full detail, including the per-Python-version trap: Installation.

First run, 60 seconds

  1. Import or select a mesh. Object Mode, one active mesh object.
  2. Open the N sidebar, ♥SH tab.
  3. Leave the Sharpen slider in the middle.
  4. Press Run Checked Steps.

Steps 3 (Make Manifold), 10 (Make Planar B) and 12 (Triangulate) start unchecked and the other eleven start checked, which is the setting that measured best on finished props. Make Manifold costs 3-4x the run time and usually makes the result worse — turn it on only when dissolve is visibly stalling at open edges; see 3. Make Manifold. On Mac and Linux it cannot run at all and the step box is flagged Windows only.

Blender will freeze. That is normal — every step runs inside execute() and the viewport cannot repaint on its own. The add-on paints the step name in the lower left of the viewport in orange-red while it works and flashes teal for a second when it finishes. Everything also goes to the console, prefixed [sharpen_hard].

When it finishes you have a new object called <name>_sharp with a fresh UV atlas and baked maps, and the original hidden beside it. The Last Run box at the bottom of the panel holds one line per step, with the numbers each one measured.


The panel, top to bottom

The Sharpen Hard N-panel

  1. Version and docs link — the installed version, read from the manifest, and a ? that opens this manual. Both sit in the panel’s header bar, so they are still there with the panel collapsed.
  2. The Sharpen slider — one dial that writes the dissolve angles, planar iterations and cycle count below it.
  3. The per-step ▶ button — runs that step once, whatever Sharpen Cycles says. To its left, the checkbox decides whether Run Checked Steps includes the step, and the disclosure triangle opens that step’s own settings. Steps 3, 10 and 12 start unchecked.
  4. Sharpen Cycles — how many times the dissolve/planar block repeats.
  5. Run Checked Steps — every checked step, in registry order.
  6. Import GLB / Export GLB — the file box. Export writes only the selected objects and skips hidden ones.
  • The panel header carries the version on the right and a ? button that opens this manual at https://cw1.me/sharpenhard-docs. Both sit in the header bar itself, so they are still there with the panel collapsed. The version is read from the manifest, so it always matches what is installed.
  • Less / More labels, then the Sharpen slider, then the note “drives the dissolve/planar values below”.
  • Fourteen boxes, one per step, numbered 1. to 14.. Each box has a checkbox (does Run Checked Steps run it), a disclosure triangle (its settings), the step name with an icon, and a ▶ button that runs only that step, once.
  • Sharpen Cycles.
  • Run Checked Steps.
  • File — Import GLB and Export GLB. See below.
  • Last Run — one line per step and a total <n>s line, kept until the next run.

File — Import GLB and Export GLB

The pipeline starts from a GLB and usually ends as one, and Blender’s own glTF operators sit several menus deep. These are the same operators, aimed at the one format this add-on cares about.

Import GLB loads a .glb or .gltf and leaves what it brought in selected, with the first mesh active — ready for step 1 without another click. It does not join multiple objects into one: that is a decision about the asset, not a detail, so make it yourself if you want a single mesh.

Export GLB writes only the selected objects, and skips hidden ones. That matters here: step 1 leaves the original hidden in the file as the bake source, and it has no business in an export. The file is named after the active object rather than the .blend. The button is greyed out with no mesh selected.


Installation

Sharpen Hard is a Blender extension: it carries a blender_manifest.toml, not a bl_info block.

field value
id sharpen_hard
name Sharpen Hard
version 0.20.0
type add-on
blender_version_min 4.2.0
licence GPL-3.0-or-later
maintainer Chipp Walters chipp@altuit.com

Manifest: D:\GitHub\sharpen_hard\blender_manifest.toml

The add-on needs nothing beyond Blender itself. NumPy ships with Blender. The only optional download is the Windows repair support for step 3.

Install the add-on

From a zip

Zip the folder D:\GitHub\sharpen_hard\ and use Edit → Preferences → Add-ons → Install from Disk.

The manifest’s paths_exclude_pattern keeps libs/, testing/, __pycache__/ and *.pyc out of a built extension, so a zip built by blender --command extension build ships without repair support. You download that once from inside Blender — see below.

As a linked folder

The related Make Manifold add-on is installed on this machine by junctioning its source folder into the portable Blender’s extension directory, for example:

E:\BlenderTestEnvironment\blender-5.0.0-stable.a37564c4df7a\portable\extensions\user_default\make_manifold

The same layout works for sharpen_hard. Edits to the source are then live after a Blender restart. Installed this way the module is bl_ext.user_default.sharpen_hard.

Headless, straight from the repo

The pipeline scripts never install the add-on. They register it from the repo, after disabling any extension install of the same id — registering twice makes the second registration steal every class from the first. The helper is load_sharpen_addon() in D:\GitHub\model-roboto\scripts\kpack_stage.py:

import addon_utils
addon_utils.disable("bl_ext.user_default.sharpen_hard", default_set=False)
sys.path.insert(0, r"D:\GitHub")          # the folder holding sharpen_hard\
import sharpen_hard
sharpen_hard.register()
assert hasattr(bpy.context.scene, "sharpen_hard")

Never call bpy.ops.wm.read_factory_settings() in a headless stage. It resets preferences, which unregisters every add-on, and the failure then looks like a missing module. Use bpy.ops.wm.read_homefile(use_empty=True).

Dependencies: the Windows repair engine

One optional download, needed only by step 3. Every other step works without it, and it is never fetched unless you press the button.

Edit → Preferences → Add-ons → Sharpen Hard shows a Dependencies block with its status and Install button, followed by two path overrides:

  • Python — an interpreter override. Leave it empty and the add-on uses Blender’s own bundled Python.
  • Libraries — a folder override for the WinRT packages. Leave it empty and the add-on uses a libs folder beside itself, or Make Manifold’s if that add-on already downloaded them.

Repair support for step 3, Make Manifold

Step 3 hands the mesh to the repair engine that ships with Windows — the netfabb-derived code under 3D Builder, reachable as the WinRT namespace Windows.Graphics.Printing3D. Blender does not bundle the Python projection for it, so five packages have to be downloaded once:

winrt-runtime
winrt-Windows.Foundation
winrt-Windows.Storage
winrt-Windows.Storage.Streams
winrt-Windows.Graphics.Printing3D

About 3.5 MB in total. The list is printed at the bottom of the preferences box.

The button

The Windows Repair Support box in preferences shows either “Repair support found (cp313): <path>” with a checkmark, or “No repair support for cp313 (this Blender’s Python).” with an error icon, and an Install Repair Support button. The button runs python -m pip install --upgrade --target <libs>\<tag> with all five wheels in one call, and reports the folder they landed in.

The same warning box and the same button appear inside step 3’s settings drawer in the N-panel, so you find out before a run rather than twenty minutes into one.

On Mac and Linux

Everything except step 3 works. The add-on installs and registers normally, and the other thirteen steps behave exactly as they do on Windows.

Step 3 is unchecked by default there, and its box in the panel is flagged unusable in this slot in red — on the closed box, not buried in the drawer, so you see it before you press anything. The step is never removed from the list; it sits in place, marked unusable. The preferences page says the same.

If you check it anyway, the step raises the Windows repair engine needs Windows and the whole run stops there, because one failing step aborts the chain. You would be left with the original hidden and a copy that got only as far as step 2. Nothing is silently skipped and nothing is faked — but there is nothing to gain by checking it either.

The same red flag appears on Windows when the WinRT packages are missing for this Blender’s Python, where it reads no repair support and the drawer offers the download button.

The support is per Python version, and that matters

The winrt wheels are compiled. They ship _winrt.cp311-win_amd64.pyd and friends, so a set installed by one Blender is useless to a Blender on another Python:

Blender Python tag
5.0 3.11 cp311
5.1, 5.2 3.13 cp313

This was a real bug, fixed in 0.11.1. Before then the add-on only checked that a winrt folder existed, said it was ready in Blender 5.1, and the worker then died on No module named 'winrt._winrt'. Now deps_present() looks for that exact .pyd filename, and the status line names the tag so “not installed” on a machine that plainly has the files reads as what it is: a different Blender.

Installs go to libs\<tag>\, for example D:\GitHub\sharpen_hard\libs\cp313\. Each Blender installs and finds its own.

Where it looks, in order

winrepair.libs_candidates() checks, and inside each base the <tag> subfolder before the flat folder:

  1. the Libraries override from preferences
  2. D:\GitHub\sharpen_hard\libs\
  3. a sibling make_manifold\libs\ — extensions install as siblings under bl_ext\user_default\

The flat folder is Make Manifold’s layout, and Sharpen Hard’s own layout before 0.11.1. It is still read, but only when what is in it matches the interpreter.

So whichever add-on downloads a given version first, the other finds it, and neither ever writes into the other’s folder — that would make the two uninstall each other.

The Make Manifold add-on is not required

D:\GitHub\sharpen_hard\winrepair.py carries the whole engine, with threemf.py and repair_worker.py beside it. Nothing in sharpen_hard imports make_manifold. That add-on is a bench that measures the same engine against Blender’s 3D Print Toolbox; the two only ever share the 3.5 MB.

Installing by hand

If the button cannot reach the network, run pip yourself against the interpreter that Blender uses:

"<blender>\<version>\python\bin\python.exe" -m pip install --upgrade ^
  --target "D:\GitHub\sharpen_hard\libs\cp313" ^
  winrt-runtime winrt-Windows.Foundation winrt-Windows.Storage ^
  winrt-Windows.Storage.Streams winrt-Windows.Graphics.Printing3D

All five in one call. pip install --target --upgrade prunes the target directory of anything it thinks it owns, so installing them one at a time silently deletes the previous one.

Check the install

Headless smoke test, which exercises every step, the whole chain, the cycle expansion, the preview and the curved-surface protection:

blender.exe -b -P "D:\GitHub\sharpen_hard\testing\run_headless_test.py" -- <model.glb>

Exit code 0 is a pass; it prints [PASS] all sharpen_hard smoke tests passed. Failures print as [FAIL] <what> and the script exits 1.


The Sharpen slider and Sharpen Cycles

The slider

At the top of the panel: a Less / More row, the Sharpen slider, and the note “drives the dissolve/planar values below”.

One dial, sharpen_amount, range 0.0 to 1.0, default 0.5. Moving it writes seven values into the per-step settings:

written value at 0.0 at 0.5 at 1.0
Max Angle (coarse) — angle_coarse 10° 20° 30°
Max Angle (fine) — angle_fine 1° 3° 5°
Iterations A and B — planar_iters_a/b 1 2 3
Factor A and B — planar_factor_a/b 0.50 0.75 1.00
Sharpen Cycles — cycles 1 2 3

Every value in that table is also the property’s own default, so the middle of the slider and an untouched scene agree. Moving the slider to 0.5 changes nothing.

The coarse range was 15-35 between 0.12.11 and 0.19.0, putting 25° at the midpoint on the reasoning that 25 merges more near-coplanar mush into single panels than 20. That made the panel lie: a fresh scene showed the property default of 20°, and the number silently became 25 the first time anyone touched the slider. 0.19.1 put the range back to 10-30. The span is 20° either way, so the slider still means the same thing end to end.

Hand-edited values survive until the slider moves again

Open a step’s drawer and type a number, and it stays. Nothing recalculates it behind your back. The next time sharpen_amount changes, every one of the seven is written over.

So the working order for scripts is: set the amount first, then any override. D:\GitHub\model-roboto\scripts\bench\sharpen_arm.py does exactly that, with a comment saying why.

The angles are radians, and they clamp silently

angle_coarse and angle_fine are subtype='ANGLE' properties — Blender stores them in radians — capped at radians(60) and radians(15). Pass degrees straight in from a script and Blender clamps without complaint.

This ran the same experiment three times. A sweep asking for 10, 14 and 17.8 degrees set all three to 60 degrees and produced three byte-identical meshes. Nothing failed; the run looked clean.

s.angle_coarse = math.radians(deg)
if abs(math.degrees(s.angle_coarse) - deg) > 0.01:
    raise SystemExit("angle_coarse %s deg was clamped to %.2f"
                     % (deg, math.degrees(s.angle_coarse)))

One real datum survived that mistake: at 60 degrees one subject collapsed to 11,830 faces against 37,534 at 20, and took 446 s against 161 s. The dissolve gets dramatically slower as it merges more.

Sharpen Cycles

At the bottom of the panel, above Run Checked Steps.

setting label default range
cycles Sharpen Cycles 2 1 - 10

It repeats only the checked dissolve/planar block:

dissolve_coarse → planar_a → dissolve_fine → planar_b

Each planar pass makes more faces truly coplanar, so the next dissolve merges further. The property’s own description says 2-4 captures most of the benefit.

What repeats and what does not

The runner takes the checked steps in registry order, then replaces the first block member with the whole block repeated cycles times, dropping the later members from their original positions. With everything checked and cycles = 3:

copy  weld  manifold_early  decimate  clear_normals  detect
  dissolve_coarse planar_a dissolve_fine planar_b
  dissolve_coarse planar_a dissolve_fine planar_b
  dissolve_coarse planar_a dissolve_fine planar_b
unwrap  triangulate  bake  auto_smooth

Uncheck a block member and it drops out of every repeat — unchecking Make Planar A and Make Planar B gives you dissolve_coarse → dissolve_fine, three times over.

Detect Curved Surfaces is deliberately outside the block. It must run once, on pristine geometry: after a dissolve leaves a few giant faces, the median edge length explodes and the detector’s radius floor silently disables protection. The headless smoke test asserts this — with cycles = 3 it requires the report to show the coarse dissolve three times, the weld once and the detect once.

The ▶ buttons always run once

A per-step ▶ button runs its step exactly once, whatever Sharpen Cycles says. Cycles apply only to Run Checked Steps.


The fourteen steps

The add-on is a registry of fourteen steps. Each one is a plain function (context, settings, obj) -> (obj, message). The ▶ button beside a step and the Run Checked Steps button at the bottom of the panel call the same functions, so a step behaves the same whether you run it alone while tuning or as part of the chain.

Every step returns a message. The panel collects them in the Last Run box and the console prints each one as it happens, prefixed [sharpen_hard]. Those numbers are the point — they are how you tell a run that worked from one that quietly did nothing.

The fourteen-step pipeline

 1 Copy & Hide Original      8 Make Planar A
 2 Weld Vertices             9 Dissolve (Fine)
 3 Make Manifold            10 Make Planar B
 4 Decimate                 11 Unwrap
 5 Clear Custom Normals     12 Triangulate
 6 Detect Curved Surfaces   13 Shade Auto Smooth
 7 Dissolve (Coarse)        14 Bake Textures

Step ids, for scripting: copy, weld, manifold_early, decimate, clear_normals, detect, dissolve_coarse, planar_a, dissolve_fine, planar_b, unwrap, triangulate, auto_smooth, bake.

Eleven are checked by default. The three that are not are 3. Make Manifold, 10. Make Planar B and 12. Triangulate.

1. Copy & Hide Original — copy

Duplicates the active object to <name>_sharp, links the copy into the same collections, selects it and makes it active. The original is hidden three ways — eye, viewport and render — so it cannot leak into a render or an export. The copy is unhidden all three ways, so re-running on an already-hidden object still works.

The copy carries a custom property sharpen_source holding the original’s name. Step 14 finds its bake source through that property. Delete it, and the bake either fails or comes back black.

Settings drawer: no settings, just the note “Original kept as the bake source”.

Report: copied to <name>_sharp, original hidden

Turn it off when you are working on a mesh you are happy to modify in place, and you are not going to bake. The KPACK INSERT cleanup leaves it out for exactly that reason: an INSERT must contain exactly one mesh.

2. Weld Vertices — weld

Merge by Distance over the whole mesh.

TRELLIS GLBs arrive about 37% duplicate vertices — a glTF import is split at every UV seam and every flat-shaded corner, so it has no vertex adjacency at all. Until those are merged a limited dissolve stops dead at invisible walls, and the planar walk sees no neighbours.

setting label default range
weld_dist Weld Distance 1e-5 min 0.0, soft max 0.001

Report: welded 534,956 -> 85,479 verts (84.0%)

If the percentage is near zero on a fresh glTF import, something is wrong — check the scale of the model against the weld distance.

Turn it off almost never. It is the first thing every other tool in the chain assumes.

3. Make Manifold — manifold_early

Windows only. Hands the mesh to the OS repair engine — the netfabb-derived code under 3D Builder, reached as Windows.Graphics.Printing3D through a temporary 3MF and a subprocess.

Its job is not watertightness. It is to unblock limited dissolve, which stops at open and non-manifold edges the same way it stops at unwelded seams — a failure the weld step cannot reach. Decimate then trims the roughly 43% extra faces the repair adds.

The step rescales the mesh so its longest edge lands near 150 mm before the round trip, because the engine welds and fills against absolute millimetre tolerances, and scales it back afterwards.

Measured on a genuinely broken 166k-face ship: every open and non-manifold edge closed in 23 s, the existing surface moved 0.002%, volume changed 0.085%. Blender’s 3D Print Toolbox failed the same file. Detail: D:\GitHub\model-roboto\docs\WINDOWS_MESH_REPAIR.md

setting label default range
manifold_timeout Timeout (s) 600 30 - 3600
repair_clean Clean After Repair off —

The worker runs as a subprocess precisely so the timeout can kill it. 600 s is fine interactively; the batch pipeline passes 1800.

Clean After Repair dissolves the zero-area faces the engine leaves behind. Its own description warns that this was measured to reopen the mesh — every merge threshold tested broke the seal and raised bowtie counts. It is offered because sharpen re-unwraps and re-bakes anyway, so a reopened surface may still dissolve better. Measure before trusting it.

The drawer also says “Windows repair engine; destroys UVs” and “Unwrap/Bake rebuild them anyway”, and shows the Install Repair Support button if the WinRT packages for this Blender’s Python are missing.

Report: faces 165,990 -> 237,702, boundary 3,757 -> 0, non-manifold edges 4,390 -> 0, SEALED in 33s — or still open in place of SEALED. With Clean After Repair on it appends , cleaned -> <n>f boundary <n>.

Leave it off unless the dissolve is stalling. It starts unchecked everywhere — in the add-on since 0.15.0 and in the pipeline all along. Measured 2026-07-28 on three finished props, each rebuilt from its original high-poly GLB with nothing else changed:

model sharpen time, repair on → off faces after, on → off better
equipment locker 410s → 104s 7,337 → 68,374 off — repaired over-flattens: diagonal creases across the door, louvre vents melted shut
supply bin 148s → 52s 20,453 → 47,963 off — repaired leaves torn shards along the top rim in 3 of 4 views
battery module 58s → 20s 70,720 → 96,519 a wash, slight edge to repaired on rib separation

Turn it on for a subject whose dissolve stalls on open edges. That is the case the repair exists for.

It belongs here and nowhere else. A second Make Manifold after the sharpening cycles shipped in 0.11.0 and was removed in 0.12.0: the engine remeshes, so it hands back triangles where the dissolve had just built flat panels. The seal is real and worthless.

4. Decimate — decimate

A native DECIMATE modifier in collapse mode with use_collapse_triangulate on, applied immediately. The ratio is target_faces / current_tris.

UVs and materials die here. That costs nothing in the normal chain, because step 11 rebuilds the atlas and step 14 bakes onto it from the original.

setting label default range
target_faces Target Faces 250,000 1,000 - 2,000,000

The Decimate step's settings

  1. Target Faces — the triangle budget. The collapse ratio is target_faces / current_tris, so the step hits this number exactly.

Report: decimated 801,280 -> 200,000 tris, or already 120,000 tris, under target -- skipped when the mesh is already inside the budget.

Turn it off when the mesh is already at the density you want, or when the atlas on it is the deliverable — a collapse decimate will wreck it. The INSERT pipeline decimates with Mesh Press’s “Keep UVs” path instead, for that reason.

PyMeshLab was tried here and lost

Version 0.16.0 added a PyMeshLab engine for this step and 0.18.0 removed it. Recorded so nobody spends the day again. Measured on an 814k-face ship, same welded input:

engine time tris (target 200,000) crisp edges
Blender collapse 9.5s 199,999 (exact) 25.3%
PyMeshLab quadric 10.9s 198,322 14.1%
PyMeshLab clustering 1.1s 158,909 (−20.5%) 12.7%

Grid clustering is the only fast one, and it is fast because it snaps vertices to a lattice without looking at the shape. It tessellates flat panels as finely as creases, so a hard-surface model comes back as a uniform triangle soup where the collapse leaves clean panels — obvious on screen, and only half-visible in the aggregate numbers. Clustering also takes a cell size, not a face count, so it misses the budget in both directions.

PyMeshLab’s quadric collapse is the same class of algorithm as Blender’s and hits the target, but it ran slower and cut crisp edges nearly in half.

Blender’s own decimate wins this job outright, so the step has one engine and no dependency. Mesh Press still uses PyMeshLab and should: Poisson reconstruction and manifold repair have no native Blender equivalent. Decimation is the one job Blender already does better.

5. Clear Custom Normals — clear_normals

bpy.ops.mesh.customdata_custom_splitnormals_clear() on the working copy.

AI-generated meshes arrive carrying custom split normals, baked to make the soft original surface read smoothly. They are mesh data, not a shading setting, so nothing else in the pipeline clears them. Leave them on and the sharpened flat panels are still shaded as if they were curved — every corner the dissolve and planar walk just built gets rounded away at render time. Step 14’s Smooth by Angle also has no visible effect while they are present, because a custom normal overrides whatever the modifier computes.

It sits right after Decimate: the normals are stale from that point on, and this is the smallest the mesh ever gets, so the clear is cheapest here.

Settings drawer: no settings, just the note that it clears baked split normals and that they shade sharp panels as if still curved.

Report: cleared custom split normals, or no custom split normals -- nothing to clear. The second message is normal on a mesh you modelled yourself, and the step is safe to run twice.

Turn it off when the custom normals are deliberate — a hand-authored mesh whose shading you tuned by hand, and which you are running through the pipeline for the unwrap and bake only.

6. Detect Curved Surfaces — detect

Finds large-radius curved surface and tags it, so the dissolve and planar steps leave it alone. Without it, a nacelle, tube or dome facets.

The Detect Curved Surfaces step's settings

  1. Min Radius % — the smallest curve radius that counts as deliberate curvature, as a percentage of the bounding-box diagonal.
  2. Preview Curved — paints the verdict on the mesh without touching geometry. The ✕ beside it clears the paint.
  3. The vertex group status — says whether curves has been built yet. The two lines under it are the reminder that later steps skip only faces whose vertices are all in the group, and that unchecking the step sharpens everything.

The detector does not look at single edges. The surfaces that need protecting are panels and greebles wrapped around a cylinder — locally every edge is panel detail and the curve only exists at a larger scale. Measured on a mining tug, per-edge detection found 7,241 noise regions, best sign coherence 0.10, and protected nothing. So it works in six stages:

  1. Smoothed normal field. Vertex normals are diffused over the edge graph until features below about 2% of the bounding-box diagonal wash out. Greebles average away; the slow normal rotation of a nacelle survives.
  2. Radius band. Per edge, on the smoothed field, radius ≈ edge length ÷ angle between endpoint normals. Only radii between Min Radius % of the bounding-box diagonal and 30% of it qualify. Below is fillets — crisping those is the whole point. The floor is also raised to keep smoothing’s own rounded corners from reading as curvature.
  3. Local sign coherence. Real curvature bends one way; noise flips convex and concave, and cancels.
  4. Region size, density and total turn. Union-find groups the candidate faces; a region is kept only if it holds at least 64 faces (or 0.2% of the mesh, whichever is larger), its candidate-edge density is at least 0.2, and its normals sweep at least 25 degrees. A quarter barrel is already 90 degrees; the gentle bulges a raw TRELLIS hull carries only turn 10-20, and protecting those painted flat panels as speckle.
  5. Discreteness veto. Smoothing turns any smallish convex box into a ball, so cargo pods, arm housings and plate rims pass every test above. Their raw normals give them away: a box concentrates its area on a few flat directions, a barrel spreads it continuously. Measured on the mining tug and an all-box inspection machine, box-like regions put at least 38% of their area within 10 degrees of their 3 dominant normals; every true barrel or dome region stayed at or under 34%. Regions at or above 36% are dropped. The check runs on raw normals and on lightly-smoothed ones, because surface wobble can hide a flat panel’s discreteness in the raw field.
  6. Assembly size. An isolated ring of curved trim — an exhaust port, a rounded plate corner — is locally identical to a ring band of a nacelle. What differs is company: real curved surfaces arrive as several regions split by greeble bands (each tug nacelle: 3-5 regions, 2.5-3.3% of the surface), junk arrives alone (0.6% or less). Nearby survivors are clustered, and a cluster is kept only if it carries at least 1.5% of the mesh’s surface area. A standalone clean cylinder passes — it is most of its own mesh.

What survives is dilated by one ring and written to a vertex group called curves, and the same faces are left selected so they show in Edit Mode.

The group is the interface. A later step protects a face only when all its vertices are in curves, which makes a hand-edited group behave the way a selection does — the boundary ring of a selection does not drag its neighbours in. Select vertices in Edit Mode and assign or remove them to correct whatever the detector got wrong.

setting label default range
protect_radius_pct Min Radius % 4.0 0.5 - 50.0

The drawer also holds Preview Curved and a ✕ clear button, and says whether the curves group “exists - edit it freely” or is “not built yet”.

Preview Curved (mesh.sharpen_preview) runs only the detector, on a throwaway welded copy, and paints the result as a colour attribute called SharpenPreview — orange for protected, blue-grey for will be sharpened. It switches the viewport to Solid / Attribute shading, because attribute colours do not render in Material Preview. Geometry is not touched. Re-run it after changing Min Radius %. Clear Preview removes the attribute and puts the viewport back to Material colours.

Report: protected 12.4% of 200,000 faces -> vertex group 'curves' (18,320 verts) at radius 4.0% Preview instead sets preview: 12.4% protected at radius 4.0% (3.2s).

Run it once, before the dissolve and planar steps. It is deliberately left out of the cycle block: after a dissolve pass leaves a few giant faces, the median edge length explodes and the radius floor silently disables protection. Detection must see pristine geometry.

Turn it off to sharpen everything — which is what the pipeline’s INSERT and bench stages do, since those subjects are meant to be curve-free.

7. Dissolve (Coarse) — dissolve_coarse

Limited dissolve at the coarse angle. This is the step that merges the near-coplanar mush into flat panels. Protected faces are excluded, and use_dissolve_boundaries is off.

setting label default range
angle_coarse Max Angle 20° 0° - 60°
dissolve_delimit_uv Keep UV Seams off —

The Sharpen slider writes Max Angle; at the middle of the slider it becomes 25 degrees.

Keep UV Seams adds UV to the dissolve delimiter, so the dissolve stops at UV island boundaries. It is shared by both dissolve steps — the same property is drawn in both drawers.

  • Leave it off for the normal chain. The atlas is about to be rebuilt by Unwrap, and delimiting only blocks the dissolve.
  • Turn it on when the mesh already carries the texture it will ship with. One face merged across an island boundary samples both islands. Measured on a textured crate: 3.3% of seam edges eaten without it against 0.6% with, for 1.2% fewer faces dissolved.

Report: 25.0deg: faces 200,000 -> 48,102, mushy 23.1%, crisp 31.8% With the delimit on it reads 25.0deg keeping UV seams: ....

Mushy is the share of two-face edges turning 5-30 degrees — the fillet band, the enemy. Crisp is the share turning more than 60 degrees.

Turn it off and there is no sharpening left. If you want less, lower the angle rather than dropping the step: at 8 degrees on one measured subject the sharpness gain was exactly zero (54.01 against a baseline of 54.22) — that is decimation under another name — while at 20 the fine detail degraded. The two are the same dial.

8. Make Planar A — planar_a

The planar walk, run over unprotected faces after the coarse dissolve. Each iteration pulls every vertex toward the best-fit plane of the faces around it, so vertices on a panel boundary converge to the intersection line of two planes and corner vertices to the corner point.

setting label default range
planar_iters_a Iterations 2 0 - 100
planar_factor_a Factor 0.75 0.01 - 1.0

Two iterations is the working value, measured 2026-07-27: the walk converges almost immediately after a dissolve, and extra passes buy no change in the dihedral angles while still moving vertices — which shows up as drift the bake cage then has to span.

Report: 2x @ 0.75: mushy 23.1% -> 23.1%, crisp 31.8% -> 31.8%, drift 0.073%

Drift is the largest movement of a bounding-box face as a percentage of the original bounding-box diagonal — a cheap first-order warning light for silhouette change, not a real Hausdorff measure.

Do not judge this step by its own report. Across 8 planar passes on two subjects, every one reported no change in either mushy or crisp, and reading that as “the planar steps do nothing” was wrong. Their whole purpose is to change what the next step can do: removing them produced more faces, not fewer (30,682 → 37,534 on one subject, 42,827 → 54,835 on another). The mushy/crisp readout measures the dihedral distribution, not coplanarity, so it cannot see the thing the step changed.

Turn it off on detail-rich subjects. Measured on two subjects, the planar steps move the surface about 9x more (0.018% mean deviation against 0.002%) for roughly 5-6% more absolute sharp edge and 22-28% fewer faces — and in the render they are what smears louvre slats into mounds. The pipeline exposes this as --no-planar. They are on by default and worth keeping on subjects that really are large flat panels.

9. Dissolve (Fine) — dissolve_fine

A second limited dissolve at a much smaller angle, now that the planar walk has made more faces truly coplanar.

setting label default range
angle_fine Max Angle 3° 0° - 15°
dissolve_delimit_uv Keep UV Seams off —

Same mechanism and the same report format as step 7.

Report: 3.0deg: faces 48,102 -> 41,880, mushy 25.0%, crisp 34.2%

On its own this is the useful one for cleaning a mesh you cannot re-unwrap: weld, dissolve fine, planar B, with Keep UV Seams on — see recipe 4.

10. Make Planar B — planar_b

The planar walk again, after the fine dissolve. Identical to step 8 with its own pair of settings.

setting label default range
planar_iters_b Iterations 2 0 - 100
planar_factor_b Factor 0.75 0.01 - 1.0

Report: 2x @ 0.75: mushy 25.0% -> 25.0%, crisp 34.2% -> 34.2%, drift 0.062%

11. Unwrap — unwrap

Drops every existing UV layer, welds, runs Smart UV Project, and repacks the islands with the concave shape method.

The weld inside this step is not optional. Smart UV Project grows charts from vertex adjacency, and a mesh imported from glTF has none — every triangle carries its own three vertices. Unwrapping that gives near-per-triangle islands at half the density, and says nothing about it. Measured on one sharpened ship:

verts UV area
straight from the GLB 534,956 0.2155
welded first 85,479 0.4004 (1.86x)

Running the whole chain hides this, because step 2 already welded. It only bites when the unwrap runs on its own — which is what any headless or per-file workflow does. Welding here is safe because the UV layers are removed first, so there is no atlas left to protect. The weld uses the same Weld Distance as step 2; set it to 0 and the weld is skipped.

setting label default range
unwrap_angle Angle Limit 66° 1° - 89°
unwrap_margin Island Margin 0.0004 0.0 - 0.05
unwrap_repack Concave Repack on —

Angle Limit is Smart UV Project’s own. Larger means fewer, bigger islands.

Island Margin is the gap between islands as a fraction of the atlas. A tight margin plus the concave repack measured 24.5% → 45.1% coverage; too tight and the bake bleeds between islands.

Concave Repack repacks with shape_method='CONCAVE' after projecting, and nearly doubles usable atlas area. Do not insert an average_islands_scale before it — that collapsed coverage to 0.6%.

Report: welded 90,120 -> 85,479 verts, unwrapped, islands cover 45.1%, or already welded, unwrapped, islands cover 45.1%.

Turn it off when the atlas on the mesh is the deliverable. Unwrapping throws away the very texture layout you are trying to keep.

12. Triangulate — triangulate

bmesh.ops.triangulate with the BEAUTY method for both quads and n-gons. No settings — the drawer says so.

The bake, the glTF exporter and every viewer triangulate eventually. Doing it here, deterministically and before the bake, means the mesh that ships is the mesh that was baked; a mismatch shows up as warped detail.

Report: triangulated 41,880 -> 78,220 faces

Unwrap must come before this. Smart UV Project grows charts across whole n-gons; hand it a triangulated mesh and it has three times the edges to treat as chart boundaries. Triangulating afterwards splits faces along existing loops and carries their UVs along, so the atlas comes through unchanged. Measured 1.03x more usable area — small, but free. The order changed in 0.12.0.

Turn it off for a mesh whose only consumer is Blender, where the n-gon panels are the point. The KIT OPS INSERT cleanup leaves it out.

13. Shade Auto Smooth — auto_smooth

Adds Blender’s Smooth by Angle modifier — the same thing Object → Shade Auto Smooth adds — and leaves it live on the object.

setting label default range
auto_smooth_angle Smooth Angle 10° 0° - 180°

The Shade Auto Smooth step's settings

  1. Smooth Angle — edges sharper than this stay hard. Ten degrees.
  2. The modifier is left live, not applied, so the angle stays adjustable after the run.

Ten degrees is low on purpose. By this point the mesh is flat panels with real corners between them, and Blender’s own default of 30° smooths straight across the shallower ones — undoing on screen what the dissolve and planar walk just built in geometry. Raise it if a protected curved surface still facets; drop it to 0 to shade everything flat.

The modifier is not applied. The angle is the one value worth nudging, Blender’s bake evaluates modifiers so the smoothing is present in the bake without being burned into the mesh, and the glTF exporter evaluates them too — so it ships correctly either way. Re-running the step replaces the modifier rather than stacking a second one.

It runs BEFORE the bake, and that matters

0.15.0 put this step last, after the bake. That was wrong. The argument was that the bake reads shading off the original, so a modifier on the target could not skew it. That holds for colour, roughness and metallic — and not for the normal map.

A tangent-space normal bake encodes the difference between the source surface and the target’s shading normals. The map is therefore only correct for the normals the target carried while it was baked. Smooth the target afterwards and you have changed exactly the thing the map was measured against: the normal map that ships no longer matches the mesh it is painted on.

Since 0.20.0 it is step 13, immediately before the bake, so the normal map is baked against the shading the mesh actually ships with.

This step needs step 5. A custom split normal overrides whatever Smooth by Angle computes, so on a mesh that still carries the ones it arrived with, this step appears to do nothing at all.

Report: auto smooth at 10 deg.

There is a second form: auto smooth at 10 deg (node group appended directly -- asset library was not loaded). Blender’s operator appends the Smooth by Angle node group from its essentials asset library, and headless Blender loads that library asynchronously — on 4.5.10 under -b it prints “Asset loading is unfinished”, returns CANCELLED and adds nothing at all. The step checks the modifier really arrived and, if it did not, appends the node group straight from <blender>/<version>/datafiles/assets/geometry_nodes/smooth_by_angle.blend instead. The result is identical; the longer message tells you which route ran. If neither works the step raises rather than returning a soft mesh. Measured on 4.5, 5.1 and 5.2: a 32-sided cylinder gets 96 sharp edges at 10° and 64 at 45°.

Turn it off when the shading is somebody else’s job, or when you want the object to carry no modifiers at all.

14. Bake Textures — bake

Bakes PBR maps from the hidden original onto the sharpened mesh, selected to active, in Cycles.

It finds the source through the sharpen_source custom property, falling back to the object name minus _sharp. It raises, loudly, if:

  • there is no source — “no source to bake from – run ‘Copy & Hide Original’ first”
  • the source has no node material
  • the target has no UVs — “target has no UVs – run ‘Unwrap’ first”
  • no maps are selected
setting label default
bake_diffuse Color on
bake_normal Normal on
bake_roughness Rough on
bake_metallic Metal on
bake_resolution Size Match Source (or 1024 / 2048 / 4096 / 8192)
bake_res_diffuse Color size Follow Bake Size
bake_res_normal Normal size Follow Bake Size
bake_res_roughness Rough size Follow Bake Size
bake_res_metallic Metal size Follow Bake Size

The Bake Textures step's settings

  1. The four map toggles — Color, Normal, Rough and Metal. Unticked maps are not baked at all.
  2. Size — Match Source by default, which sizes each map from the texture feeding that channel on the original.
  3. Per-map sizes — a nested drawer, shut by default, holding one size override per channel.
  4. A per-channel override — each defaults to Follow Bake Size, so the common case stays one control.

Each map is sized from its own source texture

Size defaults to Match Source, and it matches per channel, not once for the run. An AI-generated asset rarely ships four maps at one size — a measured example carries a 2048 colour map beside 1024 normal, roughness and metallic — and one number for all four either wastes memory on three of them or throws away half the colour detail.

So each map is sized from the texture feeding that Principled input on the original. The lookup walks back through intervening nodes, so a normal map reached through a Normal Map node is found the same as a colour map wired straight in. Non-power-of-two sources round up: a 1000px roughness map bakes at 1024. Sizes are clamped to 1024-8192.

Two fallbacks, both stated in the report rather than assumed:

  • A channel with no image — a constant roughness, say — takes the size of the largest map on the object, so the set stays consistent.
  • A source with no images at all falls back to 4096.

Overrides. Every channel has its own size setting, shut away under Per-map sizes in the drawer. Each defaults to Follow Bake Size. The order is: the channel’s own setting, then Size, then Match Source. Setting Size to a number still drives every map, so s.bake_resolution = '1024' in an existing script behaves exactly as it did.

The console prints every map’s size and the reason before the first bake, so a long run says up front what it is going to make:

[sharpen_hard] diffuse -> 2048px (source base color is 2048px)
[sharpen_hard] normal -> 1024px (source normal is 1024px)
[sharpen_hard] roughness -> 1024px (source roughness is 1000px -> 1024)
[sharpen_hard] metallic -> 1024px (no metallic map, matched the largest (2048px))

What it does, in order

  1. Unhides both objects, clears any preview paint, and puts the viewport back to Material colours.
  2. Builds a fresh material <target>_baked holding one Principled BSDF, and replaces the target’s materials with it.
  3. Switches to Cycles at 4 samples and takes the first GPU backend that answers — OPTIX, CUDA, HIP, METAL, ONEAPI — so NVIDIA, AMD, Apple silicon and Intel Arc all get their card. Failing all of them it uses the CPU and says so: the console prints [sharpen_hard] baking on <device> either way, because a bake that quietly drops to CPU just looks broken-slow. The previous render engine is restored at the end.
  4. Measures the surface deviation — the 99th-percentile distance from sampled target vertices to the nearest point on the source — and sizes the cage from it: cage = clamp(deviation × 2, diagonal × 0.01, diagonal × 0.25) and ray = cage × 2.5. Guessing the cage as a fixed fraction of the bounding box failed on a control console that drifted 7.3% of its diagonal during sharpening: rays missed and the atlas came back 30% lit.
  5. For each map: creates the image, prefills it with magenta — a colour the bake cannot produce, so a ray miss can be told from a legitimately black texel — bakes, counts what was filled, repaints any remaining magenta neutral (mid-blue for the normal map, black otherwise) and packs the image into the .blend.
  6. Wires the results into the Principled: colour to Base Color, roughness to Roughness, metallic to Metallic, and the normal map through a Normal Map node.
  7. Re-hides the original, three ways.

Everything but the normal map is baked as EMIT

The colour, roughness and metallic channels are temporarily rewired through an Emission shader on the source material and baked with type='EMIT'. Only the normal map uses a native pass.

Measured 2026-07-27 on one ship: the native DIFFUSE pass, even colour-only, lit 2.2% of texels — a black atlas — while the identical setup through EMIT lit 97.7%. This is what made baking “never work very well”. EMIT returns exactly the socket value, with no shading, no light paths and no pass-filter subtleties. Verified: colour 97.7%, roughness 99.7%, metallic 99.7%.

Images

The maps are named <target>_diffuse, <target>_normal, <target>_roughness and <target>_metallic, and they are packed into the .blend, not written to disk. Colour is sRGB; the rest are Non-Color. Save the file or export the object to get files out.

Report: baked 4 maps in 26.0s (deviation 1.23%): diffuse 2048px 97%, normal 1024px 99%, roughness 1024px 99%, metallic 1024px 99%

Each map carries its own size, because with Match Source they are routinely different and one number would misreport three of them.

The console adds a line per map with the time, the fill percentage and the island coverage:

[sharpen_hard] deviation p99 1.23% of diagonal -> cage 0.0246, ray 0.0615
[sharpen_hard] baked DIFFUSE 2048px in 11.2s, filled 97.7% of atlas (islands cover 45.1%)

A map that filled less than 85% of what its islands cover is flagged <-- SUSPECT, rays missed in the console and appended to the panel report as WARNING: DIFFUSE filled only 30.1% vs 45.1% island coverage. That is a real failure, not a cosmetic one — do not ship the result.

Turn it off when something else makes the texture. The pipeline does: it sends the sharpened mesh back to Trellis for a re-texture instead, because the bake is a transfer and reproduces the source atlas faithfully, flaws included, while Trellis regenerates from the concept image. Measured on a mining tug: the bake took 13 s and Trellis 88 s, and the side-by-side call went to Trellis anyway — the source atlas carries a muddy yellow-green wash that the bake reproduces exactly, and Trellis came back with clean colour separation and crisper panel lines. (Do not compare the two on atlas PSNR. The baked atlas fills the space around its islands with shredded noise, roughly 40% of the image, and the metric reads that noise as detail.)

The bake stays in the add-on because it is the right tool when a faithful copy is what you want — and it is the only one of the two that produces a normal map.


Recipes

Five chains that are known to work.

1. The full chain — sharpen and re-bake

Use it when you want one crisp, textured object out of one soft, textured one, in Blender, with no other tool involved.

Everything checked, Sharpen slider in the middle, Run Checked Steps. With Sharpen Cycles at 2 that is:

copy → weld → [manifold_early] → decimate → clear_normals → detect
     → (dissolve_coarse → planar_a → dissolve_fine → planar_b) × 2
     → unwrap → triangulate → bake → auto_smooth

You end up with <name>_sharp carrying a fresh atlas and four packed images, and the original hidden beside it as the bake source. Leave the original in the file: deleting it breaks a re-bake.

Make Manifold and Make Planar B start unchecked. Turn Make Manifold on only when the dissolve is stalling on open edges.

2. Geometry only — sharpen, then texture somewhere else

Use it when something else will paint the mesh. This is what the repo’s pipeline does: it sharpens, then sends the result back to Trellis for a re-texture from the original concept image.

Everything but the bake:

copy → weld → decimate → clear_normals → detect
     → (dissolve_coarse → planar_a → dissolve_fine → planar_b) × cycles
     → unwrap → triangulate → auto_smooth

Headless, D:\GitHub\model-roboto\scripts\sharpen_for_trellis.py:

blender.exe -b -P "D:\GitHub\model-roboto\scripts\sharpen_for_trellis.py" -- ^
    --glb model_pbr.glb --out model_sharp.glb ^
    [--amount 0.5] [--target-faces 200000] [--sharpen-cycles 2] ^
    [--no-planar] [--no-detect] [--manifold] [--manifold-timeout 1800]

Three things that silently ruin this if changed:

  1. Export the sharpened object alone. The copy step hides the original rather than deleting it, and Trellis’s loader merges every mesh in the file. Ship both and it textures them interpenetrating. Export with use_selection=True, use_visible=False — that keeps the hidden original out without unhiding it, deleting it, or touching its hide flags.
  2. The export must carry UVs. With them Trellis preserves the layout exactly; without them it falls back to its own unwrap — 178,026 per-triangle islands against 42,824 charts, at 0.30 density against 0.40. The stage refuses to export a mesh with no UV layer.
  3. Unwrap before triangulate. Worth 1.03x on its own. The weld inside unwrap is the part that matters (1.86x), and the chain already welded at step 2.

Note --sharpen-cycles, not --cycles: Blender’s own argument parser claims --cycles even after --, as an ambiguous match for --cycles-device.

Use it when you only need the face budget and a usable atlas.

copy → weld → decimate → unwrap → triangulate

Steps 1, 2, 4, 11, 12. Nothing in it is decoration: the weld because a glTF import carries no vertex adjacency, the decimate because of the budget, and the unwrap and triangulate because the decimate just destroyed the atlas.

Measured on the test ship: 815,884 faces to 199,999 in 22 seconds, atlas coverage 39.1%.

blender.exe -b -P "D:\GitHub\model-roboto\scripts\sharpen_for_trellis.py" -- ^
    --glb model_pbr.glb --out model_sharp.glb --minimal

4. Clean a mesh that already carries its final texture

Use it when the atlas on the mesh is the deliverable — a textured GLB you must not re-unwrap.

Steps 2, 9 and 10 only — Weld Vertices, Dissolve (Fine), Make Planar B — with Keep UV Seams on.

The mesh arriving from a glTF import is split at every UV seam and has no adjacency at all, so the weld has to come first or the dissolve stops at invisible walls and the planar walk sees no neighbours. What you get instead of near-coplanar triangle mush is flat n-gon panels. Measured on one textured prop: 26,307 faces → 18,415, texture unchanged.

The three steps that are absent matter as much as the three that are:

  • No Copy. It would leave a second mesh in the file.
  • No Unwrap. The atlas is the thing you are protecting.
  • No Triangulate. N-gons are the point.

And the delimit is the whole reason this chain is different: with the texture already painted, one face spanning two islands samples both. Measured 3.29% of seam edges eaten without the delimit against 0.56% with, for 1.2% fewer faces dissolved.

The implementation is cleanup_for_insert() in D:\GitHub\model-roboto\scripts\kpack_stage.py. It runs after the decimate, not before — Mesh Press triangulates on its way to the face budget and would undo the panels.

s = bpy.context.scene.sharpen_hard
s.sharpen_amount = 0.5          # writes the derived dissolve knobs
s.dissolve_delimit_uv = True
by_id = {sid: fn for sid, _l, _e, _x, fn in sharpen_hard.STEPS}
cur = obj
for sid in ("weld", "dissolve_fine", "planar_b"):
    cur, msg = by_id[sid](bpy.context, s, cur)

Check that the UV layer survived. That stage raises if it did not.

5. Tuning, by hand

Use it when you do not yet know what the mesh needs.

  1. Run 1. Copy & Hide Original with its ▶ button.
  2. Run 2. Weld Vertices. Look at the percentage.
  3. Open 6. Detect Curved Surfaces, set Min Radius %, press Preview Curved. Orange is protected, blue-grey will be sharpened. Adjust and preview again — it never touches geometry. Press ✕ to clear.
  4. Run 4. Decimate and 5. Clear Custom Normals, then 6. Detect Curved Surfaces for real.
  5. Run 7 through 10 one at a time, reading faces, mushy, crisp and drift after each. Repeat the four as many times as the mesh keeps improving.
  6. Correct the detector by hand if it got something wrong: in Edit Mode, select vertices and assign or remove them from the curves vertex group. A face is protected only when all its vertices are in the group.
  7. Finish with 11, 12, 13 and 14.

Undo works — every operator is REGISTER | UNDO.

Where the pipeline uses each recipe

Script Chain
D:\GitHub\model-roboto\scripts\sharpen_for_trellis.py Recipe 2, or recipe 3 with --minimal
D:\GitHub\model-roboto\scripts\kpack_stage.py Recipe 4 (cleanup_for_insert)
D:\GitHub\model-roboto\scripts\kpack_sharp_stage.py Recipe 1, straight through the bake
D:\GitHub\model-roboto\scripts\bench\sharpen_arm.py Recipe 2 split in two: export after the cycles, then unwrap + triangulate + bake and export again

Both kpack_sharp_stage.py and sharpen_arm.py leave Detect Curved Surfaces off by default: those subjects are meant to be curve-free, and protection only holds back the sharpening.


Scripting

Through the operators

bpy.ops.mesh.sharpen_step(step='weld')     # one step, exactly once
bpy.ops.mesh.sharpen_run_all()             # every checked step, with cycles
bpy.ops.mesh.sharpen_preview()             # paint the detector's result
bpy.ops.mesh.sharpen_preview_clear()
bpy.ops.mesh.sharpen_install_repair()      # download the WinRT packages
bpy.ops.mesh.sharpen_import_glb(filepath=r"D:\in.glb")   # selects + activates
bpy.ops.mesh.sharpen_export_glb(filepath=r"D:\out.glb")  # selection only

sharpen_step and sharpen_run_all need an active mesh object in Object Mode. Both return {'CANCELLED'} and report the error on failure; sharpen_run_all also returns {'CANCELLED'} with a warning if nothing is checked. The full per-step log is in bpy.context.scene.sharpen_hard.last_report, one line per step plus a total <n>s line — read it rather than guessing which steps ran.

Settings live on the scene: bpy.context.scene.sharpen_hard.

Through the step functions

This is what every pipeline script does. It skips the checkboxes and the operator poll, and gives you the message string directly:

by_id = {sid: fn for sid, _label, _enable, _expand, fn in sharpen_hard.STEPS}

ctx = bpy.context
s = ctx.scene.sharpen_hard
s.sharpen_amount = 0.5          # FIRST -- it overwrites the derived knobs
s.target_faces = 250_000

cur = obj
for sid in ["copy", "weld", "decimate", "clear_normals", "detect",
            "dissolve_coarse", "planar_a", "dissolve_fine", "planar_b",
            "dissolve_coarse", "planar_a", "dissolve_fine", "planar_b",
            "unwrap", "triangulate", "auto_smooth"]:
    cur, msg = by_id[sid](ctx, s, cur)
    print(f"  [{sid}] {msg}", flush=True)

Three rules the existing callers all follow:

  • Thread the object through. copy returns a different object from the one it was given. Ignore the return value and every later step runs on the original.
  • Select and activate the object first. Several steps drive Blender operators (modifier_apply, smart_project, bake) that work on the selection.
  • Check the step ids exist, and fail loudly if they do not:
missing = [x for x in steps if x not in by_id]
if missing:
    raise SystemExit("FAIL: sharpen_hard has no step(s) %s -- it has %s"
                     % (missing, sorted(by_id)))

The useful module-level names are STEPS (the registry tuple), SHARPEN_BLOCK (the four ids the cycle repeats) and _VGROUP (the string "curves").

If you are baking

The bake follows sharpen_source back to the hidden original. Before it runs, check the link is intact — a silently missing source produces a black atlas and a plausible-looking GLB. assert_bake_source_intact() in D:\GitHub\model-roboto\scripts\bench\sharpen_arm.py checks that the property is still there, that the object still exists in bpy.data, that it is not the target itself, and that it still has a node material.


Troubleshooting and traps

Each of these was measured. Where a number is quoted, it came from a real run.

Blender freezes while a step runs

Expected. Every operator here blocks: the work happens inside execute(), so Blender will not repaint on its own.

The add-on paints the step name in the lower left of the 3D viewport in orange-red (#fe4023) while it works, and flashes teal (#3fbba9) for one second when it finishes. A failure stays up for four seconds. It forces the repaint itself, because nothing else will. The status bar and the cursor progress carry the same message, and the console gets everything regardless — including headless runs, where the overlay does not exist.

If the viewport is blank and silent, look at the console. Every line is prefixed [sharpen_hard].

Make Manifold is the slowest. It blocks on a process outside Blender. Measured 38 s on 814k faces, and it grows with the mesh, which is why the step announces the face count and says “this can take a minute, please wait” before it starts.

The UV atlas is destroyed. That is the design

Sharpening kills UVs, and both Decimate and Make Manifold kill them outright. Steps 11-13 exist to rebuild the atlas and bake the textures back from the untouched original.

Coverage alone will not tell you. Measured on one sharpened subject, coverage improved from 78.9% to 96.3% while the overlap ratio went from 0.837 to 50.2 — the charts stack about fifty deep. It looks like a win and is unusable.

If you must keep the atlas, do not run the sharpening chain. Use recipe 4: weld, dissolve fine, planar B, with Keep UV Seams on.

Unwrapping alone gives a low-density atlas

Smart UV Project grows charts from vertex adjacency, and a mesh imported from glTF has none — every triangle carries its own three vertices. Unwrapping that gives near-per-triangle islands at half the density, and reports success.

Step 11 welds first, for that reason. Measured on one sharpened ship: straight from the GLB, 534,956 verts and UV area 0.2155; welded first, 85,479 verts and UV area 0.4004 — 1.86x.

Running the whole chain hides this, because step 2 already welded. It only bites when the unwrap runs on its own, which is what every headless or per-file workflow does. If you set Weld Distance to 0, step 11 skips its weld and you are back to the bad case.

Unwrap has to run before Triangulate

Smart UV Project grows charts across whole n-gons. Hand it a triangulated mesh and it has three times the edges to treat as chart boundaries. Triangulating afterwards splits faces along existing loops and carries their UVs along, so the atlas comes through unchanged — checked, every coordinate identical. Measured 1.03x more usable area.

The registry order changed in 0.12.0. If you build a chain by hand, keep unwrap before triangulate and bake last.

Make Manifold belongs before Decimate, and nowhere else

Running it again after the sharpening cycles undoes them. The engine remeshes, so it hands back triangles where the dissolve had just built flat n-gon panels. A manifold_late step shipped in 0.11.0 and was removed in 0.12.0.

Its purpose here is to unblock limited dissolve, which stops dead at open and non-manifold edges — the same failure the weld exists to fix, and one the weld cannot reach. Decimate then trims the roughly 43% extra faces the repair adds.

“No repair support for cp313 (this Blender’s Python)”

The winrt wheels are compiled per Python version. Blender 5.0 runs Python 3.11, Blender 5.1 and 5.2 run 3.13. A set installed by one is useless to the other, and this used to report ready and then die on No module named 'winrt._winrt' — the 0.11.1 bug.

Press Install Repair Support, either in Preferences → Add-ons → Sharpen Hard or in step 3’s own drawer in the N-panel. It installs to libs\<tag>\ for this interpreter only. Full detail: Repair support for step 3.

If the worker reports MISSING_DEPS:, the add-on appends “press Install Repair Support in the add-on preferences” to the message. Installing the wheels one at a time is the other way to get here — pip install --target --upgrade prunes the target, so each install deletes the last. Pass all five in one call.

The repair times out

repair did not finish within 600 s -- raise the timeout, or the mesh may be beyond this engine.

Raise Timeout (s) (max 3600). The pipeline uses 1800, because the add-on’s 600 is fine interactively and too tight for a batch — measured 37 s on a clean ship and a timeout on a busier prop.

There is deliberately no fallback. A mesh reported as repaired that was never repaired poisons every later step silently.

“Clean After Repair” reopens the mesh

It says so in its own description, and the measurement is in D:\GitHub\model-roboto\docs\WINDOWS_MESH_REPAIR.md. Every merge threshold tested on the sealed 237k-face result broke the seal, and bowtie counts went up, not down:

after repair boundary nm-edge nm-vert zero-area shut
untouched 0 0 10,460 2,897 yes
merge 1e-5, degen 1e-5 105 149 10,487 1,918 no
merge 1e-4, degen 1e-4 1,046 4,477 11,327 95 no

The closure depends on coincident-but-distinct vertices the engine kept on purpose. The option exists anyway because sharpen re-unwraps and re-bakes regardless, so a reopened surface may still be the better dissolve input. Measure it; do not assume it.

Curved surfaces come back faceted

Run 5. Detect Curved Surfaces before the dissolve and planar steps. Without it a nacelle, tube or dome is flattened into panels like everything else.

Then check the result with Preview Curved before committing: orange is protected, blue-grey will be sharpened. Raise or lower Min Radius % and preview again.

If the detector protects nothing on an obviously curved model, the curve is probably below the radius band — the floor is raised to keep smoothing’s own rounded corners from qualifying, and a region also has to hold at least 64 faces, carry enough candidate edges, and sweep at least 25 degrees of normal. Correct it by hand: select the vertices in Edit Mode and add them to the curves vertex group. A face is protected only when all its vertices are in the group.

Detect must run once, on pristine geometry. After a dissolve leaves a few giant faces, the median edge length explodes and the detector’s radius floor silently disables protection. That is why Sharpen Cycles never repeats it.

Fine detail is smeared

Two causes, both measured, both a trade rather than a bug.

The planar steps. They move the surface about 9x more than dissolve alone — 0.018% mean deviation against 0.002%, consistent across two very different subjects — for roughly 5-6% more absolute sharp edge. In the render, louvre slats survive as distinct lines without them and are smeared into mounds with them. Uncheck 7. Make Planar A and 9. Make Planar B, or pass --no-planar to the pipeline scripts.

The dissolve angle. On these meshes a 90-degree corner is a chamfer of several triangles each turning 10-25 degrees — and a louvre slat edge is also a chamfer of triangles turning 10-25 degrees. A single global threshold cannot tell a corner it should crisp from a detail it should keep, because on this geometry they are the same measurement. The sweep is monotonic with no knee: at 8 degrees the detail survives and the sharpness gain is exactly zero; at 20 the sharpness is up 1.25x and the detail is going.

So sharpening and detail preservation are the same dial. Picking a number only picks a point on that line.

The bake comes back black, or mostly empty

The step flags it itself. A map that filled less than 85% of what its islands cover is printed with <-- SUSPECT, rays missed and appended to the panel report as a WARNING:. Treat that as a failure.

Check, in order:

  • Did step 1 run? The bake follows the sharpen_source custom property back to the original. Without it: “no source to bake from – run ‘Copy & Hide Original’ first”.
  • Is the source still there, and still textured? Deleting it, or clearing the property, is the classic way to get a plausible GLB with a black atlas.
  • Did step 11 run? “target has no UVs – run ‘Unwrap’ first”.
  • Rays missing means the cage could not span the gap between the two surfaces. The step sizes the cage from the measured 99th-percentile deviation, which fixed a control console that drifted 7.3% of its diagonal — the old fixed 3%/6% cage could not reach and the atlas came back 30% lit. If it still misses, the surfaces have moved further than the clamp allows (25% of the diagonal); sharpen less.

Magenta never ships: unfilled texels are prefilled with a colour the bake cannot produce, counted, and then repainted black — or mid-blue on the normal map — before the image is packed.

An all-black colour map with a high fill percentage is a different thing and was the old failure this step fixed: the native Cycles DIFFUSE pass lit 2.2% of texels on one ship where an EMIT bake of the same setup lit 97.7%. Everything but the normal map is baked through EMIT now.

The baked images are not on disk

They are packed into the .blend, named <object>_diffuse, <object>_normal, <object>_roughness, <object>_metallic. Save the file, export the object, or unpack them from the Image editor.

Nothing happens when I press a button

  • Run Checked Steps reports “no steps checked” and cancels if every box is clear.
  • Every run operator needs an active mesh object in Object Mode. In Edit Mode the buttons are greyed out.
  • Clear Preview is only enabled when the SharpenPreview colour attribute exists.
  • Decimate reports already <n> tris, under target -- skipped when the mesh is inside the budget already. That is not a failure.

Preview shows nothing

The preview forces the viewport to Solid shading with Attribute colour, because attribute colours do not render in Material Preview. If you switch shading back yourself the paint disappears.

The unprotected colour is a distinct blue-grey rather than the default viewport grey, precisely so preview mode is obvious even when nothing is protected.

If the weld changed the face count, the operator warns that “preview indices may be approximate” — the detection runs on a throwaway welded copy so it sees the same graph the real run will.

Setting the amount from a script wiped my values

sharpen_amount has an update callback that writes the two dissolve angles, both planar iteration counts, both factors and the cycle count. Set the amount first, then apply overrides. Hand-edited values then survive until the amount changes again.

And convert degrees to radians. angle_coarse and angle_fine are ANGLE properties capped at 60° and 15°; pass degrees straight in and Blender clamps without complaint. A sweep asking for 10, 14 and 17.8 degrees ran three identical experiments at 60 degrees and looked clean the whole way.

Headless: the add-on will not register

  • Never call bpy.ops.wm.read_factory_settings(). It resets preferences, which unregisters every add-on. The failure looks like a missing module. Use bpy.ops.wm.read_homefile(use_empty=True).
  • Disable an extension install of the same id before registering from the repo. Registering twice makes the second registration steal every class from the first.
  • Prove the registration landed: assert hasattr(bpy.context.scene, "sharpen_hard").

Leftover working state in a shipped asset

Two things the chain leaves on the object are working state, not asset data:

  • the curves vertex group from step 6
  • the sharpen_source custom property from step 1

D:\GitHub\model-roboto\scripts\kpack_sharp_stage.py strips both before saving an INSERT. A SharpenPreview colour attribute is cleared by the dissolve, planar and bake steps, and by Clear Preview.

The metrics lie in two known ways

  • mushy and crisp cannot see what the planar steps do. They measure the dihedral distribution, not coplanarity. Eight planar passes across two subjects all reported no change, and the steps were still doing their job — removing them produced more faces, not fewer.
  • Deviation is nearly blind to detail smoothing. Flattened louvres still sit within 0.66% of the original surface, so the number shrugs while the model visibly degrades. Deviation catches displacement, not loss of high-frequency detail.

Only the render catches the second one. Never accept a metric improvement without looking at the model.


Version history

Current: 0.20.0, from D:\GitHub\sharpen_hard\blender_manifest.toml. The panel header shows the manifest version, so it always matches what is installed.

From 0.12.13 on, the changelog is D:\GitHub\sharpen_hard\Changes.md. Earlier entries came from D:\GitHub\model-roboto\Changes.md, where this add-on’s history was kept under its old name. Only the versions recorded there are listed. 0.12.1 through 0.12.10 have no entries — that is a gap in the record, not a claim that nothing changed.

0.20.0 — 2026-08-02

  • Shade Auto Smooth moved before Bake Textures — it is now step 13 and the bake is step 14. A tangent-space normal bake encodes the difference between the source surface and the target’s shading normals, so smoothing after the bake left the shipped normal map disagreeing with the mesh it is painted on.
  • Target Faces now defaults to 250,000, up from 200,000.

0.19.1 — 2026-08-02

  • The Sharpen slider’s midpoint now matches the panel. At 0.5 the coarse dissolve angle was 25°, but angle_coarse defaults to 20°, so an untouched scene read 20 and silently jumped to 25 the moment the slider moved. The range is back to 10-30. Every other derived value already agreed with its default.

0.19.0 — 2026-08-02

  • Triangulate now starts unchecked. The flat n-gon panels the sharpening just built are usually what you want to keep; triangulating throws that readable topology away for anyone who is not exporting straight to an engine that demands triangles. Turn it on when the target needs it.

0.18.1 — 2026-08-02

  • Internal only: ARCHITECTURE.md refreshed for 0.14.0-0.18.0. No change to any step, setting or default.

0.18.0 — 2026-08-02

  • The PyMeshLab decimate engine is gone, one version after it arrived. Measured against Blender’s own modifier on an 814k-face ship: clustering ran in 1.1s against 9.5s but tessellated flat panels as finely as creases (12.7% crisp edges against 25.3%, and 20.5% under target), and PyMeshLab’s quadric collapse was slower at 10.9s AND worse at 14.1%. Blender wins this job outright, so the Engine dropdown, the Timeout, the PyMeshLab installer and both modules are removed. See 4. Decimate for the table.

0.17.0 — 2026-08-02

  • Bake sizes each map from its own source texture. Size defaults to Match Source and matches per channel: a source with a 2048 colour map and 1024 normal/roughness/metallic now bakes exactly that mix instead of flattening all four to one size. Non-power-of-two sources round up, sizes clamp to 1024-8192, and both fallbacks (no map on a channel, no images at all) are stated in the report.
  • Per-map size overrides under “Per-map sizes” in the Bake drawer, each defaulting to Follow Bake Size. 8192 is now offered, and the report carries each map’s size.

0.16.0 — 2026-08-02

  • A fast Decimate engine, through PyMeshLab. Step 4 gains an Engine choice: Auto, PyMeshLab Clustering or Blender Collapse. Measured 8.5x faster on an 814k-face ship and 12.1x on a 1.96M-face dwarf — but clustering is a grid, so it lands near Target Faces rather than on it (−20.5% and +9.6%) and comes out a few points less crisp after the sharpening cycles. Auto falls back to Blender’s collapse when PyMeshLab is absent and names the engine it used.
  • Installers for both dependencies in preferences. PyMeshLab and the Windows repair engine now sit side by side in one Dependencies block, each with a status line and an Install button. The Decimate drawer in the N-panel also shows whether PyMeshLab is installed, and offers the button when it is not.
  • Make Manifold reads “unable to be used in that slot” on Mac and Linux rather than “Windows only”. The step is never removed from the list.

0.15.0 — 2026-08-02

  • Two new steps. 5. Clear Custom Normals drops the custom split normals an AI mesh arrives with — they were baked for the soft original surface and shaded the sharpened panels as if they were still curved. 14. Shade Auto Smooth adds the Smooth by Angle modifier at 10 degrees, last in the chain. Both are checked by default.
  • Shade Auto Smooth checks its own work. Blender’s operator appends the node group from the essentials asset library, which headless Blender loads asynchronously — on 4.5.10 -b it returns CANCELLED and adds nothing. The step now appends the node group straight off disk when that happens, and says so in its report.
  • The N-panel tab reads ♥SH, matching the rest of the add-on family. The panel is still called Sharpen Hard.
  • Make Manifold and Make Planar B start unchecked. Make Manifold was on by default on Windows; it is a slow, heavy repair most meshes do not need.

0.14.0 — 2026-07-29

  • Detect Curved Surfaces stops protecting boxes and isolated trim. Two new region filters: a discreteness veto (a box concentrates at least 38% of its area on 3 flat normal directions, a real barrel at most 34%) and an assembly-size floor (real curved surface arrives in clusters worth 2.5-3.3% of mesh area, junk arrives alone at 0.6% or less). The mining tug now protects exactly its six nacelle barrels; an all-box inspection machine protects nothing, where it used to protect 14 regions.

0.13.1 — 2026-07-29

  • Mac and Linux: the first run no longer dies at step 3. Make Manifold is now unchecked by default where it cannot run, and its box is flagged Windows only on the closed box rather than inside the shut drawer.
  • Bakes use the GPU on Mac, AMD and Intel Arc, not just NVIDIA — the device picker now tries HIP, METAL and ONEAPI too, and prints which device it got.

0.13.0 — 2026-07-29

  • The panel header carries the version and a docs link. A ? in the panel’s own header bar opens this manual; the version sits beside it. Both survive the panel being collapsed.
  • Import GLB and Export GLB, in a File box at the bottom of the panel. Export writes only the selected objects and skips hidden ones, so the original that step 1 hid stays out of it; import leaves what it brought in selected and active, ready for step 1, and does not join multiple objects.
  • Built zips no longer carry docs/ or developer notes.

0.12.13 — 2026-07-28

  • Renamed to Sharpen Hard. The add-on was called Sharpen Model; its extension id changed from sharpen_model to sharpen_hard and the scene settings moved from scene.sharpen_model to scene.sharpen_hard. Operator names are unchanged. It also left the retopo-roboto repo for one of its own, D:\GitHub\sharpen_hard. Remove any older install first — the old id is a separate extension as far as Blender is concerned, and two copies fight over the same operator names.

0.12.12 — 2026-07-28

  • Dissolve can keep UV seams. A new Keep UV Seams option on both dissolve steps, off by default. The normal chain dissolves before Unwrap, where island boundaries are about to be rebuilt anyway; with it on, the dissolve stops at them, which is what a mesh that already carries its final texture needs. Measured on a textured crate: 3.29% of seam edges eaten without it against 0.56% with, for 1.2% fewer faces dissolved.

Same day, in the pipeline rather than the add-on: KIT OPS INSERTs are now cleaned with steps 2, 8 and 9 before they are saved (props/0021: 26,307 faces to 18,415, texture unchanged), and step 3, Make Manifold, was turned off in the batch chain — measured on three finished props it either over-flattens or leaves litter the dissolve tears into shards, for 3-4x the sharpen time.

0.12.11 — 2026-07-28

  • The coarse dissolve is 25 degrees at the default slider position, up from 20. The slider range moved from 10-30 to 15-35, so it still means the same thing end to end.

0.12.0 — 2026-07-27

  • Unwrap now runs before Triangulate. Smart UV Project grows charts across whole faces, so unwrapping the n-gon mesh gives it fewer edges to treat as chart boundaries. Triangulating afterwards splits along existing loops and carries the UVs with it — checked, and the atlas comes through with every coordinate unchanged. Bake still runs last, so the mesh that ships is still the mesh that was baked.
  • Removed the second Make Manifold. Repairing after the sharpening cycles undid them: the engine remeshes, handing back triangles where the dissolve passes had just built flat panels. The one before Decimate stays, which is where it earns its keep.
  • The Make Manifold step now says how long it will take and how big the mesh is, and puts a line up before each of the two measuring passes. The viewport cannot repaint while the repair runs, so silence read as a hang.

0.11.1 — 2026-07-27

  • Fixed: Make Manifold failed in Blender 5.1 and 5.2. The repair support is compiled against one Python version, and Blender 5.0 uses 3.11 while 5.1 and 5.2 use 3.13. The add-on only checked that the files were there, so it said it was ready and then died on No module named 'winrt._winrt'. Support is now kept per Python version, and each Blender installs and finds its own. An existing install still works where it always did.
  • The message that failure produced named nothing useful — it quoted a footnote about pip. It now says which Python has no support and what to press.

0.11.0 — 2026-07-27

  • Make Manifold no longer needs the Make Manifold add-on. The Windows repair engine now ships inside Sharpen Hard, so the step works on a machine that has nothing else installed. Preferences → Add-ons → Sharpen Hard has an Install Repair Support button, and the step in the N-panel says so before a run starts if the support is missing. If Make Manifold is installed too, both add-ons share the one 3.5 MB download.

2026-07-27, no version recorded

  • Fixed: the unwrap silently halved the atlas. Smart UV Project grows charts from vertex adjacency, and a mesh imported from a GLB has none, so unwrapping a fresh import produced near-per-triangle islands at half the texture density and reported it as success. It now welds first and says which it did. Measured 1.86x more usable atlas.
  • Recommended, from the bench: re-texture the sharpened mesh with Trellis rather than baking in Blender. The bake is a faithful transfer and reproduces the source atlas including its flaws; Trellis regenerates from the concept image. The bake remains in the add-on.
  • Recommended, from the bench: drop the planar steps. They move the surface about nine times more for roughly five percent more sharpness, and they are what smears fine detail such as louvre slats. They remain on by default.

  • D:\GitHub\model-roboto\ARCHITECTURE.md — where this add-on sits in the pipeline.
  • D:\GitHub\model-roboto\docs\GEN_MODELS_STEPS.md — how the batch pipeline drives this add-on headlessly.
  • D:\GitHub\model-roboto\docs\WINDOWS_MESH_REPAIR.md — the Windows repair engine, measured.
  • D:\GitHub\model-roboto\docs\SHARPEN_BENCH_RESULTS.md — the bench behind most of the numbers quoted here.