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