contrek 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22d05e676f5c4a0f22f02ec2e915257bf1f5da224d468cb0e2f46fc397360242
-  data.tar.gz: '0997b63d2839cc3ba613884eff2e3a565d96502e4606db0bb72d2aee228e514d'
+  metadata.gz: 1646e5fe0beaeafefcf2d60230a12ead391c9d75c771807332de7e06128198e4
+  data.tar.gz: a42d904e10ca321d8091263af986193332ac1507cdb2155e92373cf222faa864
 SHA512:
-  metadata.gz: 57bf5e08937ea8fb4cee39e383a8f760e3a36714643c583408af6d02c7fbb84515af8d3089c753319677b8d5223c7a6a07f505c4356e21cd10570abbec358210
-  data.tar.gz: 0ec4babf59251515b05857a459adfd7365b930feaf58b17ca2215ab4b534abe3ac41ae45e7643270ec8acba4c699fbcd311b12eb3ddab6789e5dd1b7275ad220
+  metadata.gz: 32495e09d3c742d1c8a1011df2c08a204a510766a0bc4fa5bf9f647fcba5c15fe691fc5ef7207f1caeb9c9caa0ff041948cc12f6e042261dd1b1d49e69c8f430
+  data.tar.gz: 28a0e9ff0cc67cfbe7f56f73ae660d68a1ca82243ac656a67cff4c9aefff506eaf0230edc7973de9d900cb1f63e4946f9eed8c39cd9a04de01861dbcf04cb6cf

data/CHANGELOG.md

@@ -63,3 +63,8 @@ All notable changes to this project will be documented in this file.
 ### Changed
 - **RawBitmap Integration (Ruby/C++):** Introduced a native buffer class for direct contour extraction, bypassing PNG encoding to significantly reduce latency and memory overhead.
 - **Tiled Polygon Merger:** Added a spatial merger for `Finder` outputs to stitch polygons from discrete sub-areas (requiring only a 1px overlap). This multi-phase workflow supports coordinate translation and eliminates monolithic buffer requirements, optimizing the peak memory footprint.
+
+## [1.1.6] - 2026-03-21
+### Changed
+- Added strict_bounds tracing mode: enables more accurate shape tracing by strictly adhering to pixel boundaries.
+- Topological Consistency Fixes: improved the Topologically Consistent Merging algorithm to support progressive polygon tracing during sequential data streaming.

data/README.md

