Repository navigation
nnUNetv2_plot_overlay_pngs: fix IndexError with more than 15 labels and wrong slice selection - #3091
Conversation
…lection generate_overlay indexed color_cycle (15 colors) with the position of each label among the labels present in the slice, so any slice with background plus 15 or more labels raised an IndexError. Indices beyond the cycle now wrap around the non-background colors. select_slice_to_plot2 is meant to pick the slice with the highest mean fraction of each class' voxels, but divided each class' per-slice counts by the sum over all classes processed so far instead of by that class' own total. That underweights every class after the first and can select a slice without the small classes it is designed to show.
There was a problem hiding this comment.
🔍 nnU-Net Code Review
Summary
This PR fixes two bugs in nnUNetv2_plot_overlay_pngs (nnunetv2/utilities/overlay_plots.py):
generate_overlayraises anIndexErrorwhen a slice contains more labels thancolor_cyclehas entries.select_slice_to_plot2normalises each class column by the wrong total.
It also adds unit tests for both.
Contribution Guidelines
- Bug fix requirements: Met. The description has a minimal repro with master and PR output, explains the root cause of both bugs and describes the fix.
- General applicability: Fine. This is a small fix to a generic diagnostic tool and adds no dataset-specific code.
- Scope: Small and focused. No prior issue was needed.
- Compatibility: No public signatures change. The functions are only used inside this module (the console entry point and the plot helpers). Nothing touches training, inference, plans or result files, so custom trainers are unaffected and no changelog entry is needed.
Key Findings
-
select_slice_to_plot2fix is correct (overlay_plots.py~L132). On master,fg_per_slice.sum()is evaluated after the earlier columns have already been normalised to 1. Columniwas therefore divided bycount_i + iinstead ofcount_i. The error is small for large classes, but for small classes it is large: a 1-voxel class ati=1scores 0.5 instead of 1.0. Dividing byfg_per_slice[:, i].sum()matches the docstring's intent. I checked the newtest_small_class_is_not_underweightedby hand:- master picks slice 0 (0.30 vs 0.25), so the test fails there;
- the fix picks slice 2 (0.5 vs 0.3).
The test therefore does pin the bug.
-
Colour wrap-around is correct.
1 + (idx - 1) % (len(color_cycle) - 1)mapsn → 1andn+1 → 2, and never returns 0. The black background colour is never reused. Indices inside the cycle are unchanged, so overlays for datasets with ≤15 labels are byte-identical to master. The wrap uses thecolor_cycleparameter rather than the module constant, so custom cycles passed by callers are handled too. -
Tests: They are deterministic, need no env vars or data and run fast. They match the style of the other files in
nnunetv2/tests/.test_matches_per_class_fractionsis a useful independent check of the intended formula.
Minor Suggestions (non-blocking)
- Custom
color_cycleof length 1: The wrap branch now raisesZeroDivisionError(% 0) where master raisedIndexError. This is purely theoretical, but a short assert or a clearer error would be friendlier. - Pre-existing, not introduced here — label 0 absent from a slice: When
mapping is None, the mapping is built from the labels present in that slice. If a slice has no background, the first foreground label gets index 0, which is black, so it is invisible. For the same reason, a given label can get different colours in different cases. That is outside this PR's scope, but it could be a follow-up. One option is to always reserve index 0 for label 0, or to build the mapping from all labels in the dataset. - Wrapped colours repeat: With more than 15 foreground labels, different labels now share colours. That is acceptable for a sanity-check overlay, and the docstring update documents it.
|
Thanks! |
nnUNetv2_plot_overlay_pngs(the tool the readers' alignment warnings point users to) has two bugs innnunetv2/utilities/overlay_plots.py. The first makes it crash on datasets with many labels. The second makes it pick the wrong slice.Reproduction
On master:
With this PR:
I also checked it end to end with
plot_overlayon a small synthetic NIfTI pair (SimpleITKIO) with 15 foreground labels in one slice. On master it fails with the sameIndexError, and with the fix it writes the PNG.Root cause and fix
generate_overlaycrashes when a slice has more than 15 labels. It buildsmappingby enumerating the labels present in the slice and then indexescolor_cycle(15 entries) with that position. Any slice that contains background plus 15 or more labels raises anIndexError, and so doesplot_overlay/plot_overlay_preprocessed. Indices past the end of the cycle now wrap around the colors after the first one. The first color stays reserved for the background, so no label gets painted black. Indices that are inside the cycle map exactly as before, so overlays for datasets with up to 15 labels do not change.select_slice_to_plot2normalizes by the wrong total. It is meant to pick the slice with the highest mean, over classes, of "fraction of this class' voxels in this slice". But it didfg_per_slice[:, i] /= fg_per_slice.sum(), which divides by the sum of the whole array. At that point that sum is the column being normalized plus all columns already normalized (each of which sums to 1). Only the first class was normalized correctly. Every later class was divided by roughlycount + i, which underweights small classes most, and those are the ones this function exists to show. In the example above, slice 2 holds 100 % of class 2 (mean 0.5) and slice 0 holds 60 % of class 1 (mean 0.3). Master picks slice 0, which contains no class 2. The fix divides each column by its own sum.Tests
nnunetv2/tests/test_overlay_plots.py:Three of the four tests fail on master and all four pass with the fix. The fourth (the random label map) happens to pick the same slice on master and is there as an oracle check.