contrek 1.4.5 → 1.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9350d60698a69dda805ede85e42b80fcc38022a361e52674fd2780d696e0f9ff
-  data.tar.gz: '08d164d2e53bb3c96e7212ac6bc9d46bb673de8f10bb950d43f3d66d0c86d793'
+  metadata.gz: a6ed7af7c2661396d55b6ddacd89dfc6c08c4c54744d1443d03a6ba533605ed4
+  data.tar.gz: 3308bedea2f5e89fe8031a65c404c250490542142101dba32fd09f8510cb8cfb
 SHA512:
-  metadata.gz: 1c6d0b73ab8affa0ed17aa3fd803f7aed81cec846db6edd3de5dfcec8103bf23c9e23484819c4a981a4cb0c46da18f0b169122124213a9b4417df108f54c468a
-  data.tar.gz: 57817011679288782915a50ca1adf4155b71732ab73e330e2ac696ea504d7204c08935a6b83487000faac68b37f38aff5b5761d78fc85aab7703752f2700d65f
+  metadata.gz: 250b0ed1bce589beaae764e03226206853f9e9c3bb356fe3bf827cd25c69d72f33ad820f3afa5d9d31aa83e628e67dd8c4500782dcdb668f44b0e098932f6c4f
+  data.tar.gz: 7cf17a172afd9ec9b1788f2abe1779421d204886b99fd54e4729fbf9b616cc3968bb7586cafa5b17da6b5cbcf9641e3f210ee6d3d320e4be67e945022964af13

data/CHANGELOG.md

@@ -170,3 +170,6 @@ All notable changes to this project will be documented in this file.
 
 ## [1.4.5] - 2026-10-11
 - Added tile boundary validation for external geometries, with support for bypassing checks via `unsafe_mode: true`.
+
+## [1.4.6] - 2026-10-18
+- Added tile metadata, polygon bounds, ordering, and shared boundary validation for Ruby and C++ mergers, with `unsafe_mode: true` to bypass validation.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contrek (1.4.5)
+    contrek (1.4.6)
       chunky_png (~> 1.4)
       concurrent-ruby (~> 1.3.5)
       ffi (~> 1.17)

data/README.md

@@ -726,17 +726,13 @@ extractors, provided that the input geometry follows the requirements below.
 
 ### Boundary Validation
 
-By default, Contrek validates the shared boundaries of adjacent tiles when
-merging externally supplied geometries. Boundary coordinates must match
-exactly, including intermediate vertices. Otherwise, the merger raises a
-`Tile boundary mismatch` error.
+By default, Contrek validates the shared boundaries of adjacent tiles when merging externally supplied geometries. Boundary coordinates must match exactly, including intermediate vertices. Otherwise, the merger raises a `Tile boundary mismatch` error.
 
-This validation can be disabled by setting `unsafe_mode: true`, avoiding
-validation overhead when the input geometries are known to be valid.
+This validation can be disabled by setting `unsafe_mode: true`, avoiding validation overhead when the input geometries are known to be valid.
 
-**Important:** Boundary validation does not verify all the Laws of the Tiles.
-Users supplying external geometries remain responsible for satisfying every
-requirement listed above.
+**Important:** Boundary validation does not verify all the Laws of the Tiles. Users supplying external geometries remain responsible for satisfying every requirement listed above.
+
+**Important:** Boundary validation prioritizes correctness over performance and introduce additional processing overhead. Experienced users who can guarantee that their input geometries satisfy the Laws of the Tiles can enable `unsafe_mode: true` to bypass validation entirely and achieve maximum merging performance. This option can also be useful during debugging to isolate merging issues from validation errors.
 
 # Results
 

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

