[dzenanz]

Add ProcessObject::SetWorkUnitToThreadRatio so a filter can override its threader's default work units per thread, and set it in 37 classes that are faster with fewer work units. Closes #950.

Design

• Ratio 0 (default) keeps the multithreader's own default: Platform 1, Pool 4, TBB 16 work units per thread.
• A non-zero ratio sets the default NumberOfWorkUnits to ratio × GetMultiThreader()->GetMaximumNumberOfThreads(), clamped to [1, ITK_MAX_THREADS]. Filters set it in their constructor.
• An explicitly set NumberOfWorkUnits is kept. Changing the multithreader keeps the existing SetMultiThreader rule.
• The ratio-derived count goes through the virtual SetNumberOfWorkUnits, so composite filters that forward it to internal filters (e.g. GrayscaleErodeImageFilter) see it.
• Composites that forward their own count to an inner ratio-limited filter on every update get the inner filter's ratio, otherwise they would override it.

Classes changed

Ratio	Classes	Per-work-unit cost
1	BoxMeanImageFilter, BoxSigmaImageFilter	pad and accumulate region + radius
1	AnchorErodeDilateImageFilter, AnchorOpenCloseImageFilter, VanHerkGilWermanErodeDilateImageFilter (and their Erode/Dilate/Open/Close subclasses)	copy and filter region + kernel radius
1	BSplineScatteredDataPointSetToImageFilter	allocate, zero, reduce whole lattices
1	BinaryImageToLabelMapFilter, ConnectedComponentImageFilter	a line per boundary in the serial equivalence pass
1	10 binary label-map composites (BinaryFillhole, BinaryGrindPeak, BinaryShape/StatisticsOpening, BinaryShape/StatisticsKeepNObjects, BinaryImageToShape/StatisticsLabelMap, BinaryReconstructionByDilation/Erosion), BinaryOpening/ClosingByReconstructionImageFilter	forward to the above
1	BlockMatchingImageFilter	last work unit gets all remaining points
1	VariationalRegistrationCurvatureRegularizer, VariationalRegistrationElasticRegularizer	work-unit count is the FFT thread count
2	ImageToHistogramFilter (and MaskedImageToHistogramFilter)	allocate, fill, merge a whole histogram
2	LabelStatisticsImageFilter	per-label statistics and histograms, merged
2	LabelImageToLabelMapFilter and 8 label composites (LabelShape/StatisticsOpening, LabelShape/StatisticsKeepNObjects, Shape/StatisticsRelabel, LabelImageToShape/StatisticsLabelMap)	one label map per work unit, merged serially
2	FFTWForward1DFFTImageFilter, FFTWInverse1DFFTImageFilter, FFTWComplexToComplex1DFFTImageFilter	one FFTW plan and two line buffers per work unit

Benchmarks (24-thread Ryzen 9 5900, MSVC 14.51 Release, Windows)

Median of 5-15 runs, ms, threader default → new default.

Case	Pool	TBB
BoxMean radius 5, 160³ uint16	117 → 52	228 → 49
AnchorOpen box radius 5, 128³ uint8	190 → 74	405 → 71
VanHerkGilWermanDilate box radius 2, 128³	67 → 30	120 → 24
GrayscaleErode box radius 2 (internal Anchor)	105 → 40	185 → 41
BSplineScatteredData fit, 40³ control points	5550 → 4530	5300 → 4330
ImageToHistogram 3 × 64 bins, 128³	214 → 166	527 → 146
LabelStatistics 8000 labels, histograms	72 → 46	137 → 57
LabelImageToLabelMap 8000 labels	39 → 33	73 → 39
BinaryImageToLabelMap 128³	840 → 791	923 → 456
BinaryFillhole 160³	3400 → 2090	3470 → 2100
ConnectedComponent 160³	1070 → 920	1160 → 491
BlockMatching 100 points	1.43 → 1.36	8.4 → 1.5
VariationalRegistrationElasticRegularizer 64³, FFTW	12.1 → 11.5	70.3 → 11.1
VariationalRegistrationCurvatureRegularizer 64³, FFTW	18.4 → 11.7	72.2 → 12.7
1-D FFTW filters, 8 cases summed, new filter per update	26.9 → 26.6	46.7 → 27.3
1-D FFTW filters, 8 cases summed, cached plans	7.1 → 6.8	5.5 → 6.6

Each case was also swept over ratios 1, 2, 4 under Platform, Pool, and TBB to pick the ratio.

Classes left at the threader default

About 110 cases covering every module with threaded code, chosen after reading all ~400 threaded source files for per-work-unit cost. Within noise or slower with fewer work units, so not changed:

