clipper2 0.1.0

data/lib/clipper2/native_memory.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Clipper2
+  module NativeMemory
+    MAX_COORD = (2**61) - 1
+    MIN_COORD = -MAX_COORD
+
+    module_function
+
+    def paths_pointer(paths)
+      return FFI::Pointer::NULL if paths.empty?
+
+      paths.each { |path| validate_native_range(path) }
+      pointer_from_bytes(CPaths64.pack(paths))
+    end
+
+    def path_pointer(path)
+      validate_native_range(path)
+      pointer_from_bytes(CPaths64.pack_path(path))
+    end
+
+    def int64_pointer(values)
+      pointer_from_bytes(values.pack("q<*"))
+    end
+
+    def pointer_reference(pointer = FFI::Pointer::NULL)
+      reference = FFI::MemoryPointer.new(:pointer)
+      reference.write_pointer(pointer)
+      reference.instance_variable_set(:@clipper2_owner, pointer)
+      reference
+    end
+
+    def read_paths(pointer, scale:)
+      CPaths64.read(pointer, scale: scale)
+    end
+
+    def dispose_pointer(pointer)
+      return if pointer.nil? || pointer.null?
+
+      dispose_reference(pointer_reference(pointer))
+    end
+
+    def dispose_reference(reference)
+      return if reference.nil? || reference.read_pointer.null?
+
+      Native.send(:DisposeArray64, reference)
+    end
+
+    def validate_native_range(path)
+      path.send(:quantized_coords).each do |coordinate|
+        next if coordinate.between?(MIN_COORD, MAX_COORD)
+
+        raise RangeError, "quantized coordinate exceeds Clipper2's supported range"
+      end
+    end
+
+    def pointer_from_bytes(bytes)
+      pointer = FFI::MemoryPointer.new(:int64, bytes.bytesize / 8)
+      pointer.put_bytes(0, bytes)
+      pointer
+    end
+    private_class_method :pointer_from_bytes
+  end
+end

