[jira] [Comment Edited] (GEOMETRY-119) Vector normalizeOrDefault() method

["Gilles Sadowski (Jira)" <ji...@apache.org>]

    [ 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)