@@ -9,6 +9,45 @@ Contrek (**con**tour **trek**king) simply scans your png/raw bitmap and returns
 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
 ![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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+<table>
+  <tr>
+    <td><img src="docs/images/stripes/whole_0.png" alt="Contour tracing stripe 0" width="50%"></td>
+    <td rowspan="4" align="center">
+      <img src="docs/images/stripes/whole.png" alt="Contour tracing stripe 0" width="50%">
+    </td>
+  </tr>
+  <tr>
+    <td><img src="docs/images/stripes/whole_256.png" alt="Contour tracing stripe 0" width="50%"></td>
+  </tr>
+  <tr>
+    <td><img src="docs/images/stripes/whole_512.png" alt="Contour tracing stripe 0" width="50%"></td>
+  </tr>
+  <tr>
+    <td><img src="docs/images/stripes/whole_768.png" alt="Contour tracing stripe 0" width="50%"></td>
+  </tr>
+  <tr><td colspan="2"><em><b>Left:</b> The image is split into 4 independent memory buffers (stripes).
+  <br><b>Right:</b> Contrek ensures <b>perfect topological continuity</b> during merging.</em>
+    <br><span style="color: #d32f2f;">■</span> <b>Red:</b> Outer contours |
+    <span style="color: #2e7d32;">■</span> <b>Dark Green:</b> Inner zones</td></tr>
+</table>
 
 ## Prerequisites
 
@@ -180,6 +219,26 @@ result = Contrek.contour!(
 )
 ```
 
+## Tracing Modes
+
+Contrek provides two levels of precision for polygon generation to balance data density and topological accuracy.
+
+### **Standard Mode** (Default)
+Optimized for **speed** and **lightweight** output.
+* **Behavior:** Traces outer boundaries while simplifying collinear segments.
+* **Result:** Fewer vertices and smaller memory footprint.
+
+### **Strict Mode** (`strict_bounds: true`)
+Engineered for **Pixel-Perfect** precision.
+* **Behavior:** Preserves every junction and internal connectivity change.
+* **Result:** 100% topologically faithful geometry with no micro-gaps between adjacent polygons.
+
+Below are two images illustrating the difference in tracing modes. In the first case, with **strict_bounds ON**, the anti-clockwise sequence includes two additional points, **H** and **I**, which trace the shape more accurately. In the second case, the transition between **G** and **H** is approximated, omitting the indentation.
+| Strict Bounds ON | Strict Bounds OFF |
+|:---:|:---:|
+| ![Originale](./docs/images/strict_bounds_on.png) | ![Poligoni](./docs/images/strict_bounds_off.png) |
+
+
 ## Result
 
 The result structure contains polygon coordinates and a set of metadata. Polygon coordinates can be accessed via:

data/ext/cpp_polygon_finder/PolygonFinder/examples/example.cpp

@@ -24,6 +24,7 @@ void run_test() {
   // test_suite.test_f();
   // test_suite.test_g();
   // test_suite.test_h();
+  test_suite.test_i();
   std::cout << "compute time =" << cpu_timer.stop() << std::endl;
 }
 

data/ext/cpp_polygon_finder/PolygonFinder/src/Tests.cpp

@@ -14,12 +14,16 @@
 #include <map>
 #include <vector>
 #include <string>
+#include <cstring>
+#include <algorithm>
+#include <cstdio>
 #include "polygon/finder/PolygonFinder.h"
 #include "polygon/finder/concurrent/ClippedPolygonFinder.h"
 #include "polygon/bitmaps/Bitmap.h"
 #include "polygon/bitmaps/FastPngBitmap.h"
 #include "polygon/bitmaps/RawBitmap.h"
 #include "polygon/bitmaps/RemoteFastPngBitmap.h"
+#include "polygon/bitmaps/spng.h"
 #include "polygon/matchers/Matcher.h"
 #include "polygon/matchers/RGBMatcher.h"
 #include "polygon/matchers/RGBNotMatcher.h"
@@ -27,6 +31,7 @@
 #include "polygon/finder/optionparser.h"
 #include "polygon/finder/concurrent/Finder.h"
 #include "polygon/finder/concurrent/HorizontalMerger.h"
+#include "polygon/finder/concurrent/VerticalMerger.h"
 #include "polygon/finder/concurrent/Sequence.h"
 #include "polygon/finder/concurrent/Position.h"
 #include "polygon/finder/Polygon.h"
@@ -46,6 +51,7 @@ void Tests::test_a()
   Bitmap b(chunk, 16);
   PolygonFinder pl(&b, &matcher, nullptr, &arguments);
   ProcessResult *o = pl.process_info();
+  // o->print_polygons();
   std::vector<int> outer_array{11, 1, 6, 2, 6, 3, 6, 4, 6, 5, 11, 5, 11, 4, 11, 3, 11, 2, 11, 1};
   std::vector<int> inner_array{7, 3, 10, 3, 10, 4, 7, 4};
   std::vector<int> array_compare;
@@ -253,3 +259,110 @@ void Tests::test_h()
   delete left_result;
   delete right_result;
 }
+
+/* In this example, PNG data is read by streaming into a user-defined buffer height.
+  Contrek scans each stripe and extracts the polygons. Finally, it merges all
+  polygons from every stripe as if they had been read from a single image and saves
+  the result polygons on a png image.
+  This approach allows for processing large PNG files on systems where memory
+  would otherwise be insufficient.
+*/
+void stream_png_image(const std::string& filepath, uint32_t stripe_height) {
+    std::vector<ProcessResult*> result_clones;
+    std::vector<std::string> varguments = {};
+    VerticalMerger vmerger(0, &varguments);
+
+    // opens image to stream
+    FILE* fp = fopen(filepath.c_str(), "rb");
+    if (!fp) {
+      std::cerr << "Unable open file: " << filepath << std::endl;
+      return;
+    }
+
+    // exams image
+    spng_ctx *ctx = spng_ctx_new(0);
+    spng_set_png_file(ctx, fp);
+    struct spng_ihdr ihdr;
+    if (spng_get_ihdr(ctx, &ihdr)) {
+      fclose(fp);
+      spng_ctx_free(ctx);
+      return;
+    }
+    uint32_t total_width = ihdr.width;
+    uint32_t total_height = ihdr.height;
+
+    // allocates stripe buffer
+    RawBitmap stripe_bitmap;
+    stripe_bitmap.define(total_width, stripe_height, 4, true);
+    RGBNotMatcher not_matcher(-1);
+
+    if (spng_decode_image(ctx, NULL, 0, SPNG_FMT_RGBA8, SPNG_DECODE_PROGRESSIVE)) {
+      fclose(fp);
+      spng_ctx_free(ctx);
+      return;
+    }
+
+    size_t row_size = static_cast<size_t>(total_width) * 4;
+    // main strpes loop
+    for (uint32_t current_y_offset = 0; current_y_offset < total_height; current_y_offset += stripe_height) {
+      int uncovered_height = total_height - current_y_offset;
+
+      // copy previous last line to the next new one (each contigue stripe must share one pixel scanline)
+      if (current_y_offset > 0) {
+        unsigned char* last_row_prev = const_cast<unsigned char*>(stripe_bitmap.get_row_ptr(stripe_height - 1));
+        unsigned char* first_row_curr = const_cast<unsigned char*>(stripe_bitmap.get_row_ptr(0));
+        std::memcpy(first_row_curr, last_row_prev, row_size);
+      }
+      // clears the part of the stripe wont be overwritten by png data
+      if (uncovered_height < stripe_height)
+      { stripe_bitmap.draw_filled_rectangle(0, 1, total_width, stripe_height - 1, 255, 255, 255);
+      }
+      // decoding data directly in the stripe buffer
+      uint32_t lines_to_read = std::min(stripe_height, total_height - current_y_offset);
+      for (uint32_t y = (current_y_offset == 0 ? 0 : 1); y < lines_to_read; y++) {
+        unsigned char* row_ptr = const_cast<unsigned char*>(stripe_bitmap.get_row_ptr(y));
+        int ret = spng_decode_row(ctx, row_ptr, row_size);
+        if (ret != 0 && ret != SPNG_EOI) break;
+      }
+      // stripe contour tracing
+      std::vector<std::string> finder_arguments = {
+        "--versus=a",
+        "--strict_bounds"  // <- this option is strictly needed when working with vertical merger
+      };
+      PolygonFinder polygon_finder(&stripe_bitmap, &not_matcher, nullptr, &finder_arguments);
+      ProcessResult *result = polygon_finder.process_info();
+      if (result) {
+        std::cout << "Founds polygons: " << result->groups << std::endl;
+        ProcessResult* safe_result = result->clone();
+        result_clones.push_back(safe_result);
+        vmerger.add_tile(*safe_result);
+        delete result;
+      }
+    }
+
+    std::cout << "Merging polygons ..." << std::endl;
+    ProcessResult *merged_result = vmerger.process_info();
+    std::cout << "Founds total polygons: " << merged_result->groups << std::endl;
+
+    if (merged_result) {
+      RawBitmap full_bitmap;
+      full_bitmap.define(total_width, total_height, 4, true);
+      full_bitmap.fill(255, 255, 255);
+      merged_result->draw_on_bitmap(full_bitmap);
+      std::cout << "Saving whole png ..." << std::endl;
+      if (full_bitmap.save_to_png("whole.png")) {
+        std::cout << "Png saved!" << std::endl;
+      }
+    }
+    delete merged_result;
+    // frees memory
+    for (auto c : result_clones) {
+      delete c;
+    }
+    spng_ctx_free(ctx);
+    fclose(fp);
+}
+
+void Tests::test_i() {
+  stream_png_image("../images/graphs_1024x1024.png", 300);
+}

data/ext/cpp_polygon_finder/PolygonFinder/src/Tests.h

@@ -19,4 +19,5 @@ class Tests {
   virtual void test_f();
   virtual void test_g();
   virtual void test_h();
+  virtual void test_i();
 };

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/bitmaps/RawBitmap.cpp

@@ -8,6 +8,12 @@
  */
 
 #include <memory>
+#include <cstdio>
+#include <iostream>
+#include <cstring>
+#include <cerrno>
+#include <string>
+#include "spng.h"
 #include "RawBitmap.h"
 
 RawBitmap::RawBitmap() : Bitmap("", 0),
@@ -42,7 +48,7 @@ unsigned int RawBitmap::rgb_value_at(int x, int y) {
 }
 
 void RawBitmap::draw_pixel(int x, int y, unsigned char r, unsigned char g, unsigned char b, unsigned char a) {
-  if (x >= width || y >= height) return;
+  if (x < 0 || x >= width || y < 0 || y >= height) return;
   unsigned char* p = &image[(static_cast<size_t>(y) * width + x) * bpp];
   p[0] = r;
   if (bpp > 1) p[1] = g;
@@ -62,3 +68,96 @@ uint32_t RawBitmap::define(uint width, uint height, int bytes_per_pixel, bool cl
   return dimension;
 }
 
+void RawBitmap::fill(unsigned char r, unsigned char g, unsigned char b, unsigned char a) {
+  if (!image) return;
+  size_t size = static_cast<size_t>(width) * height * bpp;
+
+  if (r == g && g == b && b == a) {
+    std::memset(image.get(), r, size);
+  } else {
+    for (size_t i = 0; i < size; i += bpp) {
+      image[i] = r;
+      if (bpp > 1) image[i+1] = g;
+      if (bpp > 2) image[i+2] = b;
+      if (bpp > 3) image[i+3] = a;
+    }
+  }
+}
+
+void RawBitmap::draw_line(int x0, int y0, int x1, int y1, unsigned char r, unsigned char g, unsigned char b, unsigned char a) {
+  int dx = abs(x1 - x0), sx = x0 < x1 ? 1 : -1;
+  int dy = -abs(y1 - y0), sy = y0 < y1 ? 1 : -1;
+  int err = dx + dy, e2;
+  while (true) {
+    draw_pixel(x0, y0, r, g, b, a);
+    if (x0 == x1 && y0 == y1) break;
+    e2 = 2 * err;
+    if (e2 >= dy) {
+      err += dy; x0 += sx;
+    }
+    if (e2 <= dx) {
+      err += dx; y0 += sy;
+    }
+  }
+}
+
+void RawBitmap::draw_filled_rectangle(int x, int y, int w, int h, unsigned char r, unsigned char g, unsigned char b, unsigned char a) {
+  if (w <= 0 || h <= 0) return;
+
+  for (int i = 0; i < h; ++i) {
+    int current_y = y + i;
+    this->draw_line(x, current_y, x + w - 1, current_y, r, g, b, a);
+  }
+}
+
+bool RawBitmap::save_to_png(const std::string& filename) {
+  if (this->width == 0 || this->height == 0 || !this->image) {
+    std::cerr << "Error: Bitmap empty or uninitialized" << std::endl;
+    return false;
+  }
+  FILE *fp = fopen(filename.c_str(), "wb");
+  if (!fp) {
+    std::cerr << "Unable open file" << filename << ": "
+              << std::strerror(errno) << std::endl;
+    return false;
+  }
+  spng_ctx *ctx = spng_ctx_new(SPNG_CTX_ENCODER);
+  if (!ctx) {
+    fclose(fp);
+    return false;
+  }
+  spng_set_png_file(ctx, fp);
+  struct spng_ihdr ihdr;
+  std::memset(&ihdr, 0, sizeof(struct spng_ihdr));
+
+  ihdr.width = this->width;
+  ihdr.height = this->height;
+  ihdr.bit_depth = 8;
+
+  // color type by bpp
+  // 6 = RGBA (Truecolor with Alpha)
+  // 2 = RGB  (Truecolor)
+  ihdr.color_type = (this->bpp == 4) ? 6 : 2;
+
+  int ret = spng_set_ihdr(ctx, &ihdr);
+  if (ret) {
+    std::cerr << "Error spng_set_ihdr: " << spng_strerror(ret) << std::endl;
+    spng_ctx_free(ctx);
+    fclose(fp);
+    return false;
+  }
+
+  // encoding
+  size_t image_size = static_cast<size_t>(this->width) * this->height * this->bpp;
+  ret = spng_encode_image(ctx, this->image.get(), image_size, SPNG_FMT_PNG, SPNG_ENCODE_FINALIZE);
+  if (ret) {
+    std::cerr << "Encoding error: " << spng_strerror(ret) << " (code: " << ret << ")" << std::endl;
+    std::cerr << "Data W: " << width << " H: " << height << " BPP: " << bpp << " Size: " << image_size << std::endl;
+  }
+
+  spng_ctx_free(ctx);
+  fflush(fp);
+  fclose(fp);
+
+  return (ret == 0);
+}

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/bitmaps/RawBitmap.h

@@ -27,6 +27,10 @@ class RawBitmap : public Bitmap {
   int get_bytes_per_pixel() const;
   uint32_t define(uint width, uint height, int bytes_per_pixel, bool clear = false);
   void draw_pixel(int x, int y, unsigned char r, unsigned char g, unsigned char b, unsigned char a = 255);
+  bool save_to_png(const std::string& filename);
+  void fill(unsigned char r, unsigned char g, unsigned char b, unsigned char a = 255);
+  void draw_line(int x0, int y0, int x1, int y1, unsigned char r, unsigned char g, unsigned char b, unsigned char a = 255);
+  void draw_filled_rectangle(int x, int y, int w, int h, unsigned char r, unsigned char g, unsigned char b, unsigned char a = 255);
 
  protected:
   std::unique_ptr<unsigned char[]> image;

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

@@ -22,7 +22,9 @@ void FinderUtils::sanitize_options(pf_Options& options, std::vector<std::string>
   char** argv = &argv0[0];
   int argc = argv0.size() -1;
 
-  enum  optionIndex { COMPRESS_UNIQ, VERSUS, COMPRESS_VISVALINGAM, COMPRESS_LINEAR, NUMBER_OF_TILES, COMPRESS_VISVALINGAM_TOLERANCE, TREEMAP, NAMED_SEQUENCES, BOUNDS, CONNECTIVITY};
+  enum  optionIndex { COMPRESS_UNIQ, VERSUS, COMPRESS_VISVALINGAM, COMPRESS_LINEAR, NUMBER_OF_TILES,
+                      COMPRESS_VISVALINGAM_TOLERANCE, TREEMAP, NAMED_SEQUENCES, BOUNDS, CONNECTIVITY,
+                      STRICT_BOUNDS };
   const option::Descriptor usage[] = {
      //  {UNKNOWN, 0,"" , ""    ,option::Arg::None, 0},
      {COMPRESS_VISVALINGAM, 0, "" , "compress_visvalingam", option::Arg::None, 0},
@@ -33,6 +35,7 @@ void FinderUtils::sanitize_options(pf_Options& options, std::vector<std::string>
      {TREEMAP, 0, "", "treemap", option::Arg::None, 0},
      {NAMED_SEQUENCES, 0, "", "named_sequences", option::Arg::None, 0},
      {BOUNDS, 0, "", "bounds", option::Arg::None, 0},
+     {STRICT_BOUNDS, 0, "", "strict_bounds", option::Arg::None, 0},
      {VERSUS, 0, "v", "versus", option::Arg::Optional, 0},
      {CONNECTIVITY, 0, "c", "connectivity", option::Arg::Optional, 0},
      {0, 0, 0, 0, 0, 0}
@@ -86,6 +89,9 @@ void FinderUtils::sanitize_options(pf_Options& options, std::vector<std::string>
   if (ioptions[BOUNDS].count() > 0)
   { options.bounds = true;
   }
+  if (ioptions[STRICT_BOUNDS].count() > 0)
+  { options.strict_bounds = true;
+  }
   // COMPRESS LINEAR
   if (ioptions[COMPRESS_LINEAR].count() > 0)
   { options.compress_linear = true;

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

@@ -18,6 +18,7 @@
 #include "NodeCluster.h"
 #include "Node.h"
 #include "RectBounds.h"
+#include "PointPool.h"
 #include "../reducers/UniqReducer.h"
 #include "../reducers/LinearReducer.h"
 #include "../reducers/VisvalingamReducer.h"
@@ -243,7 +244,7 @@ std::pair<int, int> NodeCluster::test_in_hole_o(Node* node)
 
 void NodeCluster::plot_inner_node(std::vector<Point*>& sequence_coords, Node *node, int versus, Node *stop_at, Node *start_node) {
   Node *current_node = node;
-
+  bool strict_bounds = this->options->strict_bounds;
   while (current_node != nullptr) {
     current_node->outer_index = start_node->outer_index;
     current_node->inner_index = stop_at->inner_index;
@@ -271,7 +272,12 @@ void NodeCluster::plot_inner_node(std::vector<Point*>& sequence_coords, Node *no
           sequence_coords.push_back(next_node->coords_entering_to(current_node, versus, Node::INNER));
         }
       }
-    }
+    } else if (strict_bounds) {
+        bool first_is_max = ((current_node->y > last_node->y) == (versus == Node::A));
+        sequence_coords.push_back(this->points_pool.acquire((first_is_max ? last_node->max_x : last_node->min_x), current_node->y));
+        sequence_coords.push_back(this->points_pool.acquire((first_is_max ? next_node->min_x : next_node->max_x), current_node->y));
+      }
+
     if (current_node->track_uncomplete()) {
       this->inner_new->push_back(current_node);
     } else {
@@ -284,6 +290,7 @@ void NodeCluster::plot_inner_node(std::vector<Point*>& sequence_coords, Node *no
 
 void NodeCluster::plot_node(std::vector<Point*>& sequence_coords, Node *node, Node *start_node, int versus, RectBounds& bounds) {
   Node *current_node = node;
+  bool strict_bounds = this->options->strict_bounds;
 
   while (current_node != nullptr) {
     root_nodes->remove(current_node);
@@ -315,7 +322,13 @@ void NodeCluster::plot_node(std::vector<Point*>& sequence_coords, Node *node, No
           inner_plot->contains(current_node) ? inner_plot->remove(current_node) : inner_plot->push_back(current_node);
         }
       }
-    }
+    } else if (strict_bounds) {
+        bool is_down = current_node->y > last_node->y;
+        bool is_a = (versus == Node::A);
+        sequence_coords.push_back(this->points_pool.acquire((is_down == is_a ? last_node->min_x : last_node->max_x), current_node->y));
+        sequence_coords.push_back(this->points_pool.acquire((is_down == is_a ? next_node->max_x : next_node->min_x), current_node->y));
+      }
+
     if (current_node == start_node) {
       if (current_node->track_complete()) break;
     }

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

@@ -18,6 +18,7 @@
 #include "Lists.h"
 #include "RectBounds.h"
 #include "Polygon.h"
+#include "PointPool.h"
 
 class Node;
 struct Point;
@@ -34,6 +35,7 @@ class NodeCluster {
   int count = 0;
   int nodes;
   int width;
+  PointPool points_pool;
 
  public:
   pf_Options *options;

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

@@ -0,0 +1,19 @@
+/*
+ * PointPool.cpp
+ *
+ * Copyright (c) 2025-2026 Emanuele Cesaroni
+ *
+ * Licensed under the GNU Affero General Public License v3 (AGPLv3).
+ * See the LICENSE file in this directory for the full license text.
+ */
+
+#include "PointPool.h"
+
+Point* PointPool::acquire(int x, int y) {
+  storage.emplace_back(x, y);
+  return &storage.back();
+}
+
+void PointPool::clear() {
+  storage.clear();
+}

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

@@ -0,0 +1,24 @@
+/*
+ * PointPool.h
+ *
+ * Copyright (c) 2025-2026 Emanuele Cesaroni
+ *
+ * Licensed under the GNU Affero General Public License v3 (AGPLv3).
+ * See the LICENSE file in this directory for the full license text.
+ */
+
+#pragma once
+#include <deque>
+#include <cstdint>
+#include <string>
+#include "Node.h"
+
+class PointPool {
+ private:
+  std::deque<Point> storage;
+
+ public:
+  Point* acquire(int x, int y);
+  void clear();
+  size_t size() const { return storage.size(); }
+};

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

@@ -17,6 +17,8 @@
 #include <utility>
 #include "PolygonFinder.h"
 #include "../bitmaps/Bitmap.h"
+#include "../bitmaps/RawBitmap.h"
+
 #include "../matchers/Matcher.h"
 #include "../matchers/RGBMatcher.h"
 #include "../matchers/RGBNotMatcher.h"
@@ -124,3 +126,31 @@ ProcessResult* PolygonFinder::process_info() {
   else pr->named_sequence = "";
   return(pr);
 }
+
+void ProcessResult::draw_on_bitmap(RawBitmap& bitmap) const {
+  for (const auto& poly : polygons) {
+    // --- OUTER ---
+    if (!poly.outer.empty()) {
+      for (size_t i = 0; i < poly.outer.size() - 1; ++i) {
+        Point* p1 = poly.outer[i];
+        Point* p2 = poly.outer[i+1];
+        bitmap.draw_line(p1->x, p1->y, p2->x, p2->y, 255, 0, 0, 255);
+      }
+      Point* last = poly.outer.back();
+      Point* first = poly.outer.front();
+      bitmap.draw_line(last->x, last->y, first->x, first->y, 255, 0, 0, 255);
+    }
+    // --- INNER ---
+    for (const auto& sequence : poly.inner) {
+      if (sequence.empty()) continue;
+      for (size_t i = 0; i < sequence.size() - 1; ++i) {
+        Point* p1 = sequence[i];
+        Point* p2 = sequence[i+1];
+        bitmap.draw_line(p1->x, p1->y, p2->x, p2->y, 0, 128, 0, 255);
+      }
+      Point* last = sequence.back();
+      Point* first = sequence.front();
+      bitmap.draw_line(last->x, last->y, first->x, first->y, 0, 128, 0, 255);
+    }
+  }
+}

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

@@ -27,6 +27,7 @@ class Matcher;
 class RGBMatcher;
 class NodeCluster;
 class Node;
+class RawBitmap;
 struct Point;
 
 struct ShapeLine {
@@ -41,6 +42,7 @@ struct pf_Options {
   bool compress_visvalingam = false;
   bool named_sequences = false;
   bool bounds = false;
+  bool strict_bounds = false;
   int connectivity_offset = 0;
   float compress_visvalingam_tolerance = 10.0;
   int number_of_tiles = 1;
@@ -48,6 +50,7 @@ struct pf_Options {
     return(versus == Node::A ? "a" : "o");
   }
 };
+
 struct ProcessResult {
   int groups;
   int width, height;
@@ -55,6 +58,7 @@ struct ProcessResult {
   std::list<Polygon> polygons;
   std::string named_sequence;
   std::vector<std::pair<int, int>> treemap;
+  void draw_on_bitmap(RawBitmap& canvas) const;
 
   void print_polygons() {
     int counter = 0;
@@ -67,7 +71,7 @@ struct ProcessResult {
         first = false;
         for (const Point* p : seq) std::cout << p->toString();
       }
-      std::cout << "\n";
+      std::cout << "\n" << polygon.bounds.to_string() <<"\n";
       counter++;
     }
   }
@@ -89,6 +93,40 @@ struct ProcessResult {
       polygon.bounds.max_x += x;
     }
   }
+
+  ProcessResult* clone() const {
+    ProcessResult* new_res = new ProcessResult();
+    new_res->groups = this->groups;
+    new_res->width = this->width;
+    new_res->height = this->height;
+    new_res->benchmarks = this->benchmarks;
+    new_res->named_sequence = this->named_sequence;
+    new_res->treemap = this->treemap;
+
+    for (const auto& poly : this->polygons) {
+      Polygon new_poly;
+      // Bounds
+      new_poly.bounds = poly.bounds;
+      // outer
+      for (const Point* p : poly.outer) {
+        if (p) {
+          new_poly.outer.push_back(new Point(p->x, p->y));
+        }
+      }
+      // inner
+      for (const auto& seq : poly.inner) {
+        std::vector<Point*> new_seq;
+        for (const Point* p : seq) {
+          if (p) {
+            new_seq.push_back(new Point(p->x, p->y));
+          }
+        }
+        new_poly.inner.push_back(new_seq);
+      }
+      new_res->polygons.push_back(new_poly);
+    }
+    return new_res;
+  }
 };
 
 class PolygonFinder {

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

@@ -10,6 +10,9 @@
 #pragma once
 #include <limits>
 #include <algorithm>
+#include <string>
+#include <sstream>
+#include <iostream>
 
 struct RectBounds {
   int min_x = std::numeric_limits<int>::max();
@@ -37,4 +40,13 @@ struct RectBounds {
     if (is_empty()) return 0;
     return(max_x - min_x);
   }
+
+  std::string to_string() const {
+    if (is_empty()) return "RectBounds: empty";
+    std::stringstream ss;
+    ss << "RectBounds ["
+       << "X(min=" << min_x << ",max=" << max_x << ") "
+       << "Y(min=" << min_y << ",max=" << max_y << ")]";
+    return ss.str();
+  }
 };

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Part.cpp

@@ -98,7 +98,7 @@ std::vector<EndPoint*> Part::remove_adjacent_pairs(const std::vector<EndPoint*>&
 }
 
 void Part::orient()
-{ if (this->size <= 1) {
+{ if (this->size <= 1 || (this->size == 2 && this->inverts)) {
     this->versus_ = 0;
   } else {
     this->versus_ = (this->tail->payload->y - this->head->payload->y) > 0 ? 1 : -1;

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/VerticalMerger.cpp

@@ -22,8 +22,8 @@ void VerticalMerger::add_tile(ProcessResult& result)
 { transpose(result);
   if (this->tiles.size() > 0) {
     translate(result, this->current_x);
-    adjust(result);
   }
+  adjust(result);
   Merger::add_tile(result);
 }
 

data/ext/cpp_polygon_finder/cpp_polygon_finder.cpp

@@ -24,6 +24,8 @@
 #include "PolygonFinder/src/polygon/finder/List.h"
 #include "PolygonFinder/src/polygon/finder/Lists.cpp"
 #include "PolygonFinder/src/polygon/finder/Lists.h"
+#include "PolygonFinder/src/polygon/finder/PointPool.h"
+#include "PolygonFinder/src/polygon/finder/PointPool.cpp"
 #include "PolygonFinder/src/polygon/finder/Polygon.h"
 #include "PolygonFinder/src/polygon/bitmaps/Bitmap.h"
 #include "PolygonFinder/src/polygon/bitmaps/Bitmap.cpp"
@@ -219,7 +221,7 @@ class To_Ruby<ProcessResult*>
     return_me[Symbol("treemap")] = tmapout;
     rr->metadata = return_me;
 
-    // Protects objects 'out' e 'return_me' linking them to the ruby instance preventing GC
+    // Protects objects 'out' and 'return_me' linking them to the ruby instance preventing GC
     // garbage collector to free them before the instance itself.
     Rice::Object ruby_obj = rb_result;
     ruby_obj.iv_set("@polygons_storage", out);
@@ -240,7 +242,6 @@ ProcessResult ruby_result_to_process_result(Rice::Object rb_result) {
 
   Rice::Array rb_polygons = rb_result.iv_get("@polygons_storage");
   for (size_t i = 0; i < rb_polygons.size(); ++i) {
-    // Cast esplicito a Rice::Hash per evitare il Proxy
     Rice::Hash rb_poly = (Rice::Hash)rb_polygons[i];
     Polygon poly;
     // BOUNDS
@@ -371,9 +372,22 @@ void Init_cpp_polygon_finder() {
     define_class<VerticalMerger, Merger>("CPPVerticalMerger")
     .define_constructor(Constructor<VerticalMerger, int, std::vector<std::string>*>(), Arg("number_of_threads"), Arg("options") = nullptr, Arg("yield_gvl") = true);
 
-  Data_Type<RubyResult> rb_cResult =
-    define_class_under<RubyResult>(rb_cFinder, "Result")
+  Module mContrek = define_module("Contrek");
+  Module mCpp = define_module_under(mContrek, "Cpp");
+  Data_Type<RubyResult> rb_cResult = define_class_under<RubyResult>(mCpp, "CPPResult")
     .define_constructor(Constructor<RubyResult>())
     .define_method("polygons", [](RubyResult& rr) { return rr.polygons; })
-    .define_method("metadata", [](RubyResult& rr) { return rr.metadata; });
+    .define_method("metadata", [](RubyResult& rr) { return rr.metadata; })
+    .define_method("polygons=", [](RubyResult& rr, Object value) {
+      rr.polygons = value;
+      Rice::Data_Object<RubyResult> self(&rr);
+      self.iv_set("@polygons_storage", value);
+      return value;
+    })
+    .define_method("metadata=", [](RubyResult& rr, Object value) {
+      rr.metadata = (Rice::Hash)value;
+      Rice::Data_Object<RubyResult> self(&rr);
+      self.iv_set("@metadata_storage", value);
+      return value;
+    });
 }

data/lib/contrek/bitmaps/chunky_bitmap.rb

@@ -33,6 +33,16 @@ module Contrek
         ChunkyBitmap.new(@raw, @module)
       end
 
+      def draw_rect(x:, y:, width:, height:, color: "o", filled: true)
+        (y...(y + height)).each do |row|
+          (x...(x + width)).each do |col|
+            if filled || row == y || row == y + height - 1 || col == x || col == x + width - 1
+              value_set(col, row, color)
+            end
+          end
+        end
+      end
+
       def draw_polygons(polygons)
         polygons.each do |polygon|
           [[:outer, "o"], [:inner, "i"]].each do |side, color|
@@ -47,16 +57,54 @@ module Contrek
         end
       end
 
-      def to_terminal
+      def draw_numbered_polygons(polygons)
+        polygons.each do |polygon|
+          color = "A"
+          polygon[:outer].each_with_index do |position, index|
+            value_set(position[:x], position[:y], color)
+            color = next_color(color)
+          end
+          polygon[:inner].each do |sequence|
+            color = "a"
+            sequence.each_with_index do |position, index|
+              value_set(position[:x], position[:y], color)
+              color = next_color(color)
+            end
+          end
+        end
+      end
+
+      def to_terminal(label = nil)
+        puts label if label
         puts "  " + (0...@module).map { |i| (i % 10).to_s }.join
         n = 0
         @raw.scan(/.{1,#{@module}}/).each do |line|
-          puts n.to_s + " " + line
+          colored_line = line.chars.map { |c| colorize_char(c) }.join
+          puts "#{n} #{colored_line}"
           n += 1
           n = 0 if n >= 10
         end
         puts
       end
+
+      private
+
+      def next_color(color)
+        return "A" if color == "Z"
+        return "a" if color == "z"
+        color.next
+      end
+
+      def colorize_char(char)
+        case char
+        when "A".."Z"
+          "\e[91;1m#{char}\e[0m"
+        when "a".."z"
+          "\e[92;1m#{char}\e[0m"
+        else
+          char
+        end
+      end
     end
   end
 end

data/lib/contrek/cpp/cpp_result.rb

@@ -0,0 +1,42 @@
+module Contrek
+  module Cpp
+    class CPPResult
+      def polygons=(list)
+        @polygons_storage = list
+      end
+
+      def metadata=(map)
+        @metadata_storage = {
+          width: 0,
+          height: 0,
+          benchmarks: {},
+          treemap: []
+        }.merge(map)
+      end
+
+      def points
+        raw_list = polygons.to_a
+        @to_points ||= raw_list.map do |polygon|
+          {outer: self.class.to_points(polygon[:outer]),
+           inner: polygon[:inner].map { |s| self.class.to_points(s) }}
+        end
+      end
+
+      def total_time
+        metadata[:benchmarks].values.sum
+      end
+
+      def self.to_points(flat_polygon)
+        flat_polygon.each_slice(2).map { |x, y| {x: x, y: y} }
+      end
+
+      def self.to_numpy(polygons_data)
+        polygons_data.map do |poly|
+          {outer: poly[:outer].flat_map { |p| [p[:x], p[:y]] },
+           inner: (poly[:inner] || []).map { |hole| hole.flat_map { |p| [p[:x], p[:y]] } },
+           bounds: poly[:bounds]}
+        end
+      end
+    end
+  end
+end

data/lib/contrek/finder/concurrent/part.rb

@@ -69,10 +69,16 @@ module Contrek
       end
 
       def intersect_part?(other_part)
+        intersect = false
         other_part.each do |position|
-          return true if position.end_point.queues.include?(self)
+          if position.end_point.queues.include?(self)
+            intersect = true
+            false
+          else
+            true
+          end
         end
-        false
+        intersect
       end
 
       def to_endpoints
@@ -80,7 +86,7 @@ module Contrek
       end
 
       def orient!
-        @versus = if size <= 1
+        @versus = if size <= 1 || (size == 2 && @inverts)
           0
         else
           (tail.payload[:y] - head.payload[:y]).positive? ? 1 : -1

data/lib/contrek/finder/concurrent/vertical_merger.rb

@@ -5,8 +5,8 @@ module Contrek
         transpose(result)
         if @tiles.size > 0
           translate(result, @current_x)
-          adjust(result)
         end
+        adjust(result)
         super
       end
 
@@ -26,7 +26,7 @@ module Contrek
       end
 
       def transpose(result)
-        result.metadata_hash[:width], result.metadata_hash[:height] = result.metadata_hash[:height], result.metadata_hash[:width]
+        result.metadata[:width], result.metadata[:height] = result.metadata[:height], result.metadata[:width]
         result.polygons.each do |polygon|
           polygon[:outer].each { |p| p[:x], p[:y] = p[:y], p[:x] }
           polygon[:inner].each do |sequence|

data/lib/contrek/finder/node_cluster.rb

@@ -73,7 +73,7 @@ module Contrek
             @sequence_coords << coord
             bounds.expand(x: coord[:x], y: coord[:y])
           end
-          plot_node(next_node, root_node, bounds, versus) if @nodes > 0 && !next_node.nil?
+          plot_node(next_node, root_node, bounds, versus, @options[:strict_bounds]) if @nodes > 0 && !next_node.nil?
 
           draw_sequence(bitmap, "X") unless bitmap.nil?
           @polygons << {outer: @sequence_coords, inner: [], bounds: (bounds.to_h if @options[:bounds])}.compact if @sequence_coords.size >= 2
@@ -115,7 +115,7 @@ module Contrek
               @sequence_coords << next_node.coords_entering_to(first, inner_v, Contrek::Finder::Node::INNER)
             end
 
-            plot_inner_node(next_node, inner_v, first, root_node) if !next_node.nil?
+            plot_inner_node(next_node, inner_v, first, root_node, options[:strict_bounds]) if !next_node.nil?
 
             draw_sequence(bitmap, "+") unless bitmap.nil?
 
@@ -189,7 +189,7 @@ module Contrek
       # inner way
       # nodes in @plot_sequence
       # coordinates in @sequence_coords
-      def plot_inner_node(node, versus, stop_at, start_node)
+      def plot_inner_node(node, versus, stop_at, start_node, strict_bounds = false)
         node.outer_index = start_node.outer_index
         node.inner_index = stop_at.inner_index
         @root_nodes.delete(node)
@@ -210,6 +210,10 @@ module Contrek
               @sequence_coords << next_node.coords_entering_to(node, versus, Contrek::Finder::Node::INNER)
             end
           end
+        elsif strict_bounds
+          first_is_max = ((node.y > last_node.y) == (versus == :a))
+          @sequence_coords << {y: node.y, x: (first_is_max ? last_node.max_x : last_node.min_x)}
+          @sequence_coords << {y: node.y, x: (first_is_max ? next_node.min_x : next_node.max_x)}
         end
 
         if node.track_uncomplete
@@ -219,11 +223,11 @@ module Contrek
         end
 
         return if next_node == stop_at
-        plot_inner_node(next_node, versus, stop_at, start_node)
+        plot_inner_node(next_node, versus, stop_at, start_node, strict_bounds)
       end
 
       # contour tracing core logic loop
-      def plot_node(node, start_node, bounds, versus = :a)
+      def plot_node(node, start_node, bounds, versus = :a, strict_bounds = false)
         @root_nodes.delete(node)
 
         node.outer_index = start_node.outer_index
@@ -252,13 +256,18 @@ module Contrek
               @inner_plot.contains(node) ? @inner_plot.delete(node) : @inner_plot << node
             end
           end
+        elsif strict_bounds
+          is_down = node.y > last_node.y
+          is_a = (versus == :a)
+          @sequence_coords << {y: node.y, x: ((is_down == is_a) ? last_node.min_x : last_node.max_x)}
+          @sequence_coords << {y: node.y, x: ((is_down == is_a) ? next_node.max_x : next_node.min_x)}
         end
         # exit if root_node
 
         if node == start_node
           return if node.track_complete
         end
-        plot_node(next_node, start_node, bounds, versus)
+        plot_node(next_node, start_node, bounds, versus, strict_bounds)
       end
 
       def add_node(node, offset)

data/lib/contrek/finder/polygon_finder.rb

@@ -4,7 +4,7 @@ module Contrek
   module Finder
     class PolygonFinder
       def initialize(bitmap, matcher, test_bitmap = nil, options = {})
-        @options = {versus: :a}.merge(options)
+        @options = {versus: :a, strict_bounds: false}.merge(options)
         sanitize_options
         @source_bitmap = bitmap
         @matcher = matcher

data/lib/contrek/finder/result.rb

@@ -1,13 +1,9 @@
 module Contrek
   module Finder
-    Result = Struct.new(:polygons, :metadata_hash) do
+    Result = Struct.new(:polygons, :metadata) do
       def points
         polygons
       end
-
-      def metadata
-        metadata_hash
-      end
     end
   end
 end

data/lib/contrek/version.rb

@@ -1,3 +1,3 @@
 module Contrek
-  VERSION = "1.1.5"
+  VERSION = "1.1.6"
 end

data/lib/contrek.rb

@@ -49,7 +49,7 @@ require "contrek/cpp/cpp_concurrent_finder"
 require "contrek/cpp/cpp_concurrent_merger"
 require "contrek/cpp/cpp_concurrent_horizontal_merger"
 require "contrek/cpp/cpp_concurrent_vertical_merger"
-require "contrek/results/cpp_result"
+require "contrek/cpp/cpp_result"
 
 module Contrek
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors:
 - Emanuele Cesaroni
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-08 00:00:00.000000000 Z
+date: 2026-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -141,9 +141,17 @@ files:
 - Rakefile
 - contrek.gemspec
 - contrek.png
+- docs/images/strict_bounds_off.png
+- docs/images/strict_bounds_on.png
+- docs/images/stripes/whole.png
+- docs/images/stripes/whole_0.png
+- docs/images/stripes/whole_256.png
+- docs/images/stripes/whole_512.png
+- docs/images/stripes/whole_768.png
 - ext/cpp_polygon_finder/PolygonFinder/CMakeLists.txt
 - ext/cpp_polygon_finder/PolygonFinder/LICENSE_AGPL.txt
 - ext/cpp_polygon_finder/PolygonFinder/examples/example.cpp
+- ext/cpp_polygon_finder/PolygonFinder/images/graphs_1024x1024.png
 - ext/cpp_polygon_finder/PolygonFinder/images/labyrinth.png
 - ext/cpp_polygon_finder/PolygonFinder/images/sample_10240x10240.png
 - ext/cpp_polygon_finder/PolygonFinder/src/ContrekApi.h
@@ -170,6 +178,8 @@ files:
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/Node.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/NodeCluster.cpp
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/NodeCluster.h
+- ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/PointPool.cpp
+- ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/PointPool.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/Polygon.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/PolygonFinder.cpp
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/PolygonFinder.h
@@ -246,6 +256,7 @@ files:
 - lib/contrek/cpp/cpp_concurrent_horizontal_merger.rb
 - lib/contrek/cpp/cpp_concurrent_merger.rb
 - lib/contrek/cpp/cpp_concurrent_vertical_merger.rb
+- lib/contrek/cpp/cpp_result.rb
 - lib/contrek/finder/bounds.rb
 - lib/contrek/finder/concurrent/clipped_polygon_finder.rb
 - lib/contrek/finder/concurrent/cluster.rb
@@ -283,7 +294,6 @@ files:
 - lib/contrek/reducers/reducer.rb
 - lib/contrek/reducers/uniq_reducer.rb
 - lib/contrek/reducers/visvalingam_reducer.rb
-- lib/contrek/results/cpp_result.rb
 - lib/contrek/version.rb
 homepage: https://github.com/runout77/contrek
 licenses:

data/lib/contrek/results/cpp_result.rb

@@ -1,21 +0,0 @@
-module Contrek
-  module Results
-    class CPPFinder::Result
-      def points
-        raw_list = polygons.to_a
-        @to_points ||= raw_list.map do |polygon|
-          {outer: self.class.to_points(polygon[:outer]),
-           inner: polygon[:inner].map { |s| self.class.to_points(s) }}
-        end
-      end
-
-      def total_time
-        metadata[:benchmarks].values.sum
-      end
-
-      def self.to_points(flat_polygon)
-        flat_polygon.each_slice(2).map { |x, y| {x: x, y: y} }
-      end
-    end
-  end
-end