[2.0] Stabilize the undocumented `dimensions` field of `p5.Vector`

[GregStanton]

[2.0] Stabilize the undocumented dimensions field of p5.Vector

Possible bugs

The dimensions field isn't currently documented, but it appears to users when they use the command console.log(myVector), and it may sometimes have inaccurate values, as observed here and here.

Thanks to @sidwellr for the following summary:

The gist of the comments linked above is that dimensions does not always reflect the true dimensions of the vector. For example, createVector() (with no params) creates a 3D vector [0, 0, 0] but sets dimensions to 2. And p5.Vector.sub(createVector(1, 2), createVector(1, 2, 3)) will return a 3D vector with dimensions set to 2.

Proposal: Renaming dimensions to dimensionSize prior to release

This would likely be a useful feature, with precedent in other libraries, e.g. babylon.js has dimension. But, prior to release, it may be renamed to dimensionSize, which works better in the context of p5. This name would be clearer, and it'd allow a consistent interface across vectors, matrices, and potentially tensors:

Data structure	Proposed property	Example value	Data type
Vector [x, y, z]	.dimensionSize	3	Number
Matrix (3 rows, 4 cols)	.dimensionSizes	[3, 4]	Array
Matrix (3 rows, 4 cols)	.dimensionCount	2	Number

This naming scheme prevents users from falling into type traps and ambiguity traps, as described in this comment.

Settable?

Also, there would need to be discussion about whether to (a) protect this field from modification or (b) support modification, e.g. by padding a vector with zeros or truncating it if needed. Right now, as @sidwellr noted, "users can currently set dimensions to any value, including nonsensical ones like 2.5 and 'frog'."

Tasks

• Fix bugs
• Reach consensus on the rename.
• Implement the rename, if accepted by the community.
• Reach consensus on writability and associated behavior.
• Implement the agreed upon writability behavior.

Edits:

1. Added points from @sidwellr.
2. Added table to illustrate naming scheme, and clarified its benefits.
3. Added task list.

[sidwellr]

The gist of the comments linked above is that dimensions does not always reflect the true dimensions of the vector. For example, createVector() (with no params) creates a 3D vector [0, 0, 0] but sets dimensions to 2. And p5.Vector.sub(createVector(1, 2), createVector(1, 2, 3)) will return a 3D vector with dimensions set to 2.

In addition, users can currently set dimensions to any value, including nonsensical ones like 2.5 and "frog".

None of these affect operation of the vector; dimensions is not used internally.

[sidwellr]

I personally prefer the term dimensions to dimensionSize. It's intuitive: a three-dimensional vector would have dimensions 3 for example. It would also work for matrices and tensors, but the result would be a list instead of a number.

[GregStanton]

Thanks, @sidwellr!

I personally prefer the term dimensions to dimensionSize. It's intuitive: a three-dimensional vector would have dimensions 3 for example. It would also work for matrices and tensors, but the result would be a list instead of a number.

Thanks for sharing your feedback, and that's a great point about intuitiveness. For a single vector, dimensions feels natural and intuitive. The challenge appears when we extend this to a matrix.

Type trap

This creates a "type trap" that could be confusing for users. For example, a user might write code that works perfectly for a vector called myData: if (myData.dimensions > 2) { ... } But if this is a generic function that operates on vectors and matrices, the same logic will silently fail when myData is a matrix: in JavaScript, [3, 4] > 2 evaluates to false in a weird way.

This is the kind of subtle bug that can be frustrating for beginners and experts alike. Your comment totally clarified the nature of this type trap for me. Having a clear, unambiguous naming system can help users avoid these traps.

Ambiguity trap

We also need to distinguish between two different concepts:

• How many numbers define the size of each axis? (Your "list" for a matrix)
• How many axes are there in total? (e.g., 1 for a vector, 2 for a matrix)

Solution

To prevent users from falling into those traps, we could use the naming scheme I proposed, which gives a distinct name to each concept:

