feat: Suzuki and Abe Contour finding implementation#767
Open
zeel991 wants to merge 11 commits intokornia:mainfrom
Open
feat: Suzuki and Abe Contour finding implementation#767zeel991 wants to merge 11 commits intokornia:mainfrom
zeel991 wants to merge 11 commits intokornia:mainfrom
Conversation
Contributor
Review Summary by QodoImplement Suzuki & Abe contour finding with SWAR optimization
WalkthroughsDescription• Implements Suzuki & Abe (1985) border-following algorithm for contour detection • Supports four retrieval modes (External, List, CComp, Tree) with full hierarchy • Includes two approximation modes (None, Simple) for contour point compression • Optimizes scanning with SWAR (Single-Word-At-a-time Read) to skip zero pixels • Provides reusable FindContoursExecutor for repeated processing without allocation • Adds comprehensive benchmarks comparing against OpenCV implementation Diagramflowchart LR
Input["Input Image<br/>u8 pixels"]
Binarize["Binarize &<br/>Virtual Pad"]
Scan["Raster Scan<br/>with SWAR"]
Trace["Trace Border<br/>Suzuki-Abe"]
Approx["Approximate<br/>None/Simple"]
Filter["Filter by<br/>Retrieval Mode"]
Output["ContoursResult<br/>contours + hierarchy"]
Input --> Binarize
Binarize --> Scan
Scan --> Trace
Trace --> Approx
Approx --> Filter
Filter --> Output
File Changes1. crates/kornia-imgproc/src/contours.rs
|
Contributor
Code Review by Qodo
1. find_countours not implemented
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new contour-finding feature to kornia-imgproc, implementing the Suzuki & Abe (1985) border-following algorithm and exposing a public find_contours API (plus an executor for reuse), along with benchmarks and unit tests.
Changes:
- Added
contoursmodule export tokornia-imgproc. - Implemented contour tracing, approximation modes, and hierarchy reconstruction with multiple retrieval modes.
- Added Criterion benchmark comparing against OpenCV (behind
opencv_benchfeature).
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
crates/kornia-imgproc/src/lib.rs |
Exposes the new contours module from the crate root. |
crates/kornia-imgproc/src/contours.rs |
Implements contour finding, hierarchy modes, reusable executor, and unit tests. |
crates/kornia-imgproc/benches/bench_contours.rs |
Adds benchmarks for contours (kornia vs OpenCV, incl. executor variants). |
crates/kornia-imgproc/Cargo.toml |
Registers the new bench_contours benchmark gated by opencv_bench. |
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Contributor
Author
128×128 — Simple approximation
256×256 — Simple approximation
512×512 — Simple approximation
1024×1024 — Simple approximation
|
Contributor
|
also please update the |
Contributor
Author
Added |
Contributor
Author
|
| Source image | Binary (threshold = 128) |
|---|---|
 |
 |
ContourApproximationMode
Controls how contour points are stored after tracing.
Demonstrated on the largest outer contour (2950 pts → 1080 pts).
None -- every border pixel (2950 pts) |
Simple -- corners only (1080 pts) |
|---|---|
 |
 |
