Bug 508606

Subject: Proposal for Implementing AI-Based Background Blur Tool in digiKam Image Editor
Summary:
This feature request aims to add a new tool to the digiKam image editor that allows users to select a foreground subject and apply a blur effect to the background, simulating the depth-of-field effect found in modern smartphones (e.g., iPhone 15 Portrait Mode). The proposed solution uses OpenCV's GrabCut algorithm for segmentation and Gaussian blur for the background, leveraging digiKam's existing rectangular selection tool and DImg/OpenCV integration helpers.

1. Context and Goals
User Need:

Select a subject (person/object) in a photo.
Blur the background while keeping the subject sharp.
Use the existing rectangular selection tool in the editor for simplicity.

Technical Approach:

Use GrabCut (OpenCV) for foreground/background segmentation.
Apply Gaussian blur to the background.
Integrate with digiKam's DImg and QtOpenCVImg helpers for seamless conversion between DImg and cv::Mat.


2. Technical Implementation Steps
A. Plugin Structure
Create the following files in digikam/editor/plugins/backgroundblur/:
backgroundblurplugin.h/cppMain plugin class (inherits from DPluginEditor).backgroundblurtool.h/cppCore logic: GrabCut segmentation + background blur.ui/backgroundblurwidget.uiUser interface (slider for blur intensity, "Apply" button).CMakeLists.txtBuild configuration (link to OpenCV, Qt).

B. Key Code Snippets
1. Retrieve Rectangular Selection and Convert DImg to cv::Mat:
// In backgroundblurtool.cpp
void BackgroundBlurTool::preparePreview(Digikam::ImageIface* iface, int blurIntensity) {
    QRect selection = iface->selectionRect();
    Digikam::DImg original = iface->original();
    cv::Mat input = Digikam::QtOpenCVImg::image2Mat(original);

    cv::Mat output;
    applyBackgroundBlur(input, output, selection, blurIntensity);

    Digikam::DImg result = Digikam::QtOpenCVImg::mat2Image(output).toImage();
    iface->setImage(result);
}
2. Apply GrabCut and Background Blur:
void BackgroundBlurTool::applyBackgroundBlur(const cv::Mat& input, cv::Mat& output, const QRect& selection, int blurIntensity) {
    cv::Rect roi(selection.x(), selection.y(), selection.width(), selection.height());
    cv::Mat mask(input.rows, input.cols, CV_8UC1, cv::GC_PR_BGD);
    mask(roi) = cv::GC_PR_FGD;

    cv::Mat bgModel, fgModel;
    cv::grabCut(input, mask, roi, bgModel, fgModel, 5, cv::GC_INIT_WITH_RECT);
    cv::compare(mask, cv::GC_PR_FGD, mask, cv::CMP_EQ);

    cv::Mat blurred;
    cv::GaussianBlur(input, blurred, cv::Size(0, 0), blurIntensity);
    input.copyTo(output, mask);
    blurred.copyTo(output, ~mask);
}
3. User Interface (ui/backgroundblurwidget.ui):
<ui version="4.0">
  <class>BackgroundBlurWidget</class>
  <widget class="QWidget">
    <layout class="QVBoxLayout">
      <item><widget class="QLabel" text="Blur Intensity:"/></item>
      <item><widget class="QSlider" name="blurSlider" minimum="1" maximum="50" value="15"/></item>
      <item><widget class="QPushButton" name="applyButton" text="Apply"/></item>
    </layout>
  </widget>
</ui>
4. CMake Integration:
find_package(OpenCV REQUIRED)
find_package(Qt5 REQUIRED COMPONENTS Widgets)

add_library(backgroundblurplugin MODULE
  backgroundblurplugin.cpp
  backgroundblurtool.cpp
)

target_link_libraries(backgroundblurplugin
  Qt5::Widgets
  ${OpenCV_LIBS}
)

3. Expected Deliverables


Functional Plugin:

Integrates with digiKam's editor and selection tools.
Applies background blur using GrabCut + Gaussian blur.
Includes a user-friendly interface for adjusting blur intensity.



