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 `frangi` repairs

Changelog (last change 2026-11-18)
DateByChange
2026-11-18cursor:composerAdd related link to PR 8335
2026-11-13claude-code:claude-opus-5-5Add 1D illustration of scale normalisation on Gaussian bars
2026-09-22Stefan van der Walt, claude-code:claude-opus-5Add title and creation date; quote title
2026-09-18Matthew BrettCreate workbook

frangi lost its σ² scale normalisation in version 0.20.0. Before that release it went through a helper that multiplied the Hessian by sigma ** 2 under the comment # Correct for scale; the rewrite that removed the helper kept that line in sato and dropped it from frangi. #7711 is the consequence, reported as “only the smallest scale affects the filter output”.

Restoring it is one line. That one line is unsafe until a second change has landed. frangi_refactor_plan.md sets out the two stages and on_frangi.md has the full defect catalogue. This notebook asks the narrower question the two earlier _testing notebooks ask:

What should the test suite assert, such that every assertion is a sentence about a picture?

Five tests, and one ordering constraint that a test can state and check.

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

0. Smoothing and scale, in one dimension

Before the candidates, a picture of what the σ² is for. A ridge filter finds a bar by its curvature: the second derivative of the image after Gaussian smoothing at scale σ\sigma. Smoothing makes a bar lower and wider, and both changes reduce the curvature at its centre. So a larger σ\sigma always gives a smaller raw curvature, and the raw numbers cannot tell us which scale fits a bar.

To show this, we use three bright bars in one dimension, with Gaussian profiles like those of the bars in §2. Each has height 1. Its width ww is the standard deviation of the profile, and we use ww = 2, 4 and 8 pixels. The bars in §2 are dark, so their curvature has the opposite sign; that does not change anything below.

<Figure size 1056x264 with 3 Axes>

The grey lines are the bars before smoothing. Every bar gets lower and wider as σ\sigma grows, and the narrow bar changes fastest.

Height over width squared

Smoothing a Gaussian profile with a Gaussian kernel gives another Gaussian profile. The variances add, so the smoothed bar has standard deviation s=w2+σ2s = \sqrt{w^2 + \sigma^2}. Smoothing keeps the area under the profile, so the height falls to A=w/sA = w / s. The smoothed bar is

fσ(x)=Aexp⁡(−x22s2),−fσ′′(0)=As2=w(w2+σ2)3/2.f_\sigma(x) = A \exp\left(-\frac{x^2}{2 s^2}\right), \qquad -f''_\sigma(0) = \frac{A}{s^2} = \frac{w}{(w^2 + \sigma^2)^{3/2}}.

The curvature at the centre is the height divided by the width squared. Near its top, the profile follows the parabola A (1−x2/2s2)A\,(1 - x^2 / 2s^2), which has the same curvature. The profile’s inflection points are at x=±sx = \pm s. Here is the w=4w = 4 bar at four scales, with that parabola dashed and the inflection points marked.

<Figure size 1056x286 with 4 Axes>

From σ=0\sigma = 0 to σ=8\sigma = 8 the height falls by about half and s2s^2 grows by a factor of 5, so the curvature falls by a factor of 11. Both changes push the same way, at every σ\sigma. The raw curvature therefore falls monotonically as σ\sigma grows, for a bar of any width. A filter that takes the largest raw response over its scales always picks the smallest scale.

What the σ² puts back

Multiplying by σ2\sigma^2, which is Lindeberg’s scale normalisation with γ=1\gamma = 1, gives

−σ2fσ′′(0)=σ2 w(w2+σ2)3/2.-\sigma^2 f''_\sigma(0) = \frac{\sigma^2\, w}{(w^2 + \sigma^2)^{3/2}}.

This now rises and then falls. Below, everything is in the bar’s own units: heights and curvatures are multiplied by w2w^2, so each curve starts at 1 or 0. The left panel splits the raw curvature into its two factors. The right panel multiplies it by (σ/w)2(\sigma / w)^2.

<Figure size 1056x330 with 2 Axes>

On these log axes the slopes add. For σ\sigma much larger than ww, the height falls as σ−1\sigma^{-1} and 1/s21 / s^2 as σ−2\sigma^{-2}, so the raw curvature falls as σ−3\sigma^{-3}. Multiplying by σ2\sigma^2 leaves a fall of σ−1\sigma^{-1}. For σ\sigma much smaller than ww, the raw curvature is flat and σ2\sigma^2 makes the product rise. The peak lies between, at σ=w2\sigma = w\sqrt{2} (dotted). There the normalised curvature is 2/(33)≈0.3852 / (3\sqrt{3}) \approx 0.385, and ww cancels, so that is the peak for a bar of any width. SymPy confirms the algebra.

(2*sqrt(3)/9, 0.3849001794597505)

The same picture at every width