@@ -413,7 +413,7 @@ void stream_progressive_png_image(const std::string& filepath, uint32_t stripe_h
 
   SvgStreamingMerger merger(
     0,
-    {{"bounds", true},{"unsafe_mode", true}},
+    {{"bounds", true}, {"unsafe_mode", true}},
     &stream,
     source.width(),
     source.height());

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

@@ -68,7 +68,8 @@ struct pf_Options {
 
 struct ProcessResult {
   int groups;
-  int width, height;
+  int width = 0;
+  int height = 0;
   int versus;
   int number_of_threads;
   bool has_bounds = false;

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

@@ -12,6 +12,7 @@
 #include <vector>
 #include <algorithm>
 #include <list>
+#include <memory>
 #include "Merger.h"
 
 Merger::Merger(int number_of_threads, const Options& options)
@@ -19,7 +20,9 @@ Merger::Merger(int number_of_threads, const Options& options)
   if (options.contains("versus")) {
     std::cerr << "[Contrek WARNING] The given options 'versus' will be ignored." << std::endl;
   }
-  if (!this->safe()) {
+  if (safe()) {
+    validator_ = std::make_unique<MergerValidator>(*this);
+  } else {
     std::cerr << "[Contrek WARNING] Processing tile with 'unsafe_mode: true'. "
               << "Incompatible result options might lead to unexpected vector geometry.\n";
   }
@@ -30,7 +33,10 @@ bool Merger::safe() {
 }
 
 void Merger::add_tile(ProcessResult& result)
-{ if (this->height == 0) {
+{ if (validator_) {
+    validator_->validate_metadata(result);
+  }
+  if (this->height == 0) {
     this->height = result.height;
   } else {
     if (result.height != this->height && safe()) {
@@ -51,17 +57,15 @@ void Merger::add_tile(ProcessResult& result)
       }
     }
   }
-  if (safe()) validate(result);
 
   int end_x = this->current_x + result.width;
+  if (validator_) {
+    validator_->validate(result, this->current_x, end_x);
+  }
   Tile* tile = new Tile(this, this->current_x, end_x, std::to_string(tiles_.size()), tiles_.size(), Benchmarks {0, 0});
   tile->assign_raw_polygons(result.polygons, result.treemap);
   tiles_.queue_push(tile);
 
-  if (safe()) {
-    previous_boundary_ = boundary_coordinates(result.polygons, end_x);
-  }
-
   this->maximum_width_ = end_x;
   this->current_x = end_x - 1;
 }
@@ -84,26 +88,3 @@ void Merger::translate(ProcessResult& result, int offset) {
   }
 }
 
-std::vector<int> Merger::boundary_coordinates(const std::list<Polygon>& polygons, int boundary_x) {
-  std::vector<int> coordinates;
-
-  for (const auto& polygon : polygons) {
-    for (const auto& point : polygon.outer) {
-      if (point.x == boundary_x) {
-        coordinates.push_back(point.y);
-      }
-    }
-  }
-
-  std::sort(coordinates.begin(), coordinates.end());
-  return coordinates;
-}
-
-void Merger::validate(const ProcessResult& result) {
-  if (tiles_.size() == 0) return;
-
-  const auto current = boundary_coordinates(result.polygons, current_x);
-  if (previous_boundary_ != current) {
-    throw std::invalid_argument("Tile boundary mismatch: adjacent tiles have different edge coordinates");
-  }
-}

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

@@ -11,7 +11,9 @@
 #include <string>
 #include <vector>
 #include <list>
+#include <memory>
 #include "Finder.h"
+#include "MergerValidator.h"
 #include "../Options.h"
 
 class Merger : public Finder {
@@ -24,7 +26,5 @@ class Merger : public Finder {
  protected:
   void translate(ProcessResult& result, int offset);
   int current_x = 0;
-  void validate(const ProcessResult& result);
-  static std::vector<int> boundary_coordinates(const std::list<Polygon>& polygons, int boundary_x);
-  std::vector<int> previous_boundary_;
+  std::unique_ptr<MergerValidator> validator_;
 };

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

@@ -0,0 +1,104 @@
+/*
+ * MergerValidator.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 "MergerValidator.h"
+#include "Merger.h"
+#include <algorithm>
+#include <stdexcept>
+#include <vector>
+#include <list>
+#include <utility>
+
+MergerValidator::MergerValidator(const Merger& merger)
+  : merger_(merger) {}
+
+void MergerValidator::validate_metadata(const ProcessResult& result) const {
+  if (result.width <= 0) {
+    throw std::invalid_argument("Invalid result metadata: width must be a positive integer");
+  }
+  if (result.height <= 0) {
+    throw std::invalid_argument("Invalid result metadata: height must be a positive integer");
+  }
+  if (result.versus != Node::A && result.versus != Node::O) {
+    throw std::invalid_argument("Invalid result metadata: unsupported versus option");
+  }
+}
+
+void MergerValidator::validate(const ProcessResult& result, int start_x, int end_x) {
+  validate_bounds(result.polygons);
+  validate_polygon_order(result.polygons);
+  validate_boundary(result, start_x);
+
+  previous_boundary_ = boundary_coordinates(result.polygons, end_x);
+  has_previous_boundary_ = true;
+}
+
+void MergerValidator::validate_bounds(const std::list<Polygon>& polygons) const {
+  for (const auto& polygon : polygons) {
+    if (polygon.outer.empty()) {
+      throw std::invalid_argument("Invalid polygon: empty outer contour");
+    }
+    RectBounds actual = RectBounds::empty();
+
+    for (const auto& point : polygon.outer) {
+      actual.expand(point.x, point.y);
+    }
+
+    const auto& bounds = polygon.bounds;
+    if (bounds.min_x != actual.min_x ||
+        bounds.max_x != actual.max_x ||
+        bounds.min_y != actual.min_y ||
+        bounds.max_y != actual.max_y) {
+      throw std::invalid_argument("Invalid polygon bounds: bounding box does not match outer contour");
+    }
+  }
+}
+
+void MergerValidator::validate_polygon_order(const std::list<Polygon>& polygons) const {
+  bool has_previous = false;
+  std::pair<int, int> previous;
+
+  for (const auto& polygon : polygons) {
+    const auto& bounds = polygon.bounds;
+
+    const std::pair<int, int> current = merger_.transpose()
+      ? std::make_pair(bounds.min_x, bounds.min_y)
+      : std::make_pair(bounds.min_y, bounds.min_x);
+
+    if (has_previous && current < previous) {
+      throw std::invalid_argument("Invalid polygon order: polygons are not in raster scan order");
+    }
+    previous = current;
+    has_previous = true;
+  }
+}
+
+void MergerValidator::validate_boundary(const ProcessResult& result, int start_x) const {
+  if (!has_previous_boundary_) return;
+
+  const auto current = boundary_coordinates(result.polygons, start_x);
+  if (previous_boundary_ != current) {
+    throw std::invalid_argument("Tile boundary mismatch: adjacent tiles have different edge coordinates");
+  }
+}
+
+std::vector<int> MergerValidator::boundary_coordinates(const std::list<Polygon>& polygons, int boundary_x) {
+  std::vector<int> coordinates;
+
+  for (const auto& polygon : polygons) {
+    for (const auto& point : polygon.outer) {
+      if (point.x == boundary_x) {
+        coordinates.push_back(point.y);
+      }
+    }
+  }
+
+  std::sort(coordinates.begin(), coordinates.end());
+  return coordinates;
+}

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

@@ -0,0 +1,35 @@
+/*
+ * MergerValidator.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 <vector>
+#include <list>
+#include "../PolygonFinder.h"
+
+class Merger;
+
+class MergerValidator {
+ public:
+  explicit MergerValidator(const Merger& merger);
+
+  void validate_metadata(const ProcessResult& result) const;
+  void validate(const ProcessResult& result, int start_x, int end_x);
+
+ private:
+  const Merger& merger_;
+  std::vector<int> previous_boundary_;
+  bool has_previous_boundary_ = false;
+
+  void validate_bounds(const std::list<Polygon>& polygons) const;
+  void validate_polygon_order(const std::list<Polygon>& polygons) const;
+  void validate_boundary(const ProcessResult& result, int start_x) const;
+
+  static std::vector<int> boundary_coordinates(const std::list<Polygon>& polygons, int boundary_x);
+};

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

@@ -60,27 +60,25 @@ void Tile::assign_raw_polygons(const std::list<Polygon>& raw_polylines, const st
   std::unordered_map<int, Shape*> shapes_map;
   int polyline_index = 0;
   for (const auto& raw_polyline : raw_polylines)
-  { if (raw_polyline.bounds.width() > 0)
-    { Polyline* polyline = this->shapes_pool->acquire_polyline(this, raw_polyline.outer, raw_polyline.bounds);
-      std::vector<InnerPolyline*> inner_polylines_list;
-      for (auto& raw_points : raw_polyline.inner) {
-        inner_polylines_list.push_back(this->shapes_pool->acquire_inner_polyline(raw_points, nullptr));
-      }
-      Shape* shape = this->shapes_pool->acquire_shape(polyline, inner_polylines_list);
-      polyline->shape = shape;
-      this->shapes_.push_back(shape);
-
-      if (treemap.size() > 0)
-      { auto treemap_entry = treemap[polyline_index];
-        shapes_map[polyline_index] = shape;
-        if (treemap_entry.first != -1 && treemap_entry.second != -1) {
-          auto it = shapes_map.find(treemap_entry.first);
-          if (it != shapes_map.end()) {
-            Shape* parent = it->second;
-            shape->set_parent_shape(parent);
-            shape->fixed = true;
-            shape->parent_inner_polyline = parent->inner_polylines[treemap_entry.second];
-          }
+  { Polyline* polyline = this->shapes_pool->acquire_polyline(this, raw_polyline.outer, raw_polyline.bounds);
+    std::vector<InnerPolyline*> inner_polylines_list;
+    for (auto& raw_points : raw_polyline.inner) {
+      inner_polylines_list.push_back(this->shapes_pool->acquire_inner_polyline(raw_points, nullptr));
+    }
+    Shape* shape = this->shapes_pool->acquire_shape(polyline, inner_polylines_list);
+    polyline->shape = shape;
+    this->shapes_.push_back(shape);
+
+    if (treemap.size() > 0)
+    { auto treemap_entry = treemap[polyline_index];
+      shapes_map[polyline_index] = shape;
+      if (treemap_entry.first != -1 && treemap_entry.second != -1) {
+        auto it = shapes_map.find(treemap_entry.first);
+        if (it != shapes_map.end()) {
+          Shape* parent = it->second;
+          shape->set_parent_shape(parent);
+          shape->fixed = true;
+          shape->parent_inner_polyline = parent->inner_polylines[treemap_entry.second];
         }
       }
     }

data/ext/cpp_polygon_finder/cpp_polygon_finder.cpp

@@ -106,6 +106,8 @@
 #include "PolygonFinder/src/polygon/finder/concurrent/PartPool.cpp"
 #include "PolygonFinder/src/polygon/finder/concurrent/Merger.h"
 #include "PolygonFinder/src/polygon/finder/concurrent/Merger.cpp"
+#include "PolygonFinder/src/polygon/finder/concurrent/MergerValidator.h"
+#include "PolygonFinder/src/polygon/finder/concurrent/MergerValidator.cpp"
 #include "PolygonFinder/src/polygon/finder/concurrent/HorizontalMerger.h"
 #include "PolygonFinder/src/polygon/finder/concurrent/HorizontalMerger.cpp"
 #include "PolygonFinder/src/polygon/finder/concurrent/VerticalMerger.h"

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

@@ -13,18 +13,21 @@ module Contrek
         @current_x = 0
         @tiles = Queue.new
         @whole_tile = nil
-        @previous_boundary = nil
         @user_options = options
         if (warn_options = @user_options.keys & IGNORE_OPTIONS).any?
           warn "[Contrek WARNING] The given options '#{warn_options.join(",")}' will be ignored."
         end
         @options = {unsafe_mode: false}.merge(@user_options).except(*IGNORE_OPTIONS)
-        unless safe?
+        if safe?
+          @validator = MergerValidator.new(self)
+        else
           warn "[Contrek WARNING] Processing tile with 'unsafe_mode: true'. Incompatible result options might lead to unexpected vector geometry."
         end
       end
 
       def add_tile(result)
+        @validator&.validate_metadata(result)
+
         @height ||= result.metadata[:height]
         raise ArgumentError, "All results must have the same height" if @height != result.metadata[:height] && safe?
         @options[:versus] ||= result.metadata[:versus]
@@ -35,8 +38,8 @@ module Contrek
           end
         end
 
-        validate(result) if safe?
         end_x = @current_x + result.metadata[:width]
+        @validator&.validate(result, @current_x, end_x)
 
         tile = Tile.new(
           finder: self,
@@ -47,9 +50,6 @@ module Contrek
         tile.assign_raw_polygons!(result[:polygons])
 
         @tiles << tile
-
-        @previous_boundary = boundary_coordinates(result.polygons, end_x) if safe?
-
         @maximum_width = end_x
         @current_x = end_x - 1
       end
@@ -65,25 +65,6 @@ module Contrek
 
       private
 
-      def validate(result)
-        return unless @previous_boundary
-
-        current = boundary_coordinates(result.polygons, @current_x)
-        unless @previous_boundary == current
-          raise ArgumentError, "Tile boundary mismatch: adjacent tiles have different edge coordinates"
-        end
-      end
-
-      def boundary_coordinates(polygons, boundary_x)
-        coordinates = []
-        polygons.each do |polygon|
-          polygon[:outer].each do |point|
-            coordinates << point[:y] if point[:x] == boundary_x
-          end
-        end
-        coordinates.sort!
-      end
-
       def translate(result, offset)
         result.polygons.each do |polygon|
           polygon[:outer].each { |p| p[:x] += offset }

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Contrek
+  module Concurrent
+    class MergerValidator
+      def initialize(merger)
+        @merger = merger
+      end
+
+      def validate(result, start_x, end_x)
+        validate_bounds(result.polygons)
+        validate_polygon_order(result.polygons)
+        validate_boundary(result, start_x)
+
+        @previous_boundary = boundary_coordinates(result.polygons, end_x)
+      end
+
+      def validate_metadata(result)
+        metadata = result.metadata
+        [:width, :height, :versus].each do |key|
+          raise ArgumentError, "Missing result metadata: #{key}" unless metadata.key?(key)
+        end
+        [:width, :height].each do |key|
+          value = metadata[key]
+          unless value.is_a?(Integer) && value.positive?
+            raise ArgumentError, "Invalid result metadata: #{key} must be a positive integer"
+          end
+        end
+        unless [:a, :o].include?(metadata[:versus])
+          raise ArgumentError, "Invalid result metadata: unsupported versus option"
+        end
+      end
+
+      private
+
+      def validate_polygon_order(polygons)
+        previous = nil
+        polygons.each do |polygon|
+          bounds = polygon[:bounds]
+          current = if @merger.transpose?
+            [bounds[:min_x], bounds[:min_y]]
+          else
+            [bounds[:min_y], bounds[:min_x]]
+          end
+          if previous && (current <=> previous) < 0
+            raise ArgumentError, "Invalid polygon order: polygons are not in raster scan order"
+          end
+          previous = current
+        end
+      end
+
+      def validate_boundary(result, start_x)
+        return unless @previous_boundary
+
+        current = boundary_coordinates(result.polygons, start_x)
+        unless @previous_boundary == current
+          raise ArgumentError, "Tile boundary mismatch: adjacent tiles have different edge coordinates"
+        end
+      end
+
+      def boundary_coordinates(polygons, boundary_x)
+        coordinates = []
+        polygons.each do |polygon|
+          polygon[:outer].each do |point|
+            coordinates << point[:y] if point[:x] == boundary_x
+          end
+        end
+        coordinates.sort!
+      end
+
+      def validate_bounds(polygons)
+        polygons.each do |polygon|
+          outer = polygon[:outer]
+          raise ArgumentError, "Invalid polygon: empty outer contour" if outer.empty?
+          bounds = polygon[:bounds]
+          min_x = max_x = outer[0][:x]
+          min_y = max_y = outer[0][:y]
+          outer.each do |point|
+            x = point[:x]
+            y = point[:y]
+            min_x = x if x < min_x
+            max_x = x if x > max_x
+            min_y = y if y < min_y
+            max_y = y if y > max_y
+          end
+          unless bounds[:min_x] == min_x &&
+              bounds[:max_x] == max_x &&
+              bounds[:min_y] == min_y &&
+              bounds[:max_y] == max_y
+            raise ArgumentError, "Invalid polygon bounds: bounding box does not match outer contour"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -92,7 +92,6 @@ module Contrek
         @shapes = []
         shapes_map = {}
         raw_polylines.each_with_index do |raw_polyline, polyline_index|
-          next if raw_polyline[:bounds][:max_x] - raw_polyline[:bounds][:min_x] == 0
           shape = Shape.new.tap do |shape|
             shape.outer_polyline = Polyline.new(tile: self, polygon: raw_polyline[:outer], shape: shape, bounds: raw_polyline[:bounds])
             shape.inner_polylines = raw_polyline[:inner].map { |raw| InnerPolyline.new(shape: shape, raw_coordinates: raw) }

data/lib/contrek/version.rb

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

data/lib/contrek.rb

@@ -45,6 +45,7 @@ require "contrek/finder/concurrent/polyline"
 require "contrek/finder/concurrent/cluster"
 require "contrek/finder/concurrent/finder"
 require "contrek/finder/concurrent/merger"
+require "contrek/finder/concurrent/merger_validator"
 require "contrek/finder/concurrent/horizontal_merger"
 require "contrek/finder/concurrent/vertical_merger"
 require "contrek/finder/concurrent/streaming_merger"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.4.5
+  version: 1.4.6
 platform: ruby
 authors:
 - Emanuele Cesaroni
@@ -215,6 +215,8 @@ files:
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/InnerPolyline.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Merger.cpp
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Merger.h
+- ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/MergerValidator.cpp
+- ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/MergerValidator.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Part.cpp
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Part.h
 - ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/PartPool.cpp
@@ -305,6 +307,7 @@ files:
 - lib/contrek/finder/concurrent/inner_polyline.rb
 - lib/contrek/finder/concurrent/listable.rb
 - lib/contrek/finder/concurrent/merger.rb
+- lib/contrek/finder/concurrent/merger_validator.rb
 - lib/contrek/finder/concurrent/part.rb
 - lib/contrek/finder/concurrent/partitionable.rb
 - lib/contrek/finder/concurrent/polyline.rb