create_shape_modelT_create_shape_modelCreateShapeModelCreateShapeModelcreate_shape_model创建形状模型（算子）

名称

create_shape_modelT_create_shape_modelCreateShapeModelCreateShapeModelcreate_shape_model — 准备一个形状模型进行匹配。

签名

描述

算子 create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 会准备一个模板，该模板作为用于匹配的形状模型，通过图像 TemplateTemplateTemplateTemplatetemplatetemplate 传递进来。模型的 ROI 作为 TemplateTemplateTemplateTemplatetemplatetemplate 的域传递。

输出参数 ModelIDModelIDModelIDModelIDmodelIDmodel_id 是该模型的句柄，用于后续调用 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model。模型图像 TemplateTemplateTemplateTemplatetemplatetemplate 的域（区域）重心被用作模型的原点（参考点）。可通过 set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin 设置不同原点。模型通过多个图像金字塔层级生成并存储在内存中。如果选择了模型的完整预生成（见下文），则模型将在每个层级上以多种旋转角度进行生成。可通过 set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter 添加杂波参数扩展模型。

输入参数的详细说明

NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels：

金字塔层数由参数 NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 决定。该参数应尽可能取大值，因为这样能显著缩短对象搜索所需时间。另一方面，NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 的选择必须确保模型仍可识别，且最高金字塔层包含足够数量的点（至少四个）。可通过 inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model 的输出结果进行验证。若生成的模型点不足，系统将内部减少金字塔层数，直至在最高金字塔层找到足够的模型点。若此函数将导致模型无金字塔层（即最低金字塔层的模型点数已过少）create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 返回一条错误消息。

如果 NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 设置为 'auto'"auto""auto""auto""auto""auto"（或为向后兼容性设置为 0 ），create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 将自动确定金字塔层数。可通过 get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params 查询自动计算出的金字塔层数。在极少数情况下，create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 可能会确定一个过大或过小的金字塔层数值。如果金字塔层数设置过大，模型可能无法在图像中被识别，或者可能需要在 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 中将 MinScoreMinScoreMinScoreMinScoreminScoremin_score 或 GreedinessGreedinessGreedinessGreedinessgreedinessgreediness 参数设置为非常低的值才能找到模型。如果金字塔层数设置过小，find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 中查找模型所需的时间可能会增加。在这些情况下，应使用 inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model 的输出结果来选择金字塔层数。

AngleStartAngleStartAngleStartAngleStartangleStartangle_start, AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent 和 AngleStepAngleStepAngleStepAngleStepangleStepangle_step：

AngleStartAngleStartAngleStartAngleStartangleStartangle_start 和 AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent 参数决定了模型在图像中可能出现的旋转范围。请注意，find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 只能在此角度范围内查找模型。AngleStepAngleStepAngleStepAngleStepangleStepangle_step 参数则决定了选定角度范围内的步进长度。因此，如果未在 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 中指定亚像素精度，则该参数将决定 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 中角度可达到的精度。AngleStepAngleStepAngleStepAngleStepangleStepangle_step 应根据对象尺寸选择。较小的模型在图像中不具备多种不同的离散旋转，因此对于较小的模型，应选择较大的 AngleStepAngleStepAngleStepAngleStepangleStepangle_step。若 AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent 并非 AngleStepAngleStepAngleStepAngleStepangleStepangle_step 的整数倍，则AngleStepAngleStepAngleStepAngleStepangleStepangle_step 将相应调整。为了确保 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 对于没有旋转角度的模型实例返回精确为 0.0 的值，可能的旋转范围将按以下方式修改：若不存在正整数 n 使得 AngleStartAngleStartAngleStartAngleStartangleStartangle_start 加上 n 倍 AngleStepAngleStepAngleStepAngleStepangleStepangle_step 恰为 0.0，则 AngleStartAngleStartAngleStartAngleStartangleStartangle_start 最多减去 AngleStepAngleStepAngleStepAngleStepangleStepangle_step，AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent 增加 AngleStepAngleStepAngleStepAngleStepangleStepangle_step。

OptimizationOptimizationOptimizationOptimizationoptimizationoptimization：

