Adding contrast-limited adaptive histogram equalization (CLAHE) to DALI image operators #6069

tonyreina · 2025-10-14T23:58:58Z

Category:

New feature (non-breaking change which adds functionality)

Description:

This PR adds Contrast-Limited Adaptive Histogram Equalization (CLAHE) to the DALI image operators.

CLAHE performs local histogram equalization with clipping and bilinear blending of lookup tables (LUTs) between neighboring tiles. This technique enhances local contrast while preventing over-amplification of noise. The implementation maintains exact algorithmic compatibility with OpenCV's cv::createCLAHE() while providing significant GPU performance optimizations.

Additional information:

Affected modules and functionalities:

Added clahe_op.cc and clahe_op.cu for GPU implementation with CUDA kernels
Added clahe_cpu.cc for CPU implementation using OpenCV
Added comprehensive operator schema with detailed documentation
Added Jupyter Notebook example

Key points relevant for the review:

Algorithmic Compatibility: Follows the algorithm used by OpenCV
Performance Optimizations: Includes automatic optimizations:
- Kernel fusion (RGB→LAB + histogram computation)
- Warp-privatized histograms for larger tiles (≥1024 pixels)
- Vectorized memory access for larger images (≥8192 pixels)
- Adaptive algorithm selection based on image size and tile configuration
Feature Support:
- Supports grayscale (1-channel) and RGB (3-channel) uint8 images in HWC layout
- Two RGB processing modes: luminance-only (preserves color relationships) and per-channel
- Configurable tile grid, clip limit, and histogram bins

Tests:

New tests added
- Python tests: test_clahe.py with multiple parameter combinations, device testing (CPU/GPU), and API validation
- GTests: clahe_test.cc with CPU vs GPU equivalence testing, different tile sizes, clip limits, and error handling
- Example: clahe_example.py demonstrating usage patterns and parameter effects
- Benchmark: Performance benchmarking could be added in future work

Checklist

Documentation

Documentation updated
- Docstring: Comprehensive operator schema documentation with parameter descriptions and usage examples
- Doxygen: C++ code documentation following DALI conventions
- RST: Added CLAHE optimizations section to performance tuning guide
- Other: Performance optimization details documented in PERFORMANCE_NOTES.md

DALI team only

Requirements

Implements new requirements
Affects existing requirements
N/A

REQ IDs: N/A

JIRA TASK: N/A

examples/clahe_example.py

dali/operators/image/clahe/clahe_op.cc

dali/test/python/operator_1/test_clahe.py

JanuszL · 2025-10-15T05:40:20Z

@tonyreina, thank you for your contribution. We appreciate the time you spent diving into DALI and extending it.

I haven't delved deeply into the code yet, as I focused more on general remarks - mostly regarding testing, examples, and memory management. Please let us know if you need any guidance in applying the suggestions.

dali/operators/image/clahe/clahe_op.cu

docs/advanced_topics_performance_tuning.rst

dali/operators/image/clahe/clahe_op.cu

dali/operators/image/clahe/clahe_op.cc

dali/operators/image/clahe/clahe_op.cu

dali/operators/image/clahe/clahe_op.cc

dali/operators/image/clahe/PERFORMANCE_NOTES.md

review-notebook-app · 2025-10-15T22:52:30Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

dali/operators/image/clahe/clahe_op.cu

jantonguirao · 2025-10-16T09:37:11Z

!build

dali-automaton · 2025-10-16T09:40:57Z

CI MESSAGE: [36715300]: BUILD STARTED

jantonguirao · 2025-10-16T11:35:26Z

Would be nice to add images to the example, to see the effect of this transformation visually

dali/operators/image/clahe/clahe_cpu.cc

dali/operators/image/clahe/clahe_op.cc

dali/operators/image/clahe/clahe_op.cu

dali/test/python/operator_1/test_clahe.py

Signed-off-by: Tony Reina <[email protected]>

tonyreina · 2025-11-13T19:50:01Z

Can you re-try the build and tests?

Could you please render the Jupyter notebook and upload it in that format?

Rendered.

greptile-apps

