clipper2 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8e374bfe4ee5209b63a97203c8c675d132609b35b008b2ec829241cf7f94063
+  data.tar.gz: 7634829ff829a134af6885b75490629c3b8d1ea64301cefcce1a2055560d45fb
+SHA512:
+  metadata.gz: 1864bb0788c3417a00e52e4cb4b7fd7d7b11b3aebf708760ec09852cc2796e0b9328fd983ef7b42be8314f7feb1e85ef67bee41176e38c74d7784255ece21a15
+  data.tar.gz: 3dd05a3210852de65e99bdf0f64da9e0e6f38dd7d1cbd07b1f47aa0f16ebd6d220eaf929870a547d4e3e6365cecb5f9ee0406f97b8ad602e4562d803b68340da

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# Clipper2
+
+Clipper2 brings robust 2D polygon clipping and offsetting to Ruby. It wraps Angus Johnson's
+[Clipper2](https://github.com/AngusJohnson/Clipper2) C export API with FFI and keeps all native
+geometry on a quantized signed-integer grid.
+
+The gem supports union, intersection, difference, XOR, open paths, polygon and line offsets,
+rectangle clipping, Minkowski sums, point containment, path simplification, and dependency-free
+Earcut triangulation into GPU-ready buffers.
+
+## Installation
+
+Add the gem to your bundle:
+
+```bash
+bundle add clipper2
+```
+
+Or install it directly:
+
+```bash
+gem install clipper2
+```
+
+Platform gems contain a precompiled shared library. When a platform gem is unavailable, the
+source gem builds the pinned Clipper2 C++17 sources with Ruby's standard extension toolchain and
+therefore requires a C++ compiler and `make`. CMake is used by maintainers to build platform gems.
+
+## Coordinate model
+
+Ruby callers use ordinary numeric coordinates. `Path` quantizes them to signed 64-bit integers
+using a scale and restores floats when enumerated:
+
+```ruby
+require "clipper2"
+
+Clipper2.default_scale = 1_000 # 0.001 coordinate-unit precision
+
+path = Clipper2::Path[[0, 0], [10, 0], [10, 10], [0, 10]]
+path.to_a       # => [[0.0, 0.0], [10.0, 0.0], [10.0, 10.0], [0.0, 10.0]]
+path.area       # => 100.0 (signed; positive is counter-clockwise)
+path.orientation # => :ccw
+path.bounds     # => [0.0, 0.0, 10.0, 10.0]
+```
+
+Every `Paths` collection owns one scale. Operations between different scales raise
+`Clipper2::ScaleError`; coordinates that cannot be represented safely raise
+`Clipper2::RangeError`. Choose a scale that gives the precision you need without making
+`coordinate * scale` unnecessarily large.
+
+## Boolean operations
+
+All convenience methods accept a `Path`, `Paths`, one raw point array, or an array of raw paths,
+and return `Clipper2::Paths`:
+
+```ruby
+a = Clipper2::Path[[0, 0], [10, 0], [10, 10], [0, 10]]
+b = Clipper2::Path[[5, 0], [15, 0], [15, 10], [5, 10]]
+
+Clipper2.union(a, b)
+Clipper2.intersect(a, b, fill_rule: :non_zero)
+Clipper2.difference(a, b)
+Clipper2.xor(a, b)
+```
+
+Fill rules are `:even_odd`, `:non_zero`, `:positive`, and `:negative`. Clipper2 intentionally
+handles self-intersecting input according to the selected fill rule.
+
+For open subject paths, use the general API. It returns closed and open solutions separately:
+
+```ruby
+line = Clipper2::Path[[-5, 5], [15, 5]]
+closed, open = Clipper2.boolean(:intersection, [], a, subject_open: line)
+```
+
+## Offsets and clipping
+
+```ruby
+grown = Clipper2.inflate(a, 2.5, join: :round, end_type: :polygon)
+shrunk = Clipper2.inflate(a, -1.0)
+
+open_line = Clipper2::Path[[0, 0], [10, 0]]
+stroke = Clipper2.inflate(open_line, 3.0, join: :round, end_type: :round)
+
+inside = Clipper2.rect_clip(grown, [0, 0, 12, 12])
+line_segments = Clipper2.rect_clip_lines(open_line, [2, -1, 8, 1])
+```
+
+Join types are `:square`, `:bevel`, `:round`, and `:miter`. End types are `:polygon`, `:joined`,
+`:butt`, `:square`, and `:round`. `arc_tolerance` defaults to `0.25` public coordinate units and
+is scaled automatically.
+
+Minkowski sums and differences use the same integer path representation:
+
+```ruby
+pattern = Clipper2::Path[[0, 0], [1, 0], [1, 1], [0, 1]]
+Clipper2.minkowski_sum(pattern, a)
+Clipper2.minkowski_difference(pattern, a)
+```
+
+## Path utilities
+
+```ruby
+path.contains?([5, 5]) # boundary points are included
+path.reverse
+path.simplify(0.05)
+path.to_packed          # little-endian float32 x/y pairs
+```
+
+`Paths#simplify` applies the same tolerance to each member.
+
+## Packed triangulation
+
+`Clipper2.triangulate` uses the bundled pure Ruby Earcut implementation. Counter-clockwise rings
+are outer contours and clockwise rings contained by an outer contour are holes:
+
+```ruby
+outer = Clipper2::Path[[0, 0], [10, 0], [10, 10], [0, 10]]
+hole = Clipper2::Path[[2, 2], [2, 8], [8, 8], [8, 2]] # clockwise
+
+mesh = Clipper2.triangulate(Clipper2::Paths[outer, hole])
+mesh.indices     # little-endian packed u32 triangle indices
+mesh.vertices    # little-endian packed float32 x/y vertices
+mesh.index_count
+mesh.vertex_count
+
+indices, vertices = mesh # array destructuring is also supported
+```
+
+Every emitted triangle is counter-clockwise in a y-up coordinate system. The two packed strings
+can be uploaded directly by renderers that accept raw buffers. See
+[`examples/rugl_mesh.rb`](examples/rugl_mesh.rb) and
+[`examples/larb_transform.rb`](examples/larb_transform.rb).
+
+## Empty input and errors
+
+Empty inputs return empty `Paths` or an empty `Triangulation`. Invalid options and rectangles
+raise `ArgumentError`; scale, range, codec, triangulation, and native failures use subclasses of
+`Clipper2::Error`.
+
+Native arrays are always copied once into Ruby and released through Clipper2's matching
+`DisposeArray64` export.
+
+## Development
+
+Ruby 3.2 or newer, CMake, and a C++17 compiler are required.
+
+```bash
+bundle install
+bundle exec rake              # generated-binding check, native build, and specs
+bundle exec rake native:build # native library only
+bundle exec rake native:gem   # platform gem in pkg/
+bundle exec rake build        # source gem in pkg/
+```
+
+`ext/clipper2/generate_bindings.rb` derives enum values and export names from the vendored headers.
+Run `bundle exec rake bindings:generate` after updating Clipper2 and commit the generated Ruby file.
+
+The SVG boolean demo is available at [`examples/svg_boolean.rb`](examples/svg_boolean.rb).
+
+## Licenses
+
+The Ruby wrapper is MIT licensed. Vendored Clipper2 2.0.1 is distributed under the Boost Software
+License 1.0, and the Ruby Earcut port carries Mapbox's ISC license. The corresponding notices are
+included in `LICENSE.txt`, `licenses/CLIPPER2-BSL-1.0.txt`, and `licenses/EARCUT-ISC.txt`.

data/examples/larb_transform.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "clipper2"
+require "larb"
+
+vectors = [
+  Larb::Vec2.new(0, 0),
+  Larb::Vec2.new(10, 0),
+  Larb::Vec2.new(10, 10),
+  Larb::Vec2.new(0, 10)
+]
+
+path = Clipper2::Path.new(vectors.map(&:to_a))
+outline = Clipper2.inflate(path, 1.5, join: :round)
+larb_paths = outline.map { |ring| ring.map { |x, y| Larb::Vec2.new(x, y) } }
+
+puts "#{larb_paths.sum(&:length)} transformed outline vertices"

data/examples/rugl_mesh.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "clipper2"
+require "rugl"
+
+polygon = Clipper2::Path[[-0.8, -0.7], [0.8, -0.7], [0.35, 0.0], [0.8, 0.7], [-0.8, 0.7]]
+mesh = Clipper2.triangulate(polygon)
+
+rugl = Rugl.create(width: 800, height: 600, title: "Clipper2 packed mesh")
+positions = rugl.buffer(data: mesh.vertices, type: :float)
+elements = rugl.elements(data: mesh.indices.unpack("L<*"), type: :uint32, primitive: :triangles)
+
+draw = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    void main() { gl_Position = vec4(position, 0.0, 1.0); }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    out vec4 color;
+    void main() { color = vec4(0.15, 0.7, 0.55, 1.0); }
+  GLSL
+  attributes: { position: positions },
+  elements: elements
+)
+
+rugl.frame do
+  rugl.clear(color: [0.03, 0.04, 0.08, 1.0])
+  draw.call
+end
+
+rugl.destroy

