contrek 1.4.1 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eada79f09d6eede09420a2f933496d8839152f741d9c90e7d6b63fc7537bec29
-  data.tar.gz: 5652df8b513dfb26db08a1640cf59e2642a0feba7df2f9ce62eec0fe4e6dc445
+  metadata.gz: 802afd86666e1705cc50240c6f7d79abfd9c7e93c315b1222199e79836fdd9e2
+  data.tar.gz: e9f593c3ef9a661720f2587b44d65406839b25c2bc1690b8c4bfae477f967de6
 SHA512:
-  metadata.gz: 8dc280b616db1de56688ca94f5c1bcef1bf02cb81ff820638ebdf0bed821ba37745799a579a2660da6dc0934afa46a94aae51affdcb3b6fd987710a84f5f85d9
-  data.tar.gz: c815702b9abafa8b5e6de4e1f2e05ab6b03ed91248efe0786807307db6ebff19a7e2c9d002fadf94a12e2c9f41a8c07fe0ca05c01f5a838722090a737c888983
+  metadata.gz: 8e4d8940a0f6cb93fc0ee685808c8889110bedbfd604fb8de3e3aca6b0fb9caa69d57bec518cc50ce15314a6ffa45e525fc947b60d52d71403510b6c77b7302f
+  data.tar.gz: e12d7f30b9dec7ee474ab5c400f86f8331cc8eaa8e1571e6c8b895ddea4a4f0633806d2ccb0b4fdd12380d77caa714c4b6c85b9f347e3bf6ff70f39b0a1cb9d9

data/CHANGELOG.md

@@ -156,3 +156,9 @@ All notable changes to this project will be documented in this file.
 
 ## [1.4.1] - 2026-08-23
 - The number_of_threads effective value is now returned inside metadata output struct too.
+
+## [1.4.2] - 2026-09-06
+- Contrek takes care of the streaming process, providing an API that greatly simplifies the implementation of streaming raster processing.
+
+## [1.4.3] - 2026-09-09
+- Added TIFF/GeoTIFF streaming support with geolocation metadata and direct WGS84 GeoJSON output.

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    contrek (1.4.1)
+    contrek (1.4.3)
       chunky_png (~> 1.4)
       concurrent-ruby (~> 1.3.5)
+      ffi (~> 1.17)
       rice (= 4.5.0)
 
 GEM
@@ -14,6 +15,8 @@ GEM
     chunky_png (1.4.0)
     concurrent-ruby (1.3.5)
     diff-lcs (1.6.1)
+    ffi (1.17.4)
+    ffi (1.17.4-x86_64-linux-gnu)
     json (2.11.3)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)

data/README.md

@@ -2,12 +2,14 @@
 
 **Contrek** is a standalone **C++17 contour tracing and polygonization library** for raster images.
 
-It was originally developed to solve a practical problem: extracting polygons from very large raster images without loading the entire image into memory. Over time the implementation evolved into a reusable library that can process PNG images as well as raw memory buffers, while preserving polygon topology during the entire tracing process.
+It was originally developed to solve a practical problem: extracting polygons from very large raster images without loading the entire image into memory. Over time the implementation evolved into a reusable library that can process PNG and TIFF/GeoTIFF images as well as raw memory buffers, while preserving polygon topology during the entire tracing process.
 
-The engine is based on programmable pixel matchers, allowing the caller to decide which pixels belong to the regions being traced. Polygon coordinates can be streamed as they are produced, making the library suitable for datasets that would otherwise require a large amount of RAM.
+The engine is based on programmable pixel matchers, allowing the caller to decide which pixels belong to the regions being traced. Polygon coordinates can be streamed as they are produced, making the library suitable for datasets that would otherwise require a large amount of RAM. GeoTIFF geolocation can also be preserved when streaming directly to GeoJSON (EPSG:4326).
 
 Although the tracing engine is written in C++, Contrek is also distributed as a Ruby gem exposing almost the complete native API through an idiomatic Ruby interface.
 
