save-images

此示例插件演示了数据容器 API 的使用。当该插件运行时，它会自动将 MVApp 结果 中包含的图像数据保存到磁盘上的可配置目录中。该插件提供一系列丰富的配置选项，可供自定义图像格式、输出目录结构和图像输出条件。此插件的源代码在 MERLIC 安装目录的“examples\communicator_plugins\save-images”目录中提供。

使用插件

可以结合“action-sender”示例插件对该插件进行测试。您可以通过“action-sender”插件发送操作，“save-images”插件会将图像结果存储在您的磁盘上。

请记住，配方中引用的 MERLIC Vision App 至少需要一个表示图像结果的 MVApp 结果。如果没有向 MVApp 结果中添加图像结果，则无法从示例插件中检索到任何图像。

  1. 打开 MERLIC RTE Setup 并转到“配方”选项卡。
  2. 导入引用 MERLIC Vision App 的配方，该配方至少包含一个表示图像结果的 MVApp 结果。您也可以使用示例配方“verify_chip_number_recipe.mrcp”进行测试。
  3. 将该配方设置为默认配方。如果您跳过此步骤，并且在启动插件时未将该配方设置为默认配方，则必须使用命令“python.exe comm-send.py PrepareRecipe <Recipe ID>”通过“action-sender”插件手动加载配方，例如在步骤 9 之后。
  4. 通过 Windows 开始菜单项“MERLIC 5 RTE with Frontend + Communicator”启动 MERLIC RTE 和 MERLIC Communicator。以下步骤不需要 MERLIC Frontend。因此，如果您愿意，可以关闭 Frontend 窗口。但是，由于这是同时启动 MERLIC RTE 和 MERLIC Communicator 的最简单方法，我们建议使用开始菜单项。
  5. 在 MERLIC RTE Setup中，转到“通讯”选项卡，将“save-images”插件添加到左侧的插件实例列表中。

  6. 检查该插件的配置。有关可用配置选项的更多信息，请参阅配置插件部分。
  7. 单击 MERLIC RTE Setup 底部的“ 启动插件”按钮或通过左侧插件实例列表中的相应菜单，启动该插件的执行。要获取有关如何启动和停止插件的更多详细信息，请参阅 MERLIC 手册中的启动和停止 Communicator 插件主题。
  8. 按照与“save-images”插件相同的方式添加并启动“action-sender”插件。
  9. 打开命令提示符窗口，切换到“action-sender”插件的目录，即切换到 MERLIC 安装目录中的“examples\communicator_plugins\action-sender”目录。
  10. 使用 python 脚本“comm-send.py”启动单次执行，如下所示。MVApp 会执行一次，图像结果会被检索并存储在定义的目录中。您也可以输入“python.exe comm-send.py --help”获取更多使用情况信息。
    复制
    python.exe comm-send.py StartSingleJob
  11. 检查“save-images”插件配置中定义的目录中保存的图像。

配置插件

在 MERLIC RTE Setup 的“通讯”选项卡中可以配置示例插件。只需打开 MERLIC RTE Setup 并添加该插件即可查看插件的可用配置选项。请记住，您首先必须启动 MERLIC Communicator 才能启用配置。

选定插件的参数将显示在“通讯”选项卡的右侧。下面将仅介绍“User parameters”部分中的参数，因为这些是可配置参数。

Image Settings

Image format

此参数定义以哪种格式保存 MVApp 的结果图像。选定的图像格式会以蓝色突出显示。要选择其他格式，请单击相应的图像格式。根据所选的图像格式，其他参数将可进行配置。请参阅下表了解有关可用图像格式的信息。默认情况下设置为“JPEG”。

格式

描述

PNG

以 PNG 图像格式保存图像。如果选择此格式，则参数 PNG compression 将可进行配置。

JPEG

以 JPEG 图像格式保存图像。如果选择此格式，则以下其他参数可用：

HALCON Serialized Item

以 HALCON Serialized Item （即 .hse 文件）格式保存图像。这是一种专有格式，仅可供同时使用 MVTec HALCON 的用户使用。如果要在 HDevelop 中读取此格式的文件，您可以使用以下代码段：

复制 
open_file('<file path to .hse>', 'input_binary', FileHandle)
fread_serialized_item(FileHandle, SerializedItemHandle)
deserialize_object(Object, SerializedItemHandle)

open_file('<file path to .hse>', 'input_binary', FileHandle)

fread_serialized_item(FileHandle, SerializedItemHandle)

deserialize_object(Object, SerializedItemHandle)

通常，“byte”、“int1”、“uint2”、“int2”、“int4”、“int8”以及“real”类型的所有图像均可导出为 MVApp 结果，并转换为可用的图像格式。但是，“real”类型的图像是个例外，因为它们只能转换为“HALCON Serialized Item”格式。有关图像格式及相应的像素转换的信息，请参阅配置 Communicator 插件主题中的图像结果部分。

