参数化

本主题解释了您可以在 VisualApplets 设计中配置哪些类型的参数、VisualApplets 如何区分 link properties 与 module parameters、link properties 如何在管道中传播，以及如何解决它们之间的冲突。阅读本主题后，您将了解在 links 上设置哪些 properties 以及在 modules 上设置哪些 parameters、静态和动态 module parameters 之间的区别，以及如何在不违反设计规则的情况下将设计适配到特定的相机格式。

关键术语

Link 是两个 modules 之间的连接。Link properties 描述了该连接上的数据格式，例如每像素位数或最大图像尺寸。您只能在 VisualApplets 设计期间设置它们。Module parameters 是 module 上的设置，例如阈值或相机格式。如果您输入的数值无法保存，通常是由于 link properties 限制了 module 可以接受的内容。

静态参数只能在 PC 上的 VisualApplets 中更改（设计时）。动态参数还可以在主计算机软件与采集卡上的小程序进行交互的运行时更改。您在 VisualApplets 中为动态参数设置的值是运行时的默认值。VisualApplets 中的仿真不属于运行时。

链路属性和模块参数

VisualApplets 使用两种类型的设置：

Link properties 设置在链路上，定义了最大图像宽度和高度、Bit Width、Parallelism、图像协议、Color Format 和内核大小等。链路属性会限制与其连接的算子。如果模块参数与链路属性发生冲突，VisualApplets 会直接调整该值或报告错误。链路属性始终是静态的：您只能在设计阶段的 VisualApplets 中更改它们。链路属性会在管道中传递，并影响所有下游算子，直到有算子更改它们为止。

Module parameters 定义了算子行为，例如操作模式、图像位置或感兴趣区域 (ROI) 的大小。它们可以是静态的，也可以是动态的。您只能在设计阶段更改静态参数。动态参数还可以在运行时通过主计算机软件进行更改。静态参数通常比动态参数消耗更少的 FPGA 资源。当您需要在小程序运行时切换相机格式或处理设置时，动态参数非常有用。模块参数通常受链路属性的限制。如果您无法设置某个值并且 VisualApplets 会自动对其进行纠正，请检查已连接链路上的链路属性。许多算子还在其输出端定义了链路属性，因此设计一侧的更改可以传递到另一侧。

Link Properties and Module Parameters of the CxpCamera 运算符：

有关链路的正式规则，请参见《用户手册》中的 Rules of Links。有关 VisualApplets GUI 中的编辑工作流，请参见《用户手册》中的 Parameterization。

Link Properties

模块之间的每个链路都由其链路属性定义。所有链路都具有相同的属性集。链路属性始终是静态的：您只能在设计阶段的 VisualApplets 中更改它们。您可以通过双击链路或右键单击链路并选择 Properties 来打开链路属性。

以下 link properties 定义了图像数据在连接上的传输方式：

• BitWidth：链路上每像素的位数。对于彩色链路，Bit Width 涵盖所有颜色分量。相机运算符通常设置初始 Bit Width。对于具有 ImageProtocol = VALT_SIGNAL的链路上，Bit Width 始终为 1 位。

  • 某些运算符允许您设置输出 BitWidth 直接在链路上，例如 CastBitWidth, CONST或 ModuloCount。其他运算符则根据输入 link properties 或模块参数自动推导输出 BitWidth 。例如， ShiftLeft 将参数的值相加 Shift 加到输入 Bit Width 上，并且 MULT 使用输入 Bit Width 的总和。诸如 Coordinate_X 和 Coordinate_Y 之类的算子会根据 BitWidth 计算出输出 MaxImageWidth 和 MaxImageHeight。对于具有自动输出 BitWidth， Operator Reference 显示 auto 或 Supported Link Format 表，并且通常无法编辑链路上的值。当算子更改输出 BitWidth时，VisualApplets 会将该新值传播到下游链路，直到另一个算子再次对其进行更改。