_{13 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

dali/test/python/operator_1/test_clahe.py

dali/operators/image/clahe/clahe_op.cu

dali-automaton · 2025-11-13T20:04:59Z

CI MESSAGE: [38418710]: BUILD FAILED

Signed-off-by: Tony Reina <[email protected]>

greptile-apps

_{13 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

dali/operators/image/clahe/clahe_op.cu

dali/operators/image/clahe/clahe_cpu.cc

dali/test/python/operator_1/test_clahe.py

tonyreina · 2025-11-13T21:35:16Z

Is there a build error message?

JanuszL · 2025-11-14T06:02:29Z

Is there a build error message?

Let me rerun this with the latest changes.

JanuszL · 2025-11-14T08:09:41Z

!build

dali-automaton · 2025-11-14T08:15:25Z

CI MESSAGE: [38479272]: BUILD STARTED

JanuszL · 2025-11-14T18:42:02Z

I see following errors:
Gtest:

[2025-11-14 09:47:15] [ RUN      ] ClaheOpTest.LumaOnlyVsPerChannel
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] unknown file: Failure
[2025-11-14 09:47:15] C++ exception with description "Critical error in pipeline:
[2025-11-14 09:47:15] Critical error in pipeline:
[2025-11-14 09:47:15] Error in GPU operator `nvidia.dali.ops.Clahe` encountered:
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] ClaheGPU RGB input requires luma_only=True; per-channel mode (luma_only=False) is not supported on GPU. Use CPU backend for per-channel processing.
[2025-11-14 09:47:15] Current pipeline object is no longer valid.
[2025-11-14 09:47:15] Current pipeline object is no longer valid." thrown in the test body.
[2025-11-14 09:47:15]

test_clahe.py

[2025-11-14 11:02:30] ======================================================================
[2025-11-14 11:02:30] ERROR: test_clahe (nose2.loader.ModuleImportFailure)
[2025-11-14 11:02:30] ----------------------------------------------------------------------
[2025-11-14 11:02:30] ImportError: Failed to import test module: test_clahe
[2025-11-14 11:02:30] Traceback (most recent call last):
[2025-11-14 11:02:30]   File "/usr/local/lib/python3.10/dist-packages/nose2/plugins/loader/discovery.py", line 195, in _find_tests_in_file
[2025-11-14 11:02:30]     module = util.module_from_name(module_name)
[2025-11-14 11:02:30]   File "/usr/local/lib/python3.10/dist-packages/nose2/util.py", line 73, in module_from_name
[2025-11-14 11:02:30]     __import__(name)
[2025-11-14 11:02:30]   File "/opt/dali/dali/test/python/operator_1/test_clahe.py", line 17, in <module>
[2025-11-14 11:02:30]     import pytest
[2025-11-14 11:02:30] ModuleNotFoundError: No module named 'pytest
'```

dali-automaton · 2025-11-14T20:33:05Z

CI MESSAGE: [38479272]: BUILD FAILED

Signed-off-by: Tony Reina <[email protected]>

tonyreina · 2025-11-17T20:11:31Z

I see following errors: Gtest:

[2025-11-14 09:47:15] [ RUN      ] ClaheOpTest.LumaOnlyVsPerChannel
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] !!! Forced use of Executor 2.0 !!!
[2025-11-14 09:47:15] unknown file: Failure
[2025-11-14 09:47:15] C++ exception with description "Critical error in pipeline:
[2025-11-14 09:47:15] Critical error in pipeline:
[2025-11-14 09:47:15] Error in GPU operator `nvidia.dali.ops.Clahe` encountered:
[2025-11-14 09:47:15] 
[2025-11-14 09:47:15] ClaheGPU RGB input requires luma_only=True; per-channel mode (luma_only=False) is not supported on GPU. Use CPU backend for per-channel processing.
[2025-11-14 09:47:15] Current pipeline object is no longer valid.
[2025-11-14 09:47:15] Current pipeline object is no longer valid." thrown in the test body.
[2025-11-14 09:47:15]

test_clahe.py

[2025-11-14 11:02:30] ======================================================================
[2025-11-14 11:02:30] ERROR: test_clahe (nose2.loader.ModuleImportFailure)
[2025-11-14 11:02:30] ----------------------------------------------------------------------
[2025-11-14 11:02:30] ImportError: Failed to import test module: test_clahe
[2025-11-14 11:02:30] Traceback (most recent call last):
[2025-11-14 11:02:30]   File "/usr/local/lib/python3.10/dist-packages/nose2/plugins/loader/discovery.py", line 195, in _find_tests_in_file
[2025-11-14 11:02:30]     module = util.module_from_name(module_name)
[2025-11-14 11:02:30]   File "/usr/local/lib/python3.10/dist-packages/nose2/util.py", line 73, in module_from_name
[2025-11-14 11:02:30]     __import__(name)
[2025-11-14 11:02:30]   File "/opt/dali/dali/test/python/operator_1/test_clahe.py", line 17, in <module>
[2025-11-14 11:02:30]     import pytest
[2025-11-14 11:02:30] ModuleNotFoundError: No module named 'pytest
'```

