点阵颜色列表格式说明 - PointColorListFormat

概述

pointColorList / pointJson 点阵颜色列表用于在多点找色、多点比色接口中定义多个参考点的颜色信息。本说明文档统一介绍所有支持的点阵颜色列表表示方式，接口文档只需简单引用本页即可。

适用接口：

多点找色：FindMultiColor、FindMultiColorList、FindMultiColorFromPtr、FindMultiColorListFromPtr
多点比色：CmpMultiColor、CmpMultiColorPtr

与 FindMultiColor* 的参数约定

FindMultiColor* 同时接收 colorList（主色）与 pointColorList（相对偏移点阵），解析规则如下：

首项 (0,0) 提升为主色：当 colorList 为空，且 pointColorList 第一个点坐标为 (0,0) 时，自动将该点的颜色提升为主色；该 (0,0) 点不参与偏移比色。
单参数写法：因此可只传 pointColorList，把主色写在首项 (0,0)，colorList 传空字符串即可。
仅点阵全图匹配：若解析后主色仍为空，但 pointColorList 仍有非 (0,0) 的偏移点，则在搜索区域内无主色预筛，按点阵偏移全图遍历匹配。
两者都空：主色与点阵都为空时查找失败。

CmpMultiColor* 只有 pointJson，坐标为绝对坐标（屏幕/客户区或图像像素），其中的 (0,0) 也会参与比色，不会被当作主色锚点丢弃。

1. JSON 格式（原有写法，完全兼容）

json

[
  {
    "Point": {"X": 0, "Y": 2},
    "Colors": [
      {
        "StartColor": "#0A7497",
        "EndColor": "#0A7497",
        "Type": 0
      }
    ]
  },
  {
    "Point": {"X": -5, "Y": -3},
    "Colors": [
      {
        "StartColor": "#123456",
        "EndColor": "#050607",
        "Type": 0
      },
      {
        "StartColor": "#454545",
        "EndColor": "#303030",
        "Type": 0
      },
      {
        "StartColor": "#565656",
        "EndColor": "#565656",
        "Type": 0
      }
    ]
  }
]

Point 表示相对于锚点的坐标偏移量（X, Y）
在 FindMultiColor* 中：首项若为 (0,0) 且 colorList 为空，则该项颜色提升为主色，且不参与偏移比色；其余点为相对锚点的偏移
在 CmpMultiColor* 中：Point 为绝对坐标，(0,0) 也会参与比色
Colors 数组包含该点需要匹配的颜色列表
StartColor / EndColor 支持以下形式：
- #AARRGGBB
- AARRGGBB
- #RRGGBB
- RRGGBB
EndColor 颜色支持偏色模式:
- @101010：表示对起始颜色R,G,B通道做+-10的偏色
- @+101010：表示对起始颜色R通道做+10 G,B通道做+-10的偏色
- @+10-1010：表示对起始颜色R通道做+10 G通道做-10的偏色,B通道做+-10的偏色
Type 说明：
- 0：正常匹配（保留在颜色范围内的像素）
- 1：反色匹配（保留在颜色范围外的像素）
- 2：正常交集匹配
- 3：反色交集匹配
字符串规则可通过 Type 前缀 表达上述四种模式（与 JSON Type 一致，最长匹配）：
- 无前缀：Type 0
- @ 或 -：Type 1（反色，- 为兼容旧写法）
- &：Type 2（普通交集）
- @&：Type 3（反色交集）
- 每条颜色规则可独立带前缀，详见颜色模型说明 - ColorModel
ColorSpace 说明（可选，默认 0）：
- 0：BGRA 颜色空间（沿用 StartColor / EndColor 的颜色规则）
- 1：灰度空间（使用 GrayMin / GrayMax）
- 2：HSV 空间（使用 HMin/HMax/SMin/SMax/VMin/VMax）
灰度与 HSV 字段（可选，缺省按 0 处理）：
- GrayMin、GrayMax：仅当 ColorSpace=1 时生效
- HMin、HMax、SMin、SMax、VMin、VMax：仅当 ColorSpace=2 时生效

2. 简化字符串格式（新增）

基本格式

颜色列表1,坐标偏移X|坐标偏移Y|颜色列表2|颜色列表3|...

格式说明