data/examples/svg_boolean.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "clipper2"
+
+subject = Clipper2::Path[[20, 20], [180, 20], [180, 140], [20, 140]]
+clip = Clipper2::Path[[80, 0], [220, 80], [80, 160]]
+result = Clipper2.difference(subject, clip)
+
+polygon = lambda do |path, attributes|
+  points = path.map { |x, y| "#{x},#{y}" }.join(" ")
+  %(<polygon points="#{points}" #{attributes} />)
+end
+
+layers = []
+layers << polygon.call(subject, 'fill="#4f46e5" fill-opacity="0.18" stroke="#4f46e5"')
+layers << polygon.call(clip, 'fill="#e11d48" fill-opacity="0.18" stroke="#e11d48"')
+result.each { |path| layers << polygon.call(path, 'fill="#059669" fill-opacity="0.55" stroke="#047857"') }
+
+svg = <<~SVG
+  <svg xmlns="http://www.w3.org/2000/svg" width="240" height="180" viewBox="0 0 240 180">
+    <rect width="100%" height="100%" fill="white" />
+    #{layers.join("\n  ")}
+  </svg>
+SVG
+
+output = ARGV.fetch(0, "clipper2-boolean.svg")
+File.write(output, svg)
+puts "wrote #{output}"

data/ext/clipper2/CMakeLists.txt

@@ -0,0 +1,27 @@
+cmake_minimum_required(VERSION 3.15)
+project(clipper2_native LANGUAGES CXX)
+
+set(VENDOR_DIR "${CMAKE_CURRENT_SOURCE_DIR}/vendor")
+set(CLIPPER2_SOURCES
+  "${VENDOR_DIR}/src/clipper.engine.cpp"
+  "${VENDOR_DIR}/src/clipper.offset.cpp"
+  "${VENDOR_DIR}/src/clipper.rectclip.cpp"
+  "${VENDOR_DIR}/src/clipper.triangulation.cpp"
+)
+
+add_library(clipper2_native MODULE clipper2_native.cpp ${CLIPPER2_SOURCES})
+target_compile_features(clipper2_native PRIVATE cxx_std_17)
+target_include_directories(clipper2_native PRIVATE "${VENDOR_DIR}/include")
+set_target_properties(clipper2_native PROPERTIES PREFIX "")
+
+set(RUBY_EXTENSION_SUFFIX "" CACHE STRING "Ruby-loadable library suffix including the leading dot")
+if(RUBY_EXTENSION_SUFFIX)
+  set_target_properties(clipper2_native PROPERTIES SUFFIX "${RUBY_EXTENSION_SUFFIX}")
+endif()
+
+option(CLIPPER2_BUILD_MEMORY_CHECK "Build the native allocation disposal check" OFF)
+if(CLIPPER2_BUILD_MEMORY_CHECK)
+  add_executable(clipper2_memory_check memory_check.cpp ${CLIPPER2_SOURCES})
+  target_compile_features(clipper2_memory_check PRIVATE cxx_std_17)
+  target_include_directories(clipper2_memory_check PRIVATE "${VENDOR_DIR}/include")
+endif()

data/ext/clipper2/clipper2_native.cpp

@@ -0,0 +1,2 @@
+#include <clipper2/clipper.h>
+#include <clipper2/clipper.export.h>

data/ext/clipper2/extconf.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+vendor = File.expand_path("vendor", __dir__)
+headers = File.join(vendor, "include")
+sources = File.join(vendor, "src")
+
+abort "Clipper2 vendored headers are missing" unless File.file?(File.join(headers, "clipper2", "clipper.export.h"))
+
+$CPPFLAGS = "-I#{headers.shellescape} #{$CPPFLAGS}"
+$VPATH << sources
+$srcs = %w[
+  clipper2_native.cpp
+  clipper.engine.cpp
+  clipper.offset.cpp
+  clipper.rectclip.cpp
+  clipper.triangulation.cpp
+]
+
+if /mswin|msvc/ =~ RUBY_PLATFORM
+  $CXXFLAGS = "/std:c++17 /EHsc /utf-8 #{$CXXFLAGS}"
+else
+  $CXXFLAGS = "-std=c++17 #{$CXXFLAGS}"
+end
+
+create_makefile("clipper2/clipper2_native")

data/ext/clipper2/generate_bindings.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+ROOT = File.expand_path("../..", __dir__)
+HEADERS = File.join(__dir__, "vendor", "include", "clipper2")
+OUTPUT = File.join(ROOT, "lib", "clipper2", "generated.rb")
+
+ENUMS = {
+  "CLIP_TYPES" => ["clipper.engine.h", "ClipType"],
+  "FILL_RULES" => ["clipper.core.h", "FillRule"],
+  "JOIN_TYPES" => ["clipper.offset.h", "JoinType"],
+  "END_TYPES" => ["clipper.offset.h", "EndType"]
+}.freeze
+
+def snake_case(name)
+  name.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
+end
+
+def parse_enum(file_name, enum_name)
+  source = File.read(File.join(HEADERS, file_name))
+  body = source.match(/enum\s+class\s+#{Regexp.escape(enum_name)}(?:\s*:\s*[^\{]+)?\s*\{([^}]+)\}/m)&.[](1)
+  abort "Unable to find #{enum_name} in #{file_name}" unless body
+
+  next_value = 0
+  body.split(",").to_h do |entry|
+    name, explicit_value = entry.gsub(%r{//.*}, "").strip.split("=", 2).map(&:strip)
+    next_value = Integer(explicit_value, 0) if explicit_value
+    pair = [snake_case(name).to_sym, next_value]
+    next_value += 1
+    pair
+  end
+end
+
+def parse_exports
+  source = File.read(File.join(HEADERS, "clipper.export.h"))
+  source.scan(/EXTERN_DLL_EXPORT\s+[^;\{]+?\b(\w+)\s*\(/m).flatten.uniq.sort - ["__declspec"]
+end
+
+def parse_version
+  source = File.read(File.join(HEADERS, "clipper.version.h"))
+  source.match(/CLIPPER2_VERSION\s*=\s*"([^"]+)"/)&.[](1) || abort("Unable to find Clipper2 version")
+end
+
+def render
+  constants = ENUMS.map do |constant, (file_name, enum_name)|
+    values = parse_enum(file_name, enum_name).map { |name, value| "      #{name.inspect} => #{value}" }.join(",\n")
+    "    #{constant} = {\n#{values}\n    }.freeze"
+  end.join("\n\n")
+  exports = parse_exports.map { |name| "      :#{name}" }.join(",\n")
+
+  <<~RUBY
+    # frozen_string_literal: true
+
+    # Generated by ext/clipper2/generate_bindings.rb. Do not edit by hand.
+    module Clipper2
+      module Generated
+        UPSTREAM_VERSION = #{parse_version.inspect}
+
+    #{constants}
+
+        NATIVE_EXPORTS = [
+    #{exports}
+        ].freeze
+      end
+    end
+  RUBY
+end
+
+generated = render
+if ARGV.include?("--check")
+  abort "#{OUTPUT} is out of date; run #{__FILE__}" unless File.file?(OUTPUT) && File.read(OUTPUT) == generated
+else
+  File.write(OUTPUT, generated)
+end

data/ext/clipper2/memory_check.cpp

@@ -0,0 +1,48 @@
+#include "clipper2/clipper.h"
+#include "clipper2/clipper.export.h"
+
+#include <cstdint>
+
+namespace {
+
+constexpr std::uint8_t kUnion = 2;
+constexpr std::uint8_t kNonZero = 1;
+constexpr std::uint8_t kRound = 2;
+constexpr std::uint8_t kPolygon = 0;
+
+std::int64_t subject[] = {
+    12, 1, 4, 0,
+    0, 0, 100, 0, 100, 100, 0, 100,
+};
+
+std::int64_t clip[] = {
+    12, 1, 4, 0,
+    50, -20, 120, -20, 120, 80, 50, 80,
+};
+
+}  // namespace
+
+int main() {
+  using namespace Clipper2Lib;
+
+  constexpr int kIterations = 500;
+  const CRect64 rectangle{0, 0, 100, 100};
+
+  for (int iteration = 0; iteration < kIterations; ++iteration) {
+    CPaths64 closed = nullptr;
+    CPaths64 open = nullptr;
+    if (BooleanOp64(kUnion, kNonZero, subject, nullptr, clip, closed, open) != 0) {
+      return 1;
+    }
+
+    CPaths64 inflated = InflatePaths64(closed, 3.0, kRound, kPolygon);
+    CPaths64 clipped = RectClip64(rectangle, inflated);
+
+    DisposeArray64(clipped);
+    DisposeArray64(inflated);
+    DisposeArray64(open);
+    DisposeArray64(closed);
+  }
+
+  return 0;
+}

data/ext/clipper2/vendor/LICENSE

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/ext/clipper2/vendor/UPSTREAM.md

@@ -0,0 +1,11 @@
+# Vendored Clipper2
+
+- Upstream: https://github.com/AngusJohnson/Clipper2
+- Version: 2.0.1
+- Commit: `f9c5eb6e14a59f6f5d65fbfb3564519a561cf4fd`
+- License: Boost Software License 1.0 (see `LICENSE`)
+
+Only `CPP/Clipper2Lib/include/clipper2` and `CPP/Clipper2Lib/src` are vendored. The exported C API
+is compiled once by `clipper2_native.cpp`. That translation unit includes `clipper.h` before
+`clipper.export.h` because the upstream export header uses Minkowski declarations without including
+them itself.