agt 0.0.1

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

@@ -0,0 +1,145 @@
+namespace('agt.geom')
+# Public: Every geometry should have the properties of a path. For closed
+# geometries, the path starts and ends at the same point of the geometry
+# shape. This point can vary from one geometry to another.
+#
+# Path properties includes:
+#
+# - **Length** - A path has a {::length} expressed in pixels.
+# - **Positionning** - A path offers to get a [Point]{agt.geom.Point}
+#   along the geometry shape based on a {Number} in the range `0..1`.
+#   With this point it's also possible to retrieve the orientation
+#   of the path as well as the tangent vector at that point.
+#
+# ```coffeescript
+# class DummyPath
+#   @include agt.geom.Path
+#
+#   # Your path implementation
+# ```
+#
+# The default implementation include length and path computations based
+# on the distances between the [points]{agt.geom.Geometry::points}
+# of the geometry.
+#
+# If a more accurate or faster implementation exists the path geometries
+# generally overwrites the default methods with their implementations (see
+# the [Circle]{agt.geom.Circle} or [Rectangle]{agt.geom.Rectangle} classes
+# for real word examples).
+#
+# <script>window.exampleKey = 'geometry'</script>
+#
+class agt.geom.Path
+
+  ### Public ###
+
+  # Returns the length of the path in pixels.
+  #
+  # Returns a {Number}.
+  length: ->
+    sum = 0
+    points = @points()
+    if points.length > 1
+      for i in [1..points.length]
+        sum += points[i-1].distance(points[i])
+    sum
+
+  # Returns the coordinates on the path at the given
+  # {Number} position.
+  #
+  # <script>drawGeometry(exampleKey, {paths: [0.1, 0.45, 0.73]})</script>
+  #
+  # pos - The {Number} between `0` and `1` at which get the path coordinates.
+  # pathBasedOnLength - A {Boolean} of whether the position on the path
+  #                     consider the length of the path segments or not.
+  #                     With the default implementation, when true, each
+  #                     segment will only weight as much as their own length.
+  #                     When false, every segment have the same weight,
+  #                     resulting in a difference in speed when animating
+  #                     an object along a path.
+  #
+  # Returns a [Point]{agt.geom.Point}.
+  pathPointAt: (pos, pathBasedOnLength=true) ->
+    pos = 0 if pos < 0
+    pos = 1 if pos > 1
+    points = @points()
+
+    return points[0] if pos is 0
+    return points[points.length - 1] if pos is 1
+
+    if pathBasedOnLength
+      @walkPathBasedOnLength pos, points
+    else
+      @walkPathBasedOnSegments pos, points
+
+  # Returns the orientation on the path at the given
+  # {Number} position.
+  #
+  # <script>drawGeometry(exampleKey, {paths: [0.1, 0.45, 0.73]})</script>
+  #
+  # pos - The {Number} between `0` and `1` at which get the path coordinates.
+  # pathBasedOnLength - A {Boolean} of whether the position on the path
+  #                     consider the length of the path segments or not.
+  #                     With the default implementation, when true, each
+  #                     segment will only weight as much as their own length.
+  #                     When false, every segment have the same weight,
+  #                     resulting in a difference in speed when animating
+  #                     an object along a path.
+  #
+  # Returns a {Number}.
+  pathOrientationAt: (pos, pathBasedOnLength=true) ->
+    p1 = @pathPointAt pos - 0.01, pathBasedOnLength
+    p2 = @pathPointAt pos + 0.01, pathBasedOnLength
+    d = p2.subtract p1
+
+    return d.angle()
+
+  # Returns the tangent vector at the given {Number} position.
+  #
+  # <script>drawGeometry(exampleKey, {paths: [0.1, 0.45, 0.73]})</script>
+  #
+  # pos - The {Number} between `0` and `1` at which get the path coordinates.
+  # accuracy - A {Number} giving the distance, relatively to the path length,
+  #            at which sample path data around the position to approximate
+  #            the tangent.
+  # pathBasedOnLength - A {Boolean} of whether the position on the path
+  #                     consider the length of the path segments or not.
+  #                     With the default implementation, when true, each
+  #                     segment will only weight as much as their own length.
+  #                     When false, every segment have the same weight,
+  #                     resulting in a difference in speed when animating
+  #                     an object along a path.
+  #
+  # Returns a [Point]{agt.geom.Point}
+  pathTangentAt: (pos, accuracy=1 / 100, pathBasedOnLength=true) ->
+    [pathBasedOnLength, accuracy] = [accuracy, 1/100] if typeof accuracy is 'boolean'
+    @pathPointAt((pos + accuracy) % 1, pathBasedOnLength)
+      .subtract(@pathPointAt((1 + pos - accuracy) % 1), pathBasedOnLength)
+      .normalize(1)
+
+  ### Internal ###
+
+  walkPathBasedOnLength: (pos, points) ->
+    walked = 0
+    length = @length()
+
+    for i in [1..points.length-1]
+      p1 = points[i-1]
+      p2 = points[i]
+      stepLength = p1.distance(p2) / length
+
+      if walked + stepLength > pos
+        innerStepPos = Math.map pos, walked, walked + stepLength, 0, 1
+        return @pointInSegment innerStepPos, [p1, p2]
+
+      walked += stepLength
+
+  walkPathBasedOnSegments: (pos, points) ->
+    segments = points.length - 1
+    pos = pos * segments
+    segment = Math.floor pos
+    segment -= 1 if segment is segments
+    @pointInSegment pos - segment, points[segment..segment+1]
+
+  pointInSegment: (pos, segment) ->
+    segment[0].add segment[1].subtract(segment[0]).scale(pos)

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

