contrek 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d3c8751ab1e2182443227811912d1b0ad864dde99b62aae50c51b1265314bf3
-  data.tar.gz: d3a1ad93edd90e4ebb41a4e1371cd0ed5a2c134fbc093f898a920b8e81e8c249
+  metadata.gz: eada79f09d6eede09420a2f933496d8839152f741d9c90e7d6b63fc7537bec29
+  data.tar.gz: 5652df8b513dfb26db08a1640cf59e2642a0feba7df2f9ce62eec0fe4e6dc445
 SHA512:
-  metadata.gz: e423133c5e9dfe2f490c84e2c47bdd585d9771949ccf8dbd1afd21b254dea876c7bc18f5cd1e71e327d50cec3de2a7abe5bcb39029f578ab043b43c9a785b607
-  data.tar.gz: 3b343824bbe74a380e6e3f084d628c00a7b3efeac373cf65a80b50de66827d5c62b44a4e33ed248b3144336a35c7712e96681b8f754e1dbcee280680b3caf9ab
+  metadata.gz: 8dc280b616db1de56688ca94f5c1bcef1bf02cb81ff820638ebdf0bed821ba37745799a579a2660da6dc0934afa46a94aae51affdcb3b6fd987710a84f5f85d9
+  data.tar.gz: c815702b9abafa8b5e6de4e1f2e05ab6b03ed91248efe0786807307db6ebff19a7e2c9d002fadf94a12e2c9f41a8c07fe0ca05c01f5a838722090a737c888983

data/CHANGELOG.md

@@ -149,7 +149,10 @@ All notable changes to this project will be documented in this file.
 - Fixed issue found on treemap determination.
 
 ## [1.3.9] - 2026-08-09
-- Removed the curses development dependency along with the old TerminalTracker; actually Bitmaps::Rendering.to_window renders visually better results.
+- Removed the curses development dependency along with the old TerminalTracker; actually Contrek::Bitmaps::PngBitmap.to_window renders visually better results.
 
 ## [1.4.0] - 2026-08-13
 - Added deterministic merge mode usefull when you need a byte-for-byte reproducible outputs across different runs (by default, the merge stage is non-deterministic to maximize performance and thread utilization).
+
+## [1.4.1] - 2026-08-23
+- The number_of_threads effective value is now returned inside metadata output struct too.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contrek (1.4.0)
+    contrek (1.4.1)
       chunky_png (~> 1.4)
       concurrent-ruby (~> 1.3.5)
       rice (= 4.5.0)

data/PERFORMANCE.md

@@ -1,4 +1,4 @@
-# ⚡ Contrek Performance Tuning
+# Contrek Performance Tuning
 
 This document describes optional dependencies and configuration tips to get the best performance out of Contrek on large images.
 
@@ -41,7 +41,7 @@ sudo make install
 sudo ldconfig
 ```
 
-> ⚠️ The `-DZLIB_COMPAT=ON` flag is mandatory. Without it, zlib-ng uses a different ABI and CMake's `find_package(ZLIB)` won't detect it.
+> The `-DZLIB_COMPAT=ON` flag is mandatory. Without it, zlib-ng uses a different ABI and CMake's `find_package(ZLIB)` won't detect it.
 
 **macOS:**
 ```bash
@@ -136,9 +136,45 @@ Consider this depends your system. Probably is better not to saturate all cores
 
 ---
 
-## 4. Combining All Optimizations
+## 4. Transparent Huge Pages (THP) — Kernel Memory Allocation
 