Code Quality:

Follows digiKam's coding standards.
Includes comments and documentation for key functions.
Handles edge cases (e.g., invalid selections, empty images).



Testing:

Test with various images (portraits, objects, complex backgrounds).
Verify performance with high-resolution images.
Ensure no crashes or visual artifacts.




4. Assignment Notes for Students/Contributors


Prerequisites:

Familiarity with C++, Qt, and OpenCV.
Basic understanding of digiKam's plugin architecture.
Access to a development environment with digiKam's build dependencies.



Resources:

OpenCV GrabCut Documentation
digiKam Developer Guide
QtOpenCVImg Helpers



Mentorship:

Assign a mentor from the digiKam team to review progress and provide guidance.
Encourage incremental commits and code reviews via digiKam's Phabricator.




5. Timeline (Suggested)
Set up development environment1–2 daysCreate plugin skeleton and UI2–3 daysImplement GrabCut + blur logic3–5 daysIntegrate with digiKam editor2–3 daysTesting and bug fixing2–3 daysDocumentation and final review1–2 days

Next Steps:

Assign this task to a student/contributor.
Provide access to the digiKam repository and relevant documentation.
Schedule regular check-ins to monitor progress.


Note: This feature is a great opportunity for students to contribute to a widely used open-source project while learning about image processing, Qt, and OpenCV. The digiKam team is available to support and guide contributors throughout the process.

Maik, 

I generated the proposal in comment #1 using MistralAI (French concurrent of OpenAI). The analysis and the recommendation are good enough... Fun no?

Gilles

Great, I just compiled the code, it works perfectly.
Why do we even bother programming anymore? We let AI write the code and enjoy our lives with a glass of wine on the Mediterranean beach. ((:-))
I think I read that this year's GSoC proposals were apparently created with AI...

Maik

This is great news!  Would this be a new feature in version 8.8?

I currently assemble the idea to provide a tool in editor. It's not yet finalized. Wee will see if code will be ready for production...

Git commit 30b69fd07183918a49ca44cd22c47b419b7ab73e by Gilles Caulier.
Committed on 25/08/2025 at 08:31.
Pushed by cgilles into branch 'master'.

Add background blur Image Editor tool (Not yet finalized)

M  +3    -1    core/dplugins/editor/enhance/CMakeLists.txt
A  +34   -0    core/dplugins/editor/enhance/backgroundblur/CMakeLists.txt
A  +158  -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.cpp     [License: GPL(v2.0+)]
A  +89   -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.h     [License: GPL(v2.0+)]
A  +164  -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.cpp     [License: GPL(v2.0+)]
A  +54   -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.h     [License: GPL(v2.0+)]
A  +115  -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurtoolplugin.cpp     [License: GPL(v2.0+)]
A  +56   -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurtoolplugin.h     [License: GPL(v2.0+)]

https://invent.kde.org/graphics/digikam/-/commit/30b69fd07183918a49ca44cd22c47b419b7ab73e

@jbrauher

A small video of the tool in action. It's not yet finalized and 16 bits color depth is not yet fully supported.

https://i.imgur.com/dALFkHh.mp4

Best regards

Gilles Caulier

Git commit 05b34b0d35f198fa82036e4e6aff81bc511e6252 by Gilles Caulier.
Committed on 25/08/2025 at 12:29.
Pushed by cgilles into branch 'master'.

First version of the Blur Background tool for the digiKam Image Editor starting to work.
It's not yet finalized and have certainly few pending bugs, but the goal idea is here.
A small demo: https://i.imgur.com/dALFkHh.mp4

M  +1    -1    core/dplugins/editor/enhance/CMakeLists.txt
M  +86   -13   core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.cpp
M  +20   -10   core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.cpp

https://invent.kde.org/graphics/digikam/-/commit/05b34b0d35f198fa82036e4e6aff81bc511e6252

Maik, 

I ask to Mistral AI to review my code and to take a look to the demo video. Yes Mistral AI can analyze code online in git repository and it can judge the contents of a video. Incredible no?