• Arithmetic：定义用于链路的 Arithmetic。Arithmetic 可以是 Signed 或 Unsigned.

  • 如果设置为 Signed，则使用二进制补码算术。符号位包含在配置的 Bit Width 中。
  • 对于图像协议 VALT_SIGNAL的 link 上，Arithmetic 始终为 Unsigned，无论配置的 Bit Width 如何。

• Parallelism：在一个 Base Design Clock 周期内，两个模块之间并行传输的像素数。有关详细信息，请参见 Parallelism 教程主题。

• KernelColumns 和 KernelRows：滤波算子每个时钟周期所需的相邻像素数量。对于图像协议 VALT_SIGNAL，两个值始终为 1。有关详细信息，请参见 使用 Kernel 教程主题。

• ImageProtocol：定义链路上数据流的结构。可用以下图像协议：

  • VALT_IMAGE2D：带有行尾和帧尾标记的二维图像，例如来自面阵相机的图像。
  • VALT_LINE1D：一维行数据，例如来自线阵相机的数据。
  • VALT_PIXEL0D：不包含图像尺寸信息的连续像素流。
  • VALT_SIGNAL：在每个时钟周期都有效的单位（Single-bit）信号，例如在触发逻辑中。

  图像协议可能会在设计内部发生变化。例如， SplitImage 可以将一维图像流切割成具有指定高度的二维图像。有关详细信息，请参见 图像协议、图像尺寸与数据结构 （见《用户手册》）。

• ColorFormat 和 ColorFlavor：这些属性描述了像素数据的表示方式，例如灰色或 RGB。某些算子仅支持特定的 Color Format。在某些平台上，CoaXPress 相机算子仅接受灰色格式。要生成彩色输出，请使用诸如 MergeComponents之类的算子。诸如 MergeComponents, ParallelUp和 CastBitWidth 可以更改与颜色相关的 link 属性。

• MaxImageWidth 和 MaxImageHeight：link 可以承载的最大图像尺寸。link 上的图像不得超过这些值，但可以更小。这些属性与缓冲行或完整图像的算子相关，例如 ImageFifo, LineBuffer或 ColMax。将其设置得至少与处理路径中的最大图像一样大。值过小会导致设计规则检查 (DRC) 错误。较大的值会消耗更多的 FPGA 资源。相机算子或诸如 SetDimension 之类的算子 MaxImageHeight 在以下情况下无效 ImageProtocol 设为 VALT_LINE1D, VALT_PIXEL0D或 VALT_SIGNAL.

信息

您选择的最大图像尺寸和 Parallelism 越高，设计消耗的 FPGA 资源就越多。Basler 建议您仅根据应用程序的需求来设置这些值。

每个算子都定义了其允许的输出链路属性以及哪些值是固定的。链路上的一些属性被禁用，因为上游算子不允许对其进行编辑。Operator Reference 记录了每个算子允许的链路格式。

链路属性的传递

Link 属性由算子定义。您可以直接在算子的输出 link 上更改某些属性。其他属性是固定的，或者派生自模块参数或输入 link 属性。当您更改 link 属性时，VisualApplets 会将该更改传播到后续模块和 link。

更改值后，单击属性对话框中的 Apply。如果更改被接受，设计面板中的受影响链路将变为绿色。绿色表示 VisualApplets 已传递并验证了更新后的链路属性。它并不是针对整个设计的红绿灯式“全部有效”标记。

Link properties 会通过 modules 不断传播，直到某个 operator 更改它们。如果下游 link 不允许编辑某项 property，则应当在上游 operator 或能够更改该 property 的中间 operator 处进行设置。例如， ImageBuffer 算子不会更改 link Bit Width。您必须在相机输出 link 上设置 Bit Width，或者插入一个诸如 ConvertPixelFormat 或 ShiftLeft 之类的算子来更改 Bit Width。

连线 Property 更改也可能会与模块参数产生冲突。在这种情况下，VisualApplets 会将模块和受影响的参数标记为红色：

