1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.geom;
  27 
  28 import java.awt.Shape;
  29 import java.awt.Rectangle;
  30 import java.io.Serializable;
  31 
  32 /**
  33  * This {@code Line2D} represents a line segment in {@code (x,y)}
  34  * coordinate space.
  35  * <p>
  36  * This class is only the abstract superclass for all objects that
  37  * store a 2D line segment.
  38  * The actual storage representation of the coordinates is left to
  39  * the subclass.
  40  *
  41  * @author      Jim Graham
  42  * @since 1.2
  43  */
  44 public abstract class Line2D implements Shape, Cloneable {
  45 
  46     /**
  47      * A line segment specified with float coordinates.
  48      * @since 1.2
  49      */
  50     public static class Float extends Line2D implements Serializable {
  51         /**
  52          * The X coordinate of the start point of the line segment.
  53          * @since 1.2
  54          * @serial
  55          */
  56         public float x1;
  57 
  58         /**
  59          * The Y coordinate of the start point of the line segment.
  60          * @since 1.2
  61          * @serial
  62          */
  63         public float y1;
  64 
  65         /**
  66          * The X coordinate of the end point of the line segment.
  67          * @since 1.2
  68          * @serial
  69          */
  70         public float x2;
  71 
  72         /**
  73          * The Y coordinate of the end point of the line segment.
  74          * @since 1.2
  75          * @serial
  76          */
  77         public float y2;
  78 
  79         /**
  80          * Constructs and initializes a Line with coordinates (0, 0) &rarr; (0, 0).
  81          * @since 1.2
  82          */
  83         public Float() {
  84         }
  85 
  86         /**
  87          * Constructs and initializes a Line from the specified coordinates.
  88          * @param x1 the X coordinate of the start point
  89          * @param y1 the Y coordinate of the start point
  90          * @param x2 the X coordinate of the end point
  91          * @param y2 the Y coordinate of the end point
  92          * @since 1.2
  93          */
  94         public Float(float x1, float y1, float x2, float y2) {
  95             setLine(x1, y1, x2, y2);
  96         }
  97 
  98         /**
  99          * Constructs and initializes a {@code Line2D} from the
 100          * specified {@code Point2D} objects.
 101          * @param p1 the start {@code Point2D} of this line segment
 102          * @param p2 the end {@code Point2D} of this line segment
 103          * @since 1.2
 104          */
 105         public Float(Point2D p1, Point2D p2) {
 106             setLine(p1, p2);
 107         }
 108 
 109         /**
 110          * {@inheritDoc}
 111          * @since 1.2
 112          */
 113         public double getX1() {
 114             return (double) x1;
 115         }
 116 
 117         /**
 118          * {@inheritDoc}
 119          * @since 1.2
 120          */
 121         public double getY1() {
 122             return (double) y1;
 123         }
 124 
 125         /**
 126          * {@inheritDoc}
 127          * @since 1.2
 128          */
 129         public Point2D getP1() {
 130             return new Point2D.Float(x1, y1);
 131         }
 132 
 133         /**
 134          * {@inheritDoc}
 135          * @since 1.2
 136          */
 137         public double getX2() {
 138             return (double) x2;
 139         }
 140 
 141         /**
 142          * {@inheritDoc}
 143          * @since 1.2
 144          */
 145         public double getY2() {
 146             return (double) y2;
 147         }
 148 
 149         /**
 150          * {@inheritDoc}
 151          * @since 1.2
 152          */
 153         public Point2D getP2() {
 154             return new Point2D.Float(x2, y2);
 155         }
 156 
 157         /**
 158          * {@inheritDoc}
 159          * @since 1.2
 160          */
 161         public void setLine(double x1, double y1, double x2, double y2) {
 162             this.x1 = (float) x1;
 163             this.y1 = (float) y1;
 164             this.x2 = (float) x2;
 165             this.y2 = (float) y2;
 166         }
 167 
 168         /**
 169          * Sets the location of the end points of this {@code Line2D}
 170          * to the specified float coordinates.
 171          * @param x1 the X coordinate of the start point
 172          * @param y1 the Y coordinate of the start point
 173          * @param x2 the X coordinate of the end point
 174          * @param y2 the Y coordinate of the end point
 175          * @since 1.2
 176          */
 177         public void setLine(float x1, float y1, float x2, float y2) {
 178             this.x1 = x1;
 179             this.y1 = y1;
 180             this.x2 = x2;
 181             this.y2 = y2;
 182         }
 183 
 184         /**
 185          * {@inheritDoc}
 186          * @since 1.2
 187          */
 188         public Rectangle2D getBounds2D() {
 189             float x, y, w, h;
 190             if (x1 < x2) {
 191                 x = x1;
 192                 w = x2 - x1;
 193             } else {
 194                 x = x2;
 195                 w = x1 - x2;
 196             }
 197             if (y1 < y2) {
 198                 y = y1;
 199                 h = y2 - y1;
 200             } else {
 201                 y = y2;
 202                 h = y1 - y2;
 203             }
 204             return new Rectangle2D.Float(x, y, w, h);
 205         }
 206 
 207         /*
 208          * JDK 1.6 serialVersionUID
 209          */
 210         private static final long serialVersionUID = 6161772511649436349L;
 211     }
 212 
 213     /**
 214      * A line segment specified with double coordinates.
 215      * @since 1.2
 216      */
 217     public static class Double extends Line2D implements Serializable {
 218         /**
 219          * The X coordinate of the start point of the line segment.
 220          * @since 1.2
 221          * @serial
 222          */
 223         public double x1;
 224 
 225         /**
 226          * The Y coordinate of the start point of the line segment.
 227          * @since 1.2
 228          * @serial
 229          */
 230         public double y1;
 231 
 232         /**
 233          * The X coordinate of the end point of the line segment.
 234          * @since 1.2
 235          * @serial
 236          */
 237         public double x2;
 238 
 239         /**
 240          * The Y coordinate of the end point of the line segment.
 241          * @since 1.2
 242          * @serial
 243          */
 244         public double y2;
 245 
 246         /**
 247          * Constructs and initializes a Line with coordinates (0, 0) &rarr; (0, 0).
 248          * @since 1.2
 249          */
 250         public Double() {
 251         }
 252 
 253         /**
 254          * Constructs and initializes a {@code Line2D} from the
 255          * specified coordinates.
 256          * @param x1 the X coordinate of the start point
 257          * @param y1 the Y coordinate of the start point
 258          * @param x2 the X coordinate of the end point
 259          * @param y2 the Y coordinate of the end point
 260          * @since 1.2
 261          */
 262         public Double(double x1, double y1, double x2, double y2) {
 263             setLine(x1, y1, x2, y2);
 264         }
 265 
 266         /**
 267          * Constructs and initializes a {@code Line2D} from the
 268          * specified {@code Point2D} objects.
 269          * @param p1 the start {@code Point2D} of this line segment
 270          * @param p2 the end {@code Point2D} of this line segment
 271          * @since 1.2
 272          */
 273         public Double(Point2D p1, Point2D p2) {
 274             setLine(p1, p2);
 275         }
 276 
 277         /**
 278          * {@inheritDoc}
 279          * @since 1.2
 280          */
 281         public double getX1() {
 282             return x1;
 283         }
 284 
 285         /**
 286          * {@inheritDoc}
 287          * @since 1.2
 288          */
 289         public double getY1() {
 290             return y1;
 291         }
 292 
 293         /**
 294          * {@inheritDoc}
 295          * @since 1.2
 296          */
 297         public Point2D getP1() {
 298             return new Point2D.Double(x1, y1);
 299         }
 300 
 301         /**
 302          * {@inheritDoc}
 303          * @since 1.2
 304          */
 305         public double getX2() {
 306             return x2;
 307         }
 308 
 309         /**
 310          * {@inheritDoc}
 311          * @since 1.2
 312          */
 313         public double getY2() {
 314             return y2;
 315         }
 316 
 317         /**
 318          * {@inheritDoc}
 319          * @since 1.2
 320          */
 321         public Point2D getP2() {
 322             return new Point2D.Double(x2, y2);
 323         }
 324 
 325         /**
 326          * {@inheritDoc}
 327          * @since 1.2
 328          */
 329         public void setLine(double x1, double y1, double x2, double y2) {
 330             this.x1 = x1;
 331             this.y1 = y1;
 332             this.x2 = x2;
 333             this.y2 = y2;
 334         }
 335 
 336         /**
 337          * {@inheritDoc}
 338          * @since 1.2
 339          */
 340         public Rectangle2D getBounds2D() {
 341             double x, y, w, h;
 342             if (x1 < x2) {
 343                 x = x1;
 344                 w = x2 - x1;
 345             } else {
 346                 x = x2;
 347                 w = x1 - x2;
 348             }
 349             if (y1 < y2) {
 350                 y = y1;
 351                 h = y2 - y1;
 352             } else {
 353                 y = y2;
 354                 h = y1 - y2;
 355             }
 356             return new Rectangle2D.Double(x, y, w, h);
 357         }
 358 
 359         /*
 360          * JDK 1.6 serialVersionUID
 361          */
 362         private static final long serialVersionUID = 7979627399746467499L;
 363     }
 364 
 365     /**
 366      * This is an abstract class that cannot be instantiated directly.
 367      * Type-specific implementation subclasses are available for
 368      * instantiation and provide a number of formats for storing
 369      * the information necessary to satisfy the various accessory
 370      * methods below.
 371      *
 372      * @see java.awt.geom.Line2D.Float
 373      * @see java.awt.geom.Line2D.Double
 374      * @since 1.2
 375      */
 376     protected Line2D() {
 377     }
 378 
 379     /**
 380      * Returns the X coordinate of the start point in double precision.
 381      * @return the X coordinate of the start point of this
 382      *         {@code Line2D} object.
 383      * @since 1.2
 384      */
 385     public abstract double getX1();
 386 
 387     /**
 388      * Returns the Y coordinate of the start point in double precision.
 389      * @return the Y coordinate of the start point of this
 390      *         {@code Line2D} object.
 391      * @since 1.2
 392      */
 393     public abstract double getY1();
 394 
 395     /**
 396      * Returns the start {@code Point2D} of this {@code Line2D}.
 397      * @return the start {@code Point2D} of this {@code Line2D}.
 398      * @since 1.2
 399      */
 400     public abstract Point2D getP1();
 401 
 402     /**
 403      * Returns the X coordinate of the end point in double precision.
 404      * @return the X coordinate of the end point of this
 405      *         {@code Line2D} object.
 406      * @since 1.2
 407      */
 408     public abstract double getX2();
 409 
 410     /**
 411      * Returns the Y coordinate of the end point in double precision.
 412      * @return the Y coordinate of the end point of this
 413      *         {@code Line2D} object.
 414      * @since 1.2
 415      */
 416     public abstract double getY2();
 417 
 418     /**
 419      * Returns the end {@code Point2D} of this {@code Line2D}.
 420      * @return the end {@code Point2D} of this {@code Line2D}.
 421      * @since 1.2
 422      */
 423     public abstract Point2D getP2();
 424 
 425     /**
 426      * Sets the location of the end points of this {@code Line2D} to
 427      * the specified double coordinates.
 428      * @param x1 the X coordinate of the start point
 429      * @param y1 the Y coordinate of the start point
 430      * @param x2 the X coordinate of the end point
 431      * @param y2 the Y coordinate of the end point
 432      * @since 1.2
 433      */
 434     public abstract void setLine(double x1, double y1, double x2, double y2);
 435 
 436     /**
 437      * Sets the location of the end points of this {@code Line2D} to
 438      * the specified {@code Point2D} coordinates.
 439      * @param p1 the start {@code Point2D} of the line segment
 440      * @param p2 the end {@code Point2D} of the line segment
 441      * @since 1.2
 442      */
 443     public void setLine(Point2D p1, Point2D p2) {
 444         setLine(p1.getX(), p1.getY(), p2.getX(), p2.getY());
 445     }
 446 
 447     /**
 448      * Sets the location of the end points of this {@code Line2D} to
 449      * the same as those end points of the specified {@code Line2D}.
 450      * @param l the specified {@code Line2D}
 451      * @since 1.2
 452      */
 453     public void setLine(Line2D l) {
 454         setLine(l.getX1(), l.getY1(), l.getX2(), l.getY2());
 455     }
 456 
 457     /**
 458      * Returns an indicator of where the specified point
 459      * {@code (px,py)} lies with respect to the line segment from
 460      * {@code (x1,y1)} to {@code (x2,y2)}.
 461      * The return value can be either 1, -1, or 0 and indicates
 462      * in which direction the specified line must pivot around its
 463      * first end point, {@code (x1,y1)}, in order to point at the
 464      * specified point {@code (px,py)}.
 465      * <p>A return value of 1 indicates that the line segment must
 466      * turn in the direction that takes the positive X axis towards
 467      * the negative Y axis.  In the default coordinate system used by
 468      * Java 2D, this direction is counterclockwise.
 469      * <p>A return value of -1 indicates that the line segment must
 470      * turn in the direction that takes the positive X axis towards
 471      * the positive Y axis.  In the default coordinate system, this
 472      * direction is clockwise.
 473      * <p>A return value of 0 indicates that the point lies
 474      * exactly on the line segment.  Note that an indicator value
 475      * of 0 is rare and not useful for determining collinearity
 476      * because of floating point rounding issues.
 477      * <p>If the point is colinear with the line segment, but
 478      * not between the end points, then the value will be -1 if the point
 479      * lies "beyond {@code (x1,y1)}" or 1 if the point lies
 480      * "beyond {@code (x2,y2)}".
 481      *
 482      * @param x1 the X coordinate of the start point of the
 483      *           specified line segment
 484      * @param y1 the Y coordinate of the start point of the
 485      *           specified line segment
 486      * @param x2 the X coordinate of the end point of the
 487      *           specified line segment
 488      * @param y2 the Y coordinate of the end point of the
 489      *           specified line segment
 490      * @param px the X coordinate of the specified point to be
 491      *           compared with the specified line segment
 492      * @param py the Y coordinate of the specified point to be
 493      *           compared with the specified line segment
 494      * @return an integer that indicates the position of the third specified
 495      *                  coordinates with respect to the line segment formed
 496      *                  by the first two specified coordinates.
 497      * @since 1.2
 498      */
 499     public static int relativeCCW(double x1, double y1,
 500                                   double x2, double y2,
 501                                   double px, double py)
 502     {
 503         x2 -= x1;
 504         y2 -= y1;
 505         px -= x1;
 506         py -= y1;
 507         double ccw = px * y2 - py * x2;
 508         if (ccw == 0.0) {
 509             // The point is colinear, classify based on which side of
 510             // the segment the point falls on.  We can calculate a
 511             // relative value using the projection of px,py onto the
 512             // segment - a negative value indicates the point projects
 513             // outside of the segment in the direction of the particular
 514             // endpoint used as the origin for the projection.
 515             ccw = px * x2 + py * y2;
 516             if (ccw > 0.0) {
 517                 // Reverse the projection to be relative to the original x2,y2
 518                 // x2 and y2 are simply negated.
 519                 // px and py need to have (x2 - x1) or (y2 - y1) subtracted
 520                 //    from them (based on the original values)
 521                 // Since we really want to get a positive answer when the
 522                 //    point is "beyond (x2,y2)", then we want to calculate
 523                 //    the inverse anyway - thus we leave x2 & y2 negated.
 524                 px -= x2;
 525                 py -= y2;
 526                 ccw = px * x2 + py * y2;
 527                 if (ccw < 0.0) {
 528                     ccw = 0.0;
 529                 }
 530             }
 531         }
 532         return (ccw < 0.0) ? -1 : ((ccw > 0.0) ? 1 : 0);
 533     }
 534 
 535     /**
 536      * Returns an indicator of where the specified point
 537      * {@code (px,py)} lies with respect to this line segment.
 538      * See the method comments of
 539      * {@link #relativeCCW(double, double, double, double, double, double)}
 540      * to interpret the return value.
 541      * @param px the X coordinate of the specified point
 542      *           to be compared with this {@code Line2D}
 543      * @param py the Y coordinate of the specified point
 544      *           to be compared with this {@code Line2D}
 545      * @return an integer that indicates the position of the specified
 546      *         coordinates with respect to this {@code Line2D}
 547      * @see #relativeCCW(double, double, double, double, double, double)
 548      * @since 1.2
 549      */
 550     public int relativeCCW(double px, double py) {
 551         return relativeCCW(getX1(), getY1(), getX2(), getY2(), px, py);
 552     }
 553 
 554     /**
 555      * Returns an indicator of where the specified {@code Point2D}
 556      * lies with respect to this line segment.
 557      * See the method comments of
 558      * {@link #relativeCCW(double, double, double, double, double, double)}
 559      * to interpret the return value.
 560      * @param p the specified {@code Point2D} to be compared
 561      *          with this {@code Line2D}
 562      * @return an integer that indicates the position of the specified
 563      *         {@code Point2D} with respect to this {@code Line2D}
 564      * @see #relativeCCW(double, double, double, double, double, double)
 565      * @since 1.2
 566      */
 567     public int relativeCCW(Point2D p) {
 568         return relativeCCW(getX1(), getY1(), getX2(), getY2(),
 569                            p.getX(), p.getY());
 570     }
 571 
 572     /**
 573      * Tests if the line segment from {@code (x1,y1)} to
 574      * {@code (x2,y2)} intersects the line segment from {@code (x3,y3)}
 575      * to {@code (x4,y4)}.
 576      *
 577      * @param x1 the X coordinate of the start point of the first
 578      *           specified line segment
 579      * @param y1 the Y coordinate of the start point of the first
 580      *           specified line segment
 581      * @param x2 the X coordinate of the end point of the first
 582      *           specified line segment
 583      * @param y2 the Y coordinate of the end point of the first
 584      *           specified line segment
 585      * @param x3 the X coordinate of the start point of the second
 586      *           specified line segment
 587      * @param y3 the Y coordinate of the start point of the second
 588      *           specified line segment
 589      * @param x4 the X coordinate of the end point of the second
 590      *           specified line segment
 591      * @param y4 the Y coordinate of the end point of the second
 592      *           specified line segment
 593      * @return {@code true} if the first specified line segment
 594      *                  and the second specified line segment intersect
 595      *                  each other; {@code false} otherwise.
 596      * @since 1.2
 597      */
 598     public static boolean linesIntersect(double x1, double y1,
 599                                          double x2, double y2,
 600                                          double x3, double y3,
 601                                          double x4, double y4)
 602     {
 603         return ((relativeCCW(x1, y1, x2, y2, x3, y3) *
 604                  relativeCCW(x1, y1, x2, y2, x4, y4) <= 0)
 605                 && (relativeCCW(x3, y3, x4, y4, x1, y1) *
 606                     relativeCCW(x3, y3, x4, y4, x2, y2) <= 0));
 607     }
 608 
 609     /**
 610      * Tests if the line segment from {@code (x1,y1)} to
 611      * {@code (x2,y2)} intersects this line segment.
 612      *
 613      * @param x1 the X coordinate of the start point of the
 614      *           specified line segment
 615      * @param y1 the Y coordinate of the start point of the
 616      *           specified line segment
 617      * @param x2 the X coordinate of the end point of the
 618      *           specified line segment
 619      * @param y2 the Y coordinate of the end point of the
 620      *           specified line segment
 621      * @return {@code <true>} if this line segment and the specified line segment
 622      *                  intersect each other; {@code false} otherwise.
 623      * @since 1.2
 624      */
 625     public boolean intersectsLine(double x1, double y1, double x2, double y2) {
 626         return linesIntersect(x1, y1, x2, y2,
 627                               getX1(), getY1(), getX2(), getY2());
 628     }
 629 
 630     /**
 631      * Tests if the specified line segment intersects this line segment.
 632      * @param l the specified {@code Line2D}
 633      * @return {@code true} if this line segment and the specified line
 634      *                  segment intersect each other;
 635      *                  {@code false} otherwise.
 636      * @since 1.2
 637      */
 638     public boolean intersectsLine(Line2D l) {
 639         return linesIntersect(l.getX1(), l.getY1(), l.getX2(), l.getY2(),
 640                               getX1(), getY1(), getX2(), getY2());
 641     }
 642 
 643     /**
 644      * Returns the square of the distance from a point to a line segment.
 645      * The distance measured is the distance between the specified
 646      * point and the closest point between the specified end points.
 647      * If the specified point intersects the line segment in between the
 648      * end points, this method returns 0.0.
 649      *
 650      * @param x1 the X coordinate of the start point of the
 651      *           specified line segment
 652      * @param y1 the Y coordinate of the start point of the
 653      *           specified line segment
 654      * @param x2 the X coordinate of the end point of the
 655      *           specified line segment
 656      * @param y2 the Y coordinate of the end point of the
 657      *           specified line segment
 658      * @param px the X coordinate of the specified point being
 659      *           measured against the specified line segment
 660      * @param py the Y coordinate of the specified point being
 661      *           measured against the specified line segment
 662      * @return a double value that is the square of the distance from the
 663      *                  specified point to the specified line segment.
 664      * @see #ptLineDistSq(double, double, double, double, double, double)
 665      * @since 1.2
 666      */
 667     public static double ptSegDistSq(double x1, double y1,
 668                                      double x2, double y2,
 669                                      double px, double py)
 670     {
 671         // Adjust vectors relative to x1,y1
 672         // x2,y2 becomes relative vector from x1,y1 to end of segment
 673         x2 -= x1;
 674         y2 -= y1;
 675         // px,py becomes relative vector from x1,y1 to test point
 676         px -= x1;
 677         py -= y1;
 678         double dotprod = px * x2 + py * y2;
 679         double projlenSq;
 680         if (dotprod <= 0.0) {
 681             // px,py is on the side of x1,y1 away from x2,y2
 682             // distance to segment is length of px,py vector
 683             // "length of its (clipped) projection" is now 0.0
 684             projlenSq = 0.0;
 685         } else {
 686             // switch to backwards vectors relative to x2,y2
 687             // x2,y2 are already the negative of x1,y1=>x2,y2
 688             // to get px,py to be the negative of px,py=>x2,y2
 689             // the dot product of two negated vectors is the same
 690             // as the dot product of the two normal vectors
 691             px = x2 - px;
 692             py = y2 - py;
 693             dotprod = px * x2 + py * y2;
 694             if (dotprod <= 0.0) {
 695                 // px,py is on the side of x2,y2 away from x1,y1
 696                 // distance to segment is length of (backwards) px,py vector
 697                 // "length of its (clipped) projection" is now 0.0
 698                 projlenSq = 0.0;
 699             } else {
 700                 // px,py is between x1,y1 and x2,y2
 701                 // dotprod is the length of the px,py vector
 702                 // projected on the x2,y2=>x1,y1 vector times the
 703                 // length of the x2,y2=>x1,y1 vector
 704                 projlenSq = dotprod * dotprod / (x2 * x2 + y2 * y2);
 705             }
 706         }
 707         // Distance to line is now the length of the relative point
 708         // vector minus the length of its projection onto the line
 709         // (which is zero if the projection falls outside the range
 710         //  of the line segment).
 711         double lenSq = px * px + py * py - projlenSq;
 712         if (lenSq < 0) {
 713             lenSq = 0;
 714         }
 715         return lenSq;
 716     }
 717 
 718     /**
 719      * Returns the distance from a point to a line segment.
 720      * The distance measured is the distance between the specified
 721      * point and the closest point between the specified end points.
 722      * If the specified point intersects the line segment in between the
 723      * end points, this method returns 0.0.
 724      *
 725      * @param x1 the X coordinate of the start point of the
 726      *           specified line segment
 727      * @param y1 the Y coordinate of the start point of the
 728      *           specified line segment
 729      * @param x2 the X coordinate of the end point of the
 730      *           specified line segment
 731      * @param y2 the Y coordinate of the end point of the
 732      *           specified line segment
 733      * @param px the X coordinate of the specified point being
 734      *           measured against the specified line segment
 735      * @param py the Y coordinate of the specified point being
 736      *           measured against the specified line segment
 737      * @return a double value that is the distance from the specified point
 738      *                          to the specified line segment.
 739      * @see #ptLineDist(double, double, double, double, double, double)
 740      * @since 1.2
 741      */
 742     public static double ptSegDist(double x1, double y1,
 743                                    double x2, double y2,
 744                                    double px, double py)
 745     {
 746         return Math.sqrt(ptSegDistSq(x1, y1, x2, y2, px, py));
 747     }
 748 
 749     /**
 750      * Returns the square of the distance from a point to this line segment.
 751      * The distance measured is the distance between the specified
 752      * point and the closest point between the current line's end points.
 753      * If the specified point intersects the line segment in between the
 754      * end points, this method returns 0.0.
 755      *
 756      * @param px the X coordinate of the specified point being
 757      *           measured against this line segment
 758      * @param py the Y coordinate of the specified point being
 759      *           measured against this line segment
 760      * @return a double value that is the square of the distance from the
 761      *                  specified point to the current line segment.
 762      * @see #ptLineDistSq(double, double)
 763      * @since 1.2
 764      */
 765     public double ptSegDistSq(double px, double py) {
 766         return ptSegDistSq(getX1(), getY1(), getX2(), getY2(), px, py);
 767     }
 768 
 769     /**
 770      * Returns the square of the distance from a {@code Point2D} to
 771      * this line segment.
 772      * The distance measured is the distance between the specified
 773      * point and the closest point between the current line's end points.
 774      * If the specified point intersects the line segment in between the
 775      * end points, this method returns 0.0.
 776      * @param pt the specified {@code Point2D} being measured against
 777      *           this line segment.
 778      * @return a double value that is the square of the distance from the
 779      *                  specified {@code Point2D} to the current
 780      *                  line segment.
 781      * @see #ptLineDistSq(Point2D)
 782      * @since 1.2
 783      */
 784     public double ptSegDistSq(Point2D pt) {
 785         return ptSegDistSq(getX1(), getY1(), getX2(), getY2(),
 786                            pt.getX(), pt.getY());
 787     }
 788 
 789     /**
 790      * Returns the distance from a point to this line segment.
 791      * The distance measured is the distance between the specified
 792      * point and the closest point between the current line's end points.
 793      * If the specified point intersects the line segment in between the
 794      * end points, this method returns 0.0.
 795      *
 796      * @param px the X coordinate of the specified point being
 797      *           measured against this line segment
 798      * @param py the Y coordinate of the specified point being
 799      *           measured against this line segment
 800      * @return a double value that is the distance from the specified
 801      *                  point to the current line segment.
 802      * @see #ptLineDist(double, double)
 803      * @since 1.2
 804      */
 805     public double ptSegDist(double px, double py) {
 806         return ptSegDist(getX1(), getY1(), getX2(), getY2(), px, py);
 807     }
 808 
 809     /**
 810      * Returns the distance from a {@code Point2D} to this line
 811      * segment.
 812      * The distance measured is the distance between the specified
 813      * point and the closest point between the current line's end points.
 814      * If the specified point intersects the line segment in between the
 815      * end points, this method returns 0.0.
 816      * @param pt the specified {@code Point2D} being measured
 817      *          against this line segment
 818      * @return a double value that is the distance from the specified
 819      *                          {@code Point2D} to the current line
 820      *                          segment.
 821      * @see #ptLineDist(Point2D)
 822      * @since 1.2
 823      */
 824     public double ptSegDist(Point2D pt) {
 825         return ptSegDist(getX1(), getY1(), getX2(), getY2(),
 826                          pt.getX(), pt.getY());
 827     }
 828 
 829     /**
 830      * Returns the square of the distance from a point to a line.
 831      * The distance measured is the distance between the specified
 832      * point and the closest point on the infinitely-extended line
 833      * defined by the specified coordinates.  If the specified point
 834      * intersects the line, this method returns 0.0.
 835      *
 836      * @param x1 the X coordinate of the start point of the specified line
 837      * @param y1 the Y coordinate of the start point of the specified line
 838      * @param x2 the X coordinate of the end point of the specified line
 839      * @param y2 the Y coordinate of the end point of the specified line
 840      * @param px the X coordinate of the specified point being
 841      *           measured against the specified line
 842      * @param py the Y coordinate of the specified point being
 843      *           measured against the specified line
 844      * @return a double value that is the square of the distance from the
 845      *                  specified point to the specified line.
 846      * @see #ptSegDistSq(double, double, double, double, double, double)
 847      * @since 1.2
 848      */
 849     public static double ptLineDistSq(double x1, double y1,
 850                                       double x2, double y2,
 851                                       double px, double py)
 852     {
 853         // Adjust vectors relative to x1,y1
 854         // x2,y2 becomes relative vector from x1,y1 to end of segment
 855         x2 -= x1;
 856         y2 -= y1;
 857         // px,py becomes relative vector from x1,y1 to test point
 858         px -= x1;
 859         py -= y1;
 860         double dotprod = px * x2 + py * y2;
 861         // dotprod is the length of the px,py vector
 862         // projected on the x1,y1=>x2,y2 vector times the
 863         // length of the x1,y1=>x2,y2 vector
 864         double projlenSq = dotprod * dotprod / (x2 * x2 + y2 * y2);
 865         // Distance to line is now the length of the relative point
 866         // vector minus the length of its projection onto the line
 867         double lenSq = px * px + py * py - projlenSq;
 868         if (lenSq < 0) {
 869             lenSq = 0;
 870         }
 871         return lenSq;
 872     }
 873 
 874     /**
 875      * Returns the distance from a point to a line.
 876      * The distance measured is the distance between the specified
 877      * point and the closest point on the infinitely-extended line
 878      * defined by the specified coordinates.  If the specified point
 879      * intersects the line, this method returns 0.0.
 880      *
 881      * @param x1 the X coordinate of the start point of the specified line
 882      * @param y1 the Y coordinate of the start point of the specified line
 883      * @param x2 the X coordinate of the end point of the specified line
 884      * @param y2 the Y coordinate of the end point of the specified line
 885      * @param px the X coordinate of the specified point being
 886      *           measured against the specified line
 887      * @param py the Y coordinate of the specified point being
 888      *           measured against the specified line
 889      * @return a double value that is the distance from the specified
 890      *                   point to the specified line.
 891      * @see #ptSegDist(double, double, double, double, double, double)
 892      * @since 1.2
 893      */
 894     public static double ptLineDist(double x1, double y1,
 895                                     double x2, double y2,
 896                                     double px, double py)
 897     {
 898         return Math.sqrt(ptLineDistSq(x1, y1, x2, y2, px, py));
 899     }
 900 
 901     /**
 902      * Returns the square of the distance from a point to this line.
 903      * The distance measured is the distance between the specified
 904      * point and the closest point on the infinitely-extended line
 905      * defined by this {@code Line2D}.  If the specified point
 906      * intersects the line, this method returns 0.0.
 907      *
 908      * @param px the X coordinate of the specified point being
 909      *           measured against this line
 910      * @param py the Y coordinate of the specified point being
 911      *           measured against this line
 912      * @return a double value that is the square of the distance from a
 913      *                  specified point to the current line.
 914      * @see #ptSegDistSq(double, double)
 915      * @since 1.2
 916      */
 917     public double ptLineDistSq(double px, double py) {
 918         return ptLineDistSq(getX1(), getY1(), getX2(), getY2(), px, py);
 919     }
 920 
 921     /**
 922      * Returns the square of the distance from a specified
 923      * {@code Point2D} to this line.
 924      * The distance measured is the distance between the specified
 925      * point and the closest point on the infinitely-extended line
 926      * defined by this {@code Line2D}.  If the specified point
 927      * intersects the line, this method returns 0.0.
 928      * @param pt the specified {@code Point2D} being measured
 929      *           against this line
 930      * @return a double value that is the square of the distance from a
 931      *                  specified {@code Point2D} to the current
 932      *                  line.
 933      * @see #ptSegDistSq(Point2D)
 934      * @since 1.2
 935      */
 936     public double ptLineDistSq(Point2D pt) {
 937         return ptLineDistSq(getX1(), getY1(), getX2(), getY2(),
 938                             pt.getX(), pt.getY());
 939     }
 940 
 941     /**
 942      * Returns the distance from a point to this line.
 943      * The distance measured is the distance between the specified
 944      * point and the closest point on the infinitely-extended line
 945      * defined by this {@code Line2D}.  If the specified point
 946      * intersects the line, this method returns 0.0.
 947      *
 948      * @param px the X coordinate of the specified point being
 949      *           measured against this line
 950      * @param py the Y coordinate of the specified point being
 951      *           measured against this line
 952      * @return a double value that is the distance from a specified point
 953      *                  to the current line.
 954      * @see #ptSegDist(double, double)
 955      * @since 1.2
 956      */
 957     public double ptLineDist(double px, double py) {
 958         return ptLineDist(getX1(), getY1(), getX2(), getY2(), px, py);
 959     }
 960 
 961     /**
 962      * Returns the distance from a {@code Point2D} to this line.
 963      * The distance measured is the distance between the specified
 964      * point and the closest point on the infinitely-extended line
 965      * defined by this {@code Line2D}.  If the specified point
 966      * intersects the line, this method returns 0.0.
 967      * @param pt the specified {@code Point2D} being measured
 968      * @return a double value that is the distance from a specified
 969      *                  {@code Point2D} to the current line.
 970      * @see #ptSegDist(Point2D)
 971      * @since 1.2
 972      */
 973     public double ptLineDist(Point2D pt) {
 974         return ptLineDist(getX1(), getY1(), getX2(), getY2(),
 975                          pt.getX(), pt.getY());
 976     }
 977 
 978     /**
 979      * Tests if a specified coordinate is inside the boundary of this
 980      * {@code Line2D}.  This method is required to implement the
 981      * {@link Shape} interface, but in the case of {@code Line2D}
 982      * objects it always returns {@code false} since a line contains
 983      * no area.
 984      * @param x the X coordinate of the specified point to be tested
 985      * @param y the Y coordinate of the specified point to be tested
 986      * @return {@code false} because a {@code Line2D} contains
 987      * no area.
 988      * @since 1.2
 989      */
 990     public boolean contains(double x, double y) {
 991         return false;
 992     }
 993 
 994     /**
 995      * Tests if a given {@code Point2D} is inside the boundary of
 996      * this {@code Line2D}.
 997      * This method is required to implement the {@link Shape} interface,
 998      * but in the case of {@code Line2D} objects it always returns
 999      * {@code false} since a line contains no area.
1000      * @param p the specified {@code Point2D} to be tested
1001      * @return {@code false} because a {@code Line2D} contains
1002      * no area.
1003      * @since 1.2
1004      */
1005     public boolean contains(Point2D p) {
1006         return false;
1007     }
1008 
1009     /**
1010      * {@inheritDoc}
1011      * @since 1.2
1012      */
1013     public boolean intersects(double x, double y, double w, double h) {
1014         return intersects(new Rectangle2D.Double(x, y, w, h));
1015     }
1016 
1017     /**
1018      * {@inheritDoc}
1019      * @since 1.2
1020      */
1021     public boolean intersects(Rectangle2D r) {
1022         return r.intersectsLine(getX1(), getY1(), getX2(), getY2());
1023     }
1024 
1025     /**
1026      * Tests if the interior of this {@code Line2D} entirely contains
1027      * the specified set of rectangular coordinates.
1028      * This method is required to implement the {@code Shape} interface,
1029      * but in the case of {@code Line2D} objects it always returns
1030      * false since a line contains no area.
1031      * @param x the X coordinate of the upper-left corner of the
1032      *          specified rectangular area
1033      * @param y the Y coordinate of the upper-left corner of the
1034      *          specified rectangular area
1035      * @param w the width of the specified rectangular area
1036      * @param h the height of the specified rectangular area
1037      * @return {@code false} because a {@code Line2D} contains
1038      * no area.
1039      * @since 1.2
1040      */
1041     public boolean contains(double x, double y, double w, double h) {
1042         return false;
1043     }
1044 
1045     /**
1046      * Tests if the interior of this {@code Line2D} entirely contains
1047      * the specified {@code Rectangle2D}.
1048      * This method is required to implement the {@code Shape} interface,
1049      * but in the case of {@code Line2D} objects it always returns
1050      * {@code false} since a line contains no area.
1051      * @param r the specified {@code Rectangle2D} to be tested
1052      * @return {@code false} because a {@code Line2D} contains
1053      * no area.
1054      * @since 1.2
1055      */
1056     public boolean contains(Rectangle2D r) {
1057         return false;
1058     }
1059 
1060     /**
1061      * {@inheritDoc}
1062      * @since 1.2
1063      */
1064     public Rectangle getBounds() {
1065         return getBounds2D().getBounds();
1066     }
1067 
1068     /**
1069      * Returns an iteration object that defines the boundary of this
1070      * {@code Line2D}.
1071      * The iterator for this class is not multi-threaded safe,
1072      * which means that this {@code Line2D} class does not
1073      * guarantee that modifications to the geometry of this
1074      * {@code Line2D} object do not affect any iterations of that
1075      * geometry that are already in process.
1076      * @param at the specified {@link AffineTransform}
1077      * @return a {@link PathIterator} that defines the boundary of this
1078      *          {@code Line2D}.
1079      * @since 1.2
1080      */
1081     public PathIterator getPathIterator(AffineTransform at) {
1082         return new LineIterator(this, at);
1083     }
1084 
1085     /**
1086      * Returns an iteration object that defines the boundary of this
1087      * flattened {@code Line2D}.
1088      * The iterator for this class is not multi-threaded safe,
1089      * which means that this {@code Line2D} class does not
1090      * guarantee that modifications to the geometry of this
1091      * {@code Line2D} object do not affect any iterations of that
1092      * geometry that are already in process.
1093      * @param at the specified {@code AffineTransform}
1094      * @param flatness the maximum amount that the control points for a
1095      *          given curve can vary from colinear before a subdivided
1096      *          curve is replaced by a straight line connecting the
1097      *          end points.  Since a {@code Line2D} object is
1098      *          always flat, this parameter is ignored.
1099      * @return a {@code PathIterator} that defines the boundary of the
1100      *                  flattened {@code Line2D}
1101      * @since 1.2
1102      */
1103     public PathIterator getPathIterator(AffineTransform at, double flatness) {
1104         return new LineIterator(this, at);
1105     }
1106 
1107     /**
1108      * Creates a new object of the same class as this object.
1109      *
1110      * @return     a clone of this instance.
1111      * @exception  OutOfMemoryError            if there is not enough memory.
1112      * @see        java.lang.Cloneable
1113      * @since      1.2
1114      */
1115     public Object clone() {
1116         try {
1117             return super.clone();
1118         } catch (CloneNotSupportedException e) {
1119             // this shouldn't happen, since we are Cloneable
1120             throw new InternalError(e);
1121         }
1122     }
1123 }
--- EOF ---