Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Testing the one-pass Hessian

assisted-by - Unknown Directive
claude-code:claude-opus-5

hessian_matrix builds each element of the Hessian. Up to scikit-image 0.26 it used two convolution passes. From 0.27, and in skimage2, it uses one pass per element, with kernels whose discrete moments have been corrected. hessian_review.md measures why, against a supersampled reference and an exact spectral one, and on_hessian.md traces the fault to its cause.

This notebook asks the narrower question:

What should the test suite assert, such that every assertion is a sentence about a picture, with a tolerance taken from the mechanism rather than from taste?

The answer is five tests. None of them needs a reference implementation or any of the scale-space literature. One (the boundary rule) is bit-identical when it passes; the others use floors argued in §7.5. A single interior Gaussian blob is enough for the closed-form check — multi-Gaussian scenes belong in hessian_review.md, where they validate references, not here.

§1 transcribes both schemes rather than importing either, so the tests do not depend on which release is installed. §1.1 reports which scheme the installed library implements.

fatal: not a git repository (or any of the parent directories): .git

1. The two schemes

Both compute the same continuous quantity: the second derivatives of the image after smoothing with a Gaussian of width σ. They differ in how many times each axis is touched, and in what kernel does the touching.

Each is transcribed here. Neither is imported, so the name of a scheme means one fixed arithmetic in this notebook, and not whatever the installed release happens to do.

The one-pass scheme asks for the whole derivative in one go. Each axis is convolved exactly once — twice-differentiated, once-differentiated or merely smoothed — so the boundary rule is applied once, and there is no first-or-second choice to get wrong on the mixed element. That brings back the even second-derivative kernel, which a plain sampled Gaussian gets wrong at small σ, so the kernel is corrected first.

The three comments in taps are the whole of the correction, and they are also the first three tests: a filter that gets 1, xx and x2/2x^2/2 right gets every quadratic right.

The one-pass function that ships carries one more thing, which no kernel can supply: an exactly flat image returns exact zeros, by inspection rather than by arithmetic. §4.1 to §4.3 are about why.

1.1 Which scheme is installed

Both namespaces are measured against all three transcriptions. The nearest one names the arithmetic the installed release uses.

Loading...

The gap is zero where a transcription is exact, so the table reads as an identification and not as a tolerance.

§2 to §8 use the transcriptions alone, so the five tests say the same thing in either environment. §4.1 to §4.3 are the exception: they call the installed meijering, frangi and sato, with only the Hessian replaced, so their numbers carry the installed filters’ own arithmetic.

2. Test 1 — the boundary rule must be applied once

mode is a promise about what lies outside the picture. mode='nearest' says the outside is a copy of the edge pixel; mode='reflect' says it is a mirror. The promise has an exact consequence that needs no theory at all:

If we actually build that outside and hand over the larger picture, the answer inside must not change.

Loading...

The one-pass column is not “small”: it is 0.00% because the two arrays are bit-identical. The two-pass column is wrong by a large fraction of the peak response — about a fifth for nearest on this picture, and more for some of the other modes — except wrap, which is the control below.

The wrap row is the control that makes the rest of the table mean something. A periodic extension is the one rule under which applying the extension twice is the same as applying it once, so the two-pass scheme passes there too. The test is not one that any filter passes, and not one that the two-pass filter always fails: it separates exactly the cases it should.

<Figure size 1056x363 with 4 Axes>

A rim, one or two pixels deep, all the way round, and worst half-way down the left edge rather than at a corner. The one-pass panel is not faint: every pixel in it is exactly zero, so the whole panel sits on the floor of the scale.

Loading...

3. Test 2 — the second derivative of a quadratic is a constant

The most-used property of a second derivative, and the one a caller is most entitled to. Build an image that is exactly a quadratic,

f(r,c)=a+b r+b′c+12d r2+e rc+12g c2,f(r, c) = a + b\,r + b'c + \tfrac{1}{2} d\,r^2 + e\,rc + \tfrac{1}{2} g\,c^2 ,

and the Hessian is the constant matrix (deeg)\begin{pmatrix} d & e \\ e & g \end{pmatrix}, at every pixel and at every σ. Smoothing does not change it, because smoothing a quadratic returns a quadratic with the same curvature.

Loading...

The one-pass column sits at the rounding floor everywhere — two and three dimensions, isotropic and anisotropic σ — and the two-pass column is eleven orders above it at σ = 0.4. The figure below says what that means in the units a caller cares about.

