# jcoglan/sylvester

Document the Polygon class.

1 parent 8a4fbfa commit 124050cef19aa543ff778342a630b944ccefe8c1 committed Mar 18, 2012
Showing with 249 additions and 50 deletions.
1. +224 −0 site/src/pages/api/polygon.haml
3. +24 −50 src/polygon.js
 @@ -0,0 +1,224 @@ += partial 'api_navigation' + +:plain +

Class: Polygon

+ +

Sylvester version: 0.2.0 onwards

+ +

Class methods: + create +

+ +

Instance methods: + area, + centroid, + contains, + copyVertices, + dup, + hasEdgeContaining, + inspect, + isTriangle, + projectionOn, + rotate, + scale, + toTriangles, + translate, + v +

+ +

Overview

+ +

The Polygon class is designed to model planar regions whose + boundary is defined by a set of coplanar points, in 3 dimensions. It is + possible to model polygons containing holes by having the boundary + ‘cut in’ to reach the hole – see + create().

+ +

Class methods

+ + +

Polygon.create([v1, v2, ...]) 0.2.0

+ +

Creates a Polygon instance using a set of points + v1, v2Vectors or arrays, and will be + coerced into 3-dimensional Vectors internally.

+ +

For example, this creates a 4×4 square in the x-y plane.

+ +
var p = Polygon.create([[0,0],[4,0],[4,4],[0,4]]);
+ +

You can create polygons with holes in them by having the boundary + ‘cut in’ to reach the hole, for example consider this shape:

+ +
3 --  o-----------o
+        |           |
+  2 --  |   o---o   |
+        |   |   |   |
+  1 --  |   o---o   |
+        |           |
+  0 --  o-----------o
+
+        |   |   |   |
+        0   1   2   3
+ +

This can be modelled by joining the inside boundary to the outside, for + example:

+ +
3 --  o-----------o
+        |           |
+  2 --  |   o---o   |
+        |   |   |   |
+  1 --  |   o---o---o
+        |           |
+  0 --  o-----------o
+
+        |   |   |   |
+        0   1   2   3
+ +

You can think of this as a polygon with no holes, whose boundary touches + itself. You might create this shape like so:

+ +
var p = Polygon.create([
+    [0,0], [3,0], [3,1], [1,1],
+    [1,2], [2,2], [2,1], [3,1],
+    [3,3], [0,3]
+  ]);
+ +

Instance methods

+ + +

area() 0.2.0

+ +

Returns the area of the polygon. It correctly accounts for polygons + containing holes, for example:

+ +
var square = Polygon.create([[0,0],[4,0],[4,4],[0,4]]);
+
+  square.area() // -> 16
+
+  var ring = Polygon.create([
+    [0,0], [3,0], [3,1], [1,1],
+    [1,2], [2,2], [2,1], [3,1],
+    [3,3], [0,3]
+  ]);
+
+  ring.area() // -> 8
+ + +

centroid() 0.2.0

+ +

Returns the centroid, or ‘centre of mass’ of the polygon as + a Vector.

+ + +

contains(point) 0.2.0

+ +

Returns true iff the given + Vector point is + strictly inside the receiver, not on one of its edges or inside a hole + contained within the boundary.

+ +
var ring = Polygon.create([
+    [0,0], [3,0], [3,1], [1,1],
+    [1,2], [2,2], [2,1], [3,1],
+    [3,3], [0,3]
+  ]);
+
+  ring.contains([0.5, 0.5]) // -> true    -- strictly inside
+  ring.contains([1.0, 1.0]) // -> false   -- on a vertex
+  ring.contains([1.5, 1.5]) // -> false   -- in a hole
+ + +

copyVertices() 0.2.0

+ +

Copies all the Vector objects + that make the vertices of the receiver. If the receiver was created through + toTriangles(), for example, it may + be sharing vertex objects with another Polygon, and will be + transformed when the other is transformed. Copying the vertices means the + receiver can be transformed independently.

+ + +

dup() 0.2.0

+ +

Returns a copy of the receiver. The vertices themselves are not copied, + only the list that defines the polygon boundary. This means that if the + original is mutated by changing its vertices, the duplicate will be + transformed in the same way. Use + copyVertices() to get a completely + new set of vertex objects.

+ + +

hasEdgeContaining(point) 0.2.0

+ +

Returns true iff the given + Vector point lies + on any line segment or vertex on the polygon’s boundary, including + edges used as cuts to form holes.

+ + +

inspect() 0.2.0

+ +

Returns a string representation of the receiver, useful for debugging.

+ +
var p = Polygon.create([[0,0],[4,0],[4,4]]);
+  p.inspect() // -> "[0, 0, 0] -> [4, 0, 0] -> [4, 4, 0]"
+ + +

isTriangle() 0.2.0

+ +

Returns true iff the polygon has exactly 3 vertices.

+ + +

projectionOn(plane) 0.2.0

+ +

Returns a new Polygon representing the projection of the + receiver onto the given Plane.

+ + +

rotate(angle, axis) 0.1.0

+ +

Rotates the receiver by angle radians + about the Line axis. + Rotations are performed in a right-handed fashion about the line’s + direction.

+ +

Note that while some other classes’ rotate() method + returns a new object, this method mutates and returns the receiver.

+ + +

scale(k, point) 0.1.0

+ +

Scales all the vertices in the receiver by a factor k relative + to the Vector + point.

+ +

Note that while some other classes’ scale() method + returns a new object, this method mutates and returns the receiver.

+ + +

toTriangles() 0.2.0

+ +

Splits the receiver into triangles and returns them as an array of + triangular Polygons. These polygons share their vertex + Vector objects with the receiver, so for example if you call + toTriangles() and then + rotate() the receiver, all the triangles + will be rotated as well.

+ + +

translate(vector) 0.1.0

+ +

Translates the receiver by adding the given vector to all its + vertices.

+ +

Note that while some other classes’ translate() method + returns a new object, this method mutates and returns the receiver.

+ + +

v(i) 0.2.0

+ +

Returns the Vector for the + ith vertex, numbered from 1.

 @@ -5,4 +5,5 @@
• Line
• Line.Segment
• Plane
• +
• Polygon