Polygons and paths

ngon(x, y, radius, sides=5, orientation=0, action=:nothing;
    vertices=false, reversepath=false)

Find the vertices of a regular n-sided polygon centered at x, y with circumradius radius.

ngon() draws the shapes: if you just want the raw points, use keyword argument vertices=true, which returns the array of points instead. Compare:

ngon(0, 0, 4, 4, 0, vertices=true) # returns the polygon's points:

    4-element Array{Luxor.Point,1}:
    Luxor.Point(2.4492935982947064e-16,4.0)
    Luxor.Point(-4.0,4.898587196589413e-16)
    Luxor.Point(-7.347880794884119e-16,-4.0)
    Luxor.Point(4.0,-9.797174393178826e-16)

whereas

ngon(0, 0, 4, 4, 0, :close) # draws a polygon

ngon(centerpos, radius, sides=5, orientation=0, action=:nothing;
    vertices=false,
    reversepath=false)

Draw a regular polygon centered at point centerpos:

ngonside(centerpoint::Point, sidelength::Real, sides::Int=5, orientation=0,
    action=:nothing; kwargs...)

Draw a regular polygon centered at centerpoint with sides sides of length sidelength.

star(xcenter, ycenter, radius, npoints=5, ratio=0.5, orientation=0, action=:nothing;
    vertices = false,
    reversepath=false)

Make a star. ratio specifies the height of the smaller radius of the star relative to the larger.

Use vertices=true to return the vertices of a star instead of drawing it.

star(center, radius, npoints=5, ratio=0.5, orientation=0, action=:nothing;
    vertices = false, reversepath=false)

Draw a star centered at a position:

Draw a polygon.

poly(pointlist::AbstractArray{Point, 1}, action = :nothing;
    close=false,
    reversepath=false)

A polygon is an Array of Points. By default poly() doesn't close or fill the polygon, to allow for clipping.

poly(bbox::BoundingBox, :action; kwargs...)

Make a polygon around the BoundingBox in bbox.

prettypoly(points::AbstractArray{Point, 1}, action=:nothing, vertexfunction = () -> circle(O, 2, :stroke);
    close=false,
    reversepath=false,
    vertexlabels = (n, l) -> ()
    )

Draw the polygon defined by points, possibly closing and reversing it, using the current parameters, and then evaluate the vertexfunction function at every vertex of the polygon.

The default vertexfunction draws a 2 pt radius circle.

To mark each vertex of a polygon with a randomly colored filled circle:

p = star(O, 70, 7, 0.6, 0, vertices=true)
prettypoly(p, :fill, () ->
    begin
        randomhue()
        circle(O, 10, :fill)
    end,
    close=true)

The optional keyword argument vertexlabels lets you supply a function with two arguments that can access the current vertex number and the total number of vertices at each vertex. For example, you can label the vertices of a triangle "1 of 3", "2 of 3", and "3 of 3" using:

prettypoly(triangle, :stroke,
    vertexlabels = (n, l) -> (text(string(n, " of ", l))))

prettypoly(bbox::BoundingBox, :action; kwargs...)

Make a decorated polygon around the BoundingBox in bbox.

Simplify a polygon:

simplify(pointlist::AbstractArray, detail=0.1)

detail is the smallest permitted distance between two points in pixels.

isinside(p, pol; allowonedge=false)

Is a point p inside a polygon pol? Returns true if it does, or false.

This is an implementation of the Hormann-Agathos (2001) Point in Polygon algorithm.

The classification of points lying on the edges of the target polygon, or coincident with its vertices is not clearly defined, due to rounding errors or arithmetical inadequacy. By default these will generate errors, but you can suppress these by setting allowonedge to true.

isinside(p::Point, bb:BoundingBox)

Returns true if pt is inside bounding box bb.

randompoint(lowpt, highpt)

Return a random point somewhere inside the rectangle defined by the two points.

randompoint(lowx, lowy, highx, highy)

Return a random point somewhere inside a rectangle defined by the four values.

randompointarray(lowpt, highpt, n)

Return an array of n random points somewhere inside the rectangle defined by two points.