<Figure size 682x341 with 1 Axes>

The two-pass curve does not approach the answer until σ is about 1, which is where its own docstring advises callers not to go below. The corrected curve is on the line at every σ in the sweep.

3.1 This test cannot be the only one

taps normalises the kernel so that it is exact on x2/2x^2/2. This test asserts that it is exact on x2/2x^2/2. The agreement in the table above is therefore not independent evidence — it confirms that the correction was applied, not that the corrected filter is a good Hessian. §5 supplies the check that does not share a premise with the thing it checks.

4. Test 3 — a constant image has no curvature

The quadratic test contains this one, but it is worth its own name, because it is the property the two-pass scheme was designed around and the only one where the correction is the weaker of the two.

Loading...

The two-pass scheme returns exactly zero, by symmetry: it never uses an even kernel, and an odd kernel’s taps cancel in pairs however coarsely they are sampled. The bare corrected kernel returns about 10-16, because its first tap condition is imposed by subtraction rather than granted by symmetry. The short circuit returns exact zeros again, by not running the kernel at all.

So the test is atol=1e-12, not == 0, and the tolerance is chosen from the mechanism: one subtraction of numbers of order one, on an image of order one. Asserting exact equality would assert the short circuit rather than the documented behaviour, and would pass for a flat image only.

4.1 What the 10-16 costs the consuming filters

Two of the four ridge filters that consume hessian_matrix divide by a quantity derived from the Hessian, and a divisor that is rounding noise turns the noise into the output. meijering scales each scale by its own maximum; frangi takes its contrast reference γ from s.max(). Both guard the divisor against being exactly zero, and that guard holds only while the Hessian is exactly zero.

The three schemes are measured through the installed filters. Patching the name the filters import is what makes the comparison possible in one process, and **kwargs in the adapter is what makes it work against either release.

Loading...

Read the three pairs of columns as the three schemes. Under two-pass every score is zero. Under the bare corrected kernel meijering returns 1.0 — its largest score — for three of the four constants, and frangi returns 0.07 to 0.12. The short circuit returns the column to zero, which is what it is for.

0.4 is the row to notice. Its rounding noise happens to leave meijering’s selected eigenvalue non-positive, so the clip to zero catches it, and the bare kernel looks sound. Nothing about 0.4 is special otherwise. A test that used only that constant would report no fault.

4.2 The short circuit moves the cliff rather than removing it

np.ptp(image) == 0 is exact equality, so it fires on a flat image and on nothing else. Move one pixel by one part in 1015 and the divisor is rounding noise again, under every scheme.

Loading...

meijering returns 1.0 for every constant and every scheme, including two-pass. So this fault is not a consequence of the kernel change: the two-pass scheme amplifies the same noise, and §1.1 identifies that scheme as the one 0.26 installs. What the kernel change broke is the exactly flat image alone, and the short circuit closed that.

0.4 fails here too, which makes the nudged image the better test: it catches all four constants and all three schemes, where the flat image catches three constants and one scheme.

sato is clear in both tables. It takes a product of clipped eigenvalues and divides by nothing, so noise in the Hessian stays noise in the output.

Loading...

4.3 Why the repair went into the kernel’s caller and not the kernel

Repairing the kernel’s sum again, after the correction, converges at σ = 0.5 and stalls at about 10-17 from σ = 1 upward. The adjustment falls below the last bit of the accumulated sum, and correlate1d sums in its own order in any case.

Loading...

An exact zero is therefore not available from the taps, and the short circuit supplies it by inspection instead. That is the whole of the repair the release carries, and §4.2 shows what it does not reach.

The remaining fault wants a floor in each consuming filter: compare the divisor against 100 * eps * abs(image).max() rather than against zero. Both filters are self-normalising — meijering divides by its own per-scale maximum, frangi takes γ from s.max() — so any input with a non-zero response normalises to full scale, and rounding noise is the only place a principled floor can sit.

Loading...

The floor zeroes the nudged image and leaves the photograph alone. It is a fix for a fault that every release has carried, so it is not a cost of the kernel change and does not belong in the same pull request. on_meijering.md and on_frangi.md are where it goes.

5. Test 4 — a Gaussian blob, against its closed form

This is the independent check §3.1 asks for. A Gaussian blob smoothed by a Gaussian is another Gaussian, whose second derivatives are known exactly, and nothing in the kernel correction was aimed at getting them right.

