多点カラーオフセットモードで色を検索する (screen.find_color)

宣言

横座標, 縦座標 = screen.find_color({
    [find_all = 複数の結果を検索するか,]
    [max_results = 最大結果数,]
    [max_miss = 許容する不一致点の最大数,]
    {始点の横座標, 始点の縦座標, {始点の色[, 始点のカラーオフセット]}},
    {オフセット点X座標*, オフセット点Y座標*, {オフセット点の色*, オフセット点の色差*}},
    {オフセット点X座標*, オフセット点Y座標*, {オフセット点の色*, オフセット点の色差*}},
    ...
} [, 左, 上, 右, 下 ])

パラメータ

• 複数の結果を検索するか
  真偽値。省略可能。このフィールドを true に設定すると、範囲内で一致したすべての位置を {{x1, y1}, {x2, y2}, ...} 形式のテーブルで返します。デフォルトは false です
• 最大結果数
  整数。省略可能。find_all (複数の結果を検索するか) を true に設定した場合に返す結果の上限です。最大 1000、デフォルトは 100 です
• 許容する不一致点の最大数
  整数。省略可能。許容する不一致点の最大数です。デフォルトは 0 で、すべての点が一致した場合にのみ検出されます
• 始点の横座標、始点の縦座標
  整数。始点の座標です。色を検索する範囲をこの点に限定するものではなく、オフセット位置の基準座標としてのみ使用されます。オフセットが不要な場合は 0, 0 を指定できます
• 始点の色
  整数。始点で検索する色です
• 始点のカラーオフセット
  整数。検索する色に許容する最大のカラーオフセット (色差) です。0xff000000 より大きい場合は反転マッチモードになります
• オフセット点の横座標*、オフセット点の縦座標*
  整数。オフセット位置の座標です
• オフセット点の色*
  整数。オフセット位置で一致させる色です
• オフセット点のカラーオフセット*
  整数。オフセット位置の色に許容するカラーオフセット (色差) です。0xff000000 より大きい場合は反転マッチモードになります
• 左、上、右、下
  整数。省略可能。検索領域を表します。デフォルトは画面全体です

戻り値

• 横座標、縦座標
  整数。一致した多点カラー構造の最初の色の座標を返します。検索に失敗した場合は -1, -1 を返します

説明

カラーオフセット（色差）モードで検索し、領域内で最初に完全一致した多点カラー構造の位置を取得します
この関数の座標パラメータと戻り値は、screen.init 関数で初期化した座標系の影響を受けます
カラーオフセット（色差） は通常、色の範囲を表します。色にカラーオフセット（色差）を指定すると、その色の赤、緑、青の各オフセット範囲内にあるすべての色が対象になります
0x456789 のカラーオフセットが 0x123456 の場合、0x456789 に対して赤の正負範囲は 0x12、緑の正負範囲は 0x34、青の正負範囲は 0x56 になります
つまり、赤の範囲は 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 で始まる数値は 16 進数です（16 進数とは?）

使用例

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}, ...} 形式のテーブルで返します
}) -- 領域パラメータを省略すると画面全体を検索します