Поиск цвета по нескольким точкам с допуском цвета (screen.find_color)

Объявление

координата_x, координата_y = screen.find_color({
    [find_all = искать несколько результатов,]
    [max_results = максимальное число результатов,]
    [max_miss = максимально допустимое число промахов,]
    {начальная_координата_x, начальная_координата_y, {начальный_цвет[, начальный_допуск_цвета]}},
    {смещение_x*, смещениеение_y*, {цвет_смещения*, допуск_цвета_смещения*}},
    {смещение_x*, смещениеение_y*, {цвет_смещения*, допуск_цвета_смещения*}},
    ...
} [, левый, верхний, правый, нижний ])

Параметры

• Поиск нескольких результатов
  Логическое значение, необязательный параметр. При значении true возвращает таблицу всех совпавших позиций в области в формате \{\{x1, y1\}, \{x2, y2\}, ...\}; по умолчанию false.
• Максимальное число результатов
  Целое число, необязательный параметр. Если метка find_all (поиск нескольких результатов) равна true, задаёт максимальное число результатов; максимум 1000, по умолчанию 100.
• Максимально допустимое число промахов
  Целое число, необязательный параметр: максимальное число несовпавших точек; по умолчанию 0, то есть совпасть должны все точки.
• Начальная координата x, начальная координата y
  Целые числа, задающие начальную координату. Они не ограничивают поиск цвета одной фиксированной точкой, а задают относительную координату для смещённых точек. Если смещение не используется, укажите 0, 0.
• Начальный цвет
  Целое число, задающее цвет точки, которую нужно найти.
• Начальный допуск цвета
  Целое число, задающее максимальный допуск (отклонение) искомого цвета; значение больше 0xff000000 включает режим обратного совпадения.
• Координата x смещённой точки*, координата y смещённой точки*
  Целые числа, задающие координаты смещённой точки.
• Цвет смещённой точки*
  Целое число, задающее цвет для сопоставления в смещённой точке.
• Допуск цвета смещённой точки*
  Целое число, задающее допуск (отклонение) цвета смещённой точки; значение больше 0xff000000 включает режим обратного совпадения.
• Левый край, верхний край, правый край, нижний край
  Целые числа, необязательные параметры, задающие область поиска; по умолчанию — весь экран.

Возвращаемое значение

• Координата x, координата y
  Целые числа. Возвращают координаты первой точки с совпавшим цветом; при ошибке поиска возвращают -1, -1.

Описание

Выполняет поиск в режиме допуска цвета и получает позицию первой структуры цвета с несколькими точками, полностью совпавшей в области.
Система координат параметров и возвращаемых значений этой функции зависит от системы, заданной функцией screen.init.
Допуск цвета (отклонение цвета) обычно обозначает диапазон цветов. Цвет с допуском включает все цвета в пределах отклонения красной, зелёной и синей составляющих.
Если допуск цвета 0x456789 равен 0x123456, это означает положительный и отрицательный диапазоны 0x12 для красной, 0x34 для зелёной и 0x56 для синей составляющих 0x456789.
То есть диапазоны составляют 0x45 ± 0x12 для красной, 0x67 ± 0x34 для зелёной и 0x89 ± 0x56 для синей составляющих, как показано в таблице ниже.

Отрицательное	Положительное
0x45 - 0x12 = 0x33	0x45 + 0x12 = 0x57
0x67 - 0x34 = 0x33	0x67 + 0x34 = 0x9B
0x89 - 0x56 = 0x33	0x89 + 0x56 = 0xDF

Указанная в таблице пара {0x456789, 0x123456} обозначает все цвета в диапазоне от 0x333333 до 0x579BDF.
Числа, начинающиеся с 0x, являются шестнадцатеричными (что такое шестнадцатеричное число?).

Пример

x, y = screen.find_color({
    {  0,   0, {0xec1c23, 0x000000}},
    { 12,  -3, {0xffffff, 0x101010}},
    {  5, -18, {0x00adee, 0x123456}},
    { -1, -10, {0xffc823, 0x101001}},
    {  2, -34, {0xa78217, 0x101001}},
    { 12, -55, {0xd0d2d2, 0x101001}},
}, 0, 0, 100, 100)
--
--[[
    В области от (0, 0) в левом верхнем углу до (100, 100) в правом нижнем найдена первая точка, полностью совпадающая с 0xec1c23 (допуск цвета равен 0),
    а цвет в её относительной позиции (12, -3) отличается от 0xffffff менее чем на 0x101010,
    а цвет в её относительной позиции (5, -18) отличается от 0x00adee менее чем на 0x123456,
    и так далее для остальных точек.
--]]
--
-- Эквивалентный код:
--
x, y = screen.find_color({
    { 509, 488, {0xec1c23, 0x000000}},
    { 521, 485, {0xffffff, 0x101010}},
    { 514, 470, {0x00adee, 0x123456}},
    { 508, 478, {0xffc823, 0x101001}},
    { 511, 454, {0xa78217, 0x101001}},
    { 521, 433, {0xd0d2d2, 0x101001}},
}, 0, 0, 100, 100)
--
--[[
    В области от (0, 0) в левом верхнем углу до (100, 100) в правом нижнем найдена первая точка, полностью совпадающая с 0xec1c23 (допуск цвета равен 0),
    а цвет в её относительной позиции (521-509, 485-488) отличается от 0xffffff менее чем на 0x101010,
    а цвет в её относительной позиции (514-509, 470-488) отличается от 0x00adee менее чем на 0x123456,
    и так далее для остальных точек.
--]]
--
-- Без переносов строк и отступов это выглядит так:
x, y = screen.find_color({ {0,0,{0xec1c23,0x000000} },{12,-3, {0xffffff,0x101010} },{5,-18, {0x00adee,0x123456} },{-1,-10,{0xffc823,0x101001} },{2,-34,{0xa78217,0x101001} },{12,-55,{0xd0d2d2,0x101001} }, },0,0,100,100)
--
x, y = screen.find_color({ -- Демонстрация обратного совпадения; при запуске на главном экране 5C будет получен результат
    { 516,  288, {0xffffff, 0x101010} },
    { 519,  286, {0xffffff, 0x101010} },
    { 521,  289, {0xffffff, 0x101010} },
    { 516,  296, {0xffffff, 0x101010} },
    { 522,  297, {0xffffff, 0x101010} },
    { 520,  295, {0xffffff, 0xff101010} }, -- Эта точка совпадает только при разнице с 0xffffff более 0x101010; то же относится к следующим
    { 515,  291, {0xffffff, 0xff101010} },
    { 518,  284, {0xffffff, 0xff101010} },
    { 523,  298, {0xffffff, 0xff101010} },
    { 514,  298, {0xffffff, 0xff101010} },
    { 514,  296, {0xffffff, 0xff101010} },
}) -- Без параметров области поиск выполняется по всему экрану
--
results = screen.find_color({ -- Демонстрация вывода всех совпадений в области
    {  527,  278, {0xde1d26, 0x101010} },
    {  524,  285, {0x007aff, 0x101010} },
    {  555,  292, {0xe4ddc9, 0x101010} },
    {  536,  314, {0xffde02, 0x101010} },
    {  502,  291, {0xffde02, 0x101010} },
    {  502,  283, {0xe4ddc9, 0x101010} },
    find_all = true, -- Эта метка возвращает таблицу всех совпавших позиций в области в формате { {x1, y1}, {x2, y2}, ...}
}) -- Без параметров области поиск выполняется по всему экрану