第一个点：直接写颜色列表，不需要坐标（默认为 0,0）
坐标偏移：使用 ,X|Y 格式，表示相对于第一个点的偏移量
- X 为 X 坐标偏移（可为负数，如 -5）
- Y 为 Y 坐标偏移（可为负数，如 -3）
后续点：使用 | 分隔，每个点包含其颜色列表
颜色格式：支持以下格式（参考颜色模型说明 - ColorModel）：
- 单独颜色：RRGGBB 或 #RRGGBB
- 偏色区间：RRGGBB-DRDGDB（基准色-偏移量）
- 灰度：#G、#G-dG 或 #G1~G2（如 #40~60 表示 [40,60]）
- HSV：H.S.V、H,S,V、H.S.V-dH.dS.dV、H,S,V-dH,dS,dV
- Type 前缀（可选，与 JSON Type 0~3 一致）：无 / @ / & / @&
- 多个颜色用 | 分隔

示例

示例 1：简单点阵

0|0|aabbcc,-5|-3|123456

对应含义：

第一个点（0, 0）：颜色 aabbcc
第二个点（-5, -3）：颜色 123456

示例 2：多颜色点阵

0|0|aabbcc|aaffaa-101010,-5|-3|123456-050607|454545-303030|565656

对应含义：

第一个点（0, 0）：颜色列表
- aabbcc（精确颜色）
- aaffaa-101010（偏色区间，基准色 aaffaa，允许偏移 101010）
第二个点（-5, -3）：颜色列表
- 123456-050607（偏色区间）
- 454545-303030（偏色区间）
- 565656（精确颜色）

示例 3：多个点

ff0000,10|5|00ff00,20|10|0000ff

对应含义：

第一个点（0, 0）：颜色 ff0000（红色）
第二个点（10, 5）：颜色 00ff00（绿色）
第三个点（20, 10）：颜色 0000ff（蓝色）

示例 4：Type 前缀组合

0|0|aabbcc-101010|@ddeeff-202020|&#10~200|@&20.30.40-5.5.5,-5|-3|&123456

对应含义：

第一个点（0, 0）：四条规则分别为 Type 0 / 1 / 2 / 3
第二个点（-5, -3）：Type 2 的 BGRA 偏色规则 &123456

格式规则

第一个点：不需要坐标偏移，直接写颜色列表
坐标偏移格式：,X|Y（逗号后跟 X 偏移，竖线后跟 Y 偏移）
颜色分隔：同一点的多个颜色用 | 分隔
点分隔：不同点之间用 | 分隔，但坐标偏移前用 , 标识
颜色格式：支持单独颜色、偏色区间等（详见颜色模型说明 - ColorModel）

注意事项

坐标偏移可以为负数，表示向左或向上偏移
颜色格式支持所有颜色模型说明 - ColorModel 中定义的格式
使用 HSV 时遵循 OpenCV 语义，H 与 dH 若大于 179 将自动按 0~360 输入换算到 0~179
简化格式相比 JSON 格式更易书写，但功能完全等价
建议在简单场景使用简化格式，复杂场景使用 JSON 格式以获得更好的可读性
FindMultiColor 单参数示例*（colorList 传 ""）：
- 0|0|ff0000,10|5|00ff00：首项 (0,0) 提升为主色，再匹配偏移点
- 10|5|00ff00,20|10|0000ff：主色为空时，在搜索区域内按点阵偏移全图匹配
CmpMultiColor 示例*：0|0|ff0000,10|5|00ff00 表示检查绝对坐标 (0,0) 与 (10,5) 两处颜色

点阵颜色列表格式说明 - PointColorListFormat ​

概述 ​

与 FindMultiColor* 的参数约定 ​

1. JSON 格式（原有写法，完全兼容） ​

2. 简化字符串格式（新增） ​

基本格式 ​

格式说明 ​

示例 ​

示例 1：简单点阵 ​

示例 2：多颜色点阵 ​

示例 3：多个点 ​

示例 4：Type 前缀组合 ​

格式规则 ​

注意事项 ​

点阵颜色列表格式说明 - PointColorListFormat

概述

与 FindMultiColor* 的参数约定

1. JSON 格式（原有写法，完全兼容）

2. 简化字符串格式（新增）

基本格式

格式说明

示例

示例 1：简单点阵

示例 2：多颜色点阵

示例 3：多个点

示例 4：Type 前缀组合

格式规则

注意事项