The Recolor Tool is used to replace regions of similar color with another color.
The Recolor Tool has two distinct sampling modes: Sampling Once and Sampling Secondary Color. These significantly alter how the tool acts.
Sampling Once mode with the Left Mouse button recolors the color first clicked on with the Primary color.
Using the Right Mouse button recolors the color first clicked on with the Secondary color.
Sampling Secondary Color
The Sampling Secondary Color mode is the same method of recoloring as seen in paint.net 3.5x.
Using Sampling Secondary Color mode with the Left Mouse button, the Primary color becomes the replacement color.
Pixels within tolerance of the Secondary color will be replaced.
Using the Right Mouse button reverses the roles of the colors compared to the Left Mouse button.
Tolerance, Brush Size and Hardness
Adjust the sensitivity of the color replacement with the Tolerance setting.
If Tolerance is set to 0%, only exactly matching colors will be replaced.
If Tolerance is set to 100%, all pixels will be recolored (used in this way the Recolor Tool behaves much like the Paintbrush Tool).
The size of the recoloring brush is set by the Brush Width setting in the Tool Bar. The brush will always be circular in shape. This is not able to be altered.
The Hardness setting in the Tool Bar determines how hard or soft the edges of the recoloring brush are.
A high setting gives a sharper edge, while a low setting gives a more diffuse or softer edge.
The Recolor Tool is often the fastest and easiest method to change an object's color. In the image below note how the recoloring action has respected the subtle variations in hue.