Use progressive JPEG

仅当“Image format”参数设为“JPEG”时，此参数才可用。它定义是否以渐进式 JPEG 格式保存图像。默认情况下不设置该参数。

JPEG quality

仅当“Image format”参数设为“JPEG”时，此参数才可用。它定义压缩为 JPEG 的质量，用百分比表示。默认情况下设置为 50%。

PNG compression

仅当“Image format”参数设为“PNG”时，此参数才可用。它定义压缩为 PNG 的级别。可设置为 0 到 9 之间的值。默认情况下设置为 6。

Image zoom mode

此参数可用于调整结果图像的大小。下表列出了可用选项。根据所选的模式，其他参数将可进行配置。默认情况下，该参数设置为“None”。

模式

描述

None

以原始大小保存图像，不进行任何缩放。

Fixed width and height

将图像缩放到 Image width 和 Image height 参数中定义的大小。选择此选项后，这些参数将立即可用。指定大小将应用到所有结果图像，无论其原始大小如何，并且不会保留纵横比。

Zoom factor

系统将根据 Image zoom factor 参数中指定的系数延两个维度调整图像大小。选择此选项后，此参数将立即可用。此选项保留纵横比，并且与图像的原始大小相对应。
Image width

仅当“Image zoom mode”参数设为“Fixed width and height”时，此参数才可用。它定义结果图像的宽度。因此，将以“Image width”和“Image height”定义的指定大小保存所有图像。指定大小将应用到所有图像，无论其原始大小如何，并且不会保留纵横比。默认情况下设置为 512 像素。

Image height

仅当“Image zoom mode”参数设为“Fixed width and height”时，此参数才可用。它定义结果图像的高度。因此，将以“Image width”和“Image height”定义的指定大小保存所有图像。指定大小将应用到所有图像，无论其原始大小如何，并且不会保留纵横比。默认情况下设置为 512 像素。

Image zoom factor

仅当“Image zoom mode”参数设为“Zoom factor”时，此参数才可用。它定义用于沿两个维度调整图像大小的百分比值。您也可以指定大于 100% 的值。默认情况下，该参数设置为 100%，这表示保留原始图像大小。

Conditional Output

Output condition

此参数定义是否根据特定 MVApp 结果 的值检索图像结果。默认情况下设置为“Always”，图像在保存时会忽略任何 MVApp 结果 值。您可以将此选项用于各种用例，例如，在进行质量检验时只想保存检测到质量不佳的迭代的图像。

条件

描述

Always

保存图像结果时始终忽略任何 MVApp 结果 值。

On result true

仅当特定 MVApp 结果 的值为“true”时才保存图像结果。在 Result name 参数中可以定义应进行值检查的 MVApp 结果 的名称。将“Output condition”设置为“On result true”后，它将立即可用。

根据结果值的类型，输出条件会在不同情况下设置为“true”：

  • 布尔值结果：如果值为 1，则输出条件设置为“true”并保存图像。
  • 数值：如果值不为 0，则输出条件设置为“true”并保存图像。
  • 字符串值：如果字符串不为空，则输出条件设置为“true”并保存图像。

On result false

仅当特定 MVApp 结果 的值为“false”时才保存图像结果。在 Result name 参数中可以定义应进行值检查的 MVApp 结果 的名称。将“Output condition”设置为“On result false”后，它将立即可用。

根据结果值的类型，输出条件会在不同情况下设置为“false”：

  • 布尔值结果：如果值为 0，则输出条件设置为“false”并保存图像。
  • 数值：如果值为 0，则输出条件设置为“false”并保存图像。
  • 字符串值：如果字符串为空，则输出条件设置为“false”并保存图像。
Result name

仅当“Output condition”参数设为“On result true”或“On result false”时，此参数才可用。该参数可用于输入应进行值验证的 MVApp 结果 的名称。如果值符合“Output condition”中的参数设置条件，则检索并保存图像。

Output

Image result filter mode

通过此参数可以启用用于确定将检索哪些图像结果的筛选器。您可以选择以下选项。默认情况下设置为“None”。

模式

描述

None

未应用筛选器，将检索所有结果图像。

Regular expression

仅检索名称与 Result name filter regex 参数中指定的正则表达式相匹配的结果图像。
Result name filter regex

通过此参数可以指定正则表达式来筛选应保存的结果图像的名称。仅当“Image result filter mode”参数中的筛选模式设置为“Regular expression”时才提供。因此，将仅保存名称与正则表达式相匹配的结果图像。默认情况下设置为“.*”，可匹配任何内容。

Base directory

