SampleProof 1.2.0 — documentation

What it is for

You set a sample count in Cycles and you have no idea whether it is right.SampleProof measures how far your frame is from a converged one, what anotherdoubling would buy, and which sample count meets the tolerance you set. Itrenders; it does not guess.

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 SampleProof tab appears in the sidebar.

Using it

1. Set Close Enough to the difference from converged you are willing toaccept, as a percentage. The default is 0.5.
2. Leave Top Of The Ladder at zero to measure from the sample count this sceneis set to, or type your own.
3. Press Measure The Samples.

The measurement renders the ladder, two references and one extra frame withthe opposite denoiser setting — on a four-step ladder that is seven frames, andthe panel always prints how many it actually rendered and how long they took.

Measure At (px) is the size those frames are rendered at. Noise per pixel doesnot depend on resolution, so a smaller frame predicts the full one — but itcannot see detail finer than its own pixels. Measured: on a shot made of thinwires, 240 px overstated the difference by 74 to 79 per cent; on caustics thesame reduction was accurate to within one per cent. Raise it when your shot liveson fine geometry.

Reading the result

The first box is the headline and the numbers behind it:

at 64 samples you are 0.36 % from converged
measured at 160x160, 7 frames in 4.4 s; the reference is 512 samples and its ownnoise of 0.117 % has been taken back out of every number above. One doublingbuys 35 % of what is left

The Ladder panel lists every step: the sample count, how far that frame isfrom converged, and what it cost.

There is no magic number, and that is a finding

This add-on set out to find the point where a frame stops changing. It doesnot exist. Path-traced noise falls as one over the square root of the samples,so the difference keeps shrinking by the same fraction with every doubling,forever. Measured on a plain scene and a glass one, the ratio betweenneighbouring steps came out 1.42, 1.55, 1.62, 1.61 and 1.27, 1.41, 1.28, 1.38against a theoretical 1.41 — no knee, no plateau, on either.

An earlier design judged convergence against the reference's own noise. Thatwas wrong, and the measurement said so: the reference's noise falls as you raisethe reference, so the ratio to it grows without limit. Eight samples of theplain scene read 11.17 against a reference four times the ladder, 16.93 againsteight times, 25.76 against sixteen and 41.04 against thirty-two. That ratiodescribes the reference you picked, not the scene.

So the tolerance is yours. What the add-on supplies is the exchange rate andyour position on the curve.

The reference, and why it is rendered twice

The reference is a render at eight times the top of your ladder. It isrendered twice with different seeds; the difference between those two renders isthe reference's own noise, which is present in every comparison and is thereforesubtracted back out in quadrature. Measured: a raw 0.3810 % against a referencewhose own noise is 0.1186 % becomes 0.3717 %, matching an independentcalculation to the fourth decimal.

Why a reduced frame and not a crop

Noise per pixel does not depend on resolution, so a smaller frame carries thesame noise and predicts the full one. A crop measures the crop: this one landedon the glass and reported the glass.

What a reduced frame cannot see is detail finer than its own pixels — a hair,a narrow highlight, a small caustic. If your shot lives on that, measure at alarger size.

It measures the frame you render

The ladder runs with your own denoiser setting, because the answer has to beabout the frame you will produce. Measured: with denoising on, sixteen sampleswere enough where the add-on — measuring without it — was saying no sample counton the ladder would do. The reference is always rendered without denoising: ithas converged, so there is nothing left to smooth.

A render border is kept, and named. Removing it silently would answer aboutthe whole frame instead of the region you render: on a glass scene that was1.869 % where the truth inside the border was 0.291 %.

A compositor is named too. What gets measured then is the composite, and aDenoise node in there changes the answer without the measurement being able totell it apart from the render. If the compositor's node group has no output,Blender renders the frame and writes nothing at all — that is reported as arefusal with the reason, not as a crash.

How far the numbers can be trusted

The metric is a relative difference, and its denominator is floored at a shareof the frame's own average brightness — not at a fixed absolute value. Thatmatters: with an absolute floor the same pair of frames scaled down by athousand read 0.0163 % instead of 0.6172 %, a spread of thirty-eight times, and anight shot would have been told that eight samples was plenty. Scaling the wholeframe by any factor now leaves every number unchanged.

Pixels that are not numbers — nan or infinity from a broken material — areleft out of every calculation and reported separately. One of them used to turnthe entire answer into nan.

Adaptive Sampling

Switched off for the measurement and put back afterwards, with your noisethreshold named in the report. With it on, the sample count is only a ceilingand the threshold decides, so a ladder of sample counts would be measuring thethreshold. Measured: leaving it on flattens the top of the ladder to 0.823 %against 0.817 %, where a healthy ladder reads 0.606 against 0.381.

When it refuses

• The engine is not Cycles. Sample convergence in this sense is aCycles idea.
• No camera. Nothing to render.
• Animated Seed is on. Every step would use a different noise patternand the ladder would not be comparable with itself.
• The reference is no cleaner than the ladder. Then nothing here can betold apart from noise, and it says that instead of printing a number — along withthe settings notes, because a compositor or a render border is usually thereason.
• The measurement would cost more than the render. The reference iseight times the top of the ladder, rendered twice; at a top of 4096 that is oversixty thousand samples. Refused before the first frame, with the numbernamed.
• Multi-view (stereo) rendering. Blender writes one file per view andthere is no single frame to compare.
• The camera is not in the scene.

Use That Number

Sets this scene's sample count to the one the measurement found. It is theonly thing the add-on ever changes on purpose, and it is tested: pressing itchanges the sample count and nothing else.

It puts your settings back

Samples, seed, resolution and percentage, render border, output path, fileformat, denoising and Burn Into Image are all recorded before the measurement andrestored after. The panel prints the result of that comparison every time, notonly when something went wrong. Frames are written to a folder inside yoursystem's temporary directory, which the operating system clears on its ownschedule; nothing is written into your project or next to your .blend.

Report to Text

Writes the whole report, including the ladder, into a text block inside your.blend called SampleProof Report.

Tested

98 checks on each of Blender 4.2.9, 5.1 and 5.2, zero problems. Twentydeliberate sabotages of the product turn the test suite red, so the tests areknown to be able to fail — including ones that leave Adaptive Sampling on, skipsubtracting the reference's own noise, pin the metric's floor back to an absolutevalue, read the scene's sample count after the renders instead of before, andunlock the apply button on a refused report.

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.