对于特别大的模型，通过将 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization 设置为不同于 'none'"none""none""none""none""none" 的值来减少模型点数可能有所帮助。当 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization = 'none'"none""none""none""none""none" 时，所有模型点都会被存储。在其他所有情况下，点数会根据 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization 的值进行减少。对于小型模型，减少模型点数并不会提升搜索速度，因为此时通常需要检查更多如果点数减少，可能需要在 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 中将 GreedinessGreedinessGreedinessGreedinessgreedinessgreediness 参数设置为较小的值，例如 0.7 或 0.8。潜在模型实例。

如果将 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization 设置为 'auto'"auto""auto""auto""auto""auto"，create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 会自动确定模型点数的减少量。

MetricMetricMetricMetricmetricmetric：

参数 MetricMetricMetricMetricmetricmetric 决定了模型在图像中被识别的条件。

如果 MetricMetricMetricMetricmetricmetric = 'use_polarity'"use_polarity""use_polarity""use_polarity""use_polarity""use_polarity"，则图像中的对象与模型必须具有相同的对比度。例如，如果模型是暗背景上的亮色对象，则只有当该对象也比背景更亮时才能被识别。

如果 MetricMetricMetricMetricmetricmetric = 'ignore_global_polarity'"ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity"，即使图像整体对比度发生反转，该对象仍会被识别。因此在上例中，即使对象比背景更暗，仍会被识别。在这种情况下，find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 的运行时间会略有增加。

如果 MetricMetricMetricMetricmetricmetric = 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity"，即使局部对比度发生变化，模型仍会被识别。例如，当对象包含一个中等灰度值的主体剖分，其内部存在更暗或更亮的子对象时，此模式便能发挥作用。由于在此情况下 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 的运行时间会显著增加，因此通常最好使用 create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 创建多个能够反映对象可能对比度变化的模型，并使用 find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModelsfind_shape_models 同时进行匹配。

上述三项指标仅适用于单通道图像。若将多通道图像用作模型图像或搜索图像，则仅使用首个通道（且不会返回错误信息）。

如果 MetricMetricMetricMetricmetricmetric = 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity"，即使局部颜色对比度发生变化，模型仍能被识别。例如当对象部分区域可变色（如从红色变为绿色）时即属此类情况。该模式尤其适用于无法预先确定对象在哪些通道可见的场景。在此模式下，find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 的运行时间也可能显著增加。指标 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity" 可用于任意通道数的图像。若应用于单通道图像，其效果等同于 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity"。需要注意的是，当 MetricMetricMetricMetricmetricmetric = 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity" 时，使用 create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 创建模型时与使用 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 进行搜索时的通道数量可能不同。例如可利用此特性基于合成单通道图像创建模型。此外需注意，通道无需包含光谱分层数据（如 RGB 图像）。例如，这些通道还可能包含同一对象的图像，这些图像通过从不同方向照射对象获得。

ContrastContrastContrastContrastcontrastcontrast：

参数 ContrastContrastContrastContrastcontrastcontrast 决定模型点必须具备的对比度。该对比度衡量对象与背景之间、以及对象不同部分之间的局部灰度值差异。ContrastContrastContrastContrastcontrastcontrast 应选择为仅使用模板中的显著特征来构建模型。ContrastContrastContrastContrastcontrastcontrast 也可包含一个具有两个值的元组。此时，模型将采用类似于 edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image 中使用的滞后阈值法进行分割。元组的首个元素决定下限阈值，第二个元素决定上限阈值。有关滞后阈值法的更多信息，请参阅 hysteresis_thresholdhysteresis_thresholdHysteresisThresholdHysteresisThresholdHysteresisThresholdhysteresis_threshold。可选地，ContrastContrastContrastContrastcontrastcontrast 可包含第三个值作为元组的最后一个元素。该值用于根据模型组件尺寸筛选显著组件，即尺寸小于指定最小值的组件将被抑制。由于最小尺寸限制作用于组件范围，生成的模型轮廓仍可能小于指定最小值。该最小尺寸阈值在金字塔各层级中均按二分法递减。若需抑制小型模型组件但不执行迟滞阈值处理，仍需在 ContrastContrastContrastContrastcontrastcontrast 中指定三个数值。此时前两个数值可设置为相同值。该参数效果可通过 inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model 工具预先验证。