Simple compresses horizontal, vertical, and diagonal straight runs down to
their two endpoints -- from 2950 points to 1080 points
with no loss of shape information.
// Every border pixel stored
find_contours(&image, RetrievalMode::External, ContourApproximationMode::None)?;
// Direction-change endpoints only
find_contours(&image, RetrievalMode::External, ContourApproximationMode::Simple)?;RetrievalMode
External -- outermost contours only (867 contours)
Returns only contours with no parent. Holes and nested shapes are ignored.
All hierarchy entries are [-1, -1, -1, -1].
find_contours(&image, RetrievalMode::External, ContourApproximationMode::None)?;
// contours returned: 867List -- all contours, hierarchy discarded (1739 contours)
Every contour returned in raster-scan order. Hierarchy discarded -- all entries
are [-1, -1, -1, -1].
find_contours(&image, RetrievalMode::List, ContourApproximationMode::None)?;
// contours returned: 1739CComp -- two-level hierarchy (1739 contours)
Outer borders at level 1 (green), their holes at level 2 (cyan).
Outer contours found inside holes are re-rooted to level 1.
find_contours(&image, RetrievalMode::CComp, ContourApproximationMode::None)?;
// contours returned: 1739
// hierarchy[i][3] == -1 → outer (level 1)
// hierarchy[i][3] >= 0 → hole (level 2, parent = outer)Tree -- full hierarchy, depth-coloured (1739 contours)
Full parent/child hierarchy preserved. Colour encodes nesting depth:
| Depth | Colour | Meaning |
|---|---|---|
| 0 | Green | Outermost contours |
| 1 | Orange | First-level holes |
| 2 | Blue | Nested inside depth-1 |
| 3 | Yellow | Nested inside depth-2 |
| 4 | Red | Nested inside depth-3 |
find_contours(&image, RetrievalMode::Tree, ContourApproximationMode::None)?;
// contours returned: 1739Hierarchy Entry Format -- [i32; 4]
Every contour has a parallel HierarchyEntry = [i32; 4].
Indices are 0-based positions into the contours array; -1 means absent.
| Index | Field | Meaning |
|---|---|---|
[0] |
next |
Next contour at the same nesting level, or -1 |
[1] |
prev |
Previous contour at the same nesting level, or -1 |
[2] |
first_child |
First nested contour inside this one, or -1 |
[3] |
parent |
Enclosing contour index, or -1 for top-level |
ListandExternalforce all four fields to-1.
CComplimits parent depth to 1 (hole -> outer).
Treehas no depth limit.
API
One-shot (fresh buffers each call)
use kornia::imgproc::contours::{find_contours, RetrievalMode, ContourApproximationMode};
let result = find_contours(
&image,
RetrievalMode::Tree,
ContourApproximationMode::Simple,
)?;
for (i, contour) in result.contours.iter().enumerate() {
let [next, prev, child, parent] = result.hierarchy[i];
println!("contour {i}: {} pts parent={parent}", contour.len());
}FindContoursExecutor -- reuse buffers across frames
Prefer this for video or batch processing. All five internal scratch buffers
(img, arena, ranges, hierarchy, border_types) are retained between
calls. Only ContoursResult is newly allocated per frame.
use kornia::imgproc::contours::FindContoursExecutor;
let mut exec = FindContoursExecutor::new();
for frame in video_frames {
let result = exec.find_contours(
&frame,
RetrievalMode::External,
ContourApproximationMode::Simple,
)?;
// process result ...
}
Contributor
|
@sidd-27 @cjpurackal please review this pr and merge it |
sidd-27
reviewed
Mar 6, 2026
|
|
||
| /// Minimum image area in pixels above which binarisation is parallelised via Rayon | ||
| /// Below this threshold the thread-dispatch overhead outweighs the benefit | ||
| const PARALLEL_THRESHOLD: usize = 512 * 512; |
Collaborator
There was a problem hiding this comment.
do you have any benchmark numbers for this choice?
Contributor
Author
There was a problem hiding this comment.
Yes , these are the results
I'll change the threshold to 1080p
Collaborator
Review SummaryExcellent implementation of Suzuki & Abe contour finding! 🚀 ✅ Strengths:
|
Contributor
Author
Tysm, I have pushed the recommended fixes also added a test to check them for assurance |
Collaborator
|
could you look into the failing test? dosent seem related to the pr but just in case |
Contributor
Author
I checked ,its not due to my PR |
sidd-27
approved these changes
Mar 9, 2026
Collaborator
sidd-27
left a comment
sidd-27
left a comment
There was a problem hiding this comment.
i think adding an example would help, lgtm otherwise
Contributor
Author
should I add it in this PR or raise a separate PR for that? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Description
Fixes/Relates to: #169
Important:
🛠️ Changes Made
kornia-imgproc): Full implementation of the Suzuki & Abe (1985) border-following algorithm withfind_contoursand a reusableFindContoursExecutor.u64word reads to skip 4 zero pixels at a time, reducing per-pixel overhead in sparse/background regions.External,List,CComp, andTreeretrieval modes with correct parent-child nesting.SimpleandNoneapproximation modes also supported.🧪 How Was This Tested?
test_simple_square_no_approx,test_simple_square_simple_approx,test_hollow_square_external_vs_list,test_isolated_pixel,test_u_shape,test_no_empty_contour_simple_approx,test_many_contours_no_overflow,test_executor_reuse_identical🕵️ AI Usage Disclosure
Check one of the following:
🚦 Checklist
💭 Additional Context
Add any other context or screenshots about the pull request here.