Data structure	Proposed property	Example value	Data type
Vector [x, y, z]	.dimensionSize	3	Number
Matrix (3 rows, 4 cols)	.dimensionSizes	[3, 4]	Array
Matrix (3 rows, 4 cols)	.dimensionCount	2	Number

This system ensures that the names are always clear and the return types are always consistent, respecting the principle of least surprise. It completely resolves the ambiguity of the term dimensions by providing distinct names for distinct concepts: the size of the dimensions (.dimensionSizes) and the number of dimensions (.dimensionCount).

Extending this to Tensors (Advanced Example)

This pattern scales perfectly. For a tensor representing a 2x3 pixel image with 4 color channels (a 2x3x4 tensor), the properties would be:

.dimensionSizes: [2, 3, 4] (an array of the size of each dimension)

.dimensionCount: 3 (the number of dimensions, often called "rank")

How does this reasoning sound to you? Thanks again for your comment. It helped me clarify the core issue of return type (Number vs. Array), which is a really important detail to get right.

[GregStanton]

Also, thanks @sidwellr for your summary of current issues with the behavior of dimensions. That was really helpful. I've incorporated your comments into this issue's top post.

[davepagurek]

I feel like having those three properties that all sound similar might be more confusing just because there's more to remember, and all sound very similar to each other. Are there more distinct names we could use? As another idea, I wonder if rather than having three different properties, we can take inspiration from the numpy shape? That always returns an array, so a 3d vector would be [3], a 2D vector would be [2], a 3x4 matrix would be [3, 4], and the three properties we currently have can be fairly easily derived from that. The main downside there is that the shape of a vector is [3] instead of 3, but if we're expecting this to mostly be looked at as a step in debugging, that could be fine?

[GregStanton]

Thanks @davepagurek! This is a very productive conversation. I think your ideas have led to some possible improvements.

I can see how "size" vs. "count" might appear too similar. That's a good point. One way to rectify that is to replace dimensionCount with the usual rank.

Downsides of rank are that beginners will be less familiar with the term, and it conflicts with the meaning of "rank" that students learn in linear algebra. However, it's a standard term and is used in libraries like TensorFlow.js. Since one of the goals is to provide an onramp to those kinds of libraries, I think using rank has advantages. Also, there are ways around the naming conflict with linear algebra. Just as we will likely distinguish e.g. multiply() from matrixMultiply(), we could distinguish .rank from .matrixRank.

Here are a couple more variations on your idea to reduce the number of similar terms.

Data structure	Proposed property	Example value	Data type
Vector [x, y, z]	.dimension	3	Number
Matrix (3 rows, 4 cols)	.dimensions	[3, 4]	Array
Matrix (3 rows, 4 cols)	.rank	2	Number

I think "dimension" is kind of a fraught term, though, the more I think about it. The issue is that there are two interpretations: the size of each data axis (3 for a 3D vector, 3x4 for a matrix with 3 rows and 3 columns) or the number of axes (1 for any vector, 2 for any matrix). My original API was an attempt to address this in a kind of subtle way, but perhaps there are better options, like maybe the following:

Data structure	Proposed property	Example value	Data type
Vector [x, y, z]	.shape	[3]	Number
Matrix (3 rows, 4 cols)	.shape	[3, 4]	Array
Matrix (3 rows, 4 cols)	.rank	2	Number

From what I've seen, shape is a common name for what I'm calling dimensionSizes, but it's pretty far from universal. My original intuition was that vector.shape seems a bit unclear by itself, at least for people unfamiliar with this naming convention (which will likely include most p5 users). The other downside, as you noted, is that a 3D vector would have a shape of [3] rather than 3. That may be less intuitive by itself, but it doesn't seem too hard to get used to, and it may be a feature rather than a bug. It creates a unified, common API that matches the TensorFlow.js API, which provides a strong precedent. Using such a precedent reduces the likelihood of unforeseen API problems down the road and aligns with the goal of providing an onramp to advanced libraries.

Thoughts?

I can keep working on this, but do you have any initial thoughts about those options?