Add CLAHE to opencv image tool

changelog.d/20241121_062608_neildencklau_opencv_image_clahe.md

@@ -0,0 +1,4 @@
+### Added
+
+- Added contrast limited adaptive histogram equalization tool
+  (<https://github.com/cvat-ai/cvat/pull/8730>)

cvat-ui/src/components/annotation-page/standard-workspace/controls-side-bar/opencv-control.tsx

@@ -7,10 +7,11 @@ import React from 'react';
 import { connect } from 'react-redux';
 import { Row, Col } from 'antd/lib/grid';
 import Popover from 'antd/lib/popover';
-import Icon, { AreaChartOutlined, ScissorOutlined } from '@ant-design/icons';
+import Icon, { AreaChartOutlined, BarChartOutlined, ScissorOutlined } from '@ant-design/icons';
 import Text from 'antd/lib/typography/Text';
 import Tabs from 'antd/lib/tabs';
 import Button from 'antd/lib/button';
+import InputNumber from 'antd/lib/input-number';
 import Progress from 'antd/lib/progress';
 import Select from 'antd/lib/select';
 import notification from 'antd/lib/notification';
@@ -84,6 +85,9 @@ interface State {
     activeTracker: OpenCVTracker | null;
     trackers: OpenCVTracker[];
     lastTrackedFrame: number | null;
+    claheClipLimit: number;
+    claheTileColumns: number;
+    claheTileRows: number;
 }
 
 const core = getCore();
@@ -156,6 +160,9 @@ class OpenCVControlComponent extends React.PureComponent<Props & DispatchToProps
             trackers: openCVWrapper.isInitialized ? Object.values(openCVWrapper.tracking) : [],
             activeTracker: openCVWrapper.isInitialized ? Object.values(openCVWrapper.tracking)[0] : null,
             lastTrackedFrame: null,
+            claheClipLimit: 40,
+            claheTileColumns: 8,
+            claheTileRows: 8,
         };
     }
 
@@ -581,6 +588,8 @@ class OpenCVControlComponent extends React.PureComponent<Props & DispatchToProps
 
     private renderImageContent():JSX.Element {
         const { enableImageFilter, disableImageFilter, filters } = this.props;
+        const { claheClipLimit, claheTileColumns, claheTileRows } = this.state;
+
         return (
             <Row justify='start'>
                 <Col>
@@ -607,6 +616,118 @@ class OpenCVControlComponent extends React.PureComponent<Props & DispatchToProps
                         </Button>
                     </CVATTooltip>
                 </Col>
+                <Col>
+                    <CVATTooltip title='Contrast Limited Adaptive Histogram Equalization' className='cvat-opencv-image-tool'>
+                        <Button
+                            className={
+                                hasFilter(filters, ImageFilterAlias.CLAHE) ?
+                                    'cvat-opencv-clahe-tool-button cvat-opencv-image-tool-active' : 'cvat-opencv-clahe-tool-button'
+                            }
+                            onClick={(e: React.MouseEvent<HTMLElement>) => {
+                                if (!hasFilter(filters, ImageFilterAlias.CLAHE)) {
+                                    enableImageFilter({
+                                        modifier: openCVWrapper.imgproc.clahe(),
+                                        alias: ImageFilterAlias.CLAHE,
+                                    },
+                                    {
+                                        clipLimit: claheClipLimit,
+                                        tileGridSize: {
+                                            columns: claheTileColumns,
+                                            rows: claheTileRows,
+                                        },
+                                    });
+                                } else {
+                                    const button = e.target as HTMLElement;
+                                    button.blur();
+                                    disableImageFilter(ImageFilterAlias.CLAHE);
+                                }
+                            }}
+                        >
+                            <BarChartOutlined />
+                        </Button>
+                    </CVATTooltip>
+
+                    {hasFilter(filters, ImageFilterAlias.CLAHE) && (
+                        <div>
+                            <Row align='middle' gutter={8}>
+                                <Col span={12}>Clip Limit:</Col>
+                                <Col span={12}>
+                                    <InputNumber
+                                        min={1}
+                                        max={255}
+                                        step={1}
+                                        value={claheClipLimit}
+                                        onChange={(value) => {
+                                            this.setState({
+                                                claheClipLimit: value || 40,
+                                            });
+                                            enableImageFilter({
+                                                modifier: openCVWrapper.imgproc.clahe(),
+                                                alias: ImageFilterAlias.CLAHE,
+                                            }, {
+                                                clipLimit: value || 40,
+                                                tileGridSize: {
+                                                    columns: claheTileColumns,
+                                                    rows: claheTileRows,
+                                                },
+                                            });
+                                        }}
+                                    />
+                                </Col>
+                            </Row>
+                            <Row align='middle' gutter={8}>
+                                <Col span={12}>Tile Rows:</Col>
+                                <Col span={12}>
+                                    <InputNumber
+                                        min={1}
+                                        max={128}
+                                        value={claheTileColumns}
+                                        onChange={(value) => {
+                                            this.setState({
+                                                claheTileColumns: value || 8,
+                                            });
+                                            enableImageFilter({
+                                                modifier: openCVWrapper.imgproc.clahe(),
+                                                alias: ImageFilterAlias.CLAHE,
+                                            }, {
+                                                clipLimit: claheClipLimit,
+                                                tileGridSize: {
+                                                    columns: value || 8,
+                                                    rows: claheTileRows,
+                                                },
+                                            });
+                                        }}
+                                    />
+                                </Col>
+                            </Row>
+                            <Row align='middle' gutter={8}>
+                                <Col span={12}>Tile Columns:</Col>
+                                <Col span={12}>
+                                    <InputNumber
+                                        min={1}
+                                        max={128}
+                                        value={claheTileRows}
+                                        onChange={(value) => {
+                                            this.setState({
+                                                claheTileRows: value || 8,
+                                            });
+                                            enableImageFilter({
+                                                modifier: openCVWrapper.imgproc.clahe(),
+                                                alias: ImageFilterAlias.CLAHE,
+                                            }, {
+                                                clipLimit: claheClipLimit,
+                                                tileGridSize: {
+                                                    columns: claheTileColumns,
+                                                    rows: value || 8,
+                                                },
+                                            });
+                                        }}
+                                    />
+                                </Col>
+                            </Row>
+                        </div>
+                    )}
+                </Col>
             </Row>
         );
     }

