Find Color - Color Similarity Mode (screen.find_color)

Declaration

x, y = screen.find_color({
    [find_all = boolean,]
    [max_results = integer_value,]
    [max_miss = integer_value,]
    [csim_algorithm = integer_value,]
    {x0, y0, color0[, sim0]},
    {dx*, dy*, color*[, sim*]},
    {dx*, dy*, color*[, sim*]},
    ...
}[, global_similarity, left, top, right, bottom ])

Parameters

• find_all
  Boolean, optional. When true, returns a table of all match positions within the region, format {{x1, y1}, {x2, y2}, ...}. Default false.

• max_results
  Integer, optional. The maximum number of results when find_all is true. Up to 1000, default 100.

• max_miss
  Integer, optional. Maximum number of non-matching points allowed. Default 0 (all points must match).

• csim_algorithm (2025-03-02)
  Integer, optional. Color similarity algorithm, default 0.

  Algorithms

  0 = XXT default (steep gradient, similarity drops quickly with difference)
  1 = Manhattan (smooth)
  2 = Euclidean (smooth)

• x0, y0
  Integer. Starting anchor coordinate. It does not limit search to that fixed point; it serves as the base for offset positions. If unsure, use 0, 0.

• color0
  Integer. Color to match at the starting point.

• sim0
  Integer, optional. Similarity for the starting point. Range 1~100, default 100.

• dx*, dy*
  Integer. Offset coordinate relative to the starting point.

• color*
  Integer. Expected color at the offset point.

• sim*
  Integer, optional. Similarity for the offset point. Range -100~100, default 100. Negative value means match similarity less than its absolute value (inverse match).

• global_similarity
  Integer, optional. Used for all points if no per-point similarity is provided. Range 1~100, default 100.

• left, top, right, bottom
  Integer, optional. Search region. Default is full screen.

Returns

• x, y
  Integer. The coordinate of the first matched multi-point structure. Returns -1, -1 on failure.

Description

Find the position of the first fully matched multi-point color structure using similarity mode.

Example

x, y = screen.find_color({
    {  0,   0, 0xec1c23},
    { 12,  -3, 0xffffff, 85},
    {  5, -18, 0x00adee},
    { -1, -10, 0xffc823},
    {  2, -34, 0xa78217},
    { 12, -55, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
-- Equivalent form with absolute coords:
--
x, y = screen.find_color({
    { 509, 488, 0xec1c23},
    { 521, 485, 0xffffff, 85},
    { 514, 470, 0x00adee},
    { 508, 478, 0xffc823},
    { 511, 454, 0xa78217},
    { 521, 433, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
-- One-line compact form:
--
x, y = screen.find_color({ {0,0,0xec1c23},{12,-3,0xffffff,85},{5,-18,0x00adee},{-1,-10,0xffc823},{2,-34,0xa78217},{12,-55,0xd0d2d2},},90,0,0,100,100)
--
-- Inverse matching demo (run on iPhone 5C home screen for results):
x, y = screen.find_color({
    { 516,  288, 0xffffff },
    { 519,  286, 0xffffff },
    { 521,  289, 0xffffff },
    { 516,  296, 0xffffff },
    { 522,  297, 0xffffff },
    { 520,  295, 0xffffff, -10 }, -- match similarity less than 10
    { 515,  291, 0xffffff, -10 },
    { 518,  284, 0xffffff, -10 },
    { 523,  298, 0xffffff, -10 },
    { 514,  298, 0xffffff, -10 },
    { 514,  296, 0xffffff, -10 },
}, 90)
--
-- Find-all demo (returns all positions):
results = screen.find_color({
    {  527,  278, 0xde1d26 },
    {  524,  285, 0x007aff },
    {  555,  292, 0xe4ddc9 },
    {  536,  314, 0xffde02 },
    {  502,  291, 0xffde02 },
    {  502,  283, 0xe4ddc9 },
    find_all = true,
}, 90)