data/lib/clipper2/operations.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Clipper2
+  module Operations
+    NATIVE_ERRORS = {
+      -1 => "Clipper2 could not complete the clipping operation",
+      -3 => "Clipper2 rejected the fill rule",
+      -4 => "Clipper2 rejected the clip type"
+    }.freeze
+
+    module_function
+
+    def boolean(type, subject, clip = nil, subject_open: nil, fill_rule: :non_zero,
+                preserve_collinear: true, reverse_solution: false)
+      scale = common_scale(subject, clip, subject_open)
+      subjects = Paths.coerce(subject, scale: scale)
+      clips = Paths.coerce(clip, scale: scale)
+      open_subjects = Paths.coerce(subject_open, scale: scale)
+      clip_type = enum_value(Generated::CLIP_TYPES, normalize_clip_type(type), "clip type")
+      fill = enum_value(Generated::FILL_RULES, fill_rule, "fill rule")
+
+      closed_reference = NativeMemory.pointer_reference
+      open_reference = NativeMemory.pointer_reference
+      status = Native.send(
+        :BooleanOp64,
+        clip_type,
+        fill,
+        NativeMemory.paths_pointer(subjects),
+        NativeMemory.paths_pointer(open_subjects),
+        NativeMemory.paths_pointer(clips),
+        closed_reference,
+        open_reference,
+        preserve_collinear,
+        reverse_solution
+      )
+      raise_native_error(status) unless status.zero?
+
+      [
+        NativeMemory.read_paths(closed_reference.read_pointer, scale: scale),
+        NativeMemory.read_paths(open_reference.read_pointer, scale: scale)
+      ]
+    ensure
+      NativeMemory.dispose_reference(closed_reference)
+      NativeMemory.dispose_reference(open_reference)
+    end
+
+    def inflate(value, delta, join: :round, end_type: :polygon, miter_limit: 2.0,
+                arc_tolerance: 0.25, reverse_solution: false)
+      paths = Paths.coerce(value, scale: common_scale(value))
+      return Paths.new([], scale: paths.scale) if paths.empty?
+
+      scaled_delta = scaled_distance(delta, paths.scale, "delta")
+      scaled_tolerance = scaled_distance(arc_tolerance, paths.scale, "arc_tolerance", allow_zero: true)
+      miter = positive_float(miter_limit, "miter_limit")
+      join_value = enum_value(Generated::JOIN_TYPES, join, "join type")
+      end_value = enum_value(Generated::END_TYPES, end_type, "end type")
+
+      pointer = Native.send(
+        :InflatePaths64,
+        NativeMemory.paths_pointer(paths),
+        scaled_delta,
+        join_value,
+        end_value,
+        miter,
+        scaled_tolerance,
+        reverse_solution
+      )
+      NativeMemory.read_paths(pointer, scale: paths.scale)
+    ensure
+      NativeMemory.dispose_pointer(pointer)
+    end
+
+    def rect_clip(value, rect, lines: false)
+      paths = Paths.coerce(value, scale: common_scale(value))
+      return Paths.new([], scale: paths.scale) if paths.empty?
+
+      rectangle = quantize_rectangle(rect, paths.scale)
+      rectangle_pointer = NativeMemory.int64_pointer(rectangle)
+      function = lines ? :RectClipLines64 : :RectClip64
+      pointer = Native.send(function, rectangle_pointer, NativeMemory.paths_pointer(paths))
+      NativeMemory.read_paths(pointer, scale: paths.scale)
+    ensure
+      NativeMemory.dispose_pointer(pointer)
+    end
+
+    def minkowski_sum(pattern, path, closed: true)
+      minkowski(:MinkowskiSum64, pattern, path, closed: closed)
+    end
+
+    def minkowski_difference(pattern, path, closed: true)
+      minkowski(:MinkowskiDiff64, pattern, path, closed: closed)
+    end
+
+    def minkowski(function, pattern, path, closed:)
+      scale = common_scale(pattern, path)
+      pattern_path = single_path(pattern, scale, "pattern")
+      target_path = single_path(path, scale, "path")
+      return Paths.new([], scale: scale) if pattern_path.empty? || target_path.empty?
+
+      pattern_reference = NativeMemory.pointer_reference(NativeMemory.path_pointer(pattern_path))
+      path_reference = NativeMemory.pointer_reference(NativeMemory.path_pointer(target_path))
+      pointer = Native.send(function, pattern_reference, path_reference, closed)
+      NativeMemory.read_paths(pointer, scale: scale)
+    ensure
+      NativeMemory.dispose_pointer(pointer)
+    end
+    private_class_method :minkowski
+
+    def single_path(value, scale, name)
+      paths = Paths.coerce(value, scale: scale)
+      raise ArgumentError, "#{name} must contain exactly one path" unless paths.size == 1
+
+      paths.first
+    end
+    private_class_method :single_path
+
+    def common_scale(*values)
+      scales = []
+      values.each { |value| collect_scales(value, scales) }
+      scales.uniq!
+      raise ScaleError, "all operands must use the same scale" if scales.length > 1
+
+      scales.first || Clipper2.default_scale
+    end
+    private_class_method :common_scale
+
+    def collect_scales(value, scales)
+      case value
+      when Path, Paths
+        scales << value.scale
+      when Array
+        value.each { |entry| collect_scales(entry, scales) }
+      end
+    end
+    private_class_method :collect_scales
+
+    def normalize_clip_type(type)
+      type.to_sym == :intersect ? :intersection : type
+    rescue NoMethodError
+      type
+    end
+    private_class_method :normalize_clip_type
+
+    def enum_value(values, value, name)
+      key = value.to_sym
+      values.fetch(key)
+    rescue NoMethodError, KeyError
+      raise ArgumentError, "unknown #{name} #{value.inspect}; expected one of #{values.keys.join(', ')}"
+    end
+    private_class_method :enum_value
+
+    def scaled_distance(value, scale, name, allow_zero: false)
+      numeric = Float(value)
+      valid_sign = allow_zero ? numeric >= 0 : !numeric.zero?
+      unless numeric.finite? && valid_sign
+        raise ArgumentError, "#{name} must be #{allow_zero ? 'non-negative' : 'non-zero'} and finite"
+      end
+
+      scaled = numeric * scale
+      unless scaled.finite? && scaled.between?(NativeMemory::MIN_COORD, NativeMemory::MAX_COORD)
+        raise RangeError, "#{name} exceeds Clipper2's supported coordinate range"
+      end
+      scaled
+    rescue TypeError, ArgumentError => error
+      raise error if error.is_a?(Clipper2::RangeError) || error.message.start_with?(name)
+
+      raise ArgumentError, "#{name} must be numeric"
+    end
+    private_class_method :scaled_distance
+
+    def positive_float(value, name)
+      numeric = Float(value)
+      raise ArgumentError, "#{name} must be positive and finite" unless numeric.finite? && numeric.positive?
+
+      numeric
+    rescue TypeError, ArgumentError
+      raise ArgumentError, "#{name} must be positive and finite"
+    end
+    private_class_method :positive_float
+
+    def quantize_rectangle(rect, scale)
+      values = rect.respond_to?(:to_a) ? rect.to_a : []
+      raise ArgumentError, "rect must be [min_x, min_y, max_x, max_y]" unless values.length == 4
+
+      rectangle = values.map { |coordinate| Quantizer.quantize(coordinate, scale) }
+      rectangle.each do |coordinate|
+        unless coordinate.between?(NativeMemory::MIN_COORD, NativeMemory::MAX_COORD)
+          raise RangeError, "rect exceeds Clipper2's supported coordinate range"
+        end
+      end
+      unless rectangle[2] > rectangle[0] && rectangle[3] > rectangle[1]
+        raise ArgumentError, "rect must have positive width and height"
+      end
+
+      rectangle
+    end
+    private_class_method :quantize_rectangle
+
+    def raise_native_error(status)
+      message = NATIVE_ERRORS.fetch(status, "Clipper2 returned an unknown native error")
+      raise NativeError.new(message, code: status)
+    end
+    private_class_method :raise_native_error
+  end
+
+end

