contrek 1.3.7 → 1.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60aa8f5e3cfb43291e3dcce9921d77e84ce289bffd974dca7a4b2ed4c07124c0
-  data.tar.gz: 98ccefa7a9de3fa2ea0922d09c18fa45470ccb6ad0072c0b85d6203f025a7f11
+  metadata.gz: 68bd09217262e7b3495d05110af5a6b9c0c97bd493be54138706e3ec298847a7
+  data.tar.gz: a5dbd685e38170bc830fbbbf1e17c1725eaca367c53c229e6d233564a12337a6
 SHA512:
-  metadata.gz: 57731f61f8afc63f459b2fd349cd34e151406943c51628f80d0ac06dd29c360323adead860da8e2f9b9fb4579b6f29987c5a681175db7315d999d78039f4811f
-  data.tar.gz: 8420ba829bd714492b95249c567bdc1be27c8559bd11fbcdaf48ee9d975dc719891db23fd5d2f54d832e4f79f3dc335b1da557a53382f713d3c478094004f3d6
+  metadata.gz: d6179fce1a4e54c1fbcc14a25939ff769d74f9804ea6bc09f84fac511f0b3f7be435817e7467f2a2556d215ddc4aec36edd0e4ea2b4791ba01d09e8f9d748c3b
+  data.tar.gz: e0694addda28d20ca8d57108555a902b18ad0fb1765662ebad035c7637b47ae1d55fe6e87715e05d21a8793cfbb7a9a86156ef13f0333e9c2fc316eef6f379b5

data/CHANGELOG.md

@@ -144,3 +144,6 @@ All notable changes to this project will be documented in this file.
 - Added polygon compression to the progressive streaming pipeline (StreamingMerger).
 - Added strict validation in progressive streaming. Results passed to add_tile() are now validated to ensure they contain compatible settings (such as versus conventions and compression options).
 - Added unsafe_mode flag to streaming mergers. This allows bypassing compatibility checks when using custom or arbitrary input data.
+
+## [1.3.8] - 2026-08-08
+- Fixed issue found on treemap determination.

data/README.md

@@ -1,31 +1,60 @@
 # Contrek
