1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15

16
/**
17
 * @fileoverview Represents a line in 2D space.
18
 *
19
 * @author [email protected] (Robby Walker)
20
 */
21

22
goog.provide('goog.math.Line');
23

24
goog.require('goog.math');
25
goog.require('goog.math.Coordinate');
26

27

28

29
/**
30
 * Object representing a line.
31
 * @param {number} x0 X coordinate of the start point.
32
 * @param {number} y0 Y coordinate of the start point.
33
 * @param {number} x1 X coordinate of the end point.
34
 * @param {number} y1 Y coordinate of the end point.
35
 * @struct
36
 * @constructor
37
 * @final
38
 */
39
goog.math.Line = function(x0, y0, x1, y1) {
40
  /**
41
   * X coordinate of the first point.
42
   * @type {number}
43
   */
44
  this.x0 = x0;
45

46
  /**
47
   * Y coordinate of the first point.
48
   * @type {number}
49
   */
50
  this.y0 = y0;
51

52
  /**
53
   * X coordinate of the first control point.
54
   * @type {number}
55
   */
56
  this.x1 = x1;
57

58
  /**
59
   * Y coordinate of the first control point.
60
   * @type {number}
61
   */
62
  this.y1 = y1;
63
};
64

65

66
/**
67
 * @return {!goog.math.Line} A copy of this line.
68
 */
69
goog.math.Line.prototype.clone = function() {
70
  return new goog.math.Line(this.x0, this.y0, this.x1, this.y1);
71
};
72

73

74
/**
75
 * Tests whether the given line is exactly the same as this one.
76
 * @param {goog.math.Line} other The other line.
77
 * @return {boolean} Whether the given line is the same as this one.
78
 */
79
goog.math.Line.prototype.equals = function(other) {
80
  return this.x0 == other.x0 && this.y0 == other.y0 && this.x1 == other.x1 &&
81
      this.y1 == other.y1;
82
};
83

84

85
/**
86
 * @return {number} The squared length of the line segment used to define the
87
 *     line.
88
 */
89
goog.math.Line.prototype.getSegmentLengthSquared = function() {
90
  var xdist = this.x1 - this.x0;
91
  var ydist = this.y1 - this.y0;
92
  return xdist * xdist + ydist * ydist;
93
};
94

95

96
/**
97
 * @return {number} The length of the line segment used to define the line.
98
 */
99
goog.math.Line.prototype.getSegmentLength = function() {
100
  return Math.sqrt(this.getSegmentLengthSquared());
101
};
102

103

104
/**
105
 * Computes the interpolation parameter for the point on the line closest to
106
 * a given point.
107
 * @param {number|goog.math.Coordinate} x The x coordinate of the point, or
108
 *     a coordinate object.
109
 * @param {number=} opt_y The y coordinate of the point - required if x is a
110
 *     number, ignored if x is a goog.math.Coordinate.
111
 * @return {number} The interpolation parameter of the point on the line
112
 *     closest to the given point.
113
 * @private
114
 */
115
goog.math.Line.prototype.getClosestLinearInterpolation_ = function(x, opt_y) {
116
  var y;
117
  if (x instanceof goog.math.Coordinate) {
118
    y = x.y;
119
    x = x.x;
120
  } else {
121
    y = opt_y;
122
  }
123

124
  var x0 = this.x0;
125
  var y0 = this.y0;
126

127
  var xChange = this.x1 - x0;
128
  var yChange = this.y1 - y0;
129

130
  return ((Number(x) - x0) * xChange + (Number(y) - y0) * yChange) /
131
      this.getSegmentLengthSquared();
132
};
133

134

135
/**
136
 * Returns the point on the line segment proportional to t, where for t = 0 we
137
 * return the starting point and for t = 1 we return the end point.  For t < 0
138
 * or t > 1 we extrapolate along the line defined by the line segment.
139
 * @param {number} t The interpolation parameter along the line segment.
140
 * @return {!goog.math.Coordinate} The point on the line segment at t.
141
 */
142
goog.math.Line.prototype.getInterpolatedPoint = function(t) {
143
  return new goog.math.Coordinate(
144
      goog.math.lerp(this.x0, this.x1, t), goog.math.lerp(this.y0, this.y1, t));
145
};
146

147

148
/**
149
 * Computes the point on the line closest to a given point.  Note that a line
150
 * in this case is defined as the infinite line going through the start and end
151
 * points.  To find the closest point on the line segment itself see
152
 * {@see #getClosestSegmentPoint}.
153
 * @param {number|goog.math.Coordinate} x The x coordinate of the point, or
154
 *     a coordinate object.
155
 * @param {number=} opt_y The y coordinate of the point - required if x is a
156
 *     number, ignored if x is a goog.math.Coordinate.
157
 * @return {!goog.math.Coordinate} The point on the line closest to the given
158
 *     point.
159
 */
160
goog.math.Line.prototype.getClosestPoint = function(x, opt_y) {
161
  return this.getInterpolatedPoint(
162
      this.getClosestLinearInterpolation_(x, opt_y));
163
};
164

165

166
/**
167
 * Computes the point on the line segment closest to a given point.
168
 * @param {number|goog.math.Coordinate} x The x coordinate of the point, or
169
 *     a coordinate object.
170
 * @param {number=} opt_y The y coordinate of the point - required if x is a
171
 *     number, ignored if x is a goog.math.Coordinate.
172
 * @return {!goog.math.Coordinate} The point on the line segment closest to the
173
 *     given point.
174
 */
175
goog.math.Line.prototype.getClosestSegmentPoint = function(x, opt_y) {
176
  return this.getInterpolatedPoint(
177
      goog.math.clamp(this.getClosestLinearInterpolation_(x, opt_y), 0, 1));
178
};
179

180