contrek 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b46d3ae57168cfeb52a0788b6e11af74a164c8e19b4414783f95ac96d1507ed2
-  data.tar.gz: e0637093c914f2426a74b4a47ebeac34152ae473de619fda2e164f22c5d03bc8
+  metadata.gz: 3e7576fef74116c62a018f66a13d9e29d215f7b505637b40bcb16631250fed0d
+  data.tar.gz: 7ba2f39e97a44eaddd13361b4dc5a8f8cb1790a93dab327c1794d61e0ffc45a0
 SHA512:
-  metadata.gz: 472da77db1202e4cf38416e7c5dcfbd483a1f9b9fdb414afb3583a441c3ea180107741d1bc939270fb2aa46e54541712a0efc56f542abe9afd5f39d66e7c847a
-  data.tar.gz: 66ee95022392360b2cb9dbd9757d669a7f01cc95512ee4a74a288e7dc5c94657ebfc0ebe1107090b3e24df490462073f9ea3f2fd6cb57f7432214a809e486b0b
+  metadata.gz: 748e4750b607bc2a9e9e916fc0a00a96db530e94658822d1d6eb97508fa9e302e5def958a63e621a2f97be1396bb0acad4971aea936cbca700c1ea93ac5acdaf
+  data.tar.gz: 804a329359ea6648e4bcbf4babdb8af53a12205851d669b562fa37d5aa69a49f8b6988a143f2783c85b2681432f65ff52b82db8f207718bd29b16c46882f518d

data/README.md

@@ -49,6 +49,17 @@ 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).
+
+### 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 complete testing suite, source code, and raw benchmarks are available here:
+👉 **[test_opencv_contrek](https://github.com/runout77/test_opencv_contrek)**
+
 ## Prerequisites
 
 For optimal performance and efficient memory management with large images (20k+), it is highly recommended to install **tcmalloc**.
@@ -57,7 +68,11 @@ For optimal performance and efficient memory management with large images (20k+)
 ```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).
 
 ## Install
 
@@ -167,7 +182,7 @@ Regarding multithreading:
 
 - 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.
 
-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 1.1 secs with image load).
+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.816 secs with image load (0.37 secs)).
 
 ```ruby
 result = Contrek.contour!(
@@ -232,9 +247,10 @@ Engineered for **Pixel-Perfect** precision.
 * **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) |
+| <img src="./docs/images/strict_bounds_on.png" alt="Originale" width="60%"/> | <img src="./docs/images/strict_bounds_off.png" alt="Poligoni" width="60%"/> |
 
 
 ## Result
@@ -411,6 +427,8 @@ This the one for the native C++
 
 About 130x faster. Times are in microseconds; system: AMD Ryzen 7 3700X 8-Core Processor (BogoMIPS: 7199,99) on Ubuntu distro.
 
+**Note:** Benchmarks were measured inside a VMware virtual machine.
+
 ## 🛠 C++ Standalone Library Usage
 
 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.

data/Rakefile

@@ -6,7 +6,7 @@ task :compile do |t|
     Dir.glob("**/*.o").each { |f| File.delete(f) }
     File.delete("Makefile") if File.exist?("Makefile")
     system "ruby", "extconf.rb"
-    system "make", "-B"
+    system "make", "-j#{`nproc`.strip}", "-B"
     Dir.glob("**/*.o").each { |f| File.delete(f) }
     system "cp cpp_polygon_finder.so ./../../lib"
   end

data/ext/cpp_polygon_finder/PolygonFinder/CMakeLists.txt

@@ -1,6 +1,5 @@
 cmake_minimum_required(VERSION 3.10)
 project(ContrekCore C CXX)
-
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_C_STANDARD 11)
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
@@ -22,28 +21,27 @@ else()
         message(WARNING "Contrek: tcmalloc not found; standard one will be used.")
     endif()
 endif()
-
 find_package(ZLIB REQUIRED)
-
+message(STATUS "Contrek: ZLIB path found at ${ZLIB_LIBRARIES}")
 file(GLOB_RECURSE CPP_SOURCES "*.cpp")
 file(GLOB_RECURSE C_SOURCES "*.c")
-
 list(FILTER CPP_SOURCES EXCLUDE REGEX "examples/.*\\.cpp")
-
 add_library(ContrekLib STATIC ${CPP_SOURCES} ${C_SOURCES})
-
 file(GLOB_RECURSE ALL_HEADERS "*.h")
 foreach(header_file ${ALL_HEADERS})
     get_filename_component(header_dir ${header_file} DIRECTORY)
     list(APPEND ALL_INCLUDE_DIRS ${header_dir})
 endforeach()
 list(REMOVE_DUPLICATES ALL_INCLUDE_DIRS)