cvat-ui/src/utils/image-processing.tsx

@@ -32,6 +32,7 @@ export interface ImageFilter {
 
 export enum ImageFilterAlias {
     HISTOGRAM_EQUALIZATION = 'opencv.histogramEqualizaton',
+    CLAHE = 'opencv.CLAHE',
     GAMMA_CORRECTION = 'fabric.gammaCorrection',
 }
 

cvat-ui/src/utils/opencv-wrapper/clahe.ts

@@ -0,0 +1,81 @@
+// Copyright (C) 2021-2022 Intel Corporation
+// Copyright (C) 2023 CVAT.ai Corporation
+//
+// SPDX-License-Identifier: MIT
+
+import { BaseImageFilter, ImageProcessing } from 'utils/image-processing';
+
+export interface CLAHE extends ImageProcessing {
+    processImage: (src: ImageData, frameNumber: number) => ImageData;
+}
+
+export default class CLAHEImplementation extends BaseImageFilter {
+    private cv:any;
+    // same defaults as opencv
+    private clipLimit: number = 40.0;
+    private tileGridSize: { rows: number, columns: number } = { rows: 8, columns: 8 };
+
+    constructor(cv:any) {
+        super();
+        this.cv = cv;
+    }
+
+    public configure(options: {
+        clipLimit?: number,
+        tileGridSize?: { width: number, height: number }
+    }): void {
+        if (options.clipLimit !== undefined) {
+            this.clipLimit = options.clipLimit;
+        }
+        if (options.tileGridSize !== undefined) {
+            this.tileGridSize = options.tileGridSize;
+        }
+    }
+
+    public processImage(src:ImageData, frameNumber: number) : ImageData {
+        const { cv } = this;
+        let matImage = null;
+        const RGBImage = new cv.Mat();
+        const YUVImage = new cv.Mat();
+        const RGBDist = new cv.Mat();
+        const YUVDist = new cv.Mat();
+        const RGBADist = new cv.Mat();
+        let channels = new cv.MatVector();
+        const equalizedY = new cv.Mat();
+        const tileGridSize = new cv.Size(this.tileGridSize.rows, this.tileGridSize.columns);
+        const clahe = new cv.CLAHE(this.clipLimit, tileGridSize);
+        try {
+            this.currentProcessedImage = frameNumber;
+            matImage = cv.matFromImageData(src);
+            cv.cvtColor(matImage, RGBImage, cv.COLOR_RGBA2RGB, 0);
+            cv.cvtColor(RGBImage, YUVImage, cv.COLOR_RGB2YUV, 0);
+            cv.split(YUVImage, channels);
+            const [Y, U, V] = [channels.get(0), channels.get(1), channels.get(2)];
+            channels.delete();
+            channels = null;
+            clahe.apply(Y, equalizedY);
+            clahe.delete();
+            Y.delete();
+            channels = new cv.MatVector();
+            channels.push_back(equalizedY); equalizedY.delete();
+            channels.push_back(U); U.delete();
+            channels.push_back(V); V.delete();
+            cv.merge(channels, YUVDist);
+            cv.cvtColor(YUVDist, RGBDist, cv.COLOR_YUV2RGB, 0);
+            cv.cvtColor(RGBDist, RGBADist, cv.COLOR_RGB2RGBA, 0);
+            const arr = new Uint8ClampedArray(RGBADist.data, RGBADist.cols, RGBADist.rows);
+            const imgData = new ImageData(arr, src.width, src.height);
+            return imgData;
+        } catch (e) {
+            throw new Error(e.toString());
+        } finally {
+            if (matImage) matImage.delete();
+            if (channels) channels.delete();
+            RGBImage.delete();
+            YUVImage.delete();
+            RGBDist.delete();
+            YUVDist.delete();
+            RGBADist.delete();
+        }
+    }
+}

cvat-ui/src/utils/opencv-wrapper/opencv-wrapper.ts

@@ -6,6 +6,7 @@
 import { ObjectState, ShapeType, getCore } from 'cvat-core-wrapper';
 import waitFor from 'utils/wait-for';
 import config from 'config';
+import CLAHEImplementation, { CLAHE } from './clahe';
 import HistogramEqualizationImplementation, { HistogramEqualization } from './histogram-equalization';
 import TrackerMImplementation from './tracker-mil';
 import IntelligentScissorsImplementation, { IntelligentScissors } from './intelligent-scissors';
@@ -33,6 +34,7 @@ export interface Contours {
 
 export interface ImgProc {
     hist: () => HistogramEqualization;
+    clahe: () => CLAHE;
 }
 
 export interface Tracking {
@@ -299,6 +301,7 @@ export class OpenCVWrapper {
         this.checkInitialization();
         return {
             hist: () => new HistogramEqualizationImplementation(this.cv),
+            clahe: () => new CLAHEImplementation(this.cv),
         };
     }
 

site/content/en/docs/manual/advanced/ai-tools.md

@@ -31,7 +31,9 @@ See:
   - [OpenCV: annotate with trackers](#opencv-annotate-with-trackers)
   - [When tracking](#when-tracking)
   - [Trackers models](#trackers-models)
-- [OpenCV: histogram equalization](#opencv-histogram-equalization)
+- [OpenCV](#opencv)
+  - [Histogram Equalization](#opencv-histogram-equalization)
+  - [Contrast Limited Adaptive Histogram Equalization](#opencv-clahe)
 
 ## Interactors
 
@@ -280,7 +282,8 @@ All annotated objects will be automatically tracked when you move to the next fr
 
 <!--lint enable maximum-line-length-->
 
-## OpenCV: histogram equalization
+## OpenCV
+### Histogram Equalization
 
 **Histogram equalization** improves
 the contrast by stretching the intensity range.
@@ -306,3 +309,15 @@ Example of the result:
 ![](/images/image222.jpg)
 
 To disable **Histogram equalization**, click on the button again.
+
+### Contrast Limited Adaptive Histogram Equalization
+Contrast Limited Adaptive Histogram Equalization (CLAHE) increases contrast by applying clipped histogram equalization to multiple tiles across the input image. In images where there are both very bright and very dark regions, this improves contrast in the dark regions without loosing contrast in the bright ones.
+
+#### Parameters
+* Clip Limit: Maximum value a pixel can be adjusted. Higher values allow for noise to be over-amplified.
+* Tile Rows: How many rows of tiles to break the image into.
+* Tile Columns: How many columns of tiles to break the image into.
+
+
+User Interface
+![](/images/opencv-image-clahe_interaction.jpg)