-Install zlib-ng and tcmalloc, then configure:
+When processing high-resolution images, Contrek performs dense dynamic memory allocations. By default, Linux manages memory in standard 4 KiB pages, which creates heavy kernel overhead from frequent page faults and Translation Lookaside Buffer (TLB) misses under multithreaded loads.
+
+Enabling **Transparent Huge Pages (`always`)** forces the Linux kernel to allocate memory in **2 MiB blocks**, reducing page table lookup entries by a factor of 512 and dramatically speeding up memory access.
+
+### Temporary Activation
+
+To enable it immediately for your current Linux session:
+
+```bash
+echo always | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
+```
+
+### Permanent Activation
+To ensure this setting persists across system reboots:
+
+Open /etc/default/grub in an editor:
+
+```bash
+sudo nano /etc/default/grub
+```
+Add transparent_hugepage=always to GRUB_CMDLINE_LINUX_DEFAULT:
+
+```Plaintext
+GRUB_CMDLINE_LINUX_DEFAULT="quiet splash transparent_hugepage=always"
+```
+
+Update GRUB:
+
+```bash
+sudo update-grub
+```
+
+---
+
+## 5. Combining All Optimizations
+
+Install zlib-ng and tcmalloc, enable THP, then configure:
 
 ```ruby
 # Ruby

data/README.md

@@ -166,7 +166,8 @@ Metadata includes timing information (expressed in milliseconds), the number of
   },
   :groups=>2,
   :named_sequence=>"",
-  :treemap=>[]
+  :treemap=>[],
+  :number_of_threads=>0
 }
 ```
 
@@ -600,7 +601,8 @@ Typical information includes
   benchmarks:{...},
   groups:1,
   treemap:[],