+A **Python** binding is available 👉 **[here](https://github.com/runout77/contrek-python)**
+
 ## About Contrek
 
 **Contrek** (**CON**tour **TREK**king) at its simplest, the library scans a bitmap and returns the contours of all regions matching a user-defined criterion. Each region is represented by one outer polygon and, when necessary, one or more inner polygons describing holes.
@@ -25,58 +27,227 @@ The image below shows a simple example. Every non-white pixel is considered part
 
 Most contour tracing libraries process an image sequentially. That approach is perfectly adequate for many workloads, but it becomes less practical once images become very large or when memory usage starts to matter.
 
-Contrek follows a different strategy.
+Contrek supports monothread extraction but also different strategies.
 
-Instead of processing the whole image at once, it can split it into independent vertical stripes. Each stripe is traced separately and the resulting polygons are merged afterwards. Most of the implementation complexity lies in this merge phase, whose purpose is to reconstruct polygons crossing stripe boundaries without breaking their topology.
+### Mode 1: Single-threaded processing
 
-The same design makes it possible to use the library in two different ways:
+<table>
+<tr>
+<td width="40%" valign="top">
+<img src="docs/images/modes/mode1.jpg" width="100%" alt="Mode 1">
+</td>
+<td width="60%" valign="top">
+The entire image is processed using a single core.
 
-- **Parallel processing**, where several stripes are traced simultaneously on different CPU cores.
-- **Streaming processing**, where only a small portion of the image is kept in memory at any given time.
+**Profile:** low speed; low memory efficiency.
+<br><br>
+<center><img src="docs/images/modes/mode1_panel.jpg" width="80%" alt="Mode 1"></center>
+</td></tr></table>
 
-The tracing algorithm itself is identical in both cases; only the execution strategy changes.
+Trace polygons from a PNG file (`CPPPngBitMap`).
 
-## Parallel execution
+```ruby
+  png_bitmap = CPPPngBitMap.new("spec/files/images/labyrinth3.png")
+  color = Contrek::Bitmaps::RgbCppColor.new(r: 255, g: 255, b: 255, a: 255)
+  rgb_matcher = CPPRGBNotMatcher.new(color.raw)
+  polygonfinder = CPPPolygonFinder.new(
+    png_bitmap,
+    rgb_matcher,
+    nil,
+    { versus: :a,
+      compress: {
+        visvalingam: true,
+        visvalingam_tolerance: 1.5
+      }
+    }
+  )
+  result = polygonfinder.process_info
+  puts result.metadata[:number_of_threads] # => 0
+```
 
-When multiple CPU cores are available, independent stripes can be processed concurrently. The actual speedup depends on the image content and on how much work is required during the merge stage, but large datasets generally benefit from additional cores.
+`versus` accepts `:a`,`:o` for "anticlockwise"/"clockwise".
 
-This approach allows Contrek to make effective use of modern multicore processors without changing the resulting geometry.
 
-## Streaming large datasets
+### Mode 2: Parallel processing
 
-Loading an entire gigapixel image into memory is often unnecessary.
+<table>
+<tr>
+<td width="40%" valign="top">
+<img src="docs/images/modes/mode2.jpg" width="100%" alt="Mode 1">
+</td>
+<td width="60%" valign="top">
+The entire image is loaded first, then split into tiles and processed across multiple CPU cores. Partial results are progressively and dynamically merged: there is no predefined merge order, and adjacent pairs are processed as soon as they become available.
+This mode prioritizes performance, using parallelism both for tile processing and for merging partial results.
 
-Contrek can instead process the image incrementally by reading one stripe at a time. Only the current working buffer needs to be allocated, making memory consumption predictable regardless of the final image height.
+**Profile:** maximum speed, with processing time decreasing as more cores become available; low memory efficiency.
+<br><br>
+<center><img src="docs/images/modes/mode2_panel.jpg" width="80%" alt="Mode 1"></center>
+</td></tr></table>
 
-This execution mode is particularly useful when processing images that are too large to fit comfortably into RAM.
+Use 8 threads and 8 tiles
 
-## Merging polygons
+```ruby
+  png_bitmap = CPPPngBitMap.new("spec/files/images/sample_10240x10240.png")
+  color = Contrek::Bitmaps::RgbCppColor.new(r: 255, g: 255, b: 255, a: 255)
+  rgb_matcher = CPPRGBNotMatcher.new(color.raw)
+  polygonfinder = Contrek::Cpp::CPPConcurrentFinder.new(
+    number_of_threads: 8,
+    bitmap: png_bitmap,
+    matcher: rgb_matcher,
+    options: {number_of_tiles: 8, versus: :o, compress: {uniq: true}}
+  )
+  result = polygonfinder.process_info
+  puts result.metadata[:benchmarks].inspect
+  # => {"compress"=>5.08, "init"=>230.79, "inner"=>6.54, "outer"=>84.11, "total"=>235.87}
+  puts result.metadata[:number_of_threads] # => 8
+```
+
+### Mode 3: Input streaming
 
-Whenever a polygon crosses the boundary between two adjacent stripes, the library reconstructs it during the merge phase.
+<table>
+<tr>
+<td width="40%" valign="top">
+<img src="docs/images/modes/mode3.jpg" width="100%" alt="Mode 1">
+</td>
+<td width="60%" valign="top">
+The image does not need to be loaded entirely into memory. Instead, it can be read progressively using a fixed-size buffer. For example, with a PNG source, this can be done using libspng's progressive decoding.
+Adjacent tiles share an overlapping scanline to preserve geometry continuity across tile boundaries. Once all tiles have been added, the merge is performed (optionally using multiple threads) to reconstruct the complete geometry.
+This mode provides a trade-off between performance and memory usage: the entire raster does not need to be kept in RAM, while the vector state required to build the final result is retained.
+
+**Profile:** medium speed; medium-high memory efficiency.
+<br><br>
+<center><img src="docs/images/modes/mode3_panel.jpg" width="80%" alt="Mode 1"></center>
+</td></tr></table>
+
+Trace polygons from two in-memory pattern strings (`CPPBitMap`, useful for synthetic tiles or tests).
+Up is 6 rows height, down is 5 rows. Total after merging: 10 rows, because one row is the shared scanline
 
-This reconstruction preserves polygon connectivity across stripe boundaries, so the final output is equivalent to tracing the entire image in a single pass.
+```ruby
+  up =    " 00000000000000               " \
+          " 00000000000000               " \
+          " 00          00               " \
+          " 00          00               " \
+          " 00          00               " \
+          " 00          00               "
+
+  down =  " 00          00               " \
+          " 00          00               " \
+          " 00          00               " \
+          " 00000000000000               " \
+          " 00000000000000               "
+  matcher = CPPValueNotMatcher.new(" ")
+  result_up = CPPPolygonFinder.new(CPPBitMap.new(up, 30),
+    matcher,
+    nil,
+    {versus: :a, bounds: true}).process_info
+  result_down = CPPPolygonFinder.new(CPPBitMap.new(down, 30),
+    matcher,
+    nil,
+    {versus: :a, bounds: true}).process_info
+
+  step_finder = Contrek::Cpp::CPPConcurrentVerticalMerger.new(options: {compress: {linear: true}})
+  step_finder.add_tile(result_up)
+  step_finder.add_tile(result_down)
+  result = step_finder.process_info
+
+  expect(result.metadata[:groups]).to eq(1)
+  expect(result.metadata[:width]).to eq(30)
+  expect(result.metadata[:height]).to eq(10)
+```
+See an other example of **[input streaming graphical result](docs/images/stripes/merging_polygons.md)**.
+
+The same operation using Contrek's built-in streaming API and progressive PNG decoding via libspng:
+
+```ruby
+  # PNG image to stream from
+  source = CPPPngSource.new("./spec/files/images/labyrinth2.png")
+  # streamer with a 20-row window
+  streamer = CPPRasterStreamer.new(source, stripe_height: 20)
+  white = Contrek::Bitmaps::RgbCppColor.new(r: 255, g: 255, b: 255, a: 255)
+  matcher = CPPRGBNotMatcher.new(white.raw)
+  # reusable bitmap where libspng decodes rows directly
+  buffer_bitmap = CPPRawBitMap.new(source.width, streamer.stripe_height)
+  finder = Contrek::Cpp::CPPConcurrentVerticalMerger.new(options: {compress: {uniq: true, linear: true}})
+  
+  # streaming loop, 20 rows each
+  streamer.each(buffer_bitmap) do |bitmap, buffer_rows, buffer_size|
+    tile = CPPPolygonFinder.new(
+      bitmap,
+      matcher,
+      nil,
+      {processing_height: buffer_rows, versus: :o, bounds: true}
+    ).process_info
+    finder.add_tile(tile)
+  end
+  result = finder.process_info
+  puts result.metadata[:width] # => 130
+  puts result.metadata[:height] # => 130
+  puts result.points[0][:outer].first.inspect # => {:x=>10, :y=>4} # first point
+  puts result.points[0][:outer].size # => 1171 points
+```
+
+### Mode 4: End-to-end streaming
 
 <table>
-  <tr>
-    <td width="50%" style="padding: 0; background-color: white;">
-      <img src="docs/images/stripes/whole_0.png" width="100%"><br>
-      <img src="docs/images/stripes/whole_256.png" width="100%"><br>
-      <img src="docs/images/stripes/whole_512.png" width="100%"><br>
-      <img src="docs/images/stripes/whole_768.png" width="100%">
-    </td>
-    <td width="50%" align="center" style="vertical-align: middle; background-color: white;">
-      <strong>Full Topological Reconstruction</strong><br><br>
-      <img src="docs/images/stripes/whole.png" width="90%">
-    </td>
-  </tr>
-  <tr>
-    <td colspan="2" align="center" style="background-color: white;">
-      <em><b>Left:</b> Image split into 4 independent memory buffers (stripes).</em><br>
-      <em><b>Right:</b> Contrek ensures <b>perfect topological continuity</b> during merging.</em><br>
-      🔴 <b>Red:</b> Outer contours &nbsp;&nbsp; | &nbsp;&nbsp; 🟢 <b>Green:</b> Inner zones
-    </td>
-  </tr>
-</table>
+<tr>
+<td width="40%" valign="top">
+<img src="docs/images/modes/mode4.jpg" width="100%" alt="Mode 1">
+</td>
+<td width="60%" valign="top">
+This mode extends the incremental processing used in Mode 3 by streaming the output as well.
+The image is read and processed one tile at a time. Each new tile is immediately merged with the current state. As processing moves forward, whenever a geometry is complete and can no longer be affected by subsequent tiles, it is finalized and written directly to the SVG file.
+This limits both the amount of raster data kept in memory and the accumulation of generated vector geometries. It is particularly well suited to very large datasets or cases where the vector output itself can become significant in size.
+
+**Profile:** low speed; maximum memory efficiency.
+<br><br>
+<center><img src="docs/images/modes/mode4_panel.jpg" width="80%" alt="Mode 1"></center>
+</td></tr></table>
+
+Trace polygons from 2 in-memory pattern strings.
+
+```ruby
+  stripe1 = "     000       000" \
+            "    00 00     00 0" \
+            "   00   00   00  0" \
+            "    00 00   00   0" \
+            "     000   00    0" \
+            "          00     0"
+
+  stripe2 = "          00     0" \
+            " 000     00      0" \
+            "00 00   00       0" \
+            " 000   00        0" \
+            "      00         0" \
+            "     0000000000000"
+  # streaming to svg file pattern
+  stripes = [stripe1, stripe2]
+  shared_stream = Contrek::Cpp::CPPTempfile.new("output.svg")
+  step_finder = Contrek::Cpp::CPPSvgConcurrentStreamingMerger.new(
+    options:  {bounds: true, compress: {uniq: true, linear: true, douglas_peucker: true}},
+    stream_to: shared_stream,
+    total_width: 18,
+    total_height: 11
+  )
+  matcher = CPPValueNotMatcher.new(" ")
+  stripes.each do |stripe|
+    stripe_result = CPPPolygonFinder.new(CPPBitMap.new(stripe, 18),
+      matcher,
+      nil,
+      {versus: :a, bounds: true}).process_info
+    last = stripes.last == stripe
+    step_finder.add_tile(stripe_result, last)
+  end
+  result = step_finder.process_info
+  expect(result.metadata[:groups]).to eq(3)
+  expect(result.metadata[:width]).to eq(18)
+  expect(result.metadata[:height]).to eq(11)
+  shared_stream.rewind
+  puts shared_stream.read.inspect
+  # => "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"18\" height=\"11\">
+  #     <polygon points=\"3,3 5,5 8,5 10,3 8,0 5,0\" class=\"out\"/>
+  #     <polygon points=\"7,1 8,3 6,4 5,2\" class=\"in\"/>
+  #     <polygon points=\"5,11 18,11 18,0 15,0\" class=\"out\"/> ...
+```
 
 ## Benchmarking
 
@@ -134,6 +305,15 @@ During installation the native C++ extension is compiled automatically.
 
 Once installed, the C++ implementation is used by default. A pure Ruby implementation is also included and can be selected explicitly whenever native extensions are not desired.
 
+### TIFF / GeoTIFF support
+
+TIFF and GeoTIFF streaming support requires the system `libtiff` and `libgeotiff` libraries.
+Ubuntu / Debian:
+
+```bash
+sudo apt install libtiff-dev libgeotiff-dev
+```
+
 # Usage
 
 The simplest way to use Contrek is through the `Contrek.contour!` helper.

data/contrek.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency "chunky_png", "~> 1.4"
   s.add_dependency "concurrent-ruby", "~> 1.3.5"
+  s.add_dependency "ffi", "~> 1.17"
   s.add_dependency "rice", "= 4.5.0"
 
   s.required_ruby_version = ">= 3.0.0"

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

@@ -38,8 +38,8 @@ enum class Connectivity {
 
 
 struct Config {
-  int threads = 4;
-  int tiles = 2;
+  int threads = 0;
+  int tiles = 1;
   Versus versus = Versus::A;
   bool compress_unique = false;
   bool compress_linear = false;

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

@@ -28,6 +28,8 @@
 #include "polygon/bitmaps/RawBitmap.h"
 #include "polygon/bitmaps/RemoteFastPngBitmap.h"
 #include "polygon/bitmaps/spng.h"
+#include "polygon/bitmaps/streaming/RasterStreamer.h"
+#include "polygon/bitmaps/streaming/PngSource.h"
 #include "polygon/matchers/Matcher.h"
 #include "polygon/matchers/RGBMatcher.h"
 #include "polygon/matchers/RGBNotMatcher.h"
@@ -100,7 +102,7 @@ void Tests::test_b()
 
   Options options = {
     {"versus", Identifier{"o"}},
-    {"number_of_tiles",2},
+    {"number_of_tiles", 2},
     {"compress", Options{
       {"uniq", true},
       {"linear", true},
@@ -202,7 +204,7 @@ void Tests::test_e()
 
   Options options = {
     {"versus", Identifier{"a"}},
-    {"number_of_tiles",2},
+    {"number_of_tiles", 2},
     {"compress", Options{
       {"uniq", true},
     }},
@@ -243,7 +245,7 @@ void Tests::test_g()
 
   Options options = {
     {"versus", Identifier{"a"}},
-    {"number_of_tiles",2},
+    {"number_of_tiles", 2},
     {"compress", Options{
       {"uniq", true},
     }},
@@ -321,70 +323,29 @@ double get_peak_rss() {
   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, bool generate_svg = false, bool generate_png = false) {
     std::vector<ProcessResult*> result_clones;
     Options options = {};
     VerticalMerger vmerger(0, options);
 
-    // 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;
+    PngSource source(filepath);
+    RasterStreamer streamer(source, stripe_height);
 
     // allocates stripe buffer
-    RawBitmap stripe_bitmap;
-    std::cout << total_width << " " << stripe_height << std::endl;
-    stripe_bitmap.define(total_width, stripe_height, 4, true);
+    RawBitmap stripe_bitmap(source.width(), stripe_height);
     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;
     int stripe_count = 0;
+
     // main stripes loop
-    for (uint32_t current_y_offset = 0; current_y_offset < total_height; current_y_offset += stripe_height) {
-      uint32_t 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;
-      }
+    streamer.each(stripe_bitmap, [&](Bitmap& bitmap, uint32_t buffer_rows, std::size_t, std::size_t) {
       // stripe contour tracing
       Options options = {
+        {"processing_height", static_cast<int>(buffer_rows)},
         {"versus", Identifier{"a"}},
       };
-      PolygonFinder polygon_finder(&stripe_bitmap, &not_matcher, nullptr, options);
+      PolygonFinder polygon_finder(&bitmap, &not_matcher, nullptr, options);
       ProcessResult *result = polygon_finder.process_info();
       if (result) {
         std::cout << "stripe " << stripe_count << ": found polygons " << result->groups << std::endl;
@@ -392,7 +353,7 @@ void stream_png_image(const std::string& filepath, uint32_t stripe_height, bool
         vmerger.add_tile(*result);
       }
       stripe_count++;
-    }
+    });
 
     std::cout << "Merging polygons ..." << std::endl;
     ProcessResult *merged_result = vmerger.process_info();
@@ -400,8 +361,7 @@ void stream_png_image(const std::string& filepath, uint32_t stripe_height, bool
     if (merged_result) {
       std::cout << "Founds total polygons: " << merged_result->groups << std::endl;
       if (generate_png) {
-        RawBitmap full_bitmap;
-        full_bitmap.define(total_width, total_height, 4, true);
+        RawBitmap full_bitmap(source.width(), source.height());
         full_bitmap.fill(255, 255, 255);
         merged_result->draw_on_bitmap(full_bitmap);
         std::cout << "Saving whole png ..." << std::endl;
@@ -413,18 +373,18 @@ void stream_png_image(const std::string& filepath, uint32_t stripe_height, bool
         merged_result->save_svg("whole.svg");
         std::cout << "Svg saved!" << std::endl;
       }
+      delete merged_result;
     }
-    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, true);
+  // stream_png_image("../images/test_20480x20480.png", 2000, true);
   std::cout << "Memory usage peak: " << get_peak_rss() << " MB" << std::endl;
 }
 
@@ -440,103 +400,47 @@ double get_current_rss_mb() {
 }
 
 void stream_progressive_png_image(const std::string& filepath, uint32_t stripe_height) {
-    std::vector<ProcessResult*> result_clones;
-    Options voptions = {
-        {"bounds", true},
-      };
-    // 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;
-    }
-    std::vector<char> buffer(4 * 1024 * 1024);  // Buffer (4MB)
-    shared_stream.rdbuf()->pubsetbuf(buffer.data(), buffer.size());
-
-    SvgStreamingMerger vmerger(0, voptions, &shared_stream, total_width, total_height);
-    // GeoJsonStreamingMerger vmerger(0, &varguments, &shared_stream, 4294901760);
-    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) {
-        uint32_t 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
-        Options options = {
+  PngSource source(filepath);
+  RasterStreamer streamer(source, stripe_height);
+  RawBitmap bitmap(source.width(), stripe_height);
+  RGBNotMatcher not_matcher(-1);
+
+  std::ofstream stream("streaming_buffer.svg");
+
+  SvgStreamingMerger merger(
+    0,
+    {{"bounds", true}},
+    &stream,
+    source.width(),
+    source.height());
+
+  uint32_t processed_rows = 0;
+  bool first = true;
+  int stripe_count = 0;
+  streamer.each(
+    bitmap,
+    [&](Bitmap& bitmap, uint32_t buffer_rows, std::size_t, std::size_t) {
+      PolygonFinder finder(&bitmap, &not_matcher, nullptr,
+        {
+          {"processing_height", static_cast<int>(buffer_rows)},
           {"versus", Identifier{"a"}},
           {"bounds", true},
           {"compress", Options{
             {"uniq", true},
             {"linear", true},
           }},
-        };
-
-        PolygonFinder polygon_finder(&stripe_bitmap, &not_matcher, nullptr, options);
-        ProcessResult *result = polygon_finder.process_info();
-        if (result) {
-          std::cout << "stripe " << stripe_count << ": found polygons " << result->groups << std::endl;
-          vmerger.add_tile(*result, !(current_y_offset + stripe_height < total_height));
-          delete result;
-          std::cout << "-> RSS before merge: " << get_current_rss_mb() << " MB" << std::endl;
-        }
-        stripe_count++;
+        });
+      ProcessResult* result = finder.process_info();
+      if (result) {
+        std::cout << "stripe " << stripe_count++ << ": found polygons " << result->groups << std::endl;
+        processed_rows += buffer_rows - (first ? 0 : RasterStreamer::OVERLAP);
+        merger.add_tile(*result, processed_rows == source.height());
+        delete result;
       }
-      ProcessResult *merged_result = vmerger.process_info();
-      std::cout << "total found polygons " << merged_result->groups << std::endl;
-      delete merged_result;
-    } 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);
+      first = false;
+    });
+
+  delete merger.process_info();
 }
 
 void Tests::test_l() {