randompointarray(lowx, lowy, highx, highy, n)

Return an array of n random points somewhere inside the rectangle defined by the four coordinates.

polysplit(p, p1, p2)

Split a polygon into two where it intersects with a line. It returns two polygons:

(poly1, poly2)

This doesn't always work, of course. For example, a polygon the shape of the letter "E" might end up being divided into more than two parts.

Sort a polygon by finding the nearest point to the starting point, then the nearest point to that, and so on.

polysortbydistance(p, starting::Point)

You can end up with convex (self-intersecting) polygons, unfortunately.

Sort the points of a polygon into order. Points are sorted according to the angle they make with a specified point.

polysortbyangle(pointlist::AbstractArray, refpoint=minimum(pointlist))

The refpoint can be chosen, but the minimum point is usually OK too:

polysortbyangle(parray, polycentroid(parray))

Find the centroid of simple polygon.

polycentroid(pointlist)

Returns a point. This only works for simple (non-intersecting) polygons.

You could test the point using isinside().

polysmooth(points, radius, action=:action; debug=false)

Make a closed path from the points and round the corners by making them arcs with the given radius. Execute the action when finished.

The arcs are sometimes different sizes: if the given radius is bigger than the length of the shortest side, the arc can't be drawn at its full radius and is therefore drawn as large as possible (as large as the shortest side allows).

The debug option also draws the construction circles at each corner.

offsetpoly(path::AbstractArray{Point, 1}, d)

Return a polygon that is offset from a polygon by d units.

The incoming set of points path is treated as a polygon, and another set of points is created, which form a polygon lying d units away from the source poly.

Polygon offsetting is a topic on which people have written PhD theses and published academic papers, so this short brain-dead routine will give good results for simple polygons up to a point (!). There are a number of issues to be aware of:

• very short lines tend to make the algorithm 'flip' and produce larger lines

• small polygons that are counterclockwise and larger offsets may make the new polygon appear the wrong side of the original

• very sharp vertices will produce even sharper offsets, as the calculated intersection point veers off to infinity

• duplicated adjacent points might cause the routine to scratch its head and wonder how to draw a line parallel to them

polyfit(plist::AbstractArray, npoints=30)

Build a polygon that constructs a B-spine approximation to it. The resulting list of points makes a smooth path that runs between the first and last points.

pathtopoly()

Convert the current path to an array of polygons.

Returns an array of polygons.

getpath()

Get the current path and return a CairoPath object, which is an array of element_type and points objects. With the results you can step through and examine each entry:

o = getpath()
for e in o
      if e.element_type == Cairo.CAIRO_PATH_MOVE_TO
          (x, y) = e.points
          move(x, y)
      elseif e.element_type == Cairo.CAIRO_PATH_LINE_TO
          (x, y) = e.points
          # straight lines
          line(x, y)
          strokepath()
          circle(x, y, 1, :stroke)
      elseif e.element_type == Cairo.CAIRO_PATH_CURVE_TO
          (x1, y1, x2, y2, x3, y3) = e.points
          # Bezier control lines
          circle(x1, y1, 1, :stroke)
          circle(x2, y2, 1, :stroke)
          circle(x3, y3, 1, :stroke)
          move(x, y)
          curve(x1, y1, x2, y2, x3, y3)
          strokepath()
          (x, y) = (x3, y3) # update current point
      elseif e.element_type == Cairo.CAIRO_PATH_CLOSE_PATH
          closepath()
      else
          error("unknown CairoPathEntry " * repr(e.element_type))
          error("unknown CairoPathEntry " * repr(e.points))
      end
  end

getpathflat()

Get the current path, like getpath() but flattened so that there are no Bèzier curves.

Returns a CairoPath which is an array of element_type and points objects.

bezier(t, A::Point, A1::Point, B1::Point, B::Point)

Return the result of evaluating the Bezier cubic curve function, t going from 0 to 1, starting at A, finishing at B, control points A1 (controlling A), and B1 (controlling B).

bezier′(t, A::Point, A1::Point, B1::Point, B::Point)

