You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Matt Juntunen <ma...@hotmail.com> on 2020/05/06 02:03:44 UTC

Re: [geometry] API Design Feedback

No replies here so I'm assuming no one has any strong feelings on any of the designs above. However, to follow-up, we've decided to go with option 2 since it seems to be the most descriptive and least ambiguous. Note that this is a very large refactor since a large number of type names have been changed. The changes were made in commit eee258978cae8fe4987c2155ddfbd08c73d3c9db. Almost to the beta release...

Regards,
Matt
________________________________
From: Matt Juntunen <ma...@hotmail.com>
Sent: Friday, April 24, 2020 10:01 PM
To: Commons Developers List <de...@commons.apache.org>
Subject: [geometry] API Design Feedback

Hello,

Gilles and I have been working on polishing the API for commons-geometry and wrapping up a couple of last issues before the 1.0-beta1 release. We've been discussing the API design for some of the core classes in GEOMETRY-92 and GEOMETRY-94 and I'd like to get some feedback from the community on what we have. The goal is to create a mathematically correct and at the same time intuitive set of classes.

Below are 3 options for the names of some of the classes from the core (space-agnostic) module and the Euclidean module. I'm intentionally not explaining the meaning of any of the names since I'm interested in finding out how self-documenting they are. Please let me know if there is an option you prefer and if you have any suggestions for improvement. Any feedback whatsoever is greatly appreciated:-)

Note: The "::" characters below indicate some sort of inheritance, either by interface or class.

Option 1: Based on "Hyperplane/SubHyperplane" naming
    - Core Module
        - Hyperplane
        - SubHyperplane
        - ConvexSubHyperplane :: SubHyperplane
    - Euclidean 2D
        - Line :: Hyperplane
        - SubLine :: SubHyperplane
        - ConvexSubLine :: SubLine, ConvexSubHyperplane
        - Line.Span :: ConvexSubLine
        - Segment :: ConvexSubLine
        - Ray :: ConvexSubLine
        - ReverseRay :: ConvexSubLine
    - Euclidean 3D
        - Plane :: Hyperplane
        - SubPlane :: SubHyperplane
        - ConvexSubPlane :: SubPlane, ConvexSubHyperplane
        - FiniteConvexSubPlane :: ConvexSubPlane
        - Triangle3D :: FiniteConvexSubPlane
        - Line3D
        - SubLine3D
        - ConvexSubLine3D :: SubLine3D
        - Line3D.Span :: ConvexSubLine3D
        - Segment3D :: ConvexSubLine3D
        - Ray3D:: ConvexSubLine3D
        - ReverseRay3D :: ConvexSubLine3D

Option 2: Based on "Hyperplane/HyperplaneSubset" naming
    - Core Module
        - Hyperplane
        - HyperplaneSubset
        - HyperplaneConvexSubset :: HyperplaneSubset
    - Euclidean 2D
        - Line :: Hyperplane
        - LineSubset :: HyperplaneSubset
        - LineConvexSubset :: LineSubset, HyperplaneConvexSubset
        - LineSpanningSubset :: LineConvexSubset
        - Segment :: LineConvexSubset
        - Ray :: LineConvexSubset
        - ReverseRay :: LineConvexSubset
    - Euclidean 3D
        - Plane :: Hyperplane
        - PlaneSubset :: HyperplaneSubset
        - PlaneConvexSubset :: PlaneSubset, HyperplaneConvexSubset
        - PlaneFiniteConvexSubset :: PlaneConvexSubset
        - Triangle3D :: PlaneFiniteConvexSubset
        - Line3D
        - LineSubset3D
        - LineConvexSubset3D :: LineSubset3D
        - LineSpanningSubset3D :: LineConvexSubset3D
        - Segment3D :: LineConvexSubset3D
        - Ray3D:: LineConvexSubset3D
        - ReverseRay3D :: LineConvexSubset3D

Option 3: Same as #2 but with adjectives (eg "convex") coming before the hyperplane name
    - Core Module
        - Hyperplane
        - HyperplaneSubset
        - ConvexHyperplaneSubset :: HyperplaneSubset
    - Euclidean 2D
        - Line :: Hyperplane
        - LineSubset :: HyperplaneSubset
        - ConvexLineSubset :: LineSubset, ConvexHyperplaneSubset
        - SpanningLineSubset :: ConvexLineSubset
        - Segment :: ConvexLineSubset
        - Ray :: ConvexLineSubset
        - ReverseRay :: ConvexLineSubset
    - Euclidean 3D
        - Plane :: Hyperplane
        - PlaneSubset :: HyperplaneSubset
        - ConvexPlaneSubset :: PlaneSubset, ConvexHyperplaneSubset
        - FiniteConvexPlaneSubset :: ConvexPlaneSubset
        - Triangle3D :: FiniteConvexPlaneSubset
        - Line3D
        - LineSubset3D
        - ConvexLineSubset3D :: LineSubset3D
        - SpanningLineSubset3D :: ConvexLineSubset3D
        - Segment3D :: ConvexLineSubset3D
        - Ray3D:: ConvexLineSubset3D
        - ReverseRay3D :: ConvexLineSubset3D


Regards,
Matt J