Hello, > Is there a gentle introduction to how it works and/or the intended use cases?
Not specifically. The implementations are used the same way as JDK Maps and Sets so usage should be very familiar. As far as the internal implementation details, I've tried to describe that in the javadocs for the implementing classes. One example use case is construction of meshes from a stream of triangles. This is used internally in o.a.c.geometry.euclidean.threed.mesh.SimpleTriangleMesh. Another use case is finding unique entries in a cloud of points, where many points are close but not exactly equal to each other. This case was actually posted on the user mailing list (I believe) way back when I started implementing this feature. > Does it entail issues about some use cases or applications that need this functionality? Or do they not generally care about that contract? If so, maybe this collection shouldn't implement the standard JDK interfaces (?). No, there shouldn't be any issues. java.util.TreeMap documents that it's behavior is well-defined and consistent even when a Comparator that doesn't match equals is given, such as String.CASE_INSENSITIVE_ORDER. This is the same sort of situation. The map/set is still quite useful even without the strict contract. > Where does the anticipation come from? The approach I used for helping to maintain somewhat balanced trees in Euclidean 2D and 3D and spherical 2D regardless of insertion order is not based on a well-known algorithm or paper since I was unable to find one. The literature on the subject seems to focus on situations where the inserted points are all known beforehand and can be inserted in a particular order. I did not want to enforce this condition on the API. What I ended up with is just an idea I had for tree balancing that seems to work pretty well. As such, I fully expect that there will be a better option discovered later on. > I don't quite follow; which are the corresponding "non-canonical" accessors? My thought here is that there will be situations where a set of points is placed into a map/set and then these points are queried using values determined from some other source, such as through computations of some sort. These query points may vary from the originally inserted points by distances allowed by the Precision.DoubleEquivalence. In these cases, it's useful to be able to obtain the exact value of the originally inserted (i.e. "canonical") point. This is the purpose of the "resolve" methods. > Is there a notion of neighbours (as in: return the "n" entries that are closest to a given point)? I am picturing that functionality being implemented in a follow-up issue. [1] Regards, Matt [1] https://issues.apache.org/jira/browse/GEOMETRY-146 On Sat, Mar 12, 2022 at 10:36 AM Gilles Sadowski <gillese...@gmail.com> wrote: > > Hello. > > Le ven. 11 mars 2022 à 16:18, Matt Juntunen > <matt.a.juntu...@gmail.com> a écrit : > > > > Hello, > > > > I recently posted a PR [1] for GEOMETRY-142 [2], which is for adding > > PointMap and PointSet implementations. These are Map and Set > > implementations specifically designed to use Points as keys. > > Is there a gentle introduction to how it works and/or the intended > use cases? > > > They > > support fuzzy key comparison, meaning that points do not have to be > > exactly equal to each other in order to be considered equal by the > > map/set. (Note that this means these types do not follow the strict > > Map/Set contracts since they are not consistent with equals. This is > > documented in the PointMap/PointSet javadocs.) > > Does it entail issues about some use cases or applications that > need this functionality? Or do they not generally care about that > contract? > If so, maybe this collection shouldn't implement the standard JDK > interfaces (?). > > > I've completely hidden > > the implementation details from the public API > > Thanks. > > > since I anticipate > > changes in the future with regard to the algorithms used. > > Where does the anticipation come from? > > > Instances > > are created through factory classes in each space. Ex: > > > > PointMap<Vector3D, String> map = EuclideanCollections.pointMap3D(precision); > > PointSet<Point2S> set = SphericalCollections.pointSet2S(precision); > > > > Since fuzzy key comparison is used, I've added the following methods > > to the interfaces to allow access to the exact, "canonical" version of > > the key stored in the collection. > > > > PointMap<P, V> { > > // return the key corresponding to pt, or null if not found > > P resolveKey(P pt); > > > > // return the map entry corresponding to pt, or null if not found > > Map.Entry<P, V> resolveEntry(P pt); > > } > > > > PointSet<P> { > > // return the key corresponding to pt, or null if not found > > P resolve(P pt); > > } > > I don't quite follow; which are the corresponding "non-canonical" > accessors? > > > > > Reviews and comments are welcome. > > Is there a notion of neighbours (as in: return the "n" entries that > are closest to a given point)? > > Regards, > Gilles > > > > > Regards, > > Matt Juntunen > > > > > > [1] https://github.com/apache/commons-geometry/pull/194 > > [2] https://issues.apache.org/jira/projects/GEOMETRY/issues/GEOMETRY-142 > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