-**Contrek** is a standalone <u>[C++17 topology-preserving streaming polygonization engine](#-c-standalone-library-usage)</u> for raster-to-vector conversion. It extracts polygonal contours from PNG images and raw memory streams using programmable pixel matchers, representing shapes as connected graphs of shared vertices to guarantee topological consistency. Its streaming architecture supports gigapixel-scale datasets, multithreaded execution, and incremental vector serialization to multiple formats such as SVG while keeping memory consumption bounded. A fully featured Ruby wrapper is also available, exposing the complete C++ API through an idiomatic Ruby interface.
 
-## About Contrek library
+**Contrek** is a standalone **C++17 contour tracing and polygonization library** for raster images.
 
-Contrek (**con**tour **trek**king) simply scans your png/raw bitmap and returns shape contour as close polygonal lines, both for the external and internal sides. It can compute the nesting level of the polygons found with a tree structure. It supports various levels and modes of compression and approximation of the found coordinates. It is capable of multithreaded processing, splitting the image into vertical strips and recombining the coordinates in pairs.
+It was originally developed to solve a practical problem: extracting polygons from very large raster images without loading the entire image into memory. Over time the implementation evolved into a reusable library that can process PNG images as well as raw memory buffers, while preserving polygon topology during the entire tracing process.
 
-In the following image all the non-white pixels have been examined and the result is the red polygon for the outer contour and the green one for the inner one
+The engine is based on programmable pixel matchers, allowing the caller to decide which pixels belong to the regions being traced. Polygon coordinates can be streamed as they are produced, making the library suitable for datasets that would otherwise require a large amount of RAM.
+
+Although the tracing engine is written in C++, Contrek is also distributed as a Ruby gem exposing almost the complete native API through an idiomatic Ruby interface.
+
+## About Contrek
+
+**Contrek** (**CON**tour **TREK**king) at its simplest, the library scans a bitmap and returns the contours of all regions matching a user-defined criterion. Each region is represented by one outer polygon and, when necessary, one or more inner polygons describing holes.
+
+Besides extracting contours, Contrek can also determine the nesting relationship between polygons and build a tree describing which polygons contain others. This is useful when reconstructing the topology of complex shapes.
+
+Several coordinate-compression algorithms are available to reduce polygon size after tracing. The library can also split the work across multiple threads by processing independent vertical stripes and merging the results afterwards into a single topologically consistent representation.
+
+The image below shows a simple example. Every non-white pixel is considered part of the traced region. The resulting outer contour is shown in red, while inner contours are shown in green.
 
 ![alt text](contrek.png "Contour tracing")
 
-## 🚀 Why Contrek?
 
-Contrek is a high-performance vectorization engine designed for massive datasets where memory efficiency and multi-core utilization are critical. Unlike traditional sequential contour tracers, Contrek is built on a **Stripe-Merging Architecture** that allows it to process images in independent segments and reconstruct the resulting polygons with perfect topological integrity.
+# Why Contrek?
+
+Most contour tracing libraries process an image sequentially. That approach is perfectly adequate for many workloads, but it becomes less practical once images become very large or when memory usage starts to matter.
+
+Contrek follows a different strategy.
+
+Instead of processing the whole image at once, it can split it into independent vertical stripes. Each stripe is traced separately and the resulting polygons are merged afterwards. Most of the implementation complexity lies in this merge phase, whose purpose is to reconstruct polygons crossing stripe boundaries without breaking their topology.
+
+The same design makes it possible to use the library in two different ways:
+
+- **Parallel processing**, where several stripes are traced simultaneously on different CPU cores.
+- **Streaming processing**, where only a small portion of the image is kept in memory at any given time.
+
+The tracing algorithm itself is identical in both cases; only the execution strategy changes.
+
+## Parallel execution
 
-### 1. Parallel Processing Power
-Contrek is designed to saturate all available CPU cores. By partitioning a single image into stripes, it can assign each segment to a different thread.
-* **The Result:** On multi-core systems, Contrek achieves unmatched extraction speeds by parallelizing the workload.
-* **Scalability:** Performance scales directly with your hardware, making it the ideal choice for high-throughput processing servers.
+When multiple CPU cores are available, independent stripes can be processed concurrently. The actual speedup depends on the image content and on how much work is required during the merge stage, but large datasets generally benefit from additional cores.
 
-### 2. Streamed Memory Management
-Standard vectorization requires loading entire high-resolution images into RAM, which often leads to memory saturation.
-* **The Solution:** Contrek enables **streamed processing** (see the C++ example in the repo). You can define a specific stripe height (buffer) and process the image incrementally, consuming only the memory allocated for that buffer.
-* **The Benefit:** Vectorize massive, gigapixel-scale images or raw datasets directly from memory buffers. This allows for high-performance processing even on systems with limited memory that would otherwise fail.
+This approach allows Contrek to make effective use of modern multicore processors without changing the resulting geometry.
 
-### 3. Intelligent "Stitching" Technology
-The core strength of Contrek is its **Topologically Consistent Merging** algorithm, which maintains a deep understanding of polygon connectivity across stripe boundaries.
-* Whether you are optimizing for **speed** (parallel cores) or **memory** (sequential streaming), the output is always a seamless, continuous set of vector data, free from gaps or duplicates at the seams.
+## Streaming large datasets
+
+Loading an entire gigapixel image into memory is often unnecessary.
+
+Contrek can instead process the image incrementally by reading one stripe at a time. Only the current working buffer needs to be allocated, making memory consumption predictable regardless of the final image height.
+
+This execution mode is particularly useful when processing images that are too large to fit comfortably into RAM.
+
+## Merging polygons
+
+Whenever a polygon crosses the boundary between two adjacent stripes, the library reconstructs it during the merge phase.
+
+This reconstruction preserves polygon connectivity across stripe boundaries, so the final output is equivalent to tracing the entire image in a single pass.
 
 <table>
   <tr>
@@ -49,47 +78,67 @@ The core strength of Contrek is its **Topologically Consistent Merging** algorit
   </tr>
 </table>
 
-## 📊 Benchmarking & Performance
-The **Stripe-Merging** algorithm has been validated through a dedicated testing suite comparing **Contrek** against **OpenCV** (industry-standard contour extraction).
+## Benchmarking
+
+Contrek has been benchmarked mainly against OpenCV, which is probably the most widely used library for contour extraction.
 
-### Key Metrics:
-* **Execution Latency:** Single-threaded OpenCV vs. Contrek's parallel thread management.
-* **Memory Footprint:** RAM consumption during ultra-high-resolution processing.
-* **Extraction Fidelity:** Verifying polygon precision across both engines.
+The goal was not simply to compare execution times, but also to verify that the reconstructed polygons remain topologically correct after stripe merging, even when processing very large images.
+
+The benchmark suite measures three aspects:
+
+- execution time;
+- memory usage;
+- consistency of the generated polygons.
+
+The benchmark source code and the datasets used for testing are available here:
 
-The complete testing suite, source code, and raw benchmarks are available here:
 👉 **[test_contrek](https://github.com/runout77/test_contrek)**
 
+
 ## Prerequisites
 
-For optimal performance and efficient memory management with large images (20k+), it is highly recommended to install **tcmalloc**.
+For small and medium-sized images no special configuration is required.
+
+If you expect to process very large images (roughly 20k pixels or more), installing **tcmalloc** is recommended. It generally provides more stable memory behaviour than the default allocator during long-running processing.
+
+### Ubuntu / Debian
 
-**Ubuntu / Debian:**
 ```bash
 sudo apt-get install libgoogle-perftools-dev
 ```
-> For advanced performance tuning (zlib-ng, tcmalloc, thread configuration) see [PERFORMANCE.md](PERFORMANCE.md).
 
-> ⚠️ **Platform support:** Contrek native extensions are supported on **Linux** and **macOS** only. 
-> Windows is not supported due to the use of POSIX threading primitives and platform-specific 
-> memory management. On Windows, consider using WSL2 (Windows Subsystem for Linux).
+For additional tuning options (zlib-ng, thread configuration, memory allocator and other performance-related settings), see **[PERFORMANCE.md](PERFORMANCE.md)**.
 
-## Install
+> **Platform support**
+>
+> Native extensions are currently supported on **Linux** and **macOS**.
+>
+> Windows is not supported because the implementation relies on POSIX threading primitives and platform-specific memory management. Running under **WSL2** is currently the recommended approach for Windows users.
 
-Add this line to your application's Gemfile:
+
+# Installation
+
+Add the gem to your application's Gemfile:
 
 ```ruby
-gem 'contrek'
+gem "contrek"
 ```
 
-And then execute:
+and install it normally:
+
+```bash
+bundle install
+```
+
+During installation the native C++ extension is compiled automatically.
+
+Once installed, the C++ implementation is used by default. A pure Ruby implementation is also included and can be selected explicitly whenever native extensions are not desired.
 
-    bundle install
+# Usage
 
-This will install the gem and compile the native extensions.
+The simplest way to use Contrek is through the `Contrek.contour!` helper.
 
-## Usage
-In this example we are asking to examine any pixel that does not have the red color.
+In the example below, every pixel except pure red is considered part of the region to be traced.
 
 ```ruby
 result = Contrek.contour!(
@@ -101,65 +150,200 @@ result = Contrek.contour!(
   }
 )
 ```
-The resulting metadata information contains the execution times (microseconds), the count of polygons found and the nesting tree map. You can access polygons coordinates too (see later).
 
-```ruby
-{:benchmarks=>{"build_tangs_sequence"=>0.129, "compress"=>0.037, "plot"=>0.198, "scan"=>0.114, "total"=>0.478}, :groups=>2, :named_sequence=>"", :treemap=>[]}
+The returned object contains both the extracted polygons and some metadata describing the execution.
+
+Metadata includes timing information (expressed in milliseconds), the number of detected polygon groups and, if requested, the nesting tree.
 
+```ruby
+{
+  :benchmarks=>{
+    "build_tangs_sequence"=>0.129,
+    "compress"=>0.037,
+    "plot"=>0.198,
+    "scan"=>0.114,
+    "total"=>0.478
+  },
+  :groups=>2,
+  :named_sequence=>"",
+  :treemap=>[]
+}
 ```
 
-By default the C++ version is used. If you want run pure but slower ruby implementation
+The actual polygon coordinates are discussed later in the **Result** section.
+
+
+## Pure Ruby implementation
+
+By default Contrek uses the native C++ implementation.
+
+A pure Ruby version is included mainly for portability, debugging and environments where compiling native extensions is not possible.
+
+It exposes the same public API, although execution is considerably slower.
+
 ```ruby
 result = Contrek.contour!(
   png_file_path: "labyrinth3.png",
   options: {
-    native: false, # force ruby pure
+    native: false,
     class: "value_not_matcher",
     color: {r: 241, g: 156, b: 156, a: 255}
   }
+)
+```
 
+## Performance Native vs Pure
+
+One of the largest examples included in the test suite processes the image `sample_1200x800.png`.
+
+Pure Ruby:
+
+```ruby
+{
+  scan: 775.435,
+  build_tangs_sequence: 38.916,
+  plot: 101.876,
+  compress: 0.002,
+  total: 916.229
+}
 ```
 
-You can bypass the helper and access low level (here the CPP classes)
+Native C++:
+
+```ruby
+{
+  scan: 5.077,
+  build_tangs_sequence: 0.697,
+  plot: 2.004,
+  compress: 0.000,
+  total: 7.781
+}
+```
+
+On the reference machine used for development (AMD Ryzen 7 3700X, Ubuntu, 64 GB RAM), the native implementation is roughly 130× faster for this workload.
+
+As always with benchmarks, these numbers should be considered indicative rather than absolute. Actual performance depends on image content, compression settings and hardware.
+
+
+## Working with the C++ API
+
+The helper method is convenient for most applications, but it is also possible to access the native classes directly.
+
+This gives more control over bitmap creation, matcher selection and polygon finder configuration.
 
 ```ruby
 png_bitmap = CPPPngBitMap.new("labyrinth3.png")
-rgb_matcher = CPPRGBNotMatcher.new(png_bitmap.rgb_value_at(0, 0))
-polygonfinder = CPPPolygonFinder.new(png_bitmap,
+
+rgb_matcher = CPPRGBNotMatcher.new(
+  png_bitmap.rgb_value_at(0, 0)
+)
+
+polygonfinder = CPPPolygonFinder.new(
+  png_bitmap,
   rgb_matcher,
   nil,
-  {versus: :a, compress: {visvalingam: true, visvalingam_tolerance: 1.5}})
+  {
+    versus: :a,
+    compress: {
+      visvalingam: true,
+      visvalingam_tolerance: 1.5
+    }
+  }
+)
+
 result = polygonfinder.process_info
-# draws the polygons found
-Contrek::Bitmaps::Painting.direct_draw_polygons(result.points, png_image)
-png_image.save('result.png') # => inspect the image to feedback the result
+
+Contrek::Bitmaps::Painting.direct_draw_polygons(
+  result.points,
+  png_image
+)
+
+png_image.save("result.png")
 ```
 
-You can also read base64 png images
+Using the low-level API is useful when building custom processing pipelines or when more control over the tracing process is required.
+
+
+## Reading PNG images from Base64
+
+When image data is already available as a Base64 string there is no need to write it to disk first.
+
 ```ruby
-png_bitmap = CPPRemotePngBitMap.new("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==")
+png_bitmap = CPPRemotePngBitMap.new(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="
+)
 ```
 
-You can process from a raw stream
+
+## Processing raw memory buffers
+
+Contrek is not limited to PNG files.
+
+Images can also be created directly in memory, making the library suitable for integration with image-processing pipelines that never touch the filesystem.
+
+The following example creates a small bitmap, draws a rectangle and extracts its contour.
+
 ```ruby
-  raw_bitmap = CPPRawBitMap.new
-  # set 20 as width, 30 as height, 4 as bytes per pixel and clears the content (true)
-  raw_bitmap.define(20,30,4,true)
-  # draws a polygon
-  4.upto(5) do |y|
-    5.upto(8) do |x|
-      raw_bitmap.draw_pixel(x, y, 1, 0, 0, 0);
-    end
+raw_bitmap = CPPRawBitMap.new
+
+raw_bitmap.define(20,30,4,true)
+
+4.upto(5) do |y|
+  5.upto(8) do |x|
+    raw_bitmap.draw_pixel(x, y, 1, 0, 0, 0)
   end
-  not_matcher = CPPRGBNotMatcher.new(raw_bitmap.rgb_value_at(0, 0))
-  result = CPPPolygonFinder.new(raw_bitmap, not_matcher, nil,{compress: {uniq: true, linear: true}}).process_info
-  puts result.points.inspect
-  =>
-  [{:outer=>[{x: 5, y: 4}, {x: 5, y: 6}, {x: 9, y: 6}, {x: 9, y: 4}], :inner=>[]}]
+end
+
+not_matcher = CPPRGBNotMatcher.new(
+  raw_bitmap.rgb_value_at(0,0)
+)
+
+result = CPPPolygonFinder.new(
+  raw_bitmap,
+  not_matcher,
+  nil,
+  {
+    compress:{
+      uniq:true,
+      linear:true
+    }
+  }
+).process_info
+
+puts result.points.inspect
 ```
 
-Multithreaded contour processing is supported by both the native C++ and pure Ruby implementations. When using the C++ engine (default), multithreading works as expected and fully utilizes all available cores.
-When running the pure Ruby implementation, however, the Global Interpreter Lock (GIL) in Ruby MRI (the standard Ruby interpreter, up to at least version 3.x) prevents true parallel execution — threads are serialized even on multicore systems. Switching to JRuby or TruffleRuby would bypass this limitation, though these runtimes have not been tested with Contrek.
+which produces
+
+```ruby
+[
+  {
+    :outer=>[
+      {x:5,y:4},
+      {x:5,y:6},
+      {x:9,y:6},
+      {x:9,y:4}
+    ],
+    :inner=>[]
+  }
+]
+```
+
+This interface is particularly useful when image data comes from another application, a network stream or an in-memory processing stage rather than from a PNG file.
+
+# Multithreading
+
+Both the native C++ implementation and the pure Ruby implementation expose the same multithreading interface.
+
+There is, however, an important difference between the two.
+
+The native implementation performs contour extraction in parallel and can take advantage of all available CPU cores.
+
+The pure Ruby implementation, on the other hand, is limited by MRI's Global Interpreter Lock (GIL). Although multiple threads can be created, they do not execute Ruby code simultaneously, so CPU-bound workloads remain effectively sequential.
+
+Alternative runtimes such as JRuby or TruffleRuby do not have this limitation, although they have not been tested with Contrek.
+
+A simple multithreaded example:
 
 ```ruby
 result = Contrek.contour!(
@@ -169,21 +353,60 @@ result = Contrek.contour!(
     native: false,
     class: "value_not_matcher",
     color: {r: 255, g: 255, b: 255, a: 255},
-    finder: {number_of_tiles: 2, compress: {uniq: true, linear: true}}
+    finder: {
+      number_of_tiles: 2,
+      compress: {
+        uniq: true,
+        linear: true
+      }
+    }
   }
 )
 ```
-The example uses 2 threads, and the image has been divided into 2 vertical bands. It is also possible to rely on the system to determine the maximum number of threads supported by your CPU (cores) by passing the appropriate parameter.
+
+In this example the image is divided into two vertical stripes and each stripe is assigned to a worker thread.
+
+Instead of specifying the number of threads explicitly, you can also let Contrek choose a suitable value automatically.
 
 ```ruby
-  number_of_threads: nil
+number_of_threads: nil
 ```
 
-Regarding multithreading:
+The native implementation uses the number of available CPU cores reported by the operating system.
 
-- The algorithm splits the contour-detection workflow into multiple phases that can be executed in parallel. The initial contour extraction on each band and the subsequent merging of coordinates between adjacent bands—performed pairwise, recursively, and in a non-deterministic order—results in a final output that is not idempotent. Idempotence is guaranteed only when the exact same merging sequence is repeated.
+## A note about determinism
 
-By not declaring native option CPP Multithreading optimized code is used. In the above example a [105 MP image](spec/files/images/sample_10240x10240.png) is examined by 4 threads working on 4 tiles (total compute time about 0.328 secs with image load).
+The tracing stage itself is deterministic.
+
+The merge stage is not.
+
+Each stripe is processed independently and adjacent stripes are merged as soon as they become available. Depending on thread scheduling, the merge order may differ from one execution to another.
+
+For example, given three stripes:
+
+```
+B1   B2   B3
+```
+
+one execution may merge them like this:
+
+```
+(B1 + B2) + B3
+```
+
+while another execution may produce:
+
+```
+B1 + (B2 + B3)
+```
+
+Both executions generate equivalent polygons, but the order of intermediate merge operations is differentso the final coordinate sequence is not guaranteed to be byte-for-byte identical across executions.
+
+## Native execution
+
+When the `native` option is omitted, Contrek automatically uses the C++ implementation.
+
+For example, the following configuration processes a 105 MP image using four worker threads and four processing tiles.
 
 ```ruby
 result = Contrek.contour!(
@@ -192,135 +415,205 @@ result = Contrek.contour!(
     number_of_threads: 4,
     class: "value_not_matcher",
     color: {r: 255, g: 255, b: 255, a: 255},
-    finder: {number_of_tiles: 4, compress: {uniq: true}}
+    finder: {
+      number_of_tiles: 4,
+      compress: {
+        uniq: true
+      }
+    }
   }
 )
-puts result.metadata[:benchmarks].inspect
 
-{ compress: 5.3933,
+puts result.metadata[:benchmarks]
+```
+
+Example timings:
+
+```ruby
+{
+  compress: 5.3933,
   init: 322.749,
   inner: 4.795,
   outer: 81.546,
   total: 328.142
 }
-
 ```
 
-## Tracking & Topology Schema
+The reported timings include tracing, polygon reconstruction and coordinate compression.
+
+# Tracking model
 
-Contrek utilizes a **Dual-Grid / Cell-Based Topology** instead of a classic point-pixel model. Each pixel is treated as a solid 2D cell defined by **4 distinct vertices** (nodes). 
+Contrek works on a cell-based representation. Each pixel is treated as a square with four explicit vertices. During tracing, polygons are built by walking along the edges separating matching and non-matching cells.
 
+This representation makes it easier to preserve topology and simplifies the reconstruction of polygons when different image stripes are merged together.
 
-### Pixel-Cell Geometry
+### Pixel geometry
 
 ```text
     (x, y)          Top Edge         (x+1, y)
        O--------------------------------O
        |                                |
        |                                |
-  Left |             PIXEL              | Right
-  Edge |            (x, y)              | Edge
+ Left  |             PIXEL              | Right
+ Edge  |            (x, y)              | Edge
        |                                |
        |                                |
        O--------------------------------O
-   (x, y+1)        Bottom Edge       (x+1, y+1)
-
+   (x, y+1)       Bottom Edge      (x+1, y+1)
 ```
 
-### Connectivity Modes
 
-Contrek supports different pixel connectivity rules to define how polygons are traced and merged. This is controlled by the `:connectivity` option.
+## Connectivity
+
+Neighbouring pixels can be connected using either **4-connectivity** or **8-connectivity**.
 
-| Value | Name | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `4` | **Orthogonal** | Default | Only pixels sharing an edge (N, S, E, W) are connected. |
-| `8` | **Omnidirectional** | Extended | Includes diagonal neighbors (sharing a corner). |
+With **4-connectivity**, only pixels sharing an edge belong to the same region.
 
+With **8-connectivity**, diagonal neighbours are also considered connected.
 
-To enable **Omnidirectional** (8-way) connectivity, pass `connectivity: 8` in the options hash:
+| Value | Description |
+|------:|-------------|
+| `4` | Orthogonal connectivity (default) |
+| `8` | Includes diagonal neighbours |
+
+To enable 8-connectivity:
 
 ```ruby
 result = Contrek.contour!(
-  png_file_path: "./spec/files/images/sample_10240x10240.png",
+  png_file_path: "...",
   options: {
-    number_of_threads: 4,
-    class: "value_not_matcher",
-    color: {r: 255, g: 255, b: 255, a: 255},
     finder: {
-      number_of_tiles: 4,
-      connectivity: 8, # 8 for Omnidirectional, 4 for Orthogonal
-      compress: {uniq: true}}
+      connectivity: 8
+    }
   }
 )
 ```
 
-## Result
+The choice mainly affects how diagonally touching regions are interpreted.
+
+# Results
+
+The tracing result contains two kinds of information:
 
-The result structure contains polygon coordinates and a set of metadata. Polygon coordinates can be accessed via:
+- the extracted polygons;
+- metadata describing how they were produced.
+
+Polygon coordinates are available through
 
 ```ruby
 result.polygons
-
-[{:outer=>[11, 2, 11, 5, 6, 5, 6, 2],
-  :inner=>[[10, 3, 7, 3, 7, 4, 10, 4]]}]
 ```
 
-For native classes (C/C++), coordinates are represented as an interleaved NumPy array (`ndarray`) in the form:
+The native implementation stores coordinates as an interleaved array
 
-```
+```text
 [x0, y0, x1, y1, ...]
 ```
 
-A ruby side helper method could converts this data structure into point-based representations:
+This representation is compact and avoids allocating thousands of small point objects.
+
+If you prefer a more Ruby-friendly representation you can use
 
 ```ruby
 result.points
+```
+
+which converts the same data into hashes containing `x` and `y`.
 
-[{:outer=>[{:x=>11, :y=>2}, {:x=>11, :y=>5}, {:x=>6, :y=>5}, {:x=>6, :y=>2}],
-  :inner=>[[{:x=>10, :y=>3}, {:x=>7, :y=>3}, {:x=>7, :y=>4}, {:x=>10, :y=>4}]]}]
+```ruby
+[
+  {
+    outer: [
+      {x:11,y:2},
+      {x:11,y:5},
+      {x:6,y:5},
+      {x:6,y:2}
+    ],
+    inner: [
+      [
+        {x:10,y:3},
+        {x:7,y:3},
+        {x:7,y:4},
+        {x:10,y:4}
+      ]
+    ]
+  }
+]
 ```
 
-- `outer` represents a single polygonal sequence  
-- `inner` is represented as an array of polygonal sequences (holes)
+The conversion is performed only on the Ruby side. Internally, the native implementation continues to use the compact coordinate array.
+
+For pure Ruby (`native: false`) both methods return the same point-based representation.
 
-For pure Ruby implementations (`{ native: false }`), coordinates are always expressed as points.  
-In this case, both `polygons` and `points` return the same data, represented as hashes with `x` and `y` keys.
 
-For each returned polygon, it is possible to get its bounding box. You just need to request it as an option (`bounds`), for example:
+## Bounding boxes
+
+If bounding boxes are required they can be generated during tracing instead of computing them afterwards.
+
+Enable them with
+
 ```ruby
-{named_sequences: true, bounds: true, compress: {uniq: true, linear: true}}
+{
+  bounds: true
+}
 ```
-Each entry will contain the precalculated bounds key:
+
+Each polygon will then include an additional `bounds` entry.
+
 ```ruby
-[{:bounds=>{:min_x=>3, :max_x=>11, :min_y=>1, :max_y=>3},
-  :outer=>[{:x=>3, :y=>1}, {:x=>3, :y=>3}, {:x=>11, :y=>3}, {:x=>11, :y=>1}],
-  :inner=>[]}]
+{
+  bounds:{
+    min_x:3,
+    max_x:11,
+    min_y:1,
+    max_y:3
+  },
+  outer:[...],
+  inner:[...]
+}
 ```
 
+Since bounds are computed while polygons are being built, requesting them has almost no additional cost.
+
 
-## Metadata
+# Metadata
 
-Metadata associated with the result can be accessed via:
+Execution metadata is available through
 
 ```ruby
 result.metadata
+```
+
+Typical information includes
 
-{:benchmarks=>{"build_tangs_sequence"=>0.00577,
-               "compress"=>0.01239,
-               "plot"=>0.01919,
-               "scan"=>0.01473,
-               "total"=>0.05208},
- :groups=>1,
- :named_sequence=>"AFEDCBA",
- :treemap=>[],
- :options=>{versus: :a, compress: {visvalingam: true, visvalingam_tolerance: 1.5}}
+- execution times;
+- tracing options;
+- number of polygon groups;
+- nesting information.
+
+```ruby
+{
+  benchmarks:{...},
+  groups:1,
+  treemap:[],
+  options:{...}
 }
 ```
-The options are the original options passed by user.
 
-## Treemap
+The content of `options` is simply the configuration originally passed to the tracing engine.
+
 
-The treemap is a data structure that represents the containment hierarchy of polygons. For each polygon, it defines the parent polygon in which it is contained and the index of the parent inner sequence in which is placed. This structure allows reconstruction of the inclusion tree and determination of nesting relationships between geometries. The treemap indexes are referred to positions inside the array of polygons returned by result.points. Consider the above image traced clockwise (o). 
+# Treemap
+
+Besides returning polygon coordinates, Contrek can also describe how polygons are nested inside one another.
+
+This information is stored in the **treemap**, which records the parent-child relationship between every detected polygon.
+
+Rather than rebuilding the hierarchy afterwards through geometric containment tests, the information is collected during tracing, making it immediately available once processing completes.
+
+Each entry in the treemap refers to the corresponding polygon returned by `result.polygons`.
+
+For example consider the above image traced clockwise (o). 
 
 ```ruby
  "AAAAAAAAAAAAAAAAAAAAAA" \
@@ -339,19 +632,18 @@ The treemap is a data structure that represents the containment hierarchy of pol
 ```ruby
 result.metadata[:treemap]
 
-[[-1, -1],  # A
- [0, 0],    # B
- [1, 1],    # C
- [1, 0]]    # D
+[
+  [-1, -1],  # A
+  [0, 0],    # B
+  [1, 1],    # C
+  [1, 0]     # D
+]
 ```
 
-There are four polygons (`A`, `B`, `C`, and `D`).  
-The order matches the one provided in `result.polygons`.
-
-Each entry has the structure:
+Each element has the form
 
-```
-[parent_index, index_of_parent_inner_sequence]
+```text
+[parent_polygon_index, parent_inner_sequence_index]
 ```
 
 - Polygon **A** (index `0`) has no parent and is represented as `[-1, -1]`
@@ -388,11 +680,14 @@ result.metadata[:treemap]
 C, D and E will get the same pair (**[1, 0]**) because are all placed inside the first (0) inner sequence of B.
 
 
-## Multithreaded approach
+# How stripe merging works
 
-The multithreaded contour-tracing implementation operates as follows:
+The contour tracing itself is relatively straightforward.
+
+The more challenging part is reconstructing polygons that cross the boundary between two independently processed image stripes.
+
+This reconstruction step is what allows Contrek to support both streaming and parallel execution without changing the resulting geometry.
 
-The input image is divided into multiple vertical bands—at least two—where each band shares a one-pixel-wide vertical strip with its adjacent bands.
 For example, if the image is 20 pixels wide and split into two bands, the first band may span from x=0 to x=9 (10 pixels), and the second from x=9 to x=19 (11 pixels).
 The vertical column at x=9 is therefore the shared region.
 
@@ -401,62 +696,74 @@ The vertical column at x=9 is therefore the shared region.
 ---------*----------
 ```
 
-Each band is processed independently as if it were a standalone image, with its contour-tracing assigned to a dedicated thread.
-Whenever two adjacent bands have completed processing, they are assigned to an available thread that performs the merge of their coordinates.
+Each stripe is processed independently, exactly as if it were a separate image.
 
-For example, with three bands
-B1 – B2 – B3
-the merging sequence might be:
+The shared column guarantees that contours intersecting the boundary are visible from both sides.
 
-B1 + B2 → (B1+B2) + B3
-or
+Once tracing has completed, adjacent stripes are merged.
 
-B2 + B3 → B1 + (B2+B3)
+The merge algorithm identifies polygons that continue across the shared boundary, splits them into matching segments and reconnects them into a single continuous contour.
 
-The order is therefore nondeterministic, constrained only by the possible combinations derived from the initial number of bands.
+The same operation is then repeated recursively until only one stripe remains.
 
-The merging algorithm operates by splitting polygons that intersect the shared band into sequential subsets of coordinates—called parts—distinguishing between segments inside the shared region and those outside it.
-The first stage merges the outer boundary; the second stage merges the disconnected inner parts, which are inserted where needed into the outer sequences produced in the first stage.
+In other words, Contrek never attempts to trace the whole image at once.
 
-This process is applied recursively, merging bands until a single final band remains, upon which the coordinate-compression algorithms are executed.
+Instead, it repeatedly combines smaller topologically consistent pieces into a larger one.
+
+This strategy makes it possible to process images whose full size would otherwise exceed the available memory.
+
+
+## Merge order
+
+The merge order is intentionally left to the thread scheduler.
+
+For three stripes, both of the following execution orders are valid:
 
-## Performances native vs pure
-One of the most complex test you can find under the spec folder is named "scans poly 1200x800", scans this [image](spec/files/images/sample_1200x800.png) computing coordinates to draw polygons drawn in this [result](spec/files/stored_samples/sample_1200x800.png).
-On pure ruby implementation kept time
-```ruby
-{ :scan=>775.435,
-  :build_tangs_sequence=>38.916,
-  :plot=>101.876,
-  :compress=>0.002,
-  :total=>916.229
-}
 ```
-This the one for the native C++
-```ruby
-{ scan: 5.077878999999999,
-  build_tangs_sequence: 0.697222999999999,
-  plot: 2.00479,
-  compress: 0.00071,
-  total: 7.780602
-}
+(B1 + B2) + B3
+```
+
+or
+
 ```
+B1 + (B2 + B3)
+```
+
+Although the intermediate merge sequence changes, the reconstructed polygons remain geometrically equivalent.
+
+The exact ordering of coordinates may differ because polygon simplification is applied after merging.
+
+
+## Polygon reconstruction
+
+Internally, polygons crossing a stripe boundary are temporarily divided into smaller pieces.
 
-About 130x faster. Times are in microseconds; system: AMD Ryzen 7 3700X 8-Core Processor (BogoMIPS: 7199,99) on Ubuntu distro.
+The merge stage reconnects these pieces by matching their endpoints inside the shared region.
 
-**Note:** Benchmarks were measured inside a VMware virtual machine.
+Outer boundaries are reconstructed first.
 
-## 🛠 C++ Standalone Library Usage
+Inner boundaries (holes) are processed afterwards and inserted back into their corresponding outer polygon.
 
-The core of **Contrek** is a high-performance `C++17` library. It is designed to be **standalone**, meaning it has zero dependencies on Ruby and can be integrated into any `C++` project.
+This separation considerably simplifies the reconstruction logic while preserving the topology of the original image.
 
+Once every stripe has been merged into a single dataset, the optional coordinate-compression algorithms are applied.
 
-### Prerequisites
-* **CMake** (3.10+)
-* **ZLIB** (Required for PNG processing)
-* **C++17 Compiler**
+At this point the resulting polygons are identical to those that would have been obtained by processing the image in a single pass, while requiring substantially less memory.
 
-### 1. Build & Run Examples
-If you want to test the performances or see the library in action:
+
+# Standalone C++ library
+
+Although Contrek is distributed as a Ruby gem, the tracing engine itself is a standalone C++17 library.
+
+The C++ code has no dependency on Ruby and can be integrated into other projects directly.
+
+## Requirements
+
+- CMake 3.10 or newer
+- A C++17 compiler
+- ZLIB (required for PNG support)
+
+## Building the examples
 
 ```bash
 # Navigate to the core folder
@@ -473,12 +780,12 @@ make
 ./contrek_test
 ```
 
-### 2. How to integrate it into your project
+The examples are a good starting point for understanding the native API and evaluating the library without involving Ruby.
 
-To use Contrek's engine in your own C++ application without Ruby:
 
-1. **Copy the core folder**: Take the `ext/cpp_polygon_finder/PolygonFinder` directory and place it inside your project (e.g., in a `libs/` or `third_party/` folder).
-2. **Update your CMakeLists.txt**: Add these lines to link the library:
+## Integrating the library
+
+The easiest way to embed Contrek into an existing C++ project is to copy the `PolygonFinder` directory into your source tree and add it as a CMake subdirectory.
 
 ```cmake
 # Tell CMake to include Contrek
@@ -489,9 +796,12 @@ add_executable(my_app main.cpp)
 target_link_libraries(my_app PRIVATE ContrekLib)
 ```
 
-### 3. C++ API Quick Start
+No Ruby components are required.
+
+
+## Basic example
 
-Contrek provides a high-level C++ API. Here is how you can use it in your standalone projects:
+A minimal program looks like this:
 
 ```cpp
 #include "ContrekApi.h"
@@ -515,7 +825,10 @@ int main() {
 }
 ```
 
-## License
+The API intentionally stays close to the concepts used by the Ruby wrapper, making it easy to switch between the two interfaces.
+
+
+# License
 
 Contrek uses a dual-license model:
 
@@ -524,11 +837,12 @@ Contrek uses a dual-license model:
 
 See [LICENSE.md](LICENSE.md) for full details.
 
-## Changelog
+
+# Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes.
 
-## History
+# History
 The algorithm was originally developed by me in 2018 when I was commissioned to create a Rails web application whose main objective was to census buildings from GoogleMAPS; the end user had to be able to select their home building by clicking its roof on the map which had to be identified as a clickable polygon. The solution was to configure GoogleMAPS to render buildings of a well-defined color (red), and at each refresh of the same to transform the div into an image (html2canvas) then process it server side returning the polygons to be superimposed again on the map. This required very fast polygons determination. Searching for a library for tracing the contours I was not able to find anything better except OpenCV which however seemed to me a very heavy dependency. So I decided to write my algorithm directly in the context of the ROR application. Once perfected, it was already usable but a bit slow in the higher image resolutions. So I decided to write the counterpart in C++, which came out much faster and which I then used as an extension on Ruby by means of Rice.
 
 I thought that the algorithm had excellent qualities but I never had the time to develop it further. A few months ago I decided to publish it as a gem, freely usable. The gem includes the C++ extension. There is also a [Rails 7.1 demo project](https://github.com/runout77/contrek_rails) that uses the gem and proposes the same scheme I described above. Starting from a GoogleMAPS map, the server receives the image and returns the outlines to be drawn again on the same. It is a great way to test an applicative use of this gem. Enjoy!.

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/Node.cpp

@@ -132,3 +132,12 @@ Node* Node::get_tangent_node_by_virtual_index(int virtual_index) {
     return &(this->cluster->vert_nodes[y + T_DOWN][virtual_index]);
   }
 }
+
+void Node::assign_lateral_inner_index(Node* my_prev_node, Node* end_node, int versus) {
+  bool first_is_max = ((this->y > my_prev_node->y) == (versus == Node::A));
+  if (first_is_max) {
+    this->inner_right_index = end_node->inner_index;
+  } else {
+    this->inner_left_index = end_node->inner_index;
+  }
+}

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/Node.h

@@ -113,6 +113,7 @@ class Node : public  Listable {
   int min_x, max_x;
   Node(int min_x, int max_x, int y, NodeCluster* cluster, char name);
   void precalc_tangs_sequences(NodeCluster& cluster);
+  void assign_lateral_inner_index(Node* my_prev_node, Node* end_node, int versus);
   bool processed = false;
   char name;
   int inner_left_index = -1;

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/NodeCluster.cpp

@@ -292,13 +292,6 @@ Node* NodeCluster::plot_inner_node(std::vector<Point>& sequence_coords, Node *no
     Node *next_node = current_node->my_next_inner(last_node, versus);
     plot_sequence.push_back(current_node);
 
-    bool first_is_max = ((current_node->y > last_node->y) == (versus == Node::A));
-    if (first_is_max) {
-      if (current_node->inner_right_index == -1) current_node->inner_right_index = stop_at->inner_index;
-    } else {
-      if (current_node->inner_left_index == -1) current_node->inner_left_index = stop_at->inner_index;
-    }
-
     bool plot = true;
     if (next_node->y == last_node->y) {
       Node *n;
@@ -309,6 +302,7 @@ Node* NodeCluster::plot_inner_node(std::vector<Point>& sequence_coords, Node *no
       plot = (n == next_node);
     }
     if (plot) {
+      current_node->assign_lateral_inner_index(last_node, stop_at, versus);
       Point first_point = last_node->coords_entering_to(current_node, versus_inverter[versus], Node::INNER);
       if (sequence_coords.back() != first_point) {
         sequence_coords.push_back(first_point);
@@ -338,7 +332,12 @@ Node* NodeCluster::plot_inner_node(std::vector<Point>& sequence_coords, Node *no
     } else {
       inner_new->remove(current_node);
     }
-    if (next_node == stop_at) break;
+    if (next_node == stop_at) {
+      if (plot) {
+        next_node->assign_lateral_inner_index(current_node, stop_at, versus);
+      }
+      break;
+    }
     current_node = next_node;
   }
   return current_node;

data/lib/contrek/finder/node.rb

@@ -105,6 +105,17 @@ module Contrek
         get_tangent_node_by_virtual_index(@tangs_sequence.at(last_node_index))
       end
 
+      def assign_lateral_inner_index(my_prev_node, end_node, versus)
+        is_moving_up = y > my_prev_node.y
+        is_forward = (versus == :a)
+        first_is_max = (is_moving_up == is_forward)
+        if first_is_max
+          self.inner_right_index = end_node.inner_index
+        else
+          self.inner_left_index = end_node.inner_index
+        end
+      end
+
       def coords_entering_to(enter_to, enter_mode, tracking)
         enter_to_index = if enter_to.y < y
           enter_to.abs_x_index + @up_indexer

data/lib/contrek/finder/node_cluster.rb

@@ -233,13 +233,6 @@ module Contrek
         next_node = node.my_next(last_node, versus, :inner)
         @plot_sequence << node
 
-        first_is_max = ((node.y > last_node.y) == (versus == :a))
-        if first_is_max
-          node.inner_right_index = stop_at.inner_index if node.inner_right_index == -1
-        elsif node.inner_left_index == -1
-          node.inner_left_index = stop_at.inner_index
-        end
-
         plot = true
         if next_node.y == last_node.y
           virtual_index = node.tangs_sequence.send((versus == :a) ? :first : :last)
@@ -247,6 +240,7 @@ module Contrek
         end
 
         if plot
+          node.assign_lateral_inner_index(last_node, stop_at, versus)
           first_point = last_node.coords_entering_to(node, VERSUS_INVERTER[versus], Contrek::Finder::Node::INNER)
           @sequence_coords << first_point if @sequence_coords.last != first_point
           if next_node.y == last_node.y
@@ -271,8 +265,10 @@ module Contrek
         else
           @inner_new.delete(node)
         end
-
-        return node if next_node == stop_at
+        if next_node == stop_at
+          next_node.assign_lateral_inner_index(node, stop_at, versus) if plot
+          return node
+        end
         plot_inner_node(next_node, versus, stop_at, start_node)
       end
 

data/lib/contrek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Contrek
-  VERSION = "1.3.7"
+  VERSION = "1.3.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.3.7
+  version: 1.3.8
 platform: ruby
 authors:
 - Emanuele Cesaroni
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-29 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec