Represents one ARGB color and provides color sampling/comparison helpers.
Syntax
Color(value, /)
Constructor parameters
Name
Description
valueString | Number
Hex string (`#AARRGGBB`/`#RRGGBB`) or raw ARGB number.
Required · Positional only
No default
Returns
Color
Behavior / side effects
Represents one ARGB color and provides color sampling/comparison helpers.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Fallback color returned when screen capture or pixel sampling is unavailable.
Optional · Positional or named
Default:#00000000
Returns
Color | list[list[Color]] | list[Color] — Sampled color payload based on target type, with missing samples filled by default.
Behavior / side effects
Read color(s) from screen: Point -> Color, Region -> 2D Color array, list[Point] -> Color list. This is an immediate one-shot sample; if no frame is available or a sample is missing, returns the default color instead of retrying or stopping the script.
Execution
Blocking: Yes
Thread safety: Serialized
Parallel execution: Conditional
Samples a shared capture frame in the caller; capture and processing take time. Other flows share capture/cache policy.
Allowed per-channel difference (0-255). Practical start: 4-8 for near-identical UI shades, 10-16 for anti-alias/compression variation.
Optional · Positional or named
Default:0
Returns
Boolean — true when all RGB channels are within tolerance. Quick guide: 0 = exact, 4-8 = almost same, 10-16 = tolerant match, >24 = very loose.
Behavior / side effects
Compare two colors by per-channel RGB tolerance. Match passes only when |R1-R2|, |G1-G2|, and |B1-B2| are all <= tolerance.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Compute Euclidean distance in RGB space between two colors.
Syntax
Color.distance_rgb(a, b)
Parameters
Name
Description
aColor | String | Number
First color.
Required · Positional or named
No default
bColor | String | Number
Second color.
Required · Positional or named
No default
Returns
Number — RGB-space distance in range 0 -> 441.67 (0 = exact). Practical guide: <=8 almost same, 9-20 close, 21-40 visibly different, >40 far apart.
Behavior / side effects
Compute Euclidean distance in RGB space between two colors.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
actual = Color.get(Point(620, 340))
rgb_gap = Color.distance_rgb(\"#FF4CAF50\", actual)
if rgb_gap <= 15:
print(\"close in RGB\")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Compute CIE76 Delta E between two colors for perceptual difference.
Syntax
Color.delta_e(a, b)
Parameters
Name
Description
aColor | String | Number
First color.
Required · Positional or named
No default
bColor | String | Number
Second color.
Required · Positional or named
No default
Returns
Number — Perceptual difference score. Rule of thumb: <1 imperceptible, 1-2 barely noticeable, 2-5 noticeable, 5-10 clearly different, >10 different colors.
Behavior / side effects
Compute CIE76 Delta E between two colors for perceptual difference.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
actual = Color.get(Point(620, 340))
d = Color.delta_e(\"#FF4CAF50\", actual)
if d <= 3:
print(\"looks similar to human eye\")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Allowed per-channel difference (0-255). Typical same-ish range: 4-8; use 10-16 for noisy/compressed captures.
Optional · Positional or named
Default:0
Returns
Boolean — Comparison result. 0 means exact match; larger tolerance makes matching more permissive.
Behavior / side effects
Instance version of RGB tolerance compare. Useful when you already sampled one color and compare against target shades.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
picked = Color.get(Point(540, 920))
if picked.compare(\"#FFFFFFFF\", tolerance=5):
click(Point(540, 920))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Compute Euclidean distance in RGB space from this color to another color.
Syntax
color.distance_rgb(other)
Parameters
Name
Description
otherColor | String | Number
Color to compare.
Required · Positional or named
No default
Returns
Number — RGB-space distance (0 -> 441.67). Quick read: <=8 almost same, 9-20 close, 21-40 visibly different, >40 far apart.
Behavior / side effects
Compute Euclidean distance in RGB space from this color to another color.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
base = Color(\"#FF4CAF50\")
actual = Color.get(Point(620, 340))
rgb_gap = base.distance_rgb(actual)
if rgb_gap <= 20:
print(\"close enough in RGB\")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Compute CIE76 Delta E from this color to another color for perceptual comparison.
Syntax
color.delta_e(other)
Parameters
Name
Description
otherColor | String | Number
Color to compare.
Required · Positional or named
No default
Returns
Number — Perceptual color difference score. Practical guide: <1 imperceptible, 1-2 barely visible, 2-5 noticeable, 5-10 clear difference, >10 very different.
Behavior / side effects
Compute CIE76 Delta E from this color to another color for perceptual comparison.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
base = Color(\"#FF4CAF50\")
actual = Color.get(Point(620, 340))
perceptual_gap = base.delta_e(actual)
if perceptual_gap <= 2:
print(\"looks almost the same\")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