Return the first derivative of the Bezier function.

bezier′(t, A::Point, A1::Point, B1::Point, B::Point)

Return the second derivative of Bezier function.

beziercurvature(t, A::Point, A1::Point, B1::Point, B::Point)

Return the curvature of the Bezier curve at t ([0-1]), given start and end points A and B, and control points A1 and B1. The value (kappa) will typically be a value between -0.001 and 0.001 for points with coordinates in the 100-500 range.

κ(t) is the curvature of the curve at point t, which for a parametric planar curve is:

The radius of curvature, or the radius of an osculating circle at a point, is 1/κ(t). Values of 1/κ will typically be in the range -1000 to 1000 for points with coordinates in the 100-500 range.

TODO Fix overshoot...

...The value of kappa can sometimes collapse near 0, returning NaN (and Inf for radius of curvature).

bezierfrompoints(startpoint::Point, pointonline1::Point,
    pointonline2::Point, endpoint::Point)

Given four points, return the Bezier curve that passes through all four points, starting at startpoint and ending at endpoint. The two middle points of the returned BezierPathSegment are the two control points that make the curve pass through the two middle points supplied.

bezierfrompoints(ptslist::Array{Point, 1})

Given four points, return the Bezier curve that passes through all four points.

bezierpathtopoly(bezierpath::BezierPath; steps=10)

Convert a Bezier path (an array of Bezier segments, where each segment is a tuple of four points: anchor1, control1, control2, anchor2) to a polygon.

To make a Bezier path, use makebezierpath() on a polygon.

The steps optional keyword determines how many line sections are used for each path.

bezierstroke(point1, point2, width=0.0)

Return a BezierPath, a stroked version of a straight line between two points.

It wil have 2 or 6 Bezier path segments that define a brush or pen shape. If width is 0, the brush shape starts and ends at a point. Otherwise the brush shape starts and ends with the thick end.

To draw it, use eg drawbezierpath(..., :fill).

beziertopoly(bpseg::BezierPathSegment; steps=10)

Convert a Bezier segment to a polygon (an array of points).

drawbezierpath(bezierpath::BezierPath, action=:none;
    close=true)

Draw the Bézier path, and apply the action, such as :none, :stroke, :fill, etc. By default the path is closed.

drawbezierpath(bps::BezierPathSegment, action=:none;
    close=false)

Draw the Bézier path segment, and apply the action, such as :none, :stroke, :fill, etc. By default the path is open.

makebezierpath(pgon::AbstractArray{Point, 1}; smoothing=1)

Return a Bézier path (a BezierPath) that represents a polygon (an array of points). The Bézier path is an array of segments (tuples of 4 points); each segment contains the four points that make up a section of the entire Bézier path. smoothing determines how closely the curve follows the polygon. A value of 0 returns a straight-sided path; as values move above 1 the paths deviate further from the original polygon's edges.

pathtobezierpaths(
    ; flat=true)

Convert the current path (which may consist of one or more paths) to an array of Bezier paths. Each Bezier path is, in turn, an array of path segments. Each path segment is a tuple of four points. A straight line is converted to a Bezier segment in which the control points are set to be the the same as the end points.

If flat is true, use getpathflat() rather than getpath().

Example

This code draws the Bezier segments and shows the control points as "handles", like a vector-editing program might.

@svg begin
    fontface("MyanmarMN-Bold")
    st = "goo"
    thefontsize = 100
    fontsize(thefontsize)
    sethue("red")
    fontsize(thefontsize)
    textpath(st)
    nbps = pathtobezierpaths()
    for nbp in nbps
        setline(.15)
        sethue("grey50")
        drawbezierpath(nbp, :stroke)
        for p in nbp
            sethue("red")
            circle(p[2], 0.16, :fill)
            circle(p[3], 0.16, :fill)
            line(p[2], p[1], :stroke)
            line(p[3], p[4], :stroke)
            if p[1] != p[4]
                sethue("black")
                circle(p[1], 0.26, :fill)
                circle(p[4], 0.26, :fill)
            end
        end
    end
end