如果将 ContrastContrastContrastContrastcontrastcontrast 设置为 'auto'"auto""auto""auto""auto""auto"，create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 将自动确定上述三个值。只有对比度（'auto_contrast'"auto_contrast""auto_contrast""auto_contrast""auto_contrast""auto_contrast"）、滞后阈值（'auto_contrast_hyst'"auto_contrast_hyst""auto_contrast_hyst""auto_contrast_hyst""auto_contrast_hyst""auto_contrast_hyst"）或最小尺寸（'auto_min_size'"auto_min_size""auto_min_size""auto_min_size""auto_min_size""auto_min_size"）可以自动确定。 其余未自动确定的参数可通过元组形式额外传递。同时支持多种组合方式：例如传递 ['auto_contrast','auto_min_size']["auto_contrast","auto_min_size"]["auto_contrast","auto_min_size"]["auto_contrast","auto_min_size"]["auto_contrast","auto_min_size"]["auto_contrast","auto_min_size"] 时，对比度与最小尺寸均自动确定。若传递 ['auto_min_size',20,30]["auto_min_size",20,30]["auto_min_size",20,30]["auto_min_size",20,30]["auto_min_size",20,30]["auto_min_size",20,30]，则最小尺寸自动确定，而迟滞阈值分别设为 20 和 30 等。某些情况下，自动确定的对比度阈值可能无法满足需求。例如：当因应用需求需保留或抑制特定模型组件，或对象包含多种对比度时，应优先手动设置参数。因此，在调用 create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 之前，应先使用 determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParamsdetermine_shape_model_params 自动确定对比度阈值，并随后通过 inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model 进行验证。需注意 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 会影响自动对比度估算，进而影响最小尺寸的估算结果。

MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast：

通过 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 参数，可以确定模型在 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 执行的识别过程中至少应具备的对比度。换言之，该参数用于将模型与图像中的噪声分离。因此，理想设置应为图像噪声引发的灰度值变化范围。例如，若灰度值波动范围在 10 个灰度级内，则应将 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设为 10。当模型与搜索图像均为多通道图像，且参数 MetricMetricMetricMetricmetricmetric 设为 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity"（参见前文）时，需将单通道噪声乘以通道数平方根来确定 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 值。例如：若单通道灰度值波动范围为 10 个灰度级，且图像为三通道图像，则 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 应设为 17。显然，MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 必须小于 ContrastContrastContrastContrastcontrastcontrast。若需在极低对比度图像中识别模型，则需将 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设置为相应较小的数值。如果希望即使在模型严重被遮挡的情况下也能被识别，MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 应略大于噪声产生的灰度值波动范围，以确保 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 能稳健且准确地提取模型的位置和旋转信息。

如果 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设置为 'auto'"auto""auto""auto""auto""auto"，则最小对比度将根据模型图像中的噪声自动确定。因此，只有当识别过程中的图像噪声与模型图像中的噪声相似时，自动确定才具有意义。此外，在某些情况下，建议增加自动确定的值，以提高对遮挡的稳健性（参见上文）。可通过 get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params 查询自动计算的最小对比度。

完成模型的预生成

