contrek 1.2.7 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae46fa52ddce3383ef534142814ed28ddc5cae45042e677c8f445140bee67e82
-  data.tar.gz: 57cbaf53a0d6e8c7d31bdfcef0718c94654ceaf0fd7b2be84325751dc29f6224
+  metadata.gz: 8f506a5908c11f7ac1de118b4772ad9e85cd00746e4ee57b5d9c1600faea371e
+  data.tar.gz: 81c2807712361d51398962c9496bf3c833b21eb42d34907069c923cd62654f62
 SHA512:
-  metadata.gz: ee922b6b787ac0f91b98a2e7d608c351499ea5405e325a0eb6d23f751a29075b390c08d757824132c7fbef7d64cef9f3af7dbb11709506e84777ff652f9f15fc
-  data.tar.gz: 848102a6980857b1f4d3914e60de04408d0f7a4cc4c950a20b3fa8ef7231e31db029220eb6e3fb71847b6986a09c0d7b1fedae70f8e30e8ef758a3adeabeddcd
+  metadata.gz: 76c41016ce95c124ed72beacd5c838bf5fe960483e3cf7b78848d53c3d997948f5de0c8ecacdb08d3c38b8faf7349ec79cef9546415773e5d5201019b04fe3b2
+  data.tar.gz: 1823196730b740221b2e75be9915706b5b96afd91349dd898eda70d1ccce69f569270e134663137523ea3860e5d49a419b59a083a6a11be027bf4e14a1a0e30b

data/.gitignore

@@ -3,6 +3,7 @@
 .ruby-version
 # rspec failure tracking
 .rspec_status
+/spec/files/performance_history.json
 
 /ext/cpp_polygon_finder/PolygonFinder/build/
 /ext/cpp_polygon_finder/PolygonFinder/contrek
@@ -12,4 +13,4 @@
 /ext/cpp_polygon_finder/cpp_polygon_finder.o
 /ext/cpp_polygon_finder/cpp_polygon_finder.so
 /ext/cpp_polygon_finder/mkmf.log
-/lib/cpp_polygon_finder.so
+/lib/cpp_polygon_finder.so

data/.rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  DisabledByDefault: true
+  TargetRubyVersion: 3.1
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+
+# Attiva l'obbligo del magic comment
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always

data/CHANGELOG.md

@@ -115,4 +115,10 @@ All notable changes to this project will be documented in this file.
 
 ## [1.2.7] - 2026-06-02
 ### Changed
-- **Refactored `bounds` option:** Starting from this release, precalculated bounds for each polygon can now be requested in concurrent mode as well, in addition to single-threaded mode.
+- **Refactored `bounds` option:** Starting from this release, precalculated bounds for each polygon can now be requested in concurrent mode as well, in addition to single-threaded mode.
+
+## [1.2.8] - 2026-06-07
+- **Optimize main pixel scanning loop:** Implemented 4-way loop unrolling to maximize L1 cache hits and eliminate redundant RAM lookups via direct register bit-casting.
+
+## [1.2.9] - 2026-06-13
+- **Streaming merger:** The streaming merger class extends VerticalMerger and adds a useful feature: the progressive extraction of contours into a disk buffer (SVG file). In this way, all extracted polygons that are no longer within the junction zone of the next stripe are removed from the system and streamed directly to disk. This incredibly reduces memory consumption, allowing the processing of very large files on machines with low memory availability, at the expense of increased processing times. An example of this technique is available in both C++ and Ruby in the repository.

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gemspec

data/Gemfile.lock

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

data/README.md

@@ -1,5 +1,5 @@
 # Contrek
