"normalize" documentation

brooke_spreen

It looks like the documentation for the function "normalize" has been updated recently. I find it rather difficult to interpret.....if I had not used it several times in the past, it would be difficult to figure out which function would give me the Direction of a vector. This could maybe use some clarification? Perhaps "returns Direction" instead of "returns Vector" in the first line of documentation?

normalize (vector is Vector) returns Vector

Returns the (unitless) result of normalizing vector. Throws if the input is zero-length.

konstantin_shiriazdanov

Direction is not a type in onshape, it's just a name of a field of some data types which is supposed to contain unitless vector of length 1, mathematically it's just v0 = v/|v|. For someone would be more confusing to have directions and vectors not being the same type.

brooke_spreen

That's not entirely true. If you run `debug(context, a_dir)`, the readout recognizes that it is a direction. Regardless, I think it would be informative to mention something about "direction" in the description!

caden_armstrong2

Something you have to remember is that a vector with units can still be describing a direction. With units, that vector also has a magnitude. An example of this is in the StartDerivative field in the opFitSpline operation.

The normalize function does not give you the "direction" of a vector, a vector is a direction. The resulting vector is in the same direction, but the magnitude is 1 (unitless).
Normalizing is a common mathematical term, just as dot product and cross products are.

Types such as "line" specify direction to differentiate between the two vectors in the definition, one for a point and one for a direction. Both are vectors that could be normalized. Vector is the data type, direction is the purpose.

brooke_spreen

The normalize function returns the unit vector of the given vector. This is what OS seems to refer to as a "Direction".  A bit of documentation from the `vector` module:

is3dDirection (value) predicate

True for a unitless 3D Vector that is normalized (i.e. has length 1)

EXAMPLE

vector(0, 0, 1)

Though perhaps to avoid confusion the terminology "unit vector" is a safer bet

konstantin_shiriazdanov

brooke_spreen said:

Though perhaps to avoid confusion the terminology "unit vector" is a safer bet

a unitless unit vector!

brooke_spreen

Hehe yes ;D