[p5.js 2.0 Bug Report]: p5.Vector.random2D() creates a 3D vector instead of a 2D vector.

[sidwellr]

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

p5.js version

2.0.5

Web browser and version

Brave 1.81.136

Operating system

Linux Mint 6.8.0-78-generic

Steps to reproduce this

Vectors in version 1 are always 3D, so this was correct. But version 2 allows arbitrary length vectors, including 2D vectors, so p5.Vector.random2D() should create a 2D vector now. It is common to add the random vector to an existing one, and adding a 3D vector to a 2D one creates an inconsistent result (see my comment to issue #8117).

The first example in the documentation shows an example of this:

function setup() {
  // Create a p5.Vector object.
  let v = p5.Vector.random2D();

  // Prints "p5.Vector Object : [x, y, 0]" to the console
  // where x and y are small random numbers.
  print(v.toString());
}

The code should print the 2D vector "[x, y]", not the 3D vector "[x, y, 0]". (The example will need to be updated as well.)

[suynep]

@sidwellr It seems the z component exists by default in p5.Vector primarily for consistency, compatibility, and future-proofing... and defaults to 0 in 2D Vector initialization

[sidwellr]

@suynep I don't think so. A 2D vector doesn't actually contain a z component; although vec.z exists for convenience, it will be 0 if there are less than three dimensions (just like vec.w will be 0 if there are less than four dimensions).

[Swaim-Sahay]

Hey @sidwellr

Issue: [Bug] p5.Vector.random2D() creates a 3D vector instead of a 2D vector

Description In p5.js version 2.0.5, the p5.Vector.random2D() method is incorrectly creating 3D vectors [x, y, 0] instead of proper 2D vectors [x, y]. This is inconsistent with the method's intended purpose and creates problems when adding random vectors to existing 2D vectors, resulting in dimension mismatches and unexpected behavior.

Benefits
-Ensures p5.Vector.random2D() creates proper 2D vectors as intended
-Maintains consistency with p5.js 2.0's support for arbitrary-length vectors
-Prevents dimension mismatch errors when combining vectors
-Improves mathematical accuracy and expected behavior
-Aligns implementation with documentation expectations

Suggested Implementation
-Modify p5.Vector.random2D() to return vectors with only x and y components
-Update the method to create vectors without the z component (no default 0 value)
-Ensure the returned vector has length 2 instead of 3
-Update documentation examples to reflect correct output format [x, y]
-Add unit tests to verify 2D vector creation

Contribution
I would like to fix this issue by updating the p5.Vector.random2D() method implementation to properly create 2D vectors, ensuring mathematical consistency and preventing dimension-related bugs in vector operations.

Thank you

[sidwellr]

@Swaim-Sahay Thanks for offering to fix this. When you look at p5.Vector.random2D(), you will find it calls p5.Vector.fromAngle(), which has the same issue, and that is where the fix will actually be made. But the documentation for both random2D and fromAngle needs to be updated to show a 2D result.

[ayushman1210]

Hi @sidwellr !!
is this issue still opens ?
if yes can you please assign it to me

[sidwellr]

@ayushman1210 I'm new here, but my understanding of the Contributor Guidelines is that a steward or maintainer needs to assign issues to people. Also, Swaim-Sahay has already offered to fix this, so would likely have priority.

Pinging the math stewards @GregStanton @holomorfo so they can take appropriate action.

[ayushman1210]

Thanks for pointing this out! You’re right that only stewards/maintainers can assign issues.

Just to add, I had commented on this issue before and have been active since. As per the Contributor Guidelines, priority generally goes to the earliest active commenter in the queue.

Of course, I’ll wait for @GregStanton and @holomorfo to confirm, but I’d like to be considered for assignment as well.

Appreciate the clarification!

[holomorfo]

Hi team! I worked on the matrix and vector re factor. I agree with you that there are some inconsistencies regarding the dimension of the vectors. However, that we currently have is driven by the interaction with render pipeline so if we update to remove the third coordinate, this would potentially break a lot of the existing rendering code. This is the reason why Greg if suggesting at least for the matrix class you have two different implementation one for the rendering and one that behaves more consistent with our mathematical expectations. This might be relevant to do also for the Vector class. I would say that the issue at hand is that the vector does not behave intuitive, but it's doing exactly what we need at the moment from the rendering side. However, we might be open to some flexibility, if some of you find a way of updating without breaking the existing tests and functionality. I invite the first person that raise this to take a bite out of this problem and try to create a PR where you can find a solution on how to improve the class without breaking existing contract. It's important to note that this behaves very different in v1 one than v2 of p5.js if you are going to work on this, please make sure you are working on version two. cc @GregStanton

[davepagurek]

un-assigning for now, we'll figure out the scope of the work a little first!

[GregStanton]

Hi all!

Thank you for this discussion, and for pinging me.

In the opening post, @sidwellr observed that p5.Vector.random2D() appears to create a 3D vector instead of a 2D vector. This is a great observation, and it leads to a subtle but fundamental aspect of the p5.Vector class: it's designed to create the illusion of 2D vectors, while all vectors are, in fact, 3D under the hood. This design choice has a long history, but as you've noticed, it can lead to some confusing behavior.

The good news, I think, is that we can eliminate part of the confusion now. And we can eliminate all the confusion in a future 3.0 release. I'll explain it as clearly and concisely as I can. It's still possible my analysis overlooks something important, and that my conclusions need to be revised. Please let me know if so!

Note:
🙏Some of you have been active on other recent, related issues, including #8048 and #8117. If there are any questions about those issues that aren't answered by this comment, please feel free to ping me on the relevant issue, and let me know what still needs to be addressed. I'll try to help as best I can. Thanks!🙏

Short version

In the long run, I think we can eliminate confusion by making $n$-dimensional vectors always be $n$-dimensional, as suggested by @Swaim-Sahay. For example, if a vector is created like createVector(2, 3), then the vector should have only two defined components v.x and v.y, its string and array representations should only contain two components, and it should be treated as two dimensional in all operations. For anyone who hasn't worked with p5 before, it may be hard to imagine p5.Vector working any other way.

However, that's not how p5.Vector currently works, and getting it to work like that would require breaking changes. We probably can't make such changes until a future 3.0 release. In the meantime, we can reduce the confusion with a partial solution: revert the 2.0 behavior of the toString() method for vectors back to the 1.x behavior. This may sound counterintuitive, as if the change would move us in the wrong direction. I'll explain the reasoning in the long version of this comment.

Note to beginners: If you're interested in reading all the gory details of this comment in the long version, you're very welcome to do so! But, it's also fine if you skip it. Those of us who are already familiar with the details (e.g. @holomorfo and @davepagurek) can sort out the best course of action. Then we can assign this issue to anyone who is still interested to work on it.

Long version

History of the "2D illusion"

The 1.x version of p5.Vector treated all vectors as 3D: whether they were created by passing 0, 1, 2, or 3 arguments to createVector(), the result was always a vector with defined x, y, and z components. However, the API has been described as providing an "illusion" that 2D vectors are possible.

Example 1: 2D Illusion

function setup() {
  // It appears we're creating and operating on 2D vectors
  let v = createVector(1, 1);
  v.add(2, 3);
  
  // 3 4
  print(v.x, v.y)

A possible rationale for the 2D illusion

I think @shiffman may be able to shed light on the original motivation for creating this illusion, as this design was chosen intentionally (at least in the case of Processing's PVector). My guess is that the decision was based on a few key benefits:

1. A unified 3D back end: Treating all vectors internally as 3D is simple, it ensures seamless interoperability (any vector can interoperate with any other, which may be convenient in a creative context), and it may offer performance benefits due to a consistent object shape.
2. A simple 2D front end: Since users, especially beginners, will find it easier to think and write code in two dimensions, an API that allows users to work exclusively with x and y components is more accessible.
3. API consistency: The API for vectors can work similarly to the API for graphical functions: as with point() in WEBGL mode, an overload with only x and y components is allowed, but internally, a z-component is always created.

That's just a guess. My goal is to try to understand the potential benefits of the 2D illusion, in order to determine what might be lost if we were to remove it.

Some problems with the 2D illusion

Unfortunately, it appears that the 2D illusion has led to some problems. In each of the examples below, it leads users to misunderstand how vector features work.

Example 2 (continued from above): Predictability of defining properties

  // Reality: p5.Vector Object : [3, 4, 0]
  // Illusion: [3, 4]
  print(v.toString());
  
  // Reality: 3 4 0 
  // Illusion: 3 4 `undefined`
  print(v.x, v.y, v.z);

Example 3: Predictability of a basic comparison

function setup() {
 let v = createVector(1, 1);
 let w = createVector(1, 1, 0);
 
 // Reality: `true`
 // Illusion: `false`
 print(v.equals(w));
}

Example 4: Predictability of a standard operation

function setup() {
 let a = createVector(1, 0);
 let b = createVector(0, 1);
 let c = p5.Vector.cross(a, b);
 
// Reality: p5.Vector Object : [0, 0, 1]
// Illusion: `undefined`, or 1 (depending on who you ask)
 print(c.toString());

// EXPLANATION:
// math students would likely expect `undefined`
// libraries taking this approach: openFrameworks, babylon.js, ...

// physics or computer graphics students may expect the scalar 1 (a signed area, useful for e.g. winding order)
// libraries that take this approach: three.js, Blender (Python API), ...

// few are likely to expect [0, 0, 1]; producing a 3D vector in a 2D context is confusing, and less convenient
// I haven't found libraries that do this, other than p5
}

Why the 2D illusion causes problems for math features, despite working well for graphics features

Essentially, the 2D illusion works for graphical functions because the public API doesn't (as far as I know) reveal the illusion to be different from reality. The implementation of a feature like point(x, y), which internally adds a z-coordinate when needed, is completely hidden from users. That kind of information hiding is good.

Unfortunately, we can't hide information in the same way with a math feature like p5.Vector. So its public API breaks the illusion, resulting in the opposite of the intended effect: instead of leading users to a simple understanding of p5.Vector, it leads them to multiple misunderstandings.

Extra complexity introduced by p5.js 2.0

As @sidwellr observed when opening this issue, 2.x introduced $n$-dimensional vectors. The intent is for all features to support vectors of any dimension, except for special cases where that's not possible, like the cross product. I'm personally excited about this, as it opens up really cool opportunities going forward.

Unfortunately, this new feature set, when combined with the legacy 2D illusion, adds more complexity. The fundamental problem is that, even in 2.0, there are no vectors that truly have a dimension less than 3. The actual z component is still zero, and the vectors behave as if they are 3D. For example, in math and in scientific computing software, 2D vectors typically can't be added to 3D vectors.¹ But, in p5, a vector created with just two components behaves like a 3D vector: it can be added to 3D vectors, and it can be used to compute vector cross products (as opposed to scalar cross products), which are typically only defined for 3D vectors.

The best we can do in p5.js 2.x, conceptually

For vectors in p5.js 2.x, the following seems to be the simplest possible mental model: vectors in p5 all have dimension 3 or higher, but we can use 1D or 2D syntax as a shortcut when the trailing components are zero. That's more complexity than we'd ideally have, but it seems to be the best we can do for now.

Why we can't do better in p5.js 2.x

In order to truly have vectors of dimension less than 3, we'd need to make breaking changes. For example, if we want createVector(2, 3) to truly create a 2D vector, we'd want to change z from 0 to null or undefined. So, assuming the usual policy of not allowing breaking changes outside of major version upgrades, a complete solution doesn't seem possible until a potential 3.0 release.

Note for beginners: Here's why we can't make that kind of change yet. If a user relied on z being 0 in their code, they can't upgrade to get the latest patch or minor feature enhancements without breaking their code. So, this would be what's called a "breaking change." In order to maintain the trust of the community, the p5 policy is to not break users' existing code outside of major version releases (1.0, 2.0, 3.0...). In order to give users plenty of advance notice, 2.0 won't actually become the main p5 version until around next August, and any work toward 3.0 likely won't start until after that.

Note for @davepagurek: We previously talked about possibly replacing 2.0's getValue() and setValue() with a joint getter/setter like entry(). The idea is to respect the joint getter/setter pattern that other parts of the API are moving toward, while also using a more precise name ("value" could refer to the value of the vector as a whole, or something else, whereas "entry" refers correctly to one component and is still flexible enough to make sense in the context of matrix or tensor classes). I'm guessing these kinds of breaking changes are no longer an option, for good reason; but if such changes are on the table, we could potentially do some important cleanup before the main 2.0 release next August.

Recommended action for p5.Vector in p5.js 2.0

There is some cleanup that we can do in p5.js 2.0 to ward off a small amount of confusion. It has to do with a change that was made to the toString() vector method. This is best illustrated with an example.

Example 5: toString() in 1.x and 2.0

function setup() {
 let v = createVector(1, 1);

// Result in 1.x: [1, 1, 0]
// Result in 2.0: [1, 1, 0]
// (no change)
print(v.array());

// Result in 1.x: p5.Vector Object : [1, 1, 0] 
// Result in 2.0: [1, 1] 
// (breaking change)
 print(v.toString());
}

I think we can safely revert this change, and although I can see why the change could be beneficial in the long run, I think we should revert this change for 2.x:

• Why we can revert the change: The change to string representations like '[1, 1]' is a breaking change that is not documented in the main public-facing list of breaking changes from 2.0. It's also not documented in the toString() reference page for 2.0—the documented behavior still matches the behavior of 1.x. I think @holomorfo can tell us if the change was intentional or not, but it's not the behavior that's been communicated to users. Also, the change to toString() produces behavior that's inconsistent with the behavior of array(), as well as the values of v.x, v.y, and v.z. So, the new behavior of toString() may be considered to be a bug, and it should be safe to revert it.
• Why we should revert the change: The output of toString(), the output of array(), and the values of the components v.x, v.y, and v.z should ideally all be consistent. Since we can't change the value of v.z without introducing a breaking change, all of these should produce three components.

Why we can likely eliminate all confusion in a future 3.0 release

Looking toward a potential 3.0 release, we could likely eliminate the "2D illusion" altogether. Revisiting the potential rationale for it, the counterpoints are clearer now:

1. Regarding the unified 3D back end, the benefits are outweighed by the confusion it causes. Interoperability often hides bugs rather than providing convenience. While performance is important, any costs from varied object shapes are likely negligible and could potentially be addressed with other optimizations. Distinguishing dimensions, on the other hand, greatly reduces the conceptual burden for users, allowing them to correctly predict the behavior of basic operations (like equality comparison) and advanced operations (like the cross product, as seen in libraries like three.js and Blender's Python API).
2. We can still provide a 2D front end. Basing it on truly 2D vectors makes it more accessible for beginners and more expressive for advanced users.
3. The argument for API consistency with graphical functions like point() doesn't quite hold, as the internal z-component is completely hidden from the user, whereas the p5.Vector illusion is easily and confusingly broken.

Summary: In general, there doesn't seem to be a fundamental reason why a given vector should be simultaneously an illusory 2D vector and an actual 3D vector. If my understanding is correct (please let me know if not!), then rendering is the only time that we need to silently interpret 2D input like [1, 1] as [1, 1, 0].² In this case, where a 2D scene is being rendered by a 3D renderer (e.g. to leverage hardware acceleration), it seems that it should be the job of the renderer to place a 2D point within its 3D world. The vector doesn't need to live in two worlds at once.

Low effort implementation? A feature like point() is already programmed to handle both 2D and 3D input when a 3D renderer is in use. It looks like the current implementation may even work as-is if p5 were to implement true 2D vectors (in which the z-component is undefined). But, @holomorfo mentioned that "this would potentially break a lot of the existing rendering code," so maybe it would require more work? If that's true, it still seems like it'd be worthwhile in the long run.

Note for @holomorfo: You also mentioned an interesting idea about potentially having separate mathematical and graphical vector classes, akin to the separate Transform and Matrix classes that I've proposed. If you want to explore this further, let me know. I'd be interested to talk about it. I wrote down some initial ideas but will leave them out of this comment, since it's obviously long already. My initial conclusion is that separating out graphical features makes less sense for vectors than for matrices, but I wouldn't want to close the door on the idea without fully considering the potential advantages.

Footnotes

1. Note about mismatched dimensions (since some of you mentioned this): Typically, if vectors of mismatched sizes are allowed to be combined through operations like addition, it's required that one of the vectors is 1D. For example, suppose a 1D vector is represented by the array [2]. If that's added to a 3D vector [1, 1, 1], then the result is [3, 3, 3]. This may be useful in some situations, and it's consistent with how the vector's multiplication method works. The general concept, which applies also to matrices and tensors, is known as broadcasting. There are standard rules for this, but p5 doesn't currently follow them. We may want to change this in a future 3.0 release. ↩

2. Silently treating 2D vectors as 3D vectors was described in #8048 as being useful for operations like dot and cross products. I'd counter that it's not necessary for dot products, and it actually makes cross products harder to implement in a sensible way (see Example 4). ↩