agt 0.0.1

data/app/assets/javascripts/agt/geom/mixins/surface.coffee

@@ -0,0 +1,55 @@
+namespace('agt.geom')
+# Public: Every closed geometry should have the properties of a surface.
+#
+# These properties are:
+#
+# - **Acreage** - A `Surface` object can express its surface in px<sup>2</sup>.
+# - **Inclusiveness** - A `Surface` object can `contains` other geometries
+#   inside the bounds of its shape. It also can returns coordinates inside
+#   its shape randomly.
+#
+# ```coffeescript
+# class DummySurface
+#   @include agt.geom.Surface
+#
+#   # Your surface implementation
+# ```
+# <script>window.exampleKey = 'geometry'</script>
+class agt.geom.Surface
+
+  ### Public ###
+
+  # Abstract: Returns the surface of the geometry in px<sup>2</sup>.
+  #
+  # Returns a {Number}.
+  acreage: -> null
+
+  # Abstract: Returns a random [Point]{agt.geom.Point} with coordinates
+  # inside the geometry shape.
+  #
+  # <script>drawGeometry(exampleKey, {surface: true})</script>
+  #
+  # Returns a [Point]{agt.geom.Point}.
+  randomPointInSurface: -> null
+
+  # Abstract: Tests if the passed-in coordinates are inside the geometry shape.
+  #
+  # <script>drawGeometry(exampleKey, {contains: true})</script>
+  #
+  # x - Either a {Number} for the x coordinate or a [Point]{agt.geom.Point}.
+  # y - A {Number} for the y coordinate, used when a {Number} was passed for
+  #     the x coordinate as well.
+  #
+  # Returns a {Boolean}.
+  contains: (x, y) -> null
+
+  # Tests if the passed-in geometry is completely contained inside the
+  # current geometry shape.
+  #
+  # <script>drawContainsGeometry(exampleKey)</script>
+  #
+  # geometry - The [Geometry]{agt.geom.Geometry} to test.
+  #
+  # Returns a {Boolean}.
+  containsGeometry: (geometry) ->
+    geometry.points().every (point) => @contains point

data/app/assets/javascripts/agt/geom/mixins/triangulable.coffee

@@ -0,0 +1,112 @@
+namespace('agt.geom')
+# Public: The `Triangulable` mixin provides the {::triangles} method, allowing
+# closed geometries to returns the [Triangles]{agt.geom.Triangle} that compose
+# it.
+#
+# <script>window.exampleKey = 'geometry'</script>
+class agt.geom.Triangulable
+  @include agt.mixins.Memoizable
+
+  ### Public ###
+
+  # Returns the triangles that forms the geometry surface.
+  #
+  # <script>drawGeometry(exampleKey, {triangles: true})</script>
+  #
+  # Returns an {Array} of [Triangles]{agt.geom.Triangle}.
+  triangles: ->
+    return @memoFor 'triangles' if @memoized 'triangles'
+
+    vertices = @points()
+    vertices.pop()
+    indices = triangulate vertices
+    triangles = []
+    for i in [0..indices.length / 3 -1]
+      index = i * 3
+      a = vertices[indices[index]]
+      b = vertices[indices[index+1]]
+      c = vertices[indices[index+2]]
+      triangles.push new agt.geom.Triangle a, b, c
+
+    @memoize 'triangles', triangles
+
+  arrayCopy = (arrayTo, arrayFrom) -> arrayTo[i] = n for n,i in arrayFrom
+
+  pointInTriangle = (pt, v1, v2, v3) ->
+    denom = (v1.y - v3.y) * (v2.x - v3.x) +
+            (v2.y - v3.y) * (v3.x - v1.x)
+    b1 = ((pt.y - v3.y) * (v2.x - v3.x) +
+          (v2.y - v3.y) * (v3.x - pt.x)) / denom
+    b2 = ((pt.y - v1.y) * (v3.x - v1.x) +
+          (v3.y - v1.y) * (v1.x - pt.x)) / denom
+    b3 = ((pt.y - v2.y) * (v1.x - v2.x) +
+          (v1.y - v2.y) * (v2.x - pt.x)) / denom
+    return false if b1 < 0 or b2 < 0 or b3 < 0
+    true
+
+  polyArea = (pts) ->
+    sum = 0
+    i = 0
+    l = pts.length
+
+    for i in [0..l-1]
+      sum += pts[i].x * pts[(i + 1) % l].y - pts[(i + 1) % l].x * pts[i].y
+
+    sum / 2
+
+  triangulate = (vertices) ->
+    return if vertices.length < 4
+
+    safeGuard = 0
+    maxSafeGuard = 100
+
+    pts = vertices
+    refs = (i for n,i in pts)
+    ptsArea = []
+    i = 0
+    l = refs.length
+
+    while i < l
+      ptsArea[i] = pts[refs[i]].clone()
+      ++i
+    pArea = polyArea(ptsArea)
+    cr = []
+    nr = []
+    arrayCopy cr, refs
+    while cr.length > 3
+      i = 0
+      l = cr.length
+
+      while i < l
+        r1 = cr[i % l]
+        r2 = cr[(i + 1) % l]
+        r3 = cr[(i + 2) % l]
+        v1 = pts[r1]
+        v2 = pts[r2]
+        v3 = pts[r3]
+        ok = true
+        j = (i + 3) % l
+
+        while j isnt i
+          ptsArea = [v1, v2, v3]
+          tArea = polyArea(ptsArea)
+          if (pArea < 0 and tArea > 0) or
+             (pArea > 0 and tArea < 0) or
+             pointInTriangle(pts[cr[j]], v1, v2, v3)
+            ok = false
+            break
+          j = (j + 1) % l
+
+          safeGuard += 1
+          if safeGuard > maxSafeGuard
+            break
+
+        if ok
+          nr.push r1, r2, r3
+          cr.splice (i + 1) % l, 1
+          break
+        ++i
+    nr.push.apply nr, cr[0..2]
+    triangulated = true
+
+    return nr