可选地，可在 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization 中传递第二个参数。该参数决定模型是否进行完全预生成。为此，需将 OptimizationOptimizationOptimizationOptimizationoptimizationoptimization 的第二个值设置为 'pregeneration'"pregeneration""pregeneration""pregeneration""pregeneration""pregeneration" 或 'no_pregeneration'"no_pregeneration""no_pregeneration""no_pregeneration""no_pregeneration""no_pregeneration"。若未使用第二个参数（即仅传递单个参数），则采用通过 set_system('pregenerate_shape_models',...)set_system("pregenerate_shape_models",...)SetSystem("pregenerate_shape_models",...)SetSystem("pregenerate_shape_models",...)SetSystem("pregenerate_shape_models",...)set_system("pregenerate_shape_models",...) 设置的模式。默认值（'pregenerate_shape_models'"pregenerate_shape_models""pregenerate_shape_models""pregenerate_shape_models""pregenerate_shape_models""pregenerate_shape_models" = 'false'"false""false""false""false""false"）下，模型不会进行完全预生成。模型的完整预生成通常会导致运行时间略微缩短，因为模型在运行时无需进行转换。但此模式下内存需求和模型创建时间将显著增加。需注意两种模式无法产生完全相同的结果，因为运行时转换模型必然导致转换后模型的内部数据与预生成转换模型存在差异。例如，如果模型尚未完全预生成，find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 通常会返回稍低的分数，这可能需要将 MinScoreMinScoreMinScoreMinScoreminScoremin_score 的值设置得比完全预生成的模型稍低一些。此外，两种模式下通过插值获得的姿态可能存在细微差异。若追求最高精度，应通过最小二乘法调整确定模型姿态。

如果选择了模型的完整预生成，系统将针对所选的角度范围预生成模型并将其存储在内存中。存储模型所需的内存大小与角度步长数量及模型中的点数成正比。因此，若 AngleStepAngleStepAngleStepAngleStepangleStepangle_step 设置过小或 AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent 设定过大，可能导致模型无法再容纳于（虚拟）内存中。此时需扩大 AngleStepAngleStepAngleStepAngleStepangleStepangle_step 或缩小 AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent。无论如何，模型完全容纳于主内存是理想状态，因为这可避免操作系统进行分页操作，从而大幅缩短查找对象的时间。由于 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 能够以亚像素级分辨率确定角度，因此对于直径小于约 200 像素的模型，可以选择 AngleStepAngleStepAngleStepAngleStepangleStepangle_step >= 1。

如果选择了 AngleStepAngleStepAngleStepAngleStepangleStepangle_step = 'auto'"auto""auto""auto""auto""auto"（或为向后兼容而设的 0），create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 会根据模型的大小自动确定合适的角度步长。可以通过 get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params 查询自动计算出的角度步长。

若未选择完整预生成模型，则模型仅在每个金字塔层级的参考姿态下创建。在这种情况下，必须在运行时通过 find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model 将模型转换为不同的角度和比例。因此，该模型的识别过程可能需要稍长的时间。

请注意，预生成形状模型是针对特定图像尺寸定制的。出于运行时间考虑，不支持在搜索过程中使用相同模型并行处理不同尺寸的图像。此时必须使用相同模型的副本，否则程序可能崩溃！

执行信息

• 多线程类型：可重入（与非独占算子并行运行）。
• 多线程作用域：全局（可从任何线程调用）。
• 未采用并行化处理。

此算子返回一个句柄。请注意，即使该句柄被用作特定算子的输入参数，这些算子仍可能改变此句柄类型的实例状态。

参数

结果

如果参数有效，算子 create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model 返回值 2 (H_MSG_TRUE)。如有必要，则抛出异常。如果参数 NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 和 ContrastContrastContrastContrastcontrastcontrast 的选择导致模型包含的点过少，则会引发错误 8510。

可能的前趋

draw_regiondraw_regionDrawRegionDrawRegionDrawRegiondraw_region, reduce_domainreduce_domainReduceDomainReduceDomainReduceDomainreduce_domain, thresholdthresholdThresholdThresholdThresholdthreshold

可能的后继

find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model, find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModelsfind_shape_models, get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params, clear_shape_modelclear_shape_modelClearShapeModelClearShapeModelClearShapeModelclear_shape_model, write_shape_modelwrite_shape_modelWriteShapeModelWriteShapeModelWriteShapeModelwrite_shape_model, set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin, set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter

替代

create_generic_shape_modelcreate_generic_shape_modelCreateGenericShapeModelCreateGenericShapeModelCreateGenericShapeModelcreate_generic_shape_model

另见

set_systemset_systemSetSystemSetSystemSetSystemset_system, get_systemget_systemGetSystemGetSystemGetSystemget_system

模块

匹配

---