OLA 文档中心

主题

2026-06-18

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

概述 ​

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

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）
  • 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：反色交集匹配
  • 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
    • HSV：H.S.V、H,S,V、H.S.V-dH.dS.dV、H,S,V-dH,dS,dV
    • 多个颜色用 | 分隔

示例 ​

示例 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（蓝色）

格式规则 ​

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

注意事项 ​

  • 坐标偏移可以为负数，表示向左或向上偏移
  • 颜色格式支持所有 颜色模型说明 - ColorModel 中定义的格式
  • 使用 HSV 时遵循 OpenCV 语义，H 与 dH 若大于 179 将自动按 0~360 输入换算到 0~179
  • 简化格式相比 JSON 格式更易书写，但功能完全等价
  • 建议在简单场景使用简化格式，复杂场景使用 JSON 格式以获得更好的可读性