Hello Matt. Le dim. 13 mars 2022 à 15:41, Matt Juntunen <matt.a.juntu...@gmail.com> a écrit : > > 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.
I know; but as the code base provides more and more functionality (thank you!) it would be great to keep the tutorials/userguide in sync. A simple "How to..." is often enough (and faster than browsing the Javadoc) in order to get at the most common usage. > > > 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. IMHO, the above two Q & A are worth mentioning in the userguide. The second especially may attract some user's attention who could provide the missing info. [Of course, it should also appear at the relevant places in the Javadoc.] > > > 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. Indeed. > 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. I'm a little bit confused: Isn't it always the case that getEntry(p).getKey() will return the originally inserted (i.e. "canonical") point (i.e. not "p")? Anyways, I'd suggest that this be illustrated in the userguide (linked to a working application in "commons-geometry-examples"). > > > 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] Thanks. However, my impression is that the API should be more general: ---CUT--- public Iterable<P> closestInRange(P point, double radius); ---CUT--- Unless I'm missing a standard use-case, the specialized methods "closestFirst" and "farthestFirst" don't seem useful (and wasteful of computing resources: If iterating over the whole set, why would one want to start from some particular point?). Regards, Gilles > > Regards, > Matt > > [1] https://issues.apache.org/jira/browse/GEOMETRY-146 > > > [...] --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