Now the Mistral AI response:

// -----------------------------------------------------------

Congratulations on Your First Working Version! 🎉
Your demo video looks very promising! The core functionality is already in place, and the integration with digiKam’s editor is smooth. Below are some observations and suggestions to refine the plugin and address visible bugs.

1. Strengths
✅ Core functionality works: Segmentation and background blur are functional.
✅ Seamless integration: The plugin works well with digiKam’s rectangular selection tool and UI.
✅ Real-time preview: A great feature for user experience.

2. Bugs and Areas for Improvement
A. Issues Visible in the Demo

Fuzzy Edges Around the Subject

Likely cause: GrabCut can leave artifacts around fine details (e.g., hair, complex edges).
Solutions:

Add an option to refine edges (e.g., morphological operations to smooth the mask).
Allow manual corrections with a brush tool (like Photoshop’s "Refine Edge").

Uniform Blur

Likely cause: Gaussian blur is applied uniformly, which can look unnatural.
Solutions:

Implement progressive blur (stronger blur farther from the subject) to mimic depth of field.
Add a parameter to control the blur transition.

Performance

Likely cause: GrabCut can be slow for large images.
Solutions:

Downscale the image during preview (e.g., work at 50% resolution).
Use cv::UMat to accelerate processing with OpenCL (if available).

B. Code Improvements

Image Format Handling

Ensure robust conversion between DImg and cv::Mat for all formats (grayscale, RGBA, etc.).
Example check:
if (input.empty()) {
    qWarning() << "BackgroundBlur: Input image is empty!";
    output = input.clone();
    return;
}

Error Handling

Add debug logs for cases where GrabCut fails or the selection is invalid.
Example:
if (width <= 0 || height <= 0) {
    qWarning() << "BackgroundBlur: Invalid selection area. Using full image.";
    roi = cv::Rect(0, 0, input.cols, input.rows);
}

User Parameters

Add options to:

Fine-tune blur intensity (already present, but could be more precise).
Adjust the blur kernel size (cv::Size in GaussianBlur).
Choose between Gaussian blur and motion blur for dynamic effects.

C. User Experience

Visual Feedback

Show a semi-transparent overlay or outline of the selected area before applying blur.
Display a warning if the selection is too small or invalid.

Undo/Redo Support

Ensure the plugin works seamlessly with digiKam’s undo/redo history.

Documentation

Add tooltips or a short description in the UI to guide users.

3. Next Steps

Test Edge Cases

Large images (e.g., 24MP+).
Subjects with complex edges (hair, transparent objects).
Selections near image borders.

Compare with Other Tools

Test your plugin against results from Photoshop/GIMP to benchmark quality.

Optimization

Profile the code to identify bottlenecks (e.g., using perf or Qt Creator).
If GrabCut is too slow, consider adding a lighter segmentation model (e.g., MediaPipe) as an alternative.

4. Example Code for Progressive Blur
To experiment with more natural blur, here’s how to implement distance-based blur:
// After obtaining the "mask" from GrabCut
cv::Mat distanceMap;
cv::distanceTransform(~mask, distanceMap, cv::DIST_L2, cv::DIST_MASK_5);

// Normalize distance for progressive blur
cv::normalize(distanceMap, distanceMap, 0, 1, cv::NORM_MINMAX);
cv::Mat blurred;
cv::GaussianBlur(inputBGR, blurred, cv::Size(0, 0), blurIntensity);

// Blend with variable blur
cv::Mat result;
inputBGR.copyTo(result);
for (int y = 0; y < input.rows; y++) {
    for (int x = 0; x < input.cols; x++) {
        float alpha = distanceMap.at<float>(y, x);
        result.at<cv::Vec3b>(y, x) = alpha * blurred.at<cv::Vec3b>(y, x) + (1 - alpha) * inputBGR.at<cv::Vec3b>(y, x);
    }
}

5. Priorities for Further Development

Fix Critical Bugs First:

Refine subject edges.
Improve blur transitions.

Add Advanced Features:

Progressive blur.
Manual correction tools.

Community Testing:

