Gilles, > it would be great to keep the tutorials/userguide in sync.
Sounds good. I'll update the user guide in this PR. > 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")? Map does not contain a "getEntry" method. If it did, that would indeed be preferable. > 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?). Could you post this comment on the JIRA issue and we can continue the discussion there? Regards, Matt On Sun, Mar 13, 2022 at 11:25 AM Gilles Sadowski <gillese...@gmail.com> wrote: > > 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