-Contrek is a Ruby gem powered by a <u>standalone C++17 core library</u> for fast contour tracing and edge detection in PNG images and raw memory streams. It employs a **topological approach** to extract polygonal contours, representing shapes as a connected graph of shared endpoints. This ensures perfect adjacency and structural integrity for shape analysis and raster-to-vector workflows, such as PNG to SVG conversion, managed via libspng (0.7.4) with multithreading support.
+Contrek is a Ruby gem powered by a <u>[standalone C++17 core library](#-c-standalone-library-usage)</u> for fast contour tracing and edge detection in PNG images and raw memory streams. It employs a **topological approach** to extract polygonal contours, representing shapes as a connected graph of shared endpoints. This ensures perfect adjacency and structural integrity for shape analysis and raster-to-vector workflows, such as PNG to SVG conversion, managed via libspng (0.7.4) with multithreading support.
 
 
 ## About Contrek library

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rake"
 
 desc "compiles c++ extension"

data/contrek.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "contrek/version"

data/ext/cpp_polygon_finder/PolygonFinder/CMakeLists.txt

@@ -11,8 +11,8 @@ if(CMAKE_BUILD_TYPE STREQUAL "Debug")
     list(FILTER CMAKE_CXX_FLAGS EXCLUDE REGEX "-DNDEBUG")
     list(FILTER CMAKE_C_FLAGS EXCLUDE REGEX "-DNDEBUG")
 else()
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -pthread -march=native -DNDEBUG -Ofast -flto")
-    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -march=native -fPIC -DNDEBUG")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -pthread -march=native -fPIC -DNDEBUG -Ofast -flto -ftree-vectorize")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -pthread -march=native -fPIC -DNDEBUG -Ofast -flto -ftree-vectorize")
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -pthread -flto=auto -Wl,--no-as-needed")
     find_library(TCMALLOC_LIB tcmalloc)
     if(TCMALLOC_LIB)

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

@@ -34,6 +34,7 @@
 #include "polygon/finder/concurrent/Finder.h"
 #include "polygon/finder/concurrent/HorizontalMerger.h"
 #include "polygon/finder/concurrent/VerticalMerger.h"
+#include "polygon/finder/concurrent/StreamingMerger.h"
 #include "polygon/finder/concurrent/Sequence.h"
 #include "polygon/finder/concurrent/Position.h"
 #include "polygon/finder/Polygon.h"
@@ -385,6 +386,112 @@ void stream_png_image(const std::string& filepath, uint32_t stripe_height, bool
 }
 
 void Tests::test_i() {
-  stream_png_image("../images/graphs_1024x1024.png", 300);
+  stream_png_image("../images/graphs_1024x1024.png", 300, true);
+  std::cout << "Memory usage peak: " << get_peak_rss() << " MB" << std::endl;
+}
+
+void stream_progressive_png_image(const std::string& filepath, uint32_t stripe_height) {
+    std::vector<ProcessResult*> result_clones;
+    std::vector<std::string> varguments = {"--bounds"};
+    // 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;
+    }
+
+    // allocates streaming svg buffer
+    std::string output_path = "streaming_buffer.svg";
+    std::ofstream shared_stream(output_path, std::ios::out | std::ios::binary);
+    if (!shared_stream) {
+      std::cerr << "Error: Unable creating output streaming file!" << std::endl;
+    }
+
+    StreamingMerger vmerger(0, &varguments, &shared_stream, total_width, total_height);
+    try {
+      size_t row_size = static_cast<size_t>(total_width) * 4;
+      int stripe_count = 0;
+      // main stripes 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",
+          "--bounds",
+          "--strict_bounds",  // <- this option is strictly needed when working with vertical merger
+          "--compress_uniq",
+          "--compress_linear"
+        };
+
+        PolygonFinder polygon_finder(&stripe_bitmap, &not_matcher, nullptr, &finder_arguments);
+        ProcessResult *result = polygon_finder.process_info();
+        if (result) {
+          std::cout << "stripe " << stripe_count << ": found polygons " << result->groups << std::endl;
+          ProcessResult* safe_result = result->clone();
+          result_clones.push_back(safe_result);
+          vmerger.add_tile(*safe_result, !(current_y_offset + stripe_height < total_height));
+          delete result;
+        }
+        stripe_count++;
+      }
+
+      ProcessResult *merged_result = vmerger.process_info();
+      std::cout << "total found polygons " << merged_result->groups << std::endl;
+      delete merged_result;
+
+      // frees memory
+      for (auto c : result_clones) {
+        delete c;
+      }
+    } catch (const std::exception& e) {
+      std::cerr << "\n[ERROR] Processing exception: " << e.what() << std::endl;
+      if (shared_stream.is_open()) shared_stream.close();
+    }
+    spng_ctx_free(ctx);
+    fclose(fp);
+}
+
+void Tests::test_l() {
+  stream_progressive_png_image("../images/mixed_shapes_1024x1024.png", 300);
   std::cout << "Memory usage peak: " << get_peak_rss() << " MB" << std::endl;
 }

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

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

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

