[jira] [Commented] (GEOMETRY-29) Plane API cleanup

["Matt Juntunen (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/GEOMETRY-29?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16770729#comment-16770729 ] 

Matt Juntunen commented on GEOMETRY-29:
---------------------------------------

Here are some more details of what I'm picturing for the API, based on the recently updated {{o.a.c.geometry.euclidean.oned.OrientedPoint}} and {{o.a.c.geometry.euclidean.twod.Line}} classes:

{code:java}
public final class Plane implements ... {
    // all member variables final

    // no public ctor; all instance creation is through static factory methods

    // remove reset(), setNormal(), and setFrame() methods

    Vector3D getOrigin();
    Vector3D getNormal();
    Vector3D getOrigin();
    Vector3D getU();
    Vector3D getV();
    Vector3D getW(); // alias for getNormal()

    Vector3D project(Vector3D);
    Line project(Line); // new method; 3D line projected onto plane

    DoublePrecisionContext getPrecision();

    // return this since now immutable
    Plane copySelf();

    // used to be named revertSelf(); the behavior should be the same but
    // it should return a new Plane instead of modifying the instance
    Plane reverse();

    Vector2D toSubSpace(Vector3D) {... }
    Vector3D toSpace(Vector2D) {... }

    boolean contains(Vector3D) {... }
    boolean contains(Line) {... } // 3D line
    boolean contains(Plane) {... } // renamed from isSimilarTo()

    double getOffset(Vector3D);
    double getOffset(Line); // 3D line
    double getOffset(Plane);

    // renamed from getPointAt()
    Vector3D pointAt(Vector2D, double) {... }

    // these may be removed after GEOMETRY-24 but they should be retained for now
    Plane rotate(Vector3D, QuaternionRotation);
    Plane translate(Vector3D);

    Vector3D intersection(Line); // 3D line
    Line intersection(Plane); // 3D line

    SubPlane wholeHyperplane();
    PolyhedronsSet wholeSpace();

    boolean sameOrientationAs(Hyperplane<Vector3D>);

    int hashCode();
    boolean equals(Object);
    String toString();

    // u = p1.vectorTo(p2); v = p1.vectorTo(p3); w = u x v
    static Plane fromPoints(Vector3D p1, Vector3D p2, Vector3D p2);

    // u = normal.orthogonal(); v = w x u
    static Plane fromPointAndNormal(Vector3D pt, Vector3D normal);

    // same as above but uses the origin as the point
    static Plane fromNormal(Vector3D normal) {
        return fromPointAndNormal(Vector3D.ZERO, normal);
    }

    // v = u.orthogonal(v); w = u x v
    static Plane fromPointAndPlaneVectors(Vector3D pt, Vector3D u, Vector3D v);

    // same as current implementation, although I think we can clean this up considerably
    static Vector3D intersection(Plane, Plane, Plane);
}
    
{code}


> Plane API cleanup
> -----------------
>
>                 Key: GEOMETRY-29
>                 URL: https://issues.apache.org/jira/browse/GEOMETRY-29
>             Project: Apache Commons Geometry
>          Issue Type: Improvement
>            Reporter: Matt Juntunen
>            Priority: Major
>
> The following changes should be made to the {{o.a.c.g.euclidean.threed.Plane}} class:
>  * make the class immutable
>  * use well-named factory methods instead of constructor overloads
>  * provide a factory method to create a plane with user-supplied {{u}} and {{v}} axes. The current implementation allows the normal to be provided but chooses its own planar axes (see {{setFrame}}).
>  * add {{equals}}, {{hashCode}}, and {{toString}} methods.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)