[2.x] Fix dimensional quirk in the `heading()` method of `p5.Vector`

[GregStanton]

Problem

The documentation defines the concept of heading for 2D vectors specifically.

• In 1.x, there are no true 2D vectors, in that z is always defined. As a result, heading() produces output for fully 3D vectors, even when z is nonzero. It also produces output for “1D” vectors, since createVector(1) could be used as a shortcut for createVector(1, 0).
• In 2.x, we have an opportunity to resolve these unintended quirks.

Solution

Supporting only 2D input and adding errors for other dimensions would allow the simplest and clearest feature specification, and it’s how users expect this feature to be used. This could be considered a bug fix: users who accidentally provide a 3D vector can now be notified of this mistake, rather than silently allowing it. In practice, it appears that this change would cause zero (or near zero) disruption.

Disruption estimate: 0%

I used the Google search phrase site:https://editor.p5js.org/ "createVector" "heading" to find 50 sketches using the heading() method. Zero of them would break if we were to implement the proposed solution.

(I did exclude a few sketches, meaning I didn’t count them toward the numerator or denominator. One case used 4D vectors in 1.x, which is not supported, and the sketch appeared to be broken already. I also excluded three sketches that used createVector() with zero arguments somewhere in their heading calculations, since it’s not 100% clear what effect this will have in 2.x. But the goal is to prevent errors from arising in this case.)

Blocking issues (foundational issues for all of p5.Vector)

If you're interested in helping to move the current issue along, you can add a comment on the current issue to indicate whether you support the proposed solution. After that, you could add a comment on the following issues to indicate whether you support the proposals they contain, along with a brief rationale.

• #8153: Consensus would clarify the meaning of 2D. In 1.x, this meant $z=0$, but according to the proposal, in 2.x it'd mean the vector has exactly two defined elements (this would resolve an inconsistency with the current implementations of .z and toString()).
• #8155: Consensus on a user-facing API for checking dimension size would enable a more stable implementation of heading(). Adding a comment on the current leading proposal (.shape), either in support of the proposal or against it, would be helpful. The exact format of this API depends on the outcome of an ongoing review of getter/setter patterns in p5, so any comments can focus on the "shape" concept.

[reshma045]

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

[justAnotherAnotherUser]

Hi @GregStanton I would like to start work on this as mentioned in the parent issue

[GregStanton]

Hi @reshma045 and @justAnotherAnotherUser! Thank you both for volunteering. Please see the comment I just added to the setHeading() issue about how we can organize the work on this.

[adity1raut]

/assign

[Anirudh-x]

Hi @GregStanton,

I'm interested in working on this issue for GSoC preparation. I've reviewed the blocking issues #8153 and #8155 and added supporting comments there.

My understanding of the fix:

1. heading() should only work for 2D vectors (vectors with exactly 2 elements)
2. It should throw a clear error for 1D, 3D, or higher-dimensional vectors
3. Implementation depends on the .shape API from #8155

Questions before starting:

1. Should I wait for #8153 and #8155 to be fully resolved before implementing?
2. If there's a temporary implementation approach (e.g., checking hasOwnProperty('z')), should I use that?
3. Are there any additional test cases I should consider beyond 1D, 2D, 3D, and 4D vectors?

I'm ready to start once the blockers are cleared. Thank you!

[justAnotherAnotherUser]

Hi @GregStanton A bunch of stuff has come up and I dont see myself having the time to work on this any time soon. I think it would be best to reassign this issue to somebody else with more availability to work on this issue. Greetings, User

[reshma045]

Hi @GregStanton, can I be assigned this issue?

[Huc91]

Hi @GregStanton I would like to work on this

[reshma045]

Hi @davepagurek, @perminder-17 can you please re-assign this issue to me? I would like to work on this.