data/lib/clipper2/path.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Clipper2
+  class Path
+    include Enumerable
+
+    class << self
+      def [](*points, scale: Clipper2.default_scale)
+        points = points.first if points.length == 1 && point_collection?(points.first)
+        new(points, scale: scale)
+      end
+
+      def from_coords(coords, scale:)
+        new(nil, scale: scale, coords: coords)
+      end
+
+      def point?(value)
+        value.respond_to?(:size) && value.respond_to?(:[]) && value.size == 2 &&
+          value[0].is_a?(Numeric) && value[1].is_a?(Numeric)
+      end
+
+      def point_collection?(value)
+        value.is_a?(Array) && (value.empty? || value.all? { |point| point?(point) })
+      end
+    end
+
+    attr_reader :scale
+
+    def initialize(points = nil, scale: Clipper2.default_scale, coords: nil)
+      @scale = Quantizer.validate_scale(scale)
+      @coords = coords ? validate_coords(coords) : quantize_points(points || [])
+      @coords.freeze
+      freeze
+    end
+
+    def each
+      return enum_for(__method__) unless block_given?
+
+      @coords.each_slice(2) do |x, y|
+        yield [Quantizer.dequantize(x, scale), Quantizer.dequantize(y, scale)]
+      end
+      self
+    end
+
+    def [](index)
+      x = @coords.fetch(index * 2)
+      y = @coords.fetch((index * 2) + 1)
+      [Quantizer.dequantize(x, scale), Quantizer.dequantize(y, scale)]
+    end
+
+    def size
+      @coords.length / 2
+    end
+    alias length size
+
+    def empty?
+      @coords.empty?
+    end
+
+    def area
+      return 0.0 if size < 3
+
+      twice_area = 0
+      each_quantized_edge do |x1, y1, x2, y2|
+        twice_area += (x1 * y2) - (x2 * y1)
+      end
+      twice_area.fdiv(2 * scale * scale)
+    end
+
+    def orientation
+      area.negative? ? :cw : :ccw
+    end
+
+    def reverse
+      reversed = @coords.each_slice(2).to_a.reverse.flatten
+      self.class.from_coords(reversed, scale: scale)
+    end
+
+    def bounds
+      return nil if empty?
+
+      xs = @coords.each_slice(2).map(&:first)
+      ys = @coords.each_slice(2).map(&:last)
+      [xs.min, ys.min, xs.max, ys.max].map { |value| Quantizer.dequantize(value, scale) }
+    end
+
+    def contains?(point)
+      return false if size < 3
+
+      px, py = Quantizer.quantize_point(point, scale)
+      inside = false
+
+      each_quantized_edge do |x1, y1, x2, y2|
+        return true if point_on_segment?(px, py, x1, y1, x2, y2)
+        next if (y1 > py) == (y2 > py)
+
+        lhs = (x2 - x1) * (py - y1)
+        rhs = (px - x1) * (y2 - y1)
+        inside = !inside if y2 > y1 ? lhs > rhs : lhs < rhs
+      end
+
+      inside
+    end
+
+    def to_packed
+      to_a.flatten.pack("e*")
+    end
+
+    def simplify(epsilon)
+      PathSimplifier.call(self, epsilon)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && scale == other.scale && @coords == other.quantized_coords
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, scale, @coords].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} scale=#{scale.inspect} points=#{to_a.inspect}>"
+    end
+
+    protected
+
+    def quantized_coords
+      @coords
+    end
+
+    private
+
+    def quantize_points(points)
+      unless points.respond_to?(:each)
+        raise ArgumentError, "points must be an enumerable of [x, y] pairs"
+      end
+
+      points.flat_map { |point| Quantizer.quantize_point(point, scale) }
+    end
+
+    def validate_coords(coords)
+      values = Array(coords)
+      raise ArgumentError, "quantized coordinates must contain x/y pairs" if values.length.odd?
+
+      values.each do |value|
+        unless value.is_a?(Integer) && value.between?(Quantizer::INT64_MIN, Quantizer::INT64_MAX)
+          raise RangeError, "quantized coordinate must be a signed int64"
+        end
+      end
+      values.dup
+    end
+
+    def each_quantized_edge
+      previous_x = @coords[-2]
+      previous_y = @coords[-1]
+      @coords.each_slice(2) do |x, y|
+        yield previous_x, previous_y, x, y
+        previous_x = x
+        previous_y = y
+      end
+    end
+
+    def point_on_segment?(px, py, x1, y1, x2, y2)
+      cross = ((px - x1) * (y2 - y1)) - ((py - y1) * (x2 - x1))
+      return false unless cross.zero?
+
+      px.between?(*[x1, x2].minmax) && py.between?(*[y1, y2].minmax)
+    end
+  end
+end

