[ https://issues.apache.org/jira/browse/GEOMETRY-119?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17312715#comment-17312715 ]
Gilles Sadowski edited comment on GEOMETRY-119 at 3/31/21, 9:41 PM: -------------------------------------------------------------------- IMO, {{normalizeOrDefault}} is *not* self-documenting; so one would need to look at the docs anyway. For usage that departs from the obvious semantics of {{normalize()}} (which implies throwing an exception), it's a mild effort to browse the docs and learn that the boolean is meant to return {{null}} instead of throwing an exception. I'm wary that several {{somethingOrDefault}} methods could then come up and lead to API bloat. Maybe the first thing would be to get some idea of the performance gain in actual use-cases (i.e. where {{tryNormalize}} is not an option.) was (Author: erans): IMO, {{normalizeOrDefault}} is *not* self-documenting; so one would need to look at the docs anyway. For usage that departs from the obvious semantics of {{normalize()}} (which implies throwing an exception), it's a mild effort to browse the docs and learn that the boolean is meant to return {{null}} instead of throwing an exception. I'm wary that several {{somethingOrDefault}} methods could then come up and lead to API bloat. Maybe the first thing would be to get some idea of the performance gain in actual use-cases (i.e. where {{tryNormalize}} is not an option. > Vector normalizeOrDefault() method > ---------------------------------- > > Key: GEOMETRY-119 > URL: https://issues.apache.org/jira/browse/GEOMETRY-119 > Project: Apache Commons Geometry > Issue Type: Improvement > Reporter: Matt Juntunen > Priority: Major > > A frequent use case when working with vectors, especially vectors coming from > external data, is attempting to normalize the vector, and if this is not > possible, to use an alternative value. For example, the > {{QuaternionRotation}} code > [here|https://github.com/apache/commons-geometry/blob/master/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/rotation/QuaternionRotation.java#L86] > does exactly this; it attempts to normalize a vector and failing that (ie, > if the vector is exactly zero), it returns a substitute value. The > {{QuaternionRotation}} class is able to take advantage of our internal > {{Vectors.tryNormalize()}} but callers outside of the library are not able to > do so and so are left with 2 choices: > 1. wrap the {{normalize()}} call in a try-catch and handle the exception > thrown on illegal norm values, or > 2. compute and test the norm prior to calling {{normalize()}} to ensure that > the call won't fail, resulting in 2 computations of the norm. > Neither of these options are very good. > I propose adding a new method to the Euclidean Vector classes to handle this > situation: {{normalizeOrDefault()}}. The method would accept a default value > (possibly null) to return if the vector cannot be normalized. The normal > would then only need to be computed once and an exception would not need to > be thrown in case of failure. The behavior of the current {{normalize}} > method would be the same. > Examples: > {code:java} > // get some kind of normal, preferably vec but +z will also do > Vector3D.Unit norm = vec.normalizeOrDefault(Vector3D.Unit.PLUS_Z); > {code} > {code:java} > // throw a very use-case specific error message > Vector3D norm = vec.normalizeOrDefault(null); > if (norm == null) { > throw new Exception("Invalid triangle at index " + i + ": cannot compute > normal."); > } > {code} -- This message was sent by Atlassian Jira (v8.3.4#803005)