Why does ww cancel? Smooth a bar of width ww at σ=w2\sigma = w\sqrt{2}, and the result has height 1/31 / \sqrt{3} and standard deviation w3w\sqrt{3}. Double ww and σ\sigma together and the height is unchanged; the profile is twice as wide. Twice as wide means a quarter of the curvature, measured in pixels. Measure xx in units of σ\sigma instead, and the profiles are identical. That is what the σ² does: σ2f′′\sigma^2 f'' is the curvature with xx measured in units of σ\sigma.

<Figure size 1056x308 with 2 Axes>

The three profiles on the right are drawn with different line widths so that all three show; they lie on top of each other.

Measured on the sampled bars

The formulas describe continuous profiles. Here is the curvature at the centre of each bar, sampled at whole pixels and measured with gaussian_filter1d. We measure each bar alone, in a signal long enough that the smoothing never reaches its ends. The scales start at σ=2\sigma = 2: just above σ=1\sigma = 1 the sampled second-derivative kernel overstates the curvature of the w=8w = 8 bar by up to 2%, enough to put a false bump in its raw curve. Dotted lines mark σ=w2\sigma = w\sqrt{2}.

<Figure size 1056x330 with 2 Axes>
Loading...

Without the σ², every bar’s best scale is the smallest one tried, and at that scale the narrowest bar scores about 6 times as high as the widest. With it, each bar peaks near σ=w2\sigma = w\sqrt{2} with the same score. §3 makes the same measurement on the 2D bars, through frangi; §5 finds sato, which keeps the σ², choosing scales near w2w\sqrt{2} too.

1. The four candidates

The two repairs are independent switches, so there are four things to test, not two. parts caches the per-scale eigenvalues, because the tests below run the same scale many times in different orders and the Hessian is all the cost.

The transcription has to be exact or nothing below means anything.

Loading...

as shipped reproduces skimage.filters.frangi bit for bit, in both orders.

2. The regression, in one picture

The issue’s own figure: elongated features of several widths, dark on light.

<Figure size 1056x363 with 3 Axes>

The shipped filter answers with thin lines where the bars have edges, and says almost nothing at their centres — which is the reporter’s own description, that “the filter behaves like an edge detector instead”. At σ = 1 a wide bar has no curvature in its middle to respond to, and σ = 1 is the only scale that ever wins. The next cell is the same fact as numbers.

Loading...

3. Test 1 — a bar’s score must not depend on how wide the bar is

This is the plainest statement of what the σ² is for, and it needs no theory: four bars of the same contrast should come out of a ridge filter with the same score. The filter is given a scale for each of them; its job is to use it.

As shipped they come out 0.8647, 0.4148, 0.0535 and 0.0039 — a factor of 220 between the narrowest and the widest, on a picture where the only difference is width. With the σ² they come out within 5% of each other.

<Figure size 990x352 with 2 Axes>

On the left every ring sits at σ = 1 — every bar chooses the finest scale — and the four rings are at four different heights, from 0.86 down to 0.004. On the right the rings march to the right as the bar widens, and all four sit at the same height. A test can assert either fact; the height is the easier one to explain and the harder one to satisfy by accident.

4. Test 2 — shuffling the scales must not change the answer

sigmas is documented as a set of scales. A set has no order, and the docstring does not say otherwise. Today the answer depends on which scale happens to be first, because gamma=None is resolved on the first iteration of the loop and never revisited.

Loading...

Three columns of that table are the whole argument of this notebook, so read them in order. as shipped is wrong by almost the full output range. stage A is exactly zero. stage B alone is wrong again — less, but by up to 0.29 — and A + B is exactly zero.

That is the ordering constraint, measured: the σ² restore reintroduces the defect that stage A removes, so it must not ship first. §8 says why.

Loading...

Stage A is bit-identical to today’s output for an ascending sigmas, on every corpus image. It ships as a refactor, not as a behaviour change — which is what makes it safe to land first and on its own.

5. Test 3 — sato and frangi must agree which scale finds a bar

sato sits in the same module, takes the same sigmas, and kept its σ² through the rewrite that lost frangi’s. Two ridge filters given the same bar and the same scale list should nominate the same scale. This test needs no model of either filter — only that they are both ridge filters.

Loading...

γ is held fixed across the scan, for the reason §9.1 measures.

sato and the repaired frangi agree on every row, and both land next to w√2, which is where a σ-squared-normalised filter puts the peak. The shipped frangi says 1 four times.

6. Test 4 — a bright ridge is not a dark ridge

black_ridges=True asks for dark ridges. Hand the filter a bright one and it should say nothing.

Loading...

Not merely equal at the probe: the two whole arrays are identical, so black_ridges does nothing at all on this picture. 0.864665 is 1 - exp(-2), the largest score a single-scale frangi with the default γ can return — the wrong-polarity ridge is scoring the ceiling.

The cause is that the rejection is done by a division that is meant to explode, abs(lambda1) / max(lambda2, 1e-10), and on an ideal ridge lambda1 is exactly zero, so the division gives 0 rather than infinity. The repair is an explicit sign test.

Loading...

