Clamping points to boxes (#715)

* include new methods for clamping points to boxes

* avoid internal fields, use patch version, update test for complete coverage

---------

Co-authored-by: Mark Baum <>

Project.toml

@@ -1,7 +1,7 @@
 name = "Meshes"
 uuid = "eacbb407-ea5a-433e-ab97-5258b1ca43fa"
 authors = ["Júlio Hoffimann and contributors"]
-version = "0.40.0"
+version = "0.40.1"
 
 [deps]
 Bessels = "0e736298-9ec6-45e8-9647-e4fc86a2fe38"

docs/make.jl

@@ -51,6 +51,7 @@ makedocs(
         "algorithms/simplification.md",
         "algorithms/intersection.md",
         "algorithms/clipping.md",
+        "algorithms/clamping.md",
         "algorithms/merging.md",
         "algorithms/winding.md",
         "algorithms/sideof.md",

docs/src/algorithms/clamping.md

@@ -0,0 +1,31 @@
+# Clamping
+
+Meshes adds methods to Julia's built-in `clamp` function. The additional methods clamp points to the edges of a box in any number of dimensions. The target points and boxes must have the same number of dimensions and the same numeric type.
+
+```@docs
+clamp(point::Point{Dim,T}, box::Box{Dim,T}) where {Dim,T}
+clamp(points::PointSet{Dim,T}, box::Box{Dim,T}) where {Dim,T}
+```
+
+```@example clamping
+using Meshes # hide
+import CairoMakie as Mke # hide
+
+# set of 2D points to clamp
+points = PointSet(rand(2, 100))
+
+# 2D box defining the clamping boundaries
+box = Box((0.25, 0.25), (0.75, 0.75))
+
+# clamp point coordinates to the box edges
+clamped = clamp(points, box)
+
+fig = Mke.Figure(size=(800, 400))
+ax = Mke.Axis(fig[1,1], title="unclamped", aspect=1, limits=(0,1,0,1))
+viz!(ax, box)
+viz!(ax, points, color=:black, pointsize=6)
+ax = Mke.Axis(fig[1,2], title="clamped", aspect=1, limits=(0,1,0,1))
+viz!(ax, box)
+viz!(ax, clamped, color=:black, pointsize=6)
+fig
+```

docs/src/index.md

@@ -56,7 +56,7 @@ We are happy to improve the ecosystem to meet user's needs.
 
 Get the latest stable release with Julia's package manager:
 
-```julia
+```
 ] add Meshes
 ```
 

src/Meshes.jl

@@ -87,6 +87,7 @@ include("measures.jl")
 include("boundary.jl")
 include("merging.jl")
 include("clipping.jl")
+include("clamping.jl")
 include("intersections.jl")
 include("complement.jl")
 include("simplification.jl")

src/clamping.jl

@@ -0,0 +1,20 @@
+"""
+    clamp(point, box)
+
+Clamp the coordinates of a [`Point`](@ref) to the edges of a [`Box`](@ref). For each dimension, coordinates outside of the box are moved to the nearest edge of the box. The point and box must have an equal number of dimensions."""
+function Base.clamp(point::Point{Dim,T}, box::Box{Dim,T})::Point{Dim,T} where {Dim,T}
+  x = coordinates(point)
+  lo = coordinates(minimum(box))
+  hi = coordinates(maximum(box))
+  ntuple(Dim) do i
+    clamp(x[i], lo[i], hi[i])
+  end |> Point
+end
+
+"""
+    clamp(pointset, box)
+
+Clamp each point in a [`PointSet`](@ref) to the edges of a [`Box`](@ref), returning a new set of points."""
+function Base.clamp(points::PointSet{Dim,T}, box::Box{Dim,T})::PointSet{Dim,T} where {Dim,T}
+  PointSet(map(point -> clamp(point, box), points))
+end

test/clamping.jl

@@ -0,0 +1,13 @@
+@testset "Clamping" begin
+  box = Box((zero(T), zero(T)), (one(T), one(T)))
+  @test clamp(P2(0.5, 0.5), box) == P2(0.5, 0.5)
+  @test clamp(P2(-1, 0.5), box) == P2(0, 0.5)
+  @test clamp(P2(0.5, -1), box) == P2(0.5, 0)
+  @test clamp(P2(2, 0.5), box) == P2(1, 0.5)
+  @test clamp(P2(0.5, 2), box) == P2(0.5, 1)
+  @test clamp(P2(2, 2), box) == P2(1, 1)
+  @test clamp(P2(-1, -1), box) == P2(0, 0)
+
+  points = PointSet(P2(0.5, 0.5), P2(-1, 0.5), P2(0.5, 2))
+  @test clamp(points, box) == PointSet(P2(0.5, 0.5), P2(0, 0.5), P2(0.5, 1))
+end

test/runtests.jl

@@ -98,6 +98,7 @@ testfiles = [
   "orientation.jl",
   "merging.jl",
   "clipping.jl",
+  "clamping.jl",
   "intersections.jl",
   "complement.jl",
   "simplification.jl",