运行 设计规则检查 1 级 并阅读 DRC 日志以定位错误。典型原因包括超出范围的 MaxImageWidth 或 MaxImageHeight的感兴趣区域 (ROI)，或者参数值超出了 link Bit Width 允许的范围：

模块参数

每个 operator 的模块参数均不相同。它们用于控制 operator 如何处理数据。模块参数可以是静态的，也可以是动态的。静态参数只能在设计阶段的 VisualApplets 中进行设置。动态参数也可以在运行时通过 microDisplay X、Framegrabber SDK 或 pylon 从主机软件中进行更改。在 Module Properties 对话框中，Parameter Type 列显示了参数是静态的还是动态的：

编辑参数后，请在 Module Properties 对话框中单击 Apply。如果输入的新值不在允许范围内，VisualApplets 将会丢弃该值。某些参数处于禁用状态且无法编辑。参数是否可用取决于其他参数设置，或是输入/输出 link 格式。有关特定 operator 的 module parameters 的详细信息，请查阅您所使用的 operator 的 Operator Reference。

有关在示例设计中设置连线和模块参数的演练，请参阅用户手册中的硬件 Applet：从构思到应用。

尺寸参数

许多算子（例如 LineBuffer, FrameBufferMultiRoi和 SelectROI）通过参数定义感兴趣区域 (ROI) XLength, YLength, XOffset和 YOffset.感兴趣区域必须适应所连接 link 上的最大图像尺寸。如果 XLength + XOffset 超过 MaxImageWidth或 YLength + YOffset 超过 MaxImageHeight，DRC 将报告错误，并且参数会显示为红色。

在下面的截图灰度中， SelectROI operator 通过以下方式定义 ROI： XLength 和 YLength 参数：

无限源与 InfiniteSource 参数

诸如相机模块之类的 operator 无法通过流控制停止。它们的行为类似于无限源，且只能连接到接受无限源的 M 型 operator，或者将无限源 Property 向下传播到下游的 O 型和 P 型 operator。

Buffer operator 将无限流转换为可控的可停止流。当 buffer 从不可停止的源接收数据时，请将其设置为 InfiniteSource 参数至 ENABLED.当输入已经是可停止的流时，请设置 InfiniteSource 更改为 DISABLED.

Design Rules Check 包含 InfiniteSource 设置为 DISABLED 在 Infinite Source 之后：

Design Rules Check 包含 InfiniteSource 设置为 ENABLED 在 Infinite Source 之后：

有关无限源的更多详细信息，请参阅可停止和不可停止的数据流教程主题。

溢出算子

即： Overflow 运算符位于 同步方式 library 在下游处理受阻而不可停止的源继续发送图像数据时，会处理溢出情况。它本身不缓存数据。Basler 建议您将其与缓冲区 operator 配合使用。此 operator 不同于 算术溢出 （看 位算术 教程主题）或 Overflow 状态参数 关于缓冲区 operator（参见 Memory 元素 教程主题）。

当您放置 Overflow 在无限源和 memory operator（例如 LineBuffer，设置 InfiniteSource ）之间时，在 memory operator 上 DISABLED。该 Overflow operator 已经处理了来自不可停止流的溢出。在此拓扑中启用 InfiniteSource memory 模块是不正确的，会触发 DRC 错误。

使用 DRC 验证您的设计

在更改影响图像大小、Bit Width 或 ROI 的连线 Property 或模块参数后，请运行 Analysis → Design Rules Check Level 1。1 级会在 DRC 日志中报告形式错误，并高亮显示受影响的模块和连线。

设计规则检查 2 级 运行扩展检查并估算 FPGA 资源。在构建之前，请修复所有 1 级错误。2 级还检查无限源连接和 InfiniteSource 设置。

阅读 DRC 日志以及高亮显示的模块和连线。有关完整的工作流程，请参阅从空设计到运行中的 Applet 教程主题。

链路和参数冲突排查

