10 算子速查表#
用法
按"我想做什么"查表。括号内为参数顺序，: 前面是输入输出图像/区域，后面是控制参数。
快捷键：光标停在算子上按 F1 打开官方帮助（先看 Signature 定参数顺序，再看 Description 懂含义）。
一、窗口与显示（dev_ / disp_ / set_）#
| 算子 | 签名要点 | 说明 |
|---|---|---|
dev_close_window () |
无参 | 关闭当前图形窗口 |
dev_open_window (Row, Column, Width, Height, Background, WindowHandle) |
全为控制参数 | 打开新窗口，左上角屏幕坐标 + 尺寸 + 底色 |
dev_clear_window () |
无参 | 清空窗口（重画前必做） |
dev_display (Object) |
图像 / 区域 / XLD | 显示对象 |
dev_set_color (Color) |
'red' 'green' 'blue' 'black' 'white' 'yellow' 'cyan' 'magenta' 'pink' 'orange' |
设绘制颜色 |
dev_set_colored (NumColors) |
如 12 |
用 N 色循环给多个区域上色 |
dev_set_draw ('fill' \| 'margin') |
'fill' 填充 / 'margin' 只画轮廓 |
区域显示模式 |
dev_set_line_width (Width) |
如 3 |
线宽 |
dev_set_paint (...) |
—— | 更高级的绘制模式设置 |
set_display_font (WindowHandle, Size, Font, Bold, Slant) |
如 (W, 14, 'mono', 'true', 'false') |
设字体 |
disp_message (WindowHandle, String, CoordSystem, Row, Column, Color, Box) |
Box = 'true'/'false' |
绘制文字（可传元组，自动逐个显示） |
disp_arrow (WindowHandle, Row1, Column1, Row2, Column2, Size) |
起终点 + 箭头大小 | 画箭头 |
disp_circle (WindowHandle, Row, Column, Radius) |
—— | 画圆 |
disp_cross (WindowHandle, Row, Column, Size, Angle) |
—— | 画十字 |
disp_line (WindowHandle, Row1, Column1, Row2, Column2) |
—— | 画线段 |
disp_rectangle1 (WindowHandle, Row1, Column1, Row2, Column2) |
—— | 画正矩形 |
disp_rectangle2 (WindowHandle, Row, Column, Phi, Len1, Len2) |
中心 + 角度 + 半长半宽 | 画带角度矩形 |
dev_disp_text (Text, CoordSystem, Row, Column, Color, GenParamName, GenParamValue) |
CoordSystem = 'image'/'window' |
开发环境文字显示，不需要 WindowHandle |
dev_update_window ('off' \| 'on') |
—— | 关闭/打开自动刷新（提速） |
dev_update_off () / dev_update_on () |
—— | 一次性关闭/打开窗口与变量窗口更新 |
'image' 与 'window' 坐标
标注目标用 'image'（跟着图像走），显示统计信息用 'window'（固定在窗口某处）。
二、图像读写与信息#
| 算子 | 签名要点 | 说明 |
|---|---|---|
read_image (Image, FileName) |
文件名可为元组 | 读图；HALCON 自带图直接写名字，如 'clip'、'printer_chip/printer_chip_01' |
write_image (Image, Format, FillColor, FileName) |
—— | 写图 |
get_image_size (Image, Width, Height) |
输出顺序：宽、高 | 获取图像尺寸 |
get_image_type (Image, Type) |
—— | 获取像素类型（'byte' / 'uint2' / 'real' …） |
list_files (Directory, Options, Files) |
Options：'files' 'directories' 'recursive' 'max_depth N' 'follow_links' |
列出文件，输出路径元组 |
tuple_regexp_select (Tuple, Pattern, Selection) |
正则 | 按后缀筛文件，如 ['\\.(bmp|png|jpg)$'] |
count_obj (Objects, Number) |
—— | 统计对象个数 |
三、区域生成（gen_ / draw_）#
| 算子 | 签名要点 | 说明 |
|---|---|---|
gen_circle (Circle, Row, Column, Radius) |
中心 + 半径 | 生成圆区域 |
gen_rectangle1 (Rectangle, Row1, Column1, Row2, Column2) |
对角两点 | 生成正矩形区域 |
gen_rectangle2 (Rectangle, Row, Column, Phi, Len1, Len2) |
中心 + 角度 + 半长半宽 | 生成带角度矩形区域 |
gen_region_line / gen_region_polygon / gen_region_points |
—— | 生成线/多边形/点区域 |
draw_circle (WindowHandle, Row, Column, Radius) |
交互式，只返回参数 | 鼠标画圆取参，需配合 gen_circle |
draw_rectangle1 / draw_rectangle2 / draw_region |
同上 | 交互式取参 |
threshold (Image, Region, MinGray, MaxGray) |
闭区间 | 灰度阈值分割 |
binary_threshold (Image, Region, Method, LightDark, UsedThreshold) |
Method='max_separability'(Otsu) |
自动阈值分割，'dark'/'light' |
dyn_threshold (OrigImage, ThresholdImage, RegionDynThresh, Offset, LightDark) |
局部动态阈值 | 光照不均时使用 |
regiongrowing / watersheds |
—— | 区域生长 / 分水岭 |
四、区域集合运算#
| 算子 | 数学含义 | 记忆 |
|---|---|---|
intersection (R1, R2, Out) |
\(R_1 \cap R_2\) | 共有部分 |
union1 (Regions, Out) |
合并一整组 | 一组变一个 |
union2 (R1, R2, Out) |
\(R_1 \cup R_2\) | 两个变一个 |
difference (R1, R2, Out) |
\(R_1 - R_2\) | 有方向！ R1 挖掉 R2 |
symm_difference (R1, R2, Out) |
\(R_1 \oplus R_2\) | 异或，并集减交集 |
complement (R, Out) |
\(\overline{R}\) | 相对整幅图像取反 |
concat_obj (Obj1, Obj2, Out) |
拼接 | 不合并像素，个数相加 |
五、分割与形态学#
| 算子 | 说明 |
|---|---|
connection (Region, ConnectedRegions) |
按8 邻域打散成连通域 |
dilation_circle (Region, Out, Radius) |
膨胀（变胖） |
erosion_circle (Region, Out, Radius) |
腐蚀（变瘦） |
opening_circle (Region, Out, Radius) |
开运算：先腐蚀后膨胀 → 去小白点/毛刺 |
closing_circle (Region, Out, Radius) |
闭运算：先膨胀后腐蚀 → 填小黑点/裂缝 |
dilation_rectangle1 / erosion_rectangle1 / opening_rectangle1 / closing_rectangle1 |
矩形结构元版本 |
opening / closing |
任意结构元版本 |
fill_up (Region, Out) |
填充所有孔洞（不看孔大小） |
boundary (Region, Border, 'inner'\|'outer') |
取边界 |
skeleton (Region, Skeleton) |
取骨架（中轴） |
shape_trans (Region, Out, Type) |
'convex' 凸包 / 'ellipse' 等效椭圆 / 'rectangle1' / 'rectangle2' |
distance_transform (Region : DistanceImage : Metric, Foreground, Width, Height) |
距离变换：区域内（'true'）或区域外（'false'）每个点到边界的距离；Metric 可用 'euclidean'。用来求缺陷内切圆半径 → 定形态学半径下限 |
一句话口诀
开运算去"白"的小东西，闭运算去"黑"的小东西。
Radius 怎么定？
圆盘结构元下，腐蚀/膨胀等价于距离阈值，所以
半径下限 = 缺陷的内切圆半径（白斑到最近黑点的最大距离 / 孔洞到最近白点的最大距离），
用 distance_transform 在缺陷区域内取极大值即可得到；
实际贴着它向上取（Radius 是实数，不必凑整）。标定流程与实测数据见 [[13 形态学调整 结构元半径标定]]。
六、特征与筛选#
| 算子 | 说明 |
|---|---|
select_shape (Regions, Sel, Features, Operation, Min, Max) |
按形状特征筛选，Operation = 'and'/'or' |
select_shape_std (Regions, Sel, ShapeFeature, Percent) |
'max_area' / 'original' |
select_gray (Regions, Image, Sel, Features, Op, Min, Max) |
按灰度特征筛选（'mean' 'max' 'deviation' …） |
select_obj (Regions, Obj, Index) |
按序号取区域，序号从 1 开始 |
sort_region (Regions, Sorted, SortMode, Order, RowOrCol) |
排序，如 ('first_point','true','column') 从左到右 |
count_obj (Objects, Number) |
统计个数 |
select_shape 常用特征速记：
| 类别 | 特征名 |
|---|---|
| 位置尺寸 | 'area' 'row' 'column' 'width' 'height' 'ratio' 'row1' 'column1' 'row2' 'column2' |
| 形状相似 | 'circularity' 'roundness' 'compactness' 'convexity' 'rectangularity' 'anisometry' 'num_sides' 'contlength' |
| 椭圆外接 | 'ra' 'rb' 'phi' 'outer_radius' 'inner_radius' 'inner_width' 'inner_height' 'rect2_phi' 'rect2_len1' 'rect2_len2' 'max_diameter' 'orientation' |
| 拓扑 | 'connect_num' 'holes_num' 'area_holes' 'euler_number' |
| 矩 | 'moments_m11' 'moments_m20' 'moments_m02' 'moments_ia' 'moments_ib' |
| 距离 | 'dist_mean' 'dist_deviation' 'bulkiness' 'struct_factor' |
七、图像预处理与滤波#
| 算子 | 公式 / 说明 |
|---|---|
scale_image (Image, Out, Mult, Add) |
\(g' = \text{Mult}\cdot g + \text{Add}\) |
sub_image (Image1, Image2, Out, Mult, Add) |
\(g' = \text{Mult}\cdot(g_1-g_2) + \text{Add}\) |
add_image / mult_image / div_image |
图像加减乘除 |
mean_image (Image, Out, MaskWidth, MaskHeight) |
均值滤波（快，边缘模糊） |
median_image (Image, Out, MaskType, Radius, Margin) |
中值滤波（去椒盐噪点，保边） |
gauss_filter / smooth_image |
高斯 / 通用平滑 |
emphasize (Image, Out, MaskWidth, MaskHeight, Factor) |
增强局部对比（锐化） |
illuminate (Image, Out, MaskWidth, MaskHeight, Factor) |
光照补偿、提亮暗区（窗口要开大） |
anisotropic_diffusion |
各向异性扩散（保边平滑，慢但好） |
详见 图像预处理与滤波。
八、测量与特征提取#
| 算子 | 输出 | 说明 |
|---|---|---|
area_center (Regions, Area, Row, Column) |
面积 + 质心 | 顺序：Area, Row, Column |
orientation_region (Regions, Phi) |
主轴方向（弧度，−π ≤ Φ < π） | 用 deg() 转角度 |
smallest_circle (Regions, Row, Column, Radius) |
最小外接圆 | 对应 'outer_radius' |
inner_circle (Regions, Row, Column, Radius) |
最大内切圆 | 对应 'inner_radius' |
smallest_rectangle1 (Regions, Row1, Column1, Row2, Column2) |
最小外接正矩形 | 对应 'width' 'height' |
smallest_rectangle2 (Regions, Row, Column, Phi, Len1, Len2) |
最小外接带角矩形 | 对应 'rect2_phi' 'rect2_len1' 'rect2_len2' |
elliptic_axis (Regions, Ra, Rb, Phi) |
等效椭圆 | 对应 'ra' 'rb' 'phi' |
circularity (Regions, Circularity) |
圆度 | \(C=\min(1, F/(max^2\pi))\) |
roundness (Regions, Distance, Sigma, Roundness, Sides) |
圆度/轮廓均匀度 | 与 circularity 不同，见 区域特征与 select_shape 筛选 |
compactness (Regions, Compactness) |
紧密度 | \(P^2/(4\pi F)\)，圆 = 1 |
convexity (Regions, Convexity) |
凸度 | 区域/凸包面积 |
rectangularity (Regions, Rectangularity) |
矩形度 | 区域/最小外接矩形 |
contlength (Regions, ContLength) |
轮廓长度 | —— |
connect_and_holes (Regions, NumConnected, NumHoles) |
连通数 + 孔数 | 对应 'connect_num' 'holes_num' |
area_holes (Regions, AreaHoles) |
孔面积和 | —— |
euler_number (Regions, EulerNumber) |
欧拉数 | 连通数 − 孔数 |
diameter_region (Regions, Row1, Column1, Row2, Column2, Diameter) |
最大直径 | 对应 'max_diameter' |
moments_region_2nd (Regions, M11, M20, M02, Ia, Ib) |
二阶矩 | ia ≥ ib |
height_width_ratio (Regions, Ratio) |
高宽比 | 对应 'ratio' |
单位提醒
角度类输出（Phi）默认是弧度。转角度用 deg()，反之为 rad()。
8.1 距离与角度#
| 算子 | 算什么 |
|---|---|
distance_pp (Row1, Column1, Row2, Column2, Distance) |
点到点 |
distance_pl (Row, Column, Row1, Column1, Row2, Column2, Distance) |
点到直线（直线用两点式，点在参数前面） |
distance_pc (Row, Column, RowC, ColumnC, RadiusC, DistanceMin, DistanceMax) |
点到圆（两个输出：最近 / 最远） |
distance_cc (ContCircle1, ContCircle2, Mode, DistanceMin, DistanceMax) |
圆到圆（传 XLD 轮廓），Mode 常用 'point_to_point' |
distance_lc (ContCircle, Row1, Column1, Row2, Column2, DistanceMin, DistanceMax) |
线到圆（圆传轮廓） |
angle_ll (RowA1, ColA1, RowA2, ColA2, RowB1, ColB1, RowB2, ColB2, Angle) |
两直线夹角（弧度） |
8.2 2D 计量（Metrology）#
详见 测量模型 2D Metrology。五步：create_metrology_model → set_metrology_model_image_size → add_metrology_object_*_measure → apply_metrology_model → get_metrology_object_result。
| 算子 | 说明 |
|---|---|
create_metrology_model (MetrologyHandle) |
创建计量模型（空壳） |
set_metrology_model_image_size (Handle, Width, Height) |
告诉它图像尺寸（应在 add_* 之前） |
add_metrology_object_line_measure (Handle, RowBegin, ColBegin, RowEnd, ColEnd, MeasureLength1, MeasureLength2, MeasureSigma, MeasureThreshold, GenParamName, GenParamValue, Index) |
加"找线"对象 |
add_metrology_object_circle_measure (Handle, Row, Column, Radius, ...) |
加"找圆"对象 |
add_metrology_object_rectangle2_measure (Handle, Row, Column, Phi, Length1, Length2, ...) |
加"找矩形"对象 |
add_metrology_object_ellipse_measure (Handle, Row, Column, Phi, Radius1, Radius2, ...) |
加"找椭圆"对象 |
add_metrology_object_generic (Handle, Shape, ShapeParam, ...) |
通用版，Shape = 'circle'/'ellipse'/'rectangle2'/'line' |
set_metrology_object_param (Handle, Index, GenParamName, GenParamValue) |
调卡尺（Index 可写 'all'） |
apply_metrology_model (Image, Handle) |
执行测量 |
get_metrology_object_result (Handle, Index, Instance, 'result_type', 'all_param', Parameter) |
取结果 |
get_metrology_object_result_contour (Contour, Handle, Index, Instance, Resolution) |
取拟合出来的形状轮廓 |
get_metrology_object_model_contour (Contour, Handle, Index, Resolution) |
取你画的近似形状轮廓 |
get_metrology_object_measures (Contours, Handle, Index, Transition, Row, Column) |
取卡尺矩形 + 实测边缘点 |
set_metrology_model_param (Handle, 'reference_system', [Row, Column, Angle]) |
定基准（只在建模型时设一次） |
align_metrology_model (Handle, Row, Column, Angle) |
对齐到当前图的姿态（每次测之前都要调，会被下次覆盖） |
gen_cross_contour_xld (Cross, Row, Column, Size, Angle) |
把边缘点画成十字叉 |
all_param 输出顺序：circle [row, column, radius]（3）／ line [row_begin, column_begin, row_end, column_end]（4）／ rectangle2 [row, column, phi, length1, length2]（5）／ ellipse [row, column, phi, radius1, radius2]（5）。
关键参数默认值：MeasureLength1 = 20（垂直于边界的半长 = 测量容差）／ MeasureLength2 = 5（切向半长）／ num_measures = 10／ num_instances = 1／ min_score = 0.7／ distance_threshold = 3.5（RANSAC）。
三条最容易踩的
① num_measures 与 measure_distance 互斥（设了后者，前者失效）；卡尺数下限：圆 3 / 椭圆 5 / 直线 2 / 矩形每边 2。
② all_param 是按"添加顺序 × 实例"拼的一维元组，下标要自己算。
③ 三个 get_*_contour 含义不同：model_contour = 你画的近似形状，measures = 卡尺+边缘点，result_contour = 拟合结果。
九、仿射变换（HomMat2D）#
详见 仿射变换矩阵与图像变换、仿射变换实战 区域轮廓与抠图。
一句话铁律
齐次矩阵作用在图像数据上时，行坐标传给 x、列坐标传给 y，也就是照常按 (Row, Column) 顺序写。官方原文：the order of passing row and column coordinates follows the usual order (Row, Column)。正角度 = 屏幕上逆时针。
矩阵的存储：HomMat2D 是长度 6 的实数元组 [ra, rb, tc, rd, re, tf]，对应
\(\begin{bmatrix} ra & rb & tc\\ rd & re & tf\\ 0&0&1\end{bmatrix}\)。
9.1 构造矩阵#
| 算子 | 参数顺序 | 说明 |
|---|---|---|
hom_mat2d_identity (HomMat2DIdentity) |
无 | 单位矩阵，手工拼装的起点（必写） |
hom_mat2d_rotate (HomMat2D, Phi, Px, Py, Out) |
角度在前，(Px,Py) = 固定点 |
逆时针旋转 Phi（弧度） |
hom_mat2d_scale (HomMat2D, Sx, Sy, Px, Py, Out) |
缩放在前，(Px,Py) = 固定点 |
Sx 管行方向、Sy 管列方向 |
hom_mat2d_translate (HomMat2D, Tx, Ty, Out) |
无固定点 | Tx 移行、Ty 移列 |
hom_mat2d_slant (HomMat2D, Theta, Axis, Px, Py, Out) |
Axis = 'x'/'y' |
斜切；'y' 表示 y 轴斜切、x 轴不动 |
hom_mat2d_reflect (HomMat2D, Px, Py, Out) |
—— | 关于直线镜像 |
vector_angle_to_rigid (Row1, Col1, Ang1, Row2, Col2, Ang2, Out) |
全为控制参数 | 点 + 角度对应 → 刚体矩阵，最常用 |
vector_to_rigid / vector_to_similarity / vector_to_aniso / vector_to_hom_mat2d |
—— | 多组对应点反求矩阵（能力依次变强） |
hom_mat2d_invert (HomMat2D, Out) |
—— | 求逆（正变换 ↔ 反变换） |
hom_mat2d_to_affine_par (HomMat2D, Sx, Sy, Phi, Theta, Tx, Ty) |
6 个输出 | 反解变换参数 |
叠加顺序
hom_mat2d_* 是左乘：代码里先写的操作，先作用在对象上。
因此后面操作里的固定点 (Px, Py) 要写"前面几步搬完之后"的位置 —— 写"原始位置"就会跑偏。
9.2 用出去#
| 算子 | 对象 | 控制参数 |
|---|---|---|
affine_trans_image (Image, Out : HM, Interpolation, AdaptImageSize) |
Image | 插值 'nearest_neighbor'/'bilinear'/'constant'(默认)/'weighted'/'bicubic'；尺寸 'true'/'false'（默认） |
affine_trans_region (Region, Out : HM, Interpolate) |
Region | 'nearest_neighbor'(默认) / 'constant' |
affine_trans_contour_xld (Contours, Out : HM) |
XLD 轮廓 | 无 |
affine_trans_polygon_xld (Polygons, Out : HM) |
XLD 多边形 | 无 |
affine_trans_pixel (HM, Row, Col, RowT, ColT) |
点，像素坐标系 | 传参 (Row, Col) |
affine_trans_point_2d (HM, Px, Py, Qx, Qy) |
点，标准坐标系 | 传参 (Px, Py) = (Col, Row) |
三条容易踩的
① affine_trans_image 忽略输入图像的 domain（当作整幅矩形），且左、上边界永远会被裁掉；
② affine_trans_image / affine_trans_region 用的是像素坐标系（原点在左上角像素外角），和 area_center 返回的标准坐标系差 0.5 像素；
③ hom_mat2d_to_affine_par 只认官方的拼装顺序 scale → slant → rotate → translate，顺序不同就反解不回原参数。
顺带记住这几个
gen_contour_region_xld (Regions : Contours : Mode)，Mode='border'（默认）/'center'/'border_holes'area_center_xld (XLD : : : Area, Row, Column, PointOrder)，比区域版多一个绕行方向orientation_xld (XLD : : : Phi)reduce_domain (Image, Region : ImageReduced)—— 矩阵尺寸不变crop_domain (Image : ImagePart)—— 矩阵裁到 domain 的最小外接矩形full_domain (Image : ImageFull)—— 把 domain 扩回整块矩形
十、模板匹配（形状匹配）#
详见 模板匹配 形状匹配 Shape-Based Matching。
| 算子 | 参数顺序 | 说明 |
|---|---|---|
create_shape_model (Template, NumLevels, AngleStart, AngleExtent, AngleStep, Optimization, Metric, Contrast, MinContrast, ModelID) |
9 入 1 出 | 用 ROI（Template 的 domain）训练形状模型 |
create_scaled_shape_model (...) |
多 4 个缩放参数 | 各向同性缩放版本 |
create_aniso_shape_model (Template, NumLevels, AngleStart, AngleExtent, AngleStep, ScaleRMin, ScaleRMax, ScaleRStep, ScaleCMin, ScaleCMax, ScaleCStep, Optimization, Metric, Contrast, MinContrast, ModelID) |
15 入 1 出 | 各向异性缩放（行、列独立倍率） |
find_shape_model (Image, ModelID, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels, Greediness, Row, Column, Angle, Score) |
10 入 4 出 | 查找实例 |
find_scaled_shape_model (...) / find_aniso_shape_model (..., ScaleRMin, ScaleRMax, ScaleCMin, ScaleCMax, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels, Greediness, Row, Column, Angle, ScaleR, ScaleC, Score) |
—— | 带缩放的查找，aniso 版多两个输出 ScaleR/ScaleC |
find_shape_models (Image, ModelIDs, ...) |
复数 | 同时匹配多个模型（比 ignore_local_polarity 更快） |
get_shape_model_contours (ModelContours, ModelID, Level) |
Level ≥ 1，1 = 最细层 |
取模型轮廓用于可视化；轮廓已归一化，参考点在 (0,0) |
get_shape_model_params (ModelID, NumLevels, AngleStart, ...) |
—— | 查询创建时自动定下的参数 |
set_shape_model_origin (ModelID, Row, Column) |
—— | 改模型原点（find_shape_model 不认它） |
set_shape_model_param (ModelID, 'border_shape_models', 'true') |
—— | 允许模型部分出界（会变慢）；全局版 set_system |
inspect_shape_model (Image, ModelImages, ModelRegions, NumLevels, Contrast) |
—— | 看每个金字塔层的模型点够不够（≥4 个） |
determine_shape_model_params (...) |
—— | 自动推荐 Contrast / MinContrast 等参数 |
write_shape_model (ModelID, FileName) / read_shape_model (FileName, ModelID) |
—— | 模型存盘/读取，工程里用它免掉每次重训 |
clear_shape_model (ModelID) |
—— | 释放句柄 |
关键参数取值速记
| 参数 | 取值 | 含义 |
|---|---|---|
Metric |
'use_polarity' / 'ignore_global_polarity' / 'ignore_local_polarity' / 'ignore_color_polarity' |
对比度匹配规则；前三种只用单通道（静默取第一通道），第四种支持多通道 |
SubPixel |
'none' / 'interpolation'（推荐）/ 'least_squares' / 'least_squares_high' / 'least_squares_very_high' / ['least_squares','max_deformation 2'] |
亚像素精度，max_deformation 取值 0~32 |
NumMatches |
0 = 找全部 |
MinScore 优先于它 |
Greediness |
0 = 安全慢 / 1 = 快可能漏 |
抽稀模型点后降到 0.7~0.8 |
MinScore |
无遮挡可 0.8~0.9 |
得分下限，越大越快 |
MaxOverlap |
0~1，0 = 互不重叠 |
模型有对称性时要调大 |
Contrast |
'auto' 或 \([下,上]\) 或 \([下,上,最小尺寸]\) |
滞后阈值，第三值按成分大小抑制小碎块 |
MinContrast |
'auto' 或数值 |
把模型与噪声分开 |
三条最容易踩的
① 角度一律是弧度，写 rad(180) 不是 180；创建与查找的角度范围必须有重叠。
② 模型必须完全落在图像内才可能被找到；贴边也可能漏，需 set_system ('border_shape_models','true')。
③ get_shape_model_contours 的轮廓在 \((0,0)\)，回显顺序必须是 旋转（+缩放）→ 平移，颠倒就飞出画面。
十一、识别（条码 / 二维码 / OCR）#
详见 读码与 OCR 一维码 二维码 字符识别。三条链路套路一致：建句柄 → 找 → 取结果（字符串 + 区域）→ 释放。
11.1 一维条码#
| 算子 | 说明 |
|---|---|
create_bar_code_model (GenParamName, GenParamValue, BarCodeHandle) |
建条码模型（两个空元组即可） |
find_bar_code (Image, SymbolRegions, BarCodeHandle, CodeType, DecodedDataStrings) |
读码；CodeType = 'auto' 或具体码制；输出 Region |
get_bar_code_result (Handle, CandidateHandle, ResultName, ResultValue) |
'decoded_types' / 'decoded_strings' / 'decoded_reference' / 'orientation' / 'element_size' / 'quality_isoiec15416' / 'aborted' |
get_bar_code_object (BarCodeObjects, Handle, CandidateHandle, 'symbol_regions') |
取条码区域对象 |
set_bar_code_param (Handle, GenParamName, GenParamValue) |
'element_size_min' / 'check_char'（'absent'/'present'/'preserved'）/ 'timeout' / 'composite_code' |
clear_bar_code_model (Handle) |
释放 |
支持码制：2/5 Industrial、2/5 Interleaved、Codabar、Code 32、Code 39、Code 93、Code 128、EAN-8、EAN-13（+ Add-On 2/5）、GS1-128、GS1 DataBar 系列、MSI、PharmaCode、UPC-A、UPC-E（+ Add-On）。
11.2 二维码 / Data Matrix#
| 算子 | 说明 |
|---|---|
create_data_code_2d_model (SymbolType, GenParamName, GenParamValue, DataCodeHandle) |
SymbolType：'QR Code' / 'Data Matrix ECC 200' / 'Micro QR Code' / 'PDF417' / 'Aztec Code'（+ 三种 'GS1 …'） |
find_data_code_2d (Image, SymbolXLDs, DataCodeHandle, GenParamName, GenParamValue, ResultHandles, DecodedDataStrings) |
输出是 XLD，不是 Region |
set_data_code_2d_param (Handle, 'default_parameters', 'enhanced_recognition') |
提识别率（更慢，专治难读的码） |
clear_data_code_2d_model (Handle) |
释放 |
11.3 文字 OCR#
| 算子 | 说明 |
|---|---|
create_text_model_reader (Mode, OCRClassifier, TextModel) |
Mode = 'auto'（默认，必须给分类器）/ 'manual'（忽略分类器，须自己设字符高宽） |
find_text (Image, TextModel, TextResultID) |
建议先 reduce_domain 圈 ROI |
get_text_result (TextResultID, 'class', ResultValue) |
识别出的字符串 |
get_text_object (Characters, TextResultID, 'all_lines') |
识别到的字符区域 |
set_text_model_param (TextModel, 'min_char_height', 'auto' \| 数值) |
限制最小字符高度，滤掉小噪声 |
clear_text_result (TextResultID) / clear_text_model (TextModel) |
释放 |
分类器命名规律：<字体>_<字符集>_Rej.<后缀>，如 Universal_0-9A-Z_Rej.occ、Pharma_0-9A-Z_Rej.omc。
.occ = CNN，.omc = MLP；_Rej = 带拒绝类（工程推荐）。
四条最容易踩的
① 'orientation' 单位是度（−180~180，逆时针为正，读取方向垂直于条纹）—— 全库独一份，用前要 rad()。
② 条码期望浅底深码，深底浅码先 invert_image。
③ 条码出 Region，二维码出 XLD，area_center 不能直接吃 XLD。
④ 路径或内容含中文，先 set_system ('filename_encoding', 'utf8')。
11.4 判定与工程化#
| 判据 | 写法 | 适合 |
|---|---|---|
| 计数 | count_obj (Objs, Number) 后比数值 |
点个数、缺件 |
| 尺寸 | abs (实测 − 标称) < 容差 |
长宽高、直径 |
| 面积 | abs (Area − AreaRef) < 容差 或 Diff/Area < 百分比 |
缺料 / 毛刺 |
| 交叉验证 | 两条独立链路结果是否相等 | 条码 vs OCR |
| 存在性 | \|结果元组\| > 0 |
读没读到码、找没找到 |
三条工程铁律
① 不要对浮点用 ==：area_center / 测量结果都是浮点，判等几乎必然失败，必须给容差，且容差要小于最小待检缺陷。
② 取结果前先判空：find_bar_code / find_data_code_2d / find_shape_model 空手而归时返回空元组，直接 Parameter[0] 会报错。
③ 循环里别用首图的变量：read_image (Image, Files[0]) 之后再进循环 read_image (Image1, Files[Index])，
一旦循环体里漏改成 Image1，现象就是"图在变、结果不变"。详见 [[17 综合实战 五个作业题与判定逻辑]]。
十二、语言与元组#
| 语法 / 算子 | 说明 |
|---|---|
A := 1 |
赋值（:=），比较用 = |
* 注释 |
整行注释，* 必须是行首第一个非空白字符 |
\ |
续行符 |
[a, b, c] |
构造元组 |
\|Tuple\| |
求元组长度：num := \|Area\| |
Tuple[i] |
取元素，下标从 0 开始 |
tuple_length (Tuple, Length) |
元组长度（函数形式） |
'text' + num |
字符串拼接（数字自动转字符串） |
Value$'3.2f' |
格式化输出（保留 2 位小数） |
deg (Rad) / rad (Deg) |
弧度 ↔ 角度 |
abs / max2 / min2 / sqrt / sin / cos |
常用数学函数 |
for I := 0 to N-1 by 1 ... endfor |
循环 |
if ... elseif ... else ... endif |
判断 |
while ... endwhile |
循环 |
stop () |
断点暂停（配合 F6 单步） |
set_system ('no_object_result', ...) |
控制空结果行为 |
set_system ('empty_region_result', ...) |
控制空区域行为 |
try ... catch ... endtry |
异常处理 |
本库代码块里的\"行尾注释\"只是为了排版
官方文档原文：a comment is marked by entering an asterisk (*) as first non-whitespace character。
也就是说 HDevelop 的注释必须独占一行，threshold (…) * 说明 这种写法直接粘进 HDevelop 会报语法错误。
本库不少代码块为了对齐美观把注释写在了行尾（含本页），照抄运行前请把注释挪到单独一行。
新写的笔记（如 [[13 形态学调整 结构元半径标定]]）已统一改为注释独占一行。
十三、最常用的"黄金八行"#
八成以上的 Blob 任务都从这八行开始：
read_image (Image, 'xxx')
get_image_size (Image, Width, Height)
dev_close_window ()
dev_open_window (0, 0, Width, Height, 'black', WindowHandle)
dev_display (Image)
threshold (Image, Region, MinGray, MaxGray)
connection (Region, ConnectedRegions)
select_shape (ConnectedRegions, SelectedRegions, 'area', 'and', MinArea, MaxArea)
dev_clear_window ()
dev_display (Image)
dev_display (SelectedRegions)
返回：Halcon 学习地图