ok. please try the build again.

thanks!

-Tony

greptile-apps

Additional Comments (1)

docs/examples/image_processing/clahe_example.ipynb, line 1 (link)

logic: Notebook file is completely empty with no content. The PR description mentions a comprehensive Jupyter Notebook example demonstrating CLAHE usage patterns and parameter effects, but this file contains nothing. Users will have no practical example of how to use the new CLAHE operator.

_{13 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}
_{React with 👍 or 👎 to share your feedback on this new summary format}

dali/test/python/operator_1/test_clahe.py

dali-automaton · 2025-11-17T20:21:36Z

CI MESSAGE: [38651866]: BUILD STARTED

dali-automaton · 2025-11-17T22:40:27Z

CI MESSAGE: [38651866]: BUILD FAILED

tonyreina · 2025-11-17T23:44:14Z

CI MESSAGE: [38651866]: BUILD FAILED

What was the latest build error?

Is there a way I can run this build test from the docker/build.sh?

JanuszL · 2025-11-18T06:44:23Z

@tonyreina
It seems that only one issue remains:

[2025-11-17 22:00:06] [ RUN      ] ClaheOpTest.GpuRejectsPerChannelMode
[2025-11-17 22:00:06] 
[2025-11-17 22:00:06] !!! Forced use of Executor 2.0 !!!
[2025-11-17 22:00:06] /opt/dali/dali/operators/image/clahe/clahe_test.cc:202: Failure
[2025-11-17 22:00:06] Expected: pipe.Run() throws an exception of type std::runtime_error.
[2025-11-17 22:00:06]   Actual: it throws nothing.```

Signed-off-by: Tony Reina <[email protected]>

greptile-apps

Additional Comments (1)

docs/examples/image_processing/clahe_example.ipynb, line 1 (link)

logic: Empty notebook file provides no documentation despite PR claiming comprehensive example. This completely fails to deliver the promised educational content for CLAHE operator usage. Was this notebook supposed to contain actual example code and documentation, or is this an accidental commit of an empty file?

_{13 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}
_{React with 👍 or 👎 to share your feedback on this new summary format}

dali/operators/image/clahe/clahe_op.cc

dali/test/python/operator_1/test_clahe.py

JanuszL · 2025-11-18T17:40:50Z

!build

tonyreina · 2025-11-18T17:41:07Z

@tonyreina It seems that only one issue remains:

[2025-11-17 22:00:06] [ RUN      ] ClaheOpTest.GpuRejectsPerChannelMode
[2025-11-17 22:00:06] 
[2025-11-17 22:00:06] !!! Forced use of Executor 2.0 !!!
[2025-11-17 22:00:06] /opt/dali/dali/operators/image/clahe/clahe_test.cc:202: Failure
[2025-11-17 22:00:06] Expected: pipe.Run() throws an exception of type std::runtime_error.
[2025-11-17 22:00:06]   Actual: it throws nothing.```

Ok. I think I've got it now. I was able to do the GTest on my side using some mods to the build.sh script (but didn't push these).

JanuszL · 2025-11-18T17:42:01Z