data/lib/clipper2/path_simplifier.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Clipper2
+  module PathSimplifier
+    module_function
+
+    def call(path, epsilon)
+      threshold = Float(epsilon)
+      raise ArgumentError, "epsilon must be non-negative and finite" unless threshold.finite? && threshold >= 0
+      return path if path.size <= 3
+
+      quantized_threshold = (threshold * path.scale).round
+      points = path.send(:quantized_coords).each_slice(2).to_a
+      remove_redundant_points(points, quantized_threshold**2)
+      Path.from_coords(points.flatten, scale: path.scale)
+    rescue TypeError, ArgumentError => error
+      raise error if error.message.start_with?("epsilon")
+
+      raise ArgumentError, "epsilon must be non-negative and finite"
+    end
+
+    def remove_redundant_points(points, threshold_squared)
+      loop do
+        removable = points.each_index.find do |index|
+          previous = points[(index - 1) % points.length]
+          current = points[index]
+          following = points[(index + 1) % points.length]
+          point_segment_distance_within?(current, previous, following, threshold_squared)
+        end
+        break unless removable && points.length > 3
+
+        points.delete_at(removable)
+      end
+    end
+    private_class_method :remove_redundant_points
+
+    def point_segment_distance_within?(point, start_point, end_point, threshold_squared)
+      segment_x = end_point[0] - start_point[0]
+      segment_y = end_point[1] - start_point[1]
+      point_x = point[0] - start_point[0]
+      point_y = point[1] - start_point[1]
+      segment_squared = (segment_x * segment_x) + (segment_y * segment_y)
+      return squared_distance(point, start_point) <= threshold_squared if segment_squared.zero?
+
+      projection = (point_x * segment_x) + (point_y * segment_y)
+      return squared_distance(point, start_point) <= threshold_squared if projection <= 0
+      return squared_distance(point, end_point) <= threshold_squared if projection >= segment_squared
+
+      cross = (point_x * segment_y) - (point_y * segment_x)
+      (cross * cross) <= threshold_squared * segment_squared
+    end
+    private_class_method :point_segment_distance_within?
+
+    def squared_distance(first, second)
+      x = first[0] - second[0]
+      y = first[1] - second[1]
+      (x * x) + (y * y)
+    end
+    private_class_method :squared_distance
+  end
+end

