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.