Inside findContours

A paper-faithful explanation and Python implementation that’s easier to understand than the original paper

This project originated as a byproduct of improving the contour accuracy of my Thick Sprite Mesh plugin.

While working on pixel-perfect mesh generation, I needed a deeper and more reliable understanding of how contour detection actually works at the algorithm level, rather than treating it as a black-box API.

That need led me to carefully study the original Suzuki–Abe (1985) paper behind OpenCV’s findContours, and to reimplement the algorithm from scratch with a focus on clarity and correctness.

What started as internal research gradually became a standalone, well-documented explanation and reference implementation that may also be useful to other developers who want to truly understand contour tracing, not just call a function.

🧠 What this is

OpenCV’s findContours is widely used, but its internal algorithm — the border following algorithm proposed by Satoshi Suzuki and Keiichi Abe in 1985 — is rarely explained clearly.

The original paper is compact, dense, and difficult to translate directly into correct, working code.

This package is the result of fully reading, understanding, and re-implementing the algorithm from the paper, with a focus on engineering clarity rather than academic brevity.

If you’ve ever thought:

“I know findContours works — but how, exactly?”

This is for you.

📦 What you get

inside-findcontours/
 ├── images/
 ├── README.md
 ├── suzuki_abe_algorithm1.md
 ├── suzuki_abe_algorithm1.py
 ├── test_console.py
 └── test_image.py

• A clear, step-by-step explanation of the Suzuki–Abe contour tracing algorithm (suzuki_abe_algorithm1.md)
• A paper-faithful Python implementation, written to be readable and portable (suzuki_abe_algorithm1.py)
• Explicit handling of:
  • outer contours vs hole contours
  • parent–child (hierarchical) relationships
  • edge cases often skipped in blog posts
• Simple test scripts for:
  • binary images in 2D ndarray (test_console.py)
  • real image inputs (test_image.py)

This is not pseudocode. This is a working reference implementation you can run, study, and port to other languages or engines.

🎯 Who this is for

• Software engineers who want to understand how findContours really works
• Engine / game / library developers looking for a dependency-free reference
• Developers who prefer understanding algorithms, not just calling APIs

🚫 Who this is NOT for

• Absolute beginners in computer vision
• Readers looking for a quick OpenCV tutorial
• Anyone who just needs to call cv2.findContours() and move on

🕒 Why this saves you time

Instead of:

• struggling through a 1985 research paper
• guessing missing implementation details
• debugging subtle contour tracing logic

You start with:

• a clear explanation
• a complete, working reference
• a mental model that actually sticks

Many readers could save hours by starting here.