• Pixel-wise, cast, rescale, pad, flip, permute, resample, warp, bin shrink.
• Neighborhood filters: mean, median, gradient, noise, bilateral, zero crossing, Hessian objectness, NeighborhoodOperatorImageFilter, recursive Gaussian.
• Moving-histogram filters: rank, MovingHistogramDilate, MaskedRank.
• Reductions with scalar state: Statistics, MinimumMaximum, SimilarityIndex, LabelOverlapMeasures, projections, Otsu.
• Label-map filters that drain a shared label-object queue, contour filters, SignedMaurerDistanceMap.
• Noise generators, anisotropic diffusion, curvature flow, Demons, narrow-band level sets, label voting, displacement-field filters, RelabelComponent.
• N-D FFTW filters (FFTW threads follow GetMaximumNumberOfThreads), PocketFFT 1-D, FFT convolution, VariationalRegistrationDiffusionRegularizer.
• BSplineControlPointImageFilter: ratio 1 helps only when the lattice is large relative to the output, and is ~10% slower for a small lattice with a large output (the N4 case).

Known trade-offs

• LabelStatisticsImageFilter with few labels is up to 0.5 ms slower at 160³.
• Cached-plan 1-D FFTW runs are ~1 ms slower in total under TBB.
• With ratio 2, PlatformMultiThreader starts two threads per core for those classes.
• Composites that forward their own count to inner filters on every update still override inner ratios elsewhere; only the label-map and reconstruction cases are covered here.

Testing

• New GTest itkProcessObjectWorkUnitToThreadRatioGTest (default, ratio from constructor, ratio change, explicit count kept, forwarding through the virtual setter), against Platform, Pool, Single, and TBB.
• Windows, MSVC Release, TBB as default threader: all 1411 tests pass in ITKCommon, ITKSmoothing, ITKMathematicalMorphology, ITKBinaryMathematicalMorphology, ITKImageStatistics, ITKLabelMap, ITKImageGrid, ITKConnectedComponents, ITKRegistrationCommon, ITKStatistics, and VariationalRegistration.
• With Module_ITKFFTW, ITK_USE_FFTWD, ITK_USE_FFTWF: all 95 ITKFFT and VariationalRegistration tests pass.
• pre-commit passes on all changed files.

AI assistance

• Tool: Claude Code (claude-opus-5-5).
• Role: implemented the ratio and its GTest, surveyed threaded classes for per-work-unit cost, wrote and ran the benchmark harness, chose ratios from the measurements, and ran the tests listed above.
• All measurements and tests ran locally on the workstation described above.

🤖 Generated with Claude Code

[blowekamp]

Threading is complicated. And this looks like extensive work that does identify some key filters that do not scale with will numerous work units.

I am in favor of adding a per filter option to set the default WorkUnitToThreadRatio, or WorkUnitMultiplier. I also thinks that there should be some kind of "GlobalDefault" settable value for this as well, or perhaps it's per multithreaded. I think this is easier to do.

However to set the defaults for these (the globals) is going to be harder. It will require the community setting clear criteria for the defaults, and then discussion and evaluation of the purposes set out. For example getting frequent progress updates may come at the expense of performance.

[dzenanz]

Good idea. As the multi-threaders already have this, it would make more sense to have this per multi-threader. We would only have to make the current thing user-settable. Changing the defaults would benefit from extensive benchmarking on multiple machines and workloads, as well as other kinds of community input and discussion. Both can be done as follow-ups to this PR, especially the discussion about defaults.

[greptile-apps]

Confidence Score: 2/5

[Medium impact] The PR changes default scheduling for selected filters across several ITK workflows.

Fix the ratio setter, the test build without Pool, and the required includes before merging.

Findings

1.  Updates break ratio defaults ▶
2.  Explicit counts get overwritten ▶
3.  Builds without Pool fail ▶
4.  Large ratios skip work ▶
5.  Required integer includes are missing ▶

Summary

Adds per-filter work-unit ratios and configurable defaults for Pool and TBB.

• Filters can set work-unit counts to match their own workload.
• Box and morphology filters use fewer work units for costly region work.
• Histogram and label-statistics filters use fewer work units for local data.
• Spline and registration filters limit work units for costly operations.
• One-dimensional FFTW filters limit work units that allocate plans and buffers.
• Label-map and connected-component filters use fewer work units for merging.

Acknowledged by dzenanz: ratio two starts extra Platform threads; small-label statistics and cached-plan TBB FFTW cases can be slower. Other enclosing filters that override inner ratios are deferred.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["SetWorkUnitToThreadRatio"] --> B["Read old default and store ratio"]
  B --> C{"Count equals old default?"}
  C -->|Yes| D["Compute new count"]
  D --> E["Call virtual SetNumberOfWorkUnits"]
  E --> F["Forward to child filters"]
  C -->|No| G["Keep current count"]
  F --> H["Mark filter changed"]
  G --> H

Loading

_{Reviews (1) · Last reviewed commit: "ENH: Add DefaultWorkUnitPerThreadRatio t..." · Reviewed by Greptile}