@@ -0,0 +1,9 @@
+namespace('agt.geom')
+# Public:
+class agt.geom.Proxyable
+
+  @included: (klass) ->
+    klass.proxy = (targets..., options={}) ->
+      type = options.as
+      for k in targets
+        klass::[k].proxyable = type

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

@@ -0,0 +1,329 @@
+namespace('agt.geom')
+# Public: A spline is a curve made of [vertices]{agt.geom.Point} that
+# controls the resulting geometry.
+#
+# The `Spline` mixin set the ground for all other curves classes such as
+# the [CubicBezier]{agt.geom.CubicBezier} or the
+# [LinearSpline]{agt.geom.LinearSpline} classes.
+#
+# <script>window.exampleKey = 'cubic_spline'</script>
+# <script>drawGeometry('cubic_spline', {highlight: true})</script>
+# <script>drawGeometry('linear_spline', {highlight: true})</script>
+#
+# ```coffeescript
+# class DummySpline
+#   @include agt.geom.Spine(1)
+#
+#   # Your spline implementation
+# ```
+#
+# segmentSize - The {Number} of points constituting a segment minus one.
+#               For example, the [LinearSpline]{agt.geom.LinearSpline}
+#               class sets a segment size of `1`, meaning that for points
+#               `[a, b, c, d]` it will have 3 segments `ab`, `bc` and `cd`.
+#
+# Returns a {ConcreteSpline} mixin.
+agt.geom.Spline = (segmentSize) ->
+
+  # Public: The concrete mixin as returned by the
+  # [Spline](../files/geom/mixins/spline.coffee.html) method.
+  #
+  # ### Concrete Splines
+  #
+  # - {agt.geom.LinearSpline}
+  # - {agt.geom.CubicBezier}
+  # - {agt.geom.QuadBezier}
+  # - {agt.geom.QuintBezier}
+  #
+  # ### Included Mixins
+  #
+  # - [agt.mixins.Memoizable](../../../files/mixins/memoizable.coffee.html)
+  #
+  # <script>window.exampleKey = 'cubic_spline'</script>
+  class ConcreteSpline
+    @include agt.mixins.Memoizable
+
+    ### Public ###
+
+    # The `Spline` mixin is intended to be included, but it decorates
+    # the target class with a class method to return the segment size defined
+    # for the class.
+    #
+    # klass - The [Class]{Function} that receive the mixin.
+    @included: (klass) ->
+      klass.segmentSize = -> segmentSize
+
+    # Initializes the oject's spline properties. It will also proceed
+    # to the validation of the spline's `vertices` based on the segment
+    # size specified at the mixin creation.
+    #
+    # A vertices {Array} is valid when its length is equal
+    # to `x * segmentSize + 1` where `x` is any integer greater
+    # or equal to `1`.
+    #
+    # vertices - The {Array} of [Points]{agt.geom.Point} that forms the
+    #            spline shape.
+    # bias - The {Number} of steps per segments when generating the points
+    #        of the final geometry.
+    initSpline: (@vertices, @bias=20) ->
+      unless @validateVertices @vertices
+        throw new Error "The number of vertices for #{this} doesn't match"
+
+    # Returns the center of the spline by averaging its vertices.
+    #
+    # <script>drawGeometry(exampleKey, {center: true})</script>
+    #
+    # Returns a [Point]{agt.geom.Point}.
+    center: ->
+      x = y = 0
+
+      for vertex in @vertices
+        x += vertex.x
+        y += vertex.y
+
+      x = x / @vertices.length
+      y = y / @vertices.length
+
+      new agt.geom.Point x, y
+
+    # Applies a translation represented by the passed-in [point]{agt.geom.Point}
+    # to every vertices of the spline.
+    #
+    # <script>drawTransform(exampleKey, {type: 'translate', args: [50, 0], width: 150})</script>
+    #
+    # x - A {Number} for the x coordinate or a point-like {Object}.
+    # y - A {Number} for the y coordinate if the first argument is also a number.
+    #
+    # Returns this {ConcreteSpline}.
+    translate: (x,y) ->
+      {x,y} = agt.geom.Point.pointFrom x,y
+      for vertex,i in @vertices
+        @vertices[i] = vertex.add x, y
+      this
+
+    # Rotates every vertices around the spline center by an amount of `rotation`
+    # radians.
+    #
+    # <script>drawTransform(exampleKey, {type: 'rotate', args: [Math.PI / 3]})</script>
+    #
+    # rotation - The {Number} of radians to rotate the spline.
+    #
+    # Returns this {ConcreteSpline}.
+    rotate: (rotation) ->
+      center = @center()
+      for vertex,i in @vertices
+        @vertices[i] = vertex.rotateAround center, rotation
+      this
+
+    # Scales the spline by moving every vertices on the vector they forms with
+    # the spline center.
+    #
+    # <script>drawTransform(exampleKey, {type: 'scale', args: [0.6]})</script>
+    #
+    # scale - The scaling factor {Number}, a value of `0.5` will scale down
+    #         the spline at half its original size when a value of `2` will
+    #         double the size of the spline.
+    #
+    # Returns this {ConcreteSpline}.
+    scale: (scale) ->
+      center = @center()
+      for vertex,i in @vertices
+        @vertices[i] = center.add vertex.subtract(center).scale(scale)
+      this
+
+    # Returns the *final* points of the curve as determined by the `bias`
+    # property of the current spline. The total number of points for a geometry
+    # is always the result of the following equation: `segment size * number
+    # of segments`.
+    #
+    # <script>drawGeometryPoints(exampleKey, 'points')</script>
+    #
+    # Returns an {Array} of [Points]{agt.geom.Point}.
+    points: ->
+      return @memoFor('points').concat() if @memoized 'points'
+      segments = @segments() * @bias
+      points = (@pathPointAt i / segments for i in [0..segments])
+      @memoize('points', points).concat()
+
+    # Internal: Validates the length of the vertices {Array}.
+    #
+    # vertices - The {Array} of vertices to validate.
+    #
+    # Returns a {Boolean}.
+    validateVertices: (vertices) ->
+      vertices.length % segmentSize is 1 and
+      vertices.length >= segmentSize + 1
+
+    # Returns the {Number} of segments of the current spline based on the
+    # spline configuration.
+    #
+    # Returns a {Number}.
+    segments: ->
+      return 0 if not @vertices? or @vertices.length is 0
+      return @memoFor 'segments' if @memoized 'segments'
+      @memoize 'segments', (@vertices.length - 1) / segmentSize
+
+    # Returns the size {Number} of the spline segments.
+    #
+    # Returns a {Number}.
+    segmentSize: -> segmentSize
+
+    # Returns the segment at `index`. A segment is a pair of
+    # [Points]{agt.geom.Point} of each extremity of the segment.
+    #
+    # index - The index {Number} of the segment.
+    #
+    # Returns an {Array} of [Points]{agt.geom.Point}.
+    segment: (index) ->
+      if index < @segments()
+        k = "segment#{index}"
+        return @memoFor k if @memoized k
+
+        [start, end] = [index * segmentSize, (index + 1) * segmentSize + 1]
+        @memoize k, @vertices[start..end]
+      else
+        null
+
+    # Returns the length of the spline in pixels.
+    #
+    # This an approximative value based on the current spline `bias`, so the
+    # bigger the `bias` the more accurate the length is, with the downside
+    # of poorer performances.
+    #
+    # Returns a {Number}.
+    length: -> @measure @bias
+
+    # Internal: Measures the spline using the passed-in bias.
+    #
+    # bias - The {Number} of steps used to walk the spline segments.
+    #
+    # Returns a {Number}.
+    measure: (bias) ->
+      return @memoFor 'measure' if @memoized 'measure'
+      length = 0
+      length += @measureSegment @segment(i), bias for i in [0..@segments()-1]
+      @memoize 'measure', length
+
+    # Internal: Measures the given segment using the passed-in bias.
+    #
+    # segment - The index {Number} of the segment to measure.
+    # bias - The {Number} of steps used to walk the segment.
+    #
+    # Returns a {Number}.
+    measureSegment: (segment, bias) ->
+      k = "segment#{segment}_#{bias}Length"
+      return @memoFor k if @memoized k
+
+      step = 1 / bias
+      length = 0
+
+      for i in [1..bias]
+        length += @pointInSegment((i-1) * step, segment)
+                    .distance(@pointInSegment(i * step, segment))
+
+      @memoize k, length
+
+    # {Delegates to: agt.geom.Path.pathPointAt}
+    pathPointAt: (pos, pathBasedOnLength=true) ->
+      pos = 0 if pos < 0
+      pos = 1 if pos > 1
+
+      return @vertices[0] if pos is 0
+      return @vertices[@vertices.length - 1] if pos is 1
+
+      if pathBasedOnLength
+        @walkPathBasedOnLength pos
+      else
+        @walkPathBasedOnSegments pos
+
+    # Internal: Iterates over the spline steps until the given `pos` and
+    # returns the corresponding coordinates.
+    #
+    # In this implementation the path is walked with each segment taking
+    # a space in the total spline length based on its own length.
+    #
+    # pos - The position {Number} between `0` and `1`.
+    #
+    # Returns a [Point]{agt.geom.Point}.
+    walkPathBasedOnLength: (pos) ->
+      walked = 0
+      length = @length()
+      segments = @segments()
+
+      for i in [0..segments-1]
+        segment = @segment i
+        stepLength = @measureSegment(segment, @bias) / length
+
+        if walked + stepLength > pos
+          innerStepPos = Math.map pos, walked, walked + stepLength, 0, 1
+          return @pointInSegment innerStepPos, segment
+
+        walked += stepLength
+
+    # Internal: Iterates over the spline steps until the given `pos` and
+    # returns the corresponding coordinates.
+    #
+    # In this implementation the path is walked with each segment taking
+    # based on the number of segments in the spline.
+    #
+    # pos - The position {Number} between `0` and `1`.
+    #
+    # Returns a [Point]{agt.geom.Point}.
+    walkPathBasedOnSegments: (pos) ->
+      segments = @segments()
+      pos = pos * segments
+      segment = Math.floor pos
+      segment -= 1 if segment is segments
+      @pointInSegment pos - segment, @segment segment
+
+    # **Unsupported** - The {agt.geom.Geometry::fill} method is not supported
+    # by splines as they are not closed geometry.
+    fill: ->
+
+    # {Delegates to: agt.geom.Geometry.drawPath}
+    drawPath: (context) ->
+      points = @points()
+      start = points.shift()
+      context.beginPath()
+      context.moveTo(start.x,start.y)
+      context.lineTo(p.x,p.y) for p in points
+
+    # Draws the spline vertices onto the passed-in canvas context.
+    #
+    # <script>drawGeometry(exampleKey, {vertices: true})</script>
+    #
+    # context - The canvas context to draw in.
+    # color - The color {String} to use for the vertices.
+    drawVertices: (context, color=agt.COLORS.VERTICES) ->
+      context.fillStyle = color
+      for vertex in @vertices
+        context.beginPath()
+        context.arc vertex.x, vertex.y, 2, 0, Math.PI*2
+        context.fill()
+        context.closePath()
+
+    # Draws the segments between each vertex onto the passed-in canvas context.
+    #
+    # <script>drawGeometry(exampleKey, {verticesConnections: true})</script>
+    #
+    # context - The canvas context to draw in.
+    # color - The color {String} to use for the vertices connections.
+    drawVerticesConnections: (context, color=agt.COLORS.VERTICES_CONNECTIONS) ->
+      context.strokeStyle = color
+      for i in [1..@vertices.length-1]
+        vertexStart = @vertices[i-1]
+        vertexEnd = @vertices[i]
+        context.beginPath()
+        context.moveTo vertexStart.x, vertexStart.y
+        context.lineTo vertexEnd.x, vertexEnd.y
+        context.stroke()
+        context.closePath()
+
+    # The memoization key of a spline is the concatenation of its vertices.
+    #
+    # Returns a {String}.
+    memoizationKey: ->
+      @vertices.map((pt) -> "#{pt.x};#{pt.y}").join(';')
+
+    # {Delegates to: ConcreteCloneable.clone}
+    clone: -> new @constructor @vertices.map((pt) -> pt.clone()), @bias