Topological Contour Graph (TCG) Extraction

This repository implements the topological contour graph (TCG) extractor. Originally developed by Yuliang Guo; documented by Hongyi Fan and Chiang-Heng Chien. Used, edited, and updated by Chiang-Heng Chien.

Prerequisite data

1. Edges detected on the image, e.g. SE / third-order edge detector. The edges are formatted in a .edg file.
2. Compute initial curve fragments from edges using dborl_compute_curve_frags to produce a .cem file. The executive file dborl_compute_curve_frags` can be generated by compiling the curve framgment code.

MATLAB usage

The main script is main_TCG.m which undergoes several steps from curve fragements to a topological contour graph:

• loads the image, .edg, and .cem
• breaks contours at corners
• fills large gaps (DP)
• breaks at T-junctions, prunes noise, merges geometrically, classifies junctions (BP)
• breaks at corners again and prunes

C++ port (CPP/)

The C++ code converts the MATLAB code in main_TCG.m (Step 3 and onward). It takes the original image, the edge file (.edg), and the contour fragement file (.cem) as inputs, and returns a new .cem file containing the new contour fragments of the topological contour graph.

Dependencies

• CMake ≥ 3.14
• C++17 compiler
• OpenCV 4 and above (core, imgproc, imgcodecs)

Build

Follow the standard build and compile process to produce the executable TCG.

cd CPP
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j

Once built is successful, provide specific .edg, .cem, and the original image file. By default both .cem and .cemv are written using stem <image_name>_tcg_cpp.

./TCG <input.edg> <input.cem> <input.image> [format] [output]

format is one of:

• cem — write only .cem
• cemv — write only .cemv
• both — write both (default)

Examples:

# both formats (default paths)
./build/TCG ./example_data/n03425413_14351.edg \
            ./example_data/n03425413_14351.cem \
            ./example_data/n03425413_14351.JPEG

# cem only
./build/TCG ... cem ./outputs/n03425413_14351_tcg_cpp.cem

# cemv only
./build/TCG ... cemv ./outputs/n03425413_14351_tcg_cpp.cemv

# both with explicit .cem path (sibling .cemv is derived)
./build/TCG ... both ./outputs/n03425413_14351_tcg_cpp.cem

A 4th argument that is not cem|cemv|both is still treated as an output path with format=both (backward compatible).

Console output reports fragment counts and timings for each stage.

Batch over a folder

run_tcg_batch.sh walks an image root recursively and runs TCG on each image. Image, .edg, and .cem roots are specified separately; class subfolders are mirrored across those roots and under the output directory. Filename patterns use * for the image stem (needed when multiple .edg / .cem variants exist per image).

./run_tcg_batch.sh \
  --image-dir /path/to/images \
  --edg-dir   /path/to/edges \
  --cem-dir   /path/to/contours \
  --edg-name '*_to.edg' \
  --cem-name '*_to_dborl.cem' \
  -e JPEG -o /path/to/out -f both

The three roots can also be passed positionally: ./run_tcg_batch.sh <image_dir> <edg_dir> <cem_dir> [options]. Other useful flags: -e / --ext (image extension, default JPEG), -b (path to the TCG binary), -n (dry-run). See all the input argements by running ./run_tcg_batch.sh --help.

Visualize C++ results in MATLAB

The output .cem is readable by load_contours / draw_contours:

addpath(genpath('util'));
img = imread('../example_data/images/cable.png');
[CEM_cpp, ~, ~] = load_contours('outputs/cable_tcg_cpp.cem');

figure; imshow(img, 'border', 'tight'); hold on;
draw_contours(CEM_cpp{2}, 0, 1);
title('C++ final contours');

Comparing Contour Fragments by Evaluation

Two sets of contour fragments (or contour maps) can be compared by using the provided evaluation code. Check the evaluation document for more information.

Notes / known differences

• "Gap fill" (step 4) uses MATLAB-faithful bwmorph(...,'skel',Inf), bwdist (exact Euclidean EDT), and imgradient/rgb2gray (Sobel + replicate borders). On the example image, stage fragment counts match MATLAB; tiny residual map differences can still come from OpenCV vs MATLAB JPEG decoding.
• Indices inside C++ are 0-based and .cem files keep the usual 0-based edge IDs. MATLAB loaders convert to 1-based when needed.