Loading...

At σ = 0.5 the two-pass scheme is 92% wrong and the corrected one 0.3% wrong. At σ ≥ 2 both are at the rounding floor and the comparison says nothing — the two-pass scheme is even a little closer there, which is rounding, not accuracy.

That 0.3% is the honest limit of the whole change. Correcting the kernel fixes the operator on polynomials, which is a statement about zero frequency; a Gaussian narrow enough to alias on the pixel grid is not a polynomial, and no repair of a sampled kernel recovers it. So the suite below starts at σ = 1 with a floor of 1e-5; the σ = 0.5 row here is diagnostic, not a gate.

<Figure size 682x341 with 1 Axes>

The corrected curve lies on the closed form; the two-pass one is a flat line near zero, which is the same gain collapse §3 measured, now on a structure nobody would call a corner case.

5.1 What these two tests caught

The two tests above are not hypothetical. The kernel correction has to make the second-derivative taps sum to zero, and the obvious way to do it — subtract k.sum() spread over the Gaussian, as §1’s taps does in its first correction line — is unstable when σ is small. The centre tap is then a difference of two numbers of order σ−2\sigma^{-2}, and what should survive is of order e−1/2σ2e^{-1/2\sigma^{2}}: at σ = 0.1 the whole of it is lost.

DIPlib’s published recipe subtracts the mean instead, which is stable. Taking what is left out of the centre tap, as the one-pass kernel does, is a third option.

Loading...

Read the first column: the Gaussian-shaped subtraction responds to a constant image with 0.8 at σ = 0.1, which is a complete failure, and which only a test that reaches a σ that small will see. Then read the rest: the mean subtraction is stable everywhere but three to eight times worse on the blob between σ = 0.2 and σ = 0.7, because it spreads a pedestal across a support that the true kernel barely occupies.

Doing both — the Gaussian-shaped correction, then taking the residue out of the centre tap — is stable at σ = 0.1 and as accurate as the best of them everywhere else. That is the line taps carries, and the reason the constant test is parametrised down to σ = 0.1 rather than stopping where the pictures look sensible.

6. Test 5 — transposing the picture transposes the answer

A Hessian is a tensor. Relabel the axes and its entries must follow the relabelling, with no arithmetic anywhere. This is the contract the order argument was there to express. skimage2.feature.hessian_matrix has no order, and expresses it through the tensor instead.

Loading...
<Figure size 1056x363 with 4 Axes>

Only the mixed element can differ — it is the only one built by differentiating along two different axes — and under the two-pass scheme it differs along the whole border, because the two axes are extended in different frames.

6.1 What this means for order='xy'

With the contract restored, order='xy' is the reversed list and nothing more. Reversing is not enough for the two-pass numbers, because those include the border fault, and reproducing them needs the whole computation run in the transposed frame.

Loading...

For the corrected filter the two shims agree to rounding, so the reversed list is correct. For the two-pass filter they differ by up to 14%.

That 14% is the whole of the question for a port. skimage.feature.hessian_matrix answers with the one-pass scheme from 0.27, including for use_gaussian_derivatives=True, so no supported call returns two-pass numbers and the transposed shim has nothing left to reproduce. The migration note names the reversed list.

7. What the tests must avoid

Five ways to write these tests so that they pass without meaning anything.

7.1 Crop the margin on the polynomial tests

A quadratic is not constant outside the frame, so no boundary rule continues it correctly. The border pixels of the quadratic test are supposed to be wrong, and a test that includes them is testing mode, not curvature.

Loading...

7.2 Spell the boundary rule the way each library spells it

The test compares a scipy mode against a numpy pad mode, and two of the five names cross over: scipy’s reflect is numpy’s symmetric, and scipy’s mirror is numpy’s reflect. Matching them by name builds a different outside, and the test then fails on a filter that is right.

Loading...

Ten per cent of the peak, on the filter this notebook is arguing for, from a two-word mistake in the test.

7.3 Pad past the kernel’s reach, for the reflecting modes

For nearest, wrap and constant the extension is idempotent — extending an already-extended picture gives the same infinite picture — so any pad will do. Reflection is not: its period is set by the frame, so a reflected pad narrower than the kernel shows the kernel a different outside.

Loading...

At σ = 2 the kernel reaches 16 pixels, and the two reflecting columns drop to zero at the first pad that clears it. Choose the pad from the kernel, not from habit.