模块参数和 Link 属性并不是独立的设置。它们直接相互依赖，并会相互限制允许的取值范围。输入和输出连接上的 Link 属性定义了算子必须处理的数据格式。模块参数则定义了算子在该格式内如何处理数据。当您更改 Link 属性时，VisualApplets 会将该更改传播到后续的模块和 Link 中。如果某个模块参数不再符合更新后的 Link 属性，VisualApplets 会将该模块或参数标为红色。反之亦然：模块参数可以定义或更改输出 Link 属性，因此原本合法的值在 Link 更改后可能会变为非法。因此，参数是启用、禁用还是限制在特定范围内，取决于 Link 属性、其他模块参数或两者兼有。对于每个算子，Operator Reference 中都记录了这些依赖关系。有关传播行为以及 Link 更改的三种可能结果，请参阅用户手册中的 Propagation and Dependencies of Operator Parameters and Link Properties。

当 Link 更改后参数值无法固定或模块变红时，请按以下顺序解决冲突：首先检查 link properties before module parameters。Link 属性定义了模块参数的允许取值范围。模块参数必须符合该范围。许多算子还定义或更改输出 Link 属性，因此设计一侧的更改可能会影响另一侧。请阅读 DRC 日志，单击错误消息以突出显示受影响的模块或 Link，并查阅 Operator Reference 了解允许的 Link 格式和参数依赖关系。Link 上或 Module Properties 对话框中的红色高亮显示表示存在形式错误，您必须在模拟或构建之前对其进行修复。

当您尝试将某个 Value 设置参数（例如设为 500）时，通常会发生冲突，而 VisualApplets 会自动校正该输入。输出链路拥有一个 CONST 算子（例如设为 500）时，VisualApplets 会自动校正该输入。输出连接的 Bit Width 为 8 位，这只允许 0 到 255 之间的值。要解决此冲突，请增加输出链路上的链路 Bit Width ，然后再次设置模块参数：

类似的依赖关系也会出现在其他算子中。在 SelectBitField上， BitOffset 参数的有效范围取决于输入和输出链路 Bit Widths。对于灰度图像， BitOffset 必须在 0 到输入 BitWidth 减去输出 BitWidth:

在 ModuloCount 算子， Divisor 参数受输出链路的 Bit Width ，其中 n 代表输出 Bit Width:

这类 Region-of-interest 参数 XLength 和 YLength 必须符合 MaxImageWidth 和 MaxImageHeight 必须与所连接链路上的相匹配。冲突还可能涉及 Parallelism、Color Format 和图像协议。例如， XLength must always be a multiple of the parallelism, which is indicated in the Module Properties dialog as Step Size:

关键术语

在处理参数时，Basler 建议采取以下做法：

• 当您需要运行时的灵活性（例如针对阈值）时，请使用动态参数。运行时是指主机软件与采集卡上的 applet 进行通信，而不是在 VisualApplets 中进行仿真。
• 在对 link properties 或模块参数进行每次更改后，请检查下游链路上传递的 link properties。
• 为下游软件计划 bit-width 调整，例如在 DMA 之前将 12 位相机数据扩展为每像素 16 位。
• 当某个值无法设置时，请在更改模块参数之前检查所连接链路上的 link properties。
• 定期运行 DRC，以便尽早发现链路与模块之间的冲突。

相关主题

• 用户手册中的 Parameterization — 在 GUI 中编辑 Link 属性和模块参数
• 用户手册中的 Example: Applet Parameterization in Basics and Examples — 参数化示例演练
• 用户手册中的 Rules of Links — 正式 Link 规则
• Parallelism 教程主题 — Parallelism link property
• 使用 Kernel 教程主题 — KernelColumns 和 KernelRows
• 位算术 教程主题 — BitWidth 以及算术溢出
• 可停止与不可停止的数据流 教程主题 — InfiniteSource
• 教程主题 Operator Types and Synchronization — 算子类型和 Link 格式
• 教程主题 From Empty Design to Running Applet — 在设计时设置参数