more instructions on colorscale, cmin, cmax, and color

[CarlCui-AI]

Background: I was trying to use a custom color mapping on a 3D scatter plot, and specifically, I want an upper bound and lower bound on my colorscale. While I knew I should use cmin and cmax, I failed to understand the connections between them, color and colorscale.

The current document says:

cmin (number)
Has only an effect if marker.color is set to a numerical array. Sets the lower bound of the color domain.

colorscale (colorscale)
Sets the colorscale. The colorscale must be an array containing arrays mapping a normalized value to an rgb, rgba, hex, hsl, hsv, or named color string. At minimum, a mapping for the lowest (0) and highest (1) values are required. For example, [[0, 'rgb(0,0,255)', [1, 'rgb(255,0,0)']]. _(1)_To control the bounds of the colorscale in color space, use cmin and cmax

color (color)
Sets the marker color.

The problem lays on the documentation for color. It only specifies one situation, which is that we want a single color for all points. However, it does not show how to set the array for the color in order to get colorscale to work. In addition to that, cmin and cmax should specify that it should use a value associated with the color array, not the colorscale. It is very misleading to put (1) in that spot.

PS. (1) is the last sentence of colorscale spec. For some reason, italic does not work inside a quote.

[etpinard]

Good points. Thanks!

Can you give us suggestions on how to improve the above descriptions?

[CarlCui-AI]

@etpinard Thanks for your reply!

color
Sets the marker color. It accepts either a specific color, or an array of numbers.
In the case that it is a numerical array, each element inside the array is taken to the colorscale to interpolate a color associated with a corresponding point in the data set, by index. (length should match?) By default, color bound is set to min and max value of the numerical array, otherwise can be specified by cmin and cmax.

cmin (number)
Has only an effect if marker.color is set to a numerical array. Sets the lower bound of the color domain. Value should be associated to the numerical array (not on a 0 to 1 scale).

Something like that? I haven't looked into the details in the code, but from experiments, this is what I concluded.

Also, apparently, cmin and cmax only work if they are both present. I'm not sure it is intended or something, but this should also be pointed out in the API, IMO.