`p5.Color.equals` method

[aidanwyber]

Increasing access

Sometimes it's useful to be able to be able to compare colors against stored colours, for example, when sampling an image with a constrained palette. It would be great if you could compare p5.Color objects with eachother, which is kind of a hassle now.

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)

Feature enhancement details

I suggest creating a equals() method like in string objects. I could be a piecewise comparison of either of the p5.Color.levels or p5.Color._array arrays, but I don't quite understand what their difference is in practice (which one is the master).

[ksen0]

Thanks for the idea @aidanwyber ! Clarification question: What do you think the behavior should be on non-opaque colors? E.g., they may be the same in terms of comparing the rgba values, but since they are combined with the colors they may overlap with, they would be different. Should it be only defined for opaque colors?

Happy to hear others' thoughts as well.

[GregStanton]

Hi @aidanwyber and @ksen0:

It seems like this feature could be really useful! I have some thoughts to share, since I've been working on related features.

Motivation

Could we flesh out the proposed use case, and maybe add some other use cases if possible? This feature seems almost like a no-brainer, but I think it's always a good idea to provide clear motivation for any addition to the API.

Feature specification

Transparency

@ksen0:

What do you think the behavior should be on non-opaque colors?

I do think it'd make sense to support equality comparison for non-opaque colors. Although the rendered color for a given pixel depends on surrounding colors, the blending behavior of two RGBA colors color1 and color2 is the same if their R, G, B, and A components are all equal (and similarly for other color modes). In other words, if color1 and color2 are both blended with the same third color under the same blend mode, they’ll result in the same blended color. If we can’t check equality of alpha values, then we can't determine if two given, non-opaque colors will have the same behavior in this sense. For inspiration, Color4 in babylon.js, Color in Godot, and Color in Unity have methods for checking equality of RGBA colors (not just RGB).

Tolerance

It would likely make sense to support checking for both exact and approximate equality. Approximate equality is often needed, to account for issues with the way numbers are represented: a value that should be 0.3 may be 0.30000000000000004 instead, but for practical purposes, these are equal.

We already have a clampToZero() method on p5.Vector for dealing with this sort of thing, although it's less general, and it mysteriously disappeared from the documentation on the beta version of the reference (it's still in the 2.x codebase).

Allowing an optional, customizable tolerance might also be useful, since it'd allow users to check if colors are near each other, in a sense that they could define. This could include a customizable distance tolerance, and possibly even a customizable distance function (e.g. chessboard, taxicab, or Euclidean). If custom distance functions appear useful but not fundamental enough for p5 itself, we could still take care to make the API extensible enough for add-on libraries to support them.

API

Given the current state of p5's API, there are more nuances to consider than we might expect at first glance. So this is the heftiest section of my comment. I think it's good to put some of the challenges on record, but the preceding issues should probably be addressed first.

Approaches

The existing API that we'd want to use for comparison is the equals() method of p5.Vector. The Vector and Color APIs have some problems that I won't get into in this comment, though, so I expect we'll need to make some changes in the long run. That may give us flexibility to consider a few possible approaches for a new equality feature:

• extend equals() on p5.Vector to support approximate equality and provide a similar method on p5.Color
• provide one method for exact equality and one for approximate equality, on each of p5.Vector and p5.Color
• support a toArray() method on p5.Color objects, so that users can leverage the equality method of p5.Vector()
• include standalone features for exact and approximate equality (combined or separate) under Data, with overloads

I'll clarify these options further below.

Sources of inspiration

It's helpful to look at how other libraries tackle these kinds of features. A few examples are below.

• The babylon.js library has equals() and equalsWithEpsilon() for its Color4 objects
• Godot relies on general operators for exact equality and provides is_equal_approx() for approximate equality of colors
• Unity provides Color.Equals for exact equality and suggests using a general operator for approximate equality
• The glMatrix library has equals() (approximate) and exactEquals() for matrices

Note that there are no consistent conventions across libraries. For example, in glMatrix, the generic equals() refers to approximate equality, whereas in babylon.js, equals() refers to exact equality. This suggests that neither convention is more natural than the other. Although equals() might typically be understood to mean exact equality, approximate equality is more useful in practice and might therefore make sense as a default. This makes it hard to remember the meaning of equals() in APIs like these, but we can avoid some of the pitfalls, as I'll describe below.

