ShadeProof — Documentation (v1.2.2)

Installing

Download the zip and leave it zipped. In Blender open Edit, then Preferences, then Add-ons, use Install from Disk and pick the zip. Tick the checkbox next to the add-on name. Press N in the 3D Viewport; the ShadeProof tab appears in the sidebar.

Explain This Shading

Select a mesh and press it. The add-on reads the shading setup of every selected mesh and lists what it finds, worst first. Nothing in the scene is changed; the add-on checks that itself and tells you if it ever were.

Two probe-free measurements are taken. The first is the count of edges where the surface turns a corner sharper than your threshold while the shading is blended across it. The second is whether the mesh has a clear separation between its soft curvature and its real corners at all — because on a coarse organic mesh it does not, and then blending everything is the right answer rather than a fault.

Hard edge above

Faces meeting at a sharper angle than this are treated as a real corner. Thirty degrees is what Blender itself uses. When your model has an obvious gap between its soft joints and its hard corners, the add-on suggests the angle that sits in that gap — as a suggestion. The look is your decision.

Fix and Prove

Only the findings you tick are acted on. The steps run in a fixed order, not in the order they are listed, because the order matters: the scale is applied first, smoothing is set next, then the smoothing angle, then Keep Sharp on the Weighted Normal modifier, and the Weighted Normal modifier is moved last so it ends up after Bevel. Custom normals are never cleared.

Then the same count is taken again and shown as before and after. Every step reports what it changed as a number, including when it changed nothing.

One thing worth knowing: Blender keeps the Smooth by Angle modifier pinned at the end of the stack itself, so Weighted Normal ends up in front of it. That is correct — what matters is that it comes after Bevel.

On older Blender

The Smooth by Angle modifier comes from Blender's own essentials asset library. On some installations, particularly on Blender 4.2, that library is not available and Blender adds nothing without saying so. ShadeProof checks the result, and if the modifier did not appear it marks the edges above your angle as sharp directly in the mesh instead. The look is the same; the difference is that the angle is then fixed in the mesh rather than adjustable afterwards. The report says which of the two happened.

What it does not do

It does not repair geometry, and it does not edit normals by hand. When geometry is the cause of a dark patch, it says so and names it.

Linked data

If the mesh comes from another file it is read-only. ShadeProof reads and explains it as usual, and refuses to repair it, saying why. Nothing is changed and no success is reported.

Show it

The arrow button next to a finding enters edit mode on that object and selects the edges the finding is about. The selection is the only thing that changes.

Report to Text

Writes the whole report into a text block called ShadeProof Report inside your file. Nothing is written to disk.

If something looks wrong

If the add-on reports nothing on a model that clearly shades badly, the cause is most likely geometry rather than setup — try a mesh repair tool. If it reports a finding you disagree with, untick it: nothing is done that you did not ask for.

Changelog

v1.2.2 — The Whole Delivery folder check no longer replaces a file in the folder you pick. Before, the report was always written as shade_proof_report.html (and the baseline as shade_proof_report_baseline.json), and a file with that name already there, such as an earlier report you kept, was overwritten. Now a free name is taken (shade_proof_report_2.html and so on), the message at the bottom of Blender names the file it wrote, and a run that fails while writing removes only the file it created. The report is written as UTF-8, as the page declares. The report and the baseline keep one number (shade_proof_report_2.html with shade_proof_report_2_baseline.json). A folder that cannot be written to is now refused in words instead of a Python error (and no empty report is left behind when only the baseline cannot be created), a folder that already has the report's name is skipped like a taken file, and the closing message is shown: before, a run with no problems or with unchecked files ended in a Python error instead of the message. Checking a folder no longer stalls on a file whose check prints a lot: on Windows such a file sat until the 30-minute limit and was reported as not finished. A file Blender cannot open, or one with nothing to check, is now explained in words instead of a Python error.

v1.2.1 — maintenance release. The package ships the full licence text and an updated README (install, first run, uninstall). No changes to the tools.

v1.2.0 — the automated report can no longer come back clean on a file the panel has just flagged; an unrecognised severity is treated as blocking; the package carries its licence file.

v1.1.2 — repairs work straight after Show Me, which leaves you in edit mode; a mesh driven by more than one armature is measured and repaired through all of them.

v1.1.1 — wording and report fixes found by running the tools over a real five-shot delivery.

v1.1.0 — check a whole folder of .blend files in one pass — each file in its own background Blender, one report, one verdict, and exit codes for a build system.

v1.0.0 — first release.

---

Checking a whole folder

The sidebar has a Whole Delivery panel. It has two buttons.

Check A Folder Of .blend Files runs this product over every .blend in the folder you pick. Check A Folder With Every Check You Own runs every tool from this line that you have installed, over the same files, in one pass — one report, one verdict.

Each file is opened in its own background Blender. Your open scene is never touched: not opened over, not saved, not modified in any way. This is also why a file that will not open costs you only that file — the rest of the delivery is still checked. Press Escape to stop; nothing partial is written, because a report covering half a delivery is a report nobody should trust.

When it finishes, an HTML report named shade_proof_report.html is written into the folder you picked. If a file with that name is already there, it is left as it is and the new report takes the next free name (shade_proof_report_2.html, shade_proof_report_3.html and so on); the message at the bottom of Blender names the file it wrote. The same goes for the baseline file when Save As Baseline is ticked. It is one file with nothing loaded from the internet, so it can be attached to an email, put in the delivery folder, or opened years later on a machine that has never seen this add-on.

Running it from a pipeline

The same check runs headless, with no interface and no person, and finishes with a code your build system can read: one code for clean, another when something blocking was found, and a third when a file could not be checked at all. Those last two are deliberately different. A check that did not run has not passed, and a gate that treats silence as success will one day wave through the delivery it existed to stop. The command is blender --background --factory-startup --python-expr "import shade_proof; shade_proof.proofkit_cli()" -- --folder /shots --report report.html. Return codes: 0 clean, 1 something blocking, 2 a file could not be checked, 3 the command itself was called wrongly.

Comparing against last week

Any run can be saved as a baseline. A later run then reports what changed: which numbers moved and in which direction, which findings are new, and which ones you have fixed since. Direction matters and is not guessed — each measurement carries its own sense of which way is worse, so rising coverage reads as better and rising drift reads as worse.

Signing a file off

When a file is clean you can sign it off. The record lives inside the .blend itself, not in a folder next to it, so it travels with the file: open it next month and it tells you when it was checked, by which version, and how it came out. If the file is saved after that, the record says plainly that it is out of date — a sign-off that survives an edit it never saw would be worse than no sign-off at all.

One tab instead of twelve

Every tool in this line can put its panel under a single shared sidebar tab instead of its own. One button does it for all of them at once, and each panel arrives collapsed, so twelve tools cost you one tab and no scrolling. Your choice is remembered, and a tool that you later use on its own can be given its own tab back the same way.

What is deliberately not claimed

A check that could not run is reported as exactly that, never as a pass. If a tool from this line is not installed, or is an older version that predates the combined run, the report names it in a list of checks that did not take part, so the gap is visible rather than quietly absent.