data/lib/clipper2/paths.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Clipper2
+  class Paths
+    include Enumerable
+
+    class << self
+      def [](*paths, scale: nil)
+        if paths.length == 1 && paths.first.is_a?(Array) && !Path.point_collection?(paths.first)
+          paths = paths.first
+        end
+        new(paths, scale: scale)
+      end
+
+      def coerce(value, scale: nil)
+        return new([], scale: scale) if value.nil?
+        return coerce_paths(value, scale) if value.is_a?(Paths)
+        return new([value], scale: scale) if value.is_a?(Path)
+        return new([value], scale: scale) if Path.point_collection?(value)
+
+        new(value, scale: scale)
+      end
+
+      def from_coords(paths_coords, scale:)
+        paths = paths_coords.map { |coords| Path.from_coords(coords, scale: scale) }
+        new(paths, scale: scale)
+      end
+
+      private
+
+      def coerce_paths(value, scale)
+        return value if scale.nil? || scale == value.scale
+
+        raise ScaleError, "cannot use Paths at scale #{value.scale.inspect} with scale #{scale.inspect}"
+      end
+    end
+
+    attr_reader :scale
+
+    def initialize(paths = [], scale: nil)
+      path_specs = normalize_input(paths)
+      inferred_scale = infer_scale(path_specs)
+      @scale = Quantizer.validate_scale(scale || inferred_scale || Clipper2.default_scale)
+      @paths = path_specs.map { |path| coerce_path(path) }.freeze
+      freeze
+    end
+
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      @paths.each(&block)
+      self
+    end
+
+    def [](index)
+      @paths[index]
+    end
+
+    def size
+      @paths.size
+    end
+    alias length size
+
+    def empty?
+      @paths.empty?
+    end
+
+    def area
+      sum(&:area)
+    end
+
+    def absolute_area
+      sum { |path| path.area.abs }
+    end
+
+    def bounds
+      path_bounds = filter_map(&:bounds)
+      return nil if path_bounds.empty?
+
+      [
+        path_bounds.map { |bounds| bounds[0] }.min,
+        path_bounds.map { |bounds| bounds[1] }.min,
+        path_bounds.map { |bounds| bounds[2] }.max,
+        path_bounds.map { |bounds| bounds[3] }.max
+      ]
+    end
+
+    def simplify(epsilon)
+      self.class.new(map { |path| path.simplify(epsilon) }, scale: scale)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && scale == other.scale && @paths == other.to_a
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, scale, @paths].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} scale=#{scale.inspect} paths=#{@paths.inspect}>"
+    end
+
+    private
+
+    def normalize_input(paths)
+      return paths.to_a if paths.is_a?(Paths)
+      return [] if paths.respond_to?(:empty?) && paths.empty?
+      return [paths] if paths.is_a?(Path) || Path.point_collection?(paths)
+      return paths.to_a if paths.respond_to?(:to_a)
+
+      raise ArgumentError, "paths must be Path objects or point collections"
+    end
+
+    def infer_scale(paths)
+      scales = paths.grep(Path).map(&:scale).uniq
+      raise ScaleError, "all paths must use the same scale" if scales.length > 1
+
+      scales.first
+    end
+
+    def coerce_path(path)
+      return Path.new(path, scale: scale) unless path.is_a?(Path)
+      return path if path.scale == scale
+
+      raise ScaleError, "cannot use Path at scale #{path.scale.inspect} with scale #{scale.inspect}"
+    end
+  end
+end

data/lib/clipper2/quantizer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Clipper2
+  module Quantizer
+    INT64_MIN = -(2**63)
+    INT64_MAX = (2**63) - 1
+
+    module_function
+
+    def validate_scale(scale)
+      value = Float(scale)
+      raise ScaleError, "scale must be finite and greater than zero" unless value.finite? && value.positive?
+
+      scale.is_a?(Integer) ? scale : value
+    rescue ArgumentError, TypeError
+      raise ScaleError, "scale must be a finite positive number"
+    end
+
+    def quantize(value, scale)
+      numeric = Float(value)
+      raise RangeError, "coordinate must be finite" unless numeric.finite?
+
+      scaled = numeric * scale
+      raise RangeError, "coordinate exceeds the int64 range at scale #{scale}" unless scaled.finite?
+
+      quantized = scaled.round
+      unless quantized.between?(INT64_MIN, INT64_MAX)
+        raise RangeError, "coordinate exceeds the int64 range at scale #{scale}"
+      end
+
+      quantized
+    rescue ArgumentError, TypeError
+      raise RangeError, "coordinate must be a finite number"
+    end
+
+    def dequantize(value, scale)
+      value.fdiv(scale)
+    end
+
+    def quantize_point(point, scale)
+      unless point.respond_to?(:[]) && point.respond_to?(:size) && point.size == 2
+        raise ArgumentError, "point must contain exactly two coordinates"
+      end
+
+      [quantize(point[0], scale), quantize(point[1], scale)]
+    end
+  end
+end