The defect is triggered by lambda1 being exactly zero, which is a property of the picture rather than of the filter. §9.2 measures which pictures have it.

7. Test 5 — the units of brightness must not matter

With gamma=None every quantity in frangi is either a ratio of eigenvalues or is measured against s.max(). Multiplying the image by a constant should therefore change nothing at all.

Loading...

It does not hold. The 1e-10 in max(lambda2, 1e-10) is an absolute constant in a filter that is otherwise entirely ratios, so once the eigenvalues fall near it the answer changes. The sign test of §6 removes the clip and with it this dependence, which is a second reason to make that change.

8. Why stage B must not ship before stage A

§4’s table shows it; this section says why, because a test suite that knows the reason can pin it.

Stage A is a no-op today because S falls with σ, so the largest Hessian norm sits at the smallest σ, which for a sorted list is also sigmas[0]. The σ² multiplies each scale by a different number and destroys that.

Loading...

With σ**0 the answer is the smallest σ on every image, and the frozen γ is the true one — the defect is real but invisible. With σ**2 that stops being true on coins, and the frozen γ is then taken from a scale that is not the maximum.

Which images move depends on where the image’s dominant structure lives, so this table is about this corpus. §4’s permutation column is the claim that does not depend on that: with σ² and a frozen γ, every image shows an ordering spread, and with stage A none of them does.

9. What the tests must avoid

9.1 Hold γ fixed while scanning σ

This is the trap that caught three separate cells of this notebook before they were corrected, so it goes first. gamma=None resolves to half the largest Hessian norm of the scales it was given. Hand a single σ to each call and each call sets its own reference, which pins the structuredness term to 1 - e⁻² at the strongest pixel of every scale — dividing out exactly the scale dependence the scan is there to measure.

Loading...

With a per-call γ the shipped filter and the repaired one nominate the same scales, so the test cannot fail and the figure in §3 comes out as two identical panels. With one γ across the scan they differ on every bar.

9.2 Turn the ridge before trusting a rasterised one

§6’s defect needs lambda1 exactly zero, and whether a picture gives that depends on its orientation, not on how smoothly it is drawn. A bar parallel to an image axis is a function of one coordinate whatever its profile, so the curvature along it is exactly zero either way. Turn the same bar and the profile starts to matter.

Loading...

The last row is the trap, and it is the opposite of the one to expect: a turned rasterised bar puts lambda1 at 2e-05, which clears the 1e-10 clip, so the filter rejects the wrong polarity correctly and the test passes on a broken implementation. The turned exact profile keeps lambda1 at 3e-18 and the defect fires.

So a polarity test may use an axis-aligned bar drawn any way at all, or a turned bar drawn as an exact profile — but a turned bar drawn by thresholding proves nothing.

9.3 Do not test the ordering with a single σ

The ordering defect lives in which scale is first. A one-element sigmas has no order, and a test that passes one cannot fail.

9.4 Do not assert “close” where the answer is “identical”

Stage A is bit-identical to today’s output for sorted sigmas, and both stages make the permutation spread exactly 0.0. Those are equalities, not tolerances. A test written with rtol=1e-5 would pass a filter that still resolved γ from the wrong scale, as long as the scales were close together.

9.5 Do not measure scale selection below σ = 1 yet

hessian_testing.md measures the shipped Hessian reporting 8% of a quadratic’s curvature at σ = 0.5. A scale-selecting frangi on that operator picks the wrong scale for any structure narrow enough to need a small σ. Keep this suite’s σ grid at 1 and above until hessian_matrix is fixed.

10. The suite

Loading...

Each stage turns exactly the tests it is meant to turn, and turns none of the others back. The last column is the filter this plan proposes.

11. Summary

testthe sentence it assertswhich stage makes it pass
a bar’s score does not depend on its widthfour bars of one contrast score alikeB
shuffling the scales changes nothingsigmas is a setA, and A again after B
agrees with sato about scaletwo ridge filters nominate the same σB
a bright ridge is not a dark ridgeblack_ridges does what it saysthe sign test
brightness units do not mattera filter of ratios has no unitsthe sign test

and the rules a test must obey: hold γ fixed while scanning σ (§9.1), never prove polarity on a turned rasterised bar (§9.2), never test the ordering with one σ (§9.3), assert equality where the answer is exact (§9.4), and keep σ at 1 and above until hessian_matrix is fixed (§9.5).

Limits. Three photographs from skimage.data decimated to about 200 px, one synthetic bar picture at 200², one synthetic ridge at 128², mode='reflect' throughout, default beta, and σ from 1 to 12. Permutation scans use three scales, not the full default list of five. Everything here is 2-D: frangi’s 3-D branch shares the gamma and polarity code and so shares D1 and D3 by inspection, but that is a reading and not a measurement. §8’s table is a statement about this corpus; §4’s permutation column is the claim that is not. The measurements run against the released two-pass hessian_matrix, so the numbers move a little once that is repaired — the pass and fail pattern in §10 does not.

scikit-image 0.27.0rc2.dev0