RetopoProof 1.2.0 — documentation

What it is for

You have a sculpt, a scan or a high-poly model, and a new mesh you built overit. RetopoProof measures how far the new mesh sits off the old surface, and whatof the old surface the new mesh does not cover at all. It reports millimetresand vertex numbers. It does not change anything.

Installing

Download the zip and leave it zipped. In Blender open Edit, then Preferences,then Add-ons. Click the arrow button in the top right corner of that window andchoose Install from Disk, then pick the zip. On Blender 4.0 and 4.1 the samebutton is called simply Install. Tick the checkbox next to the add-on name.Press N in the 3D Viewport: the RetopoProof tab appears in the sidebar.

Using it

1. Set Original to the sculpt, the scan or the high-poly model.
2. Set Retopology to the new mesh.
3. Press Measure The Drift.

You can skip both fields: select exactly two meshes and the active one istaken as the retopology, since that is the one you are working on. If the twofields point at the same object, or at anything that is not a mesh, the panelsays so instead of measuring.

What the panel tells you

The first box is the verdict and the numbers behind it. A healthy resultreads like this:

the retopology follows the surface, and covers it down to its own resolution
worst 0.00 mm at vertex 60, average 0.00 mm; 0 of 362 vertices past 1.00 mm.Back the other way: 2562 points of 'Sculpt', furthest 47.83 mm = 0.2 of your own191.6 mm edge, nothing wider than two of your edges left uncovered. 0.01 s

Read it as two halves. The first half is your mesh against the surface: howfar the worst vertex sits, which one it is, the average, and how many are pastthe tolerance you set. The second half is the surface against your mesh: howmany points of the original were checked, how far the furthest one is fromanything you built, and — the part that matters — how that distance compareswith your own edge length.

The findings

the retopology does not follow the surface

Vertices sit further from the original than the tolerance you set. The linenames the worst vertex, how many are past the tolerance, and the average. If anyof them sit inside the original surface, that is counted separately:a vertex sunk into the high-poly bakes worse than the same distance outside,because the ray leaves from the wrong side.

one vertex is left behind, the rest are snapped

This one appears when your mesh is within tolerance and one vertexis still wrong. It is not measured against a threshold — it is measured againstthe rest of your own mesh. On a real case a vertex sat 0.393 mm off while themiddle of the mesh sat at 0.000 mm, and the line fell at 0.192 mm. Aone-millimetre tolerance lets that through. The line is drawn from the middle ofthe mesh rather than its average, because every straggler drags an average upwith it: judged on the average, fifteen stragglers look milder than one andtwenty look like nothing. It also carries a floor taken from the mesh itself — athousandth of its own edge length — because when every distance is roundingnoise no comparison means anything. When several vertices are left behind, thereport says how many. It is still a vertex the snappingmissed rather than a shape you chose, and it is the one place your meshdisagrees with itself.

part of the original has nothing on top of it

A piece of the original surface that your retopology does not cover. This iswhat the forward measurement cannot see: where a feature is missing, your meshis not wrong, it is absent, and every vertex you do have sits perfectly. Eachpatch is reported by how wide it is in your edge lengths, how manysampled points of the original it holds, and the deepest one.

scattered spots finer than your mesh

Not a problem, and said so. These sit further than one edge from your meshbut none is wider than two: pores, foliage, scanner grain. A mesh cannot carrydetail smaller than its own face — that is what the normal map is for. They arelisted so you know they were looked at.

modifiers shape the retopology besides a shrinkwrap

Everything is measured on the evaluated mesh, so a live Subdivision or Mirroris part of the number. When something other than a shrinkwrap is in the stack,it is named, because then the measurement describes the whole stack rather thanthe cage alone.

Tolerance

Tolerance (mm) is the distance a vertex may sit off the original before itcounts. The default is 1 mm. It is a real, physical setting: it is your bakecage. Set it to what your bake will actually tolerate.

Note what the tolerance does not control. The reverse measurement —what your mesh fails to cover — ignores it entirely, and is judged against yourown median edge length instead. That is deliberate. A millimetre means nothinguntil you know how big the model is, and a percentage of the model means nothinguntil you know how dense the mesh is, because any polygon cuts the corner off acurve by an amount that grows as edge length squared over radius. Judgingcoverage in millimetres would shout at every honest low-poly mesh.

What was measured to build that rule

Scale, modifiers and big scans

