[2.0] Stabilize `w` field of `p5.Vector`

[GregStanton]

[2.0] Stabilize w field of p5.Vector

A task list is below.

1. Decide whether to release (consider confusion and utility):

There are a couple of considerations.

Potential confusion:
Most users, especially beginners, will be unfamiliar with homogeneous coordinates, and will therefore be unfamiliar with the usual $(x, y, z, w)$ naming convention. They may guess that the order of coordinates is alphabetical, and this impression would be reinforced by the alphabetical ordering of the reference entries.

This confusion could be mitigated by clear documentation on the x, y, z, and w reference pages. These would need to be clearer than they currently are (right now, the full documentation is simply "The x component of the vector" for x, and is similar for the other components). However, it may not be necessary to release w into the public API (see the next section).

Limited utility?
A proposed Transform class would abstract away the need for homogeneous coordinates, with methods like applyToPoint() and applyToDirection(). These use homogeneous coordinates internally to distinguish points (which can be translated) from directions (which cannot be translated), so the user doesn't ever need to touch a w coordinate. If we think they won't need to use w coordinates, then it may not be worth it to release them into the public API. On the other hand, if we can find practical, concrete use cases that wouldn't already be handled by Transform, then it may make sense to release w to users, since the confusion it might cause may not be especially great.

2. Fix documentation

If we decide not to release w:
We could add a @private tag to its docs.

If we decide to release w:
Currently, a documentation error prevents this feature from appearing in the beta docs. Properties declared with get and set are typically documented by documenting the getter only, using the @type tag, instead of @returns, which is currently used. Once the getter documentation is fixed, the setter documentation may be deleted. At least, I think this should work.

[reshma045]

Hi @GregStanton, I would like to work on this issue, can you please assign this to me?
Thank you

[sidwellr]

I lack experience here, but is a 4D p5.Vector intended to represent a 3D point using homogeneous coordinates and projective geometry? If so, shouldn't the default value be 1 instead of 0?

I thought a 4D vector would represent a true four-dimensional vector or point. I suppose it could be used for either.

If I wanted to create quaternion fractals in p5, I'd probably use 4D Vectors (even though they aren't really quaternions) and the w field would be very useful.

[GregStanton]

@reshma045: Thanks for offering to help! You'll have first priority once we decide how to proceed.

@sidwellr: Thank you for moving the conversation forward! Right, vectors in any number of dimensions can be thought of as points. I'll briefly comment on a few applications of vectors in four dimensions that relate to the current discussion.

A few applications

Homogeneous coordinates

Homogeneous coordinates might be the most likely use case for p5 users. By using different values for $w$, these can be used to represent both points (which can be translated) and directions (which can't be translated) in three-space. However, as I mentioned, the planned Transform class will handle the $w$ component internally, so that users can write code like transform.applyToPoint(x, y, z). If the transform is a translation, this will move the point without users ever having to know a $w$ coordinate is used at all.

Physics and noise

Vectors in 4D may also be used for physics, e.g. with $(x, y, z, t)$ space-time coordinates. This may be useful for 3D noise in computer graphics, for example. Currently, p5 already documents (x, y, t) coordinates as a use case for 2D noise, but that naming convention isn't baked into the API like w would be. Using w for this might be a bit confusing.

Quaternions

I'm really glad you mentioned quaternions. It'd be great to consider this further, as it might be a significant use case. I'll just make a couple of observations for now:

• It's probably not a dealbreaker, but unfortunately, quaternions tend to deepen the confusion around the order of the coordinates. Both $(w, x, y, z)$ and $(x, y, z, w)$ naming conventions seem to be used, although $(x, y, z, w)$ might be more common in computer graphics.
• Users wanting to work with quaternions would likely want a full quaternion class with special methods, like what three.js provides. If we think such functionality might work better as an add-on library, then quaternions might not be sufficient justification to introduce a named fourth coordinate into the core p5 API. If such functionality were to fit into the core of p5, we'd need to consider how exactly (e.g. if it's a separate class, then again, we wouldn't need p5.Vector to have a user-facing w field).

Default value

Since there are different applications, I don't think there's a unique default value that's most sensible. Most importantly, it would probably be best if the values of the named components were to match the values of the components obtained by other means (see #8153). So undefined is likely the best default value.