data/app/assets/javascripts/agt/geom/point.coffee

@@ -0,0 +1,454 @@
+namespace('agt.geom')
+
+# Public: A `Point` represent a location in a two-dimensional space.
+#
+# A point with coordinates (0,0) can be constructed with:
+#
+# ```coffeescript
+# new Point
+# new Point 0, 0
+# new Point x: 0, y: 0
+# ```
+#
+# **Note:** Any functions in agt that accept a `Point` object also allow
+# to use numbers instead, this is obviously also the case in the `Point`
+# class. For more details about how to achieve the same behavior in your own
+# functions please refer to the {.pointFrom} method.
+#
+# ### Included Mixins
+#
+# - [agt.mixins.Cloneable](../../../files/mixins/cloneable.coffee.html)
+# - [agt.mixins.Equatable](../../../files/mixins/equatable.coffee.html)
+# - [agt.mixins.Formattable](../../../files/mixins/formattable.coffee.html)
+# - [agt.mixins.Sourcable](../../../files/mixins/sourcable.coffee.html)
+class agt.geom.Point
+  @include agt.mixins.Equatable('x', 'y')
+  @include agt.mixins.Formattable('Point','x', 'y')
+  @include agt.mixins.Sourcable('agt.geom.Point', 'x', 'y')
+  @include agt.mixins.Cloneable()
+
+  ### Public: Static methods ###
+
+  # Returns `true` if the passed-in object pass the requirments
+  # to be a point. Valid points are objects that possess a x and
+  # a y property.
+  #
+  # ```coffeescript
+  # Point.isPoint new Point  # true
+  # Point.isPoint x: 0, y: 0 # true
+  # Point.isPoint x: 0       # false
+  # ```
+  #
+  # pt - The point {Object} that will be tested.
+  #
+  # Returns a {Boolean}.
+  @isPoint: (pt) -> pt? and pt.x? and pt.y?
+
+  # Returns a point according to the provided arguments:
+  #
+  # ```coffeescript
+  # translate = (xOrPt, y) ->
+  #   point = Point.pointFrom xOrPt, y
+  # ```
+  #
+  # The first argument can be either an {Object} or a {Number}.
+  # In the case the argument is an object, the function will
+  # extract the x and y values from it. However, if the `strict`
+  # argument is `true`, the function will throw an error if
+  # the object does not have either x or y property:
+  #
+  # ```coffeescript
+  # Point.pointFrom x: 10            # will not throw
+  # Point.pointFrom x: 10, 0, true   # will throw
+  # ```
+  #
+  # In the case the object is incomplete or empty, and with
+  # the strict mode disabled, the missing property will end
+  # being set to `0`.
+  #
+  # ```coffeescript
+  # point = Point.pointFrom x: 10 # {x: 10, y: NaN}
+  # ```
+  #
+  # For further examples, feel free to take a look at the
+  # methods of the `Point` class.
+  #
+  # xOrPt - The x {Number} value or a point-like {Object}.
+  # y - The y {Number} value
+  # strict - A {Boolean} of whether the method raises an exception
+  #          on type mismatch.
+  #
+  # Returns a [Point]{agt.geom.Point} instance.
+  @pointFrom: (xOrPt, y, strict=false) ->
+    x = xOrPt
+    {x,y} = xOrPt if xOrPt? and typeof xOrPt is 'object'
+    @notAPoint [x,y] if strict and (isNaN(x) or isNaN(y))
+    new Point x, y
+
+  # Converts polar coordinates in cartesian coordinates.
+  #
+  # ```coffeescript
+  # Point.polar 90, 10 # [Point(x=0,y=10)]
+  # ```
+  #
+  # angle - A {Number} of the angle in radians.
+  # length - A {Number} of the vector length in pixels.
+  #
+  # Returns a [Point]{agt.geom.Point} instance.
+  @polar: (angle, length=1) -> new Point Math.sin(angle) * length,
+                                         Math.cos(angle) * length
+
+  # Returns a point between `pt1` and `pt2` at a ratio corresponding to `pos`.
+  #
+  # The `Point.interpolate` method supports all the following forms:
+  #
+  # ```coffeescript
+  # # Two points:
+  # Point.interpolate pt1, pt2, pos
+  #
+  # # Two numbers and a Point:
+  # Point.interpolate x1, y1, pt2, pos
+  #
+  # # A Point and then two numbers:
+  # Point.interpolate pt1, x2, y2, pos
+  #
+  # # Four numbers:
+  # Point.interpolate x1, x2, x2, y2, pos
+  # ```
+  #
+  # pt1 - The starting [Point]{agt.geom.Point} of the interpolation.
+  # pt2 - The ending [Point]{agt.geom.Point} of the interpolation.
+  # pos - The amount {Number} of the interpolation.
+  #
+  # Returns a [Point]{agt.geom.Point} instance.
+  @interpolate: (pt1, pt2, pos) ->
+    args = []; args[i] = v for v,i in arguments
+
+    # Utility function that extract a point from `args`
+    # and removes the values it used from it.
+    extract = (args, name) =>
+      pt = null
+      if @isPoint args[0] then pt = args.shift()
+      else if Math.isFloat(args[0]) and Math.isFloat(args[1])
+        pt = new Point args[0], args[1]
+        args.splice 0, 2
+      else @missingPoint args, name
+      pt
+
+    pt1 = extract args, 'first'
+    pt2 = extract args, 'second'
+    pos = parseFloat args.shift()
+    @missingPosition pos if isNaN pos
+
+    dif = pt2.subtract(pt1)
+    new Point pt1.x + dif.x * pos,
+              pt1.y + dif.y * pos
+
+  ### Internal: Class error methods ###
+
+  # Throws an error for a missing position in `Point.interpolate`.
+  @missingPosition: (pos) ->
+    throw new Error "Point.interpolate require a position but #{pos} was given"
+
+  # Throws an error for a missing point in `Point.interpolate`.
+  @missingPoint: (args, pos) ->
+    msg = "Can't find the #{pos} point in Point.interpolate arguments #{args}"
+    throw new Error msg
+
+  # Throws an error for an invalid point in `Point.pointFrom`.
+  @notAPoint: (args) ->
+    throw new Error "#{args} is not a point"
+
+  ### Public ###
+
+  # Whatever is passed to the `Point` constructor, a valid point
+  # is always returned. All invalid properties will be default to `0`.
+  #
+  # A point be constructed with the following forms:
+  #
+  # ```coffeescript
+  # new Point
+  # new Point 0, 0
+  # new Point x: 0, y: 0
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}
+  #     to initialize the point.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  constructor: (x, y) ->
+    y = x.y or y if x?; y = 0 if isNaN y
+    x = x.x or x if x?; x = 0 if isNaN x
+    @x = x
+    @y = y
+
+  # Returns the length of the current vector represented by this point.
+  #
+  # ```coffeescript
+  # length = point.length()
+  # ```
+  #
+  # Returns a {Number}.
+  length: -> Math.sqrt (@x * @x) + (@y * @y)
+
+  # Returns the angle in degrees formed by the vector.
+  #
+  # ```coffeescript
+  # angle = point.angle()
+  # ```
+  #
+  # Returns a {Number}.
+  angle: -> Math.atan2 @y, @x
+
+  # Given a triangle formed by this point, the passed-in point
+  # and the origin (0,0), the `Point::angleWith` method will
+  # return the angle in degrees formed by the two vectors at
+  # the origin.
+  #
+  # ```coffeescript
+  # point1 = new Point 10, 0
+  # point2 = new Point 10, 10
+  # angle = point1.angleWith point2
+  # # angle = 45
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a {Number}.
+  angleWith: (x, y) ->
+    @noPoint 'dot' if not x? and not y?
+    isPoint = @isPoint x
+    y = if isPoint then x.y else y
+    x = if isPoint then x.x else x
+    Point.notAPoint [x,y] if (isNaN(x) or isNaN(y))
+
+    d = @normalize().dot new Point(x,y).normalize()
+
+    Math.acos(Math.abs(d)) * (if d < 0 then -1 else 1)
+
+  # Returns a new point of length `length`.
+  #
+  # ```coffeescript
+  # normalized = point.normalize()
+  # normalized.length() # 1
+  #
+  # normalized = point.normalize(6)
+  # normalized.length() # 6
+  # ```
+  #
+  # length - The {Number} for the new length.
+  #
+  # Returns a [Point]{agt.geom.Point}
+  normalize: (length=1) ->
+    @invalidLength length unless Math.isFloat length
+    l = @length()
+    new Point @x / l * length, @y / l * length
+
+  # Returns a new point resulting of the addition of the
+  # passed-in point to this point.
+  #
+  # ```coffeescript
+  # point = new Point 4, 4
+  # inc = point.add 1, 5
+  # inc = point.add x: 0.2
+  # inc = point.add new Point 1.8, 8
+  # # inc = [Point(x=7,y=17)]
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a new [Point]{agt.geom.Point}.
+  add: (x, y) ->
+    y = x.y or y if x?; y = 0 if isNaN y
+    x = x.x or x if x?; x = 0 if isNaN x
+    new Point @x + x, @y + y
+
+  # Returns a new point that results of the subtraction of the
+  # passed-in point to this point.
+  #
+  # ```coffeescript
+  # point = new Point 4, 4
+  # inc = point.subtract 1, 5
+  # inc = point.subtract x: 0.2
+  # inc = point.subtract new Point 1.8, 8
+  # # inc = [Point(x=2,y=-9)]
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a new [Point]{agt.geom.Point}.
+  subtract: (x, y) ->
+    y = x.y or y if x?; y = 0 if isNaN y
+    x = x.x or x if x?; x = 0 if isNaN x
+    new Point @x - x, @y - y
+
+  # Returns the dot product of this point and the passed-in point.
+  #
+  # ```coffeescript
+  # dot = new Point(5,6).dot(7,8)
+  # # dot = 83
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a {Number}.
+  dot: (x, y) ->
+    @noPoint 'dot' if not x? and not y?
+    isPoint = @isPoint x
+    y = if isPoint then x.y else y
+    x = if isPoint then x.x else x
+    Point.notAPoint [x,y] if (isNaN(x) or isNaN(y))
+    @x * x + @y * y
+
+  # Returns the distance between this point and the passed-in point.
+  #
+  # ```coffeescript
+  # distance = new Point(0,2).distance(2,2)
+  # # distance = 2
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a {Number}.
+  distance: (x, y) ->
+    @noPoint 'distance' if not x? and not y?
+    isPoint = @isPoint x
+    y = if isPoint then x.y else y
+    x = if isPoint then x.x else x
+    Point.notAPoint [x,y] if (isNaN(x) or isNaN(y))
+    @subtract(x,y).length()
+
+  # Returns a new point which is a scaled copy of the current point.
+  #
+  # ```coffeescript
+  # point = new Point 1, 1
+  # scaled = point.scale 2
+  # # scaled = [Point(x=2,y=2)]
+  # ```
+  #
+  # n - The {Number} scale factor for the transformation.
+  #
+  # Returns a new [Point]{agt.geom.Point}.
+  scale: (n) ->
+    @invalidScale n unless Math.isFloat n
+    new Point @x * n, @y * n
+
+  # Returns a new point which is the result of rotating the
+  # current point around the origin (0,0).
+  #
+  # ```coffeescript
+  # point = new Point 10, 0
+  # rotated = point.rotate 90
+  # # rotated = [Point(x=0,y=10)]
+  # ```
+  #
+  # n - The {Number} amount of rotation to apply to the point in radians.
+  #
+  # Returns a new [Point]{agt.geom.Point}.
+  rotate: (n) ->
+    @invalidRotation n unless Math.isFloat n
+    l = @length()
+    a = Math.atan2(@y, @x) + n
+    x = Math.cos(a) * l
+    y = Math.sin(a) * l
+    new Point x, y
+
+  # Returns a new point which is the result of rotating the
+  # current point around the passed-in point.
+  #
+  # ```coffeescript
+  # point = new Point 10, 0
+  # origin = new Point 20, 0
+  # rotated = point.rotateAround origin, 90
+  # # rotated = [Point(x=20,y=-10)]
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number or the {Number} for the angle otherwise.
+  # a - A {Number} for the rotation angle in radians only if the `x` and `y`
+  #     arguments are [Numbers]{Number}.
+  #
+  # Returns a new [Point]{agt.geom.Point}.
+  rotateAround: (x, y, a) ->
+    isPoint = @isPoint x
+    a = y if isPoint
+    y = if isPoint then x.y else y
+    x = if isPoint then x.x else x
+
+    @subtract(x,y).rotate(a).add(x,y)
+
+  # Alias the `Point.isPoint` method in instances.
+  isPoint: Point.isPoint
+
+  # Alias the `Point.pointFrom` method in instances.
+  pointFrom: Point.pointFrom
+
+  # Internal: Returns the two arguments x and y in an array where arguments
+  # that were `NaN` are replaced by `0`.
+  #
+  # x - A {Number} for the x coordinate.
+  # y - A {Number} for the y coordinate.
+  #
+  # Returns an {Array}.
+  defaultToZero: (x, y) ->
+    x = if isNaN x then 0 else x
+    y = if isNaN y then 0 else y
+    [x,y]
+
+  # Copies the values of the passed-in point into this point.
+  #
+  # ```coffeescript
+  # point = new Point
+  # point.paste 1, 7
+  # # point = [Point(x=5,y=7)]
+  #
+  # point.paste new Point 4, 4
+  # # point = [Point(x=4,y=4)]
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns the current [Point]{agt.geom.Point}
+  paste: (x, y) ->
+    return this if not x? and not y?
+    isObject = x? and typeof x is 'object'
+    y = if isObject then x.y else y
+    x = if isObject then x.x else x
+    @x = x unless isNaN x
+    @y = y unless isNaN y
+    this
+
+  ### Internal: Instances error methods ###
+
+  # A generic error helper used by methods that require a point argument
+  # and was called without it.
+  noPoint: (method) ->
+    throw new Error "#{method} was called without arguments"
+
+  # Throws an error for an invalid length in `Point::normalize` method.
+  invalidLength: (l) ->
+    throw new Error "Invalid length #{l} provided"
+
+  # Throws an error for an invalid scale in `Point::scale` method.
+  invalidScale: (s) ->
+    throw new Error "Invalid scale #{s} provided"
+
+  ##### Point::invalidRotation
+  #
+  # Throws an error for an invalid rotation in `Point::rotate`
+  # and `Point::rotateAround` method.
+  invalidRotation: (a) ->
+    throw new Error "Invalid rotation #{a} provided"