org.djutils.draw.line.Project Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of djutils-draw Show documentation
DJUTILS - Delft Java Utilities Drawing and animation primitives
The newest version!
package org.djutils.draw.line;

import org.djutils.draw.point.Point;

/**
 * Project.java.
 * 
 * Copyright (c) 2021-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. 

 * BSD-style license. See DJUTILS License.
 * 
 * @author Alexander Verbraeck
 * @author Peter Knoppers
 * @param  the point type (2d or 3d)
 */
public interface Project>
{
    /**
     * Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the
     * solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, null is
     * returned.
     * @param point P; the point
     * @return P; the projection of the point (may be null if no sensible projection is possible). If the result is not null;
     *         the result lies somewhere on this object.
     * @throws NullPointerException when point is null;
     */
    P projectOrthogonal(P point) throws NullPointerException;

    /**
     * Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the
     * solution that lies on the closest segment is returned.
     * @param point P; the point
     * @return P; the projection of the point. This result cannot be null, but it may not lie on this object, but, in stead, lie
     *         on a line, or plane that extends this object
     * @throws NullPointerException when point is null;
     */
    P projectOrthogonalExtended(P point) throws NullPointerException;

    /**
     * Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the
     * solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, NaN is
     * returned.
     * @param point P; the point
     * @return double; the fractional position of the projection of the point (may be NaN if no sensible projection is
     *         possible). If the result is not NaN; the result lies somewhere on this object.
     * @throws NullPointerException when point is null;
     */
    double projectOrthogonalFractional(P point) throws NullPointerException;

    /**
     * Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the
     * solution that lies on the closest segment is returned.
     * @param point P; the point
     * @return double; the fractional position of the projection of the point. This result cannot be NaN, but it may be outside
     *         the range 0.0 .. 1.0.
     * @throws NullPointerException when point is null;
     */
    double projectOrthogonalFractionalExtended(P point) throws NullPointerException;

}