Add unfold function for point arrays (#83)

* Add unfold function for point arrays

* Make unfold interface same as reflect_across_line

* Add unfold to docs

Author: parrangoiz

CONTRIBUTING.md

@@ -35,7 +35,7 @@ To send us a pull request, please:
  5. Send us a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
-GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
+GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
 ## Finding contributions to work on

docs/src/polygons.md

@@ -77,4 +77,5 @@ In addition to other generic [entity styles](entitystyles.md) like `NoRender`, `
     points
     sweep_poly
     gridpoints_in_polygon
+    unfold
 ```

src/DeviceLayout.jl

@@ -383,6 +383,7 @@ import .Polygons:
     radius,
     rounded_corner,
     sweep_poly,
+    unfold,
     union2d
 export Polygons,
     Polygon,
@@ -405,6 +406,7 @@ export Polygons,
     radius,
     rounded_corner,
     sweep_poly,
+    unfold,
     union2d
 
 include("align.jl")

src/polygons.jl

@@ -78,6 +78,7 @@ export circle,
     radius,
     rounded_corner,
     sweep_poly,
+    unfold,
     union2d
 
 const USCALE = 1.0 * Unitful.fm
@@ -1527,6 +1528,36 @@ function uniqueray(v::Vector{Point{T}}) where {T <: Real}
     return Ray(Point(minx, miny), Point(minx, miny - 1)), indv
 end
 
+"""
+    unfold(v::Vector{Point{T}}, direction; through_pt=nothing) where {T}
+    unfold(v::Vector{Point{T}}, p0, p1) where {T}
+
+Return a vector of twice the length of `v`, where the first half is `v` and the second half
+is `v` in reverse order and reflected about an axis.
+
+This can be used to construct polygons that have a mirror symmetry. The symmetry axis
+can be defined in either of two ways: as a line with a given `direction` passing through
+point `through_pt` (defaults to origin), or by two points `p0`, `p1`. `direction` can
+be passed either as an angle or as a `Point` representing a vector.
+
+As a trivial example, to draw a centered square:
+
+```julia
+uy = Point(0μm, 1μm) # could also be passed as 90°
+pts = [Point(-1μm, -1μm), Point(-1μm, 1μm)]
+square = Polygon(unfold(pts, uy))
+```
+"""
+function unfold(v::Vector{Point{T}}, direction; through_pt=nothing) where {T}
+    N = length(v)
+    _reflect = Reflection(direction; through_pt=through_pt)
+    v_ref = [_reflect(v[N - i + 1]) for i in eachindex(v)]
+    return vcat(v, v_ref)
+end
+function unfold(v::Vector{Point{T}}, p0, p1) where {T}
+    return unfold(v, p1 - p0; through_pt=p0)
+end
+
 """
     orientation(p::Polygon)
 

test/tests.jl

@@ -263,6 +263,39 @@ end
     @test iszero(@allocated tr2 = convert(ScaledIsometry{Nothing}, tr))
     @test convert(ScaledIsometry{Point{Int}}, tr).origin isa Point{Int}
     @test hash(ScaledIsometry()) == hash(ScaledIsometry(Point(0, 0)))
+
+    # Point vector unfolding
+    ux = Point(1, 0)
+    uy = Point(0, 1)
+    # Ints
+    pts = [Point(-1, 0), Point(-1, 1)]
+    @test unfold(pts, uy) ≈ [Point(-1, 0), Point(-1, 1), Point(1, 1), Point(1, 0)]
+    # Floats
+    pts = [Point(-1.0, 0.0), Point(-1.0, 1.0)]
+    @test unfold(pts, uy) ≈
+          [Point(-1.0, 0.0), Point(-1.0, 1.0), Point(1.0, 1.0), Point(1.0, 0.0)]
+    # Mixed Ints/Floats
+    pts = [Point(-1, 0), Point(-1, 1)]
+    @test unfold(pts, Point(0.0, 1.0)) ≈
+          [Point(-1.0, 0.0), Point(-1.0, 1.0), Point(1.0, 1.0), Point(1.0, 0.0)]
+    # x-axis reflection
+    pts = [Point(-1, -1), Point(1, -1)]
+    @test unfold(pts, ux) ≈ [Point(-1, -1), Point(1, -1), Point(1, 1), Point(-1, 1)]
+    # With units
+    pts = [Point(-1μm, 0μm), Point(-1μm, 1μm)]
+    @test unfold(pts, uy) ≈
+          [Point(-1μm, 0μm), Point(-1μm, 1μm), Point(1μm, 1μm), Point(1μm, 0μm)]
+    @test unfold(pts, uy * μm) ≈
+          [Point(-1μm, 0μm), Point(-1μm, 1μm), Point(1μm, 1μm), Point(1μm, 0μm)]
+    # With angle instead of vector
+    @test unfold(pts, 90°) ≈
+          [Point(-1μm, 0μm), Point(-1μm, 1μm), Point(1μm, 1μm), Point(1μm, 0μm)]
+    # Axis by two points
+    @test unfold(pts, Point(0μm, 0μm), Point(0μm, 1μm)) ≈
+          [Point(-1μm, 0μm), Point(-1μm, 1μm), Point(1μm, 1μm), Point(1μm, 0μm)]
+    # Less trivial case (off-center axis)
+    @test unfold(pts, Point(1μm, 0μm), Point(1μm, 1μm)) ≈
+          [Point(-1μm, 0μm), Point(-1μm, 1μm), Point(3μm, 1μm), Point(3μm, 0μm)]
 end
 
 @testset "Polygon rendering" begin