@@ -20,6 +20,8 @@
 #include <sstream>
 #include <stdexcept>
 #include <limits>
+#include <cstdint>
+
 #include "../bitmaps/Bitmap.h"
 #include "NodeCluster.h"
 #include "Node.h"
@@ -210,15 +212,80 @@ class PolygonFinder {
   void run_loop(M* specific_matcher, F&& fetch_color, int offset) {
     int img_h = this->source_bitmap->h();
     int bpp = this->source_bitmap->get_bytes_per_pixel();
+
     for (int y = 0; y < img_h; y++) {
       const unsigned char* row_ptr = this->source_bitmap->get_row_ptr(y);
       const unsigned char* p = row_ptr + (this->start_x * bpp);
+
       int min_x = 0;
       bool matching = false;
       unsigned char last_red_value = 0;
-      for (int x = this->start_x; x < this->end_x; x++) {
+
+      int x = this->start_x;
+
+      if (bpp == 4) {
+        for (; x <= this->end_x - 4; x += 4) {
+          // read 4 pixels (16 bytes)
+          unsigned int c0 = fetch_color(p);
+          unsigned int c1 = fetch_color(p + 4);
+          unsigned int c2 = fetch_color(p + 8);
+          unsigned int c3 = fetch_color(p + 12);
+
+          // extracts value (used as debugging segment label)
+          unsigned char v0 = static_cast<unsigned char>(c0);
+          unsigned char v1 = static_cast<unsigned char>(c1);
+          unsigned char v2 = static_cast<unsigned char>(c2);
+          unsigned char v3 = static_cast<unsigned char>(c3);
+
+          p += 16;
+
+          bool m0 = specific_matcher->match(c0);
+          bool m1 = specific_matcher->match(c1);
+          bool m2 = specific_matcher->match(c2);
+          bool m3 = specific_matcher->match(c3);
+
+          if (m0) {
+            if (!matching) {
+              min_x = x; last_red_value = v0; matching = true;
+            }
+          } else if (matching) {
+            this->node_cluster->add_node(min_x, x - 1, y, last_red_value, offset);
+            matching = false;
+          }
+
+          if (m1) {
+            if (!matching) {
+              min_x = x + 1; last_red_value = v1; matching = true;
+            }
+          } else if (matching) {
+            this->node_cluster->add_node(min_x, x, y, last_red_value, offset);
+            matching = false;
+          }
+
+          if (m2) {
+            if (!matching) {
+              min_x = x + 2; last_red_value = v2; matching = true;
+            }
+          } else if (matching) {
+            this->node_cluster->add_node(min_x, x + 1, y, last_red_value, offset);
+            matching = false;
+          }
+
+          if (m3) {
+            if (!matching) {
+              min_x = x + 3; last_red_value = v3; matching = true;
+            }
+          } else if (matching) {
+            this->node_cluster->add_node(min_x, x + 2, y, last_red_value, offset);
+            matching = false;
+          }
+        }
+      }
+
+      // remaining pixels (width not a multiple of 4)
+      for (; x < this->end_x; x++) {
         unsigned int color = fetch_color(p);
-        unsigned char current_val = p[0];
+        unsigned char current_val = static_cast<unsigned char>(color);
         p += bpp;
         if (specific_matcher->match(color)) {
           if (!matching) {
@@ -226,15 +293,15 @@ class PolygonFinder {
             last_red_value = current_val;
             matching = true;
           }
-          if (x == this->end_x - 1) {
-            this->node_cluster->add_node(min_x, x, y, last_red_value, offset);
-            matching = false;
-          }
         } else if (matching) {
           this->node_cluster->add_node(min_x, x - 1, y, last_red_value, offset);
           matching = false;
         }
       }
+
+      if (matching) {
+        this->node_cluster->add_node(min_x, this->end_x - 1, y, last_red_value, offset);
+      }
     }
   }
 

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

@@ -35,7 +35,6 @@ class Finder : public Poolable {
   Matcher *matcher;
   pf_Options options_;
   std::vector<std::string> input_options;
-  Tile* whole_tile = nullptr;
   std::queue<ClippedPolygonFinder*> finders;
   std::mutex finders_mutex;
   std::map<std::string, double> reports;
@@ -45,6 +44,7 @@ class Finder : public Poolable {
   Queue<Tile*> tiles_;
   int maximum_width_;
   int height = 0;
+  Tile* whole_tile = nullptr;
   void process_tiles();
 
  public:

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

@@ -21,7 +21,7 @@ Polyline::Polyline(Tile* tile, const std::vector<Point*>& polygon, const std::op
   tile(tile)
 { if (bounds.has_value()) {
     min_x =  bounds->min_x;
-    max_x = bounds->max_x;
+    max_x_ = bounds->max_x;
     min_y_ =  bounds->min_y;
     max_y_ = bounds->max_y;
   } else {
@@ -32,17 +32,17 @@ Polyline::Polyline(Tile* tile, const std::vector<Point*>& polygon, const std::op
 
 int Polyline::width() {
   if (raw_.empty()) return 0;
-  return(max_x - min_x);
+  return(max_x_ - min_x);
 }
 
 bool Polyline::boundary() {
-  return( tile->tg_border(Point{min_x, 0}) || tile->tg_border(Point{max_x, 0}));
+  return( tile->tg_border(Point{min_x, 0}) || tile->tg_border(Point{max_x_, 0}));
 }
 
 void Polyline::find_boundary() {
   if (raw_.empty()) return;
   min_x =  std::numeric_limits<int>::max();
-  max_x = -std::numeric_limits<int>::max();
+  max_x_ = -std::numeric_limits<int>::max();
   min_y_ =  std::numeric_limits<int>::max();
   max_y_ = -std::numeric_limits<int>::max();
   for (Point* p : raw_) {
@@ -50,7 +50,7 @@ void Polyline::find_boundary() {
     int x = p->x;
     int y = p->y;
     if (x < min_x) min_x = x;
-    if (x > max_x) max_x = x;
+    if (x > max_x_) max_x_ = x;
     if (y < min_y_) min_y_ = y;
     if (y > max_y_) max_y_ = y;
   }
@@ -98,7 +98,7 @@ std::string Polyline::named() {
 
 void Polyline::fill_bounds(RectBounds& target_bounds) const {
   target_bounds.min_x = this->min_x;
-  target_bounds.max_x = this->max_x;
+  target_bounds.max_x = this->max_x_;
   target_bounds.min_y = this->min_y_;
   target_bounds.max_y = this->max_y_;
 }

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

@@ -40,10 +40,11 @@ class Polyline : public Partitionable {
   int width();
   Tile *tile = nullptr;
   Shape* shape = nullptr;
-  std::vector<Point*> raw() const { return raw_; }
+  const std::vector<Point*>& raw() const { return raw_; }
   const std::vector<Part*>& parts() const { return parts_; }
   const int max_y() const { return max_y_; }
   const int min_y() const { return min_y_; }
+  const int max_x() const { return max_x_; }
   void clear();
   bool is_empty();
   bool any_ancients = false;
@@ -56,7 +57,7 @@ class Polyline : public Partitionable {
 
  private:
   std::vector<Point*> raw_;
-  int min_x, max_x, min_y_, max_y_;
+  int min_x, max_x_, min_y_, max_y_;
   void find_boundary();
   uint32_t flags_ = 0;
   std::string named_;

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

@@ -0,0 +1,114 @@
+/*
+ * StreamingMerger.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 "StreamingMerger.h"
+#include <sstream>
+#include <algorithm>
+#include <vector>
+#include <string>
+
+StreamingMerger::StreamingMerger(int number_of_threads,
+                                 std::vector<std::string>* options,
+                                 std::ofstream* stream_to,
+                                 int total_width, int total_height)
+  : VerticalMerger(number_of_threads, options), stream(stream_to), total_width(total_width), total_height(total_height) {
+  if (!stream) {
+    throw std::invalid_argument("Streaming requires a valid destination output. stream_to cannot be null.");
+  }
+  if (total_width <= 0 || total_height <= 0) {
+    throw std::invalid_argument("Streaming requires valid canvas dimensions (width and height must be > 0).");
+  }
+}
+
+void StreamingMerger::add_tile(ProcessResult& result, bool flush)
+{ VerticalMerger::add_tile(result);
+  if (tiles_.size() == 2) {
+    this->process_tiles();
+    this->tiles_.queue_push(this->whole_tile);
+    this->stream_polygons(this->whole_tile, flush);
+  }
+}
+
+ProcessResult* StreamingMerger::process_info() {
+  ProcessResult *pr = VerticalMerger::process_info();
+  pr->groups =  this->moved;
+  return(pr);
+}
+
+void StreamingMerger::stream_polygons(Tile* tile, bool flush) {
+  ensure_header();
+  if (int tile_end_x = tile->end_x(); true) {
+    tile->shapes().erase(
+      std::remove_if(tile->shapes().begin(), tile->shapes().end(), [this, flush, tile_end_x](const Shape* shape) {
+        if (flush || shape->outer_polyline->max_x() < (tile_end_x - 1)) {
+          this->moved++;
+          this->stream_raw_polygon(shape);
+          return true;
+        }
+        return false;
+      }),
+      tile->shapes().end());
+  }
+  if (flush) {
+    ensure_footer();
+  }
+}
+
+void StreamingMerger::stream_raw_polygon(const Shape* shape) {
+  std::ostringstream outer_oss;
+  const std::vector<Point*> points = shape->outer_polyline->raw();
+  for (size_t i = 0; i < points.size(); ++i) {
+    outer_oss << points[i]->y << "," << points[i]->x;
+    if (i < points.size() - 1) outer_oss << " ";
+  }
+  *stream << svg_outer_polygon_string(outer_oss.str());
+
+  for (const auto& inner_polyline : shape->inner_polylines) {
+    std::ostringstream inner_oss;
+    const std::vector<Point*> inner_points = inner_polyline->raw();
+    for (size_t i = 0; i < inner_points.size(); ++i) {
+      inner_oss << inner_points[i]->y << "," << inner_points[i]->x;
+      if (i < inner_points.size() - 1) inner_oss << " ";
+    }
+    *stream << svg_inner_polygon_string(inner_oss.str());
+  }
+}
+
+void StreamingMerger::ensure_header() {
+  if (stream && stream->tellp() == 0) {
+    *stream << svg_header_string();
+  }
+}
+
+void StreamingMerger::ensure_footer() {
+  if (stream) {
+    *stream << svg_footer_string();
+  }
+}
+
+std::string StreamingMerger::svg_css() {
+  return ".out{fill:none;stroke:red;stroke-width:1;}.in{fill:none;stroke:green;stroke-width:1;}.out:hover{stroke:yellow;}";
+}
+
+std::string StreamingMerger::svg_header_string() {
+  return "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"" + std::to_string(total_width) +
+         "\" height=\"" + std::to_string(total_height) + "\"><style>" + svg_css() + "</style>";
+}
+
+std::string StreamingMerger::svg_footer_string() {
+  return "</svg>";
+}
+
+std::string StreamingMerger::svg_outer_polygon_string(std::string_view points) {
+  return "<polygon points=\"" + std::string(points) + "\" class=\"out\"/>";
+}
+
+std::string StreamingMerger::svg_inner_polygon_string(std::string_view points) {
+  return "<polygon points=\"" + std::string(points) + "\" class=\"in\"/>";
+}

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

@@ -0,0 +1,41 @@
+/*
+ * StreamingMerger.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 "VerticalMerger.h"
+#include <fstream>
+#include <string>
+#include <string_view>
+#include <stdexcept>
+#include <vector>
+
+class StreamingMerger : public VerticalMerger {
+ private:
+  std::ofstream* stream;
+  int total_width;
+  int total_height;
+  int moved = 0;
+  void ensure_header();
+  void ensure_footer();
+  void stream_polygons(Tile* tile, bool flush = false);
+  void stream_raw_polygon(const Shape* shape);
+  virtual std::string svg_css();
+  virtual std::string svg_header_string();
+  virtual std::string svg_footer_string();
+  virtual std::string svg_outer_polygon_string(std::string_view points);
+  virtual std::string svg_inner_polygon_string(std::string_view points);
+
+ public:
+  StreamingMerger(int number_of_threads,
+                  std::vector<std::string>* options,
+                  std::ofstream* stream_to,
+                  int total_width, int total_height);
+  void add_tile(ProcessResult& result, bool flush = false);
+  ProcessResult* process_info() override;
+};

data/ext/cpp_polygon_finder/cpp_polygon_finder.cpp

@@ -96,6 +96,8 @@
 #include "PolygonFinder/src/polygon/finder/concurrent/HorizontalMerger.cpp"
 #include "PolygonFinder/src/polygon/finder/concurrent/VerticalMerger.h"
 #include "PolygonFinder/src/polygon/finder/concurrent/VerticalMerger.cpp"
+#include "PolygonFinder/src/polygon/finder/concurrent/StreamingMerger.h"
+#include "PolygonFinder/src/polygon/finder/concurrent/StreamingMerger.cpp"
 #include "PolygonFinder/src/polygon/finder/concurrent/ShapePool.h"
 #include "PolygonFinder/src/polygon/finder/concurrent/ShapePool.cpp"
 extern "C" {
@@ -290,6 +292,36 @@ ProcessResult ruby_result_to_process_result(Rice::Object rb_result) {
 
 }  // namespace Rice::detail
 
+struct OfstreamWrapper {
+  std::string path;
+  std::ofstream stream;
+  OfstreamWrapper(std::string p) : path(p), stream(p, std::ios::out) {}
+  void close() { stream.close(); }
+  bool closed() { return !stream.is_open(); }
+  void rewind() { /* noop */ }
+  std::string read() {
+    stream.flush();
+    std::ifstream in(path);
+    return std::string((std::istreambuf_iterator<char>(in)),
+                        std::istreambuf_iterator<char>());
+  }
+  std::ofstream& get_stream() { return stream; }
+};
+
+StreamingMerger* create_streaming_merger(Object self,
+                                         int number_of_threads,
+                                         std::vector<std::string>* options,
+                                         Object stream_obj,
+                                         int total_width,
+                                         int total_height) {
+  OfstreamWrapper* wrapper = Rice::detail::From_Ruby<OfstreamWrapper*>().convert(stream_obj.value());
+  return new StreamingMerger(number_of_threads, options, &wrapper->get_stream(), total_width, total_height);
+}
+
+OfstreamWrapper* create_ofstream(Object self, std::string path) {
+  return new OfstreamWrapper(path);
+}
+
 extern "C"
 void Init_cpp_polygon_finder() {
   #ifdef HAVE_TCMALLOC
@@ -384,9 +416,27 @@ void Init_cpp_polygon_finder() {
     define_class<HorizontalMerger, Merger>("CPPHorizontalMerger")
     .define_constructor(Constructor<HorizontalMerger, int, std::vector<std::string>*>(), Arg("number_of_threads"), Arg("options") = nullptr, Arg("yield_gvl") = true);
 
-    Data_Type<VerticalMerger> rb_cVerticalMerger =
+  Data_Type<VerticalMerger> rb_cVerticalMerger =
     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);
+    .define_constructor(Constructor<VerticalMerger, int, std::vector<std::string>*>(), Arg("number_of_threads"), Arg("options") = nullptr, Arg("yield_gvl") = true)
+    .define_method("add_tile", [](VerticalMerger& self, Object rb_result) {
+      ProcessResult pr = Rice::detail::ruby_result_to_process_result(rb_result);
+      self.add_tile(pr);
+        });
+
+  Data_Type<OfstreamWrapper> rb_cstd_ofstream = define_class<OfstreamWrapper>("CPPOfstream");
+    rb_cstd_ofstream.define_singleton_method("new", &create_ofstream);
+    rb_cstd_ofstream.define_method("close",   [](OfstreamWrapper& self) { self.close(); });
+    rb_cstd_ofstream.define_method("closed?", [](OfstreamWrapper& self) { return self.closed(); });
+    rb_cstd_ofstream.define_method("rewind",  [](OfstreamWrapper& self) { self.rewind(); });
+    rb_cstd_ofstream.define_method("read",    [](OfstreamWrapper& self) { return self.read(); });
+
+  Data_Type<StreamingMerger> rb_cstreaming_merger = define_class<StreamingMerger, VerticalMerger>("CPPStreamingMerger");
+    rb_cstreaming_merger.define_method("add_tile", [](StreamingMerger& self, Object rb_result, bool flush) {
+      ProcessResult pr = Rice::detail::ruby_result_to_process_result(rb_result);
+      self.add_tile(pr, flush);
+    });
+    rb_cstreaming_merger.define_singleton_method("new", &create_streaming_merger);
 
   Module mContrek = define_module("Contrek");
   Module mCpp = define_module_under(mContrek, "Cpp");

data/ext/cpp_polygon_finder/extconf.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "mkmf-rice"
 
 has_tcmalloc = find_library("tcmalloc", "malloc")