@tonyreina It seems that only one issue remains:
[2025-11-17 22:00:06] [ RUN      ] ClaheOpTest.GpuRejectsPerChannelMode
[2025-11-17 22:00:06] 
[2025-11-17 22:00:06] !!! Forced use of Executor 2.0 !!!
[2025-11-17 22:00:06] /opt/dali/dali/operators/image/clahe/clahe_test.cc:202: Failure
[2025-11-17 22:00:06] Expected: pipe.Run() throws an exception of type std::runtime_error.
[2025-11-17 22:00:06]   Actual: it throws nothing.```
Ok. I think I've got it now. I was able to do the GTest on my side using some mods to the build.sh script (but didn't push these).

Thank you. Let me give it a go.

tonyreina · 2025-11-19T00:13:19Z

I think it couldn't be scheduled for the build.

dali-automaton · 2025-11-19T05:52:24Z

CI MESSAGE: [38766317]: BUILD STARTED

dali-automaton · 2025-11-19T14:31:53Z

CI MESSAGE: [38766317]: BUILD PASSED

JanuszL · 2025-11-20T06:17:52Z

@tonyreina the CI is passing so please let us review the latest changes again. We hope to do that soon (it is over 4k lines of code after all).

JanuszL reviewed Oct 15, 2025

View reviewed changes

examples/clahe_example.py Outdated Show resolved Hide resolved

JanuszL reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cc Outdated Show resolved Hide resolved

JanuszL reviewed Oct 15, 2025

View reviewed changes

dali/test/python/operator_1/test_clahe.py Outdated Show resolved Hide resolved

JanuszL reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

docs/advanced_topics_performance_tuning.rst Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cc Outdated Show resolved Hide resolved

dali-automaton assigned mdabek-nvidia, jantonguirao and klecki Oct 15, 2025

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cc Outdated Show resolved Hide resolved

mzient reviewed Oct 15, 2025

View reviewed changes

dali/operators/image/clahe/PERFORMANCE_NOTES.md Outdated Show resolved Hide resolved

tonyreina force-pushed the main branch 2 times, most recently from 084b2f1 to 4e087d2 Compare October 15, 2025 18:01

tonyreina closed this Oct 15, 2025

tonyreina force-pushed the main branch from 4e087d2 to e5d5c9a Compare October 15, 2025 18:11

mzient assigned mzient and unassigned klecki Oct 15, 2025

tonyreina reopened this Oct 15, 2025

tonyreina requested review from JanuszL and mzient October 15, 2025 22:59

mzient reviewed Oct 16, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

jantonguirao reviewed Oct 16, 2025

View reviewed changes

render notebook

cc3bc52

Signed-off-by: Tony Reina <[email protected]>

tonyreina requested a review from mzient November 13, 2025 19:49

greptile-apps bot reviewed Nov 13, 2025

View reviewed changes

dali/test/python/operator_1/test_clahe.py Outdated Show resolved Hide resolved

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

dali/operators/image/clahe/clahe_op.cu Outdated Show resolved Hide resolved

fixed test

313acdd

Signed-off-by: Tony Reina <[email protected]>

greptile-apps bot reviewed Nov 13, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cu Show resolved Hide resolved

dali/operators/image/clahe/clahe_cpu.cc Show resolved Hide resolved

dali/test/python/operator_1/test_clahe.py Show resolved Hide resolved

tonyreina added 2 commits November 17, 2025 09:49

updating tests

fd8178c

Signed-off-by: Tony Reina <[email protected]>

Merge remote-tracking branch 'upstream/main'

6b1306a

Signed-off-by: Tony Reina <[email protected]>

greptile-apps bot reviewed Nov 17, 2025

View reviewed changes

dali/test/python/operator_1/test_clahe.py Show resolved Hide resolved

update clahe tests

aa6db7c

Signed-off-by: Tony Reina <[email protected]>

greptile-apps bot reviewed Nov 18, 2025

View reviewed changes

dali/operators/image/clahe/clahe_op.cc Show resolved Hide resolved

dali/test/python/operator_1/test_clahe.py Show resolved Hide resolved

Adding contrast-limited adaptive histogram equalization (CLAHE) to DALI image operators #6069

Are you sure you want to change the base?

Adding contrast-limited adaptive histogram equalization (CLAHE) to DALI image operators #6069

Uh oh!

Conversation

tonyreina commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Category:

Description:

Additional information:

Affected modules and functionalities:

Key points relevant for the review:

Tests:

Checklist

Documentation

DALI team only

Requirements

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JanuszL commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

review-notebook-app bot commented Oct 15, 2025

Uh oh!

Uh oh!

jantonguirao commented Oct 16, 2025

Uh oh!

dali-automaton commented Oct 16, 2025

Uh oh!

jantonguirao commented Oct 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tonyreina commented Nov 13, 2025

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dali-automaton commented Nov 13, 2025

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tonyreina commented Nov 13, 2025

Uh oh!

JanuszL commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JanuszL commented Nov 14, 2025

Uh oh!

dali-automaton commented Nov 14, 2025

Uh oh!

JanuszL commented Nov 14, 2025

Uh oh!

dali-automaton commented Nov 14, 2025

Uh oh!

tonyreina commented Nov 17, 2025

tonyreina commented Oct 14, 2025 •

edited

Loading

JanuszL commented Nov 14, 2025 •

edited

Loading

greptile-apps bot left a comment •

edited

Loading

greptile-apps bot left a comment •

edited

Loading