-
-target_include_directories(ContrekLib PUBLIC ${ALL_INCLUDE_DIRS} ${ZLIB_INCLUDE_DIRS})
-target_link_libraries(ContrekLib PRIVATE ${ZLIB_LIBRARIES} pthread)
-
+target_include_directories(ContrekLib PUBLIC
+    ${ALL_INCLUDE_DIRS}
+    ${ZLIB_INCLUDE_DIRS}
+)
+target_link_libraries(ContrekLib PRIVATE
+    ${ZLIB_LIBRARIES}
+    pthread
+)
 option(BUILD_EXAMPLES "Build the example application" OFF)
-
 if(BUILD_EXAMPLES)
     if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/examples/example.cpp")
         message(STATUS "Contrek: Compiling example option ON")
@@ -56,4 +54,4 @@ if(BUILD_EXAMPLES)
     else()
         message(WARNING "Contrek: examples/example.cpp not found!")
     endif()
-endif()
+endif()

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

@@ -8,6 +8,7 @@
  */
 
 #include <iostream>
+#include <gperftools/malloc_extension.h>
 #include "ContrekApi.h"
 #include "Tests.h"
 
@@ -29,6 +30,11 @@ void run_test() {
 }
 
 int main() {
+  MallocExtension::instance()->SetNumericProperty(
+      "tcmalloc.max_total_thread_cache_bytes",
+      1024 * 1024 * 1024
+  );
+
   Contrek::Config cfg;
   cfg.threads = 4;
   cfg.tiles = 4;

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

@@ -98,7 +98,7 @@ void Tests::test_c()
   Point* p2 = new Point({2, 2});
   Point* p3 = new Point({3, 3});
 
-  Hub* hub = new Hub(4, 0, 3);
+  Hub* hub = new Hub(4);
 
   Position* pos1 = new Position(hub, p1);
   Position* pos2 = new Position(hub, p2);

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

@@ -17,6 +17,8 @@
 #include "Node.h"
 #include "NodeCluster.h"
 
+static const int TURNER[2][2] = {{Node::OMAX, Node::OMIN}, {Node::TURN_MAX, Node::TURN_MIN}};
+
 Node::Node(int min_x, int max_x, int y, NodeCluster* cluster, char name)
 : start_point(min_x, y),
   end_point(max_x, y),

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

@@ -14,8 +14,43 @@
 #include <limits>
 #include <algorithm>
 #include <map>
+#include <cstring>
+#include <cstddef>
 #include "List.h"
 
+struct SmallVec {
+  static constexpr int INLINE_CAP = 6;
+  int  buf[INLINE_CAP];
+  int* ptr = buf;
+  int  sz = 0, cap = INLINE_CAP;
+  int  front() const { return ptr[0]; }
+  int  back()  const { return ptr[sz - 1]; }
+  void push_back(int v) {
+      if (sz == cap) {
+          cap *= 2;
+          int* np = new int[cap];
+          std::memcpy(np, ptr, sz * sizeof(int));
+          if (ptr != buf) delete[] ptr;
+          ptr = np;
+      }
+      ptr[sz++] = v;
+  }
+  void reserve(int n) {
+      if (n <= cap) return;
+      int* np = new int[n];
+      std::memcpy(np, ptr, sz * sizeof(int));
+      if (ptr != buf) delete[] ptr;
+      ptr = np; cap = n;
+  }
+  void clear() { sz = 0; ptr = buf; cap = INLINE_CAP; }
+  int  size()  const { return sz; }
+  int& operator[](int i) { return ptr[i]; }
+  int  operator[](int i) const { return ptr[i]; }
+  int* begin() { return ptr; }
+  int* end()   { return ptr + sz; }
+  ~SmallVec() { if (ptr != buf) delete[] ptr; }
+};
+
 class NodeCluster;
 struct Point {
   int x;
@@ -42,7 +77,6 @@ class Node : public  Listable {
   static const int OCOMPLETE = OMIN | OMAX;
   static const int TURN_MAX = IMAX | OMAX;
   static const int TURN_MIN = IMIN | OMIN;
-  const int TURNER[2][2] = {{OMAX, OMIN}, {TURN_MAX, TURN_MIN}};
   static const int OUTER = 0;
   static const int INNER = 1;
 
@@ -60,7 +94,7 @@ class Node : public  Listable {
   Point start_point, end_point;
   NodeCluster* cluster;
   void add_intersection(Node& other_node, int other_node_index);
-  std::vector<int> tangs_sequence;
+  SmallVec tangs_sequence;
   Point* coords_entering_to(Node *enter_to, int mode, int tracking);
   Node* my_next_outer(Node *last, int versus);
   Node* my_next_inner(Node *last, int versus);

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

@@ -35,6 +35,7 @@ NodeCluster::NodeCluster(int h, int w, pf_Options *options) {
   this->root_nodes = this->lists.add_list();
   this->inner_plot = this->lists.add_list();
   this->inner_new = this->lists.add_list();
+  this->plot_sequence.reserve(1024);
 }
 
 NodeCluster::~NodeCluster() {
@@ -68,8 +69,8 @@ void NodeCluster::compress_coords(std::list<Polygon>& polygons, pf_Options optio
 }
 
 void NodeCluster::build_tangs_sequence() {
-  for (auto& line : vert_nodes) {
-    for (Node& node : line) {
+  for (int y = 0; y < (int)vert_nodes.size(); y++) {
+    for (Node& node : vert_nodes[y]) {
       node.precalc_tangs_sequences(*this);
     }
   }
@@ -94,8 +95,7 @@ Node* NodeCluster::add_node(int min_x, int max_x, int y, char name, int offset)
 
       while (it != up_nodes.end()) {
         if ((it->min_x - offset) > node.max_x) break;
-        int current_index = std::distance(up_nodes.begin(), it);
-        node.add_intersection(*it, current_index);
+        node.add_intersection(*it, it->abs_x_index);
         it->add_intersection(node, node.abs_x_index);
         ++it;
       }

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

@@ -20,7 +20,7 @@
 Cluster::Cluster(Finder *finder, int height, int start_x, int end_x)
   : finder(finder)
 { tiles_.reserve(2);  // only two (left|right)
-  this->hub_ = new Hub(height, start_x, end_x);
+  this->hub_ = new Hub(height);
 }
 
 Cluster::~Cluster() {

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

@@ -10,8 +10,8 @@
 #include "Hub.h"
 #include <cstring>
 
-Hub::Hub(int height, int start_x, int end_x)
-    : width_(end_x - start_x), height_(height), start_x_(start_x)
+Hub::Hub(int height)
+    : height_(height)
 { size_t total_pixels = static_cast<size_t>(height);
   payloads_.resize(total_pixels);
   bitset_.resize((total_pixels + 63) / 64, 0);

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

@@ -15,10 +15,8 @@
 class EndPoint;
 class Hub {
  public:
-  explicit Hub(int height, int start_x, int end_x);
+  explicit Hub(int height);
   int spawn_end_point();
-  const int width() const { return width_; }
-  const int start_x() const { return start_x_; }
   inline EndPoint* get(int key) {
     if (!is_set(key)) return nullptr;
     int index = payloads_[key];
@@ -34,9 +32,7 @@ class Hub {
   }
 
  private:
-  int width_;
   int height_;
-  int start_x_;
   std::vector<int> payloads_;
   std::vector<EndPoint> endpoint_pool_;
   Hub(const Hub&) = delete;

data/ext/cpp_polygon_finder/cpp_polygon_finder.cpp

@@ -6,6 +6,9 @@
  *      Copyright 2025 Emanuele Cesaroni
  */
 
+#ifdef HAVE_TCMALLOC
+#include <gperftools/malloc_extension.h>
+#endif
 #include <iostream>
 #include <list>
 #include <vector>
@@ -286,6 +289,13 @@ ProcessResult ruby_result_to_process_result(Rice::Object rb_result) {
 
 extern "C"
 void Init_cpp_polygon_finder() {
+  #ifdef HAVE_TCMALLOC
+  MallocExtension::instance()->SetNumericProperty(
+      "tcmalloc.max_total_thread_cache_bytes",
+      1024 * 1024 * 1024
+  );
+  #endif
+
   Data_Type<Bitmap> rb_cBitmap =
     define_class<Bitmap>("CPPBitMap")
     .define_constructor(Constructor<Bitmap, std::string, int>())

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

@@ -6,7 +6,7 @@ module Contrek
       def initialize(finder:, height:, start_x:, end_x:)
         @finder = finder
         @tiles = []
-        @hub = Hub.new(height:, start_x:, end_x:)
+        @hub = Hub.new(height: )
       end
 
       def add(tile)

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

@@ -2,7 +2,7 @@ module Contrek
   module Concurrent
     class Hub
       attr_reader :payloads
-      def initialize(height:, start_x:, end_x:)
+      def initialize(height:)
         # @payloads = Array.new(height)
         @payloads = {}
       end

data/lib/contrek/version.rb

@@ -1,3 +1,3 @@
 module Contrek
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Emanuele Cesaroni
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec