VisualApplets
Operator Reference

Operator Library: Memory

该算子支持为每个缓冲图像提供多个感兴趣区 (ROI)。所有 ROI 均会按顺序进行读出。 每个 ROI 都是一个新的独立输出图像：ROI 0、ROI 1、ROI 2，以此类推，直至 ROI N-1。其中 N 是由参数 NumRoI 指定的 ROI 数量。 只要不超过帧尺寸，所有可能的矩形区域均受支持，即可以将单个像素、单行、单列、矩形区域 或完整帧定义为 ROI。不同的 ROI 可以具有不同的尺寸。 每个 ROI 均可单独定义。各个 ROI 可以相互重叠。但是，所有 ROI 必须满足输入和输出链路定义的最大图像尺寸限制，即 ROI 宽度不得超过最大图像宽度，且 ROI 高度不得超过最大图像高度。

有关算子延迟的信息， 请参阅 表 46“Library Memory 中各算子的延迟”。

该算子将图像流缓冲在 采集卡板载 RAM 中。需要一个类型为 RAM 的 VisualApplets 资源（参见 “分配设备资源”）。

ImageBufferMultiRoI 对由输入链路最大图像宽度和高度参数定义的固定 尺寸图像进行操作。这意味着由算子执行输入帧尺寸控制。

小于最大图像尺寸的 图像将被缓冲而不进行修改。但是，读取 ROI 可能会 导致读取未定义的像素值，即输入图像尺寸之外的像素值。丢失的帧像素包含随机数据，在后续 处理中应被视为未定义。

如果发生溢出（即缓冲区因满而无法 存储更多图像），所有传入的图像将被丢弃，直到缓冲区中有 足够的可用空间来存储至少一个帧。发生溢出的原因可能是 与写入相比，读取 ROI 的速度太慢。这可能是因为 定义了太多 ROI，或者因为后续算子阻塞了输出。在 平衡设计的正常情况下，绝不会发生溢出。

一旦对应帧完全缓冲， 该算子就会在其输出端提供 ROI 图像。读出类型由 参数 Mode 定义。

参数 MaxNumRoI 指定 ROI 的最大数量。实际使用的 ROI 数量可以更少， 并通过参数 NumRoI 进行定义。

参数 NumRoI 指定算子将为每个缓冲图像在输出端提供的 ROI 数量。当设置为 动态类型时，此数字不得超过 MaxNumRoI。

参数 Mode 指定算子用于处理图像的行为。FreeRun 定义了 缓冲区以便尽快在其输出端提供 ROI，即一旦 对应帧完全缓冲。此模式也称为自由运行模式。 该算子仅由管线流控制机制控制。 WaitAfterImage 模式强制算子在帧的所有 ROI 在其输出端提供后暂停。要重新开始读取下一帧的 ROI， 必须写入参数 Unlock。WaitAfterRoI 与 WaitAfterImage 类似，不同之处在于算子在每个帧的每个 ROI 之后停止。要重新开始进一步处理，需要对参数 Unlock 进行写入循环。

参数 Unlock 用于 WaitAfterImage 和 WaitAfterRoI 模式，以解锁 算子并启动进一步的读出操作。在 FreeRun 模式下， 此参数无效。

XOffset、XLength、YOffset 和 YLength 指定 一组 ROI。这些参数是字段参数。这些参数的 参数类型可以设置为动态或静态，这意味着在运行时可调节或不可调节。 当设置一个 ROI 参数的参数类型时，所有 ROI 参数的参数类型都会自动 进行相应调整。字段的大小由参数 MaxNumRoI 定义。 算子将按顺序读取 NumRoI 个 ROI。请参阅 “参数编辑” 了解如何配置 字段参数。

所有 ROI 都可以动态更新。但是， 对于 FreeRun、WaitAfterImage 和 WaitAfterRoI 模式，只有在没有启动图像采集的情况下 才能执行更新。此外，在 WaitAfterImage 和 WaitAfterRoI 模式下，如果已传输对应帧/帧的所有 ROI，且算子正在等待对 Unlock 参数进行写入循环，则可以更新 ROI。