-  options:{...}
+  options:{...},
+  number_of_threads: 4
 }
 ```
 
@@ -717,27 +719,6 @@ Instead, it repeatedly combines smaller topologically consistent pieces into a l
 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:
-
-```
-(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.

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

@@ -21,6 +21,11 @@
 
 namespace Contrek {
 
+enum class Versus {
+  A,  // Anticlockwise
+  O   // Clockwise
+};
+
 enum class MatchMode {
   NOT_COLOR,    // Tracks border of what is not target color
   EXACT_COLOR   // Tracks border of what exactly matchs target color
@@ -31,15 +36,22 @@ enum class Connectivity {
   OMNIDIRECTIONAL = 8    // 8 directions
 };
 
+
 struct Config {
   int threads = 4;
   int tiles = 2;
+  Versus versus = Versus::A;
   bool compress_unique = false;
   bool compress_linear = false;
   bool compress_raster = false;
   bool compress_douglas_peucker = false;
   bool compress_visvalingam = false;
+  float compress_visvalingam_tolerance = 0.0f;
   bool treemap = false;
+  bool bounds = false;
+  bool named_sequences = false;
+  bool unsafe_mode = false;
+  bool deterministic = false;
   int32_t target_color = -1;
   MatchMode mode = MatchMode::NOT_COLOR;
   Connectivity connectivity_mode = Connectivity::ORTHOGONAL;
@@ -81,19 +93,33 @@ inline TraceContext trace(const std::string& image_path, const Config& cfg = Con
     ctx.matcher = std::make_unique<RGBMatcher>(color_to_match);
   }
 
+  std::string versus_str = (cfg.versus == Versus::O) ? "o" : "a";
   ctx.internal_args = {
-    {"versus", Identifier{"a"}},
+    {"versus", Identifier{versus_str}},
+    {"number_of_tiles", static_cast<int64_t>(cfg.tiles)},
+    {"treemap", cfg.treemap},
+    {"bounds", cfg.bounds},
+    {"named_sequences", cfg.named_sequences},
+    {"unsafe_mode", cfg.unsafe_mode},
+    {"deterministic", cfg.deterministic}
   };
-  Options compression_opts;
-
-  if (cfg.compress_unique) compression_opts["uniq"] = true;
-  if (cfg.compress_linear) compression_opts["linear"] = true;
-  if (cfg.compress_visvalingam) compression_opts["visvalingam"] = true;
-  if (cfg.compress_unique || cfg.compress_linear || cfg.compress_visvalingam) ctx.internal_args["compression"] = compression_opts;
-  ctx.internal_args["number_of_tiles"] = cfg.tiles;
   if (cfg.connectivity_mode == Connectivity::OMNIDIRECTIONAL) {
-    ctx.internal_args["connectivity"] = 8;
+    ctx.internal_args["connectivity"] = static_cast<int64_t>(8);
   }
+  Options compress_opts;
+  if (cfg.compress_unique) compress_opts["uniq"] = true;
+  if (cfg.compress_linear) compress_opts["linear"] = true;
+  if (cfg.compress_raster) compress_opts["raster"] = true;
+  if (cfg.compress_douglas_peucker) compress_opts["douglas_peucker"] = true;
+  if (cfg.compress_visvalingam) compress_opts["visvalingam"] = true;
+  if (cfg.compress_visvalingam_tolerance > 0.0f) {
+    compress_opts["visvalingam_tolerance"] = static_cast<double>(cfg.compress_visvalingam_tolerance);
+  }
+  if (cfg.compress_unique || cfg.compress_linear || cfg.compress_raster ||
+      cfg.compress_douglas_peucker || cfg.compress_visvalingam) {
+    ctx.internal_args["compress"] = compress_opts;
+  }
+
   ctx.finder = std::make_unique<Finder>(cfg.threads, ctx.bitmap.get(), ctx.matcher.get(), ctx.internal_args);
   ctx.result = std::unique_ptr<ProcessResult>(ctx.finder->process_info());
 

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

@@ -110,6 +110,7 @@ ProcessResult* PolygonFinder::process_info() {
   pr->has_bounds = this->node_cluster->options->bounds;
   pr->versus = this->options.versus;
   pr->options = this->incoming_options_;
+  pr->number_of_threads = 0;
 
   if (this->node_cluster->options->named_sequences && typeid(*this->source_bitmap) == typeid(Bitmap))
   { std::string sequence;

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

@@ -69,6 +69,7 @@ struct ProcessResult {
   int groups;
   int width, height;
   int versus;
+  int number_of_threads;
   bool has_bounds = false;
   std::map<std::string, double> benchmarks;
   std::list<Polygon> polygons;

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

@@ -166,6 +166,7 @@ ProcessResult* Finder::process_info() {
   pr->has_bounds = this->options_.bounds;
   pr->versus = this->options_.versus;
   pr->options = this->input_options;
+  pr->number_of_threads = this->number_of_threads();
   FakeCluster fake_cluster(pr->polygons, this->options_);
   cpu_timer.start();
   fake_cluster.compress_coords(pr->polygons, this->options_);

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

@@ -38,6 +38,7 @@ class Poolable {
     }
   }
   void wait();
+  int number_of_threads() const { return number_of_threads_; }
 
  private:
   std::vector<std::thread> workers;

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

@@ -24,10 +24,10 @@ Tile::Tile(Finder *finder, int start_x, int end_x, std::string name, int index,
 : finder(finder),
   start_x_(start_x),
   end_x_(end_x),
-  name_(name),
   index_(index),
-  benchmarks(b),
-  order_(order) {
+  order_(order),
+  name_(name),
+  benchmarks(b) {
   this->shapes_pool = new ShapePool();
   this->shapes_pool->set_owner(this);
   this->shapes_pools.push_back(this->shapes_pool);

data/ext/cpp_polygon_finder/cpp_polygon_finder.cpp

@@ -232,6 +232,7 @@ class To_Ruby<ProcessResult*>
     return_me[Symbol("height")] = pr->height;
     return_me[Symbol("versus")] = Symbol(pr->versus == Node::O ? "o" : "a");
     return_me[Symbol("options")] = options_to_ruby(pr->options);
+    return_me[Symbol("number_of_threads")] = pr->number_of_threads;
 
     Rice::Array out;
     for (Polygon& x : pr->polygons)

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

@@ -95,7 +95,8 @@ module Contrek
           width: @maximum_width,
           height: @height,
           versus: options[:versus],
-          options: options
+          options: options,
+          number_of_threads: @number_of_threads
         }
         metadata[:treemap] = @whole_tile.compute_treemap if options[:treemap]
         Contrek::Finder::Result.new(raw_polygons, metadata)

data/lib/contrek/finder/polygon_finder.rb

@@ -54,7 +54,8 @@ module Contrek
           height: @source_bitmap.h,
           treemap: (@node_cluster.treemap if @options.has_key?(:treemap)),
           options: @ori_options,
-          versus: @options[:versus]
+          versus: @options[:versus],
+          number_of_threads: 0
         }
         Result.new(@node_cluster.polygons, metadata)
       end

data/lib/contrek/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Emanuele Cesaroni