此参数定义图像结果的保存目录。您可以通过 按钮（在本地系统上）从文件系统中选择目录，也可以直接在文本字段中输入路径。默认情况下，该参数在 Windows 系统上设置为“%LOCALAPPDATA%/Temp”，在 Linux 系统上设置为“/tmp”。您还可以选择将图像结果保存到特定格式的子目录中。此操作可在Subdirectory format参数中完成。

Subdirectory format

此参数定义保存图像结果的子目录的格式。默认情况下设置为“Recipe ID”。

格式

描述

None

不创建子目录。将图像结果直接保存在“Base directory”参数中定义的位置。

Recipe ID

以当前已准备的配方（即引用已执行 MVApp 的配方）的 ID 命名子目录。

Date

以执行的当前日期命名子目录。日期格式如下：{year}-{month:02}-{day:02}，例如“2022-07-18”。

Date and recipe ID

以当前日期和当前已准备的配方的 ID 命名子目录。生成的目录名称格式如下：{year}-{month:02}-{day:02}--{recipeId}，例如“2022-07-18-6”。

Custom

此选项允许您使用自定义格式的目录名称。所需格式可以在 Subdirectory format string 参数中定义，该参数在选择“Custom”后立即可用。
Subdirectory format string

仅当“Subdirectory format”参数设为“Custom”时，此参数才可用。通过该参数可以为保存图像结果的子目录名称定义自定义格式。您可以在输入字段中输入所需的子目录名称，也可以使用表示特定值（如配方 ID）的占位符来定义名称。此类占位符必须在大括号内定义，否则会被解释为常规字符串。

下表显示可用的占位符。

格式字符串占位符

数据格式

描述

{recipeId}

String

当前已准备的配方的 ID。

{resultId}

Integer

检索到的图像结果的 ID。

{resultName}

String

相应的 MVApp 图像结果的名称，即在 MERLIC Creator 中向 MVApp 结果 添加图像结果时定义的名称。如果有多个 MVApp 图像结果，则会创建多个子目录；每个子目录用于保存具有相应名称的 MVApp 图像结果。

{dataIndex}

Integer

MVApp 图像结果的索引。它对应于在 MERLIC Creator 的“MVApp 参数和结果”面板中分配给 MVApp 图像结果的位置编号。

{year}

Integer

执行时的当前年份。

{month}

Integer

执行时的当前月份。

{day}

Integer

执行时的当前日期。

{hour}

Integer

执行时的当前小时。

{minute}

Integer

执行时的当前分钟。

{second}

Integer

执行时的当前秒钟。

{millisecond}

Integer

执行时的当前毫秒。

{<NAME_OF_MVAPP_RESULT>}

String

已使用名称“<NAME_OF_MVAPP_RESULT>”定义为 MVApp 结果 的指定工具结果的值。如果要在子目录的名称中使用或添加工具结果值，则此格式很有用。因此，您只能指定不表示图像的 MVApp 结果 的名称。请记住，使用此格式字符串时，请使用 MVApp 结果 名称，不要使用相应工具结果的名称。

{measId}

String

分配给生成图像结果的作业的测量 ID，如果未提供则为“null”。

{partId}

String

分配给生成图像结果的作业的部分 ID，如果未提供则为“null”。

所有时间特定的占位符均表示 UTC 时间。您还可以为占位符使用附加格式说明符，即 {<placeholder>:<format specifier>}，以更精确地配置名称。例如，如果“Subdirectory format”设置为“Date”，则使用以下占位符和格式说明符：{year}-{month:02}-{day:02}。有关可用的格式说明符的更多详细信息，请参阅 {fmt} 格式设置库文档。

File name format

此参数定义已保存的图像结果的文件名格式。默认情况下设置为“Result ID and data index”。

格式

描述

Result ID and data index

文件名由结果 ID 和数据索引组成。

Time and data index

文件名由当前 UTC 时间和数据索引组成，例如“13-20-00-831-0.jpg”。

Time and result name

文件名由当前 UTC 时间和相应 MVApp 图像结果的结果名称组成，例如“13-20-00-831-Heatmap.jpg”。

Result ID and result name

文件名由相应图像结果的结果 ID 和对应的 MVApp 图像结果的名称组成，例如“37-Heatmap.jpg”。

Custom

此选项允许您使用自定义格式的文件名名称。所需格式可以在 File name format string 参数中定义，该参数在选择“Custom”后立即可用。
File name format string

仅当“File name format”参数设为“Custom”时，此参数才可用。通过该参数可以为图像结果文件名定义自定义格式。您可以在输入字段中输入所需的文件名，也可以使用表示特定值（如配方 ID）的占位符来定义名称。此类占位符必须在大括号内定义，否则会被解释为常规字符串。有关可用占位符的更多信息，请参阅 Subdirectory format string 参数的说明。