Core issues

There are a couple core issues to decide on: (1) would we provide separate features for exact and approximate equality, or would we have one equals() feature that supports both? (2) Where would we put the features? I'll comment on these briefly.

(1) A single equals() method may have a couple of advantages: it's more economical in terms of API surface area, and it allows for a simpler function name. It may also address the issue of remembering whether "equals" refers to exact or approximate equality by default—if that option is specified through a parameter like EXACT or APPROXIMATE, then even if the parameter is optional, users who have trouble remembering the default could always make their choice explicit. A disadvantage is that a single equals() method that handles both exact and approximate equality will, by itself, be more complex than separate functions like exactEquals() and approximateEquals().

(2) Right now, p5.Color only supports a toString() method. This is an inconsistency with p5.Vector(), which has methods for converting to both a string and an array. If we add a toArray() method on p5.Color, then users will be able to export to an array and create a vector from it in one step, and then use p5.Vector's equality features. That's less convenient than having a direct equality method for colors, but a toArray() method should likely be added anyway, and it'd make equality checks for colors more convenient than they are now. In the long run, we'd probably want an equality operator that works directly with colors, but there are some outstanding questions regarding where such a feature would go in the overall p5 API.

There are some details about what I just said that aren't quite right, and I need to explain what the outstanding questions are that I alluded to. I'll deal with all that in the following sections.

Corrections, and implications for p5.js 2.x and 3.0

Unfortunately, the analysis of the core issues above isn't quite correct. To keep it simple, I left out two details, which I'll describe below.

1. If we could export a color to an array and then import it to a vector, then users could at least rely on the existing equals() method of p5.Vector for checking exact equality, while we sort out the core issues mentioned above. However, the p5.Vector overloads contain various inconsistencies, so it's not actually possible to create a vector directly from an array (without using the spread operator), even though some vector methods do allow vectors to be specified as arrays. That's a relatively easy fix, since we should be able to add an overload to createVector(). I'm also working on a design that would ensure consistency of overloads across methods.
2. The conversion methods on p5.Vector are inconsistently named array() and toString(), not toArray() and toString(). So it's not possible to introduce a feature for converting a color to an array without introducing another inconsistency—if we call the color method array(), we're consistent with p5.Vector but inconsistent with toString(), but if we call the method toArray(), we're inconsistent with p5.Vector while being consistent with toString(). To solve this problem, we might adopt a pragmatic policy of designing for the future, meaning that we'd use the name toArray() for the color feature if we expect to change the name of the vector feature in a future 3.0 release. That'd reduce the number of breaking changes that might need to be made. However, I'm currently working on some longer-term plans that might affect where we place the toArray() and equals() features. So it's not clear yet how to proceed.

In general, these API issues are a form of technical debt that directly affects the learning curve for users: Inconsistencies compound, and paying off the interest is very costly because it often requires breaking changes. This is a reason to move toward a 3.0 release that cleans up the API problems as quickly as possible, through the API audit. After 3.0, it should be much easier to add new features without compounding API problems.

Long-term organization

I'm actively working on a broader design that could change where the equality operator for colors would go in the API. I still need to explore the feasibility, but the core idea is to provide a set of standalone data-processing features, under the Data section of the reference. These might include an equals() operation, conversion operations equivalent to toArray(), and other data-processing operations that are common to both native JS data structures like arrays and p5 data structures like the following:

• one-dimensional data structures
  • Math: Vector (any number of numerical entries)
  • Data: Series (any number of general, labeled entries—e.g. time series)
  • Graphics: Color (a vector of length 3 or 4 with a special interpretation)
• two-dimensional data structures
  • Math: Matrix (any number of numerical rows and columns, i.e. any shape)
  • Data: Sheet (any number of general, labeled rows and columns, like a spreadsheet—a "Table" replacement)
  • Graphics: Transform (a matrix of size 3x3 or 4x4 with a special interpretation)
• $n$-dimensional data structures (still speculative for p5)
  • Math: Tensor (any shape with any number of dimensions, i.e. rank)
  • Data: we may not support an n-dimensional labeled data structure, but they are useful
  • Graphics: Image (a tensor of rank 3 or 4 with a special interpretation)

