[2.x] Fix dimensional quirk in the `heading()` method of `p5.Vector`
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 24k
- Forks
- 3.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 25
Description
Problem
The documentation defines the concept of heading for 2D vectors specifically.
- In 1.x, there are no true 2D vectors, in that
zis always defined. As a result,heading()produces output for fully 3D vectors, even whenzis nonzero. It also produces output for “1D” vectors, sincecreateVector(1)could be used as a shortcut forcreateVector(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
.zandtoString()). - #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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the p5.Vector heading() entry point and the proposals in issues #8153 and #8155, since the requested behavior depends on their unresolved consensus. Confirm how 2D, 3D, and 1D vectors are represented in 2.x, then define completion as heading() accepting only 2D input and reporting errors for other dimensions without disrupting the documented 2D use case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- computer-graphics
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100