7.4 Do not test only wrap

§2’s control row is the trap seen from the other side. wrap is the one mode the two-pass scheme gets right, so a border test parametrised over wrap alone passes on the unfixed filter.

7.5 Take the tolerance from the mechanism

Three different tolerances are right here, and each is argued rather than chosen: exact equality for the border test, where the arrays really are bit-identical; about 10-15 of the peak measured for the transpose (correlating along axis 0 and along axis 1 add in different orders), gated in the suite at 1e-12; a small multiple of the picture’s own magnitude for constants and quadratics, because the correction imposes a cancellation instead of inheriting a symmetry; and a floor no tighter than the aliasing residue for the Gaussian at σ ≥ 1, because that residue is real and is not going away.

The middle one is the one that is easy to get wrong. A quadratic’s values grow as the square of the distance from its centre, so a wider frame carries larger numbers and a larger absolute rounding error, for exactly the same filter.

Loading...

The absolute column moves by two orders across those frames; the scaled column does not move at all. So the tolerance belongs on the scaled quantity, which is what quadratic_error returns.

8. The suite

Loading...

Four of the five fail on the two-pass scheme. The exception is the constant, and that is not an accident: the two-pass scheme exists because someone noticed that a sampled second-derivative kernel responds to a flat image, and built a pair of odd first-derivative passes that cannot. It solved the one problem it was aimed at and created the other four.

Both one-pass schemes pass all five. The short circuit changes no outcome here: the constant test has a floor of 1e-12, which 10-16 already meets, so the short circuit changes that test’s margin and not its result. §4.2 is where it matters and §4.3 is why it exists.

These five landed as test_hessian_matrix_applies_the_boundary_rule_once, test_hessian_matrix_is_exact_on_a_quadratic, test_hessian_matrix_has_no_response_to_a_constant, test_hessian_matrix_matches_a_gaussian_blob and test_hessian_matrix_transposes_with_the_image in tests/skimage2/feature/test_corner.py, calling public hessian_matrix. The skimage suite carries the first four against use_gaussian_derivatives=True.

9. Summary

testthe sentence it assertstolerance
boundary rule applied oncebuilding the promised outside changes nothing insideexact (== 0)
exact on a quadraticthe curvature reported is the curvature that is there1e-14, scaled
no response to a constanta flat image has no curvature1e-12
matches a Gaussian blobagrees with a closed form the correction did not target1e-5, σ ≥ 1 (σ < 1 diagnostic only)
transposerelabelling the axes relabels the tensor1e-12 of the peak (~10-15 measured)

and the rules the pictures must obey: crop 8σ + 1 from the polynomial tests (§7.1), spell each boundary rule the way numpy spells it (§7.2), pad past the kernel reach for the reflecting modes (§7.3), and never parametrise the border test over wrap alone (§7.4). Keep the closed-form check on a single interior blob; multi-Gaussian scenes are for hessian_review.md.

Loading...

Cost is not a test, but it is the one number that might argue against the change, and it does not. At σ ≤ 1 the corrected filter is about an order of magnitude cheaper, because it does not carry the truncate = 100 guard that the sampled even kernel was thought to require. At σ = 2 the guard is gone from both and the gap closes, the corrected kernels being the wider ones. Timings move by tens of per cent between runs on this machine, so read the ratio’s order and not its last digit.

Limits. One photograph (256², camera decimated), one synthetic quadratic and one Gaussian blob, at σ from 0.1 to 4, in two and three dimensions. §4.1 to §4.3 measure the consuming filters on flat and near-flat images only; what the floor does to them on real images is on_frangi.md and on_meijering.md’s business, not this notebook’s, and the one photograph in §4.3 is a check that the floor does not fire, not a measurement of its effect. The five tests run against the transcriptions, not against the installed hessian_matrix; §1.1 identifies the installed scheme but does not run the suite against it. float32 input is not tested here, nor is the behaviour at σ below 0.3, where §5’s aliasing residue grows and no kernel repair addresses it. The interior() rule assumes truncate=8; a caller passing a larger truncate needs a larger crop. The timings are single runs on one machine and are indicative only.

scikit-image  0.27.0rc2.dev0
_skimage2     0.27.0rc2.dev0
scipy         1.18.1
skimage.feature implements two-pass (<= 0.26)
_skimage2.feature implements two-pass (<= 0.26)