The rough idea is that each standalone function, like equals(), would be able to accept arguments of any relevant data type: vectors, series, colors, matrices, sheets, transforms, etc. This would be instead of adding equals() directly to each class. That way, instead of adding eight (or more) separate equals() functions to the API, we add just one.

Considering that equals() is just one of many potential data-processing features, this would allow us to add a lot more power with a drastically smaller API. It'd also promote consistency, and potentially improve discoverability by putting data-processing features all under one prominently labeled section of the reference. I also think it may be possible to provide a clear and logical separation between the standalone and class-based features, so that overall cohesion is improved.

I’m still figuring out how well this overall approach would actually work, but it feels natural, and it happens to be how the most popular libraries are structured. Specifically, in Python, pandas and NumPy generally work together in a similar way—the core Series and DataFrame data structures of pandas can typically be passed as arguments to general mathematical functions of NumPy. And in the end, it may be that few existing p5 features would need to be modified beyond the ones that already have problematic APIs.

Implementation

Regarding implementation, we may be able to reuse a lot of code for features like equality checking, and others like interpolation. Now that p5.Vector supports 4D vectors (and higher), we can potentially reuse vector methods for colors, for example. I think we may be able to do even better than that, but I'll hold off on the details for now.

Next steps

It's probably a good idea to flesh out the motivation and feature specification before we attempt to pin down the API, so it'd be great to see some work on those areas!

[quinton-ashley]

Here's how I handled this in q5. equals includes transparency and isSameColor doesn't.

equals(c) {
	return c && this.r == c.r && this.g == c.g && this.b == c.b && this.a == c.a;
}
isSameColor(c) {
	return c && this.r == c.r && this.g == c.g && this.b == c.b;
}

@ksen0 There's a significant precedent in other programming languages and libraries with Color data structures or classes that an equals method should check for exact equivalence including transparency.

From chatgpt:

• Java (AWT Color): Use .equals() method, which compares r, g, b, a values.
• Python (Pillow, matplotlib): Compare (r, g, b, a) tuples or use == on color objects.
• Swift (UIColor): No built-in equals; compare components manually or use isEqual for object identity.
• C# (System.Drawing.Color): Use .Equals(), which compares ARGB values.
• C++ (Qt QColor): Use == operator, which compares all channels.
• Unity: Color.equals checks all channels for exact equivalency

Ought to be considered imo.

I like the idea of adding an approximateEquals function too.

[GregStanton]

Thanks @quinton-ashley! That's an interesting idea about offering both options for comparing RGBA colors (with and without considering the alpha channel).

Comparisons with and without alpha for RGBA colors

As Quinton mentioned, for two colors with components R1, G1, B1, A1 and R2, G2, B2, A2 (say), users might want to check...

either
(1) R1 equals R2, G1 equals G2, B1 equals B2, A1 equals A2 (all components)

or
(2) R1 equals R2, G1 equals G2, B1 equals B2 (only non-alpha components)

Option (1) is commonplace in existing software, and I described at least a theoretical reason to support that case. Option (2) seems like it may be useful, but I don't think I've seen it elsewhere (besides q5). Could we provide a couple concrete use cases for each version of equality?

Comparisons of general subsets of components

Just to have all options on the table during the exploratory phase... Might there be any compelling reason to offer comparisons of more general subsets of channels? That might include, for example, a comparison between only red channels. If we support approximate equality, as I think we should, I suppose that might be useful, since a simple == or === operation wouldn't suffice. I suspect the extra complexity wouldn't be worth it for a built-in feature, but it depends on how simple we could make the API, the difficulty of a manual comparison, and how commonly this kind of customization is needed.

Manual comparisons (done by the user without a dedicated color-equality checker)

I'll flesh out one approach to manual comparisons that leverages some enhancements I'm working on (the enhancements are still in a pre-proposal phase, but I'll outline the rough idea). This approach accommodates comparisons with custom subsets of components, custom tolerances, and custom distance functions. It goes like this:

1. Convert colors to vectors (e.g. with createVector(color.toArray()))
2. Subtract the vectors
3. Use the difference to compute distance, and compare it to a chosen tolerance

In step 3, built-in functions could be used to calculate any of the three distance functions I mentioned previously:

• mag() gives the Euclidean distance
• abs() and max() give the chessboard distance
• abs() and sum() give the taxicab distance

Comparing only red and blue channels, say, could be done by extracting a subvector in an extra step.