setbezierhandles(bps::BezierPathSegment;
        angles  = [0.05, -0.1],
        handles = [0.3, 0.3])

Return a new Bezier path segment with new locations for the Bezier control points in the Bezier path segment bps.

angles are the two angles that the "handles" make with the line direciton.

handles are the lengths of the "handles". 0.3 is a typical value.

setbezierhandles(bezpath::BezierPath;
        angles=[0 .05, -0.1],
        handles=[0.3, 0.3])

Return a new Bezierpath with new locations for the Bezier control points in every Bezier path segment of the BezierPath in bezpath.

angles are the two angles that the "handles" make with the line direciton.

handles are the lengths of the "handles". 0.3 is a typical value.

shiftbezierhandles(bps::BezierPathSegment;
    angles=[0.1, -0.1], handles=[1.1, 1.1])

Return a new BezierPathSegment that modifies the Bezier path in bps by moving the control handles. The values in angles increase the angle of the handles; the values in handles modifies the lengths: 1 preserves the length, 0.5 halves the length of the handles, 2 doubles them.

findbeziercontrolpoints(previouspt::Point,
    pt1::Point,
    pt2::Point,
    nextpt::Point;
    smooth_value=0.5)

Find the Bézier control points for the line between pt1 and pt2, where the point before pt1 is previouspt and the next point after pt2 is nextpt.

brush(pt1, pt2, width=10;
    strokes=10,
    minwidth=0.01,
    maxwidth=0.03,
    twist = -1,
    lowhandle  = 0.3,
    highhandle = 0.7,
    randomopacity = true,
    tidystart = false,
    action = :fill)

Draw a composite brush stroke made up of some randomized individual filled Bezier paths.

polysample(p::AbstractArray{Point, 1}, npoints::Int64;
        closed=true)

Sample the polygon p, returning a polygon with npoints to represent it. The first sampled point is:

 1/`npoints` * `perimeter of p`

away from the original first point of p.

If npoints is the same as length(p) the returned polygon is the same as the original, but the first point finishes up at the end (so new=circshift(old, 1)).

If closed is true, the entire polygon (including the edge joining the last point to the first point) is sampled.

polyperimeter(p::AbstractArray{Point, 1}; closed=true)

Find the total length of the sides of polygon p.

polyportion(p::AbstractArray{Point, 1}, portion=0.5; closed=true, pdist=[])

Return a portion of a polygon, starting at a value between 0.0 (the beginning) and 1.0 (the end). 0.5 returns the first half of the polygon, 0.25 the first quarter, 0.75 the first three quarters, and so on.

If you already have a list of the distances between each point in the polygon (the "polydistances"), you can pass them in pdist, otherwise they'll be calculated afresh, using polydistances(p, closed=closed).

Use the complementary polyremainder() function to return the other part.

polyremainder(p::AbstractArray{Point, 1}, portion=0.5; closed=true, pdist=[])

Return the rest of a polygon, starting at a value between 0.0 (the beginning) and 1.0 (the end). 0.5 returns the last half of the polygon, 0.25 the last three quarters, 0.75 the last quarter, and so on.

If you already have a list of the distances between each point in the polygon (the "polydistances"), you can pass them in pdist, otherwise they'll be calculated afresh, using polydistances(p, closed=closed).

Use the complementary polyportion() function to return the other part.

polydistances(p::AbstractArray{Point, 1}; closed=true)

Return an array of the cumulative lengths of a polygon.

nearestindex(polydistancearray, value)

Return a tuple of the index of the largest value in polydistancearray less than value, and the difference value. Array is assumed to be sorted.

(Designed for use with polydistances()).

polyarea(p::AbstractArray)

Find the area of a simple polygon. It works only for polygons that don't self-intersect.

intersectlinepoly(pt1::Point, pt2::Point, C)

Return an array of the points where a line between pt1 and pt2 crosses polygon C.

polyintersections(S::AbstractArray{Point, 1}, C::AbstractArray{Point, 1})

Return an array of the points in polygon S plus the points where polygon S crosses polygon C. Calls intersectlinepoly().