• Everything is measured in world coordinates, so object scale is part of theanswer. At scale 0.01 and at 100 the millimetres match an independentmeasurement to the second decimal.
• Everything is measured on the evaluated mesh — the one your renderer andyour bake see — not on the vertices sitting in the file.
• A very dense original is sampled deterministically, and the number ofpoints actually checked is printed. A 10 242 vertex sculpt against a 1 490vertex retopology takes 0.02 seconds. The sample is drawn with a mixed hashrather than by taking every Nth vertex: vertex numbers in a scan run in rows, anevery-Nth sample lands in neat columns, and a stripe missing between them isnever looked at. On a 400 by 400 scan that mistake reported full coverage over agap 399 edges wide.
• Distances are measured against a tree built on world-space triangles. Doingit the easy way — finding the nearest point inside the object and convertingafterwards — is wrong under non-uniform scale, and wrong in the direction offalse alarms: on a mesh scaled (1, 1, 8) it reports 199.62 mm where the truth is54.05.

Report to Text

Writes the whole report into a text block inside your .blend calledRetopoProof Report, which you open in the Text Editor. Nothing is written toyour file system.

modifiers evaluate differently in the render than in the viewport

A subdivision set to one level in the viewport and three in the render is themost common setup in Blender, and both of its switches are on, so nothing elseflags it. Everything measured here comes from the viewport result — on ameasured case that was 0.00 mm while the render mesh was 25.81 mm off. Bothobjects are checked, not only the retopology.

a narrow feature of the original is not covered

Narrower than two of your edges, so the mesh cannot carry its width — butdeeper than two of them as well. A bolt recess, a nostril, a slot. A normal mapdoes not carry 133 mm of depth, so this is reported rather than filed undersurface grain.

When it refuses

Some things cannot be measured, and saying so is part of the job.

• An object with no evaluated mesh. Switched off in the viewport by themonitor icon, or held only in collections that are switched off or excluded fromthe view layer: Blender builds nothing for such an object, so there is nothing tomeasure. The eye icon in the Outliner is different — it does not switch off theevaluation, and the measurement runs normally and returns the same number.
• A mesh with vertices but no faces. Distance to a surface needs asurface; a point cloud or a set of loose edges has none.
• A mesh that comes out empty after its modifiers, and the two fieldspointing at the same object.

Snapping the drifted vertices back

Vertices that sit further from the original surface than your tolerance canbe pulled back onto it. Topology is not touched: not one face, edge loop or UVchanges, because the whole point of a retopology is the topology.

The proof is the same measurement before and after: a worst deviation of50.000 mm became 0.000 mm, with the face and loop counts identical eitherside.

Vertices that have wandered further than the mesh's own median edge lengthare left where they are and named instead. That limit is not a number somebodypicked: pulling a vertex further than its neighbours are apart folds the mesh,and the mesh itself is the only honest source of that distance.

What it changes, and only when you ask

Measuring changes nothing. A fingerprint of the session is taken before andafter every measurement and compared, and the panel prints the result everytime — not only when something went wrong.

One button does write to your file, and only when pressed: the snapdescribed above, which moves vertex positions and nothing else. Report to Textwrites a text block.

Tested

229 checks on each of Blender 4.2.9, 5.1 and 5.2, zero problems. Silence istested as hard as noise, and each half of the measurement has its own healthysample: a snapped retopology reads 0.00 mm with no stray vertex on all twelvereal production models tried, and a coarser retopology of the same shape leavesnothing uncovered on eleven of them. Sixteen deliberate sabotages of the productturn the test suite red, so the tests are known to be able to fail.

License

GPL-3.0.

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 YouOwn runs every tool from this line that you have installed, over thesame files, in one pass — one report, one verdict.

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

When it finishes you get an HTML report next to the folder. It is one filewith nothing loaded from the internet, so it can be attached to an email, put inthe delivery folder, or opened years later on a machine that has never seen thisadd-on.

Running it from a pipeline

The same check runs headless, with no interface and no person, and finisheswith a code your build system can read: one code for clean, another whensomething blocking was found, and a third when a file could not be checked atall. Those last two are deliberately different. A check that did not run has notpassed, and a gate that treats silence as success will one day wave through thedelivery it existed to stop. The exact command line is in the add-onpreferences.

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 whichones you have fixed since. Direction matters and is not guessed — eachmeasurement carries its own sense of which way is worse, so rising coveragereads 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 .blenditself, not in a folder next to it, so it travels with the file: open it nextmonth and it tells you when it was checked, by which version, and how it cameout. If the file is saved after that, the record says plainly that it is out ofdate — a sign-off that survives an edit it never saw would be worse than nosign-off at all.

One tab instead of twelve

Every tool in this line can put its panel under a single shared sidebar tabinstead of its own. One button does it for all of them at once, and each panelarrives collapsed, so twelve tools cost you one tab and no scrolling. Yourchoice is remembered, and a tool that you later use on its own can be given itsown 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 atool from this line is not installed, or is an older version that predates thecombined run, the report names it in a list of checks that did not take part,so the gap is visible rather than quietly absent.