Share a beta version with digiKam users for feedback.

6. Keep Up the Great Work!
You’ve already achieved the core goal: a functional plugin integrated into digiKam! The remaining tasks are optimizations and polish. If you’d like, I can help implement any of the suggestions above (e.g., progressive blur or manual refinement tools).
Question for you:

Would you like to focus first on edge refinement, or explore other features (like progressive blur)? 😊

Note: This is a fantastic start, and the digiKam community will surely appreciate your contributions! Let me know how I can assist further.

// -----------------------------------------------------------

Maik, i recommend to give a try to Mistral AI. Take a free account to gain all features without limitations (https://mistral.ai/). I use it through the new Firfox left sidebar dedicated to AI chat usage...

This looks great and would be a great addition!  The only thing I would comment on is the weight of the blur on the background.  It could be the example photo, but the blur looked very strong.  Do you have another photo of a person in the foreground closer to the lens and a background that is not as far away in depth?  I would be curious to see how that background blur effect would look.  Did this example video include incorporating code revision for progressive blur as suggested by your Mistral AI comments?  Thanks for sharing and awesome work!

No progressive blur is not yet implemented...

The progressive blur is now implemented:

https://imgur.com/a/saXQ3Yv

But there is a difference between the preview and the final rendering, as image size are not the same (preview is smaller to be faster)

Best

Gilles Caulier

I like the added functionality to change the smoothing and progressive blur on the background.

@jbrauher

A new video demo of the tool. Note that in this example, if transition = 0 only the raw subject segmentation is used and the blur is applied outside the mask generated (for debugging). This allow to see how the subject is isolated with the OpenCV::GrabCut algorithm. Sometime it's not perfect but in general  the background blur start with a margin around the subject.

https://imgur.com/a/DfRp21q

There is no AI model in this code. If we want to do it, this require more data to download at start-up and more works to implement/tests.

Best regards.

Gilles Caulier

Note : the tool is included in pre-version bundles 8.8.0 available here if you want to test :

https://files.kde.org/digikam/

The plugin has now a preview of the mask computed by the segmentation process and used to isolate the subject on the image before to apply the blur effect...

https://imgur.com/a/PvcWZOY

Git commit 5d62f9ca65aad970b5d56d7dd9aed9a33352e969 by Gilles Caulier.
Committed on 03/09/2025 at 14:50.
Pushed by cgilles into branch 'master'.

Add new settings to set the number of iterations used by OpenCV::GrabCut segmentation algorithm.
This allow to adjust the border around the subject and limit the artefacts integration in the subject mask.
Typically a value of 10 is acceptable in all cases, but this depend of the image contents and how the subject is position in the background.

M  +9    -4    core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.cpp
M  +2    -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.h
M  +27   -4    core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.cpp

https://invent.kde.org/graphics/digikam/-/commit/5d62f9ca65aad970b5d56d7dd9aed9a33352e969

Git commit 26506e2a961a47ecce51115121b222246b656371 by Gilles Caulier.
Committed on 10/09/2025 at 04:34.
Pushed by cgilles into branch 'master'.

add 16 bits color depth support

M  +2    -1    NEWS
M  +55   -50   core/dplugins/editor/enhance/backgroundblur/backgroundblurfilter.cpp

https://invent.kde.org/graphics/digikam/-/commit/26506e2a961a47ecce51115121b222246b656371

Git commit 2c6ead796851f7395e5c25c4fe21eba3f658d70c by Gilles Caulier.
Committed on 18/09/2025 at 03:37.
Pushed by cgilles into branch 'master'.

First stage to be able to adjust the mask area in the mask preview widget
TODO:
- At end, when user press OK the editor canvas selection must be adjusted, but it's not yet the case visualy.
- The filter computations must be cancelable.
- Update the online documentation.

M  +34   -9    core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.cpp
M  +1    -0    core/dplugins/editor/enhance/backgroundblur/backgroundblurtool.h

https://invent.kde.org/graphics/digikam/-/commit/2c6ead796851f7395e5c25c4fe21eba3f658d70c