在图像采集期间更新 ROI 可能会 导致暂时出现非矩形的 ROI，因此应避免。

如果算子将图像协议用于 VALT_LINE1D，则 Y 坐标参数将被禁用。在 1D 操作中，算子 将读取一个 ROI 作为一行。然后，算子的输出将是一个无限的 1D 图像流，其中每行由一个 ROI 表示，例如，第 0 行 = ROI 0，第 1 行 = ROI 1，第 N 行 = ROI N，第 N+1 行 = ROI 0，...

为了测量缓冲区的填充水平， 算子提供了 2 个寄存器：FillLevel 和 Overflow。FillLevel 显示 RAM 的百分比填充水平。当 FillLevel 接近或达到 100% 且要 存储在缓冲区中的下一图像将超出 RAM 容量时，Overflow 参数设置为 1。

参数 InfiniteSource 用于指定算子是直接连接到相机，还是与 其他内存算子串联。查看 “Infinite Sources / 连接相机” 了解更多 信息。

	ImageBufferMultiRoI 不适用于 imaFlex CXP-12 Quad 和 imaFlex CXP-12 Penta 平台
	ImageBufferMultiRoI 在 imaFlex CXP-12 Quad 和 imaFlex CXP-12 Penta 平台上不受支持，但您可以改用适用于 imaFlex CXP-12 Quad 和 imaFlex CXP-12 Penta 平台的等效用户库元素。有关如何 使用用户库元素的说明，请参阅 “随附的用户库”。

	示例：优化内存使用
	客户输入尺寸为 20000 x 7096 像素的图像（输入端口上的链路 property）。Parallelism 设置 为 8。Bit Width 设置为 8。 此示例中使用的平台是 mE5， 即该平台提供 256 Mbyte RAM 库。要使用全部 256 MB， 应向算子输入 128 位。但当 Parallelism 为 8 时，仅输入 64 位（8 x 8 位），即用户只能使用 128 MB 的 RAM。要保存尺寸为 20000 x 7096 像素的图像，需要 141,920,000 字节（约 135 MB）， 这超过了可用的 128 MB。VisualApplets 会检测到这一点， 并且链路会以红色高亮显示。 解决方案：在算子 ImageBufferMultiRoi 前面使用 Parup（设为 16）。

带宽优化

流经使用 采集卡 RAM (DRAM) 的算子的理论带宽 [bits/second] 根据以下公式计算：

然而，由于 DRAM 效率的限制，实际带宽总是小于理论带宽。

当 Bit Width 和 Parallelism 的乘积等于内部 RAM Port Width 时，通过算子的 maximum bandwidth 将达到最大值。

	平台特定值
	RAM Port Width 和 System Clock 是平台相关的。 请参阅 Device Resources 以获取有关您各个平台的详细信息。

Supported Link Format

Link Parameter	Input Link I	Output Link O
Bit Width	[1, 64]	as I
Arithmetic	{unsigned, signed}	as I
Parallelism	any	as I
Kernel Columns	1	as I
Kernel Rows	1	as I
Img Protocol	{VALT_IMAGE2D, VALT_LINE1D}	as I
Color Format	any	as I
Color Flavor	any	as I
Max. Img Width	any	as I
Max. Img Height	any	as I

	对于无符号输入，输入 bit width 的范围是 [1, 64]。对于有符号输入，范围是 [2, 64]。对于无符号彩色输入，范围是 [3, 63]，对于有符号彩色输入，范围是 [6, 63]。
	bit width 与 parallelism 的乘积不得超过原生 ram 数据宽度（RamDataWidth）。 请检查 Device Resources 以了解更多信息。
	I 的最大图像尺寸： I.Img.Protocol = VALT_IMAGE2D: 2^RamAddressWidth >= (I.Max.Img.Width * I.Max.Img.Height) / I.Parallelism I.Img.Protocol = VALT_LINE1D: 2^RamAddressWidth >= I.Max.Img.Width / I.Parallelism