Reference Manual HALCON/C

HALCON Version 6.0
MVTec Software GmbH
HALCON/C
Reference Manual

This manual describes the operators of the image analysis system HALCON, version 6.0, in C syntax. It was
generated on November 15, 2000.
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in
any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written
permission of the publisher.
Copyright c­ 1997-2000 by MVTec Software GmbH, München, Germany
MVTec Software GmbH
More information about HALCON can be found at:
http://www.mvtec.com

Contents
1 Classification 1
clear sampset ............................................ 1
close all class box .......................................... 1
close class box ........................................... 2
create class box ........................................... 2
descript class box .......................................... 2
T enquire class box ......................................... 3
T enquire reject class box ..................................... 4
get class box param ......................................... 4
T learn class box .......................................... 5
learn sampset box .......................................... 6
read class box ............................................ 7
read sampset ............................................. 7
set class box param ......................................... 8
test sampset box ........................................... 9
write class box ........................................... 9
2 File 11
2.1 Images................................................ 11
read image .............................................. 11
T read image ............................................ 11
read sequence ............................................ 12
write image ............................................. 14
T write image ............................................ 14
2.2 Misc ................................................. 15
file exists ............................................... 15
T read world file .......................................... 15
2.3 Region................................................ 16
read region .............................................. 16
write region ............................................. 17
2.4 Text ................................................. 17
close all files ............................................. 17
close file ............................................... 18
fnew line ............................................... 18
fread char .............................................. 19
fread string .............................................. 19
fwrite string ............................................. 20
T fwrite string ............................................ 20
open file ............................................... 21
2.5 Tuple................................................. 22
read tuple .............................................. 22
T read tuple ............................................. 22
write tuple .............................................. 23
T write tuple ............................................. 23
2.6 XLD ................................................. 23
read contour xld arc info ...................................... 23
i

ii
Contents
read polygon xld arc info ...................................... 24
write contour xld arc info ...................................... 25
write polygon xld arc info ..................................... 25
3 Filter 27
3.1 Affine-Transformations ....................................... 27
T affine trans image ......................................... 27
mirror image ............................................. 29
polar trans image .......................................... 29
rotate image ............................................. 30
zoom image factor ......................................... 31
zoom image size ........................................... 32
3.2 Arithmetic.............................................. 33
abs image .............................................. 33
add image .............................................. 33
div image .............................................. 35
invert image ............................................. 36
max image .............................................. 36
min image .............................................. 37
mult image .............................................. 38
scale image ............................................. 39
sub image .............................................. 40
3.3 Bit .................................................. 41
bit and ................................................ 41
bit lshift ............................................... 42
bit mask ............................................... 42
bit not ................................................ 43
bit or ................................................. 44
bit rshift ............................................... 44
bit slice ............................................... 45
bit xor ................................................ 46
3.4 Color................................................. 47
rgb1 to gray ............................................. 47
rgb3 to gray ............................................. 47
trans from rgb ............................................ 48
trans to rgb ............................................. 52
3.5 Edges................................................. 55
close edges .............................................. 55
close edges length .......................................... 56
derivate gauss ............................................ 57
diff of gauss ............................................. 59
edges image ............................................. 60
edges sub pix ............................................ 63
frei amp ............................................... 65
frei dir ................................................ 66
highpass image ........................................... 67
T info edges ............................................. 68
kirsch amp .............................................. 69
kirsch dir ............................................... 70
laplace ................................................ 72
laplace of gauss ........................................... 73
prewitt amp ............................................. 74
prewitt dir .............................................. 75
roberts ................................................ 76
robinson amp ............................................ 77
robinson dir ............................................. 78
sobel amp .............................................. 79
sobel dir ............................................... 80
HALCON/C Reference Manual / 2000-11-15

Contents
iii
3.6 Enhancement............................................. 82
emphasize .............................................. 82
equ histo image ........................................... 83
illuminate .............................................. 84
scale image max ........................................... 85
3.7 FFT ................................................. 85
convol fft ............................................... 85
convol gabor ............................................. 86
energy gabor ............................................. 87
fft generic .............................................. 88
fft image ............................................... 89
fft image inv ............................................. 90
gen bandfilter ............................................ 91
gen bandpass ............................................ 92
gen filter mask ............................................ 93
gen gabor .............................................. 94
gen highpass ............................................. 96
gen lowpass ............................................. 96
gen sin bandpass .......................................... 97
gen std bandpass .......................................... 98
phase deg .............................................. 99
phase rad ............................................... 100
power byte .............................................. 100
power ln ............................................... 101
power real .............................................. 102
3.8 Lines................................................. 103
bandpass image ........................................... 103
lines facet .............................................. 103
lines gauss .............................................. 105
3.9 Match ................................................ 107
adapt template ............................................ 107
best match .............................................. 108
T best match ............................................. 108
best match mg ............................................ 109
best match pre mg .......................................... 110
best match rot ............................................ 111
T best match rot ........................................... 111
best match rot mg .......................................... 113
T best match rot mg ........................................ 113
clear template ............................................ 114
corner response ........................................... 114
create template ............................................ 115
create template rot .......................................... 117
exhaustive match .......................................... 118
exhaustive match mg ........................................ 120
fast match .............................................. 121
fast match mg ............................................ 122
T fast match mg ........................................... 122
fill dvf ................................................ 123
gen gauss pyramid ......................................... 124
monotony .............................................. 125
optical flow match .......................................... 126
T optical flow match ........................................ 126
read template ............................................ 127
set offset template .......................................... 128
set reference template ........................................ 128
write template ............................................ 129
3.10 Misc ................................................. 129
HALCON 6.0

iv
Contents
convol image ............................................ 129
expand domain gray ......................................... 130
gray inside .............................................. 131
gray skeleton ............................................ 132
T lut trans .............................................. 133
T principal comp .......................................... 134
symmetry .............................................. 134
topographic sketch .......................................... 135
3.11 Noise................................................. 136
T add noise distribution ....................................... 136
add noise white ........................................... 137
T gauss distribution ......................................... 138
T noise distribution mean ...................................... 138
T sp distribution ........................................... 139
3.12 Smoothing.............................................. 140
anisotrope diff ............................................ 140
eliminate min max ......................................... 141
eliminate sp ............................................. 143
fill interlace ............................................. 144
gauss image ............................................. 145
T info smooth ............................................ 146
mean image ............................................. 147
mean n ................................................ 148
mean sp ............................................... 148
median image ............................................ 149
median separate ........................................... 151
median weighted .......................................... 152
midrange image ........................................... 153
rank image .............................................. 154
sigma image ............................................. 155
smooth image ............................................ 156
trimmed mean ............................................ 158
3.13 Texture................................................ 159
deviation image ........................................... 159
entropy image ............................................ 160
texture laws ............................................. 161
T texture laws ............................................ 161
3.14 Wiener-Filter . . . . . ........................................ 162
gen psf defocus ........................................... 162
gen psf motion ........................................... 163
simulate defocus ........................................... 165
simulate motion ........................................... 166
wiener filter ............................................. 167
wiener filter ni ............................................ 169
4 Graphics 173
4.1 Drawing ............................................... 173
drag region1 ............................................. 173
drag region2 ............................................. 174
drag region3 ............................................. 175
draw circle .............................................. 176
draw circle mod ........................................... 176
draw ellipse ............................................. 177
draw ellipse mod .......................................... 178
draw line ............................................... 180
draw line mod ............................................ 181
draw point .............................................. 182
draw point mod ........................................... 183
HALCON/C Reference Manual / 2000-11-15

Contents
v
draw polygon ............................................ 184
draw rectangle1 ........................................... 184
draw rectangle1 mod ........................................ 186
draw rectangle2 ........................................... 187
draw rectangle2 mod ........................................ 188
draw region ............................................. 189
4.2 Gnuplot ............................................... 190
gnuplot close ............................................ 190
gnuplot open file .......................................... 190
gnuplot open pipe .......................................... 191
T gnuplot plot ctrl .......................................... 191
T gnuplot plot funct 1d ....................................... 192
gnuplot plot image ......................................... 192
4.3 LUT ................................................. 193
disp lut ................................................ 193
draw lut ............................................... 194
get fixed lut ............................................. 195
T get lut ............................................... 196
get lut style ............................................. 196
T query lut .............................................. 197
set fixed lut ............................................. 197
set lut ................................................ 198
T set lut ............................................... 198
set lut style ............................................. 200
write lut ............................................... 201
4.4 Mouse ................................................ 202
get mbutton ............................................. 202
get mposition ............................................ 203
get mshape .............................................. 203
T query mshape ........................................... 204
set mshape .............................................. 204
4.5 Output ................................................ 205
disp arc ............................................... 205
T disp arc .............................................. 205
disp arrow .............................................. 206
T disp arrow ............................................. 206
disp channel ............................................. 208
T disp channel ............................................ 208
disp circle .............................................. 209
T disp circle ............................................. 209
disp color .............................................. 210
T disp distribution .......................................... 210
disp ellipse .............................................. 211
T disp ellipse ............................................ 211
disp image .............................................. 213
disp line ............................................... 214
T disp line .............................................. 214
disp obj ............................................... 215
T disp polygon ........................................... 216
disp rectangle1 ............................................ 217
T disp rectangle1 .......................................... 217
disp rectangle2 ............................................ 219
T disp rectangle2 .......................................... 219
disp region .............................................. 220
disp xld ............................................... 221
4.6 Parameters.............................................. 221
get comprise ............................................. 221
get draw ............................................... 222
HALCON 6.0

vi
Contents
get fix ................................................ 222
T get hsi ............................................... 223
get icon ............................................... 223
get insert ............................................... 224
get line approx ........................................... 225
T get line style ........................................... 225
get line width ............................................ 225
T get paint .............................................. 226
get part ................................................ 226
get part style ............................................. 227
T get pixel .............................................. 228
T get rgb ............................................... 228
get shape ............................................... 229
T query all colors .......................................... 229
T query color ............................................ 230
T query colored ........................................... 231
T query gray ............................................. 231
T query insert ............................................ 232
query line width ........................................... 232
T query paint ............................................ 233
T query shape ............................................ 233
set color ............................................... 234
T set color .............................................. 234
set colored .............................................. 235
set comprise ............................................. 236
set draw ............................................... 237
set fix ................................................ 237
set gray ............................................... 238
T set gray .............................................. 238
T set hsi ............................................... 239
set icon ................................................ 240
set insert ............................................... 241
set line approx ............................................ 242
T set line style ............................................ 242
set line width ............................................ 243
T set paint .............................................. 244
set part ................................................ 248
set part style ............................................. 249
T set pixel .............................................. 250
T set rgb ............................................... 251
set shape ............................................... 252
4.7 Text ................................................. 253
get font ................................................ 253
get string extents .......................................... 253
T get string extents ......................................... 253
get tposition ............................................. 254
get tshape .............................................. 255
new line ............................................... 255
T query font ............................................. 256
T query tshape ............................................ 257
read char ............................................... 257
read string .............................................. 258
set font ................................................ 259
set tposition ............................................. 260
set tshape .............................................. 260
T write string ............................................ 261
4.8 Window ............................................... 262
clear rectangle ............................................ 262
T clear rectangle ........................................... 262
HALCON/C Reference Manual / 2000-11-15

Contents
vii
clear window ............................................ 263
close window ............................................ 263
copy rectangle ............................................ 264
T copy rectangle ........................................... 264
dump window ............................................ 266
T dump window ........................................... 266
get window extents ......................................... 267
get window pointer3 ........................................ 268
get window type ........................................... 268
move rectangle ........................................... 269
T move rectangle .......................................... 269
new extern window ......................................... 271
open textwindow .......................................... 273
open window ............................................ 277
T query window type ........................................ 280
set window attr ........................................... 280
set window dc ............................................ 281
set window extents ......................................... 282
set window type ........................................... 283
slide image .............................................. 284
5 Image 285
5.1 Channel ............................................... 285
access channel ............................................ 285
append channel ........................................... 286
channels to image .......................................... 286
compose2 .............................................. 286
compose3 .............................................. 287
compose4 .............................................. 287
compose5 .............................................. 288
compose6 .............................................. 289
compose7 .............................................. 289
count channels ............................................ 290
T count channels .......................................... 290
decompose2 ............................................. 290
decompose3 ............................................. 291
decompose4 ............................................. 292
decompose5 ............................................. 292
decompose6 ............................................. 293
decompose7 ............................................. 293
image to channels .......................................... 294
5.2 Creation ............................................... 295
copy image ............................................. 295
gen image1 ............................................. 295
gen image1 extern .......................................... 296
gen image1 rect ........................................... 298
gen image3 ............................................. 299
gen image const ........................................... 301
gen image gray ramp ........................................ 302
gen image proto ........................................... 303
gen image surface second order .................................. 304
get image time ............................................ 306
region to bin ............................................. 306
region to label ............................................ 307
region to mean ........................................... 308
5.3 Domain ............................................... 309
add channels ............................................. 309
change domain ............................................ 310
full domain ............................................. 310
HALCON 6.0

viii
Contents
get domain .............................................. 311
rectangle1 domain .......................................... 311
reduce domain ............................................ 312
5.4 Features ............................................... 313
area center gray ........................................... 313
T area center gray .......................................... 313
cooc feature image ......................................... 314
T cooc feature image ........................................ 314
cooc feature matrix ......................................... 315
elliptic axis gray ........................................... 316
T elliptic axis gray ......................................... 316
entropy gray ............................................. 317
T entropy gray ............................................ 317
fit surface first order ........................................ 318
T fit surface first order ....................................... 318
fit surface second order ....................................... 319
T fit surface second order ...................................... 319
fuzzy entropy ............................................ 320
T fuzzy entropy ........................................... 320
fuzzy perimeter ........................................... 321
T fuzzy perimeter .......................................... 321
gen cooc matrix ........................................... 322
T gray histo ............................................. 323
T gray projections .......................................... 324
histo 2dim .............................................. 325
intensity ............................................... 326
T intensity .............................................. 326
min max gray ............................................ 326
T min max gray ........................................... 326
moments gray plane ......................................... 328
T moments gray plane ....................................... 328
plane deviation ........................................... 329
T plane deviation .......................................... 329
select gray .............................................. 330
T select gray ............................................. 330
T shape histo all ........................................... 331
T shape histo point ......................................... 332
5.5 Format................................................ 333
change format ............................................ 333
crop domain ............................................. 334
crop part ............................................... 334
crop rectangle1 ........................................... 335
tile channels ............................................. 336
tile images .............................................. 337
T tile images offset ......................................... 338
5.6 Framegrabber ............................................ 340
close all framegrabbers ....................................... 340
close framegrabber ......................................... 340
T get framegrabber lut ....................................... 341
get framegrabber param ....................................... 341
T get framegrabber param ..................................... 341
grab image .............................................. 342
grab image async .......................................... 343
grab image start ........................................... 344
grab region .............................................. 345
grab region async .......................................... 346
info framegrabber .......................................... 346
T info framegrabber ......................................... 346
HALCON/C Reference Manual / 2000-11-15

Contents
ix
open framegrabber .......................................... 348
T open framegrabber ........................................ 348
T set framegrabber lut ....................................... 350
set framegrabber param ....................................... 351
T set framegrabber param ...................................... 351
5.7 Manipulation............................................. 351
get grayval .............................................. 351
T get grayval ............................................ 351
get image pointer1 ......................................... 352
get image pointer1 rect ....................................... 353
get image pointer3 ......................................... 354
paint gray .............................................. 355
paint region ............................................. 356
set grayval .............................................. 357
T set grayval ............................................. 357
5.8 Type-Conversion........................................... 358
complex to real ........................................... 358
convert image type ......................................... 358
dvf to int1 .............................................. 359
int1 to dvf .............................................. 359
real to complex ........................................... 360
6 Lines 361
6.1 Access . ............................................... 361
T approx chain ........................................... 361
T approx chain simple ....................................... 364
6.2 Features ............................................... 366
line orientation ............................................ 366
T line orientation .......................................... 366
line position ............................................. 367
T line position ............................................ 367
T partition lines ........................................... 368
T select lines ............................................ 369
T select lines longest ........................................ 370
7 Morphology 373
7.1 Gray-Values ............................................. 373
dual rank ............................................... 373
gen disc se .............................................. 374
gray bothat .............................................. 375
gray closing ............................................. 376
gray dilation ............................................. 377
gray dilation rect .......................................... 377
gray erosion ............................................. 378
gray erosion rect ........................................... 379
gray opening ............................................. 379
gray range rect ........................................... 380
gray tophat .............................................. 381
read gray se ............................................. 381
7.2 Region................................................ 382
bottom hat .............................................. 382
boundary ............................................... 383
closing ................................................ 384
closing circle ............................................ 385
closing golay ............................................ 387
closing rectangle1 .......................................... 388
dilation1 ............................................... 389
dilation2 ............................................... 390
HALCON 6.0

x
Contents
dilation circle ............................................ 391
dilation golay ............................................ 392
dilation rectangle1 .......................................... 394
dilation seq ............................................. 395
erosion1 ............................................... 396
erosion2 ............................................... 397
erosion circle ............................................ 399
erosion golay ............................................ 400
erosion rectangle1 .......................................... 401
erosion seq .............................................. 402
fitting ................................................. 403
gen struct elements ......................................... 404
golay elements ............................................ 405
hit or miss .............................................. 408
hit or miss golay .......................................... 409
hit or miss seq ............................................ 410
minkowski add1 ........................................... 411
minkowski add2 ........................................... 412
minkowski sub1 ........................................... 414
minkowski sub2 ........................................... 415
morph hat .............................................. 416
morph skeleton ........................................... 417
morph skiz .............................................. 418
opening ............................................... 419
opening circle ............................................ 420
opening golay ............................................ 422
opening rectangle1 ......................................... 423
opening seg ............................................. 424
pruning ................................................ 425
thickening .............................................. 426
thickening golay ........................................... 427
thickening seq ............................................ 428
thinning ............................................... 429
thinning golay ............................................ 430
thinning seq ............................................. 431
top hat ................................................ 433
8 Object 435
8.1 Information ............................................. 435
count obj ............................................... 435
get channel info ........................................... 435
T get channel info .......................................... 435
get obj class ............................................. 436
T get obj class ............................................ 436
test equal obj ............................................ 437
test equal region ........................................... 438
test obj def .............................................. 438
8.2 Manipulation............................................. 439
clear obj ............................................... 439
concat obj .............................................. 440
copy obj ............................................... 441
gen empty obj ............................................ 442
T integer to obj ........................................... 442
T obj to integer ........................................... 443
select obj ............................................... 443
9 Regions 445
9.1 Access . ............................................... 445
T get region chain .......................................... 445
HALCON/C Reference Manual / 2000-11-15

Contents
xi
T get region contour ........................................ 446
T get region convex ......................................... 446
T get region points ......................................... 447
T get region polygon ........................................ 448
T get region runs .......................................... 449
9.2 Affine-Transformations ....................................... 449
T affine trans region ......................................... 449
mirror region ............................................ 450
move region ............................................. 451
transpose region ........................................... 452
zoom region ............................................. 453
9.3 Creation ............................................... 454
gen checker region ......................................... 454
gen circle .............................................. 455
T gen circle ............................................. 455
gen ellipse .............................................. 457
T gen ellipse ............................................. 457
gen empty region .......................................... 458
gen grid region ........................................... 459
gen random region ......................................... 460
gen random regions ......................................... 461
gen rectangle1 ............................................ 463
T gen rectangle1 ........................................... 463
gen rectangle2 ............................................ 464
T gen rectangle2 ........................................... 464
T gen region histo .......................................... 465
gen region hline ........................................... 466
T gen region hline .......................................... 466
gen region line ........................................... 467
T gen region line .......................................... 467
gen region points .......................................... 468
T gen region points ......................................... 468
T gen region polygon ........................................ 469
T gen region polygon filled ..................................... 470
gen region runs ........................................... 471
T gen region runs .......................................... 471
label to region ............................................ 472
9.4 Features ............................................... 473
area center .............................................. 473
T area center ............................................. 473
circularity .............................................. 474
T circularity ............................................. 474
compactness ............................................. 475
T compactness ............................................ 475
connect and holes .......................................... 475
T connect and holes ......................................... 475
contlength .............................................. 476
T contlength ............................................. 476
convexity ............................................... 477
T convexity ............................................. 477
diameter region ........................................... 478
T diameter region .......................................... 478
eccentricity .............................................. 479
T eccentricity ............................................ 479
elliptic axis ............................................. 480
T elliptic axis ............................................ 480
euler number ............................................. 481
T euler number ........................................... 481
HALCON 6.0

xii
Contents
T find neighbors ........................................... 482
get region index ........................................... 483
T get region index .......................................... 483
T get region thickness ........................................ 483
hamming distance .......................................... 484
T hamming distance ......................................... 484
hamming distance norm ....................................... 485
T hamming distance norm ..................................... 485
inner circle .............................................. 486
T inner circle ............................................ 486
moments region 2nd ......................................... 487
T moments region 2nd ....................................... 487
moments region 2nd invar ..................................... 488
T moments region 2nd invar .................................... 488
moments region 2nd rel invar .................................... 489
T moments region 2nd rel invar .................................. 489
moments region 3rd ......................................... 490
T moments region 3rd ....................................... 490
moments region 3rd invar ...................................... 491
T moments region 3rd invar .................................... 491
moments region central ....................................... 492
T moments region central ...................................... 492
moments region central invar .................................... 493
T moments region central invar .................................. 493
orientation region .......................................... 494
T orientation region ......................................... 494
roundness .............................................. 495
T roundness ............................................. 495
T runlength distribution ....................................... 496
runlength features .......................................... 497
T runlength features ......................................... 497
select region point .......................................... 498
T select region spatial ........................................ 499
select shape ............................................. 500
T select shape ............................................ 500
select shape proto .......................................... 503
T select shape proto ......................................... 503
select shape std ........................................... 504
smallest circle ............................................ 505
T smallest circle ........................................... 505
smallest rectangle1 ......................................... 506
T smallest rectangle1 ........................................ 506
smallest rectangle2 ......................................... 507
T smallest rectangle2 ........................................ 507
T spatial relation .......................................... 508
test region point ........................................... 509
9.5 Sets.................................................. 510
complement ............................................. 510
difference .............................................. 511
intersection .............................................. 512
union1 ................................................ 513
union2 ................................................ 513
9.6 Transformation............................................ 514
background seg ........................................... 514
clip region .............................................. 515
clip region rel ............................................ 516
connection .............................................. 517
crop domain rel ........................................... 518
distance transform .......................................... 519
HALCON/C Reference Manual / 2000-11-15

Contents
xiii
eliminate runs ............................................ 520
expand region ............................................ 521
fill up ................................................ 522
fill up shape ............................................. 523
hamming change region ....................................... 524
interjacent .............................................. 525
junctions skeleton .......................................... 526
merge regions line scan ....................................... 527
partition dynamic .......................................... 528
partition rectangle .......................................... 528
rank region .............................................. 529
remove noise region ......................................... 530
shape trans .............................................. 531
skeleton ............................................... 532
sort region .............................................. 533
T split skeleton lines ........................................ 533
split skeleton region ......................................... 535
10 Segmentation 537
auto threshold ............................................ 537
bin threshold ............................................. 538
char threshold ............................................ 538
T char threshold ........................................... 538
check difference ........................................... 539
class 2dim sup ............................................ 541
class 2dim unsup .......................................... 543
class ndim box ........................................... 544
class ndim norm ........................................... 545
T class ndim norm ......................................... 545
T detect edge segments ....................................... 546
dual threshold ............................................ 548
dyn threshold ............................................ 549
expand gray ............................................. 551
T expand gray ............................................ 551
expand gray ref ........................................... 552
T expand gray ref .......................................... 552
expand line ............................................. 554
fast threshold ............................................ 555
T histo to thresh ........................................... 556
hysteresis threshold ......................................... 557
learn ndim box ........................................... 558
T learn ndim norm ......................................... 559
local max .............................................. 560
nonmax suppression amp ...................................... 561
nonmax suppression dir ....................................... 562
plateaus ............................................... 563
plateaus center ............................................ 563
pouring ................................................ 564
regiongrowing ............................................ 566
regiongrowing mean ......................................... 567
T regiongrowing mean ....................................... 567
regiongrowing n ........................................... 568
threshold ............................................... 573
T threshold .............................................. 573
threshold sub pix .......................................... 574
watersheds .............................................. 575
zero crossing ............................................. 575
zero crossing sub pix ........................................ 576
HALCON 6.0

xiv
Contents
11 System 579
11.1 Database............................................... 579
count relation ............................................ 579
T get modules ............................................ 580
reset obj db ............................................. 581
11.2 Error-Handling............................................ 582
T get check ............................................. 582
get error text ............................................. 582
get spy ................................................ 583
T query spy ............................................. 584
set check ............................................... 584
T set check ............................................. 584
set spy ................................................ 585
11.3 Information ............................................. 587
disp info ............................................... 587
T get chapter info .......................................... 588
T get keywords ........................................... 589
T get operator info ......................................... 589
T get operator name ......................................... 590
T get param info .......................................... 591
T get param names ......................................... 593
get param num ........................................... 593
T get param types .......................................... 594
T query operator info ........................................ 595
T query param info ......................................... 595
T search operator .......................................... 596
11.4 Operating-System .......................................... 596
count seconds ............................................ 596
system call .............................................. 597
wait seconds ............................................. 597
11.5 Parallelization ............................................ 598
check par hw potential ....................................... 598
load par knowledge ......................................... 599
store par knowledge ......................................... 600
11.6 Parameters.............................................. 600
get system .............................................. 600
T get system ............................................. 600
set system .............................................. 603
T set system ............................................. 603
11.7 Serial................................................. 608
clear serial .............................................. 608
close all serials ........................................... 608
close serial .............................................. 609
get serial param ........................................... 609
open serial .............................................. 610
read serial .............................................. 610
T read serial ............................................. 610
set serial param ........................................... 611
write serial .............................................. 612
T write serial ............................................ 612
11.8 Sockets................................................ 613
close socket ............................................. 613
get next socket data type ...................................... 613
open socket accept ......................................... 614
open socket connect ......................................... 615
receive image ............................................ 616
receive region ............................................ 616
receive tuple ............................................. 617
HALCON/C Reference Manual / 2000-11-15

Contents
xv
receive xld .............................................. 617
send image .............................................. 617
send region ............................................. 618
send tuple .............................................. 618
send xld ............................................... 619
socket accept connect ........................................ 620
12 Tools 621
12.1 Affine-Transformations ....................................... 621
T affine trans point 2d ....................................... 621
T affine trans point 3d ....................................... 622
T dvf to hom mat2d ......................................... 623
T hom mat2d compose ....................................... 623
T hom mat2d identity ........................................ 624
T hom mat2d invert ......................................... 624
T hom mat2d rotate ......................................... 625
T hom mat2d scale ......................................... 626
T hom mat2d slant ......................................... 627
T hom mat2d to affine par ..................................... 628
T hom mat2d translate ....................................... 629
T hom mat3d compose ....................................... 629
T hom mat3d identity ........................................ 631
T hom mat3d invert ......................................... 631
T hom mat3d rotate ......................................... 632
T hom mat3d scale ......................................... 634
T hom mat3d translate ....................................... 635
T vector angle to rigid ....................................... 637
T vector to hom mat2d ....................................... 638
T vector to rigid ........................................... 639
T vector to similarity ........................................ 639
12.2 Background-Estimator ........................................ 640
close all bg esti ........................................... 640
close bg esti ............................................. 640
create bg esti ............................................ 641
get bg esti params .......................................... 644
give bg esti ............................................. 645
run bg esti .............................................. 646
set bg esti params .......................................... 647
update bg esti ............................................ 649
12.3 Barcode ............................................... 650
T decode 1d bar code ........................................ 650
T decode 2d bar code ........................................ 651
T discrete 1d bar code ....................................... 652
T find 1d bar code ......................................... 653
T find 1d bar code region ...................................... 657
T find 2d bar code ......................................... 658
T gen 1d bar code descr ...................................... 661
T gen 1d bar code descr gen .................................... 662
T gen 2d bar code descr ...................................... 663
T get 1d bar code .......................................... 665
T get 2d bar code .......................................... 666
T get 2d bar code pos ........................................ 670
12.4 Calibration.............................................. 672
T caltab points ............................................ 672
T camera calibration ........................................ 673
T change radial distortion cam par ................................. 678
T change radial distortion contours xld .............................. 679
T change radial distortion image .................................. 680
HALCON 6.0

xvi
Contents
T contour to world plane xld .................................... 680
T convert pose type ......................................... 681
create caltab ............................................. 682
T create pose ............................................ 685
T disp caltab ............................................. 691
find caltab .............................................. 692
T find marks and pose ....................................... 694
T get line of sight .......................................... 696
T get pose type ........................................... 697
T hand eye calibration ....................................... 698
T hom mat3d to pose ........................................ 704
T image points to world plane ................................... 705
T pose to hom mat3d ........................................ 706
T project 3d point .......................................... 708
T read cam par ........................................... 709
T read pose ............................................. 711
T set origin pose .......................................... 712
T sim caltab ............................................. 712
T write cam par ........................................... 714
T write pose ............................................. 716
12.5 Fourier-Descriptor.......................................... 718
T abs invar fourier coeff ...................................... 718
T fourier 1dim ............................................ 719
T fourier 1dim inv ......................................... 720
T invar fourier coeff ......................................... 721
T match fourier coeff ........................................ 722
T move contour orig ........................................ 723
T prep contour fourier ....................................... 723
12.6 Function ............................................... 724
T abs funct 1d ............................................ 724
T create funct 1d array ....................................... 724
T create funct 1d pairs ....................................... 725
T distance funct 1d ......................................... 725
T funct 1d to pairs ......................................... 726
T get pair funct 1d ......................................... 726
T integrate funct 1d ......................................... 727
T match funct 1d trans ....................................... 727
T negate funct 1d .......................................... 728
T num points funct 1d ....................................... 729
read funct 1d ............................................ 729
T read funct 1d ........................................... 729
T sample funct 1d .......................................... 730
T scale y funct 1d .......................................... 730
T smooth funct 1d gauss ...................................... 731
T smooth funct 1d mean ...................................... 731
T transform funct 1d ........................................ 732
T write funct 1d ........................................... 732
T x range funct 1d ......................................... 733
T y range funct 1d ......................................... 733
12.7 Geometry .............................................. 734
angle ll ................................................ 734
T angle ll .............................................. 734
angle lx ............................................... 735
T angle lx .............................................. 735
distance lr .............................................. 736
T distance lr ............................................. 736
distance pl .............................................. 737
T distance pl ............................................. 737
HALCON/C Reference Manual / 2000-11-15

Contents
xvii
distance pp .............................................. 738
T distance pp ............................................ 738
distance pr .............................................. 739
T distance pr ............................................. 739
distance ps .............................................. 740
T distance ps ............................................ 740
distance rr min ........................................... 741
T distance rr min .......................................... 741
distance rr min dil .......................................... 742
T distance rr min dil ........................................ 742
distance sl .............................................. 742
T distance sl ............................................. 742
distance sr .............................................. 744
T distance sr ............................................. 744
distance ss .............................................. 744
T distance ss ............................................. 744
get points ellipse .......................................... 746
T get points ellipse ......................................... 746
intersection ll ............................................ 747
T intersection ll ........................................... 747
projection pl ............................................. 748
T projection pl ............................................ 748
12.8 Hough . ............................................... 749
hough circle trans .......................................... 749
T hough circle trans ......................................... 749
hough circles ............................................ 749
T hough circles ........................................... 749
hough line trans ........................................... 750
T hough lines ............................................ 751
T select matching lines ....................................... 752
12.9 Kalman-Filter . . . . ........................................ 753
T filter kalman ............................................ 753
T read kalman ............................................ 757
T sensor kalman ........................................... 759
T update kalman ........................................... 760
12.10Matching............................................... 763
clear shape model .......................................... 763
create shape model ......................................... 763
T find shape model ......................................... 765
inspect shape model ......................................... 767
read shape model .......................................... 768
write shape model .......................................... 769
12.11 Measure ............................................... 769
close measure ............................................ 769
gen measure arc ........................................... 769
gen measure rectangle2 ....................................... 771
T measure pairs ........................................... 773
T measure pos ............................................ 775
T measure projection ........................................ 776
T measure thresh .......................................... 777
12.12OCR ................................................. 778
append ocr trainf .......................................... 778
T append ocr trainf ......................................... 778
close all ocrs ............................................. 780
close ocr ............................................... 780
T concat ocr trainf ......................................... 781
T create ocr class box ........................................ 781
do ocr multi ............................................. 784
HALCON 6.0

xviii
Contents
T do ocr multi ............................................ 784
T do ocr single ........................................... 785
T info ocr class box ......................................... 786
T ocr change char .......................................... 787
T ocr get features .......................................... 787
read ocr ............................................... 788
T read ocr trainf ........................................... 789
read ocr trainf names ........................................ 789
T read ocr trainf names ....................................... 789
read ocr trainf select ........................................ 790
T read ocr trainf select ....................................... 790
testd ocr class box .......................................... 790
T testd ocr class box ........................................ 790
traind ocr class box ......................................... 791
T traind ocr class box ........................................ 791
trainf ocr class box ......................................... 792
T trainf ocr class box ........................................ 792
write ocr ............................................... 793
write ocr trainf ........................................... 794
T write ocr trainf .......................................... 794
write ocr trainf image ........................................ 795
T write ocr trainf image ...................................... 795
12.13OCV................................................. 795
close all ocvs ............................................ 795
close ocv ............................................... 796
create ocv proj ............................................ 796
T create ocv proj .......................................... 796
do ocv simple ............................................ 797
T do ocv simple ........................................... 797
read ocv ............................................... 799
traind ocv proj ............................................ 799
T traind ocv proj .......................................... 799
write ocv ............................................... 800
12.14 Shape-from . . . . . ........................................ 801
depth from focus .......................................... 801
T depth from focus ......................................... 801
estimate al am ............................................ 802
T estimate al am .......................................... 802
estimate sl al lr ........................................... 802
T estimate sl al lr .......................................... 802
estimate sl al zc ........................................... 803
T estimate sl al zc .......................................... 803
estimate tilt lr ............................................ 804
T estimate tilt lr ........................................... 804
estimate tilt zc ............................................ 804
T estimate tilt zc .......................................... 804
T phot stereo ............................................ 804
select grayvalues from channels .................................. 805
sfs mod lr .............................................. 806
sfs orig lr .............................................. 807
sfs pentland ............................................. 808
shade height field .......................................... 810
13 Tuple 813
13.1 Arithmetic.............................................. 813
tuple abs ............................................... 813
T tuple abs .............................................. 813
tuple acos .............................................. 813
T tuple acos ............................................. 813
HALCON/C Reference Manual / 2000-11-15

Contents
xix
tuple add ............................................... 814
T tuple add ............................................. 814
tuple asin .............................................. 814
T tuple asin ............................................. 814
tuple atan .............................................. 815
T tuple atan ............................................. 815
tuple atan2 .............................................. 815
T tuple atan2 ............................................ 815
tuple cos ............................................... 816
T tuple cos .............................................. 816
tuple cosh .............................................. 816
T tuple cosh ............................................. 816
tuple div ............................................... 817
T tuple div .............................................. 817
tuple exp ............................................... 817
T tuple exp ............................................. 817
tuple fabs .............................................. 818
T tuple fabs ............................................. 818
tuple fmod .............................................. 818
T tuple fmod ............................................. 818
tuple ldexp .............................................. 818
T tuple ldexp ............................................ 818
tuple log ............................................... 819
T tuple log .............................................. 819
tuple log10 .............................................. 819
T tuple log10 ............................................ 819
tuple mult .............................................. 820
T tuple mult ............................................. 820
tuple neg ............................................... 820
T tuple neg ............................................. 820
tuple pow .............................................. 821
T tuple pow ............................................. 821
tuple rad ............................................... 821
T tuple rad .............................................. 821
tuple sin ............................................... 822
T tuple sin .............................................. 822
tuple sinh .............................................. 822
T tuple sinh ............................................. 822
tuple sqrt ............................................... 823
T tuple sqrt ............................................. 823
tuple sub ............................................... 823
T tuple sub ............................................. 823
tuple tan ............................................... 823
T tuple tan .............................................. 823
tuple tanh .............................................. 824
T tuple tanh ............................................. 824
13.2 Bit-Operations............................................ 824
tuple band .............................................. 824
T tuple band ............................................. 824
tuple bnot .............................................. 825
T tuple bnot ............................................. 825
tuple bor ............................................... 825
T tuple bor .............................................. 825
tuple bxor .............................................. 826
T tuple bxor ............................................. 826
tuple lsh ............................................... 826
T tuple lsh .............................................. 826
tuple rsh ............................................... 827
T tuple rsh .............................................. 827
HALCON 6.0

xx
Contents
13.3 Comparison ............................................. 828
tuple equal .............................................. 828
T tuple equal ............................................ 828
tuple greater ............................................. 828
T tuple greater ............................................ 828
tuple greater equal .......................................... 829
T tuple greater equal ........................................ 829
tuple less ............................................... 829
T tuple less ............................................. 829
tuple less equal ........................................... 830
T tuple less equal .......................................... 830
tuple not equal ............................................ 830
T tuple not equal .......................................... 830
13.4 Conversion.............................................. 831
tuple chr ............................................... 831
T tuple chr .............................................. 831
tuple chrt ............................................... 831
T tuple chrt ............................................. 831
tuple deg ............................................... 832
T tuple deg ............................................. 832
tuple number ............................................. 832
T tuple number ........................................... 832
tuple ord ............................................... 833
T tuple ord .............................................. 833
tuple ords .............................................. 833
T tuple ords ............................................. 833
tuple real ............................................... 834
T tuple real ............................................. 834
tuple round .............................................. 834
T tuple round ............................................ 834
tuple string .............................................. 835
T tuple string ............................................ 835
13.5 Creation ............................................... 836
tuple concat ............................................. 836
T tuple concat ............................................ 836
tuple gen const ........................................... 836
T tuple gen const .......................................... 836
13.6 Element-Order............................................ 837
tuple inverse ............................................. 837
T tuple inverse ............................................ 837
tuple sort ............................................... 837
T tuple sort ............................................. 837
tuple sort index ........................................... 838
T tuple sort index .......................................... 838
13.7 Features ............................................... 838
tuple ceil ............................................... 838
T tuple ceil ............................................. 838
tuple deviation ............................................ 839
T tuple deviation .......................................... 839
tuple floor .............................................. 839
T tuple floor ............................................. 839
tuple is number ........................................... 840
T tuple is number .......................................... 840
tuple length ............................................. 840
T tuple length ............................................ 840
tuple max .............................................. 840
T tuple max ............................................. 840
tuple mean .............................................. 841
HALCON/C Reference Manual / 2000-11-15

Contents
xxi
T tuple mean ............................................ 841
tuple min ............................................... 841
T tuple min ............................................. 841
tuple sum .............................................. 842
T tuple sum ............................................. 842
13.8 Logical-Operations ......................................... 842
tuple and ............................................... 842
T tuple and ............................................. 842
tuple not ............................................... 843
T tuple not .............................................. 843
tuple or ................................................ 843
T tuple or .............................................. 843
tuple xor ............................................... 844
T tuple xor .............................................. 844
13.9 Selection............................................... 844
tuple first n ............................................. 844
T tuple first n ............................................ 844
tuple last n .............................................. 845
T tuple last n ............................................ 845
tuple select .............................................. 845
T tuple select ............................................ 845
tuple select range .......................................... 846
T tuple select range ......................................... 846
tuple str bit select .......................................... 847
T tuple str bit select ......................................... 847
13.10String-Operators........................................... 847
tuple environment .......................................... 847
T tuple environment ......................................... 847
tuple split .............................................. 848
T tuple split ............................................. 848
tuple str first n ............................................ 848
T tuple str first n .......................................... 848
tuple str last n ............................................ 849
T tuple str last n ........................................... 849
tuple strchr .............................................. 849
T tuple strchr ............................................ 849
tuple strlen .............................................. 850
T tuple strlen ............................................ 850
tuple strrchr ............................................. 850
T tuple strrchr ............................................ 850
tuple strrstr .............................................. 851
T tuple strrstr ............................................ 851
tuple strstr .............................................. 852
T tuple strstr ............................................. 852
14 XLD 853
14.1 Access . ............................................... 853
T get contour xld .......................................... 853
T get lines xld ............................................ 853
T get parallels xld .......................................... 854
T get polygon xld .......................................... 855
14.2 Creation ............................................... 855
T gen contour polygon xld ..................................... 855
gen contour region xld ....................................... 856
gen contours skeleton xld ...................................... 857
gen ellipse contour xld ....................................... 858
T gen ellipse contour xld ...................................... 858
gen parallels xld ........................................... 859
HALCON 6.0

xxii
Contents
gen polygons xld .......................................... 860
mod parallels xld .......................................... 861
14.3 Features ............................................... 862
area center xld ............................................ 862
T area center xld .......................................... 862
contour point num xld ....................................... 863
dist ellipse contour xld ....................................... 863
T dist ellipse contour xld ...................................... 863
fit circle contour xld ........................................ 865
T fit circle contour xld ....................................... 865
fit ellipse contour xld ........................................ 867
T fit ellipse contour xld ....................................... 867
fit line contour xld ......................................... 869
T fit line contour xld ........................................ 869
T get contour angle xld ....................................... 871
T get contour attrib xld ....................................... 872
T get contour global attrib xld ................................... 872
T get regress params xld ...................................... 873
info parallels xld .......................................... 874
length xld .............................................. 875
T length xld ............................................. 875
local max contours xld ....................................... 875
max parallels xld .......................................... 876
moments any xld .......................................... 877
T moments any xld ......................................... 877
moments xld ............................................. 878
T moments xld ........................................... 878
T query contour attribs xld ..................................... 879
T query contour global attribs xld ................................. 879
select contours xld ......................................... 880
14.4 Transformation............................................ 881
add noise white contour xld .................................... 881
T affine trans contour xld ...................................... 882
T affine trans polygon xld ..................................... 883
clip contours xld ........................................... 883
combine roads xld .......................................... 884
gen parallel contour xld ....................................... 885
merge cont line scan xld ...................................... 886
regress contours xld ......................................... 887
segment contours xld ........................................ 888
smooth contours xld ......................................... 890
split contours xld .......................................... 890
T union straight contours histo xld ................................. 891
union straight contours xld ..................................... 892
HALCON/C Reference Manual / 2000-11-15

Chapter 1
Classification
clear sampset ( long SampKey )
Free memory of a data set.
clear sampset frees the memory which was used for training data set having read by read sampset. This
memory is only reusable in combination with read sampset.
Parameter
º SampKey (input control) ..........................................................featureset long
Number of the data set.
Result
clear sampset returns H MSG TRUE. An exception handling is raised if the key SampKey does not exist.
Parallelization Information
clear sampset is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T enquire class box, T learn class box, write class box
See Also
test sampset box, learn sampset box, read sampset
Tools
Module
close all class box ( )
Destroy all classificators.
close all class box deletes all classificators and frees the used memory space. All the trained data will be
lost.
Attention
Since all classificators are closed by close all class box all handles become invalid.
Result
If it is possible to close the classificators the operator close all class box returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
close all class box is local and processed completely exclusively without parallelization.
close class box
Tools
Alternatives
Module
1

2 CHAPTER 1. CLASSIFICATION
close class box ( long ClassifHandle )
Destroy the classificator.
close class box deletes the classificator and frees the used memory space. All the trained data will be lost.
For saving this trained data you should use write class box before.
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
Result
close class box returns H MSG TRUE.
Parallelization Information
close class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T enquire class box, T learn class box, write class box
See Also
create class box, T enquire class box, T learn class box
Tools
Module
create class box ( long *ClassifHandle )
Create a new classificator.
create class box creates a new adaptive classificator. All procedures which are explained in chapter classification
refer to such a initialized classificator (of type 2). See T learn class box for more details about the
functionality of the classificator.
Parameter
º ClassifHandle (output control) ................................................class box long *
Classificator’s handle number.
Result
create class box returns H MSG TRUE if the parameter is correct. An exception handling is raised if a
classificator with this name already exists or there is not enough memory.
Parallelization Information
create class box is local and processed completely exclusively without parallelization.
Possible Successor Functions
T learn class box, T enquire class box, write class box, close class box,
clear sampset
See Also
T learn class box, T enquire class box, close class box
Tools
Module
descript class box ( long ClassifHandle, long Dimensions )
Description of the classificator.
A classificator uses a set of hyper cuboids for every class. With these hyper cuboids it is attempted to get the array
attributes inside the class. descript class box returns for every class the expansion of every appropriate
cuboid from dimension 1 up to Dimensions (to ’standard output’).
HALCON/C Reference Manual / 2000-11-15

3
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º Dimensions (input control) .........................................................integer long
Highest dimension for output.
Default Value : 3
descript class box returns H MSG TRUE.
Result
Parallelization Information
descript class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T learn class box, set class box param
Possible Successor Functions
T enquire class box, T learn class box, write class box, close class box
See Also
create class box, T enquire class box, T learn class box, read class box,
write class box
Module
Tools
T enquire class box ( Htuple ClassifHandle, Htuple FeatureList,
Htuple *Class )
Classify a tuple of attributes.
FeatureList is a tuple of any floating point- or integer numbers (attributes) which has to be assigned to a class
with assistance of a previous trained (T learn class box) classificator. It is possible to specify attributes as
unknown by indicating the symbol ’£’ instead of a number. If you specify n values, then all following values, i.e.
the attributes n+1 until ’max’, are automatically supposed to be undefined.
See T learn class box for more details about the functionality of the classificator.
You may call the procedures T learn class box and T enquire class box alternately, so that it is possible
to classify already in the phase of learning. This means you could see when a satisfying behavior had been
reached.
Parameter
º ClassifHandle (input control) ...........................................class box Htuple . long
Classificator’s handle number.
º FeatureList (input control) ........................real-array Htuple . double / long / const char *
Array of attributes which has to be classified.
Default Value : 1.0
º Class (output control) .....................................................integer Htuple . long *
Number of the class to which the array of attributes had been assigned.
T enquire class box returns H MSG TRUE.
Result
Parallelization Information
T enquire class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T learn class box, set class box param
Possible Successor Functions
T learn class box, write class box, close class box
T enquire reject class box
Alternatives
HALCON 6.0

4 CHAPTER 1. CLASSIFICATION
See Also
test sampset box, T learn class box, learn sampset box
Tools
Module
T enquire reject class box ( Htuple ClassifHandle, Htuple FeatureList,
Htuple *Class )
Classify a tuple of attributes with rejection class.
FeatureList is a tuple of any floating point- or integer numbers (attributes) which has to be assigned to a class
with assistance of a previous trained (T learn class box) classificator. It is possible to specify attributes as
unknown by indicating the symbol ’£’ instead of a number. If you specify n values, then all following values, i.e.
the attributes n+1 until ’max’, are automatically supposed to be undefined.
If the array of attributes cannot be assigned to a class, i.e. the array does not reside inside of one of the hyper
boxes, then in contrary to T enquire class box not the next class is going to be returned, but the rejection
class -1 as a result is going to be passed.
See T learn class box for more details about the functionality of the classificator.
You may call the procedures T learn class box and T enquire class box alternately, so that it is possible
to classify already in the phase of learning. By this means you could see when a satisfying behavior had been
reached.
Parameter
º ClassifHandle (input control) ...........................................class box Htuple . long
Classificator’s handle number.
º FeatureList (input control) ........................real-array Htuple . double / long / const char *
Array of attributes which has to be classfied.
Default Value : 1.0
º Class (output control) .....................................................integer Htuple . long *
Number of the class, to which the array of attributes had been assigned or -1 for the rejection class.
Result
T enquire reject class box returns H MSG TRUE.
Parallelization Information
T enquire reject class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T learn class box, set class box param
Possible Successor Functions
T learn class box, write class box, close class box
T enquire class box
Alternatives
See Also
test sampset box, T learn class box, learn sampset box
Tools
Module
get class box param ( long ClassifHandle, const char *Flag,
double *Value )
Get information about the current parameter.
get class box param gets the parameter of the classificator. The meaning of the parameter is explained in
set class box param.
Default values:
’min samples for split’ = 80,
HALCON/C Reference Manual / 2000-11-15

5
’split error’ = 0.1,
’prop constant’ = 0.25
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º Flag (input control) ............................................................string const char *
Name of the system parameter.
Default Value : ’split error’
Value List : Flag ¾’split error’, ’prop constant’, ’used memory’, ’min samples for split’
º Value (output control) ...................................................number double * / long *
Value of the system parameter.
Result
get class box param returns H MSG TRUE. An exception handling is raised if Flag has been set with
wrong values.
Parallelization Information
get class box param is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T enquire class box, T learn class box, write class box
Possible Successor Functions
set class box param, T learn class box, T enquire class box, write class box,
close class box, clear sampset
create class box, set class box param
Tools
See Also
Module
T learn class box ( Htuple ClassifHandle, Htuple Features,
Htuple Class )
Train the classificator.
Features is a tuple of any floating point numbers or integers (attributes) which has to be assigned to the class
Class. This class is specified by an integer. You may use procedure T enquire class box later to find the
most probable class for any array (=tupel). The algorithm tries to describe the set of arrays of one class by hyper
cuboids in the feature space. On demand you may even create several cuboids per class. Hence it is possible to
learn disjunct concepts, too. I.e such concepts which split in several ”‘cluster”’ of points in the feature space. The
data structure is hidden to the user and only accessible with such procedures which are described in this chapter.
It is possible to specify attributes as unknown by indicating the symbol ’£’ instead of a number. If you specify n
values, then all following values, i.e. the attributes n+1 until ’max’, are automatically supposed to be undefined.
You may call the procedures T learn class box and T enquire class box alternately, so that it is possible
to classify already in the phase of learning. By this means you could see when a satisfying behavior had been
reached.
The classificator is going to be bigger using further training. This means, that it is not advisable to continue training
after reaching a satisfactory behavior.
Parameter
º ClassifHandle (input control) ...........................................class box Htuple . long
Classificator’s handle number.
º Features (input control) .........................number-array Htuple . double / long / const char *
Array of attributes to learn.
Default Value : ’[1.0,1.5,2.0]’
º Class (input control) ........................................................integer Htuple . long
Class to which the array has to be assigned.
Default Value : 1
HALCON 6.0

6 CHAPTER 1. CLASSIFICATION
Result
T learn class box returns H MSG TRUE for a normal case. An exception handling is raised if there are
memory allocation problems. The number of classes is constrained. If this limit is passed, an exception handling
is raised, too.
Parallelization Information
T learn class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T enquire class box
Possible Successor Functions
test sampset box, T learn class box, T enquire class box, write class box,
close class box, clear sampset
See Also
test sampset box, close class box, create class box, T enquire class box,
learn sampset box
Module
Tools
learn sampset box ( long ClassifHandle, long SampKey,
const char *Outfile, long NSamples, double StopError, long ErrorN )
Train the classificator with one data set.
learn sampset box trains the classificator with data for the key SampKey (see read sampset). The training
sequence is terminated at least after NSamples examples. If NSamples is bigger than the number of examples
in SampKey, then a cyclic start at the beginning occurs. If the error underpasses the value StopError,
then the training sequence is prematurely terminated. StopError is calculated with N / ErrorN. Whereby N
significates the number of examples which were wrong classified during the last ErrorN training examples. Typically
ErrorN is the number of examples in SampKey and NSamples is a multiple of it. If you want a data set
with 100 examples to run 5 times at most and if you want it to terminate with an error lower than 5%, then the
corresponding values are NSamples = 500, ErrorN = 100 and StopError = 0.05. A protocol of the training
activity is going to be written in file Outfile.
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º SampKey (input control) ..........................................................featureset long
Number of the data set to train.
º Outfile (input control) .....................................................filename const char *
Name of the protocol file.
Default Value : ’training prot’
º NSamples (input control) ............................................................integer long
Number of arrays of attributes to learn.
Default Value : 500
º StopError (input control) ...........................................................real double
Classification error for termination.
Default Value : 0.05
º ErrorN (input control) ...............................................................integer long
Error during the assignment.
Default Value : 100
Result
learn sampset box returns H MSG TRUE. An exception handling is raised if key SampKey does not exist
or there are problems while opening the file.
Parallelization Information
learn sampset box is local and processed completely exclusively without parallelization.
create class box
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

7
Possible Successor Functions
test sampset box, T enquire class box, write class box, close class box,
clear sampset
See Also
test sampset box, T enquire class box, T learn class box, read sampset
Tools
Module
read class box ( long ClassifHandle, const char *FileName )
Read the classificator from a file.
read class box reads the saved classificator from the file FileName (see write class box). The values
of the current classificator are overwritten.
Attention
All values of the classificator are going to be overwritten.
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º FileName (input control) ...................................................filename const char *
Filename of the classificators.
Default Value : ’klassifikator1’
Result
read class box returns H MSG TRUE. An exception handling is raised if it was not possible to open file
FileName or the file has the wrong format.
Parallelization Information
read class box is local and processed completely exclusively without parallelization.
create class box
Possible Predecessor Functions
Possible Successor Functions
test sampset box, T enquire class box, write class box, close class box,
clear sampset
See Also
create class box, write class box
Tools
Module
read sampset ( const char *FileName, long *SampKey )
Read a training data set from a file.
The training examples are accessible with the key SampKey by calling procedures clear sampset and
learn sampset box. You may edit the file using an editor. Every row contains an array of attributes with
corresponding class. An example for a format might be:
(1.0, 25.3, *, 17 | 3)
This row specifies an array of attributes which belong to class 3. In this array the third attribute is unknown.
Attributes upwards 5 are supposed to be unknown, too. You may insert comments like /* .. */ in any place.
Parameter
º FileName (input control) ...................................................filename const char *
Filename of the data set to train.
Default Value : ’sampset1’
HALCON 6.0

8 CHAPTER 1. CLASSIFICATION
º SampKey (output control) .......................................................featureset long *
Identification of the data set to train.
Result
read sampset returns H MSG TRUE. An exception handling is raised if it is not possible to open the file or it
contains syntax errors or there is not enough memory.
Parallelization Information
read sampset is local and processed completely exclusively without parallelization.
create class box
Possible Predecessor Functions
Possible Successor Functions
test sampset box, T enquire class box, write class box, close class box,
clear sampset
See Also
test sampset box, clear sampset, learn sampset box
Tools
Module
set class box param ( long ClassifHandle, const char *Flag,
double Value )
Set system parameters for classification.
set class box param modifies parameter which manipulate the training sequence while calling
T learn class box. Only parameters of the classificator are modified, all other classificators remain unmodified.
’min samples for split’ is the number of examples at least which have to train in one cuboid of this
classificator, before the cuboid is allowed to divide itself. ’split error’ indicates the critical error. By its exceeding
the cuboid divides itself, if there are more than ’min samples for split’ examples to train. ’prop constant’ manipulates
the extension of the cuboids. It is proportional to the average distance of the training examples in this cuboid
to the center of the cuboid. More detailed:
extension ¢ prop = average distance of the expectation value.
This relation is valid in every dimension. Hence inside a cuboid the dimensions of the feature space are supposed
to be independent.
The parameters are set with problem independent default values, which must not modified without any reason.
Parameters are only important during a learning sequence. They do not influence on the behavior of
T enquire class box.
Default setting:
’min samples for split’ = 80,
’split error’ = 0.1,
’prop constant’ = 0.25
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º Flag (input control) ............................................................string const char *
Name of the wanted parameter.
Default Value : ’split error’
Value Suggestions : Flag ¾’min samples for split’, ’split error’, ’prop constant’
º Value (input control) .......................................................number double / long
Value of the parameter.
Default Value : 0.1
read sampset returns H MSG TRUE.
Result
Parallelization Information
set class box param is local and processed completely exclusively without parallelization.
HALCON/C Reference Manual / 2000-11-15

9
Possible Predecessor Functions
create class box, T enquire class box
Possible Successor Functions
T learn class box, test sampset box, write class box, close class box, clear sampset
See Also
T enquire class box, get class box param, T learn class box
Tools
Module
test sampset box ( long ClassifHandle, long SampKey, double *Error )
Classify a set of arrays.
In contrast to learn sampset box there is not a learning here. Typically you use test sampset box to
classify independent test data. Error gives you information about the applicability of the learned training set on
new examples.
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º SampKey (input control) ..........................................................featureset long
Key of the test data.
º Error (output control) ..............................................................real double *
Error during the assignment.
Result
test sampset box returns H MSG TRUE. An exception handling is raised, if if key SampKey does not exist
or problems occur while opening the file.
Parallelization Information
test sampset box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T learn class box, set class box param
Possible Successor Functions
T enquire class box, T learn class box, write class box, close class box,
clear sampset
See Also
T enquire class box, T learn class box, learn sampset box, read sampset
Tools
Module
write class box ( long ClassifHandle, const char *FileName )
Save the classificator in a file.
write class box saves the classificator in a file. You may read the data by calling read class box.
Attention
If a file with this name exists, it is overwritten without a warning. The file can not be edited.
Parameter
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
º FileName (input control) ...................................................filename const char *
Name of the file which contains the written data.
Default Value : ’klassifikator1’
HALCON 6.0

10 CHAPTER 1. CLASSIFICATION
Result
write class box returns H MSG TRUE. An exception handling is raised if it was not possible to open file
FileName.
Parallelization Information
write class box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T enquire class box, T learn class box, test sampset box,
write class box
Possible Successor Functions
close class box, clear sampset
create class box, read class box
Tools
See Also
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 2
File
2.1 Images
read image ( Hobject *Image, const char *FileName )
T read image ( Hobject *Image, Htuple FileName )
Read an image with different file formats.
The operator (T )read image reads the indicated image files from the background storage and generates the
image. One or more files can be indicated. The region of the generated image object (= all pixels of the matrix) is
maximal chosen.
All images files written by the operator (T )write image (format ’ima’) have the extension ’.ima’. A description
file can be available for every image in HALCON format (same file name with extension ’.exp’). The type of
the pixel data (byte, int4, real) can also be taken from the description file. If this information is not available the
type byte is used as presetting.
Besides the HALCON format TIFF, GIF, BMP, JPEG, PCX, SUN-Raster, PGM, PPM, PBM and XWD files can
also be read. The gray values of PBM images are set at the values 0 and 255. The file formats are either recognized
by the extension (if indicated) or because of the internal structure of the files. If the extension is indicated the image
can be found faster. In case of PGM, PPM and PBM the corresponding extension (e.g. ’pgm’) or the general value
’pnm’ can be used. In case of TIFF ’tiff’ and ’tif’ are accepted. In case of colored images an image with three
color channels (matrices) is created, the red channel being stored in the first, the blue channel in the second and
the green channel in the third component (channel number).
Image files are searched in the current directory (determined by the environment variable) and in the image directory
of HALCON . The image directory of HALCON is preset at ’.’ and ’/usr/local/halcon/images’ in a UNIX
environment and can be set via the operator set system. More than one image directory can be indicated. This
is done by separating the individual directories by a colon.
Furthermore the search path can be set via the environment variable HALCONIMAGES (same structure as ’image
dir’). Example:
setenv HALCONIMAGES "/usr/images:/usr/local/halcon/images"\\*
HALCON also searches images in the subdirectory ”‘images”’ (Images for the program examples). The environment
variable HALCONROOT is used for the HALCON directory.
Parameter
º Image (output object) ...........................................image Hobject * : byte / int4 / real
º FileName (input control) ...................................filename(-array) (Htuple .) const char *
Default Value : ’fabrik’
Value Suggestions : FileName ¾’monkey’, ’fabrik’, ’mreut’
11

12 CHAPTER 2. FILE
Example
/* Reading an image: */
read_image(&Image,"mreut") ;
/* Reading 3 images into an image object: */
Htuple Files ;
create_tuple(&Files,3) ;
set_s(Files,"house_red",0) ;
set_s(Files,"house_green",1) ;
set_s(Files,"house_blue",2) ;
T_read_image(&Bildobjekt,Files) ;
/* Setting of search path for images on ’/mnt/images’ and ’/home/images’:
*/
set_system("image_dir","/mnt/images:/home/images") ;
Result
If the parameters are correct the operator (T )read image returns the value H MSG TRUE. If the indicated
files cannot be found (T )read image returns the value H MSG FAIL. Otherwise an exception handling is
raised.
Parallelization Information
(T )read image is processed under mutual exclusion against itself and without parallelization.
Possible Successor Functions
disp image, threshold, regiongrowing, count channels, decompose3, class ndim norm,
gauss image, fill interlace, zoom image size, zoom image factor, crop part,
(T )write image, rgb1 to gray
read sequence
set system, (T )write image
Image / region / XLD management
Alternatives
See Also
Module
read sequence ( Hobject *Image, long HeaderSize, long SourceWidth,
long SourceHeight, long StartRow, long StartColumn, long DestWidth,
long DestHeight, const char *PixelType, const char *BitOrder,
const char *ByteOrder, const char *Pad, long Index, const char *FileName )
Read images.
The operator read sequence reads unformatted image data, from a file and returns a “suitable” image. The
image data must be filled consecutively pixel by pixel and line by line.
Any file headers (with the length HeaderSize bytes) are skipped. The parameters SourceWidth and
SourceHeight indicate the size of the filled image. DestWidth and DestHeight indicate the size of the
image. In the simplest case these parameters are the same. However, areas can also be read. The upper left corner
of the required image area can be determined via StartRow and StartColumn.
The pixel types ’bit’, ’byte’, ’short’ (16 bits, unsigned), ’signed short’ (16 bits, signed), ’long’ (32 bits, signed)
and ’swapped long’ (32 bits, with swapped segments) are supported. Furthermore the operator read sequence
enables the extraction of components of a RBG image, if a triple of three bytes (in the sequence “red”, “green”,
“blue”) was filed in the image file. For the red component the pixel type ’r byte’ must be chosen, and correspondingly
for the green and blue components ’g byte’ or ’b byte’, respectively.
’MSBFirst’ (most significant bit first) or the inversion thereof (’LSBFirst’) can be chosen for the bit order
(BitOrder). The byte orders (ByteOrder) ’MSBFirst’ (most significant byte first) or ’LSBFirst’, respectively,
are processed analogously. Finally an alignment (Pad) can be set at the end of the line: ’byte’, ’short’ or
HALCON/C Reference Manual / 2000-11-15

2.1. IMAGES 13
’long’. If a whole image sequence is stored in the file a single image (beginning at Index 1) can be chosen via the
parameter Index.
Image files are searched in the current directory (determined by the operating system environment) and in the image
directory of HALCON . The image directory of HALCON is preset as ’/bilder’ and ’/usr/local/halcon/images’ in a
UNIX environment and can be set via the operator set system. More than one image directory can be indicated
by separating the individual directories by blanks.
Furthermore the search path can be set via the environment variable HALCONIMAGES (same structure as in
’image dir’). Example:
setenv HALCONIMAGES ”/usr/images:/usr/local/halcon/images”
HALCON also searches the image in the sub-directory “images” (images for program examples). The environment
variable HALCONROOT is used for the HALCON directory.
Parameter
º Image (output object) ............................................................image Hobject *
Image read.
º HeaderSize (input control) .........................................................integer long
Number of bytes for file header.
Default Value : 0
Typical Range of Values : 0 HeaderSize
º SourceWidth (input control) .......................................................extent.x long
Number of image columns of the filed image.
Default Value : 512
Typical Range of Values : 1 SourceWidth
º SourceHeight (input control) ......................................................extent.y long
Number of image lines of the filed image.
Default Value : 512
Typical Range of Values : 1 SourceHeight
º StartRow (input control) ............................................................point.y long
Starting point of image area (line).
Default Value : 0
Typical Range of Values : 0 StartRow
Restriction : StartRow SourceHeight
º StartColumn (input control) ........................................................point.x long
Starting point of image area (column).
Default Value : 0
Typical Range of Values : 0 StartColumn
Restriction : StartColumn SourceWidth
º DestWidth (input control) ..........................................................extent.x long
Number of image columns of output image.
Default Value : 512
Typical Range of Values : 1 DestWidth
Restriction : DestWidth SourceWidth
º DestHeight (input control) ........................................................extent.y long
Number of image lines of output image.
Default Value : 512
Typical Range of Values : 1 DestHeight
Restriction : DestHeight SourceHeight
º PixelType (input control) .....................................................string const char *
Type of pixel values.
Default Value : ’byte’
Value List : PixelType ¾’bit’, ’byte’, ’r byte’, ’g byte’, ’b byte’, ’short’, ’signed short’, ’long’,
’swapped long’
º BitOrder (input control) ......................................................string const char *
Sequence of bits within one byte.
Default Value : ’MSBFirst’
Value List : BitOrder ¾’MSBFirst’, ’LSBFirst’
HALCON 6.0

14 CHAPTER 2. FILE
º ByteOrder (input control) .....................................................string const char *
Sequence of bytes within one ’short’ unit.
Default Value : ’MSBFirst’
Value List : ByteOrder ¾’MSBFirst’, ’LSBFirst’
º Pad (input control) .............................................................string const char *
Data units within one image line (alignment).
Default Value : ’byte’
Value List : Pad ¾’byte’, ’short’, ’long’
º Index (input control) ................................................................integer long
Number of images in the file.
Default Value : 1
Typical Range of Values : 1 Index (lin)
º FileName (input control) ...................................................filename const char *
Name of input file.
Result
If the parameter values are correct the operator read sequence returns the value H MSG TRUE. If the file
cannot be opened H MSG FAIL is returned. Otherwise an exception handling is raised.
Parallelization Information
read sequence is processed under mutual exclusion against itself and without parallelization.
Possible Successor Functions
disp image, count channels, decompose3, (T )write image, rgb1 to gray
(T )read image
(T )read image
Image / region / XLD management
Alternatives
See Also
Module
write image ( Hobject Image, const char *Format, long FillColor,
const char *FileName )
T write image ( Hobject Image, Htuple Format, Htuple FillColor,
Htuple FileName )
Write images in graphic formats.
The operator (T )write image returns the indicated image (Image) in different image formats in files. Pixels
outside the region receive the color defined by FillColor. For gray value images a value between 0 (black)
and 255 (white) must be passed, with RGB color images the RGB values can be passed directly as a hexadecimal
value: e.g., 0xffff00 for a yellow background (red=255, green=255, blue=0).
The following formats are currently supported:
’tiff’ TIFF format, 3-channel-images (RGB): 3 samples per pixel; other images (grayvalue images): 1 sample per
pixel, 8 bits per sample, uncompressed,72 dpi; file extension: *.tiff
’bmp’ Windows-BMP format, 3-channel-images (RGB): 3 bytes per pixel; other images (gray value image): 1
byte per pixel; file extension: *.bmp
’jpeg’ JPEG format, with lost of information; together with the format string the quality value determining the
compression rate can be provided: e.g., ’jpeg 30’. Attention: images stored for being processed later should
not be compressed with the jpeg format according to the lost of information.
’ima’ The data is written binary line by line (without header or carriage return). The size of the image and the
pixel type are stored in the description file ”’FileName.exp”’. byte, int4 and real images can be written.
The file extension is: ’.ima’
HALCON/C Reference Manual / 2000-11-15

2.2. MISC 15
Parameter
º Image (input object) ........................................................image(-array) Hobject
Output image(s).
º Format (input control) ...............................................string (Htuple .) const char *
Graphic format.
Default Value : ’tiff’
Value List : Format ¾’tiff’, ’bmp’, ’jpeg’, ’ima’, ”jpeg 100”, ”jpeg 80”, ”jpeg 60”, ”jpeg 40”, ”jpeg 20”
º FillColor (input control) .................................................integer (Htuple .) long
Fill gray value for pixels not belonging to the image region.
Default Value : 0
Value Suggestions : FillColor ¾-1, 0, 255, ’0xff0000’, ’0xff00’
º FileName (input control) ...................................filename(-array) (Htuple .) const char *
Name of graphic file.
Result
If the parameter values are correct the operator (T )write image returns the value H MSG TRUE. Otherwise
an exception handling is raised. If the file cannot be opened (T )write image returns H MSG FAIL.
Parallelization Information
(T )write image is processed under mutual exclusion against itself and without parallelization.
open window, (T )read image
Image / region / XLD management
Possible Predecessor Functions
Module
2.2 Misc
file exists ( const char *FileName )
Check whether file exists.
The operator file exists checks whether the indicated file already exists. If this is the case, the operator
file exists returns TRUE, otherwise FALSE.
Parameter
º FileName (input control) ...................................................filename const char *
Name of file to be checked.
Default Value : ’/bin/cc’
Result
The operator file exists returns the value H MSG TRUE (file exists) or H MSG FALSE (file does not exist).
Parallelization Information
file exists is reentrant and processed without parallelization.
open file
open file
Basic operators
Possible Successor Functions
Alternatives
Module
T read world file ( Htuple FileName, Htuple *WorldTransformation )
Read the geo coding from an ARC/INFO world file.
HALCON 6.0

16 CHAPTER 2. FILE
T read world file reads a geocoding from an ARC/INFO world file with the file name FileName
and returns it as a homogeneous 2D transformation matrix in WorldTransformation. To find the file
FileName, all directories contained in the HALCON system variable ’image dir’ (usually this is the content
of the environment variable HALCONIMAGES) are searched (see (T )read image). This transformation
matrix can be used to transform XLD contours to the world coordinate system before writing
them with write contour xld arc info. If the matrix WorldTransformation is inverted by calling
hom mat2d invert, the resulting matrix can be used to transform contours that have been read with
read contour xld arc info to the image coordinate system.
Parameter
º FileName (input control) ...........................................filename Htuple . const char *
Name of the ARC/INFO world file.
º WorldTransformation (output control) .........................affine2d-array Htuple . double *
Transformation matrix from image to world coordinates.
Parameter Number : 6
Result
If the parameters are correct and the world file could be read, the operator T read world file returns the value
H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
T read world file is reentrant and processed without parallelization.
Possible Successor Functions
hom mat2d invert, affine trans contour xld, affine trans polygon xld
See Also
write contour xld arc info, read contour xld arc info, write polygon xld arc info,
read polygon xld arc info
Module
Sub-pixel operators
2.3 Region
read region ( Hobject *Region, const char *FileName )
Read binary images or HALCON regions.
The operator read region reads regions from a binary file. The data is stored in packed form.
Tiff: Binary Tiff images with extension ’tiff’ or ’tif’. The result is always ÓÒ region. The color black is used as
foreground.
BMP: Binary Windows bitmap images with extension ’bmp’. The result is always ÓÒ region. The color black is
used as foreground.
HALCON regions: File format of HALCON for regions. Several images can be stored (in one file) or read
simultaneously via the operators write region and read region. All region files have the extension
’.reg’, which is not indicated when reading or writing the file.
A search path (’image dir’) can be defined analogous to the operator (T )read image.
Parameter
º Region (output object) ...................................................region(-array) Hobject *
º FileName (input control) ...................................................filename const char *
Example
/* Reading of regions and giving them gray values. */
read_image(&Img,"bild_test5") ;
read_region(&Regs,"reg_test5") ;
reduce_domain(Img,Regs,&Res) ;
HALCON/C Reference Manual / 2000-11-15

2.4. TEXT 17
Result
If the parameter values are correct the operator read region returns the value H MSG TRUE. If the file cannot
be opened H MSG FAIL is returned. Otherwise an exception handling is raised.
Parallelization Information
read region is reentrant and processed without parallelization.
(T )read image
reduce domain, disp region
write region, (T )read image
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
write region ( Hobject Region, const char *FileName )
Write regions on file.
The operator write region writes the regions of the input images (in runlength coding) to a binary file. The
data is stored in packed form. The output data can be read via the operator read region. The file name is
FileName.reg. The extension is not indicated.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region of the images which are returned.
º FileName (input control) ...................................................filename const char *
Name of region file without extension.
Default Value : ’/tmp/region’
Example
regiongrowing(Img,&Segmente,3,3,5,10) ;
write_region(Segmente,"result1") ;
Result
If the parameter values are correct the operator write region returns the value H MSG TRUE. If the file cannot
be opened H MSG FAIL is returned. Otherwise an exception handling is raised.
Parallelization Information
write region is reentrant and processed without parallelization.
Possible Predecessor Functions
open window, (T )read image, read region, threshold, regiongrowing
read region
Image / region / XLD management
See Also
Module
2.4 Text
close all files ( )
Close all open files.
close all files closes all open files.
HALCON 6.0

18 CHAPTER 2. FILE
Attention
Since all files are closed by close all files all handles become invalid.
Result
If it is possible to close the files the operator close all files returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
close all files is local and processed completely exclusively without parallelization.
close file
Basic operators
Alternatives
Module
close file ( long FileHandle )
Closing a text file.
The operator close file closes a file which was opened via the operator open file.
Parameter
º FileHandle (input control) .............................................................file long
File handle.
Example
open_file("/tmp/data.txt","input",&FileHandle) ;
/* ... */
close_file(FileHandle) ;
Result
If the file handle is correct close file returns the value H MSG TRUE. Otherwise an exception handling is
raised.
Parallelization Information
close file is local and processed completely exclusively without parallelization.
open file
open file
Basic operators
Possible Predecessor Functions
See Also
Module
fnew line ( long FileHandle )
Create a line feed.
The operator fnew line puts out a line feed into the output file. At the same time the output buffer is cleaned.
Parameter
º FileHandle (input control) .............................................................file long
File handle.
Example
fwrite_string(FileHandle,"Good Morning") ;
fnew_line(FileHandle) ;
HALCON/C Reference Manual / 2000-11-15

2.4. TEXT 19
Result
If an output file is open and it can be written to the file the operator fnew line returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
fnew line is reentrant and processed without parallelization.
(T )fwrite string
(T )fwrite string
Basic operators
Possible Predecessor Functions
See Also
Module
fread char ( long FileHandle, char *Char )
Read a character from a text file.
The operator fread char reads a character from the current input file. fread char returns the character
sequence ’eof’. At the end of a line the value ’nl’ is returned.
Parameter
º FileHandle (input control) .............................................................file long
File handle.
º Char (output control) ................................................................string char *
Read character or control string (’nl’,’eof’).
Example
do {
fread_char(FileHandle,&Char) ;
if (!strcmp(Char,"nl")) fnew_line(FileHandle) ;
if (!strcmp(Char,"nl")) fwrite_string(FileHandle,Char)) ;
} while(strcmp(Char,"eof")) ;
Result
If an input file is open the operator fread char returns H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
fread char is reentrant and processed without parallelization.
open file
close file
fread string, read string
open file, close file, fread string
Basic operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
fread string ( long FileHandle, char *OutString, long *IsEOF )
Read strings from a text file.
The operator fread string reads a string from the current input file. A string begins with the first representable
character: letters, numbers, additional characters (except blanks). A string ends when a blank or a line skip is
HALCON 6.0

20 CHAPTER 2. FILE
reached. Several successive line skips are ignored. If the end of the file is reached IsEOF return the value 1,
otherwise 0.
Parameter
º FileHandle (input control) .............................................................file long
File handle.
º OutString (output control) .........................................................string char *
Read character sequence.
º IsEOF (output control) .............................................................integer long *
Reached end of file.
Example
fwrite_string(FileHandle,"Please enter text and return: ..") ;
fread_string(FileHandle,&String,&IsEOF) ;
fwrite_string(FileHandle,"here it is again: ") ;
fwrite_string(FileHandle,String) ;
fnew_line(FileHandle) ;
Result
If a file is open and a suitable string is read fread string returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
fread string is reentrant and processed without parallelization.
open file
close file
fread char, read string
open file, close file, fread char
Basic operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
fwrite string ( long FileHandle, const char *String )
T fwrite string ( Htuple FileHandle, Htuple String )
Write values in a text file.
The operator (T )fwrite string puts out a string or numbers on the output file. The operator open file
opens a file. The call set system (’flush file’, ) determines whether the output
characters are put out directly on the output medium. If the value ’flush file’ is set to ’false’ the characters
(especially in case of screen output) show up only after the operator fnew line is called.
Strings as well as whole numbers and floating point numbers can be used as arguments. If more than one value
serves as input the values are put out consecutively without blanks.
Parameter
º FileHandle (input control) ...................................................file (Htuple .) long
File handle.
º String (input control) ...........................string(-array) (Htuple .) const char * / long / double
Values to be put out on the text file.
Default Value : ’hallo’
HALCON/C Reference Manual / 2000-11-15

2.4. TEXT 21
Example
fwrite_string(FileHandle,"text with numbers: ") ;
fwrite_string(FileHandle,"5") ;
fwrite_string(FileHandle," and ") ;
fwrite_string(FileHandle,"1.0") ;
/* results in the following output: */
/* ’text with numbers: 5 and 1.00000’ */
/* Tupel Version */
int i;
double d;
Htuple Tuple ;
create_tuple(&Tuple,4) ;
i = 5 ;
d = 10.0 ;
set_s(Tuple,"text with numbers: ",0) ;
set_i(Tuple,i,1) ;
set_s(Tuple," and ",2) ;
set_d(Tuple,d,3) ;
T_fwrite_string(FileHandle,HilfsTuple) ;
Result
If the writing procedure was carried out successfully the operator (T )fwrite string returns the value
H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )fwrite string is reentrant and processed without parallelization.
open file
close file
write string
open file, close file, set system
Basic operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
open file ( const char *FileName, const char *FileType,
long *FileHandle )
Open text file.
The operator open file opens a file. FileType determines whether this file is an input (’input’) or output
file (’output’). Text files which can be accessed either by reading (’input’) or by writing (’output’) are created.
For terminal input and output the file names ’standard’ (’input’ and ’output’) and’error’ (only ’output’) are
reserved.
Parameter
º FileName (input control) ...................................................filename const char *
Name of file to be opened.
Default Value : ’standard’
Value Suggestions : FileName ¾’standard’, ’error’, ”/tmp/dat.dat”
HALCON 6.0

22 CHAPTER 2. FILE
º FileType (input control) ......................................................string const char *
Type of file.
Default Value : ’output’
Value List : FileType ¾’input’, ’output’
º FileHandle (output control) ..........................................................file long *
File handle.
Example
/* Creating of an outputfile with the name ’/tmp/log.txt’ and writing */
/* of one string: */
open_file("/tmp/log.txt","output",&FileHandle) ;
fwrite_string(FileHandle,"these are the first and last lines") ;
fnew_line(FileHandle) ;
close_file(FileHandle);
Result
If the parameters are correct the operator open file returns the value H MSG TRUE. Otherwise an exception
handling is raised.
Parallelization Information
open file is local and processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )fwrite string, fread char, fread string, close file
See Also
close file, (T )fwrite string, fread char, fread string
Basic operators
Module
2.5 Tuple
read tuple ( const char *FileName, double *Tuple )
T read tuple ( Htuple FileName, Htuple *Tuple )
Read a tuple from a file.
The operator (T )read tuple reads the contents of FileName and converts it into Tuple. The file has to be
generated by (T )write tuple.
Parameter
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the file to be read.
º Tuple (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long * / char *
Tuple with any kind of data.
Result
If the parameters are correct the operator (T )read tuple returns the value H MSG TRUE. If the file could not
be opened (T )read tuple returns H MSG FAIL. Otherwise an exception handling is raised.
Parallelization Information
(T )read tuple is reentrant and processed without parallelization.
(T )fwrite string
Alternatives
HALCON/C Reference Manual / 2000-11-15

2.6. XLD 23
See Also
(T )write tuple, gnuplot plot ctrl, (T )write image, write region, open file
Operators not requiring licensing
Module
write tuple ( double Tuple, const char *FileName )
T write tuple ( Htuple Tuple, Htuple FileName )
Writeatupletoafile.
The operator (T )write tuple writes the contents of Tuple to a file. The data is written in an ASCII format.
Therefore, the file can be exchanged between different architectures. There is no specific extension for this kind of
file.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double / long / const char *
Tuple with any kind of data.
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the file to be written.
Result
If the parameters are correct the operator (T )write tuple returns the value H MSG TRUE. If the file could
not be opened (T )write tuple returns H MSG FAIL. Otherwise an exception handling is raised.
Parallelization Information
(T )write tuple is reentrant and processed without parallelization.
(T )fwrite string
Alternatives
See Also
(T )read tuple, (T )write image, write region, open file
Operators not requiring licensing
Module
2.6 XLD
read contour xld arc info ( Hobject *Contours, const char *FileName )
Read XLD contours to a file in ARC/INFO generate format.
read contour xld arc info reads the lines stored in ARC/INFO generate format in the file FileName,and
returns them as XLD contours in Contours. To find the file FileName, all directories contained in the HAL-
CON system variable ’image dir’ (usually this is the content of the environment variable HALCONIMAGES) are
searched (see (T )read image). The returned contours are in world coordinates. They can be transformed to
the image coordinate system with the operator affine trans contour xld. The necessary transformation
matrix can be generated by using T read world file to read the transformation matrix from image to world
coordinates, and inverting this matrix by calling hom mat2d invert.
Parameter
º Contours (output object) ...............................................xld cont(-array) Hobject *
Read XLD contours.
º FileName (input control) ...................................................filename const char *
Name of the ARC/INFO file.
HALCON 6.0

24 CHAPTER 2. FILE
Example
/* Read the transformation and invert it */
read_world_file (’image.tfw’, WorldTransformation)
hom_mat2d_invert (WorldTransformation, ImageTransformation)
/* Read the image */
read_image (Image, ’image.tif’)
/* Read the line data */
read_contour_xld_arc_info (LinesWorld, ’lines.gen’)
/* Transform the line data to image coordinates */
affine_trans_contour_xld (LinesWorld, Lines, ImageTransformation)
Result
If the parameters are correct and the file could be read, the operator read contour xld arc info returns the
value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
read contour xld arc info is reentrant and processed without parallelization.
Possible Successor Functions
hom mat2d invert, affine trans contour xld
See Also
T read world file, write contour xld arc info, read polygon xld arc info
Sub-pixel operators
Module
read polygon xld arc info ( Hobject *Polygons, const char *FileName )
Read XLD polygons from a file in ARC/INFO generate format.
read polygon xld arc info reads the lines stored in ARC/INFO generate format in the file FileName,and
returns them as XLD polygons in Polygons. To find the file FileName, all directories contained in the HAL-
CON system variable ’image dir’ (usually this is the content of the environment variable HALCONIMAGES) are
searched (see (T )read image). The returned polygons are in world coordinates. They can be transformed to
the image coordinate system with the operator affine trans polygon xld. The necessary transformation
matrix can be generated by using T read world file to read the transformation matrix from image to world
coordinates, and inverting this matrix by calling hom mat2d invert.
Parameter
º Polygons (output object) ..............................................xld poly(-array) Hobject *
Read XLD polygons.
º FileName (input control) ...................................................filename const char *
Name of the ARC/INFO file.
Example
/* Read the transformation and invert it */
read_world_file (’image.tfw’, WorldTransformation)
hom_mat2d_invert (WorldTransformation, ImageTransformation)
/* Read the image */
read_image (Image, ’image.tif’)
/* Read the line data */
read_polygon_xld_arc_info (LinesWorld, ’lines.gen’)
/* Transform the line data to image coordinates */
affine_trans_polygon_xld (LinesWorld, Lines, ImageTransformation)
Result
If the parameters are correct and the file could be read, the operator read polygon xld arc info returns the
value H MSG TRUE. Otherwise an exception is raised.
HALCON/C Reference Manual / 2000-11-15

2.6. XLD 25
Parallelization Information
read polygon xld arc info is reentrant and processed without parallelization.
Possible Successor Functions
hom mat2d invert, affine trans polygon xld
See Also
T read world file, write polygon xld arc info, read contour xld arc info
Sub-pixel operators
Module
write contour xld arc info ( Hobject Contours, const char *FileName )
Write XLD contours to a file in ARC/INFO generate format.
write contour xld arc info writes the XLD contours Contours to an ARC/INFO generate format file
with name FileName. If no absolute path is given in FileName, the output file is created in the current directory
of the HALCON process. The contours must have been transformed to the world coordinate system with
affine trans contour xld beforehand. The necessary transformation can be read from an ARC/INFO
world file with T read world file.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
XLD contours to be written.
º FileName (input control) ...................................................filename const char *
Name of the ARC/INFO file.
Example
/* Read transformation and image */
read_world_file (’image.tfw’, WorldTransformation)
read_image (Image, ’image.tif’)
/* Segment image */
...
/* Write result */
affine_trans_contour_xld (Contours, ContoursWorld, WorldTransformation)
write_contour_xld_arc_info (ContoursWorld, ’result.gen’)
Result
If the parameters are correct and the file could be written, the operator write contour xld arc info returns
the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
write contour xld arc info is reentrant and processed without parallelization.
affine trans contour xld
Possible Predecessor Functions
See Also
T read world file, read contour xld arc info, write polygon xld arc info
Sub-pixel operators
Module
write polygon xld arc info ( Hobject Polygons, const char *FileName )
Write XLD polygons to a file in ARC/INFO generate format.
write polygon xld arc info writes the XLD polygons Polygons to an ARC/INFO generate format file
with name FileName. If no absolute path is given in FileName, the output file is created in the current directory
of the HALCON process. The polygons must have been transformed to the world coordinate system with
HALCON 6.0

26 CHAPTER 2. FILE
affine trans polygon xld beforehand. The necessary transformation can be read from an ARC/INFO
world file with T read world file.
Attention
The XLD contours that are possibly referenced by Polygons are not stored in the ARC/INFO file, since this
is not possible with the ARC/INFO generate file format. Therefore, when the polygons are read again using
read polygon xld arc info, this information is lost, and no references to contours are generated for the
polygons. Hence, operators that access the contours associated with a polygon, e.g., split contours xld
will not work correctly.
Parameter
º Polygons (input object) .................................................xld poly(-array) Hobject
XLD polygons to be written.
º FileName (input control) ...................................................filename const char *
Name of the ARC/INFO file.
Example
/* Read transformation and image */
read_world_file (’image.tfw’, WorldTransformation)
read_image (Image, ’image.tif’)
/* Segment image */
...
/* Write result */
affine_trans_polygon_xld (Polygons, PolygonsWorld, WorldTransformation)
write_polygon_xld_arc_info (PolygonsWorld, ’result.gen’)
Result
If the parameters are correct and the file could be written, the operator write polygon xld arc info returns
the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
write polygon xld arc info is reentrant and processed without parallelization.
affine trans polygon xld
Possible Predecessor Functions
See Also
T read world file, read polygon xld arc info, write contour xld arc info
Sub-pixel operators
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 3
Filter
3.1 Affine-Transformations
T affine trans image ( Hobject Image, Hobject *ImageAffinTrans,
Htuple HomMat2D, Htuple Interpolation, Htuple AdaptImageSize )
Apply an arbitrary affine transformation to an image.
T affine trans image applies an arbitrary affine transformation, i.e., scaling, rotation, translation, and
skewing, to an image. The affine map is described by the transformation matrix given in HomMat2D
, which is built up by using hom mat2d identity, hom mat2d scale, hom mat2d rotate, and
hom mat2d translate. The components of the homogeneous transformation matrix are interpreted as follows:
the row coordinate of the image corresponds to the Ü coordinate of the matrix, while the column coordinate
of the image corresponds to the Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate
system, which is assumed for the homogeneous transformation matrices, also for the image. In particular, by doing
so roatations are performed in the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally
corresponds to the usual (row,column) order for coordinates in the image.
The region of the input image is ignored, i.e., assumed to be the full rectangle of the image. The region of the
resulting image is set to the transformed rectangle of the input image. If necessary, the resulting image is filled
with zero (black) outside of the region of the original image.
Generally, transformed points will lie between pixel coordinates. Therefore, an appropriate interpolation scheme
has to be used. The interpolation can also be used to avoid aliasing effects for scaled images. The quality and
speed of the interpolation can be set by the parameter Interpolation:
none No interpolation: The gray value is determined from the nearest pixel’s gray value (possibly low quality,
very fast).
constant Use equally wighted interpolation between adjacent pixels (medium quality and run time).
weighted Use Gaussian interpolation between adjacent pixels (best quality, slow).
In addition, the system parameter ’int zooming’ (see set system) affects the accuracy of the transformation.
If ’int zooming’ is set to ’true’, the transformation for byte and int2 images is carried out internally using fixed
point arithmetic, leading to much shorter execution times. However, the accuracy of the transformed gray values
is smaller in this case. For byte images, the differences to the more accurate calculation (using ’int zooming’ =
’false’) is typically less than two gray levels. Correspondingly, for int2 images, the gray value differences are less
than 1/128 times the dynamic gray value range of the image, i.e., they can be as large as 512 gray levels if the
entire dynamic range of 16 bit is used. For real images, the parameter ’int zooming’ does not affect the accuracy,
since the internal calculations are always done using floating point arithmetic.
The size of the target image can be controled by the paramter AdaptImageSize: With value ’true’ the size will
be adapted so that no clipping occures. With value ’false’ the target image has the same size as the input image.
Attention
The region of the input image is ignored.
The components of the homogeneous transformation matrix are interpreted as follows: the row coordinate of the
image corresponds to the Ü coordinate of the matrix, while the column coordinate of the image corresponds to the
27

28 CHAPTER 3. FILTER
Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate system, which is assumed for the
homogeneous transformation matrices, also for the image. In particular, by doing so roatations are performed in
the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally corresponds to the usual (row,column)
order for coordinates in the image.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / real
Input image.
º ImageAffinTrans (output object) . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / real
Transformed image.
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Interpolation (input control) .......................................string Htuple . const char *
Type of interpolation.
Default Value : ’constant’
Value List : Interpolation ¾’none’, ’constant’, ’weighted’
º AdaptImageSize (input control) ......................................string Htuple . const char *
Adaption of size of result image.
Default Value : ’false’
Value List : AdaptImageSize ¾’true’, ’false’
Example
/* Reduction of an image (512 x 512 Pixels) by 50%, rotation */
/* by 180 degrees and translation to the upper-left corner: */
hom_mat2d_identity(Matrix1)
hom_mat2d_scale(Matrix1,0.5,0.5,256.0,256.0,Matrix2)
hom_mat2d_rotate(Matrix2,3.14,256.0,256.0,Matrix3)
hom_mat2d_translate(Matrix3,-128.0,-128.0,Matrix4,)
affine_trans_image(Image,TransImage,Matrix4,1).
/* Enlarging the part of an image in the interactively */
/* chosen rectangular window sector: */
draw_rectangle2(WindowHandle,L,C,Phi,L1,L2)
hom_mat2d_identity(Matrix1)
get_system(width,Width)
get_system(height,Height)
hom_mat2d_translate(Matrix1,Height/2.0-L,Width/2.0-C,Matrix2)
hom_mat2d_rotate(Matrix2,3.14-Phi,Height/2.0,Width/2.0,Matrix3)
hom_mat2d_scale(Matrix3,Height/(2.0*L2),Width/(2.0*L1),
Height/2.0,Width/2.0,Matrix4)
affine_trans_image(Image,Matrix4,TransImage,1).
Result
T affine trans image returns H MSG TRUE if all parameter values are correct. If the input is empty the
behaviour can be set via set system(’no object result’,). If necessary, an exception handling
is raised.
Parallelization Information
T affine trans image is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
hom mat2d identity, hom mat2d translate, hom mat2d rotate, hom mat2d scale
Alternatives
zoom image size, zoom image factor, mirror image, rotate image, affine trans region
set part style
See Also
HALCON/C Reference Manual / 2000-11-15

3.1. AFFINE-TRANSFORMATIONS 29
Image filters
Module
mirror image ( Hobject Image, Hobject *ImageMirror, const char *Mode )
Mirror an image.
mirror image reflects an image Image about one of three possible axes. If Mode is set to ’row’, it is reflected
about the horizontal axis, if Mode is set to ’column’, about the vertical axis, and if Mode is set to ’main’, about
the main diagonal Ü Ý.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageMirror (output object) . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Reflected image.
º Mode (input control) ............................................................string const char *
Axis of reflection.
Default Value : ’row’
Value List : Mode ¾’row’, ’column’, ’main’
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
mirror_image(Image,&MirImage,"row");
disp_image(MirImage,WindowHandle);
Parallelization Information
mirror image is reentrant and automatically parallelized (on tuple level, channel level).
Alternatives
hom mat2d rotate, T affine trans image, rotate image
rotate image, hom mat2d rotate
Image filters
See Also
Module
polar trans image ( Hobject ImageXY, Hobject *ImagePolar, long Row,
long Column, long Width, long Height )
Transform an image to polar coordinates
polar trans image transforms an image in cartesian coordinates to an image in polar coordinates. The size
of the resulting image is selected with Width and Height. Width determines the angular resolution, while
Height determines the resolution of the radius. Row and Column determine the center of the polar coordinate
system in the original image ImageXY. This point is mapped to the upper row of ImagePolar.
A point (x’,y’) in the result image corresponds to the point (x,y) in the original image in the following manner:
Ü Ý ¼ Ó×´¾´Ü ¼ Ö×ÙÐØÛصµ · ÓÐÙÑÒÝ Ý ¼ ×Ò´¾´Ü ¼ Ö×ÙÐØÛصµ · ÊÓÛ
Parameter
º ImageXY (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte / int2
Input image in cartesian coordinates.
º ImagePolar (output object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Result image in polar coordinates.
HALCON 6.0

30 CHAPTER 3. FILTER
º Row (input control) ...................................................................point.y long
Row coordinate of the center of the coordinate system.
Default Value : 100
Value Suggestions : Row ¾0, 10, 100, 200
Typical Range of Values : 0 Row 512
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the center of the coordinate system.
Default Value : 100
Value Suggestions : Column ¾0, 10, 100, 200
Typical Range of Values : 0 Column 512
Minimal Value Step : 1
Recommended Value Step : 1
º Width (input control) ...............................................................extent.x long
Width of the result image.
Default Value : 314
Value Suggestions : Width ¾100, 200, 157, 314, 512
Typical Range of Values : 2 Width 512
Minimal Value Step : 1
Recommended Value Step : 10
º Height (input control) ..............................................................extent.y long
Height of the result image.
Default Value : 200
Value Suggestions : Height ¾100, 128, 256, 512
Typical Range of Values : 2 Height 512
Minimal Value Step : 1
Recommended Value Step : 10
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
polar_trans_image(Image,&PolarImage,100,100,314,200);
disp_image(PolarImage,WindowHandle);
Parallelization Information
polar trans image is reentrant and automatically parallelized (on tuple level, channel level).
T affine trans image
Image filters
Alternatives
Module
rotate image ( Hobject Image, Hobject *ImageRotate, double Phi,
const char *Interpolation )
Rotate an image about its center.
rotate image rotates the image Image counterclockwise by Phi degrees about its center. This operator is
much faster if Phi is a multiple of 90 degrees than the general operator T affine trans image. For rotations
by 90, 180, and 270 degrees, the region is rotated accordingly. For all other rotations the region is set to the
maximum region, i.e., to the extent of the resulting image. The effect of the parameter Interpolation is the
same as in T affine trans image. It is ignored for rotations by 90, 180, and 270 degrees. The size of the
resulting image is the same as that of the input image, with the exception of rotations by 90 and 270 degrees, where
the width and height will be exchanged.
Attention
The angle Phi is given in degrees, not in radians.
HALCON/C Reference Manual / 2000-11-15

3.1. AFFINE-TRANSFORMATIONS 31
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageRotate (output object) . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Rotated image.
º Phi (input control) ........................................................angle.deg double / long
Rotation angle.
Default Value : 90
Value Suggestions : Phi ¾90, 180, 270
Typical Range of Values : 0 Phi 360
Minimal Value Step : 0.001
Recommended Value Step : 0.2
º Interpolation (input control) ...............................................string const char *
Type of interpolation.
Default Value : ’constant’
Value List : Interpolation ¾’none’, ’constant’, ’weighted’
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
rotate_image(Image,&RotImage,270);
disp_image(RotImage,WindowHandle);
Example
Parallelization Information
rotate image is reentrant and automatically parallelized (on tuple level, channel level).
Alternatives
hom mat2d rotate, T affine trans image
mirror image
Image filters
See Also
Module
zoom image factor ( Hobject Image, Hobject *ImageZoomed,
double ScaleWidth, double ScaleHeight, const char *Interpolation )
Zoom an image by a given factor.
zoom image factor scales the image Image by a factor of ScaleWidth in width and a factor
ScaleHeight in height. The parameter Interpolation determines the type of interpolation used (see
T affine trans image).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageZoomed (output object) . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Scaled image.
º ScaleWidth (input control) ......................................................extent.x double
Scale factor for the width of the image.
Default Value : 0.5
Value Suggestions : ScaleWidth ¾0.25, 0.5, 1.5, 2.0
Typical Range of Values : 0.001 ScaleWidth 10.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
HALCON 6.0

32 CHAPTER 3. FILTER
º ScaleHeight (input control) .....................................................extent.y double
Scale factor for the height of the image.
Default Value : 0.5
Value Suggestions : ScaleHeight ¾0.25, 0.5, 1.5, 2.0
Typical Range of Values : 0.001 ScaleHeight 10.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Interpolation (input control) ...............................................string const char *
Type of interpolation.
Default Value : ’constant’
Value List : Interpolation ¾’none’, ’constant’, ’weighted’
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
zoom_image_factor(Image,&ZooImage,0,0.5,0.5);
disp_image(ZooImage,WindowHandle);
Parallelization Information
zoom image factor is reentrant and automatically parallelized (on tuple level, channel level).
Alternatives
zoom image factor, T affine trans image, hom mat2d scale
hom mat2d scale, T affine trans image
Image filters
See Also
Module
zoom image size ( Hobject Image, Hobject *ImageZoom, long Width,
long Height, const char *Interpolation )
Zoom an image to a given size.
zoom image size scales the image Image to the size given by Width and Height.
Interpolation determines the type of interpolation used (see T affine trans image).
Parameter
The parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageZoom (output object) . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Scaled image.
º Width (input control) ...............................................................extent.x long
Width of the resulting image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512
Typical Range of Values : 2 Width 512
Minimal Value Step : 1
Recommended Value Step : 10
º Height (input control) ..............................................................extent.y long
Height of the resulting image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512
Typical Range of Values : 2 Height 512
Minimal Value Step : 1
Recommended Value Step : 10
HALCON/C Reference Manual / 2000-11-15

3.2. ARITHMETIC 33
º Interpolation (input control) ...............................................string const char *
Type of interpolation.
Default Value : ’constant’
Value List : Interpolation ¾’none’, ’constant’, ’weighted’
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
zoom_image_size(Image,&ZooImage,0,200,200);
disp_image(ZooImage,WindowHandle);
Parallelization Information
zoom image size is reentrant and automatically parallelized (on tuple level, channel level).
Alternatives
zoom image factor, T affine trans image, hom mat2d scale
hom mat2d scale, T affine trans image
Image filters
See Also
Module
3.2 Arithmetic
abs image ( Hobject Image, Hobject *ImageAbs )
Calculate the absolute value (modulus) of an image.
The operator abs image calculates the absolute gray values of images of any type and stores the result in
ImageAbs. The power spectrum of complex images is calculated as a ’real’ image. The operator abs image
generates a logical copy of unsigned images.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject :any
Image(s) for which the absolute gray values are to be calculated.
º ImageAbs (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * :any
Result image(s).
Example
laws_int2(Image,&Texture,0,5);
abs_image(Texture,Abs);
Result
The operator abs image returns the value H MSG TRUE. The behavior in case of empty input (no input images
available) is set via the operator set system(’no object result’,)
Parallelization Information
abs image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
convert image type, power byte
Image filters
See Also
Module
add image ( Hobject Image1, Hobject Image2, Hobject *ImageResult,
double Mult, double Add )
Add two images.
HALCON 6.0

34 CHAPTER 3. FILTER
The operator add image adds two images. The gray values (½¾) of the input images (Image1 and Image2)
are transformed as follows:
¼ ´½ ·¾µ £ ÅÙÐØ ·
If an overflow or an underflow occurs the values are clipped. This is not the case with int2 images if Mult is equal
to1andAdd is equal to 0. To reduce the runtime the underflow and overflow check is skipped. The resulting
image is stored in ImageResult.
It is possible to add byte images with int2 and int4 images. In this case the result will be of type int2 or int4
respectively.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Please note that the runtime of the operator varies with different control parameters. For frequently used combinations
special optimizations were used.
Parameter
º Image1 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic / complex
Image(s) 1.
º Image2 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic / complex
Image(s) 2.
º ImageResult (output object) . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Result image(s) by the addition.
º Mult (input control) ........................................................number double / long
Factor for gray value adaption.
Default Value : 0.5
Value Suggestions : Mult ¾0.2, 0.4, 0.6, 0.8, 1.0, 1.5, 2.0, 3.0, 5.0
Typical Range of Values : -255.0 Mult 255.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Add (input control) ..........................................................number double / long
Value for gray value range adaption.
Default Value : 0
Value Suggestions : Add ¾0, 64, 128, 255, 512
Typical Range of Values : -512.0 Add 512.0
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Example
read_image(&Image0,"fabrik");
disp_image(Image0,WindowHandle);
read_image(&Image1,"Affe");
disp_image(Image1,WindowHandle);
add_image(Image0,Image1,&Result,2.0,10.0);
disp_image(Result,WindowHandle);
Result
The operator add image returns the value H MSG TRUE if the parameters are correct. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
add image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
sub image, mult image
sub image, mult image
Alternatives
See Also
HALCON/C Reference Manual / 2000-11-15

3.2. ARITHMETIC 35
Image filters
Module
div image ( Hobject Image1, Hobject Image2, Hobject *ImageResult,
double Mult, double Add )
Divide two images.
The operator div image divides two images. The gray values (½¾) of the input images (Image1)aretransformed
as follows:
¼ ½¾ £ ÅÙÐØ ·
If an overflow or an underflow occurs the values are clipped.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Parameter
º Image1 (input object) . . . .(multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / complex
Image(s) 1.
º Image2 (input object) . . . .(multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / complex
Image(s) 2.
º ImageResult (output object) . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
complex
Result image(s) by the division.
º Mult (input control) ........................................................number double / long
Factor for gray range adaption.
Default Value : 255
Value Suggestions : Mult ¾0.1, 0.2, 0.5, 1.0, 2.0, 3.0, 10, 100, 500, 1000
Typical Range of Values : -1000 Mult 1000
Minimal Value Step : 0.001
Recommended Value Step : 1
º Add (input control) ..........................................................number double / long
Value for gray range adaption.
Default Value : 0
Value Suggestions : Add ¾0.0, 128.0, 256.0, 1025
Typical Range of Values : -1000 Add 1000
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Example
read_image(&Image0,"fabrik");
disp_image(Image0,WindowHandle);
read_image(&Image1,"Affe");
disp_image(Image1,WindowHandle);
div_image(Image0,Image1,&Result,2.0,10.0);
disp_image(Result,WindowHandle);
Result
The operator div image returns the value H MSG TRUE if the parameters are correct. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
div image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
add image, sub image, mult image
Alternatives
HALCON 6.0

36 CHAPTER 3. FILTER
add image, sub image, mult image
Image filters
See Also
Module
invert image ( Hobject Image, Hobject *ImageInvert )
Invert an image.
The operator invert image inverts the gray values of an image. For images of the ’byte’ and ’cyclic’ type the
result is calculated as:
Images of the ’direction’ type are transformed by
¼ ¾
¼ ´ · ¼µ modulo ½¼
In the case of signed types the values are negated. The resulting image has the same pixel type as the input image.
Several images can be processed in one call. An output image is generated for every input image.
Parameter
º Image (input object) . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / cyclic /
direction
Input image(s).
º ImageInvert (output object) . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
cyclic / direction
Image(s) with inverted gray values.
read_image(&Orig,"fabrik");
invert_image(Orig,&Invert);
disp_image(Invert,WindowHandle);
Example
Parallelization Information
invert image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
watersheds
scale image
scale image, add image, sub image
Image filters
Possible Successor Functions
Alternatives
See Also
Module
max image ( Hobject Image1, Hobject Image2, Hobject *ImageMax )
Calculate the maximum of two images pixel by pixel.
max image calculates the maximum of the images Image1 and Image2 (pixel by pixel). The result is stored in
the image ImageMax. The resulting image has the same pixel type as the input image. If several (pairs of) images
are processed in one call, every i-th image from Image1 is compared to the i-th image from Image2. Thus the
number of images in both input parameters must be the same. An output image is generated for every input pair.
HALCON/C Reference Manual / 2000-11-15

3.2. ARITHMETIC 37
Attention
The two input images must be of the same type and size.
Parameter
º Image1 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic
Image(s) 1.
º Image2 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic
Image(s) 2.
º ImageMax (output object) . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic
Result image(s) by the maximization.
read_image(&Bild1,"affe");
read_image(&Bild2,"fabrik");
max_image(Bild1,Bild2,&Max);
disp_image(Max,WindowHandle);
Example
Result
If the parameter values are correct the operator max image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
max image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
max image
min image
Image filters
Alternatives
See Also
Module
min image ( Hobject Image1, Hobject Image2, Hobject *ImageMin )
Calculate the minimum of two images pixel by pixel.
The operator min image determines the minimum (pixel by pixel) of the images Image1 and Image2. The
result is stored in the image ImageMin. The resulting image has the same pixel type as the input image. If several
(pairs of) images are processed in one call, every i-th image from Image1 is compared to the i-th image from
Image2. Thus the number of images in both input parameters must be the same. An output image is generated
for every input pair.
Parameter
º Image1 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic
Image(s) 1.
º Image2 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic
Image(s) 2.
º ImageMin (output object) . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic
Result image(s) by the minimization.
Result
If the parameter values are correct the operator min image returns the value H MSG TRUE. The
HALCON 6.0

38 CHAPTER 3. FILTER
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
min image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
gray erosion
max image, min image
Image filters
Alternatives
See Also
Module
mult image ( Hobject Image1, Hobject Image2, Hobject *ImageResult,
double Mult, double Add )
Multiply two images.
mult image multiplies two images. The gray values (½¾) of the input images (Image1) aretransformedas
follows:
¼ ½ £ ¾ £ ÅÙÐØ ·
If an overflow or an underflow occurs the values are clipped.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Parameter
º Image1 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic / complex
Image(s) 1.
º Image2 (input object) . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic / complex
Image(s) 2.
º ImageResult (output object) . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Result image(s) by the product.
º Mult (input control) ........................................................number double / long
Factor for gray range adaption.
Default Value : 0.005
Value Suggestions : Mult ¾0.001, 0.01, 0.5, 1.0, 2.0, 3.0, 5.0, 10.0
Typical Range of Values : -255.0 Mult 255.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Add (input control) ..........................................................number double / long
Value for gray range adaption.
Default Value : 0
Value Suggestions : Add ¾0.0, 128.0, 256.0
Typical Range of Values : -512.0 Add 512.0
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Example
read_image(&Image0,"fabrik");
disp_image(Image0,WindowHandle);
read_image(&Image1,"Affe");
disp_image(Image1,WindowHandle);
mult_image(Image0,Image1,&Result,2.0,10.0);
disp_image(Result,WindowHandle);
HALCON/C Reference Manual / 2000-11-15

3.2. ARITHMETIC 39
Result
The operator mult image returns the value H MSG TRUE if the parameters are correct. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
mult image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
add image, sub image, div image
add image, sub image, div image
Image filters
Alternatives
See Also
Module
scale image ( Hobject Image, Hobject *ImageScaled, double Mult,
double Add )
Scale the gray values of an image.
The operator scale image scales the input images (Image) by the following transformation:
¼ £ ÅÙÐØ ·
If an overflow or an underflow occurs the values are clipped.
Parameter
º Image (input object) . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real / direction /
cyclic / complex
Image(s) whose gray values are to be scaled.
º ImageScaled (output object) . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Result image(s) by the scale.
º Mult (input control) ........................................................number double / long
Scale factor.
Default Value : 0.01
Value Suggestions : Mult ¾0.001, 0.003, 0.005, 0.008, 0.01, 0.02, 0.03, 0.05, 0.08, 0.1, 0.5, 1.0
Typical Range of Values : -255.0 Mult 255.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Add (input control) ..........................................................number double / long
Offset.
Default Value : 0
Value Suggestions : Add ¾0, 10, 50, 100, 200, 500
Typical Range of Values : -512.0 Add 512.0
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Example
/* simulation of invert for type ’byte’ */
byte_invert(Hobject In, Hobject *out)
{
scale_image(In,Out,-1.0,255.0);
}
Result
The operator scale image returns the value H MSG TRUE if the parameters are correct. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) Otherwise an exception treatment is carried out.
HALCON 6.0

40 CHAPTER 3. FILTER
Parallelization Information
scale image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
min max gray
mult image, add image, sub image
min max gray
Image filters
Possible Predecessor Functions
Alternatives
See Also
Module
sub image ( Hobject ImageMinuend, Hobject ImageSubtrahend,
Hobject *ImageSub, double Mult, double Add )
Subtract two images.
The operator sub image subtracts two images. The gray values (½¾) of the input images (ImageMinuend
and ImageSubtrahend) are transformed as follows:
¼ ´½ ¾µ £ ÅÙÐØ ·
If an overflow or an underflow occurs the values are clipped.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Parameter
º ImageMinuend (input object) . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Minuend(s).
º ImageSubtrahend (input object) (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Subtrahend(s).
º ImageSub (output object) . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real /
direction / cyclic / complex
Result image(s) by the subtraction.
º Mult (input control) ........................................................number double / long
Correction factor.
Default Value : 1.0
Value Suggestions : Mult ¾0.0, 1.0, 2.0, 3.0, 4.0
Typical Range of Values : -255.0 Mult 255.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Add (input control) ..........................................................number double / long
Correction value.
Default Value : 128.0
Value Suggestions : Add ¾0.0, 128.0, 256.0
Typical Range of Values : -512.0 Add 512.0
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Example
read_image(&Image0,"fabrik");
disp_image(Image0,WindowHandle);
read_image(&Image1,"Affe");
disp_image(Image1,WindowHandle);
sub_image(Image0,Image1,&Result,2.0,10.0);
disp_image(Result,WindowHandle);
HALCON/C Reference Manual / 2000-11-15

3.3. BIT 41
Result
The operator sub image returns the value H MSG TRUE if the parameters are correct. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
sub image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
dual threshold
mult image, add image, sub image
Possible Successor Functions
Alternatives
See Also
add image, mult image, dyn threshold, check difference
Image filters
Module
3.3 Bit
bit and ( Hobject Image1, Hobject Image2, Hobject *ImageAnd )
Bit-by-bit AND of all pixels of the input images.
The operator bit and calculates the “and” of all pixels of the input images bit by bit. The semantics of the “and”
operation corresponds to that of C for the respective types (signed char, unsigned char, short, int/long). The images
must have the same size and pixel type. The pixels within the definition range of the image in the first parameter
are processed.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Parameter
º Image1 (input object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s) 1.
º Image2 (input object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s) 2.
º ImageAnd (output object) . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by AND-operation.
read_image(&Image0,"affe");
disp_image(Image0,WindowHandle);
read_image(&Image1,"fabrik");
disp_image(Image1,WindowHandle);
bit_and(Image0,Image1,&ImageBitA);
disp_image(ImageBitA,WindowHandle);
Example
Result
If the images are correct (type and number) the operator bit and returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
bit and is reentrant and automatically parallelized (on tuple level, channel level, domain level).
bit mask, add image, max image
bit mask, add image, max image
Alternatives
See Also
HALCON 6.0

42 CHAPTER 3. FILTER
Image filters
Module
bit lshift ( Hobject Image, Hobject *ImageLShift, long Shift )
Left shift of all pixels of the image.
The operator bit lshift calculates a “left shift” of all pixels of the input image bit by bit. The semantics of the
“left shift” operation corresponds to that of C (“

3.3. BIT 43
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s).
º ImageMask (output object) . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by combination with mask.
º BitMask (input control) .............................................................integer long
Bit field
Default Value : 128
Value List : BitMask ¾1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096
Value Suggestions : BitMask ¾1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096
Result
If the images are correct (type) the operator bit mask returns the value H MSG TRUE. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
bit mask is reentrant and automatically parallelized (on tuple level, channel level, domain level).
threshold, bit or
bit slice
bit and, bit lshift
Image filters
Possible Successor Functions
Alternatives
See Also
Module
bit not ( Hobject Image, Hobject *ImageNot )
Complement all bits of the pixels.
The operator bit not calculates the “complement” of all pixels of the input image bit by bit. The semantics of
the “complement” operation corresponds to that of C (“”) for the respective types (signed char, unsigned char,
short, int/long). Only the pixels within the definition range of the image are processed.
Several images can be processed in one call. An output image is generated for every input image.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s).
º ImageNot (output object) . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by complement operation.
read_image(&Image0,"affe");
disp_image(Image0,WindowHandle);
bit_not(Image0,&ImageBitN);
disp_image(ImageBitN,WindowHandle);
Example
Result
If the images are correct (type) the operator bit not returns the value H MSG TRUE. The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
bit not is reentrant and automatically parallelized (on tuple level, channel level, domain level).
bit or, bit and, add image
Alternatives
HALCON 6.0

44 CHAPTER 3. FILTER
bit slice, bit mask
Image filters
See Also
Module
bit or ( Hobject Image1, Hobject Image2, Hobject *ImageOr )
Bit-by-bit OR of all pixels of the input images.
The operator bit or calculates the “or” of all pixels of the input images bit by bit. The semantics of the
“or”operation corresponds to that of C for the respective types (signed char, unsigned char, short, int/long). The
images must have the same size and pixel type. The pixels within the definition range of the image in the first
parameter are processed.
Several images can be processed in one call. In this case both input parameters contain the same number of images
which are then processed in pairs. An output image is generated for every pair.
Parameter
º Image1 (input object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s) 1.
º Image2 (input object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s) 2.
º ImageOr (output object) . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by OR-operation.
Example
read_image(&Image0,"affe");
disp_image(Image0,WindowHandle);
read_image(&Image1,"fabrik");
disp_image(Image1,WindowHandle);
bit_or(Image0,Image1,&ImageBitO);
disp_image(ImageBitO,WindowHandle);
Result
If the images are correct (type and number) the operator bit or returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
bit or is reentrant and automatically parallelized (on tuple level, channel level, domain level).
bit and, add image
bit xor, bit and
Image filters
Alternatives
See Also
Module
bit rshift ( Hobject Image, Hobject *ImageRShift, long Shift )
Right shift of all pixels of the image.
The operator bit rshift calculates a “right shift” of all pixels of the input image bit by bit. The semantics of
the “right shift” operation corresponds to that of C (“>>”) for the respective types (signed char, unsigned char,
short, int/long). Only the pixels within the definition range of the image are processed.
Several images can be processed in one call. An output image is generated for every input image.
HALCON/C Reference Manual / 2000-11-15

3.3. BIT 45
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s).
º ImageRShift (output object) . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by shift operation.
º Shift (input control) ................................................................integer long
shift value
Default Value : 3
Value Suggestions : Shift ¾0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 20, 24, 30, 31
Typical Range of Values : 0 Shift 31
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : ´Shift 1µ ´Shift 31µ
Example
bit_rshift(Int2Image,&ReducedInt2Image,8);
convert_image_type(ReducedInt2Image,&ByteImage,"byte");
Result
If the images are correct (type) and Shift has a valid value the operator bit rshift returns the value
H MSG TRUE. The behavior in case of empty input (no input images available) is set via the operator
set system(’no object result’,) If necessary an exception handling is raised.
Parallelization Information
bit rshift is reentrant and automatically parallelized (on tuple level, channel level, domain level).
scale image
bit lshift
Image filters
Alternatives
See Also
Module
bit slice ( Hobject Image, Hobject *ImageSlice, long Bit )
Extract a bit from the pixels.
The operator bit slice extracts a bit level from the input image. The semantics of the “and” operation corresponds
to that of C for the respective types (signed char, unsigned char, short, int/long). Only the pixels within the
definition range of the image are processed.
Several images can be processed in one call. An output image is generated for every input image.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int1 / int2 / int4
Input image(s).
º ImageSlice (output object) . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4
Result image(s) by extraction.
º Bit (input control) ...................................................................integer long
Bit to be selected.
Default Value : 8
Value Suggestions : Bit ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 20, 24, 30, 32
Typical Range of Values : 1 Bit 32
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : ´Bit 1µ ´Bit 32µ
HALCON 6.0

46 CHAPTER 3. FILTER
Example
read_image(&ByteImage,"fabrik");
for (bit=1; bit

3.4. COLOR 47
Parallelization Information
bit xor is reentrant and automatically parallelized (on tuple level, channel level, domain level).
bit or, bit and, add image
bit or, bit and
Image filters
Alternatives
See Also
Module
3.4 Color
rgb1 to gray ( Hobject RGBImage, Hobject *GrayImage )
Transform an RGB image into a gray scale image.
rgb1 to gray transforms an RGB image into a gray scale image. The three channels of the RGB image are
passed as the first three channels of the input image. The image is transformed according to the following formula:
¼¾Ö ·¼ ·¼½
Parameter
º RGBImage (input object) ........................................image(-array) Hobject : byte / int2
Three-channel RBG image.
º GrayImage (output object) ....................................image(-array) Hobject * : byte / int2
Gray scale image.
Example
/* Tranformation from rgb to gray */
read_image(Image,"patras") ;
disp_color(Image,WindowHandle) ;
rgb1_to_gray(Image,&GrayImage) ;
disp_image(GrayImage,WindowHandle);
Parallelization Information
rgb1 to gray is reentrant and automatically parallelized (on tuple level, domain level).
compose3
trans from rgb, rgb3 to gray
Image filters
Possible Predecessor Functions
Alternatives
Module
rgb3 to gray ( Hobject ImageRed, Hobject ImageGreen, Hobject ImageBlue,
Hobject *ImageGray )
Transform an RGB image to a gray scale image.
rgb3 to gray transforms an RGB image into a gray scale image. The three channels of the RGB image are
passed as three separate images. The image is transformed according to the following formula:
¼¾Ö ·¼ ·¼½
HALCON 6.0

48 CHAPTER 3. FILTER
Parameter
º ImageRed (input object) ........................................image(-array) Hobject : byte / int2
Input image (red channel).
º ImageGreen (input object) ......................................image(-array) Hobject : byte / int2
Input image (green channel).
º ImageBlue (input object) .......................................image(-array) Hobject : byte / int2
Input image (blue channel).
º ImageGray (output object) ....................................image(-array) Hobject * : byte / int2
Gray scale image.
Example
/* Tranformation from rgb to gray */
read_image(Image,"patras") ;
disp_color(Image,WindowHandle) ;
decompose3(Image,&Rimage,&Gimage,&Bimage) ;
rgb3_to_gray(Rimage,Gimage,Bimage,&GrayImage) ;
disp_image(GrayImage,WindowHandle);
Parallelization Information
rgb3 to gray is reentrant and automatically parallelized (on tuple level, domain level).
decompose3
rgb1 to gray, trans from rgb
Image filters
Possible Predecessor Functions
Alternatives
Module
trans from rgb ( Hobject ImageRed, Hobject ImageGreen,
Hobject ImageBlue, Hobject *ImageResult1, Hobject *ImageResult2,
Hobject *ImageResult3, const char *ColorSpace )
Transform an image from the RGB color space to an arbitrary color space.
trans from rgb transforms an image from the RGB color space to an arbitrary color space (ColorSpace).
The three channels of the image are passed as three separate images on input and output.
The following transformations are supported:
’yiq’
¼
Á
É
½ ¼
¼¾ ¼ ¼½
¼ ¼¾ ¼¿¿¿
¼¾¼ ¼¾¾ ¼¾
½¼
Ê
½
’argyb’
’ciexyz’
¼
Ê
¼
½ ¼
½ ¼
¼¿¼ ¼ ¼½½
¼¼ ¼¼ ¼¼¼
¼¾ ¼¾ ¼¼
¼ ¼¾ ¼½
¼¾¾ ¼ ¼¼¾
¼¼¾¼ ¼½½ ¼¼
½¼
½¼
Ê
Ê
½
½
HALCON/C Reference Manual / 2000-11-15

3.4. COLOR 49
’hls’
’hsi’
’hsv’
’ihs’
min = min(R,G,B)
max = max(R,G,B)
L = (min + max) / 2
if (max == min)
H = 0
S = 0
else
if (L > 0.5)
S = (max - min) / (2 - max - min)
else
S = (max - min) / (max + min)
fi
if (R == max)
H = ((G - B) / (max - min)) * 60
elif (G == max)
H = (2 + (B - R) / (max - min)) * 60
elif (B == max)
H = (4 + (R - G) / (max - min)) * 60
fi
fi
¼ ½
Å ½
Å ¾
Á½
¼
À Ë
Á
¼
Ô
¾
¼
½ ¼
Ô
½
Ô
½
¾
½Ô
¿
½ Ô¿
½
½
Ô
½
Ô
½
¾
Ô¿
Ž
ÖØÒ
Ô Å¾
Å ½¾ · Å ¾ ¾
Á½ £ Ô ¿
min = min(R,G,B)
max = max(R,G,B)
V = max
if (max == min)
S = 0
H = 0
else
S = (max - min) / max
if (R == max)
H = ((G - B) / (max - min)) * 60
elif (G == max)
H = (2 + (B - R) / (max - min)) * 60
elif (B == max)
H = (4 + (R - G) / (max - min)) * 60
fi
fi
¼
Ê
min = min(R,G,B)
max = max(R,G,B)
I = (R + G + B) / 3
if (I == 0)
H = 0
S = 1
else
S = 1 - min / I
if (S == 0)
H = 0
else
A = (R + R - G - B) / 2
B = (R - G) * (R - G) + (R - B) * (G - B)
½
½
HALCON 6.0

50 CHAPTER 3. FILTER
C = sqrt(B)
if (C == 0)
H = 0
else
H = acos(A / C)
fi
if (B > G)
H = 2 * pi - H
fi
fi
fi
’isfeuklid’ min = min(R,G,B)
max = max(R,G,B)
I = sqrt(R * R + G * G + B * B) / sqrt(3)
if (I == 0)
S = 0
F = 0
else
S = acos(max(1, (R + G + B) / (I * 3))) / (pi / 2)
if (R == min)
F = acos(max(1, B / sqrt(G * G + B * B)))
/ (pi * 3 / 2) + 1 / 3
elif (G == min)
F = acos(max(1, R / sqrt(B * B + R * R)))
/ (pi * 3 / 2) + 2 / 3
else
F = acos(max(1, G / sqrt(R * R + G * G)))
/ (pi * 3 / 2)
fi
fi
’isfdiff’ if (R >= B && B >= G)
I = R
S = R - G
F = (R - B) / 6
elif (R >= G && G >= B)
I = R
S = R - B
F = (2 - (R - G)) / 6
elif (G >= R && R >= B)
I = G
S = G - B
F = (2 + (G - R)) / 6
elif (G >= B && B >= R)
I = G
S = G - R
F = (4 - (G - B)) / 6
elif (B >= G && G >= R)
I = B
S = B - R
F = (4 + (B - G)) / 6
else
I = B
S = B - G
F = (6 + (B - R)) / 6
fi
’cielab’
¼
HALCON/C Reference Manual / 2000-11-15
½ ¼
¼ ¼¾ ¼½
¼¾¾ ¼ ¼¼¾
¼¼¾¼ ¼½½ ¼¼
½¼
Ê
½

3.4. COLOR 51
’i1i2i3’
’ciexyz2’
’ciexyz3’
¼
Á½
Á¾
Á¿
¼
¼
½ ¼
½
¼
½ ¼
Ä ½½ £ ½ ¿ ½
¼¼ £
½
¿
´
¼
¾¼¼ £ ´ ½ ¿
½¼
½ ¿ µ
½
¿
¼¿¿¿ ¼¿¿¿ ¼¿¿¿
½¼ ¼¼ ½¼
¼ ½¼ ¼
¼¾¼ ¼½¼ ¼½¼
¼¿½¼ ¼¼ ¼½½¼
¼¼¼¼ ¼¼ ½¼¾¼
¼½ ¼½ ¼¾¼
¼¾ ¼ ¼½½
¼¼¼¼ ¼¼ ¼
µ
½¼
½¼
½¼
Ê
Ê
Ê
½
½
½
If necessary, certain scalings are performed, e.g., for byte-images [0..1] -¿ [0..255]. In the explanation above all
input and output values, including angles, are assumed to be in the range [0..1].
Parameter
º ImageRed (input object) ...............image(-array) Hobject : byte / int1 / int2 / int4 / real / complex
Input image (red channel).
º ImageGreen (input object) ............image(-array) Hobject : byte / int1 / int2 / int4 / real / complex
Input image (green channel).
º ImageBlue (input object) ..............image(-array) Hobject : byte / int1 / int2 / int4 / real / complex
Input image (blue channel).
º ImageResult1 (output object) . . . . . . image(-array) Hobject * : byte / int1 / int2 / int4 / real / complex
Color-transformed output image (channel 1).
º ImageResult2 (output object) . . . . . . image(-array) Hobject * : byte / int1 / int2 / int4 / real / complex
Color-transformed output image (channel 1).
º ImageResult3 (output object) . . . . . . image(-array) Hobject * : byte / int1 / int2 / int4 / real / complex
Color-transformed output image (channel 1).
º ColorSpace (input control) ...................................................string const char *
Color space of the output image.
Default Value : ’hsv’
Value List : ColorSpace ¾’cielab’, ’hsv’, ’hsi’, ’yiq’, ’argyb’, ’ciexyz’, ’ciexyz2’, ’ciexyz3’, ’hls’, ’ihs’,
’isfeuklid’, ’isfdiff’, ’i1i2i3’
Example
/* Tranformation from rgb to hsv and conversely */
read_image(Image,"patras") ;
disp_color(Image,WindowHandle) ;
decompose3(Image,&Rimage,&Gimage,&Bimage) ;
trans_from_rgb(Rimage,Gimage,Bimage,&Image1,&Image2,&Image3,"hsv") ;
trans_to_rgb(Image1,Image2,Image3,&ImageRed,&ImageGreen,&ImageBlue,"hsv") ;
compose3(ImageRed,ImageGreen,ImageBlue,&Multichannel) ;
disp_color(Multichannel,WindowHandle);
Result
trans from rgb returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
HALCON 6.0

52 CHAPTER 3. FILTER
Parallelization Information
trans from rgb is reentrant and automatically parallelized (on tuple level, domain level).
decompose3
compose3
rgb1 to gray, rgb3 to gray
trans to rgb
Image filters
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
trans to rgb ( Hobject ImageInput1, Hobject ImageInput2,
Hobject ImageInput3, Hobject *ImageRed, Hobject *ImageGreen,
Hobject *ImageBlue, const char *ColorSpace )
Transform an image from an arbitrary color space to the RGB color space.
trans to rgb transforms an image from an arbitrary color space (ColorSpace) to the RGB color space. The
three channels of the image are passed as three separate images on input and output.
The following transformations are supported:
’yiq’
¼
Ê
½ ¼
¼ ¼¾ ¼½
¼ ¼¾¾¼ ¼¿¾
¼ ½½¼½ ½¼
½¼
Á
É
½
’argyb’
¼
Ê
½ ¼
½¼¼ ½¾ ¼¾¾
½¼¼ ¼½ ¼¾¾
½¼¼ ¼¾ ½
½¼
Ê
½
’ciexyz’
¼
Ê
½ ¼
¾¼ ½½ ¼¾
½½½ ¾¼¾ ¼¼¿¿
¼½¿ ¼¿¿¿ ½½¼
½¼
½
’hls’ Hi = integer(H * 6)
Hf = fraction(H * 6)
if (L

3.4. COLOR 53
’hsi’
elif (Hi == 1)
R = min + (1 - Hf) * (max - min)
G = max
B = min
elif (Hi == 2)
R = min
G = max
B = min + Hf * (max - min)
elif (Hi == 3)
R = min
G = min + (1 - Hf) * (max - min)
B = max
elif (Hi == 4)
R = min + Hf * (max - min)
G = min
B = max
elif (Hi == 5)
R = max
G = min
B = min + (1 - Hf) * (max - min)
fi
fi
Å ½Ë £ ×Ò À
Å ¾Ë £ Ó× À
¼
Ê
½ ¼
Á½ Á Ô
¿
Ô
¾
¼
Ô
½ Ô¾
½ Ô¿
½
½
Ô
½ Ô
¾
½
Ô
½
¿
Ô¿
½
¼
Å ½
Å ¾
Á½
½
’hsv’ if (S == 0)
if (H == 0)
R = V
G = V
B = V
else
R = 0
G = 0
B = 0
fi
else
Hi = integer(H)
Hf = fraction(H)
if (Hi == 0)
R = V
G = V * (1 - (S * (1 - Hf)))
B = V * (1 - S)
elif (Hi == 1)
R = V * (1 - (S * Hf))
G = V
B = V * (1 - S)
elif (Hi == 2)
R = V * (1 - S)
G = V
B = V * (1 - (S * (1 - Hf)))
elif (Hi == 3)
HALCON 6.0

54 CHAPTER 3. FILTER
fi
R = V * (1 - S)
G = V * (1 - (S * Hf))
B = V
elif (Hi == 4)
R = V * (1 - (S * (1 - Hf)))
G = V * (1 - S)
B = V
elif (Hi == 5)
R = V
G = V * (1 - S)
B = V * (1 - (S * Hf))
fi
If necessary, certain scalings are performed, e.g., for byte-images [0..1] -¿ [0..255]. In the explanation above all
input and output values, including angles, are assumed to be in the range [0..1].
Parameter
º ImageInput1 (input object) ...............................image(-array) Hobject : byte / int4 / real
Input image (channel 1).
º ImageInput2 (input object) ...............................image(-array) Hobject : byte / int4 / real
Input image (channel 2).
º ImageInput3 (input object) ...............................image(-array) Hobject : byte / int4 / real
Input image (channel 3).
º ImageRed (output object) ................................image(-array) Hobject * : byte / int4 / real
Red channel.
º ImageGreen (output object) .............................image(-array) Hobject * : byte / int4 / real
Green channel.
º ImageBlue (output object) ..............................image(-array) Hobject * : byte / int4 / real
Blue channel.
º ColorSpace (input control) ...................................................string const char *
Color space of the input image.
Default Value : ’hsv’
Value List : ColorSpace ¾’hsi’, ’yiq’, ’argyb’, ’ciexyz’, ’hls’, ’hsv’
Example
/* Tranformation from rgb to hsv and conversely */
read_image(Image,"patras") ;
disp_color(Image,WindowHandle) ;
decompose3(Image,&Rimage,&Gimage,&Bimage) ;
trans_from_rgb(Rimage,Gimage,Bimage,&Image1,&Image2,&Image3,"hsv") ;
trans_to_rgb(Image1,Image2,Image3,&ImageRed,&ImageGreen,&ImageBlue,"hsv") ;
compose3(ImageRed,ImageGreen,ImageBlue,&Multichannel) ;
disp_color(Multichannel,WindowHandle);
Result
trans to rgb returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
trans to rgb is reentrant and automatically parallelized (on tuple level, domain level).
decompose3
compose3, disp color
decompose3
Image filters
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 55
3.5 Edges
close edges ( Hobject Edges, Hobject EdgeImage, Hobject *RegionResult,
long MinAmplitude )
Close edge gaps using the edge amplitude image.
close edges closes gaps in the output of an edge detector, and thus tries to produce complete object contours.
This is done by examining the neighbors of each edge point to determine the point with maximum amplitude (i.e.,
maximum gradient), and adding the point to the edge if its amplitude is larger than the minimum amplitude passed
in MinAmplitude. This operator expects as input the edges (Edges) and amplitude image (EdgeImage)
returned by typical edge operators, such as edges image or sobel amp. close edges does not take into
account the edge directions that may be returned by an edge operator. Thus, in areas where the gradient is almost
constant the edges may become rather “wiggly.”
Parameter
º Edges (input object) .......................................................region(-array) Hobject
Region containing one pixel thick edges.
º EdgeImage (input object) ...................................................image Hobject : byte
Edge amplitude (gradient) image.
º RegionResult (output object) ...........................................region(-array) Hobject *
Region containing closed edges.
º MinAmplitude (input control) ......................................................integer long
Minimum edge amplitude.
Default Value : 16
Value Suggestions : MinAmplitude ¾5, 8, 10, 12, 16, 20, 25, 30, 40, 50
Typical Range of Values : 1 MinAmplitude 255
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinAmplitude 0
Example
sobel_amp(Image,&EdgeAmp,"sum_abs",5);
threshold(EdgeAmp,&EdgeRegion,40.0,255.0);
skeleton(EdgeRegion,&ThinEdge);
close_edge1(ThinEdge,EdgeAmp,&CloseEdges,15);
skeleton(CloseEdges,&ThinCloseEdges);
Result
close edges returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
close edges is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
edges image, sobel amp, threshold, skeleton
skeleton
Possible Successor Functions
Alternatives
close edges length, dilation1, closing
gray skeleton
Image filters
See Also
Module
HALCON 6.0

56 CHAPTER 3. FILTER
close edges length ( Hobject Edges, Hobject Gradient,
Hobject *ClosedEdges, long MinAmplitude, long MaxGapLength )
Close edge gaps using the edge amplitude image.
close edges length closes gaps in the output of an edge detector, and thus tries to produce complete object
contours. This operator expects as input the edges (Edges) and amplitude image (Gradient) returned by typical
edge operators, such as edges image or sobel amp.
Contours are closed in two steps: First, one pixel wide gaps in the input contours are closed, and isolated points are
eliminated. After this, open contours are extended by up to MaxGapLength points by adding edge points until
either the contour is closed or no more significant edge points can be found. A gradient is regarded as significant if
it is larger than MinAmplitude. The neighboring points examined as possible new edge points are the point in
the direction of the contour and its two adjacent points in an 8-neighborhood. For each of these points, the sum of
its gradient and the maximum gradient of that points three possible neighbors is calculated (look ahead of length
1). The point with the maximum sum is then chosen as the new edge point.
Attention
In the current implementation MinAmplitude is ignored; any gradient value larger than zero is regarded as
significant.
Parameter
º Edges (input object) .......................................................region(-array) Hobject
Region containing one pixel thick edges.
º Gradient (input object) .....................................................image Hobject : byte
Edge amplitude (gradient) image.
º ClosedEdges (output object) ............................................region(-array) Hobject *
Region containing closed edges.
º MinAmplitude (input control) ......................................................integer long
Minimum edge amplitude.
Default Value : 16
Value Suggestions : MinAmplitude ¾5, 8, 10, 12, 16, 20, 25, 30, 40, 50
Typical Range of Values : 1 MinAmplitude 255
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinAmplitude 0
º MaxGapLength (input control) ......................................................integer long
Maximal number of points by which edges are extended.
Default Value : 3
Value Suggestions : MaxGapLength ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 20, 30, 40, 50, 70, 100
Typical Range of Values : 1 MaxGapLength 200
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MaxGapLength 0
Example
sobel_amp(Image,&EdgeAmp,"sum_abs",5);
threshold(EdgeAmp,&EdgeRegion,40.0,255.0);
skeleton(EdgeRegion,&ThinEdge);
close_edge2(ThinEdge,EdgeAmp,&CloseEdges,15,3);
Result
close edges length returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour
can be set via set system(’no object result’,). If necessary, an exception handling is
raised.
Parallelization Information
close edges length is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
edges image, sobel amp, threshold, skeleton
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 57
close edges, dilation1, closing
Alternatives
Bibliography
M. Üsbeck: “Untersuchungen zur echtzeitfähigen Segmentierung”; Studienarbeit, Bayerisches Forschungszentrum
für Wissensbasierte Systeme (FORWISS), Erlangen, 1993.
Image filters
Module
derivate gauss ( Hobject Image, Hobject *DerivGauss, double Sigma,
const char *Component )
Convolve an image with derivatives of the Gaussian.
derivate gauss convolves an image with the derivatives of a Gaussian and calculates various features derived
thereof. Possible values for Component are:
’none’ Smoothing only.
’x’ First derivative along x.
’y’ First derivative along y.
’gradient’ Absolute value of the gradient.
¼´Ü ݵ
¼´Ü ݵ
¼´Ü ݵ
´Ü ݵ
Ü
´Ü ݵ
Ý
×
´Ü ݵ ¾
Ü
´Ü ݵ ¾
Ý
’xx’ Second derivative along x.
’yy’ Second derivative along y.
’xy’ Second derivative along x and y.
’xxx’ Third derivative along x.
’yyy’ Third derivative along y.
’xxy’ Third derivative along x, x and y.
’xyy’ Third derivative along x, y and y.
’det’ Determinant of the Hessian matrix:
¼´Ü ݵ ¾ ´Ü ݵ
Ü ¾
¼´Ü ݵ ¾ ´Ü ݵ
Ý ¾
¼´Ü ݵ ¾ ´Ü ݵ
ÜÝ
¼´Ü ݵ ¿ ´Ü ݵ
Ü ¿
¼´Ü ݵ ¿ ´Ü ݵ
Ý ¿
¼´Ü ݵ ¿ ´Ü ݵ
Ü ¾ Ý
¼´Ü ݵ ¿ ´Ü ݵ
ÜÝ ¾
Ì ¾ ´Ü ݵ ¾ ´Ü ݵ
Ü ¾ Ý ¾
¾ ´Ü ݵ
ÝÜ
¾
HALCON 6.0

58 CHAPTER 3. FILTER
’laplace’ Laplace operator (trace of the Hessian matrix):
’mean curvatue’ Mean curvature À
ÌÊ ¾ ´Ü ݵ
Ü ¾ · ¾ ´Ü ݵ
Ý ¾
´½ ·
¾
´½ ·
´Ü ݵ¾
µ ¾ ´Ü ݵ
Ü Ý ¾
´Ü ݵ
Ü
´Ü ݵ¾
´½ ·
Ü
À ·
´Ü ݵ ¾ ´Ü ݵ
Ý ÝÜ
´Ü ݵ¾
µ ¾ ´Ü ݵ
Ý Ü ¾
·
À ½ ¾ ´ ÑÒ · ÑÜ µ
´Ü ݵ¾
µ ¿ ¾
Ý
’gauss curvatue’ Gaussian curvature Ã
’eigenvalue1’ First eigenvalue
Ã
´½ · ´Üݵ¾
Ü
Ì
· ´Üݵ¾
Ý
µ ¾
’eigenvalue2’ Second eigenvalue
½ ·
¾ ´Üݵ
Ü ¾
×
· ¾ ´Üݵ
Ý ¾
¾
¾ ´¾ ´Ü ݵ ¾ ´Ü ݵ
Ü ¾ Ý ¾
¾ ´Ü ݵ ¾
µ
ÝÜ
¾
¾ ´Üݵ
Ü ¾
’main1 curvature’ First principal curvature
×
’main2 curvature’ Second principal curvature
· ¾ ´Üݵ
Ý ¾
¾
¾ ´¾ ´Ü ݵ ¾ ´Ü ݵ
Ü ¾ Ý ¾
ÑÜ À ·
Ô
À
¾
Ã
ÑÒ À
Ô
À
¾
Ã
’kitchen rosenfeld’ Second derivative perpendicular to the gradient
¾ ´Üݵ ´Üݵ ¾
Ü ¾ Ý
’2nd ddg’ Second derivative along the gradient
¾ ´Üݵ ´Üݵ ¾
Ü ¾ Ü
· ¾ ´Üݵ ´Üݵ ¾
Ý ¾
´Üݵ ¾
Ü
Ü
¾ ¾ ´Üݵ
ÝÜ
· ´Üݵ¾
Ý
·¾ ´Üݵ ´Üݵ
Ü Ý
´Üݵ ¾
Ü
¾ ´Üݵ
ÝÜ
· ´Üݵ¾
Ý
’de saint venant’ Second derivative along and perpendicular to the gradient
´Üݵ
Ü
´Üݵ
Ý
´ ¾ ´Üݵ
Ü ¾
¾ ´Üݵ
Ý ¾ µ ´ ´Üݵ¾
Ü
´Üݵ ¾
Ü
· ´Üݵ¾
Ý
¾ ´Ü ݵ ¾
µ
ÝÜ
´Üݵ ¾
Ü
´Üݵ ¾
Ý
· ¾ ´Üݵ ´Üݵ ¾
Ý ¾ Ý
´Üݵ ¾
Ý
µ ¾ ´Üݵ
ÜÝ
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 59
Parameter
º Image (input object) . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real
Input image.
º DerivGauss (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : real
Filtered result image.
º Sigma (input control) .................................................................real double
Sigma of the Gaussian.
Default Value : 1.0
Value Suggestions : Sigma ¾0.7, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.2 Sigma 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.0
º Component (input control) .....................................................string const char *
Derivative or feature to be calculated.
Default Value : ’x’
Value List : Component ¾’none’, ’x’, ’y’, ’gradient’, ’xx’, ’yy’, ’xy’, ’xxx’, ’yyy’, ’xxy’, ’xyy’, ’det’,
’mean curvature’, ’gauss curvature’, ’eigenvalue1’, ’eigenvalue2’, ’main1 curvature’, ’main2 curvature’,
’kitchen rosenfeld’, ’zuniga haralick’, ”2nd ddg”, ’de saint venant’, ’area’, ’laplace’, ’gradient dir’,
’eigenvec dir’
read_image(&Image,"mreut");
derivate_gauss(Image,&Gauss,3.0,"x");
zero_crossing(Gauss,&ZeroCrossings);
Example
Parallelization Information
derivate gauss is reentrant and automatically parallelized (on tuple level, channel level, domain level).
zero crossing, dual threshold
Possible Successor Functions
Alternatives
laplace, laplace of gauss, gauss image, smooth image
zero crossing, dual threshold
See Also
Bibliography
K. Voss H. Süse; “Praktische Bildverarbeitung” Hanser Verlag; München, Wien; 1991; Seite 88.
Image filters
Module
diff of gauss ( Hobject Image, Hobject *DiffOfGauss, double Sigma,
double SigFactor )
Approximate the LoG operator (Laplace of Gaussian).
diff of gauss approximates the Laplace-of-Gauss operator by a difference of Gaussians. The standard deviations
of these Gaussians can be calculated, according to Marr, from the Parameter Sigma of the LoG and the ratio
of the two standard deviations (SigFactor)as:
×ѽ
Ö
ËÑ
¾ ÐÓ ´ ½
Ë ØÓÖ µ
ËØÓÖ ¾ ½
×Ѿ
×ѽ
ËØÓÖ
ÇÙ×× ´ÁÑ £ Ù××´×ѽµµ ´ÁÑ £ Ù××´×Ѿµµ
HALCON 6.0

60 CHAPTER 3. FILTER
For a ËØÓÖ ½, according to Marr, an approximation to the Mexican-Hat-Operator results. The resulting
image is stored in DiffOfGauss.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image
º DiffOfGauss (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * :int2
LoG image.
º Sigma (input control) .................................................................real double
Smoothing parameter of the Laplace operator to approximate.
Default Value : 3.0
Value Suggestions : Sigma ¾2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.2 Sigma 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.0
º SigFactor (input control) ...........................................................real double
Ratio of the standard deviations used (Marr recommends 1.6).
Default Value : 1.6
Typical Range of Values : 0.1 SigFactor 10.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : SigFactor 0.0
Example
read_image(&Image,"mreut");
diff_of_gauss(Image,&Laplace,2.0,1.6);
zero_crossing(Laplace,&ZeroCrossings);
Complexity
The execution time depends linearly on the number of pixels and the size of sigma.
Result
diff of gauss returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
diff of gauss is reentrant and automatically parallelized (on tuple level, channel level, domain level).
zero crossing, dual threshold
laplace, derivate gauss
Possible Successor Functions
Alternatives
Bibliography
D. Marr: “Vision (A computational investigation into human representation and processing of visual information)”;
New York, W.H. Freeman and Company; 1982.
Module
Image filters
edges image ( Hobject Image, Hobject *ImaAmp, Hobject *ImaDir,
const char *Filter, double Alpha, const char *NMS, long Low, long High )
Extract edges using Deriche, Lanser, Shen, or Canny filters.
edges image detects step edges using recursively implemented filters (according to Deriche, Lanser and Shen)
or the conventionally implemented “derivative of Gaussian” filter (using filter masks) proposed by Canny. Thus,
the following edge operators are available:
’deriche1’, ’lanser1’, ’deriche1 int4’, ’deriche2’, ’lanser2’, ’lanser2 int4’, ’shen’, ’mshen’, and ’canny’ (parameter
Filter).
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 61
The edge amplitudes (gradient magnitude) and directions are returned in ImaAmp and ImaDir, respectively. The
edge operator ’lanser2’ is also available for int4-images, and returns the signed filter response instead of its absolute
value. This behavior can be obtained for byte-images as well by selecting ’lanser2 int4’ as filter. This can be used
to calculate the second derivative of an image by applying edges image (with parameter ’lanser2’) to the signed
first derivative. Edge directions are stored in 2-degree steps, i.e., an edge direction of Ü degrees with respect to the
horizontal axis is stored as ܾ in the edge direction image. Furthermore, the direction of the change of intensity
is taken into account. Let Ü Ý ℄ denote the image gradient. Then the following edge directions are returned as
Ö¾:
intensity increase
Ü Ý
edge direction Ö
from bottom to top ¼· ¼
from lower right to upper left · ℄¼ ¼
from right to left ·¼ ¼
from upper right to lower left ·· ℄¼ ½¼
from top to bottom ¼· ½¼
from upper left to lower right · ℄½¼ ¾¼
from left to right ·¼ ¾¼
from lower left to upper right ℄¾¼ ¿¼
Points with edge amplitude 0 are assigned the edge direction 255 (undefined direction).
The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarily, and can be estimated by calling
T info edges for concrete values of the parameter Alpha. It decreases for increasing Alpha for the Deriche,
Lanser and Shen filters and increases for the Canny filter, where it is the standard deviation of the Gaussian on
which the Canny operator is based. “Wide” filters exhibit a larger invariance to noise, but also a decreased ability
to detect small details. Non-recursive filters, such as the Canny filter, are realized using filter masks, and thus the
execution time increases for increasing filter width. In contrast, the execution time for recursive filters does not
depend on the filter width. Thus, arbitrary filter widths are possible using the Deriche, Lanser and Shen filters
without increasing the run time of the operator. The resulting advantage in speed compared to the Canny operator
naturally increases for larger filter widths. As border treatment, the recursive operators assume that the images to
be zero outside of the image, while the Canny operator repeats the gray value at the image’s border. Comparable
filter widths can be obtained by the following choices of Alpha:
ÐÔ´¼ÐÒ×Ö½ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ö¾ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼ÐÒ×Ö¾ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼×Ò ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ñ×Ò ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ù×× ¼ µ ½ÐÔ´¼Ö½ ¼ µ
The originally proposed recursive filters (’deriche1’, ’deriche2’, ’shen’) return a biased estimate of the amplitude
of diagonal edges. This bias is removed in the corresponding modified version of the operators (’lanser1’, ’lanser2’
und ’mshen’), while maintaining the same execution speed.
For relatively small filter widths (½½ ¢ ½½), i.e., for Alpha (’lanser2’ = 0.5), all filters yield similar results. Only for
“wider” filters differences begin to appear: the Shen filters begin to yield qualitatively inferior results. However,
they are the fastest of the implemented operators — closely followed by the Deriche operators.
edges image optionally offers to apply a non-maximum-suppression (NMS = ’nms’/’inms’/’hvnms’; ’none’ if
not desired) and hysteresis threshold operation (Low,High; at least one negative if not desired) to the resulting
edge image. Conceptually, this corresponds to the following calls:
nonmax suppression dir(...,NMS,...) º
hysteresis threshold(...,Low,High,999,...)
However, this calling sequence would return appropriately modified regions, whereas edges image marks suppressed
edge points by 0 in the amplitude and 255 in the direction image, while leaving the region of the image
unchanged.
HALCON 6.0

62 CHAPTER 3. FILTER
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int4 / int2
Input image.
º ImaAmp (output object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int4 / int2
Edge amplitude (gradient magnitude) image.
º ImaDir (output object) .........................................image(-array) Hobject * : direction
Edge direction image.
º Filter (input control) .........................................................string const char *
Edge operator to be applied.
Default Value : ’lanser2’
Value List : Filter ¾’deriche1’, ’lanser1’, ’deriche1 int4’, ’deriche2’, ’lanser2’, ’lanser2 int4’, ’shen’,
’mshen’, ’canny’
º Alpha (input control) .................................................................real double
Filter parameter: small values result in strong smoothing, and thus less detail (opposite for ’canny’).
Default Value : 0.5
Value Suggestions : Alpha ¾0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.9, 1.1
Typical Range of Values : 0.2 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0.0
º NMS (input control) .............................................................string const char *
Non-maximum suppression (’none’, if not desired).
Default Value : ’nms’
Value List : NMS ¾’nms’, ’inms’, ’hvnms’, ’none’
º Low (input control) ...................................................................integer long
Lower threshold for the hysteresis threshold operation (negative, if no thresholding is desired).
Default Value : 20
Value Suggestions : Low ¾5, 10, 15, 20, 25, 30, 40
Typical Range of Values : 1 Low 255
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : ´Low 1µ ´Low 0µ
º High (input control) .................................................................integer long
Upper threshold for the hysteresis threshold operation (negative, if no thresholding is desired).
Default Value : 40
Value Suggestions : High ¾10, 15, 20, 25, 30, 40, 50, 60, 70
Typical Range of Values : 1 High 255
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : ´´High 1µ ´High 0µµ ´High Lowµ
Example
read_image(&Image,"fabrik");
edges_image(Image,&Amp,&Dir,"lanser2",0.5,"none",-1,-1);
hysteresis_threshold(Amp,&Margin,20,30,30);
Result
edges image returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
input is empty the behaviour can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
edges image is reentrant and automatically parallelized (on tuple level, channel level).
T info edges
Possible Predecessor Functions
Possible Successor Functions
threshold, hysteresis threshold, close edges length
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 63
Alternatives
sobel dir, frei dir, kirsch dir, prewitt dir, robinson dir
See Also
T info edges, nonmax suppression amp, hysteresis threshold, bandpass image
Bibliography
S.Lanser, W.Eckstein: “Eine Modifikation des Deriche-Verfahrens zur Kantendetektion”; 13. DAGM-Symposium,
München; Informatik Fachberichte 290; Seite 151 - 158; Springer-Verlag; 1991.
S.Lanser: “Detektion von Stufenkanten mittels rekursiver Filter nach Deriche”; Diplomarbeit; Technische Universität
München, Institut für Informatik, Lehrstuhl Prof. Radig; 1991.
J.Canny: “Finding Edges and Lines in Images”; Report, AI-TR-720; M.I.T. Artificial Intelligence Lab., Cambridge;
1983.
J.Canny: “A Computational Approach to Edge Detection”; IEEE Transactions on Pattern Analysis and Machine
Intelligence; PAMI-8, vol. 6; S. 679-698; 1986.
R.Deriche: “Using Canny’s Criteria to Derive a Recursively Implemented Optimal Edge Detector”; International
Journal of Computer Vision; vol. 1, no. 2; S. 167-187; 1987.
R.Deriche: “Optimal Edge Detection Using Recursive Filtering”; Proc. of the First International Conference on
Computer Vision, London; S. 501-505; 1987.
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelligence;
PAMI-12, no. 1; S. 78-87; 1990.
S.Castan, J.Zhao und J.Shen: “Optimal Filter for Edge Detection Methods and Results”; Proc. of the First European
Conference on Computer Vision, Antibes; Lecture Notes on computer Science; no. 427; S. 12-17; Springer-
Verlag; 1990.
Module
Image filters
edges sub pix ( Hobject Image, Hobject *Edges, const char *Filter,
double Alpha, long Low, long High )
Extract sub-pixel precise edges using Deriche, Lanser, Shen, or Canny filters.
edges sub pix detects step edges using recursively implemented filters (according to Deriche, Lanser and Shen)
or the conventionally implemented “derivative of Gaussian” filter (using filter masks) proposed by Canny. Thus,
the following edge operators are available:
’deriche1’, ’lanser1’, ’deriche1 int4’, ’deriche2’, ’lanser2’, ’lanser2 int4’, ’shen’, ’mshen’, and ’canny’
(parameter Filter).
The extracted edges are returned as sub-pixel precise XLD contours in Edges. For each edge point the following
attributes are defined (see get contour attrib xld):
’angle’ Edge direction (modulo )
’response’ Edge amplitude (gradient magnitude)
The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarily, and can be estimated by calling
T info edges for concrete values of the parameter Alpha. It decreases for increasing Alpha for the Deriche,
Lanser and Shen filters and increases for the Canny filter, where it is the standard deviation of the Gaussian on
which the Canny operator is based. “Wide” filters exhibit a larger invariance to noise, but also a decreased ability
to detect small details. Non-recursive filters, such as the Canny filter, are realized using filter masks, and thus the
execution time increases for increasing filter width. In contrast, the execution time for recursive filters does not
depend on the filter width. Thus, arbitrary filter widths are possible using the Deriche, Lanser and Shen filters
without increasing the run time of the operator. The resulting advantage in speed compared to the Canny operator
naturally increases for larger filter widths. As border treatment, the recursive operators assume that the images to
be zero outside of the image, while the Canny operator repeats the gray value at the image’s border. Comparable
filter widths can be obtained by the following choices of Alpha:
HALCON 6.0

64 CHAPTER 3. FILTER
ÐÔ´¼ÐÒ×Ö½ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ö¾ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼ÐÒ×Ö¾ ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼×Ò ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ñ×Ò ¼ µ ÐÔ´¼Ö½ ¼ µ¾
ÐÔ´¼Ù×× ¼ µ ½ÐÔ´¼Ö½ ¼ µ
The originally proposed recursive filters (’deriche1’, ’deriche2’, ’shen’) return a biased estimate of the amplitude
of diagonal edges. This bias is removed in the corresponding modified version of the operators (’lanser1’, ’lanser2’
und ’mshen’), while maintaining the same execution speed.
For relatively small filter widths (½½ ¢ ½½), i.e., for Alpha (’lanser2’ = 0.5), all filters yield similar results. Only for
“wider” filters differences begin to appear: the Shen filters begin to yield qualitatively inferior results. However,
they are the fastest of the implemented operators — closely followed by the Deriche operators.
edges sub pix links the edge points into edges by using an algorithm similar to a hysteresis threshold operation,
whichisalsousedinlines gauss. Points with an amplitude larger than High are immediately accepted as
belonging to an edge, while points with an amplitude smaller than Low are rejected. All other points are accepted
as edges if they are connected to accepted edge points (see also lines gauss and hysteresis threshold).
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º Edges (output object) ....................................................xld cont-array Hobject *
Extracted edges.
º Filter (input control) .........................................................string const char *
Edge operator to be applied.
Default Value : ’lanser2’
Value List : Filter ¾’deriche1’, ’lanser1’, ’deriche2’, ’lanser2’, ’shen’, ’mshen’, ’canny’, ’sobel’
º Alpha (input control) .................................................................real double
Filter parameter: small values result in strong smoothing, and thus less detail (opposite for ’canny’).
Default Value : 0.5
Value Suggestions : Alpha ¾0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.9, 1.1
Typical Range of Values : 0.2 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0.0
º Low (input control) ...................................................................integer long
Lower threshold for the hysteresis threshold operation.
Default Value : 20
Value Suggestions : Low ¾5, 10, 15, 20, 25, 30, 40
Typical Range of Values : 1 Low 255
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : Low 0
º High (input control) .................................................................integer long
Upper threshold for the hysteresis threshold operation.
Default Value : 40
Value Suggestions : High ¾10, 15, 20, 25, 30, 40, 50, 60, 70
Typical Range of Values : 1 High 255
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : ´High 0µ ´High Lowµ
Example
read_image(&Image,"fabrik");
edges_sub_pix(Image,&Edges,"lanser2",0.5,20,40);
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 65
Result
edges sub pix returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
input is empty the behaviour can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
edges sub pix is reentrant and automatically parallelized (on tuple level).
Alternatives
sobel dir, frei dir, kirsch dir, prewitt dir, robinson dir, edges image
See Also
T info edges, hysteresis threshold, bandpass image, lines gauss, lines facet
Bibliography
S.Lanser, W.Eckstein: “Eine Modifikation des Deriche-Verfahrens zur Kantendetektion”; 13. DAGM-Symposium,
München; Informatik Fachberichte 290; Seite 151 - 158; Springer-Verlag; 1991.
S.Lanser: “Detektion von Stufenkanten mittels rekursiver Filter nach Deriche”; Diplomarbeit; Technische Universität
München, Institut für Informatik, Lehrstuhl Prof. Radig; 1991.
J.Canny: “Finding Edges and Lines in Images”; Report, AI-TR-720; M.I.T. Artificial Intelligence Lab., Cambridge;
1983.
J.Canny: “A Computational Approach to Edge Detection”; IEEE Transactions on Pattern Analysis and Machine
Intelligence; PAMI-8, vol. 6; S. 679-698; 1986.
R.Deriche: “Using Canny’s Criteria to Derive a Recursively Implemented Optimal Edge Detector”; International
Journal of Computer Vision; vol. 1, no. 2; S. 167-187; 1987.
R.Deriche: “Optimal Edge Detection Using Recursive Filtering”; Proc. of the First International Conference on
Computer Vision, London; S. 501-505; 1987.
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelligence;
PAMI-12, no. 1; S. 78-87; 1990.
S.Castan, J.Zhao und J.Shen: “Optimal Filter for Edge Detection Methods and Results”; Proc. of the First European
Conference on Computer Vision, Antibes; Lecture Notes on computer Science; no. 427; S. 12-17; Springer-
Verlag; 1990.
Module
Sub-pixel operators
frei amp ( Hobject Image, Hobject *ImageEdgeAmp )
Detect edges (amplitude) using the Frei-Chen operator.
frei amp calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
½ ½ ½
¼ ¼ ¼
½ ½ ½
½ ¼ ½
½ ¼ ½
½ ¼ ½
The result image contains the maximum response of the masks and .
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
HALCON 6.0

66 CHAPTER 3. FILTER
Example
read_image(&Image,"fabrik");
frei_amp(Image,&Frei_amp);
threshold(Frei_amp,&Edges,128,255);
Result
frei amp always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
frei amp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Alternatives
sobel amp, kirsch amp, prewitt amp, robinson amp, roberts
bandpass image, laplace of gauss
Image filters
See Also
Module
frei dir ( Hobject Image, Hobject *ImageEdgeAmp, Hobject *ImageEdgeDir )
Detect edges (amplitude and direction) using the Frei-Chen operator.
frei dir calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
Ô
½ ¾ ½
¼ ¼ ¼
Ô
½ ¾ ½
½ ¼ ½
Ô
¾ ¼
Ô
¾
½ ¼ ½
The result image contains the maximum response of the masks and . The edge directions are returned in
ImageEdgeDir, and are stored in 2-degree steps, i.e., an edge direction of Ü degrees with respect to the horizontal
axis is stored as ܾ in the edge direction image. Furthermore, the direction of the change of intensity is taken into
account. Let Ü Ý ℄ denote the image gradient. Then the following edge directions are returned as Ö¾:
intensity increase
Ü Ý
edge direction Ö
from bottom to top ¼· ¼
from lower right to upper left · ℄¼ ¼
from right to left ·¼ ¼
from upper right to lower left ·· ℄¼ ½¼
from top to bottom ¼· ½¼
from upper left to lower right · ℄½¼ ¾¼
from left to right ·¼ ¾¼
from lower left to upper right ℄¾¼ ¿¼
Points with edge amplitude 0 are assigned the edge direction 255 (undefined direction).
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 67
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Edge amplitude (gradient magnitude) image.
º ImageEdgeDir (output object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : direction
Edge direction image.
Example
read_image(&Image,"fabrik");
frei_dir(Image,&Frei_dirA,&Frei_dirD);
threshold(Frei_dirA,&Res,128,255);
Result
frei dir always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
frei dir is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Possible Successor Functions
hysteresis threshold, threshold, gray skeleton, nonmax suppression dir,
close edges, close edges length
Alternatives
edges image, sobel dir, robinson dir, prewitt dir, kirsch dir
bandpass image, laplace of gauss
Image filters
See Also
Module
highpass image ( Hobject Image, Hobject *Highpass, long Width,
long Height )
Extract high frequency components from an image.
highpass image extracts high frequency components in an image by applying a linear filter with the following
matrix (in case of a ¢ matrix):
½ ½ ½ ½ ½ ½ ½
½ ½ ½ ½ ½ ½ ½
½ ½ ½ ¿ ½ ½ ½
½ ½ ½ ½ ½ ½ ½
½ ½ ½ ½ ½ ½ ½
This corresponds to applying a mean operator (mean image), and then subtracting the original gray value. A
value of 128 is added to the result, i.e., zero crossings occur for 128.
This filter emphasizes high frequency components (edges and corners). The cutoff frequency is determined by the
size (Height ¢ Width) of the filter matrix: the larger the matrix, the smaller the cutoff frequency is.
At the image borders the pixels’ gray values are mirrored. In case of over- or underflow the gray values are clipped
(255 and 0, resp.).
Attention
If even values are passed for Height or Width, the operator uses the next larger odd value instead. Thus, the
center of the filter mask is always uniquely determined.
HALCON 6.0

68 CHAPTER 3. FILTER
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º Highpass (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
High-pass-filtered result image.
º Width (input control) ...............................................................extent.x long
Width of the filter mask.
Default Value : 9
Value Suggestions : Width ¾3, 5, 7, 9, 11, 13, 17, 21, 29, 41, 51, 73, 101
Typical Range of Values : 3 Width 501
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Width 3µ odd´Widthµ
º Height (input control) ..............................................................extent.y long
Height of the filter mask.
Default Value : 9
Value Suggestions : Height ¾3, 5, 7, 9, 11, 13, 17, 21, 29, 41, 51, 73, 101
Typical Range of Values : 3 Height 501
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Height 3µ odd´Heightµ
Example
highpass_image(Image,&Highpass,7,5);
threshold(Highpass,&Region,60.0,255.0);
skeleton(Region,&Skeleton);
Result
highpass image returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
highpass image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
threshold, skeleton
Possible Successor Functions
Alternatives
mean image, sub image, convol image, bandpass image
dyn threshold
Image filters
See Also
Module
T info edges ( Htuple Filter, Htuple Mode, Htuple Alpha, Htuple *Size,
Htuple *Coeffs )
Estimate the width of a filter in edges image.
T info edges returns an estimate of the width of any of the filters used in edges image. To do so, the
corresponding continuous impulse responses of the filters are sampled until the first filter coefficient is smaller than
five percent of the largest coefficient. Alpha is the filter parameter (see edges image). Seven edge operators
are supported (parameter Filter):
’deriche1’, ’lanser1’, ’deriche2’, ’lanser2’, ’shen’, ’mshen’ und ’canny’.
The parameter Mode (’edge’/’smooth’) is used to determine whether the corresponding edge or smoothing operator
is to be sampled. The Canny operator (which uses the Gaussian for smoothing) is implemented using conventional
filter masks, while all other filters are implemented recursively. Therefore, for the Canny filter the coefficients of
the one-dimensional impulse responses ´Òµ with Ò ¼ are returned in Coeffs in addition to the filter width.
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 69
Parameter
º Filter (input control) .................................................string Htuple . const char *
Name of the edge operator.
Default Value : ’lanser2’
Value List : Filter ¾’deriche1’, ’lanser1’, ’deriche2’, ’lanser2’, ’shen’, ’mshen’, ’canny’
º Mode (input control) ....................................................string Htuple . const char *
1D edge filter (’edge’) or 1D smoothing filter (’smooth’).
Default Value : ’edge’
Value List : Mode ¾’edge’, ’smooth’
º Alpha (input control) .........................................................real Htuple . double
Filter parameter: small values result in strong smoothing, and thus less detail (opposite for ’canny’).
Default Value : 0.5
Typical Range of Values : 0.2 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0.0
º Size (output control) .......................................................integer Htuple . long *
Filter width in pixels.
º Coeffs (output control) ..............................................integer-array Htuple . long *
For Canny filters: Coefficients of the “positive” half of the 1D impulse response.
Example
read_image(&Image,"fabrik");
info_edges("lanser2","edge",0.5,Size,Coeffs) ;
edges_image(Image,&Amp,&Dir,"lanser2",0.5,"none",-1,-1);
hysteresis_threshold(Amp,&Margin,20,30,30);
Result
T info edges returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
T info edges is reentrant and processed without parallelization.
Possible Successor Functions
edges image, threshold, skeleton
edges image
Image filters
See Also
Module
kirsch amp ( Hobject Image, Hobject *ImageEdgeAmp )
Detect edges (amplitude) using the Kirsch operator.
kirsch amp calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
¿ ¿
¿ ¼
¿ ¿
¿
¿ ¼
¿ ¿ ¿
¿ ¼ ¿
¿ ¿ ¿
HALCON 6.0

70 CHAPTER 3. FILTER
¿
¼ ¿
¿ ¿ ¿
¿ ¿
¼ ¿
¿ ¿
¿ ¿ ¿
¼ ¿
¿
¿ ¿ ¿
¿ ¼ ¿
¿ ¿ ¿
¿ ¼
¿
The result image contains the maximum response of all masks.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageEdgeAmp (output object) ...............................image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
read_image(&Image,"fabrik");
kirsch_amp(Image,&Kirsch_amp);
threshold(Kirsch_amp,&Edges,128,255);
Example
Result
kirsch amp always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
kirsch amp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Alternatives
sobel amp, frei amp, prewitt amp, robinson amp, roberts
bandpass image, laplace of gauss
Image filters
See Also
Module
kirsch dir ( Hobject Image, Hobject *ImageEdgeAmp,
Hobject *ImageEdgeDir )
Detect edges (amplitude and direction) using the Kirsch operator.
kirsch dir calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
¿ ¿
¿ ¼
¿ ¿
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 71
¿
¿ ¼
¿ ¿ ¿
¿ ¼ ¿
¿ ¿ ¿
¿
¼ ¿
¿ ¿ ¿
¿ ¿
¼ ¿
¿ ¿
¿ ¿ ¿
¼ ¿
¿
¿ ¿ ¿
¿ ¼ ¿
¿ ¿ ¿
¿ ¼
¿
The result image contains the maximum response of all masks. The edge directions are returned in
ImageEdgeDir, andarestoredasܾ. They correspond to the direction of the mask yielding the maximum
response.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Edge amplitude (gradient magnitude) image.
º ImageEdgeDir (output object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : direction
Edge direction image.
Example
read_image(&Image,"fabrik");
kirsch_dir(Image,&Kirsch_dirA,&Kirsch_dirD);
threshold(Kirsch_dirA,&Res,128,255);
Result
kirsch dir always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
kirsch dir is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Possible Successor Functions
hysteresis threshold, threshold, gray skeleton, nonmax suppression dir,
close edges, close edges length
Alternatives
edges image, sobel dir, robinson dir, prewitt dir, frei dir
bandpass image, laplace of gauss
Image filters
See Also
Module
HALCON 6.0

72 CHAPTER 3. FILTER
laplace ( Hobject Image, Hobject *ImageLaplace, const char *FilterType,
long Size, const char *NeighbourhoodType )
Calculate the Laplace operator by using finite differences.
laplace filters the input images Image using a Laplace operator. Depending on the parameter
NeighbourhoodType the following simple approximations of the Laplace operator are used:
’n 4’
’n 8’
’n 8 isotrop’
½
½ ½
½
½ ½ ½
½ ½
½ ½ ½
½¼ ¾¾ ½¼
¾¾ ½¾ ¾¾
½¼ ¾¾ ½¼
The filter ’n 8’ corresponds to the filter mask used in highpass image(OR3,3). For a Laplace operator with
size ¿ ¢ ¿, the corresponding filter is applied directly, while for larger filter sizes (Size = 5,7,9 and 11) the input
image is first smoothed using a Gaussian filter of the selected size. Therefore,
laplace(O:R:int4,S,N:)
for Size is equivalent to
gauss image(O:G:S:) º
laplace(G:R:int4,3,N:).
laplace either returns the absolute value of the Laplace filtered image (FilterType ’abs’) in a byte-image or
the signed result (FilterType ’int4’) in an int4-image.
laplace is only implemented for byte-images.
Attention
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageLaplace (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int4
Laplace-filtered result images.
º FilterType (input control) ...................................................string const char *
Calculate the absolute value of the filter to a byte-image or the signed result to an int4-image.
Default Value : ’int4’
Value List : FilterType ¾’abs’, ’int4’
º Size (input control) .................................................................integer long
Size of filter mask.
Default Value : 3
Value List : Size ¾3, 5, 7, 9, 11
º NeighbourhoodType (input control) ..........................................string const char *
Neighborhood used in the Laplace operator
Default Value : ’n 8 isotrop’
Value List : NeighbourhoodType ¾’n 4’, ’n 8’, ’n 8 isotrop’
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 73
Example
read_image(&Image,"mreut");
laplace(Image,&Laplace,"int4",3,"n_8_isotrop");
zero_crossing(Laplace,&ZeroCrossings);
Result
laplace returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set via
set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
laplace is reentrant and automatically parallelized (on tuple level, channel level, domain level).
zero crossing, dual threshold
diff of gauss, laplace of gauss
highpass image, edges image
Image filters
Possible Successor Functions
Alternatives
See Also
Module
laplace of gauss ( Hobject Image, Hobject *ImageLaplace, double Sigma )
LoG-Operator (Laplace of Gaussian).
laplace of gauss calculates the Laplace-of-Gaussian operator, i.e., the Laplace operator on a Gaussian
smoothed image, for arbitrary smoothing parameters Sigma. The Laplace operator is given by:
¡´Ü ݵ ¾ ´Ü ݵ
Ü ¾ · ¾ ´Ü ݵ
Ý ¾
The derivatives in laplace of gauss are calculated by appropriate derivatives of the Gaussian, resulting in the
following formula for the convolution mask:
¡ ´Ü ݵ
½ ܾ · Ý ¾
ܾ · Ý ¾
¾ ¾ ¾ ½ ÜÔ
¾ ¾
Parameter
º Image (input object) . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real
Input image.
º ImageLaplace (output object) . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * :int2
Laplace filtered image.
º Sigma (input control) .......................................................number double / long
Smoothing parameter of the Gaussian.
Default Value : 2.0
Value Suggestions : Sigma ¾0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 7.0
Typical Range of Values : 0.2 Sigma 20.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.0
HALCON 6.0

74 CHAPTER 3. FILTER
Example
read_image(&Image,"mreut");
laplace_of_gauss(Image,&Laplace,2.0);
zero_crossing(Laplace,&ZeroCrossings);
Parallelization Information
laplace of gauss is reentrant and automatically parallelized (on tuple level, channel level, domain level).
zero crossing, dual threshold
Possible Successor Functions
Alternatives
laplace, diff of gauss, derivate gauss
derivate gauss
Image filters
See Also
Module
prewitt amp ( Hobject Image, Hobject *ImageEdgeAmp )
Detect edges (amplitude) using the Prewitt operator.
prewitt amp calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
½ ½ ½
¼ ¼ ¼
½ ½ ½
½ ¼ ½
½ ¼ ½
½ ¼ ½
The result image contains the maximum response of the masks and .
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
read_image(&Image,"fabrik");
prewitt_amp(Image,&Prewitt);
threshold(Prewitt,&Edges,128,255);
Example
Result
prewitt amp always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
prewitt amp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Possible Successor Functions
threshold, gray skeleton, nonmax suppression amp, close edges, close edges length
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 75
Alternatives
sobel amp, kirsch amp, frei amp, robinson amp, roberts
bandpass image, laplace of gauss
Image filters
See Also
Module
prewitt dir ( Hobject Image, Hobject *ImageEdgeAmp,
Hobject *ImageEdgeDir )
Detect edges (amplitude and direction) using the Prewitt operator.
prewitt dir calculates an approximation of the first derivative of the image data and is used as an edge detector.
The filter is based on the following filter masks:
½ ½ ½
¼ ¼ ¼
½ ½ ½
½ ¼ ½
½ ¼ ½
½ ¼ ½
The result image contains the maximum response of the masks and . The edge directions are returned in
ImageEdgeDir, and are stored in 2-degree steps, i.e., an edge direction of Ü degrees with respect to the horizontal
axis is stored as ܾ in the edge direction image. Furthermore, the direction of the change of intensity is taken into
account. Let Ü Ý ℄ denote the image gradient. Then the following edge directions are returned as Ö¾:
intensity increase
Ü Ý
edge direction Ö
from bottom to top ¼· ¼
from lower right to upper left · ℄¼ ¼
from right to left ·¼ ¼
from upper right to lower left ·· ℄¼ ½¼
from top to bottom ¼· ½¼
from upper left to lower right · ℄½¼ ¾¼
from left to right ·¼ ¾¼
from lower left to upper right ℄¾¼ ¿¼
Points with edge amplitude 0 are assigned the edge direction 255 (undefined direction).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Edge amplitude (gradient magnitude) image.
º ImageEdgeDir (output object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : direction
Edge direction image.
Example
read_image(&Image,"fabrik");
prewitt_dir(Image,&PrewittA,&PrewittD);
threshold(PrewittA,&Edges,128,255);
Result
prewitt dir always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
HALCON 6.0

76 CHAPTER 3. FILTER
Parallelization Information
prewitt dir is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Possible Successor Functions
hysteresis threshold, threshold, gray skeleton, nonmax suppression dir,
close edges, close edges length
Alternatives
edges image, sobel dir, robinson dir, frei dir, kirsch dir
bandpass image, laplace of gauss
Image filters
See Also
Module
roberts ( Hobject Image, Hobject *ImageRoberts, const char *FilterType )
Detect edges using the Roberts filter.
roberts calculates the first derivative of an image and is used as an edge operator. If the following mask describes
a part of the image,
the different filter types are defined as follows:
’roberts max’ ÑÜ´ µ
’gradient max’
ÑÜ´ · ´ · µ · ´ · µµ
’gradient sum’
· ´ · µ · · ´ · µ
If an overflow occurs the result is clipped. The result of the operator is stored at the pixel with the coordinates of
“”.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageRoberts (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Roberts-filtered result images.
º FilterType (input control) ...................................................string const char *
Filter type.
Default Value : ’gradient sum’
Value List : FilterType ¾’roberts max’, ’gradient max’, ’gradient sum’
Example
read_image(&Image,"fabrik");
roberts(Image,&Roberts,"roberts_max");
threshold(Roberts,&Margin,128.0,255.0);
Result
roberts returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set via
set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
roberts is reentrant and automatically parallelized (on tuple level, channel level, domain level).
gauss image
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 77
threshold, skeleton
Possible Successor Functions
Alternatives
edges image, sobel amp, frei amp, kirsch amp, prewitt amp
See Also
laplace, highpass image, bandpass image
Image filters
Module
robinson amp ( Hobject Image, Hobject *ImageEdgeAmp )
Detect edges (amplitude) using the Robinson operator.
robinson amp calculates an approximation of the first derivative of the image data and is used as an edge
detector. In robinson amp the following four of the originally proposed eight ¿ ¢ ¿ filter masks are convolved
with the image. The other four masks are obtained by a multiplication by -1. All masks contain only the values
0,1,-1,2,-2.
½ ¼ ½
¾ ¼ ¾
½ ¼ ½
¾ ½ ¼
½ ¼ ½
¼ ½ ¾
¼ ½ ¾
½ ¼ ½
¾ ½ ¼
½ ¾ ½
¼ ¼ ¼
½ ¾ ½
The result image contains the maximum response of all masks.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
Example
read_image(&Image,"fabrik");
robinson_amp(Image,&Robinson_amp);
threshold(Robinson_amp,&Edges,128,255);
Result
robinson amp always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
robinson amp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Alternatives
sobel amp, frei amp, prewitt amp, robinson amp, roberts
HALCON 6.0

78 CHAPTER 3. FILTER
bandpass image, laplace of gauss
Image filters
See Also
Module
robinson dir ( Hobject Image, Hobject *ImageEdgeAmp,
Hobject *ImageEdgeDir )
Detect edges (amplitude and direction) using the Robinson operator.
robinson dir calculates an approximation of the first derivative of the image data and is used as an edge
detector. In robinson amp the following four of the originally proposed eight ¿ ¢ ¿ filter masks are convolved
with the image. The other four masks are obtained by a multiplication by -1. All masks contain only the values
0,1,-1,2,-2.
½ ¼ ½
¾ ¼ ¾
½ ¼ ½
¾ ½ ¼
½ ¼ ½
¼ ½ ¾
¼ ½ ¾
½ ¼ ½
¾ ½ ¼
½ ¾ ½
¼ ¼ ¼
½ ¾ ½
The result image contains the maximum response of all masks. The edge directions are returned in
ImageEdgeDir, andarestoredasܾ. They correspond to the direction of the mask yielding the maximum
response.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Eingabebild.
º ImageEdgeAmp (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Edge amplitude (gradient magnitude) image.
º ImageEdgeDir (output object) . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : direction
Edge direction image.
Example
read_image(&Image,"fabrik");
robinson_dir(Image,&Robinson_dirA,&Robinson_dirD);
threshold(Robinson_dirA,&Res,128,255);
Result
robinson dir always returns H MSG TRUE. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
robinson dir is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, sigma image, median image, smooth image
Possible Successor Functions
hysteresis threshold, threshold, gray skeleton, nonmax suppression dir,
close edges, close edges length
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 79
Alternatives
edges image, sobel dir, kirsch dir, prewitt dir, frei dir
bandpass image, laplace of gauss
Image filters
See Also
Module
sobel amp ( Hobject Image, Hobject *EdgeAmplitude,
const char *FilterType, long Size )
Detect edges (amplitude) using the Sobel operator.
sobel amp calculates first derivative of an image and is used as an edge detector. The filter is based on the
following filter masks:
½ ¾ ½
¼ ¼ ¼
½ ¾ ½
½ ¼ ½
¾ ¼ ¾
½ ¼ ½
These masks are used differently, according to the selected filter type. (In the following, und denote the results
of convolving an image with und for one particular pixel.)
’sum sqrt’
’sum abs’
’thin sum abs’
’thin max abs’
’x’
’y’
Ô
¾ · ¾
´ · µ¾
´ØÒ´µ ·ØÒ´µµ¾
ÑÜ´ØÒ´µ ØÒ´µµ
Here, ØҴܵ is equal to Ü for a vertical maximum (mask A) and a horizontal maximum (mask B), respectively,
and 0 otherwise. Thus, for ’thin sum abs’ and ’thin max abs’ the gradient image is thinned. In the case of byte
images for ’x’ and ’y’ the value 127 is added to the result to avoid under flows. For a Sobel operator with size
¿ ¢ ¿, the corresponding filters and are applied directly, while for larger filter sizes (Size = 5,7,9 and 11) the
input image is first smoothed using a Gaussian filter of size Size-2. Therefore,
sobel amp(I:E,Dir:FilterTyp,S:)
for Size 3 is equivalent to
gauss image(I:G:S-2) º
sobel amp(G:E:FilterType,3:).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º EdgeAmplitude (output object) . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
º FilterType (input control) ...................................................string const char *
Filter type.
Default Value : ’sum abs’
Value List : FilterType ¾’sum abs’, ’thin sum abs’, ’thin max abs’, ’sum sqrt’, ’x’, ’y’
º Size (input control) .................................................................integer long
Size of filter mask.
Default Value : 3
Value List : Size ¾3, 5, 7, 9, 11, 13
HALCON 6.0

80 CHAPTER 3. FILTER
Example
read_image(&Image,"fabrik");
sobel_amp(Image,&Amp,"sum_abs",3);
threshold(Amp,&Edg,128.0,255.0);
Result
sobel amp returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set via
set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
sobel amp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, mean image, anisotrope diff, sigma image
Possible Successor Functions
threshold, nonmax suppression amp, gray skeleton
Alternatives
frei amp, roberts, kirsch amp, prewitt amp, robinson amp
See Also
laplace, highpass image, bandpass image
Image filters
Module
sobel dir ( Hobject Image, Hobject *EdgeAmplitude,
Hobject *EdgeDirection, const char *FilterType, long Size )
Detect edges (amplitude and direction) using the Sobel operator.
sobel dir calculates first derivative of an image and is used as an edge detector. The filter is based on the
following filter masks:
½ ¾ ½
¼ ¼ ¼
½ ¾ ½
½ ¼ ½
¾ ¼ ¾
½ ¼ ½
These masks are used differently, according to the selected filter type. (In the following, und denote the results
of convolving an image with und for one particular pixel.)
’sum sqrt’
’sum abs’
Ô
¾ · ¾
´ · µ¾
For a Sobel operator with size ¿ ¢ ¿, the corresponding filters and are applied directly, while for larger filter
sizes (Size = 5,7,9 and 11) the input image is first smoothed using a Gaussian filter of size Size-2. Therefore,
sobel dir(I:Amp,Dir:FilterTyp,S:)
for Size 3 is equivalent to
gauss image(I:G:S-2) º
sobel dir(G:Amp,Dir:FilterType,3:).
HALCON/C Reference Manual / 2000-11-15

3.5. EDGES 81
The edge directions are returned in EdgeDirection, and are stored in 2-degree steps, i.e., an edge direction of Ü
degrees with respect to the horizontal axis is stored as ܾ in the edge direction image. Furthermore, the direction
of the change of intensity is taken into account. Let Ü Ý ℄ denote the image gradient. Then the following edge
directions are returned as Ö¾:
intensity increase
Ü Ý
edge direction Ö
from bottom to top ¼· ¼
from lower right to upper left · ℄¼ ¼
from right to left ·¼ ¼
from upper right to lower left ·· ℄¼ ½¼
from top to bottom ¼· ½¼
from upper left to lower right · ℄½¼ ¾¼
from left to right ·¼ ¾¼
from lower left to upper right ℄¾¼ ¿¼
Points with edge amplitude 0 are assigned the edge direction 255 (undefined direction).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º EdgeAmplitude (output object) . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Edge amplitude (gradient magnitude) image.
º EdgeDirection (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : direction
Edge direction image.
º FilterType (input control) ...................................................string const char *
Filter type.
Default Value : ’sum abs’
Value List : FilterType ¾’sum abs’, ’sum sqrt’
º Size (input control) .................................................................integer long
Size of filter mask.
Default Value : 3
Value List : Size ¾3, 5, 7, 9, 11, 13
Example
read_image(&Image,"fabrik");
sobel_dir(Image,&Amp,&Dir,"sum_abs",3);
threshold(Amp,&Edg,128.0,255.0);
Result
sobel dir returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set via
set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
sobel dir is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
gauss image, mean image, anisotrope diff, sigma image
Possible Successor Functions
nonmax suppression dir, hysteresis threshold, threshold
Alternatives
edges image, frei dir, kirsch dir, prewitt dir, robinson dir
See Also
roberts, laplace, highpass image, bandpass image
Image filters
Module
HALCON 6.0

82 CHAPTER 3. FILTER
3.6 Enhancement
emphasize ( Hobject Image, Hobject *ImageEmphasize, long MaskWidth,
long MaskHeight, double Factor )
Enhance contrast of the image.
The operator emphasize emphasizes high frequency areas of the image (edges and corners). The resulting
images appears sharper.
First the procedure carries out a filtering with the low pass (mean image). The resulting gray values (Ö×) are
calculated from the obtained gray values (ÑÒ) and the original gray values (ÓÖ) as follows:
Ö× ÖÓÙÒ´´ÓÖ ÑÒµ £ ØÓÖµ ·ÓÖ
Factor serves as measurement of the increase in contrast. The division frequency is determined via the size of
the filter matrix: The larger the matrix, the lower the disivion frequency.
As an edge treatment the gray values are mirrored at the edges of the image. Overflow and/or underflow of gray
values is clipped (255 or 0, respectively).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be enhanced.
º ImageEmphasize (output object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
contrast enhanced image.
º MaskWidth (input control) ..........................................................extent.x long
Width of low pass mask.
Default Value : 7
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 15, 21, 25, 31, 39
Typical Range of Values : 3 MaskWidth 201
Minimal Value Step : 2
Recommended Value Step : 2
º MaskHeight (input control) ........................................................extent.y long
Height of the low pass mask.
Default Value : 7
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 15, 21, 25, 31, 39
Typical Range of Values : 3 MaskHeight 201
Minimal Value Step : 2
Recommended Value Step : 2
º Factor (input control) ...............................................................real double
Intensity of contrast emphasis.
Default Value : 1.0
Value Suggestions : Factor ¾0.3, 0.5, 0.7, 1.0, 1.4, 1.8, 2.0
Typical Range of Values : 0.0 Factor 20.0 (sqrt)
Minimal Value Step : 0.01
Recommended Value Step : 0.2
Restriction : ´0 Factorµ ´Factor 20µ
read_image(&Image,"meer_rot");
disp_image(Image,WindowHandle);
draw_region(&Region,WindowHandle);
reduce_domain(Image,Region,&Mask);
emphasize(Mask,&Sharp,7,7,2.0);
disp_image(Sharp,WindowHandle);
Example
Result
If the parameter values are correct the operator emphasize returns the value H MSG TRUE The
HALCON/C Reference Manual / 2000-11-15

3.6. ENHANCEMENT 83
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
emphasize is reentrant and automatically parallelized (on tuple level, channel level, domain level).
disp image
Possible Successor Functions
Alternatives
mean image, sub image, laplace, add image
mean image, highpass image
Image filters
See Also
Module
equ histo image ( Hobject Image, Hobject *ImageEquHisto )
Histogram linearisation of images
The operator equ histo image enhances the contrast. The starting point is the histogram of the input images.
The following simple gray value transformation ´µ is carried out:
´µ ¾
ܼ
´Üµ describes the relative frequency of the occurrence of the gray value Ü. This transformation linearises the
cumulative histogram. Maxima in the original histogram are ”‘spreaded”’ and thus the contrast in image regions
with these frequently occuring gray values is increased. Supposedly homogenous regions receive more easily
visible structures. On the other hand, of course, the noise in the image increases correspondlingly. Minima in the
original histogram are dually ”‘compressed”’. The transformed histogram contains gaps, but the remaining gray
values used occur approximately at the same frequency (”‘histogram equalization”’).
Attention
The operator equ histo image primarily serves for optical processing of images for a human viewer. For
example, the (local) contrast spreading can lead to a detection of fictitious edges.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be enhanced.
º ImageEquHisto (output object) . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Image with linearized gray values.
Parallelization Information
equ histo image is reentrant and automatically parallelized (on tuple level, channel level).
disp image
´Üµ
Possible Successor Functions
Alternatives
scale image, scale image max, illuminate
scale image
See Also
Bibliography
R.C. Gonzales, P. Wintz: ”‘Digital Image Processing”’; Second edition; Addison Wesley; 1987.
Image filters
Module
HALCON 6.0

84 CHAPTER 3. FILTER
illuminate ( Hobject Image, Hobject *ImageIlluminate, long MaskWidth,
long MaskHeight, double Factor )
Illuminate image.
The operator illuminate enhances contrast. Very dark parts of the image are ”‘illuminated”’ more strongly,
very light ones are ”‘darkened”’. If ÓÖ is the original gray value and ÑÒ is the corresponding gray value of
the low pass filtered image detected via the operators mean image and filter size MaskHeight x MaskWidth,
the resulting gray value is ÒÛ:
ÒÛ ÖÓÙÒ´´½¾ ÑÒµ £ ØÓÖ · ÓÖµ
The low pass should have rather large dimensions (30 x 30 to 200 x 200). Reasonable parameter combinations
might be:
Å×ÀØ Å×ÏØ ØÓÖ
¼ ¼ ¼
½¼¼ ½¼¼ ¼
½¼ ½¼ ¼
i.e. the larger the low pass mask is chosen, the larger Factor should be as well.
The following ”‘spotlight effect”’ should be noted: If, for example, a dark object is in front of a light wall the object
as well as the wall, which is already light in the immediate proximity of the object contours, are lightened by the
operator illuminate. This corresponds roughly to the effect that is produced when the object is illuminated by
a strong spotlight. The same applies to light objects in front of a darker background. In this case, however, the
fictitious ”‘spotlight”’ darkens objects.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be enhanced.
º ImageIlluminate (output object) . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
”‘Illuminated”’ image.
º MaskWidth (input control) ..........................................................extent.x long
Width of low pass mask.
Default Value : 101
Value Suggestions : MaskWidth ¾31, 41, 51, 71, 101, 121, 151, 201
Typical Range of Values : 3 MaskWidth 299
Minimal Value Step : 2
Recommended Value Step : 10
º MaskHeight (input control) ........................................................extent.y long
Height of low pass mask.
Default Value : 101
Value Suggestions : MaskHeight ¾31, 41, 51, 71, 101, 121, 151, 201
Typical Range of Values : 3 MaskHeight 299
Minimal Value Step : 2
Recommended Value Step : 10
º Factor (input control) ...............................................................real double
Scales the ”‘correction gray value”’ added to the original gray values.
Default Value : 0.7
Value Suggestions : Factor ¾0.3, 0.5, 0.7, 1.0, 1.5, 2.0, 3.0, 5.0
Typical Range of Values : 0.0 Factor 5.0
Minimal Value Step : 0.01
Recommended Value Step : 0.2
Restriction : ´0 Factorµ ´Factor 5µ
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
illuminate(Image,&Better,40,40,0.55);
disp_image(Better,WindowHandle);
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 85
Result
If the parameter values are correct the operator illuminate returns the value H MSG TRUE The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
illuminate is reentrant and automatically parallelized (on tuple level, channel level, domain level).
disp image
Possible Successor Functions
Alternatives
scale image max, equ histo image, mean image, sub image
emphasize, gray histo
Image filters
See Also
Module
scale image max ( Hobject Image, Hobject *ImageScaleMax )
Maximum gray value spreading in the value range 0 bis 255.
The operator scale image max calculates the minimum and maximum and scales the image to the maximum
value range of a byte image. This way the dynamics (value range) is fully exploited. The number of different gray
scales does not change, but in general the visual impression is enhanced. The gray values of images of the real,
int2 and int4 type are scaled to the range 0 to 255 and returned as byte images.
The output always is an image of the type byte.
Attention
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2 / int4 / real
Image to be scaled.
º ImageScaleMax (output object) ...................................image(-array) Hobject * : byte
contrast enhanced image.
Parallelization Information
scale image max is reentrant and automatically parallelized (on tuple level, channel level).
disp image
Possible Successor Functions
Alternatives
equ histo image, scale image, illuminate, convert image type
min max gray, gray histo
Image filters
See Also
Module
3.7 FFT
convol fft ( Hobject ImageFFT, Hobject ImageFilter,
Hobject *ImageConvol )
Convolve an image with a byte-mask in the frequency domain.
convol fft convolves two (Fourier-transformed) images in the frequency domain, i.e., the pixels of the complex
image ImageFFT are multiplied by the corresponding pixels of the filter ImageFilter. This image is a byteimage
in which 0 corresponds to complete suppression of a frequency, and 255 corresponds to no suppression. The
result image is of type ’complex’.
HALCON 6.0

86 CHAPTER 3. FILTER
Attention
The filtering is always done on the entire image, i.e., the region of the image is ignored.
Parameter
º ImageFFT (input object) ..........................................image(-array) Hobject : complex
Complex input image.
º ImageFilter (input object) ................................................image Hobject : byte
Filter in frequency domain.
º ImageConvol (output object) ..................................image(-array) Hobject * : complex
Result of applying the filter.
Example
my_highpass(Hobject Image, Hobject *Result, int frequency, int size)
{
Hobject FFT, Highpass, FFTConvol;
fft_image(Image,&FFT);
gen_highpass(&Highpass,frequency,size);
convol_fft(FFT,Highpass,&FFTConvol);
clear_obj(Highpass); clear_obj(FFT);
fft_image_inv(FFTConvol,Result);
clear_obj(FFTConvol);
}
Result
convol fft returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
convol fft is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
fft image, fft generic, gen highpass, gen lowpass, gen bandpass, gen bandfilter
Possible Successor Functions
power byte, power real, power ln, fft image inv, fft generic
convol gabor
Alternatives
See Also
gen gabor, gen highpass, gen lowpass, gen bandpass, convol gabor, fft image inv
Image filters
Module
convol gabor ( Hobject ImageFFT, Hobject GaborFilter,
Hobject *ImageResultGabor, Hobject *ImageResultHilbert )
Convolve an image with a Gabor filter in the frequency domain.
convol gabor convolves a Fourier-transformed image with a Gabor filter GaborFilter (see gen gabor)
and its Hilbert transform in the frequency domain. The result image is of type ’complex’.
Attention
The filtering is always done on the entire image, i.e., the region of the image is ignored.
Parameter
º ImageFFT (input object) ..........................................image(-array) Hobject : complex
Input image.
º GaborFilter (input object) ................................................image Hobject : byte
Gabor/Hilbert-Filter.
º ImageResultGabor (output object) ...........................image(-array) Hobject * : complex
Result of the Gabor filter.
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 87
º ImageResultHilbert (output object) .........................image(-array) Hobject * : complex
Result of the Hilbert filter.
Example
fft_image(Image,&FFT);
gen_gabor(&Filter,1.4,0.4,1.0,1.5,512);
convol_gabor(FFT,Filter,&Gabor,&Hilbert);
fft_image_inv(Gabor,&GaborInv);
fft_image_inv(Hilbert,&HilbertInv);
energy_gabor(GaborInv,HilbertInv,&Energy);
Result
convol gabor returns H MSG TRUE if all images are of correct type. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
convol gabor is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
fft image, fft generic, gen gabor
Possible Successor Functions
power byte, power real, power ln, fft image inv, fft generic
convol fft
convol image
Image filters
Alternatives
See Also
Module
energy gabor ( Hobject ImageGabor, Hobject ImageHilbert,
Hobject *Energy )
Calculate the energy of a two-channel image.
energy gabor calculates the local contrast (Energy) of the two input images. The energy of the resulting
image is then defined as
ÒÖÝ channel1 ¾ · channel2 ¾
Often the calculation of the energy is preceded by the convolution of an image with a Gabor filter and the
Hilbert transform of the Gabor filter (see convol gabor). In this case, the first channel of the image passed
to energy gabor is the Gabor-filtered image, transformed back into the spatial domain (see fft image inv),
and the second channel the result of the convolution with the Hilbert transform, also transformed back into the
spatial domain. The local energy is a measure for the local contrast of structures (e.g., edges and lines) in the
image.
Parameter
º ImageGabor (input object) ......................................image(-array) Hobject : byte / real
1st channel of input image (usually: Gabor image).
º ImageHilbert (input object) ...................................image(-array) Hobject : byte / real
2nd channel of input image (usually: Hilbert image).
º Energy (output object) .............................................image(-array) Hobject * : real
Image containing the local energy.
Example
HALCON 6.0

88 CHAPTER 3. FILTER
fft_image(Image,&FFT);
gen_gabor(&Filter,1.4,0.4,1.0,1.5,512);
convol_gabor(FFT,Filter,&Gabor,&Hilbert);
fft_image_inv(Gabor,&GaborInv);
fft_image_inv(Hilbert,&HilbertInv);
energy_gabor(GaborInv,HilbertInv,&Energy);
Result
energy gabor returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
energy gabor is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessor Functions
gen gabor, convol gabor, fft image inv
Image filters
Module
fft generic ( Hobject Image, Hobject *ImageFFT, const char *Direction,
long Exponent, const char *Norm, const char *Mode )
Compute the fast Fourier transform of an image.
fft generic computes the fast Fourier transform of the input image Image. Because several definitions of the
forward and reverse transforms exist in the literature, this operator allows the user to select the most convenient
definition.
The general definition of a Fourier transform is as follows:
´Ñ Òµ
Å
½
¼
Æ
½
м
×¾´ÑÅ·ÐÒƵ ´ е
Opinions vary on whether the sign × in the exponent should be set to ½ or ½ for the forward transform, i.e. the
for going to the frequency domain. There is also disagreement on the magnitude of the normalizing factor . This
is Ôsometimes set to ½ for the forward transform, sometimes to ÅÆ, and sometimes (in case of the unitary FFT) to
ÅÆ. Especially in image processing applications the DC term is shifted to the center of the image.
fft generic allows to select these choices individually. The parameter Direction allows to select the logical
direction of the FFT. (This parameter is not unnecessary; it is needed to discern how to shift the image if the
DC term should rest in the center of the image.) Possible values are ’to freq’ and ’from freq’. The parameter
Exponent is used to determine the sign of the exponent. It can be set to ½ or ½. The normalizing factor can be
set with Norm, and can take on the values ’none’, ’sqrt’ and ’n’. The parameter Mode determines the location of
the DC term of the FFT. It can be set to ’dc center’ or ’dc edge’.
In any case, the user must ensure the consistent use of the parameters. This means that the normalizing factors
used for the forward and bacward transform must yield ÅÆ when multiplied, the exponents must be of opposite
sign, and Mode must be equal for both transforms.
A consistent combination is, for example (’to freq’,-1,’n’,’dc edge’) for the forward transform and
(’from freq’,1,’none’,’dc edge’) for the reverse transform. In this case, the FFT can be interpreted as interpolation
with trigonometric basis functions. Another useful combination is (’to freq’,1,’sqrt’,’dc center’) and
(’from freq’,-1,’sqrt’,’dc center’).
Parameter
º Image (input object) ..................................................image(-array) Hobject :any
Input image.
º ImageFFT (output object) ......................................image(-array) Hobject * : complex
Fourier-transformed image.
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 89
º Direction (input control) .....................................................string const char *
Calculate forward or reverse transform.
Default Value : ’to freq’
Value List : Direction ¾’to freq’, ’from freq’
º Exponent (input control) ............................................................integer long
Sign of the exponent.
Default Value : 1
Value List : Exponent ¾-1, 1
º Norm (input control) ............................................................string const char *
Normalizing factor of the transform.
Default Value : ’sqrt’
Value List : Norm ¾’none’, ’sqrt’, ’n’
º Mode (input control) ............................................................string const char *
Location of the DC term in the frequency domain.
Default Value : ’dc center’
Value List : Mode ¾’dc center’, ’dc edge’
Example
/* simulation of fft */
my_fft(Hobject In, Hobject *Out)
{
fft_generic(In,Out,’to_freq’,1,’sqrt’,’dc_center’);
}
/* simulation of fft_image_inv */
my_fft_image_inv(Hobject In, Hobject *Out)
{
Hobject Tmp;
fft_generic(In,&Tmp,’from_freq’,1,’sqrt’,’dc_center’);
convert_image_type(Tmp,Out,"byte");
clear_obj(Tmp);
}
Result
fft generic returns H MSG TRUE if the input image is of correct type, its width and height are a power
of 2, and all parameters are correct. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
fft generic is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
convol fft, convol gabor, convert image type, power byte, power real, power ln,
phase deg, phase rad, energy gabor
fft image, fft image inv
Image filters
Alternatives
Module
fft image ( Hobject Image, Hobject *ImageFFT )
Compute the fast Fourier transform of an image.
fft image calculates the Fourier transform of the input image (Image), i.e., it transforms the image into the
frequency domain. The algorithm used is the fast Fourier transform. This corresponds to the call
fft generic(Image,ImageFFT,’to freq’,1,’n’,’dc center’)
HALCON 6.0

90 CHAPTER 3. FILTER
The result image is of type ’complex’.
Attention
The filtering is always done on the entire image, i.e., the region of the image is ignored. The images must be
quadratic and the width and height must be a power of 2.
Parameter
º Image (input object) .............................................image(-array) Hobject : byte / real
Input image.
º ImageFFT (output object) ......................................image(-array) Hobject * : complex
Fourier-transformed image.
Example
fft_image(Image,&FFT);
gen_gabor(&Filter,1.4,0.4,1.0,1.5,512);
convol_gabor(FFT,Filter,&Gabor,&Hilbert);
fft_image_inv(Gabor,&GaborInv);
fft_image_inv(Hilbert,&HilbertInv);
energy_gabor(GaborInv,HilbertInv,&Energy);
Result
fft image returns H MSG TRUE if the input image is of correct type and its width and height are a power of
2. If the input is empty the behaviour can be set via set system(’no object result’,). If
necessary, an exception handling is raised.
Parallelization Information
fft image is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
convol fft, convol gabor, convert image type, power byte, power real, power ln,
phase deg, phase rad
fft generic
fft image inv
Image filters
Alternatives
See Also
Module
fft image inv ( Hobject Image, Hobject *ImageFFTInv )
Compute the inverse fast Fourier transform of an image.
fft image inv calculates the inverse Fourier transform of the input image (Image), i.e., it transforms the
image back into the spatial domain. This corresponds to the call
fft generic(Image,ImageFFT,’from freq’,-1,’sqrt’,’dc center’)
convert image type(ImageFFT,ImageFFTInv,’byte’) .
The result image is of type ’byte’.
Attention
The filtering is always done on the entire image, i.e., the region of the image is ignored. The images must be
quadratic and the width and height must be a power of 2.
Parameter
º Image (input object) ..............................................image(-array) Hobject : complex
Input image.
º ImageFFTInv (output object) ......................................image(-array) Hobject * : byte
Inverse-Fourier-transformed image.
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 91
Example
fft_image(Image,&FFT);
gen_gabor(&Filter,1.4,0.4,1.0,1.5,512);
convol_gabor(FFT,Filter,&Gabor,&Hilbert);
fft_image_inv(Gabor,&GaborInv);
fft_image_inv(Hilbert,&HilbertInv);
energy_gabor(GaborInv,HilbertInv,&Energy);
Result
fft image inv returns H MSG TRUE if the input image is of correct type and its width and height are a power
of 2. If the input is empty the behaviour can be set via set system(’no object result’,).
If necessary, an exception handling is raised.
Parallelization Information
fft image inv is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
convol fft, convol gabor, fft image
Possible Successor Functions
convert image type, energy gabor
fft generic
fft image, fft generic, energy gabor
Image filters
Alternatives
See Also
Module
gen bandfilter ( Hobject *ImageFilter, double MinFrequency,
double MaxFrequency, long Size )
Generate an ideal band filter.
gen bandfilter generates an ideal band filter in the frequency domain. The DC term is assumed to lie in the
center of the image. The parameters MinFrequency and MaxFrequency determine the cutoff frequencies of
the filter (in pixels). The resulting image contains an annulus with the value 0, and the value 255 outside of this
annulus.
Parameter
º ImageFilter (output object) .............................................image Hobject * : byte
Band filter in the frequency domain.
º MinFrequency (input control) .......................................................real double
Minimum frequency.
Default Value : 20
Value Suggestions : MinFrequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 MinFrequency
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinFrequency 0
º MaxFrequency (input control) .......................................................real double
Maximum frequency.
Default Value : 40
Value Suggestions : MaxFrequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 MaxFrequency
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MaxFrequency 0
HALCON 6.0

92 CHAPTER 3. FILTER
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
my_lowpass(Hobject Image, Hobject *Result)
{
Hobject FFT, Bandpass, FFTConvol;
fft_image(Image,&FFT);
gen_bandfilter(&Bandpass,20,40,512);
convol_fft(FFT,Bandpass,&FFTConvol);
clear_obj(Bandpass); clear_obj(FFT);
fft_image_inv(FFTConvol,Result);
clear_obj(FFTConvol);
}
Result
gen bandfilter returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is
raised.
Parallelization Information
gen bandfilter is reentrant and processed without parallelization.
convol fft
gen circle, paint region
Possible Successor Functions
Alternatives
See Also
gen highpass, gen lowpass, gen bandpass
Image filters
Module
gen bandpass ( Hobject *ImageBandpass, double MinFrequency,
double MaxFrequency, long Size )
Generate an ideal bandpass filter.
gen bandpass generates an ideal bandpass filter in the frequency domain. The DC term is assumed to lie in the
center of the image. The parameters MinFrequency and MaxFrequency determine the cutoff frequencies of
the filter (in pixels). The resulting image contains an annulus with the value 255, and the value 0 outside of this
annulus.
Parameter
º ImageBandpass (output object) ..........................................image Hobject * : byte
Bandpass filter in the frequency domain.
º MinFrequency (input control) .......................................................real double
Minimum frequency.
Default Value : 20
Value Suggestions : MinFrequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 MinFrequency 200
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinFrequency 0
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 93
º MaxFrequency (input control) .......................................................real double
Maximum frequency.
Default Value : 40
Value Suggestions : MaxFrequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 MaxFrequency 200
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MaxFrequency 0
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
my_lowpass(Hobject Image, Hobject *Result)
{
Hobject FFT, Bandpass, FFTConvol;
fft(Image,&FFT);
gen_bandpass(&Bandpass,20,40,512);
convol_fft(FFT,Bandpass,&FFTConvol);
clear_obj(Bandpass); clear_obj(FFT);
fft_image_inv(FFTConvol,Result);
clear_obj(FFTConvol);
}
Result
gen bandpass returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is raised.
Parallelization Information
gen bandpass is reentrant and processed without parallelization.
convol fft
gen circle, paint region
Possible Successor Functions
Alternatives
See Also
gen highpass, gen lowpass, gen bandfilter
Image filters
Module
gen filter mask ( Hobject *ImageFilter, const char *FileName,
double Scale, long Size )
Store a filter mask in the spatial domain as a real-image.
gen filter mask stores a filter mask in the spatial domain as a real-image. The center of the filter mask lies in
the center of the resulting image. The parameter Scale determines by which amount the values of the filter mask
are multiplied (this results in larger values of the Fourier transform of the filter). The file format of the filter mask
file is described with the operator convol image. Example filter masks can be found in the directory “filter” in
the HALCON home directory. This operator is useful for visualizing the frequency response of filter masks (by
applying a Fourier transform to the result image of this operator).
Parameter
º ImageFilter (output object) .......................................image(-array) Hobject * : real
Filter in the spatial domain.
º FileName (input control) ......................................................string const char *
File name of the filter mask.
Default Value : ’sobel’
Value Suggestions : FileName ¾’laplace4’, ’laplace8’, ’lowpass 3 3’
HALCON 6.0

94 CHAPTER 3. FILTER
º Scale (input control) .................................................................real double
Scaling factor.
Default Value : 1.0
Value Suggestions : Scale ¾0.3, 0.5, 0.75, 1.0, 1.25, 1.5, 2.0
Typical Range of Values : 0.001 Scale 10.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
Restriction : Scale 0.0
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
gen_filter_mask(&Filter,"lowpass_3_3",1.0,512);
fft_image(Filter,&FilterFFT);
set_paint(WindowHandle,"3D-plot_hidden");
disp_image(FilterFFT,WindowHandle);
Parallelization Information
gen filter mask is reentrant and processed without parallelization.
fft image, fft generic
convol image
Image filters
Possible Successor Functions
See Also
Module
gen gabor ( Hobject *ImageFilter, double Angle, double Frequency,
double Bandwidth, double Orientation, long Size )
Generate a Gabor filter.
gen gabor generates a Gabor filter with a user-definable bandpass frequency range and sign for the Hilbert
transformation. This is done by calculating a symmetrical filter in the frequency domain, which can be adapted by
the parameters Angle, Frequency, Bandwidth und Orientation such that a certain frequency band and
a certain direction range in the spatial domain is filtered out in the frequency domain.
The parameters Frequency (central frequency = distance from the DC term) and Orientation (direction)
determine the center of the filter. Larger values of Frequency result in higher frequencies being passed. A value
of 0 for Orientation generates a horizontally oriented “crescent” (the bulge of the crescent points upward).
Higher values of Orientation result in the counterclockwise rotation of the crescent.
The parameters Angle and Bandwidth are used to determine the range of frequencies and angles being passed
by the filter. The larger Angle is, the smaller the range of angles passed by the filter gets (because the “crescent”
gets narrower). The larger Bandwidth is, the smaller the frequency band being passed gets (because the
“crescent” gets thinner).
The resulting image is a byte-image, containing the Gabor filter in the upper half of the image (symmetry of
the Gabor filter), and the corresponding sign values needed for the calculation of the Hilbert transform, which is
needed to compute the local energy of the image, in the lower half of the image.
Parameter
º ImageFilter (output object) ......................................image(-array) Hobject * : byte
Gabor filter (and sign values).
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 95
º Angle (input control) .................................................................real double
Angle range, inversely proportional to the range of orientations.
Default Value : 1.4
Value Suggestions : Angle ¾1.0, 1.2, 1.4, 1.6, 2.0, 2.5, 3.0, 5.0, 6.0, 10.0, 20.0, 30.0, 50.0, 70.0, 100.0
Typical Range of Values : 1.0 Angle 500.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Frequency (input control) ...........................................................real double
Distance of the center of the filter to the DC term.
Default Value : 0.4
Value Suggestions : Frequency ¾0.0, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.50, 0.55, 0.60,
0.65, 0.699
Typical Range of Values : 0.0 Frequency 0.7
Minimal Value Step : 0.00001
Recommended Value Step : 0.005
º Bandwidth (input control) ...........................................................real double
Bandwith range, inversely proportional to the range of frequencies being passed.
Default Value : 1.0
Value Suggestions : Bandwidth ¾0.1, 0.3, 0.7, 1.0, 1.5, 2.0, 3.0, 5.0, 7.0, 10.0, 15.0, 20.0, 30.0, 50.0
Typical Range of Values : 0.05 Bandwidth 100.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
º Orientation (input control) .........................................................real double
Angle of the principal orientation being passed.
Default Value : 1.5
Value Suggestions : Orientation ¾0.0, 0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 1.6, 1.8, 2.0, 2.2, 2.4, 2.6, 2.8,
3.0, 3.14
Typical Range of Values : 0.0 Orientation 3.1416
Minimal Value Step : 0.0001
Recommended Value Step : 0.05
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
fft_image(Image,&FFT);
gen_gabor(&Filter,1.4,0.4,1.0,1.5,512);
convol_gabor(FFT,Filter,&Gabor,&Hilbert);
fft_image_inv(Gabor,&GaborInv);
fft_image_inv(Hilbert,&HilbertInv);
energy_gabor(GaborInv,HilbertInv,&Energy);
Result
gen gabor returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is raised.
Parallelization Information
gen gabor is reentrant and processed without parallelization.
fft image, fft generic
convol gabor
Possible Predecessor Functions
Possible Successor Functions
Alternatives
gen bandpass, gen bandfilter, gen highpass, gen lowpass
fft image inv, energy gabor
Image filters
See Also
Module
HALCON 6.0

96 CHAPTER 3. FILTER
gen highpass ( Hobject *ImageHighpass, double Frequency, long Size )
Generate an ideal highpass filter.
gen highpass generates an ideal highpass filter in the frequency domain. The DC term is assumed to lie in
the center of the image. The parameter Frequency determines the cutoff frequency of the filter (in pixels). The
resulting image contains a circle of radius Frequency with the value 0, and the value 255 outside of this circle.
Parameter
º ImageHighpass (output object) ..........................................image Hobject * : byte
Highpass filter in the frequency domain.
º Frequency (input control) ...........................................................real double
Cutoff frequency.
Default Value : 20
Value Suggestions : Frequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 Frequency 200
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Frequency 0
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
my_highpass(Hobject Image, Hobject *Result, int frequency, int size)
{
Hobject FFT, Highpass, FFTConvol;
fft_image(Image,&FFT);
gen_highpass(&Highpass,frequency,size);
convol_fft(FFT,Highpass,&FFTConvol);
clear_obj(Highpass); clear_obj(FFT);
fft_image_inv(FFTConvol,Result);
clear_obj(FFTConvol);
}
Result
gen highpass returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is raised.
Parallelization Information
gen highpass is reentrant and processed without parallelization.
convol fft
gen circle, paint region
Possible Successor Functions
Alternatives
See Also
convol fft, gen lowpass, gen bandpass, gen bandfilter
Image filters
Module
gen lowpass ( Hobject *ImageLowpass, double Frequency, long Size )
Generate an ideal lowpass filter.
gen lowpass generates an ideal lowpass filter in the frequency domain. The DC term is assumed to lie in the
center of the image. The parameter Frequency determines the cutoff frequency of the filter (in pixels). The
resulting image contains a circle of radius Frequency with the value 255, and the value 0 outside of this circle.
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 97
Parameter
º ImageLowpass (output object) ............................................image Hobject * : byte
Highpass filter in the frequency domain.
º Frequency (input control) ...........................................................real double
Cutoff frequency.
Default Value : 20
Value Suggestions : Frequency ¾10, 20, 30, 40, 50, 60, 70, 100
Typical Range of Values : 1 Frequency 200
Minimal Value Step : 1
Recommended Value Step : 1
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Example
my_lowpass(Hobject Image, Hobject *Result, int frequency, int size)
{
Hobject FFT, Lowpass, FFTConvol;
fft(Image,&FFT);
gen_lowpass(&Lowpass,frequency,size);
convol_fft(FFT,Lowpass,&FFTConvol);
clear_obj(Lowpass); clear_obj(FFT);
fft_image_inv(FFTConvol,Result);
clear_obj(FFTConvol);
}
Result
gen lowpass returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is raised.
Parallelization Information
gen lowpass is reentrant and processed without parallelization.
convol fft
gen circle, paint region
Possible Successor Functions
Alternatives
See Also
gen highpass, gen bandpass, gen bandfilter
Image filters
Module
gen sin bandpass ( Hobject *ImageFilter, double Frequency, long Size )
Generate a bandpass filter with sinusoidal shape.
gen sin bandpass generates a rotationally invariant bandpass filter with the response being a sinusoidal function
in the frequency domain. The maximum of the sine (255) is determined by Frequency (distance from the
DC term in pixels). The filter is always zero for the DC term, rises with the sine function up to Frequency,and
drops for higher frequencies accordingly. The range of the sine used is from ¼ to . All other points are set to zero.
Parameter
º ImageFilter (output object) ......................................image(-array) Hobject * : byte
Bandpass filter as image in the frequency domain.
HALCON 6.0

98 CHAPTER 3. FILTER
º Frequency (input control) ...........................................................real double
Distance of the filter’s maximum from the DC term.
Default Value : 20
Value Suggestions : Frequency ¾0.0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 80, 100, 150, 200
Typical Range of Values : 0.0 Frequency 1000
Minimal Value Step : 1
Recommended Value Step : 2
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
Result
gen sin bandpass returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is
raised.
Parallelization Information
gen sin bandpass is reentrant and processed without parallelization.
fft image, fft generic
convol fft
Possible Predecessor Functions
Possible Successor Functions
Alternatives
gen std bandpass, gen bandpass, gen bandfilter, gen highpass, gen lowpass
fft image inv
Image filters
See Also
Module
gen std bandpass ( Hobject *ImageFilter, double Frequency, double Sigma,
long Size, const char *Mode )
Generate a bandpass filter with Gaussian or sinusoidal shape.
gen std bandpass generates a rotationally invariant bandpass filter with the response being determined by
the parameters Frequency and Sigma: Frequency determines the location of the maximum response with
respect to the DC term, while Sigma determines the width of the frequency band that passes the filter. For Mode
= ’gauss’, a Gaussian response is generated with Sigma being the standard deviation. For Mode = ’sin’, asine
function is generated with the maximum at Frequency and the extent Sigma.
Parameter
º ImageFilter (output object) ......................................image(-array) Hobject * : byte
Bandpass filter as image in the frequency domain.
º Frequency (input control) ...........................................................real double
Distance of the filter’s maximum from the DC term.
Default Value : 20
Value Suggestions : Frequency ¾0.0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 80, 100, 150, 200
Typical Range of Values : 0.0 Frequency 1000
Minimal Value Step : 1
Recommended Value Step : 2
º Sigma (input control) .................................................................real double
Bandwidth of the filter (standard deviation).
Default Value : 1.0
Value Suggestions : Sigma ¾0.1, 0.3, 0.7, 1.0, 1.5, 2.0, 3.0, 5.0, 7.0, 10.0, 15.0, 20.0, 30.0, 50.0
Typical Range of Values : 0.05 Sigma 100.0
Minimal Value Step : 0.001
Recommended Value Step : 0.1
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 99
º Size (input control) .................................................................integer long
Size (dimension) of the image (filter).
Default Value : 512
Value List : Size ¾8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
º Mode (input control) ............................................................string const char *
Filter type.
Default Value : ’sin’
Value List : Mode ¾’sin’, ’gauss’
Result
gen std bandpass returns H MSG TRUE if all parameters are correct. If necessary, an exception handling is
raised.
Parallelization Information
gen std bandpass is reentrant and processed without parallelization.
fft image, fft generic
convol fft
Possible Predecessor Functions
Possible Successor Functions
Alternatives
gen sin bandpass, gen bandpass, gen bandfilter, gen highpass, gen lowpass
fft image inv
Image filters
See Also
Module
phase deg ( Hobject ImageComplex, Hobject *ImagePhase )
Return the phase of a complex image in degrees.
phase deg computes the phase of a complex image in degrees. The following formula is used:
Ô×
½¼ØÒ ½´ÑÒÖÝÔÖØÖÐÔÖص
Parameter
º ImageComplex (input object) ....................................image(-array) Hobject : complex
Input image in frequency domain.
º ImagePhase (output object) ...................................image(-array) Hobject * : direction
Phase of the image in degrees.
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
fft_image(Image,&FFT);
phase_deg(FFT,&Phase);
disp_image(Phase,WindowHandle);
Example
Result
phase deg returns H MSG TRUE if the image is of correct type. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
phase deg is reentrant and automatically parallelized (on tuple level, domain level).
fft image, fft generic
Possible Predecessor Functions
HALCON 6.0

100 CHAPTER 3. FILTER
disp image
phase rad
fft image inv
Image filters
Possible Successor Functions
Alternatives
See Also
Module
phase rad ( Hobject ImageComplex, Hobject *ImagePhase )
Return the phase of a complex image in radians.
phase rad computes the phase of a complex image in radians. The following formula is used:
Ô× ØÒ ½´ÑÒÖÝÔÖØÖÐÔÖص
Parameter
º ImageComplex (input object) ....................................image(-array) Hobject : complex
Input image in frequency domain.
º ImagePhase (output object) ........................................image(-array) Hobject * : real
Phase of the image in radians.
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
fft_image(Image,&FFT);
phase_rad(FFT,&Phase);
disp_image(Phase,WindowHandle);
Result
phase rad returns H MSG TRUE if the image is of correct type. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
phase rad is reentrant and automatically parallelized (on tuple level, domain level).
fft image, fft generic
disp image
phase deg
fft image inv
Image filters
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
power byte ( Hobject Image, Hobject *PowerByte )
Return the power spectrum of a complex image.
power byte computes the power spectrum from the real and imaginary parts of a Fourier-transformed image
(see fft image), i.e., the modulus of the frequencies. The result image is of type ’byte’. The following formula
is used:
HALCON/C Reference Manual / 2000-11-15

3.7. FFT 101
Ô
ÖÐÔÖؾ · ÑÒÖÝÔÖØ ¾
Parameter
º Image (input object) ..............................................image(-array) Hobject : complex
Input image in frequency domain.
º PowerByte (output object) .........................................image(-array) Hobject * : byte
Power spectrum of the input image.
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
fft_image(Image,&FFT);
power_byte(FFT,&Power);
disp_image(Power,WindowHandle);
Result
power byte returns H MSG TRUE if the image is of correct type. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
power byte is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessor Functions
fft image, fft generic, convol fft, convol gabor
disp image
Possible Successor Functions
Alternatives
abs image, convert image type, power real, power ln
fft image
Image filters
See Also
Module
power ln ( Hobject Image, Hobject *ImageResult )
Return the power spectrum of a complex image.
power ln computes the power spectrum from the real and imaginary parts of a Fourier-transformed image (see
fft image), i.e., the modulus of the frequencies. Additionally, the natural logarithm is applied to the result. The
result image is of type ’real’. The following formula is used:
ÐÒ
Ô
ÖÐÔÖؾ · ÑÒÖÝÔÖØ ¾
Parameter
º Image (input object) ..............................................image(-array) Hobject : complex
Input image in frequency domain.
º ImageResult (output object) .......................................image(-array) Hobject * : real
Power spectrum of the input image.
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
fft_image(Image,&FFT);
power_real(FFT,&Power);
disp_image(Power,WindowHandle);
HALCON 6.0

102 CHAPTER 3. FILTER
Result
power ln returns H MSG TRUE if the image is of correct type. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
power ln is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessor Functions
fft image, fft generic, convol fft, convol gabor
Possible Successor Functions
disp image, convert image type, scale image
Alternatives
abs image, convert image type, power real, power byte
fft image, fft generic
Image filters
See Also
Module
power real ( Hobject Image, Hobject *ImageResult )
Return the power spectrum of a complex image.
power real computes the power spectrum from the real and imaginary parts of a Fourier-transformed image
(see fft image), i.e., the modulus of the frequencies. The result image is of type ’real’. The following formula
is used:
Ô
ÖÐÔÖؾ · ÑÒÖÝÔÖØ ¾
Parameter
º Image (input object) ..............................................image(-array) Hobject : complex
Input image in frequency domain.
º ImageResult (output object) .......................................image(-array) Hobject * : real
Power spectrum of the input image.
Example
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
fft_image(Image,&FFT);
power_real(FFT,&Power);
disp_image(Power,WindowHandle);
Result
power real returns H MSG TRUE if the image is of correct type. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
power real is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessor Functions
fft image, fft generic, convol fft, convol gabor
Possible Successor Functions
disp image, convert image type, scale image
Alternatives
abs image, convert image type, power byte, power ln
fft image
Image filters
See Also
Module
HALCON/C Reference Manual / 2000-11-15

3.8. LINES 103
3.8 Lines
bandpass image ( Hobject Image, Hobject *ImageBandpass,
const char *FilterType )
Edge extraction using bandpass filters.
bandpass image serves as an edge filter. It applies a linear filter with the following convolution mask to
Image:
FilterType: ’lines’
In contrast to the edge operator sobel amp this filter detects lines instead of edges, i.e., two closely adjacent
edges.
¼ ¾ ¾ ¾ ¼
¾ ¼ ¿ ¼ ¾
¾ ¿ ½¾ ¿ ¾
¾ ¼ ¿ ¼ ¾
¼ ¾ ¾ ¾ ¼
At the border of the image the gray values are mirrored. Over- and underflows of gray values are clipped to the
interval [0,255]. The resulting images are returned in ImageBandpass.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input images.
º ImageBandpass (output object) . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Bandpass-filtered images.
º FilterType (input control) ...................................................string const char *
Filter type: currently only ’lines’ is supported.
Default Value : ’lines’
Value List : FilterType ¾’lines’
Example
bandpass_image(Image,&LineImage,"lines");
threshold(LineImage,&Lines,60.0,255.0);
skeleton(Lines,&ThinLines);
Result
bandpass image returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
bandpass image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
threshold, skeleton
Possible Successor Functions
Alternatives
convol image, topographic sketch, (T )texture laws
highpass image, gray skeleton
Image filters
See Also
Module
lines facet ( Hobject Image, Hobject *Lines, long MaskSize, double Low,
double High, const char *LightDark )
Detection of lines using the facet model.
HALCON 6.0

104 CHAPTER 3. FILTER
The operator lines facet can be used to extract lines (curvilinear structures) from the image Image. The
extracted lines are returned in Lines as sub-pixel precise XLD-contours. The parameter LightDark determines,
whether bright or dark lines are extracted.
The extraction is done by using the facet model, i.e., a least squares fit, to determine the parameters of a quadratic
polynomial in x and y for each point of the image. The parameter MaskSize determines the size of the window
used for the least squares fit. Larger values of MaskSize lead to a larger smoothing of the image, but can
lead to worse localization of the line. The parameters of the polynomial are used to calculate the line direction
for each pixel. Pixels which exhibit a local maximum in the second directional derivative perpendicular to the
line direction are marked as line points. The line points found in this manner are then linked to contours. This
is done by immediately accepting line points that have a second derivative larger than High. Points that have
a second derivative smaller than Low are rejected. All other line points are accepted if they are connected to
accepted points by a connected path. This is similar to a hysteresis threshold operation with infinite path length (see
hysteresis threshold). However, this function is not used internally since it does not allow the extraction
of sub-pixel precise contours.
The gist of how to select the thresholds in the description of lines gauss also holds for this operator. A value
of Sigma = 1.5 there roughly corresponds to a MaskSize of 5 here.
The extracted lines are returned in a topologically sound data structure in Lines. This means that lines are
correctly split at junction points.
Attention
The smaller the filter size MaskSize is chosen, the more short, fragmented lines will be extracted. This can lead
to considerably longer execution times.
Parameter
º Image (input object) ......................singlechannel-image Hobject : byte / int1 / int2 / int4 / real
Input image.
º Lines (output object) ....................................................xld cont-array Hobject *
Extracted lines.
º MaskSize (input control) ............................................................integer long
Size of the facet model mask.
Default Value : 5
Value List : MaskSize ¾3, 5, 7, 9, 11
º Low (input control) ..........................................................number double / long
Lower threshold for the hysteresis threshold operation.
Default Value : 3
Value Suggestions : Low ¾0, 0.5, 1, 2, 3, 4, 5, 8, 10
Typical Range of Values : 0 Low 20
Recommended Value Step : 0.5
Restriction : Low 0
º High (input control) ........................................................number double / long
Upper threshold for the hysteresis threshold operation.
Default Value : 8
Value Suggestions : High ¾0, 0.5, 1, 2, 3, 4, 5, 8, 10, 12, 15, 18, 20, 25
Typical Range of Values : 0 High 35
Recommended Value Step : 0.5
Restriction : ´High 0µ ´High Lowµ
º LightDark (input control) .....................................................string const char *
Extract bright or dark lines.
Default Value : ’light’
Value List : LightDark ¾’dark’, ’light’
Example
/* Detection of lines in an aerial image */
read_image(&Image,"mreut4_3");
lines_facet(Image:&Lines:5,3,8,"light");
disp_xld(Lines,WindowHandle);
Result
lines facet returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
HALCON/C Reference Manual / 2000-11-15

3.8. LINES 105
input is empty the behaviour can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
lines facet is reentrant and automatically parallelized (on tuple level).
gen polygons xld
lines gauss
Possible Successor Functions
Alternatives
See Also
bandpass image, dyn threshold, topographic sketch
Bibliography
A. Busch: ”‘Fast Recognition of Lines in Digital Images Without User-Supplied Parameters”’. In H. Ebner, C.
Heipke, K.Eder, eds., ”‘Spatial Information from Digital Photogrammetry and Computer Vision”’, International
Archives of Photogrammetry and Remote Sensing, Vol. 30, Part 3/1, pp. 91-97, 1994.
Module
Sub-pixel operators
lines gauss ( Hobject Image, Hobject *Lines, double Sigma, double Low,
double High, const char *LightDark, const char *ExtractWidth,
const char *CorrectPositions, const char *CompleteJunctions )
Detect lines and their width.
The operator lines gauss can be used to extract lines (curvilinear structures) from the image Image. Theextracted
lines are returned in Lines as sub-pixel precise XLD-contours. The parameter LightDark determines,
whether bright or dark lines are extracted. If ExtractWidth is set to ’true’ the line width is extracted for each
line point. If CorrectPositions is set to ’true’, lines gauss compensates the effect of asymmetrical lines
(lines having different contrast on each side of the line), and corrects the position and width of the line. This parameter
is only meaningful if ExtractWidth=’true’. Because the line extractor is unable to extract certain junctions
because of differential geometric reasons, it tries to extract these by different means if CompleteJunctions is
set to ’true’.
The extraction is done by using partial derivatives of a Gaussian smoothing kernel to determine the parameters
of a quadratic polynomial in x and y for each point of the image. The parameter Sigma determines the amount
of smoothing to be performed. Larger values of Sigma lead to a larger smoothing of the image, but can lead
to worse localization of the line. Generally, the localization will be much better than that of lines returned by
lines facet with comparable parameters. The parameters of the polynomial are used to calculate the line
direction for each pixel. Pixels which exhibit a local maximum in the second directional derivative perpendicular
to the line direction are marked as line points. The line points found in this manner are then linked to contours.
This is done by immediately accepting line points that have a second derivative larger than High. Points that
have a second derivative smaller than Low are rejected. All other line points are accepted if they are connected to
accepted points by a connected path. This is similar to a hysteresis threshold operation with infinite path length (see
hysteresis threshold). However, this function is not used internally since it does not allow the extraction
of sub-pixel precise contours.
For the choice of the thresholds High and Low one has to keep in mind that the second directional derivative
depends on the amplitude and width of the line as well as the choice of Sigma. The value of the second derivative
depends linearly on the amplitude, i.e., the larger the amplitude, the larger the response. For the width of the
line there is an approximately inverse exponential dependence: The wider the line is, the smaller the response
gets. This holds analogously for the dependence on Sigma: ThelargerSigma is chosen, the smaller the second
derivative will be. This means that for larger smoothing correspondingly smaller values for High and Low have
to be chosen. Two examples help to illustrate this: If 5 pixel wide lines with an amplitude larger than 100 are to be
extracted from an image with a smoothing of Sigma =1.5,High should be chosen larger than 14. If, on the other
hand, 10 pixel wide lines with an amplitude larger than 100 and a Sigma = 3 are to be detected, High should be
chosen larger than 3.5. For the choice of Low values between 0.25 High and 0.5 High are appropriate.
The extracted lines are returned in a topologically sound data structure in Lines. This means that lines are
correctly split at junction points.
HALCON 6.0

106 CHAPTER 3. FILTER
lines gauss defines the following attributes for each line point if ExtractWidth was set to ’false’:
’angle’ The angle of the direction perpendicular to the line
’response’ The magnitude of the second derivative
If ExtractWidth was set to ’true’ and CorrectPositions to ’false’, the following attributes are defined
in addition to the above ones:
’width left’ The line width to the left of the line
’width right’ The line width to the right of the line
Finally, if CorrectPositions was set to ’true’, additionally the following attributes are defined:
’asymmetry’ The asymmetry of the line point
’contrast’ The contrast of the line point
Here, the asymmetry is positive if the asymmetric part, i.e., the part with the weaker gradient, is on the right side of
the line, while it is negative if the asymmetric part is on the left side of the line. All these attributes can be queried
via the operator get contour attrib xld.
Attention
In general, but in particular if the line width is to be extracted, ËÑ Û Ô ¿ should be selected, where Û is
the width (half the diameter) of the lines in the image. As the lowest allowable value ËÑ Û¾ must be
selected. If, for example, lines with a width of 4 pixels (diameter 8 pixels) are to be extracted, ËÑ ¾¿ should
be selected.
Parameter
º Image (input object) ......................singlechannel-image Hobject : byte / int1 / int2 / int4 / real
Input image.
º Lines (output object) ....................................................xld cont-array Hobject *
Extracted lines.
º Sigma (input control) .......................................................number double / long
Amount of Gaussian smoothing to be applied.
Default Value : 1.5
Value Suggestions : Sigma ¾1, 1.2, 1.5, 1.8, 2, 2.5, 3, 4, 5
Typical Range of Values : 0.7 Sigma 20
Recommended Value Step : 0.1
º Low (input control) ..........................................................number double / long
Lower threshold for the hysteresis threshold operation.
Default Value : 3
Value Suggestions : Low ¾0, 0.5, 1, 2, 3, 4, 5, 8, 10
Typical Range of Values : 0 Low 20
Recommended Value Step : 0.5
Restriction : Low 0
º High (input control) ........................................................number double / long
Upper threshold for the hysteresis threshold operation.
Default Value : 8
Value Suggestions : High ¾0, 0.5, 1, 2, 3, 4, 5, 8, 10, 12, 15, 18, 20, 25
Typical Range of Values : 0 High 35
Recommended Value Step : 0.5
Restriction : ´High 0µ ´High Lowµ
º LightDark (input control) .....................................................string const char *
Extract bright or dark lines.
Default Value : ’light’
Value List : LightDark ¾’dark’, ’light’
º ExtractWidth (input control) .................................................string const char *
Should the line width be extracted?
Default Value : ’true’
Value List : ExtractWidth ¾’true’, ’false’
º CorrectPositions (input control) ...........................................string const char *
Should the line position and width be corrected?
Default Value : ’true’
Value List : CorrectPositions ¾’true’, ’false’
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 107
º CompleteJunctions (input control) ..........................................string const char *
Should junctions be added where they cannot be extracted?
Default Value : ’true’
Value List : CompleteJunctions ¾’true’, ’false’
Example
/* Detection of lines in an aerial image */
read_image(&Image,"mreut4_3");
lines_gauss(Image:&Lines:1.5,3,8,"light","true","true","true");
disp_xld(Lines,WindowHandle);
Result
lines gauss returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
input is empty the behaviour can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
lines gauss is reentrant and automatically parallelized (on tuple level).
gen polygons xld
lines facet
Possible Successor Functions
Alternatives
See Also
bandpass image, dyn threshold, topographic sketch
Bibliography
C. Steger: “Extracting Curvilinear Structures: A Differential Geometric Approach”. In B. Buxton, R. Cipolla, eds.,
“Fourth European Conference on Computer Vision”, Lecture Notes in Computer Science, Volume 1064, Springer
Verlag, pp. 630-641, 1996.
C. Steger: “Extraction of Curved Lines from Images”. In “13th International Conference on Pattern Recognition”,
Volume II, pp. 251-255, 1996.
C. Steger: “An Unbiased Detector of Curvilinear Structures”. Technical Report FGBV-96-03, Forschungsgruppe
Bildverstehen (FG BV), Informatik IX, Technische Universit”at M”unchen, July 1996.
Module
Sub-pixel operators
3.9 Match
adapt template ( Hobject Image, long TemplateID )
Adapting a template to the size of an image.
The operator adapt template serves to adapt a template which has been created by create template to
the size of an image. The operator adapt template can be called before the template is used with images of
another size, or if the image used to create the template had another size. If it is not called explicitly it will be
called internally each time another image size is used. The contents of the image is hereby irrelevant; only the
width of Image will be considered.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image which determines the size of the later matching.
º TemplateID (input control) ........................................................template long
Template number.
HALCON 6.0

108 CHAPTER 3. FILTER
Result
If the parameter values are correct, the operator adapt template returns the value H MSG TRUE. If necessary,
an exception handling is raised.
Parallelization Information
adapt template is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
create template, create template rot, read template
Possible Successor Functions
set reference template, (T )best match, fast match, (T )fast match mg,
set offset template, best match mg, best match pre mg, (T )best match rot,
(T )best match rot mg
Module
Template matching
best match ( Hobject Image, long TemplateID, double MaxError,
const char *SubPixel, double *Row, double *Column, double *Error )
T best match ( Hobject Image, Htuple TemplateID, Htuple MaxError,
Htuple SubPixel, Htuple *Row, Htuple *Column, Htuple *Error )
Searching the best matching of a template and an image.
The operator (T )best match performs a matching of the template of TemplateID and Image. Hereby
the template will be moved over the points of Image so that the template will lie always inside Image.
(T )best match works similar to fast match, with the exception, that each time a better match is found
the value of MaxError is internally updated to a lower value to reduce runtime.
With regard to the parameter SubPixel, the position will be indicated by subpixel accuracy. The matching
criterion (“displaced frame difference”) is defined as follows:
È
ÙÚ ÁÑÖÓÛ Ù ÓÐ Ú℄ ÌÑÔÐØÁÙ Ú℄
ÖÖÓÖÖÓÛ ÓÐ℄
Ö´Ì ÑÔÐØÁµ
The runtime of the operator depends on the size of the domain of Image. Therefore it is important to restrict the
domain as far as possible, i.e. to apply the operator only in a very confined “region of interest”. The parameter
MaxError determines the maximal error which the searched position is allowed to have at most. The lower this
value is, the faster the operator runs.
Row and Column return the position of the best match, whereby Error indicates the average difference of the
grayvalues. If no position with an error below MaxError was found the position ´¼ ¼µ and a matching result of
¾ for Error are returned. In this case MaxError has to be set larger.
The maximum error of the position (without noise) is ¼½ pixel. The average error is ¼¼¿ pixel.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
º TemplateID (input control) ..............................................template (Htuple .) long
Template number.
º MaxError (input control) ...................................................real (Htuple .) double
Maximum average difference of the grayvalues.
Default Value : 20
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 0, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 3
º SubPixel (input control) .............................................string (Htuple .) const char *
Subpixel accuracy in case of ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 109
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row position of the best match.
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column position of the best match.
º Error (output control) .............................................real(-array) (Htuple .) double *
Average divergence of the grayvalues of the best match.
Result
If the parameter values are correct, the operator (T )best match returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
(T )best match is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template, read template, set offset template, set reference template,
adapt template, draw region, draw rectangle1, reduce domain
Alternatives
fast match, (T )fast match mg, best match mg, best match pre mg, (T )best match rot,
(T )best match rot mg, exhaustive match, exhaustive match mg
Template matching
Module
best match mg ( Hobject Image, long TemplateID, double MaxError,
const char *SubPixel, long NumLevels, long WhichLevels, double *Row,
double *Column, double *Error )
Searching the best grayvalue matches in a pyramid.
best match mg applies gray value matching using an image pyramid. best match mg works analogously
to (T )best match, but it is faster due to the use of a pyramid. Input is an image with an optionally reduced
domain. The paramter MaxError specifies the maximum error for template matching. Using smaller values
results in a reduced runtime but it is possible that the pattern might be missed. The value of MaxError has to set
larger compared with (T )best match, because the error is at higher levels of the pyramid often increased.
SubPixel specifies if the result is calculated with sub pixel accuracy or not. A value of 1 for SubPixel results
in an operator similar to (T )best match, i.e. only the original gray values are used. For values larger than 1,
the algorithm starts at the lowest resultion and searches for a position with the lowest matching error. At the next
higher resolution this position is refined. This is continued up to the maximum resolution (WhichLevels = ’all’).
As an alternative Method the mode WhichLevels with value ’original’ can be used. In this case not only the
position with the lowest error but all points below MaxError are analysed further on in the next higher resolution.
This method is slower but it is more stable and the possibilty to miss the correct position is very low. In this case
it is often possible to start with a lower resolution (higher level in Pyramid, i.e. larger value for NumLevels)
which leads to a reduced runtime. Besides the values ’all’ and ’original’ for WhichLevels you can specify
the pyramid level explicitly where to switch between a “match all” and the ”best match”. Here 0 corresponds to
’original’ and NumLevels - 1 is equivalent to ’all’. A value in between is in most cases a good compromise
between speed and a stable detection. A larger value for WhichLevels results in a reduced runtime, a smaller
value results in a more stable detection. The value of NumLevels has to equal or smaller than the value used to
create the template.
The position of the found matching position is returned in Row and Column. The corresponding error is given
in Error. If no point below MaxError is found a value of 255 for Error and 0 for Row and Column is
returned. If the desired object is missed (no object found or wrong position) you have to set MaxError higher or
WhichLevels lower. Check also if the illumination has changed (see set offset template).
The maximum error of the position (without noise) is ¼½ pixel. The average error is ¼¼¿ pixel.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
HALCON 6.0

110 CHAPTER 3. FILTER
º TemplateID (input control) ........................................................template long
Template number.
º MaxError (input control) .............................................................real double
Maximal average difference of the grayvalues.
Default Value : 30
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 3
º SubPixel (input control) ......................................................string const char *
Exactness in subpixels in case of ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
º NumLevels (input control) ...........................................................integer long
Number of the used resolution levels.
Default Value : 4
Value List : NumLevels ¾1, 2, 3, 4, 5, 6
º WhichLevels (input control) ...........................................integer long / const char *
Resolution level up to which the method “best match” is used.
Default Value : 2
Value Suggestions : WhichLevels ¾’all’, ’original’, 0, 1, 2, 3, 4, 5, 6
º Row (output control) ..............................................................point.y double *
Row position of the best match.
º Column (output control) ..........................................................point.x double *
Column position of the best match.
º Error (output control) ..............................................................real double *
Average divergence of the grayvalues in the best match.
Result
If the parameter values are correct, the operator best match mg returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
best match mg is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template, read template, adapt template, draw region, draw rectangle1,
reduce domain, set reference template, set offset template
Alternatives
fast match, (T )fast match mg, (T )best match, best match pre mg, (T )best match rot,
(T )best match rot mg, exhaustive match, exhaustive match mg
Template matching
Module
best match pre mg ( Hobject ImagePyramid, long TemplateID,
double MaxError, const char *SubPixel, long NumLevels, long WhichLevels,
double *Row, double *Column, double *Error )
Searching the best grayvalue matches in a pre generated pyramid.
best match pre mg applies gray value matching using an image pyramid. best match pre mg works analogously
to best match mg, but it makes use of pre calculated pyramid which has to be generated beforehand
using gen gauss pyramid. This reduces runtime if more than one match has to be done or the pyramid has be
used otherwise. The pyramid has to be generated using the zooming factor 0.5 and the mode ’constant’.
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 111
Parameter
º ImagePyramid (input object) ..........................................image-array Hobject : byte
Image pyramid inside of which the pattern has to be found.
º TemplateID (input control) ........................................................template long
Template number.
º MaxError (input control) .............................................................real double
Maximal average difference of the grayvalues.
Default Value : 30
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 3
º SubPixel (input control) ......................................................string const char *
Exactness in subpixels in case of ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
º NumLevels (input control) ...........................................................integer long
Number of the used resolution levels.
Default Value : 3
Value List : NumLevels ¾1, 2, 3, 4, 5, 6
º WhichLevels (input control) ...........................................integer long / const char *
Resolution level up to which the method “best match” is used.
Default Value : ’original’
Value Suggestions : WhichLevels ¾’all’, ’original’, 0, 1, 2, 3, 4, 5, 6
º Row (output control) ..............................................................point.y double *
Row position of the best match.
º Column (output control) ..........................................................point.x double *
Column position of the best match.
º Error (output control) ..............................................................real double *
Average divergence of the grayvalues in the best match.
Result
If the parameter values are correct, the operator best match pre mg returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
best match pre mg is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gen gauss pyramid, create template, read template, adapt template, draw region,
draw rectangle1, reduce domain, set reference template
Alternatives
fast match, (T )fast match mg, exhaustive match, exhaustive match mg
Template matching
Module
best match rot ( Hobject Image, long TemplateID, double AngleStart,
double AngleExtend, double MaxError, const char *SubPixel, double *Row,
double *Column, double *Angle, double *Error )
T best match rot ( Hobject Image, Htuple TemplateID, Htuple AngleStart,
Htuple AngleExtend, Htuple MaxError, Htuple SubPixel, Htuple *Row,
Htuple *Column, Htuple *Angle, Htuple *Error )
Searching the best matching of a template and an image with rotation.
The operator (T )best match rot performs a matching of the template of TemplateID and Image.
It works similar to (T )best match with the extension that the pattern can be rotated. The parameters
HALCON 6.0

112 CHAPTER 3. FILTER
AngleStart and AngleExtend define the maximum rotation of the pattern: AngleStart specifies the maximum
counter clockwise rotation and AngleExtend the maximum clockwise rotation relative to this angle. Both
values have to smaller or equal to the values used for the creation of the pattern (see create template rot).
In addition to (T )best match (T )best match rot returns the rotion angle of the pattern in Angle (radiant).
The accuracy of this angle depends on the parameter AngleStep of create template rot. In the case
of SubPixel = ’true’ the position and the angle are calculated with “sub pixel” accuracy.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
º TemplateID (input control) ..............................................template (Htuple .) long
Template number.
º AngleStart (input control) ...........................................angle.rad (Htuple .) double
Smallest Rotation auf the pattern.
Default Value : -0.39
Value Suggestions : AngleStart ¾-3.14, -1.57, -0.79, -0.39, -0.20, 0.0
º AngleExtend (input control) ..........................................angle.rad (Htuple .) double
Maximum positive Extention of AngleStart.
Default Value : 0.79
Value Suggestions : AngleExtend ¾6.28, 3.14, 1.57, 0.79, 0.39
Restriction : AngleExtend 0
º MaxError (input control) ...................................................real (Htuple .) double
Maximum average difference of the grayvalues.
Default Value : 30
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 3
º SubPixel (input control) .............................................string (Htuple .) const char *
Subpixel accuracy in case of ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row position of the best match.
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column position of the best match.
º Angle (output control) ........................................angle.rad(-array) (Htuple .) double *
Rotation angle of pattern.
º Error (output control) .............................................real(-array) (Htuple .) double *
Average divergence of the grayvalues of the best match.
Result
If the parameter values are correct, the operator (T )best match rot returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
(T )best match rot is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template rot, read template, set offset template, set reference template,
adapt template, draw region, draw rectangle1, reduce domain
(T )best match rot mg
(T )best match, best match mg
Template matching
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 113
best match rot mg ( Hobject Image, long TemplateID, double AngleStart,
double AngleExtend, double MaxError, const char *SubPixel, long NumLevels,
double *Row, double *Column, double *Angle, double *Error )
T best match rot mg ( Hobject Image, Htuple TemplateID,
Htuple AngleStart, Htuple AngleExtend, Htuple MaxError, Htuple SubPixel,
Htuple NumLevels, Htuple *Row, Htuple *Column, Htuple *Angle,
Htuple *Error )
Searching the best matching of a template and a pyramid with rotation.
The operator (T )best match rot mg performs a matching of the template of TemplateID and Image.
It works similar to best match mg with the extension that the pattern can be rotated analogously to
(T )best match rot. The parameters AngleStart and AngleExtend define the maximum rotation of
the pattern: AngleStart specifies the maximum counter clockwise rotation and AngleExtend the maximum
clockwise rotation relative to this angle. Both values have to smaller or equal to the values used for the creation
of the pattern (see create template rot). In addition to best match mg (T )best match rot mg
returns the rotion angle of the pattern in Angle (radiant).
The value of MaxError has to set larger compared with (T )best match rot, because the error is at higher
levels of the pyramid often increased.
In the case of SubPixel = ’true’ the position and the angle are calculated with “sub pixel” accuracy.
The value of NumLevels has to equal or smaller than the value used to create the template.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
º TemplateID (input control) ..............................................template (Htuple .) long
Template number.
º AngleStart (input control) ...........................................angle.rad (Htuple .) double
Smallest Rotation auf the pattern.
Default Value : -0.39
Value Suggestions : AngleStart ¾-3.14, -1.57, -0.79, -0.39, -0.20, 0.0
º AngleExtend (input control) ..........................................angle.rad (Htuple .) double
Maximum positive Extention of AngleStart.
Default Value : 0.79
Value Suggestions : AngleExtend ¾6.28, 3.14, 1.57, 0.79, 0.39
Restriction : AngleExtend 0
º MaxError (input control) ...................................................real (Htuple .) double
Maximum average difference of the grayvalues.
Default Value : 40
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 1
º SubPixel (input control) .............................................string (Htuple .) const char *
Subpixel accuracy in case of ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
º NumLevels (input control) .................................................integer (Htuple .) long
Number of the used resolution levels.
Default Value : 3
Value List : NumLevels ¾1, 2, 3, 4, 5, 6
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row position of the best match.
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column position of the best match.
º Angle (output control) ........................................angle.rad(-array) (Htuple .) double *
Rotation angle of pattern.
HALCON 6.0

114 CHAPTER 3. FILTER
º Error (output control) .............................................real(-array) (Htuple .) double *
Average divergence of the grayvalues of the best match.
Result
If the parameter values are correct, the operator (T )best match rot mg returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
(T )best match rot mg is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template rot, set reference template, set offset template, adapt template,
draw region, draw rectangle1, reduce domain
(T )best match rot, best match mg
fast match
Template matching
Alternatives
See Also
Module
clear template ( long TemplateID )
Deallocation of the memory of a template.
The operator clear template deallocates the memory of a template which has been created by
create template or create template rot. After execution of the operator clear template the template
can no longer be used. The value of TemplateID is not valid. However, the number can be used again by
further calls of create template or create template rot.
Parameter
º TemplateID (input control) ........................................................template long
Template number.
Result
If the number of the template is valid, the operator clear template returns the value H MSG TRUE. If necessary
an exception handling will be raised.
Parallelization Information
clear template is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create template, create template rot, read template, write template
Template matching
Module
corner response ( Hobject Image, Hobject *ImageCorner, long Size,
double Weight )
Searching corners in images.
The operator corner response helps to extract grayvalue corners in an image. The formula for the calculation
is as follows:
Ê´Ü Ýµ ´Ü ݵ ¡ ´Ü ݵ ¾´Ü ݵ Ï Ø ¡ ´´Ü ݵ ·´Ü ݵµ ¾
´Ü ݵ Ï ´Ù Úµ £ ´Ö Ü Á´Ü ݵµ ¾
´Ü ݵ Ï ´Ù Úµ £ ´Ö Ý Á´Ü ݵµ ¾
´ ݵ Ï ´Ù Úµ £ ´Ö Ü Á´Ü ÝµÖ Ý Á´Ü ݵµ
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 115
whereby Á is the input image and Ê the output image of the filtering. The operator gauss image is used for
smoothing (Ï ), the operator sobel amp is used for calculating the derivative (Ö).
The corner response function is invariant with regard to rotation. In order to achieve a suitable dependency of
the function Ê´Ü Ýµ of the local gradient, the parameter Weight has to be set to 0.04. Thereby only grayvalue
corners will return positive values for Ê´Ü Ýµ, while straight edges will receive negative values (due to clipping
they are set to 0).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageCorner (output object) . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject * : byte
Result of the filtering.
Parameter Number : ImageCorner Image
º Size (input control) .................................................................integer long
Desired filtersize of the graymask.
Default Value : 3
Value List : Size ¾3, 5, 7, 9, 11
º Weight (input control) ...............................................................real double
Weighting.
Default Value : 0.04
Typical Range of Values : 0.0 Weight 0.3
Minimal Value Step : 0.001
Recommended Value Step : 0.01
Example
read_image(&Fabrik,"fabrik");
corner_response(Fabrik,&CornerResponse,3,0.04);
local_max(CornerResponse,&LocalMax);
disp_image(Fabrik,WindowHandle);
set_color(WindowHandle,"red");
disp_region(LocalMax,WindowHandle);
Parallelization Information
corner response is reentrant and automatically parallelized (on tuple level, channel level, domain level).
local max, threshold
gauss image, sobel amp
Possible Successor Functions
See Also
Bibliography
C.G. Harris, M.J. Stephens, “A combined corner and edge detector”’; Proc. of the 4th Alvey Vision Conference;
August 1988; pp. 147-152.
H. Breit, “Bestimmung der Kameraeigenbewegung und Gewinnung von Tiefendaten aus monokularen Bildfolgen”;
Diplomarbeit am Lehrstuhl f”ur Nachrichtentechnik der TU M”unchen; 30. September 1990.
Module
Image filters
create template ( Hobject Template, long FirstError, long NumLevel,
const char *Optimize, const char *GrayValues, long *TemplateID )
Preparing a pattern for template matching.
The operator create template preprocesses a pattern (Template),whichispassedasanimage,forthe
template matching. After the transformation, a number (TemplateID) is assigned to the template for being used
in the further process. The shape and the size of Template can be chosen arbitrarily. You have to be aware, that
the matching is only applied to that part of an image where Template fits completely into the image.
HALCON 6.0

116 CHAPTER 3. FILTER
The template has be chosen such that it contains no pixels of the (changing) background. Here you can make
use of the artitrary shape of a template which is not restricted to a rectangle. To create a template you can use
segmentation operators like threshold. In the case of sub pixel accurate matching Template has in addition
to be one pixel smaller than the pattern (i.e. one pixel border to the changing background). This can be done e.g.
by applying the operator erosion circle.
The parameter NumLevel specifies the number of pyramid levels (NumLevel = 1 means only original gray
values) which can be used for matching. The number of levels used later for matching will be below or equal this
value. If the pattern becomes to small due to zooming, the maximum number of pyramid levels is automatically
reduced (without error message).
The parameter GrayValues defines, wheter the original gray values (’original’, ’normalized) or the edge amplitude
(’gradient’, ’sobel’) is used. With ’original’ the sum of the differences is used as feature which is very
stable and fast if there is no change in illumination. ’normalized is used if the illumination changes. The method
is a bit slower and not quite as stable. If there is no change in illumination the mode ’original’ should be used.
The edge amplitude is another method to be invariant to changes in illumination. The disadvantage is the increased
execution time and the higher sensitivity to changes in the shape of the pattern. The mode ’gradient’ is slighy
faster but more sensitive to noise.
The maximum error for matching has typically to be chosen higher when using the edge amplitude. The mode
chosen by GrayValues leads automatically to calling the appropriate filter during matching — if necessary.
As an alternative to the gradient approach the operator set offset template can be used, if the change in
illumination is known.
The parameter Optimize specifies if the pattern has to optimized for runtime. This optimization results in a
longer time to create the template but reduces the time for matching. In addition the optimization leads to a more
stable matching, i.e., the possibilty to miss good matches is reduced. The optimization process selects the most
stable and significant gray values to be tested first during the matching process. Using this technique a wrong
match can be eliminated very early.
The reference position for the template is its center of gravity. I.e. if you apply the template to the original
image the center of gravity is returned. This default reference can be adapted using the operator
set reference template.
In sub pixel mode a special position correction is calculated which is added after each matching: The template is
applied to the original image and the difference between the found position and the center of gravity is used as a
correction vector. This is important for patterns in a textured context or for asymetric pattern. For most templates
this correction vector is near null.
If the pattern is no longer used, it has to be freed by the operator clear template in order to deallocate the
memory.
Before the use of the template, which is stored independently of the image size, it can be adapted explicitly to the
size of a definite image size by using adapt template.
Parameter
º Template (input object) .....................................................image Hobject : byte
Input image whose domain will be processed for the pattern matching.
º FirstError (input control) .........................................................integer long
Not jet in use.
Default Value : 255
Value List : FirstError ¾255
º NumLevel (input control) ............................................................integer long
Maximal number of pyramid levels.
Default Value : 4
Value List : NumLevel ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
º Optimize (input control) ......................................................string const char *
Kind of optimizing.
Default Value : ’sort’
Value List : Optimize ¾’none’, ’sort’
º GrayValues (input control) ...................................................string const char *
Kind of grayvalues.
Default Value : ’original’
Value List : GrayValues ¾’original’, ’normalized’, ’gradient’, ’sobel’
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 117
º TemplateID (output control) .....................................................template long *
Template number.
Result
If the parameters are valid, the operator create template returns the value H MSG TRUE. If necessary an
exception handling will be raised.
Parallelization Information
create template is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
draw region, reduce domain, threshold
Possible Successor Functions
adapt template, set reference template, clear template, write template,
set offset template, (T )best match, best match mg, fast match, (T )fast match mg
create template rot, read template
Template matching
Alternatives
Module
create template rot ( Hobject Template, long NumLevel,
double AngleStart, double AngleExtend, double AngleStep,
const char *Optimize, const char *GrayValues, long *TemplateID )
Preparing a pattern for template matching with rotation.
The operator create template rot preprocesses a pattern, which is passed as an image, for the template
matching. An extension to create template the matching can applied to rotated patterns. The parameters
AngleStart and AngleExtend define the maximum rotation of the pattern: AngleStart specifies the
maximum counter clockwise rotation and AngleExtend the maximum clockwise rotation relative to this angle.
Therefore AngleExtend has to be smaller than ¾. With the parameter AngleStep the maximum angle
resolution (on the highest resolution level) can be specified.
You have to be aware, that all possible rotations are calculated beforehand to reduce runtime during matching. This
leads to a higher execution time for create template rot and high memory requirements for the template.
The amount of memory depends on the parameters AngleExtend and AngleStep. The number of pyramid
levels can be neglected. If is the number of pixels of Template, the memory Å needed for the template in
byte is about:
£ ½¾ £ ÒÐÜØÒ
Å
ÒÐËØÔ
After the transformation, a number (TemplateID) is assigned to the template for being used in the further
process.
A description of the other parameters can be found at the operator create template.
Attention
You have to be aware, that depending on the resolution a large number of pre calculated patterns have to be created
which might result in a large amount of memory needed.
Parameter
º Template (input object) .....................................................image Hobject : byte
Input image whose domain will be processed for the pattern matching.
º NumLevel (input control) ............................................................integer long
Maximal number of pyramid levels.
Default Value : 4
Value List : NumLevel ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
º AngleStart (input control) .....................................................angle.rad double
Smallest Rotation of the pattern.
Default Value : -0.39
Value Suggestions : AngleStart ¾-3.14, -1.57, -0.79, -0.39, -0.20, 0.0
HALCON 6.0

118 CHAPTER 3. FILTER
º AngleExtend (input control) ....................................................angle.rad double
Maximum positive Extention of AngleStart.
Default Value : 0.79
Value Suggestions : AngleExtend ¾6.28, 3.14, 1.57, 0.79, 0.39
Restriction : AngleExtend 0
º AngleStep (input control) ......................................................angle.rad double
Step rate (angle precition) of matching.
Default Value : 0.0982
Value Suggestions : AngleStep ¾0.3927, 0.1963, 0.0982, 0.0491, 0.0245
Restriction : AngleStep 0
º Optimize (input control) ......................................................string const char *
Kind of optimizing.
Default Value : ’sort’
Value List : Optimize ¾’none’, ’sort’
º GrayValues (input control) ...................................................string const char *
Kind of grayvalues.
Default Value : ’original’
Value List : GrayValues ¾’original’, ’normalized’, ’gradient’, ’sobel’
º TemplateID (output control) .....................................................template long *
Template number.
Result
If the parameters are valid, the operator create template rot returns the value H MSG TRUE. If necessary
an exception handling will be raised.
Parallelization Information
create template rot is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
draw region, reduce domain, threshold
Possible Successor Functions
(T )best match rot, (T )best match rot mg, adapt template, set reference template,
clear template, set offset template, write template
create template
Template matching
Alternatives
Module
exhaustive match ( Hobject Image, Hobject RegionOfInterest,
Hobject ImageTemplate, Hobject *ImageMatch, const char *Mode )
Matching of a template and an image.
The operator exhaustive match matches ImageTemplate and Image within the region of interest
RegionOfInterest. Hereby the ImageTemplate will be moved over all points of Image which lie within
the RegionOfInterest. With regard to the parameter Mode, a matching criterion will be calculated. The
result values will be stored in ImageMatch.
The following matching criteria (Mode) are available:
’norm correlation’
ÁÑÅØ℄℄ ¾ ¡
ÕÈ
È
ÙÚ ´ÁÑ Ù℄ Ú℄ ¡ ÁÑÌÑÔÐØÐ
Ù℄ Ú℄µ
ÙÚ ´ÁÑ Ù℄ Ú℄¾ µ ¡ È ÙÚ ´ÁÑÌÑÔÐØÐ Ù℄ Ú℄¾ µ
whereby ℄℄ indicates the grayvalue in the th column and th row of the image . ´Ð µ is the centre of
the region of ImageTemplate. Ù and Ú are chosen so that all points of the template will be reached,
run accross the RegionOfInterest. At the image frame only those parts of ImageTemplate will be
considered which lie inside the image (i.e. Ù and Ú will be restricted correspondingly). Range of values: 0 -
255 (best fit).
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 119
’dfd’ Calculating the average “displaced frame difference”:
È
ÙÚ ÁÑ Ù℄ Ú℄ ÁÑÌÑÔÐØÐ Ù℄ Ú℄
ÁÑÅØ℄℄
Ê´ÁÑÌ ÑÔÐص
The terms are the same as in ’norm correlation’. AREA ( X ) means the area of the region X. Range of value
0 (best fit) - 255.
To calculate the normalized correlation as well as the “displaced frame difference” is (with regard to the
area of ImageTemplate) very time consuming. Therefore it is important to restrict the input region
(RegionOfInterest if possible, i.e. to apply the filter only in a very confined “region of interest”.
As far as quality is concerned, both modes return comparable results, whereby the mode ’dfd’ is faster by a factor
of about 3.5.
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º RegionOfInterest (input object) ...............................................region Hobject
Area to be searched in the input image.
º ImageTemplate (input object) ..............................................image Hobject : byte
This area will be “matched” by Image within the RegionOfInterest.
º ImageMatch (output object) .....................................................image Hobject *
Result image: values of the matching criterion.
º Mode (input control) ............................................................string const char *
Desired matching criterion.
Default Value : ’dfd’
Value List : Mode ¾’norm correlation’, ’dfd’
Example
read_image(&Image,"monkey");
disp_image(Image,WindowHandle);
/* mark one eye */
draw_rectangle2(WindowHandle,&Row,&Column,&Phi,&Length1,&Length2);
gen_rectangle2(&Rectangle,Row,Column,Phi,Length1,Length2);
reduce_domain(Image,Rectangle,&Template);
exhaustive_match(Image,Image,Template,&ImageMatch,’dfd’);
invert_image(ImageMatch,&ImageInvert);
local_max(ImageInvert,&Maxima);
union1(Maxima,&AllMaxima);
add_channels(AllMaxima,ImageInvert,&FitMaxima);
threshold(FitMaxima,&BestFit,230.0,255.0);
disp_region(BestFit,WindowHandle);
Result
If the parameter values are correct, the operator exhaustive match returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
exhaustive match is reentrant and automatically parallelized (on tuple level).
draw region, draw rectangle1
local max, threshold
exhaustive match mg
Image filters
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
HALCON 6.0

120 CHAPTER 3. FILTER
exhaustive match mg ( Hobject Image, Hobject ImageTemplate,
Hobject *ImageMatch, const char *Mode, long Level, long Threshold )
Matching a template and an image in a resolution pyramid.
The operator exhaustive match mg is an additional option for the operator exhaustive match performing
a matching of the image Image and the template ImageTemplate. Hereby ImageTemplate will be
moved over all points of the region of Image, a matching criterion will be calculated with regard to the parameter
Mode and the result values will be stored in ImageMatch.
Of images having been filtered this way, normally only those areas with good matching results are of interest. The
size of the area to be searched, i.e. the region of the input image Image, determines decisively the runtime of
the matching filter. Therefore it is recommendable to use at first exhaustive match mg with reduced image
resolution in order to determine a “region of interest” in which good matching results can be expected; then in this
restricted area only the real matching (see also exhaustive match) will be executed with normal resolution.
Hereby the Gauss-pyramids of Image and ImageTemplate will be composed (in particular the corresponding
regions will be transformed as well). Then on each level of the resolution pyramids - starting with the startlevel
Level - the matching inside the current “region of interest” will be executed. Whereby the “region of interest” on
the startlevel is equivalent to the region of the input image Image. After the filtering, a new “region of interest” is
determined with the help of a threshold operation and will be transformed on the next resolution level:
threshold(..0,Threshold..), if Mode = ’dfd’
threshold(..Threshold,255..), if Mode = ’crosscorrelation’
The final matching in the determined “region of interest” will then be calculated with the highest resolution (Level
0). The output image ImageMatch includes the corresponding filter result and the final “region of interest”, which
is determined on the result image with the help of a threshold operation.
The operator exhaustive match mg therefore is not simply a filter, but can also be considered as a member of
the class of region transformations.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º ImageTemplate (input object) ..............................................image Hobject : byte
The domain of this image will be matched with Image.
º ImageMatch (output object) ........................................image(-array) Hobject * : byte
Result image and result region: values of the matching criterion within the determined “region of interest”.
Parameter Number : ImageMatch Image
º Mode (input control) ............................................................string const char *
Desired matching criterion.
Default Value : ’dfd’
Value List : Mode ¾’crosscorrelation’, ’dfd’
º Level (input control) ................................................................integer long
Startlevel in the resolution pyramid (highest resolution: Level 0).
Default Value : 1
Value List : Level ¾0, 1, 2, 3, 4, 5, 6, 7, 8
Restriction : ´Level ld´width´Imageµµµ ´Level ld´height´Imageµµµ
º Threshold (input control) ...........................................................integer long
Threshold to determine the “region of interest”.
Default Value : 30
Value Suggestions : Threshold ¾5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95,
100, 105, 110, 115, 120, 125, 130, 135, 140, 145, 150, 155, 160, 165, 170, 175, 180, 185, 190, 195, 200, 205,
210, 215, 220, 225, 230, 235, 240, 245, 250
Typical Range of Values : 0 Threshold 255
Minimal Value Step : 1
Recommended Value Step : 5
read_image(&Image,"monkey");
disp_image(Image,WindowHandle);
Example
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 121
draw_rectangle2(WindowHandle,&Row,&Column,&Phi,&Length1,&Length2);
gen_rectangle2(&Rectangle,Row,Column,Phi,Length1,Length2);
reduce_domain(Image,Rectangle,&Template);
exhaustive_match_mg(Image,Template,&ImageMatch,’dfd’1,30);
invert_image(ImageMatch,&ImageInvert);
local_max(ImageInvert,&BestFit);
disp_region(BestFit,WindowHandle);
Result
If the parameter values are correct, the operator exhaustive match mg returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
exhaustive match mg is reentrant and automatically parallelized (on tuple level).
draw region, draw rectangle1
threshold, local max
exhaustive match
gen gauss pyramid
Image filters
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
fast match ( Hobject Image, Hobject *Matches, long TemplateID,
double MaxError )
Searching all good matches of a template and an image.
The operator fast match performs a matching of the template of TemplateID and Image. Hereby the
template will be moved over the points of Image so that the template always lies completely inside of Image.
The matching criterion (“displaced frame difference”) is defined as follows:
È
ÙÚ ÁÑÖÓÛ Ù ÓÐ Ú℄ ÌÑÔÐØÁÙ Ú℄
ÖÖÓÖÖÓÛ ÓÐ℄
Ö´Ì ÑÔÐØÁµ
The difference between fast match and exhaustive match is that the matching for one position is stopped
if the error is to high. This leads to a reduced runtime but one might miss correct matches. The runtime of the
operator depends mainly on the size of the domain of Image. Therefore it is important to restrict the domain as
far as possible, i.e. to apply the operator only in a very confined “region of interest”. The parameter MaxError
determines the maximal error which the searched position is allowed to show. The lower this value is, the faster
the operator runs.
All points which show a matching error smaller than MaxError will be returned in the output region Matches.
This region can be used for further processing. For example by using a connection and (T )best match to
find all the matching objects. If no point has a match error below MaxError the empty region (i.e no points) is
returned.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
º Matches (output object) ..................................................region(-array) Hobject *
All points whose error lies below a certain threshold.
º TemplateID (input control) ........................................................template long
Template number.
HALCON 6.0

122 CHAPTER 3. FILTER
º MaxError (input control) .............................................................real double
Maximal average difference of the grayvalues.
Default Value : 20
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 1
Result
If the parameter values are correct, the operator fast match returns the value H MSG TRUE. If
the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
fast match is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template, read template, adapt template, draw region, draw rectangle1,
reduce domain
Possible Successor Functions
connection, (T )best match
Alternatives
(T )best match, best match mg, (T )fast match mg, exhaustive match,
exhaustive match mg
Module
Template matching
fast match mg ( Hobject Image, Hobject *Matches, long TemplateID,
double MaxError, long NumLevel )
T fast match mg ( Hobject Image, Hobject *Matches, Htuple TemplateID,
Htuple MaxError, Htuple NumLevel )
Searching all good grayvalue matches in a pyramid.
The operator (T )fast match mg like the operator fast match performs a matching of the template of
TemplateID and Image. In contrast to fast match, however, the search for good matches starts in scaled
down images (pyramid). The number of levels of the pyramid will be determined by NumLevel. Hereby the
value 1 indicates that no pyramid will be used. In this case the operator (T )fast match mg is equivalent to
the operator fast match. The value 2 triggers the search in the image with half the framesize. The search for
all those points showing an error small enough in the scaled down image (error smaller than MaxError) will be
refined at the corresponding positions in the original image (Image).
The runtime of matching dependends on the parameter MaxError: the larger the value the longer is the processing
time, because more points of the pattern have to be tested. If MaxError is to low the pattern will not be found.
The value has therefore to be optimized for every application.
NumLevel indicates the number of levels of the pyramid, including the original image. Optionally a second value
can be given. This value specifies the number (0..n) of the lowest level which is used the the matching. The region
found up to this level will then be zoomed to the size of the original level. This can used to increase the runtime in
the case that the accuracy does not have to be so high.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image inside of which the pattern has to be found.
º Matches (output object) ..................................................region(-array) Hobject *
All points which have an error below a certain threshold.
º TemplateID (input control) ..............................................template (Htuple .) long
Template number.
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 123
º MaxError (input control) ...................................................real (Htuple .) double
Maximal average difference of the grayvalues.
Default Value : 30
Value Suggestions : MaxError ¾0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70
Typical Range of Values : 0 MaxError 255
Minimal Value Step : 1
Recommended Value Step : 3
º NumLevel (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Number of levels in the pyramid.
Default Value : 3
Value List : NumLevel ¾1, 2, 3, 4, 5, 6, 7, 8
Result
If the parameter values are correct, the operator (T )fast match mg returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
(T )fast match mg is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
create template, read template, adapt template, draw region, draw rectangle1,
reduce domain
Alternatives
(T )best match, best match mg, fast match, exhaustive match, exhaustive match mg
Template matching
Module
fill dvf ( Hobject Image, Hobject *ImageExpanded, long Width,
long Height, long Iterations )
Expansion of a displacement vector field onto undefined areas.
The operator fill dvf calculates a value for each undefined point in a displacement vector field by averaging its
neighbors. The dimension of the neighborhod will be determined by the parameters Width and Height. Asthe
gaps may be larger than the masks, the filter may be used iteratively (Iterations). Correctly defined values in
the input image will not be modified.
Parameter
º Image (input object) ...................................................image(-array) Hobject : dvf
Input image.
º ImageExpanded (output object) ....................................image(-array) Hobject * : dvf
Result of adding the points which are missing.
º Width (input control) ...............................................................extent.x long
Width of the filtermask.
Default Value : 5
Value Suggestions : Width ¾3, 5, 7, 9, 11, 15
Typical Range of Values : 3 Width 201
Minimal Value Step : 2
Recommended Value Step : 2
º Height (input control) ..............................................................extent.y long
Height of the filtermask.
Default Value : 5
Value Suggestions : Height ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 Height 201
Minimal Value Step : 2
Recommended Value Step : 2
HALCON 6.0

124 CHAPTER 3. FILTER
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 3
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Typical Range of Values : 1 Iterations 100
Minimal Value Step : 1
Recommended Value Step : 1
Parallelization Information
fill dvf is reentrant and automatically parallelized (on tuple level, domain level).
(T )optical flow match
Image filters
Possible Predecessor Functions
Module
gen gauss pyramid ( Hobject Image, Hobject *ImagePyramid,
const char *Mode, double Scale )
Calculating a Gauss pyramid.
The operator gen gauss pyramid calculates a pyramid of scaled down images. The scale by which the next
image will be reduced is determined by the parameter Scale. For instance, a value of 0.5 for Scale will shorten
the edge length of Image by 50%. This is exactly equivalent to the “normal” pyramid.
The parameter Mode determines the way of averaging. For a more detailed description concerning this parameter
see also T affine trans image. In the case that Scale is equal 0.5 there are the additional modes ’min’ and
’max’ available. In this case the minimum or the maximum of the four neighboring pixels is selected.
Please note that each level will be returned as an individual image, i.e. as one iconic objekt, with one matrix and
its own domain. If a multichannel image is needed as a result, the operator image to channels has to be used.
A single level or more than one level can be selected by using select obj respectively copy obj.
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º ImagePyramid (output object) ......................................image-array Hobject * : byte
Output images.
Parameter Number : ImagePyramid Image
º Mode (input control) ............................................................string const char *
Kind of filtermask.
Default Value : ’weighted’
Value List : Mode ¾’none’, ’constant’, ’weighted’, ’min’, ’max’
º Scale (input control) .................................................................real double
Factor for scaling down.
Default Value : 0.5
Value Suggestions : Scale ¾0.2, 0.3, 0.4, 0.5, 0.6
Typical Range of Values : 0.1 Scale 0.9
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : ´0.1 Scaleµ ´Scale 0.9µ
Example
gen_gauss_pyramid(Image,Pyramid,"weighted",0.5);
count_obj(Pyramid,&num);
for (i=1; i

3.9. MATCH 125
Parallelization Information
gen gauss pyramid is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
image to channels, count obj, select obj, copy obj
zoom image size, zoom image factor
T affine trans image
Image filters
Alternatives
See Also
Module
monotony ( Hobject Image, Hobject *ImageMonotony )
Calculating the monotony operation.
The operator monotony calculates the monotony operator. Thereby the points which are strictly smaller than the
current grayvalue will be counted in the 8 neighborhood. This number will be entered into the output imaged.
If there is a strict maximum, the value 8 is returned; in case of a minimum or a plateau, the value 0 will be returned.
A ridge or a slope will return the corresponding intermediate values.
The monotony operator is often used to prepare matching operations as it is invariant with regard to lightness
modifications.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageMonotony (output object) . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Result of the monotony operator.
Parameter Number : ImageMonotony Image
/* searching the strict maximums */
gauss_image(Image,&Gauss,5);
monotony(Gauss,&Monotony);
threshold(Monotony,Maxima,8.0,8.0);
Example
Parallelization Information
monotony is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessor Functions
gauss image, median image, mean image, smooth image, invert image
Possible Successor Functions
threshold, exhaustive match, disp image
Alternatives
local max, topographic sketch, corner response
Image filters
Module
HALCON 6.0

126 CHAPTER 3. FILTER
optical flow match ( Hobject Image1, Hobject Image2,
Hobject *VectorField, const char *Mode, long Threshold, long Step,
long SizeWindow, long SizeSearch, long Weights )
T optical flow match ( Hobject Image1, Hobject Image2,
Hobject *VectorField, Htuple Mode, Htuple Threshold, Htuple Step,
Htuple SizeWindow, Htuple SizeSearch, Htuple Weights )
Calculating the Displacement vector field by correlation methods.
The operator (T )optical flow match determines a displacement vector field (DVF) with the help of correlation
methods. Simple- and multichannel Images may be used. A window of the size SizeWindow will be
moved inside a mask of the size SizeSearch over a second image and there the grayvalues will be compared
with the ones from the first image. The correlation showing the slightest error will determine the vector. In case
of two vectors having the same weighting, the shorter vector will be prefered. After having processed one image
point, the next image point at a distance of Step will be selected. It is therefore not guaranteed to get a dense
displacement vector field.
The parameter Threshold specifies the maximal divergence of previously estimated correlations and the best
estimation of a displacement vector.
The method used by the operator is determined by the parameter Mode. The follwing values for Mode can be
selected:
’dfd’ Calculation of displaced frame difference.
’dfd norm’ Calculation of displaced frame difference normalized by the mean value of the matching windows.
If the image has more than one channel the parameter Weights indicates the weighting of the individual channels.
For each channel one weight factor must be passed.
For the parameters SizeWindow, SizeSearch and Step optionally two values can be passed: The first value
indicates hereby the width (respectively the row), the second value the height (respectively the column).
Parameter
º Image1 (input object) ................................................image(-array) Hobject : byte
First input image (optionally with more than one channel).
º Image2 (input object) ................................................image(-array) Hobject : byte
Second input image (optionally with more than one channel).
Parameter Number : Image2 Image1
º VectorField (output object) .......................................image(-array) Hobject * : dvf
Displacement vector field to be calculated.
Parameter Number : VectorField Image1
º Mode (input control) ..................................................string (Htuple .) const char *
Kind of correlation.
Default Value : ’dfd’
Value List : Mode ¾’dfd’, ’dfd norm’
º Threshold (input control) .................................................integer (Htuple .) long
Maximal divergence of the previously estimated correlations and the best estimate of a displacement vector.
Default Value : 10
Value Suggestions : Threshold ¾1, 2, 3, 4, 5, 7, 10, 12, 15, 17, 20
Typical Range of Values : 1 Threshold 300
Minimal Value Step : 1
Recommended Value Step : 5
º Step (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Step width.
Default Value : 10
Value Suggestions : Step ¾1, 2, 3, 5, 7, 10, 15, 20, 30, 50
Typical Range of Values : 1 Step 300
Minimal Value Step : 1
Recommended Value Step : 5
HALCON/C Reference Manual / 2000-11-15

3.9. MATCH 127
º SizeWindow (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Size of the correlation window.
Default Value : 11
Value Suggestions : SizeWindow ¾3, 5, 7, 9, 11, 15, 20, 30
Typical Range of Values : 1 SizeWindow 30
Minimal Value Step : 1
Recommended Value Step : 2
º SizeSearch (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Size of the area to be searched.
Default Value : 20
Value Suggestions : SizeSearch ¾3, 5, 7, 10, 20, 30, 40, 50, 60
Typical Range of Values : 1 SizeSearch 60
Minimal Value Step : 1
Recommended Value Step : 2
º Weights (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Weighting of the channels.
Default Value : 1
Value Suggestions : Weights ¾1, 3, 5, 7, 10
Typical Range of Values : 1 Weights 10
Minimal Value Step : 1
Recommended Value Step : 1
Example
read_image(&B1,"image1") ;
mean(B1,&L1,16,16) ;
read_image(&B2,"image2") ;
mean_image(B2,&L2,16,16) ;
optical_flow_match(L1,L2,VVF,’dfd’,10,10,11,20,1) ;
disp_image(B1,WindowHandle) ;
set_color(WindowHandle,"red") ;
disp_image(VVF,WindowHandle) ;
Parallelization Information
(T )optical flow match is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
mean image, gauss image, smooth image
fill dvf
dvf to int1, dvf to hom mat2d
Image filters
Possible Successor Functions
See Also
Module
read template ( const char *FileName, long *TemplateID )
Reading a template from file.
The operator read template reads a matching template from file which has been written with
write template.
Parameter
º FileName (input control) ...................................................filename const char *
file name.
º TemplateID (output control) .....................................................template long *
Template number.
HALCON 6.0

128 CHAPTER 3. FILTER
Result
If the file name is valid, the operator read template returns the value H MSG TRUE. If necessary an exception
handling will be raised.
Parallelization Information
read template is local and processed completely exclusively without parallelization.
Possible Successor Functions
adapt template, set reference template, set offset template, (T )best match,
fast match, (T )best match rot
Template matching
Module
set offset template ( long TemplateID, long GrayOffset )
Gray value offset for template.
set offset template adds a gray value offset to the template to eliminate gray value changes in the image.
The parameter GrayOffset specifies a difference relative to the gray values of the pattern when it was
created with create template (not relative to the last call of set offset template). The values of
GrayOffset has to be chosen according to the gray values of the image: A brighter image results in a positive
value, a darker image results in a negative value. set offset template has to be called each time the
gray values of the image changes. The gray values can be meassured in a reference area using intensity or
min max gray
Parameter
º TemplateID (input control) ........................................................template long
Template number.
º GrayOffset (input control) .........................................................number long
Offset of gray values.
Default Value : 0
Value Suggestions : GrayOffset ¾-10,-5,-2,-1,0,1,2,5,10
Typical Range of Values : -255 GrayOffset 255
Minimal Value Step : 1
Recommended Value Step : 1
Result
If the parameter values are correct, the operator set offset template returns the value H MSG TRUE. If
necessary, an exception handling is raised.
Parallelization Information
set offset template is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
create template, adapt template, read template
Possible Successor Functions
(T )best match, best match mg, (T )best match rot, fast match, (T )fast match mg
Template matching
Module
set reference template ( long TemplateID, double Row, double Column )
Define reference position for a matching template.
set reference template allows to define a new reference position for a template. As default after calling
create template or create template rot the center of gravity of the template is used. Using
set reference template the reference position can be redefined. In the case of the center of gravity as
reference the vector ´¼ ¼µ is returned after matching for a null translation of the pattern relative to the image.
HALCON/C Reference Manual / 2000-11-15

3.10. MISC 129
Parameter
º TemplateID (input control) ........................................................template long
Template number.
º Row (input control).................................................................point.y double
Reference position of template (row).
º Column (input control) ............................................................point.x double
Reference position of template (column).
Result
If the parameter values are correct, the operator set reference template returns the value H MSG TRUE.
If necessary, an exception handling is raised.
Parallelization Information
set reference template is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
create template, create template rot, read template, adapt template
Possible Successor Functions
(T )best match, best match mg, (T )best match rot, fast match, (T )fast match mg
Template matching
Module
write template ( long TemplateID, const char *FileName )
Writing a template to file.
The operator write template writes a matching template to file which can be read again with
read template.
Parameter
º TemplateID (input control) ........................................................template long
Template number.
º FileName (input control) ...................................................filename const char *
file name.
Result
If the file name is valid (permission to write), the operator write template returns the value H MSG TRUE.
If necessary an exception handling will be raised.
Parallelization Information
write template is reentrant and processed without parallelization.
Possible Predecessor Functions
create template, create template rot
Template matching
Module
3.10 Misc
convol image ( Hobject Image, Hobject *ImageResult,
const char *FileName, long Margin )
Convolve an image with an arbitrary filter mask.
convol image convolves the input image Image with an arbitrary linear filter. The corresponding filter matrix
is stored in a file named FileName. Several options for the treatment at the image’s borders can be chosen
(Margin):
¼ ¾ Gray values are assumed constant outside of the image (with the given gray value).
HALCON 6.0

130 CHAPTER 3. FILTER
-1 The border’s gray values are continued.
-2 The border’s gray values are continued cyclically.
-3 The gray values are mirrored along the image borders.
All image points are convolved with the filter mask. If an overflow or underflow occurs, the resulting gray value is
clipped (to 0 or 255, respectively). The filter mask is contained in a file with the following structure:
Mask size
Inverse weight of the mask
Matrix
The first line contains the size of the filter mask, given as two numbers separated by white space (e.g., 3 3 for
¿ ¢ ¿). Here, the first number defines the height of the filter mask, while the second number defines its width. The
next line contains the inverse weight of the mask, i.e., the number by which the convolution of a particular image
point is divided. The remaining lines contain the filter mask as integer numbers (separated by white space), one
line of the mask per line in the file. The file must have the extension “.fil”. This extension must not be passed to
the operator.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be convolved.
º ImageResult (output object) . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject * : byte
Convolved result image.
º FileName (input control) ......................................................string const char *
Name of the file containing the filter mask.
Default Value : ’filter’
º Margin (input control) ...............................................................integer long
Border treatment: 0...255 (constant), -1 (continue border’s gray value), -2 (continue cyclically), -3 (mirror
gray values).
Default Value : -3
Typical Range of Values : -3 Margin 255
Parallelization Information
convol image is reentrant and automatically parallelized (on tuple level, channel level).
Image filters
Module
expand domain gray ( Hobject InputImage, Hobject *ExpandedImage,
long ExpansionRange )
Expand the domain of an image and set the gray values in the expanded domain.
expand domain gray expands the border gray values of the domain outwards. The width of the expansion
is set by the parameter ExpansionRange. All filters in HALCON use gray values of the pixels outside the
domain depending on the filter width. This may lead to undesirable side effects especially in the border region
of the domain. For example, if the foreground (domain) and the background of the image differ strongly in
brightness, the result of a filter operation may lead to undesired darkening or brightening at the border of the
domain. In order to avoid this drawback, the domain is expanded by expand domain gray in a preliminary
stage, copying the gray values of the border pixels to the outside of the domain. In addition, the domain itself
is also expanded to reflect the newly set pixels. Therefore, in many cases it is reasonable to reduce the domain
again (reduce domain or change domain)afterusingexpand domain gray and call the filter operation
afterwards. ExpansionRange should be set to the half of the filter width.
Parameter
º InputImage (input object) ......................................image(-array) Hobject : byte / int2
Input image with domain to be expanded.
º ExpandedImage (output object) ..............................image(-array) Hobject * : byte / int2
Output image with new gray values in the expanded domain.
HALCON/C Reference Manual / 2000-11-15

3.10. MISC 131
º ExpansionRange (input control) ....................................................integer long
Radius of the gray value expansion, measured in pixels.
Default Value : 2
Value Suggestions : ExpansionRange ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 14, 16
Restriction : ExpansionRange 1
Example
read_image(Fabrik, ’fabrik.tif’);
gen_rectangle2(Rectangle_Label,243,320,-1.55,62,28);
reduce_domain(Fabrik, Rectangle_Label, Fabrik_Label);
/* Character extraction without gray value expansion: */
mean_image(Fabrik_Label,Label_Mean_normal,31,31);
dyn_threshold(Fabrik_Label,Label_Mean_normal,Characters_normal,10,’dark’);
dev_display(Fabrik);
dev_display(Characters_normal);
/* The characters in the border region are not extracted ! */
stop();
/* Character extraction with gray value expansion: */
expand_domain_gray(Fabrik_Label, Label_expanded,15);
reduce_domain(Label_expanded,Rectangle_Label, Label_expanded_reduced);
mean_image(Label_expanded_reduced,Label_Mean_expanded,31,31);
dyn_threshold(Fabrik_Label,Label_Mean_expanded,Characters_expanded,10,’dark’);
dev_display(Fabrik);
dev_display(Characters_expanded);
/* Now, even in the border region the characters are recognized */
Complexity
Let Ä the perimeter of the domain. Then the runtime complexity is approximately Ǵĵ £ ÜÔÒ×ÓÒÊÒ.
Result
expand domain gray returns H MSG TRUE if all parameters are correct. If necessary, an exception handling
is raised.
Parallelization Information
expand domain gray is reentrant and automatically parallelized (on tuple level).
reduce domain
Possible Predecessor Functions
Possible Successor Functions
reduce domain, mean image, dyn threshold
reduce domain, mean image
Image filters
See Also
Module
gray inside ( Hobject Image, Hobject *ImageDist )
Calculate the lowest possible gray value on an arbitrary path to the image border for each point in the image.
gray inside determines the “cheapest” path to the image border for each point in the image, i.e., the path on
which the lowest gray values have to be overcome. The resulting image contains the difference of the gray value
of the particular point and the maximum gray value on the path. Bright areas in the result image therefore signify
that these areas (which are typically dark in the original image) are surrounded by bright areas. Dark areas in the
result image signify that there are only small gray value differences between them and the image border (which
doesn’t mean that they are surrounded by dark areas; a small “gap” of dark values suffices). The value 0 (black) in
the result image signnifies that only darker or equally bright pixels exist on the path to the image border.
The operator is implemented by first segmenting into basins and watersheds the image using the watersheds
operator. If the image is regarded as a gray value mountain range, basins are the places where water accumulates
HALCON 6.0

132 CHAPTER 3. FILTER
and the mountain ridges are the watersheds. Then, the watersheds are distributed to adjacent basins, thus leaving
only basins. The border of the domain (region) of the original image is now searched for the lowest gray value,
and the region in which it resides is given its result values. If the lowest gray value resides on the image border,
all result values can be calculated immediately using the gray value differences to the darkest point. If the smalles
found gray value lies in the interior of a basin, the lowest possible gray value has to be determined from the already
processed adjacent basins in order to compute the new values. An 8-neighborhood is used to determine adjacency.
The found region is subtracted from the regions yet to process, and the whole process is repeated. Thus, the image
is “stripped” form the outside.
Analogously to watersheds, it is advisable to apply a smoothing operation before calling watersheds, e.g.,
gauss image, in order to reduce the amount of regions that result from the watershed algorithm, and thus to
speed up the processing time.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image being processed.
º ImageDist (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * :int2
Result image.
Example
read_image(Image,"coin");
gauss_image(Image,&GaussImage,11);
open_window (0,0,512,512,0,"visible","",&WindowHandle);
gray_inside(GaussImage,Result);
disp_image(Result,WindowHandle);
gray inside always returns H MSG TRUE.
Result
Parallelization Information
gray inside is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
gauss image, smooth image, mean image, median image
Possible Successor Functions
select shape, area center, count obj
watersheds
Image filters
See Also
Module
gray skeleton ( Hobject Image, Hobject *GraySkeleton )
Thinning of gray value images.
gray skeleton applies a gray value thinning operation to the input image Image. Figuratively, the gray
value “mountain range” is reduced to its ridge lines by setting the gray value of “hillsides” to the gray value
at the corresponding valley bottom. The resulting ridge lines are at most two pixels wide. This operator is especially
useful for thinning edge images, and is thus an alternative to nonmax suppression amp. In contrast
to nonmax suppression amp, gray skeleton preserves contours, but is much slower. In contrast to
skeleton, this operator changes the gray values of an image while leaving its region unchanged.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be thinned.
º GraySkeleton (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Thinned image.
HALCON/C Reference Manual / 2000-11-15

3.10. MISC 133
Example
/* Seeking leafs of a tree in an aerial picture: */
read_image(&Image,"wald1");
gray_skeleton(Image&,Skelett);
mean_image(Skelett,&MeanSkelett,7,7);
dyn_threshold(Skelett,MeanSkelett,&Leafs,3.0,"light");
Result
gray skeleton returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
gray skeleton is reentrant and automatically parallelized (on tuple level, channel level).
mean image
Possible Successor Functions
Alternatives
nonmax suppression amp, nonmax suppression dir, local max
skeleton, gray dilation rect
Image filters
See Also
Module
T lut trans ( Hobject Image, Hobject *ImageResult, Htuple Lut )
Transform an image with a gray-value look-up-table
T lut trans transforms an image Image by using a gray value look-up-table Lut. This table acts as a transformation
function.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image whose gray values are to be transformed.
º ImageResult (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Transformed image.
º Lut (input control) .....................................................integer-array Htuple . long
Table containing the transformation.
/* To get the inverse of an image: */
Htuple lut;
read_image(&Image,"wald1");
creat_tuple(&lut,256);
for (i=0; i

134 CHAPTER 3. FILTER
T principal comp ( Hobject MultichannelImage, Hobject *PCAImage,
Htuple *InfoPerComp )
Compute the principal components of multi-channel images.
T principal comp does a principal components analysis of multi-channel images. This is useful for images
obtained, e.g., with the thematic mapper of the Landsat satellite. Because the spectral bands are highly correlated it
is desirable to transform them to uncorrelated images. This can be used to save storage, since the bands containing
little information can be discarded, and with respect to a later classification step.
The operator T principal comp takes a (multi-channel) image MultichannelImage and transforms it
to the output image PCAImage, which contains the same number of channels, using the principal components
analysis. The parameter InfoPerComp contains the relative information content of each output channel.
Parameter
º MultichannelImage (input object) . . . . . . .multichannel-image Hobject : byte / int1 / int2 / int4 / real
Multi-channel input image.
º PCAImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image Hobject * : real
Multi-channel ouput image.
º InfoPerComp (output control) ........................................real-array Htuple . double *
Information content of each output channel.
Result
The operator T principal comp returns the value H MSG TRUE if the parameters are correct. Otherwise an
exception is raised.
Parallelization Information
T principal comp is reentrant and processed without parallelization.
Image filters
Module
symmetry ( Hobject Image, Hobject *ImageSymmetry, long MaskSize,
double Direction, double Exponent )
Symmentry of gray values along a row.
symmetry calculates the symmetry along a line. For each pixel the gray values of both sides of the line are
compared: The absolut value of the differences of gray values with same distance to the pixel is computed. Each
of these differences is weighted by the exponent (after division by 255) and the summed up.
×ÝÑ ¾
¾
Å×ËÞ
Å×ËÞ
½
´µ ´ µ
¾
ÜÔÓÒÒØ
Pixels with a high symmetry have large gray values.
Attention
Currently only horizontal search lines are implemented
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageSymmetry (output object) . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Symmetry image.
º MaskSize (input control) ...........................................................number long
Extension of search area.
Default Value : 40
Value Suggestions : MaskSize ¾3, 5, 7, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 100, 120, 140, 180
Typical Range of Values : 3 MaskSize 1000
Minimal Value Step : 1
Recommended Value Step : 2
HALCON/C Reference Manual / 2000-11-15

3.10. MISC 135
º Direction (input control) ........................................................number double
Angle of test direction.
Default Value : 0.0
Value Suggestions : Direction ¾0.0
Typical Range of Values : 0.0 Direction 0.0
º Exponent (input control) .........................................................number double
Exponent for weighting.
Default Value : 0.5
Value Suggestions : Exponent ¾0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.8, 0.9, 1.0
Typical Range of Values : 0.05 Exponent 1.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : ´0 Exponentµ ´Exponent 1µ
Example
read_image(Image,’monkey’)
symmetry(Image,ImageSymmetry,70,0.0,0.5)
threshold(ImageSymmetry,SymmPoints,170,255)
Result
If the parameter values are correct the operator symmetry returns the value H MSG TRUE The behavior
in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
symmetry is reentrant and automatically parallelized (on tuple level, channel level, domain level).
threshold
Image filters
Possible Successor Functions
Module
topographic sketch ( Hobject Image, Hobject *Sketch )
Compute the topographic primal sketch of an image.
topographic sketch computes the topographic primal sketch of the input image Image. This is done by
approximating the image locally by a bicubic polynomial (“facet model”). It serves to calculate the first and
second partial derivatives of the image, and thus to classify the image into 11 classes. These classes are coded in
the output image Sketch as numbers from 1 to 11. The classes are as follows:
Peak 1
Pit 2
Ridge 3
Ravine 4
Saddle 5
Flat 6
Hillside Slope 7
Hillside Convex 8
Hillside Concave 9
Hillside Saddle 10
Hillside Inflection 11
In order to obtain the separate classes as regions, a threshold operation has to be applied to the result image with
the appropriate thresholds.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image for which the topographic primal sketch is to be computed.
º Sketch (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Label image containing the 11 classes.
HALCON 6.0

136 CHAPTER 3. FILTER
Example
/* To extract the Ridges from a Image */
read_image(&Image,"sinus");
topographic_sketch(Image,&Sketch);
threshold(Sketch,&Ridges,3.0,3.0);
Complexity
Let Ò be the number of pixels in the image. Then Ç´Òµ operations are performed.
Result
topographic sketch returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour
can be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
topographic sketch is reentrant and automatically parallelized (on tuple level, channel level).
threshold
Possible Successor Functions
Bibliography
R. Haralick, L. Shapiro: “Computer and Robot Vision, Volume I”; Reading, Massachusetts, Addison-Wesley;
1992; Kapitel 8.13.
Module
Image filters
3.11 Noise
T add noise distribution ( Hobject Image, Hobject *ImageNoise,
Htuple Distribution )
Add noise to an image.
T add noise distribution adds noise distributed according to Distribution to the image Image. Resulting
gray values are clipped to the range [0,255].
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageNoise (output object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Noisy image.
Parameter Number : ImageNoise Image
º Distribution (input control) ............................distribution.values-array Htuple . double
Noise distribution.
Parameter Number : 513
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
set_d(PerSalt,30.0,0);
set_d(PerPepper,30.0,0);
T_sp_distribution(PerSalt,PerPepper,&Dist);
T_add_noise_distribution(Image,&ImageNoise,Dist);
disp_image(ImageNoise,WindowHandle);
Result
T add noise distribution returns H MSG TRUE if all parameters are correct. If the input is empty the
behaviour can be set via set system(’no object result’,). If necessary, an exception handling
is raised.
HALCON/C Reference Manual / 2000-11-15

3.11. NOISE 137
Parallelization Information
T add noise distribution is reentrant and automatically parallelized (on tuple level, channel level, domain
level).
Possible Predecessor Functions
T gauss distribution, T sp distribution, T noise distribution mean
add noise white
Alternatives
See Also
T sp distribution, T gauss distribution, T noise distribution mean, add noise white
Image filters
Module
add noise white ( Hobject Image, Hobject *ImageNoise, double Amp )
Add noise to an image.
add noise white adds noise to the image Image. The noise is white noise, equally distributed in the interval
[-Amp,Amp], and is generated by using the C function “drand48” with an initial time dependent seed. Resulting
gray values are clipped to the range [0,255].
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Input image.
º ImageNoise (output object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Noisy image.
Parameter Number : ImageNoise Image
º Amp (input control) ...................................................................real double
Maximum noise amplitude.
Default Value : 60.0
Value Suggestions : Amp ¾1.0, 2.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 1.0 Amp 1000.0
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Amp 0
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
add_noise_white(Image,&ImageNoise,90.0);
disp_image(ImageNoise,WindowHandle);
Result
add noise white returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
add noise white is reentrant and automatically parallelized (on tuple level, channel level, domain level).
T add noise distribution
Alternatives
See Also
T add noise distribution, T noise distribution mean, T gauss distribution,
T sp distribution
Module
Image filters
HALCON 6.0

138 CHAPTER 3. FILTER
T gauss distribution ( Htuple Sigma, Htuple *Distribution )
Generate a Gaussian noise distribution.
T gauss distribution generates a Gaussian noise distribution. The parameter Sigma determines
the noise’s standard deviation. Usually, the result Distribution is used as input for the operator
T add noise distribution.
Parameter
º Sigma (input control) .........................................................real Htuple . double
Standard deviation of the Gaussian noise distribution.
Default Value : 2.0
Value Suggestions : Sigma ¾1.5, 2.0, 3.0, 5.0, 10.0
Typical Range of Values : 0.0 Sigma 100.0
Minimal Value Step : 0.1
Recommended Value Step : 1.0
º Distribution (output control) ..........................distribution.values-array Htuple . double *
Resulting Gaussian noise distribution.
Parameter Number : 513
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
set_d(Sigma,30.0,0);
T_gauss_distribution(Sigma,&Dist);
T_add_noise_distribution(Image,&ImageNoise,Dist);
disp_image(ImageNoise,WindowHandle);
Parallelization Information
T gauss distribution is reentrant and processed without parallelization.
T add noise distribution
Possible Successor Functions
Alternatives
T sp distribution, T noise distribution mean
See Also
T sp distribution, add noise white, T noise distribution mean
Image filters
Module
T noise distribution mean ( Hobject ConstRegion, Hobject Image,
Htuple FilterSize, Htuple *Distribution )
Determine the noise distribution of an image.
T noise distribution mean calculates the noise distribution in a region of the image Image. The parameter
ConstRegion determines a region of the image with approximately constant gray values. Ideally, the
changes in gray values should only be caused by noise in this region. From this region the noise distribution is
determined by using the mean image operator to smooth the image, and to use the gray value differences in this
area as an estimate for the noise distribution, which is returned in Distribution.
Attention
It is important to ensure that the region ConstRegion is not too close to a large gradient in the image, because
the gradient values are then used for calculating the mean. This means the the distance of ConstRegion must
be at least as large as the filter size FilterSize used for calculating the mean.
HALCON/C Reference Manual / 2000-11-15

3.11. NOISE 139
Parameter
º ConstRegion (input object) ...............................................region(-array) Hobject
Region from which the noise distribution is to be estimated.
º Image (input object) .........................................................image Hobject : byte
Corresponding image.
º FilterSize (input control) .................................................integer Htuple . long
Size of the mean filter.
Default Value : 21
Value Suggestions : FilterSize ¾5, 11, 15, 21, 31, 51, 101
Typical Range of Values : 3 FilterSize 501 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
º Distribution (output control) ..........................distribution.values-array Htuple . double *
Noise distribution of all input regions.
Parallelization Information
T noise distribution mean is reentrant and processed without parallelization.
Possible Predecessor Functions
draw region, gen circle, gen ellipse, gen rectangle1, gen rectangle2, threshold,
erosion circle, gauss image, smooth image, sub image
Possible Successor Functions
T add noise distribution, disp distribution
mean image, T gauss distribution
Image filters
See Also
Module
T sp distribution ( Htuple PercentSalt, Htuple PercentPepper,
Htuple *Distribution )
Generate a salt-and-pepper noise distribution.
T sp distribution generates a noise distribution with the values 0 and 255. The parameters PercentSalt
and PercentPepper determine the percentage of white and black noise pixels, respectively. The sum of these
parameters must be smaller than 100. Usually, the result Distribution is used as input for the operator
T add noise distribution.
Parameter
º PercentSalt (input control) .......................................number Htuple . double / long
Percentage of salt (white noise pixels).
Default Value : 5.0
Value Suggestions : PercentSalt ¾1.0, 2.0, 5.0, 7.0, 10.0, 15.0, 20.0, 30.0
Typical Range of Values : 0.0 PercentSalt 100.0
Minimal Value Step : 0.1
Recommended Value Step : 1.0
Restriction : ´0.0 PercentSaltµ ´PercentSalt 100.0µ
º PercentPepper (input control) ....................................number Htuple . double / long
Percentage of pepper (black noise pixels).
Default Value : 5.0
Value Suggestions : PercentPepper ¾1.0, 2.0, 5.0, 7.0, 10.0, 15.0, 20.0, 30.0
Typical Range of Values : 0.0 PercentPepper 100.0
Minimal Value Step : 0.1
Recommended Value Step : 1.0
Restriction : ´0.0 PercentPepperµ ´PercentPepper 100.0µ
º Distribution (output control) ..........................distribution.values-array Htuple . double *
Resulting noise distribution.
Parameter Number : 513
HALCON 6.0

140 CHAPTER 3. FILTER
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
create_tuple(&PerSalt,1);
set_d(PerSalt,30.0,0);
create_tuple(&PerPepper,1);
set_d(PerPepper,30.0,0);
T_sp_distribution(PerSalt,PerPepper,&Dist);
T_add_noise_distribution(Image,&ImageNoise,Dist);
disp_image(ImageNoise,WindowHandle);
Parallelization Information
T sp distribution is reentrant and processed without parallelization.
T add noise distribution
Possible Successor Functions
Alternatives
T gauss distribution, T noise distribution mean
See Also
T gauss distribution, T noise distribution mean, add noise white
Image filters
Module
3.12 Smoothing
anisotrope diff ( Hobject Image, Hobject *ImageAniso, long Percent,
long Mode, long Iteration, long neighborhoodType )
Smooth an image by edge-preserving anisotropic diffusion.
The operator anisotrope diff carries out an iterative, anisotropic smoothing process on the mathematical
basis of physical diffusion. In analogy to the physical diffusion process describing the concentration balance
between molecules dependent on the density gradient, the diffusion filter carries out a smoothing of the gray
values dependent on the local gray value gradients.
For iterative calculation of the gray value of a pixel the gray value differences in relation to the four or eight
neighbors, respectively, are used. These gray value differences, however, are evaluated differently, i.e., a nonlinear
diffusion process is carried out.
The evaluation is carried out by using a diffusion function (two different functions were implemented, namely
Mode = 1 and/or 2), which — depending on the gradient — ensures that within homogenous regions the smoothing
is stronger than over the margins of regions so that the edges remain sharp. The diffusion function is adjusted to
the noise ratio of the image by a histogram analysis in the gradient image (according to Canny). A high value for
Percent increases the smoothing effect but blurs the edges a little more (values from 80 - 90 percent are typical).
The parameter Iteration determines the number of iterations (typically 3–7).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be smoothed.
º ImageAniso (output object) . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Smoothed image.
º Percent (input control) .............................................................integer long
For histogram analysis; higher values increase the smoothing effect, typically: 80-90.
Default Value : 80
Value Suggestions : Percent ¾65, 70, 75, 80, 85, 90
Typical Range of Values : 50 Percent 100
Minimal Value Step : 1
Recommended Value Step : 5
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 141
º Mode (input control) .................................................................integer long
Selection of diffusion function.
Default Value : 1
Value List : Mode ¾1, 2
º Iteration (input control) ...........................................................integer long
Number of iterations, typical values: 3-7.
Default Value : 5
Value Suggestions : Iteration ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Typical Range of Values : 1 Iteration 30
Minimal Value Step : 1
Recommended Value Step : 1
º neighborhoodType (input control) .................................................integer long
Reqired neighborhood type.
Default Value : 8
Value List : neighborhoodType ¾4, 8
Example
read_image(&Image,"fabrik");
anisotrope_diff(Image,&Aniso,80,1,5,8);
sub_image(Image,Aniso,&Sub,2.0,127.0);
disp_image(Sub,WindowHandle);
For each pixel: Ç´ÁØÖØÓÒ× £ ½µ.
Complexity
Result
If the parameter values are correct the operator anisotrope diff returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
anisotrope diff is reentrant and automatically parallelized (on tuple level, channel level, domain level).
read image, grab image
Possible Predecessor Functions
Possible Successor Functions
regiongrowing, threshold, sub image, dyn threshold, auto threshold
sigma image, rank image
Alternatives
See Also
smooth image, gauss image, sigma image, rank image, eliminate min max
Bibliography
P. Perona, J. Malik: “Scale-space and edge detection using anisotropic diffusion”, IEEE transaction on pattern
analysis and machine intelligence, Vol. 12, No. 7, July 1990.
Module
Image filters
eliminate min max ( Hobject Image, Hobject *filteredImage,
long MaskWidth, long MaskHeight, double Gap, long Mode )
Smooth an image in the spatial domain to suppress noise.
eliminate min max smooths an image by replacing gray values with neighboring mean values, or local minima/maxima.
In order to prevent edges and lines from being smoothed, only those gray values that represent local
minima or maxima are replaced (if there is a line or edge within an image there will be at least one neighboring
pixel with a comparable gray value). Gap controls the strictness of replacment: Only gray values that exceed all
other values within their local neighborhood more than Gap and all values that fall below their neighboring more
than Gap are replaced: ´Ü ݵ represents a Æ ¢ Å sized rectangular neighborhood of an pixel at position ´Ü ݵ,
containing all pixels within the neighborhood except the pixel itself;
HALCON 6.0

142 CHAPTER 3. FILTER
¯ if ÖÝÚÐÙ´Ü Ýµ Ô · ÑÜÑÙÑ´´Ü ݵµ then replacement;
¯ else if ÖÝÚÐÙ´Ü Ýµ ·Ô ÑÒÑÙÑ´´Ü ݵµ then replacement;
¯ else adopt ÖÝÚÐÙ´Ü Ýµ without change;
Mode specifies how to perform the new value in case of a replacement.
ÅÓ ½ replace a local maximum with next minor local maximum and replace a local minimum with
next bigger local minimum
ÅÓ ¾ replace with mean value of all pixels within the local neighborhood (including the replaced
pixel)
ÅÓ ¿ replace with median value of all pixels within the local neighborhood (including the replaced
pixel (this is default and used if Mode has got any other value than 1 or 2)
MaskWidth and MaskHeight specifiy the width and height of the rectangular neighborhood. Border treatment:
Pixels outside the image border are not considered (e.g.: With a local ¿ ¢ ¿-mask the neighborhood of a pixel at
´¼ ¼µ reduces to the pixels at ´½ ¼µ ´¼ ½µ and ´½ ½µ).
Attention
eliminate min max only can work on byte images (HALCON image type BYTE IMAGE). If MaskWidth
or MaskHeight is an even number, it is replaced by the next higher odd number (this allows the unique extraction
of the center of the filter mask). Width/height of the mask may not exceed the image width/height.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image Hobject : byte
Image to smooth.
º filteredImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image Hobject * : byte
Smoothed image.
º MaskWidth (input control) ..........................................................extent.x long
Width of filter mask.
Default Value : 3
Value Suggestions : MaskWidth ¾3, 5, 7, 9
Typical Range of Values : 3 MaskWidth width(Image)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
º MaskHeight (input control) ........................................................extent.y long
Height of filter mask.
Default Value : 3
Value Suggestions : MaskHeight ¾3, 5, 7, 9
Typical Range of Values : 3 MaskHeight width(Image)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
º Gap (input control) ................................................................number double
Gap between local maximum/minimum and all other gray values of the neighborhood.
Default Value : 1.0
Value Suggestions : Gap ¾1.0, 2.0, 5.0, 10.0
º Mode (input control) .................................................................integer long
Replacement rule (1 = next minimum/maximum, 2 = average, 3 =median).
Default Value : 3
Value List : Mode ¾1, 2, 3
Result
eliminate min max returns H MSG TRUE if all parameters are correct.
eliminate min max returns with an error message.
If the input is empty
Parallelization Information
eliminate min max is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successor Functions
wiener filter, wiener filter ni
See Also
mean sp, mean image, median image, median weighted, gauss image, smooth image
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 143
Bibliography
M. Imme:“A Noise Peak Elimination Filter”; S. 204-211 in CVGIP Graphical Models and Image Processing, Vol.
53, No. 2, March 1991
M. L”uckenhaus:“Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”; Diplomarbeit; Technische
Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995.
Module
Image filters
eliminate sp ( Hobject Image, Hobject *ImageFillSP, long MaskWidth,
long MaskHeight, long MinThresh, long MaxThresh )
Replace values outside of thresholds with average value.
The operator eliminate sp replaces all gray values outside the indicated gray value intervals (MinThresh to
MaxThresh) with the neighboring mean values. Only those neighboring pixels which also fall within the gray
value interval are used for averaging. If no such pixel is present in the vicinity the original gray value is used. The
gray values in the input image falling within the gray value interval are also adopted without change.
Attention
If even values instead of odd values are given for MaskHeight or MaskWidth, the routine uses the next larger
odd values instead (this way the center of the filter mask is always explicitly determined).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageFillSP (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Smoothed image.
º MaskWidth (input control) ..........................................................extent.x long
Width of filter mask.
Default Value : 3
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11
Typical Range of Values : 3 MaskWidth 512 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
º MaskHeight (input control) ........................................................extent.y long
Height of filter mask.
Default Value : 3
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11
Typical Range of Values : 3 MaskHeight 512 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
º MinThresh (input control) ...........................................................integer long
Minimum gray value.
Default Value : 1
Value Suggestions : MinThresh ¾1, 5, 7, 9, 11, 15, 23, 31, 43, 61, 101
Typical Range of Values : 0 MinThresh 254 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º MaxThresh (input control) ...........................................................integer long
Maximum gray value.
Default Value : 254
Value Suggestions : MaxThresh ¾5, 7, 9, 11, 15, 23, 31, 43, 61, 101, 200, 230, 250, 254
Typical Range of Values : 1 MaxThresh 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinThresh MaxThresh
HALCON 6.0

144 CHAPTER 3. FILTER
Example
read_image(&Image,"meer_rot");
disp_image(Image,WindowHandle);
eliminate_sp(Image,&ImageMeansp,3,3,101,201);
disp_image(ImageMeansp,WindowHandle);
Parallelization Information
eliminate sp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
disp image
Possible Successor Functions
Alternatives
mean sp, mean image, median image, eliminate min max
See Also
gauss image, smooth image, anisotrope diff, sigma image, eliminate min max
Image filters
Module
fill interlace ( Hobject ImageCamera, Hobject *ImageFilled,
const char *Mode )
Interpolate 2 video half images.
The operator fill interlace calculates an interpolated full image or removes odd/even lines from a video
image composed of two half images. If an image is recorded with a video camera it consists of two half images
recorded at different times but stored in one image in the digital form. This can lead to several errors in further
processing. In order to reduce these errors the video image is modified. Every second line is re-calculated or
removed. The parameter Mode determines whether this must be done for even (’even’, ’rmeven’) or odd (’odd’,
’rmodd’) line numbers. If you choose ’even’ or ’odd’ the gray values in the generated lines are calculated as mean
values from the direct neighbors above or below the current pixel, respectively. If you choose ’rmeven’ or ’rmodd’
the even or odd lines numbers are removed (in that case the resulting image is only half as high as the input image).
The value ’switch’ for Mode cause the odd and even lines to be exchanged.
Parameter
º ImageCamera (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte
Gray image consisting of two half images.
º ImageFilled (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Full image with interpolated/removed lines.
º Mode (input control) ............................................................string const char *
Instruction whether even or odd lines should be replaced/removed.
Default Value : ’odd’
Value List : Mode ¾’odd’, ’even’, ’rmodd’, ’rmeven’, ’switch’
Example
read_image(&Image,"video_bild");
fill_interlace(Image,&New,"odd");
sobel_amp(New,&Sobel,"sum_abs",3);
For each pixel: Ç´¾µ.
Complexity
Result
If the parameter values are correct the operator fill interlace returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
fill interlace is reentrant and automatically parallelized (on tuple level, channel level, domain level).
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 145
read image, grab image
Possible Predecessor Functions
Possible Successor Functions
sobel amp, edges image, regiongrowing, diff of gauss, threshold, dyn threshold,
auto threshold, mean image, gauss image, anisotrope diff, sigma image, median image
median image, gauss image, crop part
Image filters
See Also
Module
gauss image ( Hobject Image, Hobject *ImageGauss, long Size )
Smooth using discrete gauss functions.
The operator gauss image smoothes images using the discrete Gaussian. The smoothing effect increases with
increasing filter size. The following filter sizes (Size) are supported (the sigma value of the gauss function is
indicated in brackets):
3 (0.81)
5 (0.93)
7 (1.50)
9 (2.00)
11 (2.45)
For margin control the gray values of the images are reflected at the image borders.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int4 / int2
Image to be smoothed.
º ImageGauss (output object) . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int4 / int4
Filtered image.
º Size (input control) .................................................................integer long
Required filter size.
Default Value : 5
Value List : Size ¾3, 5, 7, 9, 11
Example
gauss_image(Input,&Gauss,7,);
regiongrowing(Gauss,&Segments,7,7,5,100,);
For each pixel: Ç´ËÞ £ ¾µ.
Complexity
Result
If the parameter values are correct the operator gauss image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
gauss image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
read image, grab image
Possible Predecessor Functions
Possible Successor Functions
regiongrowing, threshold, sub image, dyn threshold, auto threshold
smooth image, derivate gauss
Alternatives
HALCON 6.0

146 CHAPTER 3. FILTER
See Also
mean image, anisotrope diff, sigma image, gen lowpass
Image filters
Module
T info smooth ( Htuple Filter, Htuple Alpha, Htuple *Size,
Htuple *Coeffs )
Information on smoothing filter smooth image.
The operator T info smooth returns an estimation of the width of the smoothing filters used in routine
smooth image. For this purpose the underlying continuous impulse answers of Filter are scanned until a
filter coefficient is smaller than five percent of the maximum coefficient (at the origin). Alpha is the filter parameter
(see smooth image). Currently four filters are supported (parameter Filter):
’deriche1’, ’deriche2’, ’shen’ und ’gauss’.
The gauss filter was conventionally implemented with filter masks (the other three are recursive filters). In the case
of the gauss filter the filter coefficients (of the one-dimensional impulse answer ´Òµ with Ò ¼) are returned in
Coeffs in addition to the filter size.
Parameter
º Filter (input control) .................................................string Htuple . const char *
Name of required filter.
Default Value : ’deriche2’
Value List : Filter ¾’deriche1’, ’deriche2’, ’shen’, ’gauss’
º Alpha (input control) .........................................................real Htuple . double
Filter parameter: small values effect strong smoothing (reversed in case of ’gauss’).
Default Value : 0.5
Value Suggestions : Alpha ¾0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 7.0, 10.0
Typical Range of Values : 0.01 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0.0
º Size (output control) .......................................................integer Htuple . long *
Width of filter is approx. size x size pixels.
º Coeffs (output control) ..............................................integer-array Htuple . long *
In case of gauss filter: coeffients of the “positive” half of the 1D impulse answer.
Example
info_smooth(’deriche2’,0.5,Size,Coeffs);
smooth_image(Input,&Smooth,’deriche2’,7);
Result
If the parameter values are correct the operator T info smooth returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
T info smooth is reentrant and processed without parallelization.
read image
smooth image
smooth image
Image filters
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 147
mean image ( Hobject Image, Hobject *ImageMean, long MaskWidth,
long MaskHeight )
Smooth by averaging.
The operator mean image carries out a linear smoothing with the gray values of all input images (Image). The
filter matrix consists of ones (evaluated equally) and has the size Å×ÀØ ¢ Å×ÏØ. The result of the
convolution is divided by Å×ÀØ¢ Å×ÏØ. For margin control the gray values are reflected at the image
edges.
Attention
If even values instead of odd values are given for MaskHeight or MaskWidth, the routine uses the next larger
odd values instead (this way the center of the filter mask is always explicitly determined).
Parameter
º Image (input object) . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2 / int4 / real / dvf
Image to be smoothed.
º ImageMean (output object) . . . . . . (multichannel-)image(-array) Hobject * : byte / int2 / int4 / real / dvf
Smoothed image.
º MaskWidth (input control) ..........................................................extent.x long
Width of filter mask.
Default Value : 9
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 15, 23, 31, 43, 61, 101
Typical Range of Values : 3 MaskWidth 501
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
º MaskHeight (input control) ........................................................extent.y long
Height of filter mask.
Default Value : 9
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 15, 23, 31, 43, 61, 101
Typical Range of Values : 3 MaskHeight 501
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
read_image(&Image,"fabrik");
mean_image(Image,&Mean,3,3);
disp_image(Mean,WindowHandle);
Example
Complexity
For each pixel: O(15).
Result
If the parameter values are correct the operator mean image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
mean image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
dyn threshold, regiongrowing
gauss image, smooth image
Possible Successor Functions
Alternatives
See Also
anisotrope diff, sigma image, convol image, gen lowpass
Image filters
Module
HALCON 6.0

148 CHAPTER 3. FILTER
mean n ( Hobject Image, Hobject *ImageMean )
Average gray values over several channels.
The operator mean n generates the pixel-by-pixel mean value of all channels . For each coordinate point the sum
of all gray values at this coordinate is calculated. The result is the mean of the gray values (sum divided by the
number of channels). The output image has one channel.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject : byte / real
Multichannel gray image.
º ImageMean (output object) ......................singlechannel-image(-array) Hobject * : byte / real
Result of averaging.
Example
compose3(Channel1,Channel2,Channel3,&MultiChannel);
mean_n(MultiChannel,&Mean);
Parallelization Information
mean n is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessor Functions
compose2, compose3, compose4, add channels
disp image
count channels
Image filters
Possible Successor Functions
See Also
Module
mean sp ( Hobject Image, Hobject *ImageSPMean, long MaskWidth,
long MaskHeight, long MinThresh, long MaxThresh )
Suppress salt and pepper noise.
The operator mean sp carries out a smoothing by averaging the values. Only the gray values within the interval
from MinThresh to MaxThresh are averaged. Gray values which are too light or too dark are ignored during
summation. If no gray value lies within the default interval during summation the original gray value is adopted.
If the thresholds are set at 0 or 255, respectively, the operator mean sp behaves like mean image except for the
running time.
The operator mean sp is used to suppress extreme gray values (salt and pepper noise = white and black dots).
Attention
If even values instead of odd values are given for MaskHeight or MaskWidth, the routine uses the next larger
odd values instead (this way the center of the filter mask is always explicitly determined).
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º ImageSPMean (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Smoothed image.
º MaskWidth (input control) ..........................................................extent.x long
Width of filter mask.
Default Value : 3
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11
Typical Range of Values : 3 MaskWidth 512 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 149
º MaskHeight (input control) ........................................................extent.y long
Height of filter mask.
Default Value : 3
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11
Typical Range of Values : 3 MaskHeight 512 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
º MinThresh (input control) ...........................................................integer long
Minimum gray value.
Default Value : 1
Value Suggestions : MinThresh ¾1, 5, 7, 9, 11, 15, 23, 31, 43, 61, 101
Typical Range of Values : 0 MinThresh 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º MaxThresh (input control) ...........................................................integer long
Maximum gray value.
Default Value : 254
Value Suggestions : MaxThresh ¾5, 7, 9, 11, 15, 23, 31, 43, 61, 101, 200, 230, 250, 254
Typical Range of Values : 0 MaxThresh 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinThresh MaxThresh
Example
read_image(&Image,"meer_rot");
disp_image(Image,WindowHandle);
mean_sp(Image,&ImageMeansp,3,3,101,201);
disp_image(ImageMeansp,WindowHandle);
Parallelization Information
mean sp is reentrant and automatically parallelized (on tuple level, channel level, domain level).
disp image
Possible Successor Functions
Alternatives
mean image, median image, median separate, eliminate min max
See Also
anisotrope diff, sigma image, gauss image, smooth image, eliminate min max
Image filters
Module
median image ( Hobject Image, Hobject *ImageMedian,
const char *MaskType, long Radius, long Margin )
Median filtering with different rank masks.
The operator median image carries out a non-linear smoothing of the gray values of all input images (Image).
The shift mask (MaskType) is transmitted in the form of an object (more precisely: its region). Several margin
controls can be chosen for filtering (Margin):
0...255 Pixels outside of the image edges are assumued
constant (with the indicated gray value).
-1 Continuation of edge pixels.
-2 Cyclic continuation of image edges.
-3 Reflection of pixels at the image edges.
HALCON 6.0

150 CHAPTER 3. FILTER
The indicated mask (= region of the mask image) is put over the image to be filtered in such a way that the center
of the mask touches all pixels of the objects once. For each of these pixels all neighboring pixels covered by the
mask are sorted in an ascending sequence according to their gray values. Thus, each of these sorted gray value
sequences contains exactly as many gray values as the mask has pixels. From these sequences the median is
selected and entered as resulting gray value at the corresponding output image.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be filtered.
º ImageMedian (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Median filtered image.
º MaskType (input control) ......................................................string const char *
Type of median mask.
Default Value : ’circle’
Value List : MaskType ¾’circle’, ’rectangle’
º Radius (input control) ...............................................................integer long
Radius of median mask.
Default Value : 1
Value Suggestions : Radius ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 15, 19, 25, 31, 39, 47, 59
Typical Range of Values : 1 Radius 101
Minimal Value Step : 1
Recommended Value Step : 2
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (edge pixels continued), -2 (cyclic continuation), -3 (reflection).
Default Value : -3
Typical Range of Values : -3 Margin 255
Example
read_image(&Image,"fabrik");
median_image(Image,&Median,"circle",3,-1);
disp_image(MedianWeighted,WindowHandle);
For each pixel: O( Ô Ö´Å×ÌÝÔµ £ ).
Complexity
Result
If the parameter values are correct the operator median image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
median image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
read image
Possible Predecessor Functions
Possible Successor Functions
threshold, dyn threshold, regiongrowing
rank image
Alternatives
See Also
gen circle, gen rectangle1, gray erosion rect, gray dilation rect
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 318-319
Image filters
Module
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 151
median separate ( Hobject Image, Hobject *ImageSMedian, long MaskWidth,
long MaskHeight, long Margin )
Separated median filtering with rectangle masks.
The operator median separate carries out a variation of the median filtering: First two auxiliary images are
created. The first one originates from a median filtering with a horizontal mask with a height of one pixel and the
width MaskWidth followed by filtering with a mask with the height MaskHeight. The second auxiliary image
is created by filtering with the same masks, but with a reversed sequence of the operation: first the vertical, then
the horizontal mask. The output image results from averaging the two auxiliary images pixel by pixel.
The operator median separate is clearly faster than the normal operator median image because both masks
are one pixel wide, facilitating a very effecient processing. The runtime is practically ÒÔÒÒØ of the size of
the mask. For example, the operator median separate can be well used after texture filters, where large masks
are needed.
The filter can also be used several times in a row in order to enhance the smoothing.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be filtered.
º ImageSMedian (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Median filtered image.
º MaskWidth (input control) ..........................................................extent.x long
Width of rank mask.
Default Value : 25
Value Suggestions : MaskWidth ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 27, 43, 51, 67, 91, 121, 151
Typical Range of Values : 1 MaskWidth 401
Minimal Value Step : 2
Recommended Value Step : 2
º MaskHeight (input control) ........................................................extent.y long
Height of rank mask.
Default Value : 25
Value Suggestions : MaskHeight ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 27, 43, 51, 67, 91, 121, 151
Typical Range of Values : 1 MaskHeight 401
Minimal Value Step : 2
Recommended Value Step : 2
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (edge pixels continued), -2 (cyclic continuation), -3 (reflection).
Default Value : -3
Typical Range of Values : -3 Margin 255
Minimal Value Step : 1
Recommended Value Step : 1
Example
read_image(&Image,"fabrik");
median_separate(Image,&MedianSeparate,5,5,3);
disp_image(MedianSeparate,WindowHandle);
Complexity
For each pixel: O(¼).
Parallelization Information
median separate is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
(T )texture laws, sobel amp, deviation image
Possible Successor Functions
learn ndim norm, learn ndim box, median separate, regiongrowing, auto threshold
median image
Alternatives
HALCON 6.0

152 CHAPTER 3. FILTER
rank image
See Also
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 319
Image filters
Module
median weighted ( Hobject Image, Hobject *ImageWMedian,
const char *MaskType, long MaskSize )
Weighted median filtering with different rank masks.
The operator median weighted calculates the median of the gray values within a local environment. In
contrast to median image, which uses all gray values within the environment exactly once, the operator
median weighted weights all gray values several times depending on their position. A gray value is received
into the field to be sorted several times according to its weighting. The following masks are available:
’gauss’ (MaskSize =3)
’inner’ (MaskSize =3)
½ ¾ ½
¾ ¾
½ ¾ ½
½ ½ ½
½ ¿ ½
½ ½ ½
The operator median weighted means that, contrary to median image, gray value corners remain.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Image to be filtered.
º ImageWMedian (output object) . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte / int2
Median filtered image.
º MaskType (input control) ......................................................string const char *
Type of median mask.
Default Value : ’inner’
Value List : MaskType ¾’inner’, ’gauss’
º MaskSize (input control) ............................................................integer long
mask size.
Default Value : 3
Value List : MaskSize ¾3
Example
read_image(&Image,"fabrik");
median_weighted(Image,&MedianWeighted,"gauss",3);
disp_image(MedianWeighted,WindowHandle);
Complexity
For each pixel: O(ÐÓ´Ö´Å×ÌÝÔµµÖ´Å×ÌÝÔµ).
Parallelization Information
median weighted is reentrant and automatically parallelized (on tuple level, channel level, domain level).
read image
Possible Predecessor Functions
Possible Successor Functions
threshold, dyn threshold, regiongrowing
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 153
Alternatives
median image, trimmed mean, sigma image
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 319
Image filters
Module
midrange image ( Hobject Image, Hobject Mask, Hobject *ImageMidrange,
long Margin )
Calculate the average of maximum and minimum inside any mask.
The operator midrange image forms the average of maximum and minimum inside the indicated mask in the
whole image. Several margin controls (Margin) can be chosen for filtering:
0...255 Pixels outside of the image edges are assumued
constant (with the indicated gray value).
-1 Continuation of edge pixels.
-2 Cyclic continuation of image edges.
-3 Reflection of pixels at the image edges.
The indicated mask (= region of the mask image) is put over the image to be filtered in such a way that the center
of the mask touches all pixels once.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be filtered.
º Mask (input object) ..........................................................region Hobject : byte
Region serving as filter mask.
º ImageMidrange (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Filtered output image.
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (edge pixels continued), -2 (cyclic continuation), -3 (reflection).
Default Value : -3
Typical Range of Values : -3 Margin 255
Example
read_image(&Image,"fabrik");
draw_region(&Region,WindowHandle);
midrange_image(Image,Region,&Midrange,-3,);
disp_image(Midrange,WindowHandle);
For each pixel: O( Ô Ö´Å×µ £ ).
Complexity
Result
If the parameter values are correct the operator midrange image returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
midrange image is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
read image, draw region, gen circle, gen rectangle1
Possible Successor Functions
threshold, dyn threshold, regiongrowing
HALCON 6.0

154 CHAPTER 3. FILTER
sigma image
Alternatives
See Also
gen circle, gen rectangle1, gray erosion rect, gray dilation rect, gray range rect
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 319
Image filters
Module
rank image ( Hobject Image, Hobject Mask, Hobject *ImageRank, long Rank,
long Margin )
Smooth an image with an arbitrary rank mask.
The operator rank image carries out a non-linear smoothing of the gray values of all input images (Image).
The shift mask (Mask) is transmitted in the form of a region. The rank gray value (Rank) within the shift mask is
calculated for all pixels. Several margin controls can be chosen for filtering (Margin):
0...255 Pixels outside of the image edges are assumued
constant (with the indicated gray value).
-1 Continuation of edge pixels.
-2 Cyclic continuation of image edges.
-3 Reflection of pixels at the image edges.
The indicated mask is put over the image to be filtered in such a way that the center of the mask touches all pixels
once. For each of these pixels all neighboring pixels covered by the mask are sorted in an ascending sequence
according to their gray values. Thus, each of these sorted gray value sequences contains exactly as many gray
values as the mask has pixels. From these sequences the n-largest element (= Rank) is selected and entered as
resulting gray value at the corresponding output image.
If Rank is set to the median the well known median filter is applied. For Mask images can be created e.g., via
the operators gen circle or gen rectangle1. IfRank is applied to 1 or the area of Mask, respectively, the
effect is the same as in case of gray erosion rect or gray dilation rect.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject : byte
Image to be filtered.
º Mask (input object) ..........................................................region Hobject : byte
Region serving as filter mask.
º ImageRank (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject *
Filtered image.
º Rank (input control) .................................................................integer long
Rank of the output gray value in the sorted sequence of input gray values inside the filter mask. Typical value
(median): area(mask) / 2.
Default Value : 5
Value Suggestions : Rank ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31
Typical Range of Values : 1 Rank 512
Minimal Value Step : 1
Recommended Value Step : 2
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (edge pixels continued), -2 (cyclic continuation), -3 (reflection).
Default Value : -3
Typical Range of Values : -3 Margin 255
read_image(&Image,"fabrik");
Example
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 155
draw_region(&Region,WindowHandle);
rank_image(Image,Region,&ImageRank,5,-3,);
disp_image(ImageRank,WindowHandle);
For each pixel: O( Ô Ö´Å×µ £ ).
Complexity
Result
If the parameter values are correct the operator rank image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
rank image is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
read image, draw region, gen circle, gen rectangle1
Possible Successor Functions
threshold, dyn threshold, regiongrowing
sigma image
Alternatives
See Also
gen circle, gen rectangle1, gray erosion rect, gray dilation rect
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 318-320
Image filters
Module
sigma image ( Hobject Image, Hobject *ImageSigma, long MaskHeight,
long MaskWidth, long Sigma )
Non-linear smoothing with the sigma filter.
The operator sigma image carries out a non-linear smoothing of the gray values of all input images (Image).
All pixels are checked in a rectangular window (MaskHeight ¢ MaskWidth). All pixels of the window which
differ from the current pixel by less than Sigma are used for calculating the new pixel, which is the average of the
chosen pixels. If all differences are larger than Sigma the gray value is adapted unchanged.
Attention
The filter is implemented for images of the ’byte’ type only. If even values instead of odd values are given for
MaskHeight or MaskWidth, the routine uses the next larger odd values instead (this way the center of the filter
mask is always explicitly determined).
Parameter
º Image (input object) . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte / int1 / int2 / int4 / real
Image to be smoothed.
º ImageSigma (output object) . . . . (multichannel-)image(-array) Hobject * : byte / int1 / int2 / int4 / real
Smoothed image.
º MaskHeight (input control) ........................................................extent.y long
Height of the mask (number of lines).
Default Value : 5
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskHeight 101
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
HALCON 6.0

156 CHAPTER 3. FILTER
º MaskWidth (input control) ..........................................................extent.x long
Width of the mask (number of columns).
Default Value : 5
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskWidth 101
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
º Sigma (input control) ................................................................integer long
Max. deviation to the average.
Default Value : 3
Value Suggestions : Sigma ¾3, 5, 7, 9, 11, 20, 30, 50
Typical Range of Values : 0 Sigma 255
Minimal Value Step : 1
Recommended Value Step : 2
Example
read_image(&Image,"fabrik");
sigma_image(Image,&ImageSigma,5,5,3);
disp_image(ImageSigma,WindowHandle);
Complexity
For each pixel: O(MaskHeight¢ MaskWidth).
Result
If the parameter values are correct the operator sigma image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
sigma image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
read image
Possible Predecessor Functions
Possible Successor Functions
threshold, dyn threshold, regiongrowing
anisotrope diff, rank image
smooth image, gauss image, mean image
Alternatives
See Also
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 325
Image filters
Module
smooth image ( Hobject Image, Hobject *ImageSmooth, const char *Filter,
double Alpha )
Smooth an image using recursive filters.
smooth image smooths gray images using recursive filters originally developed by Deriche and Shen and using
the non-recursive Gaussian filter. The following filters can be choosen via the parameter Filter:
’deriche1’, ’deriche2’, ’shen’ und ’gauss’.
The “filter width” (i.e., the range of the filter and thereby result of the filter) can be of any size. In the case that the
Deriche or Shen is choosen it decreases by increasing the filter parameter Alpha and increases in the case of the
Gauss filter (and Alpha corresponds to the standard deviation of the Gaussian function). An approximation of the
appropiate size of the filterwidth Alpha is performed by the operator T info smooth.
HALCON/C Reference Manual / 2000-11-15

3.12. SMOOTHING 157
Non-recursive filters like the Gaussian filter are often implemented using filter-masks. In this case the runtime
of the operator increases with increasing size of the filter mask. The runtime of the recursive filters remains
constant; except the margin control becomes a little bit more time consuming. The Gaussian filter becomes slow in
comparison to the recursive ones but is in contrast to them isotropic (the filter ’deriche2’ is only weakly direction
sensitive). A comparable result of the smoothing is achieved by choosing the following values for the parameter:
ÐÔ´¼Ö¾ ¼ µ ÐÔ´¼Ö½ ¼ µ
¾
ÐÔ´¼×Ò ¼ µ ÐÔ´¼Ö½ ¼ µ
¾
ÐÔ´¼Ù×× ¼ µ
Parameter
½
ÐÔ´¼Ö½ ¼ µ
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be smoothed.
º ImageSmooth (output object) . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject * : byte
Smoothed image.
º Filter (input control) .........................................................string const char *
Filter.
Default Value : ’deriche2’
Value List : Filter ¾’deriche1’, ’deriche2’, ’shen’, ’gauss’
º Alpha (input control) .................................................................real double
Filterparameter: small values cause strong smoothing (vice versa by using bei ’gauss’).
Default Value : 0.5
Value Suggestions : Alpha ¾0.1, 0.2, 0.3, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 7.0, 10.0
Typical Range of Values : 0.01 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0
Example
info_smooth(’deriche2’,0.5,Size,Coeffs);
smooth_image(Input,&Smooth,’deriche2’,7);
Result
If the parameter values are correct the operator smooth image returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
smooth image is reentrant and automatically parallelized (on tuple level, channel level).
read image
Possible Predecessor Functions
Possible Successor Functions
threshold, dyn threshold, regiongrowing
Alternatives
gauss image, mean image, derivate gauss
See Also
T info smooth, median image, sigma image, anisotrope diff
Bibliography
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelligence;
PAMI-12, no. 1; S. 78-87; 1990.
Module
Image filters
HALCON 6.0

158 CHAPTER 3. FILTER
trimmed mean ( Hobject Image, Hobject Mask, Hobject *ImageTMean,
long Number, long Margin )
Smooth an image with an arbitrary rank mask.
The operator trimmed mean carries out a non-linear smoothing of the gray values of all input images (Image).
The shift mask (Mask) is transmitted in the form of a region. The average of Number gray values located near
the median is calculated. Several margin controls can be chosen for filtering (Margin):
0...255 Pixels outside of the image edges are assumued
constant (with the indicated gray value).
-1 Continuation of edge pixels.
-2 Cyclic continuation of image edges.
-3 Reflection of pixels at the image edges.
The indicated mask (= region of the mask image) is put over the image to be filtered in such a way that the center
of the mask touches all pixels once. For each of these pixels all neighboring pixels covered by the mask are sorted
in an ascending sequence according to their gray values. Thus, each of these sorted gray value sequences contains
exactly as many gray values as the mask has pixels. If F is the surface of the mask the average of these sequences
is calculated as follows: The first (F - Number)/2 gray values are ignored. Then the following Number gray values
are summed up and divided by Number. Again the remaining (F - Number)/2 gray values are ignored.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject : byte
Image to be filtered.
º Mask (input object) ................................................................region Hobject
Image whose region serves as filter mask.
º ImageTMean (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject * : byte
Filtered output image.
º Number (input control) ...............................................................integer long
Number of averaged pixels. Typical value: Surface(Mask) / 2.
Default Value : 5
Value Suggestions : Number ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31
Typical Range of Values : 1 Number 401
Minimal Value Step : 1
Recommended Value Step : 2
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (edge pixels continued), -2 (cyclic continuation), -3 (reflection).
Default Value : -3
Typical Range of Values : -3 Margin 255
Example
read_image(&Image,"fabrik");
draw_region(&Region,WindowHandle);
trimmed_mean(Image,Region,&TrimmedMean,5,-3,);
disp_image(TrimmedMean,WindowHandle);
For each pixel: O( Ô Ö´Å×µ £ ).
Complexity
Result
If the parameter values are correct the operator trimmed mean returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
trimmed mean is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
read image, draw region, gen circle, gen rectangle1
HALCON/C Reference Manual / 2000-11-15

3.13. TEXTURE 159
Possible Successor Functions
threshold, dyn threshold, regiongrowing
Alternatives
sigma image, median weighted, median image
See Also
gen circle, gen rectangle1, gray erosion rect, gray dilation rect
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, Seite 320
Image filters
Module
3.13 Texture
deviation image ( Hobject Image, Hobject *ImageDeviation, long Width,
long Height )
Calculate the standard deviation of gray values within rectangular windows.
deviation image calculates the standard deviation of gray values in the image Image within a rectangular
mask of size (Height, Width). The resulting image is returned in ImageDeviation. For byte images, the
result is multiplied by 2. If the parameters Height and Width are even, they are changed to the next larger odd
value. At the image borders the gray values are mirrored.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int4 / real / int2
Image for which the standard deviation is to be calculated.
º ImageDeviation (output object) ..................image(-array) Hobject * : byte / int4 / real / int2
Image containing the standard deviation.
º Width (input control) ...............................................................extent.x long
Width of the mask in which the standard deviation is calculated.
Default Value : 11
Value List : Width ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25
Restriction : ´3 Widthµ odd´Widthµ
º Height (input control) ..............................................................extent.y long
Height of the mask in which the standard deviation is calculated.
Default Value : 11
Value List : Height ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25
Restriction : ´3 Heightµ odd´Heightµ
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
deviation_image(Image,&Deviation,9,9);
disp_image(Deviation,WindowHandle);
Result
deviation image returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
deviation image is reentrant and automatically parallelized (on tuple level, channel level).
disp image
entropy image, entropy gray
Possible Successor Functions
Alternatives
HALCON 6.0

160 CHAPTER 3. FILTER
See Also
convol image, (T )texture laws, intensity
Image filters
Module
entropy image ( Hobject Image, Hobject *ImageEntropy, long Width,
long Height )
Calculate the entropy of gray values within a rectangular window.
entropy image calculates the entropy of gray values in the image Image within a rectangular mask of size
(Height, Width). The resulting image is returned in ImageEntropy, in which the entropy is multiplied by
32. If the parameters Height and Width are even, they are changed to the next larger odd value. At the image
borders the gray values are mirrored.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image for which the entropy is to be calculated.
º ImageEntropy (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Entropy image.
º Width (input control) ...............................................................extent.x long
Width of the mask in which the entropy is calculated.
Default Value : 9
Value List : Width ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25
Value Suggestions : Width ¾3, 5, 7, 9, 11, 13, 15
Restriction : ´3 Widthµ odd´Widthµ
º Height (input control) ..............................................................extent.y long
Height of the mask in which the entropy is calculated.
Default Value : 9
Value List : Height ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25
Value Suggestions : Height ¾3, 5, 7, 9, 11, 13, 15
Restriction : ´3 Heightµ odd´Heightµ
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
entropy_image(Image,&Entropy1,9,9);
disp_image(Entropy1,WindowHandle);
Example
Result
entropy image returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
entropy image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
disp image
entropy gray
energy gabor, entropy gray
Image filters
Possible Successor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

3.13. TEXTURE 161
texture laws ( Hobject Image, Hobject *ImageTexture,
const char *FilterTypes, long Shift, long FilterSize )
T texture laws ( Hobject Image, Hobject *ImageTexture,
Htuple FilterTypes, Htuple Shift, Htuple FilterSize )
Filter an image using a Laws texture filter.
(T )texture laws applies one or more texture transformations (according to Laws) to an image. This is done
by convolving the input image with one (or more) filter masks. The filters are:
9 different 3x3 matrices obtainable from the following three vectors:
l ½ ¾ ½℄
e ½ ¼ ½℄
s ½ ¾ ½℄
25 different 5x5 matrices obtainable from the following five vectors:
l ½ ½℄
e ½ ¾ ¼ ¾ ½℄
s ½ ¼ ¾ ¼ ½℄
r ½ ½℄
w ½ ¾ ¼ ¾ ½℄
36 different 7x7 matrices obtainable from the following six vectors:
l ½ ½ ¾¼ ½ ½℄
e ½ ¼ ½℄
s ½ ¾ ½ ½ ¾ ½℄
r ½ ¾ ½ ½ ¾ ½℄
w ½ ¼ ¿ ¼ ¿ ¼ ½℄
o ½ ½ ¾¼ ½ ½℄
For most of the filters the resulting gray values must be modified by a Shift. This makes the different textures in
the output image more comparable to each other, provided suitable filters are used.
The name of the filter is composed of the letters of the two vectors used, where the first letter denotes convolution
in the column direction while the second letter denotes convolution in the row direction.
If more than one filter type is passed, a multi-channel image is returned for each (single-channel) input image, with
each channel corresponding to a particular filter.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject : byte / int2
Images to which the texture transformation is to be applied.
º ImageTexture (output object) . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * : byte
Texture images.
º FilterTypes (input control) ..................................string(-array) (Htuple .) const char *
Desired filters (name or number).
Default Value : ’el’
Value Suggestions : FilterTypes ¾’ll’, ’le’, ’ls’, ’lr’, ’lw’, ’lo’, ’el’, ’ee’, ’es’, ’er’, ’ew’, ’eo’, ’sl’, ’se’,
’ss’, ’sr’, ’sw’, ’so’, ’rl’, ’re’, ’rs’, ’rr’, ’rw’, ’ro’, ’wl’, ’we’, ’ws’, ’wr’, ’ww’, ’wo’, ’ol’, ’oe’, ’os’, ’or’, ’ow’,
’oo’
º Shift (input control) ......................................................integer (Htuple .) long
Shift to reduce the gray value dynamics.
Default Value : 2
Value List : Shift ¾0, 1, 2, 3, 4, 5, 6, 7, 8, 9
º FilterSize (input control) ................................................integer (Htuple .) long
Size of the filter kernel.
Default Value : 5
Value List : FilterSize ¾3, 5, 7
HALCON 6.0

162 CHAPTER 3. FILTER
Example
/* 2 dimensional pixel classification */
read_image(&Image,"combine");
open_window(0,0,-1,-1,"root","visible","",&WindowHandle);
disp_image(Image,WindowHandle);
texture_laws(Image,&Texture1,"es",2,5);
texture_laws(Image,&Texture2,"le",2,5);
mean_image(Texture1,&H1,51,51);
mean_image(Texture2,&H2,51,51);
fwrite_string(FileId,"mark desired image section");
fnew_line(FileId);
set_color(WindowHandle,"green");
draw_region(&Region,WindowHandle);
reduce_domain(H1,Region,&Foreground1);
reduce_domain(H2,Region&,Foreground2);
histo_2dim(Region,Foreground1,Foreground2,&Histo);
threshold(Histo,&Characteristic_area,1.0,1000000.0);
set_color(WindowHandle,"blue");
disp_region(Characteristic_area,WindowHandle);
class_2dim(H1,H2,Characteristic_area,&Seg,4,5:);
set_color(WindowHandle,"red");
disp_region(Seg,WindowHandle);
Result
(T )texture laws returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
(T )texture laws is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successor Functions
mean image, gauss image, median image, histo 2dim, learn ndim norm, learn ndim box,
threshold
Alternatives
convol image
See Also
class 2dim sup, class ndim norm
Bibliography
Laws, K.I. “Textured image segmentation”; Ph.D. dissertation, Dept. of Engineering, Univ. Southern California,
1980
Module
Image filters
3.14 Wiener-Filter
gen psf defocus ( Hobject *Psf, long PSFwidth, long PSFheight,
double Blurring )
Generate an impulse response of an uniform out-of-focus blurring.
gen psf defocus generates an impulse response (spatial domain) of an uniform out-of-focus blurring and
writes it into an image of HALCON image type ’real’. Blurring specifies the extent of blurring by defining
the ”‘blur radius”’ (out-of-focus blurring maps each image pixel on a small circle with a radius of Blurring
- specified in ”‘number of pixels”’). If specified less than zero, the absolute value of Blurring is used. The
result image of gen psf defocus encloses an spatial domain impulse response of the specified blurring. Its
representation presumes the origin in the upper left corner. This results in the following disposition of an ÆÜÅ
sized image:
HALCON/C Reference Manual / 2000-11-15

3.14. WIENER-FILTER 163
¯ first rectangle (”‘upper left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý ¼´Å¾µ ½µ
- conforms to the fourth quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ¼Æ¾ and Ý ¼ ž
¯ second rectangle (”‘upper right”’): (image coordinates Ü Æ¾Æ ½, Ý ¼´Å¾µ ½µ
- conforms to the third quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ and Ý ½ ž
¯ third rectangle (”‘lower left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý Å¾Å ½µ
- conforms to the first quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ½Æ¾ and Ý Å¾¼
¯ fourth rectangle (”‘lower right”’): (image coordinates Ü Æ¾Æ ½, Ý Å¾Å ½µ
- conforms to the second quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ und Ý Å¾½
This representation conforms to that of the impulse response parameter of the HALCON-operator
wiener filter. So one can use gen psf defocus to generate an impulse response for Wiener filtering.
Parameter
º Psf (output object) ........................................................image Hobject * : real
Impuls response of uniform out-of-focus blurring.
º PSFwidth (input control) ............................................................integer long
Width of result image.
Default Value : 256
Value Suggestions : PSFwidth ¾128, 256, 512, 1024
Typical Range of Values : 1 PSFwidth
º PSFheight (input control) ...........................................................integer long
Height of result image.
Default Value : 256
Value Suggestions : PSFheight ¾128, 256, 512, 1024
Typical Range of Values : 1 PSFheight
º Blurring (input control) .............................................................real double
Degree of Blurring.
Default Value : 5.0
Value Suggestions : Blurring ¾1.0, 5.0, 10.0, 15.0, 18.0
Result
gen psf defocus returns H MSG TRUE if all parameters are correct.
Parallelization Information
gen psf defocus is reentrant and processed without parallelization.
Possible Predecessor Functions
simulate motion, gen psf motion
Possible Successor Functions
simulate defocus, wiener filter, wiener filter ni
See Also
simulate defocus, gen psf motion, simulate motion, wiener filter, wiener filter ni
Bibliography
Reginald L. Lagendijk, Jan Biemond: Iterative Identification and Restoration of Images, Kluwer Academic Publishers
Boston/Dordrecht/London, 1991
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995.
Module
Wiener filter
gen psf motion ( Hobject *Psf, long PSFwidth, long PSFheight,
double Blurring, long Angle, long Type )
Generate an impulse response of a (linearly) motion blurring.
HALCON 6.0

164 CHAPTER 3. FILTER
gen psf motion generates an impulse response (spatial domain) of a blurring caused by a relative motion
between the object and the camera during exposure. The generated impulse response is output into an image
of HALCON image type ’real’. PSFwidth and PSFheight define the width and height of the ouput image.
The blurring motion moves along an even. Angle fixes its direction by specifying the angle between the motion
direction and the x-axis (anticlockwise, measured in degrees). To specify different velocity behaviour five PSF
prototypes can be generated. Type switches between the following prototypes:
1. reverse ramp (crude model for acceleration)
2. reverse trapezoid (crude model for high acceleration)
3. square pulse (exact model for constant velocity), this is default
4. forward trapezoid (crude model for deceleration)
5. forward ramp (crude model for high deceleration)
The blurring affects all part of the image uniformly. Blurring controls the extent of blurring. It specifies the
number of pixels (lying one after another) that are affetcetd by the blurring. This number is determined by velocity
of the motion and exposure time. If Blurring is a negative number, an adequate blurring in reverse direction
is simulated. If Angle is a negative number, it is interpreted clockwise. If Angle exceeds 360 or falls below
-360, it is transformed modulo(360) in an adequate number between ¼¿¼℄ resp. ¿¼¼℄. The result image
of gen psf motion encloses an spatial domain impulse response of the specified blurring. Its representation
presumes the origin in the upper left corner. This results in the following disposition of an ÆÜÅ sized image:
¯ first rectangle (”‘upper left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý ¼´Å¾µ ½µ
- conforms to the fourth quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ¼Æ¾ and Ý ¼ ž
¯ second rectangle (”‘upper right”’): (image coordinates Ü Æ¾Æ ½, Ý ¼´Å¾µ ½µ
- conforms to the third quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ and Ý ½ ž
¯ third rectangle (”‘lower left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý Å¾Å ½µ
- conforms to the first quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ½Æ¾ and Ý Å¾¼
¯ fourth rectangle (”‘lower right”’): (image coordinates Ü Æ¾Æ ½, Ý Å¾Å ½µ
- conforms to the second quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ und Ý Å¾½
This representation conforms to that of the impulse response parameter of the HALCON-operator
wiener filter. So one can use gen psf motion to generate an impulse response for Wiener filtering a
motion blurred image.
Parameter
º Psf (output object) ........................................................image Hobject * : real
Impulse response of motion-blur.
º PSFwidth (input control) ............................................................integer long
Width of impulse response image.
Default Value : 256
Value Suggestions : PSFwidth ¾128, 256, 512, 1024
Typical Range of Values : 1 PSFwidth
º PSFheight (input control) ...........................................................integer long
Height of impulse response image.
Default Value : 256
Value Suggestions : PSFheight ¾128, 256, 512, 1024
Typical Range of Values : 1 PSFheight
º Blurring (input control) .............................................................real double
Degree of motion-blur.
Default Value : 20.0
Value Suggestions : Blurring ¾5.0, 10.0, 20.0, 30.0, 40.0
º Angle (input control) ................................................................integer long
Angle between direction of motion and x-axis (anticlockwise).
Default Value : 0
Value Suggestions : Angle ¾0, 45, 90, 180, 270
HALCON/C Reference Manual / 2000-11-15

3.14. WIENER-FILTER 165
º Type (input control) .................................................................integer long
PSF protoype resp. type of motion.
Default Value : 3
Value List : Type ¾1, 2, 3, 4, 5
Result
gen psf motion returns H MSG TRUE if all parameters are correct.
Parallelization Information
gen psf motion is reentrant and processed without parallelization.
Possible Predecessor Functions
gen psf motion, simulate defocus, gen psf defocus
Possible Successor Functions
simulate motion, wiener filter, wiener filter ni
See Also
simulate motion, simulate defocus, gen psf defocus, wiener filter, wiener filter ni
Bibliography
Anil K. Jain:Fundamentals of Digital Image Processing, Prentice-Hall International Inc., Englewood Cliffs, New
Jersey, 1989
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995.
Kha-Chye Tan, Hock Lim, B. T. G. Tan:”‘Restoration of Real-World Motion-Blurred Images”’;S. 291-299 in:
CVGIP Graphical Models and Image Processing, Vol. 53, No. 3, May 1991
Module
Wiener filter
simulate defocus ( Hobject Image, Hobject *DefocusedImage,
double Blurring )
Simulate an uniform out-of-focus blurring of an image.
simulate defocus simulates out-of-focus blurring of an image. All parts of the image are blurred uniformly.
Blurring specifies the extent of blurring by defining the ”‘blur radius”’ (out-of-focus blurring maps each image
pixel on a small circle with a radius of Blurring - specified in ”‘number of pixels”’). If specified less than null,
the absolute value of Blurring is used. Simulation of blurring is done by a convolution of the image with a
blurring specific impulse response. The convolution is realized by multiplication in the Fourier domain.
Attention
As the simulation of the blurring is realized based on the Fourier transform, image height and width must be a
power of 2, e.g. 128, 128, 256, 512,...
Parameter
º Image (input object) .........................................................image Hobject :any
Image to blur.
º DefocusedImage (output object) .........................................image Hobject * : real
Blurred image.
º Blurring (input control) .............................................................real double
Degree of blurring.
Default Value : 5.0
Value Suggestions : Blurring ¾1.0, 5.0, 10.0, 15.0, 18.0
Result
simulate defocus returns H MSG TRUE if all parameters are correct.
simulate defocus returns with an error message.
Parallelization Information
simulate defocus is reentrant and processed without parallelization.
Possible Predecessor Functions
gen psf defocus, simulate motion, gen psf motion
If the input is empty
HALCON 6.0

166 CHAPTER 3. FILTER
Possible Successor Functions
wiener filter, wiener filter ni
See Also
gen psf defocus, simulate motion, gen psf motion
Bibliography
Reginald L. Lagendijk, Jan Biemond: Iterative Identification and Restoration of Images, Kluwer Academic Publishers
Boston/Dordrecht/London, 1991
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995.
Module
Wiener filter
simulate motion ( Hobject Image, Hobject *MovedImage, double Blurring,
long Angle, long Type )
Simulation of (linearly) motion blur.
simulate motion simulates blurring caused by a relative motion between the object and the camera during
exposure. The simulated motion moves along an even. Angle fixes its direction by specifying the angle between
the motion direction and the x-axis (anticlockwise, measured in degrees). Simulation is done by a convolution of
the image with a blurring specific impulse response. The convolution is realized by multiplication in the Fourier
domain. simulate motion offers five protoypes of impulse responses conforming to different acceleration
behaviours. Type allows to choose one of the following PSF prototypes:
1. reverse ramp (crude model for acceleration)
2. reverse trapezoid (crude model for high acceleration)
3. square pulse (exact model for constant velocity), this is default
4. forward trapezoid (crude model for deceleration)
5. forward ramp (crude model for high deceleration)
The simulated blurring affects all part of the image uniformly. Blurring controls the extent of blurring. It
specifies the number of pixels (lying one after another) that are affetcetd by the blurring. This number is determined
by velocity of the motion and exposure time. If Blurring is a negative number, an adequate blurring in reverse
direction is simulated. If Angle is a negative number, it is interpreted clockwise. If Angle exceeds 360 or falls
below -360, it is transformed modulo(360) in an adequate number between ¼¿¼℄ resp. ¿¼¼℄.
Attention
As the simulation of the blurring is realized based on the Fourier transform, image height and width must be a
power of 2, e.g. 128, 128, 256, 512,...
Parameter
º Image (input object) .........................................................image Hobject :any
imagetobeblurred.
º MovedImage (output object) ...............................................image Hobject * : real
motion blurred image.
º Blurring (input control) .............................................................real double
extent of blurring.
Default Value : 20.0
Value Suggestions : Blurring ¾5.0, 10.0, 20.0, 30.0, 40.0
º Angle (input control) ................................................................integer long
Angle between direction of motion and x-axis (anticlockwise).
Default Value : 0
Value Suggestions : Angle ¾0, 45, 90, 180, 270
º Type (input control) .................................................................integer long
impulse response of motion blur.
Default Value : 3
Value List : Type ¾1, 2, 3, 4, 5
HALCON/C Reference Manual / 2000-11-15

3.14. WIENER-FILTER 167
Result
simulate motion returns H MSG TRUE if all parameters are correct. If the input is empty
simulate motion returns with an error message.
Parallelization Information
simulate motion is reentrant and processed without parallelization.
Possible Predecessor Functions
gen psf motion, gen psf motion
Possible Successor Functions
simulate defocus, wiener filter, wiener filter ni
See Also
gen psf motion, simulate defocus, gen psf defocus
Bibliography
Anil K. Jain:Fundamentals of Digital Image Processing, Prentice-Hall International Inc., Englewood Cliffs, New
Jersey, 1989
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995.
Kha-Chye Tan, Hock Lim, B. T. G. Tan:”‘Restoration of Real-World Motion-Blurred Images”’;S. 291-299 in:
CVGIP Graphical Models and Image Processing, Vol. 53, No. 3, May 1991
Module
Wiener filter
wiener filter ( Hobject Image, Hobject Psf, Hobject FilteredImage,
Hobject *RestoredImage )
Image restoration by Wiener filtering.
wiener filter produces an estimate of the original image (= image without noise and blurring) by minimizing
the mean square error between estimated and original image. wiener filter can be used to restore images
corrupted by noise and/or blurring (e.g. motion blur, atmospheric turbulence or out-of-focus blur). Method and
realisation of this restoration technique bases on the following model: The corrupted image is interpreted as the
output of a (disturbed) linear system. Functionality of a linear system is determined by its specific impuls response.
So the convolution of original image and impulse response results in the corrupted image. The specific impulse
response describes image acquisition and the occured degradations. In the presence of additive noise an additional
noise term must be considered. So the corrupted image can be modeled as the result of
ÓÒÚÓÐÙØÓÒ´ÑÔÙÐ× Ö×ÔÓÒ× ÓÖÒРѵ℄ · ÒÓ× ØÖÑ
The noise term encloses two different terms describing image-dependent and image-independent noise. According
to this model, two terms must be known for restoration by Wiener filtering:
1. degradation-specific impulse response
2. noise term
So wiener filter needs a smoothed version of the input image to estimate the power spectral density of
noise and original image. One can use one of the smoothing HALCON-filters (e.g. eliminate min max)to
get this version. wiener filter needs further the impulse response that describes the specific degradation.
This impulse response (represented in spatial domain) must fit into an image of HALCON image type ’real’.
There exist two HALCON-operators for generation of an impulse response for motion blur and out-of-focus (see
gen psf motion, gen psf defocus). The representation of the impulse response presumes the origin in the
upper left corner. This results in the following disposition of an ÆÜÅ sized image:
¯ first rectangle (”‘upper left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý ¼´Å¾µ ½µ
- conforms to the fourth quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ¼Æ¾ and Ý ¼ ž
¯ second rectangle (”‘upper right”’): (image coordinates Ü Æ¾Æ ½, Ý ¼´Å¾µ ½µ
- conforms to the third quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ and Ý ½ ž
HALCON 6.0

168 CHAPTER 3. FILTER
¯ third rectangle (”‘lower left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý Å¾Å ½µ
- conforms to the first quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ½Æ¾ and Ý Å¾¼
¯ fourth rectangle (”‘lower right”’): (image coordinates Ü Æ¾Æ ½, Ý Å¾Å ½µ
- conforms to the second quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ und Ý Å¾½
As the Wiener filter is realized using the Fourier transform, only images with height and width fitting a power of 2
can be processed. wiener filter works as follows:
¯ estimation of the power spectrum density of the original image by using the smoothed version of the corrupted
image,
¯ estimation of the power spectrum density of each pixel by subtracting smoothed version from unsmoothed
version,
¯ building the Wiener filter kernel with the quotient of power spectrum densities of noise and original image
and with the impulse response,
¯ processing the convolution of image and Wiener filter frequency response.
The result image has got image type ’real’.
Attention
Psf must be of image type ’real’ and conform to Image and FilteredImage in image width and height.
Parameter
º Image (input object) .........................................................image Hobject :any
Corrupted image.
º Psf (input object) ............................................................image Hobject : real
impulse response (PSF) of degradation (in spatial domain).
º FilteredImage (input object) ..............................................image Hobject :any
Smoothed version of corrupted image.
º RestoredImage (output object) ...........................................image Hobject * : real
Restored image.
Example
/* Restoration of a noisy image (size=256x256), that was blurred by motion*/
Hobject object;
Hobject restored;
Hobject psf;
Hobject noisefiltered;
/* 1. Generate a Point-Spread-Function for a motion-blur with */
/* parameter a=10 and direction along the x-axis */
gen_psf(&psf,256,256,10,0,3);
/* 2. Noisefiltering of the image */
median_image(object,&noisefiltered,"circle",2,0);
/* 3. Wiener-filtering */
wiener_filter(object,psf,noisefiltered,&restored);
Result
wiener filter returns H MSG TRUE if all parameters are correct. If the input is empty wiener filter
returns with an error message.
Parallelization Information
wiener filter is reentrant and processed without parallelization.
Possible Predecessor Functions
gen psf motion, simulate motion, simulate defocus, gen psf defocus
wiener filter ni
Alternatives
See Also
simulate motion, gen psf motion, simulate defocus, gen psf defocus
HALCON/C Reference Manual / 2000-11-15

3.14. WIENER-FILTER 169
Bibliography
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995
Azriel Rosenfeld, Avinash C. Kak: Digital Picture Processing, Computer Science and Aplied Mathematics, Academic
Press New York/San Francisco/London 1982
Module
Wiener filter
wiener filter ni ( Hobject Image, Hobject Psf, Hobject NoiseRegion,
Hobject *RestoredImage, long MaskWidth, long MaskHeight )
Image restoration by Wiener filtering.
wiener filter ni (ni = noise-estimation integrated) produces an estimate of the original image (= image
without noise and blurring) by minimizing the mean square error between estimated and original image.
wiener filter can be used to restore images corrupted by noise and/or blurring (e.g. motion blur, atmospheric
turbulence or out-of-focus blur). Method and realisation of this restoration technique bases on the following model:
The corrupted image is interpreted as the output of a (disturbed) linear system. Functionality of a linear system is
determined by its specific impuls response. So the convolution of original image and impulse response results in
the corrupted image. The specific impulse response describes image acquisition and the occured degradations. In
the presence of additive noise an additional noise term must be considered. So the corrupted image can be modeled
as the result of
ÓÒÚÓÐÙØÓÒ´ÑÔÙÐ× Ö×ÔÓÒ× ÓÖÒРѵ℄ · ÒÓ× ØÖÑ
The noise term encloses two different terms describing image-dependent and image-independent noise. According
to this model, two terms must be known for restoration by Wiener filtering:
1. degradation-specific impulse response
2. noise term
wiener filter ni estimates the noise term as follows: The user defines a region that is suitable for noise
estimation within the image (homogeneous as possible, as edges or textures aggravate noise estimation). After
smoothing within this region by an (unweighted) median filter and subtracting smoothed version from unsmoothed,
the average noise amplitude of the region is processed within wiener filter ni. This amplitude together with
the average gray value within the region allows estimating the quotient of the power spectral densities of noise and
original image (in contrast to wiener filter wiener filter ni assumes a rather constant quotient within
the whole image). The user can define width and height of the rectangular (median-)filter mask to influence the
noise estimation (MaskWidth, MaskHeight). wiener filter ni needs further the impulse response that
describes the specific degradation. This impulse response (represented in spatial domain) must fit into an image
of HALCON image type ’real’. There exist two HALCON-operators for generation of an impulse response for
motion blur and out-of-focus (see gen psf motion, gen psf defocus). The representation of the impulse
response presumes the origin in the upper left corner. This results in the following disposition of an ÆÜÅ sized
image:
¯ first rectangle (”‘upper left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý ¼´Å¾µ ½µ
- conforms to the fourth quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ¼Æ¾ and Ý ¼ ž
¯ second rectangle (”‘upper right”’): (image coordinates Ü Æ¾Æ ½, Ý ¼´Å¾µ ½µ
- conforms to the third quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ and Ý ½ ž
¯ third rectangle (”‘lower left”’): (image coordinates Ü ¼´Æ¾µ ½, Ý Å¾Å ½µ
- conforms to the first quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü ½Æ¾ and Ý Å¾¼
¯ fourth rectangle (”‘lower right”’): (image coordinates Ü Æ¾Æ ½, Ý Å¾Å ½µ
- conforms to the second quadrant of the Cartesian coordinate system, encloses values of the impulse response
at position Ü Æ¾ ½ und Ý Å¾½
HALCON 6.0

170 CHAPTER 3. FILTER
As the Wiener filter is realized using the Fourier transform, only images with height and width fitting a power of 2
can be processed. wiener filter works as follows:
¯ estimating the quotient of the power spectrum densities of noise and original image,
¯ building the Wiener filter kernel with the quotient of power spectrum densities of noise and original image
and with the impulse response,
¯ processing the convolution of image and Wiener filter frequency response.
The result image has got image type ’real’.
Attention
Psf must be of image type ’real’ and conform to Image in width and height. The Region used for noise estimation
must lie completely within the image. If MaskWidth or MaskHeight is an even number, it is replaced by the
next higher odd number (this allows the unique extraction of the center of the filter mask). Width/height of the
mask may not exceed the image width/height or be less than null.
Parameter
º Image (input object) .........................................................image Hobject :any
Corrupted image.
º Psf (input object) ............................................................image Hobject : real
impulse response (PSF) of degradation (in spatial domain).
º NoiseRegion (input object) ......................................................region Hobject
Region for noise estimation.
º RestoredImage (output object) ...........................................image Hobject * : real
Restored image.
º MaskWidth (input control) ...........................................................integer long
Width of filter mask.
Default Value : 3
Value Suggestions : MaskWidth ¾3, 5, 7, 9
Typical Range of Values : 0 MaskWidth width(Image)
º MaskHeight (input control) .........................................................integer long
Height of filter mask.
Default Value : 3
Value Suggestions : MaskHeight ¾3, 5, 7, 9
Typical Range of Values : 0 MaskHeight height(Image)
Example
/* Restoration of a noisy image (size=256x256), that was blurred by motion*/
Hobject object;
Hobject restored;
Hobject psf;
Hobject noise_region;
/* 1. Generate a Point-Spread-Function for a motion-blur with */
/* parameter a=10 and direction of the x-axis */
gen_psf(&psf,256,256,10,0,3);
/* 2. Segmentation of a region for the noise-estimation */
open_window(0,0,256,256,0,"visible",&WindowHandle);
disp_image(object,WindowHandle);
draw_region(&noise_region,draw_region);
/* 3. Wiener-filtering */
wiener_filter_ni(object,psf,noise_region,&restored,3,3);
Result
wiener filter ni returns H MSG TRUE if all parameters are correct. If the input is empty
wiener filter ni returns with an error message.
Parallelization Information
wiener filter ni is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

3.14. WIENER-FILTER 171
Possible Predecessor Functions
gen psf motion, simulate motion, simulate defocus, gen psf defocus
wiener filter
Alternatives
See Also
simulate motion, gen psf motion, simulate defocus, gen psf defocus
Bibliography
M. L”uckenhaus:”‘Grundlagen des Wiener-Filters und seine Anwendung in der Bildanalyse”’; Diplomarbeit;
Technische Universit”at M”unchen, Institut f”ur Informatik; Lehrstuhl Prof. Radig; 1995
Azriel Rosenfeld, Avinash C. Kak: Digital Picture Processing, Computer Science and Aplied Mathematics, Academic
Press New York/San Francisco/London 1982
Module
Wiener filter
HALCON 6.0

172 CHAPTER 3. FILTER
HALCON/C Reference Manual / 2000-11-15

Chapter 4
Graphics
4.1 Drawing
drag region1 ( Hobject SourceRegion, Hobject *DestinationRegion,
long WindowHandle )
Interactive moving of a region.
drag region1 is used to move a region on the display by mouse. Calling drag region1 turns the region
visible as soon as the left mouse button is pressed. Therefore the region’s edges are displayed only. As representation
mode the mode ’not’ (see set draw) is used during procedure’s permanence. During the movement
the cursor resides in the region’s barycenter. If you move the mouse with pressed left mouse button, the depicted
region follows - delayed - this movement. If you press the right mouse button you terminate drag region1.
The depicted region disappears from the display. Output is a region which corresponds to the last position on the
display. You may pass even several regions at once. Procedure affine trans image moves the gray values.
Attention
Gray values of regions are not moved. With moving the input region it is not sure whether the gray values of the
output regions are filled reasonable. This may occur if the gray values of the input regions do not comprise the
whole image.
Parameter
º SourceRegion (input object) ...............................................region-array Hobject
Regions to move.
º DestinationRegion (output object) ......................................region-array Hobject *
Moved Regions.
º WindowHandle (input control) ......................................................window long
Window id.
Example
draw_region(&Obj,WindowHandle) ;
drag_region1(Obj,&New,WindowHandle) ;
disp_region(New,WindowHandle) ;
position(Obj,_,Row1,Column1,_,_,_,_) ;
position(New,_,Row2,Column2,_,_,_,_) ;
disp_arrow(WindowHandle,Row1,Column1,Row2,Column2,1.0) ;
fwrite_string("Transformation: ") ;
fwrite_string(Row2-Row1) ;
fwrite_string(", ") ;
fwrite_string(Column2-Column1) ;
fnew_line() ;
Result
drag region1 returns H MSG TRUE, if a region is entered, the window is valid and the needed drawing mode
173

174 CHAPTER 4. GRAPHICS
(see set insert) is available. If necessary, an exception handling is raised. You may determine the behavior
after an empty input with set system(’no object result’,).
Parallelization Information
drag region1 is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
get mposition, move region
Alternatives
See Also
set insert, set draw, affine trans image
System
Module
drag region2 ( Hobject SourceRegion, Hobject *DestinationRegion,
long WindowHandle, long Row, long Column )
Interactive movement of a region with fixpoint specification.
You use drag region2 to move a region on the display by mouse. It corresponds to the procedure
drag region1 with the difference, that the position of the mouse cursor can be determined.
Attention
Gray values of the regions are not moved. With moving the input region it is not sure whether the gray values of
the output regions are filled reasonable. This may occur if the gray values of the input regions do not comprise the
whole image.
Parameter
º SourceRegion (input object) ...............................................region-array Hobject
Regions to move.
º DestinationRegion (output object) ......................................region-array Hobject *
Moved regions.
º WindowHandle (input control) ......................................................window long
Window id.
º Row (input control) ...................................................................point.y long
Row index of the reference point.
Default Value : 100
Value Suggestions : Row ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Row 1024
º Column (input control) ...............................................................point.x long
Column index of the reference point.
Default Value : 100
Value Suggestions : Column ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Column 1024
Result
drag region2 returns H MSG TRUE, if a region is entered, the window is valid and the needed drawing mode
(see set insert) is available. If necessary, an exception handling is raised. You may determine the behavior
after an empty input with set system(’no object result’,).
Parallelization Information
drag region2 is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert,
affine trans image
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 175
Alternatives
get mposition, move region, drag region1, drag region3
See Also
set insert, set draw, affine trans image
System
Module
drag region3 ( Hobject SourceRegion, Hobject MaskRegion,
Hobject *DestinationRegion, long WindowHandle, long Row, long Column )
Interactive movement of a region with restriction of positions.
You use drag region3 to move a region on the display by mouse. It corresponds to the procedure
drag region2 with the enhancement, that all points are specified which can be entered by mouse. If you
move the mouse outside of this area (MaskRegion), the region on the point with the smallest distance inside
MaskRegion will be displayed.
Attention
The region’s gray values are not moved. With moving the input region it is not sure whether the gray values of
the output regions are filled reasonable. This may occur if the gray values of the input regions do not comprise the
whole image.
Parameter
º SourceRegion (input object) ...............................................region-array Hobject
Regions to move.
º MaskRegion (input object) ..................................................region-array Hobject
Points on which it is allowed for a region to move.
º DestinationRegion (output object) ......................................region-array Hobject *
Moved regions.
º WindowHandle (input control) ......................................................window long
Window id.
º Row (input control) ...................................................................point.y long
Row index of the reference point.
Default Value : 100
Value Suggestions : Row ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Row 1024
º Column (input control) ...............................................................point.x long
Column index of the reference point.
Default Value : 100
Value Suggestions : Column ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Column 1024
Result
drag region3 returns H MSG TRUE, if a region is entered, if the window is valid and the needed drawing
mode (see set insert) is available. If necessary, an exception handling is raised. You may determine the
behavior after an empty input with set system(’no object result’,).
Parallelization Information
drag region3 is local and processed completely exclusively without parallelization.
open window, get mposition
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert,
affine trans image
Alternatives
get mposition, move region, drag region1, drag region2
See Also
set insert, set draw, affine trans image
HALCON 6.0

176 CHAPTER 4. GRAPHICS
System
Module
draw circle ( long WindowHandle, double *Row, double *Column,
double *Radius )
Interactive drawing of a circle.
draw circle produces the parameter for a circle created interactive by the user in the window.
To create a circle you have to press the mouse button at the location which is used as the center of that circle. While
keeping the mouse button pressed, the Radius’s length can be modified through moving the mouse. After another
mouse click in the created circle center you can move it. A clicking close to the circular arc you can modify the
Radius of the circle. Pressing the right mousebutton terminates the procedure. After terminating the procedure
the circle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row (output control) .......................................................circle.center.y double *
Barycenter’s row index.
º Column (output control) ...................................................circle.center.x double *
Barycenter’s column index.
º Radius (output control) .....................................................circle.radius double *
Circle’s radius.
Example
read_image(&Image,"affe") ;
draw_circle(WindowHandle,&Row,&Column,&Radius) ;
gen_circle(&Circle,Row,Column,Radius) ;
reduce_domain(Image,Circle,&GrayCircle) ;
disp_image(GrayCircle,WindowHandle) ;
Result
draw circle returns H MSG TRUE if the window is valid and the needed drawing mode (see set insert)
is available. If necessary, an exception handling is raised.
Parallelization Information
draw circle is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw circle mod, draw ellipse, draw region
See Also
gen circle, draw rectangle1, draw rectangle2, draw polygon, set insert
System
Module
draw circle mod ( long WindowHandle, double RowIn, double ColumnIn,
double RadiusIn, double *Row, double *Column, double *Radius )
Interactive drawing of a circle.
draw circle mod produces the parameter for a circle created interactive by the user in the window.
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 177
To create a circle are expected the coordinates RowIn and ColumnIn of the center of a circle with radius
RadiusIn. After another mouse click in the created circle center you can move it. A clicking close to the
circular arc you can modify the Radius of the circle. Pressing the right mousebutton terminates the procedure.
After terminating the procedure the circle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º RowIn (input control) .......................................................circle.center.y double
Row index of the center.
º ColumnIn (input control) ...................................................circle.center.x double
Column index of the center.
º RadiusIn (input control) ....................................................circle.radius1 double
Radius of the circle.
º Row (output control) .......................................................circle.center.y double *
Barycenter’s row index.
º Column (output control) ...................................................circle.center.x double *
Barycenter’s column index.
º Radius (output control) .....................................................circle.radius double *
Circle’s radius.
Example
read_image(&Image,"affe") ;
draw_circle_mod(WindowHandle,20,20,15,&Row,&Column,&Radius) ;
gen_circle(&Circle,Row,Column,Radius) ;
reduce_domain(Image,Circle,&GrayCircle) ;
disp_image(GrayCircle,WindowHandle) ;
Result
draw circle mod returns H MSG TRUE if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
Parallelization Information
draw circle mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw circle, draw ellipse, draw region
See Also
gen circle, draw rectangle1, draw rectangle2, draw polygon, set insert
System
Module
draw ellipse ( long WindowHandle, double *Row, double *Column,
double *Phi, double *Radius1, double *Radius2 )
Interactive drawing of an ellipse.
draw ellipse returns the parameter for any orientated ellipse, which has been created interactively by the user
in the window.
The created ellipse is described by its center, its two half axes and the angle between the first half axis and the
horizontal coordinate axis.
To create an ellipse you have to determine the center of the ellipse with the left mouse button. Keeping the button
pressed determines the length (Radius1) and the orientation (Phi) of the first half axis. In doing so a temporary
HALCON 6.0

178 CHAPTER 4. GRAPHICS
default length for the second half axis is assumed, which may be modified afterwards on demand. After another
mouse click in the center of the created ellipse you can move it. A mouse click close to a vertex “grips” it to
modify the length of the appropriate half axis. You may modify the orientation only, if a vertex of the first half axis
is gripped.
Pressing the right mouse button terminates the procedure. After terminating the procedure the ellipse is not visible
in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y double *
Row index of the center.
º Column (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x double *
Column index of the center.
º Phi (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad double *
Orientation of the first half axis in radians.
º Radius1 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1 double *
First half axis.
º Radius2 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2 double *
Second half axis.
Example
read_image(&Image,"affe") ;
draw_ellipse(WindowHandle,&Row,&Column,&Phi,&Radius1,&Radius2) ;
gen_ellipse(&Ellipse,Row,Column,Phi,Radius1,Radius2) ;
reduce_domain(Image,Ellipse,&GrayEllipse) ;
sobel_amp(GrayEllipse,&Sobel,"sum_abs",3) ;
disp_image(Sobel,WindowHandle) ;
Result
draw ellipse returns H MSG TRUE, if the window is valid and the needed drawing mode (see set insert)
is available. If necessary, an exception handling is raised.
Parallelization Information
draw ellipse is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw ellipse mod, draw circle, draw region
See Also
gen ellipse, draw rectangle1, draw rectangle2, draw polygon, set insert
System
Module
draw ellipse mod ( long WindowHandle, double RowIn, double ColumnIn,
double PhiIn, double Radius1In, double Radius2In, double *Row,
double *Column, double *Phi, double *Radius1, double *Radius2 )
Interactive drawing of an ellipse.
draw ellipse mod returns the parameter for any orientated ellipse, which has been created interactively by the
user in the window.
The created ellipse is described by its center, its two half axes and the angle between the first half axis and the
horizontal coordinate axis.
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 179
To create an ellipse are expected the parameters RowIn, ColumnIn,PhiIn,Radius1In,Radius2In. Keeping
the button pressed determines the length (Radius1) and the orientation (Phi) of the first half axis. In doing
so a temporary default length for the second half axis is assumed, which may be modified afterwards on demand.
After another mouse click in the center of the created ellipse you can move it. A mouse click close to a vertex
“grips” it to modify the length of the appropriate half axis. You may modify the orientation only, if a vertex of the
first half axis is gripped.
Pressing the right mouse button terminates the procedure. After terminating the procedure the ellipse is not visible
in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º RowIn (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.center.y double
Row index of the barycenter.
º ColumnIn (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x double
Column index of the barycenter.
º PhiIn (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad double
Orientation of the bigger half axis in radians.
º Radius1In (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.radius1 double
Bigger half axis.
º Radius2In (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.radius1 double
Smallerhalfaxis.
º Row (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y double *
Row index of the center.
º Column (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x double *
Column index of the center.
º Phi (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad double *
Orientation of the first half axis in radians.
º Radius1 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1 double *
First half axis.
º Radius2 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2 double *
Second half axis.
Example
read_image(&Image,"affe") ;
draw_ellipse_mod(WindowHandle,RowIn,ColumnIn,PhiIn,Radius1In,Radius2In,&Row,&Column,&Phi
gen_ellipse(&Ellipse,Row,Column,Phi,Radius1,Radius2) ;
reduce_domain(Image,Ellipse,&GrayEllipse) ;
sobel_amp(GrayEllipse,&Sobel,"sum_abs",3) ;
disp_image(Sobel,WindowHandle) ;
Result
draw ellipse mod returns H MSG TRUE, if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
Parallelization Information
draw ellipse mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw ellipse, draw circle, draw region
See Also
gen ellipse, draw rectangle1, draw rectangle2, draw polygon, set insert
System
Module
HALCON 6.0

180 CHAPTER 4. GRAPHICS
draw line ( long WindowHandle, double *Row1, double *Column1,
double *Row2, double *Column2 )
Draw a line.
draw line returns the parameter for a line, which has been created interactively by the user in the window.
To create a line you have to press the left mouse button determining a start point of the line. While keeping the
button pressed you may “drag” the line in any direction. After another mouse click in the middle of the created
line you can move it. If you click on one end point of the created line, you may move this point. Pressing the right
mousebutton terminates the procedure.
After terminating the procedure the line is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1 (output control) ........................................................line.begin.y double *
Row index of the first point of the line.
º Column1 (output control) ....................................................line.begin.x double *
Column index of the first point of the line.
º Row2 (output control) ..........................................................line.end.y double *
Row index of the second point of the line.
º Column2 (output control) ......................................................line.end.x double *
Column index of the second point of the line.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_line(WindowHandle,&Row1,&Column1,&Row2,&Column2) ;
set_part(WindowHandle,Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fwrite_string(Row2) ;
fwrite_string(",") ;
fwrite_string(Column2) ;
fwrite_string(")") ;
fnew_line(:::) ;
Result
draw line returns H MSG TRUE, if the window is valid and the needed drawing mode (see set insert) is
available. If necessary, an exception handling is raised.
Parallelization Information
draw line is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, (T )disp line, set colored, set line width, set draw, set insert
See Also
draw line mod, gen rectangle1, draw circle, draw ellipse, set insert
System
Module
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 181
draw line mod ( long WindowHandle, double Row1In, double Column1In,
double Row2In, double Column2In, double *Row1, double *Column1,
double *Row2, double *Column2 )
Draw a line.
draw line mod returns the parameter for a line, which has been created interactively by the user in the window.
To create a line are expected the coordinates of the start point Row1In, Column1In and of the end point
Row2In,Column2In. If you click on one end point of the created line, you may move this point. After another
mouse click in the middle of the created line you can move it.
Pressing the right mousebutton terminates the procedure.
After terminating the procedure the line is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1In (input control) ........................................................line.begin.y double
Row index of the first point of the line.
º Column1In (input control) ....................................................line.begin.x double
Column index of the first point of the line.
º Row2In (input control) ..........................................................line.end.y double
Row index of the second point of the line.
º Column2In (input control) ......................................................line.end.x double
Column index of the second point of the line.
º Row1 (output control) ........................................................line.begin.y double *
Row index of the first point of the line.
º Column1 (output control) ....................................................line.begin.x double *
Column index of the first point of the line.
º Row2 (output control) ..........................................................line.end.y double *
Row index of the second point of the line.
º Column2 (output control) ......................................................line.end.x double *
Column index of the second point of the line.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_line_mod(WindowHandle,10,20,55,124,&Row1,&Column1,&Row2,&Column2) ;
set_part(WindowHandle,Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fwrite_string(Row2) ;
fwrite_string(",") ;
fwrite_string(Column2) ;
fwrite_string(")") ;
fnew_line(:::) ;
Result
draw line mod returns H MSG TRUE, if the window is valid and the needed drawing mode is available. If
necessary, an exception handling is raised.
HALCON 6.0

182 CHAPTER 4. GRAPHICS
Parallelization Information
draw line mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, (T )disp line, set colored, set line width, set draw, set insert
draw line, draw ellipse, draw region
Alternatives
See Also
gen circle, draw rectangle1, draw rectangle2
System
Module
draw point ( long WindowHandle, double *Row, double *Column )
Draw a point.
draw point returns the parameter for a point, which has been created interactively by the user in the window.
To create a point you have to press the left mouse button. While keeping the button pressed you may “drag” the
point in any direction. Pressing the right mousebutton terminates the procedure.
After terminating the procedure the point is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row (output control) ..............................................................point.y double *
Row index of the point.
º Column (output control) ..........................................................point.x double *
Column index of the point.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_point(WindowHandle,&Row1,&Column1) ;
disp_line(WindowHandle,Row1-2,Column1,Row1+2,Column1) ;
disp_line(WindowHandle,Row1,Column1-2,Row1,Column1+2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fnew_line(:::) ;
Result
draw point returns H MSG TRUE, if the window is valid and the needed drawing mode is available. If necessary,
an exception handling is raised.
Parallelization Information
draw point is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 183
Possible Successor Functions
reduce domain, (T )disp line, set colored, set line width, set draw, set insert
See Also
draw point mod, draw circle, draw ellipse, set insert
System
Module
draw point mod ( long WindowHandle, double RowIn, double ColumnIn,
double *Row, double *Column )
Draw a point.
draw point mod returns the parameter for a point, which has been created interactively by the user in the
window.
To create a point are expected the coordinates RowIn and ColumnIn. While keeping the button pressed you may
“drag” the point in any direction. Pressing the right mousebutton terminates the procedure.
After terminating the procedure the point is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º RowIn (input control) ..............................................................point.y double
Row index of the point.
º ColumnIn (input control) ..........................................................point.x double
Column index of the point.
º Row (output control) ..............................................................point.y double *
Row index of the point.
º Column (output control) ..........................................................point.x double *
Column index of the point.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_point_mod(WindowHandle,&Row1,&Column1) ;
disp_line(WindowHandle,Row1-2,Column1,Row1+2,Column1) ;
disp_line(WindowHandle,Row1,Column1-2,Row1,Column1+2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fnew_line(:::) ;
Result
draw point mod returns H MSG TRUE, if the window is valid and the needed drawing mode is available. If
necessary, an exception handling is raised.
Parallelization Information
draw point mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
HALCON 6.0

184 CHAPTER 4. GRAPHICS
Possible Successor Functions
reduce domain, (T )disp line, set colored, set line width, set draw, set insert
See Also
draw point, draw circle, draw ellipse, set insert
System
Module
draw polygon ( Hobject *PolygonRegion, long WindowHandle )
Interactive drawing of a polygon row.
draw polygon produces an image. The region of that image spans exactly the imagepoints entered interactively
by mouse clicks (gray values remain undefined).
Painting in the output window happens while pressing the left mouse button. Releasing the left mouse button and
repressing it at another position effects drawing a line between these two points. Pressing the right mouse button
terminates the input. Painting uses that color which has been set by (T )set color, T set rgb,etc..
To put gray values on the created PolygonRegion for further processing, you may use the procedure
reduce domain.
Attention
The painted contour is not closed automatically, in particular it is not “filled up” either.
Output object’s gray values are not defined.
Parameter
º PolygonRegion (output object) .................................................region Hobject *
Region, which encompasses all painted points.
º WindowHandle (input control) ......................................................window long
Window id.
Example
draw_polygon(&Polygon,WindowHandle) ;
convex(Polygon,&Filled) ;
disp_region(Filled,WindowHandle) ;
Result
If the window is valid, draw polygon returns H MSG TRUE. If necessary, an exception handling is raised.
Parallelization Information
draw polygon is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw
Alternatives
draw region, draw circle, draw rectangle1, draw rectangle2, boundary
reduce domain, fill up, (T )set color
System
See Also
Module
draw rectangle1 ( long WindowHandle, double *Row1, double *Column1,
double *Row2, double *Column2 )
Draw a rectangle parallel to the coordinate axis.
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 185
draw rectangle1 returns the parameter for a rectangle parallel to the coordinate axes, which has been created
interactively by the user in the window.
To create a rectangle you have to press the left mouse button determining a corner of the rectangle. While keeping
the button pressed you may “drag” the rectangle in any direction. After another mouse click in the middle of the
created rectangle you can move it. A click close to one side “grips” it to modify the rectangle’s dimension in
perpendicular direction to this side. If you click on one corner of the created rectangle, you may move this corner.
Pressing the right mousebutton terminates the procedure.
After terminating the procedure the rectangle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1 (output control) ...................................................rectangle.origin.y double *
Row index of the left upper corner.
º Column1 (output control) ...............................................rectangle.origin.x double *
Column index of the left upper corner.
º Row2 (output control) ..................................................rectangle.corner.y double *
Row index of the right lower corner.
º Column2 (output control) ..............................................rectangle.corner.x double *
Column index of the right lower corner.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_rectangle1(WindowHandle,&Row1,&Column1,&Row2,&Column2) ;
set_part(WindowHandle,Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fwrite_string(Row2) ;
fwrite_string(",") ;
fwrite_string(Column2) ;
fwrite_string(")") ;
fnew_line(:::) ;
Result
draw rectangle1 returns H MSG TRUE, if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
Parallelization Information
draw rectangle1 is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw rectangle1 mod, draw rectangle2, draw region
See Also
gen rectangle1, draw circle, draw ellipse, set insert
System
Module
HALCON 6.0

186 CHAPTER 4. GRAPHICS
draw rectangle1 mod ( long WindowHandle, double Row1In,
double Column1In, double Row2In, double Column2In, double *Row1,
double *Column1, double *Row2, double *Column2 )
Draw a rectangle parallel to the coordinate axis.
draw rectangle1 mod returns the parameter for a rectangle parallel to the coordinate axes, which has been
created interactively by the user in the window.
To create a rectangle are expected the parameters Row1In, Column1In,Row2In und Column2In. After a
mouse click in the middle of the created rectangle you can move it. A click close to one side “grips” it to modify
the rectangle’s dimension in perpendicular direction to this side. If you click on one corner of the created rectangle,
you may move this corner. Pressing the right mousebutton terminates the procedure.
After terminating the procedure the rectangle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1In (input control) ...................................................rectangle.origin.y double
Row index of the left upper corner.
º Column1In (input control) ...............................................rectangle.origin.x double
Column index of the left upper corner.
º Row2In (input control) ...................................................rectangle.corner.y double
Row index of the right lower corner.
º Column2In (input control) ..............................................rectangle.corner.x double
Column index of the right lower corner.
º Row1 (output control) ...................................................rectangle.origin.y double *
Row index of the left upper corner.
º Column1 (output control) ...............................................rectangle.origin.x double *
Column index of the left upper corner.
º Row2 (output control) ..................................................rectangle.corner.y double *
Row index of the right lower corner.
º Column2 (output control) ..............................................rectangle.corner.x double *
Column index of the right lower corner.
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Width-1,Height-1) ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_rectangle1_mod(WindowHandle,Row1In,Column1In,Row2In,Column2In,&Row1,&Column1,&Row2,
set_part(WindowHandle,Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
fwrite_string("Clipping = (") ;
fwrite_string(Row1) ;
fwrite_string(",") ;
fwrite_string(Column1) ;
fwrite_string("),(") ;
fwrite_string(Row2) ;
fwrite_string(",") ;
fwrite_string(Column2) ;
fwrite_string(")") ;
fnew_line(:::) ;
Result
draw rectangle1 mod returns H MSG TRUE, if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 187
Parallelization Information
draw rectangle1 mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw rectangle1, draw rectangle2, draw region
See Also
gen rectangle1, draw circle, draw ellipse, set insert
System
Module
draw rectangle2 ( long WindowHandle, double *Row, double *Column,
double *Phi, double *Length1, double *Length2 )
Interactive drawing of any orientated rectangle.
draw rectangle2 returns the parameter for any orientated rectangle, which has been created interactively by
the user in the window.
The created rectangle is described by its center, its two half axes and the angle between the first half axis and the
horizontal coordinate axis.
To create a rectangle you have to press the left mouse button for the center of the rectangle. While keeping the
button pressed you may dimension the length (Length1) and the orientation (Phi) of the first half axis. In doing
so a temporary default length for the second half axis is assumed, which may be modified afterwards on demand.
After another mouse click in the middle of the created rectangle, you can move it. A click close to one side “grips”
it to modify the rectangle’s dimension in perpendicular direction to this side. You only can modify the orientation,
if you grip a side perpendicular to the first half axis. Pressing the right mouse button terminates the procedure.
After terminating the procedure the rectangle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row (output control) ...................................................rectangle2.center.y double *
Row index of the barycenter.
º Column (output control) ...............................................rectangle2.center.x double *
Column index of the barycenter.
º Phi (output control) ..................................................rectangle2.angle.rad double *
Orientation of the bigger half axis in radians.
º Length1 (output control) ..............................................rectangle2.hwidth double *
Bigger half axis.
º Length2 (output control) ..............................................rectangle2.hheight double *
Smallerhalfaxis.
Result
draw rectangle2 returns H MSG TRUE, if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
Parallelization Information
draw rectangle2 is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
Alternatives
draw rectangle2 mod, draw rectangle1, draw region
HALCON 6.0

188 CHAPTER 4. GRAPHICS
See Also
gen rectangle2, draw circle, draw ellipse, set insert
System
Module
draw rectangle2 mod ( long WindowHandle, double RowIn, double ColumnIn,
double PhiIn, double Length1In, double Length2In, double *Row,
double *Column, double *Phi, double *Length1, double *Length2 )
Interactive drawing of any orientated rectangle.
draw rectangle2 mod returns the parameter for any orientated rectangle, which has been created interactively
by the user in the window.
The created rectangle is described by its center, its two half axes and the angle between the first half axis and the
horizontal coordinate axis.
To create a rectangle are expected the parameters RowIn, ColumnIn,PhiIn,Length1In,Length2In. A
click close to one side “grips” it to modify the rectangle’s dimension in perpendicular direction (Length2)tothis
side. You only can modify the orientation (Phi), if you grip a side perpendicular to the first half axis. After another
mouse click in the middle of the created rectangle, you can move it. Pressing the right mouse button terminates
the procedure.
After terminating the procedure the rectangle is not visible in the window any longer.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º RowIn (input control) ...................................................rectangle2.center.y double
Row index of the barycenter.
º ColumnIn (input control) ...............................................rectangle2.center.x double
Column index of the barycenter.
º PhiIn (input control) ..................................................rectangle2.angle.rad double
Orientation of the bigger half axis in radians.
º Length1In (input control) ..............................................rectangle2.hwidth double
Bigger half axis.
º Length2In (input control) ..............................................rectangle2.hheight double
Smallerhalfaxis.
º Row (output control) ...................................................rectangle2.center.y double *
Row index of the barycenter.
º Column (output control) ...............................................rectangle2.center.x double *
Column index of the barycenter.
º Phi (output control) ..................................................rectangle2.angle.rad double *
Orientation of the bigger half axis in radians.
º Length1 (output control) ..............................................rectangle2.hwidth double *
Bigger half axis.
º Length2 (output control) ..............................................rectangle2.hheight double *
Smallerhalfaxis.
Result
draw rectangle2 mod returns H MSG TRUE, if the window is valid and the needed drawing mode (see
set insert) is available. If necessary, an exception handling is raised.
Parallelization Information
draw rectangle2 mod is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw, set insert
HALCON/C Reference Manual / 2000-11-15

4.1. DRAWING 189
Alternatives
draw rectangle2, draw rectangle1, draw rectangle2, draw region
See Also
gen rectangle2, draw circle, draw ellipse, set insert
System
Module
draw region ( Hobject *Region, long WindowHandle )
Interactive drawing of a closed region.
draw region produces an image. The region of that image spans exactly the image region entered interactively
by mouse clicks (gray values remain undefined). Painting happens in the ouput window while keeping the left
mouse button pressed. The left mouse button even operates by clicking in the output window; through this a line
between the previous clicked points is drawn. Clicking the right mouse button terminates input and closes the
outline. Subsequently the image is “filled up”. Also it contains the whole image area enclosed by the mouse.
Painting uses that color which has been set by (T )set color, T set rgb,etc..
The output object’s gray values are not defined.
Attention
Parameter
º Region (output object) ..........................................................region Hobject *
Interactive created region.
º WindowHandle (input control) ......................................................window long
Window id.
Example
read_image(&Image,"fabrik") ;
disp_image(Image,WindowHandle) ;
draw_region(&Region,WindowHandle) ;
reduce_domain(Image,Region,&New) ;
regiongrowing(New,&Segmente,5,5,6,50) ;
set_colored(WindowHandle,12) ;
disp_region(Segmente,WindowHandle) ;
Result
If the window is valid, draw region returns H MSG TRUE. If necessary, an exception handling is raised.
Parallelization Information
draw region is local and processed completely exclusively without parallelization.
open window
Possible Predecessor Functions
Possible Successor Functions
reduce domain, disp region, set colored, set line width, set draw
Alternatives
draw circle, draw ellipse, draw rectangle1, draw rectangle2
See Also
draw polygon, reduce domain, fill up, (T )set color
System
Module
HALCON 6.0

190 CHAPTER 4. GRAPHICS
4.2 Gnuplot
gnuplot close ( long GnuplotFileID )
Close all open gnuplot files or terminate an active gnuplot sub-process.
gnuplot close closes all gnuplot files opened by gnuplot open file or terminates the gnuplot subprocess
created with gnuplot open pipe. In the latter case, all temporary files used to display images
and control values are deleted. This means that gnuplot close must be called after such a plot sequence.
GnuplotFileID is the identifier of the corresponding gnuplot output stream.
Parameter
º GnuplotFileID (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id long
Identifier for the gnuplot output stream.
Result
gnuplot close returns H MSG TRUE if GnuplotFileID is a valid gnuplot output stream. Otherwise, an
exception handling is raised.
Parallelization Information
gnuplot close is processed completely exclusively without parallelization.
Possible Predecessor Functions
gnuplot open pipe, gnuplot open file, gnuplot plot image
See Also
gnuplot open pipe, gnuplot open file, gnuplot plot image
System
Module
gnuplot open file ( const char *FileName, long *GnuplotFileID )
Open a gnuplot file for visualization of images and control values.
gnuplot open file allows the output of images and control values in a format which can be later
processed by gnuplot. The parameter FileName determines the base-name of the files to be created
by calls to gnuplot plot image. gnuplot open file generates a gnuplot control file with the
name FileName.gp, in which the respective plot commands are written. Each image plotted by
gnuplot plot image (or control values plotted by T gnuplot plot ctrl) creates a data file with the
name FileName.dat.Number, where Number is the number of the plot in the current sequence. The generated
control file can later be edited to create the desired effect. After the last plot gnuplot close has to be
called in order to close all open files. The corresponding identifier for the gnuplot output stream is returned in
GnuplotFileID.
Parameter
º FileName (input control) ...................................................filename const char *
Base name for control and data files.
º GnuplotFileID (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id long *
Identifier for the gnuplot output stream.
Result
gnuplot open file returns the value H MSG TRUE if the control file could be opened. Otherwise, an exception
handling is raised.
Parallelization Information
gnuplot open file is processed completely exclusively without parallelization.
Possible Successor Functions
gnuplot plot image, gnuplot close
gnuplot open pipe
Alternatives
HALCON/C Reference Manual / 2000-11-15

4.2. GNUPLOT 191
See Also
gnuplot open pipe, gnuplot close, gnuplot plot image
System
Module
gnuplot open pipe ( long *GnuplotFileID )
Open a pipe to a gnuplot process for visualization of images and control values.
gnuplot open pipe opens a pipe to a gnuplot sub-process with which subsequently images can
be visualized as 3D-plots (gnuplot plot image) or control values can be visualized as 2D-plots
(T gnuplot plot ctrl). The sub-process must be terminated after displaying the last plot by calling
gnuplot close. The corresponding identifier for the gnuplot output stream is returned in GnuplotFileID.
Attention
gnuplot open pipe is only implemented for Unix because gnuplot for Windows (wgnuplot) cannot be
controlled by an external process.
Parameter
º GnuplotFileID (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id long *
Identifier for the gnuplot output stream.
Result
gnuplot open pipe returns the value H MSG TRUE if the sub-process could be created. Otherwise, an exception
handling is raised.
Parallelization Information
gnuplot open pipe is processed completely exclusively without parallelization.
Possible Successor Functions
gnuplot plot image, T gnuplot plot ctrl, gnuplot close
gnuplot open file
System
Alternatives
Module
T gnuplot plot ctrl ( Htuple GnuplotFileID, Htuple Values )
Plot control values using gnuplot.
T gnuplot plot ctrl displays a tuple of control values using gnuplot. If there is an active gnuplot subprocess
(started with gnuplot open pipe), the image is displayed in a gnuplot window. Otherwise, the image
is output to a file, which can be later read by gnuplot. In both cases the gnuplot output stream is identified by
GnuplotFileID.
Parameter
º GnuplotFileID (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id Htuple . long
Identifier for the gnuplot output stream.
º Values (input control) ........................................number-array Htuple . double / long
Control values to be plotted (y-values).
Result
T gnuplot plot ctrl returns the value if GnuplotFileID is a valid gnuplot output stream, if the data
file for the current plot could be opened, and if only integer or floating point values were passed. Otherwise, an
exception handling is raised.
Parallelization Information
T gnuplot plot ctrl is processed completely exclusively without parallelization.
Possible Predecessor Functions
gnuplot open pipe, gnuplot open file
HALCON 6.0

192 CHAPTER 4. GRAPHICS
gnuplot close
Possible Successor Functions
See Also
gnuplot open pipe, gnuplot open file, gnuplot close
System
Module
T gnuplot plot funct 1d ( Htuple GnuplotFileID, Htuple Function )
Plot a function using gnuplot.
T gnuplot plot ctrl displays a function of control values using gnuplot. If there is an active gnuplot subprocess
(started with gnuplot open pipe), the image is displayed in a gnuplot window. Otherwise, the image
is output to a file, which can be later read by gnuplot. In both cases the gnuplot output stream is identified by
GnuplotFileID.
Parameter
º GnuplotFileID (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id Htuple . long
Identifier for the gnuplot output stream.
º Function (input control) ..................................function 1d-array Htuple . double / long
Function to be plotted.
Result
T gnuplot plot ctrl returns H MSG TRUE if GnuplotFileID is a valid gnuplot output stream, and if
the data file for the current plot could be opened. Otherwise, an exception handling is raised.
Parallelization Information
T gnuplot plot funct 1d is processed completely exclusively without parallelization.
Possible Predecessor Functions
gnuplot open pipe, gnuplot open file
gnuplot close
T gnuplot plot ctrl
Possible Successor Functions
Alternatives
See Also
gnuplot open pipe, gnuplot open file, gnuplot close
System
Module
gnuplot plot image ( Hobject Image, long GnuplotFileID, long SamplesX,
long SamplesY, double ViewRotX, double ViewRotZ, const char *Hidden3D )
Visualize images using gnuplot.
gnuplot plot image displays an image as a 3D-plot using gnuplot. If there is an active gnuplot sub-process
(started with gnuplot open pipe), the image is displayed in a gnuplot window. Otherwise, the image is
output to a file, which can be later read by gnuplot. In both cases the gnuplot output stream is identified by
GnuplotFileID. The parameters SamplesX and SamplesY determine the number of data points in the x-
and y-direction, respectively, which gnuplot should use to display the image. They are the equivalent of the gnuplot
variables samples and isosamples. The parameters ViewRotX und ViewRotZ determine the rotation of the plot
with respect to the viewer. ViewRotX is the rotation of the coordinate system about the x-axis, while ViewRotZ
is the rotation of the plot about the z-axis. These two parameters correspond directly to the first two parameters
of the ’set view’ command in gnuplot. The parameter Hidden3D determines whether hidden surfaces should be
removed. This is equivalent to the ’set hidden3d’ command in gnuplot. If a single image is passed to the operator,
it is displayed in a separate plot. If multiple images are passed, they are displayed in the same plot.
HALCON/C Reference Manual / 2000-11-15

4.3. LUT 193
Parameter
º Image (input object) ..............................................................image Hobject
Image to be plotted.
º GnuplotFileID (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gnuplot id long
Identifier for the gnuplot output stream.
º SamplesX (input control) ............................................................integer long
Number of samples in the x-direction.
Default Value : 64
Typical Range of Values : 2 SamplesX 10000
Restriction : SamplesX 2
º SamplesY (input control) ............................................................integer long
Number of samples in the y-direction.
Default Value : 64
Typical Range of Values : 2 SamplesY 10000
Restriction : SamplesY 2
º ViewRotX (input control) ...................................................number double / long
Rotation of the plot about the x-axis.
Default Value : 60
Typical Range of Values : 0 ViewRotX 180
Minimal Value Step : 0.01
Recommended Value Step : 10
Restriction : ´0 ViewRotXµ ´ViewRotX 180µ
º ViewRotZ (input control) ...................................................number double / long
Rotation of the plot about the z-axis.
Default Value : 30
Typical Range of Values : 0 ViewRotZ 360
Minimal Value Step : 0.01
Recommended Value Step : 10
Restriction : ´0 ViewRotZµ ´ViewRotZ 360µ
º Hidden3D (input control) ......................................................string const char *
Plot the image with hidden surfaces removed.
Default Value : ’hidden3d’
Value List : Hidden3D ¾’hidden3d’, ’nohidden3d’
Result
gnuplot plot image returns the value if GnuplotFileID is a valid gnuplot output stream, and if the data
file for the current plot could be opened. Otherwise, an exception handling is raised.
Parallelization Information
gnuplot plot image is processed completely exclusively without parallelization.
Possible Predecessor Functions
gnuplot open pipe, gnuplot open file
gnuplot close
Possible Successor Functions
See Also
gnuplot open pipe, gnuplot open file, gnuplot close
System
Module
4.3 LUT
disp lut ( long WindowHandle, long Row, long Column, long Scale )
Graphical view of the look-up-table (lut).
HALCON 6.0

194 CHAPTER 4. GRAPHICS
disp lut displays a graphical view of the look-up-table (lut) in the valid window. A look-up-table defines the
transformation of image gray values to colors/gray levels on the screen. On most systems this can be modified.
disp lut creates a graphical view of the table assigned to the output window with the logical window number
WindowHandle and displays it for every basic color (red, green, blue). Row and Column define the position
of the centre of the graphic. Scale allows scaling of the graphic, whereas 1 means displaying all 256 values,
2 means displaying 128 values, 3 means displaying only 64 values, etc. Tables for monochrome-representations
are displayed in the currently set color (see (T )set color, T set rgb, etc.). Tables for displaying ”‘false
colors”’ are viewed with red, green and blue for each color component.
Attention
draw lut can only be used on hardware supporting look-up-tables for the output.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (input control) ...................................................................point.y long
Row of centre of the graphic.
Default Value : 128
Typical Range of Values : 0 Row 511
º Column (input control) ...............................................................point.x long
Column of centre of the graphic.
Default Value : 128
Typical Range of Values : 0 Column 511
º Scale (input control) ................................................................integer long
Scaling of the graphic.
Default Value : 1
Value List : Scale ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Typical Range of Values : 0 Scale 20
set_lut(WindowHandle,"color") ;
disp_lut(WindowHandle,256,256,1) ;
get_mbutton(WindowHandle,_,_,_) ;
set_lut(WindowHandle,"sqrt") ;
disp_lut(WindowHandle,128,128,2) ;
Example
Result
disp lut returns H MSG TRUE if the hardware supports a look-up-table, the window is valid and the parameters
are correct. Otherwise an exception handling is raised.
Parallelization Information
disp lut is local and processed completely exclusively without parallelization.
(T )set lut
Possible Predecessor Functions
See Also
open window, open textwindow, draw lut, (T )set lut, set fix, T set pixel, write lut,
T get lut, (T )set color
System
Module
draw lut ( long WindowHandle )
Manipulate look-up-table (lut) interactively.
draw lut allows interactive manipulation of the look-up-table of the device currently displaying the output window.
HALCON/C Reference Manual / 2000-11-15

4.3. LUT 195
By pressing and holding down the left mouse button one can change (from ”‘left to right”’) the red-, green- and
blue-intensity displayed in a 2 dimensional diagram with the gray values on the x-axis. The left mouse button
also is used for choosing the color channel that should be changed. As an alternative, one can map pure gray
levels (gray ”‘color channel”’) to the gray values on the x-axis. The right mouse button is used for terminating the
change-process. The modified look-up-table can be saved by write lut and reloaded later by (T )set lut.
T get lut succeeding draw lut returns directly the RGB tuple of the look-up-table. These are suitable as
input of (T )set lut.
Attention
draw lut can only be used on hardware supporting look-up-tables for the output and allow dynamic changing of
the tables.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
Example
read_image(&Image,"fabrik") ;
disp_image(Image,WindowHandle) ;
draw_lut(WindowHandle) ;
write_lut(WindowHandle,"my_lut") ;
...
read_image(&Image,"fabrik") ;
set_lut(WindowHandle,"my_lut") ;
Result
draw lut returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
draw lut is local and processed completely exclusively without parallelization.
Possible Successor Functions
set lut style, (T )set lut, write lut, disp lut
set fix, T set rgb
Alternatives
See Also
write lut, (T )set lut, T get lut, disp lut
System
Module
get fixed lut ( long WindowHandle, char *Mode )
Get fixing of ”‘look-up-table”’ (lut) for ”‘real color images”’
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Mode (output control) ................................................................string char *
Mode of fixing.
Default Value : ’true’
Value List : Mode ¾’true’, ’false’
Parallelization Information
get fixed lut is local and processed completely exclusively without parallelization.
set fixed lut
System
Possible Successor Functions
Module
HALCON 6.0

196 CHAPTER 4. GRAPHICS
T get lut ( Htuple WindowHandle, Htuple *LookUpTable )
Get current look-up-table (lut).
T get lut returns the name or the values of the look-up-table (lut) of the window, currently used by
disp image (or indirectly by disp region, etc.) for output. To set a look-up-table use (T )set lut.
If the current table is a system table without any modification ( by set fix ), the name of the table is returned. If
it is a modified table, a table read from a file or a table for output with pseudo real colors, the RGB-values of the
table are returned.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º LookUpTable (output control) .................................string-array Htuple . char * / long *
Name of look-up-table or tuple of RGB-values.
Result
T get lut returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get lut is local and processed completely exclusively without parallelization.
draw lut, (T )set lut
set fix, T get pixel
(T )set lut, draw lut
System
Possible Successor Functions
Alternatives
See Also
Module
get lut style ( long WindowHandle, double *Hue, double *Saturation,
double *Intensity )
Get modification parameters of look-up-table (lut).
get lut style returns the values that were set with set lut style. Default is:
Hue: 0.0
Saturation 1.0
Intensity 1.0
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Hue (output control) .................................................................real double *
Modification of color value.
º Saturation (output control) .......................................................real double *
Modification of saturation.
º Intensity (output control) ........................................................real double *
Modification of intensity.
Result
get lut style returns H MSG TRUE if the window is valid and the parameter is correct. Otherwise an exception
handling is raised.
Parallelization Information
get lut style is local and processed completely exclusively without parallelization.
HALCON/C Reference Manual / 2000-11-15

4.3. LUT 197
set lut style, (T )set lut
set lut style
System
Possible Successor Functions
See Also
Module
T query lut ( Htuple WindowHandle, Htuple *LookUpTable )
Query all available look-up-tables (lut).
T query lut returns the names of all look-up-tables available on the current used device. These tables can be
set with (T )set lut. An table named ’default’ is always available.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º LookUpTable (output control) .........................................string-array Htuple . char *
Names of look-up-tables.
Result
T query lut returns H MSG TRUE if a window is valid. Otherwise an exception handling is raised.
Parallelization Information
T query lut is local and processed completely exclusively without parallelization.
Possible Successor Functions
set lut style, (T )set lut, write lut, disp lut
(T )set lut
System
See Also
Module
set fixed lut ( long WindowHandle, const char *Mode )
Fix ”‘look-up-table”’ (lut) for ”‘real color images”’.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Mode (input control) ............................................................string const char *
Mode of fixing.
Default Value : ’true’
Value List : Mode ¾’true’, ’false’
Parallelization Information
set fixed lut is local and processed completely exclusively without parallelization.
get fixed lut
System
Possible Predecessor Functions
Module
HALCON 6.0

198 CHAPTER 4. GRAPHICS
set lut ( long WindowHandle, const char *LookUpTable )
T set lut ( Htuple WindowHandle, Htuple LookUpTable )
Set ”‘look-up-table”’ (lut).
(T )set lut sets look-up-table of the device (monitor) displaying the output window. A look-up-table defines
the transformation of a ”‘gray value”’ within an image into a gray value or color on the screen. It describes the
screen gray value/color as a combination of red, green and blue for any image gray value (0..255) (so it is a ’table’
to ’look up’ the screen gray value/color for each image gray value: look-up-table). Transformation into screencolors
is performed in real-time at every time the screen is displayed new (typically this happens about 60 - 70
times per second). So it is possible to change the llok-up-table to get a new look of images or regions. Please
remind that not all machines support changing the look-up-table (e.g. monochrome resp. real color).
Look-up-tables within HALCON (and on a machine that supports 256 colors) are diposed into three areas:
S: system area resp. user area,
G: graphic colors,
B: image data.
Colors in S descend from applications that were active before starting HALCON and should not get lost. Graphic
colors in G are used for operators such as disp region, (T )disp circle etc. and are set unique within
all look-up-tables. An output in a graphic color has always got the same (color-)look, even if different look-uptables
are used. (T )set color and T set rgb set graphic colors. Gray values resp. colors in B are used
by disp image to display an image. They can change according to the current look-up-table. There exist two
exceptions to this concept:
¯ (T )set gray allows setting of colors of the area B for operators such as disp region,
¯ set fix that allows modification of graphic colors.
For common monitors only one look-up-table can be loaded per screen. Whereas (T )set lut can be activated
separately for each window. There is the following solution for this problem: It will always be activated the
look-up-table that is assigned to the ”‘active window”’ (a window is set into the state ”‘active”’ by the window
manager).
look-up-table can also be used with truecolor displays. In this case the look-up-table will be simulated in software.
This means, that the look-up-table will be used each time an image is displayed.
WindowsNT specific: if the graphiccard is used in mode different from truecolor, you must display the image after
setting the look-up-taple.
T query lut lists the names of all look-up-tables. They differ from each other in the area used for gray values.
Within this area the following behaiviour is defined:
gray value tables (1-7 image levels)
’default’: Only the two basic colors (generally black and white) are used.
color tables (Real color, static gray value steps)
’default’: Table proposed by the hardware.
gray value tables (256 colors)
’default’: As ’linear’.
’linear’: Linear increasing of gray values from 0 (black) to 255 (white).
’inverse’: Inverse function of ’linear’.
’sqr’: Gray values increase according to square function.
’inv sqr’: Inverse function of ’sqr’.
’cube’: Gray values increase according to cubic function.
’inv cube’: Inverse function of ’cube’.
HALCON/C Reference Manual / 2000-11-15

4.3. LUT 199
’sqrt’: Gray values increase according to square-root function.
’inv sqrt’: Inverse Function of ’sqrt’.
’cubic root’: Gray values increase according to cubic-root function.
’inv cubic root’: Inverse Function of ’cubic root’.
color tables (256 colors)
’color1’: Linear transition from red via green to blue.
’color2’: Smooth transition from yellow via red, blue to green.
’color3’: Smooth transition from yellow via red, blue, green, red to blue.
’color4’: Smooth transition from yellow via red to blue.
’three’: Displaying the three colors red, green and blue.
’six’: Displaying the six basic colors yellow, red, magenta, blue, cyan and green.
’twelve’: Displaying 12 colors.
’twenty four’: Displaying 24 colors.
’rainbow’: Displaying the spectral colors from red via green to blue.
’temperature’: Temperature table from black via red, yellow to white.
’change1’: Color changement after every pixel within the table alternating the six basic colors.
’change2’: Fivefold color changement from green via red to blue.
’change3’: Threefold color changement from green via red to blue.
A look-up-table can be read from a file. Every line of such a file must contain three numbers in the range of
0 to 255, with the first number describing the amount of red, the second the amount of green and the third the
amount of blue of the represented display color. The number of lines can vary. The first line contains information
for the first gray value and the last line for the last value. If there are less lines than gray values, the
available information values are distributed over the whole interval calculating the missing values by interpolation.
If there are more lines than gray values, a number of (uniformly distributed) lines is ignored. The file-name must
conform to ”‘LookUpTable.lut”’. Within the parameter the name is specified without file extension. HAL-
CON will search for the file in the current directory and after that in a specified directory ( see set system
(’lut dir’,) ). It is also possible to call (T )set lut with a tuple of RGB-Values. These will
be set directly. The number of parameter values must conform to the number of pixels currently used within the
look-up-table.
Attention
(T )set lut can only be used with monitors supporting 256 gray levels/colors.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º LookUpTable (input control) ............................string(-array) (Htuple .) const char * / long
Name of look-up-table, values of look-up-table (RGB) or file name.
Default Value : ’default’
Value Suggestions : LookUpTable ¾’default’, ’linear’, ’inverse’, ’sqr’, ’inv sqr’, ’cube’, ’inv cube’,
’sqrt’, ’inv sqrt’, ’cubic root’, ’inv cubic root’, ’color1’, ’color2’, ’color3’, ’color4’, ’three’, ’six’, ’twelfe’,
’twenty four’, ’rainbow’, ’temperature’, ’cyclic gray’, ’cyclic temperature’, ’hsi’, ’change1’, ’change2’,
’change3’
Example
Htuple WindowHandleTuple, LUTs ;
read_image(&Image,"affe") ;
create_tuple(&WindowHandleTuple,1) ;
set_i(WindowHandleTuple,WindowHandle,0) ;
T_query_lut(WindowHandleTuple,&LUTs) \:
for(i=1; i

200 CHAPTER 4. GRAPHICS
fwrite_string("current table: ") ;
fwrite_string(get_s(LUTs,i)) ;
fnew_line() ;
get_mbutton(WindowHandle,_,_,_) ;
} ;
Result
(T )set lut returns H MSG TRUE if the hardware supports a look-up-table and the parameter is correct. Otherwise
an exception handling is raised.
Parallelization Information
(T )set lut is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
T query lut, draw lut, T get lut
write lut
draw lut, set fix, T set pixel
Possible Successor Functions
Alternatives
See Also
T get lut, T query lut, draw lut, set fix, (T )set color, T set rgb, T set hsi, write lut
System
Module
set lut style ( long WindowHandle, double Hue, double Saturation,
double Intensity )
Changing the look-up-table (lut).
set lut style changes the look-up-table (lut) of the device displaying the valid output window. It has got three
parameters:
Hue: Rotation of color space, Hue = 1.9 conforms to a one-time rotation of the color space. No changement: Hue
= 0.0 Complement colors: Hue = 0.5
Saturation: Changement of saturation, No changement: Saturation = 1.0 Gray value image: Saturation = 0.0
Intensity: Changement of intensity, No changement: Intensity = 1.0 Black image: Intensity = 0.0
Changement affects only the part of an look-up-table that is used for diplaying images. The parameter of modification
remain until the next call of set lut style. Calling (T )set lut has got no effect on these parameters.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Hue (input control) ...................................................................real double
Modification of color value.
Default Value : 0.0
Typical Range of Values : 0.0 Hue 1.0
Restriction : ´0.0 Hueµ ´Hue 1.0µ
º Saturation (input control) ..........................................................real double
Modification of saturation.
Default Value : 1.5
Typical Range of Values : 0.0 Saturation
Restriction : 0.0 Saturation
º Intensity (input control) ...........................................................real double
Modification of intensity.
Default Value : 1.5
Typical Range of Values : 0.0 Intensity
Restriction : 0.0 Intensity
HALCON/C Reference Manual / 2000-11-15

4.3. LUT 201
Example
read_image(&Image,"affe") ;
set_lut(WindowHandle,"color") ;
do{
get_mbutton(WindowHandle,&Row,&Column,&Button) ;
Saturation= Row/300.0 ;
Hue = Column/512.0 ;
set_lut_style(WindowHandle,Hue,Saturation,1.0) ;
}
while(Button > 1) ;
Result
set lut style returns H MSG TRUE if the window is valid and the parameter is correct. Otherwise an exception
handling is raised.
Parallelization Information
set lut style is local and processed completely exclusively without parallelization.
get lut style
(T )set lut
(T )set lut, scale image
get lut style
System
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
write lut ( long WindowHandle, const char *FileName )
Write look-up-table (lut) as file.
write lut saves the look-up-table (resp. the part of it that is relevant for displaying image gray values) of the
valid output window into a file named ’FileName.lut’. It can be read again later with (T )set lut.
Attention
write lut is only suitable for systems using 256 colors.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º FileName (input control) ...................................................filename const char *
File name (of file containing the look-up-table).
Default Value : ’/tmp/lut’
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
draw_lut(WindowHandle) ;
write_lut(WindowHandle,"test_lut") ;
Example
Result
disp lut returns H MSG TRUE if the window with the demanded properties (256 colors) is valid and the
parameter (file-name) is correct. It returns H MSG FAIL if the specified file can’t be opened. Otherwise an
exception handling is raised.
HALCON 6.0

202 CHAPTER 4. GRAPHICS
Parallelization Information
write lut is local and processed completely exclusively without parallelization.
draw lut, (T )set lut
Possible Predecessor Functions
See Also
(T )set lut, draw lut, T set pixel, T get pixel
System
Module
4.4 Mouse
get mbutton ( long WindowHandle, long *Row, long *Column, long *Button )
Wait until a mouse button is pressed.
get mbutton returns the coordinates of the mouse pointer in the output window and the mouse button pressed
(Button):
1: Left button,
2: Middle button,
4: Right button.
The operator waits until a button is pressed in the output window. If more than one button is pressed, the sum of
the individual buttons’ values is returned. The origin of the coordinate system is located in the left upper corner
of the window. The row coordinates increase towards the bottom, while the column coordinates increase towards
the right. For graphics windows, the coordinates of the lower right corner are (image height-1,image width-1)
(see open window, reset obj db), while for text windows they are (window height-1,window width-1) (see
open textwindow).
Attention
get mbutton only returns if a mouse button is pressed in the window.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (output control) ................................................................point.y long *
Row coordinate of the mouse position in the window.
º Column (output control) ............................................................point.x long *
Column coordinate of the mouse position in the window.
º Button (output control) ............................................................integer long *
Mouse button(s) pressed.
get mbutton returns the value H MSG TRUE.
Result
Parallelization Information
get mbutton is local and processed completely exclusively without parallelization.
open window, open textwindow
get mposition
open window, open textwindow
System
Possible Predecessor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

4.4. MOUSE 203
get mposition ( long WindowHandle, long *Row, long *Column,
long *Button )
Query the mouse position.
get mposition returns the coordinates of the mouse pointer in the output window and the mouse button pressed.
These values are returned regardless of the state of the mouse buttons (pressed or not pressed). If more than one
button is pressed, the sum of the individual buttons’ values is returned. The possible values for Button are:
0: No button,
1: Left button,
2: Middle button,
4: Right button.
The origin of the coordinate system is located in the left upper corner of the window. The row coordinates increase
towards the bottom, while the column coordinates increase towards the right. For graphics windows, the coordinates
of the lower right corner are (image height-1,image width-1) (see open window, reset obj db), while
for text windows they are (window height-1,window width-1) (see open textwindow).
Attention
get mposition fails (returns FAIL) if the mouse pointer is not located within the window. In this case, no
values are returned.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (output control) ................................................................point.y long *
Row coordinate of the mouse position in the window.
º Column (output control) ............................................................point.x long *
Column coordinate of the mouse position in the window.
º Button (output control) ............................................................integer long *
Mouse button(s) pressed or 0.
Result
get mposition returns the value H MSG TRUE. If the mouse pointer is not located within the window,
H MSG FAIL is returned.
Parallelization Information
get mposition is local and processed completely exclusively without parallelization.
open window, open textwindow
get mbutton
open window, open textwindow
System
Possible Predecessor Functions
Alternatives
See Also
Module
get mshape ( long WindowHandle, char *Cursor )
Query the current mouse pointer shape.
get mshape returns the name of the pointer shape set for the window. The mouse pointer shape can be used in
the operator set mshape.
HALCON 6.0

204 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Cursor (output control) .............................................................string char *
Mouse pointer name.
Result
get mshape returns the value H MSG TRUE.
Parallelization Information
get mshape is processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, T query mshape
set mshape
set mshape, T query mshape
System
Possible Successor Functions
See Also
Module
T query mshape ( Htuple WindowHandle, Htuple *ShapeNames )
Query all available mouse pointer shapes.
T query mshape returns the names of all available mouse pointer shapes for the window. These can be used in
the operator set mshape. If no mouse pointers are available, the empty tuple is returned.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º ShapeNames (output control) ..........................................string-array Htuple . char *
Available mouse pointer names.
Result
T query mshape returns the value H MSG TRUE.
Parallelization Information
T query mshape is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, get mshape
set mshape
set mshape, get mshape
System
Possible Successor Functions
See Also
Module
set mshape ( long WindowHandle, const char *Cursor )
Set the current mouse pointer shape.
set mshape sets the shape of the mouse pointer for the window. A list of the names of all available mouse
pointer shapes can be obtained by calling T query mshape. The mouse pointer shape given by Cursor is used
if the mouse pointer enters the window, irrespective of which window is the output window at present.
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 205
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Cursor (input control) .........................................................string const char *
Mouse pointer name.
Default Value : ’arrow’
Result
set mshape returns the value H MSG TRUE if the mouse pointer shape Cursor is defined for this window.
Otherwise, an exception handling is raised.
Parallelization Information
set mshape is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, T query mshape, get mshape
get mshape, T query mshape
System
See Also
Module
4.5 Output
disp arc ( long WindowHandle, double CenterRow, double CenterCol,
double Angle, long BeginRow, long BeginCol )
T disp arc ( Htuple WindowHandle, Htuple CenterRow, Htuple CenterCol,
Htuple Angle, Htuple BeginRow, Htuple BeginCol )
Displays circular arcs in a window.
(T )disp arc displays one or several circular arcs in the output window. An arc is described by its center point
(CenterRow,CenterCol), the angle between start and end of the arc (Angle in radians) and the first point of
the arc (BeginRow,BeginCol). The arc is displayed in clockwise direction. The parameters for output can be
determined - as with the output of regions - with the procedures (T )set color, (T )set gray, set draw,
etc. It is possible to draw several arcs with one call by using tupel parameters. For the use of colors with several
arcs, see (T )set color.
Attention
The center point has to be within the window. The radius of the arc has be at least 2 pixel.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º CenterRow (input control) ....................................arc.center.y (Htuple .) double / long
Row coordinate of center point.
Default Value : 64
Value Suggestions : CenterRow ¾0, 64, 128, 256
Typical Range of Values : 0 CenterRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º CenterCol (input control) ....................................arc.center.x (Htuple .) double / long
Column coordinate of center point.
Default Value : 64
Value Suggestions : CenterCol ¾0, 64, 128, 256
Typical Range of Values : 0 CenterCol 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON 6.0

206 CHAPTER 4. GRAPHICS
º Angle (input control) .........................................arc.angle.rad (Htuple .) double / long
Angle between start and end of the arc (in radians).
Default Value : 3.1415926
Value Suggestions : Angle ¾0.0, 0.785398, 1.570796, 3.1415926, 6.283185
Typical Range of Values : 0.0 Angle 6.283185 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Angle 0.0
º BeginRow (input control) ...............................arc.begin.y(-array) (Htuple .) long / double
Row coordinate of the start of the arc.
Default Value : 32
Value Suggestions : BeginRow ¾0, 64, 128, 256
Typical Range of Values : 0 BeginRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º BeginCol (input control) ...............................arc.begin.x(-array) (Htuple .) long / double
Column coordinate of the start of the arc.
Default Value : 32
Value Suggestions : BeginCol ¾0, 64, 128, 256
Typical Range of Values : 0 BeginCol 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Example
double Row, Column, WindowHandle;
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
set_draw(WindowHandle,"fill") ;
set_color(WindowHandle,"white") ;
set_insert(WindowHandle,"not") ;
Row = 100 ;
Column = 100 ;
disp_arc(WindowHandle,Row,Column,(double)3.14,(int)Row+10,(int)Column+10) ;
close_window(WindowHandle).
(T )disp arc returns H MSG TRUE.
Result
Parallelization Information
(T )disp arc is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb, T set hsi
Alternatives
(T )disp circle, (T )disp ellipse, disp region, gen circle, gen ellipse
See Also
open window, open textwindow, (T )set color, set draw, T set rgb, T set hsi
System
Module
disp arrow ( long WindowHandle, double Row1, double Column1,
double Row2, double Column2, double Size )
T disp arrow ( Htuple WindowHandle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple Size )
Displays arrows in a window.
(T )disp arrow displays one or several arrows in the output window. An arrow is described by the coordinates
of the start (Row1,Column1) and the end (Row2,Column2). An arrowhead is displayed at the end of the arrow.
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 207
The size of the arrowhead is specified by the parameter Size. If the arrow consists of just one point (start = end)
nothing is displayed. The procedures used to control the display of regions (e.g. set draw, (T )set color,
set line width) can also be used with arrows. Several arrows can be displayed with one call by using tuple
parameters. For the use of colors with several arcs, see (T )set color.
Attention
The start and the end of the arrows must fall within the window.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Row1 (input control) ....................................line.begin.y(-array) (Htuple .) double / long
Row index of the start.
Default Value : 10.0
Value Suggestions : Row1 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Row1 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
º Column1 (input control) ................................line.begin.x(-array) (Htuple .) double / long
Column index of the start.
Default Value : 10.0
Value Suggestions : Column1 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Column1 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
º Row2 (input control) ......................................line.end.y(-array) (Htuple .) double / long
Row index of the end.
Default Value : 118.0
Value Suggestions : Row2 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Row2 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
º Column2 (input control) ..................................line.end.x(-array) (Htuple .) double / long
Column index of the end.
Default Value : 118.0
Value Suggestions : Column2 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Column2 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
º Size (input control) ...............................................number (Htuple .) double / long
Size of the arrowhead.
Default Value : 1.0
Value Suggestions : Size ¾1.0, 2.0, 3.0, 5.0
Typical Range of Values : 0.0 Size 20.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Restriction : Size 0.0
Example
set_colored(WindowHandle,3) ;
disp_arrow(WindowHandle,10,10,118,118,1.0);
(T )disp arrow returns H MSG TRUE.
Result
Parallelization Information
(T )disp arrow is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb, T set hsi
HALCON 6.0

208 CHAPTER 4. GRAPHICS
Alternatives
(T )disp line, gen region polygon, disp region
See Also
open window, open textwindow, (T )set color, set draw, set line width
System
Module
disp channel ( Hobject MultichannelImage, long WindowHandle,
long Channel )
T disp channel ( Hobject MultichannelImage, Htuple WindowHandle,
Htuple Channel )
Displays images with several channels.
(T )disp channel displays an image in the output window. It is possible to display several images with one
call. In this case the images are displayed one after another. If the definition domains of the images overlap only
the last image is visible. The parameter Channel defines the number of the channel that is displayed. For RGBimages
the three color channels have to be used within a tuple parameter. For more information see disp image.
Parameter
º MultichannelImage (input object) .......................................image(-array) Hobject
Multichannel images to be displayed.
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Channel (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Number of channel or the numbers of the RGB-channels
Default Value : 1
Value List : Channel ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Example
/* Tranformation from rgb to gray */
read_image(Image,"patras") ;
disp_color(Image,WindowHandle) ;
rgb1_to_gray(Image,&GrayImage) ;
disp_image(GrayImage,WindowHandle);
Result
If the used images contain valid values and a correct output mode is set, (T )disp channel returns
H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )disp channel is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi
disp image, disp color
Alternatives
See Also
open window, open textwindow, reset obj db, (T )set lut, draw lut, (T )dump window
System
Module
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 209
disp circle ( long WindowHandle, double Row, double Column,
double Radius )
T disp circle ( Htuple WindowHandle, Htuple Row, Htuple Column,
Htuple Radius )
Displays circles in a window.
(T )disp circle displays one or several circles in the output window. A circle is described by the center
(Row, Column) and the radius Radius. If the used coordinates are not within the window the circle is clipped
accordingly.
The procedures used to control the display of regions (e.g. set draw, (T )set gray, set draw) can also be
used with circles. Several circles can be displayed with one call by using tuple parameters. For the use of colors
with several circles, see (T )set color.
Attention
The center of the circle must be within the window.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Row (input control) ...................................circle.center.y(-array) (Htuple .) double / long
Row index of the center.
Default Value : 64
Value Suggestions : Row ¾0, 64, 128, 256
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................circle.center.x(-array) (Htuple .) double / long
Column index of the center.
Default Value : 64
Value Suggestions : Column ¾0, 64, 128, 256
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Radius (input control) .................................circle.radius(-array) (Htuple .) double / long
Radius of the circle.
Default Value : 64
Value Suggestions : Radius ¾0, 64, 128, 256
Typical Range of Values : 0 Radius 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Radius 0.0
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
set_draw(WindowHandle,"fill") ;
set_color(WindowHandle,"white") ;
set_insert(WindowHandle,"not") ;
get_mbutton(WindowHandle,&Row,&Column,&Button) ;
disp_circle(WindowHandle,Row,Column,(Row + Column) mod 50) ;
(T )disp circle returns H MSG TRUE.
Result
Parallelization Information
(T )disp circle is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb, T set hsi
HALCON 6.0

210 CHAPTER 4. GRAPHICS
Alternatives
(T )disp ellipse, disp region, gen circle, gen ellipse
See Also
open window, open textwindow, (T )set color, set draw, T set rgb, T set hsi
System
Module
disp color ( Hobject ColorImage, long WindowHandle )
Displays a color (RGB) image
disp color displays the three channels of a color image in the output window. The channels are ordered in the
sequence (red,green,blue). disp color can be simulated by (T )disp channel.
Attention
Due to the restricted number of available colors the color appearance is usually different from the original.
Parameter
º ColorImage (input object) ........................................................image Hobject
Color image to display.
º WindowHandle (input control) ......................................................window long
Window identifier.
Example
/* disp_color(ColorImage) is identical to: */
Herror my_disp_color(Hobject ColorImage, Htuple *WindowHandle) {
Htuple Tupel;
create_tuple(&Tupel,3);
set_i(Tupel,1,0);
set_i(Tupel,2,1);
set_i(Tupel,3,2);
T_disp_channel(ColorImage,*WindowHandle,Tupel);
destroy_tuple(Tupel);
}
Result
If the used image contains valid values and a correct output mode is set, disp color returns H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
disp color is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi
(T )disp channel, disp obj
Alternatives
See Also
disp image, open window, open textwindow, reset obj db, (T )set lut, draw lut,
(T )dump window
Module
System
T disp distribution ( Htuple WindowHandle, Htuple Distribution,
Htuple Row, Htuple Column, Htuple Scale )
Displays a noise distribution.
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 211
T disp distribution displays a distribution in the window. The parameters are the same as in
T set paint(WindowHandle,’histogram’) or gen region histo. Noise distributions can be generated
with operations like gauss distribution or noise distribution mean.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º Distribution (input control) ..........................................real-array Htuple . double
Gray value distribution (513 values).
º Row (input control) ...........................................................point.y Htuple . long
Row index of center.
Default Value : 256
Value Suggestions : Row ¾0, 64, 128, 256
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column (input control) .......................................................point.x Htuple . long
Column index of center.
Default Value : 256
Value Suggestions : Column ¾0, 64, 128, 256
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Scale (input control) ........................................................integer Htuple . long
Size of display.
Default Value : 1
Value Suggestions : Scale ¾1, 2, 3, 4, 5, 6
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
set_draw(WindowHandle,"fill") ;
set_color(WindowHandle,"white") ;
set_insert(WindowHandle,"not") ;
read_image(Image,"affe") ;
draw_region(&Region,WindowHandle) ;
noise_distribution_mean(Region,Image,21,&Distribution) ;
disp_distribution (WindowHandle,Distribution,100,100,3) ;
Parallelization Information
T disp distribution is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb,
T set hsi, noise distribution mean, gauss distribution
See Also
gen region histo, T set paint, gauss distribution, noise distribution mean
System
Module
disp ellipse ( long WindowHandle, long CenterRow, long CenterCol,
double Phi, double Radius1, double Radius2 )
T disp ellipse ( Htuple WindowHandle, Htuple CenterRow,
Htuple CenterCol, Htuple Phi, Htuple Radius1, Htuple Radius2 )
Displays ellipses.
HALCON 6.0

212 CHAPTER 4. GRAPHICS
(T )disp ellipse displays one or several ellipses in the output window. An ellipse is described by the center
(CenterRow, CenterCol), the orientation Phi (in radians) and the radii of the minor and the major axis
(Radius1 and Radius2).
The procedures used to control the display of regions (e.g. set draw, (T )set gray, set draw) can also be
used with ellipses. Several ellipses can be displayed with one call by using tuple parameters. For the use of colors
with several ellipses, see (T )set color.
Attention
The center of the ellipse must be within the window.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º CenterRow (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y(-array) (Htuple .) long
Row index of center.
Default Value : 64
Value Suggestions : CenterRow ¾0, 64, 128, 256
Typical Range of Values : 0 CenterRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º CenterCol (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x(-array) (Htuple .) long
Column index of center.
Default Value : 64
Value Suggestions : CenterCol ¾0, 64, 128, 256
Typical Range of Values : 0 CenterCol 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Phi (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad(-array) (Htuple .) double / long
Orientation of the ellipse in radians
Default Value : 0.0
Value Suggestions : Phi ¾0.0, 0.785398, 1.570796, 3.1415926, 6.283185
Typical Range of Values : 0.0 Phi 6.283185 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Radius1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1(-array) (Htuple .) double / long
Radius of major axis.
Default Value : 24.0
Value Suggestions : Radius1 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Radius1 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Radius2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2(-array) (Htuple .) double / long
Radius of minor axis.
Default Value : 14.0
Value Suggestions : Radius2 ¾0.0, 64.0, 128.0, 256.0
Typical Range of Values : 0.0 Radius2 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Example
set_color(WindowHandle,"red") ;
draw_region(&MyRegion,WindowHandle) ;
elliptic_axis(MyRegion,&Ra,&Rb,&Phi) ;
area_center(MyRegion,_,&Row,&Column) ;
disp_ellipse(WindowHandle,Row,Column,Phi,Ra,Rb);
Result
(T )disp ellipse returns H MSG TRUE, if the parameters are correct. Otherwise an exception handling is
raised.
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 213
Parallelization Information
(T )disp ellipse is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb,
T set hsi, elliptic axis, area center
Alternatives
(T )disp circle, disp region, gen ellipse, gen circle
See Also
open window, open textwindow, (T )set color, T set rgb, T set hsi, set draw,
set line width
Module
System
disp image ( Hobject Image, long WindowHandle )
Displays gray value images.
disp image displays the gray values of an image in the output window. The gray value pixels of the definition
domain (set comprise(WindowHandle,’object’)) or of the whole image (set comprise
(WindowHandle,’image’)) are used. Restriction to the definition domain is the default.
For the display of gray value images the number of gray values is usually reduced. This is due to the fact that colors
have to be reserved for the display of graphics (e.g. (T )set color) and the window manager. Also depending
on the number of bitplanes on the used output device often less than 256 colors (eight bitplanes) are available. The
number of ”’colors”’ actually reserved for the display of gray values can be queried by get system. Before
opening the first window this value can be modified by set system. For instance for 8 bitplanes 200 real gray
values are the default.
The reduction of the number of gray values does not pose problems as long as only gray value information is
displayed, humans cannot distinguish 256 different shades of gray. If certain gray values are used for the representation
of region information (which is not the style commonly used in HALCON ), confusions might be
the result, since different numerical values are displayed on the screen with the same gray value. The procedure
label to region should be used on these images in order to transform the label data into HALCON objects.
If images of type ’int2’, ’int4’, ’real’ or ’complex’ are displayed, the smallest and largest gray value is computed.
Afterwards the pixel data is rescaled according to the number of available gray values (depending on the output
device. e.g. 200). It is possible that some pixels have a very different value than the other pixels. This might lead
to the display of an (almost) completely white or black image. In order to decide if the current image is a binary
image min max gray can be used. If neccessary the image can be transformed or converted by scale image
and convert image type before it is displayed.
Attention
If a wrong output mode was set by T set paint, the error will be reported when disp image is used.
Parameter
º Image (input object) ..............................................................image Hobject
Gray value image to display.
º WindowHandle (input control) ......................................................window long
Window identifier.
/* Output of a gray image: */
read_image(&Image,"affe");
disp_image(Image,WindowHandle);
Example
Result
If the used image contains valid values and a correct output mode is set, disp image returns H MSG TRUE.
Otherwise an exception handling is raised.
HALCON 6.0

214 CHAPTER 4. GRAPHICS
Parallelization Information
disp image is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, scale image, convert image type,
min max gray
Alternatives
disp obj, disp color
See Also
open window, open textwindow, reset obj db, set comprise, T set paint, (T )set lut,
draw lut, paint gray, scale image, convert image type, (T )dump window
System
Module
disp line ( long WindowHandle, double Row1, double Column1, double Row2,
double Column2 )
T disp line ( Htuple WindowHandle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2 )
Draws lines in a window.
(T )disp line displays one or several lines in the output window. A line is described by the coordinates of
the start (Row1,Column1) and the coordinates of the end (Row2,Column2). The procedures used to control the
display of regions (e.g. (T )set color, (T )set gray, set draw, set line width) can also be used
with lines. Several lines can be displayed with one call by using tuple parameters. For the use of colors with
several lines, see (T )set color.
Attention
The starting points and the ending points of the lines must be in the window.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Row1 (input control) ..........................................line.begin.y(-array) (Htuple .) double
Row index of the start.
Default Value : 32
Value Suggestions : Row1 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Row1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column1 (input control) ......................................line.begin.x(-array) (Htuple .) double
Column index of the start.
Default Value : 32
Value Suggestions : Column1 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Column1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Row2 (input control) ............................................line.end.y(-array) (Htuple .) double
Row index of end.
Default Value : 64
Value Suggestions : Row2 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 215
º Column2 (input control) ........................................line.end.x(-array) (Htuple .) double
Column index of end.
Default Value : 64
Value Suggestions : Column2 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Example
/* Prozedur zur Ausgabe der Kontur eines Rechtecks: /*
disp_rectangle1_margin(long WindowHandle,
long Row1, long Column1,
long Row2, long Column2)
{
disp_line(WindowHandle,Row1,Column1,Row1,Column2) ;
disp_line(WindowHandle,Row1,Column2,Row2,Column2) ;
disp_line(WindowHandle,Row2,Column2,Row2,Column1) ;
disp_line(WindowHandle,Row2,Column1,Row1,Column1) ;
}
(T )disp line returns H MSG TRUE.
Result
Parallelization Information
(T )disp line is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, set draw, (T )set color, set colored,
set line width
Alternatives
(T )disp arrow, (T )disp rectangle1, (T )disp rectangle2, disp region,
gen region polygon, gen region points
See Also
open window, open textwindow, (T )set color, T set rgb, T set hsi, set insert,
set line width
Module
System
disp obj ( Hobject Object, long WindowHandle )
Displays image objects (image, region, XLD).
disp obj displays objects depending of their kind. disp obj is equivalent to disp image for one channel
images, equivalent to disp color for three channel images, equivalent to disp region for regions and
equivalent to disp xld for XLDs.
Parameter
º Object (input object) ......................................................object(-array) Hobject
Image object to be displayed.
º WindowHandle (input control) ......................................................window long
Window identifier.
/* Output of a gray image: */
read_image(&Image,"affe");
Example
HALCON 6.0

216 CHAPTER 4. GRAPHICS
disp_obj(Image,WindowHandle);
threshold(Image,&Region,0.0,128.0);
disp_obj(Region,WindowHandle);
Result
If the used object is valid and a correct output mode is set, disp obj returns H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
disp obj is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, scale image, convert image type,
min max gray
Alternatives
disp color, disp image, disp xld, disp region
See Also
open window, open textwindow, reset obj db, set comprise, T set paint, (T )set lut,
draw lut, paint gray, scale image, convert image type, (T )dump window
System
Module
T disp polygon ( Htuple WindowHandle, Htuple Row, Htuple Column )
Displays a polyline.
T disp polygon displays a polyline with the row coordinates Row and the column coordinates Column in the
output window. The parameters Row and Column have to be provided as tuples. Straight lines are drawn between
the given points. The start and the end of the polyline are not connected.
The procedures used to control the display of regions (e.g. (T )set color, (T )set gray, set draw,
set line width) can also be used with polylines.
The given coordinates must lie within the window.
Attention
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º Row (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long / double
Row index
Default Value : ’[16,80,80]’
Value Suggestions : Row ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long / double
Column index
Default Value : ’[48,16,80]’
Value Suggestions : Column ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
/* display a rectangle */
Example
disp_rectangle1_margin1(long WindowHandle,
long Row1, long Column1,
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 217
{
long Row2, long Column2)
Htuple Row, Col;
create_tuple(&Row,4) ;
create_tuple(&Col,4) ;
set_i(Row,Row1,0) ;
set_i(Col,Column1,0) ;
set_i(Row,Row1,1) ;
set_i(Col,Column2,1) ;
set_i(Row,Row2,2) ;
set_i(Col,Column2,2) ;
set_i(Row,Row2,3) ;
set_i(Col,Column1,3) ;
set_i(Row,Row1,4) ;
set_i(Col,Column1,4) ;
T_disp_polygon(WindowHandle,Row,Col) ;
}
T disp polygon returns H MSG TRUE.
Result
Parallelization Information
T disp polygon is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, set draw, (T )set color, set colored,
set line width
Alternatives
(T )disp line, gen region polygon, disp region
See Also
open window, open textwindow, (T )set color, T set rgb, T set hsi, set insert,
set line width
Module
System
disp rectangle1 ( long WindowHandle, double Row1, double Column1,
double Row2, double Column2 )
T disp rectangle1 ( Htuple WindowHandle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2 )
Display of rectangles aligned to the coordinate axes.
(T )disp rectangle1 displays one or several rectangles in the output window. A rectangle is described by
the upper left corner (Row1,Column1) and the lower right corner (Row2,Column2). If the given coordinates are
not within the boundary of the window the rectangle is clipped accordingly. The procedures used to control the
display of regions (e.g. (T )set color, (T )set gray, set draw, set line width) can also be used
with rectangles. Several rectangles can be displayed with one call by using tuple parameters.
HALCON 6.0

218 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Row1 (input control) ...............................rectangle.origin.y(-array) (Htuple .) double / long
Row index of the upper left corner.
Default Value : 16
Value Suggestions : Row1 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Row1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column1 (input control) ...........................rectangle.origin.x(-array) (Htuple .) double / long
Column index of the upper left corner.
Default Value : 16
Value Suggestions : Column1 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Column1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Row2 (input control) ..............................rectangle.corner.y(-array) (Htuple .) double / long
Row index of the lower right corner.
Default Value : 48
Value Suggestions : Row2 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Row2 Row1
º Column2 (input control) ..........................rectangle.corner.x(-array) (Htuple .) double / long
Column index of the lower right corner.
Default Value : 80
Value Suggestions : Column2 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Column2 Column1
Example
set_color(WindowHandle,"green") ;
draw_region(&MyRegion,WindowHandle) ;
smallest_rectangle1(MyRegion,&R1,&C1,&R2,&C2) ;
disp_rectangle1(WindowHandle,R1,C1,R2,C2) ;
(T )disp rectangle1 returns H MSG TRUE.
Result
Parallelization Information
(T )disp rectangle1 is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, set draw, (T )set color, set colored,
set line width
Alternatives
(T )disp rectangle2, gen rectangle1, disp region, (T )disp line, set shape
See Also
open window, open textwindow, (T )set color, set draw, set line width
System
Module
HALCON/C Reference Manual / 2000-11-15

4.5. OUTPUT 219
disp rectangle2 ( long WindowHandle, double CenterRow,
double CenterCol, double Phi, double Length1, double Length2 )
T disp rectangle2 ( Htuple WindowHandle, Htuple CenterRow,
Htuple CenterCol, Htuple Phi, Htuple Length1, Htuple Length2 )
Displays arbitrarily oriented rectangles.
(T )disp rectangle2 draws one or several arbitrarily oriented rectangles in the output window. A rectangle
is described by the center (CenterRow,CenterCol), the orientation Phi (in radians) and half the lengths of
the edges Length1 and Length2. The procedures used to control the display of regions (e.g. set draw,
(T )set gray, set draw) can also be used with rectangles. Several rectangles can be displayed with one call
by using tuple parameters. For the use of colors with several rectangles, see (T )set color.
Attention
The center must lie within the window boundaries.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º CenterRow (input control) .......................rectangle2.center.y(-array) (Htuple .) double / long
Row index of the center.
Default Value : 48
Value Suggestions : CenterRow ¾0, 64, 128, 256, 511
Typical Range of Values : 0 CenterRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º CenterCol (input control) .......................rectangle2.center.x(-array) (Htuple .) double / long
Column index of the center.
Default Value : 64
Value Suggestions : CenterCol ¾0, 64, 128, 256, 511
Typical Range of Values : 0 CenterCol 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Phi (input control) ..............................rectangle2.angle.rad(-array) (Htuple .) double / long
Orientation of rectangle in radians.
Default Value : 0.0
Value Suggestions : Phi ¾0.0, 0.785398, 1.570796, 3.1415926, 6.283185
Typical Range of Values : 0.0 Phi 6.283185 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Length1 (input control) ..........................rectangle2.hwidth(-array) (Htuple .) double / long
Half of the length of the longer side.
Default Value : 48
Value Suggestions : Length1 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Length1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Length2 (input control) ..........................rectangle2.hheight(-array) (Htuple .) double / long
Half of the length of the shorter side.
Default Value : 32
Value Suggestions : Length2 ¾0, 64, 128, 256, 511
Typical Range of Values : 0 Length2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Length2 Length1
set_color(WindowHandle,"green") ;
Example
HALCON 6.0

220 CHAPTER 4. GRAPHICS
draw_region(&MyRegion,WindowHandle) ;
elliptic_axis(MyRegion,&Ra,&Rb,&Phi) ;
area_center(MyRegion,_,&Row,&Column) ;
disp_gen_rectangle2(WindowHandle,Row,Column,Phi,Ra,Rb) ;
Result
(T )disp rectangle2 returns H MSG TRUE, if the parameters are correct. Otherwise an exception handling
is raised.
Parallelization Information
(T )disp rectangle2 is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, set draw, (T )set color, set colored,
set line width
Alternatives
disp region, gen rectangle2, (T )disp rectangle1, set shape
See Also
open window, open textwindow, disp region, (T )set color, set draw, set line width
System
Module
disp region ( Hobject DispRegions, long WindowHandle )
Displays regions in a window.
disp region displays the regions in DispRegions in the output window. The parameters for output can be
set with the procedures (T )set color, (T )set gray, set draw, set line width,etc.
The color(s) for the display of the regions are determined with (T )set color, T set rgb, (T )set gray
or set colored. If more than one region is displayed and more than one color is set, the colors are assigned in
a cyclic way to the regions.
The form of the region for output can be modified by T set paint (e.g. encompassing circle, convex
hull). The command set draw determines if the region is filled or only the boundary is drawn. If only the
boundary is drawn, the thickness of the boundary will be determined by set line width and the style by
T set line style.
Parameter
º DispRegions (input object) ...............................................region(-array) Hobject
Regions to display.
º WindowHandle (input control) ......................................................window long
Window identifier.
Example
/* Output with 12 colors: */
set_colored(WindowHandle,12) ;
disp_region(SomeSegments,WindowHandle) ;
/* Symbolic representation: */
set_draw(WindowHandle,"margin") ;
set_color(WindowHandle,"red") ;
set_shape(WindowHandle,"ellipse") ;
disp_region(SomeSegments,WindowHandle) ;
/* Representation of a margin with pattern: */
set_draw(WindowHandle,"margin") ;
create_tuple(&Color,2) ;
set_s(Color,"blue",0) ;
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 221
set_s(Color,"red",0) ;
create_tuple(&Handle,1) ;
set_i(Handle,WindowHandle,0) ;
T_set_color(Handle,Color) ;
create_tuple(&Par,2) ;
set_i(Par,12,0) ;
set_i(Par,3,1) ;
T_set_line_style(WindowHandle,Par) ;
disp_region(Segments,WindowHandle) ;
disp region returns H MSG TRUE.
Result
Parallelization Information
disp region is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, T set rgb, (T )set lut, T set hsi, set shape, T set line style, set insert,
set fix, set draw, (T )set color, set colored, set line width
Alternatives
disp obj, (T )disp arrow, (T )disp line, (T )disp circle, (T )disp rectangle1,
(T )disp rectangle2, (T )disp ellipse
See Also
open window, open textwindow, (T )set color, set colored, set draw, set shape,
T set paint, (T )set gray, T set rgb, T set hsi, T set pixel, set line width,
T set line style, set insert, set fix, paint region, (T )dump window
System
Module
disp xld ( Hobject XLDObject, long WindowHandle )
DisplayanXLDobject.
disp xld serves to display an XLD object of arbitrary type.
Parameter
º XLDObject (input object) ......................................................xld-array Hobject
XLD object to display.
º WindowHandle (input control) ......................................................window long
Window id.
Parallelization Information
disp xld is local and processed completely exclusively without parallelization.
See Also
disp image, disp region, (T )disp channel, disp color, (T )disp line, (T )disp arc
Sub-pixel operators
Module
4.6 Parameters
get comprise ( long WindowHandle, char *Mode )
Get the output treatment of an image matrix.
HALCON 6.0

222 CHAPTER 4. GRAPHICS
get comprise returns the output mode of grayvalues in the window WindowHandle that is used by
disp image and disp color. The output mode defines whether only the grayvalues of objects are displayed
or the whole image is displayed. The query is used for temporary mode settings, i.e., the current mode is queried,
then overwritten with (set comprise) and finally reset.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (output control) ................................................................string char *
Display mode for images.
Result
get comprise returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get comprise is processed completely exclusively without parallelization.
Possible Successor Functions
set comprise, disp image, disp image
set comprise, disp image, disp color
System
See Also
Module
get draw ( long WindowHandle, char *Mode )
Get the current region fill mode.
get draw returns the region fill mode of the output window. It is used by operators as disp region,
(T )disp circle, (T )disp arrow, (T )disp rectangle1, (T )disp rectangle2 etc. The region
fill mode is set with set draw.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (output control) ................................................................string char *
Current region fill mode.
Result
get draw returns H MSG TRUE, if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get draw is processed completely exclusively without parallelization.
set draw, disp region
set draw, disp region, T set paint
System
Possible Successor Functions
See Also
Module
get fix ( long WindowHandle, char *Mode )
Get mode of fixing of current look-up-table (lut).
Use get fix to get mode of fixing of current look-up-table (look-up-table of valid window) set before by
set fix.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 223
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Mode (output control) ................................................................string char *
Current Mode of fixing.
Result
get fix returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get fix is processed completely exclusively without parallelization.
set fix, T set pixel, T set rgb
set fix
System
Possible Successor Functions
See Also
Module
T get hsi ( Htuple WindowHandle, Htuple *Hue, Htuple *Saturation,
Htuple *Intensity )
Get the HSI coding of the current color.
T get hsi returns the output color or grayvalues, respectively, for the window, described in Hue, Saturation
and Intensity. T get hsi corresponds to the procedure T get pixel but returns the entries of the color
lookup table instead of its indices. The values returned by T get hsi can be set with T set hsi.
Attention
The values returned by T get hsi may be inaccurate due to rounding errors. They do not necessarily match the
values set with T set hsi exactly (colors are stored in RGB internally).
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Hue (output control) ...................................................integer-array Htuple . long *
Hue (color value) of the current color.
º Saturation (output control) .........................................integer-array Htuple . long *
Saturation of the current color.
º Intensity (output control) ..........................................integer-array Htuple . long *
Intensity of the current color.
Result
T get hsi returns H MSG TRUE, if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get hsi is processed completely exclusively without parallelization.
Possible Successor Functions
T set hsi, T set rgb, disp image
See Also
T set hsi, (T )set color, T set rgb, trans to rgb, trans from rgb
System
Module
get icon ( Hobject *Icon, long WindowHandle )
Query the icon for region output
HALCON 6.0

224 CHAPTER 4. GRAPHICS
get icon queries the icon that was set with set icon.
Parameter
º Icon (output object) .............................................................region Hobject *
Icon for the regions center of gravity.
º WindowHandle (input control) ......................................................window long
Window id.
Example
/* draw a region and an icon. */
/* set it and get it again. */
draw_region(&Region,WindowHandle) ;
draw_region(&Icon,WindowHandle) ;
set_icon(Icon) ;
set_shape(WindowHandle,"icon") ;
disp_region(Region,WindowHandle) ;
get_icon(&OldIcon) ;
disp_region(OldIcon,WindowHandle) ;
get icon always returns H MSG TRUE.
Result
Parallelization Information
get icon is processed completely exclusively without parallelization.
set icon
disp region
System
Possible Predecessor Functions
Possible Successor Functions
Module
get insert ( long WindowHandle, char *Mode )
Get the current display mode.
get insert returns the display mode of the output window. It is used by procedures like disp region,
(T )disp line, (T )disp rectangle1, etc. The mode is set with set insert. Possible values for
Mode can be queried with the procedure T query insert.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (output control) ................................................................string char *
Display mode.
Result
get insert returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get insert is processed completely exclusively without parallelization.
T query insert
set insert, disp image
Possible Predecessor Functions
Possible Successor Functions
See Also
set insert, T query insert, disp region, (T )disp line
System
Module
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 225
get line approx ( long WindowHandle, long *Approximation )
Get the current approximation error for contour display.
get line approx returns a parameter that controls the approximation error for region contour display in the
window. It is used by the procedure disp region. Approximation controls the polygon approximation
for contour display (¼ ¸ no approximation). Approximation is only important for displaying the contour of
objects, especially if a line style was set with T set line style.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Approximation (output control) ...................................................string long *
Current approximation error for contour display.
Result
get line approx returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get line approx is processed completely exclusively without parallelization.
Possible Successor Functions
set line approx, T set line style, disp region
See Also
get region polygon, set line approx, T set line style, disp region
System
Module
T get line style ( Htuple WindowHandle, Htuple *Style )
Get the current graphic mode for contours.
T get line style returns the display mode for contoures when displaying regions. It is used by procedures
like disp region, (T )disp line, T disp polygon, etc. Style is set with the procedure
T set line style. Style is only important for displaying the contour of objects, especially if a line style
was set with T set line style.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Style (output control) ................................................integer-array Htuple . long *
Template for contour display.
Result
T get line style returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get line style is local and processed completely exclusively without parallelization.
T set line style, disp region
System
See Also
Module
get line width ( long WindowHandle, long *Width )
Get the current line width for contour display.
HALCON 6.0

226 CHAPTER 4. GRAPHICS
get line width returns the line width for region display in the window. It is used by procedures
like disp region, (T )disp line, T disp polygon, etc. Width is set with the procedure
set line width. Width is only important for displaying the contour of objects.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Width (output control) .............................................................integer long *
Current line width for contour display.
Result
get line width returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get line width is processed completely exclusively without parallelization.
Possible Successor Functions
set line width, T set line style, disp region
set line width, disp region
System
See Also
Module
T get paint ( Htuple WindowHandle, Htuple *Mode )
Get the current display mode for grayvalues.
T get paint returns the display mode for grayvalues in the window. Mode is used by the procedure
disp image. T get paint is used for temporary changes of the grayvalue display mode. The current value
is queried, then changed (with procedure T set paint) and finally the old value is written back. The available
modes can be viewed with the procedure T query paint. Mode is the name of the display mode. If a mode
can be customized with parameters, the parameter values are passed in a tuple after the mode name. The order of
values is the same as in T set paint.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Mode (output control) ...........................................string-array Htuple . char * / long *
Name and parameter values of the current display mode.
Result
T get paint returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get paint is processed completely exclusively without parallelization.
T query paint
Possible Predecessor Functions
Possible Successor Functions
T set paint, disp region, disp image
T set paint, T query paint, disp image
System
See Also
Module
get part ( long WindowHandle, long *Row1, long *Column1, long *Row2,
long *Column2 )
Get the image part.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 227
get part returns the upper left and lower right corner of the image part shown in the window. The image part
can be changed with the procedure set part (Default is the whole image).
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1 (output control) .....................................................rectangle.origin.y long *
Row index of the image part’s upper left corner.
º Column1 (output control) .................................................rectangle.origin.x long *
Column index of the image part’s upper left corner.
º Row2 (output control) .....................................................rectangle.corner.y long *
Row index of the image part’s lower right corner.
º Column2 (output control) ................................................rectangle.corner.x long *
Column index of the image part’s lower right corner.
Result
get part returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get part is processed completely exclusively without parallelization.
Possible Successor Functions
set part, disp region, disp image
See Also
set part, disp image, disp region, disp color
System
Module
get part style ( long WindowHandle, long *Style )
Get the current interpolation mode for grayvalue display.
get part style returns the interpolation mode used for displaying an image part in the window. An interpolation
takes place if the output window is larger than the image format or the image output format (see set part).
HALCON supports three interpolation modes:
0 no interpolation (low quality, very fast).
1 unweighted interpolation (average quality and computation time)
2 weighted interpolation (high quality, slow)
The current mode can be changed with set part style.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Style (output control) .............................................................integer long *
Interpolation mode for image display: 0 (fast, low quality) to 2 (slow, high quality).
Value List : Style ¾0, 1, 2
Result
get part style returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get part style is processed completely exclusively without parallelization.
Possible Successor Functions
set part style, disp region, disp image
See Also
set part style, set part, disp image, disp color
System
Module
HALCON 6.0

228 CHAPTER 4. GRAPHICS
T get pixel ( Htuple WindowHandle, Htuple *Pixel )
Get the current color lookup table index.
T get pixel returns the internal coding of the output grayvalue or color, respectively, for the window. If the
output mode is set to color(s) or grayvalue(s) (see (T )set color or (T )set gray), then the color- or grayvalues
are transformed for internal use. The internal code is then used for (physical) screen display. The transformation
depends on the mapping characteristics and the condition of the output device and can be different in
different program runs. Don’t confuse the term ”‘pixel”’ with the term ”‘pixel”’ in image processing (the other
procedure is get grayval). Here a pixel is meant to be the color loookup table index.
With T get pixel it is possible to save the output mode without knowing whether colors or grayvalues are used.
Pixel is set with the procedure T set pixel.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Pixel (output control) .................................................string-array Htuple . long *
Index of the current color loopup table.
Result
get part style returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get pixel is processed completely exclusively without parallelization.
Possible Successor Functions
T set pixel, disp region, disp image
T set pixel, set fix
System
See Also
Module
T get rgb ( Htuple WindowHandle, Htuple *Red, Htuple *Green,
Htuple *Blue )
Get the current color in RGB-coding.
T get rgb returns the output colors or grayvalues, respectively, for the output window. They are defined by the
three color components red, green and blue.
T get rgb is like T get pixel but returns the entries of the color lookup table rather than the indices. The
values returned by T get rgb can be set with T set rgb.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Red (output control) ...................................................integer-array Htuple . long *
The current color’s red value.
º Green (output control) ................................................integer-array Htuple . long *
The current color’s green value.
º Blue (output control) .................................................integer-array Htuple . long *
The current color’s blue value.
Result
T get rgb returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T get rgb is processed completely exclusively without parallelization.
Possible Successor Functions
T set rgb, disp region, disp image
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 229
T set rgb
System
See Also
Module
get shape ( long WindowHandle, char *DisplayShape )
Get the current region output shape.
get shape returns the shape in which regions are displayed.
T query shape and then changed with set shape.
Parameter
The available shapes can be queried with
º WindowHandle (input control) ......................................................window long
Window id.
º DisplayShape (output control) .....................................................string char *
Current region output shape.
Result
get shape returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get shape is processed completely exclusively without parallelization.
T query shape
set shape, disp region
set shape, T query shape, disp region
System
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
T query all colors ( Htuple WindowHandle, Htuple *Colors )
Query all color names.
T query all colors returns the names of all colors that are known to HALCON . That doesn’t mean, that
these colors are available for specific screens. On some screens there may only be a subset of colors available (see
T query color). Before opening the first window, set system can be used to define which and how many
colors should be used. The HALCON colors are used to display regions (disp region, T disp polygon,
(T )disp circle, etc.). They can be defined with (T )set color.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Colors (output control) ................................................string-array Htuple . char *
Color names.
Example
Htuple Colors,ColorsAtWindow,WindowHandleTuple ;
create_tuple(&WindowHandleTuple,1) ;
open_window(0,0,1,1,"root","invisible","",&WindowHandle) ;
set_i(WindowHandleTuple, WindowHandle, 0) ;
T_query_all_colors(WindowHandleTuple,&Colors) ;
/* interactive selection from Colors, provide als result ActColors */
HALCON 6.0

230 CHAPTER 4. GRAPHICS
set_system("graphic_colors",ActColors) ;
T_query_color(WindowHandleTuple,&ColorsAtWindow) ;
close_window(WindowHandle) ;
for (i=0; i

4.6. PARAMETERS 231
(T )set color, disp region
Possible Successor Functions
See Also
T query all colors, (T )set color, disp region, open window, open textwindow
System
Module
T query colored ( Htuple *PossibleNumberOfColors )
Query the number of colors for color output.
T query colored returns all possible parameter values for set colored. set colored defines how many
colors are used for region or graphics output.
Parameter
º PossibleNumberOfColors (output control) .........................integer-array Htuple . long *
Tuple of the possible numbers of colors.
Example
Htuple Colors ;
regiongrowing(Image,&Seg,5,5,6,100) ;
T_query_colored(&Colors) ;
set_colored(WindowHandle,get_i(Colors,1)) ;
disp_region(Seg,WindowHandle) ;
Result
T query colored always returns H MSG TRUE.
Parallelization Information
T query colored is reentrant and processed without parallelization.
Possible Successor Functions
set colored, (T )set color, disp region
T query color
set colored, (T )set color
System
Alternatives
See Also
Module
T query gray ( Htuple WindowHandle, Htuple *Grayval )
Query the displayable grayvalues.
T query gray returns all grayvalues that are used for grayvalue output (disp image) and that can be reproduced
exactly in the window. They can be set with the (T )set gray call. The number of displayable grayvalues
can be set with set system(’num gray *’,...) before opening the first window.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Grayval (output control) .............................................integer-array Htuple . long *
Tuple of all displayable grayvalues.
Result
T query gray returns H MSG TRUE, if the window is valid. Otherwise an exception handling is raised.
HALCON 6.0

232 CHAPTER 4. GRAPHICS
Parallelization Information
T query gray is local and processed completely exclusively without parallelization.
(T )set gray, disp region
(T )set gray, disp image
System
Possible Successor Functions
See Also
Module
T query insert ( Htuple WindowHandle, Htuple *Mode )
Query the possible graphic modes.
T query insert returns the possible modes pixels can be displayed in the output window. New pixels may e.g.
overwrite old ones. In most of the cases there is a functional relationship between old and new values.
Possible display functions:
’copy’: overwrite displayed pixels
’xor’: display old ”‘xor”’ new pixels
’not’: complement displayed pixels
”‘copy”’ is always available.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Mode (output control) ..................................................string-array Htuple . char *
Display function name.
Result
T query insert returns H MSG TRUE, if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T query insert is local and processed completely exclusively without parallelization.
set insert, disp region
set insert, get insert
System
Possible Successor Functions
See Also
Module
query line width ( long *Min, long *Max )
Query the possible line widths.
query line width returns the minimal (Min) and maximal (Max) values of widths of region border
which can be displayed. Setting of the border width is done with set line width. Border width is
used by operators like disp region, (T )disp line, (T )disp circle, (T )disp rectangle1,
(T )disp rectangle2 etc. if the drawing mode is ”‘margin”’ (set draw(::WindowHandle,’margin’:)).
Parameter
º Min (output control) ................................................................integer long *
Displayable minimum width.
º Max (output control) ................................................................integer long *
Displayable maximum width.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 233
Result
query line width returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
query line width is reentrant and processed without parallelization.
Possible Successor Functions
get line width, set line width, T set line style, (T )disp line
See Also
(T )disp circle, (T )disp line, (T )disp rectangle1, (T )disp rectangle2,
disp region, set line width, get line width, T set line style
System
Module
T query paint ( Htuple WindowHandle, Htuple *Mode )
Query the grayvalue display modes.
T query paint returns the names of all grayvalue display modes (e.g. ’gray’, ’3D-plot’, ’contourline’, etc.) for
the output window. These modes are used by T set paint. T query paint only returns the names of the
display values, not the additional parameters that may be necessary for some modes.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Mode (output control) ..................................................string-array Htuple . char *
Grayvalue display mode names.
Result
T query paint returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T query paint is local and processed completely exclusively without parallelization.
Possible Successor Functions
T get paint, T set paint, disp image
T set paint, T get paint, disp image
System
See Also
Module
T query shape ( Htuple *DisplayShape )
Query the region display modes.
T query shape returns the names of all region display modes (e.g. ’original’, ’circle’, ’rectangle1’, ’rectangle2’,
’ellipse’, etc.) for the window. They are used by set shape.
Parameter
º DisplayShape (output control) .......................................string-array Htuple . char *
region display mode names.
Result
T query shape returns H MSG TRUE, if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
T query shape is reentrant and processed without parallelization.
Possible Successor Functions
get shape, set shape, disp region
HALCON 6.0

234 CHAPTER 4. GRAPHICS
set shape, get shape, disp region
System
See Also
Module
set color ( long WindowHandle, const char *Color )
T set color ( Htuple WindowHandle, Htuple Color )
Set output color.
(T )set color defines the colors for region output in the window. The available colors can be queried with the
procedure T query color. The ”‘colors”’ ’black’ and ’white’ are available for all screens. If colors are used
that are not displayable on the screen, HALCON can choose a similar, displayable color of the output. For this,
set check(’˜color’:) must be called. Furthermore, the list of available colors can be set with the procedure
set system(’graphic colors’,...). That must be done before opening the first output window. If only
a single color is passed, all output is in this color. If a tuple of colors is passed, the output color of regions is modulo
to the number of colors. In the example below, the first circle is displayed red, the second in green and the third
in red again. HALCON always begins output with the first color passed. Note, that the number of output colors
depends on the number of objects that are displayed in one procedure call. If only single objects are displayed,
they always appear in the first color, even if the consist of more than one connected components.
The defined colors are used until (T )set color, T set pixel, T set rgb, T set hsi or
(T )set gray is called again.
Colors are defined seperately for each window. They can only be changed for the valid window.
Color is used in procedures with region output like disp region, (T )disp line,
(T )disp rectangle1, (T )disp arrow etc. It is also used by procedures with grayvalue output in
certain output modes (e.g. ’3D-plot’,’histogram’, ’contourline’, etc. See T set paint).
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window id.
º Color (input control) ..........................................string(-array) (Htuple .) const char *
Output color names.
Default Value : ’white’
Example
Htuple Colors, WindowHandleTuple ;
create_tuple(Colors,2) ;
set_s(Colors,"red",0) ;
set_s(Colors,"green",1) ;
create_tuple(&WindowHandleTuple,1) ;
set_i(WindowHandleTuple, WindowHandle,0) ;
T_set_color(WindowHandleTuple,Colors) ;
disp_circle(WindowHandle,(double)100.0,(double)200.0,(double)100.0) ;
disp_circle(WindowHandle,(double)200.0,(double)300.0,(double)100.0) ;
disp_circle(WindowHandle,(double)300.0,(double)100.0,(double)100.0) ;
Result
(T )set color returns H MSG TRUE if the window is valid and the passed colors are displayable on the
screen. Otherwise an exception handling is raised.
Parallelization Information
(T )set color is local and processed completely exclusively without parallelization.
T query color
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 235
disp region
T set rgb, T set hsi
Possible Successor Functions
Alternatives
See Also
T get rgb, disp region, set fix, T set paint
System
Module
set colored ( long WindowHandle, long NumberOfColors )
Set multiple output colors.
set colored is a shortcut for certain (T )set color calls. It allows the user to display a region set in different
colors. NumberOfColors defines the number of colors that are used. Valid values for NumberOfColors
can be queried with T query colored. Furthermore, the list of available colors can be set with the procedure
set system(’graphic colors’,...). That must be done before opening the first output window.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º NumberOfColors (input control) ....................................................integer long
Number of output colors.
Default Value : 12
Example
Htuple TColors,SColors, WindowHandleTuple ;
set_colored(WindowHandle,Num) ;
if(Num == 3)
{
create_tuple(TColors,3) ;
set_s(Colors,"red",0) ;
set_s(Colors,"green",1) ;
set_s(Colors,"blue",2) ;
create_tuple(&WindowHandleTuple,1) ;
set_i(WindowHandleTuple, WindowHandle, 0) ;
T_set_color(WindowHandleTuple,TColors) ;
}
if(Num == 6)
{
create_tuple(SColors,6) ;
set_s(Colors,"red",0) ;
set_s(Colors,"green",1) ;
set_s(Colors,"blue",2) ;
set_s(Colors,"cyan",3) ;
set_s(Colors,"magenta",4) ;
set_s(Colors,"yellow",5) ;
T_set_color(WindowHandleTuple,SColors) ;
}
Result
set colored returns H MSG TRUE if NumberOfColors is correct and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
set colored is local and processed completely exclusively without parallelization.
HALCON 6.0

236 CHAPTER 4. GRAPHICS
Possible Predecessor Functions
T query colored, (T )set color
disp region
Possible Successor Functions
See Also
T query colored, (T )set color, disp region
System
Module
set comprise ( long WindowHandle, const char *Mode )
Define the image matrix output clipping.
set comprise defines the image matrix output clipping. If Mode is set to ’object’, only grayvalues belonging
to the output object are displayed. If set to ’image’, the whole image matrix is displayed. Default is ’object’.
Attention
If Mode was set to ’image’, undefined grayvalues may be displayed. Depending on the context they are black or
can have random content. See the examples.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (input control) ............................................................string const char *
Clipping mode for grayvalue output.
Default Value : ’object’
Value List : Mode ¾’image’, ’object’
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
read_image(&Image,"fabrik") ;
threshold(Image,&Seg,100,255) ;
set_system("init_new_image","false") ;
sobel_amp(Image,&Sob,"sum_abs",3) ;
disp_image(Sob,WindowHandle) ;
get_comprise(&Mode) ;
fwrite_string("Current mode for gray values: ") ;
fwrite_string(Mode) ;
fnew_line() ;
set_comprise(WindowHandle,"image") ;
get_mbutton(WindowHandle,_,_,_) ;
disp_image(Sob,WindowHandle) ;
fwrite_string("Current mode for gray values: image") ;
fnew_line() ;
Result
set comprise returns H MSG TRUE if Mode is correct and the window is valid. Otherwise an exception
handling is raised.
Parallelization Information
set comprise is processed completely exclusively without parallelization.
get comprise
disp image
get comprise, disp image, disp color
Possible Predecessor Functions
Possible Successor Functions
See Also
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 237
System
Module
set draw ( long WindowHandle, const char *Mode )
Define the region fill mode.
set draw defines the region fill mode. If Mode is set to ’fill’, output regions are filled, if set to ’margin’,
only contours are displayed. Setting Mode only affects the valid window. It is used by procedures with region
output like disp region, (T )disp circle, (T )disp rectangle1, (T )disp rectangle2,
(T )disp arrow etc. It is also used by procedures with grayvalue output for some grayvalue output modes (e.g.
’histogram’, see T set paint). If the mode is ’margin’, the contour can be affected with set line width,
set line approx and T set line style.
Attention
If the output mode is ’margin’ and the line width is more than one, objects may not be displayed.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (input control) ............................................................string const char *
Fill mode for region output.
Default Value : ’fill’
Value List : Mode ¾’fill’, ’margin’
Result
set draw returns H MSG TRUE if Mode is correct and the window is valid. Otherwise an exception handling
is raised.
Parallelization Information
set draw is local and processed completely exclusively without parallelization.
get draw
disp region
Possible Predecessor Functions
Possible Successor Functions
See Also
get draw, disp region, T set paint, disp image, set line width, T set line style
System
Module
set fix ( long WindowHandle, const char *Mode )
Set fixing of ”‘look-up-table”’ (lut)
Behaviour for Mode = ’true’: set fix fixes that pixel lastly ascertained by one of the operators (T )set gray,
(T )set color, T set hsi or T set rgb (Remark: Here a pixel is the index within the current look-uptable).
To assign a new color to a fixed pixel set a color or gray value by using (T )set color, T set rgb,
T set hsi or (T )set gray. This makes it possible to define any color ((T )set color), any gray value
((T )set gray) and any color combination (T set rgb, T set hsi) at any position of the look-up-table.
Mode set to ’false’ reset the fixing. To modify or create a look-up-table process T set pixel, set fix
(WindowHandle,’true’), T set rgb and set fix(WindowHandle,’false’) one after another.
Attention
As a side effect set fix can change colors of ”‘non-HALCON windows”’.
HALCON 6.0

238 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Mode (input control) ............................................................string const char *
Mode of fixing.
Default Value : ’true’
Value List : Mode ¾’true’, ’false’
Result
set fix returns H MSG TRUE if the window is valid, the hardware supports a look-up-table and all parameters
are correct. Otherwise an exception handling is raised.
Parallelization Information
set fix is local and processed completely exclusively without parallelization.
get fix
T set pixel, T set rgb
Possible Predecessor Functions
Possible Successor Functions
See Also
get fix, T set pixel, T set rgb, (T )set color, T set hsi, (T )set gray
System
Module
set gray ( long WindowHandle, long GrayValues )
T set gray ( Htuple WindowHandle, Htuple GrayValues )
Define grayvalues for region output.
(T )set gray defines the grayvalues for region output. Grayvalues are defined as the range of the
color lookup table that is used for grayvalue output with disp image in conjunction with T set paint
(WindowHandle,’gray’). These entries can be modified by (T )set lut. So a ’grayvalue’ is the color in
which a pixel with the same value is displayed (not necessarily really gray). In general, when changing the color
lookup table with (T )set lut, the colors of the displayed image will change too.
If a grayvalue is needed as a color for image output (i.e. no color changes with (T )set lut are possible), it can
be set with (T )set color(WindowHandle,’gray’).
If only a single grayvalue is passed, all output will take place in that grayvalue. If a tuple of grayvalues is passed,
all output will take place in grayvalues modulo the number of tuple elements. In the example below, the first circle
is displayed with grayvalue 100, the second with 200 and the third with 100 again. Every output procedure starts
with the first grayvalue. Note, that the number of output grayvalues depends on the number of objects that are
displayed in one procedure call. If only single objects are displayed, they always appear in the first grayvalue, even
if the consist of more than one connected components.
When the procedures (T )set gray, (T )set color, T set rgb, T set hsi are called, the overwrite
the existing values. If not all grayvalues are displayable on the output device, the number range of GrayValues
(0..255) is dithered to the range of displayable grayvalues. In any case 0 is displayed as black and 255 as white. The
displayable grayvalues can be queried with the procedure T query gray. Furthermore, the number of actually
displayed grayvalues can be changed with set system(’num gray *’,...). This must be done before
opening the first window. With set check(’˜color’:) error messages can be suppressed if a grayvalue
can’t be displayed on the screen. In that case, a similar grayvalue is displayed.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window id.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 239
º GrayValues (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Grayvalues for region output.
Default Value : 255
Value Suggestions : GrayValues ¾0, 1, 2, 10, 16, 32, 64, 100, 120, 128, 250, 251, 252, 253, 254, 255
Typical Range of Values : 0 GrayValues 255
Example
Htuple GrayValues ;
create_tuple(&GrayValues,2) ;
set_i(GrayValues,100,0) ;
set_i(GrayValues,200,0) ;
T_set_gray(WindowHandle,GrayValues) ;
disp_circle(WindowHandle,(double)100.0,(double)200.0,(double)100.0) ;
disp_circle(WindowHandle,(double)200.0,(double)300.0,(double)100.0) ;
disp_circle(WindowHandle,(double)300.0,(double)100.0,(double)100.0) ;
Result
(T )set gray returns H MSG TRUE if GrayValues is displayable and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
(T )set gray is local and processed completely exclusively without parallelization.
disp region
T get pixel, (T )set color
System
Possible Successor Functions
See Also
Module
T set hsi ( Htuple WindowHandle, Htuple Hue, Htuple Saturation,
Htuple Intensity )
Define output colors (HSI-coded).
T set hsi sets the region output color(s)/grayvalue(s) for the valid window.
Saturation,andIntensity. Transformation from HSI to RGB is done with:
Colors are passed as Hue,
À ´¾ÀÙµ¾
Á ´ÔÁÒØÒ×Øݵ¾
Å ½ ´×Ò ´ÀµËØÙÖØÓÒµ´¾ Ô µ
Å ¾ ´Ó× ´ÀµËØÙÖØÓÒµ´¾ Ô ¾µ
Ê ´¾Å ½ · Áµ´ Ô µ
´ Å ½ · Å ¾ · Áµ´ Ô
´ Å ½ Å ¾ · Áµ´ Ô µ
Ê Ê £ ¾
ÖÒ £ ¾
ÐÙ £ ¾
If only one combination is passed, all output will take place in that color. If a tuple of colors is passed, the output
color of regions and geometric objects is modulo to the number of colors. HALCON always begins output with
the first color passed. Note, that the number of output colors depends on the number of objects that are displayed
in one procedure call. If only single objects are displayed, they always appear in the first color, even if the consist
of more than one connected components.
Selected colors are used until the next call of (T )set color,T set pixel, T set rgb or (T )set gray.
Colors are relevant to windows, i.e. only the colors of the valid window can be set. Region output colors are used
HALCON 6.0

240 CHAPTER 4. GRAPHICS
by operatores like disp region, (T )disp line, (T )disp rectangle1, (T )disp rectangle2,
(T )disp arrow, etc. It is also used by procedures with grayvalue output in certain output modes (e.g. ’3Dplot’,’histogram’,
’contourline’, etc. See T set paint).
Attention
The selected intensities may not be available for the selected hues. In that case, the intensities will be lowered
automatically.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Hue (input control) .....................................................integer-array Htuple . long
Hue for region output.
Default Value : 30
Typical Range of Values : 0 Hue 255
Restriction : ´0 Hueµ ´Hue 255µ
º Saturation (input control) ............................................integer-array Htuple . long
Saturation for region output.
Default Value : 255
Typical Range of Values : 0 Saturation 255
Restriction : ´0 Saturationµ ´Saturation 255µ
º Intensity (input control) .............................................integer-array Htuple . long
Intensity for region output.
Default Value : 84
Typical Range of Values : 0 Intensity 255
Restriction : ´0 Intensityµ ´Intensity 255µ
Result
T set hsi returns H MSG TRUE if the window is valid and the output colors are displayable. Otherwise an
exception handling is raised.
Parallelization Information
T set hsi is local and processed completely exclusively without parallelization.
T get hsi
disp region
Possible Predecessor Functions
Possible Successor Functions
See Also
T get hsi, T get pixel, trans from rgb, trans to rgb, disp region
System
Module
set icon ( Hobject Icon, long WindowHandle )
Icon definition for region output.
set icon defines an icon for region output (disp region). It is displayed in the regions center of gravity. The
use of this icon is activated with set shape.
Parameter
º Icon (input object) ................................................................region Hobject
Icon for center of gravity.
º WindowHandle (input control) ......................................................window long
Window id.
/* draw a region and an icon */
Example
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 241
draw_region(&Region,WindowHandle) ;
draw_region(&Icon,WindowHandle) ;
set_icon(Icon) ;
set_shape(WindowHandle,"icon") ;
disp_region(Region,WindowHandle) ;
Result
set icon returns H MSG TRUE if exactly one region is passed. Otherwise an exception handling is raised.
Parallelization Information
set icon is processed completely exclusively without parallelization.
Possible Predecessor Functions
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region
set shape, disp region
System
Possible Successor Functions
Module
set insert ( long WindowHandle, const char *Mode )
Define the pixel output function.
set insert defines the function, with which pixels are displayed in the output window. It is e.g. possible for a
pixel to overwrite the old value. In most of the cases there is a functional relationship between old and new values.
The definiton value is only valid for the valid window. Output procedures that honor Mode are e.g. disp region,
T disp polygon,(T )disp circle.
Possible display functions are:
’copy’: overwrite displayed pixels
’xor’: display old ”xor” new pixels
’not’: complement displayed pixels
There may not be all functions available, depending on the physical display. However, ”‘copy”’ is always available.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Mode (input control) ............................................................string const char *
Name of the display function.
Default Value : ’copy’
Value List : Mode ¾’copy’, ’xor’, ’not’
Result
set insert returns H MSG TRUE if the paramter is correct and the window is valid. Otherwise an exception
handling is raised.
Parallelization Information
set insert is local and processed completely exclusively without parallelization.
T query insert, get insert
disp region
get insert, T query insert
System
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
HALCON 6.0

242 CHAPTER 4. GRAPHICS
set line approx ( long WindowHandle, long Approximation )
Define the approximation error for contour display.
set line approx defines the approximation error for region contour display in the window.
Approximation values greater than zero cause a polygon approximation smoothing (with a maximum
polygon/contour deviation of Approximation pixel). The approximation algorithm is the same as in
get region polygon. set line approx is important for contour output via T set line style.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Approximation (input control) .....................................................integer long
Maximum deviation from the original contour.
Default Value : 0
Typical Range of Values : 0 Approximation
Restriction : Approximation 0
Example
/* Calling */
set_line_approx(WindowHandle,Approximation) ;
set_draw(WindowHandle,"margin") ;
disp_region(Obj,WindowHandle) ;
/* correspond with */
Htuple Approximation,Row,Col, WindowHandleTuple ;
create_tuple(&Approximation,1) ;
set_i(Approximation,0,0) ;
create_tuple(&WindowHandleTuple,1) ;
set_i(WindowHandleTuple,WindowHandle, 0) ;
T_get_region_polygon(Obj,Approximation,&Row,&Col) ;
T_disp_polygon(WindowHandleTuple,Row,Col) ;
Result
set line approx returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
set line approx is processed completely exclusively without parallelization.
get line approx
disp region
get region polygon, T disp polygon
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
get line approx, T set line style, set draw, disp region
System
Module
T set line style ( Htuple WindowHandle, Htuple Style )
Define a contour output pattern.
T set line style defines the output pattern of region contours. The information is used by procedures
like disp region, (T )disp line, T disp polygon etc. The current value can be queried with
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 243
T get line style. Style contains up to five pairs of values. The first value is the length of the visible
contour part, the second is the length of the invisible part. The value pairs are used cyclical for contour output.
Attention
T set line style does an implicit polygon approximation (see set line approx(WindowHandle,3)).
It is only possible to enlarge it with set line approx.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Style (input control) ...................................................integer-array Htuple . long
Countour pattern.
Default Value : ’[]’
Htuple LineStyle ;
Example
/* stroke line: X-Windows */
create_tuple(&LineStyle,2) ;
set_i(LineStyle,20,0) ;
set_i(LineStyle,7,1) ;
T_set_line_style(WindowHandle,LineStyle) ;
destroy_tuple(LineStyle) ;
/* point-stroke line: X-Windows */
create_tuple(&LineStyle,4) ;
set_i(LineStyle,20,0) ;
set_i(LineStyle,7,1) ;
set_i(LineStyle,3,2) ;
set_i(LineStyle,7,3) ;
T_set_line_style(WindowHandle,LineStyle) ;
destroy_tuple(LineStyle) ;
/* passing line (standard) */
create_tuple(&LineStyle,0) ;
T_set_line_style(WindowHandle,LineStyle) ;
destroy_tuple(LineStyle) ;
Result
T set line style returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
T set line style is local and processed completely exclusively without parallelization.
T get line style
disp region
Possible Predecessor Functions
Possible Successor Functions
See Also
T get line style, set line approx, disp region
System
Module
set line width ( long WindowHandle, long Width )
Define the line width for region contour output.
HALCON 6.0

244 CHAPTER 4. GRAPHICS
set line width defines the line width (in pixel) in which a region contour is displayed (e.g. with
disp region, (T )disp line, T disp polygon, etc.) The procedure get line width returns the current
value for the window. Some output devices may not allow to change the contour width. If it is possible for the
current device, it can be queried with query line width.
Attention
The line width is important if the output mode was set to ’margin’ (see set draw). If the line width is greater
than one, regions may not always be displayed correctly.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Width (input control) ................................................................integer long
Line width for region output in contour mode.
Default Value : 1
Restriction : Width 1
Result
set line width returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
set line width is processed completely exclusively without parallelization.
Possible Predecessor Functions
query line width, get line width
disp region
Possible Successor Functions
See Also
get line width, query line width, set draw, disp region
System
Module
T set paint ( Htuple WindowHandle, Htuple Mode )
Define the grayvalue output mode.
T set paint defines the output mode for grayvalue display (single- or multichannel) in the window. The mode
is used by disp image.
This page describes the different modes, that can be used for grayvalue output. It should be noted, that the mode
’default’ is the most suitable.
The hardware characteristics determine how grayvalues can be displayed. On a screen with one to seven bit planes,
only binary data can be displayed. On screens with at least eight bit planes, it is possible to display multiple
grayvalues. For binary displays HALCON includes algorithms with dithering matrix (fast, but low resolution),
minimal error (good, but slow) and thresholding. Using the thresholding algorithm, the threshold can be passed as
a second parameter (a tuple with the string ’threshold’ and the actual threshold, e.g.: [’theshold’, 100]).
Displays with eight bit planes use approximately 200 grayvalues for output. Of course it is still possible to use a
binary display on those displays.
A different way to display grayvalues is the histogram (mode: ’histogram’). This mode has two additional parameter
values: Row (second value) and column (third value). They denote row and column of the histogram center
for positioning on the screen. The scale factor (fourth value) determines the histogram size: a scale factor of 1
distinguishes 256 grayvalues, 2 distinguishes 128 grevalues, and so on. The four values are passed as a tuple,
e.g. [’histogram’, 256,256,1]. If only the first value is passed (’histogram’), the other values are set to defaults
or the last values, respectively. For histogram computation see gray histo. Histogram output honors the same
parameters as procedures like disp region etc. (e.g. (T )set color, set draw,etc.)
Yet another mode is the display of relative frequencies of the number of connection components (”’component
histogram”’). For informations on computing the component histogram see shape histo all). Positioning
and resolution are exactly as in the mode ’histogram’.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 245
In mode ’mean’, all object regions are displayed in their mean grayvalue.
The modes ’line’ and ’column’ allow the display of lines or columns, respecively. The position (line- and columnindex)
is passed with the second paramter value. The third parameter value is the scale factor in percent (100 means
1 pixel per grayvalue, 50 means one pixel per two grayvalues).
Gray images can also be interpreted as 3d data, depending on the grayvalue. To view these 3d plots, select the
modes ’contourline’, ’3D-plot’ or ’3D-plot hidden’.
Two-channel images can be viewed as ’vectorfield’.
Three-channel images are interpreted as RGB images. They can be displayed in three different modes. Two of
them can be optimized by Floyd-Steinberg dithering.
Paramters for modes that need more than one parameter can be passed the following ways:
¯ Only the name of the mode is passed: the defaults or the last values are used, respectively. Example:
T set paint(WindowHandle,’contourline’)
¯ All values are passed: all output characteristics can be set. Example: T set paint
(WindowHandle,[’contourline’,10,1])
¯ Only the first n values are passed: only the passed values are changed. Example: T set paint
(WindowHandle,[’contourline’,10])
¯ Some of the values are replaced by an asterisk (’*’): The value of the replaced parameters is not changed.
Example: T set paint(WindowHandle,[’contourline’,’*’,1])
If the current mode is ’default’, HALCON chooses a suitable algorithm for the output of 2- and 3-channel images..
No T set paint call is necessary in this case.
Apart from T set paint there are other procedures that affect the output of grayvalues. The most important
of them are set part, set part style,(T )set lut and set lut style. Some output modes display
grayvalues using region output (e.g. ’histogram’,’contourline’,’3D-plot’, etc.). In these modes, paramters
set with (T )set color, T set rgb,T set hsi, T set pixel, set shape, set line width and
set insert influence grayvalue output. This can lead to unexpected results when using set shape
(’convex’) and T set paint(WindowHandle,’histogram’). Here the convex hull of the histogram
is displayed.
Modes:
¯ one-channel images:
’default’ optimal display on given hardware
’gray’ grayvalue output
’mean’ mean grayvalue
’dither4 1’ binary image, dithering matrix 4x4
’dither4 2’ binary image, dithering matrix 4x4
’dither4 3’ binary image, dithering matrix 4x4
’dither8 1’ binary image, dithering matrix 8x8
’floyd steinberg’ binary image, optimal grayvalue simulation
[’threshold’,Threshold ]
’threshold’ binary image, threshold: 128 (default)
[’threshold’,200 ] binary image, any threshold: (here: 200)
[’histogram’,Line,Column,Scale ]
’histogram’ grayvalue output as histogram.
position default: max. size, in the window center
[’histogram’,256,256,2 ] grayvalue output as histogram, any parameter values.
positioning: window center (here (256,256))
size: (here 2, half the max. size)
[’component histogram’,Line,Column,Scale ]
’component histogram’ output as histogram of the connection components.
Positioning: default
[’component histogram’,256,256,1 ] output as histogram of the connection components.
Positioning: (here (256, 256))
Scaling: (here 1, max. size)
HALCON 6.0

246 CHAPTER 4. GRAPHICS
[’line’,Line,Scale ]
’line’ output of the grayvalue profile along the given line.
line: image center (default)
Scaling: 50
[’line’,100,20 ] output of the grayvalue profile of line 100 with a scaling of 0.2 (20
[’column’,Column,Scale ]
’column’ output of the grayvalue profile along the given column.
column: image center (default)
Scaling: 50
[’column’,100,20 ] output of the grayvalue profile of column 100 with a scaling of 0.2 (20
[’contourline’,Step,Colored ]
’contourline’ grayvalue output as contour lines: the grayvalue difference per line is defined with the
parameter ’Step’ (default: 30, i.e. max. 8 lines for 256 grayvalues). The line can be displayed in
a given color (see set color) or in the grayvalue they represent. This behaviour is defined with the
parameter ’Colored’ (0 = color, 1 = grayvalues). Default is color.
[’contourline’,15,1 ] grayvalue output as contour lines with a step of 15 and gray output.
[’3D-plot’, Step, Colored, EyeHeight, EyeDistance, ScaleGray, LinePos, ColumnPos]
’3D-plot’ grayvalues are interpreted as 3d data: the greater the value, the ’higher’ the assumed mountain.
Lines with step 2 (second paramter value) are drawn along the x- and y-axes. The third parameter
(Colored) determines, if the output should be in color (default) or grayvalues. To define the
projection of the 3d data, use the parameters EyeHeight and EyeDistance. The projection parameters
take values from 0 to 255. ScaleGray defines a factor, by which the grayvalues are multiplied for
’height’ interpretation (given in percent. 100EyeHeight and EyeDistance the image can be shifted
out of place. Use RowPos and ColumnPos to move the whole output. Values from -127 to 127 are
possible.
[’3D-plot’, 5, 1, 110, 160, 150, 70, -10 ] line step: 5 pixel
Colored: yes (1)
EyeHeight: 110
EyeDistance: 160
ScaleGray: 1.5 (150)
RowPos: 70 pixel down
ColumnPos: 10 pixel right
[’3D-plot hidden’, Step, Colored, EyeHeight, EyeDistance, ScaleGray, LinePos, ColumnPos]
’3D-plot hidden’ like ’3D-plot’, but computes hidden lines.
¯ Two-channel images:
’default’ output as vector field.
[’vectorfield’, Step, MinLengh, ScaleLength ]
’vectorfield’ output of the two channels as displacement vector field. Procedures like optical flow*
produce images of pixel displacements (first channel: x-displacement, second channel: y-
displacement).
In this mode, an arrow is drawn for each vector. The parameter Step has to be set in correspondence
to optical flow*. Short vectors can be suppressed by the third parameter value (MinLength). The
fourth parameter value scales the vector length. Vectors, that exceed the window boundaries are nor
drawn.
[’vectorfield’,16,2,3 ] Output of every 16. vector, that is longer than 2 pixel. Each vector is multiplied
by 3 for output.
¯ Three-channel images:
’default’ output as RGB image with ’median cut’.
’television’ color addition algorithm for RGB images: (three components necessary for disp image).
Images are displayed via a fixed color lookup table. Fast, but non-optimal color resolution. Only recommended
on bright screens.
’grid scan’ grid-scan algorithm for RGB images (three components necessary for disp image). An optimized
color lookup table is generated for each image. Slower than ’television’. Disadvantages: Hard
color boundaries (no dithering). Different color lookup table for every image.
’grid scan floyd steinberg’ grid-scan with Floyd-Steinberg dithering for smooth color boundaries.
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 247
’median cut’ median-cut algorithm for RGB images (three components necessary for disp image). Similar
to grid-scan. Disadvantages: Hard color boundaries (no dithering). Different color lookup table for
every image.
’median cut floyd steinberg’ median-cut algorithm with Floyd-Steinberg dithering for smooth color
boundaries.
Attention
¯ Display of color images (’television’, ’grid scan’, etc.) changes the color lookup tables.
¯ If a wrong color mode is set, the error message may appear not until the disp image call.
¯ Grayvalue output may be influenced by region output parameters. This can yield unexpected results.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Mode (input control) ........................................string-array Htuple . const char * / long
Grevalue output name. Additional parameters possible.
Default Value : ’default’
Example
Htuple Modi,HilfsTuple1,HilfsTuple2,HilfsTuple3, WindowHandleTuple ;
create_tuple(&HilfsTuple1,1) ;
create_tuple(&HilfsTuple2,2) ;
create_tuple(&HilfsTuple3,3) ;
create_tuple(&WindowHandleTuple,1) ;
read_image(&Image,"fabrik") ;
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
T_query_paint(WindowHandleTuple,Modi) ;
T_fwrite_string(Modi) ;
fnew_line() ;
disp_image(Image,WindowHandle) ;
get_mbutton(WindowHandle,_,_,_) ;
set_s(HilfsTuple1,"red",0) ;
set_i(WindowHandleTuple,WindowHandle,0);
T_set_color(WindowHandleTuple,HilfsTuple1) ;
set_draw(WindowHandle,"margin") ;
set_s(HilfsTuple1,"histogram",0) ;
T_set_paint(WindowHandleTuple,HilfsTuple1) ;
disp_image(Image,WindowHandle) ;
set_s(HilfsTuple1,"blue",0) ;
T_set_color(WindowHandleTuple,HilfsTuple1) ;
set_s(HilfsTuple3,"histogram",0) ;
set_s(HilfsTuple3,100,1) ;
set_s(HilfsTuple3,100,2) ;
T_set_paint(WindowHandleTuple,HilfsTuple3) ;
disp_image(Image,WindowHandle) ;
set_s(HilfsTuple1,"yellow",0) ;
T_set_color(WindowHandleTuple,HilfsTuple1) ;
set_s(HilfsTuple2,"line",0) ;
set_s(HilfsTuple2,100,1) ;
T_set_paint(WindowHandleTuple,HilfsTuple3) ;
disp_image(Image,WindowHandle) ;
get_mbutton(WindowHandle,_,_,_) ;
HALCON 6.0

248 CHAPTER 4. GRAPHICS
clear_window(WindowHandle) ;
set_s(HilfsTuple3,"contourline",0) ;
set_s(HilfsTuple3,10,1) ;
set_s(HilfsTuple3,1,2) ;
T_set_paint(WindowHandleTuple,HilfsTuple3) ;
disp_image(Image,WindowHandle) ;
set_lut(WindowHandle,"color") ;
get_mbutton(WindowHandle,_,_,_) ;
clear_window(WindowHandle) ;
set_part(WindowHandle,100,100,300,300) ;
set_s(HilfsTuple1,"3D-plot",0) ;
T_set_paint(WindowHandleTuple,HilfsTuple1) ;
disp_image(Image,WindowHandle) ;
Result
T set paint returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an exception
handling is raised.
Parallelization Information
T set paint is local and processed completely exclusively without parallelization.
T query paint, T get paint
disp image
Possible Predecessor Functions
Possible Successor Functions
See Also
T get paint, T query paint, disp image, set shape, T set rgb, (T )set color,
(T )set gray
Module
System
set part ( long WindowHandle, long Row1, long Column1, long Row2,
long Column2 )
Modify the displayed image part.
set part modifies the image part that is displayed in the window. (Row1,Column1) denotes the upper left
corner and (Row2,Column2) the lower right corner of the image part to display. The changed values are used by
grayvalue output operators (disp image, disp color) as well as region output operators (disp region)).
If only part of an image is displayed, it will be zoomed to full window size. The zooming interpolation method
can be set with set part style. get part returns the values of the image part to display.
Beside setting the image part directly, the following special modes are supported:
Row1 = Column1 = Row2 = Column2 =-1: The window size is choosen as the image part, i.e. no zooming of
the image will be performed.
Row1, Column1 -1 and Row2 = Column2 =-1: The size of the last displayed image (in this window) is
choosen as the image part, i.e. the image can completely be displayed in the image. For this the image
will be zoomed if necessary.
Attention
After a call of set part, some operators like draw region, draw ellipse, etc. can no longer be used.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Row1 (input control) ........................................................rectangle.origin.y long
Row of the upper left corner of the chosen image part.
Default Value : 0
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 249
º Column1 (input control) ....................................................rectangle.origin.x long
Column of the upper left corner of the chosen image part.
Default Value : 0
º Row2 (input control) .......................................................rectangle.corner.y long
Row of the lower right corner of the chosen image part.
Default Value : -1
Restriction : ´Row2 Row1µ ´Row2 -1µ
º Column2 (input control) ...................................................rectangle.corner.x long
Column of the lower right corner of the chosen image part.
Default Value : -1
Restriction : ´Column2 Column1µ ´Column2 -1µ
Example
get_system("width",Width) ;
get_system("height",Height) ;
set_part(WindowHandle,0,0,Height-1,Width-1) ;
disp_image(Image,WindowHandle) ;
draw_rectangle1(WindowHandle,&Row1,&Column1,&Row2,&Column2) ;
set_part(WindowHandle,Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
Result
set part returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
set part is processed completely exclusively without parallelization.
get part
Possible Predecessor Functions
Possible Successor Functions
set part style, disp image, disp region
affine trans image
Alternatives
See Also
get part, set part style, disp region, disp image, disp color
System
Module
set part style ( long WindowHandle, long Style )
Define an interpolation method for grayvalue output.
set part style defines the interpolation method to zoom an image part which is displayed in the window.
Interpolation takes place, if the output window has different size than the image to display (e.g. after a call to
set part or a window resize). Three modes are supported:
0 no interpolation (low quality, very fast).
1 unweighted interpolation (medium quality and run time)
2 weighted interpolation (high quality, slow)
The current value can be queried with get part style.
HALCON 6.0

250 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Style (input control) ................................................................integer long
Interpolation method for image output: 0 (fast, low quality) to 2 (slow, high quality).
Default Value : 0
Value List : Style ¾0, 1, 2
Result
set part style returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an
exception handling is raised.
Parallelization Information
set part style is processed completely exclusively without parallelization.
get part style
Possible Predecessor Functions
Possible Successor Functions
set part, disp image, disp region
affine trans image
Alternatives
See Also
get part style, set part, disp image, disp color
System
Module
T set pixel ( Htuple WindowHandle, Htuple Pixel )
Define a color lookup table index.
T set pixel sets pixel values: colors ((T )set color, T set rgb, etc.) and grayvalues ((T )set gray)
are coded together into a number, called pixel. This ’pixel’ is an index in the color lookup table. It ranges from 0
to 1 in b/w images and 0 to 255 color images with 8 bit planes. It is different from the ’pixel’ (”picture element”)
in image processing. Therefore HALCON distinguishes between pixel and image element (or grayvalue).
The current value can be queried with T get pixel.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Pixel (input control) ...................................................integer-array Htuple . long
Color lookup table index.
Default Value : 128
Typical Range of Values : 0 Pixel 255
Result
T set pixel returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an exception
handling is raised.
Parallelization Information
T set pixel is local and processed completely exclusively without parallelization.
T get pixel
disp image, disp region
T set rgb, (T )set color, T set hsi
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
T get pixel, (T )set lut, disp region, disp image, disp color
HALCON/C Reference Manual / 2000-11-15

4.6. PARAMETERS 251
System
Module
T set rgb ( Htuple WindowHandle, Htuple Red, Htuple Green, Htuple Blue )
Set the color definition via RGB values.
T set rgb sets the output color(s) or the grayvalues, respectively, for region output for the window. The colors
are defined with the red, green and blue components. If only one combination is passed, all output takes place in
that color. If a tuple is passed, region output and output of geometric objects takes place modulo the passed colors.
For every call of an output procedure, output is started with the first color. If only one object is displayed per
call, it will always be displayed in the first color. This is even true for objects with multiple connection components.
If multiple objects are displayed per procedure call, multiple colors are used. The defined colors are used
until (T )set color, T set pixel, T set rgb or (T )set gray is called again. The values are used
by procedures like disp region, (T )disp line, (T )disp rectangle1, (T )disp rectangle2,
(T )disp arrow,etc.
Attention
If a passed is not available, an exception handling is raised. If set check(’˜color’:) was called before,
HALCON uses a similar color and suppresses the error.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º Red (input control) .....................................................integer-array Htuple . long
Red component of the color.
Default Value : 255
Typical Range of Values : 0 Red 255
Restriction : ´0 Redµ ´Red 255µ
º Green (input control) ...................................................integer-array Htuple . long
Green component of the color.
Default Value : 0
Typical Range of Values : 0 Green 255
Restriction : ´0 Greenµ ´Green 255µ
º Blue (input control) ....................................................integer-array Htuple . long
Blue component of the color.
Default Value : 0
Typical Range of Values : 0 Blue 255
Restriction : ´0 Blueµ ´Blue 255µ
Result
T set rgb returns H MSG TRUE if the window is valid and all passed colors are available and displayable.
Otherwise an exception handling is raised.
Parallelization Information
T set rgb is local and processed completely exclusively without parallelization.
disp image, disp region
Possible Successor Functions
Alternatives
T set hsi, (T )set color, (T )set gray
set fix, disp region
System
See Also
Module
HALCON 6.0

252 CHAPTER 4. GRAPHICS
set shape ( long WindowHandle, const char *Shape )
Define the region output shape.
set shape defines the shape for region output. It is only valid for the window with the logical window number
WindowHandle. The output shape is used by disp region. The available shapes can be queried with
T query shape.
Available modes:
’original’: The shape is displayed unchanged. Nevertheless modifications via parameters like set line width or
set line approx can take place. This is also true for all other modes.
’outer circle’: Each region is displayed by the smallest surrounding circle. (See smallest circle.)
’inner circle’: Each region is displayed by the largest included circle. (See inner circle.)
’ellipse’: Each region is displayed by an ellipse with the same moments and orientation (See elliptic axis.)
’rectangle1’: Each region is displayed by the smallest surrounding rectangle parallel to the coordinate axes. (See
smallest rectangle1.)
’rectangle2’: Each region is displayed by the smallest surrounding rectangle. (See smallest rectangle2.)
’convex’: Each region is displayed by its convex hull (See convexity.)
’icon’ Each region is displayed by the icon set with set icon in the center of gravity.
Attention
Caution is advised for grayvalue output procedures with output parameter settings that use region
output, e.g. disp image with T set paint(WindowHandle,’histogram’) and set shape
(WindowHandle,’convex’). In that case the convex hull of the grayvalue histogram is displayed.
Parameter
º WindowHandle (input control) ......................................................window long
Window id.
º Shape (input control) ..........................................................string const char *
Region output mode.
Default Value : ’original’
Value List : Shape ¾’original’, ’convex’, ’outer circle’, ’inner circle’, ’rectangle1’, ’rectangle2’, ’ellipse’,
’icon’
Example
read_image(&Image,"fabrik");
regiongrowing(Image,&Seg,5,5,6.0,100);
set_colored(WindowHandle,12);
set_shape(WindowHandle,"rectangle2");
disp_region(Seg,WindowHandle);
Result
set shape returns H MSG TRUE if the parameter is correct and the window is valid. Otherwise an exception
handling is raised.
Parallelization Information
set shape is processed completely exclusively without parallelization.
Possible Predecessor Functions
set icon, T query shape, get shape
disp region
get shape, T query shape, disp region
System
Possible Successor Functions
See Also
Module
HALCON/C Reference Manual / 2000-11-15

4.7. TEXT 253
4.7 Text
get font ( long WindowHandle, char *Font )
Get the current font.
get font queries the name of the font used in the output window. The font is used by the operators
T write string, read string etc. The font is set by the operator set font. Text windows as well as
windows for image display use fonts. Both types of windows have a default font that can be modified with
set system(’default font’,Fontname) prior to opening the window. A list of all available fonts can
be obtained using T query font.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Font (output control) ................................................................string char *
Name of the current font.
Example
get_font(WindowHandle,&CurrentFont) ;
set_font(WindowHandle,MyFont) ;
create_tuple(&String,1) ;
sprintf(buf,"The name of my Font is: %s ",Myfont) ;
set_s(String,buf,0) ;
T_write_string(TupleWindowHandle,String) ;
new_line(WindowHandle) ;
set_font(WindowHandle,CurrentFont) ;
get font returns H MSG TRUE.
Result
Parallelization Information
get font is processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, T query font
set font
Possible Successor Functions
See Also
set font, T query font, open window, open textwindow, set system
System
Module
get string extents ( long WindowHandle, const char *Values,
long *Ascent, long *Descent, long *Width, long *Height )
T get string extents ( Htuple WindowHandle, Htuple Values,
Htuple *Ascent, Htuple *Descent, Htuple *Width, Htuple *Height )
Get the spatial size of a string.
(T )get string extents queries width and height of the output size of a string using the font of the window.
In addition the extension above and below the current baseline for writing is returned (Ascent bzw. Descent).
The sizes are measured in the coordinate system of the window (for text windows in pixels). Using
(T )get string extents it is possible to determine text output and input independently from the used
font. The conversion from integer numbers and floating point numbers to text strings is the same as in
T write string.
HALCON 6.0

254 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Values (input control) ...........................string(-array) (Htuple .) const char * / double / long
Values to consider.
Default Value : ’test string’
º Ascent (output control) ..................................................integer (Htuple .) long *
Maximum height above baseline for writing.
º Descent (output control) .................................................integer (Htuple .) long *
Maximum extension below baseline for writing.
º Width (output control) ....................................................integer (Htuple .) long *
Text width.
º Height (output control) ..................................................integer (Htuple .) long *
Text height.
Result
(T )get string extents returns H MSG TRUE if the window is valid. Otherwise an exception handling is
raised.
Parallelization Information
(T )get string extents is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, set font
Possible Successor Functions
set tposition, T write string, read string, read char
set tposition, set font
System
See Also
Module
get tposition ( long WindowHandle, long *Row, long *Column )
Get cursor position.
get tposition queries the current position of the text cursor in the output window. The position is measured
in the coordinate system of the window (in pixels for text windows). The next output of text in this window starts
at the cursor position. The left end of the baseline for writing the next string (not considering descenders) is placed
on this position. The position is changed by the output or input of text (T write string, read string) or
by an explicit change of position by (set tposition, new line).
Attention
If the output text does not fit completely into the window, an exception handling is raised. This can be avoided by
set check(’˜text’).
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (output control) ................................................................point.y long *
Row index of text cursor position.
º Column (output control) ............................................................point.x long *
Column index of text cursor position.
Result
get tposition returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get tposition is local and processed completely exclusively without parallelization.
HALCON/C Reference Manual / 2000-11-15

4.7. TEXT 255
Possible Predecessor Functions
open window, open textwindow, set font
Possible Successor Functions
set tposition, T write string, read string, read char
See Also
new line, read string, set tposition, T write string, set check
System
Module
get tshape ( long WindowHandle, char *TextCursor )
Get the shape of the text cursor.
get tshape queries the shape of the text cursor for the output window. A new cursor shape is set by the operator
set tshape.
A text cursor marks the current position for text output (which can also be invisible). It is different from the mouse
cursor (although both will be called ”’cursor”’ if the context makes misconceptions impossible). The available
shapes for the text cursor can be queried with T query tshape.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º TextCursor (output control) ........................................................string char *
Name of the current text cursor.
Result
get tshape returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
get tshape is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, set font
Possible Successor Functions
set tshape, set tposition, T write string, read string, read char
See Also
set tshape, T query tshape, T write string, read string
System
Module
new line ( long WindowHandle )
Set the position of the text cursor to the beginning of the next line.
new line sets the position of the text cursor to the beginning of the next line. The new position depends on the
current font. The left end of the baseline for writing the following text string (not considering descenders) is placed
on this position.
If the next line does not fit into the window the content of the window is scrolled by the height of one line in the
upper direction. In order to reach the correct new cursor position the font used in the next line must be set before
new line is called. The position is changed by the output or input of text (T write string, read string)
or by an explicit change of position by (set tposition).
HALCON 6.0

256 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
Result
new line returns H MSG TRUE if the window is valid. Otherwise an exception handling is raised.
Parallelization Information
new line is processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, set font, T write string
Alternatives
get tposition, (T )get string extents, set tposition, (T )move rectangle
T write string, set font
System
See Also
Module
T query font ( Htuple WindowHandle, Htuple *Font )
Query the available fonts.
T query font queries the fonts available for text output in the output window. They can be set with the operator
set font. Fonts are used by the operators T write string, read char, read string and new line.
Attention
For different machines the available fonts may differ a lot. Therefore T query font will return different fonts
on different machines.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º Font (output control) ..................................................string-array Htuple . char *
Tupel with available font names.
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
set_check("˜text") ;
create_tuple(&Fontlist,1) ;
create_tuple(&String,1) ;
create_tuple(&WindowHandleTuple,1) ;
set_i(WindowHandleTuple,WindowHandle,0) ;
T_query_font(WindowHandleTuple,&Fontlist) ;
set_color(WindowHandle,"white") ;
for(i=0; i

4.7. TEXT 257
open window, open textwindow
Possible Predecessor Functions
Possible Successor Functions
set font, T write string, read string, read char
See Also
set font, T write string, read string, read char, new line
System
Module
T query tshape ( Htuple WindowHandle, Htuple *TextCursor )
Query all shapes available for text cursors.
T query tshape queries the available shapes of text cursors for the output window. The retrieved shapes can
be used by the operator set tshape.
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º TextCursor (output control) ..........................................string-array Htuple . char *
Names of the available text cursors.
Result
T query tshape returns H MSG TRUE.
Parallelization Information
T query tshape is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
Possible Successor Functions
set tshape, T write string, read string
See Also
set tshape, get shape, set tposition, T write string, read string
System
Module
read char ( long WindowHandle, char *Char, char *Code )
Read a character from a text window.
read char reads a character from the keyboard in the input window (= output window). If the character is
printable it is returned in Char. If a control key has been pressed, this will be indicated by the value of Code.
Some important keys are recognizable by this value. Possible values are:
’character’: printable character
’left’: cursor left
’right’: cursor right
’up’: cursor up
’down’: cursor down
’insert’: insert
’none’: none of these keys
The window has to be a text window.
Attention
HALCON 6.0

258 CHAPTER 4. GRAPHICS
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Char (output control) ................................................................string char *
Input character (if it is not a control character).
º Code (output control) ................................................................string char *
Code for input character.
Result
read char returns H MSG TRUE if the text window is valid. Otherwise an exception handling is raised.
Parallelization Information
read char is local and processed completely exclusively without parallelization.
open textwindow, set font
Possible Predecessor Functions
Alternatives
read string, fread char, fread string
T write string, set font
System
See Also
Module
read string ( long WindowHandle, const char *InString, long Length,
char *OutString )
Read a string in a text window.
read string reads a string with a predetermined maximum size (Length) from the keyboard in the input
window (= output window). The string is read from the current position of the text cursor using the current font.
The maximum size has to be small enough to keep the string within the right window boundary. A default string
which can be edited or simply accepted by the user may be provided. After text input the text cursor is positioned
at the end of the edited string. Commands for editing:
RETURN finish input
BACKSPACE delete the character on the left side of the cursor and move the cursor to this position.
The window has to be a text window.
Attention
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º InString (input control) ......................................................string const char *
Default string (visible before input).
Default Value : ”
º Length (input control) ...............................................................integer long
Maximum number of characters.
Default Value : 32
Restriction : Length 0
º OutString (output control) .........................................................string char *
Read string.
Result
read string returns H MSG TRUE if the text window is valid and a string of maximal length fits within the
right window boundary. Otherwise an exception handling is raised.
Parallelization Information
read string is local and processed completely exclusively without parallelization.
HALCON/C Reference Manual / 2000-11-15

4.7. TEXT 259
open textwindow, set font
read char, fread string, fread char
Possible Predecessor Functions
Alternatives
See Also
set tposition, new line, open textwindow, set font, (T )set color
System
Module
set font ( long WindowHandle, const char *Font )
Set the font used for text output.
set font sets the font for the output window. The font is used by the operators T write string,
read string etc. Text windows as well as windows for image display use fonts. A default font is assigned
when a window is opened. This font can be changed with set font. On UNIX systems all
available fonts can be queried with T query font. The default font can be modified with set system
(’default font’,Fontname). Fonts are not used for file operations.
The syntax for the specification of a font (in Font) differs for UNIX and Windows NT environments: In Windows
NT a string with the following components is used:
-FontName-Height-Width-Italic-Underlined-Strikeoutwhere
“Italic”, “Underlined”, and “Strikeout” can take the values 1 and 0 to activate or deactivate the corresponding
feature. Please refer to the Windows NT documentation for a detailed discussion.
Attention
For different machines the available fonts may differ a lot. Therefore it is suggested to use wildcards, tables of
fonts and/or the operator T query font.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Font (input control) ............................................................string const char *
Name of new font.
Example
// UNIX
set_font(WindowHandle,"-*-courier-*-*-*-*-18-*-*-*-*-*-*-*") ;
// Windows NT
set_font(WindowHandle,"-Arial-18-*-*-*-*-") ;
write_string(WindowHandle,"Text with Font size of 18 pixels") ;
new_line(WindowHandle) ;
Result
set font returns H MSG TRUE if the font name is correct. Otherwise an exception handling is raised.
Parallelization Information
set font is local and processed completely exclusively without parallelization.
open window, open textwindow
T query font
Possible Predecessor Functions
Possible Successor Functions
See Also
get font, T query font, open textwindow, open window
System
Module
HALCON 6.0

260 CHAPTER 4. GRAPHICS
set tposition ( long WindowHandle, long Row, long Column )
Set the position of the text cursor.
set tposition sets the position of the text cursor in the output window. The reference position is the upper
left corner of an upper case character.
The position is measured in the coordinate system of the window and has to be valid for the window size and font.
The position of the text cursor can be marked e.g. by an underscore. The next text output in this window starts at
the cursor position. The left end of the baseline for writing the following text string (not considering descenders)
is placed on this position.
The position is changed by the output or input of text (T write string, read string) or by an explicit
change of position by (set tposition, new line). In order to stop the display of the cursor, the operator
set tshape with the parameter ”’invisible”’ can be used.
Attention
If a string starting at the given position does not fit into the window an exception handling will be raised. This
exception handling can be avoided by set check(’˜text’).
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (input control) ...................................................................point.y long
Row index of text cursor position.
Default Value : 24
º Column (input control) ...............................................................point.x long
Column index of text cursor position.
Default Value : 12
Result
set tposition returns H MSG TRUE if the window is valid and the values of the parameters are valid. Otherwise
an exception handling is raised.
Parallelization Information
set tposition is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
Possible Successor Functions
set tshape, T write string, read string
new line
Alternatives
See Also
read string, set tshape, T write string
System
Module
set tshape ( long WindowHandle, const char *TextCursor )
Set the shape of the text cursor.
set tshape sets the shape and the display mode of the text cursor of the output window.
A text cursor marks the current position for text output. It is different from the mouse cursor (although both will
be called ’cursor’, if the context makes misconceptions impossible). The available shapes for the text cursor can
be queried with T query tshape.
HALCON/C Reference Manual / 2000-11-15

4.7. TEXT 261
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º TextCursor (input control) ...................................................string const char *
Name of cursor shape.
Default Value : ’invisible’
Result
get tshape returns H MSG TRUE if the window is valid and the given cursor shape is defined for this window.
Otherwise an exception handling is raised.
Parallelization Information
set tshape is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, T query tshape, get tshape
T write string, read string
Possible Successor Functions
See Also
get tshape, T query tshape, T write string, read string
System
Module
T write string ( Htuple WindowHandle, Htuple String )
Printtextinawindow.
T write string prints String in the output window starting at the current cursor position. The output text has
to fit within the right window boundary (the width of the string can be queried by (T )get string extents).
The font currently assigned to the window will used. The text cursor is positioned at the end of the text.
T write string can output all three types of data used in HALCON . The conversion to a string is guided by
the following rules:
¯ strings are not converted.
¯ integer numbers are converted without any spaces before or after the number.
¯ floating numbers are printed (if possible) with a floating point and without an exponent.
¯ the resulting strings are concatenated without spaces.
For buffering of texts see set system with the flag ’flush graphic’.
Attention
If clipping at the window boundary is desired, exceptions can be switched off by set check(’˜text’).
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window identifier.
º String (input control) ..............................string-array Htuple . const char * / long / double
Tuple of output values (all types).
Default Value : ’hello’
Result
T write string returns H MSG TRUE if the window is valid and the output text fits within the current line
(see set check). Otherwise an exception handling is raised.
Parallelization Information
T write string is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, open textwindow, set font, (T )get string extents
HALCON 6.0

262 CHAPTER 4. GRAPHICS
fwrite string
Alternatives
See Also
set tposition, (T )get string extents, open textwindow, set font, set system,
set check
Module
System
4.8 Window
clear rectangle ( long WindowHandle, long Row1, long Column1,
long Row2, long Column2 )
T clear rectangle ( Htuple WindowHandle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2 )
Delete a rectangle on the output window.
(T )clear rectangle deletes all entries in the rectangle which is defined through the upper left corner
(Row1,Column1) and the lower right corner (Row2,Column2). Deletion significates that the specified rectangle
is set to the background color (see open window, open textwindow).
If you want to delete more than one rectangle, you may pass several rectangles, i.e. the parameters Row1,
Column1, Row2 and Column2 are tupel.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Row1 (input control) .......................................rectangle.origin.y(-array) (Htuple .) long
Line index of upper left corner.
Default Value : 10
Typical Range of Values : 0 Row1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column1 (input control) ...................................rectangle.origin.x(-array) (Htuple .) long
Column index of upper left corner.
Default Value : 10
Typical Range of Values : 0 Column1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Row2 (input control) .......................................rectangle.corner.y(-array) (Htuple .) long
Row index of lower right corner.
Default Value : 118
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Row2 Row1
º Column2 (input control) ...................................rectangle.corner.x(-array) (Htuple .) long
Column index of lower right corner.
Default Value : 118
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Column2 Column1
Example
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 263
/* "Interactiv" erase of a rectangle in output window */
draw_rectangle1(WindowHandle,&L1,&C1,&L2,&C2) ;
clear_rectangle(WindowHandle,L1,C1,L2,C2) ;
Result
If an ouputwindow exists and the specified parameters are correct (T )clear rectangle returns
H MSG TRUE. If necessary an exception handling is raised.
Parallelization Information
(T )clear rectangle is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, T set rgb,
T set hsi, draw rectangle1
clear window, (T )disp rectangle1
open window, open textwindow
System
Alternatives
See Also
Module
clear window ( long WindowHandle )
Delete an output window.
clear window deletes all entries in the output window. The window (background and edge) is reset to its
original state. Parameters assigned to this window (e.g. with (T )set color, T set paint, etc.) remain
unmodified.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
clear_window(WindowHandle) ;
Example
Result
If the ouput window is valid clear window returns H MSG TRUE. If necessary an exception handling is raised.
Parallelization Information
clear window is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
Alternatives
(T )clear rectangle, (T )disp rectangle1
open window, open textwindow
System
See Also
Module
close window ( long WindowHandle )
Close an output window.
HALCON 6.0

264 CHAPTER 4. GRAPHICS
close window closes a window which have been opened by open window or by open textwindow. Afterwards
the output device or the window area, respectively, is ready to accept new calls of open window or
open textwindow.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
Result
If the ouput window is valid close window returns H MSG TRUE. If necessary an exception handling is raised.
Parallelization Information
close window is local and processed completely exclusively without parallelization.
open window, open textwindow
open window, open textwindow
System
Possible Predecessor Functions
See Also
Module
copy rectangle ( long WindowHandleSource, long WindowHandleDestination,
long Row1, long Column1, long Row2, long Column2, long DestRow,
long DestColumn )
T copy rectangle ( Htuple WindowHandleSource,
Htuple WindowHandleDestination, Htuple Row1, Htuple Column1, Htuple Row2,
Htuple Column2, Htuple DestRow, Htuple DestColumn )
Copy all pixels within rectangles between output windows.
(T )copy rectangle copies all pixels from the specified window with the logical window
number WindowHandleSource in the specified window with the logical window number
WindowHandleDestination. It copies pixels which reside inside a rectangle which is specified by
parameters Row1, Column1, Row2 and Column2. The target position is specified through the upper left corner
of the rectangle (DestRow, DestColumn).
If you want to move more than one rectangle, you may pass them at once (in form of the tupel mode).
You may use (T )copy rectangle to copy edited graphics from an ”‘invisible”’ window in a visible window.
Therefore a window with the option ’buffer’ is opened. The graphics is then displayed in this window and is
copied in a visible window afterwards. The advantage of this strategy is, that (T )copy rectangle is much
more rapid than output procedures as e.g. (T )disp channel. This means a particular advantage while using
demo programs. You could even realise short ”‘clips”’: you have to create for every image of a sequence a window
of a ’buffer’ type and pass the data into it. Output is the image sequence whereat all buffers are copied one after
another in a visible window.
Attention
Both windows have to reside on the same computer.
Parameter
º WindowHandleSource (input control) ....................................window (Htuple .) long
Number of the source window.
º WindowHandleDestination (input control) .............................window (Htuple .) long
Number of the destination window.
º Row1 (input control) .......................................rectangle.origin.y(-array) (Htuple .) long
Row index of upper left corner in the source window.
Default Value : 0
Typical Range of Values : 0 Row1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 265
º Column1 (input control) ...................................rectangle.origin.x(-array) (Htuple .) long
Column index of upper left corner in the source window.
Default Value : 0
Typical Range of Values : 0 Column1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Row2 (input control) .......................................rectangle.corner.y(-array) (Htuple .) long
Row index of lower right corner in the source window.
Default Value : 128
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Row2 Row1
º Column2 (input control) ...................................rectangle.corner.x(-array) (Htuple .) long
Column index of lower right corner in the source window.
Default Value : 128
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Column2 Column1
º DestRow (input control) .............................................point.y(-array) (Htuple .) long
Row index of upper left corner in the target window.
Default Value : 0
Typical Range of Values : 0 DestRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º DestColumn (input control) .........................................point.x(-array) (Htuple .) long
Column index of upper left corner in the target window.
Default Value : 0
Typical Range of Values : 0 DestColumn 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Example
read_image(Image,"affe") ;
open_window(0,0,-1,-1,"root","buffer","",&WindowHandle) ;
disp_image(Image,WindowHandle) ;
open_window(0,0,-1,-1,"root","visible","",&WindowHandleDestination) ;
do{
get_mbutton(WindowHandleDestination,&Row,&Column,&Button) ;
copy_rectangle(BufferID,WindowHandleDestination,90,120,390,Row,Column) ;
}
while(Button > 1) ;
close_window(WindowHandleDestination) ;
close_window(WindowHandle) ;
clear_obj(Image) ;
Result
If the ouput window is valid and if the specified parameters are correct close window returns H MSG TRUE.
If necessary an exception handling is raised.
Parallelization Information
(T )copy rectangle is local and processed completely exclusively without parallelization.
open window, open textwindow
close window
(T )move rectangle, slide image
Possible Predecessor Functions
Possible Successor Functions
Alternatives
HALCON 6.0

266 CHAPTER 4. GRAPHICS
open window, open textwindow
System
See Also
Module
dump window ( long WindowHandle, const char *Device,
const char *FileName )
T dump window ( Htuple WindowHandle, Htuple Device, Htuple FileName )
Write the window content to a file.
(T )dump window writes the content of the window to a file. You may continue to process this file by convenient
printers or other programs. The content of a display is prepared for each special device (Device), i.e. it is
formated in a manner, that you may print this file directly or it can be processed furthermore by a graphical
program.
To transform gray values the current color table of the window is used, i.e. the values of set lut style remain
unconsidered.
The gray values of the display have in general a poorer resolution then the original gray values of the output images.
This results in a reduced resolution (default setting are e.g. 200 gray levels with 8 bit planes) for the representation
of gray values (see also (T )disp channel). You may request the amount of actual disposable gray levels by
get system. To modify them before opening the first window you may use set system.
Possible values for Device
’postscript’: PostScript - file. Filetermination: FileName.ps
’postscript’,Width,Height: PostScript - file with specification of the output size. Ï Ø and ÀØ refer to the
size. In this case a tupel with three values as Device is passed. Filetermination: FileName.ps
’tiff’: TIFF - file, 1 byte per pixel incl. current color table or 3 bytes per sample (dependent on VGA card),
uncompressed. Filetermination: FileName.tiff
’bmp’: Windows-BMP format, RGB image, 3 bytes per pixel. The color resolution pendends on the VGA card.
File extension: ’.bmp’
’jpeg’ JPEG format, with lost of information; together with the format string the quality value determining the
compression rate can be provided: e.g., ’jpeg 30’.
Attention
Under X Windows, the HALCON window must be completely visible on the root window, because otherwise the
contents of the window cannot be read due to limitations in X Windows. If larger graphical displays are to be
written to a file, the window type ’pixmap’ can be used.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
º Device (input control) ...................................string(-array) (Htuple .) const char * / long
Name of the target device or of the graphic format.
Default Value : ’postscript’
Value List : Device ¾’postscript’, ’tiff’, ’bmp’, ’jpeg’, ”jpeg 100”, ”jpeg 80”, ”jpeg 60”, ”jpeg 40”, ”jpeg
20”
º FileName (input control) ..........................................filename (Htuple .) const char *
File name (without extension).
Default Value : ’halcon dump’
Example
/* PostScript - Dump of Image and Regions */
disp_image(Image,WindowHandle) ;
set_colored(WindowHandle,12) ;
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 267
disp_region(Regions,WindowHandle) ;
dump_window(WindowHandle,"postscript","/tmp/halcon_dump") ;
system_call("lp -d ps /tmp/halcon_dump.ps") ;
Result
If the appropriate window is valid and the specified parameters are correct (T )dump window returns
H MSG TRUE. If necessary an exception handling is raised.
Parallelization Information
(T )dump window is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, open textwindow,
disp region
Possible Successor Functions
system call
See Also
open window, open textwindow, set system
System
Module
get window extents ( long WindowHandle, long *Row, long *Column,
long *Width, long *Height )
Information about a window’s size and position.
get window extents returns the position of the upper left corner, as well as width and height of the output
window.
Attention
Size and position of a window may be modified by the window manager, without explicit instruction in the program.
Therefore the values which are returned by get window extents may change cause of side effects.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (output control) ......................................................rectangle.origin.y long *
Row index of upper left corner of the window.
º Column (output control) ..................................................rectangle.origin.x long *
Column index of upper left corner of the window.
º Width (output control) ...................................................rectangle.extent.x long *
Window width.
º Height (output control) ..................................................rectangle.extent.y long *
Window height.
Example
open_window(100,100,200,200,"root","visible","",&WindowHandle) ;
fwrite_string("Move the window with the mouse!") ;
fnew_line() ;
create_tuple(&String,1) ;
do
{
get_mbutton(WindowHandle,_,_,&Button) ;
get_window_extents(WindowHandle,&Row,&Column,&Width,&Height) ;
sprintf(buf,"Row %d Col %d ",Row,Column) ;
set_s(String,buf,0) ;
T_fwrite_string(String) ;
fnew_line() ;
}
while(Button < 4) ;
HALCON 6.0

268 CHAPTER 4. GRAPHICS
Result
If the window is valid get window extents returns H MSG TRUE. If necessary an exception handling is
raised.
Parallelization Information
get window extents is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, open textwindow
See Also
set window extents, open window, open textwindow
System
Module
get window pointer3 ( long WindowHandle, long *ImageRed,
long *ImageGreen, long *ImageBlue, long *Width, long *Height )
Access to a window’s pixel data.
get window pointer3 enables (in some window systems) the direct access to the bitmap. Result values are
the three pointers on the color extracts of a 24-bit window (ImageRed, ImageGreen, ImageBlue), as well as
the window size (Width, Height). In the language C the type of the image points is unsigned char.
Attention
get window pointer3 is usable only for window type ’pixmap’.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º ImageRed (output control) .........................................................integer long *
Pointer on red channel of pixel data.
º ImageGreen (output control) ......................................................integer long *
Pointer on green channel of pixel data.
º ImageBlue (output control) ........................................................integer long *
Pointer on blue channel of pixel data.
º Width (output control) ............................................................extent.x long *
Length of an image line.
º Height (output control) ...........................................................extent.y long *
Number of image lines.
Result
If a window of type ’pixmap’ exists and it is valid get window pointer3 returns H MSG TRUE. If necessary
an exception handling is raised.
Parallelization Information
get window pointer3 is local and processed completely exclusively without parallelization.
open window, open textwindow
open window, set window type
System
Possible Predecessor Functions
See Also
Module
get window type ( long WindowHandle, char *WindowType )
Get the window type.
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 269
get window type determines the type or the graphical software, respectively, of the output device for the
window. You may query the available types of output devices with procedure T query window type. A
reasonable use for get window type might be in the field of the development of machine independent software.
Possible values are:
’X-Window’ X-Window Version 11.
’pixmap’ Windows are not shown, but managed in memory. By this means Halcon programs can be ported on
computers without a graphical display.
’PostScript’ Objects are output to a PostScript File.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º WindowType (output control) ........................................................string char *
Window type
Example
open_window(100,100,200,200,"root","visible","",&WindowHandle) ;
get_window_type(WindowHandle,&WindowType) ;
fwrite_string("Window type:") ;
sprintf(buf,"%d",WindowType) ;
fwrite_string(buf) ;
fnew_line() ;
Result
If the window is valid get window type returns H MSG TRUE. If necessary an exception handling is raised.
Parallelization Information
get window type is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
See Also
T query window type, set window type, get window pointer3, open window,
open textwindow
Module
System
move rectangle ( long WindowHandle, long Row1, long Column1, long Row2,
long Column2, long DestRow, long DestColumn )
T move rectangle ( Htuple WindowHandle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple DestRow, Htuple DestColumn )
Copy inside an output window.
(T )move rectangle copies all entries in the rectangle (Row1,Column1), (Row2,Column2) of the output
window to a new position inside the same window. This position is determined by the upper left corner (DestRow,
DestColumn). Regions of the window, which are ”‘uncovered”’ through moving the rectangle, are set to the color
of the background.
If you want to move several rectangles at once, you may pass parameters in form of tupels.
Parameter
º WindowHandle (input control) ............................................window (Htuple .) long
Window identifier.
HALCON 6.0

270 CHAPTER 4. GRAPHICS
º Row1 (input control) .......................................rectangle.origin.y(-array) (Htuple .) long
Row index of upper left corner of the source rectangle.
Default Value : 0
Typical Range of Values : 0 Row1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column1 (input control) ...................................rectangle.origin.x(-array) (Htuple .) long
Column index of upper left corner of the source rectangle.
Default Value : 0
Typical Range of Values : 0 Column1 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Row2 (input control) .......................................rectangle.corner.y(-array) (Htuple .) long
Row index of lower right corner of the source rectangle.
Default Value : 64
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column2 (input control) ...................................rectangle.corner.x(-array) (Htuple .) long
Column index of lower right corner of the source rectangle.
Default Value : 64
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º DestRow (input control) .............................................point.y(-array) (Htuple .) long
Row index of upper left corner of the target position.
Default Value : 64
Typical Range of Values : 0 DestRow 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º DestColumn (input control) .........................................point.x(-array) (Htuple .) long
Column index of upper left corner of the target position.
Default Value : 64
Typical Range of Values : 0 DestColumn 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Example
/* "Interactiv" copy of a rectangle in the same window */
draw_rectangle1(WindowHandle,&L1,&C1,&L2,&C2) ;
get_mbutton(WindowHandle,LN,CN,_) ;
move_rectangle(WindowHandle,L1,C1,L2,C2,LN,CN) ;
Result
If the window is valid and the specified parameters are correct (T )move rectangle returns H MSG TRUE.
If necessary an exception handling is raised.
Parallelization Information
(T )move rectangle is local and processed completely exclusively without parallelization.
open window, open textwindow
(T )copy rectangle
open window, open textwindow
System
Possible Predecessor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 271
new extern window ( long WINHWnd, long WINHDC, long Row, long Column,
long Width, long Height, long *WindowHandle )
Create a virtual graphics window under Windows NT.
new extern window opens a new virtual window. Virtual means that a new window will not be created, but the
window whose Windows NT handle is given in the parameter WINHWnd is used to perform output of gray value
data, regions, graphics as well as to perform textual output. Visualization parameters for the output of data can be
done either using Halcon commands or by the appropriate Windows NT commands.
Example: setting of the drawing color:
Halcon:
set\_color(WindowHandle,"green");
disp\_region(WindowHandle,region);
Windows NT:
HPEN* penold;
HPEN penGreen = CreatePen(PS\_SOLID,1,RGB(0,255,0));
pen = (HPEN*)SelectObject(WINHDC,penGreen);
disp\_region(WindowHandle,region);
Interactive operators, for example draw region, draw circle or get mbutton cannot be used in this window.
The following operators can be used:
¯ Output of gray values: T set paint, set comprise, ((T )set lut and set lut style after output)
¯ Regions: (T )set color, T set rgb, T set hsi, (T )set gray, T set pixel, set shape,
set line width, set insert, T set line style, set draw
¯ Image part: set part
¯ Text: set font
You may query current set values by calling procedures like get shape. As some parameters are specified
through the hardware (Resolution/Colors), you may query current available resources by calling operators like
T query color.
The parameter WINHWnd is used to pass the window handle of the Windows NT window, in which output should
be done. The parameter WINHDC is used to pass the device context of the window WINHWnd. This device context
is used in the output routines of Halcon.
The origin of the coordinate system of the window resides in the upper left corner (coordinates: (0,0)). The row
index grows downward (maximum: Height-1), the column index grows to the right (maximal: Width-1).
You may use the value -1 for parameters Width and Height. This means, that the corresponding value is chosen
automatically. In particular, this is important if the aspect ratio of the pixels is not 1.0 (see set system). If one
of the two parameters is set to -1, it will be chosen through the size which results out of the aspect ratio of the
pixels. If both parameters are set to -1, they will be set to the current image format.
The position and size of a window may change during runtime of a program. This may be achieved by calling
set window extents, but also through external influences (window manager). For the latter case the procedure
set window extents is provided.
Opening a window causes the assignment of a default font. It is used in connection with procedures
like T write string and you may change it by performing set font after calling open window.
On the other hand, you have the possibility to specify a default font by calling set system
(’default font’,) before opening a window (and all following windows; see also
T query font).
You may set the color of graphics and font, which is used for output procedures like disp region
or (T )disp circle, by calling T set rgb, T set hsi, (T )set gray or T set pixel. Calling
set insert specifies how graphics is combined with the content of the image repeat memory. Thereto you
may achieve by calling e.g. set insert(::’not’:) to eliminate the font after writing text twice at the same
position.
HALCON 6.0

272 CHAPTER 4. GRAPHICS
The content of the window is not saved, if other windows overlap the window. This must be done in the program
code that handles the Windows NT window in the calling program.
For graphical output (disp image,disp region, etc.) you may adjust the window by calling procedure
set part in order to represent a logical clipping of the image format. In particular this implies that only this part
(appropriately scaled) of images and regions is displayed.
Steps to use new extern window:
Creation: ¯ Create a Windows-window.
¯ Call new extern window whit the WINHWnd of the above created window.
Use: ¯ Before drawing in the window you have to call the method set window dc. This ensures that the halcon
drawing routines use the right DC.
Destroy: ¯ Call close window.
Attention
Note that parameters as Row, Column, Width and Height are constrained through the output device, i.e., the
size of the Windows NT desktop.
Parameter
º WINHWnd (input control) .............................................................integer long
Windows windowhandle of a previously created window.
Restriction : WINHWnd 0
º WINHDC (input control) ...............................................................integer long
Device context of WINHWnd.
Restriction : WINHDC 0
º Row (input control) .........................................................rectangle.origin.y long
Row coordinate of upper left corner.
Default Value : 0
Restriction : Row 0
º Column (input control) .....................................................rectangle.origin.x long
Column coordinate of upper left corner.
Default Value : 0
Restriction : Column 0
º Width (input control) ......................................................rectangle.extent.x long
Width of the window.
Default Value : 512
Restriction : ´Width 0µ ´Width -1µ
º Height (input control) .....................................................rectangle.extent.y long
Height of the window.
Default Value : 512
Restriction : ´Height 0µ ´Height -1µ
º WindowHandle (output control) ...................................................window long *
Window identifier.
HTuple m_tHalconWindow ;
Hobject m_objImage ;
Example
WM_CREATE:
/* here you should create your extern halcon window*/
HTuple tWnd, tDC ;
::set_check("˜father") ;
tWnd = (INT)((INT*)&m_hWnd) ;
tDC = (INT)(INT*)GetWindowDC() ;
::new_extern_window(tWnd, tDC, 0, 0, sizeTotal.cx, sizeTotal.cy, &m_tHalconWindow) ;
::set_check("father") ;
WM_PAINT:
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 273
/* here you can draw halcon objects */
if (m_thWindow != -1) {
/* dont forget to set the dc !! */
HTuple tDC((INT)(INT*)&pDC->m_hDC) ;
::set_window_dc(m_tHalconWindow,tDC) ;
::disp_obj(pDoc->m_objImage, m_tHalconWindow) ;
}
WM_CLOSE:
/* close the halcon window */
if (m_tHalconWindow != -1) {
::close_window(m_tHalconWindow) ;
}
Result
If the values of the specified parameters are correct new extern window returns H MSG TRUE. If necessary,
an exception is raised.
Parallelization Information
new extern window is local and processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )set color, T query window type, get window type, set window type, get mposition,
set tposition, set tshape, set window extents, get window extents, T query color,
set check, set system
open window, open textwindow
Alternatives
See Also
open window, disp region, disp image, disp color, (T )set lut, T query color,
(T )set color, T set rgb, T set hsi, T set pixel, (T )set gray, set part,
set part style, T query window type, get window type, set window type, get mposition,
set tposition, set window extents, get window extents, set window attr, set check,
set system
Module
System
open textwindow ( long Row, long Column, long Width, long Height,
long BorderWidth, const char *BorderColor, const char *BackgroundColor,
long FatherWindow, const char *Mode, const char *Machine,
long *WindowHandle )
Open a textual window.
open textwindow opens a new textual window, which can be used to perform textual input and output, as
well as to perform output of images. All output (T write string, read string, disp region, etc.) is
redirected to this window, if the same logical window number WindowHandle is used.
Besides the mouse cursor textual windows possess also a textual cursor which indicates the current writing position
(more exactly: the lower left corner of the output string without consideration of descenders). Its position is
indicated through an underscore or another type (the indication of this position may also be disabled (= default
setting); cf. set tshape). You may set or query the position by calling the procedures set tposition or
get tposition.
After you opened a textual window the position of the cursor is set to (H,0). Whereby H significates the height of
the default font less the descenders. But the cursor is not shown. Hence the output starts for writing in the upper
left corner of the window.
You may query the colors of the background and the image edges by calling T query color. Inthesameway
you may use T query color in a window of type ’invisible’. During output (T write string) you may set
HALCON 6.0

274 CHAPTER 4. GRAPHICS
the clipping of text out of the window edges by calling set check(::’ text’:). This disables the creation of error
messages, if text passes over the edge of the window.
The origin of the coordinate system of the window resides in the upper left corner (coordinates: (0,0)). The row
index grows downward (maximal: Height-1), the column index grows to the right (maximal: Width-1).
The parameter Machine indicates the name of the computer, which has to open the window. In case of a X-
window, TCP-IP only sets the name, DEC-Net sets in addition a colon behind the name. The ”‘server”’ or the
”‘screen”’, respectively, are not specified. If the empty string is passed the environment variable DISPLAY is
used. It indicates the target computer. At this the name is indicated in common syntax
:0.0
.
Position and size of a window may change during runtime of a program. This may be achieved by calling
set window extents, but also through external interferences (window manager). In the latter case the procedure
set window extents is provided.
Opening a window causes the assignment of a called default font. It is used in connection with
procedures like T write string and you may overwrite it by performing set font after calling
open textwindow. On the other hand you have the possibility to specify a default font by calling
set system(’default font’,) before opening a window (and all following windows; see
also T query font).
You may set the color of the font (T write string, read string) by calling (T )set color,
T set rgb, T set hsi, (T )set gray or T set pixel. Calling set insert specifies how the text or
the graphics, respectively, is combined with the content of the image repeat memory. So you may achieve by
calling e.g. set insert(::’not’:) to eliminate the font after writing text twice at the same position.
Normally every output (e.g. T write string, disp region, (T )disp circle, etc.) in a window is
terminated by a ”‘flush”’. This causes the data to be fully visible on the display after termination of the output
procedure. But this is not necessary in all cases, in particular if there are permanently output tasks or there is a
mouse procedure active. Therefore it is more favorable (i.e. more rapid) to store the data until sufficient data is
available. You may stop this behavior by calling set system(’flush graphic’,’false’).
The content of windows is saved (in case it is supported by special driver software); i.e. it is preserved, also
if the window is hidden by other windows. But this is not necessary in all cases: If you use a textual window
e.g. as a parent window for other windows, you may suppress the security mechanism for it and save the
necessary memory at the same moment. You achieve this before opening the window by calling set system
(’backing store’,’false’).
Difference: graphical window - textual window
¯ In contrast to graphical windows (open window) you may specify more parameters (color, edge) for a
textual window while opening it.
¯ You may use textual windows only for input of user data (read string).
¯ Using textual windows, the output of images, regions and graphics is ”‘clipped”’ at the edges. Whereas
during the use of graphical windows the edges are ”‘zoomed”’.
¯ The coordinate system (e.g. with get mbutton or get mposition) consists of display coordinates
independently of image size. The maximum coordinates are equal to the size of the window minus 1. In
contrast to this, graphical windows (open window) use always a coordinate system, which corresponds to
the image format.
The parameter Mode specifies the mode of the window. It can have following values:
’visible’: Normal mode for textual windows: The window is created according to the parameters and all inputs
and outputs are possible.
’invisible’: Invisible windows are not displayed in the display. Parameters like Row, Column, BorderWidth,
BorderColor, BackgroundColor and FatherWindow do not have any meaning. Output to these
windows has no effect. Input (read string, mouse, etc.) is not possible. You may use these windows to
query representation parameter for an output device without opening a (visible) window. General queries are
e.g. T query color and (T )get string extents.
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 275
’transparent’: These windows are transparent: the window itself is not visible (edge and background), but
all the other operations are possible and all output is displayed. Parameters like BorderColor and
BackgroundColor do not have any meaning. A common use for this mode is the creation of mouse
sensitive regions.
’buffer’: These are also not visible windows. The output of images, regions and graphics is not visible on
the display, but is stored in memory. Parameters like Row, Column, BorderWidth, BorderColor,
BackgroundColor and FatherWindow do not have any meaning. You may use buffer windows, if you
prepare output (in the background) and copy it finally with (T )copy rectangle in a visible window.
Another usage might be the rapid processing of image regions during interactive manipulations. Textual input
and mouse interaction are not possible in this mode.
Attention
You have to keep in mind that parameters like Row, Column, Width and Height are restricted by the output
device. Is a father window (FatherWindow ’root’) specified, then the coordinates are relative to this window.
Parameter
º Row (input control) .........................................................rectangle.origin.y long
Row index of upper left corner.
Default Value : 0
Typical Range of Values : 0 Row (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Row 0
º Column (input control) .....................................................rectangle.origin.x long
Column index of upper left corner.
Default Value : 0
Typical Range of Values : 0 Column (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Column 0
º Width (input control) ......................................................rectangle.extent.x long
Window’s width.
Default Value : 256
Typical Range of Values : 0 Width (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Width 0
º Height (input control) .....................................................rectangle.extent.y long
Window’s height.
Default Value : 256
Typical Range of Values : 0 Height (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Height 0
º BorderWidth (input control) ........................................................integer long
Window border’s width.
Default Value : 2
Typical Range of Values : 0 BorderWidth (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : BorderWidth 0
º BorderColor (input control) ..................................................string const char *
Window border’s color.
Default Value : ’white’
º BackgroundColor (input control) .............................................string const char *
Background color.
Default Value : ’black’
HALCON 6.0

276 CHAPTER 4. GRAPHICS
º FatherWindow (input control) .........................................integer long / const char *
Logical number of the father window. For the display as father you may specify ’root’ or 0.
Default Value : 0
Restriction : FatherWindow 0
º Mode (input control) ............................................................string const char *
Window mode.
Default Value : ’visible’
Value List : Mode ¾’visible’, ’invisible’, ’transparent’, ’buffer’
º Machine (input control) .......................................................string const char *
Computer name, where the window has to be opened or empty string.
Default Value : ”
º WindowHandle (output control) ...................................................window long *
Window identifier.
Example
open_textwindow(0,0,900,600,1,"black","slate blue","root","visible",
"",&WindowHandle1) ;
open_textwindow(10,10,300,580,3,"red","blue",Father,"visible",
"",&WindowHandle2) ;
open_window(10,320,570,580,Father,"visible","",&WindowHandle) ;
set_color(WindowHandle,"red") ;
read_image(&Image,"affe") ;
disp_image(Image,WindowHandle) ;
create_tuple(&String,1) ;
do {
get_mposition(WindowHandle,&Row,&Column,&Button) ;
get_grayval(Image,Row,Column,1,&Gray) ;
sprintf(buf,"Position( %d,%d ) ",Row,Column) ;
set_s(String,buf,0) ;
T_fwrite_string(String) ;
new_line(WindowHandle) ;
}
while(Button < 4) ;
close_window(WindowHandle) ;
clear_obj(Image) ;
Result
If the values of the specified parameters are correct open textwindow returns H MSG TRUE. If necessary an
exception handling is raised.
Parallelization Information
open textwindow is local and processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )set color, T query window type, get window type, set window type, get mposition,
set tposition, set tshape, set window extents, get window extents, T query color,
set check, set system
open window
Alternatives
See Also
T write string, read string, new line, (T )get string extents, get tposition,
(T )set color, T query window type, get window type, set window type, get mposition,
set tposition, set tshape, set window extents, get window extents, T query color,
set check, set system
System
Module
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 277
open window ( long Row, long Column, long Width, long Height,
long FatherWindow, const char *Mode, const char *Machine,
long *WindowHandle )
Open a graphics window.
open window opens a new window, which can be used to perform output of gray value data, regions, graphics as
well as to perform textual output. All output (disp region, disp image, etc.) is redirected to this window, if
the same logical window number WindowHandle is used.
The background of the created window is set to black in advance and it has a white border, which is 2 pixels wide
(see also set window attr(’border width’,).
Certain parameters used for the editing of output data are assigned to a window. These parameters are considered
during the output itself (e.g. with disp image or disp region). They are not specified by an output procedure,
but by ”‘configuration procedures”’. If you want to set e.g. the color red for the output of regions, you have to call
(T )set color(WindowHandle,’red’) before calling disp region. These parameters are always set
for the window with the logical window number WindowHandle and remain assigned to a window as long as
they will be overwritten. You may use the following configuration procedures:
¯ Output of gray values: T set paint, set comprise, ((T )set lut and set lut style after output)
¯ Regions: (T )set color, T set rgb, T set hsi, (T )set gray, T set pixel, set shape,
set line width, set insert, T set line style, set draw
¯ Image clipping: set part
¯ Text: set font
You may query current set values by calling procedures like get shape. As some parameters are
specified through the hardware (Resolution/Colors), you may query current available ressources by calling
T query color.
The origin of the coordinate system of the window resides in the upper left corner (coordinates: (0,0)). The row
index grows downward (maximal: Height-1), the column index grows to the right (maximal: Width-1). You
have to keep in mind, that the range of the coordinate system is independent of the window size. It is specified
only through the image format (see reset obj db).
The parameter Machine indicates the name of the computer, which has to open the window. In case of a X-
window, TCP-IP only sets the name, DEC-Net sets in addition a colon behind the name. The ”‘server”’ resp. the
”‘screen”’ are not specified. If the empty string is passed the environment variable DISPLAY is used. It indicates
the target computer. At this the name is indicated in common syntax
:0.0
.
You may use the value ”‘-1”’ for parameters Width and Height. This means, that the according value has to be
specified automatically. In particular this is of importance, if the proportion of pixels is not 1.0 (see set system):
Is one of the two parameters set to ”‘-1”’, it will be specified through the size which results out of the proportion
of pixels. Are both parameters set to ”‘-1”’, they will be set to the maximum image format, which is currently
used (further information about the currently used maximum image format can be found in the description of
get system using ”‘width”’ or ”‘height”’).
Position and size of a window may change during runtime of a program. This may be achieved by calling
set window extents, but also through external interferences (window manager). In the latter case the procedure
set window extents is provided.
Opening a window causes the assignment of a called default font. It is used in connection with
procedures like T write string and you may overwrite it by performing set font after calling
open window. On the other hand you have the possibility to specify a default font by calling set system
(’default font’,) before opening a window (and all following windows; see also
T query font).
You may set the color of graphics and font, which is used for output procedures like disp region
or (T )disp circle, by calling T set rgb, T set hsi, (T )set gray or T set pixel. Calling
set insert specifies how graphics is combined with the content of the image repeat memory. Thereto you
HALCON 6.0

278 CHAPTER 4. GRAPHICS
may achieve by calling e.g. set insert(::’not’:) to eliminate the font after writing text twice at the same
position.
Normally every output (e.g. disp image, disp region, (T )disp circle, etc.) in a window is terminated
by a called ”‘flush”’. This causes the data to be fully visible on the display after termination of the output procedure.
But this is not necessary in all cases, in particular if there are permanently output tasks or if there is a mouse
procedure active. Therefore it is more favorable (i.e. more rapid) to store the data until sufficient data is available.
You may stop this behavior by calling set system(’flush graphic’,’false’).
The content of windows is saved (in case it is supported by special driver software); i.e. it is preserved, also if the
window is hidden by other windows. But this is not necessary in all cases: If the content of a window is built up
permanently new ((T )copy rectangle), you may suppress the security mechanism for that and hence you
can save the necessary memory. This is done by calling set system(’backing store’,’false’) before
opening a window. In doing so you save not only memory but also time to compute. This is significant for the
output of video clips (see (T )copy rectangle).
For graphical output (disp image,disp region, etc.) you may adjust the window by calling procedure
set part in order to represent a logical clipping of the image format. In particular this implicates that you
obtain this clipping (with appropriate enlargement) of images and regions only.
Difference: graphical window - textual window
¯ Using graphical windows the layout is not as variable as concerned to textual windows.
¯ You may use textual windows for the input of user data only (read string).
¯ During the output of images, regions and graphics a ”‘zooming”’ is performed using graphical windows:
Independent on size and side ratio of the window images are transformed in that way, that they are displayed
in the window by filling it completely. On the opposite side using textual windows the output does not care
about the size of the window (only if clipping is necessary).
¯ Using graphical windows the coordinate system of the window corresponds to the coordinate system of
the image format. Using textual windows, its coordinate system is always equal to the display coordinates
independent on image size.
The parameter Mode determines the mode of the window. It may have following values:
’visible’: Normal mode for graphical windows: The window is created according to the parameters and all input
and output are possible.
’invisible’: Invisible windows are not displayed in the display. Parameters like Row, Column and
FatherWindow do not have any meaning. Output to these windows has no effect. Input (read string,
mouse, etc.) is not possible. You may use these windows to query representation parameter for an
output device without opening a (visible) window. Common queries are e.g. T query color and
(T )get string extents.
’transparent’: These windows are transparent: the window itself is not visible (edge and background), but all
the other operations are possible and all output is displayed. A common use for this mode is the creation of
mouse sensitive regions.
’buffer’: These are also not visible windows. The output of images, regions and graphics is not visible on the
display, but is stored in memory. Parameters like Row, Column and FatherWindow do not have any
meaning. You may use buffer windows, if you prepare output (in the background) and copy it finally with
(T )copy rectangle in a visible window. Another usage might be the rapid processing of image regions
during interactive manipulations. Textual input and mouse interaction are not possible in this mode.
Attention
You may keep in mind that parameters as Row, Column, Width and Height are constrained by the output
device. If you specify a father window (FatherWindow ’root’) the coordinates are relative to this window.
Parameter
º Row (input control) .........................................................rectangle.origin.y long
Row index of upper left corner.
Default Value : 0
Typical Range of Values : 0 Row (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Row 0
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 279
º Column (input control) .....................................................rectangle.origin.x long
Column index of upper left corner.
Default Value : 0
Typical Range of Values : 0 Column (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Column 0
º Width (input control) ......................................................rectangle.extent.x long
Width of the window.
Default Value : 256
Typical Range of Values : 0 Width (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : ´Width 0µ ´Width -1µ
º Height (input control) .....................................................rectangle.extent.y long
Height of the window.
Default Value : 256
Typical Range of Values : 0 Height (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : ´Height 0µ ´Height -1µ
º FatherWindow (input control) .........................................integer long / const char *
Logical number of the father window. To specify the display as father you may enter ’root’ or 0.
Default Value : 0
Restriction : FatherWindow 0
º Mode (input control) ............................................................string const char *
Window mode.
Default Value : ’visible’
Value List : Mode ¾’visible’, ’invisible’, ’transparent’, ’buffer’
º Machine (input control) .......................................................string const char *
Name of the computer on which you want to open the window. Otherwise the empty string.
Default Value : ”
º WindowHandle (output control) ...................................................window long *
Window identifier.
Example
set_system("pixel_ratio",1.53) ;
open_window(0,0,400,-1,"root","visible","",&WindowHandle) ;
read_image(&Image,"fabrik") ;
disp_image(Image,WindowHandle) ;
write_string(WindowHandle,"File: fabrik.ima") ;
new_line(WindowHandle) ;
get_mbutton(WindowHandle,_,_,_) ;
set_lut(WindowHandle,"temperature") ;
set_color(WindowHandle,"blue") ;
write_string(WindowHandle,"temperature") ;
new_line(WindowHandle) ;
write_string(WindowHandle,"Draw Rectangle") ;
new_line(WindowHandle) ;
draw_rectangle1(WindowHandle,&Row1,&Column1,&Row2,&Column2) ;
set_part(Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
new_line(WindowHandle) ;
Result
If the values of the specified parameters are correct open window returns H MSG TRUE. If necessary an exception
handling is raised.
HALCON 6.0

280 CHAPTER 4. GRAPHICS
Parallelization Information
open window is local and processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )set color, T query window type, get window type, set window type, get mposition,
set tposition, set tshape, set window extents, get window extents, T query color,
set check, set system
open textwindow
Alternatives
See Also
disp region, disp image, disp color, (T )set lut, T query color, (T )set color,
T set rgb, T set hsi, T set pixel, (T )set gray, set part, set part style,
T query window type, get window type, set window type, get mposition, set tposition,
set window extents, get window extents, set window attr, set check, set system
System
Module
T query window type ( Htuple *WindowTypes )
Query all available window types.
T query window type returns a tupel which contains all devices or software systems, respectively, which
are used to display image objects. You may use T query window type usefully while developing machine
independent programs. Possible values are:
’X-Window’ X-Window Version 11.
’pixmap’ Windows are not displayed, but managed in memory. In this manner it is possible to port Halcon
programs to computers without graphical display.
’PostScript’ Objects are output to a PostScript File.
Parameter
º WindowTypes (output control) .........................................string-array Htuple . char *
Names of available window types.
Result
T query window type always returns H MSG TRUE.
Parallelization Information
T query window type is local and processed completely exclusively without parallelization.
reset obj db
System
Possible Predecessor Functions
Module
set window attr ( const char *AttributeName,
const char *AttributeValue )
Set window’s characteristics.
You may use set window attr to set specific characteristics of graphical windows. With it you may modify
following default parameters of a window:
’border width’ Width of the window border in pixels.
’border color’ Color of the window border.
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 281
’background color’ Background color of the window.
’window title’ Name of the window in the titlebar.
Attention
You have to call set window attr before calling open window.
Parameter
º AttributeName (input control) ...............................................string const char *
Name of the attribut, which has to be modified.
Value List : AttributeName ¾’border width’, ’border color’, ’background color’, ’window title’
º AttributeValue (input control) ........................................string const char * / long
Value of the attribut, which has to be set.
Value List : AttributeValue ¾0, 1, 2, ’white’, ’black’, ’MyName’, ’default’
Result
If the parameters are correct set window attr returns H MSG TRUE. If necessary an exception handling is
raised.
Parallelization Information
set window attr is reentrant, local, and processed without parallelization.
Possible Predecessor Functions
open window, set draw, (T )set color, set colored, set line width, open textwindow
open window
System
See Also
Module
set window dc ( long WindowHandle, long WINHDC )
Set the device context of a virtual graphics window (Windows NT).
set window dc sets the device context of a window previously opened with new extern window. All output
(disp region, disp image, etc.) is done in the window with this device context.
The parameter WINHDC contains the device context of the window in which Halcon should output its data. This
device context is used in all output routines of Halcon.
Attention
The window WindowHandle has to created with new extern window beforehand.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º WINHDC (input control) ...............................................................integer long
devicecontext of WINHWnd.
Restriction : WINHDC 0
Example
set_system("pixel_ratio",1.53) ;
hWnd = createWINDOW(...) ;
new_extern_window(hwnd, hdc, 0,0,400,-1,WindowHandle) ;
set_device_context(WindowHandle, hdc) ;
read_image(&Image,"fabrik") ;
disp_image(Image,WindowHandle) ;
write_string(WindowHandle,"File: fabrik.ima") ;
new_line(WindowHandle) ;
get_mbutton(WindowHandle,_,_,_) ;
set_lut(WindowHandle,"temperature") ;
HALCON 6.0

282 CHAPTER 4. GRAPHICS
set_color(WindowHandle,"blue") ;
write_string(WindowHandle,"temperature") ;
new_line(WindowHandle) ;
write_string(WindowHandle,"Draw Rectangle") ;
new_line(WindowHandle) ;
draw_rectangle1(WindowHandle,&Row1,&Column1,&Row2,&Column2) ;
set_part(Row1,Column1,Row2,Column2) ;
disp_image(Image,WindowHandle) ;
new_line(WindowHandle) ;
Result
If the values of the specified parameters are correct, set window dc returns H MSG TRUE. If necessary, an
exception is raised.
Parallelization Information
set window dc is local and processed completely exclusively without parallelization.
new extern window
disp image, disp region
Possible Predecessor Functions
Possible Successor Functions
See Also
new extern window, disp region, disp image, disp color, (T )set lut, T query color,
(T )set color, T set rgb, T set hsi, T set pixel, (T )set gray, set part,
set part style, T query window type, get window type, set window type, get mposition,
set tposition, set window extents, get window extents, set window attr, set check,
set system
Module
System
set window extents ( long WindowHandle, long Row, long Column,
long Width, long Height )
Modify position and size of a window.
set window extents positions the upper left corner of the output window at (Row,Column) and changes the
size of the window to Width and Height at the same time.
Attention
If you modify the size of a window an adaptation of the displayed date to the new format is not processed automatically.
This has to be done by the program in performing another output of these data.
Parameter
º WindowHandle (input control) ......................................................window long
Window identifier.
º Row (input control) .........................................................rectangle.origin.y long
Row index of upper left corner in target position.
Default Value : 0
Typical Range of Values : 0 Row (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) .....................................................rectangle.origin.x long
Column index of upper left corner in target position.
Default Value : 0
Typical Range of Values : 0 Column (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON/C Reference Manual / 2000-11-15

4.8. WINDOW 283
º Width (input control) ......................................................rectangle.extent.x long
Width of the window.
Default Value : 512
Typical Range of Values : 0 Width (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Height (input control) .....................................................rectangle.extent.y long
Height of the window.
Default Value : 512
Typical Range of Values : 0 Height (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Result
If the window is valid and the parameters are correct set window extents returns H MSG TRUE. If necessary
an exception handling is raised.
Parallelization Information
set window extents is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
See Also
get window extents, open window, open textwindow
System
Module
set window type ( const char *WindowType )
Specify a window type.
set window type determines on which type of output device the output is going to be displayed. This specification
is going to be used by procedure open window while opening the windows. You may open different
windows on different types of output devices. Therefore you have to specify the wanted type before opening. You
may request the available types of output devices by calling procedure T query window type. Possible values
are:
’X-Window’ X-Window Version 11.
’WIN32-Window’ Microsoft Windows.
’pixmap’ Windows are not displayed, but managed in memory only. In this manner you may port Halcon programs
to computers without graphical display.
’PostScript’ Objects are output to a PostScript File.
A useful usage of set window type could be the development of machine independent programs.
Parameter
º WindowType (input control) ...................................................string const char *
Name of the window type which has to be set.
Default Value : ’X-Window’
Value List : WindowType ¾’X-Window’, ’WIN32-Window’, ’pixmap’, ’PostScript’
Result
If the type of the output device is available, then set window type returns H MSG TRUE. If necessary an
exception handling is raised.
Parallelization Information
set window type is local and processed completely exclusively without parallelization.
open window, open textwindow
Possible Predecessor Functions
HALCON 6.0

284 CHAPTER 4. GRAPHICS
See Also
open window, open textwindow, T query window type, get window type
System
Module
slide image ( long WindowHandleSource1, long WindowHandleSource2,
long WindowHandle )
Interactive output from two window buffers.
slide image divides the window horizontal in two logical areas dependent of the mouse position. The content
of the first indicated window is copied in the upper area, the content of the second window is copied in the lower
area. If you press the left mouse button you may scroll the delimitation between the two areas (you may move
the mouse outside the window, too. In doing so the position of the mouse relative to the window determines the
borderline).
Pressing the right mouse button in the window terminates the procedure slide image.
A useful application of procedure slide image might be the visualisation of the effect of a filtering operation
for an image. The output is directed to the current set window (WindowHandle).
Attention
The three windows must have the same size and have to reside on the same computer.
Parameter
º WindowHandleSource1 (input control) ............................................window long
Logical window number of the ”‘upper window”’.
º WindowHandleSource2 (input control) ............................................window long
Logical window number of the ”‘lower window”’.
º WindowHandle (input control) ......................................................window long
Window identifier.
Example
read_image(&Image,"fabrik") ;
sobel_amp(Image,&Amp,"sum_abs",3) ;
open_window(0,0,-1,-1,"root","buffer","",&WindowHandle) ;
disp_image(Amp,WindowHandle) ;
sobel_dir(Image,&Dir,"sum_abs",3) ;
open_window(0,0,-1,-1,"root","buffer","",&WindowHandle) ;
disp_image(Dir,WindowHandle) ;
open_window(0,0,-1,-1,"root","visible","",&WindowHandle) ;
slide_image(Puffer1,Puffer2,WindowHandle) ;
Result
If the both windows exist and one of these windows is valid slide image returns H MSG TRUE. If necessary
an exception handling is raised.
Parallelization Information
slide image is local and processed completely exclusively without parallelization.
open window, open textwindow
(T )copy rectangle, get mposition
Possible Predecessor Functions
Alternatives
See Also
open window, open textwindow, (T )move rectangle
System
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 5
Image
5.1 Channel
access channel ( Hobject MultiChannelImage, Hobject *Image,
long Channel )
Access a channel of a multichannel image.
The operator access channel accesses a channel of the (multichannel) input image. The result is a one-channel
image. The definition domain of the input is adopted. The channels are numbered from 1 to n. The number of
channels can be determined via the operator (T )count channels.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image Hobject
Multichannel image.
º Image (output object) ..............................................singlechannel-image Hobject *
One channel of MultiChannelImage.
º Channel (input control) .............................................................channel long
Index of channel to be accessed.
Default Value : 1
Value Suggestions : Channel ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Typical Range of Values : 1 Channel
Example
read_image(&Color,"patras"); /* Farbbild einlesen */
access_channel(Color,&Red,1); /* Rotkanal extrahieren */
disp_image(Red,WindowHandle);
Parallelization Information
access channel is reentrant and processed without parallelization.
(T )count channels
disp image
Possible Predecessor Functions
Possible Successor Functions
Alternatives
decompose2, decompose3, decompose4, decompose5
(T )count channels
Image / region / XLD management
See Also
Module
285

286 CHAPTER 5. IMAGE
append channel ( Hobject MultiChannelImage, Hobject Image,
Hobject *ImageExtended )
Append additional matrices (channels) to the image.
The operator append channel appends the matrices of the image Image to the matrices of
MultiChannelImage. The result is an image containing as many matrices (channels) as
MultiChannelImage and Image combined. The definition domain of the ouptput image is calculated
as the average of the definition domains of both input images.
Parameter
º MultiChannelImage (input object) ..............................................image Hobject
Multichannel image.
º Image (input object) ..............................................................image Hobject
Image to be appended.
º ImageExtended (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image Hobject *
Image appended by Image.
Parallelization Information
append channel is reentrant and processed without parallelization.
disp image
Possible Successor Functions
Alternatives
compose2, compose3, compose4, compose5
Image / region / XLD management
Module
channels to image ( Hobject Images, Hobject *MultiChannelImage )
Convert one-channel images into a multichannel image
The operator channels to image converts several one-channel images into a multichannel image. The new
definition domain is the average of the definition domains of the input images.
Parameter
º Images (input object) ..........................................singlechannel-image-array Hobject
One-channel images to be combined into a one-channel image.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image Hobject *
Multichannel image.
Parallelization Information
channels to image is reentrant, local, and processed without parallelization.
Possible Successor Functions
(T )count channels, disp image
Image / region / XLD management
Module
compose2 ( Hobject Image1, Hobject Image2, Hobject *MultiChannelImage )
Convert two images into a two-channel image.
The operator compose2 converts 2 one-channel images into a 2-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
HALCON/C Reference Manual / 2000-11-15

5.1. CHANNEL 287
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose2 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose2
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
compose3 ( Hobject Image1, Hobject Image2, Hobject Image3,
Hobject *MultiChannelImage )
Convert 3 images into a three-channel image.
The operator compose3 converts 3 one-channel images into a 3-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º Image3 (input object) .........................................singlechannel-image(-array) Hobject
Input image 3.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose3 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose3
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
compose4 ( Hobject Image1, Hobject Image2, Hobject Image3,
Hobject Image4, Hobject *MultiChannelImage )
Convert 4 images into a four-channel image.
The operator compose4 converts 4 one-channel images into a 4-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
HALCON 6.0

288 CHAPTER 5. IMAGE
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º Image3 (input object) .........................................singlechannel-image(-array) Hobject
Input image 3.
º Image4 (input object) .........................................singlechannel-image(-array) Hobject
Input image 4.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose4 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose4
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
compose5 ( Hobject Image1, Hobject Image2, Hobject Image3,
Hobject Image4, Hobject Image5, Hobject *MultiChannelImage )
Convert 5 images into a five-channel image.
The operator compose5 converts 5 one-channel images into a 5-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º Image3 (input object) .........................................singlechannel-image(-array) Hobject
Input image 3.
º Image4 (input object) .........................................singlechannel-image(-array) Hobject
Input image 4.
º Image5 (input object) .........................................singlechannel-image(-array) Hobject
Input image 5.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose5 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose5
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

5.1. CHANNEL 289
compose6 ( Hobject Image1, Hobject Image2, Hobject Image3,
Hobject Image4, Hobject Image5, Hobject Image6,
Hobject *MultiChannelImage )
Convert 6 images into a six-channel image.
The operator compose6 converts 6 one-channel images into a 6-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º Image3 (input object) .........................................singlechannel-image(-array) Hobject
Input image 3.
º Image4 (input object) .........................................singlechannel-image(-array) Hobject
Input image 4.
º Image5 (input object) .........................................singlechannel-image(-array) Hobject
Input image 5.
º Image6 (input object) .........................................singlechannel-image(-array) Hobject
Input image 6.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose6 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose6
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
compose7 ( Hobject Image1, Hobject Image2, Hobject Image3,
Hobject Image4, Hobject Image5, Hobject Image6, Hobject Image7,
Hobject *MultiChannelImage )
Convert 7 images into a seven-channel image.
The operator compose7 converts 7 one-channel images into a 7-channel image. The definition domain is calculated
as the intersection of the definition domains of the input images.
Parameter
º Image1 (input object) .........................................singlechannel-image(-array) Hobject
Input image 1.
º Image2 (input object) .........................................singlechannel-image(-array) Hobject
Input image 2.
º Image3 (input object) .........................................singlechannel-image(-array) Hobject
Input image 3.
º Image4 (input object) .........................................singlechannel-image(-array) Hobject
Input image 4.
º Image5 (input object) .........................................singlechannel-image(-array) Hobject
Input image 5.
HALCON 6.0

290 CHAPTER 5. IMAGE
º Image6 (input object) .........................................singlechannel-image(-array) Hobject
Input image 6.
º Image7 (input object) .........................................singlechannel-image(-array) Hobject
Input image 7.
º MultiChannelImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject *
Multichannel image.
Parallelization Information
compose7 is reentrant and automatically parallelized (on tuple level).
disp image
append channel
decompose7
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
count channels ( Hobject MultiChannelImage, long *Channels )
T count channels ( Hobject MultiChannelImage, Htuple *Channels )
Count channels of image.
The operator (T )count channels counts the number of channels of all input images.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
One- or multichannel image.
º Channels (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Number of channels.
Example
read_image(&Color,"patras");
count_channels(Color,&num_channels);
for (i=1; i

5.1. CHANNEL 291
The operator decompose2 converts a 2-channel image into two one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
Parallelization Information
decompose2 is reentrant and automatically parallelized (on tuple level).
(T )count channels
disp image
access channel, image to channels
compose2
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
decompose3 ( Hobject MultiChannelImage, Hobject *Image1,
Hobject *Image2, Hobject *Image3 )
Convert a three-channel image into three images.
The operator decompose3 converts a 3-channel image into three one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
º Image3 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 3.
Parallelization Information
decompose3 is reentrant and automatically parallelized (on tuple level).
(T )count channels
disp image
access channel, image to channels
compose3
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
HALCON 6.0

292 CHAPTER 5. IMAGE
decompose4 ( Hobject MultiChannelImage, Hobject *Image1,
Hobject *Image2, Hobject *Image3, Hobject *Image4 )
Convert a four-channel image into four images.
The operator decompose4 converts a 4-channel image into four one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
º Image3 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 3.
º Image4 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 4.
Parallelization Information
decompose4 is reentrant and automatically parallelized (on tuple level).
(T )count channels
disp image
access channel, image to channels
compose4
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
decompose5 ( Hobject MultiChannelImage, Hobject *Image1,
Hobject *Image2, Hobject *Image3, Hobject *Image4, Hobject *Image5 )
Convert a five-channel image into five images.
The operator decompose5 converts a 5-channel image into five one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
º Image3 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 3.
º Image4 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 4.
º Image5 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 5.
Parallelization Information
decompose5 is reentrant and automatically parallelized (on tuple level).
HALCON/C Reference Manual / 2000-11-15

5.1. CHANNEL 293
Possible Predecessor Functions
(T )count channels
Possible Successor Functions
disp image
Alternatives
access channel, image to channels
See Also
compose5
Module
Image / region / XLD management
decompose6 ( Hobject MultiChannelImage, Hobject *Image1,
Hobject *Image2, Hobject *Image3, Hobject *Image4, Hobject *Image5,
Hobject *Image6 )
Convert a six-channel image into six images.
The operator decompose6 converts a 6-channel image into six one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
º Image3 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 3.
º Image4 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 4.
º Image5 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 5.
º Image6 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 6.
Parallelization Information
decompose6 is reentrant and automatically parallelized (on tuple level).
(T )count channels
disp image
access channel, image to channels
compose6
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
decompose7 ( Hobject MultiChannelImage, Hobject *Image1,
Hobject *Image2, Hobject *Image3, Hobject *Image4, Hobject *Image5,
Hobject *Image6, Hobject *Image7 )
Convert a seven-channel image into seven images.
HALCON 6.0

294 CHAPTER 5. IMAGE
The operator decompose7 converts a 7-channel image into seven one-channel images with the same definition
domain.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject
Multichannel image.
º Image1 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 1.
º Image2 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 2.
º Image3 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 3.
º Image4 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 4.
º Image5 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 5.
º Image6 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 6.
º Image7 (output object) ......................................singlechannel-image(-array) Hobject *
Output image 7.
Parallelization Information
decompose7 is reentrant and automatically parallelized (on tuple level).
(T )count channels
disp image
access channel, image to channels
compose7
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
image to channels ( Hobject MultiChannelImage, Hobject *Images )
Convert a multichannel image into One-channel images
The operator image to channels generates a one-channel image for each channel of the multichannel image
in MultiChannelImage. The definition domains are adopted from the input image. As many images are
created as MultiChannelImage has channels.
Parameter
º MultiChannelImage (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image Hobject
Multichannel image to be decomposed.
º Images (output object) ........................................singlechannel-image-array Hobject *
Generated one-channel images.
Parallelization Information
image to channels is reentrant and processed without parallelization.
(T )count channels
disp image
Possible Predecessor Functions
Possible Successor Functions
Alternatives
access channel, decompose2, decompose3, decompose4, decompose5
HALCON/C Reference Manual / 2000-11-15

5.2. CREATION 295
Image / region / XLD management
Module
5.2 Creation
copy image ( Hobject Image, Hobject *DupImage )
Copy an image and allocate new memory for it.
copy image copies the first channel of the input image into a new (single-channel) image with the same domain
as the imput image. In contrast to HALCON operators such as copy obj, the image is copied into a newly
allocated memory segment. This can be used to modify the gray values of the new image, for example (see
get image pointer1).
Parameter
º Image (input object) ..............................................................image Hobject
Image to be copied.
º DupImage (output object) ........................................................image Hobject *
Copied image.
Parallelization Information
copy image is reentrant and processed without parallelization.
read image, gen image const
Possible Predecessor Functions
Possible Successor Functions
(T )set grayval, get image pointer1
Alternatives
(T )set grayval, paint gray, gen image const, gen image proto
get image pointer1
Basic operators
See Also
Module
gen image1 ( Hobject *Image, const char *Type, long Width, long Height,
long PixelPointer )
Create an image from a pointer to the pixels.
The operator gen image1 creates an image of the size Width ¢ Height. The pixels in PixelPointer are
stored line-sequentially. The type of the given pixels (PixelPointer) must correspond to Type. The storage
for the new image is newly created by HALCON . Thus, the storage on the PixelPointer can be released after
the call. Since the type of the parameter PixelPointer is generic (long) a cast has to be used for the call.
Parameter
º Image (output object) ............................................................image Hobject *
Created image with new image matrix.
º Type (input control) ............................................................string const char *
Pixel type.
Default Value : ’byte’
Value List : Type ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’
HALCON 6.0

296 CHAPTER 5. IMAGE
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
º PixelPointer (input control) ......................................................integer long
Pointer to first gray value.
Example
void NewImage(Hobject *new)
{
unsigned char image[768*525];
int
r,c;
for (r=0; r

5.2. CREATION 297
void ClearProc(void* ptr);
It is called when deleting Image. If the memory shall not be released (in the case of frame grabbers or
static memory) a procedure “without trunk” or the NULL-Pointer can be passed. Analogous to the parameter
PixelPointer the pointer has to be passed to the procedure by casting it to long.
Parameter
º Image (output object) ............................................................image Hobject *
Created HALCON image.
º Type (input control) ............................................................string const char *
Pixel type.
Default Value : ’byte’
Value List : Type ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
º PixelPointer (input control) ......................................................integer long
Pointer to the first gray value.
º ClearProc (input control) ...........................................................integer long
Pointer to the procedure re-releasing the memory of the image when deleting the object.
Default Value : 0
Example
void NewImage(Hobject *new)
{
unsigned char *image;
int
r,c;
image = malloc(640*480);
for (r=0; r

298 CHAPTER 5. IMAGE
gen image1 rect ( Hobject *Image, long PixelPointer, long Width,
long Height, long VerticalPitch, long HorizontalBitPitch,
long BitsPerPixel, const char *DoCopy, long ClearProc )
Create an image with a rectangular domain from a pointer on the pixels (with storage management).
The operator gen image1 rect creates an image of size (Width + VerticalPitch)*Height. The pixels
pointed to by PixelPointer are stored line by line. Since the type of the parameter PixelPointer is generic
(long) a cast must be used for the call. VerticalPitch determines the distance (in pixels) between the last pixel
in row n and the first pixel in row n+1 inside of memory. All rows of the ’input image’ have the same vertical
pitch. The width of the output image equals Width + VerticalPitch. The height of input and output image
are equal. The domain of the output image Image is a rectangle of the size Width * Height. The parameters
HorizontalBitPitch and BitsPerPixel are not supported at the time and have to be passed as default
values.
If DoCopy is set ’true’, the image data pointed to by PixelPointer is copied and memory for the new image is
newly allocated by HALCON . Else the image data is not duplicated and the memory space that PixelPointer
points to must be released when deleting the object Image. This is done by the procedure ClearProc provided
by the caller. This procedure must have the following signature:
void ClearProc(void* ptr);
It is called when deleting Image. If the memory shall not be released (in the case of frame grabbers or
static memory) a procedure ”without trunk” or the NULL-pointer can be passed. Analogously to the parameter
PixelPointer the pointer has to be passed to the procedure by casting it to long. If DoCopy
is ’true’ then ClearProc is irrelevant. The operator gen image1 rect is approximately symmetrical to
get image pointer1 rect.
Parameter
º Image (output object) ............................................................image Hobject *
Created HALCON image.
º PixelPointer (input control) ......................................................integer long
Pointer to the first pixel.
º Width (input control) ...............................................................extent.x long
Width of the image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of the image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
º VerticalPitch (input control) .....................................................integer long
Distance between last pixel in row n and first pixel in row n+1 of the ’input image’.
Restriction : VerticalPitch 0
º HorizontalBitPitch (input control) ..............................................integer long
Distance between two neighbouring pixels in bits .
Default Value : 8
Restriction : HorizontalBitPitch 8
º BitsPerPixel (input control) ......................................................integer long
Number of used bits per pixel.
Default Value : 8
Restriction : BitsPerPixel 8
HALCON/C Reference Manual / 2000-11-15

5.2. CREATION 299
º DoCopy (input control) .........................................................string const char *
Copy image data.
Default Value : ’false’
Value Suggestions : DoCopy ¾’true’, ’false’
º ClearProc (input control) ...........................................................integer long
Pointer to the procedure releasing the memory of the image when deleting the object.
Default Value : 0
void NewImage(Hobject *new)
{
unsigned char *image;
int r,c;
Example
}
image = malloc(640*480);
for (r=0; r

300 CHAPTER 5. IMAGE
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º PixelPointerRed (input control) ..................................................integer long
Pointer to first red value (channel 1).
º PixelPointerGreen (input control) ................................................integer long
Pointer to first green value (channel 2).
º PixelPointerBlue (input control) .................................................integer long
Pointer to first blue value (channel 3).
Example
void NewRGBImage(Hobject *new)
{
unsigned char red[768*525];
unsigned char green[768*525];
unsigned char blue[768*525];
int
r,c;
for (r=0; r

5.2. CREATION 301
See Also
reduce domain, paint gray, paint region, (T )set grayval, get image pointer1,
decompose3
Module
Image / region / XLD management
gen image const ( Hobject *Image, const char *Type, long Width,
long Height )
Create an image with constant gray value.
The operator gen image const creates an image of the indicated size. The height and width of the image are
determined by Height and Width. HALCON supports the following image types:
’byte’ 1 byte per pixel (0..255)
’int1’ 1 byte per pixel (-127..127)
’int2’ 2 bytes per pixel (-32767..32767)
’int4’ 4 bytes per pixel (-2147483647..2147483647)
’real’ 4 bytes per pixel, floating point
’complex’ two matrices of the type real
’dvf’ two matrices of the type int1
’dir’ 1 byte per pixel (0..180)
’cyclic’ 1 byte per pixel; cyclic arithmetics (0..255).
The default value 0 is set via the operator set system(’init new image’,).
Parameter
º Image (output object) ............................................................image Hobject *
Created image with new image matrix.
º Type (input control) ............................................................string const char *
Pixel type.
Default Value : ’byte’
Value List : Type ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’, ’complex’, ’dvf’, ’lut’
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
Example
gen_image_const(&New,"byte",width,height);
get_image_pointer1(New,(long*)&pointer,"byte",width,height);
for (row=0; row

302 CHAPTER 5. IMAGE
Result
If the parameter values are correct, the operator gen image const returns the value H MSG TRUE. Otherwise
an exception handling is raised.
Parallelization Information
gen image const is reentrant and processed without parallelization.
Possible Successor Functions
paint region, reduce domain, get image pointer1, copy obj
gen image1, gen image3
Alternatives
See Also
reduce domain, paint gray, paint region, (T )set grayval, get image pointer1
Image / region / XLD management
Module
gen image gray ramp ( Hobject *ImageGrayRamp, double Alpha,
double Beta, double Mean, long Row, long Column, long Width, long Height )
Create a gray value ramp.
The operator gen image gray ramp creates a gray value ramp according to the following equation:
ÁÑÖÝÊÑÔ ¼´ÖµÐÔ´Ö ÊÓÛµ ·Ø´ ÓÐÙÑÒµ ·ÅÒ
The size of the image is determined by Width and Height The gray values are of the type byte. Grayvalues
outside the valid area are clipped.
Parameter
º ImageGrayRamp (output object) ..........................................image Hobject * : byte
Created image with new image matrix.
º Alpha (input control) .............................................................number double
Gradient in line direction.
Default Value : 1.0
Value Suggestions : Alpha ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Beta (input control) ...............................................................number double
Gradient in column direction.
Default Value : 1.0
Value Suggestions : Beta ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Mean (input control) ...............................................................number double
Mean gray value.
Default Value : 128
Value Suggestions : Mean ¾0, 20, 40, 60, 80, 100, 120, 140, 160, 180, 200, 220, 255
Minimal Value Step : 1
Recommended Value Step : 10
º Row (input control) ...................................................................point.y long
Line index of reference point.
Default Value : 256
Value Suggestions : Row ¾128, 256, 512, 1024
Minimal Value Step : 1
Recommended Value Step : 10
HALCON/C Reference Manual / 2000-11-15

5.2. CREATION 303
º Column (input control) ...............................................................point.x long
Column index of reference point.
Default Value : 256
Value Suggestions : Column ¾128, 256, 512, 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
Result
If the parameter values are correct gen image gray ramp returns the value H MSG TRUE. Otherwise an exception
handling is raised.
Parallelization Information
gen image gray ramp is reentrant and processed without parallelization.
(T )moments gray plane
Possible Predecessor Functions
Possible Successor Functions
paint region, reduce domain, get image pointer1, copy obj
gen image1
reduce domain, paint gray
Image / region / XLD management
Alternatives
See Also
Module
gen image proto ( Hobject Image, Hobject *ImageCleared, double Grayval )
Set the gray values of an image to a specified value.
gen image proto sets the gray values of the image ImageCleared to the value Grayval. The input image
is not modified. It is merely used to determine the size of the output image.
Parameter
º Image (input object) ..............................................................image Hobject
Image, whose gray values are to be cleared.
º ImageCleared (output object) ..................................................image Hobject *
Image with constant gray value.
º Grayval (input control) ....................................................number double / long
Gray value to be used for the output image.
Default Value : 0
Value Suggestions : Grayval ¾0, 1, 2, 5, 10, 16, 32, 64, 128, 253, 254, 255
HALCON 6.0

304 CHAPTER 5. IMAGE
Result
gen image proto returns H MSG TRUE if all parameters are correct. If necessary, an exception is raised.
Parallelization Information
gen image proto is reentrant and processed without parallelization.
test obj def
Possible Predecessor Functions
Alternatives
(T )set grayval, paint gray, gen image const, copy image
get image pointer1
Basic operators
See Also
Module
gen image surface second order ( Hobject *ImageSurface,
const char *Type, double Alpha, double Beta, double Gamma, double Delta,
double Epsilon, double Zeta, double Row, double Col, long Width,
long Height )
Create a curved gray surface with second order polynomial.
The operator gen image surface second order creates a curved gray value surface according to the following
equation:
ÁÑËÙÖ´ÖµÐÔ´Ö ÊÓÛµ££¾·Ø´ Óе££¾·ÑÑ´Ö ÊÓÛµ£´ Óе·ÐØ´Ö ÊÓÛµ·ÐØ´ Óе·Ø
The size of the image is determined by Width and Height. The gray values are of the type Type. Grayvalues
outside the valid area are clipped.
Parameter
º ImageSurface (output object) .......................................image Hobject * : byte / real
Created image with new image matrix.
º Type (input control) ............................................................string const char *
Pixel type.
Default Value : ’byte’
Value List : Type ¾’byte’, ’real’
º Alpha (input control) .............................................................number double
Second order coefficent in line direction.
Default Value : 1.0
Value Suggestions : Alpha ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Beta (input control) ...............................................................number double
Second order coefficent in column direction.
Default Value : 1.0
Value Suggestions : Beta ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Gamma (input control) .............................................................number double
Mixed second order coefficent.
Default Value : 1.0
Value Suggestions : Gamma ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
HALCON/C Reference Manual / 2000-11-15

5.2. CREATION 305
º Delta (input control) .............................................................number double
First order coefficent in line direction.
Default Value : 1.0
Value Suggestions : Delta ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Epsilon (input control) ..........................................................number double
First order coefficent ibn column direction.
Default Value : 1.0
Value Suggestions : Epsilon ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Zeta (input control) ...............................................................number double
Zero order coefficent
Default Value : 1.0
Value Suggestions : Zeta ¾-2.0, -1.0, -0.5, -0.0, 0.5, 1.0, 2.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Row (input control) ................................................................number double
line coordinate of the apex of the surface
Default Value : 256.0
Value Suggestions : Row ¾0.0, 128.0, 256.0, 512.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Col (input control) ................................................................number double
Column coordinate of the apex of the surface
Default Value : 256.0
Value Suggestions : Col ¾0.0, 128.0, 256.0, 512.0
Minimal Value Step : 0.000001
Recommended Value Step : -0.005
º Width (input control) ...............................................................extent.x long
Width of image.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of image.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
Result
If the parameter values are correct gen image surface second order returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
gen image surface second order is reentrant, local, and processed without parallelization.
gen image gray ramp
Image / region / XLD management
See Also
Module
HALCON 6.0

306 CHAPTER 5. IMAGE
get image time ( Hobject Image, long *MSecond, long *Second,
long *Minute, long *Hour, long *Day, long *YDay, long *Month, long *Year )
Request time at which the image was created.
The operator get image time returns the time at which the image was created.
Parameter
º Image (input object) ..............................................................image Hobject
Input image.
º MSecond (output control) ..........................................................integer long *
Milliseconds (0..999).
º Second (output control) ............................................................integer long *
Seconds (0..59).
º Minute (output control) ............................................................integer long *
Minutes (0..59).
º Hour (output control) ...............................................................integer long *
Hours (0..11).
º Day (output control) ................................................................integer long *
Day of the month (1..31).
º YDay (output control) ...............................................................integer long *
Day of the year (1..365).
º Month (output control) .............................................................integer long *
Month (1..12).
º Year (output control) ...............................................................integer long *
Year (xxxx).
Result
The operator get image time returns the value H MSG TRUE if exactly one image was passed. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
get image time is reentrant, local, and processed without parallelization.
read image, grab image
count seconds
Image / region / XLD management
Possible Predecessor Functions
See Also
Module
region to bin ( Hobject Region, Hobject *BinImage, long ForegroundGray,
long BackgroundGray, long Width, long Height )
Convert a region into a binary byte-image.
region to bin converts the input region given in Region into a byte-image and assigns a gray value of
ForegroundGray to all pixels in the region. If the input region is larger than the generated image, it is clipped
at the image borders. The background is set to BackgroundGray.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be converted.
º BinImage (output object) .................................................image Hobject * : byte
Result image of dimension Width ¢ Height containing the converted regions.
HALCON/C Reference Manual / 2000-11-15

5.2. CREATION 307
º ForegroundGray (input control) ....................................................integer long
Gray value in which the regions are displayed.
Default Value : 255
Value Suggestions : ForegroundGray ¾0, 1, 50, 100, 128, 150, 200, 254, 255
Typical Range of Values : 0 ForegroundGray 255 (lin)
Recommended Value Step : 1
º BackgroundGray (input control) ....................................................integer long
Gray value in which the background is displayed.
Default Value : 0
Value Suggestions : BackgroundGray ¾0, 1, 50, 100, 128, 150, 200, 254, 255
Typical Range of Values : 0 BackgroundGray 255 (lin)
Recommended Value Step : 1
º Width (input control) ...............................................................extent.x long
Width of the image to be generated.
Default Value : 512
Value Suggestions : Width ¾256, 512, 1024
Typical Range of Values : 1 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Height of the image to be generated.
Default Value : 512
Value Suggestions : Height ¾256, 512, 1024
Typical Range of Values : 1 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
Restriction : Height 1
Ç´¾ £ ÀØ £ Ïص.
Complexity
Result
region to bin always returns H MSG TRUE. The behavior in case of empty input (no regions given) can be
set via set system(’no object result’,) and the behavior in case of an empty input region
via set system(’empty region result’,). If necessary, an exception handling is raised.
Parallelization Information
region to bin is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )get grayval
Possible Successor Functions
Alternatives
region to label, paint region, (T )set grayval
gen image proto, paint gray
Image / region / XLD management
See Also
Module
region to label ( Hobject Region, Hobject *ImageLabel, const char *Type,
long Width, long Height )
Convert regions to a label image.
region to label converts the input regions into a label image according to their index (½Ò), i.e., the first
region is painted with the gray value 1, the second the gray value 2, etc. Only positive gray values are used. For
byte-images the index is entered modulo 256.
HALCON 6.0

308 CHAPTER 5. IMAGE
Regions larger than the generated image are clipped appropriately. If regions overlap the regions with the higher
image are entered (i.e., they are painted in the order in which they are contained in the input regions). If so desired,
the regions can be made non-overlapping by calling expand region.
The background, i.e., the area not covered by any regions, is set to 0. This can be used to test in which image range
no region is present.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be converted.
º ImageLabel (output object) ....................................image Hobject * : byte / int2 / int4
Result image of dimension Width ¢ Height containing the converted regions.
º Type (input control) ............................................................string const char *
Pixel type of the result image.
Default Value : ’int2’
Value List : Type ¾’byte’, ’int2’, ’int4’
º Width (input control) ...............................................................extent.y long
Width of the image to be generated.
Default Value : 512
Value Suggestions : Width ¾64, 128, 256, 512, 1024
Typical Range of Values : 1 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
Restriction : Width 1
º Height (input control) ..............................................................extent.x long
Height of the image to be generated.
Default Value : 512
Value Suggestions : Height ¾64, 128, 256, 512, 1024
Typical Range of Values : 1 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
Restriction : Height 1
Ç´¾ £ ÀØ £ Ïص.
Complexity
Result
region to label always returns H MSG TRUE. The behavior in case of empty input (no regions given) can be
set via set system(’no object result’,) and the behavior in case of an empty input region
via set system(’empty region result’,). If necessary, an exception handling is raised.
Parallelization Information
region to label is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, expand region
Possible Successor Functions
(T )get grayval, get image pointer1
region to bin, paint region
label to region
Image / region / XLD management
Alternatives
See Also
Module
region to mean ( Hobject Regions, Hobject Image, Hobject *ImageMean )
Paint regions with their average gray value.
HALCON/C Reference Manual / 2000-11-15

5.3. DOMAIN 309
region to mean returns an image in which the regions Regions are painted with their average gray value
basedontheimageImage. This operator is mainly intended to visualize segmentation results.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Input regions.
º Image (input object) .........................................................image Hobject : byte
original gray-value image.
º ImageMean (output object) ................................................image Hobject * : byte
Result image with painted regions.
Example
read_image(&Image,"fabrik");
region_growing(Image,&Regions,3,3,6,100);
region_to_mean(Regions,Image,&Disp);
disp_image(Disp,WindowHandle);
set_draw(WindowHandle,"margin");
set_color(WindowHandle,"black");
disp_region(Regions,WindowHandle);
Result
region to mean returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
region to mean is reentrant and automatically parallelized (on tuple level, channel level).
regiongrowing, connection
disp image
paint region, (T )intensity
Image filters
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
5.3 Domain
add channels ( Hobject Regions, Hobject Image, Hobject *GrayRegions )
Add gray values to regions.
The operator add channels adds the gray values from Image to the regions in Regions. All channels of
Image are adopted. The definition domain is calculated as the average of the definition domain of the image with
the region. Thus the new definition domain can be a subset of the input region. The size of the matrix is not
changed.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Input regions (without gray values).
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image Hobject :any
Gray image for regions.
º GrayRegions (output object) .............................................image(-array) Hobject *
Regions with gray values (also gray images).
Parameter Number : Regions GrayRegions
HALCON 6.0

310 CHAPTER 5. IMAGE
Parallelization Information
add channels is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, gen circle, draw region
Possible Successor Functions
threshold, regiongrowing, get domain
change domain, reduce domain
full domain, get domain, intersection
Image / region / XLD management
Alternatives
See Also
Module
change domain ( Hobject Image, Hobject NewDomain, Hobject *ImageNew )
Change definition domain of an image.
The operator change domain uses the indicated region as new definition domain. Unlike the operator
reduce domain it does not form the intersection of the previous definition domain. This can lead to errors
particularly when the region is larger than the image matrix. The size of the matrix is not changed.
Attention
Due to running time the transferred region is not checked for consistency (i.e., whether it fits with the image
matrix). Incorrect regions lead to system hang-ups during subsequent operations.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input image.
º NewDomain (input object) .........................................................region Hobject
New definition domain.
º ImageNew (output object) .................................................image(-array) Hobject *
Image with new definition domain.
Parallelization Information
change domain is reentrant and automatically parallelized (on tuple level).
get domain
reduce domain
full domain, get domain, intersection
Image / region / XLD management
Possible Predecessor Functions
Alternatives
See Also
Module
full domain ( Hobject Image, Hobject *ImageFull )
Expand the domain of an image to maximum.
The operator full domain enters a rectangle with the edge length of the image as new definition domain. This
means that all pixels of the matrix are included in further operations. Thus the same definition domain is obtained
as by reading or generating an image. The size of the matrix is not changed.
HALCON/C Reference Manual / 2000-11-15

5.3. DOMAIN 311
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input image.
º ImageFull (output object) ...............................................image(-array) Hobject *
Image with maximum definition domain.
Parallelization Information
full domain is reentrant and automatically parallelized (on tuple level).
get domain
change domain, reduce domain
get domain, gen rectangle1
Image / region / XLD management
Possible Predecessor Functions
Alternatives
See Also
Module
get domain ( Hobject Image, Hobject *Domain )
Get the domain of an image.
The operator get domain returns the definition domains of all input images as a region.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input images.
º Domain (output object) ...................................................region(-array) Hobject *
Definition domains of input images.
Parallelization Information
get domain is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
change domain, reduce domain, full domain
See Also
get domain, change domain, reduce domain, full domain
Image / region / XLD management
Module
rectangle1 domain ( Hobject Image, Hobject *ImageReduced, long Row1,
long Column1, long Row2, long Column2 )
Reduce the domain of an image to a rectangle.
The operator rectangle1 domain reduces the definition domain of the given image to the specified rectangle.
The old domain of the input image is ignored. The size of the matrix is not changed.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input image.
º ImageReduced (output object) ...........................................image(-array) Hobject *
Image with reduced definition domain.
º Row1 (input control) ........................................................rectangle.origin.y long
Line index of upper left corner of image area.
Default Value : 100
Value Suggestions : Row1 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Row1 1024
HALCON 6.0

312 CHAPTER 5. IMAGE
º Column1 (input control) ....................................................rectangle.origin.x long
Column index of upper left corner of image area.
Default Value : 100
Value Suggestions : Column1 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Column1 1024
º Row2 (input control) ........................................................rectangle.origin.y long
Line index of lower right corner of image area.
Default Value : 200
Value Suggestions : Row2 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Row2 1024
º Column2 (input control) ....................................................rectangle.origin.x long
Column index of lower right corner of image area.
Default Value : 200
Value Suggestions : Column2 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Column2 1024
Parallelization Information
rectangle1 domain is reentrant and automatically parallelized (on tuple level).
get domain
Possible Predecessor Functions
Alternatives
change domain, reduce domain, add channels
full domain, get domain, intersection
Image / region / XLD management
See Also
Module
reduce domain ( Hobject Image, Hobject Region, Hobject *ImageReduced )
Reduce the domain of an image.
The operator reduce domain reduces the definition domain of the given image to the indicated region. The
new definition domain is calculated as the intersection of the old definition domain with the region. Thus, the new
definition domain can be a subset of the region. The size of the matrix is not changed.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input image.
º Region (input object) .............................................................region Hobject
New definition domain.
º ImageReduced (output object) ...........................................image(-array) Hobject *
Image with reduced definition domain.
Parallelization Information
reduce domain is reentrant and automatically parallelized (on tuple level).
get domain
Possible Predecessor Functions
Alternatives
change domain, rectangle1 domain, add channels
full domain, get domain, intersection
Image / region / XLD management
See Also
Module
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 313
5.4 Features
area center gray ( Hobject Regions, Hobject Image, double *Area,
double *Row, double *Column )
T area center gray ( Hobject Regions, Hobject Image, Htuple *Area,
Htuple *Row, Htuple *Column )
Compute the area and center of gravity of a region in a gray value image.
(T )area center gray computes the area and center of gravity of the regions Regions that have gray values
which are defined by the image Image. This operator is similar to area center, but in contrast to that operator,
the gray values of the image are taken into account while computing the area and center of gravity.
The area of a region Ê in the image with the gray values ´Öµ is defined as
´Öµ¾Ê
´Öµ
This means that the area is defined by the volume of the gray value function ´Öµ. The center of gravity is defined
by the first two normalized moments of the gray values ´Öµ, i.e., by ´Ñ ½¼ Ñ ¼½ µ,where
Ñ ÔÕ ½
´Öµ¾Ê
Parameter
Ö Ô Õ ´Öµ
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Image (input object) . . . . . singlechannel-image Hobject : byte / cyclic / direction / int1 / int2 / int4 / real
Gray value image.
º Area (output control) ...............................................real(-array) (Htuple .) double *
Gray value volume of the region.
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row coordinate of the gray value center of gravity.
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column coordinate of the gray value center of gravity.
Result
(T )area center gray returns H MSG TRUE if all parameters are correct and no error occurs during execution.
If the input is empty the behavior can be set via set system(’no object result’,). If
necessary, an exception handling is raised.
Parallelization Information
(T )area center gray is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
area center
Alternatives
See Also
area center xld, (T )elliptic axis gray
Image filters
Module
HALCON 6.0

314 CHAPTER 5. IMAGE
cooc feature image ( Hobject Regions, Hobject Image, long LdGray,
long Direction, double *Energy, double *Correlation, double *Homogenity,
double *Contrast )
T cooc feature image ( Hobject Regions, Hobject Image, Htuple LdGray,
Htuple Direction, Htuple *Energy, Htuple *Correlation, Htuple *Homogenity,
Htuple *Contrast )
Calculate a co-occurrence matrix and derive gray value features thereof.
The call of (T )cooc feature image corresponds to the consecutive execution of the operators
gen cooc matrix and cooc feature matrix. If several direction matrices of the co-occurrence matrix
are to be evaluated consecutively, it is more efficient to generate the matrix via gen cooc matrix and then
call the operator cooc feature matrix for the resulting matrix. The parameter Direction transfers the
direction of the neighborhood in angle or ’mean’. In the case of ’mean’ the mean value is calculated in all four
directions.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region to be examined.
º Image (input object) .........................................................image Hobject : byte
Corresponding gray values.
º LdGray (input control) .....................................................integer (Htuple .) long
Number of gray values to be distinguished (¾ ÄÖÝ ).
Default Value : 6
Value List : LdGray ¾1, 2, 3, 4, 5, 6, 7, 8
º Direction (input control) ....................................integer (Htuple .) long / const char *
Direction in which the matrix is to be calculated.
Default Value : 0
Value List : Direction ¾0, 45, 90, 135, ’mean’
º Energy (output control) ............................................real(-array) (Htuple .) double *
Gray value energy.
º Correlation (output control) .....................................real(-array) (Htuple .) double *
Correlation of gray values.
º Homogenity (output control) .......................................real(-array) (Htuple .) double *
Local homogenity of gray values.
º Contrast (output control) .........................................real(-array) (Htuple .) double *
Gray value contrast.
Result
The operator (T )cooc feature image returns the value H MSG TRUE if an image with defined gray values
(byte) is entered and the parameters are correct. The behavior in case of empty input (no input images available)
is set via the operator set system(’no object result’,), the behavior in case of empty region
is set via set system(’empty region result’,). If necessary an exception handling is
raised.
Parallelization Information
(T )cooc feature image is reentrant and automatically parallelized (on tuple level).
gen cooc matrix
cooc feature matrix
Possible Predecessor Functions
Alternatives
See Also
(T )intensity, (T )min max gray, (T )entropy gray, (T )select gray
Image filters
Module
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 315
cooc feature matrix ( Hobject CoocMatrix, double *Energy,
double *Correlation, double *Homogenity, double *Contrast )
Calculate gray value features from a co-occurrence matrix.
The procedure calculates from a co-occurence matrix (CoocMatrix) the energy (Energy), correlation
(Correlation), local homogenity (Homogenity) and contrast (Contrast).
The operator cooc feature matrix calculates the gray value features from the part of the input matrix generated
by gen cooc matrix corresponding to the direction matrix indicated by the parameters ÄÖÝ and
ÖØÓÒ according to the following formulae:
Energy:
ÒÖÝ
ÛØ
¾
¼
(Measure for image homogenity)
Correlation:
ÓÖÖÐØÓÒ
È ÛØ
¼ ´ ٠ܵ´ Ù Ý µ
× Ü × Ý
(Measure for gray value dependencies)
Local homogenity:
Contrast:
ÀÓÑÓÒØÝ
ÓÒØÖ×Ø
ÛØ
¼
ÛØ
½
½·´ µ ¾
´ µ ¾
¼
(Measure for the size of the intensity differences)
where
ÛØ Width of CoocMatrix
Entry of co-occurrence matrix
Ù Ü È ÛØ
¼ £
Ù Ý È ÛØ
¼ £
× ¾ Ü È ÛØ
¼ ´ ٠ܵ ¾ £
× ¾ Ý È ÛØ
¼ ´ ٠ݵ ¾ £
The region of the input image is disregarded.
Attention
Parameter
º CoocMatrix (input object) ..................................................image Hobject :int4
Co-occurrence matrix.
º Energy (output control) .............................................................real double *
Homogenity of the gray values.
º Correlation (output control) ......................................................real double *
Correlation of gray values.
º Homogenity (output control) .......................................................real double *
Local homogenity of gray values.
º Contrast (output control) ..........................................................real double *
Gray value contrast.
Result
The operator cooc feature matrix returns the value H MSG TRUE if an image with defined gray values is
passed and the parameters are correct. The behavior in case of empty input (no input images available) is set via the
operator set system(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
cooc feature matrix is reentrant and automatically parallelized (on tuple level).
HALCON 6.0

316 CHAPTER 5. IMAGE
gen cooc matrix
(T )cooc feature image
Possible Predecessor Functions
Alternatives
See Also
(T )intensity, (T )min max gray, (T )entropy gray, (T )select gray
Image filters
Module
elliptic axis gray ( Hobject Regions, Hobject Image, double *Ra,
double *Rb, double *Phi )
T elliptic axis gray ( Hobject Regions, Hobject Image, Htuple *Ra,
Htuple *Rb, Htuple *Phi )
Compute the orientation and major axes of a region in a gray value image.
The operator (T )elliptic axis gray calculates the length of the axes and the orientation of the ellipse
having the “same orientation” and the “aspect ratio” as the input region. Several input regions can be passed in
Regions as tuples. The length of the major axis Ra and the minor axis Rb as well as the orientation of the
major axis with regard to the x-axis (Phi) are determined. The angle is returned in radians. The calculation is
done analogously to elliptic axis. The only difference is that in (T )elliptic axis gray the gray
value moments are used instead of the region moments. The gray value moments are derived from the input image
Image. For the definition of the gray value moments, see (T )area center gray.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Image (input object) . . . . . singlechannel-image Hobject : byte / cyclic / direction / int1 / int2 / int4 / real
Gray value image.
º Ra (output control) ..................................................real(-array) (Htuple .) double *
Major axis of the region.
º Rb (output control) ..................................................real(-array) (Htuple .) double *
Minor axis of the region.
º Phi (output control) ...........................................angle.rad(-array) (Htuple .) double *
Angle enclosed by the major axis and the x-axis.
Result
(T )elliptic axis gray returns H MSG TRUE if all parameters are correct and no error occurs during execution.
If the input is empty the behavior can be set via set system(’no object result’,).
If necessary, an exception handling is raised.
Parallelization Information
(T )elliptic axis gray is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
gen ellipse
elliptic axis
(T )area center gray
Image filters
Possible Successor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 317
entropy gray ( Hobject Regions, Hobject Image, double *Entropy,
double *Anisotropy )
T entropy gray ( Hobject Regions, Hobject Image, Htuple *Entropy,
Htuple *Anisotropy )
Determine the entropy and anisotropy of images.
The operator (T )entropy gray creates the histogram of relative frequencies of the gray values in the input
image and calculates from these frequencies the entropy and the anisotropy coefficient for each region from
Regions according to the following formulae:
Entropy:
ÒØÖÓÔÝ
¾
¼
ÖÐ℄ £ ÐÓ ¾´ÖÐ℄µ
Anisotropy coefficient:
Ò×ÓØÖÓÔÝ
È
¼
ÖÐ℄ £ ÐÓ ¾´ÖÐ℄µ
ÒØÖÓÔÝ
where
ÖÐ℄
= Histogram of relative gray value frequencies
= Gray value of input image ´¼ ¾µ
È
= Smallest possible gray value with
¼
ÖÐ℄ ¼
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions where the features are to be determined.
º Image (input object) .........................................................image Hobject : byte
Gray value image.
º Entropy (output control) ...........................................real(-array) (Htuple .) double *
Information content (entropy) of the gray values.
Assertion : ´0 Entropyµ ´Entropy 8µ
º Anisotropy (output control) .......................................real(-array) (Htuple .) double *
Measure of the symmetry of gray value distribution.
Complexity
If is the area of the region the runtime complexity is Ç´ · ¾µ.
Result
The operator (T )entropy gray returns the value H MSG TRUE if an image with defined gray values is
entered and the parameters are correct. The behavior in case of empty input (no input images available) is set via
the operator set system(’no object result’,), the behavior in case of empty region is set
via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )entropy gray is reentrant and automatically parallelized (on tuple level).
(T )select gray
Alternatives
See Also
entropy image, T gray histo, (T )fuzzy entropy, (T )fuzzy perimeter
Image filters
Module
HALCON 6.0

318 CHAPTER 5. IMAGE
fit surface first order ( Hobject Regions, Hobject Image,
const char *Algorithm, long Iterations, double ClippingFactor,
double *Alpha, double *Beta, double *Gamma )
T fit surface first order ( Hobject Regions, Hobject Image,
Htuple Algorithm, Htuple Iterations, Htuple ClippingFactor, Htuple *Alpha,
Htuple *Beta, Htuple *Gamma )
Calculate gray value moments and approximation by a first order surface (plane).
The operator (T )fit surface first order calculates the gray value moments and the parameters of the
approximation of the gray values by a first order surface. The calculation is done by minimizing the distance
between the gray values and the surface. A first order surface is described by the following formula:
ÁÑ ¼´ÖµÐÔ´Ö Ö ÒØÖµ ·Ø´ ÒØÖµ ·ÑÑ
r center and c center are the coordinates of the center of the input region. By the minimization process the parameters
from Alpha to Gamma is calculated.
The algorithm used for the fitting can be selected via Algorithm:
’regression’ Standard ’least squares’ line fitting.
’huber’ Weighted ’least squares’ fitting, where the impact of outliers is decreased based on the approach of
Huber.
’tukey’ Weighted ’least squares’ fitting, where the impact of outliers is decreased based on the approach of
Tukey.
The parameter ClippingFactor (a scaling factor for the standard deviation) controls the amount of damping
outliers: The smaller the value chosen for ClippingFactor the more outliers are detected. The detection of
outliers is repeated. The parameter Iterations specifies the number of iterations. In the modus ’regression’
this value is ignored.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be checked.
º Image (input object) ...................................................image Hobject : byte / real
Corresponding gray values.
º Algorithm (input control) ...........................................string (Htuple .) const char *
Algorithm for the fitting.
Default Value : ’regression’
Value List : Algorithm ¾’regression’, ’huber’, ’tukey’
º Iterations (input control) ................................................integer (Htuple .) long
Maximum number of iterations (unused for ’regression’).
Default Value : 5
Restriction : Iterations 0
º ClippingFactor (input control) ...........................................real (Htuple .) double
Clipping factor for the elimination of outliers.
Default Value : 2.0
Value List : ClippingFactor ¾1.0, 1.5, 2.0, 2.5, 3.0
Restriction : ClippingFactor 0
º Alpha (output control) .............................................real(-array) (Htuple .) double *
Parameter Alpha of the approximating surface.
º Beta (output control) ...............................................real(-array) (Htuple .) double *
Parameter Beta of the approximating surface.
º Gamma (output control) .............................................real(-array) (Htuple .) double *
Parameter Gamma of the approximating surface.
Result
The operator (T )fit surface second order returns the value H MSG TRUE if an image with the defined
gray values (byte) is entered and the parameters are correct. If necessary an exception handling is raised.
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 319
Parallelization Information
(T )fit surface first order is reentrant and automatically parallelized (on tuple level).
See Also
(T )moments gray plane, (T )fit surface second order
Image filters
Module
fit surface second order ( Hobject Regions, Hobject Image,
const char *Algorithm, long Iterations, double ClippingFactor,
double *Alpha, double *Beta, double *Gamma, double *Delta,
double *Epsilon, double *Zeta )
T fit surface second order ( Hobject Regions, Hobject Image,
Htuple Algorithm, Htuple Iterations, Htuple ClippingFactor, Htuple *Alpha,
Htuple *Beta, Htuple *Gamma, Htuple *Delta, Htuple *Epsilon,
Htuple *Zeta )
Calculate gray value moments and approximation by a second order surface.
The operator (T )fit surface second order calculates the gray value moments and the parameters of the
approximation of the gray values by a second order surface. The calculation is done by minimizing the distance
between the gray values and the surface. A second order surface is described by the following formula:
ÁÑ´ÖµÐÔ´Ö Ö ÒØÖµ££¾·Ø´ ÒØÖµ££¾·ÑÑ´Ö Ö ÒØÖµ£´ ÒØÖµ·ÐØ´Ö Ö ÒØÖµ·ÐØ
r center and c center are the coordinates of the center of the input region. By the minimization process the parameters
from Alpha to Zeta is calculated.
The algorithm used for the fitting can be selected via Algorithm:
’regression’ Standard ’least squares’ fitting.
’huber’ Weighted ’least squares’ fitting, where the impact of outliers is decreased based on the approach of
Huber.
’tukey’ Weighted ’least squares’ fitting, where the impact of outliers is decreased based on the approach of
Tukey.
The parameter ClippingFactor (a scaling factor for the standard deviation) controls the amount of damping
outliers: The smaller the value chosen for ClippingFactor the more outliers are detected. The detection of
outliers is repeated. The parameter Iterations specifies the number of iterations. In the modus ’regression’
this value is ignored.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be checked.
º Image (input object) ...................................................image Hobject : byte / real
Corresponding gray values.
º Algorithm (input control) ...........................................string (Htuple .) const char *
Algorithm for the fitting.
Default Value : ’regression’
Value List : Algorithm ¾’regression’, ’tukey’, ’huber’
º Iterations (input control) ................................................integer (Htuple .) long
Maximum number of iterations (unused for ’regression’).
Default Value : 5
Restriction : Iterations 0
º ClippingFactor (input control) ...........................................real (Htuple .) double
Clipping factor for the elimination of outliers.
Default Value : 2.0
Value List : ClippingFactor ¾1.0, 1.5, 2.0, 2.5, 3.0
Restriction : ClippingFactor 0
HALCON 6.0

320 CHAPTER 5. IMAGE
º Alpha (output control) .............................................real(-array) (Htuple .) double *
Parameter Alpha of the approximating surface.
º Beta (output control) ...............................................real(-array) (Htuple .) double *
Parameter Beta of the approximating surface.
º Gamma (output control) .............................................real(-array) (Htuple .) double *
Parameter Gamma of the approximating surface.
º Delta (output control) .............................................real(-array) (Htuple .) double *
Parameter Deltaa of the approximating surface.
º Epsilon (output control) ...........................................real(-array) (Htuple .) double *
Parameter Epsilon of the approximating surface.
º Zeta (output control) ...............................................real(-array) (Htuple .) double *
Parameter Zeta of the approximating surface.
Result
The operator (T )fit surface second order returns the value H MSG TRUE if an image with the defined
gray values (byte) is entered and the parameters are correct. If necessary an exception handling is raised.
Parallelization Information
(T )fit surface second order is reentrant and automatically parallelized (on tuple level).
See Also
(T )moments gray plane, (T )fit surface first order
Image filters
Module
fuzzy entropy ( Hobject Regions, Hobject Image, long Apar, long Cpar,
double *Entropy )
T fuzzy entropy ( Hobject Regions, Hobject Image, Htuple Apar,
Htuple Cpar, Htuple *Entropy )
Determine the fuzzy entropy of regions.
(T )fuzzy entropy calculates the fuzzy entropy of a fuzzy set. To do so, the image is regarded as a fuzzy set.
The entropy then is a measure of how well the image approximates a white or black image. It is defined as follows:
À´µ
È
½
ÅÆÐÒ¾ Ð Ì ´Ðµ´Ðµ
where Å ¢ Æ is the size of the image, and ´Ðµ is the histogram of the image. Furthermore,
Ì ´Ðµ ´ÐµÐҴе ´½ ´Ðµµ ÐÒ´½ ´Ðµµ
Here, Ù´Ü´Ñ Òµµ is a fuzzy membership function defining the fuzzy set (see (T )fuzzy perimeter). The
same restrictions hold as in (T )fuzzy perimeter.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions for which the fuzzy entropy is to be calculated.
º Image (input object) .........................................................image Hobject : byte
Input image containing the fuzzy membership values.
º Apar (input control) ........................................................integer (Htuple .) long
Start of the fuzzy function.
Default Value : 0
Value Suggestions : Apar ¾0, 5, 10, 20, 50, 100
Typical Range of Values : 0 Apar 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 321
º Cpar (input control) ........................................................integer (Htuple .) long
End of the fuzzy function.
Default Value : 255
Value Suggestions : Cpar ¾50, 100, 150, 200, 220, 255
Typical Range of Values : 0 Cpar 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : Apar Cpar
º Entropy (output control) ...........................................real(-array) (Htuple .) double *
Fuzzy entropy of a region.
Example
/* To find a Fuzzy Entropy from an Image */
read_image(&Image,’affe’) ;
fuzzy_entropy(Trans,Trans,0,255,&Entro) ;
Result
The operator (T )fuzzy entropy returns the value H MSG TRUE if the parameters are correct. Otherwise an
exception is raised.
Parallelization Information
(T )fuzzy entropy is reentrant and automatically parallelized (on tuple level).
(T )fuzzy perimeter
See Also
Bibliography
M.K. Kundu, S.K. Pal: ‘”Automatic selection of object enhancement operator with quantitative justification based
on fuzzy set theoretic measures”; Pattern Recognition Letters 11; 1990; pp. 811-829.
Module
Image filters
fuzzy perimeter ( Hobject Regions, Hobject Image, long Apar, long Cpar,
double *Perimeter )
T fuzzy perimeter ( Hobject Regions, Hobject Image, Htuple Apar,
Htuple Cpar, Htuple *Perimeter )
Calculate the fuzzy perimeter of a region.
The operator (T )fuzzy perimeter is used to determine the differences of fuzzy membership between an
image point and its neighbor points. The right and lower neighbor are taken into account. The fuzzy perimeter is
then defined as follows:
Å ½
Ô´µ
Æ
½
ѽ ҽ
´Ü ÑÒ µ ´Ü ÑÒ·½ µ ·
Å
½
Æ
½
ѽ ҽ
´Ü ÑÒ µ ´Ü Ñ·½Ò µ
where Å ¢ Æ is the size of the image, and Ù´Ü´Ñ Òµµ is the fuzzy membership function (i.e., the input image).
This implementation uses Zadeh’s Standard-S function, which is defined as follows:
´Üµ
¼
¾
Ü
½ ¾
½
¾
Ü
¾
Ü
Ü
Ü
Ü
The parameters , and obey the following restrictions: · is the inflection point of the function, ¡
¾
is the bandwith, and for Ü ´Üµ ¼ holds. In (T )fuzzy perimeter, the parameters
Apar and Cpar are defined as follows: is ÔÖ·ÔÖ .
¾
HALCON 6.0

322 CHAPTER 5. IMAGE
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions for which the fuzzy perimeter is to be calculated.
º Image (input object) .........................................................image Hobject : byte
Input image containing the fuzzy membership values.
º Apar (input control) ........................................................integer (Htuple .) long
Start of the fuzzy function.
Default Value : 0
Value Suggestions : Apar ¾0, 5, 10, 20, 50, 100
Typical Range of Values : 0 Apar 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
º Cpar (input control) ........................................................integer (Htuple .) long
End of the fuzzy function.
Default Value : 255
Value Suggestions : Cpar ¾50, 100, 150, 200, 220, 255
Typical Range of Values : 0 Cpar 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : Apar Cpar
º Perimeter (output control) ........................................real(-array) (Htuple .) double *
Fuzzy perimeter of a region.
Example
/* To find a Fuzzy Entropy from an Image */
read_image(&Image,"affe");
fuzzy_perimeter(Trans,Trans,Apar,Bpar,&Per);
Result
The operator (T )fuzzy perimeter returns the value H MSG TRUE if the parameters are correct. Otherwise
an exception is raised.
Parallelization Information
(T )fuzzy perimeter is reentrant and automatically parallelized (on tuple level).
(T )fuzzy entropy
See Also
Bibliography
M.K. Kundu, S.K. Pal: ‘”Automatic selection of object enhancement operator with quantitative justification based
on fuzzy set theoretic measures”; Pattern Recognition Letters 11; 1990; pp. 811-829.
Module
Image filters
gen cooc matrix ( Hobject Regions, Hobject Image, Hobject *Matrix,
long LdGray, long Direction )
Calculate the co-occurrence matrix of a region in an image.
The operator gen cooc matrix determines from the input regions how often the gray values and are located
next to each other in a certain direction (0, 45, 90, 135 degrees), stores this number in the co-occurrence matrix at
the locations ´ µ and ´ µ (the matrix is symmetrical), and finally scalse the matrix with the number of entries.
LdGray indicates the number of gray values to be distinguished (namely ¾ ÄÖÝ ).
Example (LdGray = 2, i.e. 4 gray values are distinguished):
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 323
Input image
with gray values:
Co-occurrence matrix
(not scaled)
003 2001 0110
112 0220 1011
123 0201 1100
1010 0100
0200 0100
2210 1201
0102 0020
0020 0100
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region to be checked.
º Image (input object) .........................................................image Hobject : byte
Image providing the gray values.
º Matrix (output object) .............................................image(-array) Hobject * :int4
Co-occurrence matrix (matrices).
º LdGray (input control) ...............................................................integer long
Number of gray values to be distinguished (¾ ÄÖÝ ).
Default Value : 6
Value List : LdGray ¾1, 2, 3, 4, 5, 6, 7, 8
Typical Range of Values : 1 LdGray 256 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Direction (input control) ...........................................................integer long
Direction of neighbor relation.
Default Value : 0
Value List : Direction ¾0, 45, 90, 135
Result
The operator gen cooc matrix returns the value H MSG TRUE if an image with defined gray values is entered
and the parameters are correct. The behavior in case of empty input (no input images available) is set via the
operator set system(’no object result’,), the behavior in case of empty region is set via
set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
gen cooc matrix is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
draw region, gen circle, gen ellipse, gen rectangle1, gen rectangle2, threshold,
erosion circle, gauss image, smooth image, sub image
(T )cooc feature image
cooc feature matrix
Image filters
Alternatives
See Also
Module
T gray histo ( Hobject Regions, Hobject Image, Htuple *AbsoluteHisto,
Htuple *RelativeHisto )
Calculate the gray value distribution.
The operator T gray histo calculates for the image (Image) within Regions the absolute
(AbsoluteHisto) and relative (RelativeHisto) histogram of the gray values.
HALCON 6.0

324 CHAPTER 5. IMAGE
Both histograms are tupels of 256 values, which — beginning at 0 — contain the frequencies of the individual gray
values of the image.
AbsoluteHisto indicates the absolute frequencies of the gray values in integers, and RelativeHisto indicates
the relative, i.e. the absolute frequencies divided by the area of the image as floating point numbers.
real-, int2-andint4-images are transformed into byte-images (first the largest and smallest gray value in the image
are determined, and then the original gray values are mapped linearly into the area 0..255) and then processed
as mentioned above. The histogram can also be returned directly as a graphic via the operators set paint
(WindowHandle,’histogram’) and disp image.
Attention
Real, int2 and int4 images are reduced to 256 gray values.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region in which the histogram is to be calculated.
º Image (input object) ...................image Hobject : byte / cyclic / direction / int1 / int2 / int4 / real
Image the gray value distribution of which is to be calculated.
º AbsoluteHisto (output control) ..................................histogram-array Htuple . long *
Absolute frequencies of the gray values.
º RelativeHisto (output control) ................................histogram-array Htuple . double *
Frequencies, normalized to the area of the region.
Complexity
If is the area of the region the runtime complexity is Ç´ · ¾µ.
Result
The operator T gray histo returns the value H MSG TRUE if the image has defined gray values and the
parameters are correct. The behavior in case of empty input (no input images available) is set via the operator
set system(’no object result’,), the behavior in case of empty region is set via
set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T gray histo is reentrant and processed without parallelization.
Possible Successor Functions
histo to thresh, gen region histo
(T )min max gray, (T )intensity
Alternatives
See Also
set paint, disp image, histo 2dim, scale image max, (T )entropy gray
Image filters
Module
T gray projections ( Hobject Region, Hobject Image, Htuple Mode,
Htuple *HorProjection, Htuple *VertProjection )
Calculate horizontal and vertical gray-value projections.
T gray projections calculates the horizontal and vertical gray-value projections.
Parameter
º Region (input object) .............................................................region Hobject
Region to be processed.
º Image (input object) ..............................................................image Hobject
Grayvalues for projections.
º Mode (input control) ....................................................string Htuple . const char *
Type of invariance.
Default Value : ’simple’
Value List : Mode ¾’simple’, ’rectangle’, ’wave’
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 325
º HorProjection (output control) ......................................real-array Htuple . double *
Horizontal projections.
º VertProjection (output control) ....................................real-array Htuple . double *
Vertical projections.
Parallelization Information
T gray projections is reentrant and processed without parallelization.
Image filters
Module
histo 2dim ( Hobject Regions, Hobject ImageCol, Hobject ImageRow,
Hobject *Histo2Dim )
Calculate the histogram of two-channel gray value images.
The operator histo 2dim calculates the 2-dimensional histogram of two images within Regions. The gray
values of channel 1 (ImageCol) are interpreted as row index, those of channel 2 (ImageRow) as column index.
The gray value at one point È ´½¾µ in the output image Histo2Dim indicates the frequency of the gray value
combination (½,¾) with ½ indicating the line index and ¾ the column index.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region in which the histogram is to be calculated.
º ImageCol (input object) ..............................image Hobject : byte / direction / cyclic / int1
Channel 1.
º ImageRow (input object) .....................................................image Hobject : byte
Channel 2.
º Histo2Dim (output object) ................................................image Hobject * :int4
Histogram to be calculated.
Example
read_image(&Image,"affe");
texture_laws(Image,&Texture,"el",1,5);
draw_region(&Region,WindowHandle);
histo_2dim(Region,Texture,Image,&Histo2Dim);
set_part(WindowHandle,0,0,255,255);
disp_image(Histo2Dim,WindowHandle);
Complexity
If is the plane of the region, the runtime complexity is Ç´ · ¾ ¾ µ.
Result
The operator histo 2dim returns the value H MSG TRUE if both images have defined gray values.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
histo 2dim is reentrant and processed without parallelization.
Possible Predecessor Functions
decompose3, decompose2, draw region
Possible Successor Functions
threshold, class 2dim sup, pouring, local max, gray skeleton
T gray histo
(T )get grayval
Image filters
Alternatives
See Also
Module
HALCON 6.0

326 CHAPTER 5. IMAGE
intensity ( Hobject Regions, Hobject Image, double *Mean,
double *Deviation )
T intensity ( Hobject Regions, Hobject Image, Htuple *Mean,
Htuple *Deviation )
Calculate the mean and deviation of gray values.
The operator (T )intensity calculates the mean and the deviation of the gray values in the input image within
Regions. IfÊ is a region, Ô a pixel from Ê with the gray value ´Ôµ and the plane ( Ê), the features are
defined by:
ÅÒ
ÚØÓÒ
È
Ô¾Ê ´Ôµ
× È
Ô¾Ê ´´Ôµ ÅÒµ¾
Attention
The calculation of Deviation does not follow the usual definition if the region of the image contains only one
pixel. In this case 0.0 is returned.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions the features of which are to be calculated.
º Image (input object) ....................................image Hobject : byte / int1 / int2 / int4 / real
Gray value image.
º Mean (output control) ...............................................real(-array) (Htuple .) double *
Mean gray value of a region.
º Deviation (output control) ........................................real(-array) (Htuple .) double *
Deviation of gray values within a region.
Complexity
If is the area of the region, the runtime complexity is Ç´ µ.
Result
The operator (T )intensity returns the value H MSG TRUE. The behavior in case of empty input (no input
images available) is set via the operator set system(’no object result’,), the behavior
in case of empty region is set via set system(’empty region result’,). If necessary an
exception handling is raised.
Parallelization Information
(T )intensity is reentrant and automatically parallelized (on tuple level).
threshold
(T )select gray, (T )min max gray
mean image, mean image, T gray histo
Image filters
Possible Successor Functions
Alternatives
See Also
Module
min max gray ( Hobject Regions, Hobject Image, double Percent,
double *Min, double *Max, double *Range )
T min max gray ( Hobject Regions, Hobject Image, Htuple Percent,
Htuple *Min, Htuple *Max, Htuple *Range )
Determine the minimum and maximum gray values within regions.
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 327
The operator (T )min max gray creates the histogram of the absolute frequencies of the gray values within
Regions in the input image Image (see T gray histo) and calculates the number of pixels Percent corresponding
to the area of the input image. Then it goes inwards on both sides of the histogram by this number of
pixels and determines the smallest and the largest gray value:
e.g.:
Area = 60, percent = 5, i.e. 3 pixels
histogram = [2,8,0,7,13,0,0,. . . ,0,10,10,5,3,1,1]
µ Maximum = 255, Minimum = 0, Range = 255
(T )min max gray returns: Maximum = 253, Minimum = 1, Range = 252
If Percent issetat50,Min = Max = Median. If Percent is 0 no histogram is calculated in order to enhance
the runtime.
Attention
In case of int2, int4- and real-images Percent has to be 0.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions, the features of which are to be calculated.
º Image (input object) ....................................image Hobject : byte / int1 / int2 / int4 / real
Gray value image.
º Percent (input control) ...........................................number (Htuple .) double / long
Percentage below (above) the absolute maximum (minimum).
Default Value : 0
Value Suggestions : Percent ¾0, 1, 2, 5, 7, 10, 15, 20, 30, 40, 50
Restriction : ´0 Percentµ ´Percent 50µ
º Min (output control) ................................................real(-array) (Htuple .) double *
“Minimum” gray value.
º Max (output control) ................................................real(-array) (Htuple .) double *
“Maximum” gray value.
Assertion : Max Min
º Range (output control) .............................................real(-array) (Htuple .) double *
Difference between Max and Min.
Assertion : Range 0
Example
/* Threshold segmentation with training region: */
read_image(&Image,"fabrik");
draw_region(&Region,WindowHandle);
min_max_gray(Region,Image,5.0,&Min,&Max,_);
threshold(Bild,&Seg,Min,Max);
disp_region(Seg,WindowHandle);
Complexity
If is the area of the region the runtime complexity is Ç´ µ if Percent =0,Ç´ · ¾µ otherwise.
Result
The operator (T )min max gray returns the value H MSG TRUE if the input image has the defined gray values
and the parameters are correct. The behavior in case of empty input (no input images available) is set via the
operator set system(’no object result’,). The behaviour in case of an empty region is set
via the operator set system(’empty region result’,). If necessary an exception handling
is raised.
Parallelization Information
(T )min max gray is reentrant and processed without parallelization.
Possible Predecessor Functions
draw region, gen circle, gen ellipse, gen rectangle1, threshold, regiongrowing
threshold
Possible Successor Functions
HALCON 6.0

328 CHAPTER 5. IMAGE
(T )select gray, (T )intensity
Alternatives
See Also
T gray histo, scale image, scale image max, learn ndim norm
Image filters
Module
moments gray plane ( Hobject Regions, Hobject Image, double *MRow,
double *MCol, double *Alpha, double *Beta, double *Mean )
T moments gray plane ( Hobject Regions, Hobject Image, Htuple *MRow,
Htuple *MCol, Htuple *Alpha, Htuple *Beta, Htuple *Mean )
Calculate gray value moments and approximation by a plane.
The operator (T )moments gray plane calculates the gray value moments and the parameters of the approximation
of the gray values by a plane. The calculation is carried out according to the following formula:
ÅÊÓÛ
½
¾
´Öµ¾ÊÓÒ×
´Ö Öµ´ÁÑ´Öµ ÅÒµ ÅÓÐ ½
¾
´Öµ¾ÊÓÒ×
´ µ´ÁÑ´Öµ ÅÒµ
ÐÔ ÅÊÓÛÑ ¼¾ Ñ ½½ ÅÓÐ
Ñ ¾¼ Ñ ¼¾ Ñ ¾ ½½
Ø Ñ ¾¼ÅÓÐ ÅÊÓÛÑ ½½
Ñ ¾¼ Ñ ¼¾ Ñ ¾ ½½
where is the plane, Ö, the center, and Ñ ½½ , Ñ ¾¼ ,andÑ ¼¾ the scaled moments of Regions.
The parameters Alpha, Beta and Mean describe a plane above the region:
ÁÑ ¼´ÖµÐÔ´Ö
Öµ ·Ø´ µ ·ÅÒ
Thus Alpha indicates the gradient in the direction of the line axis (“down”), Beta the gradient in the direction of
the column axis (to the “right”).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be checked.
º Image (input object) ...................................................image Hobject : byte / real
Corresponding gray values.
º MRow (output control) ...............................................real(-array) (Htuple .) double *
Mixed moments along a line.
º MCol (output control) ...............................................real(-array) (Htuple .) double *
Mixed moments along a column.
º Alpha (output control) .............................................real(-array) (Htuple .) double *
Parameter Alpha of the approximating plane.
º Beta (output control) ...............................................real(-array) (Htuple .) double *
Parameter Beta of the approximating plane.
º Mean (output control) ...............................................real(-array) (Htuple .) double *
Mean gray value.
Result
The operator (T )moments gray plane returns the value H MSG TRUE if an image with the defined gray
values (byte) is entered and the parameters are correct. The behavior in case of empty input (no input images
available) is set via the operator set system(’no object result’,), the behavior in case of
emptyregionissetviaset system(’empty region result’,). If necessary an exception
handling is raised.
Parallelization Information
(T )moments gray plane is reentrant and automatically parallelized (on tuple level).
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 329
Possible Predecessor Functions
draw region, gen circle, gen ellipse, gen rectangle1, gen rectangle2, threshold,
regiongrowing
See Also
(T )intensity, moments region 2nd
Bibliography
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, pp 75-76
Image filters
Module
plane deviation ( Hobject Regions, Hobject Image, double *Deviation )
T plane deviation ( Hobject Regions, Hobject Image, Htuple *Deviation )
Calculate the deviation of the gray values from the approximating image plane.
The operator (T )plane deviation calculates the deviation of the gray values in Image from the approximation
of the gray values through a plane. Contrary to the standard deviation in case of (T )intensity
slanted gray value planes also receive the value zero. The gray value plane is calculated according to
gen image gray ramp.
If is the plane, «, ¬, the parameters of the image plane and ´Ö ¼ ¼ µ the center, Deviation is defined by:
ÚØÓÒ
Ö
×ÙÑ´Öµ¾ÊÓÒ×´´«´Ö Ö ¼ µ·¬´ ¼ µ·µ ÁÑ´Öµµ ¾
Attention
It should be noted that the calculation of Deviation does not follow the usual definition. It is defined to return
the value 0.0 for an image with only one pixel.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions, of which the plane deviation is to be calculated.
º Image (input object) .........................................................image Hobject : byte
Gray value image.
º Deviation (output control) ........................................real(-array) (Htuple .) double *
Deviation of the gray values within a region.
Complexity
If is the area of the region the runtime complexity amounts to Ç´ µ.
Result
The operator (T )plane deviation returns the value H MSG TRUE if Image is of the type byte.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )plane deviation is reentrant and automatically parallelized (on tuple level).
Alternatives
(T )intensity, gen image gray ramp, sub image
(T )moments gray plane
Image filters
See Also
Module
HALCON 6.0

330 CHAPTER 5. IMAGE
select gray ( Hobject Regions, Hobject Image, Hobject *SelectedRegions,
const char *Features, const char *Operation, double Min, double Max )
T select gray ( Hobject Regions, Hobject Image,
Hobject *SelectedRegions, Htuple Features, Htuple Operation, Htuple Min,
Htuple Max )
Select regions based on gray value features.
The operator (T )select gray has a number of regions (Regions) as input. For each of these regions the
features (Features) are calculated. If each (Operation = ’and’) or at least one (Operation = ’or’) of the
calculated features is within the limits determined by the parameter, the region is transferred (duplicated) into the
output. The parameter Image contains an image which returns the gray values for calculating the features.
Condition:
ÅÒ ØÙÖ× ´ÊÓÒ× Áѵ ÅÜ
Possble values for Features:
’area’
Gray value volume of region (see (T )area center gray)
’row’
Rowindexofthecenterofgravity(see(T )area center gray)
’column’ Column index of the center of gravity (see (T )area center gray)
’ra’
Major axis of equivallent ellipse (see (T )elliptic axis gray)
’rb’
Minor axis of equivallent ellipse (see (T )elliptic axis gray)
’phi’
Orientation of equivallent ellipse (see (T )elliptic axis gray)
’min’
Minimum gray value (see (T )min max gray)
’max’
Maximum gray value (see (T )min max gray)
’mean’
Mean gray value (see (T )intensity)
’deviation’ Deviationofgrayvalues(see(T )intensity)
’plane deviation’ Deviation from the approximating plane (see (T )plane deviation)
’anisotropy’ Anisotropy (see (T )entropy gray)
’entropy’ Entropy (see (T )entropy gray)
’fuzzy entropy’ Fuzzy entropie of region (see (T )fuzzy entropy, with a fuzzy function from Apar=0 to
Cpar=255)
’fuzzy perimeter’ Fuzzy perimeter of region (see (T )fuzzy perimeter, with a fuzzy function from
Apar=0 to Cpar=255)
’moments row’ Mixed moments along a row (see (T )moments gray plane)
’moments column’ Mixed moments along a column (see (T )moments gray plane)
’alpha’
Approximating plane, parameter Alpha (see (T )moments gray plane)
’beta’
Approximating plane, parameter Beta (see (T )moments gray plane)
Attention
If only one feature is used the value of Operation is meaningless. Several features are processed in the order in
which they are entered.
Parameter
º Regions (input object) ......................................................region-array Hobject
Regions to be examined.
º Image (input object) .........................................image Hobject : byte / int2 / int4 / real
Gray value image.
º SelectedRegions (output object) ........................................region-array Hobject *
Regions having features within the limits.
º Features (input control) ......................................string(-array) (Htuple .) const char *
Names of the features.
Default Value : ’mean’
Value List : Features ¾’area’, ’row’, ’column’, ’ra’, ’rb’, ’phi’, ’min’, ’max’, ’mean’, ’deviation’,
’plane deviation’, ’anisotropy’, ’entropy’, ’fuzzy entropy’, ’fuzzy perimeter’, ’moments row’,
’moments column’, ’alpha’, ’beta’
HALCON/C Reference Manual / 2000-11-15

5.4. FEATURES 331
º Operation (input control) ...........................................string (Htuple .) const char *
Logical connection of features.
Default Value : ’and’
Value List : Operation ¾’and’, ’or’
º Min (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Lower limit(s) of features.
Default Value : 128.0
Value Suggestions : Min ¾0.5, 1.0, 10.0, 20.0, 50.0, 128.0, 255.0, 1000.0
º Max (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Upper limit(s) of features.
Default Value : 255.0
Value Suggestions : Max ¾0.5, 1.0, 10.0, 20.0, 50.0, 128.0, 255.0, 1000.0
Complexity
If is the area of the region and Æ the number of features the runtime complexity is Ç´ £ Æ µ.
Result
The operator (T )select gray returns the value H MSG TRUE if the input image has the defined gray values
and the parameters are correct. The behavior in case of empty input (no input images available) is set via the
operator set system(’no object result’,), the behavior in case of empty region is set via
set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )select gray is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
connection, mean image, entropy image, sobel amp, median separate
Possible Successor Functions
select shape, (T )select gray, shape trans, reduce domain, count obj
See Also
deviation image, (T )entropy gray, (T )intensity, mean image, (T )min max gray,
select obj
Module
Image filters
T shape histo all ( Hobject Region, Hobject Image, Htuple Feature,
Htuple *AbsoluteHisto, Htuple *RelativeHisto )
Determine a histogram of features along all threshold values.
The operator T shape histo all carries out 255 threshold operations within Region with the gray values
of Image. The entry in the histogram corresponds to the number of connected components/holes of this image
segmented with the threshold (Feature = ’connected components’, ’holes’) orthemeanvalueofthe
feature values of the regions segmented in this way (Feature = ’convexity’, ’compactness’, ’ansisometry’),
respectively.
The histogram can also be displayed directly as a graphic via the operators set paint
(WindowHandle,’component histogram’) and disp image.
Attention
The operator T shape histo all expects a region and exactly one gray value image as input. Because of the
power of this operator the runtime of T shape histo all is relatively large!
Parameter
º Region (input object) .............................................................region Hobject
Region in which the features are to be examined.
º Image (input object) .........................................................image Hobject : byte
Gray value image.
º Feature (input control) ...............................................string Htuple . const char *
Feature to be examined.
Default Value : ’connected components’
Value List : Feature ¾’connected components’, ’convexity’, ’compactness’, ’anisometry’, ’holes’
HALCON 6.0

332 CHAPTER 5. IMAGE
º AbsoluteHisto (output control) ........................histogram-array Htuple . double * / long *
Absolute distribution of the feature.
º RelativeHisto (output control) ................................histogram-array Htuple . double *
Relative distribution of the feature.
Example
/* Simulation von shape_histo_all mit Merkmal ’connected_components’: */
my_shape_histo_all(Hobject Region,Hobject Image,
long AbsHisto[], double RelHisto[])
{
long i,sum;
Hobject RegionGray,Seg;
}
reduce_domain(Region,Image,&RegionGray);
for (i=0; i

5.5. FORMAT 333
The histogram can also be displayed directly as a graphic via the operators set paint
(WindowHandle,’component histogram’) and disp image.
Parameter
º Region (input object) .............................................................region Hobject
Region in which the features are to be examined.
º Image (input object) .........................................................image Hobject : byte
Gray value image.
º Feature (input control) ...............................................string Htuple . const char *
Feature to be examined.
Default Value : ’convexity’
Value List : Feature ¾’convexity’, ’compactness’, ’anisometry’, ’holes’
º Row (input control) ...........................................................point.y Htuple . long
Row of the pixel which the region must contain.
Default Value : 256
Value Suggestions : Row ¾10, 50, 100, 200, 300, 400
º Column (input control) .......................................................point.x Htuple . long
Column of the pixel which the region must contain.
Default Value : 256
Value Suggestions : Column ¾10, 50, 100, 200, 300, 400
º AbsoluteHisto (output control) ........................histogram-array Htuple . double * / long *
Absolute distribution of the feature.
º RelativeHisto (output control) ................................histogram-array Htuple . double *
Relative distribution of the feature.
Result
The operator T shape histo point returns the value H MSG TRUE if an image with defined gray values
is entered. The behavior in case of empty input (no input images available) is set via the operator
set system(’no object result’,), the behavior in case of empty region is set via
set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T shape histo point is reentrant and processed without parallelization.
get mbutton, area center
Possible Predecessor Functions
Possible Successor Functions
histo to thresh, threshold, gen region histo
T shape histo all
Alternatives
See Also
connection, connect and holes, convexity, compactness, set paint
Image filters
Module
5.5 Format
change format ( Hobject Image, Hobject *ImagePart, long Width,
long Height )
Change image size.
The operator change format increases or decreases the size of the input images to the indicated height or width,
respectively. If the image is reduced parts are cut off at the “right” or “lower” edge of the image, respectively. If
the image is enlarged the additional areas are set to 0. The definition domain includes all pixels of the new image.
No zooming is carried out.
HALCON 6.0

334 CHAPTER 5. IMAGE
Parameter
º Image (input object) ........................................................image(-array) Hobject
Input image.
º ImagePart (output object) ...............................................image(-array) Hobject *
Image with new format.
º Width (input control) ...............................................................extent.x long
Width of new image.
Default Value : 512
Value Suggestions : Width ¾32, 64, 128, 256, 512, 768, 1024
º Height (input control) ..............................................................extent.y long
Height of new image.
Default Value : 512
Value Suggestions : Height ¾32, 64, 128, 256, 512, 525, 1024
Parallelization Information
change format is reentrant and automatically parallelized (on tuple level).
disp image
crop part
zoom image size, zoom image factor
Image / region / XLD management
Possible Successor Functions
Alternatives
See Also
Module
crop domain ( Hobject Image, Hobject *ImagePart )
Cut out of defined gray values.
The operator crop domain cuts a rectangular area from the input images. This rectangle is the smallest surrounding
rectangle of the domain of the imput image. The new definition domain includes all pixels of the new
image. The new image matrix has the size of the rectangle.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
Input image.
º ImagePart (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject *
Image area.
Parallelization Information
crop domain is reentrant and automatically parallelized (on tuple level).
disp image
Possible Successor Functions
Alternatives
crop part, crop rectangle1, change format, reduce domain
zoom image size, zoom image factor
Image / region / XLD management
See Also
Module
crop part ( Hobject Image, Hobject *ImagePart, long Row, long Column,
long Width, long Height )
Cut out a rectangular image area.
HALCON/C Reference Manual / 2000-11-15

5.5. FORMAT 335
The operator crop part cuts a rectangular area from the input images. The area is indicated by a rectangle
(upper left corner and size). The area must be within the image. The definition domain includes all pixels of the
new image. The new image matrix has the size of a rectangle.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
Input image.
º ImagePart (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject *
Image area.
º Row (input control) .........................................................rectangle.origin.y long
Line index of upper left corner of image area.
Default Value : 100
Value Suggestions : Row ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Row 1024
º Column (input control) .....................................................rectangle.origin.x long
Column index of upper left corner of image area.
Default Value : 100
Value Suggestions : Column ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Column 1024
º Width (input control) ......................................................rectangle.extent.x long
Width of new image.
Default Value : 128
Value Suggestions : Width ¾32, 64, 128, 256, 512, 768
Typical Range of Values : 0 Width 1024
º Height (input control) .....................................................rectangle.extent.y long
Height of new image.
Default Value : 128
Value Suggestions : Height ¾32, 64, 128, 256, 512, 525
Typical Range of Values : 0 Height 1024
Parallelization Information
crop part is reentrant and automatically parallelized (on tuple level).
disp image
Possible Successor Functions
Alternatives
crop rectangle1, crop domain, change format, reduce domain
zoom image size, zoom image factor
Image / region / XLD management
See Also
Module
crop rectangle1 ( Hobject Image, Hobject *ImagePart, long Row1,
long Column1, long Row2, long Column2 )
Cut out a rectangular image area.
The operator crop rectangle1 cuts a rectangular area from the input images. The area is indicated by a
rectangle (upper left and lower right corner). The area must be within the image. The definition domain includes
all pixels of the new image. The new image matrix has the size of a rectangle.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
Input image.
º ImagePart (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject *
Image area.
HALCON 6.0

336 CHAPTER 5. IMAGE
º Row1 (input control) ........................................................rectangle.origin.y long
Line index of upper left corner of image area.
Default Value : 100
Value Suggestions : Row1 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Row1 1024
º Column1 (input control) ....................................................rectangle.origin.x long
Column index of upper left corner of image area.
Default Value : 100
Value Suggestions : Column1 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Column1 1024
º Row2 (input control) .......................................................rectangle.corner.y long
Line index of lower right corner of image area.
Default Value : 200
Value Suggestions : Row2 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Row2 1024
º Column2 (input control) ...................................................rectangle.corner.x long
Column index of lower right corner of image area.
Default Value : 200
Value Suggestions : Column2 ¾10, 20, 50, 100, 200, 300, 500
Typical Range of Values : 0 Column2 1024
Parallelization Information
crop rectangle1 is reentrant and automatically parallelized (on tuple level).
disp image
Possible Successor Functions
Alternatives
crop part, crop domain, change format, reduce domain
zoom image size, zoom image factor
Image / region / XLD management
See Also
Module
tile channels ( Hobject Image, Hobject *TiledImage, long NumColumns,
const char *TileOrder )
Tile multiple images into a large image.
tile channels tiles an image consisting of multiple channels into a large single-channel image. The input
image Image contains Num images of the same size, which are stored in the individual channels. The output
image TiledImage contains a single channel image, where the Num input channels have been tiled into
NumColumns columns. In particular, this means that tile channels cannot tile color images. For this purpose,
tile images can be used. The parameter TileOrder determines the order in which the images are
copied into the output in the cases in which this is not already determined by NumColumns (i.e., if NumColumns
!= 1 and NumColumns != Num). If TileOrder = ’horizontal’ the images are copied in the horizontal direction,
i.e., the second channel of Image will be to the right of the first channel. If TileOrder = ’vertical’ the images
are copied in the vertical direction, i.e., the second channel of Image will be below the first channel. The domain
of TiledImage is obtained by copying the domain of Image to the corresponding locations in the output image.
If Num is not a multiple of NumColumns the output image will have undefined gray values in the lower right
corner of the image. The output domain will reflect this.
Parameter
º Image (input object) multichannel-image(-array) Hobject : byte / int1 / cyclic / direction / int2 / int4 / real
Input image.
º TiledImage (output object) .................................singlechannel-image(-array) Hobject *
Tiled output image.
HALCON/C Reference Manual / 2000-11-15

5.5. FORMAT 337
º NumColumns (input control) .........................................................integer long
Number of columns to use for the output image.
Default Value : 1
Value Suggestions : NumColumns ¾1, 2, 3, 4, 5, 6, 7
º TileOrder (input control) .....................................................string const char *
Order of the input images in the output image.
Default Value : ’vertical’
Value List : TileOrder ¾’horizontal’, ’vertical’
Example
/* Grab 5 single-channel images and stack them vertically. */
gen_rectangle1 (Image, 0, 0, Height-1, Width-1)
for I := 1 to 5 by 1
grab_image_async (ImageGrabbed, FGHandle, -1)
append_channel (Image, ImageGrabbed, Image)
endfor
tile_channels (Image, TiledImage, 1, ’vertical’)
Result
tile channels returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
input is empty the behavior can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
tile channels is reentrant and automatically parallelized (on tuple level).
append channel
tile images, T tile images offset
Possible Predecessor Functions
Alternatives
See Also
change format, crop part, crop rectangle1
Image / region / XLD management
Module
tile images ( Hobject Images, Hobject *TiledImage, long NumColumns,
const char *TileOrder )
Tile multiple image objects into a large image.
tile images tiles multiple input image objects, which must contain the same number of channels, into a large
image. The input image object Images contains Num images, which may be of different size. The output image
TiledImage contains as many channels as the input images. In the output image the Num input images have been
tiled into NumColumns columns. Each tile has the same size, which is determined by the maximum width and
height of all input images. If an input image is smaller than the tile size it is copied to the center of the respective
tile. The parameter TileOrder determines the order in which the images are copied into the output in the cases
in which this is not already determined by NumColumns (i.e., if NumColumns != 1 and NumColumns != Num).
If TileOrder = ’horizontal’ the images are copied in the horizontal direction, i.e., the second image of Images
will be to the right of the first image. If TileOrder = ’vertical’ the images are copied in the vertical direction,
i.e., the second image of Images will be below the first image. The domain of TiledImage is obtained by
copying the domains of Images to the corresponding locations in the output image. If Num is not a multiple of
NumColumns the output image will have undefined gray values in the lower right corner of the image. The output
domain will reflect this.
Parameter
º Images (input object) . .(multichannel-)image-array Hobject : byte / int1 / cyclic / direction / int2 / int4 /
real
Input images.
HALCON 6.0

338 CHAPTER 5. IMAGE
º TiledImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image Hobject *
Tiled output image.
º NumColumns (input control) .........................................................integer long
Number of columns to use for the output image.
Default Value : 1
Value Suggestions : NumColumns ¾1, 2, 3, 4, 5, 6, 7
º TileOrder (input control) .....................................................string const char *
Order of the input images in the output image.
Default Value : ’vertical’
Value List : TileOrder ¾’horizontal’, ’vertical’
Example
/* Grab 5 (multi-channel) images and stack them vertically. */
gen_empty_obj (Images)
for I := 1 to 5 by 1
grab_image_async (ImageGrabbed, FGHandle, -1)
concat_obj (Images, ImageGrabbed, Images)
endfor
tile_images (Images, TiledImage, 1, ’vertical’)
Result
tile images returns H MSG TRUE if all parameters are correct and no error occurs during execution. If the
input is empty the behavior can be set via set system(’no object result’,). If necessary,
an exception handling is raised.
Parallelization Information
tile images is reentrant and automatically parallelized (on channel level).
append channel
tile channels, T tile images offset
Possible Predecessor Functions
Alternatives
See Also
change format, crop part, crop rectangle1
Image / region / XLD management
Module
T tile images offset ( Hobject Images, Hobject *TiledImage,
Htuple OffsetRow, Htuple OffsetCol, Htuple Row1, Htuple Col1, Htuple Row2,
Htuple Col2, Htuple Width, Htuple Height )
Tile multiple image objects into a large image with explicit positioning information.
T tile images offset tiles multiple input image objects, which must contain the same number of channels,
into a large image. The input image object Images contains Num images, which may be of different size. The
output image TiledImage contains as many channels as the input images. The size of the output image is
determined by the parameters Width and Height. The position of the upper left corner of the input images in
the output images is determined by the parameters OffsetRow and OffsetCol. Both parameters must contain
exactly Num values. Optionally, each input image can be cropped to an arbitrary rectangle that is smaller than the
input image. To do so, the parameters Row1, Col1, Row2,andCol2 must be set accordingly. If any of these four
parameters is set to -1, the corresponding input image is not cropped. In any case, all four parameters must contain
Num values. If the input images are cropped the position parameters OffsetRow and OffsetCol refer to the
upper left corner of the cropped image. If the input images overlap each other in the output image (while taking
into account their respective domains), the image with the higher index in Images overwrites the image data of
the image with the lower index. The domain of TiledImage is obtained by copying the domains of Images to
the corresponding locations in the output image.
Attention
If the input images all have the same size and tile the output image exactly, the operator tile images usually
will be slightly faster.
HALCON/C Reference Manual / 2000-11-15

5.5. FORMAT 339
Parameter
º Images (input object) . .(multichannel-)image-array Hobject : byte / int1 / cyclic / direction / int2 / int4 /
real
Input images.
º TiledImage (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image Hobject *
Tiled output image.
º OffsetRow (input control) .............................................point.y-array Htuple . long
Row coordinate of the upper left corner of the input images in the output image.
Default Value : 0
Value Suggestions : OffsetRow ¾0, 50, 100, 150, 200, 250
º OffsetCol (input control) .............................................point.x-array Htuple . long
Column coordinate of the upper left corner of the input images in the output image.
Default Value : 0
Value Suggestions : OffsetCol ¾0, 50, 100, 150, 200, 250
º Row1 (input control) ..........................................rectangle.origin.y-array Htuple . long
Row coordinate of the upper left corner of the copied part of the respective input image.
Default Value : -1
Value Suggestions : Row1 ¾-1, 0, 10, 20, 50, 100, 200, 300, 500
º Col1 (input control) ..........................................rectangle.origin.x-array Htuple . long
Column coordinate of the upper left corner of the copied part of the respective input image.
Default Value : -1
Value Suggestions : Col1 ¾-1, 0, 10, 20, 50, 100, 200, 300, 500
º Row2 (input control) ..........................................rectangle.corner.y-array Htuple . long
Row coordinate of the lower right corner of the copied part of the respective input image.
Default Value : -1
Value Suggestions : Row2 ¾-1, 0, 10, 20, 50, 100, 200, 300, 500
º Col2 (input control) ..........................................rectangle.corner.x-array Htuple . long
Column coordinate of the lower right corner of the copied part of the respective input image.
Default Value : -1
Value Suggestions : Col2 ¾-1, 0, 10, 20, 50, 100, 200, 300, 500
º Width (input control) .......................................................extent.x Htuple . long
Width of the output image.
Default Value : 512
Value Suggestions : Width ¾32, 64, 128, 256, 512, 768, 1024, 2048, 4096
º Height (input control) ......................................................extent.y Htuple . long
Height of the output image.
Default Value : 512
Value Suggestions : Height ¾32, 64, 128, 256, 512, 525, 1024, 2048, 4096
Example
/* Grab 2 (multi-channel) NTSC images, crop the bottom 5 lines off */
/* of each image, the right 5 columns off of the first image, and */
/* the left five lines off of the second image, and put the cropped */
/* images side-by-side. */
gen_empty_obj (Images)
for I := 1 to 2 by 1
grab_image_async (ImageGrabbed, FGHandle, -1)
concat_obj (Images, ImageGrabbed, Images)
endfor
tile_images_offset (Images, TiledImage, [0,635], [0,0], [0,0],
[0,5], [474,474], [634,639])
Result
T tile images offset returns H MSG TRUE if all parameters are correct and no error occurs during execution.
If the input is empty the behavior can be set via set system(’no object result’,). If
necessary, an exception handling is raised.
HALCON 6.0

340 CHAPTER 5. IMAGE
Parallelization Information
T tile images offset is reentrant and automatically parallelized (on channel level).
append channel
tile channels, tile images
Possible Predecessor Functions
Alternatives
See Also
change format, crop part, crop rectangle1
Image / region / XLD management
Module
5.6 Framegrabber
close all framegrabbers ( )
Close all frame grabbers.
The operator close all framegrabbers closes all frame grabbers. It is used to cope with deadlocks resulting
from damaged frame grabber handles (in that case the use of close framegrabber is impossible).
Attention
Since all frame grabbers are closed by close all framegrabbers all frame grabber handles become invalid.
Result
If it is possible to close the frame grabbers the operator close all framegrabbers returns the value
H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
close all framegrabbers is local and processed completely exclusively without parallelization.
grab image
(T )open framegrabber
Image / region / XLD management
Possible Predecessor Functions
See Also
Module
close framegrabber ( long FGHandle )
Close specified frame grabber.
The operator close framegrabber closes the frame grabber specified by FGHandle. In particular possible
storage space for data buffers is released and the frame grabber is made available for other processes.
Parameter
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be closed.
Result
If the frame grabber is open the operator close framegrabber returns the value H MSG TRUE. Otherwise
an exception handling is raised.
Parallelization Information
close framegrabber is local and processed completely exclusively without parallelization.
grab image
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

5.6. FRAMEGRABBER 341
(T )open framegrabber
Image / region / XLD management
See Also
Module
T get framegrabber lut ( Htuple FGHandle, Htuple *ImageRed,
Htuple *ImageGreen, Htuple *ImageBlue )
Query frame grabber lut.
The operator T get framegrabber lut queries the lut of the frame grabber specified by FGHandle. This
operation is not supported for all kinds of frame grabbers.
Parameter
º FGHandle (input control) ..............................................framegrabber Htuple . long
Handle of the desired frame grabber.
º ImageRed (output control) ............................................integer-array Htuple . long *
Red level of the lut entries.
º ImageGreen (output control) .........................................integer-array Htuple . long *
Green level of the lut entries.
º ImageBlue (output control) ..........................................integer-array Htuple . long *
Blue level of the lut entries.
Result
The operator T get framegrabber lut returns the value H MSG TRUE if the frame grabber is open.
Parallelization Information
T get framegrabber lut is reentrant and processed without parallelization.
(T )open framegrabber
T set framegrabber lut
Possible Predecessor Functions
Possible Successor Functions
See Also
T set framegrabber lut, (T )open framegrabber
Image / region / XLD management
Module
get framegrabber param ( long FGHandle, const char *Param,
char *Value )
T get framegrabber param ( Htuple FGHandle, Htuple Param,
Htuple *Value )
Get specific parameters for a frame grabber.
The operator (T )get framegrabber param returns specific parameter values for the frame grabber specified
by FGHandle. The standard parameters listed below are available for all frame grabbers. Additional parameters
may be supported by specific frame grabbers. A list of those can be obtained with the query ’parameter’ via
(T )info framegrabber.
Standard values for Param,see(T )open framegrabber:
’name’ Name of the frame grabber.
’horizontal resolution’ Horizontal resolution of the frame grabber.
’vertical resolution’ Vertical resolution of the frame grabber.
’image width’ Width of the image area.
’image height’ Height of the image area.
HALCON 6.0

342 CHAPTER 5. IMAGE
’start row’ Line number of upper left corner of the image area.
’start column’ Column number of upper left corner of the image area.
’field’ Selected half image or for full image.
’bits per channel’ Number of transferred bits per pixel and image channel.
’color space’ Color images: color space.
’gain’ Amplification factor for video amplifier.
’external trigger’ External triggering (’true’ / ’false’).
’camera type’ Type of used camera (frame grabber specific).
’device’ Device the frame grabber is linked to.
’port’ Port of the frame grabber the video signal is linked to.
’line in’ Camera input line of multiplexer.
Parameter
º FGHandle (input control) ............................................framegrabber (Htuple .) long
Handle of the frame grabber to be used.
º Param (input control) ..........................................string(-array) (Htuple .) const char *
Parameter of interest.
Default Value : ’name’
Value Suggestions : Param ¾’name’, ’horizontal resolution’, ’vertical resolution’, ’image width’,
’image height’, ’start row’, ’start column’, ’field’, ’bits per channel’, ’color space’, ’gain’, ’external trigger’,
’camera type’, ’device’, ’port’, ’line in’
º Value (output control) .............................string(-array) (Htuple .) char * / double * / long *
Parameter value.
Result
If the frame grabber is open and the specified parameter is supported by the frame grabber, the operator
(T )get framegrabber param returns the value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )get framegrabber param is reentrant and processed without parallelization.
(T )open framegrabber
Possible Predecessor Functions
Possible Successor Functions
grab image, grab region, grab image start, grab image async, grab region async,
close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )set framegrabber param
Image / region / XLD management
Module
grab image ( Hobject *Image, long FGHandle )
Grab an image from the specified frame grabber.
The operator grab image grabs an image via the frame grabber specified by FGHandle. The desired
operational mode of the frame grabber as well as a suitable image area can be adjusted via the
operator (T )open framegrabber. Additional (frame grabber specific) settings might be possible via
(T )set framegrabber param.
Parameter
º Image (output object) ............................................................image Hobject *
Grabbed image.
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be used.
HALCON/C Reference Manual / 2000-11-15

5.6. FRAMEGRABBER 343
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
grab_image(&Img,FgHandle) ;
close_framegrabber(FgHandle) ;
Result
If the frame grabber is open the operator grab image returns the value H MSG TRUE. Otherwise an exception
handling is raised.
Parallelization Information
grab image is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )open framegrabber, grab image start
Possible Successor Functions
grab image, grab image start, grab image async, close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )set framegrabber param
Image / region / XLD management
Module
grab image async ( Hobject *Image, long FGHandle, double MaxDelay )
Grab of an image from the specified frame grabber and start of the asynchronous grab of the next image.
The operator grab image async grabs an image via theframe grabber specified by FGHandle and starts the
asynchronous grab of the next image. The desired operational mode of the frame grabber as well as a suitable
image area can be adjusted via the operator (T )open framegrabber. Additional (frame grabber specific)
settings might be possible via (T )set framegrabber param. The grab of the next image is finished via
grab image or again via grab image async. If more than MaxDelay ms have passed since the asynchronous
grab was started, a new image is grabbed (the asynchronously grabbed image is considered as too old).
If a negative value is assigned to MaxDelay this control mechanism is deactivated.
Parameter
º Image (output object) ............................................................image Hobject *
Grabbed image.
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be used.
º MaxDelay (input control) .........................................................number double
Maximum tolerated delay beteween the start of the asynchronous grab and the delivery of the image [ms].
Default Value : -1.0
Value Suggestions : MaxDelay ¾-1.0, 20.0, 33.3, 40.0, 66.6, 80.0, 99.9
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
/* grab image + start next grab */
grab_image_async(&Img,FgHandle,-1.0) ;
/* Process Img ... */
HALCON 6.0

344 CHAPTER 5. IMAGE
/* Finish asynchronous grab + start next grab */
grab_image_async(Img,FgHandle,-1.0) ;
close_framegrabber(FgHandle) ;
Result
If the frame grabber is open and supports asynchronous grabbing the operator grab image async returns the
value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
grab image async is reentrant and processed without parallelization.
(T )open framegrabber
Possible Predecessor Functions
Possible Successor Functions
grab image, grab image async, close framegrabber
See Also
grab image start, (T )open framegrabber, (T )info framegrabber,
(T )set framegrabber param
Module
Image / region / XLD management
grab image start ( long FGHandle, double MaxDelay )
Start an asynchronous grab of an image from the specified frame grabber.
The operator grab image start starts an asynchronous grab of an image via the frame grabber specified
by FGHandle. The desired operational mode of the frame grabber as well as a suitable image area can be
adjusted via the operator (T )open framegrabber. Additional (frame grabber specific) settings might be
possible via (T )set framegrabber param. The grab is finished via grab image, grab image async,
grab region, orgrab region async. If one of those operators is called more than MaxDelay ms later, a
new image is grabbed (the asynchronously grabbed image is considered as to old). If a negative value is assigned
to MaxDelay this control mechanism is deactivated.
Parameter
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be used.
º MaxDelay (input control) .........................................................number double
Maximum tolerated delay between the start of the asynchronous grab and the delivery of the image [ms].
Default Value : -1.0
Value Suggestions : MaxDelay ¾20.0, 33.3, 40.0, 66.6, 80.0, 99.9
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
grab_image(&Img,FgHandle) ;
/* Start next grab */
grab_image_start(FgHandle,-1.0) ;
/* Process Img ... */
/* Finish asynchronous grab */
grab_image(Img,FgHandle) ;
close_framegrabber(FgHandle) ;
Result
If the frame grabber is open and supports asynchronous grabbing the operator grab image start returns the
value H MSG TRUE. Otherwise an exception handling is raised.
HALCON/C Reference Manual / 2000-11-15

5.6. FRAMEGRABBER 345
Parallelization Information
grab image start is reentrant and processed without parallelization.
(T )open framegrabber
Possible Predecessor Functions
Possible Successor Functions
grab image, grab region, grab image async, grab region async, close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )set framegrabber param
Image / region / XLD management
Module
grab region ( Hobject *Region, long FGHandle )
Grab and segment an image from the specified frame grabber.
The operator grab region grabs an image via the frame grabber specified by FGHandle and segments
it. The desired operational mode of the frame grabber as well as a suitable image area can be adjusted via
the operator (T )open framegrabber. Additional (frame grabber specific) settings might be possible via
(T )set framegrabber param.
Parameter
º Region (output object) ...................................................region(-array) Hobject *
Grabbed and segmented image: Region(s).
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be used.
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
/* grab and segment image */
grab_region(&Region,FgHandle) ;
/* Process Region ... */
close_framegrabber(FgHandle) ;
Result
If the frame grabber is open the operator grab region returns the value H MSG TRUE. Otherwise an exception
handling is raised.
Parallelization Information
grab region is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )open framegrabber, grab image start
Possible Successor Functions
grab region, grab region async, grab image start, grab image, grab image async,
close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )set framegrabber param
Image / region / XLD management
Module
HALCON 6.0

346 CHAPTER 5. IMAGE
grab region async ( Hobject *Region, long FGHandle, double MaxDelay )
Grab and segment an image from the specified frame grabber and start the asynchronous grab of the next image.
The operator grab region async grabs an image via the frame grabber specified by FGHandle, segments
it, and starts the asynchronous grab of the next image. The desired operational mode of the frame grabber as
well as a suitable image area can be adjusted via the operator (T )open framegrabber. Additional (frame
grabber specific) settings might be possible via (T )set framegrabber param. The grab of the next image
is finished via grab region or again via grab region async. If more than MaxDelay ms have passed
since the asynchronous grab was started, a new image is grabbed (the asynchronously grabbed image is considered
as too old). If a negative value is assigned to MaxDelay this control mechanism is deactivated.
Parameter
º Region (output object) ...................................................region(-array) Hobject *
Grabbed and segmented image: Region(s).
º FGHandle (input control) ......................................................framegrabber long
Handle of the frame grabber to be used.
º MaxDelay (input control) .........................................................number double
Maximum tolerated delay beteween the start of the asynchronous grab and the delivery of the image [ms].
Default Value : -1.0
Value Suggestions : MaxDelay ¾-1.0, 20.0, 33.3, 40.0, 66.6, 80.0, 99.9
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
/* grab image, segment it, and start next grab */
grab_region_async(Region,FgHandle,-1.0) ;
/* Process Region ... */
/* Finish asynchronous grab, segment this image, and start next grab */
grab_region_async(Region,FgHandle,-1.0) ;
close_framegrabber(FgHandle) ;
Result
If the frame grabber is open the operator grab region async returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
grab region async is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )open framegrabber, grab image start
Possible Successor Functions
grab region, grab region async, grab image start, grab image, grab image async,
close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )set framegrabber param
Image / region / XLD management
Module
info framegrabber ( const char *Name, const char *Query,
char *Information, char *ValueList )
T info framegrabber ( Htuple Name, Htuple Query, Htuple *Information,
Htuple *ValueList )
Information about the specified frame grabber.
HALCON/C Reference Manual / 2000-11-15

5.6. FRAMEGRABBER 347
The operator (T )info framegrabber returns information about the frame grabber Name. The desired information
is specified via Query. A textual description according to the selected topic is returned in Information.
If applicable, ValueList contains a list of supported values. Up to now, the following queries are possible:
’ports’: Description of the ports (signal, connectors etc.) in Information and the port numbers in
ValueList.
’camera types’: Description of the frame grabber specific parameter ’CameraType’, see
(T )open framegrabber.
’general’: General information (in Information).
’defaults’: Framegrabber specific default values in ValueList,see(T )open framegrabber.
’parameters’: Frame grabber specific parameters accessable via (T )set framegrabber param and
(T )get framegrabber param.
Please check also the directory doc/html/manuals for files describing selected frame grabbers.
Parameter
º Name (input control) ..................................................string (Htuple .) const char *
Frame grabber of interest.
Default Value : ’File’
Value Suggestions : Name ¾’BitFlow’, ’DFG-BW1’, ’DFG-LC’, ’DT315x’, ’File’, ’Fire-i’, ’FlashBus’,
’GINGA’, ’IDS’, ’Inspecta2’, ’MatrixVision’, ’Meteor1’, ’Opteon’, ’PCEye’, ’PicPort’, ’PX’, ’PXC’, ’PXD’,
’Ramses1’, ’TWAIN’, ’VideoPort’
º Query (input control) .................................................string (Htuple .) const char *
Name of the chosen query.
Default Value : ’info boards’
Value List : Query ¾’info boards’, ’ports’, ’camera types’, ’general’, ’defaults’, ’parameters’
º Information (output control) .............................................string (Htuple .) char *
Textual information (according to Query).
º ValueList (output control) .......................string(-array) (Htuple .) char * / long * / double *
If applicable, a list of values (according to Query).
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
grab_image(&Img,FgHandle) ;
close_framegrabber(FgHandle) ;
Result
If the parameter values are correct and the desired frame grabber is available at call time,
(T )info framegrabber returns the value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )info framegrabber is local and processed completely exclusively without parallelization.
(T )open framegrabber
(T )open framegrabber
(T )open framegrabber
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
HALCON 6.0

348 CHAPTER 5. IMAGE
open framegrabber ( const char *Name, long HorizontalResolution,
long VerticalResolution, long ImageWidth, long ImageHeight, long StartRow,
long StartColumn, const char *Field, long BitsPerChannel,
const char *ColorSpace, double Gain, const char *ExternalTrigger,
const char *CameraType, const char *Device, long Port, long LineIn,
long *FGHandle )
T open framegrabber ( Htuple Name, Htuple HorizontalResolution,
Htuple VerticalResolution, Htuple ImageWidth, Htuple ImageHeight,
Htuple StartRow, Htuple StartColumn, Htuple Field, Htuple BitsPerChannel,
Htuple ColorSpace, Htuple Gain, Htuple ExternalTrigger, Htuple CameraType,
Htuple Device, Htuple Port, Htuple LineIn, Htuple *FGHandle )
Open and configure a frame grabber.
The operator (T )open framegrabber opens and configures the chosen frame grabber. During this process
the connection to the frame grabber is tested, the frame grabber is (normally) locked for other processes, and
if necessary memory is reserved as data buffer. The image is actually grabbed via the operators grab image,
grab region, grab image async,orgrab region async. If the frame grabber is not needed anymore,
it should be closed via the operator close framegrabber, releasing it for other processes. This automatically
happens when a frame grabber is reopened. Some frame grabbers allow to open several instances of the same
frame grabber class (up to 5).
For some parameters frame grabber specific default values can be chosen explicitly (see the parameter description
below). Additional information for a specific frame grabber is available via (T )info framegrabber. Please
check also the directory doc/html/manuals for files describing selected frame grabbers.
The meaning of the particular parameters is as follows:
HorizontalResolution, VerticalResolution Desired resolution of the frame grabber.
ImageWidth, ImageHeight Size of the image area to be returned by grab image etc.
StartRow, StartColumn StartRow, StartColumn upper left corner of the desired image area.
Field Desired half image (’first’, ’second’,or’next’) or selection of a full image.
BitsPerChannel Number of bits, which are transferred from the frame grabber board per pixel and image channel
(typically 5, 8, 10, 12, or 16 Bits).
ColorSpace Specify to grab single-channel (’gray’) or three-channel images (’rgb’, ’yuv’, ...).
Gain Amplification factor for the video amplifier (if available).
ExternalTrigger Activation of external triggering (if available).
CameraType Frame grabber specific parameter (string type) to specify the type of the used camera, which can be
inquired via (T )info framegrabber.
Device Device name of the frame grabber card.
Port Port of the frame grabber the video signal is connected to.
LineIn Camera input line of multiplexer (if available).
The operator (T )open framegrabber returns a handle (FGHandle) to the opened frame grabber.
Attention
Due to the multitude of supported frame grabbers a large number of parameters is necessary for the operator
(T )open framegrabber. However, not all parameters are needed for a specific frame grabber.
Parameter
º Name (input control) ..................................................string (Htuple .) const char *
HALCON frame grabber interface, i.e. name of the corresponding DLL (WindowsNT) or shared library
(UNIX).
Default Value : ’File’
Value Suggestions : Name ¾’BitFlow’, ’DFG-BW1’, ’DFG-LC’, ’DT315x’, ’File’, ’Fire-i’, ’FlashBus’,
’GINGA’, ’IDS’, ’Inspecta2’, ’MatrixVision’, ’Meteor1’, ’Opteon’, ’PCEye’, ’PicPort’, ’PX’, ’PXC’, ’PXD’,
’Ramses1’, ’TWAIN’, ’VideoPort’
HALCON/C Reference Manual / 2000-11-15

5.6. FRAMEGRABBER 349
º HorizontalResolution (input control) .................................extent.x (Htuple .) long
Desired horizontal resolution of frame grabber (1: full resolution, 2: half resolution, 4: quarter resolution).
Default Value : 1
Value Suggestions : HorizontalResolution ¾1, 2, 4, 768, 720, 640, 384, 320, 192, 160
º VerticalResolution (input control) ....................................extent.y (Htuple .) long
Desired vertical resolution of frame grabber (1: full resolution, 2: half resolution, 4: quarter resolution).
Default Value : 1
Value Suggestions : VerticalResolution ¾1, 2, 4, 576, 480, 288, 240, 144, 120
º ImageWidth (input control) ......................................rectangle.extent.x (Htuple .) long
Width of desired image part (0: HorizontalResolution -2*StartColumn).
Default Value : 0
Value Suggestions : ImageWidth ¾-1, 0
º ImageHeight (input control) ....................................rectangle.extent.y (Htuple .) long
Height of desired image part (0: VerticalResolution -2*StartRow).
Default Value : 0
Value Suggestions : ImageHeight ¾-1, 0
º StartRow (input control) .........................................rectangle.origin.y (Htuple .) long
Line number of upper left corner of desired image part, for ImageHeight = 0: Height of a border.
Default Value : 0
Value Suggestions : StartRow ¾-1, 0
º StartColumn (input control) .....................................rectangle.origin.x (Htuple .) long
Column number of upper left corner of desired image part, for ImageWidth = 0: Width of a border.
Default Value : 0
Value Suggestions : StartColumn ¾-1, 0
º Field (input control) .................................................string (Htuple .) const char *
Desired half image or for full image.
Default Value : ’default’
Value Suggestions : Field ¾’first’, ’second’, ’next’, ’interlaced’, ’progressive’, ’default’
º BitsPerChannel (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Number of transferred bits per pixel and image channel (-1: frame grabber specific default value).
Default Value : -1
Value Suggestions : BitsPerChannel ¾5, 8, 10, 12, 16, -1
º ColorSpace (input control) ...................................string(-array) (Htuple .) const char *
Specify to grab single-channel (’gray’) or three-channel (’rgb’, ’yuv’, ...) images (’default’: frame grabber
specific default value, mostly ’rgb’).
Default Value : ’default’
Value Suggestions : ColorSpace ¾’gray’, ’rgb’, ’yuv’, ’default’
º Gain (input control) .........................................................real (Htuple .) double
Amplification factor for video amplifier (-1.0: frame grabber specific default value).
Default Value : -1.0
Value Suggestions : Gain ¾0.25, 0.5, 0.75, 1.0, -1.0
º ExternalTrigger (input control) ...................................string (Htuple .) const char *
External triggering.
Default Value : ’default’
Value List : ExternalTrigger ¾’true’, ’false’, ’default’
º CameraType (input control) ...................................string(-array) (Htuple .) const char *
Type of used camera (frame grabber specific) (’default’: frame grabber specific default value).
Default Value : ’default’
Value Suggestions : CameraType ¾’ntsc’, ’pal’, ’auto’, ’default’
º Device (input control) ........................................string(-array) (Htuple .) const char *
Device the frame grabber is linked to (’default’: frame grabber specific default value).
Default Value : ’default’
Value Suggestions : Device ¾’-1’, ’0’, ’1’, ’2’, ’3’, ’default’
º Port (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Port of the frame grabber the video signal is linked to (-1: frame grabber specific default value).
Default Value : -1
Value Suggestions : Port ¾0, 1, 2, 3, -1
HALCON 6.0

350 CHAPTER 5. IMAGE
º LineIn (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Camera input line of multiplexer.
Default Value : -1
Value Suggestions : LineIn ¾1, 2, 3, 4, -1
º FGHandle (output control) ..........................................framegrabber (Htuple .) long *
Handle of the opened frame grabber.
Example
/* Select a suitable frame grabber FgName */
info_framegrabber(FgName,"ports",&Information,&Val) ;
/* Choose the port P and the input line L your camera is connected to */
open_framegrabber(FgName,1,1,0,0,0,0,"default",-1,"default",-1.0,
"default","default","default",P,L,&FgHandle) ;
grab_image(&Img,FgHandle) ;
close_framegrabber(FgHandle) ;
Result
If the parameter values are correct and the desired frame grabber is available at call time,
(T )open framegrabber returns the value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )open framegrabber is local and processed completely exclusively without parallelization.
(T )info framegrabber
Possible Predecessor Functions
Possible Successor Functions
grab image, grab region, grab image start, grab image async, grab region async,
(T )set framegrabber param
See Also
(T )info framegrabber, close framegrabber, grab image
Image / region / XLD management
Module
T set framegrabber lut ( Htuple FGHandle, Htuple ImageRed,
Htuple ImageGreen, Htuple ImageBlue )
Set frame grabber lut.
The operator T set framegrabber lut sets the lut of the frame grabbers spezified by FGHandle. This
operation is not supported for all kinds of frame grabbers.
Parameter
º FGHandle (input control) ..............................................framegrabber Htuple . long
Handle of the desired frame grabber.
º ImageRed (input control) ...............................................integer-array Htuple . long
Red level of the lut entries.
º ImageGreen (input control) ............................................integer-array Htuple . long
Green level of the lut entries.
º ImageBlue (input control) .............................................integer-array Htuple . long
Blue level of the lut entries.
Result
The operator T set framegrabber lut returns the value H MSG TRUE if the transferred lut is correct and
the frame grabber is open.
Parallelization Information
T set framegrabber lut is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )open framegrabber, T get framegrabber lut
HALCON/C Reference Manual / 2000-11-15

5.7. MANIPULATION 351
Possible Successor Functions
grab image, grab region, grab image start, grab image async, grab region async
See Also
T get framegrabber lut, (T )open framegrabber
Image / region / XLD management
Module
set framegrabber param ( long FGHandle, const char *Param,
const char *Value )
T set framegrabber param ( Htuple FGHandle, Htuple Param,
Htuple Value )
Set specific parameters for a frame grabber.
The operator (T )set framegrabber param sets specific parameters for the frame grabber specified by
FGHandle.
Parameter
º FGHandle (input control) ............................................framegrabber (Htuple .) long
Handle of the frame grabber to be used.
º Param (input control) ..........................................string(-array) (Htuple .) const char *
Parameter to be set.
º Value (input control) ............................string(-array) (Htuple .) const char * / double / long
Parameter value.
Result
If the frame grabber is open and the specified parameter / parameter value is supported by the frame grabber, the
operator (T )set framegrabber param returns the value H MSG TRUE. Otherwise an exception handling
is raised.
Parallelization Information
(T )set framegrabber param is reentrant and processed without parallelization.
(T )open framegrabber
Possible Predecessor Functions
Possible Successor Functions
grab image, grab region, grab image start, grab image async, grab region async,
close framegrabber
See Also
(T )open framegrabber, (T )info framegrabber, (T )get framegrabber param
Image / region / XLD management
Module
5.7 Manipulation
get grayval ( Hobject Image, long Row, long Column, double *Grayval )
T get grayval ( Hobject Image, Htuple Row, Htuple Column,
Htuple *Grayval )
Access the gray values of an image object.
The operator Grayval is a tuple of floating point numbers, integer respectively, which returns the gray values of
several pixels of Image. The line coordinates of the pixels are in the tuple Row,thecolumnsinColumn.
Attention
The type of the values of Grayval depends on the type of the gray values.
HALCON 6.0

352 CHAPTER 5. IMAGE
Gray values which do not belong to the image can also be accessedṪhe state of these gray values is not ascertained.
The operator (T )get grayval involves a lot of work. It is not suitable for programming image processing
operations such as filters. In this case it is more useful to use the procedure get image pointer1 or to directly
use the C interface for integrating own procedures.
Parameter
º Image (input object) ..............................................................image Hobject
Image whose gray value is to be accessed.
º Row (input control) ..................................................point.y(-array) (Htuple .) long
Line numbers of pixels to be viewed.
Default Value : 0
Value Suggestions : Row ¾0, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Row 32768 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : ´0 Rowµ ´Row height´Imageµµ
º Column (input control) ..............................................point.x(-array) (Htuple .) long
Column numbers of pixels to be viewed.
Default Value : 0
Value Suggestions : Column ¾0, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Column 32768 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : Column Row
Restriction : ´0 Columnµ ´Column width´Imageµµ
º Grayval (output control) ................................grayval(-array) (Htuple .) double * / long *
Gray values of indicated pixels.
Parameter Number : Grayval Row
Result
If the state of the parameters is correct the operator (T )get grayval returns the value H MSG TRUE.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
(T )get grayval is reentrant and processed without parallelization.
read image
get image pointer1
(T )set grayval
Image / region / XLD management
Possible Predecessor Functions
Alternatives
See Also
Module
get image pointer1 ( Hobject Image, long *Pointer, char *Type,
long *Width, long *Height )
Access the pointer of a channel.
The operator get image pointer1 returns a C pointer to the first channel of the image Image. Additionally
the image type (Type = ’byte’, ’integer’, ’float’ etc.) and the image size (width and height) are returned.
Consequently a direct access to the image data in the HALCON databank from the HALCON host language
via the pointer is possible. An image is stored in HALCON as a vector of image lines. The operator
get image pointer1 is only of interest for HALCON/C.
Attention
The operator get image pointer1 should only be used for entry into newly created images, since otherwise
the gray values of other images might be overwritten (see relational structure).
HALCON/C Reference Manual / 2000-11-15

5.7. MANIPULATION 353
Parameter
º Image (input object) ..............................................................image Hobject
Input image.
º Pointer (output control) ..........................................................pointer long *
Pointer to the image data in the HALCON databank.
º Type (output control) ................................................................string char *
Type of image.
Value List : Type ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’, ’complex’, ’dvf’, ’lut’
º Width (output control) ............................................................extent.x long *
Width of image.
º Height (output control) ...........................................................extent.y long *
Height of image.
Hobject Bild;
char typ[128];
long width,height;
unsigned char *ptr;
Example
read_image(&Bild,"fabrik");
get_image_pointer1(Bild,(long*)&ptr,typ,&width,&height);
Result
The operator get image pointer1 returns the value H MSG TRUE if exactly one image was passed.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
get image pointer1 is reentrant and processed without parallelization.
read image
Possible Predecessor Functions
Alternatives
(T )set grayval, (T )get grayval, get image pointer3
paint region, paint gray
Image / region / XLD management
See Also
Module
get image pointer1 rect ( Hobject Image, long *PixelPointer,
long *Width, long *Height, long *VerticalPitch )
Access to the image data pointer and the image data inside the smallest rectangle of the domain of the input image.
The operator get image pointer1 rect returns the pointer PixelPointer which points to the beginning
of the image data inside the smallest rectangle of the domain of Image. The difference between the width of
Image and the width of the smallest rectangle is returned by VerticalPitch. Width and Height correspond
to the size of the smallest rectangle of the input region. get image pointer1 rect is approximately
symmetrical to gen image1 rect.
Attention
The operator get image pointer1 rect should only be used for entry into newly created images, since
otherwise the gray values of other images might be overwritten (see relational structure).
HALCON 6.0

354 CHAPTER 5. IMAGE
Parameter
º Image (input object) ..............................................................image Hobject
Input image (Himage).
º PixelPointer (output control) ...................................................pointer long *
Pointer to the image data.
º Width (output control) ............................................................extent.x long *
Width of the output image.
º Height (output control) ...........................................................extent.y long *
Height of the output image.
º VerticalPitch (output control) ..................................................integer long *
Difference between the width of the smallest rectangle of the domain of the input image and the width of the
input image.
Example
Hobject image,reg,imagereduced;
char typ[128];
long width,height,vert_pitch,winID;
unsigned char *ptr;
open_window(0,0,512,512,"black",winID);
read_image(&image,"monkey");
draw_region(&reg,winID);
reduce_domain(image,reg,&imagereduced);
get_image_pointer1_rect(imagereduced,(long*)&ptr,&width,&height,&vert_pitch);
Result
The operator get image pointer1 rect returns the value H MSG TRUE if exactly one image (byte) was
passed. The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
get image pointer1 rect is reentrant and processed without parallelization.
read image
Possible Predecessor Functions
Alternatives
(T )set grayval, (T )get grayval, get image pointer3, get image pointer1
See Also
paint region, paint gray, gen image1 rect
Image / region / XLD management
Module
get image pointer3 ( Hobject ImageRGB, long *PointerRed,
long *PointerGreen, long *PointerBlue, char *Type, long *Width,
long *Height )
Access the pointers of a colored image.
The operator get image pointer3 returns a C pointer to the three channels of a colored image (ImageRGB).
Additionally the image type (Type = ’byte’, ’int2’,’float’ etc.) and the image size (Width and Height) are
returned. Consequently a direct access to the image data in the HALCON databank from the HALCON host
language via the pointer is possible. An image is stored in HALCON as a vector of image lines. The three
channels must have the same pixel type and the same size. The operator get image pointer3 is only of
interest for HALCON/C.
Attention
Only one image can be passed. The operator get image pointer3 should only be used for entry into newly
created images, since otherwise the gray values of other images might be overwritten (see relational structure).
HALCON/C Reference Manual / 2000-11-15

5.7. MANIPULATION 355
Parameter
º ImageRGB (input object) ..........................................................image Hobject
Input image.
º PointerRed (output control) ......................................................pointer long *
Pointer to the pixels of the first channel.
º PointerGreen (output control) ...................................................pointer long *
Pointer to the pixels of the second channel.
º PointerBlue (output control) .....................................................pointer long *
Pointer to the pixels of the third channel.
º Type (output control) ................................................................string char *
Type of image.
Value List : Type ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’, ’complex’, ’dvf’, ’lut’
º Width (output control) ............................................................extent.x long *
Width of image.
º Height (output control) ...........................................................extent.y long *
Height of image.
Result
The operator get image pointer3 returns the value H MSG TRUE if exactly one image is passed.
The behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
get image pointer3 is reentrant and processed without parallelization.
read image
Possible Predecessor Functions
Alternatives
(T )set grayval, (T )get grayval, get image pointer1
paint region, paint gray
Image / region / XLD management
See Also
Module
paint gray ( Hobject ImageSource, Hobject ImageDestination,
Hobject *MixedImage )
Copy the gray values of an image into another image.
paint gray copies the gray values of the images given in ImageSource into the image in
ImageDestination. Only the gray values of the domain of ImageSource are copied (see
reduce domain).
Parameter
º ImageSource (input object) ......................................................image Hobject
Input image containing the desired gray values.
º ImageDestination (input object) ...............................................image Hobject
Input image to be painted over.
º MixedImage (output object) .....................................................image Hobject *
Result image.
Example
/* Copy of a circle of the image ’affe’ into a new image (New): */
read_image(&Image,"affe");
gen_circle(&Circle,200.0,200.0,150.0);
reduce_domain(Image,Circle,&Mask);
HALCON 6.0

356 CHAPTER 5. IMAGE
/* New image with black (0) background */
gen_image_proto(Image,&New1,0.0);
/* Copy of a segment of the image ’affe’ into New1 */
paint_gray(Mask,New1,&New);
Result
paint gray returns H MSG TRUE if all parameters are correct. If necessary, an exception is raised.
Parallelization Information
paint gray is reentrant and processed without parallelization.
Possible Predecessor Functions
read image, gen image const, gen image proto
Alternatives
get image pointer1, (T )set grayval, copy image
paint region
Basic operators
See Also
Module
paint region ( Hobject Region, Hobject Image, Hobject *ImageResult,
double Grayval, const char *Type )
Paint a region in an image with a constant gray value.
paint region paints the regions given in Region with a constant gray value into the image given in Image.
The parameter Type determines whether the region should be painted filled (’fill’) or whether only its boundary
should be painted (’margin’). The resulting image is returned in ImageResult.
Attention
paint region should only be used to paint into newly created images (gen image const), because otherwise
the gray values of other existing images may be overwritten.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be painted into the input image.
º Image (input object) ..............................................................image Hobject
Image in which the regions are to be painted.
º ImageResult (output object) ...................................................image Hobject *
Image containing the result.
º Grayval (input control) ....................................................number double / long
Desired gray value of the region.
Default Value : 255.0
Value Suggestions : Grayval ¾0.0, 1.0, 2.0, 5.0, 10.0, 16.0, 32.0, 64.0, 128.0, 253.0, 254.0, 255.0
Typical Range of Values : 0.0 Grayval 255.0
º Type (input control) ............................................................string const char *
Paint regions filled or as boundaries.
Default Value : ’fill’
Value List : Type ¾’fill’, ’margin’
Example
/* Copy of a rectangle in a new image (New) */
read_image(&Image,"affe");
gen_rectangle1(&Rectangle,100.0,100.0,300.0,300.0);
reduce_domain(Image,Rectangle,&Mask);
/* generate a black image */
gen_image_proto(Image,&New1,0.0);
/* copy a white rectangle */
paint_region(Mask,New1,&New,255.0,"fill");
HALCON/C Reference Manual / 2000-11-15

5.7. MANIPULATION 357
Result
paint region returns H MSG TRUE if all parameters are correct. If the input is empty the behavior can be set
via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
paint region is reentrant and processed without parallelization.
Possible Predecessor Functions
read image, gen image const, gen image proto, reduce domain
(T )set grayval, paint gray
Alternatives
See Also
reduce domain, set draw, gen image const
Basic operators
Module
set grayval ( Hobject Image, long Row, long Column, double Grayval )
T set grayval ( Hobject Image, Htuple Row, Htuple Column,
Htuple Grayval )
Set single gray values in an image.
(T )set grayval sets the gray values of the input image Image at the positions (Row,Column)tothevalues
specified by Grayval. The number of values in Grayval must match the number of points passed to the
operator.
Parameter
º Image (input object) ..............................................................image Hobject
Image to be modified.
º Row (input control) ..................................................point.y(-array) (Htuple .) long
Row coordinates of the pixels to be modified.
Default Value : 0
Value Suggestions : Row ¾0, 10, 50, 127, 255, 511
Typical Range of Values : 0 Row
Restriction : ´0 Rowµ ´Row height´Imageµµ
º Column (input control) ..............................................point.x(-array) (Htuple .) long
Column coordinates of the pixels to be modified.
Default Value : 0
Value Suggestions : Column ¾0, 10, 50, 127, 255, 511
Typical Range of Values : 0 Column
Restriction : ´0 Columnµ ´Column width´Imageµµ
º Grayval (input control) ....................................grayval(-array) (Htuple .) double / long
Gray values to be used.
Default Value : 255.0
Value Suggestions : Grayval ¾0.0, 1.0, 10.0, 128.0, 255.0
Result
(T )set grayval returns H MSG TRUE if all parameters are correct. If the input is empty the behavior can
be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )set grayval is reentrant and processed without parallelization.
Possible Predecessor Functions
read image, get image pointer1, gen image proto, gen image1
Alternatives
get image pointer1, paint gray, paint region
See Also
(T )get grayval, gen image const, gen image1, gen image proto
HALCON 6.0

358 CHAPTER 5. IMAGE
Basic operators
Module
5.8 Type-Conversion
complex to real ( Hobject ImageComplex, Hobject *ImageReal,
Hobject *ImageImaginary )
Convert a complex image into two real images.
complex to real converts a complex image ImageComplex into two real images ImageReal and
ImageImaginary, which contain the real and imaginary part of the complex image.
Parameter
º ImageComplex (input object) ....................................image(-array) Hobject : complex
Complex image.
º ImageReal (output object) .........................................image(-array) Hobject * : real
Real part.
º ImageImaginary (output object) ...................................image(-array) Hobject * : real
Imaginary part.
Parallelization Information
complex to real is reentrant and automatically parallelized (on tuple level).
real to complex
Image / region / XLD management
See Also
Module
convert image type ( Hobject Image, Hobject *ImageConverted,
const char *NewType )
Convert the type of an image.
convert image type converts images of an arbitrary type into an arbitrary new image type. If the conversion
is done from a larger to a smaller gray value range (e.g., from ’int4’ to ’byte’), too large or too small values are
simply “clipped.” It is therefore advisable to adapt the range of gray values by calling scale image before
calling this operator.
Attention
If the source and destination image type are identical, no new image matrix is allocated.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject :any
Image whose image type is to be changed.
º ImageConverted (output object) . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject * :any
Converted image.
º NewType (input control) .......................................................string const char *
Desired image type (i.e., type of the gray values).
Default Value : ’byte’
Value List : NewType ¾’int1’, ’int2’, ’int4’, ’byte’, ’real’, ’direction’, ’cyclic’, ’complex’, ’dvf’, ’lut’
Result
convert image type returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour
can be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
convert image type is reentrant and automatically parallelized (on tuple level, channel level, domain level).
HALCON/C Reference Manual / 2000-11-15

5.8. TYPE-CONVERSION 359
scale image
scale image, abs image
Image / region / XLD management
Possible Predecessor Functions
See Also
Module
dvf to int1 ( Hobject VectorField, Hobject *Row, Hobject *Col )
Convert a displacement vector field into two int1-images.
dvf to int1 converts the displacement vector field VectorField into two int1-images Row and Col. The
output images contain the displacements in Ü- andÝ-direction, respectively.
Parameter
º VectorField (input object) ..........................................image(-array) Hobject : dvf
Displacement vector field.
º Row (output object) .................................................image(-array) Hobject * :int1
Displacement along y.
º Col (output object) .................................................image(-array) Hobject * :int1
Displacement along x.
Parallelization Information
dvf to int1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
mean image, optical flow match, fill dvf
optical flow match
Image / region / XLD management
See Also
Module
int1 to dvf ( Hobject Row, Hobject Col, Hobject *VectorField )
Convert two int1-images into a displacement vector field.
int1 to dvf converts two int1-images Row and Col into a displacement vector field VectorField. The
input images contain the displacements in Ü- andÝ-direction, respectively.
Parameter
º Row (input object) .....................................................image(-array) Hobject :int1
Displacement along y.
º Col (input object) .....................................................image(-array) Hobject :int1
Displacement along x.
º VectorField (output object) .......................................image(-array) Hobject * : dvf
Displacement vector field.
Parallelization Information
int1 to dvf is reentrant and automatically parallelized (on tuple level).
dvf to int1
optical flow match, fill dvf
Image / region / XLD management
Possible Predecessor Functions
Possible Successor Functions
Module
HALCON 6.0

360 CHAPTER 5. IMAGE
real to complex ( Hobject ImageReal, Hobject ImageImaginary,
Hobject *ImageComplex )
Convert two real images into a complex image.
real to complex converts two real images ImageReal and ImageImaginary, which contain the real and
imaginary part of a complex image, into a complex image ImageComplex.
Parameter
º ImageReal (input object) .............................................image(-array) Hobject : real
Real part.
º ImageImaginary (input object) ......................................image(-array) Hobject : real
Imaginary part.
º ImageComplex (output object) .................................image(-array) Hobject * : complex
Complex image.
Parallelization Information
real to complex is reentrant and automatically parallelized (on tuple level).
complex to real
Image / region / XLD management
See Also
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 6
Lines
6.1 Access
T approx chain ( Htuple Row, Htuple Column, Htuple MinWidthCoord,
Htuple MaxWidthCoord, Htuple ThreshStart, Htuple ThreshEnd,
Htuple ThreshStep, Htuple MinWidthSmooth, Htuple MaxWidthSmooth,
Htuple MinWidthCurve, Htuple MaxWidthCurve, Htuple Weight1,
Htuple Weight2, Htuple Weight3, Htuple *ArcCenterRow,
Htuple *ArcCenterCol, Htuple *ArcAngle, Htuple *ArcBeginRow,
Htuple *ArcBeginCol, Htuple *LineBeginRow, Htuple *LineBeginCol,
Htuple *LineEndRow, Htuple *LineEndCol, Htuple *Order )
Approximate a contour by arcs and lines.
The coordinates of a curve are approximated by a row of lines and arcs. The procedure tries values from
a user-definable range for certain parameters. The limits of these ranges are explicitly stated in the parameter
list of the function (MinWidthCoord ... MaxWidthCoord, ThreshStart ... ThreshEnd, MinWidthSmooth ...
MaxWidthSmooth, MinWidthCurve ... MaxWidthCurve). Additionally, the step width for the parameter area of
the threshold value for pointed corners has to be indicated (ThreshStep). By narrowing the covered areas the
runtime of the calculation can be shortened, but the result may deteriorate.
The parameters Weight1, Weight2 and Weight3 indicate whether the desired weighting is placed more on precision
of the approximation, obtaining as much large segments as possible or as few small segments as possible. Thus,
for (Weight1,Weight2,Weight3) (1,0,0) creates a very precise approximation and (0,1,1) an approximation with as
few large segments as possible.
The result of the procedure is returned separately as arcs and lines. If one is interested in the sequence of the
segments the individual resulting elements can be read successively from the resulting tuples; the sequence can be
taken from the return parameter order (0: next element is next line segment, 1: next element is next arc segment).
Attention
Contours which can possibly consist of only one segment should also be examined with a threshold maximum
(ThreshEnd) 1.0, because otherwise at least one “corner point” is determined in any case.
Parameter
º Row (input control) ...........................................................point.y Htuple . long
Row of the contour.
Default Value : 32
º Column (input control) .......................................................point.x Htuple . long
Column of the contour.
Default Value : 32
361

362 CHAPTER 6. LINES
º MinWidthCoord (input control) ..............................................real Htuple . double
Minimum width of Gauss operator for coordinate smoothing ( 0.4).
Default Value : 0.5
Value Suggestions : MinWidthCoord ¾0.5, 0.7, 1.0, 1.2, 1.5, 1.7
Typical Range of Values : 0.4 MinWidthCoord 3.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º MaxWidthCoord (input control) ..............................................real Htuple . double
Maximum width of Gauss operator for coordinate smoothing ( 0.4).
Default Value : 2.4
Value Suggestions : MaxWidthCoord ¾0.5, 0.7, 1.0, 1.2, 1.5, 1.7
Typical Range of Values : 0.4 MaxWidthCoord 3.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º ThreshStart (input control) .................................................real Htuple . double
Minimum threshold value of the curvature for accepting a corner (relative to the largest curvature present).
Default Value : 0.3
Value Suggestions : ThreshStart ¾0.3, 0.4, 0.5, 0.6, 0.7, 0.8
Typical Range of Values : 0.1 ThreshStart 0.9 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º ThreshEnd (input control) ...................................................real Htuple . double
Maximum threshold value of the curvature for accepting a corner (relative to the largest curvature present).
Default Value : 0.9
Value Suggestions : ThreshEnd ¾0.3, 0.4, 0.5, 0.6, 0.7, 0.8
Typical Range of Values : 0.1 ThreshEnd 0.9 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º ThreshStep (input control) ..................................................real Htuple . double
Step width for threshold increase.
Default Value : 0.2
Value Suggestions : ThreshStep ¾0.3, 0.4, 0.5
Typical Range of Values : 0.1 ThreshStep 0.9 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º MinWidthSmooth (input control) ............................................real Htuple . double
Minimum width of Gauss operator for smoothing the curvature function ( 0.4).
Default Value : 0.5
Value Suggestions : MinWidthSmooth ¾0.5, 0.7, 1.0, 1.2, 1.5, 1.7
Typical Range of Values : 0.4 MinWidthSmooth 3.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º MaxWidthSmooth (input control) ............................................real Htuple . double
Maximum width of Gauss operator for smoothing the curvature function.
Default Value : 2.4
Value Suggestions : MaxWidthSmooth ¾0.5, 0.7, 1.0, 1.2, 1.5, 1.7
Typical Range of Values : 0.4 MaxWidthSmooth 3.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º MinWidthCurve (input control) .............................................integer Htuple . long
Minimum width of curve area for curvature determination ( 0.4).
Default Value : 2
Value Suggestions : MinWidthCurve ¾2, 5, 7
Typical Range of Values : 1 MinWidthCurve 12 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
HALCON/C Reference Manual / 2000-11-15

6.1. ACCESS 363
º MaxWidthCurve (input control) .............................................integer Htuple . long
Maximum width of curve area for curvature determination.
Default Value : 12
Value Suggestions : MaxWidthCurve ¾2, 5, 7
Typical Range of Values : 1 MaxWidthCurve 20 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
º Weight1 (input control) ......................................................real Htuple . double
Weighting factor for approximation precision.
Default Value : 1.0
Value Suggestions : Weight1 ¾0.0, 0.5, 1.0
Typical Range of Values : 0.0 Weight1 1.0 (lin)
Minimal Value Step : 0.1
Recommended Value Step : 0.5
º Weight2 (input control) ......................................................real Htuple . double
Weighting factor for large segments.
Default Value : 1.0
Value Suggestions : Weight2 ¾0.0, 0.5, 1.0
Typical Range of Values : 0.0 Weight2 1.0 (lin)
Minimal Value Step : 0.1
Recommended Value Step : 0.5
º Weight3 (input control) ......................................................real Htuple . double
Weighting factor for small segments.
Default Value : 1.0
Value Suggestions : Weight3 ¾0.0, 0.5, 1.0
Typical Range of Values : 0.0 Weight3 1.0 (lin)
Minimal Value Step : 0.1
Recommended Value Step : 0.5
º ArcCenterRow (output control) ..................................arc.center.y-array Htuple . long *
Rowofthecenterofanarc.
º ArcCenterCol (output control) ..................................arc.center.x-array Htuple . long *
Column of the center of an arc.
º ArcAngle (output control) ....................................arc.angle.rad-array Htuple . double *
Angle of an arc.
º ArcBeginRow (output control) ....................................arc.begin.y-array Htuple . long *
Row of the starting point of an arc.
º ArcBeginCol (output control) ....................................arc.begin.x-array Htuple . long *
Column of the starting point of an arc.
º LineBeginRow (output control) ..................................line.begin.y-array Htuple . long *
Row of the starting point of a line segment.
º LineBeginCol (output control) ..................................line.begin.x-array Htuple . long *
Column of the starting point of a line segment.
º LineEndRow (output control) ......................................line.end.y-array Htuple . long *
Row of the ending point of a line segment.
º LineEndCol (output control) ......................................line.end.x-array Htuple . long *
Column of the ending point of a line segment.
º Order (output control) ................................................integer-array Htuple . long *
Sequence of line (value 0) and arc segments (value 1).
Example
/* read edge image */
read_image(&Image,"fig1_kan");
/* construct edge region */
hysteresis_threshold(Image,&RK1,64,255,40,1);
connection(RK1,&Rand);
/* fetch chain code */
T_get_region_contour(Rand,&Rows,&Columns);
HALCON 6.0

364 CHAPTER 6. LINES
firstline = get_i(Tline,0);
firstcol = get_i(Tcol,0);
/* approximation with lines and circular arcs */
set_d(t1,0.4,0);
set_d(t2,2.4,0);
set_d(t3,0.3,0);
set_d(t4,0.9,0);
set_d(t5,0.2,0);
set_d(t6,0.4,0);
set_d(t7,2.4,0);
set_i(t8,2,0);
set_i(t9,12,0);
set_d(t10,1.0,0);
set_d(t11,1.0,0);
set_d(t12,1.0,0);
T_approx_chain(Rows,Columns,t1,t2,t3,t4,t5,t6,t7,t8,t9,t10,t11,t12,
&Bzl,&Bzc,&Br,&Bwl,&Bwc,&Ll0,&Lc0,&Ll1,&Lc1,&order);
nob = length_tuple(Bzl);
nol = length_tuple(Ll0);
/* draw lines and arcs */
set_i(WindowHandleTuple,WindowHandle,0) ;
set_line_width(WindowHandle,4);
if (nob>0) T_disp_arc(Bzl,Bzc,Br,Bwl,Bwc);
set_line_width(WindowHandle,1);
if (nol>0) T_disp_line(WindowHandleTuple,Ll0,Lc0,Ll1,Lc1);
Result
The operator T approx chain returns the value H MSG TRUE if the parameters are correct. Otherwise an
exception is raised.
Parallelization Information
T approx chain is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, get region contour, threshold, hysteresis threshold
Possible Successor Functions
set line width, disp arc, disp line
Alternatives
get region polygon, T approx chain simple
See Also
get region chain, smallest circle, disp circle, disp line
Region processing
Module
T approx chain simple ( Htuple Row, Htuple Column,
Htuple *ArcCenterRow, Htuple *ArcCenterCol, Htuple *ArcAngle,
Htuple *ArcBeginRow, Htuple *ArcBeginCol, Htuple *LineBeginRow,
Htuple *LineBeginCol, Htuple *LineEndRow, Htuple *LineEndCol,
Htuple *Order )
Approximate a contour by arcs and lines.
HALCON/C Reference Manual / 2000-11-15

6.1. ACCESS 365
The contour of a curve is approximated by a sequence of lines and arcs.
The result of the procedure is returned separately as arcs and lines. If one is interested in the sequence of the
segments the individual resulting elements can be read successively from the resulting tuplesṪhe sequence can be
taken from the return parameter order (0: next element is next line segment, 1: next element is next arc segment).
The operator T approx chain simple behaves similarly as T approx chain except that in the case of
T approx chain simple the missing parameters are internally allocated as follows: MinWidthCoord =
1.0, MaxWidthCoord = 3.0, ThreshStart = 0.5, ThreshEnd = 0.9, ThreshStep = 0.3, MinWidthSmooth = 1.0,
MaxWidthSmooth = 3.0, MinWidthCurve = 2, MaxWidthCurve = 9, Weight1 = 1.0, Weight2 = 1.0, Weight3 = 1.0.
Parameter
º Row (input control) ...........................................................point.y Htuple . long
Row of the contour.
Default Value : 32
º Column (input control) .......................................................point.x Htuple . long
Column of the contour.
Default Value : 32
º ArcCenterRow (output control) ..................................arc.center.y-array Htuple . long *
Rowofthecenterofanarc.
º ArcCenterCol (output control) ..................................arc.center.x-array Htuple . long *
Column of the center of an arc.
º ArcAngle (output control) ....................................arc.angle.rad-array Htuple . double *
Angle of an arc.
º ArcBeginRow (output control) ....................................arc.begin.y-array Htuple . long *
Row of the starting point of an arc.
º ArcBeginCol (output control) ....................................arc.begin.x-array Htuple . long *
Column of the starting point of an arc.
º LineBeginRow (output control) ..................................line.begin.y-array Htuple . long *
Row of the starting point of a line segment.
º LineBeginCol (output control) ..................................line.begin.x-array Htuple . long *
Column of the starting point of a line segment.
º LineEndRow (output control) ......................................line.end.y-array Htuple . long *
Row of the ending point of a line segment.
º LineEndCol (output control) ......................................line.end.x-array Htuple . long *
Column of the ending point of a line segment.
º Order (output control) ................................................integer-array Htuple . long *
Sequence of line (value 0) and arc segments (value 1).
Example
/* read edge image */
read_image(&Image,"fig1_kan");
/* construct edge region */
hysteresis_threshold(Image,&RK1,64,255,40,1);
connection(RK1,&Rand);
/* fetch chain code */
T_get_region_contour(Rand,&Rows,&Columns);
firstline = get_i(Tline,0);
firstcol = get_i(Tcol,0);
/* approximation with lines and circular arcs */
T_approx_chain_simple(Rows,Columns,
&Bzl,&Bzc,&Br,&Bwl,&Bwc,&Ll0,&Lc0,&Ll1,&Lc1,&order);
nob = length_tuple(Bzl);
nol = length_tuple(Ll0);
/* draw lines and arcs */
set_i(WindowHandleTuple,WindowHandle,0) ;
set_line_width(WindowHandle,4);
if (nob>0) T_disp_arc(Bzl,Bzc,Br,Bwl,Bwc);
set_line_width(WindowHandle,1);
if (nol>0) T_disp_line(WindowHandleTuple,Ll0,Lc0,Ll1,Lc1);
HALCON 6.0

366 CHAPTER 6. LINES
Result
The operator T approx chain simple returns the value H MSG TRUE if the parameters are correct. Otherwise
an exception is raised.
Parallelization Information
T approx chain simple is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, get region contour, threshold, hysteresis threshold
Possible Successor Functions
set line width, disp arc, disp line
get region polygon, T approx chain
Alternatives
See Also
get region chain, smallest circle, disp circle, disp line
Region processing
Module
6.2 Features
line orientation ( double RowBegin, double ColBegin, double RowEnd,
double ColEnd, double *Phi )
T line orientation ( Htuple RowBegin, Htuple ColBegin, Htuple RowEnd,
Htuple ColEnd, Htuple *Phi )
Calculate the orientation of lines.
The operator (T )line orientation returns the orientation ( ¾ È ¾)ofthegivenlines.Ifmore
than one line is to be treated the line and column indices can be passed as tuples. In this case Phi is, of course,
also a tuple and contains the corresponding orientations.
The procedure is typically applied to model lines in order to select parallel image lines, which were found, e.g., by
detect edge segments, via the operator T select lines.
Parameter
º RowBegin (input control) ...............................line.begin.y(-array) (Htuple .) double / long
Row coordinates of the starting points of the input lines.
º ColBegin (input control) ...............................line.begin.x(-array) (Htuple .) double / long
Column coordinates of the starting points of the input lines.
º RowEnd (input control) ...................................line.end.y(-array) (Htuple .) double / long
Row coordinates of the ending points of the input lines.
º ColEnd (input control) ...................................line.end.x(-array) (Htuple .) double / long
Column coordinates of the ending points of the input lines.
º Phi (output control) ...........................................angle.rad(-array) (Htuple .) double *
Orientation of the input lines.
Result
(T )line orientation always returns the value H MSG TRUE.
Parallelization Information
(T )line orientation is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, threshold, hysteresis threshold, split skeleton region,
split skeleton lines
Possible Successor Functions
set line width, disp line
Alternatives
(T )line position, T select lines, T partition lines
HALCON/C Reference Manual / 2000-11-15

6.2. FEATURES 367
See Also
(T )line position, T select lines, T partition lines, detect edge segments
Region processing
Module
line position ( long RowBegin, long ColBegin, long RowEnd, long ColEnd,
double *RowCenter, double *ColCenter, double *Length, double *Phi )
T line position ( Htuple RowBegin, Htuple ColBegin, Htuple RowEnd,
Htuple ColEnd, Htuple *RowCenter, Htuple *ColCenter, Htuple *Length,
Htuple *Phi )
Calculate the center of gravity, length, and orientation of a line.
The operator (T )line position returns the center (RowCenter, ColCenter), the (Euclidean) length
(Length) and the orientation ( ¾ È ¾) of the given lines. If more than one line is to be treated
the line and column indices can be passed as tuples. In this case the output parameters, of course, are also tuples.
The routine is applied, for example, to model lines in order to determine search regions for the edge detection
(detect edge segments).
Parameter
º RowBegin (input control) .......................................line.begin.y(-array) (Htuple .) long
Row coordinates of the starting points of the input lines.
º ColBegin (input control) .......................................line.begin.x(-array) (Htuple .) long
Column coordinates of the starting points of the input lines.
º RowEnd (input control) ............................................line.end.y(-array) (Htuple .) long
Row coordinates of the ending points of the input lines.
º ColEnd (input control) ............................................line.end.x(-array) (Htuple .) long
Column coordinates of the ending points of the input lines.
º RowCenter (output control) .....................................point.y(-array) (Htuple .) double *
Row coordinates of the centers of gravity of the input lines.
º ColCenter (output control) .....................................point.x(-array) (Htuple .) double *
Column coordinates of the centers of gravity of the input lines.
º Length (output control) ............................................real(-array) (Htuple .) double *
Euclidean length of the input lines.
º Phi (output control) ...........................................angle.rad(-array) (Htuple .) double *
Orientation of the input lines.
Result
(T )line position always returns the value H MSG TRUE.
Parallelization Information
(T )line position is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, threshold, hysteresis threshold, split skeleton region,
split skeleton lines
Possible Successor Functions
set line width, disp line
Alternatives
(T )line orientation, T select lines, T partition lines
See Also
(T )line orientation, T select lines, T partition lines, detect edge segments
Region processing
Module
HALCON 6.0

368 CHAPTER 6. LINES
T partition lines ( Htuple RowBeginIn, Htuple ColBeginIn,
Htuple RowEndIn, Htuple ColEndIn, Htuple Feature, Htuple Operation,
Htuple Min, Htuple Max, Htuple *RowBeginOut, Htuple *ColBeginOut,
Htuple *RowEndOut, Htuple *ColEndOut, Htuple *FailRowBOut,
Htuple *FailColBOut, Htuple *FailRowEOut, Htuple *FailColEOut )
Partition lines according to various criteria.
The operator T partition lines divides lines into two sets according to various criteria. For each input line
the indicated features (Feature) are calculated. If each (Operation = ’and’) or at least one (Operation
= ’or’) of the calculated features is within the given limits (Min,Max) the line is transferred into the first set
(parameters RowBeginOut to ColEndOut), otherwise into the second set (parameters FailRowBOut to
FailColEOut).
Condition:
ÅÒ ØÙÖ ´ÄÒµ ÅÜ
Possible values for Feature:
’length’ (Euclidean) length of the line
’row’ Line index of the center
’column’ Column index of the center
’phi’ Orientation of the line ( ³ )
¾ ¾
Attention
If only one feature is used the value of Operation is meaningless. Several features are processed according to
the sequence in which they are passed.
Parameter
º RowBeginIn (input control) .......................................line.begin.y-array Htuple . long
Row coordinates of the starting points of the input lines.
º ColBeginIn (input control) .......................................line.begin.x-array Htuple . long
Column coordinates of the starting points of the input lines.
º RowEndIn (input control) ............................................line.end.y-array Htuple . long
Row coordinates of the ending points of the input lines.
º ColEndIn (input control) ............................................line.end.x-array Htuple . long
Column coordinates of the ending points of the input lines.
º Feature (input control).........................................string(-array) Htuple . const char *
Features to be used for selection.
Value List : Feature ¾’length’, ’row’, ’column’, ’phi’
º Operation (input control) .............................................string Htuple . const char *
Desired combination of the features.
Value List : Operation ¾’and’, ’or’
º Min (input control) ................................string(-array) Htuple . const char * / long / double
Lower limits of the features or ’min’.
Default Value : ’min’
º Max (input control) ................................string(-array) Htuple . const char * / long / double
Upper limits of the features or ’max’.
Default Value : ’max’
º RowBeginOut (output control) ...................................line.begin.y-array Htuple . long *
Row coordinates of the starting points of the lines fulfilling the conditions.
º ColBeginOut (output control) ...................................line.begin.x-array Htuple . long *
Column coordinates of the starting points of the lines fulfilling the conditions.
º RowEndOut (output control) ........................................line.end.y-array Htuple . long *
Row coordinates of the ending points of the lines fulfilling the conditions.
º ColEndOut (output control) ......................................line.begin.x-array Htuple . long *
Column coordinates of the ending points of the lines fulfilling the conditions.
º FailRowBOut (output control) ...................................line.begin.y-array Htuple . long *
Row coordinates of the starting points of the lines not fulfilling the conditions.
HALCON/C Reference Manual / 2000-11-15

6.2. FEATURES 369
º FailColBOut (output control) ...................................line.begin.x-array Htuple . long *
Column coordinates of the starting points of the lines not fulfilling the conditions.
º FailRowEOut (output control) .....................................line.end.y-array Htuple . long *
Row coordinates of the ending points of the lines not fulfilling the conditions.
º FailColEOut (output control) .....................................line.end.x-array Htuple . long *
Column coordinates of the ending points of the lines not fulfilling the conditions.
Result
The operator T partition lines returns the value H MSG TRUE if the parameter values are correct. Otherwise
an exception is raised.
Parallelization Information
T partition lines is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, threshold, hysteresis threshold, split skeleton region,
split skeleton lines
Possible Successor Functions
set line width, disp line
Alternatives
(T )line orientation, (T )line position, T select lines, T select lines longest
See Also
T select lines, T select lines longest, detect edge segments, select shape
Region processing
Module
T select lines ( Htuple RowBeginIn, Htuple ColBeginIn, Htuple RowEndIn,
Htuple ColEndIn, Htuple Feature, Htuple Operation, Htuple Min, Htuple Max,
Htuple *RowBeginOut, Htuple *ColBeginOut, Htuple *RowEndOut,
Htuple *ColEndOut )
Select lines according to various criteria.
The operator T select lines chooses lines according to various criteria. For every input line the indicated
features (Feature) are calculated. If each (Operation = ’and’) or at least one (Operation = ’or’) of the
calculated features is within the given limits (Min,Max) the line is transferred into the output.
Condition:
Possible values for Feature:
ÅÒ ØÙÖ ´ÄÒµ ÅÜ
’length’ (Euclidean) length of the line
’row’ Line index of the center
’column’ Column index of the center
’phi’ Orientation of the line ( ³ )
¾ ¾
Attention
If only one feature is used the value of Operation is meaningless. Several features are processed according to
the sequence in which they are passed.
Parameter
º RowBeginIn (input control) .......................................line.begin.y-array Htuple . long
Row coordinates of the starting points of the input lines.
º ColBeginIn (input control) .......................................line.begin.x-array Htuple . long
Column coordinates of the starting points of the input lines.
º RowEndIn (input control) ............................................line.end.y-array Htuple . long
Row coordinates of the ending points of the input lines.
HALCON 6.0

370 CHAPTER 6. LINES
º ColEndIn (input control) ............................................line.end.x-array Htuple . long
Column coordinates of the ending points of the input lines.
º Feature (input control).........................................string(-array) Htuple . const char *
Features to be used for selection.
Default Value : ’length’
Value List : Feature ¾’length’, ’row’, ’column’, ’phi’
º Operation (input control) .............................................string Htuple . const char *
Desired combination of the features.
Default Value : ’and’
Value List : Operation ¾’and’, ’or’
º Min (input control) ................................string(-array) Htuple . const char * / long / double
Lower limits of the features or ’min’.
Default Value : ’min’
º Max (input control) ................................string(-array) Htuple . const char * / long / double
Upper limits of the features or ’max’.
Default Value : ’max’
º RowBeginOut (output control) ...................................line.begin.y-array Htuple . long *
Row coordinates of the starting points of the output lines.
º ColBeginOut (output control) ...................................line.begin.x-array Htuple . long *
Column coordinates of the starting points of the output lines.
º RowEndOut (output control) ........................................line.end.y-array Htuple . long *
Row coordinates of the ending points of the output lines.
º ColEndOut (output control) ........................................line.end.x-array Htuple . long *
Column coordinates of the ending points of the output lines.
Result
The operator T select lines returns the value H MSG TRUE if the parameter values are correct. Otherwise
an exception is raised.
Parallelization Information
T select lines is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, threshold, hysteresis threshold, split skeleton region,
split skeleton lines
Possible Successor Functions
set line width, disp line
Alternatives
(T )line orientation, (T )line position, T partition lines
See Also
T partition lines, T select lines longest, detect edge segments, select shape
Region processing
Module
T select lines longest ( Htuple RowBeginIn, Htuple ColBeginIn,
Htuple RowEndIn, Htuple ColEndIn, Htuple Num, Htuple *RowBeginOut,
Htuple *ColBeginOut, Htuple *RowEndOut, Htuple *ColEndOut )
Select the longest input lines.
The operator T select lines longest selects the Num longest input lines from the input lines described by
the tuples RowBeginIn, ColBeginIn, RowEndIn and ColEndIn.
Parameter
º RowBeginIn (input control) .......................................line.begin.y-array Htuple . long
Row coordinates of the starting points of the input lines.
º ColBeginIn (input control) .......................................line.begin.x-array Htuple . long
Column coordinates of the starting points of the input lines.
HALCON/C Reference Manual / 2000-11-15

6.2. FEATURES 371
º RowEndIn (input control) ............................................line.end.y-array Htuple . long
Row coordinates of the ending points of the input lines.
º ColEndIn (input control) ............................................line.end.x-array Htuple . long
Column coordinates of the ending points of the input lines.
º Num (input control) ...........................................................integer Htuple . long
(Maximum) desired number of output lines.
Default Value : 10
º RowBeginOut (output control) ...................................line.begin.y-array Htuple . long *
Row coordinates of the starting points of the output lines.
º ColBeginOut (output control) ...................................line.begin.x-array Htuple . long *
Column coordinates of the starting points of the output lines.
º RowEndOut (output control) ........................................line.end.y-array Htuple . long *
Row coordinates of the ending points of the output lines.
º ColEndOut (output control) ........................................line.end.x-array Htuple . long *
Column coordinates of the ending points of the output lines.
Result
The operator T select lines longest returns the value H MSG TRUE if the parameter values are correct.
Otherwise an exception is raised.
Parallelization Information
T select lines longest is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, edges image, threshold, hysteresis threshold, split skeleton region,
split skeleton lines
Possible Successor Functions
set line width, disp line
Alternatives
(T )line orientation, (T )line position, T select lines, T partition lines
See Also
T select lines, T partition lines, detect edge segments, select shape
Region processing
Module
HALCON 6.0

372 CHAPTER 6. LINES
HALCON/C Reference Manual / 2000-11-15

Chapter 7
Morphology
7.1 Gray-Values
dual rank ( Hobject Image, Hobject *ImageRank, const char *MaskType,
long Radius, long ModePercent, long Margin )
Opening, Median and Closing with circle or rectangle mask.
The operator dual rank carries out a non-linear transformation of the gray values of all input images (Image).
Circles or squares can be used as structuring elements. The operator dual rank effects two consecutive calls of
rank image. At the first call the range gray value is calculated with the indicated range (ModePercent).
The result of this calculation is the input of a further call of rank image, this time using the range value
½¼¼ ModePercent.
When filtering different parameters for margin control (Margin) can be chosen:
0...255 Pixels outside the image edges are assumed to be constant
(with the indicated gray value).
-1 Continuation of edge pixels.
-2 cyclic continuation of image edges.
-3 Reflection of pixels at image edges.
A range filtering is calculated according to the following scheme: The indicated mask is put over the image to be
filtered in such a way that the center of the mask touches all pixels once. For each of these pixels all neighboring
pixels covered by the mask are sorted in an ascending sequence corresponding to their gray values. Each sorted
sequence of gray values contains the same number of gray values like the mask has image points. The n-th highest
element, (= ModePercent, rank values between ¼ ½¼¼ in percent) is selected and set as result gray value in
the corresponding result image.
If ModePercent is ¼, then the operator equals to the gray value opening (gray opening). If ModePercent
is ¼, the operator results in the median filter, which is applied twice (median image). The ModePercent
100 in dual rank means that it calculates the gray value closing (gray closing). Choosing parameter values
inside this range results in a smooth transformation of these operators.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Image to be filtered.
º ImageRank (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) Hobject *
Filtered Image.
º MaskType (input control) ......................................................string const char *
Shape of the mask.
Default Value : ’circle’
Value List : MaskType ¾’circle’, ’rectangle’
373

374 CHAPTER 7. MORPHOLOGY
º Radius (input control) ...............................................................integer long
Radius of the filter mask.
Default Value : 1
Value Suggestions : Radius ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 15, 19, 25, 31, 39, 47, 59
Typical Range of Values : 1 Radius 101
Minimal Value Step : 1
Recommended Value Step : 2
º ModePercent (input control) ........................................................integer long
Filter Mode: 0 corresponds to a gray value opening , 50 corresponds to a median and 100 to a gray values
closing.
Default Value : 10
Value Suggestions : ModePercent ¾0, 2, 5, 10, 15, 20, 40, 50, 60, 80, 85, 90, 95, 98, 100
Typical Range of Values : 0 ModePercent 100
Minimal Value Step : 1
Recommended Value Step : 2
º Margin (input control) ...............................................................integer long
Margin control: 0...255 (constant), -1 (margin points continued), -2 (cyclic continuation), -3 (mirroring).
Default Value : -3
Typical Range of Values : -3 Margin 255
Example
read_image(&Image,"fabrik");
dual_rank(Image,&ImageOpening,"circle",10,10,-3);
disp_image(ImageOpening,WindowHandle);
Complexity
For each pixel: O( Ô £ ½¼) with F = area of the structuring element.
Result
If the parameter values are correct the operator dual rank returns the value H MSG TRUE. The
behavior in case of empty input (no input images available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
dual rank is reentrant and automatically parallelized (on tuple level, channel level).
read image
Possible Predecessor Functions
Possible Successor Functions
threshold, dyn threshold, sub image, regiongrowing
Alternatives
rank image, gray closing, gray opening, median image
See Also
gen circle, gen rectangle1, gray erosion rect, gray dilation rect, sigma image
Bibliography
W. Eckstein, O. Munkelt “Extracting Objects from Digital Terrain Model” Remote Sensing and Reconstruction for
Threedimensional Objects and Scenes, SPIE Symposium on Optical Science, Engeneering, and Instrumentation,
July 1995, San Diego
Module
Image filters
gen disc se ( Hobject *SE, long Width, long Height, long Smax )
Generate ellipsoidal structuring elements for gray morphology.
gen disc se generates an ellipsoidal structuring element (SE) for gray morphology of images. The parameters
Width and Height determine the length of the two major axes of the ellipse. The value of Smax determines
HALCON/C Reference Manual / 2000-11-15

7.1. GRAY-VALUES 375
the maximum gray value of the structuring element. For the generation of arbitrary structuring elements, see
read gray se.
Parameter
º SE (output object) .........................................................image Hobject * : byte
Generated structuring element.
º Width (input control) ................................................................integer long
Width of the structuring element.
Default Value : 5
Value Suggestions : Width ¾0, 1, 2, 3, 4, 5, 10, 15, 20
Typical Range of Values : 0 Width 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Height (input control) ...............................................................integer long
Height of the structuring element.
Default Value : 5
Value Suggestions : Height ¾0, 1, 2, 3, 4, 5, 10, 15, 20
Typical Range of Values : 0 Height 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Smax (input control) .................................................................integer long
Maximum gray value of the structuring element.
Default Value : 0
Value Suggestions : Smax ¾0, 1, 2, 5, 10, 20, 30, 40
Typical Range of Values : 0 Smax 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Result
gen disc se returns H MSG TRUE if all parameters are correct. If necessary, an exception is raised.
Parallelization Information
gen disc se is reentrant and processed without parallelization.
Possible Successor Functions
gray erosion, gray dilation, gray opening, gray closing, gray tophat, gray bothat
read gray se
Alternatives
See Also
read image, paint region, paint gray, crop part
Image filters
Module
gray bothat ( Hobject Image, Hobject SE, Hobject *ImageBotHat )
Perform a gray value bottom hat transformation on an image.
gray bothat applies a gray value bottom hat transformation to the input image Image with the structuring
element SE. The gray value bottom hat transformation of an image with a structuring element × is defined as
bothat´ ×µ ´ ¯ ×µ
i.e., the difference of the closing of the image with × and the image (see gray closing). For the generation of
structuring elements, see read gray se.
HALCON 6.0

376 CHAPTER 7. MORPHOLOGY
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageBotHat (output object) ......................................image(-array) Hobject * : byte
Bottom hat image.
Result
gray bothat returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray bothat is reentrant and automatically parallelized (on tuple level).
read gray se, gen disc se
threshold
gray closing
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
gray tophat, top hat, gray erosion rect, sub image
Image filters
Module
gray closing ( Hobject Image, Hobject SE, Hobject *ImageClosing )
Performagrayvalueclosingonanimage.
gray closing applies a gray value closing to the input image Image with the structuring element SE. The gray
value closing of an image with a structuring element × is defined as
¯ × ´ ¨ ×µ © ×
i.e., a dilation of the image with × followed by an erosion with × (see gray dilation and gray erosion).
For the generation of structuring elements, see read gray se.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageClosing (output object) .....................................image(-array) Hobject * : byte
Gray-closed image.
Result
gray closing returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray closing is reentrant and automatically parallelized (on tuple level).
read gray se
dual rank
closing, gray dilation, gray erosion
Possible Predecessor Functions
Alternatives
See Also
HALCON/C Reference Manual / 2000-11-15

7.1. GRAY-VALUES 377
Image filters
Module
gray dilation ( Hobject Image, Hobject SE, Hobject *ImageDilation )
Perform a gray value dilation on an image.
gray dilation applies a gray value dilation to the input image Image with the structuring element SE. The
gray value dilation of an image with a structuring element × at the pixel position Ü is defined as:
´ ¨ ×µ´Üµ ÑÜ ´Ü Þµ ·×´ÞµÞ ¾ Ë
Here, Ë is the domain of the structuring element ×, i.e., the pixels Þ where ×´Þµ ¼ (see read gray se).
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageDilation (output object) ...................................image(-array) Hobject * : byte
Gray-dilated image.
Result
gray dilation returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray dilation is reentrant and automatically parallelized (on tuple level).
read gray se
sub image, gray erosion
gray dilation rect
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
gray opening, gray closing, dilation1, gray skeleton
Image filters
Module
gray dilation rect ( Hobject Image, Hobject *ImageMax, long MaskHeight,
long MaskWidth )
Determine the maximum gray value within a rectangle.
gray dilation rect calculates the maximum gray value of the input image Image within a rectangular mask
of size (MaskHeight, MaskWidth) for each image point. The resulting image is returned in ImageMax. Ifthe
parameters MaskHeight or MaskWidth are even, they are changed to the next larger odd value. At the border
of the image the gray values are mirrored.
Parameter
º Image (input object) .............................image(-array) Hobject : byte / direction / int4 / real
Image for which the maximum gray values are to be calculated.
º ImageMax (output object) ......................image(-array) Hobject * : byte / direction / int4 / real
Image containing the maximum gray values.
HALCON 6.0

378 CHAPTER 7. MORPHOLOGY
º MaskHeight (input control) ........................................................extent.y long
Height of the filter mask.
Default Value : 11
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskHeight 511
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
º MaskWidth (input control) ..........................................................extent.x long
Width of the filter mask.
Default Value : 11
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskWidth 511
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
Result
gray dilation rect returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour
can be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
gray dilation rect is reentrant and automatically parallelized (on tuple level, channel level, domain level).
gray skeleton
Image filters
See Also
Module
gray erosion ( Hobject Image, Hobject SE, Hobject *ImageErosion )
Perform a gray value erosion on an image.
gray erosion applies a gray value erosion to the input image Image with the structuring element SE. The
gray value erosion of an image with a structuring element × at the pixel position Ü is defined as:
´ © ×µ´Üµ ÑÒ ´Ü · Þµ ×´ÞµÞ ¾ Ë
Here, Ë is the domain of the structuring element ×, i.e., the pixels Þ where ×´Þµ ¼ (see read gray se).
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageErosion (output object) .....................................image(-array) Hobject * : byte
Gray-eroded image.
Result
gray erosion returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray erosion is reentrant and automatically parallelized (on tuple level).
read gray se
gray dilation, sub image
gray erosion rect
Possible Predecessor Functions
Possible Successor Functions
Alternatives
HALCON/C Reference Manual / 2000-11-15

7.1. GRAY-VALUES 379
See Also
gray opening, gray closing, erosion1, gray skeleton
Image filters
Module
gray erosion rect ( Hobject Image, Hobject *ImageMin, long MaskHeight,
long MaskWidth )
Determine the minimum gray value within a rectangle.
gray erosion rect calculates the minimum gray value of the input image Image within a rectangular mask
of size (MaskHeight, MaskWidth) for each image point. The resulting image is returned in ImageMin. Ifthe
parameters MaskHeight or MaskWidth are even, they are changed to the next larger odd value. At the border
of the image the gray values are mirrored.
Parameter
º Image (input object) .............................image(-array) Hobject : byte / direction / int4 / real
Image for which the minimum gray values are to be calculated.
º ImageMin (output object) ......................image(-array) Hobject * : byte / direction / int4 / real
Image containing the minimum gray values.
º MaskHeight (input control) ........................................................extent.y long
Height of the filter mask.
Default Value : 11
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskHeight 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
º MaskWidth (input control) ..........................................................extent.x long
Width of the filter mask.
Default Value : 11
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskWidth 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
Result
gray erosion rect returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour
can be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
gray erosion rect is reentrant and automatically parallelized (on tuple level, channel level, domain level).
gray dilation rect
Image filters
See Also
Module
gray opening ( Hobject Image, Hobject SE, Hobject *ImageOpening )
Perform a gray value opening on an image.
gray opening applies a gray value opening to the input image Image with the structuring element SE. The
gray value opening of an image with a structuring element × is defined as
Æ × ´ © ×µ ¨ ×
HALCON 6.0

380 CHAPTER 7. MORPHOLOGY
i.e., an erosion of the image with × followed by a dilation with × (see gray erosion and gray dilation).
For the generation of structuring elements, see read gray se.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageOpening (output object) .....................................image(-array) Hobject * : byte
Gray-opened image.
Result
gray opening returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray opening is reentrant and automatically parallelized (on tuple level).
read gray se
dual rank
opening, gray dilation, gray erosion
Image filters
Possible Predecessor Functions
Alternatives
See Also
Module
gray range rect ( Hobject Image, Hobject *ImageResult, long MaskHeight,
long MaskWidth )
Determine the gray value range within a rectangle.
gray range rect calculates the gray value range, i.e., the difference ´ÑÜ ÑÒµ of the maximum and minimum
gray values, of the input image Image within a rectangular mask of size (MaskHeight, MaskWidth)
for each image point. The resulting image is returned in ImageResult. If the parameters MaskHeight or
MaskWidth are even, they are changed to the next larger odd value. At the border of the image the gray values
are mirrored.
Parameter
º Image (input object) .............................image(-array) Hobject : byte / direction / int4 / real
Image for which the gray value range is to be calculated.
º ImageResult (output object) ..................image(-array) Hobject * : byte / direction / int4 / real
Image containing the gray value range.
º MaskHeight (input control) ........................................................extent.y long
Height of the filter mask.
Default Value : 11
Value Suggestions : MaskHeight ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskHeight 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskHeightµ
º MaskWidth (input control) ..........................................................extent.x long
Width of the filter mask.
Default Value : 11
Value Suggestions : MaskWidth ¾3, 5, 7, 9, 11, 13, 15
Typical Range of Values : 3 MaskWidth 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : odd´MaskWidthµ
HALCON/C Reference Manual / 2000-11-15

7.1. GRAY-VALUES 381
Result
gray range rect returns H MSG TRUE if all parameters are correct. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
gray range rect is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
gray dilation rect, gray erosion rect, sub image
Image filters
Module
gray tophat ( Hobject Image, Hobject SE, Hobject *ImageTopHat )
Performagrayvaluetophattransformationonanimage.
gray tophat applies a gray value top hat transformation to the input image Image with the structuring element
SE. The gray value top hat transformation of an image with a structuring element × is defined as
tophat´ ×µ ´ Æ ×µ
i.e., the difference of the image and its opening with × (see gray opening). For the generation of structuring
elements, see read gray se.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Input image.
º SE (input object) .............................................................image Hobject : byte
Structuring element.
º ImageTopHat (output object) ......................................image(-array) Hobject * : byte
Top hat image.
Result
gray tophat returns H MSG TRUE if the structuring element is not the empty region. Otherwise, an exception
is raised.
Parallelization Information
gray tophat is reentrant and automatically parallelized (on tuple level).
read gray se, gen disc se
threshold
gray opening
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
gray bothat, top hat, gray erosion rect, sub image
Image filters
Module
read gray se ( Hobject *SE, const char *FileName )
Load a structuring element for gray morphology.
read gray se loads a structuring element for gray morphology from a file. The file names of these structuring
elements must end in ’.gse’ (for gray-scale structuring element). This suffix is automatically appended by
read gray se to the passed file name, and thus must not be passed. The structuring element’s data must be
HALCON 6.0

382 CHAPTER 7. MORPHOLOGY
contained in the file in the following format: The first two numbers in the file determine the width and height of
the structuring element, and determine a rectangle enclosing the structuring element. Both values must be greater
than 0. Then, Width*Height integer numbers follow, with the following interpretation: Values smaller than 0 are
regarded as not belonging to the region of the structuring element, i.e., they are not considered in morphological
operations. This allows the creation of irregularly shaped, not connected structuring elements. All other values
are regarded as the corresponding values for gray morphology. Structuring elements are stored internally as byteimages,
with negative values being mapped to 0, and all other values increased by 1. Thus, normal byte-images
can also be used as structuring elements. However, care should be taken not to use too large images, since the
runtime is proportional to the area of the image times the area of the structuring element.
Parameter
º SE (output object) .........................................................image Hobject * : byte
Generated structuring element.
º FileName (input control) ...................................................filename const char *
Name of the file containing the structuring element.
Result
read gray se returns H MSG TRUE if all parameters are correct. If the file cannot be opened, H MSG FAIL
is returned. Otherwise, an exception is raised.
Parallelization Information
read gray se is reentrant and processed without parallelization.
Possible Successor Functions
gray erosion, gray dilation, gray opening, gray closing, gray tophat, gray bothat
gen disc se
Alternatives
See Also
read image, paint region, paint gray, crop part
Image filters
Module
7.2 Region
bottom hat ( Hobject Region, Hobject StructElement,
Hobject *RegionBottomHat )
Compute the bottom hat of regions.
bottom hat computes the closing of Region with StructElement. The difference between the result of
the closing and the original region is called the bottom hat. In contrast to closing, which merges regions under
certain circumstances, bottom hat computes the regions generated by such a merge.
The position of StructElement is meaningless, since a closing operation is invariant with respect to the choice
of the reference point.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement (input object) ...................................................region Hobject
Structuring element (position independent).
º RegionBottomHat (output object) .......................................region(-array) Hobject *
Result of the bottom hat operator.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 383
Example
threshold(Image,&Regions,128.0,255.0);
gen_circle(&Circle,128.0,128.0,16.0);
bottom_hat(Regions,Circle,&RegionBottomHat);
set_color(WindowHandle,"red");
disp_region(Regions,WindowHandle);
set_color(WindowHandle,"green");
disp_region(RegionBottomHat,WindowHandle);
Result
bottom hat returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
bottom hat is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
closing, difference
Alternatives
See Also
top hat, morph hat, gray bothat, opening
Morphology
Module
boundary ( Hobject Region, Hobject *RegionBorder,
const char *BoundaryType )
Reduce a region to its boundary.
boundary computes the boundary of a region by using morphological operations. The parameter
BoundaryType determines the type of boundary to compute:
’inner’, ’inner filled’ and ’outer’.
boundary computes the contour of each input region. The resulting regions consist only of the minimal border
of the input regions. If BoundaryType is set to ’inner’, the contour lies within the original region, if it is set
to ’outer’, it is one pixel outside of the original region. If BoundaryType is set to ’inner filled’, holes in the
interior of the input region are suppressed.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions for which the boundary is to be computed.
º RegionBorder (output object) ...........................................region(-array) Hobject *
Resulting boundaries.
º BoundaryType (input control) .................................................string const char *
Boundary type.
Default Value : ’inner’
Value List : BoundaryType ¾’inner’, ’outer’, ’inner filled’
HALCON 6.0

384 CHAPTER 7. MORPHOLOGY
Example
/* Intersections of two circles: */
gen_circle(&Circle1,200.0,100.0,100.5);
gen_circle(&Circle2,200.0,150.0,100.5);
boundary(Circle1,&Margin1,"inner");
boundary(Circle2,&Margin2,"inner");
intersection(Margin1,Margin2,&Intersections);
connection(Intersections,&Single);
T_area_center(Single,_,&Rows,&Columns);
/* simulation of Mode ’inner’ */
void inner(Hobject Region, Hobject *Border)
{
Hobject Smaller;
erosion_circle(Region,&Smaller,1.5);
difference(Region,Smaller,Border);
clear_obj(Smaller);
}
Complexity
Let be the area of the input region. Then the runtime complexity for one region is
Ç´¿Ô
µ
Result
boundary returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
boundary is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
dilation circle, erosion circle, difference
fill up
Morphology
See Also
Module
closing ( Hobject Region, Hobject StructElement,
Hobject *RegionClosing )
Close a region.
A closing operation is defined as a dilation followed by a Minkowsi subtraction. By applying closing to
a region, larger structures remain mostly intact, while small gaps between adjacent regions and holes smaller
than StructElement are closed, and the regions’ boundaries are smoothed. All closing variants share the
property that separate regions are not merged, but remain separate objects. The position of StructElement is
meaningless, since a closing operation is invariant with respect to the choice of the reference point.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 385
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Attention
closing is applied to each input region separately. If gaps between different regions are to be closed, union1
or union2 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be closed.
º StructElement (input object) ...................................................region Hobject
Structuring element (position-invariant).
º RegionClosing (output object) ..........................................region(-array) Hobject *
Closed regions.
Example
my_closing(Hobject In, Hobject StructElement, Hobject *Out)
{
Hobject tmp;
dilation1(In,StructElement,&tmp,1);
minkowski_sub1(tmp,StructElement,Out,1);
clear_obj(tmp);
}
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´¾ ¡ Ô ½ ¡ Ô ¾µ
Result
closing returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
closing is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
closing circle, closing golay
Alternatives
See Also
dilation1, erosion1, opening, minkowski sub1
Morphology
Module
closing circle ( Hobject Region, Hobject *RegionClosing, double Radius )
Close a region with a circular structuring element.
HALCON 6.0

386 CHAPTER 7. MORPHOLOGY
closing circle behaves analogously to closing, i.e., the regions’ boundaries are smoothed and holes
within a region which are smaller than the circular structuring element of radius Radius are closed. The
closing circle operation is defined as a dilation followed by a Minkowski subtraction, both with the same
circular structuring element.
Attention
closing circle is applied to each input region separately. If gaps between different regions are to be closed,
union1 or union2 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be closed.
º RegionClosing (output object) ..........................................region(-array) Hobject *
Closed regions.
º Radius (input control) .........................................................real double / long
Radius of the circular structuring element.
Default Value : 3.5
Value Suggestions : Radius ¾1.5, 2.5, 3.5, 4.5, 5.5, 7.5, 9.5, 12.5, 15.5, 19.5, 25.5, 33.5, 45.5, 60.5,
110.5
Typical Range of Values : 0.5 Radius 511.5 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Example
my_closing_circle(Hobject In, double Radius, Hobject *Out)
{
Hobject tmp, StructElement;
gen_circle(StructElement,100.0,100.0,Radius);
dilation1(In,StructElement,&tmp,1);
minkowski_sub1(tmp,StructElement,Out,1);
clear_obj(tmp); clear_obj(StructElement);
}
Complexity
Let ½ be the area of the input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô ½ ¡ ÊÙ×µ
Result
closing circle returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
closing circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
rank region, fill up, closing, closing circle, closing golay
See Also
dilation1, minkowski sub1, erosion1, opening
Morphology
Module
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 387
closing golay ( Hobject Region, Hobject *RegionClosing,
const char *GolayElement, long Rotation )
Close a region with an element from the Golay alphabet.
closing golay is defined as a Minkowski addition followed by a Minkowski subtraction. First the Minkowski
addition of the input region (Region) with the structuring element from the Golay alphabet defined by
GolayElement and Rotation is computed. Then the Minkowski subtraction of the result and the structuring
element rotated by 180 Æ is performed.
The following structuring elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used, and whether the foreground
(even) or background version (odd) of the selected element should be used. The Golay elements, together
with all possible rotations, are described with the operator golay elements.
closing golay serves to close holes smaller than the structuring element, and to smooth regions’ boundaries.
Attention
Not all values of Rotation are valid for any Golay element. For some of the values of Rotation, the resulting
regions are identical to the input regions.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be closed.
º RegionClosing (output object) ..........................................region(-array) Hobject *
Closed regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô µ
Result
closing golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
closing golay is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
closing
Alternatives
See Also
erosion golay, dilation golay, opening golay, hit or miss golay, thinning golay,
thickening golay, golay elements
HALCON 6.0

388 CHAPTER 7. MORPHOLOGY
Morphology
Module
closing rectangle1 ( Hobject Region, Hobject *RegionClosing,
long Width, long Height )
Close a region with a rectangular structuring element.
closing rectangle1 performs a dilation rectangle1 followed by an erosion rectangle1 on
the input region Region. The size of the rectangular structuring element is determined by the parameters Width
and Height. As is the case for all closing variants, regions’ boundaries are smoothed and holes within a region
which are smaller than the rectangular structuring element are closed.
Attention
closing rectangle1 is applied to each input region separately. If gaps between different regions are to be
closed, union1 or union2 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be closed.
º RegionClosing (output object) ..........................................region(-array) Hobject *
Closed regions.
º Width (input control) .......................................................extent.x long / double
Width of the structuring rectangle.
Default Value : 10
Value Suggestions : Width ¾1, 2, 3, 4, 5, 7, 9, 12, 15, 19, 25, 33, 45, 60, 110, 150, 200
Typical Range of Values : 1 Width 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Height (input control) .....................................................extent.y long / double
Height of the structuring rectangle.
Default Value : 10
Value Suggestions : Height ¾1, 2, 3, 4, 5, 7, 9, 12, 15, 19, 25, 33, 45, 60, 110, 150, 200
Typical Range of Values : 1 Height 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of an input region and À be the height of the rectangle. Then the runtime complexity for one
region is:
Ç´¾ ¡ Ô ½ ¡ ÐÓ ¾´Àµµ
Result
closing rectangle1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or
no input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
closing rectangle1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 389
closing
Alternatives
See Also
dilation rectangle1, erosion rectangle1, opening rectangle1, gen rectangle1
Morphology
Module
dilation1 ( Hobject Region, Hobject StructElement,
Hobject *RegionDilation, long Iterations )
Dilate a region.
dilation1 dilates the input regions with a structuring element. By applying dilation1 to a region, its
boundary gets smoothed. In the process, the area of the region is enlarged. Furthermore, disconnected regions
may be merged. Such regions, however, remain logically distinct region. The dilation is a set-theoretic region
operation. It uses the union operation.
Let Å (StructElement) andÊ (Region) be two regions, where Å is the structuring element and Ê is the
region to be processed. Furthermore, let Ñ be a point in Å. Then the displacement vector Ú Ñ ´Ü ݵ is
defined as the difference of the center of gravity of Å and the vector Ñ. LetØ ÚѴʵ denote the translation of a
region Ê by a vector Ú. Then
ÐØÓÒ½´Ê ŵ
ѾÅ
Ø Ú Ñ ´Êµ
For each point Ñ in Å a translation of the region Ê is performed. The union of all these translations is the dilation
of Ê with Å. dilation1 is similar to the operator minkowski add1, the difference is that in dilation1
the structuring element is mirrored at the origin. The position of StructElement is meaningless, since the
displacement vectors are determined with respect to the center of gravity of Å.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò. From the above definition it follows that an
empty region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Attention
A dilation always results in enlarged regions. Closely spaced regions which may touch or overlap as a result of
the dilation are still treated as two separate regions. If the desired behavior is to merge them into one region, the
operator union1 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
HALCON 6.0

390 CHAPTER 7. MORPHOLOGY
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
dilation1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, add channels, select shape, area center, connection
Alternatives
minkowski add1, minkowski add2, dilation2, dilation golay, dilation seq
erosion1, erosion2, opening, closing
Morphology
See Also
Module
dilation2 ( Hobject Region, Hobject StructElement,
Hobject *RegionDilation, long Row, long Column, long Iterations )
Dilate a region (using a reference point).
dilation2 dilates the input regions with a structuring element (StructElement) having the reference point
(Row,Column). dilation2 has a similar effect as dilation1, the difference is that the reference point of the
structuring element can be chosen arbitrarily. The parameter Iterations determines the number of iterations
which are to be performed with the structuring element. The result of iteration Ò ½ is used as input for iteration
Ò.
An empty region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Attention
A dilation always results in enlarged regions. Closely spaced regions which may touch or overlap as a result of
the dilation are still treated as two separate regions. If the desired behavior is to merge them into one region, the
operator union1 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 0
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 391
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 0
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 7, 11, 17, 25, 32, 64, 128
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
dilation2 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation2 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, add channels, select shape, area center, connection
Alternatives
minkowski add1, minkowski add2, dilation1, dilation golay, dilation seq
erosion1, erosion2, opening, closing
Morphology
See Also
Module
dilation circle ( Hobject Region, Hobject *RegionDilation,
double Radius )
Dilate a region with a circular structuring element.
dilation circle applies a Minkowski addition with a circular structuring element to the input regions
Region. Because the circular mask is symmetrical, this is identical to a dilation. The size of the circle used
as structuring element is determined by Radius.
The operator results in enlarged regions, smoothed region boundaries, and the holes smaller than the circular mask
in the interior of the region are closed. It is useful to select only values like ¿, , etc.forRadius in order
to avoid a translation of a region, because integer radii result in the circle having a non-integer center of gravity
which is rounded to the next integer.
Attention
dilation circle is applied to each input region separately. If gaps between different regions are to be closed,
union1 or union2 has to be called first.
HALCON 6.0

392 CHAPTER 7. MORPHOLOGY
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º Radius (input control) .........................................................real double / long
Radius of the circular structuring element.
Default Value : 3.5
Value Suggestions : Radius ¾1.5, 2.5, 3.5, 4.5, 5.5, 7.5, 9.5, 12.5, 15.5, 19.5, 25.5, 33.5, 45.5, 60.5,
110.5
Typical Range of Values : 0.5 Radius 511.5 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Example
my_dilation_circle(Hobject In, double Radius, Hobject *Out)
{
Hobject Circle;
gen_circle(&Circle,100.0,100.0,Radius);
minkowski_add1(In,Circle,Out,1);
clear_obj(Circle);
}
Complexity
Let ½ be the area of an input region. Then the runtime complexity for one region is:
Ç´¾ ¡ ÊÙ× ¡ Ô ½µ
Result
dilation circle returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
minkowski add1, minkowski add2, expand region, dilation1, dilation2,
dilation rectangle1
See Also
gen circle, erosion circle, closing circle, opening circle
Morphology
Module
dilation golay ( Hobject Region, Hobject *RegionDilation,
const char *GolayElement, long Iterations, long Rotation )
Dilate a region with an element from the Golay alphabet.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 393
dilation golay dilates a region with the selected element GolayElement from the Golay alphabet. The
following structuring elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used, and whether the foreground
(even) or background version (odd) of the selected element should be used. The Golay elements, together
with all possible rotations, are described with the operator golay elements. The operator works by shifting
the structuring element over the region to be processed (Region). For all positions of the structuring element that
intersect the region, the corresponding reference point (relative to the structuring element) is added to the output
region. This means that the union of all translations of the structuring element within the region is computed.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò.
Attention
Not all values of Rotation are valid for any Golay element. For some of the values of Rotation, the resulting
regions are identical to the input regions.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´¿ ¡ Ô µ
Result
dilation golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation golay is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
dilation1, dilation2, dilation seq
Alternatives
HALCON 6.0

394 CHAPTER 7. MORPHOLOGY
See Also
erosion golay, opening golay, closing golay, hit or miss golay, thinning golay,
thickening golay, golay elements
Morphology
Module
dilation rectangle1 ( Hobject Region, Hobject *RegionDilation,
long Width, long Height )
Dilate a region with a rectangular structuring element.
dilation rectangle1 applies a dilation with a rectangular structuring element to the input regions Region.
The size of the structuring rectangle is Width ¢ Height. The operator results in enlarged regions, and the holes
smaller than the rectangular mask in the interior of the regions are closed.
dilation rectangle1 is a very fast operation because the height of the rectangle enters only logarithmically
into the runtime complexity, while the width does not enter at all. This leads to excellent runtime efficiency, even
in the case of very large rectangles (edge length 100).
Attention
dilation rectangle1 is applied to each input region separately. If gaps between different regions are to be
closed, union1 or union2 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º Width (input control) ...............................................................extent.x long
Width of the structuring rectangle.
Default Value : 10
Value Suggestions : Width ¾1, 2, 3, 4, 6, 10, 15, 20, 30, 50, 70, 100, 150, 200
Typical Range of Values : 1 Width 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Height (input control) ..............................................................extent.y long
Height of the structuring rectangle.
Default Value : 10
Value Suggestions : Height ¾1, 2, 3, 4, 6, 10, 15, 20, 30, 50, 70, 100, 150, 200
Typical Range of Values : 1 Height 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Example
threshold(Image,&Light,220.0,255.0);
dilation_rectangle1(Light,&Wide,50,50);
set_color(WindowHandle,"red");
disp_region(Wide,WindowHandle);
set_color(WindowHandle,"white");
disp_region(Light,WindowHandle);
Complexity
Let ½ be the area of an input region and À be the height of the rectangle. Then the runtime complexity for one
region is:
Ç´Ô
½ ¡ дÀµµ
Result
dilation rectangle1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or
no input region can be set via:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 395
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation rectangle1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
minkowski add1, minkowski add2, expand region, dilation1, dilation2,
dilation circle
See Also
gen rectangle1, gen region polygon filled
Morphology
Module
dilation seq ( Hobject Region, Hobject *RegionDilation,
const char *GolayElement, long Iterations )
Dilate a region sequentially.
dilation seq computes the sequential dilation of the input region Region with the selected structuring element
GolayElement from the Golay alphabet. This is done by executing the operator dilation golay with
all rotations of the structuring element Iterations times. The following structuring elements can be selected:
’l’, ’d’, ’c’, ’f’, ’h’, ’k’.
In order to compute the skeleton of a region, usually the elements ’l’ and ’m’ are used. Only the “foreground
elements” (even rotation numbers) are used. The elements ’i’ and ’e’ result in unchanged output regions. The
elements ’l’, ’m’ and ’f2’ are identical for the foreground. The Golay elements, together with all possible rotations,
are described with the operator golay elements.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º RegionDilation (output object) ........................................region(-array) Hobject *
Dilated regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’d’, ’c’, ’f’, ’h’, ’k’
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ÁØÖØÓÒ× ¡ ¾¼ ¡ Ô µ
Result
dilation seq returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
HALCON 6.0

396 CHAPTER 7. MORPHOLOGY
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
dilation seq is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
dilation1, dilation2, dilation golay
See Also
erosion seq, hit or miss seq, thinning seq
Morphology
Module
erosion1 ( Hobject Region, Hobject StructElement,
Hobject *RegionErosion, long Iterations )
Erode a region.
erosion1 erodes the input regions with a structuring element. By applying erosion1 to a region, its boundary
gets smoothed. In the process, the area of the region is reduced. Furthermore, connected regions may be split.
Such regions, however, remain logically one region. The erosion is a set-theoretic region operation. It uses the
intersection operation.
Let Å (StructElement) andÊ (Region) be two regions, where Å is the structuring element and Ê is the
region to be processed. Furthermore, let Ñ be a point in Å. Then the displacement vector Ú Ñ ´Ü ݵ is
defined as the difference of the center of gravity of Å and the vector Ñ. LetØ ÚѴʵ denote the translation of a
region Ê by a vector Ú. Then
ÖÓ×ÓÒ½´Ê ŵ
ѾÅ
Ø Ú Ñ´Êµ
For each point Ñ in Å a translation of the region Ê is performed. The intersection of all these translations is
the erosion of Ê with Å. erosion1 is similar to the operator minkowski sub1, the difference is that in
erosion1 the structuring element is mirrored at the origin. The position of StructElement is meaningless,
since the displacement vectors are determined with respect to the center of gravity of Å.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò. From the above definition it follows that the
maximum region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 397
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
erosion1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm, gen circle, gen ellipse,
gen rectangle1, gen rectangle2, draw region, gen region points,
gen struct elements, gen region polygon filled
Possible Successor Functions
connection, reduce domain, select shape, area center
Alternatives
minkowski sub1, minkowski sub2, erosion2, erosion golay, erosion seq
transpose region
Morphology
See Also
Module
erosion2 ( Hobject Region, Hobject StructElement,
Hobject *RegionErosion, long Row, long Column, long Iterations )
Erode a region (using a reference point).
erosion2 erodes the input regions with a structuring element (StructElement) having the reference point
(Row,Column). erosion2 has a similar effect as erosion1, the difference is that the reference point of the
structuring element can be chosen arbitrarily. The parameter Iterations determines the number of iterations
which are to be performed with the structuring element. The result of iteration Ò ½ is used as input for iteration
Ò.
A maximum region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
HALCON 6.0

398 CHAPTER 7. MORPHOLOGY
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 0
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 0
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
erosion2 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion2 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm, gen circle, gen ellipse,
gen rectangle1, gen rectangle2, draw region, gen region points,
gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
minkowski sub2, minkowski sub1, erosion1, erosion golay, erosion seq
See Also
transpose region, gen circle, gen rectangle2, gen region polygon
Morphology
Module
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 399
erosion circle ( Hobject Region, Hobject *RegionErosion, double Radius )
Erode a region with a circular structuring element.
erosion circle applies a Minkowski subtraction with a circular structuring element to the input regions
Region. Because the circular mask is symmetrical, this is identical to an erosion. The size of the circle used
as structuring element is determined by Radius.
The operator results in reduced regions, smoothed region boundaries, and the regions smaller than the circular
mask are eliminated. It is useful to select only values like ¿, ,etc.forRadius in order to avoid a translation
of a region, because integer radii result in a circle having a non-integer center of gravity which is rounded to the
next integer.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
º Radius (input control) .........................................................real double / long
Radius of the circular structuring element.
Default Value : 3.5
Value Suggestions : Radius ¾1.5, 2.5, 3.5, 4.5, 5.5, 7.5, 9.5, 12.5, 15.5, 19.5, 25.5, 33.5, 45.5, 60.5,
110.5
Typical Range of Values : 0.5 Radius 511.5 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Example
my_erosion_circle(Hobject In, double Radius, Hobject *Out)
{
Hobject Circle;
gen_circle(&Circle,100.0,100.0,Radius);
minkowski_sub1(In,Circle,Out,1);
clear_obj(Circle);
}
Complexity
Let ½ be the area of an input region. Then the runtime complexity for one region is:
Ç´¾ ¡ ÊÙ× ¡ Ô ½µ
Result
erosion circle returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm
Possible Successor Functions
connection, reduce domain, select shape, area center
minkowski sub1
Alternatives
HALCON 6.0

400 CHAPTER 7. MORPHOLOGY
See Also
gen circle, dilation circle, closing circle, opening circle
Morphology
Module
erosion golay ( Hobject Region, Hobject *RegionErosion,
const char *GolayElement, long Iterations, long Rotation )
Erode a region with an element from the Golay alphabet.
erosion golay erodes a region with the selected element GolayElement from the Golay alphabet. The
following structuring elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used, and whether the foreground
(even) or background version (odd) of the selected element should be used. The Golay elements, together
with all possible rotations, are described with the operator golay elements. The operator works by shifting
the structuring element over the region to be processed (Region). For all positions of the structuring element
fully contained in the region, the corresponding reference point (relative to the structuring element) is added to the
output region. This means that the intersection of all translations of the structuring element within the region is
computed.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò.
Attention
Not all values of Rotation are valid for any Golay element. For some of the values of Rotation, the resulting
regions are identical to the input regions.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´¿ ¡ Ô µ
Result
erosion golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 401
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion golay is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
erosion seq, erosion1, erosion2
Alternatives
See Also
dilation golay, opening golay, closing golay, hit or miss golay, thinning golay,
thickening golay, golay elements
Morphology
Module
erosion rectangle1 ( Hobject Region, Hobject *RegionErosion,
long Width, long Height )
Erode a region with a rectangular structuring element.
erosion rectangle1 applies an erosion with a rectangular structuring element to the input regions Region.
The size of the structuring rectangle is Width ¢ Height. The operator results in reduced regions, and the areas
smaller than the rectangular mask are eliminated.
erosion rectangle1 is a very fast operation because the height of the rectangle enters only logarithmically
into the runtime complexity, while the width does not enter at all. This leads to excellent runtime efficiency, even
in the case of very large rectangles (edge length 100).
Regions containing small connecting strips between large areas are separated only seemingly. They remain logically
one region.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
º Width (input control) ...............................................................extent.x long
Width of the structuring rectangle.
Default Value : 10
Value Suggestions : Width ¾1, 2, 3, 4, 6, 10, 15, 20, 30, 50, 70, 100
Typical Range of Values : 1 Width 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Height (input control) ..............................................................extent.y long
Height of the structuring rectangle.
Default Value : 10
Value Suggestions : Height ¾1, 2, 3, 4, 6, 10, 15, 20, 30, 50, 70, 100
Typical Range of Values : 1 Height 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of an input region and À be the height of the rectangle. Then the runtime complexity for one
region is:
Ô
Ç´ ½ ¡ дÀµµ
HALCON 6.0

402 CHAPTER 7. MORPHOLOGY
Result
erosion rectangle1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or
no input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion rectangle1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
erosion1, minkowski sub1
gen rectangle1
Morphology
Alternatives
See Also
Module
erosion seq ( Hobject Region, Hobject *RegionErosion,
const char *GolayElement, long Iterations )
Erode a region sequentially.
erosion seq computes the sequential erosion of the input region Region with the selected structuring element
GolayElement from the Golay alphabet. This is done by executing the operator erosion golay with all
rotations of the structuring element Iterations times. The following structuring elements can be selected:
’l’, ’d’, ’c’, ’f’, ’h’, ’k’.
Only the “foreground elements” (even rotation numbers) are used. The elements ’i’ and ’e’ result in unchanged
output regions. The elements ’l’, ’m’ and ’f2’ are identical for the foreground. The Golay elements, together with
all possible rotations, are described with the operator golay elements.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º RegionErosion (output object) ..........................................region(-array) Hobject *
Eroded regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’d’, ’c’, ’f’, ’h’, ’k’
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ÁØÖØÓÒ× ¡ ¾¼ ¡ Ô µ
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 403
Result
erosion seq returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
erosion seq is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm
Possible Successor Functions
connection, reduce domain, select shape, area center
erosion golay, erosion1, erosion2
Alternatives
See Also
dilation seq, hit or miss seq, thinning seq
Morphology
Module
fitting ( Hobject Region, Hobject StructElements,
Hobject *RegionFitted )
Perform a closing after an opening with multiple structuring elements.
fitting performs an opening and a closing successively on the input regions. The eight structuring elements
normally used for this operation can be generated with the operator gen struct elements. However,
other user-defined structuring elements can also be used. Let Ê be the input region(s) and let Å denote the structuring
elements. Furthermore, let È be the result of the opening and É be the final result. Then the operator can
be formalized as follows:
È
É
Ò
Ò
½
½
´Ê Æ Å µ
´È ¯ Å µ
Regions larger than the structuring elements are preserved, while small gaps are closed.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElements (input object) ...........................................region(-array) Hobject
Structuring elements.
º RegionFitted (output object) ...........................................region(-array) Hobject *
Fitted regions.
Result
fitting returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
HALCON 6.0

404 CHAPTER 7. MORPHOLOGY
Otherwise, an exception is raised.
Parallelization Information
fitting is reentrant and processed without parallelization.
Possible Predecessor Functions
gen struct elements, gen region points
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
opening, closing, connection, select shape
Morphology
Module
gen struct elements ( Hobject *StructElements, const char *Type,
long Row, long Column )
Generate standard structuring elements.
gen struct elements serves to generate eight structuring elements normally used in the operator fitting.
The default value ’noise’ of the parameter Type generates elements especially suited for the elimination of noise.
Ü
Ü
Ü
Ü Ü Ü
Ü
Ü
Ü
Ü
Ü
Ü
Å ½
Å ¾
Å ¿
Å
Ü
Ü
Ü Ü
Ü Ü
Ü Ü
Ü Ü
Ü
Ü
Å
Å
Parameter
Å
Å
º StructElements (output object) ........................................region(-array) Hobject *
Generated structuring elements.
º Type (input control) ............................................................string const char *
Type of structuring element to generate.
Default Value : ’noise’
Value List : Type ¾’noise’
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 1
Value Suggestions : Row ¾0, 1, 10, 50, 100, 200, 300, 400
Typical Range of Values : ½ Row ½(lin)
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 1
Value Suggestions : Column ¾0, 1, 10, 50, 100, 200, 300, 400
Typical Range of Values : ½ Column ½(lin)
Result
gen struct elements returns H MSG TRUE if all parameters are correct. Otherwise, an exception is raised.
Parallelization Information
gen struct elements is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 405
Possible Successor Functions
fitting, hit or miss, opening, closing, erosion2, dilation2
golay elements
Morphology
See Also
Module
golay elements ( Hobject *StructElement1, Hobject *StructElement2,
const char *GolayElement, long Rotation, long Row, long Column )
Generate the structuring elements of the Golay alphabet.
golay elements generates the structuring elements from the Golay alphabet. The parameter GolayElement
determines the name of the structuring element, while Rotation determines its rotation. The structuring elements
are intended for use in hit or miss: In StructElement1 the structuring element for the foreground is
returned, while in StructElement2 the structuring element for the background is returned. Row and Column
determine the reference point of the structuring element.
The rotations are numbered from 0 to 15. This does not mean, however, that there are 16 different rotations: Even
values denote rotations of the foreground elements, while odd values denote rotations of the background elements.
For golay elements only even values are accepted, and determine the Golay element for StructElement1.
The next larger odd value is used for StructElement2. There are no rotations for the Golay elements ’h’ and ’i’.
Therefore, only the values 0 and 1 are possible as “rotations” (and hence only 0 for golay elements). The element
’e’ has only four possible rotations, and hence the rotation must be between 0 and 7 (for golay elements
thevalues0,2,4,or6mustbeused).
The tables below show the elements of the Golay alphabet with all possible rotations. The characters used have
the following meaning:
¯ Foreground pixel
Æ Background pixel
¡ Don’t care pixel
The names of the elements and their rotation numbers are displayed below the respective element. The elements
with even number contain the foreground pixels, while the elements with odd numbers contain the background
pixels.
¯ ¯ ¯
¯ ¯ ¯
¯ ¯ ¯
h(0,1)
Æ Æ Æ
Æ Æ Æ
Æ Æ Æ
i(0,1)
¡ ¡ ¡
Æ ¯ Æ
Æ Æ Æ
e(0,1)
Æ Æ ¡
Æ ¯ ¡
Æ Æ ¡
e(2,3)
Æ Æ Æ
Æ ¯ Æ
¡ ¡ ¡
e(4,5)
¡ Æ Æ
¡ ¯ Æ
¡ Æ Æ
e(6,7)
Æ Æ Æ
¡ ¯ ¡
¯ ¯ ¯
l(0,1)
Æ
¡ ¡ Æ
¯ ¡ ¯ ¡ Æ
¯ ¡ ¡
¯
l(2,3)
¯ ¡ Æ
¯ ¯ Æ
¯ ¡ Æ
l(4,5)
¯
¯ ¡ ¡
¯ ¡ ¯ ¡ Æ
¡ ¡ Æ
Æ
l(6,7)
HALCON 6.0

406 CHAPTER 7. MORPHOLOGY
¯ ¯ ¯
¡ ¯ ¡
Æ Æ Æ
l(8,9)
¯
¡ ¡ ¯
Æ ¡ ¯ ¡ ¯
Æ ¡ ¡
Æ
l(10,11)
Æ ¡ ¯
Æ ¯ ¯
Æ ¡ ¯
l(12,13)
Æ
Æ ¡ ¡
Æ ¡ ¯ ¯
¡ ¡ ¯
¯
l(14,15)
¯ ¡ ¡
¯ ¯ Æ
¯ ¡ ¡
m(0,1)
¯
¯ ¡ ¡
¯ ¡ ¯ ¡ ¡
¡ ¡ Æ
¡
m(2,3)
¯ ¯ ¯
¡ ¯ ¡
¡ Æ ¡
m(4,5)
¯
¡ ¡ ¯
¡ ¡ ¯ ¡ ¯
Æ ¡ ¡
¡
m(6,7)
¡ ¡ ¯
Æ ¯ ¯
¡ ¡ ¯
m(8,9)
¡
Æ ¡ ¡
¡ ¡ ¯ ¡ ¯
¡ ¡ ¯
¯
m(10,11)
¡ Æ ¡
¡ ¯ ¡
¯ ¯ ¯
m(12,13)
¡
¡ ¡ Æ
¯ ¡ ¯ ¡ ¡
¯ ¡ ¡
¯
m(14,15)
Æ ¡ ¡
Æ ¯ ¯
Æ ¡ ¡
d(0,1)
Æ
Æ ¡ ¡
Æ ¡ ¯ ¡ ¡
¡ ¡ ¯
¡
d(2,3)
Æ Æ Æ
¡ ¯ ¡
¡ ¯ ¡
d(4,5)
Æ
¡ ¡ Æ
¡ ¡ ¯ ¡ Æ
¯ ¡ ¡
¡
d(6,7)
¡ ¡ Æ
¯ ¯ Æ
¡ ¡ Æ
d(8,9)
¡
¯ ¡ ¡
¡ ¡ ¯ ¡ Æ
¡ ¡ Æ
Æ
d(10,11)
¡ ¯ ¡
¡ ¯ ¡
Æ Æ Æ
d(12,13)
¡
¡ ¡ ¯
Æ ¡ ¯ ¡ ¡
Æ ¡ ¡
Æ
d(14,15)
¯ Æ Æ
Æ ¯ ¯
¯ Æ Æ
f(0,1)
¯
Æ ¯ Æ
¯ ¯ ¯ ¡ Æ
Æ ¡ ¯
Æ
f(2,3)
¯ Æ ¯
Æ ¯ Æ
Æ ¯ Æ
f(4,5)
¯
Æ ¯ Æ
Æ ¡ ¯ ¯ ¯
¯ ¡ Æ
Æ
f(6,7)
Æ Æ ¯
¯ ¯ Æ
Æ Æ ¯
f(8,9)
Æ
¯ ¡ Æ
Æ ¡ ¯ ¯ ¯
Æ ¯ Æ
¯
f(10,11)
Æ ¯ Æ
Æ ¯ Æ
¯ Æ ¯
f(12,13)
Æ
Æ ¡ ¯
¯ ¯ ¯ ¡ Æ
Æ ¯ Æ
¯
f(14,15)
¯ ¯ ¯
Æ ¯ Æ
Æ Æ Æ
f2(0,1)
¯
Æ ¡ ¯
Æ ¡ ¯ ¡ ¯
Æ ¡ Æ
Æ
f2(2,3)
Æ Æ ¯
Æ ¯ ¯
Æ Æ ¯
f2(4,5)
Æ
Æ ¡ Æ
Æ ¡ ¯ ¡ ¯
Æ ¡ ¯
¯
f2(6,7)
Æ Æ Æ
Æ ¯ Æ
¯ ¯ ¯
f2(8,9)
Æ
Æ ¡ Æ
¯ ¡ ¯ ¡ Æ
¯ ¡ Æ
¯
f2(10,11)
¯ Æ Æ
¯ ¯ Æ
¯ Æ Æ
f2(12,13)
¯
¯ ¡ Æ
¯ ¡ ¯ ¡ Æ
Æ ¡ Æ
Æ
f2(14,15)
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 407
¯ ¯ Æ
¡ ¯ ¡
¡ ¡ ¡
k(0,1)
¯
¡ ¡ ¯
¡ ¡ ¯ ¡ Æ
¡ ¡ ¡
¡
k(2,3)
¡ ¡ ¯
¡ ¯ ¯
¡ ¡ Æ
k(4,5)
¡
¡ ¡ ¡
¡ ¡ ¯ ¡ ¯
¡ ¡ ¯
Æ
k(6,7)
¡ ¡ ¡
¡ ¯ ¡
Æ ¯ ¯
k(8,9)
¡
¡ ¡ ¡
Æ ¡ ¯ ¡ ¡
¯ ¡ ¡
¯
k(10,11)
Æ ¡ ¡
¯ ¯ ¡
¯ ¡ ¡
k(12,13)
Æ
¯ ¡ ¡
¯ ¡ ¯ ¡ ¡
¡ ¡ ¡
¡
k(14,15)
¯ ¡ ¡
¯ Æ ¡
¯ ¡ ¡
c(0,1)
¯
¯ ¡ ¡
¯ ¡ Æ ¡ ¡
¡ ¡ ¡
¡
c(2,3)
¯ ¯ ¯
¡ Æ ¡
¡ ¡ ¡
c(4,5)
¯
¡ ¡ ¯
¡ ¡ Æ ¡ ¯
¡ ¡ ¡
¡
c(6,7)
¡ ¡ ¯
¡ Æ ¯
¡ ¡ ¯
c(8,9)
¡
¡ ¡ ¡
¡ ¡ Æ ¯
¡ ¡ ¯
¯
c(10,11)
¡ ¡ ¡
¡ Æ ¡
¯ ¯ ¯
c(12,13)
¡
¡ ¡ ¡
¯ Æ ¡ ¡
¯ ¡ ¡
¯
c(14,15)
Parameter
º StructElement1 (output object) ...............................................region Hobject *
Structuring element for the foreground.
º StructElement2 (output object) ...............................................region Hobject *
Structuring element for the background.
º GolayElement (input control) .................................................string const char *
Name of the structuring element.
Default Value : ’l’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 16
Value Suggestions : Row ¾0, 16, 32, 128, 256
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 16
Value Suggestions : Column ¾0, 16, 32, 128, 256
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Result
golay elements returns H MSG TRUE if all parameters are correct. Otherwise, an exception is raised.
Parallelization Information
golay elements is reentrant and processed without parallelization.
HALCON 6.0

408 CHAPTER 7. MORPHOLOGY
hit or miss
Possible Successor Functions
Alternatives
gen region points, gen struct elements, gen region polygon filled
See Also
dilation golay, erosion golay, opening golay, closing golay, hit or miss golay,
thickening golay
Bibliography
J. Serra: ”‘Image Analysis and Mathematical Morphology”’. Volume I. Academic Press, 1982
Module
Morphology
hit or miss ( Hobject Region, Hobject StructElement1,
Hobject StructElement2, Hobject *RegionHitMiss, long Row, long Column )
Hit-or-miss operation for regions.
hit or miss performs the hit-or-miss-transformation. First, an erosion with the structuring element
StructElement1 is done on the input region Region. Then an erosion with the structuring element
StructElement2 is performed on the complement of the input region. The intersection of the two resulting
regions is the result RegionHitMiss of hit or miss.
The hit-or-miss-transformation selects precisely the points for which the conditions given by the structuring elements
StructElement1 and StructElement2 are fulfilled. StructElement1 determines the condition
for the foreground pixels, while StructElement2 determines the condition for the background pixels. In order
to obtain sensible results, StructElement1 and StructElement2 must fit like key and lock. In any case,
StructElement1 and StructElement2 must be disjunct. Row and Column determine the reference point
of the structuring elements.
Structuring elements (StructElement1, StructElement2) can be generated by calling operators like
gen struct elements, gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement1 (input object) ..................................................region Hobject
Erosion mask for the input regions.
º StructElement2 (input object) ..................................................region Hobject
Erosion mask for the complements of the input regions.
º RegionHitMiss (output object) ..........................................region(-array) Hobject *
Result of the hit-or-miss operation.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 16
Value Suggestions : Row ¾0, 16, 32, 128, 256
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 16
Value Suggestions : Column ¾0, 16, 32, 128, 256
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region, ½ the area of the structuring element 1, and ¾ theareaofthestructuring
element 2. Then the runtime complexity for one object is:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 409
Ô Ô
Ç ¡ ½·Ô
¾
Result
hit or miss returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
hit or miss is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
golay elements, gen struct elements, threshold, regiongrowing, connection, union1,
watersheds, class ndim norm
Possible Successor Functions
difference, reduce domain, select shape, area center, connection
Alternatives
hit or miss golay, hit or miss seq, erosion2, dilation2
See Also
thinning, thickening, gen region points, gen region polygon filled
Morphology
Module
hit or miss golay ( Hobject Region, Hobject *RegionHitMiss,
const char *GolayElement, long Rotation )
Hit-or-miss operation for regions using the Golay alphabet.
hit or miss golay performs the hit-or-miss-transformation for the input regions Region (using structuring
elements from the Golay alphabet). First, an erosion with the foreground of the structuring element
GolayElement is done on the input region Region. Then an erosion with the background of the structuring
element GolayElement is performed on the complement of the input region. The intersection of the two
resulting regions is the result RegionHitMiss of hit or miss golay. The following structuring elements
are available:
’l’, ’m’, ’d’, ’c’, ’e’,’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used. The hit-or-misstransformation
selects precisely the points for which the conditions given by the selected Golay element are fulfilled.
Attention
Not all values of Rotation are valid for any Golay element.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionHitMiss (output object) ..........................................region(-array) Hobject *
Result of the hit-or-miss operation.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
HALCON 6.0

410 CHAPTER 7. MORPHOLOGY
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô µ
Result
hit or miss golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
hit or miss golay is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
hit or miss seq, hit or miss
Alternatives
See Also
erosion golay, dilation golay, opening golay, closing golay, thinning golay,
thickening golay, golay elements
Morphology
Module
hit or miss seq ( Hobject Region, Hobject *RegionHitMiss,
const char *GolayElement )
Hit-or-miss operation for regions using the Golay alphabet (sequential).
hit or miss golay performs the hit-or-miss-transformation for the input regions Region using all rotations
of a structuring element from the Golay alphabet. The result of the operator is the union of all intermediate results
of the respective rotations. The following structuring elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The Golay elements, together with all possible rotations, are described with the operator golay elements.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionHitMiss (output object) ..........................................region(-array) Hobject *
Result of the hit-or-miss operation.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
Complexity
Let be the area of an input region, and Ê be the number of rotations. Then the runtime complexity for one region
is:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 411
Ç´Ê ¡ ¡ Ô µ
Result
hit or miss seq returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
hit or miss seq is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
hit or miss golay, hit or miss
thinning seq, thickening seq
Morphology
Alternatives
See Also
Module
minkowski add1 ( Hobject Region, Hobject StructElement,
Hobject *RegionMinkAdd, long Iterations )
Perform a Minkowski addition on a region.
minkowski add1 dilates the input regions with a structuring element. By applying minkowski add1 to a
region, its boundary gets smoothed. In the process, the area of the region is enlarged. Furthermore, disconnected
regions may be merged. Such regions, however, remain logically distinct region. The Minkowski addition is a
set-theoretic region operation. It is based on translations and union operations.
Let Å (StructElement) andÊ (Region) be two regions, where Å is the structuring element and Ê is the
region to be processed. Furthermore, let Ñ be a point in Å. Then the displacement vector Ú Ñ ´Ü ݵ is
defined as the difference of the center of gravity of Å and the vector Ñ. LetØ ÚѴʵ denote the translation of a
region Ê by a vector Ú. Then
ÑÒÓÛ× ½´Ê ŵ
ѾÅ
Ø ÚÑ ´Êµ
For each point Ñ in Å a translation of the region Ê is performed. The union of all these translations is the
Minkowski addition of Ê with Å. minkowski add1 is similar to the operator dilation1, the difference
is that in dilation1 the structuring element is mirrored at the origin. The position of StructElement is
meaningless, since the displacement vectors are determined with respect to the center of gravity of Å.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò. From the above definition it follows that an
empty region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Attention
A Minkowski addition always results in enlarged regions. Closely spaced regions which may touch or overlap as
HALCON 6.0

412 CHAPTER 7. MORPHOLOGY
a result of the dilation are still treated as two separate regions. If the desired behavior is to merge them into one
region, the operator union1 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionMinkAdd (output object) ..........................................region(-array) Hobject *
Dilated regions.
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
minkowski add1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
minkowski add1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
minkowski add2, dilation1
transpose region, minkowski sub1
Morphology
Alternatives
See Also
Module
minkowski add2 ( Hobject Region, Hobject StructElement,
Hobject *RegionMinkAdd, long Row, long Column, long Iterations )
Dilate a region (using a reference point).
minkowski add2 computes the Minkowski addition of the input regions with a structuring element
(StructElement) having the reference point (Row,Column). minkowski add2 has a similar effect as
minkowski add1, the difference is that the reference point of the structuring element can be chosen arbitrarily.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 413
An empty region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Attention
A Minkowski addition always results in enlarged regions. Closely spaced regions which may touch or overlap as
a result of the dilation are still treated as two separate regions. If the desired behavior is to merge them into one
region, the operator union1 has to be called first.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be dilated.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionMinkAdd (output object) ..........................................region(-array) Hobject *
Dilated regions.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Typical Range of Values : 1 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Typical Range of Values : 1 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
minkowski add2 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
minkowski add2 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
HALCON 6.0

414 CHAPTER 7. MORPHOLOGY
minkowski add1, dilation1
transpose region
Morphology
Alternatives
See Also
Module
minkowski sub1 ( Hobject Region, Hobject StructElement,
Hobject *RegionMinkSub, long Iterations )
Erode a region.
minkowski sub1 computes the Minkowski subtraction of the input regions with a structuring element. By
applying minkowski sub1 to a region, its boundary gets smoothed. In the process, the area of the region is
reduced. Furthermore, connected regions may be split. Such regions, however, remain logically one region. The
Minkowski subtraction is a set-theoretic region operation. It uses the intersection operation.
Let Å (StructElement) andÊ (Region) be two regions, where Å is the structuring element and Ê is the
region to be processed. Furthermore, let Ñ be a point in Å. Then the displacement vector Ú Ñ ´Ü ݵ is
defined as the difference of the center of gravity of Å and the vector Ñ. LetØ ÚѴʵ denote the translation of a
region Ê by a vector Ú. Then
ÑÒÓÛ× ×Ù½´Ê ŵ
ѾÅ
Ø ÚÑ ´Êµ
For each point Ñ in Å a translation of the region Ê is performed. The intersection of all these translations is the
Minkowski subtraction of Ê with Å. minkowski sub1 is similar to the operator erosion1, the difference
is that in erosion1 the structuring element is mirrored at the origin. The position of StructElement is
meaningless, since the displacement vectors are determined with respect to the center of gravity of Å.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò. From the above definition it follows that the
maximum region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionMinkSub (output object) ..........................................region(-array) Hobject *
Eroded regions.
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
minkowski sub1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 415
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
minkowski sub1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
minkowski sub2, erosion1
transpose region
Morphology
Alternatives
See Also
Module
minkowski sub2 ( Hobject Region, Hobject StructElement,
Hobject *RegionMinkSub, long Row, long Column, long Iterations )
Erode a region (using a reference point).
minkowski sub2 computes the Minkowski subtraction of the input regions with a structuring element
(StructElement) having the reference point (Row,Column). minkowski sub2 has a similar effect as
minkowski sub1, the difference is that the reference point of the structuring element can be chosen arbitrarily.
The parameter Iterations determines the number of iterations which are to be performed with the structuring
element. The result of iteration Ò ½ is used as input for iteration Ò.
A maximum region is generated in case of an empty structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be eroded.
º StructElement (input object) ...................................................region Hobject
Structuring element.
º RegionMinkSub (output object) ..........................................region(-array) Hobject *
Eroded regions.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 0
Value Suggestions : Row ¾0, 10, 16, 32, 64, 100, 128
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 0
Value Suggestions : Column ¾0, 10, 16, 32, 64, 100, 128
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON 6.0

416 CHAPTER 7. MORPHOLOGY
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡ ÁØÖØÓÒ×µ
Result
minkowski sub2 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
minkowski sub2 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm, gen circle, gen ellipse,
gen rectangle1, gen rectangle2, draw region, gen region points,
gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
minkowski sub1, erosion1, erosion2, erosion golay, erosion seq
See Also
gen circle, gen rectangle2, gen region polygon
Morphology
Module
morph hat ( Hobject Region, Hobject StructElement,
Hobject *RegionTopHat )
Compute the union of bottom hat and top hat.
morph hat computes the union of the regions that are removed by an opening operation with the regions that
areaddedbyaclosing operation. Hence this is the union of the results of top hat and bottom hat. The
position of StructElement does not influence the result.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
The individual regions are processed separately.
Attention
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement (input object) ...................................................region Hobject
Structuring element (position-invariant).
º RegionTopHat (output object) ...........................................region(-array) Hobject *
Union of top hat and bottom hat.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 417
Example
my_morph_hat(Hobject *In, Hobject StructElement, Hobject *Out)
{
Hobject top, bottom;
top_hat(In,StructElement,&top);
bottom_hat(In,StructElement,&bottom);
union2(top,bottom,Out);
clear_obj(top); clear_obj(bottom);
}
Result
morph hat returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
morph hat is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
top hat, bottom hat, union2
opening, closing
Morphology
Alternatives
See Also
Module
morph skeleton ( Hobject Region, Hobject *RegionSkeleton )
Compute the morphological skeleton of a region.
morph skeleton computes the skeleton of the input regions (Region) using morphological transformations.
The computation yields a disconnected skeleton (gaps in the diagonals) having a width of one or two pixels. The
calculation uses the Golay element ’h’, i.e., an 8-neighborhood. This is equivalent to the maximum-norm.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionSkeleton (output object) ........................................region(-array) Hobject *
Resulting morphological skeleton.
Result
morph skeleton returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
HALCON 6.0

418 CHAPTER 7. MORPHOLOGY
Otherwise, an exception is raised.
Parallelization Information
morph skeleton is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
skeleton, reduce domain, select shape, area center, connection
skeleton, thinning
thinning seq, morph skiz
Morphology
Alternatives
See Also
Module
morph skiz ( Hobject Region, Hobject *RegionSkiz, long Iterations1,
long Iterations2 )
Thinning of a region.
morph skiz first performs a sequential thinning (thinning seq) of the input region with the element ’l’ of
the Golay alphabet. The number of iterations is determined by the parameter Iterations1. Then a sequential
thinning of the resulting region with the element ’e’ of the Golay alphabet is carried out. The number of iterations
for this step is determined by the parameter Iterations2. The skiz operation serves to compute a kind of
skeleton of the input regions, and to prune the branches of the resulting skeleton. If the skiz operation is applied to
the complement of the region, the region and the resulting skeleton are separated.
If very large values or ’maximal’ are passed for Iterations1 or Iterations2, the processing stops if no
more changes occur.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be thinned.
º RegionSkiz (output object) ..............................................region(-array) Hobject *
Result of the skiz operator.
º Iterations1 (input control) ...........................................integer long / const char *
Number of iterations for the sequential thinning with the element ’l’ of the Golay alphabet.
Default Value : 100
Value Suggestions : Iterations1 ¾’maximal’, 0, 1, 2, 3, 5, 7, 10, 15, 20, 30, 40, 50, 70, 100, 150, 200,
300, 400
Typical Range of Values : 0 Iterations1 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Iterations2 (input control) ...........................................integer long / const char *
Number of iterations for the sequential thinning with the element ’e’ of the Golay alphabet.
Default Value : 1
Value Suggestions : Iterations2 ¾’maximal’, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 0 Iterations2 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of the input region. Then the runtime complexity for one region is
Ç´´ÁØÖØÓÒ×½ · ÁØÖØÓÒ×¾µ ¡ ¿ ¡ Ô µ
Result
morph skiz returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 419
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
morph skiz is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
pruning, reduce domain, select shape, area center, connection, background seg,
complement
Alternatives
skeleton, thinning seq, morph skeleton, interjacent
thinning, hit or miss seq, difference
Morphology
See Also
Module
opening ( Hobject Region, Hobject StructElement,
Hobject *RegionOpening )
Open a region.
An opening operation is defined as an erosion followed by a Minkowsi addition. By applying opening to a
region, larger structures remain mostly intact, while small structures like lines or points are eliminated. In contrast,
a closing operation results in small gaps being retained or filled up (see closing).
opening serves to eliminate small regions (smaller than StructElement) and to smooth the boundaries of a
region. The position of StructElement is meaningless, since an opening operation is invariant with respect to
the choice of the reference point.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be opened.
º StructElement (input object) ...................................................region Hobject
Structuring element (position-invariant).
º RegionOpening (output object) ..........................................region(-array) Hobject *
Opened regions.
Example
/* simulation of opening */
my_opening(Hobject In, Hobject StructElement, Hobject *Out)
{
Hobject H;
erosion1(In,StructElement,&H,1);
minkowski_add1(H,StructElement,Out,1);
clear_obj(H);
}
/* Large regions in an aerial picture (beech trees or meadows): */
read_image(&Image,"wald1");
threshold(Image,&Light,80.0,255.0);
gen_circle(&StructElement1,100.0,100.0,2.0);
HALCON 6.0

420 CHAPTER 7. MORPHOLOGY
gen_circle(&StructElement2,100.0,100.0,20.0);
/* close the small gap */
closing(Light,StructElement1,&H);
/* selecting the large regions */
opening(H,StructElement2,&Large);
/* Selecting of edges with certain orientation: */
read_image(&Image,"fabrik");
sobel_amp(Image,&Sobel,"sum_abs",3);
threshold(Sobel,Edges,30.0,255.0);
gen_rectangle2(&StructElement,100.0,100.0,3.07819,20.0,1.0);
opening(Edges,StructElement,&Direction);
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´¾ ¡ Ô ½ ¡ Ô ¾µ
Result
opening returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
opening is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
minkowski add1, erosion1, opening circle
See Also
gen circle, gen rectangle2, gen region polygon
Morphology
Module
opening circle ( Hobject Region, Hobject *RegionOpening, double Radius )
Open a region with a circular structuring element.
opening circle is defined as an erosion followed by a Minkowsi addition with a circular structuring element
(see example). opening serves to eliminate small regions (smaller than the circular structuring element) and to
smooth the boundaries of a region.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be opened.
º RegionOpening (output object) ..........................................region(-array) Hobject *
Opened regions.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 421
º Radius (input control) .........................................................real double / long
Radius of the circular structuring element.
Default Value : 3.5
Value Suggestions : Radius ¾1.5, 2.5, 3.5, 4.5, 5.5, 7.5, 9.5, 12.5, 15.5, 19.5, 25.5, 33.5, 45.5, 60.5,
110.5
Typical Range of Values : 0.5 Radius 511.5 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Example
/* simulation of opening_circle */
my_opening_circle(Hobject In, double Radius, Hobject *Out)
{
Hobject Circle, tmp;
gen_circle(&Circle,100.0,100.0,Radius);
erosion1(Region,Circle,&tmp,1);
minkowski_add1(tmp,Circle,&Out,1);
clear_obj(Circle); clear_obj(tmp);
}
/* Large regions in an aerial picture (beech trees or meadows): */
read_image(&Image,"wald1");
threshold(Image,&Light,80.0,255.0);
/* close the small gap */
closing_circle(Light,&H,2.5);
/* selecting the large regions */
opening_circle(H,&Large,20.5);
Complexity
Let ½ be the area of the input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô ½ ¡ ÊÙ×µ
Result
opening circle returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
opening circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
Alternatives
opening, dilation1, minkowski add1, gen circle
transpose region
Morphology
See Also
Module
HALCON 6.0

422 CHAPTER 7. MORPHOLOGY
opening golay ( Hobject Region, Hobject *RegionOpening,
const char *GolayElement, long Rotation )
Open a region with an element from the Golay alphabet.
opening golay is defined as a Minkowski subtraction followed by a Minkowski addition. First the Minkowski
subtraction of the input region (Region) with the structuring element from the Golay alphabet defined by
GolayElement and Rotation is computed. Then the Minkowski addition of the result and the structuring
element rotated by 180 Æ is performed.
The following structuring elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used, and whether the foreground
(even) or background version (odd) of the selected element should be used. The Golay elements, together
with all possible rotations, are described with the operator golay elements.
opening golay serves to eliminate regions smaller than the structuring element, and to smooth regions’ boundaries.
Attention
Not all values of Rotation are valid for any Golay element. For some of the values of Rotation, the resulting
regions are identical to the input regions.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be opened.
º RegionOpening (output object) ..........................................region(-array) Hobject *
Opened regions.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô µ
Result
opening golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
opening golay is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
opening seg, opening
Alternatives
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 423
See Also
erosion golay, dilation golay, closing golay, hit or miss golay, thinning golay,
thickening golay, golay elements
Morphology
Module
opening rectangle1 ( Hobject Region, Hobject *RegionOpening,
long Width, long Height )
Open a region with a rectangular structuring element.
opening rectangle1 performs an erosion rectangle1 followedbyadilation rectangle1 on
the input region Region. The size of the rectangular structuring element is determined by the parameters Width
and Height. As is the case for all opening variants, larger structures are preserved, while small regions like
lines or points are eliminated.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be opened.
º RegionOpening (output object) ..........................................region(-array) Hobject *
Opened regions.
º Width (input control) .......................................................extent.x long / double
Width of the structuring rectangle.
Default Value : 10
Value Suggestions : Width ¾1, 2, 3, 4, 5, 7, 9, 12, 15, 19, 25, 33, 45, 60, 110, 150, 200
Typical Range of Values : 1 Width 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Height (input control) .....................................................extent.y long / double
Height of the structuring rectangle.
Default Value : 10
Value Suggestions : Height ¾1, 2, 3, 4, 5, 7, 9, 12, 15, 19, 25, 33, 45, 60, 110, 150, 200
Typical Range of Values : 1 Height 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let ½ be the area of an input region and À be the height of the rectangle. Then the runtime complexity for one
region is:
Ç´¾ ¡ Ô ½ ¡ дÀµµ
Result
opening rectangle1 returns H MSG TRUE if all parameters are correct. The behavior in case of empty or
no input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
opening rectangle1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, watersheds, class ndim norm
Possible Successor Functions
reduce domain, select shape, area center, connection
HALCON 6.0

424 CHAPTER 7. MORPHOLOGY
Alternatives
opening, gen rectangle1, dilation rectangle1, erosion rectangle1
opening seg, opening golay
Morphology
See Also
Module
opening seg ( Hobject Region, Hobject StructElement,
Hobject *RegionOpening )
Separate overlapping regions.
The opening seg operation is defined as a sequence of the following operators: erosion1, connection
and dilation1 (see example). Only one iteration is done in erosion1 and dilation1.
opening seg serves to separate overlapping regions whose area of overlap is smaller than StructElement.
It should be noted that the resulting regions can overlap without actually merging (see expand region).
opening seg uses the center of gravity as the reference point of the structuring element.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be opened.
º StructElement (input object) ...................................................region Hobject
Structuring element (position-invariant).
º RegionOpening (output object) ...........................................region-array Hobject *
Opened regions.
Example
/* Simulation of opening_seg */
my_opening_seg(Hobject Region, Hobject StructElement, Hobject *Opening)
{
Hobject H1,H2;
erosion1(Region,StructElement,&H1,1);
connection(H1,&H2);
dilation1(H2,StructElement,Opening,1);
clear_obj(H1); clear_obj(H2);
}
/* separation of circular objects */
gen_random_regions(&Regions,"circle",8.5,10.5,0.0,0.0,0.0,0.0,400,512,512);
union1(Regions,&UnionReg);
gen_circle(&Mask,100,100,8.5);
opening_seg(UnionReg,Mask,&RegionsNew);
Complexity
Let ½ be the area of the input region, and ¾ be the area of the structuring element. Then the runtime complexity
for one region is:
Ç´Ô
½ ¡
Ô
¾ ¡
Õ Ô
½µ
Result
opening seg returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 425
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
opening seg is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
expand region, reduce domain, select shape, area center, connection
erosion1, connection, dilation1
Morphology
Alternatives
Module
pruning ( Hobject Region, Hobject *RegionPrune, long Length )
Prune the branches of a region.
pruning removes branches from a skeleton (Region) having a length less than Length. All other branches
are preserved.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionPrune (output object) ............................................region(-array) Hobject *
Result of the pruning operation.
º Length (input control) ...............................................................integer long
Length of the branches to be removed.
Default Value : 2
Value Suggestions : Length ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Length 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of the input region. Then the runtime complexity for one region is
Ç´ÄÒØ ¡ ¿ ¡ Ô µ
Result
pruning returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
pruning is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
morph skiz, skeleton, thinning seq
Possible Successor Functions
reduce domain, select shape, area center, connection
HALCON 6.0

426 CHAPTER 7. MORPHOLOGY
morph skeleton, junctions skeleton
Morphology
See Also
Module
thickening ( Hobject Region, Hobject StructElement1,
Hobject StructElement2, Hobject *RegionThick, long Row, long Column,
long Iterations )
Add the result of a hit-or-miss operation to a region.
thickening performs a thickening of the input regions using morphological operations. The operator first
applies a hit-or-miss-transformation to Region (cf. hit or miss), and then adds the detected points to the
input region. The parameter Iterations determines the number of iterations performed.
For the choice of the structuring elements StructElement1 and StructElement2,aswellasforRow and
Column, the same restrictions described under hit or miss apply.
The structuring elements (StructElement1 and StructElement2) can be generated by calling
golay elements, for example.
Attention
If the reference point is contained in StructElement1 the input region remains unchanged.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement1 (input object) ..................................................region Hobject
Structuring element for the foreground.
º StructElement2 (input object) ..................................................region Hobject
Structuring element for the background.
º RegionThick (output object) ............................................region(-array) Hobject *
Result of the thickening operator.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 16
Value Suggestions : Row ¾0, 2, 4, 8, 16, 32, 128
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 16
Value Suggestions : Column ¾0, 2, 4, 8, 16, 32, 128
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50, 70, 100, 200,
400
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region, ½ the area of the structuring element 1, and ¾ theareaofthestructuring
element 2. Then the runtime complexity for one object is:
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 427
Ç ÁØÖØÓÒ× ¡ Ô Ô
¡ ½·Ô
¾
Result
thickening returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thickening is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
golay elements, threshold, regiongrowing, connection, union1, watersheds,
class ndim norm, gen circle, gen ellipse, gen rectangle1, gen rectangle2,
draw region, gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
thickening golay, thickening seq
hit or miss
Morphology
Alternatives
See Also
Module
thickening golay ( Hobject Region, Hobject *RegionThick,
const char *GolayElement, long Rotation )
Add the result of a hit-or-miss operation to a region (using a Golay structuring element).
thickening golay performs a thickening of the input regions using morphological operations and structuring
elements from the Golay alphabet. The operator first applies a hit-or-miss-transformation to Region (cf.
hit or miss golay), and then adds the detected points to the input region. The following structuring elements
are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used. The Golay elements,
together with all possible rotations, are described with the operator golay elements.
Attention
Not all values of Rotation are valid for any Golay element.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionThick (output object) ............................................region(-array) Hobject *
Result of the thickening operator.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
HALCON 6.0

428 CHAPTER 7. MORPHOLOGY
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô µ
Result
thickening golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thickening golay is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
reduce domain, select shape, area center, connection
thickening, thickening seq
erosion golay, hit or miss golay
Morphology
Alternatives
See Also
Module
thickening seq ( Hobject Region, Hobject *RegionThick,
const char *GolayElement, long Iterations )
Add the result of a hit-or-miss operation to a region (sequential).
thickening seq calculates the sequential thickening of the input regions with a structuring element from the
Golay alphabet (GolayElement). To do so, thickening seq calls the operator thickening golay with
all possible rotations of the structuring element Iterations times. The following structuring elements are
available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The Golay elements, together with all possible rotations, are described with the operator golay elements. For
all elements of the Golay alphabet, except for ’c’, the foreground and background masks are exchanged in order to
have an effect for them on the outer boundary of the region. The element ’c’ can be used to generate the convex
hull of the input region if enough iterations are performed.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionThick (output object) ............................................region(-array) Hobject *
Result of the thickening operator.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50, 70, 100, 200
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 429
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ÁØÖØÓÒ× ¡ ¡ Ô µ
Result
thickening seq returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thickening seq is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
reduce domain, select shape, area center, connection
thickening golay, thickening
erosion golay, thinning seq
Morphology
Alternatives
See Also
Module
thinning ( Hobject Region, Hobject StructElement1,
Hobject StructElement2, Hobject *RegionThin, long Row, long Column,
long Iterations )
Remove the result of a hit-or-miss operation from a region.
thinning performs a thinning of the input regions using morphological operations. The operator first applies a
hit-or-miss-transformation to Region (cf. hit or miss), and then removes the detected points from the input
region. The parameter Iterations determines the number of iterations performed.
For the choice of the structuring elements StructElement1 and StructElement2,aswellasforRow and
Column, the same restrictions described under hit or miss apply.
Structuring elements (StructElement1, StructElement2) can be generated with operators
such as gen circle, gen rectangle1, gen rectangle2, gen ellipse, draw region,
gen region polygon, gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement1 (input object) ..................................................region Hobject
Structuring element for the foreground.
º StructElement2 (input object) ..................................................region Hobject
Structuring element for the background.
º RegionThin (output object) ..............................................region(-array) Hobject *
Result of the thinning operator.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 0
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON 6.0

430 CHAPTER 7. MORPHOLOGY
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 0
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Iterations (input control) .........................................................integer long
Number of iterations.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 20, 30, 40, 50
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region, ½ the area of the structuring element 1, and ¾ theareaofthestructuring
element 2. Then the runtime complexity for one object is:
Ç ÁØÖØÓÒ× ¡ Ô Ô
¡ ½·Ô
¾
Result
thinning returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thinning is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
thinning golay, thinning seq
hit or miss
Morphology
Alternatives
See Also
Module
thinning golay ( Hobject Region, Hobject *RegionThin,
const char *GolayElement, long Rotation )
Remove the result of a hit-or-miss operation from a region (using a Golay structuring element).
thinning golay performs a thinning of the input regions using morphological operations and structuring
elements from the Golay alphabet. The operator first applies a hit-or-miss-transformation to Region (cf.
hit or miss golay), and then removes the detected points from the input region. The following structuring
elements are available:
’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’.
The rotation number Rotation determines which rotation of the element should be used. The Golay elements,
together with all possible rotations, are described with the operator golay elements.
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 431
Attention
Not all values of Rotation are valid for any Golay element.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionThin (output object) ..............................................region(-array) Hobject *
Result of the thinning operator.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’h’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Rotation (input control) ............................................................integer long
Rotation of the Golay elementḊepending on the element, not all rotations are valid.
Default Value : 0
Value List : Rotation ¾0, 2, 4, 6, 8, 10, 12, 14, 1, 3, 5, 7, 9, 11, 13, 15
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ ¡ Ô µ
Result
thinning golay returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thinning golay is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
reduce domain, select shape, area center, connection
thinning seq, thinning
erosion golay, hit or miss golay
Morphology
Alternatives
See Also
Module
thinning seq ( Hobject Region, Hobject *RegionThin,
const char *GolayElement, long Iterations )
Remove the result of a hit-or-miss operation from a region (sequential).
thinning seq calculates the sequential thinning of the input regions with a structuring element from the Golay
alphabet (GolayElement). To do so, thinning seq calls the operator thinning golay with all possible
rotations of the structuring element Iterations times. If Iterations is chosen large enough, the operator
calculates the skeleton of a region if the structuring elements ’l’ or ’m’ are used. For the element ’c’ the background
and foreground are exchanged in order to have an effect on the interior boundary of a region. If a very large value
or ’maximal’ is passed for Iterations the iteration stops if no more changes occur. The following structuring
elements are available:
’l’ Skeleton, similar to skeleton. This structuring element is also used in morph skiz.
’m’ A skeleton with many “hairs” and multiple (parallel) branches.
HALCON 6.0

432 CHAPTER 7. MORPHOLOGY
’d’ A skeleton without multiple branches, but with many gaps, similar to morph skeleton.
’c’ Uniform erosion of the region.
’e’ One pixel wide lines are shortened. This structuring element is also used in morph skiz.
’i’ Isolated points are removed. (Only Iterations = 1 is useful.)
’f’ Y-junctions are eliminated. (Only Iterations = 1 is useful.)
’f2’ One pixel long branches and corners are removed. (Only Iterations = 1 is useful.)
’h’ A kind of inner boundary, which, however, is thicker than the result of boundary, is generated. (Only
Iterations = 1 is useful.)
’k’ Junction points are eliminated, but also new ones are generated.
The Golay elements, together with all possible rotations, are described with the operator golay elements.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º RegionThin (output object) ..............................................region(-array) Hobject *
Result of the thinning operator.
º GolayElement (input control) .................................................string const char *
Structuring element from the Golay alphabet.
Default Value : ’l’
Value List : GolayElement ¾’l’, ’m’, ’d’, ’c’, ’e’, ’i’, ’f’, ’f2’, ’h’, ’k’
º Iterations (input control) ............................................integer long / const char *
Number of iterationsḞor ’f’, ’f2’, ’h’ and ’i’ the only useful value is 1.
Default Value : 20
Value Suggestions : Iterations ¾’maximal’, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 30, 40, 50, 70, 100, 150,
200
Typical Range of Values : 1 Iterations (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of an input region. Then the runtime complexity for one region is:
Ç´ÁØÖØÓÒ× ¡ ¡ Ô µ
Result
thinning seq returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input
region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
thinning seq is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
pruning, reduce domain, select shape, area center, connection, complement
skeleton, morph skiz, expand region
Alternatives
See Also
hit or miss seq, erosion golay, difference, thinning golay, thinning, thickening seq
Morphology
Module
HALCON/C Reference Manual / 2000-11-15

7.2. REGION 433
top hat ( Hobject Region, Hobject StructElement, Hobject *RegionTopHat )
Compute the top hat of regions.
top hat computes the opening of Region with StructElement. The difference between the original
region and the result of the opening is called the top hat. In contrast to opening, which splits regions under
certain circumstances, top hat computes the regions removed by such a splitting.
The position of StructElement is meaningless, since an opening operation is invariant with respect to the
choice of the reference point.
Structuring elements (StructElement) can be generated with operators such as gen circle,
gen rectangle1, gen rectangle2, gen ellipse, draw region, gen region polygon,
gen region points,etc.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º StructElement (input object) ...................................................region Hobject
Structuring element (position independent).
º RegionTopHat (output object) ...........................................region(-array) Hobject *
Result of the top hat operator.
Result
top hat returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no input region
can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
top hat is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, union1, watersheds, class ndim norm,
gen circle, gen ellipse, gen rectangle1, gen rectangle2, draw region,
gen region points, gen struct elements, gen region polygon filled
Possible Successor Functions
reduce domain, select shape, area center, connection
opening, difference
Alternatives
See Also
bottom hat, morph hat, gray tophat, opening
Morphology
Module
HALCON 6.0

434 CHAPTER 7. MORPHOLOGY
HALCON/C Reference Manual / 2000-11-15

Chapter 8
Object
8.1 Information
count obj ( Hobject Objects, long *Number )
Number of objects in a tuple.
The operator count obj determines for the object parameter Objects the number of objects it contains. In
this connection it should be noted that object is not the same as connection component (see connection). For
example, the number of objects of a region not consisting of three connected parts is 1.
Attention
In Prolog and Lisp the length of the list is not necessarily identical with the number of objects. This is the case
when object keys are contained which were created in the compact mode (keys from compact and normal mode
can be used as a mixture). See in this connection set system(’compact object’,).
Parameter
º Objects (input object) ......................................................object-array Hobject
Objects to be examined.
º Number (output control) ............................................................integer long *
Number of objects in the tuple Objects.
Runtime complexity: Ç´ÇØ×µ.
Complexity
Result
If the surrogates are correct, i.e. all objects are present in the HALCON operator data base, the operator
count obj returns the value H MSG TRUE. The behavior in case of empty input (no input objects available) is
set via the operator set system(’no object result’,).
Parallelization Information
count obj is reentrant and processed without parallelization.
See Also
copy obj, T obj to integer, connection, set system
Basic operators
Module
get channel info ( Hobject Object, const char *Request, long Channel,
char *Information )
T get channel info ( Hobject Object, Htuple Request, Htuple Channel,
Htuple *Information )
Informations about the components of an image object.
435

436 CHAPTER 8. OBJECT
The operator (T )get channel info gives information about the components of an image object. The following
requests (Request) are currently possible:
’creator’ Output of the names of the procedures which initially created the image components (not the object).
’type’ Output of the type of image component (’byte’, ’int1’, ’int2’, ’int4’, ’real’, ’direction’, ’cyclic’, ’complex’,
’dvf’, ’lut’). The component 0 is of type ’region’ or ’xld’.
In the tuple Channel the numbers of the components about which information is required are stated. After carrying
out (T )get channel info, Information contains a tuple of strings (one string per entry in Channel)
with the required information.
Parameter
º Object (input object) .............................................................object Hobject
Image object to be examined.
º Request (input control) ..............................................string (Htuple .) const char *
Required information about object components.
Default Value : ’creator’
Value List : Request ¾’creator’, ’type’
º Channel (input control) ............................................channel(-array) (Htuple .) long
Components to be examined (0 for region/XLD).
Default Value : 0
Value Suggestions : Channel ¾0, 1, 2, 3, 4, 5, 6, 7, 8
º Information (output control) ......................................string(-array) (Htuple .) char *
Requested information.
Result
If the parameters are correct the operator (T )get channel info returns the value H MSG TRUE. Otherwise
an exception is raised.
Parallelization Information
(T )get channel info is reentrant and processed without parallelization.
read image
count relation
Basic operators
Possible Predecessor Functions
See Also
Module
get obj class ( Hobject Object, char *Class )
T get obj class ( Hobject Object, Htuple *Class )
Name of the class of an image object.
(T )get obj class returns the name of the corresponding class to each object. The following classes are
possible:
’image’ Object with region (definition domain) and at least one channel.
’region’ Object with a region without gray values.
’xld cont’ XLD object as contour
’xld poly’ XLD object as polygon
’xld parallel’ XLD object with parallel polygons
HALCON/C Reference Manual / 2000-11-15

8.1. INFORMATION 437
Parameter
º Object (input object) ......................................................object(-array) Hobject
Image objects to be examined.
º Class (output control) ..............................................string(-array) (Htuple .) char *
Name of class.
Result
If the parameter values are correct the operator (T )get obj class returns the value H MSG TRUE. Otherwise
an exception is raised.
Parallelization Information
(T )get obj class is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
disp image, disp region, disp xld
(T )get channel info, count relation
Basic operators
See Also
Module
test equal obj ( Hobject Objects1, Hobject Objects2 )
Compare image objects regarding equality.
The operator test equal obj compares the regions and gray value components of all objects of the two input
parameters. The n-th object in Objects1 is compared to the n-th object in Objects2 (for all n). If all corresponding
regions are equal and the number of regions is also identical the operator test equal obj returns the
value TRUE, otherwise FALSE.
Attention
Image matrices are not compared regarding their contents. Thus, two images are “equal” if they are at the same
place in the store. If the input parameters are empty and the behavior was set via the operator set system
(’no object result’,’true’), the operator test equal obj returns TRUE, since all input (= empty
set) is equal.
Parameter
º Objects1 (input object) .....................................................object-array Hobject
Test objects.
º Objects2 (input object) .....................................................object-array Hobject
Comparative objects.
Complexity
If is the area of a region the runtime complexity is Ç´½µ or Ç´Ô
µ if the result is TRUE and Ç´Ô
µ if the
result is FALSE.
Result
The operator test equal obj returns the value H MSG TRUE if both object tuples are identical. If the tuples
differ in at least one place test equal obj returns H MSG FALSE. The behavior in case of empty input
(no input objects available) is set via the operator set system(’no object result’,). Ifthe
number of objects differs an exception is raised.
Parallelization Information
test equal obj is reentrant and processed without parallelization.
test equal region
bool
Basic operators
See Also
Return Value
Module
HALCON 6.0

438 CHAPTER 8. OBJECT
test equal region ( Hobject Regions1, Hobject Regions2 )
Test whether the regions of two objects are identical.
The operator test equal region compares the regions of the two input parameters. The n-th element in
Regions1 is compared to the n-th object in Regions2 (for all n). If all regions are equal and the number of
regions is identical the operator test equal region returns the value TRUE, otherwise FALSE.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Test regions.
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions.
Parameter Number : Regions1 Regions2
Complexity
If is the area of a region the runtime complexity is Ç´½µ or Ç´Ô
µ if the result is TRUE, Ç´Ô
µ if the result is
FALSE.
Result
The operator test equal region returns the value H MSG TRUE if both object tuples are identical. If the
tuples differ in at least one place test equal region returns H MSG FALSE. The behavior in case of empty
input (no input objects available) is set via the operator set system(’no object result’,).
If the number of objects differs an exception is raised.
Parallelization Information
test equal region is reentrant and processed without parallelization.
Alternatives
intersection, complement, area center
test equal obj
bool
Basic operators
See Also
Return Value
Module
test obj def ( Hobject Object )
Test whether an object is already deleted.
The operator test obj def checks whether the object still exists in the HALCON operator data base (i.e.
whether the surrogate is still valid). This check especially makes sense before deleting an object if it is not sure
that the object has already been deleted by a prior deleting operator (clear obj).
Attention
The operator test obj def can return TRUE even if the object was already deleted because the surrogates of
deleted objects are re-used for new objects. In this context see the example.
Parameter
º Object (input object) .............................................................object Hobject
Object to be checked.
Example
Herror err;
circle(&Circle,100.0,100.0,100.0);
err = test_obj_def(Circle);
printf("Result for test_obj_def (H_MSG_TRUE): %d\n",err);
clear_obj(Circle);
HALCON/C Reference Manual / 2000-11-15

8.2. MANIPULATION 439
err = test_obj_def(Circle);
printf("Result for test_obj_def (H_MSG_FALSE): %d\n",err);
gen_rectangle1(&Rectangle,200.0,200.0,300.0,300.0);
err = test_obj_def(Circle);
printf("Result for test_obj_def (H_MSG_TRUE!!!): %d\n",err);
The runtime complexity is Ç´½µ.
Complexity
Result
The operator test obj def returns the value H MSG TRUE if an object with this surrogate is present in the
HALCON operator data base, otherwise the value H MSG FALSE is returned. The behavior in case of empty
input (no input objects available) is set via the operator set system(’no object result’,).
Parallelization Information
test obj def is reentrant and processed without parallelization.
Possible Predecessor Functions
clear obj, gen circle, gen rectangle1
set check, clear obj, reset obj db
bool
Basic operators
See Also
Return Value
Module
8.2 Manipulation
clear obj ( Hobject Objects )
Delete an iconic object from the HALCON database.
clear obj deletes iconic objects, which are no longer needed, from the HALCON database. It should be noted
that clear obj is the only way to delete objects from the database, and hence to reclaim their memory, in all
host languages except Smalltalk and C++.
Images and regions are normally used by several iconic objects at the same time (uses less memory!). This has the
consequence that a region or an image is only deleted if all objects using it have been deleted.
The operator reset obj db can be used to reset the system and clear all remaining iconic objects.
Attention
Regarding the use of local variables: Because only local variables are deleted on exit of a subroutine (or a rule
in Prolog), while the HALCON database is not updated, it is necessary to clear local objects before exiting the
subroutine. Special care has to be taken if backtracking is possible in Prolog (before reaching the clear obj
statements).
Parameter
º Objects (input object) .....................................................object(-array) Hobject
Objects to be deleted.
Result
clear obj returns H MSG TRUE if all objects are contained in the HALCON database. If not all objects are
valid (e.g., already cleared), an exception is raised, which also clears all valid objects. The operator set check
(’˜clear’:) can be used to suppress the raising of this exception. If the input is empty the behavior can be set
via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
clear obj is reentrant and processed without parallelization.
test obj def
Possible Predecessor Functions
HALCON 6.0

440 CHAPTER 8. OBJECT
reset obj db
test obj def, set check
Basic operators
Alternatives
See Also
Module
concat obj ( Hobject Objects1, Hobject Objects2,
Hobject *ObjectsConcat )
Concatenate two iconic object tuples.
concat obj concatenates the two tuples of iconic objects Objects1 and Objects2 into a new object tuple
ObjectsConcat. Hence, this tuple contains all the objects of the two input tuples:
ObjectsConcat =[Objects1,Objects2]
In ObjectsConcat the objects of Objects1 are stored first, followed by the objects of Objects2. The
order of the objects is preserved. As usual, only the objects are copied, and not the corresponding images and
regions, i.e., no new memory is allocated. concat obj is designed especially for HALCON/C. In languages like
Smalltalk, Prolog, and C++ it is not needed.
concat obj should not be confused with union1 or union2, in which regions are merged, i.e., in which the
number of objects is modified.
concat obj can be used to concatenate objects of different image object types (e.g., images and XLD contours)
into a single object. This is only recommended if it is necessary to accumulate in a single object variable, for
example, the results of an image processing sequence. It should be noted that the only operators that can handle
such object tuples of mixed type are concat obj, copy obj, select obj, anddisp obj. For technical
reasons, object tuples of mixed type must not be created in HDevelop.
Parameter
º Objects1 (input object) ...................................................object(-array) Hobject
Object tuple 1.
º Objects2 (input object) ...................................................object(-array) Hobject
Object tuple 2.
º ObjectsConcat (output object) ...........................................object-array Hobject *
Concatenated objects.
Example
/* generate a tuple of a circle and a rectangle */
gen_circle(&Circle,200.0,400.0,23.0);
gen_rectangle1(&Rectangle,23.0,44.0,203.0,201.0);
concat_obj(Circle,Rectangle,&CirclAndRectangle);
clear_obj(Circle); clear_obj(Rectangle);
disp_region(CircleAndRectangle,WindowHandle);
Complexity
Runtime complexity: Ç´ÇØ×½ · ÇØ×¾µ;
Memory complexity of the result objects: Ç´ÇØ×½ · ÇØ×¾µ
Result
concat obj returns H MSG TRUE if all objects are contained in the HALCON database. If the input is empty
the behavior can be set via set system(’no object result’,). If necessary, an exception is
raised.
Parallelization Information
concat obj is reentrant and processed without parallelization.
See Also
count obj, copy obj, select obj, disp obj
HALCON/C Reference Manual / 2000-11-15

8.2. MANIPULATION 441
Basic operators
Module
copy obj ( Hobject Objects, Hobject *ObjectsSelected, long Index,
long NumObj )
Copy an iconic object in the HALCON database.
copy obj copies NumObj iconic objects beginning with index Index (starting with 1) from the iconic input
object tuple Objects to the output object ObjectsSelected.If-1ispassedforNumObj all objects beginning
with Index are copied. No new storage is allocated for the regions and images. Instead, new objects containing
references to the existing objects are created. The number of objects in an object tuple can be queried with the
operator count obj.
Parameter
º Objects (input object) .....................................................object(-array) Hobject
Objects to be copied.
º ObjectsSelected (output object) .......................................object(-array) Hobject *
Copied objects.
º Index (input control) ................................................................integer long
Starting index of the objects to be copied.
Default Value : 1
Value Suggestions : Index ¾1, 2, 3, 4, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000
Typical Range of Values : 1 Index
Restriction : Index number´Objectsµ
º NumObj (input control) ...............................................................integer long
Number of objects to be copied or -1.
Default Value : 1
Value Suggestions : NumObj ¾-1, 1, 2, 3, 4, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000
Typical Range of Values : -1 NumObj
Restriction : ´´NumObj · Indexµ number´Objectsµµ ´NumObj 0µ
Example
/* Access all regions */
count_obj(Regions,&Num);
for (i=1; i

442 CHAPTER 8. OBJECT
select obj
Alternatives
See Also
count obj, concat obj, T obj to integer, copy image
Basic operators
Module
gen empty obj ( Hobject *EmptyObject )
Create an empty object tuple.
The operator gen empty obj creates an empty tuple. This means that the output parameter does not contain any
objects. Thus, the operator count obj returns 0. However, clear obj can be called for the output. It should
be noted that no objects must not be confused with an empty region. In case of an empty region, i.e. a region with
0pixelscount obj returns the value 1.
Parameter
º EmptyObject (output object) ...................................................object Hobject *
No objects.
Parallelization Information
gen empty obj is reentrant and processed without parallelization.
Image / region / XLD management
Module
T integer to obj ( Hobject *Objects, Htuple SurrogateTuple )
Convert an “integer number” into an iconic object.
T integer to obj is the inverse operator to T obj to integer. All surrogates of objects passed in
SurrogateTuple are stored as objects. In contrast to T obj to integer, the objects are duplicated.
T integer to obj is intended especially for use in HALCON/C, because iconic objects and control parameters
are treated differently in C.
Attention
The objects are duplicated in the database.
Parameter
º Objects (output object) ...................................................object-array Hobject *
Created objects.
º SurrogateTuple (input control) ......................................integer-array Htuple . long
Tuple of object surrogates.
Default Value : 1
Result
T integer to obj returns H MSG TRUE if all parameters are correct, i.e., if they are valid object keys. If the
input is empty the behavior can be set via set system(’no object result’,). If necessary,
an exception is raised.
Parallelization Information
T integer to obj is reentrant and processed without parallelization.
T obj to integer
Basic operators
See Also
Module
HALCON/C Reference Manual / 2000-11-15

8.2. MANIPULATION 443
T obj to integer ( Hobject Objects, Htuple Index, Htuple Number,
Htuple *SurrogateTuple )
Convert an iconic object into an “integer number.”
T obj to integer stores Number, starting at index Index, of the database keys of the input object Objects
as integer numbers in the output parameter SurrogateTuple. This facilitates a direct access to an arbitrary
element of Objects. In conjunction with count obj (returns the number of objects in Objects) the elements
of Objects can be processed successively. The objects are not duplicated by T obj to integer and thus
must not be cleared by clear obj.
The objects’ data is not duplicated.
Attention
Parameter
º Objects (input object) ......................................................object-array Hobject
Objects for which the surrogates are to be returned.
º Index (input control) ........................................................integer Htuple . long
Starting index of the surrogates to be returned.
Default Value : 1
Typical Range of Values : 1 Index
º Number (input control) .......................................................integer Htuple . long
Number of surrogates to be returned.
Default Value : 1
Restriction : ´Number · Indexµ number´Objectsµ
º SurrogateTuple (output control) ....................................integer-array Htuple . long *
Tuple containing the surrogates.
Example
/* Access the i-th element: */
long i,Surrogate;
obj_to_integer(Objects,i,1,&Surrogat);
Runtime complexity: Ç´ÇØ× · ÆÙÑÖµ
Complexity
Result
T obj to integer returns H MSG TRUE if all parameters are correct. If the input is empty the behavior can
be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
T obj to integer is reentrant and processed without parallelization.
test obj def
Possible Predecessor Functions
Alternatives
copy obj, select obj, copy image, gen image proto
T integer to obj, count obj
Basic operators
See Also
Module
select obj ( Hobject Objects, Hobject *ObjectSelected, long Index )
Select an object from an object tuple.
select obj copies the iconic object with index Index (starting with 1) from the iconic input object tuple
Objects to the output object ObjectSelected. No new storage is allocated for the regions and images.
HALCON 6.0

444 CHAPTER 8. OBJECT
Instead, new objects containing references to the existing objects are created. The number of objects in an object
tuple can be queried with the operator count obj.
Parameter
º Objects (input object) .....................................................object(-array) Hobject
Objects, of which one is to be selected.
º ObjectSelected (output object) ...............................................object Hobject *
Selected object.
º Index (input control) ................................................................integer long
Index of the object to be selected.
Default Value : 1
Value Suggestions : Index ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 50, 100, 200, 500, 1000, 2000, 5000
Typical Range of Values : 1 Index
/* Access to all Regions */
Example
count_obj(Regions,&Num);
for (i=1; i

Chapter 9
Regions
9.1 Access
T get region chain ( Hobject Region, Htuple *Row, Htuple *Column,
Htuple *Chain )
Contour of an object as chain code.
The operator T get region chain returns the contour of a region. A contour is a series of pixels describing
the outline of the region. The contour “lies on” the region. It starts at the smallest line number; in that line at the
pixel with the largest column index. The rotation occurs clockwise. Holes of the region are ignored. The direction
code (chain code) is defined as follows:
¿ ¾ ½
£ ¼
The operator T get region chain returns the code in the form of a tuple. In case of an empty region the
parameters Row and Column are zero and Chain is the empty tuple.
Attention
Holes of the region are ignored. Only one region may be passed, and it must have exactly one connection component.
Parameter
º Region (input object) .............................................................region Hobject
Region to be transformed.
º Row (output control) ..................................................chain.begin.y Htuple . long *
Line of starting point.
º Column (output control) ..............................................chain.begin.x Htuple . long *
Column of starting point.
º Chain (output control) ............................................chain.code-array Htuple . long *
Direction code of the contour (from starting point).
Typical Range of Values : 0 Chain 7
Result
The operator T get region chain normally returns the value H MSG TRUE. If more than one connection
component is passed an exception handling is caused. The behavior in case of empty input (no input
regions available) is set via the operator set system(’no object result’,). The
behavior in case of empty region (the region is the empty set) is set via the operator set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T get region chain is reentrant and processed without parallelization.
445

446 CHAPTER 9. REGIONS
Possible Predecessor Functions
sobel amp, threshold, skeleton, edges image, (T )gen rectangle1, (T )gen circle
Possible Successor Functions
approx chain, approx chain simple
See Also
copy obj, T get region contour, T get region polygon
Region processing
Module
T get region contour ( Hobject Region, Htuple *Rows, Htuple *Columns )
Access the contour of an object.
The operator T get region contour returns the contour of a region. A contour is a result of line (Rows)
and column coordinates (Columns), describing the boundary of the region. The contour lies on the region. It
starts at the smallest line numberİn that line at the pixel with the largest column index. The rotation direction is
clockwise. The first pixel of the contour is identical with the last. Holes of the region are ignored. The operator
T get region contour returns the coordinates in the form of tuples. An empty region is passed as empty
tuple.
Attention
Holes of the region are ignored. Only one region may be passed, and this region must have exactly one connection
component.
Parameter
º Region (input object) .............................................................region Hobject
Output region.
º Rows (output control) ...............................................contour.y-array Htuple . long *
Line numbers of the contour pixels.
º Columns (output control) ...........................................contour.x-array Htuple . long *
Column numbers of the contour pixels.
Parameter Number : Columns Rows
Result
The operator T get region contour normally returns the value H MSG TRUE. If more than one connection
component is passed an exception handling is caused. The behavior in case of empty input (no input regions
available) is set via the operator set system(’no object result’,).
Parallelization Information
T get region contour is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, threshold, skeleton, edges image, (T )gen rectangle1, (T )gen circle
See Also
copy obj, T get region chain, T get region polygon
Region processing
Module
T get region convex ( Hobject Region, Htuple *Rows, Htuple *Columns )
Access convex hull as contour.
The operator T get region convex returns the convex hull of a region as polygon. The polygon is the minimum
result of line (Rows) and column coordinates (Columns) describing the hull of the region. The polygon
pixels lie on the region. The polygon starts at the smallest line number; in this line at the pixel with the largest
column index. The rotation direction is clockwise. The first pixel of the polygon is identical with the last. The
HALCON/C Reference Manual / 2000-11-15

9.1. ACCESS 447
operator T get region convex returns the coordinates in the form of tuples. An empty region is passed as
empty tuple.
Parameter
º Region (input object) .............................................................region Hobject
Output region.
º Rows (output control) ...............................................contour.y-array Htuple . long *
Line numbers of contour pixels.
º Columns (output control) ...........................................contour.x-array Htuple . long *
Column numbers of the contour pixels.
Parameter Number : Columns Rows
Result
The operator T get region convex returns the value H MSG TRUE.
Parallelization Information
T get region convex is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, skeleton, dyn threshold
disp polygon
shape trans
select obj, T get region contour
Region processing
Possible Successor Functions
Alternatives
See Also
Module
T get region points ( Hobject Region, Htuple *Rows, Htuple *Columns )
Access the pixels of a region.
The operator T get region points returns the region data in the form of coordinate lists. The coordinates
are sorted in the following order:
´Ö ½ ½ µ ´Ö ¾ ¾ µ´Ö ½ Ö ¾ µ ´Ö ½ Ö ¾ µ ´½ ¾µ
T get region points returns the coordinates in the form of tuples. An empty region is passed as empty tuple.
Only one region may be passed.
Attention
Parameter
º Region (input object) .............................................................region Hobject
This region is accessed.
º Rows (output control) ...........................................coordinates.y-array Htuple . long *
Line numbers of the pixels in the region
º Columns (output control) .......................................coordinates.x-array Htuple . long *
Column numbers of the pixels in the region.
Parameter Number : Columns Rows
Result
The operator T get region points normally returns the value H MSG TRUE. If more than one connection
component is passed an exception handling is caused. The behavior in case of empty input (no input regions
available) is set via the operator set system(’no object result’,).
Parallelization Information
T get region points is reentrant and processed without parallelization.
HALCON 6.0

448 CHAPTER 9. REGIONS
Possible Predecessor Functions
sobel amp, threshold, connection
T get region runs
copy obj, (T )gen region points
Region processing
Alternatives
See Also
Module
T get region polygon ( Hobject Region, Htuple Tolerance, Htuple *Rows,
Htuple *Columns )
Polygon approximation of a region.
The operator T get region polygon calculates a polygon to approximate the edge of a region. A polygon
is a sequence of line (Rows) and column coordinates (Columns). It describes the contour of the region. Only
the base points of the polygon are returned. The parameter Tolerance indicates how large the maximum distance
between the polygon and the edge of the region may be. Holes of the region are ignored. The operator
T get region polygon returns the coordinates in the form of tuples.
Attention
Holes of the region are ignored. Only one region may be passed, and this region must have exactly one connection
component.
Parameter
º Region (input object) .............................................................region Hobject
Region to be approximated.
º Tolerance (input control) .........................................number Htuple . double / long
Maximum distance between the polygon and the edge of the region.
Default Value : 5.0
Value Suggestions : Tolerance ¾0.0, 2.0, 5.0, 10.0
Typical Range of Values : 0.0 Tolerance (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
º Rows (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long *
Line numbers of the base points of the contour.
º Columns (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long *
Column numbers of the base points of the contour.
Parameter Number : Columns Rows
Result
The operator T get region polygon normally returns the value H MSG TRUE. If more than one connection
component is passed an exception handling is caused. The behavior in case of empty input (no input regions
available) is set via the operator set system(’no object result’,).
Parallelization Information
T get region polygon is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, threshold, skeleton, edges image
See Also
copy obj, T gen region polygon, disp polygon, T get region chain,
T get region contour, set line approx
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

9.2. AFFINE-TRANSFORMATIONS 449
T get region runs ( Hobject Region, Htuple *Row, Htuple *ColumnBegin,
Htuple *ColumnEnd )
Access the runlength coding of a region.
The operator T get region runs returns the region data in the form of chord tuples. The chord representation
is caused by examining a region line by line with ascending line number (= from “top” to “bottom”). Every line is
passed from left to right (ascending column number); storing all starting and ending points of region segments (=
chords). Thus a region can be described by a sequence of chords, a chord being defined by line number, starting
and ending points (column number). The operator T get region runs returns the three components of the
chords in the form of tuples. In case of an empty region three empty tuples are returned.
Attention
Only one region may be passed.
Parameter
º Region (input object) .............................................................region Hobject
Output region.
º Row (output control) ..................................................chord.y-array Htuple . long *
Line numbers of the chords.
º ColumnBegin (output control) ......................................chord.x1-array Htuple . long *
Column numbers of the starting points of the chords.
Parameter Number : ColumnBegin Row
º ColumnEnd (output control) .........................................chord.x2-array Htuple . long *
Column numbers of the ending points of the chords.
Parameter Number : ColumnEnd Row
Result
The operator T get region runs normally returns the value H MSG TRUE. If more than one region is passed
an exception handling is caused. The behavior in case of empty input (no input regions available) is set via the
operator set system(’no object result’,).
Parallelization Information
T get region runs is reentrant and processed without parallelization.
threshold, connection
T get region points
copy obj, (T )gen region runs
Region processing
Possible Predecessor Functions
Alternatives
See Also
Module
9.2 Affine-Transformations
T affine trans region ( Hobject Region, Hobject *RegionAffineTrans,
Htuple HomMat2D, Htuple Interpolate )
Transform a region using an affine transformation.
T affine trans region applies an arbitrary affine transformation, i.e., scaling, rotation, translation, and
skewing, to a region. The affine map is described by the transformation matrix given in HomMat2D
, which is built up by using hom mat2d identity, hom mat2d scale, hom mat2d rotate, and
hom mat2d translate. The components of the homogeneous transformation matrix are interpreted as follows:
the row coordinate of the image corresponds to the Ü coordinate of the matrix, while the column coordinate
of the image corresponds to the Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate
system, which is assumed for the homogeneous transformation matrices, also for the image. In particular, by doing
so roatations are performed in the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally
corresponds to the usual (row,column) order for coordinates in the image.
HALCON 6.0

450 CHAPTER 9. REGIONS
The parameter Interpolate determines whether the transformation is to be done by using interpolation internally.
This can lead to smoother region boundaries, especially if regions are enlarged. However, the runtime
increases drastically.
Attention
T affine trans region in general is not reversible (clipping and discretization during rotation and scaling).
The components of the homogeneous transformation matrix are interpreted as follows: the row coordinate of the
image corresponds to the Ü coordinate of the matrix, while the column coordinate of the image corresponds to the
Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate system, which is assumed for the
homogeneous transformation matrices, also for the image. In particular, by doing so roatations are performed in
the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally corresponds to the usual (row,column)
order for coordinates in the image.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region(s) to be rotated and scaled.
º RegionAffineTrans (output object) ....................................region(-array) Hobject *
Transformed output region(s).
Parameter Number : RegionAffineTrans Region
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Interpolate (input control) ..........................................string Htuple . const char *
Should the transformation be done using interpolation?
Default Value : ’false’
Value List : Interpolate ¾’true’, ’false’
Result
T affine trans region returns H MSG TRUE if all parameters are correct. The behavior in case of empty
input (no regions given) can be set via set system(’no object result’,), the behavior in
case of an empty input region via set system(’empty region result’,), and the behavior
in case of an empty result region via set system(’store empty region’,). If necessary,
an exception handling is raised.
Parallelization Information
T affine trans region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
hom mat2d identity, hom mat2d scale, hom mat2d translate, hom mat2d invert,
hom mat2d rotate
Possible Successor Functions
(T )select shape
Alternatives
move region, mirror region, zoom region
affine trans image
Region processing
See Also
Module
mirror region ( Hobject Region, Hobject *RegionMirror,
const char *RowColumn, long WidthHeight )
Reflect a region about the x- or y-axis.
mirror region reflects a region about the x- or y-axis (parameter RowColumn). The parameter
WidthHeight specifies the corresponding image width or height respectively, i.e., it is two times the coordinate
of the axis of symmetry.
HALCON/C Reference Manual / 2000-11-15

9.2. AFFINE-TRANSFORMATIONS 451
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region(s) to be reflected.
º RegionMirror (output object) ...........................................region(-array) Hobject *
Reflected region(s).
Parameter Number : RegionMirror Region
º RowColumn (input control) .....................................................string const char *
Coordinate of the axis of symmetry.
Default Value : ’row’
Value List : RowColumn ¾’column’, ’row’
º WidthHeight (input control) ........................................................integer long
Height or width of the corresponding image.
Default Value : 512
Value Suggestions : WidthHeight ¾128, 256, 512, 525, 768, 1024
Typical Range of Values : 1 WidthHeight 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : WidthHeight 0
read_image(&Image,"affe");
threshold(Image,&Seg,128.0,255.0);
mirror_region(Seg,&Mirror,"row",512);
disp_region(Mirror,WindowHandle);
Example
Parallelization Information
mirror region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
T affine trans region
zoom region
Region processing
Possible Successor Functions
Alternatives
See Also
Module
move region ( Hobject Region, Hobject *RegionMoved, long Row,
long Column )
Translate a region.
move region translates the input regions by the vector given by (Row, Column). If necessary, the resulting
regions are clipped with the current image format.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region(s) to be moved.
º RegionMoved (output object) ............................................region(-array) Hobject *
Translated region(s).
Parameter Number : RegionMoved Region
HALCON 6.0

452 CHAPTER 9. REGIONS
º Row (input control) ...................................................................point.y long
Row coordinate of the vector by which the region is to be moved.
Default Value : 30
Value Suggestions : Row ¾-128, -64, -32, -16, -10, -8, -4, -2, -1, 0, 1, 2, 4, 5, 8, 10, 16, 32, 64, 128
Typical Range of Values : -512 Row 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column (input control) ...............................................................point.x long
Row coordinate of the vector by which the region is to be moved.
Default Value : 30
Value Suggestions : Column ¾-128, -64, -32, -16, -10, -8, -4, -2, -1, 0, 1, 2, 4, 5, 8, 10, 16, 32, 64, 128
Typical Range of Values : -512 Column 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ µ.
Result
move region always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,), the behavior in case of an empty input region
via set system(’empty region result’,), and the behavior in case of an empty result
region via set system(’store empty region’,). If necessary, an exception handling
is raised.
Parallelization Information
move region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
Possible Successor Functions
See Also
affine trans image, mirror region, zoom region
Region processing
Module
transpose region ( Hobject Region, Hobject *Transposed, long Row,
long Column )
Reflect a region about a point.
transpose region reflects a region about a point. The fixed point is given by Column and Row. Theimage
È ¼ of a point È is determined by the following requirement:
If È Ë,thenÈ ¼ Ë, i.e., the point Ë is the fixed point of the mapping. If È Ë, Ë is the center point of a line
segment connecting È and È ¼ . Therefore, the following equations result:
ÓÐÙÑÒ Ü · ܼ
¾
ÊÓÛ Ý · ݼ
¾
If Row and Column are set to the origin, the in morphology often used transposition results.
transpose region is often used to reflect (transpose) a structuring element.
Hence
HALCON/C Reference Manual / 2000-11-15

9.2. AFFINE-TRANSFORMATIONS 453
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be reflected.
º Transposed (output object) ..............................................region(-array) Hobject *
Transposed region.
º Row (input control) ...................................................................point.y long
Row coordinate of the reference point.
Default Value : 0
Value Suggestions : Row ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Row 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column coordinate of the reference point.
Default Value : 0
Value Suggestions : Column ¾0, 64, 128, 256, 512
Typical Range of Values : 0 Column 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the area of the input region. Then the runtime complexity for one region is
Ç´Ô
µ
Result
transpose region returns H MSG TRUE if all parameters are correct. The behavior in case of empty or no
input region can be set via:
¯ no region: set system(’no object result’,)
¯ empty region: set system(’empty region result’,)
Otherwise, an exception is raised.
Parallelization Information
transpose region is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
reduce domain, (T )select shape, (T )area center, connection
dilation1, opening, closing
Morphology
See Also
Module
zoom region ( Hobject Region, Hobject *RegionZoom, double ScaleWidth,
double ScaleHeight )
Zoom a region.
zoom region enlarges or reduces the regions given in Region in the x- and y-direction by the given scale
factors ScaleWidth and ScaleHeight.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region(s) to be zoomed.
º RegionZoom (output object) ..............................................region(-array) Hobject *
Zoomed region(s).
Parameter Number : RegionZoom Region
HALCON 6.0

454 CHAPTER 9. REGIONS
º ScaleWidth (input control) ......................................................extent.x double
Scale factor in x-direction.
Default Value : 2.0
Value Suggestions : ScaleWidth ¾0.25, 0.5, 1.0, 2.0, 3.0
Typical Range of Values : 0.0 ScaleWidth 100.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.5
º ScaleHeight (input control) .....................................................extent.y double
Scale factor in y-direction.
Default Value : 2.0
Value Suggestions : ScaleHeight ¾0.25, 0.5, 1.0, 2.0, 3.0
Typical Range of Values : 0.0 ScaleHeight 100.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.5
Parallelization Information
zoom region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
zoom image size, zoom image factor
Region processing
Possible Successor Functions
See Also
Module
9.3 Creation
gen checker region ( Hobject *RegionChecker, long WidthRegion,
long HeightRegion, long WidthPattern, long HeightPattern )
Create a checkered region.
The operator gen checker region returns a checkered region. Every black field of the checkerboard belongs
to the region. The horizontal and vertical expansion of the region is limited by WidthRegion, HeightRegion
respectively, the size of the fields of the checkerboard by WidthPattern ¢ HeightPattern.
Attention
If a very small pattern is chosen (WidthPattern 4) the created region requires much storage.
Parameter
º RegionChecker (output object) .................................................region Hobject *
Created checkerboard region.
º WidthRegion (input control) .......................................................extent.x long
Largest occurring Ü value of the region.
Default Value : 511
Value Suggestions : WidthRegion ¾10, 20, 31, 63, 127, 255, 300, 400, 511
Typical Range of Values : 1 WidthRegion 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : WidthRegion 1
º HeightRegion (input control) ......................................................extent.y long
Largest occurring Ý value of the region.
Default Value : 511
Value Suggestions : HeightRegion ¾10, 20, 31, 63, 127, 255, 300, 400, 511
Typical Range of Values : 1 HeightRegion 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : HeightRegion 1
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 455
º WidthPattern (input control) ......................................................extent.y long
Width of a field of the checkerboard.
Default Value : 64
Value Suggestions : WidthPattern ¾1, 2, 4, 8, 16, 20, 32, 64, 100, 128, 200, 300, 500
Typical Range of Values : 1 WidthPattern 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´WidthPattern 0µ ´WidthPattern WidthRegionµ
º HeightPattern (input control) ....................................................extent.y long
Height of a field of the checkerboard.
Default Value : 64
Value Suggestions : HeightPattern ¾1, 2, 4, 8, 16, 20, 32, 64, 100, 128, 200, 300, 500
Typical Range of Values : 1 HeightPattern 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´HeightPattern 0µ ´HeightPattern HeightRegionµ
Example
gen_checker_region(&Checker,512,512,32,64);
set_draw(WindowHandle,"fill");
set_part(WindowHandle,0,0,511,511);
disp_region(Checker,WindowHandle);
The required storage (in bytes) for the region is:
Ç´´ÏØÊÓÒ £ ÀØÊÓÒµÏØÈØØÖÒµ
Complexity
Result
The operator gen checker region returns the value H MSG TRUE if the parameter values are correct. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
gen checker region is reentrant and processed without parallelization.
paint region
Possible Successor Functions
Alternatives
gen grid region, T gen region polygon filled, (T )gen region points,
(T )gen region runs, (T )gen rectangle1, concat obj, gen random region,
gen random regions
See Also
hamming change region, reduce domain
Region processing
Module
gen circle ( Hobject *Circle, double Row, double Column, double Radius )
T gen circle ( Hobject *Circle, Htuple Row, Htuple Column,
Htuple Radius )
Create a circle.
The operator (T )gen circle generates one or more circles described by the center and Radius. If several
circles shall be generated the coordinates must be passed in the form of tuples.
The coordinate system runs from (0,0) (upper left corner) to (Width-1,Height-1). See get system and
reset obj db in this context.
HALCON 6.0

456 CHAPTER 9. REGIONS
If an integer value (1,2,3..) is given for the radius the result is an even-numbered diameter and thus an asymmetrical
circle. In case of an odd-numbered diameter (radius = 1.5,2.5,3.5...) a symmetrical circle is obtained.
If the circle extends beyond the image edge it is clipped to the current image format according to the value of the
system flag ’clip region’ (set system).
Parameter
º Circle (output object) ...................................................region(-array) Hobject *
Generated circle.
º Row (input control) ...................................circle.center.y(-array) (Htuple .) double / long
Line index of center.
Default Value : 200.0
Value Suggestions : Row ¾0.0, 10.0, 50.0, 100.0, 200.0, 300.0
Typical Range of Values : 1.0 Row 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Column (input control) ...............................circle.center.x(-array) (Htuple .) double / long
Column index of center.
Default Value : 200.0
Value Suggestions : Column ¾0.0, 10.0, 50.0, 100.0, 200.0, 300.0
Typical Range of Values : 1.0 Column 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Radius (input control) .................................circle.radius(-array) (Htuple .) double / long
Radius of circle.
Default Value : 100.5
Value Suggestions : Radius ¾1.0, 1.5, 2.0, 2.5, 3, 3.5, 4, 4.5, 5.5, 6.5, 7.5, 9.5, 11.5, 15.5, 20.5, 25.5, 31.5,
50.5
Typical Range of Values : 1.0 Radius 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Radius 0.0
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle);
read_image(&Image,"meer");
gen_circle(&Circle,300.0,200.0,150.5);
reduce_domain(Image,Circle,Mask);
disp_color(Mask,WindowHandle);
Runtime complexity: Ç´ÊÙ× £ ¾µ
Storage complexity (byte): Ç´ÊÙ× £ µ
Complexity
Result
If the parameter values are correct, the operator (T )gen circle returns the value H MSG TRUE.
Otherwise an exception handling is raised. The clipping according to the current image format is
set via the operator set system(’clip region’,). If an empty region is
created by clipping (the circle is completely outside of the image format) the operator set system
(’store gen empty region’,) determines whether the empty region is put out.
Parallelization Information
(T )gen circle is reentrant and processed without parallelization.
paint region, reduce domain
Possible Successor Functions
Alternatives
(T )gen ellipse, T gen region polygon filled, (T )gen region points,
(T )gen region runs, draw circle
See Also
disp circle, set shape, (T )smallest circle, reduce domain
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 457
Region processing
Module
gen ellipse ( Hobject *Ellipse, double Row, double Column, double Phi,
double Radius1, double Radius2 )
T gen ellipse ( Hobject *Ellipse, Htuple Row, Htuple Column, Htuple Phi,
Htuple Radius1, Htuple Radius2 )
Create an ellipse.
The operator (T )gen ellipse generates one or more ellipses with the center (Row, Column), the orientation
Phi and the half-radii Radius1 and Radius2. The angle is indicated in arc measure according to the Ü axis in
mathematically positive direction. More than one region can be created by passing tuples of parameter values.
The center must be located within the image coordinates. The coordinate system runs from (0,0) (upper left corner)
to (Width-1,Height-1). See get system and reset obj db in this context. If the ellipse reaches beyond the
edge of the image it is clipped to the current image format according to the value of the system flag ’clip region’
(set system).
Parameter
º Ellipse (output object) ..................................................region(-array) Hobject *
Created ellipse(s).
º Row (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y(-array) (Htuple .) double / long
Line index of center.
Default Value : 200.0
Value Suggestions : Row ¾0.0, 10.0, 20.0, 50.0, 100.0, 256.0, 300.0, 400.0
Typical Range of Values : 1.0 Row 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Column (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x(-array) (Htuple .) double / long
Column index of center.
Default Value : 200.0
Value Suggestions : Column ¾0.0, 10.0, 20.0, 50.0, 100.0, 256.0, 300.0, 400.0
Typical Range of Values : 1.0 Column 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Phi (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad(-array) (Htuple .) double / long
Orientation of the longer radius (Radius1).
Default Value : 0.0
Value Suggestions : Phi ¾-1.178097, -0.785398, -0.392699, 0.0, 0.392699, 0.785398, 1.178097
Typical Range of Values : -1.178097 Phi 1.178097 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Radius1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1(-array) (Htuple .) double / long
Longer radius.
Default Value : 100.0
Value Suggestions : Radius1 ¾2.0, 5.0, 10.0, 20.0, 50.0, 100.0, 256.0, 300.0, 400.0
Typical Range of Values : 1.0 Radius1 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Radius1 0
HALCON 6.0

458 CHAPTER 9. REGIONS
º Radius2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2(-array) (Htuple .) double / long
Shorter radius.
Default Value : 60.0
Value Suggestions : Radius2 ¾1.0, 2.0, 4.0, 5.0, 10.0, 20.0, 50.0, 100.0, 256.0, 300.0, 400.0
Typical Range of Values : 1.0 Radius2 1024.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : ´Radius2 0µ ´Radius2 Radius1µ
Example
open_window(0,0,-1,-1,"root","visible","",&WindowHandle);
set_insert(WindowHandle,"xor");
do {
get_mbutton(WindowHandle,&Row,&Column,&Button);
gen_ellipse(&Ellipse,(double)Row,(double)Column,Column / 300.0,
(Row % 100)+1.0,(Column % 50) + 1.0);
disp_region(Ellipse,WindowHandle);
clear_obj(Ellipse);
} while(Button != 1);
Runtime complexity: Ç´ÊÙ×½ £ ¾µ
Storage complexity (byte): Ç´ÊÙ×½ £ µ
Complexity
Result
If the parameter values are correct, the operator (T )gen ellipse returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
(T )gen ellipse is reentrant and processed without parallelization.
paint region, reduce domain
Possible Successor Functions
Alternatives
(T )gen circle, T gen region polygon filled, draw ellipse
See Also
disp ellipse, set shape, (T )smallest circle, reduce domain
Region processing
Module
gen empty region ( Hobject *EmptyRegion )
Create an empty region.
The operator gen empty region creates an empty region. This means that the output parameter contains an
object. Thus, count obj returns 1. The area of the region is 0. Most of the shape features are undefined (0). It
should be noted that an empty region must not be confused with the empty tuple.
Parameter
º EmptyRegion (output object) ...................................................region Hobject *
Empty region (no pixels).
Parallelization Information
gen empty region is reentrant and processed without parallelization.
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 459
gen grid region ( Hobject *RegionGrid, long RowSteps, long ColumnSteps,
const char *Type, long Width, long Height )
Create a region from lines or pixels.
The operator gen grid region creates a grid constructed of lines (Type = ’lines’) or pixels (Type = ’points’).
In case of ’lines’ continuous lines are returned, in case of ’points’ only the intersections of the lines. Starting from
the pixel (0,0) to the pixel (Height-1,Width-1) the grid is built up at stepping width RowSteps in line direction
and ColumnSteps in column direction. In the ’lines’ mode RowSteps, ColumnSteps respectively, can be
set to zero. In this case only columns, lines respectively, are created.
Attention
If a very small pattern is chosen (RowSteps 4 oder ColumnSteps 4) the created region requires much
storage.
In the ’points’ mode RowSteps and ColumnSteps must not be set to zero.
Parameter
º RegionGrid (output object) .....................................................region Hobject *
Created lines/pixel region.
º RowSteps (input control) ..................................................extent.y long / double
Step width in line direction or zero.
Default Value : 10
Value Suggestions : RowSteps ¾0, 2, 3, 4, 5, 7, 10, 15, 20, 30, 50, 100
Typical Range of Values : 0 RowSteps 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´RowSteps 1µ ´RowSteps 0µ
º ColumnSteps (input control) ..............................................extent.x long / double
Step width in column direction or zero.
Default Value : 10
Value Suggestions : ColumnSteps ¾0, 2, 3, 4, 5, 7, 10, 15, 20, 30, 50, 100
Typical Range of Values : 0 ColumnSteps 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´ColumnSteps 1µ ´ColumnSteps 0µ
º Type (input control) ............................................................string const char *
Type of created pattern.
Default Value : ’lines’
Value List : Type ¾’lines’, ’points’
º Width (input control) ...............................................................extent.x long
Maximum width of pattern.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 1
º Height (input control) ..............................................................extent.y long
Maximum height of pattern.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 1
Example
read_image(&Image,"fabrik");
gen_grid_region(&Raster,10,10,"lines",512,512);
HALCON 6.0

460 CHAPTER 9. REGIONS
reduce_domain(Image,Raster,&Mask);
sobel_amp(Mask,GridSobel,"sum_abs",3);
disp_image(GridSobel,WindowHandle);
Complexity
The necessary storage (in bytes) for the region is:
Ç´´ÁÑÏ ØÓÐÙÑÒËØÔ×µ £ ´ÁÑÀØÊÓÛËØÔ×µµ
Result
If the parameter values are correct the operator gen grid region returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
gen grid region is reentrant and processed without parallelization.
reduce domain, paint region
Possible Successor Functions
Alternatives
(T )gen region line, T gen region polygon, (T )gen region points,
(T )gen region runs
See Also
gen checker region, reduce domain
Region processing
Module
gen random region ( Hobject *RegionRandom, long Width, long Height )
Create a random region.
The operator gen random region returns a random region. During this process every pixel in the image area
¼ ÏØ ½℄¼ ÀØ ½℄ is adapted into the region with the probability 0.5. The created region can be
imagined as the threshold formation in an image with noise.
This procedure is particularly important for the creation of uncorrelated binary patterns. The random pattern is
created by the C function “nrand48()”.
Attention
If Width and Height are chosen large ( 100) the created region may require much storage space due to the
internally used runlength coding. The gray values of the output region are undefined.
Parameter
º RegionRandom (output object) ..................................................region Hobject *
Created random region with expansion Width x Height.
º Width (input control) ...............................................................extent.x long
Maximum horizontal expansion of random region.
Default Value : 128
Value Suggestions : Width ¾16, 32, 50, 64, 100, 128, 256, 300, 400, 512
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 0
º Height (input control) ..............................................................extent.y long
Maximum vertical expansion of random region.
Default Value : 128
Value Suggestions : Height ¾16, 32, 50, 64, 100, 128, 256, 300, 400, 512
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 0
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 461
Complexity
The worst case for the storage complexity for the created region (in byte) is: Ç´Ï Ø £ ÀØ £ ¾µ.
Result
If the parameter values are correct, the operator gen random region returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
gen random region is reentrant and processed without parallelization.
paint region, reduce domain
Possible Successor Functions
See Also
gen checker region, hamming change region, add noise distribution, add noise white,
reduce domain
Module
Region processing
gen random regions ( Hobject *Regions, const char *Type,
double WidthMin, double WidthMax, double HeightMin, double HeightMax,
double PhiMin, double PhiMax, long NumRegions, long Width, long Height )
Create random regions like circles, rectangles and ellipses.
The operator gen random region generates circles, rectangles and ellipses whose parameters are determined
at random. In each case only one lower, upper limit respectively, is given. The position is always random and
cannot be determined by parameters. The parameter NumRegions indicates how many regions shall be created.
Parameter
º Regions (output object) ...................................................region-array Hobject *
Created regions.
º Type (input control) ............................................................string const char *
Type of regions to be created.
Default Value : ’circle’
Value List : Type ¾’circle’, ’ring’, ’ellipse’, ’rectangle1’, ’rectangle2’
º WidthMin (input control) ...................................................number double / long
Minimum width of the region.
Default Value : 10.0
Value Suggestions : WidthMin ¾1.0, 3.0, 5.0, 10.0, 20.0, 40.0, 80.0
Typical Range of Values : 1.0 WidthMin 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : WidthMin 0
º WidthMax (input control) ...................................................number double / long
Maximum width of the region.
Default Value : 20.0
Value Suggestions : WidthMax ¾1.0, 3.0, 5.0, 10.0, 20.0, 40.0, 80.0
Typical Range of Values : 1.0 WidthMax 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : WidthMax 0
º HeightMin (input control) .................................................number double / long
Minimum height of the region.
Default Value : 10.0
Value Suggestions : HeightMin ¾1.0, 3.0, 5.0, 10.0, 20.0, 40.0, 80.0
Typical Range of Values : 1.0 HeightMin 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : HeightMin 0
HALCON 6.0

462 CHAPTER 9. REGIONS
º HeightMax (input control) .................................................number double / long
Maximum height of the region.
Default Value : 30.0
Value Suggestions : HeightMax ¾1.0, 3.0, 5.0, 10.0, 20.0, 40.0, 80.0
Typical Range of Values : 1.0 HeightMax 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : HeightMax 0
º PhiMin (input control) .....................................................number double / long
Minimum rotation angle of the region.
Default Value : -0.7854
Value Suggestions : PhiMin ¾0.0, 0.1, 0.3, 0.6, 0.9, 1.2, 1.5
Typical Range of Values : 0.0 PhiMin 6.28 (lin)
Minimal Value Step : 0.001
Recommended Value Step : 0.10
Restriction : PhiMin 0
º PhiMax (input control) .....................................................number double / long
Maximum rotation angle of the region.
Default Value : 0.7854
Value Suggestions : PhiMax ¾0.0, 0.1, 0.3, 0.6, 0.9, 1.2, 1.5
Typical Range of Values : 0.0 PhiMax 6.28 (lin)
Minimal Value Step : 0.001
Recommended Value Step : 0.10
Restriction : PhiMax 0
º NumRegions (input control) .........................................................integer long
Number of regions.
Default Value : 100
Value Suggestions : NumRegions ¾1, 5, 20, 100, 200, 500, 1000, 2000
Typical Range of Values : 1 NumRegions 2000 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : NumRegions 0
º Width (input control) ................................................................integer long
Maximum horizontal expansion.
Default Value : 512
Value Suggestions : Width ¾128, 256, 512, 1024
Typical Range of Values : 1 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 0
º Height (input control) ...............................................................integer long
Maximum vertical expansion.
Default Value : 512
Value Suggestions : Height ¾128, 256, 512, 1024
Typical Range of Values : 1 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 0
Result
If the parameter values are correct gen random regions returns the value H MSG TRUE. Otherwise an exception
handling is raised. The clipping according to the current image format is determined by the operator
set system(’clip region’,).
Parallelization Information
gen random regions is reentrant and processed without parallelization.
paint region
Region processing
Possible Successor Functions
Module
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 463
gen rectangle1 ( Hobject *Rectangle, double Row1, double Column1,
double Row2, double Column2 )
T gen rectangle1 ( Hobject *Rectangle, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2 )
Create a rectangle parallel to the coordinate axes.
The operator (T )gen rectangle1 generates one or more rectangles parallel to the coordinate axes which are
described by the upper left corner (Row1, Column1) and the lower right corner (Row2, Column2). More than
one region can be created by passing a tuple of corner points. The coordinate system runs from (0,0) (upper left
corner) to (Width-1,Height-1). See get system and reset obj db in this context.
Parameter
º Rectangle (output object) ...............................................region(-array) Hobject *
Created rectangle.
º Row1 (input control) ...............................rectangle.origin.y(-array) (Htuple .) double / long
Line of upper left corner point.
Default Value : 30.0
Value Suggestions : Row1 ¾0.0, 10.0, 20.0, 50.0, 100.0, 200.0
Typical Range of Values : ½ Row1 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Column1 (input control) ...........................rectangle.origin.x(-array) (Htuple .) double / long
Column of upper left corner point.
Default Value : 20.0
Value Suggestions : Column1 ¾0.0, 10.0, 20.0, 50.0, 100.0, 200.0
Typical Range of Values : ½ Column1 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Row2 (input control) ..............................rectangle.corner.y(-array) (Htuple .) double / long
Line of lower right corner point.
Default Value : 100.0
Value Suggestions : Row2 ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0, 511.0
Typical Range of Values : ½ Row2 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Row2 Row1
º Column2 (input control) ..........................rectangle.corner.x(-array) (Htuple .) double / long
Column of lower right corner point.
Default Value : 200.0
Value Suggestions : Column2 ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0, 511.0
Typical Range of Values : ½ Column2 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Column2 Column1
Example
/* Contrast improvement in a rectangular region of interest */
read_image(&Image,"fabrik");
open_window(0,0,-1,-1,"root","visible","",&WindowHandle);
disp_image(Image,WindowHandle);
draw_rectangle1(WindowHandle,&Row1,&Column1,&Row2,&Column2);
gen_rectangle1(&Rect,(double)Row1,(double)Column1,
(double)Row2,(double)Column2);
reduce_domain(Image,Rect,&Mask);
emphasize(Mask,&Emphasize,9,9,1.0);
disp_image(Emphasize,WindowHandle);
HALCON 6.0

464 CHAPTER 9. REGIONS
Result
If the parameter values are correct, the operator (T )gen rectangle1 returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
(T )gen rectangle1 is reentrant and processed without parallelization.
paint region, reduce domain
Possible Successor Functions
Alternatives
(T )gen rectangle2, T gen region polygon, fill up, (T )gen region runs,
(T )gen region points, (T )gen region line
See Also
draw rectangle1, reduce domain, (T )smallest rectangle1
Region processing
Module
gen rectangle2 ( Hobject *Rectangle, double Row, double Column,
double Phi, double Length1, double Length2 )
T gen rectangle2 ( Hobject *Rectangle, Htuple Row, Htuple Column,
Htuple Phi, Htuple Length1, Htuple Length2 )
Create a rectangle of any orientation.
The operator (T )gen rectangle2 generates one or more rectangles with the center (Row, Column) ,the
orientation Phi and the half edge lengths Length1 and Length2. The orientation is given in arc measure and
indicates the angle between the horizontal axis and Length1 (mathematically positive). The coordinate system
runs from (0,0) (upper left corner) to (Width-1,Height-1). See get system and reset obj db in this context.
More than one region can be created by passing one tuple of corner points.
Attention
The gray values of the output objects are undefined.
Parameter
º Rectangle (output object) ...............................................region(-array) Hobject *
Created rectangle.
º Row (input control) ...............................rectangle2.center.y(-array) (Htuple .) double / long
Line index of the center.
Default Value : 50.0
Value Suggestions : Row ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : ½ Row ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Column (input control) ...........................rectangle2.center.x(-array) (Htuple .) double / long
Column index of the center.
Default Value : 100.0
Value Suggestions : Column ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : ½ Column ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Phi (input control) ..............................rectangle2.angle.rad(-array) (Htuple .) double / long
Angle of longitudinal axis to horizontal (arc measure).
Default Value : 0.0
Value Suggestions : Phi ¾-1.178097, -0.785398, -0.392699, 0.0, 0.392699, 0.785398, 1.178097
Typical Range of Values : -1.178097 Phi 1.178097 (lin)
Minimal Value Step : 0.001
Recommended Value Step : 0.1
Restriction : ´´ pi2µ Phiµ ´Phi ´pi2µµ
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 465
º Length1 (input control) ..........................rectangle2.hwidth(-array) (Htuple .) double / long
Half width.
Default Value : 200.0
Value Suggestions : Length1 ¾3.0, 5.0, 10.0, 15.0, 20.0, 50.0, 100.0, 200.0, 300.0, 500.0
Typical Range of Values : ½ Length1 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Length2 (input control) ..........................rectangle2.hheight(-array) (Htuple .) double / long
Half height.
Default Value : 100.0
Value Suggestions : Length2 ¾1.0, 2.0, 3.0, 5.0, 10.0, 15.0, 20.0, 50.0, 100.0, 200.0
Typical Range of Values : ½ Length2 ½(lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Length2 Length1
Result
If the parameter values are correct the operator (T )gen rectangle2 returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,).
Parallelization Information
(T )gen rectangle2 is reentrant and processed without parallelization.
paint region, reduce domain
Possible Successor Functions
Alternatives
(T )gen rectangle1, T gen region polygon filled, T gen region polygon,
(T )gen region points, fill up
See Also
draw rectangle2, reduce domain, (T )smallest rectangle2, (T )gen ellipse
Region processing
Module
T gen region histo ( Hobject *Region, Htuple Histogramm, Htuple Row,
Htuple Column, Htuple Scale )
Convert a histogram into a region.
T gen region histo converts a histogram created with gray histo into a region. The effect of the three
control parameters is the same as in disp image and set paint.
Parameter
º Region (output object) ..........................................................region Hobject *
Region containing the histogram.
º Histogramm (input control) .........................................histogram-array Htuple . long
Input histogram.
º Row (input control) ...........................................................point.y Htuple . long
Row coordinate of the center of the histogram.
Default Value : 255
Value Suggestions : Row ¾100, 200, 255, 300, 400
Typical Range of Values : 0 Row 511
º Column (input control) .......................................................point.x Htuple . long
Column coordinate of the center of the histogram.
Default Value : 255
Value Suggestions : Column ¾100, 200, 255, 300, 400
Typical Range of Values : 0 Column 511
HALCON 6.0

466 CHAPTER 9. REGIONS
º Scale (input control) ........................................................integer Htuple . long
Scale factor for the histogram.
Default Value : 1
Value List : Scale ¾1, 2, 3, 4, 5, 6, 7
Typical Range of Values : 1 Scale 10 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Result
T gen region histo returns H MSG TRUE if all parameters are correct. If necessary, an exception handling
is raised.
Parallelization Information
T gen region histo is reentrant and processed without parallelization.
gray histo
disp channel, set paint
Region processing
Possible Predecessor Functions
See Also
Module
gen region hline ( Hobject *Regions, double Orientation,
double Distance )
T gen region hline ( Hobject *Regions, Htuple Orientation,
Htuple Distance )
Store input lines described in Hesse normal shape as regions.
The operator (T )gen region hline stores the lines described in Hesse normal shape as regions. A line is
determined by the distance from the line to the origin (Distance, corresponds to the length of the normal vector)
and the direction of the normal vector (Orientation, corresponds to the orientation of the line ¦¾). The
directions were defined in such a way that at Orientation = 0 the normal vector lies in the direction of the X
axis, which corresponds to a vertical line. At Orientation = ¾ the normal vector points in the direction of
the Y axis, i.e. a horizontal line is described.
Attention
The lines are clipped to the current maximum image format.
Parameter
º Regions (output object) ..................................................region(-array) Hobject *
Created regions (one for every line), clipped to maximum image format.
Parameter Number : Regions Distance
º Orientation (input control) ....................hesseline.angle.rad(-array) (Htuple .) double / long
Orientation of the normal vector in radians.
Default Value : 0.0
Value Suggestions : Orientation ¾-0.78, 0.0, 0.78, 1.57
Typical Range of Values : ½ Orientation ½(lin)
Recommended Value Step : 0.02
Parameter Number : Orientation Distance
º Distance (input control) .........................hesseline.distance(-array) (Htuple .) double / long
Distance from the line to the coordinate origin (0.0).
Default Value : 200
Value Suggestions : Distance ¾10, 50, 100, 200, 300, 400
Typical Range of Values : ½ Distance ½(lin)
Recommended Value Step : 1
Result
The operator (T )gen region hline always returns the value H MSG TRUE.
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 467
Parallelization Information
(T )gen region hline is reentrant and processed without parallelization.
(T )gen region line
hough lines
Region processing
Alternatives
See Also
Module
gen region line ( Hobject *RegionLines, long BeginRow, long BeginCol,
long EndRow, long EndCol )
T gen region line ( Hobject *RegionLines, Htuple BeginRow,
Htuple BeginCol, Htuple EndRow, Htuple EndCol )
Store input lines as regions.
The operator (T )gen region line stores the given lines (with starting point [BeginRow,BeginCol] and
ending point [EndRow, EndCol]) as region.
Parameter
º RegionLines (output object) ............................................region(-array) Hobject *
Created regions.
º BeginRow (input control) .......................................line.begin.y(-array) (Htuple .) long
Line coordinates of the starting points of the input lines.
Default Value : 100
Value Suggestions : BeginRow ¾10, 50, 100, 200, 300, 400
Typical Range of Values : ½ BeginRow ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º BeginCol (input control) .......................................line.begin.x(-array) (Htuple .) long
Column coordinates of the starting points of the input lines.
Default Value : 50
Value Suggestions : BeginCol ¾10, 50, 100, 200, 300, 400
Typical Range of Values : ½ BeginCol ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º EndRow (input control) ............................................line.end.y(-array) (Htuple .) long
Line coordinates of the ending points of the input lines.
Default Value : 150
Value Suggestions : EndRow ¾50, 100, 200, 300, 400, 500
Typical Range of Values : ½ EndRow ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º EndCol (input control) ............................................line.end.x(-array) (Htuple .) long
Column coordinates of the ending points of the input lines.
Default Value : 250
Value Suggestions : EndCol ¾50, 100, 200, 300, 400, 500
Typical Range of Values : ½ EndCol ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
Result
The operator (T )gen region line always returns the value H MSG TRUE. The clipping according to the
current image format is determined by the operator set system(’clip region’,).
Parallelization Information
(T )gen region line is reentrant and processed without parallelization.
HALCON 6.0

468 CHAPTER 9. REGIONS
T split skeleton lines
(T )gen region hline
Region processing
Possible Predecessor Functions
Alternatives
Module
gen region points ( Hobject *Region, long Rows, long Columns )
T gen region points ( Hobject *Region, Htuple Rows, Htuple Columns )
Store individual pixels as image region.
The operator (T )gen region points creates a region described by a number of pixels. The pixels do not
have to be stored in a fixed order, but the best runtime behavior is obtained when the pixels are stored in ascending
order. The order is as follows:
´Ð ½ ½ µ ´Ð ¾ ¾ µ´Ð ½ Ð ¾ µ ´Ð ½ Ð ¾ µ ´ ½ ¾ µ
The indicated coordinates stand for two consecutive pixels in the tupel.
Attention
The gray values of the output regions are undefined. All pixels must be located within the image format. If no
pixels are passed an empty region is created.
Parameter
º Region (output object) ..........................................................region Hobject *
Created region.
º Rows (input control) ...........................................coordinates.y(-array) (Htuple .) long
Lines of the pixels in the region.
Default Value : 100
Value Suggestions : Rows ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Rows ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Columns (input control) .......................................coordinates.x(-array) (Htuple .) long
Columns of the pixels in the region.
Default Value : 100
Value Suggestions : Columns ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Columns ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : Columns Rows
Complexity
shall be the number of pixels. If the pixels are sorted in ascending order the runtime complexity is: Ç´ µ,
otherwise Ç´ÐÓ´ µ £ µ.
Result
The operator (T )gen region points returns the value H MSG TRUE if the pixels are located within the image
format. Otherwise an exception handling is raised. The clipping according to the current image format is set via
the operator set system(’clip region’,). If an empty region is created (empty
input) the operator set system(’store gen empty region’,) determines whether the
region is returned.
Parallelization Information
(T )gen region points is reentrant, local, and processed without parallelization.
T get region points
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 469
paint region, reduce domain
Possible Successor Functions
Alternatives
T gen region polygon, (T )gen region runs, (T )gen region line
reduce domain
Region processing
See Also
Module
T gen region polygon ( Hobject *Region, Htuple Rows, Htuple Columns )
Store a polygon as an image object.
The operator T gen region polygon creates a region from a polygon row described by a series of line and
column coordinates. The created region consists of the pixels of the routes defined thereby, wherein it is linearily
interpolated between the base points.
Attention
The region is automatically closed and not filled. The gray values of the output regions are undefined. All base
points must be located within the image format. If no pixels are passed an empty region is created.
Parameter
º Region (output object) ..........................................................region Hobject *
Created region.
º Rows (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long
Line indices of the base points of the region contour.
Default Value : 100
Value Suggestions : Rows ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Rows ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Columns (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long
Colum indices of the base points of the region contour.
Default Value : 100
Value Suggestions : Columns ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Columns ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : Columns Rows
Example
/* Polygon-approximation */
T_get_region_polygon(Region,7,&Row,&Column);
/* store it as a region */
T_gen_region_polygon(&Pol,Row,Column);
destroy_tuple(Row);
destroy_tuple(Column);
/* fill up the hole */
fill_up(Pol,&Filled);
Result
If the base points are correct the operator T gen region polygon returns the value H MSG TRUE. Otherwise
an exception handling is raised. The clipping according to the current image format is set via the operator
set system(’clip region’,). If an empty region is created the operator
set system(’store gen empty region’,) determines whether the region is returned.
Parallelization Information
T gen region polygon is reentrant, local, and processed without parallelization.
HALCON 6.0

470 CHAPTER 9. REGIONS
Possible Predecessor Functions
T get region polygon, draw polygon
Alternatives
T gen region polygon filled, (T )gen region points, (T )gen region runs
See Also
fill up, reduce domain, T get region polygon, draw polygon
Region processing
Module
T gen region polygon filled ( Hobject *Region, Htuple Rows,
Htuple Columns )
Store a polygon as a “filled” region.
The operator T gen region polygon filled creates a region from a polygon containing the corner
points of the region (line and column coordinates) either clockwise or anti-clockwise. Contrary to
T gen region polygon a “filled” region is returned here.
Attention
All base points must be located within the image format. If no pixels are passed an empty region is created.
Parameter
º Region (output object) ..........................................................region Hobject *
Created region.
º Rows (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long
Line indices of the base points of the region contour.
Default Value : 100
Value Suggestions : Rows ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Rows ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Columns (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long
Column indices of the base points of the region contour.
Default Value : 100
Value Suggestions : Columns ¾0, 10, 30, 50, 100, 200, 300, 500
Typical Range of Values : ½ Columns ½(lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : Columns Rows
Example
/* Polygon approximation */
T_get_region_polygon(Region,7,&Row,&Column);
T_gen_region_polygon_filled(&Pol,Row,Column);
/* fill up with original gray value */
reduce_domain(Image,Pol,&New);
Result
If the base points are correct the operator T gen region polygon filled returns the value H MSG TRUE.
Otherwise an exception handling is raised. If an empty region is created the operator set system
(’store gen empty region’,) determines whether the region is returned.
Parallelization Information
T gen region polygon filled is reentrant, local, and processed without parallelization.
Possible Predecessor Functions
T get region polygon, draw polygon
Alternatives
T gen region polygon, (T )gen region points, draw polygon
HALCON/C Reference Manual / 2000-11-15

9.3. CREATION 471
See Also
T gen region polygon, reduce domain, T get region polygon, (T )gen region runs
Region processing
Module
gen region runs ( Hobject *Region, long Row, long ColumnBegin,
long ColumnEnd )
T gen region runs ( Hobject *Region, Htuple Row, Htuple ColumnBegin,
Htuple ColumnEnd )
Create an image region from a runlength coding.
The operator (T )gen region runs creates a region described by the input runlength structure. The runlength
representation is created by examining a region line by line with ascending line number (= from “top” to “bottom”).
Every line runs through from left to right (ascending column number)Ȧll starting and ending points being stored
by region segments (=runs). Thus a region can be described by a sequence of runs, a run being defined by line
number as well as starting and ending points (column number).
The storing is fastest when the runs are sorted. The order is as follows:
.
´Ð ½ ½ ½ µ ´Ð ¾ ¾ ¾ µ´Ð ½ Ð ¾ µ ´Ð ½ Ð ¾ µ ´ ½ ¾ µ
Attention
All pixels must be located within the image format. If no runs are passed an empty region is created.
Parameter
º Region (output object) ..........................................................region Hobject *
Created region.
º Row (input control) ..................................................chord.y(-array) (Htuple .) long
Lines of the runs.
Default Value : 100
Value Suggestions : Row ¾0, 50, 100, 200, 300, 500
Typical Range of Values : ½ Row ½(lin)
Minimal Value Step : 1
Recommended Value Step : 10
º ColumnBegin (input control) ......................................chord.x1(-array) (Htuple .) long
Columns of the starting points of the runs.
Default Value : 50
Value Suggestions : ColumnBegin ¾0, 50, 100, 200, 300, 500
Typical Range of Values : ½ ColumnBegin ½(lin)
Minimal Value Step : 1
Recommended Value Step : 10
Parameter Number : ColumnBegin Row
º ColumnEnd (input control) ........................................chord.x2(-array) (Htuple .) long
Columns of the ending points of the runs.
Default Value : 200
Value Suggestions : ColumnEnd ¾50, 100, 200, 300, 500
Typical Range of Values : ½ ColumnEnd ½(lin)
Minimal Value Step : 1
Recommended Value Step : 10
Parameter Number : ColumnEnd Row
Restriction : ColumnEnd ColumnBegin
Complexity
shall be the number of pixels. If the pixels are sorted in ascending order the runtime complexity is: Ç´ µ,
otherwise it is Ç´ÐÓ´ µ £ µ.
HALCON 6.0

472 CHAPTER 9. REGIONS
Result
If the data is correct the operator (T )gen region runs returns the value H MSG TRUE, otherwise an exception
handling is raised. The clipping according to the current image format is set via the operator set system
(’clip region’,). If an empty region is created (= empty input) the operator
set system(’store gen empty region’,) determines whether the region is returned.
Parallelization Information
(T )gen region runs is reentrant, local, and processed without parallelization.
T get region runs
Possible Predecessor Functions
Alternatives
(T )gen region points, T gen region polygon, (T )gen region line,
T gen region polygon filled
See Also
reduce domain
Module
Region processing
label to region ( Hobject LabelImage, Hobject *Regions )
Extract regions with equal gray values from an image.
label to region segments an image into regions of equal gray value. One output region is generated for
each gray value occuring in the image. This is similar to calling threshold multiple times, and accumulating
the results with concat obj. Another related operator is regiongrowing. However,label to region
does not perform a connection operation on the resulting regions, i.e., they may be disconnected. A typical
application of label to region is the segmentation of label images, hence its name.
The number of output regions is limited by the system parameter ’max outp obj par’, which can be read via
get system(::’max outp obj par’:Anzahl).
Attention
label to region is not implemented for images of type ’real’. The input images must not contain negative
gray values.
Parameter
º LabelImage (input object) ................................image(-array) Hobject : byte / int2 / int4
Label image.
º Regions (output object) ...................................................region-array Hobject *
Regions having a constant gray value.
Complexity
Let ܽ be the minimum x-coordinate, ܾ the maximum x-coordinate, ݽ be the minimum y-coordinate, and ݾ the
maximum y-coordinate of a particular gray value. Furthermore, let Æ be the number of different gray values in the
image. Then the runtime complexity is Ç´Æ £ ´Ü¾ ܽ ·½µ£ ´Ý¾ ݽ · ½µµ
Result
label to region returns H MSG TRUE if the gray values lie within a correct range. The behavior with respect
to the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
label to region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
min max gray, sobel amp, gauss image, reduce domain, diff of gauss
Possible Successor Functions
connection, dilation1, erosion1, opening, closing, rank region, shape trans, skeleton
See Also
threshold, concat obj, regiongrowing, region to label
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 473
Region processing
Module
9.4 Features
area center ( Hobject Regions, long *Area, double *Row, double *Column )
T area center ( Hobject Regions, Htuple *Area, Htuple *Row,
Htuple *Column )
Area and center of regions.
The operator (T )area center calculates the area and the center of the input regions. The area is defined as
the number of pixels of a region. The center is calculated as the mean value of the line or column coordinates,
respectively, of all pixels.
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of the input region. In case of empty region all parameters have the value 0.0 if no other behavior was
set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Area (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Area of the region.
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Line index of the center.
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column index of the center.
Example
threshold(&Image,&Seg,120.0,255.0);
connection(Seg,&Connected);
T_area_center(Connected,&Area,&Row,&Column);
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )area center returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )area center is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )select shape
Region processing
See Also
Module
HALCON 6.0

474 CHAPTER 9. REGIONS
circularity ( Hobject Regions, double *Circularity )
T circularity ( Hobject Regions, Htuple *Circularity )
Shape factor for the circularity (similarity to a circle) of a region.
The operator (T )circularity calculates the similarity of the input region with a circle.
Calculation: If F is the area of the region and max is the maximum distance from the center to all contour pixels,
the shape factor C is defined as:
´ÑÜ ¾ £ µ
The shape factor of a circle is 1. If the region is long or has holes is smaller than 1. The operator
(T )circularity especially responds to large bulges, holes and unconnected regions.
In case of an empty region the operator (T )circularity returns the value 0 (if no other behavior was set (see
set system)). If more than one region is passed the numerical values of the shape factor are stored in a tuple,
the position of a value in the tuple corresponding to the position of the region in the input tuple.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Circularity (output control) .....................................real(-array) (Htuple .) double *
Roundness of the input region(s).
Assertion : ´0 Circularityµ ´Circularity 1.0µ
Example
/* Comparison between shape factors of rectangle, circle and ellipse */
gen_rectangle1(&R1,10.0,10.0,20.0,20.0);
gen_rectangle2(&R2,100.0,100.0,0.0,100.0,20.0);
gen_ellipse(&E,100.0,100.0,0.0,100.0,20.0);
gen_circle(&C,100.0,100.0,20.0);
circularity(R1,&R1_);
circularity(R2,&R2_);
circularity(E,&E_);
circularity(C,&C_);
printf("quadrate: %g\n",R1_);
printf("rectangle: %g\n",R2_);
printf("ellipse: %g\n",E_);
printf("circle: %g\n",C_);
Result
The operator (T )circularity returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )circularity is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
(T )roundness, (T )compactness, (T )convexity, (T )eccentricity
(T )area center, (T )select shape
Region processing
See Also
Module
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 475
compactness ( Hobject Regions, double *Compactness )
T compactness ( Hobject Regions, Htuple *Compactness )
Shape factor for the compactness of a region.
The operator (T )compactness calculates the compactness of the input regions.
Calculation: If Ä is the length of the contour (see (T )contlength) and the area of the region the shape
factor is defined as:
ľ
The shape factor of a circle is 1. If the region is long or has holes is larger than 1. The operator
(T )compactness responds to the course of the contour (roughness) and to holes. In case of an empty region
the operator (T )compactness returns the value 0 if no other behavior was set (see set system). If
more than one region is passed the numerical values of the shape factor are stored in a tuple, the position of a value
in the tuple corresponding to the position of the region in the input tuple.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Compactness (output control) .....................................real(-array) (Htuple .) double *
Compactness of the input region(s).
Assertion : ´Compactness 1.0µ ´Compactness 0µ
Result
The operator (T )compactness returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )compactness is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
(T )compactness, (T )convexity, (T )eccentricity
See Also
(T )contlength, (T )area center, (T )select shape
Region processing
Module
connect and holes ( Hobject Regions, long *NumConnected,
long *NumHoles )
T connect and holes ( Hobject Regions, Htuple *NumConnected,
Htuple *NumHoles )
Number of connection components and holes
The operator (T )connect and holes calculates the number of connection components and the number of
holes of each region of Regions.
If more than one region is passed the numerical values of the output control parameters NumConnected and
NumHoles are each stored in a tuple, the position of a value in the tuple corresponding to the position of the
region in the input tuple.
HALCON 6.0

476 CHAPTER 9. REGIONS
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º NumConnected (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Number of connection components of a region.
º NumHoles (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Number of holes of a region.
Result
The operator (T )connect and holes returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set)
is set via set system(’empty region result’,).
Parallelization Information
(T )connect and holes is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )euler number
Alternatives
See Also
connection, fill up, fill up shape, union1
Region processing
Module
contlength ( Hobject Regions, double *ContLength )
T contlength ( Hobject Regions, Htuple *ContLength )
Contour length of a region.
The operator (T )contlength calculates the total length of the contour (sum of all connection components of
the region) for each region of Regions. The distance between two neighboring contour points parallel to the
coordinate axes is rated 1, the distance in the diagonal is rated Ô ¾. If more than one region is passed the numerical
values of the contour length are stored in a tuple, the position of a value in the tuple corresponding to the position
of the region in the input tuple. In case of an empty region the operator (T )contlength returns the value 0.
The contour of holes is not calculated.
Attention
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º ContLength (output control) .......................................real(-array) (Htuple .) double *
Contour length of the input region(s).
Assertion : ContLength 0
Example
#include
#include
"HalconCpp.h"
int main (int argc, char *argv[])
{
if (argc < 2)
{
cout

9.4. FEATURES 477
}
HWindow w;
HRegionArray reg;
int NumOfElements = atoi (argv[1]);
cout

478 CHAPTER 9. REGIONS
Ó
The shape factor is 1 if the region is convex (e.g. rectangle, circle etc.). If there are indentations or holes is
smaller than 1.
In case of an empty region the operator (T )convexity returns the value 0 (if no other behavior was set (see
set system)). If more than one region is passed the numerical values of the contour length are stored in a tuple,
the position of a value in the tuple corresponding to the position of the region in the input tuple.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Convexity (output control) ........................................real(-array) (Htuple .) double *
Convexity of the input region(s).
Assertion : Convexity 1
Result
The operator (T )convexity returns the value H MSG TRUE if the input is not empty. The behavior
in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )convexity is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
See Also
(T )select shape, (T )area center, shape trans
Region processing
Module
diameter region ( Hobject Regions, long *Row1, long *Column1,
long *Row2, long *Column2, double *Diameter )
T diameter region ( Hobject Regions, Htuple *Row1, Htuple *Column1,
Htuple *Row2, Htuple *Column2, Htuple *Diameter )
Maximal distance between two boundary points of a region.
The operator (T )diameter region calculates the maximal distance between two boundary points of a region.
The coordinates of these two extremes and the distance between them will be returned.
Attention
If the region is empty, the results of Row1, Column1, Row2 and Column2 (all of them = 0) may lead to confusion.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Row1 (output control) ..........................................line.begin.y(-array) (Htuple .) long *
Row index of the first extreme point.
º Column1 (output control) ......................................line.begin.x(-array) (Htuple .) long *
Column index of the first extreme point.
º Row2 (output control) ...........................................line.end.y(-array) (Htuple .) long *
Row index of the second extreme point.
º Column2 (output control) .......................................line.end.x(-array) (Htuple .) long *
Column index of the second extreme point.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 479
º Diameter (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Distance of the two extreme points.
Complexity
If is the area of a region, the runtime complexity amounts to Ç´Ô
µ on average.
Result
The operator (T )diameter region returns the value H MSG TRUE, if the input is not empty. The reaction
to empty input (no input regions are available) may be determined with the help of the operator set system
(’no object result’,). The reaction concerning an empty region (region is the empty set)
will be determined by the operator set system(’empty region result’,). If necessary an
exception handling is raised.
Parallelization Information
(T )diameter region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
disp line
(T )smallest rectangle2
Region processing
Possible Successor Functions
Alternatives
Module
eccentricity ( Hobject Regions, double *Anisometry, double *Bulkiness,
double *StructureFactor )
T eccentricity ( Hobject Regions, Htuple *Anisometry, Htuple *Bulkiness,
Htuple *StructureFactor )
Shape features derived from the ellipse parameters.
The operator (T )eccentricity calculates three shape features derived from the geometric moments.
Definition: If the parameters Á, Á and the area of the region are given (see (T )moments region 2nd,
(T )elliptic axis), the following applies:
Ò×ÓÑØÖÝ Á
Á
ÙÐÒ××
¡ ¡ Á ¡ Á
¿
ËØÖÙØÙÖØÓÖ Ò×ÓÑØÖÝ ¡ ÙÐÒ××
½
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Anisometry (output control) .......................................real(-array) (Htuple .) double *
Shape feature (in case of a circle = 1.0).
Assertion : Anisometry 1.0
º Bulkiness (output control) ........................................real(-array) (Htuple .) double *
Calculated shape feature.
º StructureFactor (output control) ................................real(-array) (Htuple .) double *
Calculated shape feature.
HALCON 6.0

480 CHAPTER 9. REGIONS
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )eccentricity returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )eccentricity is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
See Also
(T )elliptic axis, (T )moments region 2nd, (T )select shape, (T )area center
Region processing
Module
elliptic axis ( Hobject Regions, double *Ra, double *Rb, double *Phi )
T elliptic axis ( Hobject Regions, Htuple *Ra, Htuple *Rb, Htuple *Phi )
Parameters of the equivalent ellipse.
The operator (T )elliptic axis calculates the radii and the orientation of the ellipse having the “same orientation”
and the “same side relation” as the input region. Several input regions can be passed in Regions as
tuples. The length of the main radius Ra and the secondary radius Rb as well as the orientation of the main axis
with regard to the horizontal (Phi) are determined. The angle is indicated in arc measure.
Calculation:
If the moments Å ¾¼ , Å ¼¾ and Å ½½ are normalized and passed to the area (see (T )moments region 2nd),
the radii Ra and Rb are calculated as:
Ê
Ê
The orientation Phi is defined by:
Õ
´Å ¾¼ · Å ¼¾ ·
Õ
´Å ¾¼ · Å ¼¾
Ô
´Å ¾¼ Å ¼¾ µ ¾ ·Å ¾ ½½ µ
¾
Ô
´Å ¾¼ Å ¼¾ µ ¾ ·Å½½ ¾ µ
È ¼ØÒ¾´¾Å ½½ Å ¼¾ Å ¾¼ µ
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system
(’no object result’,)).
¾
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Ra (output control) ..................................................real(-array) (Htuple .) double *
Main radius (normalized to the area).
Assertion : Ra 0.0
º Rb (output control) ..................................................real(-array) (Htuple .) double *
Secondary radius (normalized to the area).
Assertion : ´Rb 0.0µ ´Rb Raµ
º Phi (output control) ................................................real(-array) (Htuple .) double *
Angle between main radius and x axis (arc measure).
Assertion : ´´ pi2µ Phiµ ´Phi ´pi2µµ
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 481
Example
read_image(&Image,"fabrik");
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
regiongrowing(Image,&Seg,5,5,6.0,100);
T_elliptic_axis(Seg,&Ra,&Rb,&Phi);
T_area_center(Seg,_t,&Row,&Column);
T_gen_ellipse(&Ellipses,Row,Column,Phi,Ra,Rb);
set_draw(WindowHandle,"margin");
disp_region(Ellipses,WindowHandle);
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )elliptic axis returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )elliptic axis is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )gen ellipse
Possible Successor Functions
Alternatives
(T )smallest rectangle2, (T )orientation region
See Also
(T )moments region 2nd, (T )select shape, set shape
Bibliography
R. Haralick, L. Shapiro “Computer and Robot Vision” Addison-Wesley, 1992, pp. 73-75
Region processing
Module
euler number ( Hobject Regions, long *EulerNumber )
T euler number ( Hobject Regions, Htuple *EulerNumber )
Calculate the Euler number.
The procedure (T )euler number calculates the Euler number, i.e. the difference between the number of connection
components and the number of holes.
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º EulerNumber (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Calculated Euler number.
Result
The operator (T )euler number returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
HALCON 6.0

482 CHAPTER 9. REGIONS
Parallelization Information
(T )euler number is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )connect and holes
Region processing
Alternatives
Module
T find neighbors ( Hobject Regions1, Hobject Regions2,
Htuple MaxDistance, Htuple *RegionIndex1, Htuple *RegionIndex2 )
Search direct neighbors.
The operator T find neighbors determines neighboring regions with Regions1 and Regions2 containing
the regions to be examined. Regions1 can have three different states:
¯ Regions1 is empty:
In this case all regions in Regions2 are permutatively checked for neighborhood.
¯ Regions1 consists of one region:
The regions of Regions1 are compared to all regions in Regions2.
¯ Regions1 consists of the same number of regions as Regions2:
Here all regions at the n-th position in Regions1 and Regions2 are checked for the neighboring relation.
The operator T find neighbors uses the city block distance between neighboring regions. It can be specified
by the parameter MaxDistance. neighboring regions are located at the n-th position in RegionIndex1 and
RegionIndex2, i.e. the region with index RegionIndex1[n] from Regions1 is the neighbor of the region
with index RegionIndex2[n] from Regions2.
Covered regions are not found!
Attention
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Starting regions.
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions.
º MaxDistance (input control) ................................................integer Htuple . long
Maximal distance of regions.
Default Value : 1
Value Suggestions : MaxDistance ¾1, 2, 3, 4, 5, 6, 7, 8, 10, 15, 20, 50
Typical Range of Values : 1 MaxDistance 255
Minimal Value Step : 1
Recommended Value Step : 1
º RegionIndex1 (output control) ......................................integer-array Htuple . long *
Indices of the found regions from Regions1.
º RegionIndex2 (output control) ......................................integer-array Htuple . long *
Indices of the found regions from Regions2.
Result
The operator T find neighbors returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T find neighbors is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 483
See Also
T spatial relation, T select region spatial, expand region, interjacent, boundary
Region processing
Module
get region index ( Hobject Regions, long Row, long Column, long *Index )
T get region index ( Hobject Regions, Htuple Row, Htuple Column,
Htuple *Index )
Index of all regions containing a given pixel.
The operator (T )get region index returns the index of all regions in Regions (value range 0 to n-1)
containing the test pixel (Row,Column), i.e.:
ÊÓÒ×Ò℄ ´ÊÓÛ ÓÐÙÑÒµ
Attention
If the regions overlap more than one region might contain the pixel. In this case all these regions are returned. If
no region contains the indicated pixel the empty tuple (= no region) is returned.
Parameter
º Regions (input object) ......................................................region-array Hobject
Regions to be examined.
º Row (input control) .........................................................point.y (Htuple .) long
Line index of the test pixel.
Default Value : 100
Typical Range of Values : ½ Row ½(lin)
º Column (input control) .....................................................point.x (Htuple .) long
Column index of the test pixel.
Default Value : 100
Typical Range of Values : ½ Column ½(lin)
º Index (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Index of the regions containing the test pixel.
Complexity
If is the area of the region and Æ is the number of regions the mean runtime complexity is Ç´ÐÒ´Ô
µ £ Æ µ.
Result
The operator (T )get region index returns the value H MSG TRUE if the parameters are correct.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
(T )get region index is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
select region point
Alternatives
See Also
get mbutton, get mposition, test region point
Region processing
Module
T get region thickness ( Hobject Region, Htuple *Thickness,
Htuple *Histogramm )
Access the thickness of a region along the main axis.
HALCON 6.0

484 CHAPTER 9. REGIONS
The operator T get region thickness calculates the thickness of the regions along the main axis (see
(T )elliptic axis) for each pixel of the section. The thickness at one point on the main axis is defined
as the distance between the intersections of the contour with the plumb on the main axis in the respective point
which are the furthest apart. Additionally the operator T get region thickness returns the Histogramm
of the thicknesses of the region. The length of the histogram corresponds to the largest occurring thickness in the
observed region.
Attention
Only one region may be passed. If the region has several connection components, only the first one is investigated.
All other components are ignored.
Parameter
º Region (input object) .............................................................region Hobject
Region to be analysed.
º Thickness (output control) ..........................................integer-array Htuple . long *
Thickness of the region along its main axis.
º Histogramm (output control) .........................................integer-array Htuple . long *
Histogram of the thickness of the region along its main axis.
Result
The operator T get region thickness returns the value H MSG TRUE if exactly one region is passed.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,).
Parallelization Information
T get region thickness is reentrant and processed without parallelization.
Possible Predecessor Functions
sobel amp, threshold, connection, (T )select shape, select obj
copy obj, (T )elliptic axis
Region processing
See Also
Module
hamming distance ( Hobject Regions1, Hobject Regions2, long *Distance,
double *Similarity )
T hamming distance ( Hobject Regions1, Hobject Regions2,
Htuple *Distance, Htuple *Similarity )
Hamming distance between two regions.
The operator (T )hamming distance returns the hamming distance between two regions, i.e. the number of
pixels of the regions which are different (Distance), i.e. the number of pixels contained in one region but not in
the other:
×ØÒ ÊÓÒ×½ ÊÓÒ×¾ · ÊÓÒ×¾ ÊÓÒ×½
The parameter Similarity describes the similarity between the two regions based on the hamming distance
Distance:
ËÑÐÖØÝ ½
×ØÒ
ÊÓÒ×½ · ÊÓÒ×¾
If both regions are empty Similarity is set to 0. The regions with the same index from both input parameters
are always compared.
Attention
In both input parameters the same number of regions must be passed.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 485
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions.
º Distance (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Hamming distance of two regions.
Assertion : Distance 0
º Similarity (output control) .......................................real(-array) (Htuple .) double *
Similarity of two regions.
Assertion : ´0 Similarityµ ´Similarity 1µ
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
hamming distance returns the value H MSG TRUE if the number of objects in both parameters is the same and
is not 0. The behavior in case of empty input (no input objects available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling handling
is raised.
Parallelization Information
(T )hamming distance is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
intersection, complement, (T )area center
hamming change region
Region processing
See Also
Module
hamming distance norm ( Hobject Regions1, Hobject Regions2,
const char *Norm, long *Distance, double *Similarity )
T hamming distance norm ( Hobject Regions1, Hobject Regions2,
Htuple Norm, Htuple *Distance, Htuple *Similarity )
Hamming distance between two regions using normalization.
The operator (T )hamming distance norm returns the hamming distance between two regions, i.e. the number
of pixels of the regions which are different (Distance). Before calculating the different the region in
Regions1 are normalized according to the regions in Regions2. The result is the number of pixels contained
in one region but not in the other:
×ØÒ ÆÓÖÑ´ÊÓÒ×½µ ÊÓÒ×¾ · ÊÓÒ×¾ ÆÓÖÑ´ÊÓÒ×½µ
The parameter Similarity describes the similarity between the two regions based on the hamming distance
Distance:
ËÑÐÖØÝ ½
×ØÒ
ÆÓÖÑ´ÊÓÒ×½µ · ÊÓÒ×¾
The following types of normalization are available:
’center’: The region is moved so that both regions have the save center of gravity.
HALCON 6.0

486 CHAPTER 9. REGIONS
If both regions are empty Similarity is set to 0. The regions with the same index from both input parameters
are always compared.
Attention
In both input parameters the same number of regions must be passed.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions.
º Norm (input control) ...........................................string(-array) (Htuple .) const char *
Type of normalization.
Default Value : ’center’
Value List : Norm ¾’center’
º Distance (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Hamming distance of two regions.
Assertion : Distance 0
º Similarity (output control) .......................................real(-array) (Htuple .) double *
Similarity of two regions.
Assertion : ´0 Similarityµ ´Similarity 1µ
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
hamming distance norm returns the value H MSG TRUE if the number of objects in both parameters is the same
and is not 0. The behavior in case of empty input (no input objects available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )hamming distance norm is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
intersection, complement, (T )area center
hamming change region
Region processing
See Also
Module
inner circle ( Hobject Regions, double *Row, double *Column,
double *Radius )
T inner circle ( Hobject Regions, Htuple *Row, Htuple *Column,
Htuple *Radius )
Largest inner circle of a region.
The operator (T )inner circle determines the largest inner circle of a region, i.e. the circle with the largest
area of all circles that fit into the region. For this circle the center (Row,Column) and the radius (Radius) are
calculated. The output of the procedure is chosen in such a way that it can be used as input for the HALCONprocedures
disp circle and (T )gen circle.
If several regions are passed in Regions corresponding tuples are returned as output parameters. In case of empty
region all parameters have the value 0.0 if no other behavior was set (see set system).
Attention
If several inner circles are present at a region only one solution is returned.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 487
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Row (output control) .......................................circle.center.y(-array) (Htuple .) double *
Line index of the center.
º Column (output control) ...................................circle.center.x(-array) (Htuple .) double *
Column index of the center.
º Radius (output control) ....................................circle.radius(-array) (Htuple .) double *
Radius of the inner circle.
Assertion : Radius 0
Example
read_image(&Image,"fabrik");
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
regiongrowing(Image,&Seg,5,5,6.0,100);
select_shape(Seg,&H,"area","and",100.0,2000.0);
T_inner_circle(H,&Row,&Column,&Radius);
T_gen_circle(&Circles,Row,Column,Radius);
set_draw(WindowHandle,"margin");
disp_region(Circles,WindowHandle);
Complexity
If is the area of the region and Ê is the radius of the inner circle the runtime complexity is Ç´Ô
£ ʵ.
Result
The operator (T )inner circle returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )inner circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
(T )gen circle, disp circle
erosion circle
Possible Successor Functions
Alternatives
See Also
set shape, (T )select shape, (T )smallest circle
Region processing
Module
moments region 2nd ( Hobject Regions, double *M11, double *M20,
double *M02, double *Ia, double *Ib )
T moments region 2nd ( Hobject Regions, Htuple *M11, Htuple *M20,
Htuple *M02, Htuple *Ia, Htuple *Ib )
Geometric moments of regions.
The operator (T )moments region 2nd calculates the moments (M20, M02) and the product of inertia of the
axes through the center parallel to the coordinate axes (M11). Furthermore the main axes of inertia (Ia, Ib) are
calculated.
HALCON 6.0

488 CHAPTER 9. REGIONS
Calculation: ¼ and Ë ¼ are the coordinates of the center of a region Ê with the area . Then the moments Å
are defined by:
Å ´ ¼ µ ´Ë ¼ ˵
´Ëµ¾Ê
wherein and Ë run through all pixels of the region Ê.
Furthermore,
Å ¾¼ · Å ¼¾
¾
then Ia and Ib are defined by:
Ô
Á ·
¾
Å ¾¼ £ Å ¼¾ · Å ½½ ¾
Á
Ô
¾
Å ¾¼ £ Å ¼¾ · Å ½½ ¾
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º M11 (output control) ................................................real(-array) (Htuple .) double *
Product of inertia of the axes through the center parallel to the coordinate axes.
º M20 (output control) ................................................real(-array) (Htuple .) double *
Moment of 2nd order (line-dependent).
º M02 (output control) ................................................real(-array) (Htuple .) double *
Moment of 2nd order (column-dependent).
º Ia (output control) ..................................................real(-array) (Htuple .) double *
The one main axis of inertia.
º Ib (output control) ..................................................real(-array) (Htuple .) double *
The other main axis of inertia.
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region 2nd returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (region is the empty set) is set
via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region 2nd is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd invar
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region 2nd invar ( Hobject Regions, double *M11, double *M20,
double *M02 )
T moments region 2nd invar ( Hobject Regions, Htuple *M11, Htuple *M20,
Htuple *M02 )
Geometric moments of regions.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 489
The operator (T )moments region 2nd invar calculates the scaled moments (M20, M02)andtheprocutof
inertia of the axes through the center parallel to the coordinate axes (M11).
Calculation: ¼ and Ë ¼ are the coordinates of the center of a region Ê with the area . Then the moments Å
are defined by:
Å
½ ´ ¼ µ ´Ë ¼ ˵
¾
´Ëµ¾Ê
wherein and Ë run through all pixels of the region Ê.
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º M11 (output control) ................................................real(-array) (Htuple .) double *
Product of inertia of the axes through the center parallel to the coordinate axes.
º M20 (output control) ................................................real(-array) (Htuple .) double *
Moment of 2nd order (line-dependent).
º M02 (output control) ................................................real(-array) (Htuple .) double *
Moment of 2nd order (column-dependent).
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region 2nd invar returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region 2nd invar is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region 2nd rel invar ( Hobject Regions, double *PHI1,
double *PHI2 )
T moments region 2nd rel invar ( Hobject Regions, Htuple *PHI1,
Htuple *PHI2 )
Geometric moments of regions.
The operator (T )moments region 2nd rel invar calculates the scaled relative moments (PHI1, PHI2).
Calculation: The moments ÈÀÁ ½ and ÈÀÁ ¾ are defined by:
ÈÀÁ ½ Î ¾¼ · Î ¼¾
ÈÀÁ ¾ ´Î ¾¼ · Î ¼¾ µ ¾ · Î ¾
½½
HALCON 6.0

490 CHAPTER 9. REGIONS
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º PHI1 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
º PHI2 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
Result
The operator (T )moments region 2nd rel invar returns the value H MSG TRUE if the input is not
empty. The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region 2nd rel invar is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region 3rd ( Hobject Regions, double *M21, double *M12,
double *M03, double *M30 )
T moments region 3rd ( Hobject Regions, Htuple *M21, Htuple *M12,
Htuple *M03, Htuple *M30 )
Geometric moments of regions.
The operator (T )moments region 3rd calculates the translation-invariant central moments (M21, M12, M03,
M30)oforder´Ô · Õµ.
Calculation: Ü and Ý are the coordinates of the center of a region Ê with the area . Then the moments Å ÔÕ are
defined by:
Å ÔÕ Å´Ü Ý µ´Ü ܵ Ô´Ý Ýµ Õ
wherein are Ü Ñ½¼
Ñ ¼¼
and Ý Ñ¼½
Ñ ¼¼
.
½
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º M21 (output control) ................................................real(-array) (Htuple .) double *
oment of 3nd order (line-dependent).
º M12 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (column-dependent).
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 491
º M03 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (column-dependent).
º M30 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (line-dependent).
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region 3rd returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region 3rd is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region 3rd invar ( Hobject Regions, double *M21, double *M12,
double *M03, double *M30 )
T moments region 3rd invar ( Hobject Regions, Htuple *M21, Htuple *M12,
Htuple *M03, Htuple *M30 )
Geometric moments of regions.
The operator (T )moments region 3rd invar calculates the scale-invariant moments (M21, M12, M03,
M30).
Calculation: Then the moments Å are defined by:
wobei Ô · Õ¾und ¼¼ Ñ ¼¼ sind.
wherein are Ô · Õ¾and ¼¼ Ñ ¼¼ .
Å ÔÕ ÔÕ
¿
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º M21 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (line-dependent).
º M12 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (column-dependent).
º M03 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (column-dependent).
º M30 (output control) ................................................real(-array) (Htuple .) double *
Moment of 3nd order (line-dependent).
HALCON 6.0

492 CHAPTER 9. REGIONS
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region 3rd invar returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region 3rd invar is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region central ( Hobject Regions, double *I1, double *I2,
double *I3, double *I4 )
T moments region central ( Hobject Regions, Htuple *I1, Htuple *I2,
Htuple *I3, Htuple *I4 )
Geometric moments of regions.
The operator (T )moments region central calculates the central moments (I1, I2, I3, I4).
Calculation: Then the moments Á are defined by: Á ½ ¾¼ ¼¾ ¾ ½½
Á ¾ ´ ¿¼ ¼¿ ¾½ ½¾ µ ¾ ´ ¿¼ ½¾ ¾ ¾½ µ´ ¾½ ¼¿ ¾ ½¾ µ
Á ¿ ¾¼´ ¾½ ¼¿ ¾ ½¾ µ ½½´ ¿¼ ¼¿ ¾½ ½¾ µ· ¼¾´ ¿¼ ½¾ ¾ ¾½ µ
Á ¾ ¿¼ ¿ ¼¾ ¿¼ ¾½ ½½ ¾ · ¼¾ ¿¼ ½¾ ¼¾´¾ ¾ ½½ ¾¼ ¼¾ µ
· ¿¼ ¼¿´ ¾¼ ½½ ¼¾ ¿ ½½ µ·¾ ¾½ ¾¼ ¾ ¼¾ ½ ¾½ ½¾ ¾¼ ½½ ¼¾
· ¾½ ¼¿ ¾¼´¾ ¾ ½½ ¾¼ ¼¾ µ· ¾ ½¾ ¾ ¾¼ ¼¾ ½¾ ¼¿ ½½ ¾ ¾¼ · ¾ ¼¿ ¿ ¾¼
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º I1 (output control) ..................................................real(-array) (Htuple .) double *
Moment of 2nd order.
º I2 (output control) ..................................................real(-array) (Htuple .) double *
Moment of 2nd order.
º I3 (output control) ..................................................real(-array) (Htuple .) double *
Moment of 2nd order.
º I4 (output control) ..................................................real(-array) (Htuple .) double *
Moment of 3nd order.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 493
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region central returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region central is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
moments region central invar ( Hobject Regions, double *PSI1,
double *PSI2, double *PSI3, double *PSI4 )
T moments region central invar ( Hobject Regions, Htuple *PSI1,
Htuple *PSI2, Htuple *PSI3, Htuple *PSI4 )
Geometric moments of regions.
The operator (T )moments region central invar calculates the moments (PSI1, PSI2, PSI3, PSI4)
that are invariant under translation and general linear transformations.
Calculation: Then the moments are defined by: ½ Á½
¾
Á¾
½ ¼
¿ Á¿
Á
½ ½
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º PSI1 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
º PSI2 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
º PSI3 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
º PSI4 (output control) ...............................................real(-array) (Htuple .) double *
Moment of 2nd order.
HALCON 6.0

494 CHAPTER 9. REGIONS
Complexity
If is the area of the region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )moments region central invar returns the value H MSG TRUE if the input is not
empty. The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )moments region central invar is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )moments region 2nd
(T )elliptic axis
Region processing
Alternatives
See Also
Module
orientation region ( Hobject Regions, double *Phi )
T orientation region ( Hobject Regions, Htuple *Phi )
Orientation of a region.
The operator (T )orientation region calculates the orientation of the region. The operator is based on
(T )elliptic axis. In addition the point on the contour with maximal distance to the center of gravity is
calculated. If the column coordinate of this point is less than the column coordinate of the center of gravity the
value of is added to the angle.
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system
(’no object result’,)).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Phi (output control) ................................................real(-array) (Htuple .) double *
Orientation of region (arc measure).
Assertion : ´´ pi2µ Phiµ ´Phi ´´3 ¡ piµ2µµ
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )orientation region returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )orientation region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
disp arrow
Possible Successor Functions
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 495
Alternatives
(T )elliptic axis, (T )smallest rectangle2
See Also
(T )moments region 2nd, line orientation
Region processing
Module
roundness ( Hobject Regions, double *Distance, double *Sigma,
double *Roundness, double *Sides )
T roundness ( Hobject Regions, Htuple *Distance, Htuple *Sigma,
Htuple *Roundness, Htuple *Sides )
Shape factors from contour.
The operator (T )roundness examines the distance between the contour and the center of the area. In particular
the mean distance (Distance), the deviation from the mean distance (Sigma) and two shape features derived
therefrom are determined. Roundness is the relation between mean value and standard deviation, and Sides
indicates the number of polygon pieces if a regular polygon is concerned.
The contour for calculating the features is determined depending on the global neighborhood (see set system).
Calculation:
If Ô is the center of the area, Ô the pixels and the area of the contour.
×ØÒ ½
Ô Ô
ËÑ ¾ ½
´Ô Ô ×ØÒµ ¾
ËÑ
ÊÓÙÒÒ×× ½
×ØÒ
×ØÒ
Ë× ½½½½
ËÑ
¼¾
If more than one region is passed the results are stored in tuples, the index of a value in the tuple corresponding to
the index of a region in the input.
In case of empty region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Distance (output control) .........................................real(-array) (Htuple .) double *
Mean distance from the center.
Assertion : Distance 0.0
º Sigma (output control) .............................................real(-array) (Htuple .) double *
Standard deviation of Distance.
Assertion : Sigma 0.0
º Roundness (output control) ........................................real(-array) (Htuple .) double *
Shape factor for roundness.
Assertion : Roundness 1.0
º Sides (output control) .............................................real(-array) (Htuple .) double *
Number of polygon sides.
Assertion : Sides 0
Complexity
If is the area of a region the mean runtime complexity is Ç´Ô
µ.
Result
The operator (T )roundness returns the value H MSG TRUE if the input is not empty. The
HALCON 6.0

496 CHAPTER 9. REGIONS
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )roundness is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )compactness
(T )contlength
Alternatives
See Also
Bibliography
R. Haralick, L. Shapiro “Computer and Robot Vision” Addison-Wesley, 1992, pp. 61
Region processing
Module
T runlength distribution ( Hobject Region, Htuple *Foreground,
Htuple *Background )
Distribution of runs needed for runlength encoding of a region.
The operator T runlength distribution calculates the distribution of the runs of a region of the fore- and
background. The frequency of the occurrence of a certain length is calculated. Runs of infinite length are not
counted. Therefore the background are the holes of the region. As many values are passed as set by the maximum
length of fore- or background, respectively. The length of both tuples usually differs. The first entry of the tuples is
always 0 (no runs of the length 0). If there are no blanks the empty tuple is passed at Background. Analogously
the empty tuple is passed in case of an empty region at Foreground.
Parameter
º Region (input object) .............................................................region Hobject
Region to be examined.
º Foreground (output control) .........................................integer-array Htuple . long *
Length distribution of the region (foreground).
º Background (output control) .........................................integer-array Htuple . long *
Length distribution of the background.
Complexity
If Ò is the number of runs of the region the runtime complexity is Ç´Òµ.
Result
The operator T runlength distribution returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). If more than one region is passed an exception handling is raised.
Parallelization Information
T runlength distribution is reentrant and processed without parallelization.
threshold, select obj
(T )runlength features
(T )runlength features
Region processing
Possible Predecessor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 497
runlength features ( Hobject Regions, long *NumRuns, double *KFactor,
double *LFactor, double *MeanLength, long *Bytes )
T runlength features ( Hobject Regions, Htuple *NumRuns,
Htuple *KFactor, Htuple *LFactor, Htuple *MeanLength, Htuple *Bytes )
Characteristic values for runlength coding of regions.
The operator (T )runlength features calculates for every input region from Regions the number of
runs necessary for storing this region with the aid of runlength coding. Furthermore the so-called ”‘K-factor”’ is
determined, which indicates by how much the number of runs differs from the ideal of the square in which this
value is 1.0.
The K-factor (KFactor) is calculated according to the formula:
ÃØÓÖ ÆÙÑÊÙÒ× Ô
Ö
wherein Ö indicates the area of the region. It should be noted that the K-factor can be smaller than 1.0 (in case
of long horizontal regions).
The L-factor (LFactor) indicates the mean number of runs for each line index occurring in the region.
MeanLength indicates the mean length of the runs. The parameter Bytes indicates how many bytes are necessary
for coding the region with runlengths.
Attention
All features calculated by the operator (T )runlength features are not rotation invariant because the runlength
coding depends on the direction. The operator (T )runlength features does not serve for calculating
shape features but for controlling and analysing the efficiency of the runlength coding.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º NumRuns (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Number of runs.
Assertion : 0 NumRuns
º KFactor (output control) ...........................................real(-array) (Htuple .) double *
Storing factor in relation to a square.
Assertion : 0 KFactor
º LFactor (output control) ...........................................real(-array) (Htuple .) double *
Mean number of runs per line.
Assertion : 0 LFactor
º MeanLength (output control) .......................................real(-array) (Htuple .) double *
Mean length of runs.
Assertion : 0 MeanLength
º Bytes (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Number of bytes necessary for coding the region.
Assertion : 0 Bytes
Complexity
The mean runtime complexity is Ç´½µ.
Result
The operator (T )runlength features returns the value H MSG TRUE if the input is not empty. If necessary
an exception handling is raised.
Parallelization Information
(T )runlength features is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
See Also
(T )runlength features, T runlength distribution
Region processing
Module
HALCON 6.0

498 CHAPTER 9. REGIONS
select region point ( Hobject Regions, Hobject *DestRegions, long Row,
long Column )
Choose all regions containing a given pixel.
The operator select region point selects alle regions from Regions containing the test pixel
(Row,Column), i.e.:
ÊÓÒ×Ò℄ ´ÊÓÛ ÓÐÙÑÒµ ½
Attention
If the regions overlap more than one region might contain the pixel. In this case all these regions are returned. If
no region contains the indicated pixel the empty tuple (= no region) is returned.
Parameter
º Regions (input object) ......................................................region-array Hobject
Regions to be examined.
º DestRegions (output object) ..............................................region-array Hobject *
All regions containing the test pixel.
º Row (input control) ...................................................................point.y long
Line index of the test pixel.
Default Value : 100
Typical Range of Values : ½ Row ½(lin)
º Column (input control) ...............................................................point.x long
Column index of the test pixel.
Default Value : 100
Typical Range of Values : ½ Column ½(lin)
Example
read_image(&Image,"fabrik");
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
disp_image(Image);
regiongrowing(Image,&Seg,3,3,5.0,0);
set_color(WindowHandle,"red");
set_draw(WindowHandle,"margin");
do {
printf("Select the region with the mouse (End right buttonn \n");
get_mbutton(WindowHandle,&Row,&Column,&Button);
select_region_point(Seg,&Single,Row,Column);
disp_region(Single,WindowHandle);
clear(Single);
} while(Button != 4);
Complexity
If is the area of the region and Æ is the number of regions, the mean runtime complexity is Ç´ÐÒ´Ô
µ £ Æ µ.
Result
The operator select region point returns the value H MSG TRUE if the parameters are correct.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). If necessary an exception handling is raised.
Parallelization Information
select region point is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
test region point
get mbutton, get mposition
Alternatives
See Also
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 499
Region processing
Module
T select region spatial ( Hobject Regions1, Hobject Regions2,
Htuple Direction, Htuple *RegionIndex1, Htuple *RegionIndex2 )
Pose relation of regions.
The operator T select region spatial chooses the regions from Regions2 which are sufficient for the
neighboring relation Direction. The regions to be examined have to be passed in Regions1 or Regions2,
respectively. Regions1 can have three different states:
¯ Regions1 is empty:
In this case all regions in Regions2 are permutatively checked for neighborhood.
¯ Regions1 consists of one region:
The regions of Regions1 are compared to all regions in Regions2.
¯ Regions1 consists of the same number of regions as Regions2:
The regions at the n-th position in Regions1 and Regions2 are each checked for a neighboring relation.
Possible values for Direction are:
’left’: Regions2 is left of Regions1
’right’: Regions2 is right of Regions1
’above’: Regions2 is above Regions1
’below’: Regions2 is below Regions1
The operator T select region spatial calculates the centers of the regions to be compared and decides
according to the angle between the center straight lines and the x axis whether the direction relation is fulfilled.
The relation is fulfilled within the area of -45 degree to +45 degree around the coordinate axes. Thus, the direction
relation can be understood in such a way that the center of the second region must be located left (or right, above,
below) of the center of the first region. The indices of the regions fulfilling the direction relation are located at the
n-th position in RegionIndex1 and RegionIndex2, i.e. the region with the index RegionIndex2[n] has
the indicated relation with the region with the index RegionIndex1[n]. Access to regions via the index can be
obtained via the operator copy obj.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Starting regions
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions
º Direction (input control) .............................................string Htuple . const char *
Desired neighboring relation.
Default Value : ’left’
Value List : Direction ¾’left’, ’right’, ’above’, ’below’
º RegionIndex1 (output control) ......................................integer-array Htuple . long *
Indices in the input tuples (Regions1 or Regions2), respectively.
º RegionIndex2 (output control) ......................................integer-array Htuple . long *
Indices in the input tuples (Regions1 or Regions2), respectively.
Result
The operator T select region spatial returns the value H MSG TRUE if Regions2 is not empty. The
behavior in case of empty parameter Regions2 (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T select region spatial is reentrant and processed without parallelization.
HALCON 6.0

500 CHAPTER 9. REGIONS
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )area center, intersection
Alternatives
See Also
T spatial relation, T find neighbors, copy obj, obj to integer
Region processing
Module
select shape ( Hobject Regions, Hobject *SelectedRegions,
const char *Features, const char *Operation, double Min, double Max )
T select shape ( Hobject Regions, Hobject *SelectedRegions,
Htuple Features, Htuple Operation, Htuple Min, Htuple Max )
Choose regions with the aid of shape features.
The operator (T )select shape chooses regions according to shape. For each input region from Regions the
indicated features (Features) are calculated. If each (Operation = ’and’) or at least one (Operation = ’or’)
of the calculated features is within the default limits (Min,Max) the region is adapted into the output (duplicated).
Condition: ÅÒ ØÙÖ ´Çص ÅÜ
Possible values for Features:
’area’: Area of the object
’row’: Row index of the center
’column’: Column index of the center
’width’: Width of the region
’height’: Height of the region
’row1’: Row index of upper left corner
’column1’: Column index of upper left corner
’row2’: Row index of lower right corner
’column2’: Column index of lower right corner
’circularity’: Circularity (see (T )circularity)
’compactness’: Compactness (see (T )compactness)
’contlength’: Total length of contour (see operator (T )contlength)
’convexity’: Convexity (see (T )convexity)
’ra’: Main radius of the equivalent ellipse (see (T )elliptic axis)
’rb’: Secondary radius of the equivalent ellipse (see (T )elliptic axis)
’phi’: Orientation of the equivalent ellipse (see (T )elliptic axis)
’anisometry:’ Anisometry (see (T )eccentricity)
’bulkiness:’ Bulkiness (see operator (T )eccentricity)
’struct factor:’ Structur Factor (see operator (T )eccentricity)
’outer radius’: Radius of smallest surrounding circle (see (T )smallest circle)
’inner radius’: Radius of largest inner circle (see (T )inner circle)
’dist mean’: Mean distance from the region border to the center (see operator (T )roundness)
’dist deviation:’ Deviation of the distance from the region border from the center (see operator
(T )roundness)
’roundness’: Roundness (see operator (T )roundness)
’num sides’: Number of polygon sides (see operator (T )roundness)
’connect num’: Number of connection components (see operator (T )connect and holes)
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 501
’holes num’: Number of holes (see operator (T )connect and holes)
’max diameter’: Maximum diameter of the region (see operator (T )diameter region)
’orientation’: Orientation of the region (see operator (T )orientation region)
’euler number’: Euler number (see operator (T )euler number)
’rect2 phi’: Orientation of the smallest surrounding rectangle (see operator (T )smallest rectangle2)
’rect2 len1’: Half the length of the smallest surrounding rectangle (see operator
(T )smallest rectangle2)
’rect2 len2’: Half the width of the smallest surrounding rectangle (see operator (T )smallest rectangle2)
’moments m11’: Geometric moments of the region (see operator (T )moments region 2nd)
’moments m20’: Geometric moments of the region (see operator (T )moments region 2nd)
’moments m02’: Geometric moments of the region (see operator (T )moments region 2nd)
’moments ia’: Geometric moments of the region (see operator (T )moments region 2nd)
’moments ib’: Geometric moments of the region (see operator (T )moments region 2nd)
’moments m11 invar’: Geometric moments of the region (see operator (T )moments region 2nd invar)
’moments m20 invar’: Geometric moments of the region (see operator (T )moments region 2nd invar)
’moments m02 invar’: Geometric moments of the region (see operator (T )moments region 2nd invar)
’moments phi1’: Geometric moments of the region (see operator (T )moments region 2nd rel invar)
’moments phi2’: Geometric moments of the region (see operator (T )moments region 2nd rel invar)
’moments m21’: Geometric moments of the region (see operator (T )moments region 3rd)
’moments m12’: Geometric moments of the region (see operator (T )moments region 3rd)
’moments m03’: Geometric moments of the region (see operator (T )moments region 3rd)
’moments m30’: Geometric moments of the region (see operator (T )moments region 3rd)
’moments m21 invar’: Geometric moments of the region (see operator (T )moments region 3rd invar)
’moments m12 invar’: Geometric moments of the region (see operator (T )moments region 3rd invar)
’moments m03 invar’: Geometric moments of the region (see operator (T )moments region 3rd invar)
’moments m30 invar’: Geometric moments of the region (see operator (T )moments region 3rd invar)
’moments i1’: Geometric moments of the region (see operator (T )moments region central)
’moments i2’: Geometric moments of the region (see operator (T )moments region central)
’moments i3’: Geometric moments of the region (see operator (T )moments region central)
’moments i4’: Geometric moments of the region (see operator (T )moments region central)
’moments psi1’: Geometric moments of the region (see operator (T )moments region central invar)
’moments psi2’: Geometric moments of the region (see operator (T )moments region central invar)
’moments psi3’: Geometric moments of the region (see operator (T )moments region central invar)
’moments psi4’: Geometric moments of the region (see operator (T )moments region central invar)
If only one feature (Features)isusedthevalueofOperation is meaningless. Several features are processed
in the sequence in which they are entered.
Parameter
º Regions (input object) ......................................................region-array Hobject
Regions to be examined.
º SelectedRegions (output object) ........................................region-array Hobject *
Regions fulfilling the condition.
º Features (input control) ......................................string(-array) (Htuple .) const char *
Shape features to be checked.
Default Value : ’area’
Value List : Features ¾’area’, ’row’, ’column’, ’width’, ’height’, ’row1’, ’column1’, ’row2’, ’column2’,
’circularity’, ’compactness’, ’contlength’, ’convexity’, ’ra’, ’rb’, ’phi’, ’anisometry’, ’bulkiness’,
’struct factor’, ’outer radius’, ’inner radius’, ’max diameter’, ’dist mean’, ’dist deviation’, ’roundness’,
HALCON 6.0

502 CHAPTER 9. REGIONS
’num sides’, ’orientation’, ’connect num’, ’holes num’, ’euler number’, ’rect2 phi’, ’rect2 len1’, ’rect2 len2’,
’moments m11’, ’moments m20’, ’moments m02’, ’moments ia’, ’moments ib’, ’moments m11 invar’,
’moments m20 invar’, ’moments m02 invar’, ’moments phi1’, ’moments phi2’, ’moments m21’,
’moments m12’, ’moments m03’, ’moments m30’, ’moments m21 invar’, ’moments m12 invar’,
’moments m03 invar’, ’moments m30 invar’, ’moments i1’, ’moments i2’, ’moments i3’, ’moments i4’,
’moments psi1’, ’moments psi2’, ’moments psi3’, ’moments psi4’
º Operation (input control) ...........................................string (Htuple .) const char *
Linkage type of the individual features.
Default Value : ’and’
Value List : Operation ¾’and’, ’or’
º Min (input control) ................................real(-array) (Htuple .) double / long / const char *
Lower limits of the features or ’min’.
Default Value : 150.0
Typical Range of Values : 0.0 Min 99999.0
Minimal Value Step : 0.001
Recommended Value Step : 1.0
º Max (input control) ................................real(-array) (Htuple .) double / long / const char *
Upper limits of the features or ’max’.
Default Value : 99999.0
Typical Range of Values : 0.0 Max 99999.0
Minimal Value Step : 0.001
Recommended Value Step : 1.0
Restriction : Max Min
Example
/* where are the eyes of the ape ? */
read_image(&Image,"affe");
threshold(Image,&S1,128.0,255.0);
connection(S1,&S2);
select_shape(S2,&S3,"area","and",500.0,50000.0);
select_shape(S3,&Eyes,"anisometry","and",1.0,1.7);
disp_region(Eyes,WindowHandle);
Result
The operator (T )select shape returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input objects available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )select shape is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
Possible Successor Functions
(T )select shape, select gray, shape trans, reduce domain, count obj
See Also
(T )area center, (T )circularity, (T )compactness, (T )contlength, (T )convexity,
(T )elliptic axis, (T )eccentricity, (T )inner circle, (T )smallest circle,
(T )smallest rectangle1, (T )smallest rectangle2, (T )roundness,
(T )connect and holes, (T )diameter region, (T )orientation region,
(T )moments region 2nd, (T )moments region 2nd invar,
(T )moments region 2nd rel invar, (T )moments region 3rd,
(T )moments region 3rd invar, (T )moments region central,
(T )moments region central invar, select obj
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 503
select shape proto ( Hobject Regions, Hobject Pattern,
Hobject *SelectedRegions, const char *Feature, double Min, double Max )
T select shape proto ( Hobject Regions, Hobject Pattern,
Hobject *SelectedRegions, Htuple Feature, Htuple Min, Htuple Max )
Choose regions having a certain relation to each other.
The operator (T )select shape proto puts two regions in relation to each other. Every i-th region from
Regions is compared to the combination of regions from Pattern. The limits (Min and Max) are indicated
absolutely or in percent (0..100) depending on the feature. Possible values for Feature are:
’distance dilate’ The minimum distance in the maximum norm from the edge of Pattern to the edge of every
region from Regions is determined (see distance rr min dil).
’distance contour’ The minimum Euclidean distance from the edge of Pattern to the edge of every region
from Regions is determined. (see distance rr min).
’distance center’ The Euclidean distance from the center of Pattern to the center of every region from
Regions is determined.
’covers’ It is examined how well the region Pattern fits into the regions from Regions. If there is no shift
so that Pattern is a subset of Regions the overlap is 0. If Pattern corresponds to the region after a
corresponding shift the overlap is 100. Otherwise the area of the opening of Regions with Pattern is put
into relation with the area of Regions (in percent).
’fits’ It is examined whether Pattern can be shifted in such a way that it fits in Regions. If this is possible the
corresponding region is copied from Regions. The parameters Min and Max have no meaning here.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Pattern (input object) .....................................................region(-array) Hobject
Region compared to Regions.
º SelectedRegions (output object) .......................................region(-array) Hobject *
Regions fulfilling the condition.
º Feature (input control) .......................................string(-array) (Htuple .) const char *
Shape features to be checked.
Default Value : ’covers’
Value List : Feature ¾’distance center’, ’distance dilate’, ’distance contour’, ’covers’, ’fits’
º Min (input control) ................................................number (Htuple .) double / long
Lower border of feature.
Default Value : 50.0
Value Suggestions : Min ¾0.0, 1.0, 5.0, 10.0, 20.0, 30.0, 50.0, 60.0, 70.0, 80.0, 90.0, 95.0, 99.0, 100.0,
200.0, 400.0
Typical Range of Values : 0.0 Min
Minimal Value Step : 0.001
Recommended Value Step : 5.0
º Max (input control) ................................................number (Htuple .) double / long
Upper border of the feature.
Default Value : 100.0
Value Suggestions : Max ¾0.0, 10.0, 20.0, 30.0, 50.0, 60.0, 70.0, 80.0, 90.0, 95.0, 99.0, 100.0, 200.0, 300.0,
400.0
Typical Range of Values : 0.0 Max
Minimal Value Step : 0.001
Recommended Value Step : 5.0
Example
regiongrowing(Image,&Seg,3,3,5.0,0);
gen_circle(&C,100.0,100.0,MinRadius);
select_shape_proto(Seg,C,"fits",0.0,0.0);
HALCON 6.0

504 CHAPTER 9. REGIONS
Result
The operator (T )select shape proto returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )select shape proto is reentrant and processed without parallelization.
Possible Predecessor Functions
connection, draw region, (T )gen circle, (T )gen rectangle1, (T )gen rectangle2,
(T )gen ellipse
Possible Successor Functions
select gray, shape trans, reduce domain, count obj
(T )select shape
Alternatives
See Also
opening, erosion1, distance rr min dil, distance rr min
Region processing
Module
select shape std ( Hobject Regions, Hobject *SelectedRegions,
const char *Shape, double Percent )
Select regions of a given shape.
The operator select shape std compares the shape of the given regions with default shapes. If the region has
a similar shape it is adopted into the output. Possible values for Shape are:
’max area’ The largest region is selected.
’rectangle1’ The surrounding rectangle parallel to the coordinate axes is determined via the operator
(T )smallest rectangle1. If the area difference in percent is larger than Percent the region is
adopted.
’rectangle1’ The smallest surrounding rectangle with any orientation is determined via the operator
(T )smallest rectangle2. If the area difference in percent is larger than Percent the region is
adopted.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Input regions to be selected.
º SelectedRegions (output object) .......................................region(-array) Hobject *
Regions with desired shape.
º Shape (input control) ..........................................................string const char *
Shape features to be checked.
Default Value : ’max area’
Value List : Shape ¾’max area’, ’rectangle1’, ’rectangle2’
º Percent (input control) ..............................................................real double
Similarity measure.
Default Value : 70.0
Value Suggestions : Percent ¾10.0, 30.0, 50.0, 60.0, 70.0, 80.0, 90.0, 95.0, 100.0
Typical Range of Values : 0.0 Percent 100.0 (lin)
Minimal Value Step : 0.1
Recommended Value Step : 10.0
Parallelization Information
select shape std is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 505
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )smallest rectangle1,
(T )smallest rectangle2
Alternatives
intersection, complement, (T )area center
See Also
(T )smallest rectangle1, (T )smallest rectangle2
Region processing
Module
smallest circle ( Hobject Regions, double *Row, double *Column,
double *Radius )
T smallest circle ( Hobject Regions, Htuple *Row, Htuple *Column,
Htuple *Radius )
Smallest surrounding circle of a region.
The operator (T )smallest circle determines the smallest surrounding circle of a region, i.e. the circle
with the smallest area of all circles containing the region. For this circle the center (Row,Column) and the radius
(Radius) are calculated. The procedure is applied when, for example, the location and size of circular objects
(e.g. coins) which, however, are not homogeneous inside or have broken edges due to bad segmentation, has
to be determined. The output of the procedure is selected in such a way that it can be used as input for the
HALCONprocedures disp circle and (T )gen circle.
If several regions are passed in Regions corresponding tuples are returned as output parameter. In case of empty
region all parameters have the value 0.0 if no other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Row (output control) .......................................circle.center.y(-array) (Htuple .) double *
Line index of the center.
º Column (output control) ...................................circle.center.x(-array) (Htuple .) double *
Column index of the center.
º Radius (output control) ....................................circle.radius(-array) (Htuple .) double *
Radius of the surrounding circle.
Assertion : Radius 0
Example
read_image(&Image,"fabrik");
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
regiongrowing(Image,&Seg,5,5,6.0,100);
select_shape(Seg,&H,"area","and",100.0,2000.0);
T_smallest_circle(H,&Row,&Column,&Radius);
T_gen_circle(&Circles,Row,Column,Radius);
set_draw(WindowHandle,"margin");
disp_region(Circles,WindowHandle);
Complexity
If is the area of the region and Æ is the number of supporting points of the convex hull, the mean runtime
complexity is Ç´Ô
· Æ ¿ µ.
Result
The operator (T )smallest circle returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
HALCON 6.0

506 CHAPTER 9. REGIONS
Parallelization Information
(T )smallest circle is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
(T )gen circle, disp circle
Possible Successor Functions
Alternatives
(T )elliptic axis, (T )smallest rectangle1, (T )smallest rectangle2
See Also
set shape, (T )select shape, (T )inner circle
Region processing
Module
smallest rectangle1 ( Hobject Regions, long *Row1, long *Column1,
long *Row2, long *Column2 )
T smallest rectangle1 ( Hobject Regions, Htuple *Row1, Htuple *Column1,
Htuple *Row2, Htuple *Column2 )
Surrounding rectangle parallel to the coordinate axes.
The operator (T )smallest rectangle1 calculates the surrounding rectangle of all input regions (parallel
to the coordinate axes). The surrounding rectangle is described by the coordinates of the corner pixels
(Row1,Column1,Row2,Column2)
If more than one region is passed in Regions, the results are stored in tuples, the index of a value in the tuple
corresponding to the index of a region in the input. In case of empty region all parameters have the value 0 if no
other behavior was set (see set system).
Attention
In case of empty region the result of Row1,Column1, Row2 and Column2 (all are 0) can lead to confusion.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Row1 (output control) ....................................rectangle.origin.y(-array) (Htuple .) long *
Line index of upper left corner point.
º Column1 (output control) ................................rectangle.origin.x(-array) (Htuple .) long *
Column index of upper left corner point.
º Row2 (output control) ....................................rectangle.corner.y(-array) (Htuple .) long *
Line index of lower right corner point.
º Column2 (output control) ................................rectangle.corner.x(-array) (Htuple .) long *
Column index of lower right corner point.
Complexity
If is the area of the region the mean runtime complexity is Ç´×ÕÖØ´ µµ.
Result
The operator (T )smallest rectangle1 returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )smallest rectangle1 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
Possible Successor Functions
disp rectangle1, (T )gen rectangle1
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 507
Alternatives
(T )smallest rectangle2, (T )area center
(T )select shape
Region processing
See Also
Module
smallest rectangle2 ( Hobject Regions, double *Row, double *Column,
double *Phi, double *Length1, double *Length2 )
T smallest rectangle2 ( Hobject Regions, Htuple *Row, Htuple *Column,
Htuple *Phi, Htuple *Length1, Htuple *Length2 )
Smallest surrounding rectangle with any orientation.
The operator (T )smallest rectangle2 determines the smallest surrounding rectangle of a region, i.e. the
rectangle with the smallest area of all rectangles containing the region. For this rectangle the center, the inclination
and the two radii are calculated.
The procedure is applied when, for example, the location of a scenery of several regions (e.g. printed
text on a rectangular paper or in rectangular print (justified lines)) must be found. The parameters of
(T )smallest rectangle2 are chosen in such a way that they can be used directly as input for the HALCONprocedures
disp rectangle2 and (T )gen rectangle2.
If more than one region is passed in Regions the results are stored in tuples, the index of a value in the tuple
corresponding to the index of a region in the input. In case of empty region all parameters have the value 0.0 if no
other behavior was set (see set system).
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions to be examined.
º Row (output control) ..................................rectangle2.center.y(-array) (Htuple .) double *
Line index of the center.
º Column (output control) ..............................rectangle2.center.x(-array) (Htuple .) double *
Column index of the center.
º Phi (output control) .................................rectangle2.angle.rad(-array) (Htuple .) double *
Orientation of the surrounding rectangle (arc measure)
Assertion : ´´ pi2µ Phiµ ´Phi ´pi2µµ
º Length1 (output control) ..............................rectangle2.hwidth(-array) (Htuple .) double *
First radius (half length) of the surrounding rectangle.
Assertion : Length1 0.0
º Length2 (output control) .............................rectangle2.hheight(-array) (Htuple .) double *
Second radius (half width) of the surrounding rectangle.
Assertion : ´Length2 0.0µ ´Length2 Length1µ
Example
#include
#include
"HalconCpp.h"
int main (int argc, char *argv[])
{
Tuple row, col, phi, len1, len2;
HImage img (argv[1]);
HWindow w;
img.Display (w);
HALCON 6.0

508 CHAPTER 9. REGIONS
HRegionArray reg = img.Regiongrowing (5, 5, 6.0, 100);
HRegionArray seg = reg.SelectShape ("area", "and", 100.0, 1000.0);
row = seg.SmallestRectangle2 (&col, &phi, &len1, &len2);
HRegionArray rect = HRegionArray::GenRectangle2 (row, col, phi, len1, len2);
w.SetDraw ("margin");
w.SetColor ("green"); reg.Display (w);
w.SetColor ("blue"); seg.Display (w);
w.SetColor ("red"); rect.Display (w);
w.Click ();
}
return(0);
Complexity
If is the area of the region and Æ is the number of supporting points of the convex hull, the runtime complexity
is Ç´Ô
· Æ ¾ µ.
Result
The operator (T )smallest rectangle2 returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,). The behavior in case of empty region (the region is the empty set) is
set via set system(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )smallest rectangle2 is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, regiongrowing, connection, (T )runlength features
Possible Successor Functions
disp rectangle2, (T )gen rectangle2
Alternatives
(T )elliptic axis, (T )smallest rectangle1
(T )smallest circle, set shape
Region processing
See Also
Module
T spatial relation ( Hobject Regions1, Hobject Regions2,
Htuple Percent, Htuple *RegionIndex1, Htuple *RegionIndex2,
Htuple *Relation1, Htuple *Relation2 )
Pose relation of regions with regard to the coordinate axes.
The operator T spatial relation selects regions located by Percent percent “left”, “right”, “above” or
“below” other regions. Regions1 and Regions2 contain the regions to be compared. Regions1 can have
three states:
¯ Regions1 is empty:
In this case all regions in Regions2 are permutatively checked for neighborhood.
¯ Regions1 consists of one region:
The regions of Regions1 are compared to all regions in Regions2.
¯ Regions1 consists of the same number of regions as Regions2:
Regions1 and Regions2 are checked for a neighboring relation.
The percentage Percent is interpreted in such a way that the area of the second region has to be located really
left/right or above/below the region margins of the first region by at least Percent percent. The indices of
HALCON/C Reference Manual / 2000-11-15

9.4. FEATURES 509
the regions that fulfill at least one of these conditions are then located at the n-th position in the output parameters
RegionIndex1 and RegionIndex2. Additionally the output parameters Relation1 and Relation2
contain at the n-th position the type of relation of the region pair (RegionIndex1[n], RegionIndex2[n]),
i.e. region with index RegionIndex2[n] has the relation Relation1[n] and Relation2[n] with region with
index RegionIndex1[n].
Possible values for Relation1 and Relation2 are:
Relation1: ’left’, ’right’ or ”
Relation2: ’above’, ’below’ or ”
In RegionIndex1 and RegionIndex2 the indices of the regions in the tuples of the input regions (Regions1
or Regions2), respectively, are entered as image identifiers. Access to chosen regions via the index can be
obtained by the operator copy obj.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Starting regions.
º Regions2 (input object) ...................................................region(-array) Hobject
Comparative regions.
º Percent (input control) .....................................................integer Htuple . long
Percentage of the area of the comparative region which must be located left/right or above/below the region
margins of the starting region.
Default Value : 50
Value Suggestions : Percent ¾0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100
Typical Range of Values : 0 Percent 100 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´0 Percentµ ´Percent 100µ
º RegionIndex1 (output control) ......................................integer-array Htuple . long *
Indices of the regions in the tuple of the input regions which fulfill the pose relation.
º RegionIndex2 (output control) ......................................integer-array Htuple . long *
Indices of the regions in the tuple of the input regions which fulfill the pose relation.
º Relation1 (output control) ............................................string-array Htuple . char *
Horizontal pose relation in which RegionIndex2[n] stands with RegionIndex1[n].
º Relation2 (output control) ............................................string-array Htuple . char *
Vertical pose relation in which RegionIndex2[n] stands with RegionIndex1[n].
Result
The operator T spatial relation returns the value H MSG TRUE if Regions2 is not empty and Percent
is correctly choosen. The behavior in case of empty parameter Regions2 (no input regions available) is set via
the operator set system(’no object result’,). The behavior in case of empty region (the
region is the empty set) is set via set system(’empty region result’,). If necessary an
exception handling is raised.
Parallelization Information
T spatial relation is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
(T )area center, intersection
Alternatives
See Also
T select region spatial, T find neighbors, copy obj, obj to integer
Region processing
Module
test region point ( Hobject Regions, long Row, long Column )
Test if the region consists of the given point.
HALCON 6.0

510 CHAPTER 9. REGIONS
test region point tests if at least one input region of Regions consists of the test point (Row,Column).
Attention
In case of empty input (= no region) and set system(’no object result’,’true’) FALSE is returned
(no region contains the pixel).
The test pixel is not contained in an empty region (no pixel of the region corresponds to the pixel). If all regions
are empty FALSE is also returned, i.e. an empty region behaves as if it did not exist.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Region(s) to be examined.
º Row (input control) ...................................................................point.y long
Line index of the test pixel.
Default Value : 100
Typical Range of Values : 0 Row 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Column (input control) ...............................................................point.x long
Column index of the test pixel.
Default Value : 100
Typical Range of Values : 0 Column 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
If is the area of one region and Æ is the number of regions, the runtime complexity is Ç´ÐÒ´Ô
µ £ Æ µ.
Result
The operator test region point returns the value H MSG TRUE if a region contains the test pixel. If this
is not the case test region point returns H MSG FALSE. The behavior in case of empty input (no input
regions available) is set via the operator set system(’no object result’,). If necessary an
exception handling is raised.
Parallelization Information
test region point is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
union1, intersection, (T )area center
select region point
bool
Region processing
See Also
Return Value
Module
9.5 Sets
complement ( Hobject Region, Hobject *RegionComplement )
Return the complement of a region.
complement determines the complement of the input region(s).
If the system flag ’clip region’ is ’false’ (see set system) the complement is done virtually by setting the
complement flag of Region to TRUE. For succeeding operations the de Morgan laws are applied while calculating
results.
HALCON/C Reference Manual / 2000-11-15

9.5. SETS 511
If the system flag ’clip region’ is ’true’ the difference of the largest image processed so far (see reset obj db)
and the input region is returned.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Input region(s).
º RegionComplement (output object) .....................................region(-array) Hobject *
Complemented regions.
Parameter Number : RegionComplement Region
Result
complement always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,) and the behavior in case of an empty input
region via set system(’empty region result’,). If necessary, an exception handling is
raised.
Parallelization Information
complement is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring, class ndim norm
(T )select shape
Possible Successor Functions
See Also
difference, union1, union2, intersection, reset obj db, set system
Region processing
Module
difference ( Hobject Region, Hobject Sub, Hobject *RegionDifference )
Calculate the difference of two regions.
difference calculates the set-theoretic difference of two regions:
(Regions in Region) (Regions in Sub)
The resulting region is defined as the input region (Region) with all points from Sub removed. The following
two special regions can also be used as input:
’full’ i.e., the full region (FULL REGION in HALCON/C) or
’empty’ i.e., the empty region (EMPTY REGION in HALCON/C).
Attention
Empty regions are valid for both parameters. On output, empty regions may resultṪhe value of the system flag
’store empty region’ determines the behavior in this case.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be processed.
º Sub (input object) ..........................................................region(-array) Hobject
The union of these regions is subtracted from Region.
º RegionDifference (output object) .....................................region(-array) Hobject *
Resulting region.
Example
/* provides the region X without the points in Y */
difference(X,Y,&RegionDifference);
/* provides the region. */
difference(Region,EMPTY_REGION,&RegionDifference);
HALCON 6.0

512 CHAPTER 9. REGIONS
Complexity
Let Æ be the number of regions, ½ be their average area, and ¾ be the total area of all regions in Sub. Then the
runtime complexity is Ç´ ½ £ ÐÓ´ ½ µ·Æ £ ´Ô
½ · Ô
¾ µµ.
Result
difference always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,) and the behavior in case of an empty input
region via set system(’empty region result’,). If necessary, an exception handling is
raised.
Parallelization Information
difference is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring, class ndim norm
(T )select shape, disp region
Possible Successor Functions
See Also
intersection, union1, union2, complement
Region processing
Module
intersection ( Hobject Region1, Hobject Region2,
Hobject *RegionIntersection )
Calculate the intersection of two regions.
intersection calculates the intersection of the regions in Region1 with the regions in Region2. Each
region in Region1 is intersected with all regions in Region2. The order of regions in RegionIntersection
is identical to the order of regions in Region1.
Attention
Empty input regions are permitted. Because empty result regions are possible, the system flag
’store empty region’ should be set appropriately.
Parameter
º Region1 (input object) .....................................................region(-array) Hobject
Regions to be intersected with all regions in Region2.
º Region2 (input object) .....................................................region(-array) Hobject
Regions with which Region1 is intersected.
º RegionIntersection (output object) ...................................region(-array) Hobject *
Result of the intersection.
Parameter Number : RegionIntersection Region1
Complexity
Let Æ be the number of regions in Region1, ½ be their average area, and ¾ be the total area of all regions in
Region2. Then the runtime complexity is Ç´ ½ ÐÓ ´ ½ µ·Æ £ ´Ô
½ · Ô
¾ µµ.
Result
intersection always returns H MSG TRUE. The behavior in case of empty input (no regions given) can be
set via set system(’no object result’,) and the behavior in case of an empty input region
via set system(’empty region result’,). If necessary, an exception handling is raised.
Parallelization Information
intersection is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
union1, union2, complement
Possible Successor Functions
See Also
HALCON/C Reference Manual / 2000-11-15

9.5. SETS 513
Region processing
Module
union1 ( Hobject Region, Hobject *RegionUnion )
Return the union of all input regions.
union1 computes the union of all input regions and returns the result in RegionUnion.
Parameter
º Region (input object) .......................................................region-array Hobject
Regions of which the union is to be computed.
º RegionUnion (output object) ...................................................region Hobject *
Union of all input regions.
Parameter Number : RegionUnion Region
Example
/* Union of segmentation results: */
threshold(Image,&Seg1,128.0,255.0);
dyn_threshold(Image,Mean,&Seg2,5.0,"light");
concat_obj(Seg1,Seg2,&H);
union1(H,&Seg);
Complexity
Let be the sum of all areas of the input regions. Then the runtime complexity is Ç´ÐÓ´Ô
µ £
Ô
µ.
Result
union1 always returns H MSG TRUE. The behavior in case of empty input (no regions given) can be set via
set system(’no object result’,) and the behavior in case of an empty input region via
set system(’empty region result’,). If necessary, an exception handling is raised.
Parallelization Information
union1 is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
union2
intersection, complement
Region processing
Possible Successor Functions
Alternatives
See Also
Module
union2 ( Hobject Region1, Hobject Region2, Hobject *RegionUnion )
Return the union of two regions.
union2 computes the union of the region in Region1 with all regions in Region2. This means that union2
is not commutative!
Parameter
º Region1 (input object) .....................................................region(-array) Hobject
Region for which the union with all regions in Region2 is to be computed.
º Region2 (input object) .....................................................region(-array) Hobject
Regions which should be added to Region1.
HALCON 6.0

514 CHAPTER 9. REGIONS
º RegionUnion (output object) ............................................region(-array) Hobject *
Resulting regions.
Parameter Number : RegionUnion Region1
Complexity
Let be the sum of all areas of the input regions. Then the runtime complexity is Ç´ÐÓ´Ô
µ £
Ô
µ.
Result
union2 always returns H MSG TRUE. The behavior in case of empty input (no regions given) can be set via
set system(’no object result’,) and the behavior in case of an empty input region via
set system(’empty region result’,). If necessary, an exception handling is raised.
Parallelization Information
union2 is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
union1
intersection, complement
Region processing
Possible Successor Functions
Alternatives
See Also
Module
9.6 Transformation
background seg ( Hobject Foreground, Hobject *BackgroundRegions )
Determine the connected components of the background of given regions.
background seg determines connected components of the background of the foreground regions given in
Foreground. This operator is normally used after an edge operator in order to determine the regions enclosed
by the extracted edges. The connected components are determined using 4-connectivity.
Parameter
º Foreground (input object) .................................................region(-array) Hobject
Input regions.
º BackgroundRegions (output object) ......................................region-array Hobject *
Connected components of the background.
Example
/* Segmentation with edge filter: */
read_image(&Image,"fabrik") ;
sobel_dir(Image,&Sobel,&Dir,"sum_sqrt",3) ;
threshold(Sobel,&Edges,20,255) ;
skeleton(Edges,&Margins) ;
background_seg(Margins,&Regions) ;
Complexity
Let be the area of the background, À and Ï be the height and width of the image, and Æ be the number of
resulting regions. Then the runtime complexity is Ç´À ·
Ô
£
Ô
Ƶ.
Result
background seg always returns the value H MSG TRUE. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,) and the behavior in case of an empty
input region via set system(’empty region result’,). If necessary, an exception handling
is raised.
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 515
Parallelization Information
background seg is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring, class ndim norm
(T )select shape
complement, connection
Possible Successor Functions
Alternatives
See Also
threshold, hysteresis threshold, skeleton, expand region, set system, sobel amp,
edges image, roberts, bandpass image
Region processing
Module
clip region ( Hobject Region, Hobject *RegionClipped, long Row1,
long Column1, long Row2, long Column2 )
Clip a region to a rectangle.
clip region clips the input regions to the rectangle given by the four control parameters. clip region is
more efficient than calling intersection with a rectangle generated by (T )gen rectangle1.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be clipped.
º RegionClipped (output object) ..........................................region(-array) Hobject *
Clipped regions.
º Row1 (input control) ........................................................rectangle.origin.y long
Row coordinate of the upper left corner of the rectangle.
Default Value : 0
Value Suggestions : Row1 ¾0, 128, 200, 256
Typical Range of Values : ½ Row1 ½(lin)
º Column1 (input control) ....................................................rectangle.origin.x long
Column coordinate of the upper left corner of the rectangle.
Default Value : 0
Value Suggestions : Column1 ¾0, 128, 200, 256
Typical Range of Values : ½ Column1 ½(lin)
º Row2 (input control) .......................................................rectangle.corner.y long
Row coordinate of the lower right corner of the rectangle.
Default Value : 256
Value Suggestions : Row2 ¾128, 200, 256, 512
Typical Range of Values : 0 Row2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Column2 (input control) ...................................................rectangle.corner.x long
Column coordinate of the lower right corner of the rectangle.
Default Value : 256
Value Suggestions : Column2 ¾128, 200, 256, 512
Typical Range of Values : 0 Column2 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Result
clip region returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
HALCON 6.0

516 CHAPTER 9. REGIONS
Parallelization Information
clip region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
Possible Successor Functions
Alternatives
intersection, (T )gen rectangle1, clip region rel
Region processing
Module
clip region rel ( Hobject Region, Hobject *RegionClipped, long Top,
long Bottom, long Left, long Right )
Clip a region relative to its size.
clip region rel clips a region to a rectangle lying within the region. The size of the rectangle is determined
by the enclosing rectangle of the region, which is reduced by the values given in the four control parameters. All
four parameters must contain numbers larger or equal to zero, and determine by which amount the rectangle is
reduced at the top (Top), at the bottom (Bottom), at the left (Left), and at the right (Right). If all parameters
are set to zero, the region remains unchanged.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be clipped.
º RegionClipped (output object) ..........................................region(-array) Hobject *
Clipped regions.
º Top (input control) ...................................................................integer long
Number of rows clipped at the top.
Default Value : 1
Value Suggestions : Top ¾0, 1, 2, 3, 4, 5, 7, 10, 20, 30, 50
Typical Range of Values : 0 Top (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Bottom (input control) ...............................................................integer long
Number of rows clipped at the bottom.
Default Value : 1
Value Suggestions : Bottom ¾0, 1, 2, 3, 4, 5, 7, 10, 20, 30, 50
Typical Range of Values : 0 Bottom (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Left (input control) .................................................................integer long
Number of columns clipped at the left.
Default Value : 1
Value Suggestions : Left ¾0, 1, 2, 3, 4, 5, 7, 10, 20, 30, 50
Typical Range of Values : 0 Left (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Right (input control) ................................................................integer long
Number of columns clipped at the right.
Default Value : 1
Value Suggestions : Right ¾0, 1, 2, 3, 4, 5, 7, 10, 20, 30, 50
Typical Range of Values : 0 Right (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 517
Result
clip region rel returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
Parallelization Information
clip region rel is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
Possible Successor Functions
Alternatives
(T )smallest rectangle1, intersection, (T )gen rectangle1, clip region
Region processing
Module
connection ( Hobject Region, Hobject *ConnectedRegions )
Compute connected components of a region.
connection determines the connected components of the input regions given in Region. The neighborhood
used for this can be set via set system(’neighborhood’,) The default is 8-neighborhood, which
is useful for determining the connected components of the foreground. The inverse operator of connection is
union1.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Input region.
º ConnectedRegions (output object) .......................................region-array Hobject *
Connected components.
Example
read_image(&Image,"affe");
set_colored(WindowHandle,12);
threshold(Image,&Light,150.0,255.0);
count_obj(Light,&Number1);
printf("Nummber of regions after threshold = %d\n",Number1);
disp_region(Light,WindowHandle);
connection(Light,&Many);
count_obj(Many,&Number2);
printf("Nummber of regions after threshold = %d\n",Number2);
disp_region(Many,WindowHandle);
Complexity
Let be the areaÔ of theÔinput region and Æ be the number of generated connected components. Then the runtime
complexity is Ç´ £ Æ µ.
Result
connection always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,) and the behavior in case of an empty input
region via set system(’empty region result’,). If necessary, an exception handling is
raised.
Parallelization Information
connection is reentrant and processed without parallelization.
Possible Predecessor Functions
auto threshold, threshold, dyn threshold, erosion1
HALCON 6.0

518 CHAPTER 9. REGIONS
Possible Successor Functions
(T )select shape, select gray, shape trans, set colored, dilation1, count obj,
reduce domain, add channels
background seg
set system, union1
Region processing
Alternatives
See Also
Module
crop domain rel ( Hobject Image, Hobject *ImagePart, long Top,
long Bottom, long Left, long Right )
Cut out an image area relative to the domain.
crop domain rel cuts a rectangular area from the input images. The area is determined by the surrounding
rectangle of the domain of the input image. The rectangle can be influenced by the control parameters to modify
at the top (Top), at the bottom (Bottom), at the left (Left), and at the right (Right). Positive values results in
a smaller, negative values in a larger size. If all parameters are set to zero, the region remains unchanged. The new
image matrix has the size of a rectangle.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
Input image.
º ImagePart (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject *
Image area.
º Top (input control) ...................................................................integer long
Number of rows clipped at the top.
Default Value : -1
Value Suggestions : Top ¾-20, -10, -5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 20
º Bottom (input control) ...............................................................integer long
Number of rows clipped at the bottom.
Default Value : -1
Value Suggestions : Bottom ¾-20, -10, -5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 20
º Left (input control) .................................................................integer long
Number of columns clipped at the left.
Default Value : -1
Value Suggestions : Left ¾-20, -10, -5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 20
º Right (input control) ................................................................integer long
Number of columns clipped at the right.
Default Value : -1
Value Suggestions : Right ¾-20, -10, -5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 20
Result
crop domain rel returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
Parallelization Information
crop domain rel is reentrant and automatically parallelized (on tuple level, channel level).
Possible Predecessor Functions
reduce domain, threshold, connection, regiongrowing, pouring
crop domain, crop rectangle1
Alternatives
See Also
(T )smallest rectangle1, intersection, (T )gen rectangle1, clip region
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 519
Image / region / XLD management
Module
distance transform ( Hobject Region, Hobject *DistanceImage,
const char *Metric, const char *Foreground, long Width, long Height )
Compute the distance transformation of a region.
distance transform computes for every point of the input region Region (or its complement, respectively)
the distance of the point to the border of the region. The parameter Foreground determines whether the distances
are calculated for all points within the region (Foreground = ’true’) or for all points outside the region
(Foreground = ’false’). The distance is computed for every point of the output image DistanceImage,
which has the specified dimensions Width and Height. The input region is always clipped to the extent of
the output image. If it is important that the distances within the entire region should be computed, the region
should be moved (see move region) so that it has only positive coordinates and the width and height of the
output image should be large enough to contain the region. The extent of the input region can be obtained with
(T )smallest rectangle1.
The parameter Metric determines which metric is used for the calculation of the distances. If Metric = ’cityblock’,
the distance is calculated from the shortest path from the point to the border of the region, where only
horizontal and vertical “movements” are allowed. They are weighted with a distance of 1. If Metric = ’chessboard’,
the distance is calculated from the shortest path to the border, where horizontal, vertical, and diagonal
“movements” are allowed. They are weighted with a distance of 1. If Metric = ’octagonal’, a combination of
these approaches is used, which leads to diagonal paths getting a higher weight. If Metric = ’chamfer-3-4’,
horizontal and vertical movements are weighted with a weight of 3, while diagonal movements are weighted with
a weight of 4. To normalize the distances, the resulting distance image is divided by 3. Since this normalization
step takes some time, and one usually is interested in the relative distances of the points, the normalization can
be suppressed with Metric = ’chamfer-3-4-unnormalized’. Finally, if Metric = ’euclidean’, the computed
distance is approximately Euclidean.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region for which the distance to the border is computed.
º DistanceImage (output object) ...........................................image Hobject * :int4
Image containing the distance information.
º Metric (input control) .........................................................string const char *
Type of metric to be used for the distance transformation.
Default Value : ”city-block”
Value List : Metric ¾”city-block”, ”chessboard”, ”octagonal”, ”chamfer-3-4”,
”chamfer-3-4-unnormalized”, ”euclidean”
º Foreground (input control) ...................................................string const char *
Compute the distance for pixels inside (true) or outside (false) the input region.
Default Value : ’true’
Value List : Foreground ¾’true’, ’false’
º Width (input control) ...............................................................extent.x long
Width of the output image.
Default Value : 640
Value Suggestions : Width ¾160, 192, 320, 384, 640, 768
Typical Range of Values : 1 Width
º Height (input control) ..............................................................extent.y long
Height of the output image.
Default Value : 480
Value Suggestions : Height ¾120, 144, 240, 288, 480, 576
Typical Range of Values : 1 Height
Example
/* Step towards extracting the medial axis of a shape: */
gen_rectangle1 (Rectangle1, 0, 0, 200, 400)
HALCON 6.0

520 CHAPTER 9. REGIONS
gen_rectangle1 (Rectangle2, 200, 0, 400, 200)
union2 (Rectangle1, Rectangle2, Shape)
distance_transform (Shape, DistanceImage, ’chessboard’, ’true’, 640, 480)
The runtime complexity is Ç´ÏØ £ Àص.
Complexity
Result
distance transform returns H MSG H MSG TRUE if all parameters are correct.
Parallelization Information
distance transform is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, dyn threshold, regiongrowing
threshold
skeleton
Possible Successor Functions
See Also
Bibliography
P. Soille: “Morphological Image Analysis, Principles and Applications”; Springer Verlag Berlin Heidelberg New
York, 1999.
G. Borgefors: “Distance Transformations in Arbitrary Dimensions”; Computer Vision, Graphics, and Image Processing,
Vol. 27, pages 321–345, 1984.
P.E. Danielsson: “Euclidean Distance Mapping”; Computer Graphics and Image Processing, Vol. 14, pages 227–
248, 1980.
Module
Region processing
eliminate runs ( Hobject Region, Hobject *RegionClipped,
long ElimShorter, long ElimLonger )
Eliminate runs of a given length.
eliminate runs eliminates all runs of the run length encoding of the input regions which are shorter than
ElimShorter or longer as ElimLonger.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be clipped.
º RegionClipped (output object) ..........................................region(-array) Hobject *
Clipped regions.
º ElimShorter (input control) ........................................................integer long
All runs which are shorter are eliminated.
Default Value : 3
Value Suggestions : ElimShorter ¾2, 3, 4, 5, 6, 8, 10, 12, 15
Typical Range of Values : 1 ElimShorter 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º ElimLonger (input control) .........................................................integer long
All runs which are longer are eliminated.
Default Value : 1000
Value Suggestions : ElimLonger ¾50, 100, 200, 500, 1000, 2000
Typical Range of Values : 1 ElimLonger 10000 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 521
Result
eliminate runs returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
Parallelization Information
eliminate runs is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
Possible Successor Functions
erosion1, dilation1, disp region
shape trans
Region processing
Alternatives
Module
expand region ( Hobject Regions, Hobject ForbiddenArea,
Hobject *RegionExpanded, long Iterations, const char *Mode )
Fill gaps between regions or split overlapping regions.
expand region closes gaps between the input regions, which resulted from the suppression of small regions in
a segmentation operator, for example, (mode ’image’), or to separate overlapping regions (mode ’region’). Both
uses result from the expansion of regions. The operator works by adding or removing a one pixel wide “strip” to a
region.
The expansion takes place only in regions, which are designated as not “forbidden” (parameter
ForbiddenArea). The number of iterations is determined by the parameter Iterations. By passing ’maximal’,
expand region iterates until convergence, i.e., until no more changes occur. By passing 0 for this parameter,
all non-overlapping regions are returned. The two modes of operation (’image’ and ’region’) are different in
the following ways:
’image’ The input regions are expanded iteratively until they touch another region or the image border. Because
expand region processes all regions simultaneously, gaps between regions are distributed evenly to all
regions. Overlapping regions are split by distributing the area of overlap evenly to both regions.
’region’ No expansion of the input regions is performed. Instead, only overlapping regions are split by distributing
the area of overlap evenly to the respective regions. Because the intersection with the original region is
computed after the shrinking operation gaps in the output regions may result, i.e., the segmentation is not
complete. This can be prevented by calling expand region a second time with the complement of the
original regions as “forbidden area.”
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions for which the gaps are to be closed, or which are to be separated.
º ForbiddenArea (input object) ...................................................region Hobject
Regions in which no expasion takes place.
º RegionExpanded (output object) ........................................region(-array) Hobject *
Expanded or separated regions.
º Iterations (input control) ............................................integer long / const char *
Number of iterations.
Default Value : ’maximal’
Value Suggestions : Iterations ¾’maximal’, 0, 1, 2, 3, 5, 7, 10, 15, 20, 30, 50, 70, 100, 200
Typical Range of Values : 0 Iterations 1000 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON 6.0

522 CHAPTER 9. REGIONS
º Mode (input control) ............................................................string const char *
Expansion mode.
Default Value : ’image’
Value List : Mode ¾’image’, ’region’
Example
read_image(&Image,"fabrik");
threshold(Image,&Light,100.0,255.0);
disp_region(Light,WindowHandle);
connection(Light,&Seg);
expand_region(Seg,EMPTY_REGION,&Exp1,"maximal","image");
set_colored(WindowHandle,12);
set_draw(WindowHandle,"margin");
disp_region(Exp1,WindowHandle);
Result
expand region always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,), the behavior in case of an empty input region
via set system(’empty region result’,), and the behavior in case of an empty result
region via set system(’store empty region’,). If necessary, an exception handling
is raised.
Parallelization Information
expand region is reentrant and processed without parallelization.
Possible Predecessor Functions
pouring, threshold, dyn threshold, regiongrowing
dilation1
expand gray, interjacent, skeleton
Region processing
Alternatives
See Also
Module
fill up ( Hobject Region, Hobject *RegionFillUp )
Fill up holes in regions.
fill up fills up holes in regions. The number of regions remains unchanged. The neighborhood type is set via
set system(’neighborhood’,) (default: 8-neighborhood).
Parameter
º Region (input object) ......................................................region(-array) Hobject
Input regions containing holes.
º RegionFillUp (output object) ...........................................region(-array) Hobject *
Regions without holes.
Result
fill up returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,) and the behavior in case of an empty
input region via set system(’empty region result’,). If necessary, an exception handling
is raised.
Parallelization Information
fill up is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
Possible Successor Functions
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 523
fill up shape
boundary
Region processing
Alternatives
See Also
Module
fill up shape ( Hobject Region, Hobject *RegionFillUp,
const char *Feature, double Min, double Max )
Fill up holes in regions having given shape features.
fill up shape fills up those holes in the input region Region having given shape features. The parameter
Feature determines the shape feature to be used, while Min and Max determine the range the shape feature has
to lie in in order for the hole to be filled up.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Input region(s).
º RegionFillUp (output object) ...........................................region(-array) Hobject *
Output region(s) with filled holes.
º Feature (input control) .......................................................string const char *
Shape feature used.
Default Value : ’area’
Value List : Feature ¾’area’, ’compactness’, ’convexity’, ’anisometry’, ’phi’, ’ra’, ’rb’, ’inner circle’,
’outer circle’
º Min (input control) ..........................................................number double / long
Minimum value for Feature.
Default Value : 1.0
Value Suggestions : Min ¾0.0, 1.0, 10.0, 50.0, 100.0, 500.0, 1000.0, 10000.0
Typical Range of Values : 0.0 Min
º Max (input control) ..........................................................number double / long
Maximum value for Feature.
Default Value : 100.0
Value Suggestions : Max ¾10.0, 50.0, 100.0, 500.0, 1000.0, 10000.0, 100000.0
Typical Range of Values : 0.0 Max
Example
read_image(&Image,"affe");
threshold(Image,&Seg,120.0,255.0);
fill_up_shape(Seg,&Filled,"area",0.0,200.0);
Result
fill up shape returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
Parallelization Information
fill up shape is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
fill up
Possible Successor Functions
Alternatives
HALCON 6.0

524 CHAPTER 9. REGIONS
See Also
(T )select shape, connection, (T )area center
Region processing
Module
hamming change region ( Hobject InputRegion, Hobject *OutputRegion,
long Width, long Height, long Distance )
Generate a region having a given Hamming distance.
hamming change region changes the region in the left upper part of the image given by Width and Height
such that the resulting regions have a Hamming distance of Distance to the input regions. This is done by
adding or removing Distance points from the input region.
Attention
If Width and Height are chosen too large the resulting region requires a lot of memory.
Parameter
º InputRegion (input object) ...............................................region(-array) Hobject
Region to be modified.
º OutputRegion (output object) ...........................................region(-array) Hobject *
Regions having the required Hamming distance.
º Width (input control) ...............................................................extent.x long
Width of the region to be changed.
Default Value : 100
Value Suggestions : Width ¾64, 128, 256, 512
Typical Range of Values : 1 Width 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Width 0
º Height (input control) ..............................................................extent.y long
Height of the region to be changed.
Default Value : 100
Value Suggestions : Height ¾64, 128, 256, 512
Typical Range of Values : 1 Height 512 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Height 0
º Distance (input control) ............................................................integer long
Hamming distance between the old and new regions.
Default Value : 1000
Value Suggestions : Distance ¾100, 500, 1000, 5000, 10000
Typical Range of Values : 0 Distance 10000 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´Distance 0µ ´Distance ´Width ¡ Heightµµ
Complexity
Memory requirement of the generated region (worst case): Ç´¾ £ ÏØ £ Àص.
Result
hamming change region returns H MSG TRUE if all parameters are correct. The behavior in case of empty
input (no regions given) can be set via set system(’no object result’,). If necessary, an
exception handling is raised.
Parallelization Information
hamming change region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
connection, regiongrowing, pouring, class ndim norm
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 525
(T )select shape
(T )hamming distance
Region processing
Possible Successor Functions
See Also
Module
interjacent ( Hobject Region, Hobject *RegionInterjacent,
const char *Mode )
Partition the image plane using given regions.
interjacent partitions the image plane using the regions given in Region. The result is a region containing
the extracted separating lines. The following modes of operation can be used:
’medial axis’ This mode is used for regions that do not touch or overlap. The operator will find separating lines
between the regions which partition the background evenly between the input regions. This corresponds to
the following calls:
complement(’full’,Region,Tmp) skeleton(Tmp,Result)
’border’ If the input regions do not touch or overlap this mode is equivalent to boundary(Region,Result),
i.e., it replaces each region by its boundary. If regions are touching they are aggregated into one region. The
corresponding output region then contains the boundary of the aggregated region, as well as the one pixel
wide separating line between the original regions. This corresponds to the following calls:
boundary(Region,Tmp1,’inner’) union1(Tmp1,Tmp2)
skeleton(Tmp2,Result)
’mixed’ In this mode the operator behaves like the mode ’medial axis’ for non-overlapping regions. If regions
touch or overlap, again separating lines between the input regions are generated on output, but this time
including the “touching line” between regions, i.e., touching regions are separated by a line in the output
region. This corresponds to the following calls:
erosion1(Region,Mask,Tmp1,1) union1(Tmp1,Tmp2)
complement(full,Tmp2,Tmp3) skeleton(Tmp3,Result)
where Mask denotes the following “cross mask”:
¢
¢ ¢ ¢
¢
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions for which the separating lines are to be determined.
º RegionInterjacent (output object) ...........................................region Hobject *
Output region containing the separating lines.
º Mode (input control) ............................................................string const char *
Mode of operation.
Default Value : ’mixed’
Value List : Mode ¾’medial axis’, ’border’, ’mixed’
Example
read_image(&Image,"wald1_rot") ;
mean(Image,&Mean,31,31) ;
dyn_threshold(Mean,&Seg,20) ;
interjacent(Seg,&Graph,"medial_axis") ;
disp_region(Graph,WindowHandle) ;
HALCON 6.0

526 CHAPTER 9. REGIONS
Result
interjacent always returns the value H MSG TRUE. The behavior in case of empty input (no regions given)
can be set via set system(’no object result’,), the behavior in case of an empty input region
via set system(’empty region result’,), and the behavior in case of an empty result
region via set system(’store empty region’,). If necessary, an exception handling
is raised.
Parallelization Information
interjacent is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring
(T )select shape, disp region
Possible Successor Functions
See Also
expand region, junctions skeleton, boundary
Region processing
Module
junctions skeleton ( Hobject Region, Hobject *EndPoints,
Hobject *JuncPoints )
Find junctions and end points in a skeleton.
junctions skeleton detects junctions and end points in a skeleton (see skeleton). The junctions in the
input region Region are output as a region in JuncPoints, while the end points are output as a region in
EndPoints.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Input skeletons.
º EndPoints (output object) ...............................................region(-array) Hobject *
Extracted end points.
Parameter Number : EndPoints Region
º JuncPoints (output object) ..............................................region(-array) Hobject *
Extracted junctions.
Parameter Number : JuncPoints Region
Example
/* non-connected branches of a skeleton */
skeleton(Region,&Skeleton) ;
junctions_skeleton(Skeleton,&EPoints,&JPoints) ;
difference(S,JPoints,&Rows) ;
connection(Rows,&Parts) ;
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ µ.
Result
junctions skeleton always returns the value H MSG TRUE. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,), the behavior in case of an
empty input region via set system(’empty region result’,), and the behavior in case of
an empty result region via set system(’store empty region’,). If necessary, an exception
handling is raised.
Parallelization Information
junctions skeleton is reentrant and automatically parallelized (on tuple level).
skeleton
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 527
Possible Successor Functions
(T )area center, connection, T get region points, difference
pruning, split skeleton region
Region processing
See Also
Module
merge regions line scan ( Hobject CurrRegions, Hobject PrevRegions,
Hobject *CurrMergedRegions, Hobject *PrevMergedRegions, long ImageHeight,
const char *MergeBorder, long MaxImagesRegion )
Merge regions from line scan images.
The operator merge regions line scan connects adjacent regions, which were segmentated from adjacent
images with the height ImageHeight. This operator was especially designed to process regions that were extracted
from images grabbed by a line scan camera. CurrRegions contains the regions from the current image
and PrevRegions the regions from the previous one.
With the help of the parameter MergeBorder two cases can be distinguished: If the top (first) line of the current
image touches the bottom (last) line of the previous image, MergeBorder must be set to ’top’, otherwise set
MergeBorder to ’bottom’.
If the operator merge regions line scan is used recursivly, the parameter MaxImagesRegion determines
the maximum number of images which are covered by a merged region. All older region parts are removed.
The operator merge regions line scan returns two region arrays. PrevMergedRegions contains all
those regions from the previous input regions PrevRegions, which could not be merged with a current
region. CurrMergedRegions collects all current regions together with the merged parts from the previous
images. Merged regions will exceed the original image, because the previous regions are moved upward
(MergeBorder=’top’) ordownward(MergeBorder=’bottom’) according to the image height. For this the
system parameter ’clip region’ (see also set system) will internaly be set to ’false’.
Parameter
º CurrRegions (input object) ...............................................region(-array) Hobject
Current input regions.
º PrevRegions (input object) ...............................................region(-array) Hobject
Merged regions from the previous iteration.
º CurrMergedRegions (output object) ....................................region(-array) Hobject *
Current regions, merged with old ones where applicable.
º PrevMergedRegions (output object) ....................................region(-array) Hobject *
Regions from the previous iteration which could not be merged with the current ones.
º ImageHeight (input control) ........................................................integer long
Height of the line scan images.
Default Value : 512
Value List : ImageHeight ¾240, 480, 512
º MergeBorder (input control) ..................................................string const char *
Image line of the current image, which touches the previous image.
Default Value : ”top”
Value List : MergeBorder ¾”top”, ”bottom”
º MaxImagesRegion (input control) ..................................................integer long
Maximum number of images for a single region.
Default Value : 3
Value Suggestions : MaxImagesRegion ¾1, 2, 3, 4, 5
Result
The operator merge regions line scan returns the value H MSG TRUE if the given parameters are correct.
Otherwise, an exception will be raised.
Parallelization Information
merge regions line scan is reentrant and processed without parallelization.
HALCON 6.0

528 CHAPTER 9. REGIONS
Region processing
Module
partition dynamic ( Hobject Region, Hobject *Partitioned,
double Distance, double Percent )
Partition a region horizontally into rectangles.
partition dynamic partitions the input region into rectangles having an average width of Distance. The
region is not split exactly into Ò parts, but rather starting from the calculated splitting point positions having a
minimum number of set pixels in the vertical directions are extracted. The search area is at most plus/minus the
width of a rectangle. If Percent is passed as 100, this search area is used fully. If it is passed as 0, no search is
done.
If the region is smaller than the given size its output remains unchanged. A partition is only done if the size of the
region is at least 1.5 times the size of the rectangle given by the parameters.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be partitioned.
º Partitioned (output object) ..............................................region-array Hobject *
Partitioned region.
º Distance (input control) .............................................................real double
Width of the individual rectangles.
º Percent (input control) ..............................................................real double
Maximum shift of the partition point.
Default Value : 20
Value Suggestions : Percent ¾0, 10, 20, 30, 40, 50, 70, 90, 100
Typical Range of Values : 0 Percent 100
Result
partition dynamic returns H MSG TRUE if all parameters are correct. The behavior in case of empty input
(no regions given) can be set via set system(’no object result’,), the behavior in case of
an empty input region via set system(’empty region result’,), and the behavior in case
of an empty result region via set system(’store empty region’,). If necessary, an
exception handling is raised.
Parallelization Information
partition dynamic is reentrant and automatically parallelized (on tuple level).
threshold, connection
partition rectangle
Possible Predecessor Functions
Alternatives
See Also
intersection, (T )smallest rectangle1, shape trans, clip region
Region processing
Module
partition rectangle ( Hobject Region, Hobject *Partitioned,
double Width, double Height )
Partition a region into rectangles of equal size.
partition rectangle partitions the input region into rectangles having an extent of Width times Height.
The region is always split into rectangles of equal size. Therefore, Width and Height are adapted to the actual
size of the region. If the region is smaller than the given size its output remains unchanged. A partition is only
done if the size of the region is at least 1.5 times the size of the rectangle given by the paramters.
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 529
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be partitioned.
º Partitioned (output object) ............................................region(-array) Hobject *
Partitioned region.
º Width (input control) .................................................................real double
Width of the individual rectangles.
º Height (input control) ...............................................................real double
Height of the individual rectangles.
Result
partition rectangle returns H MSG TRUE if all parameters are correct. The behavior in case of empty input
(no regions given) can be set via set system(’no object result’,), the behavior in case
of an empty input region via set system(’empty region result’,), and the behavior in
case of an empty result region via set system(’store empty region’,). If necessary,
an exception handling is raised.
Parallelization Information
partition rectangle is reentrant and automatically parallelized (on tuple level).
threshold, connection
partition dynamic
Possible Predecessor Functions
Alternatives
See Also
intersection, (T )smallest rectangle1, shape trans, clip region
Region processing
Module
rank region ( Hobject Region, Hobject *RegionCount, long Width,
long Height, long Number )
Rank operator for regions.
rank region calculates the binary rank operator. A filter mask of size Height x Width) isused. Inthe
process, for each point in the region the number of points of Region lying within the filter mask are counted. If
this number is greater or equal to Number, the current point is added to the output region. If
is chosen, the median operator is obtained.
ÀØ £ ÏØ
ÆÙÑÖ
¾
Attention
For Height and Width only odd values 3 are valid. If invalid parameters are chosen they are converted
automatically (without raising an exception handling) to the next larger even values.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region(s) to be transformed.
º RegionCount (output object) ............................................region(-array) Hobject *
Resulting region(s).
º Width (input control) ...............................................................extent.x long
Width of the filter mask.
Default Value : 15
Value Suggestions : Width ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21
Typical Range of Values : 3 Width 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Width 3µ odd´Widthµ
HALCON 6.0

530 CHAPTER 9. REGIONS
º Height (input control) ..............................................................extent.y long
Height of the filter mask.
Default Value : 15
Value Suggestions : Height ¾3, 5, 7, 9, 11, 13, 15, 17, 19, 21
Typical Range of Values : 3 Height 511 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Height 3µ odd´Heightµ
º Number (input control) ...............................................................integer long
Minimum number of points lying within the filter mask.
Default Value : 70
Value Suggestions : Number ¾5, 10, 20, 40, 60, 80, 90, 120, 150, 200
Typical Range of Values : 1 Number 1000 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : Number 0
read_image(&Image,"affe") ;
mean_image(Image,&Mean,5,5) ;
dyn_threshold(Mean,&Points,25) ;
rank_region(Points,Textur,15,15,30) ;
gen_circle(&Mask,10,10,3) ;
opening1(Textur,Mask,&Seg) ;
Example
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ £ µ.
Result
rank region returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,) and the behavior in case of
an empty input region via set system(’empty region result’,). If necessary, an exception
handling is raised.
Parallelization Information
rank region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
threshold, connection, regiongrowing, pouring, class ndim norm
(T )select shape, disp region
closing rectangle1, expand region
rank image, mean image
Region processing
Possible Successor Functions
Alternatives
See Also
Module
remove noise region ( Hobject InputRegion, Hobject *OutputRegion,
const char *Type )
Remove noise from a region.
remove noise region removes noise from a region. In mode ’n 4’, a structuring element consisting of the
four neighbors of a point is generated. A dilation with this structuring element is performed, and the intersection
of the result and the input region is calculated. Thus all pixels having no 4-connected neighbor are removed.
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 531
Parameter
º InputRegion (input object) ...............................................region(-array) Hobject
Regions to be modified.
º OutputRegion (output object) ...........................................region(-array) Hobject *
Less noisy regions.
º Type (input control) ............................................................string const char *
Mode of noise removal.
Default Value : ’n 4’
Value List : Type ¾’n 4’, ’n 8’, ’n 48’
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´Ô
£ µ.
Result
remove noise region returns H MSG TRUE if all parameters are correct. The behavior in case of empty
input (no regions given) can be set via set system(’no object result’,). If necessary, an
exception handling is raised.
Parallelization Information
remove noise region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
connection, regiongrowing, pouring, class ndim norm
(T )select shape
Possible Successor Functions
See Also
dilation1, intersection, (T )gen region points
Region processing
Module
shape trans ( Hobject Region, Hobject *RegionTrans, const char *Type )
Transform the shape of a region.
shape trans transforms the shape of the input regions depending on the parameter Type:
’convex’ Convex hull.
’ellipse’ Ellipse with the same moments and area as the input region.
’outer circle’ Smallest enclosing circle.
’inner circle’ Largest circle fitting into the region.
’rectangle1’ Smallest enclosing rectangle parallel to the coordinate axes.
’rectangle2’ Smallest enclosing rectangle.
’inner center’ The point on the skeleton of the input region having the smallest distance to the center of gravity
of the input region.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be transformed.
º RegionTrans (output object) ............................................region(-array) Hobject *
Transformed regions.
º Type (input control) ............................................................string const char *
Type of transformation.
Default Value : ’convex’
Value List : Type ¾’convex’, ’ellipse’, ’outer circle’, ’inner circle’, ’rectangle1’, ’rectangle2’,
’inner center’
HALCON 6.0

532 CHAPTER 9. REGIONS
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ µ.
Result
shape trans returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,). If necessary, an exception
handling is raised.
Parallelization Information
shape trans is reentrant and automatically parallelized (on tuple level).
connection, regiongrowing
Possible Predecessor Functions
Possible Successor Functions
disp region, regiongrowing mean, (T )area center
See Also
(T )convexity, (T )elliptic axis, (T )area center, (T )smallest rectangle1,
(T )smallest rectangle2, set shape, (T )select shape, (T )inner circle
Region processing
Module
skeleton ( Hobject Region, Hobject *Skeleton )
Compute the skeleton of a region.
skeleton computes the skeleton of the input regions.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Region to be thinned.
º Skeleton (output object) ................................................region(-array) Hobject *
Resulting skeleton.
Parameter Number : Skeleton Region
Complexity
Let be the area of the enclosing rectangle of the input region. Then the runtime complexity is Ç´ µ (per region).
Result
skeleton returns H MSG TRUE if all parameters are correct. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,) and the behavior in case of an empty
input region via set system(’empty region result’,). If necessary, an exception handling
is raised.
Parallelization Information
skeleton is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
sobel amp, edges image, bandpass image, threshold, hysteresis threshold
junctions skeleton, pruning
morph skeleton, thinning
Possible Successor Functions
Alternatives
See Also
gray skeleton, sobel amp, edges image, roberts, bandpass image, threshold
Bibliography
Eckardt, U. “Verd”unnung mit Perfekten Punkten”, Proceedings 10. DAGM-Symposium, IFB 180, Zurich, 1988
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 533
sort region ( Hobject Regions, Hobject *SortedRegions,
const char *SortMode, const char *Order, const char *RowOrCol )
Sorting of regions with respect to their relative position.
The operator sort region sorts the regions with respect to their relative position. All sorting methods with the
exception of ’character’ use one point of the region. With the help of the parameter RowOrCol = ’row’ these
points will be sorted according to their row and then according to their columnḂy using ’column’, thecolumn
value will be used first. The following values are available for the parameter SortMode:
’character’ The regions will be treated like characters in a row and will be sorted according to their order in the
line: If two regions overlap horizontally, they will be sorted with respect to their column values, otherwise
they will be sorted with regard to their row values.
’first point’ The point with the lowest column value in the first row of the region.
’last point’ The point with the highest column value in the last row of the region.
’upper left’ Upper left corner of the surrounding rectangle.
’upper right’ Upper right corner of the surrounding rectangle.
’lower left’ Lower left corner of the surrounding rectangle.
’lower right’ Lower right corner of the surrounding rectangle.
The parameter Order determines whether the sorting order is increasing or decreasing: using ’true’ the order will
be increasing, using ’false’ the order will be decreasing.
Parameter
º Regions (input object) ......................................................region-array Hobject
Regions to be sorted.
º SortedRegions (output object) ...........................................region-array Hobject *
Sorted regions.
º SortMode (input control) ......................................................string const char *
Kind of sorting.
Default Value : ’first point’
Value List : SortMode ¾’character’, ’first point’, ’last point’, ’upper left’, ’lower left’, ’upper right’,
’lower right’
º Order (input control) ..........................................................string const char *
Increasing or decreasing sorting order.
Default Value : ’true’
Value List : Order ¾’true’, ’false’
º RowOrCol (input control) ......................................................string const char *
Sorting first with respect to row, then to column.
Default Value : ’row’
Value List : RowOrCol ¾’row’, ’column’
Result
If the parameters are correct, the operator sort region returns the value H MSG TRUE. Otherwise an exception
will be raised.
Parallelization Information
sort region is reentrant and processed without parallelization.
do ocr multi, do ocr single
Region processing
Possible Successor Functions
Module
T split skeleton lines ( Hobject SkeletonRegion, Htuple MaxDistance,
Htuple *BeginRow, Htuple *BeginCol, Htuple *EndRow, Htuple *EndCol )
Split lines represented by one pixel wide, non-branching lines.
HALCON 6.0

534 CHAPTER 9. REGIONS
T split skeleton lines splits lines represented by one pixel wide, non-branching regions into shorter lines
based on their curvature. A line is split if the maximum distance of a point on the line to the line segment
connecting its end points is larger than MaxDistance (split & merge algorithm). The start and end points of
the approximating line segments are returned in BeginRow, BeginCol, EndRow,andEndCol.
Attention
The input regions must represent non-branching lines, that is single branches of the skeleton.
Parameter
º SkeletonRegion (input object) .............................................region-array Hobject
Input lines (represented by 1 pixel wide, non-branching regions).
º MaxDistance (input control) ................................................integer Htuple . long
Maximum distance of the line points to the line segment connecting both end points.
Default Value : 3
Value Suggestions : MaxDistance ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Typical Range of Values : 1 MaxDistance 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º BeginRow (output control) .......................................line.begin.y-array Htuple . long *
Row coordinates of the start points of the output lines.
º BeginCol (output control) .......................................line.begin.x-array Htuple . long *
Column coordinates of the start points of the output lines.
º EndRow (output control) ............................................line.end.y-array Htuple . long *
Row coordinates of the end points of the output lines.
º EndCol (output control) ............................................line.end.x-array Htuple . long *
Column coordinates of the end points of the output lines.
Example
read_image(&Image,"fabrik");
edges_image (Image, &ImaAmp, &ImaDir, "lanser2", 0.5, "nms", 8, 16);
threshold (ImaAmp, &RawEdges, 8, 255);
skeleton (RawEdges, &Skeleton);
junctions_skeleton (Skeleton, &EndPoints, &JuncPoints);
difference (Skeleton, JuncPoints, &SkelWithoutJunc);
connection (SkelWithoutJunc, &SingleBranches);
select_shape (SingleBranches, &SelectedBranches, "area", "and", 16, 99999);
split_skeleton_lines (SelectedBranches, 3, &BeginRow, &BeginCol, &EndRow,
&EndCol);
Result
T split skeleton lines always returns the value H MSG TRUE. The behavior in case of empty input
(no regions given) can be set via set system(’no object result’,), the behavior in case of
an empty input region via set system(’empty region result’,), and the behavior in case
of an empty result region via set system(’store empty region’,). If necessary, an
exception handling is raised.
Parallelization Information
T split skeleton lines is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
connection, (T )select shape, skeleton, junctions skeleton, difference
Possible Successor Functions
select lines, partition lines, disp line
See Also
split skeleton region, detect edge segments
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

9.6. TRANSFORMATION 535
split skeleton region ( Hobject SkeletonRegion, Hobject *RegionLines,
long MaxDistance )
Split lines represented by one pixel wide, non-branching regions.
split skeleton region splits lines represented by one pixel wide, non-branching regions into shorter lines
based on their curvature. A line is split if the maximum distance of a point on the line to the line segment connecting
its end points is larger than MaxDistance (split & merge algorithm). However, not the approximating lines are
returned, but rather the original lines split into several output regions.
Attention
The input regions must represent non-branching lines, that is single branches of the skeleton.
Parameter
º SkeletonRegion (input object) ...........................................region(-array) Hobject
Input lines (represented by 1 pixel wide, non-branching regions).
º RegionLines (output object) ..............................................region-array Hobject *
Split lines.
º MaxDistance (input control) ........................................................integer long
Maximum distance of the line points to the line segment connecting both end points.
Default Value : 3
Value Suggestions : MaxDistance ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Typical Range of Values : 1 MaxDistance 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Example
read_image(&Image,"fabrik");
edges_image (Image, &ImaAmp, &ImaDir, "lanser2", 0.5, "nms", 8, 16);
threshold (ImaAmp, &RawEdges, 8, 255);
skeleton (RawEdges, &Skeleton);
junctions_skeleton (Skeleton, &EndPoints, &JuncPoints);
difference (Skeleton, JuncPoints, &SkelWithoutJunc);
connection (SkelWithoutJunc, &SingleBranches);
select_shape (SingleBranches, &SelectedBranches, "area", "and", 16, 99999);
split_skeleton_region (SelectedBranches, Lines, 3);
Result
split skeleton region always returns the value H MSG TRUE. The behavior in case of empty input (no
regions given) can be set via set system(’no object result’,), the behavior in case of an
empty input region via set system(’empty region result’,), and the behavior in case of
an empty result region via set system(’store empty region’,). If necessary, an exception
handling is raised.
Parallelization Information
split skeleton region is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
connection, (T )select shape, skeleton, junctions skeleton, difference
Possible Successor Functions
count obj, (T )select shape, select obj, (T )area center, (T )elliptic axis,
(T )smallest rectangle2, T get region polygon, T get region contour
See Also
T split skeleton lines, T get region polygon, gen polygons xld
Region processing
Module
HALCON 6.0

536 CHAPTER 9. REGIONS
HALCON/C Reference Manual / 2000-11-15

Chapter 10
Segmentation
auto threshold ( Hobject Image, Hobject *Regions, double Sigma )
Segment an image using thresholds determined from its histogram.
auto threshold segments a single-channel image using multiple thresholding. First the relative histogram of
the gray values is determined. Then relevant minima are extracted from the histogram, which are used successively
as parameters for a thresholding operation. The thresholds used are 0, 255, and all minima extracted from the
histogram (after the histogram has been smoothed). For each gray value interval one region is generated. Thus,
the number of regions is the number of minima + 1. The larger the value of Sigma is chosen, the less regions
will be extracted. This operator is particularly suited if the regions to be extracted exhibit similar gray values
(homogeneous regions).
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be segmented.
º Regions (output object) ...................................................region-array Hobject *
Regions with gray values within the automatically determined intervals.
º Sigma (input control) .......................................................number double / long
Sigma for the Gaussian smoothing of the histogram.
Default Value : 2.0
Value Suggestions : Sigma ¾0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.0 Sigma 100.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.3
Restriction : Sigma 0.0
Example
read_image(&Image,"fabrik");
median_image(Image,&Median,"circle",3);
auto_threshold(Median,&Seg,2.0);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);
connection(Seg,&Connected);
disp_region(Connected,WindowHandle);
Parallelization Information
auto threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
anisotrope diff, median image, illuminate
Possible Successor Functions
connection, select shape, select gray
537

538 CHAPTER 10. SEGMENTATION
Alternatives
gray histo, smooth funct 1d gauss, (T )threshold
Region processing
Module
bin threshold ( Hobject Image, Hobject *Region )
Segment a black-and-white image using an automatically determined threshold.
bin threshold segments a single-channel gray value image using an automatically determined threshold. First
the relative histogram of the gray values is determined. Then relevant minima are extracted from the histogram,
which are used as parameters for a thresholding operation. In order to reduce the number of minima, the histogram
is smoothed with a Gaussian, as in auto threshold. The mask size is enlarged until there is only one minimum
in the smoothed histogram. The selected region contains the pixels with gray values from 0 to the minimum. This
operator is particularly suited for the segmentation of dark characters on a light paper.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be segmented.
º Region (output object) ...................................................region(-array) Hobject *
Dark regions of the image.
read_image(&Image,"letters");
bin_threshold(Image,&Seg);
set_colored(WindowHandle,6);
disp_region(Seg,WindowHandle);
set_shape(WindowHandle,"rectangle1");
connection(Seg,&Connected);
disp_region(Connected,WindowHandle);
Example
Parallelization Information
bin threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
anisotrope diff, median image, illuminate
Possible Successor Functions
connection, select shape, select gray
Alternatives
auto threshold, gray histo, smooth funct 1d gauss, (T )threshold
Region processing
Module
char threshold ( Hobject Image, Hobject HistoRegion,
Hobject *Characters, double Sigma, double Percent, long *Threshold )
T char threshold ( Hobject Image, Hobject HistoRegion,
Hobject *Characters, Htuple Sigma, Htuple Percent, Htuple *Threshold )
Perform a threshold segmentation for extracting characters.
(T )char threshold segments a single-channel image using an automatically determined threshold. It is
assumed that the background of the image is bright and the foreground (the characters) are dark. First a histogram
of the gray values in the image Image is computed in the points given by the region HistoRegion. Then the
maximum in the histogram is computed (most frequently ocuring gray value = bright paper). Finally, the first
HALCON/C Reference Manual / 2000-11-15

539
gray value to the “left” of the maximum is located, which is at least Percent less frequently occuring than the
maximum. In addition a Gaussian smoothing can be applied to suppress gaps in the histogram.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be segmented.
º HistoRegion (input object) ......................................................region Hobject
Region in which the histogram is computed.
º Characters (output object) ..............................................region(-array) Hobject *
Dark regions (characters).
º Sigma (input control) ....................................................number (Htuple .) double
Sigma for the Gaussian smoothing of the histogram.
Default Value : 2.0
Value Suggestions : Sigma ¾0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.0 Sigma 50.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.2
º Percent (input control) ...........................................number (Htuple .) double / long
Percentage for the gray value difference.
Default Value : 95
Value Suggestions : Percent ¾90, 92, 95, 96, 97, 98, 99, 99.5, 100
Typical Range of Values : 0.0 Percent 100.0 (lin)
Minimal Value Step : 0.1
Recommended Value Step : 0.5
º Threshold (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Calculated threshold.
Example
read_image(&Image,"letters");
char_threshold(Median,&Seg,0.0,5.0,&Threshold);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);
set_shape(WindowHandle,"rectangle1");
connection(Seg,&Connected);
disp_region(Connected,WindowHandle);
Parallelization Information
(T )char threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
anisotrope diff, median image, illuminate
Possible Successor Functions
connection, select shape, select gray
Alternatives
bin threshold, auto threshold, gray histo, smooth funct 1d gauss, (T )threshold
Region processing
Module
check difference ( Hobject Image, Hobject Pattern, Hobject *Selected,
const char *Mode, long DiffLowerBound, long DiffUpperBound,
long GrayOffset, long AddRow, long AddCol )
Compare two images pixel by pixel.
check difference selects from the input image Image those pixels ( Ó ÁÑ ), whose
gray value difference to the corresponding pixels in Pattern is inside (outside) of the interval
HALCON 6.0

540 CHAPTER 10. SEGMENTATION
ÄÓÛÖÓÙÒ ÄÓÛÖÓÙÒ℄. The pixels of Pattern are translated by ´ÊÓÛ Óе with respect
to Image. Let Ô be the gray value from Pattern translated by ´ÊÓÛ Óе w.r.t. Ó .
If the selected mode Mode is ’diff inside’, a pixel Ó is selected if
Ó Ô ÖÝÇ×Ø ÄÓÛÖÓÙÒ and
Ó Ô ÖÝÇ×Ø ÍÔÔÖÓÙÒ
If the mode is set to ’diff outside’, a pixel Ó is selected if
Ó Ô ÖÝÇ×Ø ÄÓÛÖÓÙÒ or
Ó Ô ÖÝÇ×Ø ÍÔÔÖÓÙÒ
This test is performed for all points of the domain (region) of Image, intersected with the domain of the translated
Pattern. All points fulfilling the above condition are aggregated in the output region. The two images may be
of different size. Typically, Pattern is smaller than Image.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be examined.
º Pattern (input object) ...............................................image(-array) Hobject : byte
Comparison image.
º Selected (output object) ................................................region(-array) Hobject *
Points in which the two images are similar/different.
º Mode (input control) ............................................................string const char *
Mode: return similar or different pixels.
Default Value : ’diff outside’
Value Suggestions : Mode ¾’diff inside’, ’diff outside’
º DiffLowerBound (input control) ...................................................number long
Lower bound of the tolerated gray value difference.
Default Value : -5
Value Suggestions : DiffLowerBound ¾0, -1, -2, -3, -5, -7, -10, -12, -15, -17, -20, -25, -30
Typical Range of Values : -255 DiffLowerBound 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
Restriction : ´-255 DiffLowerBoundµ ´DiffLowerBound 255µ
º DiffUpperBound (input control) ...................................................number long
Upper bound of the tolerated gray value difference.
Default Value : 5
Value Suggestions : DiffUpperBound ¾0, 1, 2, 3, 5, 7, 10, 12, 15, 17, 20, 25, 30
Typical Range of Values : -255 DiffUpperBound 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
Restriction : ´-255 DiffUpperBoundµ ´DiffUpperBound 255µ
º GrayOffset (input control) .........................................................number long
Offset gray value subtracted from Image.
Default Value : 0
Value Suggestions : GrayOffset ¾-30, -25, -20, -17, -15, -12, -10, -7, -5, -3, -2, -1, 0, 1, 2, 3, 5, 7, 10,
12, 15, 17, 20, 25, 30
Typical Range of Values : -255 GrayOffset 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
Restriction : ´-255 GrayOffsetµ ´GrayOffset 255µ
HALCON/C Reference Manual / 2000-11-15

541
º AddRow (input control) ...............................................................point.y long
Row coordinate, by which Pattern is translated.
Default Value : 0
Value Suggestions : AddRow ¾-200, -100, -20, -10, 0, 10, 20, 100, 200
Typical Range of Values : -32000 AddRow 32000 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º AddCol (input control) ...............................................................point.x long
Column coordinate, by which Pattern is translated.
Default Value : 0
Value Suggestions : AddCol ¾-200, -100, -20, -10, 0, 10, 20, 100, 200
Typical Range of Values : -32000 AddCol 32000 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Complexity
Let be the number of valid pixels. Then the runtime complexity is Ç´ µ.
Result
check difference returns H MSG TRUE if all parameters are correct. The behavior with respect to
the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
check difference is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
connection, select shape, reduce domain, select gray, rank region, dilation1,
opening
Alternatives
sub image, dyn threshold
Region processing
Module
class 2dim sup ( Hobject ImageCol, Hobject ImageRow,
Hobject FeatureSpace, Hobject *RegionClass2Dim )
Segment an image using two-dimensional pixel classification.
class 2dim sup classifies the points in two-channel images using a two-dimensional feature space. For each
point, two gray values (one from each image) are used as features. The feature space is represented by the input
region. The classification is done as follows:
A point from the input region of an image is accepted if the point ´ Ð µ, which is determined by the respective
gray values, is contained in the region FeatureSpace. Ð is here a gray value from the image ImageRow, while
is the corresponding gray value from ImageCol.
Let È be a point with the coordinates È ´Ä µ, Ð be the gray value at position ´Ä µ in the image ImageRow,
and be the gray value at position ´Ä µ in the image ImageCol. Then the point È is aggregated into the output
region if
´ Ð µ ¾ ØÙÖËÔ
Ð is interpreted as row coordinate and as colum coordinate.
For the generation of FeatureSpace,seehisto 2dim. The feature space can be modified by applying region
transformation operators, such as rank region, dilation1, shape trans, elliptic axis, etc., before
calling class 2dim sup.
The parameters ImageCol and ImageRow must contain an equal number of images with the same respective
size. The image points are taken from the intersection of the domains of both images (see reduce domain).
HALCON 6.0

542 CHAPTER 10. SEGMENTATION
Parameter
º ImageCol (input object) .......................image(-array) Hobject : byte / int1 / cyclic / direction
Input image (first channel).
º ImageRow (input object) ..............................................image(-array) Hobject : byte
Input image (second channel).
º FeatureSpace (input object) ..............................................region(-array) Hobject
Region defining the feature space.
º RegionClass2Dim (output object) .......................................region(-array) Hobject *
Classified regions.
Example
read_image(&Image,"combine");
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
disp_image(Image,WindowHandle);
fwrite_string("draw region of interest with the mouse");
fnew_line();
set_color(WindowHandle,"green");
draw_region(&Testreg,draw_region);
/* Texture transformation for 2-dimensional charachteristic */
texture_laws(Image,&T1,"el",2,5);
mean_image(T1,&M1,21,21);
clear_obj(T1);
texture_laws(M1,&T2,"es,",2,5);
mean_image(T2,&M2,21,21);
clear_obj(T2);
/* 2-dimensinal histogram of the test region */
histo_2dim(Testreg,M1,M2,&Histo);
/* All points occuring at least once */
threshold(Histo,&FeatureSpace,1.0,100000.0);
set_draw(WindowHandle,"fill");
set_color(WindowHandle,"red");
disp_region(FeatureSpace,WindowHandle);
fwrite_string("Characteristics area in red");
fnew_line();
/* Segmentation */
class_2dim_sup(M1,M2,FeatureSpace,&RegionClass2Dim);
set_color(WindowHandle,"blue");
disp_region(RegionClass2Dim,WindowHandle);
fwrite_string("Result of classification in blue");
fnew_line();
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´¾ ¾ · µ.
Result
class 2dim sup always returns H MSG TRUE. The behavior with respect to the input images and output
regions can be determined by setting the values of the flags ’no object result’, ’empty region result’, and
’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
class 2dim sup is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
histo 2dim, (T )threshold, draw region, dilation1, opening, shape trans
Possible Successor Functions
connection, select shape, select gray
Alternatives
(T )class ndim norm, class ndim box, (T )threshold, histo 2dim
Region processing
Module
HALCON/C Reference Manual / 2000-11-15

543
class 2dim unsup ( Hobject Image1, Hobject Image2, Hobject *Classes,
long Threshold, long NumClasses )
Segment two images by clustering.
class 2dim unsup performs a classification with two single-channel images. First a two-dimensional histogram
of the two images is computed (histo 2dim). In this histogram the first maximum is extracted; it serves
as the first cluster center. The histogram is computed with the intersection of the domains of both images (see
reduce domain). After this, all pixels in the images, which are at most Threshold pixels from the cluster
center in the maximum norm, are determined. These pixels form one output region. Next, the pixels thus classified
are deleted from the histogram so that they are not taken into account for the next class. In this modified histogram
again the maximum is extracted; it again serves as a cluster center. The above steps are repeated NumClasses
times; thus, NumClasses output regions result. Only pixels defined in both images are returned.
Both input images must have the same size.
Attention
Parameter
º Image1 (input object) .......................................................image Hobject : byte
First input image.
º Image2 (input object) .......................................................image Hobject : byte
Second input image.
º Classes (output object) ...................................................region-array Hobject *
Segmentation result.
º Threshold (input control) ...........................................................integer long
Threshold (maximum distance to the cluster’s center).
Default Value : 15
Value Suggestions : Threshold ¾0, 2, 5, 8, 12, 17, 20, 30, 50, 70
º NumClasses (input control) .........................................................integer long
Number of classes (cluster centers).
Default Value : 5
Value Suggestions : NumClasses ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 20, 30, 40, 50
Example
read_image(&ColorImage,"patras");
decompose3(ColorImage,&Red,&Green,&Blue);
class_2dim_unsup(Red,Green,&Seg,15,5);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);
Result
class 2dim unsup returns H MSG TRUE if all parameters are correct. The behavior with respect to
the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
class 2dim unsup is reentrant and processed without parallelization.
Possible Predecessor Functions
decompose2, decompose3, median image, anisotrope diff, reduce domain
Possible Successor Functions
select shape, select gray, connection
Alternatives
(T )threshold, histo 2dim, class 2dim sup, (T )class ndim norm, class ndim box
Region processing
Module
HALCON 6.0

544 CHAPTER 10. SEGMENTATION
class ndim box ( Hobject MultiChannelImage, Hobject *Regions,
long ClassifHandle )
Classify pixels using hyper-cuboids.
class ndim box classifies the pixels of the multi-channel image given in MultiChannelImage. Todoso,
the classificator ClassifHandle created with create class box is used. The classificator can be trained
using class ndim box or as described with create class box. More information on the structure of the
classificator can be found also under that operator.
MultiChannelImage is a multi channel image. Its pixel values are used for the classification.
Parameter
º MultiChannelImage (input object) multichannel-image(-array) Hobject : byte / int1 / int2 / int4 / real
/ direction / cyclic
Multi-channel input image.
º Regions (output object) ...................................................region-array Hobject *
Segmentation result.
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
Example
read_image(&Image,"meer");
disp_image(Image,WindowHandle);
set_color(WindowHandle,"green");
fwrite_string("Draw the foreground");
fnew_line();
draw_region(&Reg1,WindowHandle);
reduce_domain(Image,Reg1,&Foreground);
set_color(WindowHandle,"red");
fwrite_string("Draw background");
fnew_line();
draw_region(&Reg2,WindowHandle);
reduce_domain(Image,Reg2,&Background);
fwrite_string("Start to learn");
fnew_line();
create_classif(&ClassifHandle);
class_ndim_box(Foreground,Background,Image,ClassifHandle);
fwrite_string("start classification");
fnew_line();
class_ndim_box(Image,&Res,ClassifHandle);
set_draw(WindowHandle,"fill");
disp_region(Res,WindowHandle);
free_classif(ClassifHandle);
Complexity
Let Æ be the number of hyper-cuboids and be the area of the input region. Then the runtime complexity is
Ç´Æ £ µ.
Result
class ndim box returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
class ndim box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, T learn class box, median image, compose2, compose3, compose4
(T )class ndim norm, class 2dim sup
Alternatives
HALCON/C Reference Manual / 2000-11-15

545
See Also
class ndim box, descript class box, create class box
Region processing
Module
class ndim norm ( Hobject MultiChannelImage, Hobject *Regions,
const char *Metric, const char *SingleMultiple, double Radius,
double Center )
T class ndim norm ( Hobject MultiChannelImage, Hobject *Regions,
Htuple Metric, Htuple SingleMultiple, Htuple Radius, Htuple Center )
Classify pixels using hyper-spheres or hyper-cubes.
(T )class ndim norm classifies the pixels of the multi-channel image given in MultiChannelImage. The
result is returned in Regions as one region per classification object. The metric used (’euclid’ or ’maximum’)
is determined by Metric. This paramter must be set to the same value used in T learn ndim norm. The
parameter is used to determine whether one region (’single’) or multiple regions (’multiple’) have to be generated
for each cluster. Radius determines the radii or half edge length of the clusters, respectively. Center determines
their centers.
Parameter
º MultiChannelImage (input object) multichannel-image(-array) Hobject : byte / int1 / int2 / int4 / real
Multi-channel input image.
º Regions (output object) ...................................................region-array Hobject *
Segmentation result.
º Metric (input control) ...............................................string (Htuple .) const char *
Metrictobeused.
Default Value : ’euclid’
Value List : Metric ¾’euclid’, ’maximum’
º SingleMultiple (input control) ....................................string (Htuple .) const char *
Return one region or one region for each cluster.
Default Value : ’single’
Value List : SingleMultiple ¾’single’, ’multiple’
º Radius (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Cluster radii or half edge lengths (returned by T learn ndim norm).
º Center (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Coordinates of the cluster centers (returned by T learn ndim norm).
Example
read_image(&Image,"meer:);
open_window(0,0,-1,-1,0,"visible","",&WindowHandle);
disp_image(Image,WindowHandle);
fwrite_string("draw region of interest with the mouse");
fnew_line();
set_color(WindowHandle,"green");
draw_region(&Testreg,draw_region);
/* Texture transformation for 3-dimensional charachteristic */
texture_laws(Image,&T1,"el",2,5);
mean_image(T1,&M1,21,21);
texture_laws(Image,&T2,"es",2,5);
mean_image(T2,&M2,21,21);
texture_laws(Image,&T3,"le",2,5);
mean_image(T3,&M3,21,21);
compose3(M1,M2,M3,&M);
/* Cluster for 3-dimensional characteristic area determine training area */
create_tuple(&Metric,1);
HALCON 6.0

546 CHAPTER 10. SEGMENTATION
set_s(Metric,"euclid",0);
create_tuple(&Radius,1);
set_d(Radius,20.0,0);
create_tuple(&MinNumber,1);
set_i(MinNumber,5,0);
T_learn_ndim_norm(Testobj,EMPTY_REGION,&M,"euclid",Radius,MinNumber,
&Radius,&Center,_t);
/* Segmentation */
create_tuple(&RegionMode,1);
set_s(RegionMode,"multiple",0);
class_ndim_norm(M,&Regions,Metric,RegionMode,Radius,Center);
set_colored(WindowHandle,12);
disp_region(Regions,WindowHandle);
fwrite_string("Result of classification;");
fwrite_string("Each cluster in another color.");
fnew_line();
Complexity
Let Æ be the number of clusters and be the area of the input region. Then the runtime complexity is Ç´Æ £ µ.
Result
(T )class ndim norm returns H MSG TRUE if all parameters are correct. The behavior with respect to
the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
(T )class ndim norm is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
T learn ndim norm, compose2, compose3, compose4
Possible Successor Functions
connection, select shape, reduce domain, select gray
class ndim box, class 2dim sup
disp circle, disp rectangle1
Region processing
Alternatives
See Also
Module
T detect edge segments ( Hobject Image, Htuple SobelSize,
Htuple MinAmplitude, Htuple MaxDistance, Htuple MinLength,
Htuple *BeginRow, Htuple *BeginCol, Htuple *EndRow, Htuple *EndCol )
Detect straight edge segments.
T detect edge segments detects straight edge segments in the gray image Image. The extracted edge segments
are returned as line segments with start point (BeginRow,BeginCol) and end point (EndRow,EndCol).
Edge detection is based on the Sobel filter, using ’sum abs’ as parameter and SobelSize as the filter mask size
(see sobel amp). Only pixels with a filter response larger than MinAmplitude are used as candidates for edge
points. These thresholded edge points are thinned and split into straight segments. Due to technical reasons, edge
points in which several edges meet are lost. Therefore, T detect edge segments usually does not return
closed object contours. The parameter MaxDistance controls the maximum allowed distance of an edge point
to its approximating line. For efficiency reasons, the sum of the absolute values of the coordinate differences is
used instead of the Euclidean distance. MinLength controls the minimum length of the line segments. Lines
shorter than MinLength are not returned.
HALCON/C Reference Manual / 2000-11-15

547
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .(multichannel-)image(-array) Hobject : byte
Input image.
º SobelSize (input control) ...................................................integer Htuple . long
Mask size of the Sobel operator.
Default Value : 5
Value List : SobelSize ¾3, 5, 7, 9, 11, 13
º MinAmplitude (input control) ..............................................integer Htuple . long
Minimum edge strength.
Default Value : 32
Value Suggestions : MinAmplitude ¾10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 80, 90, 100, 110
Typical Range of Values : 1 MinAmplitude 255
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinAmplitude 0
º MaxDistance (input control) ................................................integer Htuple . long
Maximum distance of the approximating line to its original edge.
Default Value : 3
Value Suggestions : MaxDistance ¾2, 3, 4, 5, 6, 7, 8
Typical Range of Values : 1 MaxDistance 30
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MaxDistance 0
º MinLength (input control) ...................................................integer Htuple . long
Minimum lenght of to resulting line segments.
Default Value : 10
Value Suggestions : MinLength ¾3, 5, 7, 9, 11, 13, 16, 20
Typical Range of Values : 1 MinLength 500
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : MinLength 0
º BeginRow (output control) .......................................line.begin.y-array Htuple . long *
Row coordinate of the line segments’ start points.
º BeginCol (output control) .......................................line.begin.x-array Htuple . long *
Column coordinate of the line segments’ start points.
º EndRow (output control) ............................................line.end.y-array Htuple . long *
Row coordinate of the line segments’ end points.
º EndCol (output control) ............................................line.end.x-array Htuple . long *
Column coordinate of the line segments’ end points.
Example
Htuple
Htuple
SobelSize,MinAmplitude,MaxDistance,MinLength;
RowBegin,ColBegin,RowEnd,ColEnd;
create_tuple(&SobelSize,1);
set_i(SobelSize,5,0);
create_tuple(&MinAmplitude,1);
set_i(MinAmplitude,32,0);
create_tuple(&MaxDistance,1);
set_i(MaxDistance,3,0);
create_tuple(&MinLength,1);
set_i(MinLength,10,0);
T_detect_edge_segments(Image,SobelSize,MinAmplitude,MaxDistance,MinLength,
&RowBegin,&ColBegin,&RowEnd,&ColEnd);
Result
T detect edge segments returns H MSG TRUE if all parameters are correct. If the input is empty the
HALCON 6.0

548 CHAPTER 10. SEGMENTATION
behaviour can be set via set system(’no object result’,). If necessary, an exception handling
is raised.
Parallelization Information
T detect edge segments is reentrant and automatically parallelized (on tuple level, channel level).
sigma image, median image
Possible Predecessor Functions
Possible Successor Functions
select lines, partition lines, select lines longest, line position,
line orientation
Alternatives
sobel amp, (T )threshold, skeleton
Image filters
Module
dual threshold ( Hobject Image, Hobject *RegionCrossings, long MinSize,
double MinGray, double Threshold )
Threshold operator for signed images.
dual threshold segments the input image into a region with gray values Threshold (“positive” regions)
and a region with gray values -Threshold (“negative” regions). “Positive” or “negative” regions having a size
of less than MinSize are suppressed, as well as regions whose maximum gray value is less than MinGray in
absolute value.
The segmentation performed is not complete, i.e., the “positive” and “negative” regions together do not necessarily
cover the entire image: Areas with a gray value between ÌÖ×ÓÐ and Threshold, ÅÒÖÝ and
MinGray respectively, are not taken into account.
dual threshold is usually called after applying a Laplace operator (laplace, derivate gauss or
diff of gauss) or the difference of two images (sub image)toanimage.
The zero crossings of a Laplace image correspond to edges in an image, and are the separating regions of the
“positive” and “negative” regions in the Laplace image. They can be determined by calling dual threshold
with Threshold = 1. The parameter MinGray controls the noise invariance, while MinSize controls the
resolution of the edge detection.
Using byte images only the positive part of the operator is applied. Therefore dual threshold behaves like a
standard threshold operator ((T )threshold) with successive connection and select gray.
Parameter
º Image (input object) ..................................image(-array) Hobject : byte / int2 / int4 / real
Input Laplace image.
º RegionCrossings (output object) ........................................region-array Hobject *
“Positive” and “negative” regions.
º MinSize (input control) .............................................................integer long
Regions smaller than MinSize are suppressed.
Default Value : 20
Value Suggestions : MinSize ¾0, 10, 20, 50, 100, 200, 500, 1000
Typical Range of Values : 0 MinSize 10000 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º MinGray (input control) ..............................................................real double
Regions whose maximum absolute gray value is smaller than MinGray are suppressed.
Default Value : 5.0
Value Suggestions : MinGray ¾1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 9.0, 11.0, 15.0, 20.0
Typical Range of Values : 0.001 MinGray 10000.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : MinGray 0
HALCON/C Reference Manual / 2000-11-15

549
º Threshold (input control) ...........................................................real double
Regions which have a gray value larger than Threshold (or smaller than -Threshold) are suppressed.
Default Value : 2.0
Value Suggestions : Threshold ¾1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 9.0, 11.0, 15.0, 20.0
Typical Range of Values : 0.001 Threshold 10000.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : ´Threshold 1µ ´Threshold MinGrayµ
Example
/* Edge detection with the Laplace operator (and edge thinning) */
diff_of_gauss(Image,&Laplace,2.0,1.6) ;
/* finde "‘positive"’ und "‘negative"’ Bildbereiche: */
dual_threshold(Laplace,&Region,20,2,1) ;
/*The zero runnings are the complement to these image section: */
complement("full",Region,Nulldurchgaenge) ;
Result
dual threshold returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
dual threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
min max gray, sobel amp, gauss image, reduce domain, diff of gauss, sub image,
derivate gauss
Possible Successor Functions
connection, dilation1, erosion1, opening, closing, rank region, shape trans, skeleton
Alternatives
(T )threshold, connection, select shape, select gray, dyn threshold,
check difference
See Also
laplace, diff of gauss, expand region
Region processing
Module
dyn threshold ( Hobject OrigImage, Hobject ThresholdImage,
Hobject *RegionDynThresh, double Offset, const char *LightDark )
Segment an image using a local threshold.
dyn threshold selects from the input image those regions in which the pixels fulfill a threshold condition. Let
Ó ÇÖÁÑ ,and Ñ ÌÖ×ÓÐÁÑ . Then the condition for LightDark = ’light’ is:
For LightDark = ’dark’ the condition is:
Ó Ñ · Ç×Ø
Ó Ñ Ç×Ø
For LightDark = ’equal’ it is:
Ñ Ç×Ø Ó Ñ · Ç×Ø
Finally, for LightDark = ’not equal’ it is:
Ñ
Ç×Ø Ó Ó Ñ · Ç×Ø
HALCON 6.0

550 CHAPTER 10. SEGMENTATION
This means that all points in OrigImage whose gray value is larger then or equal to the gray value in
ThresholdImage plus an offset are aggregated into the resulting region.
Typically, the threshold images are smoothed versions of the original image (e.g., by applying mean image,
gauss image, etc.). Then the effect of dyn threshold is similar to applying (T )threshold to a
highpass-filtered version of the original image (see highpass image).
With dyn threshold contours of an object can be extracted, where the objects’ size (diameter) is determined
by the mask size of the lowpass filter and the amplitude of the objects’ edges:
The larger the mask size is chosen, the larger the found regions get. As a rule of thumb, the mask size should be
about twice the diameter of the objects to be extracted. It is important not to set the parameter Offset to zero
because in this case too many small regions will be found (noise). Values between 5 and 40 are a sensible choice.
The larger Offset is chosen, the smaller the extracted regions get.
All points of the input image fulfilling the above condition are stored jointly in one region. If necessary, the
connected components can be obtained by calling connection.
Attention
If Offset is chosen from ½ to ½ usually a very noisy region is generated, requiring large storage. If Offset
is chosen too large ( 60, say) it may happen that no points fulfill the threshold condition (i.e., an empty region is
returned). If Offset is chosen too small ( -60, say) it may happen that all points fulfill the threshold condition
(i.e., a full region is returned).
Parameter
º OrigImage (input object) ............................image(-array) Hobject : byte / int2 / int4 / real
Image to be segmented.
º ThresholdImage (input object) ......................image(-array) Hobject : byte / int2 / int4 / real
Image containing the local thresholds.
º RegionDynThresh (output object) .......................................region(-array) Hobject *
Segmented regions.
º Offset (input control) .....................................................number double / long
Offset added to ThresholdImage.
Default Value : 5.0
Value Suggestions : Offset ¾1.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.0
Typical Range of Values : -255.0 Offset 255.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 5
Restriction : ´-255 Offsetµ ´Offset 255µ
º LightDark (input control) .....................................................string const char *
Extract light, dark or similar areas?
Default Value : ’light’
Value List : LightDark ¾’dark’, ’light’, ’equal’, ’not equal’
Example
/* Looking for regions with the diameter D */
mean_image(Image,&Mean,D*2+1,D*2+1);
dyn_threshold(Image,Mean,&Seg,5.0,"light");
connection(Seg,&Region);
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ µ.
Result
dyn threshold returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
dyn threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
mean image, smooth image, gauss image
HALCON/C Reference Manual / 2000-11-15

551
Possible Successor Functions
connection, select shape, reduce domain, select gray, rank region, dilation1,
opening
Alternatives
check difference, highpass image, sub image, (T )threshold
See Also
mean image, smooth image, gauss image, connection, rank region, dilation1
Region processing
Module
expand gray ( Hobject Regions, Hobject Image, Hobject ForbiddenArea,
Hobject *RegionExpand, const char *Iterations, const char *Mode,
long Threshold )
T expand gray ( Hobject Regions, Hobject Image, Hobject ForbiddenArea,
Hobject *RegionExpand, Htuple Iterations, Htuple Mode, Htuple Threshold )
Fill gaps between regions (depending on gray value or color) or split overlapping regions.
(T )expand gray closes gaps between the input regions, which resulted from the suppression of small regions
in a segmentation operator, (mode ’image’), for example, or separates overlapping regions ’region’). Both uses
result from the expansion of regions. The operator works by adding a one pixel wide “strip” to a region, in which
the gray values or color are different from the gray values or color of neighboring pixles on the region’s border
by at most Threshold (in each channel). For images of type ’cyclic’ (e.g., direction images), also points with a
gray value difference of at least ¾ ÌÖ×ÓÐ are added to the output region.
The expansion takes place only in regions, which are designated as not “forbidden” (parameter
ForbiddenArea). The number of iterations is determined by the parameter Iterations. By passing ’maximal’,
(T )expand gray iterates until convergence, i.e., until no more changes occur. By passing 0 for this
parameter, all non-overlapping regions are returned. The two modes of operation (’image’ and ’region’) are different
in the following ways:
’image’ The input regions are expanded iteratively until they touch another region or the image border, or the
expansion stops because of too high gray value differences. Because (T )expand gray processes all
regions simultaneously, gaps between regions are distributed evenly to all regions with a similar gray value.
Overlapping regions are split by distributing the area of overlap evenly to both regions.
’region’ No expansion of the input regions is performed. Instead, only overlapping regions are split by distributing
the area of overlap evenly to regions having a matching gray value or color.
Attention
Because regions are only expanded into areas having a matching gray value or color, usually gaps will remain
between the output regions, i.e., the segmentation is not complete.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions for which the gaps are to be closed, or which are to be separated.
º Image (input object) ..............................................................image Hobject
Image (possibly multi-channel) for gray value or color comparison.
º ForbiddenArea (input object) ...................................................region Hobject
Regions in which no expansion takes place.
º RegionExpand (output object) ...........................................region(-array) Hobject *
Expanded or separated regions.
º Iterations (input control) ....................................string (Htuple .) const char * / long
Number of iterations.
Default Value : ’maximal’
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ’maximal’
Typical Range of Values : 1 Iterations 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
HALCON 6.0

552 CHAPTER 10. SEGMENTATION
º Mode (input control) ..................................................string (Htuple .) const char *
Expansion mode.
Default Value : ’image’
Value List : Mode ¾’image’, ’region’
º Threshold (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Maximum difference between the gray value or color at the region’s border and a candidate for expansion.
Default Value : 32
Value Suggestions : Threshold ¾5, 10, 15, 20, 25, 30, 40, 50
Typical Range of Values : 1 Threshold 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
regiongrowing(Image,&RawSegments,3,3,6.0,100);
set_colored(WindowHandle,12);
disp_region(RawSegments,WindowHandle);
expand_gray(RawSegments,Image,EMPTY_REGION,&Segments,"maximal","image",24);
clear_window(WindowHandle);
disp_region(Segments,WindowHandle)
Result
(T )expand gray always returns the value H MSG TRUE. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,), the behavior in case of an empty input
region via set system(’empty region result’,), and the behavior in case of an empty
result region via set system(’store empty region’,). If necessary, an exception handling
is raised.
Parallelization Information
(T )expand gray is reentrant and processed without parallelization.
Possible Predecessor Functions
connection, regiongrowing, pouring, (T )class ndim norm
select shape
(T )expand gray ref, expand region
Region processing
Possible Successor Functions
See Also
Module
expand gray ref ( Hobject Regions, Hobject Image, Hobject ForbiddenArea,
Hobject *RegionExpand, const char *Iterations, const char *Mode,
long RefGray, long Threshold )
T expand gray ref ( Hobject Regions, Hobject Image,
Hobject ForbiddenArea, Hobject *RegionExpand, Htuple Iterations,
Htuple Mode, Htuple RefGray, Htuple Threshold )
Fill gaps between regions (depending on gray value or color) or split overlapping regions.
(T )expand gray ref closes gaps between the input regions, which resulted from the suppression of small
regions in a segmentation operator, (mode ’image’), for example, or separates overlapping regions ’region’). Both
uses result from the expansion of regions. The operator works by adding a one pixel wide “strip” to a region, in
which the gray values or color are different from a reference gray value or color by at most Threshold (in each
channel). For images of type ’cyclic’ (e.g., direction images), also points with a gray value difference of at least
¾ ÌÖ×ÓÐ are added to the output region.
HALCON/C Reference Manual / 2000-11-15

553
The expansion takes place only in regions, which are designated as not “forbidden” (parameter
ForbiddenArea). The number of iterations is determined by the parameter Iterations. By passing ’maximal’,
(T )expand gray ref iterates until convergence, i.e., until no more changes occur. By passing 0 for
this parameter, all non-overlapping regions are returned. The two modes of operation (’image’ and ’region’) are
different in the following ways:
’image’ The input regions are expanded iteratively until they touch another region or the image border, or the
expansion stops because of too high gray value differences. Because (T )expand gray ref processes all
regions simultaneously, gaps between regions are distributed evenly to all regions with a similar gray value.
Overlapping regions are split by distributing the area of overlap evenly to both regions.
’region’ No expansion of the input regions is performed. Instead, only overlapping regions are split by distributing
the area of overlap evenly to regions having a matching gray value or color.
Attention
Because regions are only expanded into areas having a matching gray value or color, usually gaps will remain
between the output regions, i.e., the segmentation is not complete.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Regions for which the gaps are to be closed, or which are to be separated.
º Image (input object) ..............................................................image Hobject
Image (possibly multi-channel) for gray value or color comparison.
º ForbiddenArea (input object) ...................................................region Hobject
Regions in which no expansion takes place.
º RegionExpand (output object) ...........................................region(-array) Hobject *
Expanded or separated regions.
º Iterations (input control) ....................................string (Htuple .) const char * / long
Number of iterations.
Default Value : ’maximal’
Value Suggestions : Iterations ¾’maximal’, 1, 2, 3, 4, 5, 7, 10, 15, 20, 30, 50, 70, 100, 150, 200, 300,
500
Typical Range of Values : 1 Iterations 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Mode (input control) ..................................................string (Htuple .) const char *
Expansion mode.
Default Value : ’image’
Value List : Mode ¾’image’, ’region’
º RefGray (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Reference gray value or color for comparison.
Default Value : 128
Value Suggestions : RefGray ¾1, 10, 20, 50, 100, 128, 200, 255
Typical Range of Values : 1 RefGray 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
º Threshold (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Maximum difference between the reference gray value or color and a candidate for expansion.
Default Value : 32
Value Suggestions : Threshold ¾4, 10, 15, 20, 25, 30, 40
Typical Range of Values : 1 Threshold 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Example
read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
regiongrowing(Image,&RawSegments,3,3,6.0,100);
set_colored(WindowHandle,12);
HALCON 6.0

554 CHAPTER 10. SEGMENTATION
disp_region(RawSegments,WindowHandle);
T_intensity(RawSegments,Image,&Mean,_t);
set_i(Thresh,24,0);
set_s(Iter,"maximal",0);
set_s(Mode,"image",0);
T_expand_gray_ref(RawSegments,Image,EMPTY_REGION,&Segments,Iter,Mode,
Mean,Thresh);
clear_window(WindowHandle);
disp_region(Segments,WindowHandle);
Result
(T )expand gray ref always returns the value H MSG TRUE. The behavior in case of empty input (no regions
given) can be set via set system(’no object result’,), the behavior in case of an
empty input region via set system(’empty region result’,), and the behavior in case of
an empty result region via set system(’store empty region’,). If necessary, an exception
handling is raised.
Parallelization Information
(T )expand gray ref is reentrant and processed without parallelization.
Possible Predecessor Functions
connection, regiongrowing, pouring, (T )class ndim norm
select shape
(T )expand gray, expand region
Region processing
Possible Successor Functions
See Also
Module
expand line ( Hobject Image, Hobject *RegionExpand, long Index,
const char *ExpandType, const char *RowColumn, double Threshold )
Expand a region starting at a given line.
expand line generates a region by expansion, starting at a given line (row or column).
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be segmented.
º RegionExpand (output object) ...........................................region(-array) Hobject *
Extracted segments.
º Index (input control) ................................................................integer long
Row or column index.
Default Value : 256
Value Suggestions : Index ¾16, 64, 128, 200, 256, 300, 400, 511
Restriction : Index 0
º ExpandType (input control) ...................................................string const char *
Stopping criterion.
Default Value : ’gradient’
Value List : ExpandType ¾’gradient’, ’mean’
º RowColumn (input control) .....................................................string const char *
Segmentation mode (row or column).
Default Value : ’row’
Value List : RowColumn ¾’row’, ’column’
HALCON/C Reference Manual / 2000-11-15

555
º Threshold (input control) .................................................number double / long
Threshold for the expansion.
Default Value : 3.0
Value Suggestions : Threshold ¾0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 13.0, 17.0, 20.0, 30.0
Typical Range of Values : 1.0 Threshold 255.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 1.0
Restriction : ´Threshold 0.0µ ´Threshold 255.0µ
Example
read_image(&Image,"fabrik");
gauss_image(Image,&Gauss,5);
expand_line(Gauss,&Reg,100,"mean","row",5.0);
set_colored(WindowHandle,12);
disp_region(Maxima,WindowHandle);
Parallelization Information
expand line is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gauss image, smooth image, anisotrope diff, median image, affine trans image,
rotate image
Possible Successor Functions
intersection, opening, closing
Alternatives
(T )regiongrowing mean, (T )expand gray, (T )expand gray ref
Region processing
Module
fast threshold ( Hobject Image, Hobject *Region, double MinGray,
double MaxGray, long MinHeight )
Fast selection of grayvalues within a given gray intervall.
fast threshold selects the pixels from the input image whose gray values fulfill the following condition:
ÅÒÖÝ ÅÜÖÝ
To reduce procesing time, the selection is done in two steps: At first all pixels along rows with distances
MinHeight are processed. In the next step the neighborhood (size MinHeight ¢ MinHeight) ofallpreviously
selected points are processed.
Parameter
º Image (input object) .................................image(-array) Hobject : byte / direction / cyclic
Image to be thresholded.
º Region (output object) ...................................................region(-array) Hobject *
Regions with gray values lying in the specified interval.
º MinGray (input control) ....................................................number double / long
Lower threshold for the gray values.
Default Value : 128
Value Suggestions : MinGray ¾0.0, 10.0, 30.0, 64.0, 128.0, 200.0, 220.0, 255.0
Typical Range of Values : 0.0 MinGray 255.0 (lin)
Minimal Value Step : 1
Recommended Value Step : 5.0
HALCON 6.0

556 CHAPTER 10. SEGMENTATION
º MaxGray (input control) ....................................................number double / long
Upper threshold for the gray values.
Default Value : 255.0
Value Suggestions : MaxGray ¾0.0, 10.0, 30.0, 64.0, 128.0, 200.0, 220.0, 255.0
Typical Range of Values : 0.0 MaxGray 255.0 (lin)
Minimal Value Step : 1
Recommended Value Step : 5.0
º MinHeight (input control) ..........................................................number long
Minimum height of objects to be extracted.
Default Value : 20
Value Suggestions : MinHeight ¾5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 100
Typical Range of Values : 2 MinHeight 200 (lin)
Minimal Value Step : 1
Recommended Value Step : 2
Complexity
Let be the area of the ouput region and Ø the height of Image. Then the runtime complexity is Ç´ ·
ØÅÒÀص.
Result
fast threshold returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
fast threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
T histo to thresh, min max gray, sobel amp, gauss image, reduce domain,
fill interlace
Possible Successor Functions
connection, dilation1, erosion1, opening, closing, rank region, shape trans, skeleton
(T )threshold
Alternatives
See Also
class 2dim sup, hysteresis threshold, dyn threshold
Region processing
Module
T histo to thresh ( Htuple Histogramm, Htuple Sigma, Htuple *MinThresh,
Htuple *MaxThresh )
Determine gray value thresholds from a histogram.
T histo to thresh determines gray value thresholds from a histogram for a segmentation of an image using
(T )threshold. The thresholds returned are 0, 255, and all minima extracted from the histogram. Before the
thresholds are determined the histogram is smoothed with a Gaussian.
Parameter
º Histogramm (input control) ................................histogram-array Htuple . long / double
Gray value histogram.
º Sigma (input control) .....................................................number Htuple . double
Sigma for the Gaussian smoothing of the histogram.
Default Value : 2.0
Value Suggestions : Sigma ¾0.5, 1.0, 2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.1 Sigma 30.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.2
º MinThresh (output control) ..........................................integer-array Htuple . long *
Minimum thresholds.
HALCON/C Reference Manual / 2000-11-15

557
º MaxThresh (output control) ..........................................integer-array Htuple . long *
Maximum thresholds.
Example
read_image(&Image,"fabrik");
T_histo(Image,Image,&HistoAbs,&HistoRel);
create_tuple(&Sigma,1);
set_d(Sigma,3.0,0);
T_histo_to_thresh(HistoAbs,Sigma,&MinThresh,&MaxThresh);
T_threshold(Image,&Seg,MinThresh,MaxThresh);
connection(Seg,&Connected);
Parallelization Information
T histo to thresh is reentrant and processed without parallelization.
gray histo
(T )threshold
auto threshold
Region processing
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
hysteresis threshold ( Hobject Image, Hobject *RegionHysteresis,
long Low, long High, long MaxLength )
Perform a hysteresis threshold operation on an image.
hysteresis threshold performs a hysteresis threshold operation (due to Canny) on an image. All points
in the input image Image having a gray value larger than or equal to High are immediately accepted (“secure”
points). Conversely, all points with gray values less than Low are immediately rejected. “Potential” points with
gray values between both thresholds are accepted if they are connected to “secure” points by a path of “potential”
points having a length of at most MaxLength points. This means that “secure” points influence their surroundings
(hysteresis). The gray values of the input images remain unchanged. Only the regions of the image may get smaller.
Parameter
º Image (input object) ..................................................image(-array) Hobject : byte
Image to be segmented.
º RegionHysteresis (output object) .....................................region(-array) Hobject *
Segmentation result.
º Low (input control) ...................................................................integer long
Lower threshold for the gray values.
Default Value : 30
Value Suggestions : Low ¾5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100
Typical Range of Values : 0 Low 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : ´0 Lowµ ´Low 255µ
º High (input control) .................................................................integer long
Lower threshold for the gray values.
Default Value : 60
Value Suggestions : High ¾5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130
Typical Range of Values : 0 High 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : ´´0 Highµ ´High 255µµ ´High Lowµ
HALCON 6.0

558 CHAPTER 10. SEGMENTATION
º MaxLength (input control) ...........................................................integer long
Maximum length of a path of “potential” points to reach a “secure” point.
Default Value : 10
Value Suggestions : MaxLength ¾1, 2, 3, 5, 7, 10, 12, 14, 17, 20, 25, 30, 35, 40, 50
Typical Range of Values : 1 MaxLength 1000 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : MaxLength 1
Result
hysteresis threshold returns H MSG TRUE if all parameters are correct. The behavior with respect to
the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
hysteresis threshold is reentrant and automatically parallelized (on tuple level).
Alternatives
dyn threshold, (T )threshold, class 2dim sup
See Also
edges image, sobel amp, background seg
Bibliography
J. Canny, ”‘Finding Edges and Lines in Images”’; Report, AI-TR-720, M.I.T. Artificial Intelligence Lab., Cambridge,
MA, 1983.
Module
Region processing
learn ndim box ( Hobject Foreground, Hobject Background,
Hobject MultiChannelImage, long ClassifHandle )
Train the current classificator using a multi-channel image.
learn ndim box trains the classificator ClassifHandle with the gray values of MultiChannelImage
using the points in Foreground as training sample. The points in Background are to be rejected by the
classificator. The classificator trained thus can be used in learn ndim box to segment multi-channel images.
Foreground are the points that have to be found, Background contains the points which shall not be found.
Each pixel is trained once during the training process. For points in Foreground the class “0” is used, while
for Background “1” is used. Pixels are trained by alternating points from Foreground with points from
Background. If one region is smaller than the other, pixels are taken cyclically from the smaller region until the
larger region is exhausted. learn ndim box later accepts only points which can be classified into class “0”.
Attention
All channels must be of the same type and have the same size.
Parameter
º Foreground (input object) .................................................region(-array) Hobject
Foreground pixels to be trained.
º Background (input object) .................................................region(-array) Hobject
Background pixels to be trained (rejection class).
º MultiChannelImage (input object) multichannel-image(-array) Hobject : byte / int1 / int2 / int4 / real
/ direction / cyclic
Multi-channel training image.
º ClassifHandle (input control) ...................................................class box long
Classificator’s handle number.
Complexity
Let Æ be the number of generated hyper-cuboids and be the area of the input region. Then the runtime complexity
is Ç´Æ £ µ.
Result
class ndim box returns H MSG TRUE if all parameters are correct and there is an active classificator. The
HALCON/C Reference Manual / 2000-11-15

559
behavior with respect to the input images can be determined by setting the values of the flags ’no object result’
and ’empty region result’ with set system. If necessary, an exception is raised.
Parallelization Information
learn ndim box is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
create class box, draw region
Possible Successor Functions
class ndim box, descript class box
T learn class box
Region processing
Alternatives
Module
T learn ndim norm ( Hobject Foreground, Hobject Background,
Hobject Image, Htuple Metric, Htuple Distance, Htuple MinNumberPercent,
Htuple *Radius, Htuple *Center, Htuple *Quality )
Construct clusters for (T )class ndim norm.
T learn ndim norm generates classification clusters from the region Foreground and the corresponding
gray values in the multi-channel image Image, which can be used in (T )class ndim norm. Background
determines a class of pixels not to be found in (T )class ndim norm. This parameter may be empty (empty
tuple).
The parameter Distance determines the maximum distance Radius of the clusters. It describes the minimum
distance between two cluster centers. If the parameter Distance is small the (small) hyper-cubes or hyperspheres
can approximate the feature space well. Simultaneously the runtime during classification increases.
The ratio of the number of pixels in a cluster to the total number of pixels (in percent) must be larger than the
value of MinNumberPercent, otherwise the cluster is not returned. MinNumberPercent serves to eliminate
outliers in the training set. If it is chosen too large many clusters are suppressed.
Two different clustering procedures can be selected: The minimum distance algorithm (n-dimensional hyperspheres)
and the maximum algorithm (n-dimensional hyper-cubes) for describing the pixels of the image to classify
in the n-dimensional histogram (parameter Metric). The Euclidian metric usually yields the better results, but
takes longer to compute. The parameter Quality returns the quality of the clustering. It is a measure of overlap
between the rejection class and the classificator classes. Values larger than 0 denote the corresponding ratio of
overlap. If no rejection region is given, its value is set to 1. The regions in Background do not influence on the
clusteringṪhey are merely used to check the results that can be expected.
Parameter
º Foreground (input object) .................................................region(-array) Hobject
Foreground pixels to be trained.
º Background (input object) .................................................region(-array) Hobject
Background pixels to be trained (rejection class).
º Image (input object) .............................image(-array) Hobject : byte / int1 / int2 / int4 / real
Multi-channel training image.
º Metric (input control) .................................................string Htuple . const char *
Metrictobeused.
Default Value : ’euclid’
Value List : Metric ¾’euclid’, ’maximum’
º Distance (input control) ...........................................number Htuple . double / long
Maximum cluster radius.
Default Value : 10.0
Value Suggestions : Distance ¾1.0, 2.0, 3.0, 4.0, 6.0, 8.0, 10.0, 13.0, 17.0, 24.0, 30.0, 40.0
Typical Range of Values : 0.0 Distance 511.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Restriction : Radius 0.0
HALCON 6.0

560 CHAPTER 10. SEGMENTATION
º MinNumberPercent (input control) ................................number Htuple . double / long
The ratio of the number of pixels in a cluster to the total number of pixels (in percent) must be larger than
MinNumberPercent (otherwise the cluster is not output).
Default Value : 0.01
Value Suggestions : MinNumberPercent ¾0.001, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0
Typical Range of Values : 0.0 MinNumberPercent 100.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : ´0 MinNumberPercentµ ´MinNumberPercent 100µ
º Radius (output control) ...............................................real-array Htuple . double *
Cluster radii of half edge lengths.
º Center (output control) ...............................................real-array Htuple . double *
Coordinates of all cluster centers.
º Quality (output control) ...................................................real Htuple . double *
Overlap of the rejection class with the classified objects (1: no overlapping).
Assertion : ´0 Qualityµ ´Quality 1µ
Result
T learn ndim norm returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images can be determined by setting the values of the flags ’no object result’ and ’empty region result’
with set system. If necessary, an exception is raised.
Parallelization Information
T learn ndim norm is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
min max gray, sobel amp, gauss image, reduce domain, diff of gauss
Possible Successor Functions
(T )class ndim norm, connection, dilation1, erosion1, opening, closing, rank region,
shape trans, skeleton
See Also
(T )class ndim norm, class ndim box, histo 2dim
Bibliography
P. Haber”acker, ”‘Digitale Bildverarbeitung”’; Hanser-Studienb”ucher, M”unchen, Wien, 1987
Region processing
Module
local max ( Hobject Image, Hobject *LocalMaxima )
Detect all local maxima in an image.
local max extracts all points in an image having a gray value larger than the gray value of all its neighbors. The
neighborhood used can be set by set system(’neighborhood’,).
Parameter
º Image (input object) .............................image(-array) Hobject : byte / int1 / int2 / int4 / real
Image to be processed.
º LocalMaxima (output object) ............................................region(-array) Hobject *
Extracted local maxima as regions.
Parameter Number : LocalMaxima Image
Example
read_image(&Image,"fabrik");
corner_responce(Image,&CornerResp,5,0.04);
local_max(CornerResp,&Maxima);
set_colored(WindowHandle,12);
disp_region(Maxima,WindowHandle);
T_get_region_points(Maxima,&Row,&Col);
HALCON/C Reference Manual / 2000-11-15

561
Parallelization Information
local max is reentrant and automatically parallelized (on tuple level).
gauss image, smooth image
get region points, connection
Possible Predecessor Functions
Possible Successor Functions
Alternatives
gray skeleton, nonmax suppression amp, plateaus, plateaus center
See Also
monotony, topographic sketch, corner response, texture laws
Region processing
Module
nonmax suppression amp ( Hobject ImgAmp, Hobject *ImageResult,
const char *Mode )
Suppress non-maximum points on an edge.
nonmax suppression amp suppresses in the regions of the image ImgAmp all points whose gray values are
not local (directed) maxima. In contrast to nonmax suppression dir, a direction image is not needed. Two
modes of operation can be selected:
’hvnms’ A point is labeled as a local maximum if its gray value is larger than or equal to the gray values within
a seach space of ¦ 5 pixels, either horizontally or vertically. Non-maximum points are removed from the
region, gray values remain unchanged.
’loc max’ A point is labeled as a local maximum if its gray value is larger than or equal to the gray values of its
eight neighbors.
Parameter
º ImgAmp (input object) ................................................image(-array) Hobject : byte
Amplitude (gradient magnitude) image.
º ImageResult (output object) ......................................image(-array) Hobject * : byte
Image with thinned edge regions.
º Mode (input control) ............................................................string const char *
Select horizontal/vertical or undirected NMS.
Default Value : ’hvnms’
Value List : Mode ¾’hvnms’, ’loc max’
Result
nonmax suppression amp returns H MSG TRUE if all parameters are correct. The behavior with respect
to the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
nonmax suppression amp is reentrant and automatically parallelized (on tuple level, channel level).
sobel amp
Possible Predecessor Functions
Possible Successor Functions
(T )threshold, hysteresis threshold
Alternatives
gray skeleton, local max, gray dilation rect
skeleton
See Also
Bibliography
S.Lanser: ”‘Detektion von Stufenkanten mittels rekursiver Filter nach Deriche”’; Diplomarbeit; Technische Universit”at
M”unchen, Institut f”ur Informatik, Lehrstuhl Prof. Radig; 1991.
HALCON 6.0

562 CHAPTER 10. SEGMENTATION
J.Canny: ”‘Finding Edges and Rows in Images”’; Report, AI-TR-720; M.I.T. Artificial Intelligence Lab., Cambridge,
MA; 1983.
Module
Region processing
nonmax suppression dir ( Hobject ImgAmp, Hobject ImgDir,
Hobject *ImageResult, const char *Mode )
Suppress non-maximum points on an edge.
nonmax suppression dir suppresses in the regions of the image ImgAmp all points whose gray values
are not local (directed) maxima. ImgDir is a direction image giving the direction perpendicular for the local
maximum (Unit: 2 degrees, i.e., 50 degrees are coded as 25 in the image). Such images are returned, for example,
by edges image. Two modes of operation can be selected:
’nms’ Each point in the image is tested whether its gray value is a local maximum perpendicular to its direction.
In this mode only the two neighbors closest to the given direction are examined. If one of the two gray values
is greater than the gray of the point to be tested, it is suppressed (i.e., removed from the input regionṪhe
corresponding gray value remains unchanged).
’inms’ Like ’nms’Ḣowever, the two gray values for the test are obtained by interpolation from four adjacent
points.
Parameter
º ImgAmp (input object) ......................................................image(-array) Hobject
Amplitude (gradient magnitude) image.
º ImgDir (input object) ......................................................image(-array) Hobject
Direction image.
º ImageResult (output object) .............................................image(-array) Hobject *
Image with thinned edge regions.
º Mode (input control) ............................................................string const char *
Select non-maximum-suppression or interpolating NMS.
Default Value : ’nms’
Value List : Mode ¾’nms’, ’inms’
Result
nonmax suppression dir returns H MSG TRUE if all parameters are correct. The behavior with respect
to the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
nonmax suppression dir is reentrant and automatically parallelized (on tuple level, channel level).
edges image, sobel dir
Possible Predecessor Functions
Possible Successor Functions
(T )threshold, hysteresis threshold
Alternatives
nonmax suppression amp, gray skeleton, gray dilation rect
skeleton
See Also
Bibliography
S.Lanser: ”‘Detektion von Stufenkanten mittels rekursiver Filter nach Deriche”’; Diplomarbeit; Technische Universit”at
M”unchen, Institut f”ur Informatik, Lehrstuhl Prof. Radig; 1991.
J.Canny: ”‘Finding Edges and Rows in Images”’; Report, AI-TR-720; M.I.T. Artificial Intelligence Lab., Cambridge;
1983.
Module
Region processing
HALCON/C Reference Manual / 2000-11-15

563
plateaus ( Hobject Image, Hobject *Plateaus )
Detect all gray value plateaus.
plateaus extracts all points with a gray value greater or equal to the gray value of its neighbors (8-connectivity).
Each maximum is returned as a separate region.
Parameter
º Image (input object) .............................image(-array) Hobject : byte / int1 / int2 / int4 / real
Image to be processed.
º Plateaus (output object) ..................................................region-array Hobject *
Extracted plateaus as regions (one region for each plateau).
Example
read_image(&Image,"fabrik");
corner_responce(Image,&CornerResp,5,0.04);
plateaus(CornerResp,&Maxima);
set_colored(WindowHandle,12);
disp_region(Maxima,WindowHandle);
T_area_center(Maxima,_,&Row,&Col);
Parallelization Information
plateaus is reentrant and automatically parallelized (on tuple level).
gauss image, smooth image
Possible Predecessor Functions
Possible Successor Functions
area center, get region points, select shape
Alternatives
plateaus center, gray skeleton, nonmax suppression amp, local max
See Also
monotony, topographic sketch, corner response, texture laws
Region processing
Module
plateaus center ( Hobject Image, Hobject *Plateaus )
Detect the centers of all gray value plateaus.
plateaus center extracts all points with a gray value greater or equal to the gray value of its neighbors (8-
connectivity). If more than one of these points are connected (plateau), their center of gravity is returned. Each
maximum is returned as a separate region.
Parameter
º Image (input object) .............................image(-array) Hobject : byte / int1 / int2 / int4 / real
Image to be processed.
º Plateaus (output object) ..................................................region-array Hobject *
Centers of gravity of the extracted plateaus as regions (one region for each plateau).
Example
read_image(&Image,"fabrik");
corner_responce(Image,&CornerResp,5,0.04);
plateaus_center(CornerResp,&Maxima);
set_colored(WindowHandle,12);
disp_region(Maxima,WindowHandle);
T_area_center(Maxima,_,&Row,&Col);
HALCON 6.0

564 CHAPTER 10. SEGMENTATION
Parallelization Information
plateaus center is reentrant and automatically parallelized (on tuple level).
gauss image, smooth image
Possible Predecessor Functions
Possible Successor Functions
area center, get region points, select shape
Alternatives
plateaus, gray skeleton, nonmax suppression amp, local max
See Also
monotony, topographic sketch, corner response, texture laws
Region processing
Module
pouring ( Hobject Image, Hobject *Regions, const char *Mode,
long MinGray, long MaxGray )
Segment an image by “pouring water” over it.
pouring regards the input image as a “mountain range.” Larger gray values correspond to mountain peaks, while
smaller gray values correspond to valley bottoms. pouring segments the input image in several steps. First the
local maxima are extracted, i.e., pixels which either alone or in the form of an extended plateau have larger gray
values than their immediate neighbors (in 4-connectivity). In the next step, the maxima thus found are the starting
points for an expansion until “valley bottoms” are reached. The expansion is done as long as there are chains of
pixels in which the gray value gets smaller (like water running downhill from the maxima in all directions). Again,
4-connectivity is used, but with a weaker condition (smaller or equal). This means that points at valley bottoms
may belong to more than one maximum. These areas are at first not assigned to a region, but rather are split among
all competing segments in the last step. The split is done by a uniform expansion of all involved segments, until all
ambiguous pixels were assigned. The parameter Mode determines which steps are executed. The following values
are possible:
’all’ This is the normal mode of operation. All steps of the segmentation are performed. The regions are assigned
to maxima, and overlapping regions are split.
’maxima’ The segmentation only extracts the local maxima of the input image. No corresponding regions are
extracted.
’regions’ The segmentation extracts the local maxima of the input image and the corresponding regions, which
are uniquely determined. Areas which could be assigned to more than one maximum are not split.
In order to prevent the algorithm from splitting a uniform background, which is different from the rest of the
image, the parameters MinGray and MaxGray determine gray value thresholds for regions in the image which
should be regarded as background. All parts of the image having a gray value smaller than MinGray or larger
than MaxGray are disregarded for the extraction of the maxima as well as for the assignment of regions. For
a complete segmentation of the image, MinGray = 0 und MaxGray = 255 should be selected. In any case,
MinGray MaxGray must be observed.
Parameter
º Image (input object) .........................................................image Hobject : byte
Image to be segmented.
º Regions (output object) ...................................................region-array Hobject *
Segmentation result.
º Mode (input control) ............................................................string const char *
Mode of operation.
Default Value : ’all’
Value List : Mode ¾’all’, ’maxima’, ’regions’
HALCON/C Reference Manual / 2000-11-15

565
º MinGray (input control) .............................................................integer long
All gray values smaller than this threshold are disregarded.
Default Value : 0
Value Suggestions : MinGray ¾0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110
Typical Range of Values : 0 MinGray 256 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : MinGray 0
º MaxGray (input control) .............................................................integer long
All gray values larger than this threshold are disregarded.
Default Value : 255
Value Suggestions : MaxGray ¾100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240,
250, 255
Typical Range of Values : 0 MaxGray 256 (lin)
Minimal Value Step : 1
Recommended Value Step : 10
Restriction : ´MaxGray 255µ ´MaxGray MinGrayµ
Example
/* Segmentation of a filtered image */
read_image(&Image,"br2");
mean_image(Image,&Mean,11,11);
pouring(Mean,&Seg,"all",0,255);
disp_image(Mean,WindowHandle);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);
/* Segmentation of an image with masking of a dark backround */
read_image(&Image,"hand");
mean_image(Image,&Mean,15,15);
pouring(Mean,&Seg,"all",40,255);
disp_image(Mean,WindowHandle);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);
/* Segmentation of a 2D-histogram */
read_image(&Image,"affe");
texture_laws(Image,&Texture,"el",2,5);
disp_image(Image,WindowHandle);
draw_region(&Region,draw_region);
reduce_domain(Texture,Region,&Testreg);
histo_2dim(Testreg,Texture,Region,&Histo);
pouring(Histo,Seg,"all",0,255);
Complexity
Let Æ be the number of pixels in the input image and Å be the number of found segments, where the enclosing
rectangle of the segment contains Ñ pixels. Furthermore, let à be the number of chords in segment . Then the
runtime complexity is
Ç´¿ £ Æ · ×ÙÑ Å ´¿ £ Ñ µ·×ÙÑ Å ´Ã µµ
Result
pouring usually returns the value H MSG TRUE. If necessary, an exception is raised.
Parallelization Information
pouring is processed under mutual exclusion against itself and without parallelization.
gauss image, smooth image
Possible Predecessor Functions
HALCON 6.0

566 CHAPTER 10. SEGMENTATION
watersheds, local max
Alternatives
See Also
histo 2dim, expand region, (T )expand gray, (T )expand gray ref
Region processing
Module
regiongrowing ( Hobject Image, Hobject *Regions, long Row, long Column,
double Tolerance, long MinSize )
Segment an image using regiongrowing.
regiongrowing segments images into regions of the same intensity — rastered into rectangles of size Row ¢
Column. In order to decide whether two adjacent rectangles belong to the same region only the gray value of their
center points is used. If the gray value difference is less then or equal to Tolerance the rectangles are merged
into one region.
If ½ und ¾ are two gray values to be examined, they are merged into the same region if:
½ ¾ ÌÓÐÖÒ
For images of type ’cyclic’, the following formulas are used:
´ ½ ¾ ÌÓÐÖÒµ ´ ½ ¾ ½¾µ
´¾ ½ ¾ ÌÓÐÖÒµ ´ ½ ¾ ½¾µ
For rectangles larger than one pixel, ususally the images should be smoothed with a lowpass filter with a size of
at least Row ¢ Column before calling regiongrowing (so that the gray values at the centers of the regtangles
are “representative” for the whole rectangle). If the image contains little noise and the rectangles are small, the
smoothing can be omitted in many cases. This, of course, makes the whole procedure faster.
The resulting regions are collections of rectangles of the chosen size Row ¢ Column . Only regions containing at
least MinSize points are returned.
Regiongrowing is a very fast operation, and thus suited for time-critical applications.
Attention
Column and Row are automatically converted to odd values if necessary.
Parameter
º Image (input object) .....................image(-array) Hobject : byte / int1 / int2 / int4 / cyclic / real
Image to be segmented.
º Regions (output object) ...................................................region-array Hobject *
Extracted segments.
º Row (input control) ..................................................................extent.y long
Vertical distance between tested pixels (height of the raster).
Default Value : 3
Value Suggestions : Row ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21
Typical Range of Values : 1 Row 99 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Row 1µ odd´Rowµ
º Column (input control) ..............................................................extent.x long
Horizontal distance between tested pixels (height of the raster).
Default Value : 3
Value Suggestions : Column ¾1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21
Typical Range of Values : 1 Column 99 (lin)
Minimal Value Step : 2
Recommended Value Step : 2
Restriction : ´Column 1µ odd´Columnµ
HALCON/C Reference Manual / 2000-11-15

567
º Tolerance (input control) .................................................number double / long
Points with a gray value difference less then or equal to tolerance are accumulated into the same object.
Default Value : 6.0
Value Suggestions : Tolerance ¾1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 12.0, 14.0, 18.0, 25.0
Typical Range of Values : 1.0 Tolerance 127.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Restriction : ´0 Toleranceµ ´Tolerance 127µ
º MinSize (input control) .............................................................integer long
Minimum size of the output regions.
Default Value : 100
Value Suggestions : MinSize ¾1, 5, 10, 20, 50, 100, 200, 500, 1000
Typical Range of Values : 1 MinSize 1000 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Restriction : MinSize 1
Example
read_image(&Image,"fabrik");
mean_image(Image,&Mean,Row,Column);
regiongrowing(Mean,&Result,Row,Column,6,100);
Complexity
Let Æ be the number of found regions and Å the number of points in one of these regions. Then the runtime
complexity is Ç´Æ £ ÐÓ´Å µ £ Å µ.
Result
regiongrowing returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
regiongrowing is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
mean image, gauss image, smooth image, median image, anisotrope diff
Possible Successor Functions
select shape, reduce domain, select gray
Alternatives
regiongrowing n, (T )regiongrowing mean, label to region
Region processing
Module
regiongrowing mean ( Hobject Image, Hobject *Regions, long StartRows,
long StartColumns, double Tolerance, long MinSize )
T regiongrowing mean ( Hobject Image, Hobject *Regions,
Htuple StartRows, Htuple StartColumns, Htuple Tolerance, Htuple MinSize )
Regiongrowing using mean gray values.
(T )regiongrowing mean performs a regiongrowing using mean gray values of a region, starting from points
given by StartRows and StartColumns. At any point in the process the mean gray value of the current region
is calculated. Gray values at the boundary of the region are added to the region if they differ from the current mean
by less than Tolerance. Regions smaller than MinSize are suppressed.
If no starting points are given (empty tuples), the expansion process starts at the upper leftmost point, and is
continued with the first unprocessed point after a region has been created.
HALCON 6.0

568 CHAPTER 10. SEGMENTATION
Parameter
º Image (input object) ............................................image(-array) Hobject : byte / int4
Image to be segmented.
º Regions (output object) ...................................................region-array Hobject *
Extracted segments.
º StartRows (input control) ..........................................point.y(-array) (Htuple .) long
Row coordinates of the starting points.
Default Value : ’[]’
Typical Range of Values : 0 StartRows 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º StartColumns (input control) ......................................point.x(-array) (Htuple .) long
Column coordinates of the starting points.
Default Value : ’[]’
Typical Range of Values : 0 StartColumns 511 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
º Tolerance (input control) ..............................................number (Htuple .) double
Maximum deviation from the mean.
Default Value : 5.0
Value Suggestions : Tolerance ¾0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 12.0, 15.0, 17.0,
20.0, 25.0, 30.0, 40.0
Typical Range of Values : 0.1 Tolerance 100.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
Restriction : Tolerance 0.0
º MinSize (input control) ....................................................integer (Htuple .) long
Minimum size of a region.
Default Value : 100
Value Suggestions : MinSize ¾0, 10, 30, 50, 100, 500, 1000, 2000
Typical Range of Values : 0 MinSize 50000 (lin)
Minimal Value Step : 1
Recommended Value Step : 100
Restriction : MinSize 0
Result
(T )regiongrowing mean returns H MSG TRUE if all parameters are correct. The behavior with respect
to the input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
(T )regiongrowing mean is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gauss image, sigma image, anisotrope diff, median image
Possible Successor Functions
select shape, reduce domain, opening, expand region
regiongrowing, regiongrowing n
Region processing
Alternatives
Module
regiongrowing n ( Hobject MultiChannelImage, Hobject *Regions,
const char *Metric, double MinTolerance, double MaxTolerance,
long MinSize )
Regiongrowing for multi-channel images.
HALCON/C Reference Manual / 2000-11-15

569
regiongrowing n performs a multi-channel regiongrowing. The Ò channels give rise to an n-dimensional
feature vector. Neighboring points are aggregated into the same region if the difference of their feature vectors
with respect to the given metric lies in the interval [MinTolerance, MaxTolerance]. Only 4-connected
neighbors are examined. The following metrics can be used:
Let denote the gray value in the feature vector at point of the image, and likewise be the gray value
in the feature vector at point a neighboring point . Let´µ be the gray value with index . Furthermore, let
ÅÒÌ denote MinTolerance and ÅÜÌ denote MaxTolerance.
’1-norm’: Sum of absolute values
’2-norm’: Euclidian distance
’3-norm’: p - Norm with p = 3
’4-norm’: p - Norm with p = 4
’n-norm’: Minkowski distance
’max-diff’: Supremum distance
’min-diff’: Infimum distance
ÅÒÌ ½ Ò
ÅÜÌ
ÅÒÌ
ÖÈ
´ µ ¾
Ò
ÅÒÌ ¿ ÖÈ
´ µ ¿
Ò
ÅÒÌ ÖÈ
´ µ
Ò
ÅÒÌ Ò ÖÈ
´ µ Ò
Ò
ÅÜÌ
ÅÜÌ
ÅÜÌ
ÅÜÌ
ÅÒÌ ÑÜ ÅÜÌ
ÅÒÌ ÑÒ ÅÜÌ
’variance’: Variance of gray value differences
ÅÒÌ ÎÖ´ µ ÅÜÌ
’dot-product’: Dot product
’correlation’: Correlation
ÅÒÌ ½ Ò
ÎÖ ½ Ò
Õ
´ µ ÅÜÌ
Ñ ½ Ò
Õ
´ Ñ µ ¾
ÎÖ ½ Ò
Ñ ½ Ò
Õ
´ Ñ µ ¾
ÅÒÌ ½ Ò ¾ ´ Ñ µ´ Ñ µ
´ÎÖ ÎÖ µ
ÅÜÌ
’mean-diff’: Difference of arithmetic means
½ Ò
½ Ò
ÅÒÌ
ÅÜÌ
HALCON 6.0

570 CHAPTER 10. SEGMENTATION
’mean-ratio’: Ratio of arithmetic means
½ Ò
’length-diff’: Difference of the vector lengths
’length-ratio’: Ratio of the vector lengths
ÅÒÌ ÑÒ
ÅÒÌ
ÅÒÌ ÑÒ
½ Ò
ÖÈ
¾
Ò
ÖÈ
¾
Ò
ÖÈ
¾
Ò
ÖÈ
¾
Ò
ÅÜÌ
ÅÜÌ
ÅÜÌ
’n-norm-ratio’: Ratio of the vector lengths w.r.t the p-norm with Ô Ò
ÅÒÌ ÑÒ
’gray-max-diff’: Difference of the maximum gray values
Ò ÖÈ
Ò
Ò
ÖÈ
Ò
Ò
Ò
ÑÜ
ÑÜ
ÅÒÌ
’gray-max-ratio’: Ratio of the maximum gray values
ÅÒÌ ÑÒ
’gray-min-diff’: Difference of the minimum gray values
ÅÜÌ
ÅÜÌ
ÑÜ
ÑÜ
ÑÒ
ÑÒ
ÅÒÌ
ÅÜÌ
ÅÜÌ
HALCON/C Reference Manual / 2000-11-15

571
’gray-min-ratio’: Ratio of the minimum gray values
ÅÒÌ ÑÒ
ÑÒ
ÑÒ
ÅÜÌ
’variance-diff’: Difference of the variances over all gray values (channels)
ÅÒÌ ÎÖ´ µ ÎÖ´ µÅÜÌ
’variance-ratio’: Ratio of the variances over all gray values (channels)
ÅÒÌ ÎÖ´ µ
ÎÖ´ µ ÅÜÌ
’mean-abs-diff’: Difference of the sum of absolute values over all gray values (channels)
´µ ´µ
´µ
´µ
ÅÒÌ
Anzahl der Summen ÅÜÌ
’mean-abs-ratio’: Ratio of the sum of absolute values over all gray values (channels)
ÅÒÌ ÑÒ
´µ ´µ
´µ
´µ
ÅÜÌ
’max-abs-diff’: Difference of the maximum distance of the components
ÑÜ ´µ ´µ
ÑÜ ´µ ´µ
ÅÒÌ
ÅÜÌ
’max-abs-ratio’: Ratio of the maximum distance of the components
ÑÜ ´µ ´µ
ÑÜ ´µ ´µ
ÅÒÌ ÑÒ
ÅÜÌ
’min-abs-diff’: Difference of the minimum distance of the components
ÑÒ ´µ ´µ
ÑÒ ´µ ´µ
ÅÒÌ
ÅÜÌ
HALCON 6.0

572 CHAPTER 10. SEGMENTATION
’min-abs-ratio’: Ratio of the minimum distance of the components
ÑÒ ´µ ´µ
ÑÒ ´µ ´µ
ÅÒÌ ÑÒ
’plane’: The following has to hold for all ½ , ¾ ¾ ½Ò℄:
Regions with less than MinSize are suppressed.
ÅÜÌ
´ ½ µ ´ ¾ µ µ ´ ½ µ ´ ¾ µ
´ ½ µ ´ ¾ µ µ ´ ½ µ ´ ¾ µ
Parameter
º MultiChannelImage (input object) .................................image(-array) Hobject : byte
Multi-channel image to be segmented.
º Regions (output object) ...................................................region-array Hobject *
Segmented regions.
º Metric (input control) .........................................................string const char *
Metric for the distance of the feature vectors.
Default Value : ’2-norm’
Value List : Metric ¾’1-norm’, ’2-norm’, ’3-norm’, ’4-norm’, ’n-norm’, ’max-diff’, ’min-diff’,
’variance’, ’dot-product’, ’correlation’, ’mean-diff’, ’mean-ratio’, ’length-diff’, ’length-ratio’, ’n-norm-ratio’,
’gray-max-diff’, ’gray-max-ratio’, ’gray-min-diff’, ’gray-min-ratio’, ’variance-diff’, ’variance-ratio’,
’mean-abs-diff’, ’mean-abs-ratio’, ’max-abs-diff’, ’max-abs-ratio’, ’min-abs-diff’, ’min-abs-ratio’, ’plane’
º MinTolerance (input control) .............................................number double / long
Lower threshold for the features’ distance.
Default Value : 0.0
Value Suggestions : MinTolerance ¾0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 12.0, 14.0, 16.0,
18.0, 20.0, 25.0, 30.0
Typical Range of Values : 0.0 MinTolerance 255.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
º MaxTolerance (input control) .............................................number double / long
Upper threshold for the features’ distance.
Default Value : 20.0
Value Suggestions : MaxTolerance ¾0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 12.0, 14.0, 16.0,
18.0, 20.0, 25.0, 30.0
Typical Range of Values : 0.0 MaxTolerance 255.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 1.0
º MinSize (input control) .............................................................integer long
Minimum size of the output regions.
Default Value : 30
Value Suggestions : MinSize ¾1, 10, 25, 50, 100, 200, 500, 1000
Typical Range of Values : 1 MinSize 10000 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Result
regiongrowing n returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
regiongrowing n is reentrant and automatically parallelized (on tuple level).
compose2, compose3
Possible Predecessor Functions
HALCON/C Reference Manual / 2000-11-15

573
Alternatives
class 2dim sup, (T )class ndim norm, class ndim box
regiongrowing
Region processing
See Also
Module
threshold ( Hobject Image, Hobject *Region, double MinGray,
double MaxGray )
T threshold ( Hobject Image, Hobject *Region, Htuple MinGray,
Htuple MaxGray )
Select gray values lying within an interval.
(T )threshold selects the pixels from the input image whose gray values fulfill the following condition:
ÅÒÖÝ ÅÜÖÝ
All points of an image fulfilling the condition are returned as one region. If more than one gray value interval is
passed (tuples for MinGray and MaxGray), one separate region is returned for each interval.
Parameter
º Image (input object) .................image(-array) Hobject : byte / direction / cyclic / int2 / int4 / real
Image to be thresholded.
º Region (output object) ...................................................region(-array) Hobject *
Regions with gray values lying in the specified interval.
º MinGray (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double / long
Lower threshold for the gray values.
Default Value : 128.0
Value Suggestions : MinGray ¾0.0, 10.0, 30.0, 64.0, 128.0, 200.0, 220.0, 255.0
Typical Range of Values : 0.0 MinGray 255.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 5.0
º MaxGray (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double / long
Upper threshold for the gray values.
Default Value : 255.0
Value Suggestions : MaxGray ¾0.0, 10.0, 30.0, 64.0, 128.0, 200.0, 220.0, 255.0
Typical Range of Values : 0.0 MaxGray 255.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 5.0
Restriction : MaxGray MinGray
Example
read_image(&Image,"fabrik");
sobel_amp(Image,&EdgeAmp,"sum_abs",3);
threshold(EdgeAmp,&Seg,50.0,255.0);
skeleton(Seg,&Rand);
connection(Rand,&Lines);
select_shape(Lines,&Edges,"area","and",10.0,1000000.0);
Complexity
Let be the area of the input region. Then the runtime complexity is Ç´ µ.
Result
(T )threshold returns H MSG TRUE if all parameters are correct. The behavior with respect to the
input images and output regions can be determined by setting the values of the flags ’no object result’,
’empty region result’,and’store empty region’ with set system. If necessary, an exception is raised.
HALCON 6.0

574 CHAPTER 10. SEGMENTATION
Parallelization Information
(T )threshold is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
T histo to thresh, min max gray, sobel amp, gauss image, reduce domain,
fill interlace
Possible Successor Functions
connection, dilation1, erosion1, opening, closing, rank region, shape trans, skeleton
Alternatives
class 2dim sup, hysteresis threshold, dyn threshold
See Also
dual threshold, zero crossing, background seg, regiongrowing
Region processing
Module
threshold sub pix ( Hobject Image, Hobject *Border, double Threshold )
Extract level crossings from an image with subpixel accuracy.
threshold sub pix extracts the level crossings at the level Threshold of the input image Image with
subpixel accuracy. The extracted level crossings are returned as XLD-contours in Border. In contrast to the
operator (T )threshold, threshold sub pix does not return regions, but the lines which separate regions
with a gray value less than Threshold from regions with a gray value greater than Threshold.
For the extraction, the input image is regarded as a surface, in which the gray values are interpolated bilinearly
between the centers of the individual pixels. Consistent with the surface thus defined, level crossing lines are
extracted for each pixel and linked into topologically sound contours. This means that the level crossing contours
are correctly split at junction points. If the image contains extended areas of constant gray value Threshold,
only the border of such areas is returned as level crossings.
Parameter
º Image (input object) ......................singlechannel-image Hobject : byte / int1 / int2 / int4 / real
Input image.
º Border (output object) ...................................................xld cont-array Hobject *
Extracted level crossings.
º Threshold (input control) .................................................number double / long
Threshold for the level crossings.
Default Value : 128
Value Suggestions : Threshold ¾0.0, 10.0, 30.0, 64.0, 128.0, 200.0, 220.0, 255.0
Example
/* Detection zero crossings of the Laplacian-of-Gaussian of aerial image */
read_image(&Image,"fabrik");
threshold_sub_pix(Laplace,&Border,35);
disp_xld(Border,WindowHandle);
Result
threshold sub pix usually returns the value H MSG TRUE. If necessary, an exception is raised.
Parallelization Information
threshold sub pix is reentrant and processed without parallelization.
(T )threshold
zero crossing sub pix
Sub-pixel operators
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

575
watersheds ( Hobject GrayImage, Hobject *Basins, Hobject *Watersheds )
Extract watersheds and basins from an image.
watersheds segments an image based on the topology of the gray values. The image is interpreted as a “mountain
range.” Higher gray values correspond to “mountains,” while lower gray values correspond to “valleys.” In the
resulting mountain range watersheds are extracted. These correspond to the bright ridges between dark basins. On
output, the parameter Basins contains these basins, while Watersheds contains the watersheds, which are at
least one pixel wide (points on the ridge which form a plateau). Watersheds always is a single region per input
image, while Basins contains a separate region for each basin. It is advisable to apply a smoothing operator (e.g.,
gauss image) to the input image before calling watersheds in order to reduce the number of output regions.
Attention
If the image contains many fine structures or is noisy, many output regions result, and thus the runtime increases
considerably.
Parameter
º GrayImage (input object) ............................................image(-array) Hobject : byte
Images to be segmented.
º Basins (output object) .....................................................region-array Hobject *
Segments found (dark basins).
º Watersheds (output object) ..............................................region(-array) Hobject *
Watersheds between the basins.
Example
read_image(&Cells,"meningg5");
gauss_image(Cells,&CellsGauss,9);
invert_image(CellsGauss,&CellsInvert);
watersheds(CellsInvert,&Bassins,&Watersheds);
set_colored(WindowHandle,12);
disp_region(Bassins,WindowHandle);
Result
watersheds always returns H MSG TRUE. The behavior with respect to the input images and output regions
can be determined by setting the values of the flags ’no object result’, ’empty region result’, and
’store empty region’ with set system. If necessary, an exception is raised.
Parallelization Information
watersheds is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gauss image, smooth image, invert image
Possible Successor Functions
expand region, select shape, reduce domain, opening
pouring
Region processing
Alternatives
Module
zero crossing ( Hobject Image, Hobject *RegionCrossing )
Detect zero crossings in an image.
zero crossing returns the zero crossings of the input image as a region. A pixel is accepted as a zero crossing
if its gray value (in Image) is zero, or if at least one of its 4-connected neighbors has a different sign.
This operator is intended to be used after edge operators returning the second derivative of the image (e.g.,
laplace of gauss), which were possibly followed by a smoothing operator. In this case, the zero crossings
are (candidates for) edges.
HALCON 6.0

576 CHAPTER 10. SEGMENTATION
Parameter
º Image (input object) ........................................image(-array) Hobject : int2 / int4 / real
Input image.
º RegionCrossing (output object) ........................................region(-array) Hobject *
Zero crossings (as region).
Result
zero crossing usually returns the value H MSG TRUE. If necessary, an exception is raised.
Parallelization Information
zero crossing is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
laplace, laplace of gauss, derivate gauss
Possible Successor Functions
connection, skeleton, boundary, select shape, fill up
(T )threshold, dual threshold
Region processing
Alternatives
Module
zero crossing sub pix ( Hobject Image, Hobject *ZeroCrossings )
Extract zero crossings from an image with subpixel accuracy.
zero crossing sub pix extracts the zero crossings of the input image Image with subpixel accuracy. The
extracted zero crossings are returned as XLD-contours in ZeroCrossings. Thus, zero crossing sub pix
can be used as a sub-pixel precise edge extractor if the input image is a Laplace-filtered image (see laplace,
laplace of gauss, derivate gauss).
For the extraction, the input image is regarded as a surface, in which the gray values are interpolated bilinearly
between the centers of the individual pixels. Consistent with the surface thus defined, zero crossing lines are
extracted for each pixel and linked into topologically sound contours. This means that the zero crossing contours
are correctly split at junction points. If the image contains extended areas of constant gray value 0, only the border
of such areas is returned as zero crossings.
Parameter
º Image (input object) ............................singlechannel-image Hobject : int1 / int2 / int4 / real
Input image.
º ZeroCrossings (output object) .........................................xld cont-array Hobject *
Extracted zero crossings.
Example
/* Detection zero crossings of the Laplacian-of-Gaussian of aerial image */
read_image(&Image,"mreut");
derivate_gauss(Image,&Laplace,3,"laplace");
zero_crossing_sub_pix(Laplace,&ZeroCrossings);
disp_xld(ZeroCrossings,WindowHandle);
/* Detection of edges, i.e, zero crossings of the Laplacian-of-Gaussian
that have a large gradient magnitude, in an aerial image */
read_image(&Image,"mreut");
Sigma = 1.5;
/* Compensate the threshold for the fact that derivate_gauss(...,’gradient’)
calculates a Gaussian-smoothed gradient, in which the edge amplitudes
are too small because of the Gaussian smoothing, to correspond to a true
edge amplitude of 20. */
Threshold = 20/(Sigma*sqrt(2*PI));
HALCON/C Reference Manual / 2000-11-15

577
derivate_gauss(Image,&Gradient,Sigma,"gradient");
threshold(Gradient,&Region,Threshold,255);
reduce_domain(Image,Region,&ImageReduced);
derivate_gauss(ImageReduced,&Laplace,Sigma,"laplace");
zero_crossing_sub_pix(Laplace,&Edges);
disp_xld(Edges,WindowHandle);
Result
zero crossing sub pix usually returns the value H MSG TRUE. If necessary, an exception is raised.
Parallelization Information
zero crossing sub pix is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
laplace, laplace of gauss, diff of gauss, derivate gauss
zero crossing
Sub-pixel operators
Alternatives
Module
HALCON 6.0

578 CHAPTER 10. SEGMENTATION
HALCON/C Reference Manual / 2000-11-15

Chapter 11
System
11.1 Database
count relation ( const char *RelationName, long *NumOfTuples )
Number of entries in the HALCON database.
The operator count relation counts the number of entries in one of the four relations of the HALCON
database. The HALCON database is organized as follows:
There are two basic relations for ÖÓÒ Ø and Ñ ÑØÖ×. The HALCON objects ÖÓÒ and Ñ
are constructed from elements from these two relations: a region consists of a pointer to a tuplet in the region-data
relation. An image consists also of a pointer to a tuplet in the region-data relation (like a region) and additionally
of one or more pointers to tuplets in the matrix relation. If there is more than one matrix pointer, the image is called
a ÑÙÐØ ÒÒÐ Ñ.
Both regions and images are called ÓØ×. A region can be considered as the special case of an iconic object
having no image matrixes. For reasons of an efficient memory managment, the tuplets of the region-data relation
and the image-matrix relation ÛÐÐ Ù× Ý ÖÒØ ÓØ× ØÓØÖ. Therefore there may be for example
more images than image matrices. Only the two lowlevel relations are of relevance to the memory consumption.
Image objects (regions as well as images) consist only of references on region and matrix data and therefore only
need a couple of bytes of memory.
Possible values for RelationName:
’image’: Image matrices. One matrix may also be the component of more than one image (no redundant storage).
’region’: Regions (the full and the empty region are always available). One region may of course also be the
component of more than one image object (no redundant storage).
’XLD’: eXtended Line Description: Contours, Polygons, paralles, lines, etc. XLD data types don’t have gray
values and are stored with subpixel accuracy.
’object’: Iconic objects. Composed of a region (called region) and optionally image matrices (called image).
’tuple’: In the compact mode, tuplets of iconic objects are stored as a surrogate in this relation. Instead of working
with the individual object keys, only this tuplet key is used. It depends on the host language, whether the
objects are passed individually (Prolog and C++) or as tuplets (C, Smalltalk, Lisp, OPS-5).
Certain database objects will be created already by the operator reset obj db and therefore have to be available
all the time (the undefined gray value component, the objects ’full’ (FULL REGION in HALCON/C) and
’empty’ (EMPTY REGION in HALCON/C) as well as the herein included empty and full region). By calling
get channel info, the operator therefore appears correspondingly also as ’creator’ of the full and empty region.
The procedure can be used for example to check the completeness of the clear obj operation.
579

580 CHAPTER 11. SYSTEM
Parameter
º RelationName (input control) .................................................string const char *
Relation of interest of the HALCON database.
Default Value : ’object’
Value List : RelationName ¾’image’, ’region’, ’XLD’, ’object’, ’tuple’
º NumOfTuples (output control) .....................................................integer long *
Number of tuplets in the relation.
Example
reset_obj_db(512,512,3) ;
count_relation("image",&I1) ;
count_relation("region",&R1) ;
count_relation("XLD",&X1) ;
count_relation("object",&O1) ;
count_relation("tuple",&T1) ;
read_image(&X,"monkey") ;
count_relation("image",&I2) ;
count_relation("region",&R2) ;
count_relation("XLD",&X2) ;
count_relation("object",&O2) ;
count_relation("tuple",&T2) ;
/*
Result: I1 = 1 (undefined image)
R1 = 2 (full and empty region)
X1 = 0 (no XLD data)
O1 = 2 (full and empty objects)
T1 = 0 (always 0 in the normal mode)
*/
I2 = 2 (additionally the image ’monkey’)
R2 = 2 (read_image uses the full region)
X2 = 0 (no XLD data)
O2 = 3 (additionally the image object X)
T2 = 0.
Result
If the parameter is correct, the operator count relation returns the value H MSG TRUE. Otherwise an exception
is raised.
Parallelization Information
count relation is reentrant and processed without parallelization.
reset obj db
clear obj
System
Possible Predecessor Functions
See Also
Module
T get modules ( Htuple *UsedModules, Htuple *ModuleKey )
Query of used modules and the module key.
T get modules returns the module numbers of all operators used up to this point. Each operator belongs to
one module (maximum 32). Each module has a name, which is returned in UsedModules. Based on the used
modules, a key is generated that is needed for the licence manager. T get modules is normally called at the end
of a programm to check the used modules.
HALCON/C Reference Manual / 2000-11-15

11.1. DATABASE 581
Parameter
º UsedModules (output control) .........................................string-array Htuple . char *
Names of used modules.
º ModuleKey (output control) ................................................integer Htuple . long *
Key for licence manager.
Parallelization Information
T get modules is reentrant and processed without parallelization.
Operators not requiring licensing
Module
reset obj db ( long DefaultImageWidth, long DefaultImageHeight,
long DefaultChannels )
Initialization of the HALCON system.
The operator reset obj db initializes the HALCON system. With this procedure the four relations (grayvalue
data, region data, iconic objects and object tuplets) which are necessary for image processing with HALCON will
be installed (see also count relation). In case the relations already exist, all tuplets in the relations will be
deallocated!
The parameters DefaultImageWidth and DefaultImageHeight provide the initial values for the global
maximum image size. If the first created object is an image, (e.g. read image), the set values will be overruled
in Standard-HALCON by the size of this picture. Instead of this, in Parallel HALCON the set values will only be
changed, if they are smaller than the size of the created object. If on the other hand the first object to be created
is a region, both in Standard- and in Parallel HALCON the values will only be adjusted in case the new image is
larger than the set values. This is not only the case for the first image which is created or read: the global image
size will always be enlarged, if larger images are created.
The global image size is of consequence for the opening of windows (open window) and the clipping of
regions. Whenever the clip mode is activated, regions will be clipped according to the global image size
((T )set system(’clip region’,’true’)). This can lead to problems if images of various sizes are
used. In this case only the fact that a region is smaller or of the same size as the largest image can be guaranteed.
The parameter DefaultChannels returns the most frequent number of channels of an image object. This value
can be set to 0 if for the most part regions are used. If more channels than those having been set at the initialization
are necessary for one image, the number will be enlarged dynamically for this image. If less channels than those
having been set at the initialization are necessary for the image, the superfluous channels will be set as undefined.
For the user this will seem as if they were non existent, however, memory is allocated unnecessarily.
The parameter values can be queried using the operator (T )get system.
Attention
If the operator reset obj db is not called at the beginning of a HALCON session, HALCON will be initialized
automatically by the operator reset obj db(128,128,0). In case the operator reset obj db is called
again, all image objects in the database will be deallocated.
Parameter
º DefaultImageWidth (input control) ................................................integer long
Default image width (in pixels).
Default Value : 128
Value Suggestions : DefaultImageWidth ¾64, 128, 256, 512, 525, 1024
º DefaultImageHeight (input control) ..............................................integer long
Default image height (in pixels).
Default Value : 128
Value Suggestions : DefaultImageHeight ¾64, 128, 256, 512, 768, 1024
º DefaultChannels (input control) ..................................................integer long
Usual number of channels by which the system constant ’max channels’ is limited.
Default Value : 0
Value Suggestions : DefaultChannels ¾0, 1, 2, 3, 4, 5, 6, 7
HALCON 6.0

582 CHAPTER 11. SYSTEM
Result
The operator reset obj db returns the value H MSG TRUE if the parameter values are correct. Otherwise an
exception will be raised.
Parallelization Information
reset obj db is reentrant and processed without parallelization.
get channel info, count relation
Operators not requiring licensing
See Also
Module
11.2 Error-Handling
T get check ( Htuple *Check )
State of the HALCON control modes.
Executing the operator T get check the user can inquire what kind of control modes are currently activated and
which are not. Check gives the tuplet containing the names of the control modes (see also (T )set check)
which are preceded by a tilde (˜, e.g. ’˜data’), if the corresponding control is deactivated.
Parameter
º Check (output control) .................................................string-array Htuple . char *
Tuplet of the currently activated control modes.
Result
T get check always returns the value H MSG TRUE.
Parallelization Information
T get check is reentrant and processed without parallelization.
(T )set check
(T )set check
System
Possible Predecessor Functions
See Also
Module
get error text ( long ErrorNumber, char *ErrorText )
Inquiry after the error text of a HALCON error number.
The operator get error text returns the error text for the corresponding HALCON error number. This is
indeed the same text which will be given during an exception. The operator get error text is especially useful
if the error treatment is programmed by the users themselves (see also (T )set check(’˜give error’:)).
Attention
Unknown error numbers will trigger a standard message.
Parameter
º ErrorNumber (input control) ........................................................integer long
Number of the HALCON error.
Restriction : ´1 ErrorNumberµ ´ErrorNumber 36000µ
º ErrorText (output control) .........................................................string char *
Corresponding error text.
HALCON/C Reference Manual / 2000-11-15

11.2. ERROR-HANDLING 583
Example
Herror
char
err;
message[MAX_STRING];
set_check("˜give_error");
err = send_region(region,socket_id);
set_check("give_error");
if (err != MESS_TRUE) {
get_error_text((long)err,message);
fprintf(stderr,"my error message: %s\n",message);
exit(1);
}
Result
The operator get error text always returns the value H MSG TRUE.
Parallelization Information
get error text is reentrant and processed without parallelization.
(T )set check
(T )set check
System
Possible Predecessor Functions
See Also
Module
get spy ( const char *Class, char *Value )
Current configuration of the HALCON debugging-tool.
The operator get spy returns the current configuration of spy, the HALCON debugging tool. The available
control modes (possible choices for Class) as well as the corresponding tuning possibilities (possible values for
Value) can be called up by using the operator T query spy. You will find a more detailed description under
set spy.
Parameter
º Class (input control) ..........................................................string const char *
Control mode
Default Value : ’mode’
Value List : Class ¾’mode’, ’procedure’, ’input control’, ’output control’, ’parameter values’,
’input gray window’, ’output gray window’, ’input region window’, ’db’, ’output region window’, ’halt’,
’timeout’, ’button window’, ’button window’, ’button click’, ’button notify’, ’log file’, ’error’, ’internal’
º Value (output control) .............................................string char * / long * / double *
State of the control mode.
Result
The operator get spy returns the value H MSG TRUE if the parameter Class is correct. Otherwise an exception
is raised.
Parallelization Information
get spy is reentrant and processed without parallelization.
reset obj db
set spy, T query spy
System
Possible Predecessor Functions
See Also
Module
HALCON 6.0

584 CHAPTER 11. SYSTEM
T query spy ( Htuple *Classes, Htuple *Values )
Inquiring for possible settings of the HALCON debugging tool.
The operator T query spy returns all possible settings of spy, the HALCON debugging tool, i.e. all the available
control modes (Classes) as well as the corresponding possible ways of setting (Values). For a more detailed
description of spy see operator set spy.
Attention
The values of Values cannot be used as direct input for set spy, as they are transmitted as a symbolic constant.
Parameter
º Classes (output control) ..............................................string-array Htuple . char *
Available control modes (see also set spy).
º Values (output control) ................................................string-array Htuple . char *
Corresponding state of the control modes.
Result
query spy always returns the value H MSG TRUE.
Parallelization Information
T query spy is reentrant, local, and processed without parallelization.
reset obj db
set spy, get spy
System
Possible Predecessor Functions
See Also
Module
set check ( const char *Check )
T set check ( Htuple Check )
Activating and deactivating of HALCON control modes.
With the help of the operator (T )set check different control modes of the HALCON system can be activated
or deactivated. If a certain control mode is activated, parameters etc. will be checked at runtime. Whenever an
inconsistency is hereby detected, the program will be interrupted by an exception.
It is recommendable to activate the control modes during the development of a program and to deactivate them
only after a successfully concluded testrun. For if the control mode is deactivated and an error occurs, the system
may react in an unpredictable way.
The HALCON system provides various possible control modes which can be activated and deactivated independently.
By calling the operator (T )set check with the name (Check) of the desired control mode, this control
mode is activated; the control mode is deactivated by passing its name prefixed with a tilde (˜, z.B. ’˜data’).
Available control modes:
’color’: If this control mode is activated, only colors may be used which are supported by the display for the
currently active window. Otherwise an error message is displayed.
In case of deactivated control mode and non existent colors, the nearest color is used (see also set color,
set gray, set rgb).
’text’: If this control mode is activated, it will check the coordinates during the setting of the text cursor as well
as during the display of strings (write string) to the effect whether a part of a sign would lie outside the
windowframe (a fact which is not forbidden in principle by the system).
If the control mode is deactivaed, the text will be clipped at the windowframe.
’parameter’: (For HALCON/PRO only)
If this control mode is activated, output parameter may not be instantiated by calling a procedure.
Otherwise a normal unification mechanism is used.
HALCON/C Reference Manual / 2000-11-15

11.2. ERROR-HANDLING 585
’data’: (For program development)
Checks the consistency of image objects (regions and grayvalue components.
’interface’: If this control mode is activated, the interface between the host language and the HALCON procedures
will be checked in course (e.g. typifying and counting of the values).
’database’: This is a consistency check of the database (e.g. checks whether an object which shall be canceled
does indeed exist or not.)
’give error’: Determines whether errors shall trigger exceptions or not. If this control modes is deactivated,
the application program must provide a suitable error treatment itself. Please note that errors which are
not reported usually lead to undefined output parameters which may cause an unpredictable reaction of the
program.
’father’: If this control mode is activated by calling the operator open window, HALCON allows only the usage
of the number of another HALCON window as the ”‘father”’ of the new window; otherwise it allows also
other X Window IDs.
’region’: For program development)
Checks the consistency of chords (this may lead to a notable speed reduction of routines).
’clear’: Normally, if a list of objects shall be canceled by using clear obj, an exception will be raised, in case
individual objects do not or no longer exist. If the ’clear’ mode is activated, such objects will be ignored.
’all’: Activates all control modes.
’none’: Deactivates all control modes.
’default’: Original setting.
Parameter
º Check (input control) ..........................................string(-array) (Htuple .) const char *
Desired control mode.
Default Value : ’default’
Value List : Check ¾’color’, ’text’, ’database’, ’data’, ’interface’, ’give error’, ’father’, ’region’, ’clear’,
’all’, ’none’, ’default’
Result
The operator (T )set check returns the value H MSG TRUE, if the parameters are correct. Otherwise an
exception will be raised.
Parallelization Information
(T )set check is reentrant and processed without parallelization.
See Also
T get check, set color, set rgb, set hsi, write string
System
Module
set spy ( const char *Class, const char *Value )
Control of the HALCON Debugging Tools.
The operator set spy is the HALCON debugging tool. This tool allows the flexible control of the input and
output data of HALCON-operators - in graphical as well as in textual form. The datacontrol is activated by using
set spy(’mode’,’on’),
and deactivated by using
set spy(’mode’,’off’).
The debugging tool can further be activated with the help of the environment variable HALCONSPY. The definition
of this variable corresponds to calling up ’mode’ and ’on’.
The following control modes can be tuned (in any desired combination of course) with the help of Class/Value:
Class Meaning / Value
HALCON 6.0

586 CHAPTER 11. SYSTEM
’operator’ When a routine is called, its name and the names of its parameters will be given (in TRIAS notation).
Value: ’on’ or ’off’
default: ’off’
’input control’ When a routine is called, the names and values of the input control parameters will be given.
Value: ’on’ or ’off’
default: ’off’
’output control’ When a routine is called, the names and values of the output control parameters are given.
Value: ’on’ or ’off’
default: ’off’
’parameter values’ Additional information on ’input control’ and ’output control’: indicates how many values
per parameter shall be displayed at most (maximum tuplet length of the output).
Value: tuplet length (integer)
default: 4
’db’ Information concerning the 4 relations in the HALCON-database. This is especially valuable in looking for
forgotten clear obj.
Value: ’on’ or ’off’
default: ’off’
’input gray window’ Any reading access of the gray-value component of an (input) image object will cause the
gray-value component to be shown in the indicated window (Window-ID; ’none’ will deactivate this control
).
Value: Window-ID (integer) or ’none’
default: ’none’
’output gray window’ As soon as the gray-value component of an (output) image object is set, spy will show
this gray-value component in the indicated window (Window-ID; ’none’ will deactivate this control).
Value: Window-ID (integer) or ’none’
default: ’none’
’input region window’ Any reading access of the region of an (input) iconic object will cause this region to be
shown in the indicated (Window-ID; ’none’ will deactivate this control ).
Value: Window-ID (integer) or ’none’
default: ’none’
’output region window’ As soon as the region of an (output) iconic object is set, spy will show this region in the
indicated window (Window-ID; ’none’ will deactivate this control ).
Value: Window-ID (integer) or ’none’
default: ’none’
’time’ Processing time of the operator
Value: ’on’ or ’off’
default: ’off’
’halt’ Determines whether there is a halt after every individual action (’multiple’) or only at the end of each operator
(’single’). The parameter is only effective if the halt has been activated by ’timeout’ or ’button window’.
Value: ’single’ or ’multiple’
default: ’multiple’
’timeout’ After every output there will be a halt of the indicated number of seconds.
Value: seconds (real)
default 0.0
’button window’ Alternative to ’timeout’: after every output spy waits until the cursor indicates (’button click’ =
’false’) or clicks into (’button click’ = ’true’) the indicated window. (Window-ID; ’none’ will deactivate this
control ).
Value: Window-ID (integer) or ’none’
default: ’none’
’button click’ Additional option for ’button window’: determines whether or not a mouse-click has to be waited
for after an output.
Value: ’on’ or ’off’
default: ’off’
’button notify’ If ’button notify’ is activated, spy generates a beep after every output. This is useful in combination
with ’button window’.
HALCON/C Reference Manual / 2000-11-15

11.3. INFORMATION 587
Value: ’on’ or ’off’
default: ’off’
’log file’ Spy can hereby divert the text output into a file having been opened with open file.
Value: a file handle (see open file)
’error’ If ’error’ is activated and an internal error occurs, spy will show the internal procedures (file/line) concerned.
Value: ’on’ or ’off’
default: ’off’
’internal’ If ’internal’ is activated, spy will display the internal procedures and their parameters (file/line) while
an HALCON-operator is processed.
Value: ’on’ or ’off’
default: ’off’
Parameter
º Class (input control) ..........................................................string const char *
Control mode
Default Value : ’mode’
Value List : Class ¾’mode’, ’operator’, ’input control’, ’output control’, ’parameter values’,
’input gray window’, ’db’, ’time’, ’output gray window’, ’output region window’, ’input region window’,
’halt’, ’timeout’, ’button window’, ’button click’, ’button notify’, ’log file’, ’error’, ’internal’
º Value (input control) ............................................string const char * / long / double
State of the control mode to be set.
Default Value : ’on’
Value Suggestions : Value ¾’on’, ’off’, 1, 2, 3, 4, 5, 10, 50, 0.0, 1.0, 2.0, 5.0, 10.0
Example
/* init spy: Setting of the wished control modi */
set_spy("mode","on");
set_spy("operator","on");
set_spy("input_control","on");
set_spy("output_control","on");
/* calling of program section, that will be examined */
set_spy("mode","off");
Result
The operator set spy returns the value H MSG TRUE if the parameters are correct. Otherwise an exception is
raised.
Parallelization Information
set spy is reentrant, local, and processed without parallelization.
reset obj db
get spy, T query spy
System
Possible Predecessor Functions
See Also
Module
11.3 Information
disp info ( const char *ProcName, const char *Machine,
const char *DispProgram, const char *Extension )
Display the manual information of a procedure on the screen.
The operator disp info together with the previewer DispProgram shows the manual entry of the indicated
procedure on the screen. The individual files (Name: .Extension) are located in the HALCON-Directory
HALCON 6.0

588 CHAPTER 11. SYSTEM
”‘doc/ps/reference/LANGUAGE/*”’, whereby the value for LANGUAGE will be determined by the currently
used host language. The directory can also be generated with the help of the operator (T )set system
(’reference dir’,’Pfad’).
Parameter
º ProcName (input control)..................................................proc name const char *
Name of the seeked procedure.
Default Value : ’read image’
º Machine (input control) .......................................................string const char *
Name of the computer to which the data shall be transmitted or empty string.
Default Value : ”
º DispProgram (input control) ..................................................string const char *
Name of the program which shall display the help text.
Default Value : ’ghostview’
Value Suggestions : DispProgram ¾’gs’, ’ghostview’
º Extension (input control) .....................................................string const char *
Extension of the helpfile.
Default Value : ’ps’
Result
If the parameter values are correct and the file and the program are available, the operator disp info returns the
value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
disp info is reentrant and processed without parallelization.
open window
Image / region / XLD management
See Also
Module
T get chapter info ( Htuple Chapter, Htuple *Info )
Get information concerning the chapters on procedures.
The operator T get chapter info gives information concerning the chapters on procedures. If instead of
Chapter the empty string is transmitted, the routine will provide in Info the names of all chapters. If on the
other hand a certain chapter or a chapter and its subchapter(s) are indicated (by a tuple of names), the corresponding
subchapters or - in case there are no further subchapters - the names of the corresponding procedures will be given.
The organization of the chapters on procedures is the same as the organization of chapters and subchapters in the
HALCON-manual. Please note: The chapters on procedures respectively the subchapters concerning an individual
procedure can be called by using the operator T get operator info(,’chapter’,Info).
The Online-texts will be taken from the files english.hlp, english.sta, english.num and english.idx, which will be
searched by HALCON in the currently used directory or the directory ’help dir’ (see also (T )get system and
(T )set system).
Parameter
º Chapter (input control).........................................string(-array) Htuple . const char *
Procedure class or subclass of interest.
Default Value : ”
º Info (output control) ..................................................string-array Htuple . char *
Procedure classes (Chapter = ”) or procedure subclasses respectively procedures.
Result
If the parameter values are correct and the helpfile is available, the operator T get chapter info returns the
value H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
T get chapter info is processed completely exclusively without parallelization.
Possible Predecessor Functions
(T )get system, (T )set system
HALCON/C Reference Manual / 2000-11-15

11.3. INFORMATION 589
See Also
T get operator info, (T )get system, (T )set system
Image / region / XLD management
Module
T get keywords ( Htuple ProcName, Htuple *Keywords )
Get keywords which are assigned to procedures.
The operator T get keywords returns all the keywords in the online-texts corresponding to those procedures
which have the indicated substring ProcName in their name. If instead of ProcName the empty string is transmitted,
the operator T get keywords returns all keywords. The keywords of an individual procedure can also be
called by using the operator T get operator info. The online-texts will be taken from the files english.hlp,
english.sta, english.num, english.key and english.idx, which are searched by HALCON in the currently used
directory and in the directory ’help dir’ (see also (T )get system and (T )set system).
Parameter
º ProcName (input control) .........................................proc name Htuple . const char *
Substring in the names of those procedures for which keywords are needed.
Default Value : ’get keywords’
º Keywords (output control) .............................................string-array Htuple . char *
Keywords for the procedures.
Result
The operator T get keywords returns the value H MSG TRUE if the parameters are correct and the helpfiles
are available. Otherwise an exception handling is raised.
Parallelization Information
T get keywords is processed completely exclusively without parallelization.
T get chapter info
T get operator info
Possible Predecessor Functions
Alternatives
See Also
T get operator name, T search operator, T get param info
Image / region / XLD management
Module
T get operator info ( Htuple ProcName, Htuple Slot,
Htuple *Information )
Get information concerning a HALCON-procedure.
With the help of the operator T get operator info the online-texts concerning a certain procedure can be
called (see also T get operator name). The form of information available for all procedures (Slot) can be
called using the operator T query operator info. For the time being the following slots are available:
’short’: Short description of the procedure.
’abstract’: Description of the procedure.
’procedure class’: Name(s) of the chapter(s) in the procedure hierarchy (chapter, subchapter in the HALCON
manual).
’functionality’: Functionality is equivalent to the object class to which the procedure can be assigned.
’keywords’: Keywords of the procedure (optional).
’example’: Example for the use of the procedure (optional). The operator ’example.LANGUAGE’ (LANGUAGE
¾c,c++,smalltalk,trias) calls up examples for a certain language if available. If the language is not indicated
or if no example is available in this language, the TRIAS-example will be returned.
HALCON 6.0

590 CHAPTER 11. SYSTEM
’complexity’: Complexity of the procedure (optional).
’effect’: Not in use so far.
’alternatives’: Alternative procedures (optional).
’see also’: Procedures containing further information (optional).
’predecessor’: Possible and sensible predecessor
’successor’: Possible and sensible successor
’result state’: Return value of the procedure (TRUE, FALSE, FAIL, VOID or EXCEPTION).
’attention’: Restrictions and advice concering the correct use of the procedure (optional).
’parameter’: Names of the parameter of the procedure (see also T get param info).
’references’: Literary references (optional).
’module’: The module to which the operator is assigned.
’html path’: The directory where the HTML documentation of the operator resides.
’parameter relations’: Assurances concerning the parameters (optional).
The texts will be taken from the files english.hlp, english.sta, english.key, english.num und english.idx which will
be searched by HALCON in the currently used directory or in the directory ’help dir’ (respectively ’user help dir’)
(see also (T )get system and (T )set system). By adding ’.latex’ after the slotname, the text of slots
containing textual information can be made available in L A TEX notation.
Parameter
º ProcName (input control) .........................................proc name Htuple . const char *
Name of the procedure on which more information is needed.
Default Value : ’get operator info’
º Slot (input control) ....................................................string Htuple . const char *
Desired information.
Default Value : ’abstract’
Value List : Slot ¾’short’, ’abstract’, ’procedure class’, ’functionality’, ’effect’, ’complexity’,
’predecessor’, ’successor’, ’alternatives’, ’see also’, ’keywords’, ’example’, ’attention’, ’result state’,
’return value’, ’references’, ’sourcefiles’, ’deffile’, ’module’, ’html path’
º Information (output control) .........................................string-array Htuple . char *
Information (empty if no information is available)
Result
The operator T get operator info returns the value H MSG TRUE if the parameters are correct and the
helpfiles are availabe. Otherwise an exception handling is raised.
Parallelization Information
T get operator info is processed completely exclusively without parallelization.
Possible Predecessor Functions
T get keywords, T search operator, T get operator name, T query operator info,
T query param info, T get param info
Possible Successor Functions
T get param names, get param num, T get param types
T get param names
Alternatives
See Also
T query operator info, T get param info, T get operator name, get param num,
T get param types
Module
Image / region / XLD management
T get operator name ( Htuple Pattern, Htuple *ProcNames )
Get procedures with the given string as a substring of their name.
HALCON/C Reference Manual / 2000-11-15

11.3. INFORMATION 591
The operator T get operator name takes a string (Pattern) as input and searches all HALCON-procedures
having this string as a substring in their name. If an empty string is entered, the names of all procedures available
will be returned.
Parameter
º Pattern (input control) ...............................................string Htuple . const char *
Substring of the seeked names (empty all names).
Default Value : ’info’
º ProcNames (output control) ............................................string-array Htuple . char *
Detected procedure names.
Result
The operator T get operator name returns the value H MSG TRUE if the helpfiles are available. Otherwise
an exception handling is raised.
Parallelization Information
T get operator name is reentrant, local, and processed without parallelization.
Possible Successor Functions
T get operator info, T get param names, get param num, T get param types
T search operator
Alternatives
See Also
T get operator info, T get param names, get param num, T get param types
Image / region / XLD management
Module
T get param info ( Htuple ProcName, Htuple ParamName, Htuple Slot,
Htuple *Information )
Get information concerning the procedure parameters.
The operator T get param info is used for calling up the online-texts assigned to a parameter of an indicated
procedure. The form of information available for each parameter (Slot), can be called up by using the operator
T query param info. At the moment the following slots are available:
’description’: Description of the parameter.
’description.latex’: Description of the parameter in L A TEX notation.
’parameter class’: Parameter classes: ’input object’, ’output object’, ’input control’ oder ’output control’.
’type list’: Permitted type(s) of data for parameter values (for control parameters only). Value: ’real’, ’integer’
oder ’string’.
’default type’: Default-type for parameter values (for control parameters only). This type of parameter is the one
HALCON/C uses in the ”‘simple mode”’. If ’none’ is indicated, the ”‘tuple mode”’ must be used. Value:
’real’, ’integer’, ’string’ oder ’none’.
’sem type’: Semantic type of the parameter. This is important to allow the assignment of the parameters to object
classes in object-oriented languages (C++, Smalltalk). If more than one parameter belongs semantically to
one type, this fact is indicated as well. So far the the following objects are supported:
object, image, region, xld,
xld cont, xld para, xld poly, xld ext para, xld mod para,
integer, real, number, string,
channel, grayval, window,
histogram, distribution,
point(.x, .y), extent(.x, .y),
angle(.rad oder .deg),
circle(.center.x, .center.y, .radius),
arc(.center.x, .center.y, .angle.rad, .begin.x, .begin.y),
ellipse(.center.x, .center.y, .angle.rad, .radius1, .radius2),
line(.begin.x, .begin.y, .end.x, .end.y)
HALCON 6.0

592 CHAPTER 11. SYSTEM
rectangle(.origin.x, .origin.y, .corner.x, .corner.y
bzw. .extent.x, .extent.y),
polygon(.x, .y), contour(.x, .y),
coordinates(.x, .y), chord(.x1, .x2, .y),
chain(.begin.x, .begin.y, .code).
’default value’: Default-value for the parameter (for input-control parameters only). It is the question of mere
information only (the parameter value must be transmitted explicitly, even if the default-value is used). This
entry serves only as a notice, a point of departure for own experiments. The values have been selected so that
they normally do not cause any errors but generate something that makes sense.
’multi value’: ’true’, if more than one value is permitted in this parameter position, otherwise ’false’.
’multichannel’: ’true’, in case the input image object may be multichannel.
’mixed type’: For control parameters exclusively and only if value tuples (’multivalue’-’true’) and various types
of data are permitted for the parameter values (’type list’ having more than one value). In this case Slot
indicates, whether values of various types may be mixed in one tuple (’true’ or ’false’).
’values’: Selection of values (optional).
’value list’: In case a parameter can take only a limited number of values, this fact will be indicated explicitly
(optional).
’valuemin’: Minimum value of a value interval.
’valuemax’: Maximum value of a value interval.
’valuefunction’: Function discribing the course of the values for a series of tests (lin, log, quadr, ...).
’steprec’: Recommended step width for the parameter values in a series of tests.
’steprec’: Minimum step width of the parameter values in a series of tests.
’valuenumber’: Expression describing the number of parameters as such or in relation to other parameters.
’assertion’: Expression describing the parameter values as such or in relation to other parameters.
The online-texts will be taken from the files english.hlp, english.sta, english.key, english.num and english.idx
which will be searched by HALCON in the currently used directory or the directory ’help dir’ (see also
(T )get system and (T )set system).
Parameter
º ProcName (input control) .........................................proc name Htuple . const char *
Name of the procedure on whose parameter more information is needed.
Default Value : ’get param info’
º ParamName (input control) .............................................string Htuple . const char *
Name of the parameter on which more information is needed.
Default Value : ’Slot’
º Slot (input control) ....................................................string Htuple . const char *
Desired information.
Default Value : ’description’
Value List : Slot ¾’description’, ’type list’, ’default type’, ’sem type’, ’default value’, ’values’,
’value list’, ’valuemin’, ’valuemax’, ’valuefunction’, ’valuenumber’, ’assertion’, ’steprec’, ’stepmin’,
’mixed type’, ’multivalue’, ’multichannel’
º Information (output control) .........................................string-array Htuple . char *
Information (empty in case there is no information available).
Result
The operator T get param info returns the value H MSG TRUE if the parameters are correct and the helpfiles
are available. Otherwise an exception handling is raised.
Parallelization Information
T get param info is processed completely exclusively without parallelization.
Possible Predecessor Functions
T get keywords, T search operator
Alternatives
T get param names, get param num, T get param types
HALCON/C Reference Manual / 2000-11-15

11.3. INFORMATION 593
See Also
T query param info, T get operator info, T get operator name
Image / region / XLD management
Module
T get param names ( Htuple ProcName, Htuple *InpObjPar,
Htuple *OutpObjPar, Htuple *InpCtrlPar, Htuple *OutpCtrlPar )
Get the names of the parameters of a HALCON-procedure.
For the HALCON-procedure indicated in ProcName the operator T get param names returns the names of
the input objects, the output objects, of the input control parameters and the output control parameters.
Parameter
º ProcName (input control) .........................................proc name Htuple . const char *
Name of the procedure.
Default Value : ’get param names’
º InpObjPar (output control) ............................................string-array Htuple . char *
Names of the input objects.
º OutpObjPar (output control) ..........................................string-array Htuple . char *
Names of the output objects.
º InpCtrlPar (output control) ..........................................string-array Htuple . char *
Names of the input control parameters.
º OutpCtrlPar (output control) .........................................string-array Htuple . char *
Names of the output control parameters.
Result
The operator T get param names returns the value H MSG TRUE if the name of the procedure exists and the
helpfiles are available. Otherwise an exception handling is raised.
Parallelization Information
T get param names is reentrant and processed without parallelization.
Possible Predecessor Functions
T get keywords, T search operator, T get operator name, T get operator info
Possible Successor Functions
get param num, T get param types
Alternatives
T get operator info, T get param info
See Also
get param num, T get param types, T get operator name
Image / region / XLD management
Module
get param num ( const char *ProcName, char *CName, long *InpObjPar,
long *OutpObjPar, long *InpCtrlPar, long *OutpCtrlPar, char *Type )
Get number of the different parameter classes of a HALCON-procedure.
The operator get param num returns the number of the input and output object parameters, as well as the input
and output control parameters for the indicated HALCON-procedure. Further, you will receive the name of the
C-function (CName) called by the procedure. The output parameter Type indicates, whether the procedure is a
system procedure or an user procedure.
HALCON 6.0

594 CHAPTER 11. SYSTEM
Parameter
º ProcName (input control)..................................................proc name const char *
Name of the procedure.
Default Value : ’get param num’
º CName (output control) ..............................................................string char *
Name of the called C-function.
º InpObjPar (output control) ........................................................integer long *
Number of the input object parameters.
º OutpObjPar (output control) ......................................................integer long *
Number of the output object parameters.
º InpCtrlPar (output control) ......................................................integer long *
Number of the input control parameters.
º OutpCtrlPar (output control) .....................................................integer long *
Number of the output control parameters.
º Type (output control) ................................................................string char *
System procedure or user procedure.
Value Suggestions : Type ¾’system’, ’user’
Result
The operator get param num returns the value H MSG TRUE if the name of the procedure exists. Otherwise
an exception handling is raised.
Parallelization Information
get param num is reentrant and processed without parallelization.
Possible Predecessor Functions
T get keywords, T search operator, T get operator name, T get operator info
T get param types
Possible Successor Functions
Alternatives
T get operator info, T get param info
See Also
T get param names, T get param types, T get operator name
Image / region / XLD management
Module
T get param types ( Htuple ProcName, Htuple *InpCtrlParType,
Htuple *OutpCtrlParType )
Get default data type for the control parameters of a HALCON-procedure.
The operator T get param types returns the default data type for each input and output control parameter.
The default type of a parameter is the type used in ”‘simple mode”’ in HALCON/C. This concerns parameters
which allow more than one type as for example write string. Hereby the types of input parameters are
combined in the variable InpCtrlParType, whereas the types of output parameters are combined in the variable
OutpCtrlParType. The following types are possible:
’integer’: an integer.
’integer tuple’: an integer or a tuple of integers.
’real’: a floating point number.
’real tuple’: a floating point number or a tuple of floating point numbers.
’string’: a string.
’string tuple’: a string or a tuple of strings.
’no default’: individual value of which the type cannot be determined.
’no default tuple’: individual value or tuple of values of which the type cannot be determined.
HALCON/C Reference Manual / 2000-11-15

11.3. INFORMATION 595
’default’: individual value of unknown type, whereby the systems assumes it to be an ’integer’.
Parameter
º ProcName (input control) .........................................proc name Htuple . const char *
Name of the procedure.
Default Value : ’get param types’
º InpCtrlParType (output control) .....................................string-array Htuple . char *
Default type of the input control parameters.
º OutpCtrlParType (output control) ...................................string-array Htuple . char *
Default type of the output control parameters.
Result
The operator T get param types returns the value H MSG TRUE if the indicated procedure name exists.
Otherwise an exception handling is raised.
Parallelization Information
T get param types is reentrant and processed without parallelization.
Possible Predecessor Functions
T get keywords, T search operator, T get operator name, T get operator info
T get param info
Alternatives
See Also
T get param names, get param num, T get operator info, T get operator name
Image / region / XLD management
Module
T query operator info ( Htuple *Slots )
Query slots concerning information with relation to the operator T get operator info.
The operator T query operator info returns the names of those online texts (Slots) which are available
online for each procedure. The information itself can be called up using
T get operator info(,).
Parameter
º Slots (output control) .................................................string-array Htuple . char *
Slotnames of the operator T get operator info.
Result
The operator T query operator info always returns the value H MSG TRUE.
Parallelization Information
T query operator info is local and processed completely exclusively without parallelization.
T get operator info
T get operator info
Image / region / XLD management
Possible Successor Functions
See Also
Module
T query param info ( Htuple *Slots )
Query slots of the online-information concerning the operator T get param info.
The operator T query param info returns the names of those pieces of information (Slots) which are available
online for each parameter (online texts). The online texts themselves can be called up using
T get param info(,,).
HALCON 6.0

596 CHAPTER 11. SYSTEM
Parameter
º Slots (output control) .................................................string-array Htuple . char *
Slotnames for the operator T get param info.
Result
T query param info always returns the value H MSG TRUE.
Parallelization Information
T query param info is reentrant, local, and processed without parallelization.
T get param info
T get param info
Image / region / XLD management
Possible Successor Functions
See Also
Module
T search operator ( Htuple Keyword, Htuple *ProcNames )
Search names of all procedures assigned to one keyword.
The operator T search operator returns the names of all procedures whose online-texts include the keyword
Keyword (see also T get operator info). All available keywords are called by using the operator
T get keywords(’’ ). The online-texts are taken from the files english.hlp, english.sta, english.key,
english.num and Halcon.idx, which are searched by HALCON in the currently used directory or the
directory ’help dir’ (see also (T )get system and (T )get system).
Parameter
º Keyword (input control) ...............................................string Htuple . const char *
Keyword for which corresponding procedures are searched.
Default Value : ’Information’
º ProcNames (output control) ............................................string-array Htuple . char *
Procedures whose slot ’keyword’ contains the keyword.
Result
The operator T search operator returns the value H MSG TRUE if the parameters are correct and the helpfiles
are available. Otherwise an exception handling is raised.
Parallelization Information
T search operator is processed completely exclusively without parallelization.
T get keywords
Possible Predecessor Functions
See Also
T get keywords, T get operator info, T get param info
Image / region / XLD management
Module
11.4 Operating-System
count seconds ( double *Seconds )
Elapsed processing time since the last call of count seconds.
The operator count seconds helps to measure the runtime. The first call of the procedure normally returns a
zero. Each further call returns the processing time which has elapsed in the meantime in seconds. The C-function
”‘clock’” is used for the measurement.
HALCON/C Reference Manual / 2000-11-15

11.4. OPERATING-SYSTEM 597
Attention
The time measurement is not exact and depends on the load of the computer.
Parameter
º Seconds (output control) ...........................................................real double *
Processtime since the program start.
Example
count_seconds(&Start);
/* aktion to be measured */
count_seconds(&End);
printf("RunTime = %g\n",End-Start);
Result
The operator count seconds always returns the value H MSG TRUE.
Parallelization Information
count seconds is reentrant and processed without parallelization.
System
Module
system call ( const char *Command )
Executes a system command.
The operator system call executes the system command specified by the string pointed to by Command (Cprocedure
”‘system”’). If the string is empty, an interactive shell will be started (’csh -i’).
Parameter
º Command (input control) .......................................................string const char *
Command to be called by the system.
Default Value : ’ls’
Result
If the entered operator can be executed by the system, the operator system call returns the value
H MSG TRUE. Otherwise an exception will be raised.
Parallelization Information
system call is reentrant and processed without parallelization.
count seconds
wait seconds, count seconds
System
Possible Predecessor Functions
See Also
Module
wait seconds ( double Seconds )
Delaying the execution of the program.
The operator wait seconds delays the execution by the number of seconds indicated in Seconds.
Parameter
º Seconds (input control) ..............................................................real double
Number of seconds by which the execution of the program will be delayed.
Default Value : 10
Restriction : Seconds 0
HALCON 6.0

598 CHAPTER 11. SYSTEM
Result
The operator wait seconds always returns the value H MSG TRUE.
Parallelization Information
wait seconds is reentrant and processed without parallelization.
system call
system call, count seconds
System
Possible Successor Functions
See Also
Module
11.5 Parallelization
check par hw potential ( long AllInpPars )
Check hardware regarding its potential for parallel processing.
check par hw potential is necessary for an efficient automatic parallelization, which is used by HALCON
to better utilize multiprocessor hardware in order to speed up the processing of operators. As the parallelization
of operators is done automatically, there is no need for the user to explicitely prepare or change programs for
their parallelization. Thus, all HALCON-based programs can be used unchanged on multiprocessor hardware and
nevertheless utilize the potential of parallel hardware. check par hw potential checks a given hardware
with respect to a parallel processing of HALCON operators. At this, it examines every operator, which can be
sped up in principle by an automatic parallelization. Each examined operator is processed several times - both
sequentially and in parallel - with a changing set of input parameter values/images. The latter helps to evaluate
dependencies between an operator’s input parameter characteristics (e.g. the size of an input image) and the
efficiency of its parallel processing. At this, AllInpPars is used in the following way: In the normal case,
i.e. if AllInpPars contains the default value 0 (“false”), only those input parameters are examined which are
supposed to show influence on the processing time. Other parameters are not examined so that the whole process is
sped up. However, in some rare cases, the internal implementation of a HALCON operator might change from one
HALCON release to another. Then, a parameter which did not show any direct influence on the processing time in
former releases, may now show such an influence. In this case it is necessary to set AllInpPars to 1 (“true”) in
order to force the examination of all input parameters. If this happens, the HALCON release notes will most likely
contain an appropriate note about this fact. Overall, check par hw potential performs several test loops and
collects a lot of hardware-specific informations, which enable HALCON to optimize the automatic parallelization
for a given hardware. The hardware information is stored so that it can be used again in future HALCON sessions.
Thus, it is sufficient, to start check par hw potential once on each multiprocessor machine that is used for
parallel processing. Of course, it should be started again, if the hardware of the machine changes, for example,
by installing a new cpu, or if the operating system of the machine changes, or if the machine gets a new host
name. The latter is necessary, because HALCON identifies the machine-specific parallelization information by
the machine’s host name. If the same multiprocessor machine is used with different operating systems, such
as Windows and Linux, it is necessary to start check par hw potential once for each operating system
in order to correctly measure the rather strong influence of the operating system on the potential of exploiting
multiprocessor hardware. Under Windows, HALCON stores the parallelization knowledge, which belongs to a
specific machine, in the machine’s registry. At this, it uses a machine-specific registry key, which can be used by
different users simultaneously. In the normal case, this key can be written or changed by any user under Windows
NT. However, under Windows 2000 the key may only be changed by users with administrator privileges or by
users which at least belong to the “power user” group. For all other users check par hw potential shows
no effect (but does not return an error). Under Linux/UNIX the parallelization information is stored in a file in the
HALCON installation directory ($HALCONROOT). Again this means that check par hw potential must
be called by users with the appropriate privileges, here by users which have write access to the HALCON directory.
If HALCON is used within a network under Linux/UNIX, the denoted file contains the information about every
computer in the network for which the hardware check has been successfully completed.
Attention
During its test loops check par hw potential has to start every examined operator several times. Thus,
HALCON/C Reference Manual / 2000-11-15

11.5. PARALLELIZATION 599
the processing of check par hw potential can take rather a long time. check par hw potential
bases on the automatic parallelization of operators which is exclusively supported by Parallel HALCON. Thus,
check par hw potential always returns an appropriate error, if it used with a non-parallel HALCON version.
check par hw potential must be called by users with the appropriate privileges for storing the parallelization
information permanently (see the operator’s description above for more details about this subject).
Parameter
º AllInpPars (input control) .........................................................integer long
Check every input parameter?
Default Value : 0
Value List : AllInpPars ¾0, 1
Result
check par hw potential returns H MSG TRUE if all parameters are correct.
Parallelization Information
check par hw potential is local and processed completely exclusively without parallelization.
store par knowledge
Possible Successor Functions
See Also
store par knowledge, load par knowledge
System
Module
load par knowledge ( const char *FileName )
Load knowledge about automatic parallelization from file.
load par knowledge supports the automatic parallelization of HALCON operators, which is used to better utilize
multiprocessor hardware in order to speed up the processing of operators. To parallelize the processing of operators
automatically HALCON needs some specific knowledge about the used hardware. This hardware-specific
knowledge can be obtained by using the operator check par hw potential. In the normal case, HALCON
stores this knowledge in a specific file in the HALCON installation directory (Linux/UNIX) or within the “registry”
(Windows). This enables HALCON to use the knowledge again later on. With load par knowledge
it is possible to load this knowledge explicitely from an ASCII file. At this, FileName denotes the name of
this file (incl. path and file extension). The file must conform to a specific syntax and must have been stored
beforehand by using store par knowledge. While reading the file load par knowledge checks whether
its content was written for the currently used computer and whether the contained parallelization information regards
the currently used HALCON version (and revision). If this is the case, load par knowledge adopts the
information so that it will also be used with further HALCON sessions. Otherwise, the information is ignored and
load par knowledge returns an appropriate error message.
Parameter
º FileName (input control) .............................................filename.named const char *
Name of parallelization knowledge file.
Default Value : ”
Result
load par knowledge returns H MSG TRUE if all parameters are correct.
Parallelization Information
load par knowledge is local and processed completely exclusively without parallelization.
store par knowledge
Possible Predecessor Functions
See Also
store par knowledge, check par hw potential
System
Module
HALCON 6.0

600 CHAPTER 11. SYSTEM
store par knowledge ( const char *FileName )
Store knowledge about automatic parallelization in file.
store par knowledge supports the automatic parallelization of HALCON operators, which is used to better
utilize multiprocessor hardware in order to speed up the processing of operators. To parallelize the processing
of operators automatically HALCON needs some specific knowledge about the used hardware. This hardwarespecific
knowledge can be obtained by calling the operator check par hw potential. There, HALCON
stores the knowledge in a specific file in the HALCON installation directory (Linux/UNIX) or within the “registry”
(Windows). This enables HALCON to use the knowledge again later on. With store par knowledge it is
possible to store this knowledge explicitely as an ASCII file. At this, FileName denotes the name of this file (incl.
path and file extension). The stored knowledge can be read again later on by using load par knowledge.
Parameter
º FileName (input control) .............................................filename.named const char *
Name of parallelization knowledge file.
Default Value : ”
Result
store par knowledge returns H MSG TRUE if all parameters are correct.
Parallelization Information
store par knowledge is local and processed completely exclusively without parallelization.
check par hw potential
load par knowledge
Possible Predecessor Functions
Possible Successor Functions
See Also
load par knowledge, check par hw potential
System
Module
11.6 Parameters
get system ( const char *Query, long *Information )
T get system ( Htuple Query, Htuple *Information )
Information concerning the currently used HALCON system parameter.
The operator (T )get system returns information concerning the currently activated HALCON system parameters.
Some of these parameters can be changed dynamically by using the operator (T )set system. They
are marked by a + in the list below. By passing the string ’?’ as the parameter Query, the names of all system
parameters are provided with Information.
The following system parameters can be queried:
Versions
’version’: HALCON version number, e.g.: 6.0
’last update’: Date of creation of the HALCON library
’revision’: Revision number of the HALCON library, e.g.: 1
Upper Limits
’max contour length’: Maximum number of contour respectively polygone control points of a region.
’max images’: Maximum total of images.
’max channels’: Maximum number of channels of an image.
’max obj per par’: Maximum number of image objects which may be used during one call up per parameter
HALCON/C Reference Manual / 2000-11-15

11.6. PARAMETERS 601
’max inp obj par’: Maximum number of input parameters.
’max outp obj par’: Maximum number of output parameters.
’max inp ctrl par’: Maximum number of input control parameters.
’max outp ctrl par’: Maximum number of output control parameters.
’max window’: Maximum number of windows.
’max window types’: Maximum number of window systems.
’max proc’: Maximum number of HALCON procedures (system defined + user defined).
Graphic
+’flush graphic’: Determines, whether the flush operation is called or not after each HALCON procedure.
+’int2 bits’: Number of significant bits of int2 images. This number is used when scaling the gray values.
If the values is -1 the gray values will be automatically scaled (default).
+’int zooming’: Determines if the zooming of images is done with integer arithmetic or with floating point
arithmetic.
+’draw mode’: (no description available)
+’ignore colormap’: (no description available)
+’backing store’: Storage of the window contents in case of overlaps.
+’icon name’: (no description available)
+’window name’: (no description available)
+’default font’: Name of the font to set at opening the window.
+’single lut’: (no description available)
+’update lut’: (no description available)
+’x package’: Number of bytes which are sent to the X server during each transfer of data.
+’num gray 4’: Number of colors reserved under X Xindows concerning the output of graylevels
(disp channel) on a machine with 4 bitplanes (16 colors).
+’num gray 6’: Number of colors reserved under X Window concerning the output of graylevels
(disp channel) on a machine with 6 bitplanes (64 colors).
+’num gray 8’: Number of colors reserved under X Window concerning the output of graylevels
(disp channel) on a machine with 8 bitplanes (256 colors).
+’num gray percentage’: HALCON reserves a certain amount of the available colors under X Window
for the representation of graylevels (disp image). This shall interfere with other X applications
as little as possible. However, if HALCON does not succeed in reserving a miminum percentage of
’num gray percentage’ of the necessary colors on the X server, a certain amount of the lookup-table will
be claimed for the HALCON graylevels regardless of the consequences for other applications.
This may result in undesired shifts of color when switching between HALCON windows and windows
of other applications, or if (outside HALCON) a window-dump is generated. The number of the real
graylevels to be reserved depends on the number of available bitplanes on the outputmachine (see also
’num gray *’. Naturally no colors will be reserved on monochrome machines - the graylevels will
instead be dithered when displayed. If graylevel displays are used, only different shades of gray will be
applied (’black’, ’white’, ’gray’, etc.). Machines with 2 or 3 bitplanes will be considered monochrome
machines, machines with 5 (7) bitplanes like machines with 4 (6) bitplanes, and machines having more
than 8 bitplanes like machines with 8 bitplanes. A special case are machines providing a 24 bit display
(true color machines). Naturally no colors are reserved for the display of graylevels in this case.
Note: Before the first window on a machine with x bitplanes is opened, num gray x indicates the number
of colors which have to be reserved for the display of graylevels, afterwards, however, it will indicate
the number of colors which actually have been reserved.
+’num graphic percentage’: (no description available)
+’num graphic 2’: Number of the HALCON graphic colors reserved under X Window (for disp region
etc.) on a machine with 2 bitplanes (4 colors).
+’num graphic 4’: Number of the HALCON graphic colors reserved under X Window (for disp region
etc.) on a machine with 4 bitplanes (16 colors).
+’num graphic 6’: Number of the HALCON graphic colors reserved under X Window (for disp region
etc.) on a machine with 6 bitplanes (64 colors).
+’num graphic 8’: Number of the HALCON graphic colors reserved under X Window (for disp region
etc.) on a machine with 8 bitplanes (256 colors).
HALCON 6.0

602 CHAPTER 11. SYSTEM
Image Processing
+’neighborhood’: Using the 4 or 8 neighborhood.
+’only lines’: (no description available)
+’init new image’: Initialization of images before applying grayvalue transformations.
+’no object result’: Behavior for an empty object lists.
+’empty region result’: Reaction of procedures concerning input objects with empty regions which
actually are not useful for such objects (e.g. certain region features, segmentation, etc.). Possible return
values:
’true’: the error will be ignored if possible
’false’: the procedure returns FALSE
’fail’: the procedure returns FAIL
’void’: the procedure returns VOID
’exception’: an exception is raised
+’store empty region’: Storing of objects with empty regions.
+’clip region’: Clipping of output regions so that they fit the global image size.
’width’: Global maximum image width - in Standard-HALCON this value contains the maximum image
width of all HALCON image objects which are currently stored in memory. In Parallel HALCON
this value contains the maximum image width of all HALCON image objects which are or were in
memory since the start of the current HALCON session (this also includes objects which may be deleted
meanwhile).
’height’: Global maximum image height - in Standard-HALCON this value contains the maximum image
height of all HALCON image objects which are currently stored in memory. In Parallel HALCON
this value contains the maximum image height of all HALCON image objects which are or were in
memory since the start of the current HALCON session (this also includes objects which may be deleted
meanwhile).
’obj images’: Current number of grayvalue components per image object.
+’current runlength number’: Currently used number of chords which can be used for the encoding of
regions.
Parallelization
+’parallelize operators’: Determines whether Parallel HALCON uses an automatic parallelization to speed
up the processing of operators on multiprocessor machines.
+’reentrant’: Denotes whether Parallel HALCON currently supports reentrancy (default case), or whether
this feature has been switched off. Reentrancy is necessary for the automatic parallelization of Parallel
HALCON and for calling and processing multiple HALCON operators in parallel within multithreaded
applications.
’processor num’: Returns the number of processors which Parallel HALCON has found on the hardware it
is running on. This also indicates the number of processors which is used by Parallel HALCON for the
automatic parallelization of operators.
File
+’flush file’: Buffering of file output.
Directories
+’image dir’: Path which will searched for the image file after the default directory (see also:
read image).
+’lut dir’: Path for the default directory for color tables (see also: set lut).
+’reference dir’: Path for the default directory concerning the postscript HALCON documentation.
+’help dir’: Path for the default help directory for the online help files:
german,english.hlp,sta,idx,num,key.
Other
+’do low error’: Flag, if low level error should be printed.
’num proc’: Total number of the available HALCON procedures (’num sys proc’ + ’num user proc’).
’num sys proc’: Number of the system procedures (supported procedures).
’num user proc’: Number of the user defined procedures (see also ’Extension Packages’ manual).
’byte order’: Byte order of the processor (’msb first’ or ’lsb first’).
HALCON/C Reference Manual / 2000-11-15

11.6. PARAMETERS 603
’operating system’: Name of the operating system of the computer on which the HALCONprocess is being
executed.
’operating system version’: Version number of the operating system of the computer on which the HAL-
CON process is being executed.
+’alloctmp single block’: Flag for kind of temporary memory management.
’temp mem’: Amount of temporary memory used by the last operator. This feature is only supported by
Standard-HALCON. Instead of this, Parallel HALCON returns the amount of temporary memory used
by (T )get system itself.
+’language’: Language used for error messages (’english’ or ’german’).
Parameter
º Query (input control) ..........................................string(-array) (Htuple .) const char *
Desired system parameter.
Default Value : ’width’
Value List : Query ¾”?”, ’version’, ’last update’, ’revision’, ’max images’, ’max channels’,
’max obj per par’, ’max inp obj par’, ’max outp obj par’, ’max inp ctrl par’, ’max outp ctrl par’,
’max window’, ’max window types’, ’max proc’, ’flush graphic’, ’int2 bits’, ’int zooming’, ’draw mode’,
’ignore colormap’, ’backing store’, ’icon name’, ’window name’, ’default font’, ’single lut’, ’update lut’,
’x package’, ’num gray 4’, ’num gray 6’, ’num gray 8’, ’num gray percentage’, ’num graphic 2’,
’num graphic 4’, ’num graphic 6’, ’num graphic 8’, ’num graphic percentage’, ’neighborhood’,
’only lines’, ’init new image’, ’no object result’, ’empty region result’, ’store empty region’, ’clip region’,
’width’, ’height’, ’obj images’, ’current runlength number’, ’flush file’, ’image dir’, ’lut dir’, ’reference dir’,
’help dir’, ’num proc’, ’num sys proc’, ’num user proc’, ’temp mem’, ’alloctmp single block’,
’do low error’, ’reentrant’, ’parallelize operators’, ’processor num’, ’byte order’, ’operating system’,
’operating system version’, ’language’
º Information (output control) . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long * / double * / char *
Current value of the system parameter.
Result
The operator (T )get system returns the value H MSG TRUE if the parameters are correct. Otherwise an
exception is raised.
Parallelization Information
(T )get system is local and processed completely exclusively without parallelization.
reset obj db
(T )set system
(T )set system
System
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
set system ( const char *Systemparameter, const char *Value )
T set system ( Htuple Systemparameter, Htuple Value )
Setting of HALCON system parameters.
The operator (T )set system allows to change different system parameters with relation to the runlength.
Available system parameters:
’neighborhood’: This parameter is used with all procedures which examine neighborhood relations:
connection, get region contour, get region chain, get region polygon,
get region thickness, boundary, paint region, disp region, fill up, contlength,
shape histo all.
HALCON 6.0

604 CHAPTER 11. SYSTEM
Value: 4or8
default: 8
’default font’: Whenever a window is opened, a font will be set for the text output, whereby the ’default font’
will be used. If the preset font cannot be found, another fontname can be set before opening the window.
Value: Filename of the fonts
default: fixed
’single lut’: (no description available) default: ’false’
’update lut’ Determines whether the HALCON color tables are adapted according to their environment or not.
Value: ’true’ or ’false’
default: ’false’
’image dir’: Image files (e.g. read image and read sequence) will be looked for in the currently used
directory and in ’image dir’ (if no absolute paths are indicated). More than one directory name can be
indicated (searchpaths), seperated by semicolons (Windows NT) or colons (Unix). The path can also be
determined using the environment variable HALCONIMAGES.
Value: Name of the filepath
default: ’$HALCONROOT/images’ bzw. ’%HALCONROOT%/images’
’lut dir’: Color tables (set lut) which are realized as an ASCII-file will be looked for in the currently used
directory and in ’lut dir’ (if no absolute paths are indicated). If HALCONROOT is set, HALCON will search
the color tables in the sub-directory ”‘lut”’.
Value: Name of the filepath
default: ’$HALCONROOT/lut’ bzw. ’%HALCONROOT%/lut’
’reference dir’: The HTML and postscript sources of the HALCON documentation (especially the HALCON
manual itself) will be looked for in the currently used directory or in ’reference dir’. This system parameter
is necessary for example using the operator disp info. This parameter can also be set by the environment
variable HALCONROOT before initializing HALCON. In this case the variable must indicate the directory
above the help directories (that is the HALCON-Homedirectory): e.g.: ’/usr/local/halcon’
Value: Name of the filepath
default: ’$HALCONROOT/doc/ps/reference/c’ bzw. ’%HALCONROOT%/doc/ps/reference/c’
’help dir’: The online text files german or english.hlp, .sta, .key .num and .idx will be looked for in the currently
used directory or in ’help dir’. This system parameter is necessary for instance using the operators
T get operator info and T get param info. This parameter can also be set by the environment
variable HALCONROOT before initializing HALCON. In this case the variable must indicate the directory
above the helpdirectories (that is the HALCON-Homedirectory): e.g.: ’/usr/local/halcon’
Value: Name of the filepath
default: ’$HALCONROOT/help’ bzw. ’%HALCONROOT%/help’
’only lines’: (no description available) default: ’true’
’init new image’: Determines whether new images shall be set to 0 before using filters. This is not necessary if
always the whole image is filtered of if the data of not filtered image areas are unimportant.
Value: ’true’ or ’false’
default: ’true’
’no object result’: Determines how operations processing iconic objects shall react if the object tuplet is empty
(= no objects). Available values for Value:
’true’: the error will be ignored
’false’: the procedure returns FALSE
’fail’: the procedure returns FAIL
’void’: the procedure returns VOID
’exception’: an exception is raised
default: ’true’
’empty region result’: Controls the reaction of procedures concerning input objects with empty regions which
actually are not useful for such objects (e.g. certain region features, segmentation, etc.). Available values for
Value:
’true’: the error will be ignored if possible
’false’: the procedure returns FALSE
’fail’: the procedure returns FAIL
’void’: the procedure returns VOID
’exception’: an exception is raised
default: ’true’
HALCON/C Reference Manual / 2000-11-15

11.6. PARAMETERS 605
’store empty region’: Quite a number of operations will lead to the creation of objects with an empty region (=
no image points) (e.g. intersection,threshold, etc.). This parameter determines whether the object
with an empty region will be returned as a result (’true’) or whether it will be ignored (’false’) that is no result
will be returned.
Value: ’true’ or ’false’
default: ’true’
’backing store’: Determines whether the window content will be refreshed in case of overlapping of the windows.
Some implementations of X Window are faulty; in order to avoid these errors, the storing of contents
can be deactivated. It may be recommendable in some cases to deactivate the security mechanism, if e.g.
performance / memory is what matters.
Value: true or false
default: true
’flush graphic’: After each HALCON procedure which creates a graphic output, a flush operation will be executed
in order to display the data immediately on screen. This is not necessary with all programs (e.g. if
everything is done with the help of the mouse). In this case ’flush graphic’ can be set to ’false’ to improve
the runlength.
Value: ’true’ or ’false’
default: ’true’
’flush file’: This parameter determines whether the output into a file (also to the terminal) shall be buffered or
not. If the output is to be buffered, in general the data will be displayed on the terminal only after entering
the operator fnew line.
Value: ’true’ or ’false’
default: ’true’
’x package’: The output of image data via the network may cause errors owing to the heavy load on the computer
or on the network. In order to avoid this, the data are transmitted in small packages. If the computer is used
locally, these units can be enlarged at will. This can lead to a notably improved output performance.
Value: package size (in bytes)
default: 20480
’int2 bits’: Number of significant bits of int2 images. This number is used when scaling the gray values. If the
values is -1 the gray values will be automatically scaled (default).
Value: -1 or 9..15
default: -1
’num gray 4’: Number of colors to be reserved under X Window to allow the output of graylevels disp channel
on a machine with 4 bitplanes (16 colors).
Attention! This value may only be changed before the first window has been opened on the machine.
Value: 2-12
default: 8
’num gray 6’: Number of colors to be reserved under X Window to allow the output of graylevels disp channel
on a machine with 6 bitplanes (64 colors).
Attention! This value may only be changed before the first window has been opened on the machine.
Value: 2-62
default: 50
’num gray 8’: Number of colors to be reserved under X Window to allow the output of graylevels disp channel
on a machine with 8 bitplanes (256 colors).
Attention! This value may only be changed before the first window has been opened on the machine.
Value: 2 - 254
default: 140
’num gray percentage’: Under X Window HALCON reserves a part of the available colors for the representation
of gray values (disp channel). This shall interfere with other X applications as little as possible.
However, if HALCON does not succeed in reserving a miminum percentage of ’num gray percentage’ of
the necessary colors on the X server, a certain amount of the lookup table will be claimed for the HALCON
graylevels regardless of the consequences. This may result in undesired shifts of color when switching between
HALCON windows and windows of other applications, or (outside HALCON) if a window-dump is
generated. The number of the real graylevels to be reserved depends on the number of available bitplanes on
the outputmachine (see also ’num gray *’. Naturally no colors will be reserved on monochrome machines -
the graylevels will instead be dithered when displayed. If graylevel-displays are used, only different shades
HALCON 6.0

606 CHAPTER 11. SYSTEM
of gray will be applied (’black’, ’white’, ’gray’, etc.). Machines with 2 or 3 bitplanes will be considered
monochrome machines, machines with 5 (7) bitplanes like machines with 4 (6) bitplanes, and machines having
more than 8 bitplanes like machines with 8 bitplanes. A special case are machines providing a 24 bit
display (true color machines). Naturally no colors are reserved for the display of graylevels in this case.
Note: This value may only be changed before the first window has been opened on the machine. For before
opening the first window on a machine with x bitplanes, num gray x indicates the number of colors which
have to be reserved for the display of graylevels, afterwards, however, it will indicate the number of colors
which actually have been reserved.
Value: 0 - 100
default: 30
’num graphic percentage’: (no description available) default: 60
’draw mode’: (no description available) default: ’complement’
’int zooming’: (no description available) default: ’true’
’ignore colormap’: (no description available) default: ’false’
’icon name’: (no description available) default: ’default’
’num graphic 2’: Number of the graphic colors to be reserved by HALCON under X Window (concerning the
operators disp region etc.) on a machine with 2 bitplanes (4 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0-2
default: 2
’num graphic 4’: Number of the graphic colors to be reserved by HALCON under X Window (concerning the
operators disp region etc.) on a machine with 4 bitplanes (16 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0-14
default: 5
’num graphic 6’: Number of the graphic colors to be reserved by HALCON under X Window (concerning the
operators disp region etc.) on a machine with 6 bitplanes (64 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0-62
default: 10
’num graphic 8’: Number of the graphic colors to be reserved by HALCON under X Window (concerning the
operators disp region etc.) on a machine with 8 bitplanes (256 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0-64
default: 20
’graphic colors’ HALCON reserves the first num graphic x colors form this list of color names as graphic colors.
As a default HALCON uses this same list which is also returned by using query all colors. However,
the list can be changed individually: hereby a tuplet of color names will be returned as value. It is recommendable
that such a tuplet always includes the colors ’black’ and ’white’, and optionally also ’red’, ’green’
and ’blue’. If ’default’ is set as Value, HALCON returns to the initial setting. Note: On graylevel machines
not the first x colors will be reserved, but the first x shades of gray from the list.
Attention: This value may only be changed before the first window has been opened on the machine.
Value: Tuplets of X Window color names
default: see also query all colors
’current runlength number’: Regions will be stored internally in a certain runlengthcode. This parameter can
determine the maximum number of chords which may be used for representing a region. Please note that
some procedures raise the number on their own if necessary.
The value can be enlarged as well as reduced.
Value: maximum number of chords
default: 50000
’clip region’: Determines whether the regions of iconic objects of the HALCON database will be clipped to
the currently used image size or not. This is the case for example in procedures like gen circle,
gen rectangle1 or dilation1.
See also: reset obj db
Value: ’true’ or ’false’
default: ’true’
HALCON/C Reference Manual / 2000-11-15

11.6. PARAMETERS 607
’do low error’ Determines whether the HALCON should print low level error or not.
Value: ’true’ or ’false’
default: ’false’
’reentrant’ Determines whether HALCON must be reentrant for being used within a parallel programming environment
(e.g. a multithreaded application). This parameter is only of importance for Parallel HALCON,
which can process several operators concurrently. Thus, the parameter is ignored by the sequentially working
HALCON-Version. If it is set to ’true’, Parallel HALCON internally uses synchronization mechanisms to
protect shared data objects from concurrent accesses. Though this is inevitable with any effectively parallel
working application, it may cause undesired overhead, if used within an application which works purely
sequentially. The latter case can be signalled by setting ’reentrant’ to ’false’. This switches off all internal
synchronization mechanisms and thus reduces overhead. Of course, Parallel HALCON then is no longer
thread-safe, which causes another side-effect: Parallel HALCON will then no longer use the internal parallelization
of operators, because this needs reentrancy. Setting ’reentrant’ to ’true’ resets Parallel HALCON
to its default state, i.e. it is reentrant (and thread-safe) and it uses the automatic parallelization to speed up
the processing of operators on multiprocessor machines.
Value: ’true’ or ’false’
default: Parallel HALCON: ’true’, otherwise: ’false’
’parallelize operators’ Determines whether Parallel HALCON uses an automatic parallelization to speed up the
processing of operators on multiprocessor machines. This feature can be switched off by setting ’parallelize
operators’ to ’false’. Even then Parallel HALCON will remain reentrant (and thread-safe), unless the
parameter ’reentrant’ is changed via (T )set system accordingly. Changing ’parallelize operators’ can
be helpful, for example, if HALCON-operators are called by a multithreaded application, which also does
the scheduling and load-balancing of operators and data by itself. Then it may be undesired that HALCON
performs additional parallelization steps, which may disturb the application’s scheduling and load-balancing
concepts. The parameter ’parallelize operators’ is only supported by Parallel HALCON and thus ignored by
the sequentially working HALCON-Version.
Value: ’true’ or ’false’
default: Parallel HALCON: ’true’, otherwise: ’false’
’alloctmp single block’ Kind of temporary memory management. Value: ’true’ or ’false’
default: ’false’
’language’ Language used for error messages. Value: ’english’ or ’german’. default: ’ english’
Parameter
º Systemparameter (input control) ............................string(-array) (Htuple .) const char *
Name of the system parameter to be changed.
Default Value : ’image dir’
Value List : Systemparameter ¾’neighborhood’, ’default font’, ’single lut’, ’update lut’, ’image dir’,
’lut dir’, ’reference dir’, ’help dir’, ’only lines’, ’init new image’, ’no object result’, ’empty region result’,
’store empty region’, ’backing store’, ’flush graphic’, ’flush file’, ’x package’, ’int2 bits’, ’icon name’,
’num gray 4’, ’num gray 6’, ’num gray 8’, ’num gray percentage’, ’num graphic 2’, ’num graphic 4’,
’num graphic 6’, ’num graphic 8’, ’num graphic percentage’, ’draw mode’, ’int zooming’,
’ignore colormap’, ’graphic colors’, ’current runlength number’, ’clip region’, ’update lut’, ’do low error’,
’reentrant’, ’parallelize operators’, ’alloctmp single block’, ’language’
º Value (input control) ............................string(-array) (Htuple .) const char * / long / double
New value of the system parameter.
Default Value : ’true’
Value Suggestions : Value ¾’true’, ’false’, 0, 4, 8, 100, 140, 255
Result
The operator (T )set system returns the value H MSG TRUE if the parameters are correct. Otherwise an
exception will be raised.
Parallelization Information
(T )set system is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
reset obj db, (T )get system, (T )set check
(T )get system, (T )set check
See Also
HALCON 6.0

608 CHAPTER 11. SYSTEM
System
Module
11.7 Serial
clear serial ( long SerialHandle, const char *Channel )
Clear the buffer of a serial connection.
clear serial discards data written to the serial device referred to by SerialHandle, but not transmitted
(Channel = ’output’), or data received, but not read (Channel = ’input’), or performs both these operations at
once (Channel = ’in out’).
Parameter
º SerialHandle (input control) .....................................................serial id long
Serial interface handle.
º Channel (input control) .......................................................string const char *
Buffer to be cleared.
Default Value : ’input’
Value List : Channel ¾’input’, ’output’, ’in out’
Result
If the parameters are correct and the buffers of the serial device could be cleared, the operator clear serial
returns the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
clear serial is reentrant and processed without parallelization.
open serial
Possible Predecessor Functions
Possible Successor Functions
(T )read serial, (T )write serial
(T )read serial
System
See Also
Module
close all serials ( )
Close all serial devices.
close all serials closes all serial devices that have been opened with open serial.
Result
close all serials returns always H MSG TRUE.
Parallelization Information
close all serials is reentrant and processed without parallelization.
open serial
close serial
open serial, close file
System
Possible Predecessor Functions
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

11.7. SERIAL 609
close serial ( long SerialHandle )
Close a serial device.
close serial closes a serial device that was opened with open serial.
Parameter
º SerialHandle (input control) .....................................................serial id long
Serial interface handle.
Result
If the parameters are correct and the device could be closed, the operator close serial returns the value
H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
close serial is reentrant and processed without parallelization.
open serial
open serial, close file
System
Possible Predecessor Functions
See Also
Module
get serial param ( long SerialHandle, long *BaudRate, long *DataBits,
char *FlowControl, char *Parity, long *StopBits, long *TotalTimeOut,
long *InterCharTimeOut )
Get the parameters of a serial device.
get serial param returns the current parameter settings of the serial device passed in SerialHandle. For
a description of the parameters of a serial device, see set serial param.
Parameter
º SerialHandle (input control) .....................................................serial id long
Serial interface handle.
º BaudRate (output control) .........................................................integer long *
Speed of the serial interface.
º DataBits (output control) .........................................................integer long *
Number of data bits of the serial interface.
º FlowControl (output control) ......................................................string char *
Type of flow control of the serial interface.
º Parity (output control) .............................................................string char *
Parity of the serial interface.
º StopBits (output control) .........................................................integer long *
Number of stop bits of the serial interface.
º TotalTimeOut (output control) ....................................................integer long *
Total timeout of the serial interface in ms.
º InterCharTimeOut (output control) ..............................................integer long *
Inter-character timeout of the serial interface in ms.
Result
If the parameters are correct and the parameters of the device could be read, the operator get serial param
returns the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
get serial param is reentrant and processed without parallelization.
open serial
Possible Predecessor Functions
HALCON 6.0

610 CHAPTER 11. SYSTEM
Possible Successor Functions
get serial param, (T )read serial, (T )write serial
set serial param
System
See Also
Module
open serial ( const char *PortName, long *SerialHandle )
Open a serial device.
open serial opens a serial device. The name of the device is determined by the parameter PortName and is
operating system specific. On Windows NT machines, ’COM1’-’COM4’ is typically used, while on Unix systems
the serial devices usually are named ’/dev/tty*’. The parameters of the serial device, e.g., its speed or number of
data bits, are set to the system default values for the respective device after the device has been opened. They can
be set or changed by calling set serial param.
Parameter
º PortName (input control) .............................................filename.named const char *
Name of the serial port.
Default Value : ”COM1”
Value Suggestions : PortName ¾”COM1”, ”COM2”, ”COM3”, ”COM4”, ”/dev/ttya”, ”/dev/ttyb”,
”/dev/tty00”, ”/dev/tty01”, ”/dev/ttyd1”, ”/dev/ttyd2”, ”/dev/cua0”, ”/dev/cua1”
º SerialHandle (output control) ..................................................serial id long *
Serial interface handle.
Result
If the parameters are correct and the device could be opened, the operator open serial returns the value
H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
open serial is reentrant and processed without parallelization.
Possible Successor Functions
set serial param, (T )read serial, (T )write serial, close serial
See Also
set serial param, get serial param, open file
System
Module
read serial ( long SerialHandle, long NumCharacters, long *Data )
T read serial ( Htuple SerialHandle, Htuple NumCharacters,
Htuple *Data )
Read from a serial device.
(T )read serial tries to read NumCharacters from the serial device given in SerialHandle. The read
characters are returned in Data as a tuple of integers. This allows to read NUL characters, which would otherwise
be interpreted as the end of a string. If the timeout of the serial device has been set to a value greater than 0 with
set serial param, (T )read serial waits at most as long for the arrival of the first character as indicated
by the timeout. Otherwise, the operator returns immediately. In any case, the number of characters available at
the time of return are passed back to the caller, i.e., fewer characters than requested can be returned. This can be
checked by the length of the tuple Data.
HALCON/C Reference Manual / 2000-11-15

11.7. SERIAL 611
Parameter
º SerialHandle (input control) ............................................serial id (Htuple .) long
Serial interface handle.
º NumCharacters (input control) ............................................integer (Htuple .) long
Number of characters to read.
Default Value : 1
Value Suggestions : NumCharacters ¾1, 2, 3, 4, 5, 10, 20, 40, 100
º Data (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Read characters (as tuple of integers).
Result
If the parameters are correct and the read from the device was successful, the operator (T )read serial returns
the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
(T )read serial is reentrant and processed without parallelization.
open serial
(T )write serial
System
Possible Predecessor Functions
See Also
Module
set serial param ( long SerialHandle, long BaudRate, long DataBits,
const char *FlowControl, const char *Parity, long StopBits,
long TotalTimeOut, long InterCharTimeOut )
Set the parameters of a serial device.
set serial param can be used to set the parameters of a serial device. The parameter BaudRate determines
the input and output speed of the device. It should be noted that not all devices support all possible speeds. The
number of sent and received data bits is set with DataBits. The parameter FlowControl determines if and
what kind of data flow control should be used. In the latter case, a choice between software control (’xon xoff’)
and hardware control (’cts rts’, ’dtr dsr’) can be made. If and what kind of parity check of the transmitted
data should be performed can be determined by Parity. The number of stop bits sent is set with StopBits.
Finally, two timeout for reading from the serial device can be set. The parameter TotalTimeOut determines
the maximum time, which may pass in (T )read serial until the first character arrives, independent of the
actual number of characters requested. The parameter InterCharTimeOut determines the time which may
pass between the reading of individual characters, if multiple characters are requested with (T )read serial.
If one of the timeouts is set to -1, a read waits an arbitrary amount of time for the arrival of characters. Thus, on
Windows NT systems, a total timeout of ÌÓØÐÌÑÇÙØ · ÒÁÒØÖÖÌÑÇÙØ results if Ò characters are to be
read. On Unix systems, only one of the two timeouts can be set. Thus, if both timeouts are passed larger than -1,
only the total timeout is used. The unit of both timeouts is milliseconds. For each parameter, the current values
can be left in effect by passing ’unchanged’.
Parameter
º SerialHandle (input control) .....................................................serial id long
Serial interface handle.
º BaudRate (input control) ...............................................integer long / const char *
Speed of the serial interface.
Default Value : ’unchanged’
Value List : BaudRate ¾50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200,
38400, 57600, 76800, 115200, 153600, 230400, 307200, 460800, ’unchanged’
º DataBits (input control) ...............................................integer long / const char *
Number of data bits of the serial interface.
Default Value : ’unchanged’
Value List : DataBits ¾5, 6, 7, 8, ’unchanged’
HALCON 6.0

612 CHAPTER 11. SYSTEM
º FlowControl (input control) ..................................................string const char *
Type of flow control of the serial interface.
Default Value : ’unchanged’
Value List : FlowControl ¾’none’, ’xon xoff’, ’cts rts’, ’dtr dsr’, ’unchanged’
º Parity (input control) .........................................................string const char *
Parity of the serial interface.
Default Value : ’unchanged’
Value List : Parity ¾’none’, ’odd’, ’even’, ’unchanged’
º StopBits (input control) ...............................................integer long / const char *
Number of stop bits of the serial interface.
Default Value : ’unchanged’
Value List : StopBits ¾1, 2, ’unchanged’
º TotalTimeOut (input control) .........................................integer long / const char *
Total timeout of the serial interface in ms.
Default Value : ’unchanged’
Value Suggestions : TotalTimeOut ¾-1, 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000,
’unchanged’
º InterCharTimeOut (input control) ....................................integer long / const char *
Inter-character timeout of the serial interface in ms.
Default Value : ’unchanged’
Value Suggestions : InterCharTimeOut ¾-1, 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000,
’unchanged’
Result
If the parameters are correct and the parameters of the device could be set, the operator set serial param
returns the value H MSG TRUE. Otherwise an exception is raised.
Parallelization Information
set serial param is reentrant and processed without parallelization.
Possible Predecessor Functions
open serial, get serial param
Possible Successor Functions
(T )read serial, (T )write serial
get serial param
System
See Also
Module
write serial ( long SerialHandle, long Data )
T write serial ( Htuple SerialHandle, Htuple Data )
Write to a serial connection.
(T )write serial writes the characters given in Data to the serial device given by SerialHandle. The
data to be written is passed as a tuple of integers. This allows to write NUL characters, which would otherwise
be interpreted as the end of a string. (T )write serial always waits until all data has been transmitted, i.e., a
timout for writing cannot be set.
Parameter
º SerialHandle (input control) ............................................serial id (Htuple .) long
Serial interface handle.
º Data (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Characters to write (as tuple of integers).
Result
If the parameters are correct and the write to the device was successful, the operator (T )write serial returns
the value H MSG TRUE. Otherwise an exception is raised.
HALCON/C Reference Manual / 2000-11-15

11.8. SOCKETS 613
Parallelization Information
(T )write serial is reentrant and processed without parallelization.
open serial
(T )read serial
System
Possible Predecessor Functions
See Also
Module
11.8 Sockets
close socket ( long Socket )
Close a socket.
close socket closes a socket that was previously opened with open socket accept,
open socket connect, or socket accept connect. For a detailed example, see
open socket accept.
Parameter
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
close socket is reentrant and processed without parallelization.
See Also
open socket accept, open socket connect, socket accept connect
System
Module
get next socket data type ( long Socket, char *DataType )
Determine the HALCON data type of the next socket data.
get next socket data type returns the data type of the next data that are present on the socket Socket
and returns it in DataType. The possible values for DataType are:
’no data’: No data are present.
’no halcon data’: Some data are present, but they are not HALCON data.
’tuple’: Thenextdataisatuple.
’region’: The next data is a region object.
’image’: The next data is an image object.
’xld cont’: The next data is an XLD contour.
’xld poly’: The next data is an XLD polygon.
’xld para’: The next data is an XLD parallel.
’xld mod para’: The next data is a modified XLD parallel.
’xld ext para’: The next data is an extended XLD parallel.
HALCON 6.0

614 CHAPTER 11. SYSTEM
Parameter
º Socket (input control) .............................................................socket id long
Socket number.
º DataType (output control) ..........................................................string char *
Data type of next HALCON data.
Parallelization Information
get next socket data type is reentrant and processed without parallelization.
See Also
send image, receive image, send region, receive region, send tuple, receive tuple
System
Module
open socket accept ( long Port, long *AcceptingSocket )
Open a socket that accepts connection requests.
open socket accept opens a socket that accepts incoming connection requests by other HALCON processes.
This operator is the necessary first step in the establishment of a communication channel between two HALCON
processes. The socket listens for incoming connection requests on the port number given by Port. The accepting
socket is returned in AcceptingSocket. open socket accept returns immediately without waiting for
a request from another process, done by calling open socket connect in the other process. This allows
multiple other processes to connect to the particular HALCON process that calls open socket accept. To
accept an incoming connection request, socket accept connect must be called after another process has
called open socket connect.
Parameter
º Port (input control) .................................................................integer long
Port number.
Default Value : 3000
Typical Range of Values : 1024 Port 65535
Minimal Value Step : 1
Recommended Value Step : 1
º AcceptingSocket (output control) .............................................socket id long *
Socket number.
Example
/* Process 1 */
dev_set_colored (12)
open_socket_accept (3000, AcceptingSocket)
/* Busy wait for an incoming connection */
dev_error_var (Error, 1)
dev_set_check (’˜give_error’)
OpenStatus := 5
while (OpenStatus # 2)
socket_accept_connect (AcceptingSocket, ’false’, Socket)
OpenStatus := Error
wait_seconds (0.2)
endwhile
dev_set_check (’give_error’)
/* Connection established */
receive_image (Image, Socket)
threshold (Image, Region, 0, 63)
send_region (Region, Socket)
receive_region (ConnectedRegions, Socket)
area_center (ConnectedRegions, Area, Row, Column)
HALCON/C Reference Manual / 2000-11-15

11.8. SOCKETS 615
send_tuple (Socket, Area)
send_tuple (Socket, Row)
send_tuple (Socket, Column)
close_socket (Socket)
close_socket (AcceptingSocket)
/* Process 2 */
dev_set_colored (12)
open_socket_connect (’localhost’, 3000, Socket)
read_image (Image, ’fabrik’)
send_image (Image, Socket)
receive_region (Region, Socket)
connection (Region, ConnectedRegions)
send_region (ConnectedRegions, Socket)
receive_tuple (Socket, Area)
receive_tuple (Socket, Row)
receive_tuple (Socket, Column)
close_socket (Socket)
Parallelization Information
open socket accept is reentrant and processed without parallelization.
socket accept connect
Possible Successor Functions
See Also
open socket connect, close socket, send image, receive image, send region,
receive region, send tuple, receive tuple
System
Module
open socket connect ( const char *HostName, long Port, long *Socket )
Open a socket to an existing socket.
open socket connect opens a connection to an accepting socket on the computer HostName, which listens
on port Port. The listening socket in the other HALCON process must have been created earlier with the operator
open socket accept. The socket thus created is returned in Socket. To establish the connection, the
HALCON process, in which the accepting socket resides, must call socket accept connect. For a detailed
example, see open socket accept.
Parameter
º HostName (input control) ......................................................string const char *
Hostname of the computer to connect to.
Default Value : ’localhost’
º Port (input control) .................................................................integer long
Port number.
Default Value : 3000
Typical Range of Values : 1024 Port 65535
Minimal Value Step : 1
Recommended Value Step : 1
º Socket (output control) ..........................................................socket id long *
Socket number.
Parallelization Information
open socket connect is reentrant and processed without parallelization.
Possible Successor Functions
send image, receive image, send region, receive region, send tuple, receive tuple
HALCON 6.0

616 CHAPTER 11. SYSTEM
See Also
open socket accept, socket accept connect, close socket
System
Module
receive image ( Hobject *Image, long Socket )
Receive an image over a socket connection.
receive image reads an image object that was sent over the socket connection determined by Socket by
another HALCON process using the operator send image. If no image has been sent, the HALCON process
calling receive image blocks until enough data arrives. For a detailed example, see open socket accept.
Parameter
º Image (output object) .....................................................image(-array) Hobject *
Received image.
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
receive image is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
send image, send region, receive region, send tuple, receive tuple,
get next socket data type
Module
System
receive region ( Hobject *Region, long Socket )
Receive regions over a socket connection.
receive region reads a region object that was sent over the socket connection determined by Socket
by another HALCON process using the operator send region. If no regions have been sent, the HAL-
CON process calling receive region blocks until enough data arrives. For a detailed example, see
open socket accept.
Parameter
º Region (output object) ...................................................region(-array) Hobject *
Received regions.
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
receive region is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
send region, send image, receive image, send tuple, receive tuple,
get next socket data type
Module
System
HALCON/C Reference Manual / 2000-11-15

11.8. SOCKETS 617
receive tuple ( long Socket, char *Tuple )
Receive a tuple over a socket connection.
receive tuple reads a tuple that was sent over the socket connection determined by Socket by another
HALCON process using the operator send tuple. If no tuple has been sent, the HALCON process calling
receive tuple blocks until enough data arrives. For a detailed example, see open socket accept.
Parameter
º Socket (input control) .............................................................socket id long
Socket number.
º Tuple (output control) ..............................................................string char *
Received tuple.
Parallelization Information
receive tuple is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
send tuple, send image, receive image, send region, receive region,
get next socket data type
Module
System
receive xld ( Hobject *XLD, long Socket )
Receive an XLD object over a socket connection.
receive xld reads an XLD object that was sent over the socket connection determined by Socket by another
HALCON process using the operator send xld. If no XLD object has been sent, the HALCON process calling
receive xld blocks until enough data arrives. For a detailed example, see send xld.
Parameter
º XLD (output object) ..........................................................xld(-array) Hobject *
Received XLD object.
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
receive xld is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
send xld, send image, receive image, send region, receive region, send tuple,
receive tuple, get next socket data type
System
Module
send image ( Hobject Image, long Socket )
Send an image over a socket connection.
send image sends an image object over the socket connection determined by Socket. The receiving HAL-
CON process must call receive image to read the image from the socket. For a detailed example, see
open socket accept.
HALCON 6.0

618 CHAPTER 11. SYSTEM
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image to be sent.
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
send image is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
receive image, send region, receive region, send tuple, receive tuple,
get next socket data type
Module
System
send region ( Hobject Region, long Socket )
Send regions over a socket connection.
send region sends a region object over the socket connection determined by Socket. The receiving HAL-
CON process must call receive region to read the regions from the socket. For a detailed example, see
open socket accept.
Parameter
º Region (input object) ......................................................region(-array) Hobject
Regions to be sent.
º Socket (input control) .............................................................socket id long
Socket number.
Parallelization Information
send region is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
receive region, send image, receive image, send tuple, receive tuple,
get next socket data type
Module
System
send tuple ( long Socket, const char *Tuple )
Send a tuple over a socket connection.
send tuple sends a tuple over the socket connection determined by Socket. The receiving HAL-
CON process must call receive tuple to read the tuple from the socket. For a detailed example, see
open socket accept.
Parameter
º Socket (input control) .............................................................socket id long
Socket number.
º Tuple (input control) ..........................................................string const char *
Tupletobesent.
HALCON/C Reference Manual / 2000-11-15

11.8. SOCKETS 619
Parallelization Information
send tuple is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
receive tuple, send image, receive image, send region, receive region,
get next socket data type
Module
System
send xld ( Hobject XLD, long Socket )
Send an XLD object over a socket connection.
send xld sends an XLD object over the socket connection determined by Socket. The receiving HALCON
process must call receive xld to read the XLD object from the socket.
Parameter
º XLD (input object) .............................................................xld(-array) Hobject
XLD object to be sent.
º Socket (input control) .............................................................socket id long
Socket number.
Example
/* Process 1 */
dev_set_colored (12)
open_socket_accept (3000, AcceptingSocket)
socket_accept_connect (AcceptingSocket, ’true’, Socket)
receive_image (Image, Socket)
edges_sub_pix (Image, Edges, ’canny’, 1.5, 20, 40)
send_xld (Edges, Socket)
receive_xld (Polygons, Socket)
split_contours_xld (Polygons, Contours, ’polygon’, 1, 5)
gen_parallels_xld (Polygons, Parallels, 10, 30, 0.15, ’true’)
send_xld (Parallels, Socket)
receive_xld (ModParallels, Socket)
receive_xld (ExtParallels, Socket)
stop ()
close_socket (Socket)
close_socket (AcceptingSocket)
/* Process 2 */
dev_set_colored (12)
open_socket_connect (’localhost’, 3000, Socket)
read_image (Image, ’mreut’)
send_image (Image, Socket)
receive_xld (Edges, Socket)
gen_polygons_xld (Edges, Polygons, ’ramer’, 2)
send_xld (Polygons, Socket)
split_contours_xld (Polygons, Contours, ’polygon’, 1, 5)
receive_xld (Parallels, Socket)
mod_parallels_xld (Parallels, Image, ModParallels, ExtParallels,
0.4, 160, 220, 10)
send_xld (ModParallels, Socket)
send_xld (ExtParallels, Socket)
stop ()
close_socket (Socket)
HALCON 6.0

620 CHAPTER 11. SYSTEM
Parallelization Information
send xld is reentrant and processed without parallelization.
Possible Predecessor Functions
open socket connect, socket accept connect
See Also
receive xld, send image, receive image, send region, receive region, send tuple,
receive tuple, get next socket data type
System
Module
socket accept connect ( long AcceptingSocket, const char *Wait,
long *Socket )
Accept a connection request on a listening socket.
socket accept connect accepts an incoming connection request, generated by open socket connect
in another HALCON process, on the listening socket AcceptingSocket. The listening socket must have been
created earlier with open socket accept. IfWait=’true’, socket accept connect waits until a connection
request from another HALCON process arrives. If Wait=’false’, socket accept connect returns
with the error FAIL, if currently there are no connection requests from other HALCON processes. The result of
socket accept connect is another socket Socket, which is used for a two-way communication with another
HALCON process. After this connection has been established, data can be exchanged between the two processes
by calling the appropriate send or receive operators. For a detailed example, see open socket accept.
Parameter
º AcceptingSocket (input control) ................................................socket id long
Socket number of the accepting socket.
º Wait (input control) ............................................................string const char *
Should the operator wait until a connection request arrives?
Value List : Wait ¾’true’, ’false’
º Socket (output control) ..........................................................socket id long *
Socket number.
Parallelization Information
socket accept connect is reentrant and processed without parallelization.
open socket accept
Possible Predecessor Functions
Possible Successor Functions
send image, receive image, send region, receive region, send tuple, receive tuple
open socket connect, close socket
System
See Also
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 12
Tools
12.1 Affine-Transformations
T affine trans point 2d ( Htuple HomMat2D, Htuple Px, Htuple Py,
Htuple *Qx, Htuple *Qy )
Apply a homogeneous 2D transformation matrix to points.
T affine trans point 2d calculates the result of applying the affine transformation, given by the homogeneous
2D transformation matrix HomMat2D, to the input points (Px,Py). The resulting points are returned in
(Qx,Qy).
If the coordinates (Px,Py) are image coordinates, it should be noted that the components of the homogeneous
transformation matrix are to be interpreted as follows: the row coordinate of the image corresponds to the Ü coordinate
of the matrix, while the column coordinate of the image corresponds to the Ý coordinate of the matrix. This
is necessary to obtain a right-handed coordinate system, which is assumed for the homogeneous transformation
matrices, also for the image. In particular, by doing so roatations are performed in the correct direction. Note that
the (Ü,Ý) order of the matrices quite naturally corresponds to the usual (row,column) order for coordinates in the
image.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Px (input control) .............................................point.x(-array) Htuple . double / long
Input point (x coordinate).
Default Value : 64
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) .............................................point.y(-array) Htuple . double / long
Input point (y coordinate).
Default Value : 64
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Qx (output control) ................................................point.x(-array) Htuple . double *
Output point (x coordinate).
º Qy (output control) ................................................point.y(-array) Htuple . double *
Output point (y coordinate).
Result
T affine trans point 2d always returns H MSG TRUE.
621

622 CHAPTER 12. TOOLS
Parallelization Information
T affine trans point 2d is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T affine trans point 3d ( Htuple HomMat3D, Htuple Px, Htuple Py,
Htuple Pz, Htuple *Qx, Htuple *Qy, Htuple *Qz )
Apply a homogeneous 3D transformation matrix to points.
T affine trans point 3d calculates the result of applying the affine transformation, given by the homogeneous
3D transformation matrix HomMat3D, to the input points (Px,Py ,Pz). The resulting points are returned in
(Qx, Qy,Qz).
T affine trans point 3d is used to transform a 3D point (Px, Py, Pz) into a new coordinate system. The
necessary translation and rotation is given by the 4x3 transformation matrix HomMat3D. The values are given as
a tupel in the following order: The first three values of each row describe the three rows of the rotation matrix Ê
and the last values of each row describe the translation Ì . During the transformation the 3D point is first rotated
and subsequently translated:
¼
Ü ¾
Ý ¾
Þ ¾
½ ¼
Ê¡ Ü ½
Ý ½
Þ ½
Parameter
½
· Ì
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Input transformation matrix.
Parameter Number : 12
º Px (input control) ..........................................point3d.x(-array) Htuple . double / long
Input point (x coordinate).
Default Value : 64
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) ..........................................point3d.y(-array) Htuple . double / long
Input point (y coordinate).
Default Value : 64
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Pz (input control) ..........................................point3d.z(-array) Htuple . double / long
Input point (z coordinate).
Default Value : 64
Value Suggestions : Pz ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Pz 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Qx (output control) ..............................................point3d.x(-array) Htuple . double *
Output point (x coordinate).
º Qy (output control) ..............................................point3d.y(-array) Htuple . double *
Output point (y coordinate).
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 623
º Qz (output control) ..............................................point3d.z(-array) Htuple . double *
Output point (z coordinate).
Result
T affine trans point 3d always returns H MSG TRUE.
Parallelization Information
T affine trans point 3d is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate, T pose to hom mat3d
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate, T project 3d point
Basic operators
Module
T dvf to hom mat2d ( Hobject VectorField, Htuple *HomMat2D )
Approximate an affine map from a displacement vector field.
T dvf to hom mat2d approximates an affine map from the displacement vector field VectorField. The
affine map is returned in HomMat2D.
If the displacement vector field has been computed from the original image Á orig and the second image Áres,
the internally stored transformation matrix (see affine trans image) contains a map that describes how to
transform the first image Á orig to the second image Áres.
Parameter
º VectorField (input object) ....................................singlechannel-image Hobject : dvf
Input image.
º HomMat2D (output control) ........................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Parallelization Information
T dvf to hom mat2d is reentrant and processed without parallelization.
optical flow match
affine trans image
T vector to hom mat2d
Basic operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
T hom mat2d compose ( Htuple HomMat2DSecond, Htuple HomMat2DFirst,
Htuple *HomMat2DCompose )
Compose two homogeneous 2D transformation matrices.
T hom mat2d compose composes a new 2D transformation matrix from the two input matrices. The transformation
given by HomMat2DFirst is applied first, followed by the transformation given by HomMat2DSecond,
i.e., with HomMat2DFirst = À ½ , HomMat2DSecond = À ¾ ,andHomMat2DCompose = À is:
À À ¾ ¡À ½
HALCON 6.0

624 CHAPTER 12. TOOLS
Parameter
º HomMat2DSecond (input control) ...................................affine2d-array Htuple . double
Second input transformation matrix.
Parameter Number : 6
º HomMat2DFirst (input control) ....................................affine2d-array Htuple . double
First input transformation matrix.
Parameter Number : 6
º HomMat2DCompose (output control) ...............................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d compose always returns H MSG TRUE.
Parallelization Information
T hom mat2d compose is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d identity ( Htuple *HomMat2DIdentity )
Generate the homogeneous transformation matrix of the identical 2D transformation.
T hom mat2d identity generates the homogeneous ¾ ¢ ¿ transformation matrix HomMat2DIdentity describing
the identical 2D transformation.
Parameter
º HomMat2DIdentity (output control) .............................affine2d-array Htuple . double *
Transformation matrix.
Parameter Number : 6
Result
T hom mat2d identity always returns H MSG TRUE.
Parallelization Information
T hom mat2d identity is reentrant and processed without parallelization.
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d invert ( Htuple HomMat2D, Htuple *HomMat2DInvert )
Invert a homogeneous 2D transformation matrix.
T hom mat2d invert inverts the homogeneous 2D transformation matrix given by HomMat2D. The resulting
matrix is returned in HomMat2DInvert.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 625
º HomMat2DInvert (output control) ................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d invert returns H MSG TRUE if the input matrix is invertible.
Parallelization Information
T hom mat2d invert is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d rotate ( Htuple HomMat2D, Htuple Phi, Htuple Px, Htuple Py,
Htuple *HomMat2DRotate )
Add a rotation to a homogeneous 2D transformation matrix.
T hom mat2d rotate adds a rotation by the angle Phi to a homogeneous 2D transformation matrix
HomMat2D. The point (Px,Py) is the fixed point of the transformation. The resulting matrix is returned in
HomMat2DRotate.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Phi (input control) ................................................angle.rad Htuple . double / long
Rotation angle.
Default Value : 0.78
Value Suggestions : Phi ¾0.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.14
Typical Range of Values : 0 Phi 6.28318530718
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Px (input control) ...................................................point.x Htuple . double / long
Fixed point of the transformation (x coordinate).
Default Value : 0
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) ...................................................point.y Htuple . double / long
Fixed point of the transformation (y coordinate).
Default Value : 0
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat2DRotate (output control) ................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d rotate always returns H MSG TRUE.
Parallelization Information
T hom mat2d rotate is reentrant and processed without parallelization.
HALCON 6.0

626 CHAPTER 12. TOOLS
Possible Predecessor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d scale ( Htuple HomMat2D, Htuple Sx, Htuple Sy, Htuple Px,
Htuple Py, Htuple *HomMat2DScale )
Add a scaling to a homogeneous 2D transformation matrix.
T hom mat2d scale adds a scaling by the scale factors Sx and Sy to a homogeneous 2D transformation matrix
HomMat2D. The point (Px,Py) is the fixed point of the transformation. The resulting matrix is returned in
HomMat2DScale.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Sx (input control) ...................................................number Htuple . double / long
Scale factor along the x-axis.
Default Value : 2
Value Suggestions : Sx ¾0.125, 0.25, 0.5, 1, 2, 4, 8, 16
Typical Range of Values : 0 Sx 1024
Minimal Value Step : 0.001
Recommended Value Step : 0.125
Restriction : Sx 0
º Sy (input control) ...................................................number Htuple . double / long
Scale factor along the y-axis.
Default Value : 2
Value Suggestions : Sy ¾0.125, 0.25, 0.5, 1, 2, 4, 8, 16
Typical Range of Values : 0 Sy 1024
Minimal Value Step : 0.001
Recommended Value Step : 0.125
Restriction : Sy 0
º Px (input control) ...................................................point.x Htuple . double / long
Fixed point of the transformation (x coordinate).
Default Value : 0
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) ...................................................point.y Htuple . double / long
Fixed point of the transformation (y coordinate).
Default Value : 0
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat2DScale (output control) ..................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d scale returns H MSG TRUE if both scale factors are not 0.
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 627
Parallelization Information
T hom mat2d scale is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d slant ( Htuple HomMat2D, Htuple Theta, Htuple Axis,
Htuple Px, Htuple Py, Htuple *HomMat2DSlant )
Add a slant to a homogeneous 2D transformation matrix.
T hom mat2d slant adds a slant by the angle Theta to a homogeneous 2D transformation matrix HomMat2D.
A slant is an affine transformation in which one coordinate axis remains fixed, while the other coordinate axis is
rotated counterclockwise by an angle Theta. The parameter Axis determines which coordinate axis is slanted.
For Axis = ’x’, the x-axis is slanted, while for Axis = ’y’ the y-axis is slanted. The point (Px,Py) isthefixed
point of the transformation. The resulting matrix is returned in HomMat2DSlant.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Theta (input control) .............................................angle.rad Htuple . double / long
Slant angle.
Default Value : 0.78
Value Suggestions : Theta ¾0.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.14
Typical Range of Values : 0 Theta 6.28318530718
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Axis (input control) ....................................................string Htuple . const char *
Coordinate axis that is slanted.
Default Value : ’x’
Value List : Axis ¾’x’, ’y’
º Px (input control) ...................................................point.x Htuple . double / long
Fixed point of the transformation (x coordinate).
Default Value : 0
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) ...................................................point.y Htuple . double / long
Fixed point of the transformation (y coordinate).
Default Value : 0
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat2DSlant (output control) ..................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d slant always returns H MSG TRUE.
Parallelization Information
T hom mat2d slant is reentrant and processed without parallelization.
HALCON 6.0

628 CHAPTER 12. TOOLS
Possible Predecessor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat2d to affine par ( Htuple HomMat2D, Htuple *Sx, Htuple *Sy,
Htuple *Phi, Htuple *Theta, Htuple *Tx, Htuple *Ty )
Compute the affine transformation parameters from a homogeneous 2D transformation matrix.
T hom mat2d to affine par computes the affine transformation parameters corresponding to the homogeneous
2D transformation matrix HomMat2D. The parameters Sx and Sy determine how the transformation scales
the original x- and y-axes, respectively. The two scaling factors are always positive. The angle Theta determines
how the transformed coordinate axes deviate from orthogonality. For Theta = 0, the two coordinate axes are
orthogonal. If ÌØ ¾ the transformation contains a reflection. The angle Phi determines the rotation of
the transformed x-axis with respect to the original x-axis. The parameters Tx and Ty determine the translation of
the two coordinate systems. The Matrix HomMat2D can be constructed from the six transformation parameters by
the following operator sequence:
hom\_mat2d\_identity (HomMat2DIdentity)
hom\_mat2d\_scale (HomMat2DIdentity, Sx, Sy, 0, 0, HomMat2DScale)
hom\_mat2d\_slant (HomMat2DScale, Theta, ’y’, 0, 0, HomMat2DSlant)
hom\_mat2d\_rotate (HomMat2DSlant, Phi, 0, 0, HomMat2DRotate)
hom\_mat2d\_translate (HomMat2DRotate, Tx, Ty, HomMat2D)
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Sx (output control) ..........................................................real Htuple . double *
Scaling factor along the x direction.
º Sy (output control) ..........................................................real Htuple . double *
Scaling factor along the y direction.
º Phi (output control) ....................................................angle.rad Htuple . double *
Rotation angle.
º Theta (output control) .................................................angle.rad Htuple . double *
Slant angle.
º Tx (output control) .......................................................point.x Htuple . double *
Translation along the x direction.
º Ty (output control) .......................................................point.y Htuple . double *
Translation along the y direction.
Result
If the matrix HomMat2D is non-degenerate, T hom mat2d to affine par returns H MSG TRUE. Otherwise,
an exception is raised.
Parallelization Information
T hom mat2d to affine par is reentrant and processed without parallelization.
Possible Predecessor Functions
T vector to hom mat2d, T vector to rigid, T vector to similarity
Possible Successor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Module
Basic operators
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 629
T hom mat2d translate ( Htuple HomMat2D, Htuple Tx, Htuple Ty,
Htuple *HomMat2DTranslate )
Add a translation to a homogeneous 2D transformation matrix.
T hom mat2d translate adds a translation by the vector (Tx,Ty) to a homogeneous 2D transformation matrix
HomMat2D. The resulting matrix is returned in HomMat2DTranslate.
Parameter
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
º Tx (input control) ...................................................point.x Htuple . double / long
Translation along the x-axis.
Default Value : 64
Value Suggestions : Tx ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Tx 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Ty (input control) ...................................................point.y Htuple . double / long
Translation along the y-axis.
Default Value : 64
Value Suggestions : Ty ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Ty 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat2DTranslate (output control) ............................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Result
T hom mat2d identity always returns H MSG TRUE.
Parallelization Information
T hom mat2d translate is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat2d identity, T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate,
T hom mat2d slant
Possible Successor Functions
T hom mat2d translate, T hom mat2d scale, T hom mat2d rotate, T hom mat2d slant
Basic operators
Module
T hom mat3d compose ( Htuple HomMat3DSecond, Htuple HomMat3DFirst,
Htuple *HomMat3DCompose )
Compose two homogeneous 3D transformation matrices.
T hom mat3d compose composes a new 3D transformation matrix from the two input matrices. The transformation
given by HomMat3DFirst is applied first, followed by the transformation given by HomMat3DSecond,
i.e., with HomMat3DFirst = À ½ , HomMat3DSecond = À ¾ ,andHomMat3DCompose = À is:
À À ¾ ¡À ½
A homogeneous 4x3 transformation matrix describes the transformation of a 3D point from the source coordinate
system into the destination coordinate system. In this sight the following holds are usable:
HALCON 6.0

630 CHAPTER 12. TOOLS
with:
¼
Ü ¿
Ý ¿
Þ ¿
½
À ¡
À ¾ ¡
¼
Ü ½
Ý ½
¼
Þ ½
Ü ¾
Ý ¾
Þ ¾
½
À¾ ¡À ½ ¡
½
¼
Ü ½
Ý ½
Þ ½
½
therefore:
¼
Ü ¾
Ý ¾
Þ ¾
½
À½ ¡
¼
Ü ½
Ý ½
Þ ½
½
ʽ ¡
¼
Ü ½
Ý ½
Þ ½
½
· ̽
with:
¼
Ü ¿
Ý ¿
Þ ¿
½
ʾ ¡
¼
Ü ¾
Ý ¾
Ê ¾ ¡Ê ½ ¡
Þ ¾
¼
½
¼
· ̾ Ê ¾ ¡ ʽ ¡
Ü ½
Ý ½
Þ ½
½
¼
Ü ½
Ý ½
Þ ½
· ʾ ¡Ì ½ · Ì ¾ Ê ¡
½ ½
· ̽
¼
Ü ½
Ý ½
Þ ½
· ̾
½
· Ì
Rotation:
Ê Ê ¾ ¡Ê ¾
Translation: Ì Ê ¾ ¡Ì ½ · Ì ¾
Parameter
º HomMat3DSecond (input control) ...................................affine3d-array Htuple . double
Second input transformation matrix.
Parameter Number : 12
º HomMat3DFirst (input control) ....................................affine3d-array Htuple . double
First input transformation matrix.
Parameter Number : 12
º HomMat3DCompose (output control) ...............................affine3d-array Htuple . double *
Output transformation matrix.
Parameter Number : 12
Example
HTuple Pose, HomTransMat1, HomTransMat2, HomTransMatMult ;
// read camera pose
::read_pose("campose.dat",&CamPose);
// transform pose to transformation matrix
::pose_to_hom_mat3d(CamPose,&HomTransMat1);
// multiply transformation matrices
::hom_mat3d_compose(HomTransMat2, HomTransMat1, &HomTransMatMult);
Result
T hom mat3d compose always returns H MSG TRUE.
Parallelization Information
T hom mat3d compose is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d identity, T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate,
T pose to hom mat3d
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 631
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
See Also
T affine trans point 3d, T hom mat3d identity, T hom mat3d rotate,
T hom mat3d translate, T pose to hom mat3d, T hom mat3d to pose
Basic operators
Module
T hom mat3d identity ( Htuple *HomMat3DIdentity )
Generate the homogeneous transformation matrix of the identical 3D transformation.
T hom mat3d identity generates the homogeneous ¿ ¢ transformation matrix HomMat3DIdentity describing
the identical 3D transformation.
Parameter
º HomMat3DIdentity (output control) .............................affine3d-array Htuple . double *
Transformation matrix.
Parameter Number : 12
Result
T hom mat3d identity always returns H MSG TRUE.
Parallelization Information
T hom mat3d identity is reentrant and processed without parallelization.
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
T pose to hom mat3d
Basic operators
Alternatives
Module
T hom mat3d invert ( Htuple HomMat3D, Htuple *HomMat3DInvert )
Invert a homogeneous 3D transformation matrix.
T hom mat3d invert inverts the homogeneous 3D transformation matrix given by HomMat3D. The resulting
matrix is returned in HomMat3DInvert.
A homogeneous 4x3 transformation matrix describes the transformation of a 3D point from the source coordinate
system into the destination coordinate system. In this sight the inverted transformation matrix HomMat3DInvert
describes the transformation from the original destination coordinate system to the original source coordinate
system. The transformation of a 3D point (given in the source coordinate system) into a destination coordinate
system is given by a rotation Ê and a translation Ì (see T affine trans point 3d). Thus, the following
holds:
¼
Ü ¾
Ý ¾
¼
Ü ½
Ý ½
Þ ½
Þ ¾
½
½
ÊÓÖ ¡
ÊÓÖ ½ ¡
¼
Ü ½
Ý ½
¼
Þ ½
Ü ¾
Ý ¾
Þ ¾
½
· ÌÓÖ
½
Ì ÓÖ
with Ê ÒÚ Ê ÓÖ ½ and Ì ÒÚ Ì ÓÖ :
HALCON 6.0

632 CHAPTER 12. TOOLS
¼
Ü ½
Ý ½
Þ ½
½
ÊÒÚ ¡
¼
Ü ¾
Ý ¾
Þ ¾
Parameter
½
· ÌÒÚ
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Input transformation matrix.
Parameter Number : 12
º HomMat3DInvert (output control) ................................affine3d-array Htuple . double *
Output transformation matrix.
Parameter Number : 12
Example
HTuple CamPose, HomTransMat, HomTransMatInv;
// read camera pose
::read_pose("campose.dat",&CamPose);
// transform pose to transformation matrix
pose_to_hom_mat3d(CamPose,&HomTransMat);
// invert transformation matrix
::hom_mat3d_invert(HomTransMat,&HomTransMatInv);
Result
T hom mat3d invert returns H MSG TRUE if the input matrix is invertible.
Parallelization Information
T hom mat3d invert is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate, T pose to hom mat3d
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate, T hom mat3d to pose
See Also
T affine trans point 3d, T hom mat3d identity, T hom mat3d rotate,
T hom mat3d translate, T pose to hom mat3d, T hom mat3d to pose, T hom mat3d compose
Basic operators
Module
T hom mat3d rotate ( Htuple HomMat3D, Htuple Phi, Htuple Axis,
Htuple Px, Htuple Py, Htuple Pz, Htuple *HomMat3DRotate )
Add a rotation to a homogeneous 3D transformation matrix.
T hom mat3d rotate adds a rotation around the Axis-axis by the angle Phi to a homogeneous 3D transformation
matrix HomMat3D. The point (Px,Py,Pz) is the fixed point of the transformation. The resulting matrix is
returned in HomMat3DRotate.
The homogeneous 4x3 transformation matrix HomMat3D describes the transformation of a 3D point from the
source coordinate system into the destination coordinate system (Without Attention to the fixed point).
T hom mat3d rotate is used to generate a new 4x3 transformation matrix HomMat3DRotate by rotating the
Axis-axis of HomMat3D by the angle Phi (in mathematical positive direction).
If you want to rotate the source coordinate system, you have to invert the transformation matrix using
T hom mat3d invert, rotate it using T hom mat3d rotate, and invert it back again.
The transformation of a 3D point (given in the source coordinate system) into a destination coordinate system ist
given by a rotation Ê and a translation Ì (see T affine trans point 3d). Thus, the following holds:
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 633
¼
Ü ¾
Ý ¾
Þ ¾
½
ÊÖÓØ ¡
¼
Ü ½
Ý ½
Þ ½
´Ê ¡Ê ÓÖ µ ¡
½
· ÌÖÓØ
¼
Ü ¾
Ý ¾
Þ ¾
½
· ÌÓÖ
with
Ê Ü ¼
½ ¼ ¼
¼ Ó× ×Ò
¼ ×Ò Ó×
½
¼
Ê
Ý
Ó× ¼ ×Ò
¼ ½ ¼
×Ò ¼ Ó×
½
Ê
Þ
¼
Ó× ×Ò ¼
×Ò Ó× ¼
¼ ¼ ½
½
Parameter
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Input transformation matrix.
Parameter Number : 12
º Phi (input control) ................................................angle.rad Htuple . double / long
Rotation angle.
Default Value : 0.78
Value Suggestions : Phi ¾0.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.14
Typical Range of Values : 0 Phi 6.28318530718
Minimal Value Step : 0.01
Recommended Value Step : 0.1
º Axis (input control) ....................................................string Htuple . const char *
Axis, to be rotated around.
Default Value : ”x”
Value Suggestions : Axis ¾”x”, ”y”, ”z”
º Px (input control) .................................................point3d.x Htuple . double / long
Fixed point of the transformation (x coordinate).
Default Value : 0
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) .................................................point3d.y Htuple . double / long
Fixed point of the transformation (y coordinate).
Default Value : 0
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Pz (input control) .................................................point3d.z Htuple . double / long
Fixed point of the transformation (z coordinate).
Default Value : 0
Value Suggestions : Pz ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Pz 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat3DRotate (output control) ................................affine3d-array Htuple . double *
Output transformation matrix.
Parameter Number : 12
Example
HTuple CamPose, HomTransMat, HomTransMatRot;
HALCON 6.0

634 CHAPTER 12. TOOLS
HTuple HomTransMatInv, HomTransMatRot2, HomTransMat2;
// read camera pose
::read_pose("campose.dat",&CamPose);
// transform pose to transformation matrix
::pose_to_hom_mat3d(CamPose,&HomTransMat);
// rotate destination coordinate system around x-axis by 10 degree
::hom_mat3d_rotate(HomTransMat,10,"x",0,0,0,&HomTransMatRot);
// rotate source coordinate system around y-axis by 270 degree
::hom_mat3d_invert(HomTransMat,&HomTransMatInv);
::hom_mat3d_rotate(HomTransMatInv,270,"y",0,0,0,&HomTransMatRot2);
::hom_mat3d_invert(HomTransMatRot2,&HomTransMat2);
Result
T hom mat3d rotate always returns H MSG TRUE.
Parallelization Information
T hom mat3d rotate is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d identity, T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
See Also
T hom mat3d invert, T hom mat3d identity, T hom mat3d rotate, T hom mat3d translate,
T pose to hom mat3d, T hom mat3d to pose, T hom mat3d compose
Basic operators
Module
T hom mat3d scale ( Htuple HomMat3D, Htuple Sx, Htuple Sy, Htuple Sz,
Htuple Px, Htuple Py, Htuple Pz, Htuple *HomMat3DScale )
Add a scaling to a homogeneous 3D transformation matrix.
T hom mat3d scale adds a scaling by the scale factors Sx and Sy to a homogeneous 3D transformation matrix
HomMat3D. The point (Px,Py,Pz) is the fixed point of the transformation. The resulting matrix is returned in
HomMat3DScale.
Parameter
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Input transformation matrix.
Parameter Number : 12
º Sx (input control) ...................................................number Htuple . double / long
Scale factor along the x-axis.
Default Value : 2
Value Suggestions : Sx ¾0.125, 0.25, 0.5, 1, 2, 4, 8, 112
Typical Range of Values : 0 Sx 1024
Minimal Value Step : 0.001
Recommended Value Step : 0.125
Restriction : Sx 0
º Sy (input control) ...................................................number Htuple . double / long
Scale factor along the y-axis.
Default Value : 2
Value Suggestions : Sy ¾0.125, 0.25, 0.5, 1, 2, 4, 8, 112
Typical Range of Values : 0 Sy 1024
Minimal Value Step : 0.001
Recommended Value Step : 0.125
Restriction : Sy 0
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 635
º Sz (input control) ...................................................number Htuple . double / long
Scale factor along the z-axis.
Default Value : 2
Value Suggestions : Sz ¾0.125, 0.25, 0.5, 1, 2, 4, 8, 112
Typical Range of Values : 0 Sz 1024
Minimal Value Step : 0.001
Recommended Value Step : 0.125
Restriction : Sz 0
º Px (input control) .................................................point3d.x Htuple . double / long
Fixed point of the transformation (x coordinate).
Default Value : 0
Value Suggestions : Px ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Px 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Py (input control) .................................................point3d.y Htuple . double / long
Fixed point of the transformation (y coordinate).
Default Value : 0
Value Suggestions : Py ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Py 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Pz (input control) .................................................point3d.z Htuple . double / long
Fixed point of the transformation (z coordinate).
Default Value : 0
Value Suggestions : Pz ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Pz 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat3DScale (output control) ..................................affine3d-array Htuple . double *
Output transformation matrix.
Parameter Number : 12
Result
T hom mat3d scale returns H MSG TRUE if all three scale factors are not 0.
Parallelization Information
T hom mat3d scale is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d identity, T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
Basic operators
Module
T hom mat3d translate ( Htuple HomMat3D, Htuple Tx, Htuple Ty,
Htuple Tz, Htuple *HomMat3DTranslate )
Add a translation to a homogeneous 3D transformation matrix.
T hom mat3d translate adds a translation by the vector (Tx,Ty,Tz) to a homogeneous 3D transformation
matrix HomMat3D. The resulting matrix is returned in HomMat3DTranslate.
The homogeneous 4x3 transformation matrix HomMat3D describes the transformation of a 3D point from the
source coordinate system into the destination coordinate system. In this sight T hom mat3d translate is
used to generate a new 4x3 transformation matrix HomMat3DTranslate by translating the origin of HomMat3D
along the negative Axis by the amount (in meter) of the according to the vector (Tx,Ty,Tz).
If you want to translate the source coordinate system, you have to invert the transformation matrix using
T hom mat3d invert, translate it using T hom mat3d translate, and invert it back again.
HALCON 6.0

636 CHAPTER 12. TOOLS
The transformation of a 3D point (given in the source coordinate system) into a destination coordinate system ist
given by a rotation Ê and a translation Ì (see T affine trans point 3d). Thus, the following holds:
¼
Ü ¾
Ý ¾
Þ ¾
½
ÊØÖÒ× ¡
Ê ÓÖ ¡
¼
¼
Ü ½
Ý ½
Ü ¾
Ý ¾
Þ ¾
Þ ½
½
· ÌØÖÒ×
½
·´ÌÓÖ · Ì Æ µ
with
Ì Æ
¼
Ø Ü
Ø Ý
Ø Þ
Parameter
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Input transformation matrix.
Parameter Number : 12
º Tx (input control) .................................................point3d.x Htuple . double / long
Translation along the x-axis.
Default Value : 64
Value Suggestions : Tx ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Tx 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Ty (input control) .................................................point3d.y Htuple . double / long
Translation along the y-axis.
Default Value : 64
Value Suggestions : Ty ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Ty 1024
Minimal Value Step : 1
Recommended Value Step : 10
º Tz (input control) .................................................point3d.z Htuple . double / long
Translation along the z-axis.
Default Value : 64
Value Suggestions : Tz ¾0, 16, 32, 64, 128, 256, 512, 1024
Typical Range of Values : 0 Tz 1024
Minimal Value Step : 1
Recommended Value Step : 10
º HomMat3DTranslate (output control) ............................affine3d-array Htuple . double *
Output transformation matrix.
Parameter Number : 12
Example
Tuple CamPose, HomTransMat, HomTransMatTransl, HomTransMatInv;
Tuple HomTransMatTransl2, HomTransMat2;
// read camera pose
::read_pose("campose.dat",&CamPose);
// transform pose to transformation matrix
::pose_to_hom_mat3d(CamPose,&HomTransMat);
// translate destination coordinate along x-axis by 0.4 m
::hom_mat3d_translate(HomTransMat,-0.4,0,0,"x",&HomTransMatTransl);
// translate source coordinate along y-axis by -0.03 m
½
HALCON/C Reference Manual / 2000-11-15

12.1. AFFINE-TRANSFORMATIONS 637
::hom_mat3d_invert(HomTransMat, &HomTransMatInv);
::hom_mat3d_translate(HomTransMatInv,0,0.03,0,&HomTransMatTransl2);
::hom_mat3d_invert(HomTransMatTransl2,&HomTransMat2);
Result
T hom mat3d identity always returns H MSG TRUE.
Parallelization Information
T hom mat3d translate is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d identity, T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
Possible Successor Functions
T hom mat3d translate, T hom mat3d scale, T hom mat3d rotate
See Also
T hom mat3d invert, T hom mat3d identity, T hom mat3d rotate, T hom mat3d translate,
T pose to hom mat3d, T hom mat3d to pose, T hom mat3d compose
Basic operators
Module
T vector angle to rigid ( Htuple Row1, Htuple Column1, Htuple Angle1,
Htuple Row2, Htuple Column2, Htuple Angle2, Htuple *HomMat2D )
Compute a rigid affine transformation from points and angles.
T vector angle to rigid computes a rigid affine transformation from a point correspondence and two corresponding
angles. The coordinates of the original point are passed in (Row1,Column1), while the corresponding
angle is passed in Angle1. The coordinates of the transformed point are passed in (Row2,Column2), while the
corresponding angle is passed in Angle2. In particular, the operator T vector angle to rigid is useful
to construct a rigid affine transformation from the results of the pattern matching operators (best match rot
and best match rot mg), which transforms a reference image to the current image or (if the parameters are
passed in reverse order) from the current image to the reference image. The computed transformation is returned
in HomMat2D and can be used directly with operators that transform data using affine transformations,
e.g., affine trans image.
Parameter
º Row1 (input control) .................................................point.y Htuple . double / long
Row coordinate of the original point.
º Column1 (input control) .............................................point.x Htuple . double / long
Column coordinate of the original point.
º Angle1 (input control) ............................................angle.rad Htuple . double / long
Angle of the original point.
º Row2 (input control) .................................................point.y Htuple . double / long
Row coordinate of the transformed point.
º Column2 (input control) .............................................point.x Htuple . double / long
Column coordinate of the transformed point.
º Angle2 (input control) ............................................angle.rad Htuple . double / long
Angle of the transformed point.
º HomMat2D (output control) ........................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Example
draw_rectangle2 (WindowID, RowTempl, ColumnTempl, PhiTempl, Length1, Length2)
gen_rectangle2 (Rectangle, RowTempl, ColumnTempl, PhiTempl, Length1, Length2)
reduce_domain (ImageTempl, Rectangle, ImageReduced)
create_template_rot (ImageReduced, 4, 0, rad(360), rad(1), ’sort’,
HALCON 6.0

638 CHAPTER 12. TOOLS
’original’, TemplateID)
while (true)
best_match_rot_mg (Image, TemplateID, 0, rad(360), 30, ’true’, 4, Row,
Column, Angle, ErrMatch)
if (ErrMatch

12.1. AFFINE-TRANSFORMATIONS 639
T dvf to hom mat2d
Alternatives
See Also
affine trans image, optical flow match
Basic operators
Module
T vector to rigid ( Htuple Rows1, Htuple Columns1, Htuple Rows2,
Htuple Columns2, Htuple *HomMat2D )
Approximate a rigid affine transformation from point correspondences.
T vector to rigid approximates a rigid affine transformation from at least two point correspondences. The
point correspondences are passed in the tuples (Rows1, Columns1) and(Rows2,Columns2), where corresponding
points must be at the same index positions in the tuples. The transformation is always overdetermined.
Therefore, the returned transformation is the transformation that minimizes the distances between the original
points (Rows1,Columns1) and the transformed points (Rows2,Columns2). The calculated transformation is
returned in HomMat2D and can be used directly with operators that transform data using affine transformations,
e.g., affine trans image.
Parameter
º Rows1 (input control) ................................................point.y-array Htuple . double
Row coordinates of the original points.
º Columns1 (input control) ............................................point.x-array Htuple . double
Column coordinates of the original points.
º Rows2 (input control) ................................................point.y-array Htuple . double
Row coordinates of the transformed points.
º Columns2 (input control) ............................................point.x-array Htuple . double
Column coordinates of the transformed points.
º HomMat2D (output control) ........................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Parallelization Information
T vector to rigid is reentrant and processed without parallelization.
Possible Successor Functions
affine trans image, affine trans region, affine trans contour xld,
affine trans polygon xld, T affine trans point 2d
Alternatives
T vector to hom mat2d, T vector to similarity
T dvf to hom mat2d
Basic operators
See Also
Module
T vector to similarity ( Htuple Rows1, Htuple Columns1, Htuple Rows2,
Htuple Columns2, Htuple *HomMat2D )
Approximate an similarity transformation from point correspondences.
T vector to similarity approximates a similarity transformation from at least two point correspondences.
The point correspondences are passed in the tuples (Rows1, Columns1) and(Rows2,Columns2), where corresponding
points must be at the same index positions in the tuples. If more than two point correspondences
are passed the transformation is overdetermined. In this case, the returned transformation is the transformation
that minimizes the distances between the original points (Rows1,Columns1) and the transformed points
HALCON 6.0

640 CHAPTER 12. TOOLS
(Rows2,Columns2). The calculated transformation is returned in HomMat2D and can be used directly with
operators that transform data using affine transformations, e.g., affine trans image.
Parameter
º Rows1 (input control) ................................................point.y-array Htuple . double
Row coordinates of the original points.
º Columns1 (input control) ............................................point.x-array Htuple . double
Column coordinates of the original points.
º Rows2 (input control) ................................................point.y-array Htuple . double
Row coordinates of the transformed points.
º Columns2 (input control) ............................................point.x-array Htuple . double
Column coordinates of the transformed points.
º HomMat2D (output control) ........................................affine2d-array Htuple . double *
Output transformation matrix.
Parameter Number : 6
Parallelization Information
T vector to similarity is reentrant and processed without parallelization.
Possible Successor Functions
affine trans image, affine trans region, affine trans contour xld,
affine trans polygon xld, T affine trans point 2d
Alternatives
T vector to hom mat2d, T vector to rigid
T dvf to hom mat2d
Basic operators
See Also
Module
12.2 Background-Estimator
close all bg esti ( )
Delete all background estimation data sets.
close all bg esti deletes the background estimation data sets and releases all used memory.
Attention
Since all estimaters are closed by close all bg esti, all handles become invalid.
Result
If it is possible to close the background estimation data sets the operator close all bg esti returns the value
H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
close all bg esti is local and processed completely exclusively without parallelization.
close bg esti
create bg esti
Background estimation
Alternatives
See Also
Module
close bg esti ( long BgEstiHandle )
Delete the background estimation data set.
HALCON/C Reference Manual / 2000-11-15

12.2. BACKGROUND-ESTIMATOR 641
close bg esti deletes the background estimation data set and releases all used memory.
Parameter
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
Example
/* read Init-Image: */
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset
with fixed gains and threshold adaption: */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7,10,3.25,15.0,&BgEstiHandle) \’
/* read the next image in sequence: */
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region1,WindowHandle) ;
/* read the next image in sequence: */
read_image(&Image2,"Image_2") ;
/* estimate the Background: */
run_bg_esti(Image2,&Region2,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region2,WindowHandle) ;
/* etc. */
/* - end of background estimation - */
/* close the dataset: */
close_bg_est(BgEstiHandle) ;
Result
close bg esti returns H MSG TRUE if all parameters are correct.
Parallelization Information
close bg esti is local and processed completely exclusively without parallelization.
run bg esti
create bg esti
Background estimation
Possible Predecessor Functions
See Also
Module
create bg esti ( Hobject InitializeImage, double Syspar1,
double Syspar2, const char *GainMode, double Gain1, double Gain2,
const char *AdaptMode, double MinDiff, long StatNum, double ConfidenceC,
double TimeC, long *BgEstiHandle )
Generate and initialize a data set for the background estimation.
create bg esti creates a new data set for the background estimation and initializes it with the appropriate
parameters. The estimated background image is part of this data set. The newly created set automatically becomes
the current set.
InitializeImage is used as an initial prediction for the background image. For a good prediction an image of
the ovserved scene without moving objects should be passed in InitializeImage. That way the foreground
adaptation rate can be held low. If there is no empty scene image available, a homogenous gray image can be used
instead. In that case the adaptation rate for the foreground image must be raised, because initially most of the image
will be detected as foreground. The intialization image must to be of type byte or real. Because of processing
HALCON 6.0

642 CHAPTER 12. TOOLS
single-channel images, data sets must be created for every channel. Size and region of InitializeImage
determines size and region for all background estimations (run bg esti) that are performed with this data set.
Syspar1 and Syspar2 are the parameters of the Kalman system matrix. The system matrix describes the
system of the gray value changes according to Kalman filter theory. The background estimator implements a
different system for each pixel.
GainMode defines whether a fixed Kalman gain should be used for the estimation or whether the gain should
adapt itself depending on the difference between estimation and actual value. If GainMode is set to ’fixed’,
then Gain1 is used as Kalman gain for pixels predicted as foreground and Gain2 as gain for pixels predicted as
background. Gain1 should be smaller than Gain2, because adaptation of the foreground should be slower than
adaptation of the background. Both Gain1 and Gain2 should be smaller than 1.0.
If GainMode is set to ’frame’, then tables for foreground and background estimation are computed containing
Kalman gains for all the 256 possible grayvalue changes. Gain1 and Gain2 then denote the number of frames
necessary to adapt the difference between estimated value and actual value. So with a fixed time for adaptation
(i.e. number of frames) the needed Kalman gain grows with the grayvalue difference. Gain1 should therefore
be larger than Gain2. Different gains for different grayvalue differences are useful if the background estimator
is used for generating an ’empty’ scene assuming that there are always moving objects in the observated area. In
that case the adaptation time for foreground adaptaion (Gain1) must not be too big. Gain1 and Gain2 should
be bigger than 1.0.
AdaptMode denotes, whether the foreground/background decision threshold applied to the grayvalue difference
between estimation and actual value is fixed or whether it adapts itself depending on the grayvalue deviation of the
background pixels.
If AdaptMode is set to ’off’, the parameter MinDiff denotes a fixed threshold. The parameters StatNum,
ConfidenceC and TimeC are meaningless in this case.
If AdaptMode is set to ’on’, thenMinDiff is interpreted as a base threshold. For each pixel an offset is added
to this threshold depending on the statistical evaluation of the pixel value over time. StatNum holds the number
of data sets (past frames) that are used for computing the grayvalue variance (FIR-Filter). ConfidenceC is used
to determine the confidence interval.
The confidence interval determines the values of the background statistics if background pixels are hidden by
a foreground object and thus are detected as foreground. According to the student t-distribution the confidence
constant is 4.30 (3.25, 2.82, 2.26) for a confidence interval of 99,8% (99,0%, 98,0%, 95,0%). TimeC holds a
time constant for the exp-function that raises the threshold in case of a foreground estimation of the pixel. That
means, the threshold is raised in regions where movement is detected in the foreground. That way larger changes in
illumination are tolerated if the background becomes visible again. The main reason for increasing this tolerance is
the impossibility for a prediction of illumintaion changes while the background is hidden. Therefore no adaptation
of the estimated background image is possible.
Attention
If GainMode was set to ’frame’, the run-time can be extremly long for large values of Gain1 or Gain2, because
the values for the gains’ table are determined by a simple binary search.
Parameter
º InitializeImage (input object) ......................................image Hobject : byte / real
initialization image.
º Syspar1 (input control) ..............................................................real double
1. system matrix parameter.
Default Value : 0.7
Value Suggestions : Syspar1 ¾0.65, 0.7, 0.75
Typical Range of Values : 0.05 Syspar1 1.0
Recommended Value Step : 0.05
º Syspar2 (input control) ..............................................................real double
2. system matrix parameter.
Default Value : 0.7
Value Suggestions : Syspar2 ¾0.65, 0.7, 0.75
Typical Range of Values : 0.05 Syspar2 1.0
Recommended Value Step : 0.05
HALCON/C Reference Manual / 2000-11-15

12.2. BACKGROUND-ESTIMATOR 643
º GainMode (input control) ......................................................string const char *
Gain type.
Default Value : ’fixed’
Value List : GainMode ¾’fixed’, ’frame’
º Gain1 (input control) .................................................................real double
Kalman gain / foreground adaptation time.
Default Value : 0.002
Value Suggestions : Gain1 ¾10.0, 20.0, 50.0, 0.1, 0.05, 0.01, 0.005, 0.001
Restriction : 0.0 Gain1
º Gain2 (input control) .................................................................real double
Kalman gain / background adaptation time.
Default Value : 0.02
Value Suggestions : Gain2 ¾2.0, 4.0, 8.0, 0.5, 0.1, 0.05, 0.01
Restriction : 0.0 Gain2
º AdaptMode (input control) .....................................................string const char *
Threshold adaptation.
Default Value : ’on’
Value List : AdaptMode ¾’on’, ’off’
º MinDiff (input control) ..............................................................real double
Foreground/background threshold.
Default Value : 7.0
Value Suggestions : MinDiff ¾3.0, 5.0, 7.0, 9.0, 11.0
Recommended Value Step : 0.2
º StatNum (input control) .............................................................integer long
Number of statistic data sets.
Default Value : 10
Value Suggestions : StatNum ¾5, 10, 20, 30
Typical Range of Values : 1 StatNum
Recommended Value Step : 5
º ConfidenceC (input control) .........................................................real double
Confidence constant.
Default Value : 3.25
Value Suggestions : ConfidenceC ¾4.30, 3.25, 2.82, 2.62
Recommended Value Step : 0.01
Restriction : 0.0 ConfidenceC
º TimeC (input control) .................................................................real double
Constant for decay time.
Default Value : 15.0
Value Suggestions : TimeC ¾10.0, 15.0, 20.0
Recommended Value Step : 5.0
Restriction : 0.0 TimeC
º BgEstiHandle (output control) .............................................bg estimation long *
ID of the BgEsti data set.
Example
long Handle1, Handle2;
/* read Init-Image: */
read_image(&InitImage,"Init_Image") ;
/* initialize 1. BgEsti-Dataset with
fixed gains and threshold adaption: */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7.0,10,3.25,15.0:&BgEstiHandle) ;
/* initialize 2. BgEsti-Dataset with
frame orientated gains and fixed threshold */
create_bg_esti(InitImage,0.7,0.7,"frame",30.0,4.0,
"off",9.0,10,3.25,15.0:&BgEstiHandle2) ;
Result
create bg esti returns H MSG TRUE if all parameters are correct.
HALCON 6.0

644 CHAPTER 12. TOOLS
Parallelization Information
create bg esti is local and processed completely exclusively without parallelization.
run bg esti
set bg esti params, close bg esti
Background estimation
Possible Successor Functions
See Also
Module
get bg esti params ( long BgEstiHandle, double *Syspar1,
double *Syspar2, char *GainMode, double *Gain1, double *Gain2,
char *AdaptMode, double *MinDiff, long *StatNum, double *ConfidenceC,
double *TimeC )
Return the parameters of the data set.
get bg esti params returns the parameters of the data set. The returned parameters are the same as in
create bg esti and set bg esti params (see these for an explanation).
Parameter
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
º Syspar1 (output control) ...........................................................real double *
1. system matrix parameter.
º Syspar2 (output control) ...........................................................real double *
2. system matrix parameter.
º GainMode (output control) ..........................................................string char *
Gain type.
º Gain1 (output control) ..............................................................real double *
Kalman gain / foreground adaptation time.
º Gain2 (output control) ..............................................................real double *
Kalman gain / background adaptation time.
º AdaptMode (output control) .........................................................string char *
Threshold adaptation.
º MinDiff (output control) ...........................................................real double *
Foreground / background threshold.
º StatNum (output control) ..........................................................integer long *
Number of statistic data sets.
º ConfidenceC (output control) ......................................................real double *
Confidence constant.
º TimeC (output control) ..............................................................real double *
Constant for decay time.
Example
/* read Init-Image:*/
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset with
fixed gains and threshold adaption: */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7.0,10,3.25,15.0,&BgEstiHandle) ;
/* read the next image in sequence: */
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* display the foreground region: */
HALCON/C Reference Manual / 2000-11-15

12.2. BACKGROUND-ESTIMATOR 645
disp_region(Region1,WindowHandle) ;
/* read the next image in sequence: */
read_image(&Image2,"Image_2") ;
/* estimate the Background: */
run_bg_esti(Image2,&Region2,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region2,WindowHandle) ;
/* etc. */
/* change only the gain parameter in dataset: */
get_bg_esti_params(BgEstiHandle,&par1,&par2,&par3,&par4,
&par5,&par6,&par7,&par8,&par9,&par10);
set_bg_esti_params(BgEstiHandle,par1,par2,par3,0.004,
0.08,par6,par7,par8,par9,par10) ;
/* read the next image in sequence: */
read_image(&Image3,"Image_3") ;
/* estimate the Background: */
run_bg_esti(Image3,&Region3,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region3,WindowHandle) ;
/* etc. */
Result
get bg esti params returns H MSG TRUE if all parameters are correct.
Parallelization Information
get bg esti params is reentrant and processed without parallelization.
create bg esti
run bg esti
set bg esti params
Background estimation
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
give bg esti ( Hobject *BackgroundImage, long BgEstiHandle )
Return the estimated background image.
give bg esti returns the estimated background image of the current BgEsti data set. The background image
has the same type and size as the initialization image passed in create bg esti.
Parameter
º BackgroundImage (output object) ..................................image Hobject * : byte / real
Estimated background image of the current data set.
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
Example
/* read Init-Image: */
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset with
fixed gains and threshold adaption: */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7,10,3.25,15.0,&BgEstiHandle) ;
/* read the next image in sequence: */
HALCON 6.0

646 CHAPTER 12. TOOLS
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* give the background image from the aktive dataset: */
give_bg_esti(&BgImage,BgEstiHandle) ;
/* display the background image: */
disp_image(BgImage,WindowHandle) ;
Result
give bg esti returns H MSG TRUE if all parameters are correct.
Parallelization Information
give bg esti is local and processed completely exclusively without parallelization.
run bg esti
Possible Predecessor Functions
Possible Successor Functions
run bg esti, create bg esti, update bg esti
See Also
run bg esti, update bg esti, create bg esti
Background estimation
Module
run bg esti ( Hobject PresentImage, Hobject *ForegroundRegion,
long BgEstiHandle )
Estimate the background and return the foreground region.
run bg esti adapts the background image stored in the BgEsti data set using a Kalman filter on each pixel and
returns a region of the foreground (detected moving objects).
For every pixel an estimation of its grayvalue is computed using the values of the current data set and its stored
background image and the current image (PresentImage). By comparison to the threshold (fixed or adaptive,
see create bg esti) the pixels are classified as either foreground or background.
The background estimation processes only single-channel images. Therefore the background has to be adapted
separately for every channel.
The background estimation should be used on half- or even quarter-sized images. For this, the input images (and
the initialization image!) has to be reduced using zoom image factor. The advantage is a shorter run-time on
one hand and a low-band filtering on the other. The filtering eliminates high frequency noise and results in a more
reliable estimation. As a result the threshold (see create bg esti) can be lowered. The foreground region
returned by run bg esti then has to be enlarged again for further processing.
Attention
The passed image (PresentImage) must have the same type and size as the background image of the current
data set (initialized with create bg esti).
Parameter
º PresentImage (input object) ..........................................image Hobject : byte / real
Current image.
º ForegroundRegion (output object) ............................................region Hobject *
Region of the detected foreground.
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
/* read Init-Image: */
Example
HALCON/C Reference Manual / 2000-11-15

12.2. BACKGROUND-ESTIMATOR 647
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset with
fixed gains and threshold adaption */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7,10,3.25,15.0,&BgEstiHandle) ;
/* read the next image in sequence: */
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region1,WindowHandle) ;
/* read the next image in sequence: */
read_image(&Image2,"Image_2") ;
/* estimate the Background: */
run_bg_esti(Image2,&Region2,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region2,WindowHandle) ;
/* etc. */
Result
run bg esti returns H MSG TRUE if all parameters are correct.
Parallelization Information
run bg esti is reentrant and processed without parallelization.
Possible Predecessor Functions
create bg esti, update bg esti
Possible Successor Functions
run bg esti, give bg esti, update bg esti
See Also
set bg esti params, create bg esti, update bg esti, give bg esti
Background estimation
Module
set bg esti params ( long BgEstiHandle, double Syspar1, double Syspar2,
const char *GainMode, double Gain1, double Gain2, const char *AdaptMode,
double MinDiff, long StatNum, double ConfidenceC, double TimeC )
Change the parameters of the data set.
set bg esti params is used to change the parameters of the data set. The parameters passed by
set bg esti params are the same as in create bg esti (see there for an explanation).
The image format cannot be changed! To do this, a new data set with an initialization image of the appropriate
format has to be created.
To exchange the background image completely, use update bg esti. The current image then has to be passed
for both the input image and the update region.
Attention
If GainMode was set to ’frame’, the run-time can be extremly long for large values of Gain1 or Gain2, because
the values for the gains’ table are determined by a simple binary search.
Parameter
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
º Syspar1 (input control) ..............................................................real double
1. system matrix parameter.
Default Value : 0.7
Value Suggestions : Syspar1 ¾0.65, 0.7, 0.75
Typical Range of Values : 0.05 Syspar1 1.0
Recommended Value Step : 0.05
HALCON 6.0

648 CHAPTER 12. TOOLS
º Syspar2 (input control) ..............................................................real double
2. system matrix parameter.
Default Value : 0.7
Value Suggestions : Syspar2 ¾0.65, 0.7, 0.75
Typical Range of Values : 0.05 Syspar2 1.0
Recommended Value Step : 0.05
º GainMode (input control) ......................................................string const char *
Gain type.
Default Value : ’fixed’
Value List : GainMode ¾’fixed’, ’frame’
º Gain1 (input control) .................................................................real double
Kalman gain / foreground adaptation time.
Default Value : 0.002
Value Suggestions : Gain1 ¾10.0, 20.0, 50.0, 0.1, 0.05, 0.01, 0.005, 0.001
Restriction : 0.0 Gain1
º Gain2 (input control) .................................................................real double
Kalman gain / background adaptation time.
Default Value : 0.02
Value Suggestions : Gain2 ¾2.0, 4.0, 8.0, 0.5, 0.1, 0.05, 0.01
Restriction : 0.0 Gain2
º AdaptMode (input control) .....................................................string const char *
Threshold adaptation.
Default Value : ’on’
Value List : AdaptMode ¾’on’, ’off’
º MinDiff (input control) ..............................................................real double
Foreground/background threshold.
Default Value : 7.0
Value Suggestions : MinDiff ¾3.0, 5.0, 7.0, 9.0, 11.0
Recommended Value Step : 0.2
º StatNum (input control) .............................................................integer long
Number of statistic data sets.
Default Value : 10
Value Suggestions : StatNum ¾5, 10, 20, 30
Typical Range of Values : 1 StatNum
Recommended Value Step : 5
º ConfidenceC (input control) .........................................................real double
Confidence constant.
Default Value : 3.25
Value Suggestions : ConfidenceC ¾4.30, 3.25, 2.82, 2.62
Recommended Value Step : 0.01
Restriction : 0.0 ConfidenceC
º TimeC (input control) .................................................................real double
Constant for decay time.
Default Value : 15.0
Value Suggestions : TimeC ¾10.0, 15.0, 20.0
Recommended Value Step : 5.0
Restriction : 0.0 TimeC
Example
/* read Init-Image:*/
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset with
fixed gains and threshold adaption: */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7.0,10,3.25,15.0,&BgEstiHandle) ;
/* read the next image in sequence: */
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
HALCON/C Reference Manual / 2000-11-15

12.2. BACKGROUND-ESTIMATOR 649
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region1,WindowHandle) ;
/* read the next image in sequence: */
read_image(&Image2,"Image_2") ;
/* estimate the Background: */
run_bg_esti(Image2,&Region2,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region2,WindowHandle) ;
/* etc. */
/* change parameter in dataset: */
set_bg_esti_params(BgEstiHandle,0.7,0.7,"fixed",
0.004,0.08,"on",9.0,10,3.25,20.0) ;
/* read the next image in sequence: */
read_image(&Image3,"Image_3") ;
/* estimate the Background: */
run_bg_esti(Image3,&Region3,BgEstiHandle) ;
/* display the foreground region: */
disp_region(Region3,WindowHandle) ;
/* etc. */
Result
set bg esti params returns H MSG TRUE if all parameters are correct.
Parallelization Information
set bg esti params is reentrant and processed without parallelization.
create bg esti
run bg esti
update bg esti
Background estimation
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
update bg esti ( Hobject PresentImage, Hobject UpDateRegion,
long BgEstiHandle )
Change the estimated background image.
update bg esti overwrites the image stored in the current BgEsti data set with the grayvalues of
PresentImage within the bounds of UpDateRegion. This can be used for a ”‘hard”’ adaptation: Image
regions with a sudden change in (known) background can be adapted very fast this way.
Attention
The passed image (PresentImage) must have the same type and size as the background image of the current
data set (initialized with create bg esti).
Parameter
º PresentImage (input object) ..........................................image Hobject : byte / real
Current image.
º UpDateRegion (input object) .....................................................region Hobject
Region describing areas to change.
º BgEstiHandle (input control) ................................................bg estimation long
ID of the BgEsti data set.
Example
HALCON 6.0

650 CHAPTER 12. TOOLS
/* read Init-Image: */
read_image(&InitImage,"Init_Image") ;
/* initialize BgEsti-Dataset with
fixed gains and threshold adaption */
create_bg_esti(InitImage,0.7,0.7,"fixed",0.002,0.02,
"on",7,10,3.25,15.0,&BgEstiHandle) ;
/* read the next image in sequence: */
read_image(&Image1,"Image_1") ;
/* estimate the Background: */
run_bg_esti(Image1,&Region1,BgEstiHandle) ;
/* use the Region and the information of a knowledge base */
/* to calculate the UpDateRegion */
update_bg_esti(Image1,UpdateRegion,BgEstiHandle) ;
/* then read the next image in sequence: */
read_image(&Image2,"Image_2") ;
/* estimate the Background: */
run_bg_esti(Image2,&Region2,BgEstiHandle) ;
/* etc. */
Result
update bg esti returns H MSG TRUE if all parameters are correct.
Parallelization Information
update bg esti is reentrant and processed without parallelization.
run bg esti
run bg esti
run bg esti, give bg esti
Background estimation
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
12.3 Barcode
T decode 1d bar code ( Htuple BarCodeElements, Htuple BarCodeDescr,
Htuple *Characters, Htuple *Reference, Htuple *IsCorrect )
Decoding of a sequence of elements of a barcode.
T decode 1d bar code decodes a sequence of elements which have been extracted by T find 1d bar code
or T get 1d bar code into a sequence of characters. As input the widths of the elements (in pixels) are
used. The discrete form as it is returned from T discrete 1d bar code can optionally be used. Otherwise
T decode 1d bar code creates the discrete form automatically.
The result of T decode 1d bar code is a sequence of Characters and the corresponding reference numbers
(Reference). In addition a parity check is applied, the result of which is returned in IsCorrect. If all
characters are used to store user data (i.e. no parity is used) the value of this parameter has to be ignored.
Parameter
º BarCodeElements (input control) ..................................number-array Htuple . double
Widths of the elements of the barcode.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a bar code class.
º Characters (output control) ..........................................string-array Htuple . char *
Decoded characters in standard interpretation.
º Reference (output control) ..........................................integer-array Htuple . long *
Decoded characters as numbers.
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 651
º IsCorrect (output control) ................................................integer Htuple . long *
Information whether the barcode is correct.
Value List : IsCorrect ¾0, 1
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple BarcodeFound,Elements,Orientation;
HTuple Characters,Reference,IsCorrect;
Hobject Image,CodeRegion;
gen_1d_bar_code_descr("EAN 13",13,13,&BarCodeDescr);
find_1d_bar_code(Image,&CodeRegion,BarCodeDescr,empty,empty,
&BarcodeFound,&Elements,&Orientation);
if (BarcodeFound[0].l)
{
decode_1d_bar_code(Elements,BarCodeDescr,
&Characters,&Reference,&IsCorrect);
if (IsCorrect[0].l)
for (int i=0; i

652 CHAPTER 12. TOOLS
Parameter
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of the bar code class.
º BarCodeDimension (input control) ....................................integer-array Htuple . long
Tuple with the dimension of the examined symbol. In the case of ECC 200: width, height, symbol code.
º BarCodeData (input control) ..........................................integer-array Htuple . long
Tuple with the data values of the examined symbol.
º SymbolCharacters (output control) ..................................string-array Htuple . char *
Data and error codewords of the symbol.
º CorrSymbolData (output control) ....................................integer-array Htuple . long *
Corrected data codewords of the symbol.
º DecodedData (output control) ........................................integer-array Htuple . long *
Decoded data characters as numbers.
º DecodingError (output control) ..........................................integer Htuple . long *
Number of errors during the decoding process.
º StructuredAppend (output control) .................................integer-array Htuple . long *
If the symbol belongs to a group (“structured append”): position in the group, total symbol number, group
(“file”) id.
Result
The return value signals incorrect parameters as well as a failure in the decoding procedure. The error code 8812,
e.g., signals that the decoded data stream contained an invalid data word. Up to now, user-defined control words
can not be handled by the operator. If such control words are detected in the decoded data stream, the error code
8813 is returned.
Parallelization Information
T decode 2d bar code is reentrant and processed without parallelization.
T get 2d bar code
Barcode reader
Possible Predecessor Functions
Module
T discrete 1d bar code ( Htuple Elements, Htuple BarCodeDescr,
Htuple *DisrecteBarCode )
Generate a discrete barcode from the elements widths.
T discrete 1d bar code converts the list of element widths (output from T find 1d bar code or
T get 1d bar code) into a discrete barcode. Thus every element is then represented by its number of modules
(1,2,..) and no longer as its width in pixels.
This operator is used if the barcode type is not available so that T decode 1d bar code cannot be applied,
thus the user wants to find the barcode with the help of HALCON operators and then himself decode the
barcode. To create the barcode description the operator T gen 1d bar code descr gen is used and with
T find 1d bar code the element widths are extracted. Then T discrete 1d bar code is used to create
the list of the multiple of the modules.
Parameter
º Elements (input control) ............................................number-array Htuple . double
List of elements widths of the barcode.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a bar code class.
º DisrecteBarCode (output control) .................................number-array Htuple . long *
Widths of elements as multiple of modules.
Example
HTuple empty; // empty list of values
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 653
HTuple
HTuple
HTuple
Hobject
BarCodeDescr;
BarcodeFound,Elements,Orientation;
DiscreteBarCode;
Image,CodeRegion;
gen_1d_bar_code_descr_gen(20,40,2,empty,empty,-1.0,"false",&BarCodeDescr);
find_1d_bar_code(Image,&CodeRegion,BarCodeDescr,empty,empty,
&BarcodeFound,&Elements,&Orientation);
if (BarcodeFound[0].l)
{
discrete_1d_bar_code(Elements,BarCodeDescr,&DiscreteBarCode);
for (int i=0; i

654 CHAPTER 12. TOOLS
’min size element’ During the analysis of elements (or parts of them) this parameter is used to eliminate very
small objects which do not belong to the barcode. You have to be aware that with a low image quality
elements can be divided into smaller pieces. The parameter has to be larger than the smallest piece. With
good image quality the value can be larger to reduce runtime. In any case the value may not be larger than
the length of one element (in pixels). The area calculated includes only the border of the elements and is
thus smaller. If the value is too large parts of the barcode may be missing.
Default value: 30
Used for: Search for bar code region
’max size element’ Similar to the minimal size this parameter is used to suppress large objects. You have to
know that with a low resolution multiple elements can be extracted as one intermediate region. The value
has thus to be larger than the size of this region. This can be the size of many elements. The area internally
calculated includes only the border of the elements. Furthermore the value should be smaller than the total
size of the barcode.
Default value: 15000
Used for: Search for bar code region
’angle range’ This parameter has the same function as the parameter ’sum angles’ but here it is used during the
inital search for elements of the barcode. It has influence on the estimation of the orientation of the elements.
For low quality images this value has to be large. A small value results in a reduced runtime. The value is
given in degrees. There is no need to change the parameter.
Default value: 24
Used for: Search for bar code region
’correct angle’ This parameter is used to decide if a region can be part of a barcode. For this the orientation
of all boundary points are calculated. If enough points have the same orientation the region is accepted for
further processing. Increasing this value reduces the amount of accepted regions and improves speed. For
low image quality this value has to be low.
Default value: 0.5 (corresponds 50 percent)
Used for: Search for bar code region
’dilation factor’ After the initial step of finding elements these are conbined into a barcode region
(CodeRegion). This is implemented using the closing operator. The mask size is automatically estimated.
If this estimation is wrong it can be corrected using this parameter. If the barcode elements have
large gaps the value has to be larger than one. If the barcode is very close to other objects and is wrongly
connected to this object the value can be smaller than 1. The parameter is independent of the image quality
and runtime.
Default value: 1
Used for: Search for bar code region
’sum angles’ This parameter is used for the final estimation of the orientation of the barcode region (value of
Orientation). For this at first the orientation of the boundaries of all elements are calculated. The most
frequent orientation is calculated. Using the neighboring orientations the mean orientation is calculated. The
parameter determines the amount of neighboring angles used for summing up. The value is given in degrees.
Default value: 40
Used for: Search for bar code region
’min area bar code’ This value is used for the final decision if the region is a barcode. The parameter specifies
the minimum area of the barcode. This area used here consists only of the boundary pixels of the elements
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 655
and is thus smaller than the area of CodeRegion. If areas were found which are too small the value has
to be increased. The parameter can also be used if small areas with the same orientation as the barcode
elements were found. The parameter is independent of the image quality and runtime.
Default value: 1000
Used for: Search for bar code region
’sigma project’ For the extraction of the element widths the gray values of the barcode region are projected in
the direction of the elements. The data calculated this way is smoothed to reduce noise. For barcodes with
large gaps between the elements this value can be increased if extra elements were detected. The value
should be larger than 0.5.
Default value: 0.7
Used for: Extraction of element widths
’amplitude project’ For the calculation of the element widths from the gray projections this parameter controls
the minimum amplitude (gray value difference) between dark and light elements. With a lot of noise (e.g.
scratches) this value can be increased. For low contrast images the value has to be low.
Default value: 3
Used for: Extraction of element widths
’width project’ The gray value projections are calculated only in the center part of the barcode region. The
parameter specifies the half width of this area. If the orientation of the region is not estimated correctly this
value has to be small. If there are distortions (e.g. scratches) this value can be increased. For very small
barcodes the value can be decreased.
Default value: 25
Used for: Extraction of element widths
’add length project’ Because the length of the barcode is sometimes to short to get get elements at the beginning
and at the end the region is extended based on this parameter. If the barcode lies near to another object
resulting in a connection of both areas this value can be decreased.
Default value: 5
Used for: Extraction of element widths
’interpolation project’ With this parameter the type of interpolation used for the gray projection is determined.
With a value of 1 a bilinear interpolation is used. With 0 no interpolation is used. In this case the runtime is
shorter but it might result in a wrong extraction of the elements.
Default value: 1
Used for: Extraction of element widths
Please note that these parameters should normally not be changed.
Parameter
º Image (input object) ..............................................................image Hobject
Image with bar code inside.
º CodeRegion (output object) .....................................................region Hobject *
Region of bar code.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a bar code class.
HALCON 6.0

656 CHAPTER 12. TOOLS
º GenericName (input control) ...................................string(-array) Htuple . const char *
Names of optional control parameters.
Default Value : ’[]’
Value List : GenericName ¾’amplitude sobel’, ’min size element’, ’max size element’, ’angle range’,
’correct angle’, ’dilation factor’, ’sum angles’, ’sigma project’, ’amplitude project’, ’width project’,
’add length project’, ’interpolation project’
º GenericValue (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double / long
Values of optional control parameters.
Default Value : ’[]’
º BarcodeFound (output control) ............................................integer Htuple . long *
Information whether the barcode was found.
Value List : BarcodeFound ¾0, 1
º BarCodeElements (output control) ...............................number-array Htuple . double *
Widths of elements.
º Orientation (output control) .........................................angle.rad Htuple . double *
Orientation of bar code.
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple BarcodeFound,Elements,Orientation;
HTuple Characters,Reference,IsCorrect;
Hobject Image,CodeRegion;
gen_1d_bar_code_descr("EAN 13",13,13,&BarCodeDescr);
find_1d_bar_code(Image,&CodeRegion,BarCodeDescr,empty,empty,
&BarcodeFound,&Elements,&Orientation);
if (BarcodeFound[0].l)
{
decode_1d_bar_code(Elements,BarCodeDescr,
&Characters,&Reference,&IsCorrect);
if (IsCorrect[0].l)
for (int i=0; i

12.3. BARCODE 657
T find 1d bar code region ( Hobject Image, Hobject *CodeRegion,
Htuple BarCodeDescr, Htuple GenericName, Htuple GenericValue,
Htuple *Orientation )
Look for multiple barcode regions in an image.
T find 1d bar code region looks for multiple barcodes in the image. In contrast to T find 1d bar code
this operator is used if an image contains more than one barcode. Here only the regions but not the widths of the
elements are extracted. For every region the orientation in radians is calculated.
The control of the image processing is identical to T find 1d bar code. The description of the parameters
GenericName and GenericValue can be found at this operator.
Parameter
º Image (input object) ..............................................................image Hobject
Image with barcodes inside.
º CodeRegion (output object) ..............................................region(-array) Hobject *
Regions of barcodes.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a bar code class.
º GenericName (input control) ...................................string(-array) Htuple . const char *
Names of optional parameters.
Default Value : ’[]’
Value List : GenericName ¾’amplitude sobel’, ’min size element’, ’max size element’, ’angle range’,
’correct angle’, ’dilation factor’, ’sum angles’
º GenericValue (input control) . . . . . . . . . . . . . . . . . .number(-array) Htuple . double / long / const char *
Values of optional parameters.
Default Value : ’[]’
º Orientation (output control) .......................................real(-array) Htuple . double *
Orientation of bar code.
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple Orientations, Elements;
HTuple Characters,Reference,IsCorrect;
Hobject Image,CodeRegions,CodeRegion,GrayRegion;
long num;
gen_1d_bar_code_descr("code 39",4,15,&BarCodeDescr);
find_1d_bar_code_region(Image,&CodeRegion,BarCodeDescr,empty,empty,
&Orientations);
count_obj(CodeRegions,&num);
for (long i=0; i

658 CHAPTER 12. TOOLS
Possible Predecessor Functions
T gen 1d bar code descr, T gen 1d bar code descr gen
Possible Successor Functions
T get 1d bar code, count obj, select obj, reduce domain
T find 1d bar code
sobel dir
Barcode reader
Alternatives
See Also
Module
T find 2d bar code ( Hobject Image, Hobject *CodeRegion,
Htuple BarCodeDescr, Htuple GenParamNames, Htuple GenParamValues,
Htuple *CodeRegDescr )
Find regions that might contain a 2D bar code.
T find 2d bar code searches in the image Image for regions that might contain a 2D bar code. Candidate regions
are returned in the array of regions CodeRegion. Whether such a region really contains a (readable) 2D bar
code can only be determined with the help of the operator T get 2d bar code (or T get 2d bar code pos).
Besides regions that might contain a 2D bar code, the operator passes further, internal information about the regions
to the operator for extracting the data from a symbol (T get 2d bar code or T get 2d bar code pos). This
information is stored in a region descriptor and returned in the parameter CodeRegDescr.
Depending on the method for printing the bar code (’mode’), different image processing steps are performed.
Together with other information about the 2D bar code, the actual printing method is part of a descriptor created
with the help of the operator T gen 2d bar code descr and passed in the parameter BarCodeDescr.
In the case of difficult conditions, additional control parameters can be passed to the operator with the help of the
(optional) generic parameters GenParamNames nd GenParamValues, in the form of descriptor-value pairs.
One group of parameters describes the appearance of the symbols in the actual images, e.g., the expected size of
data elements in pixels. The operator will then check candidate regions against the specified criteria. Suitable
values can be determined from the real images, e.g., by manually selecting a region with a bar code and then
applying the corresponding operator. If the specification of such parameters does not lead to successfully extracted
regions, the user can influence the underlying image processing operators directly with the help of a second group
of parameters. As the image processing steps taken depend on the printing method, different parameters are to be
applied.
¯ Parameter that will be passed on in CodeRegDescr:
’module width’ Mean size of a module (data element) in pixels.
From this quantity, a set of other parameters will be derived. A module should have a size of 4 to 16
pixels in order to be recognized successfully.
GenParamValues: 0
default: 10
¯ Parameters for the printing method ’printed’:
The following parameters are used to limit the set of candidate regions with the help of region features. To
prevent the use of a certain feature, the corresponding parameter must be set to -1.
’anisometry max’ Maximum anisometry (see operator eccentricity).
GenParamValues: 1 (-1: feature not used)
default: 1.45
’compactness min’ Minimum compactness (see operator compactness).
GenParamValues: 1 (-1: feature not used)
default: 1.2
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 659
’compactness max’ Maximum compactness.
GenParamValues: ’compactness min’ (-1: feature not used)
default: 3.0
’circularity max’ Maximum circularity (see operator circularity).
GenParamValues: 0...1.0 (-1: featurenotused)
default: 0.8
’circularity min’ Minimum circularity.
GenParamValues: ’circularity max’ (-1: feature not used)
default: 0.45
’deviation min’ Minimum deviation of gray values (see operator intensity).
GenParamValues: 1.0 (-1: feature not used)
default: 20.0
The following parameters are automatically derived from the size of a module, ’module width’, and from
parameters of the bar code descriptor BarCodeDescr (see operator T gen 2d bar code descr). However,
they can be adjusted individually, too.
ATTENTION: If you want to set ’module width’ together with other parameters, make sure set ’module
width’ BEFORE the others!
’mean mask size 1’ Mask size for the first smoothing of the image.
GenParamValues: 3
default:
¾ £ ¼ ÑÓÙÐ ÛØ ¼
’mean mask size 2’ Mask size for the second smoothing of the image.
GenParamValues: 5
default:
½¼¼ £ ¼ ÑÓÙÐ ÛØ ¼
’area min’ Minimum size of the symbol in pixels squared.
GenParamValues: 0
default:
¼¾ £ ¼ ÑÓÙÐ ÛØ ¼¾ £ ¼ ÓÐÙÑÒ× ÑÒ ¼ £ ¼ ÖÓÛ× ÑÒ ¼
’area max’ Maximum size of the symbol in pixels squared.
GenParamValues: ’area min’
default:
¼¼ £ ¼ ÑÓÙÐ ÛØ ¼¾ £ ¼ ÓÐÙÑÒ× ÑÒ ¼ £ ¼ ÖÓÛ× ÑÒ ¼
’closing mask rad’ Mask size for calling the operator closing circle with a test region..
GenParamValues: 0
default:
’module width’
¯ Parameters for the printing method ’engraved darkfield’:
’compactness min’ Minimum compactness (see operator compactness).
GenParamValues: 1.0 (-1: feature not used)
default: 1.2
’compactness max’ .
GenParamValues: ’compactness min’ (-1: feature not used)
default: 3.0
’edge thresh’ Maximum compactness.
GenParamValues: 0...255
default: 120
’region rect2 rel’ Relation between the areas of the region and the smallest surrounding rectangle.
GenParamValues: 1.0
default: 0.7
’median mask rad’ Mask size for the initial median filtering (see operator median image).
GenParamValues: 0
default:
¼½ £ ¼ ÑÓÙÐ ÛØ ¼ ·¼
HALCON 6.0

660 CHAPTER 12. TOOLS
¯ Parameters for the printing method ’engraved lightfield’:
’anisometry max’ Maximum anisometry (see operator eccentricity).
GenParamValues: 1 (-1: feature not used)
default: 1.45
’compactness min’ Minimum compactness (see operator compactness).
GenParamValues: 1 (-1: feature not used)
default: 1.2
’compactness max’ Maximum compactness.
GenParamValues: ’compactness min’ (-1: feature not used)
default: 3.0
’circularity max’ Maximum circularity (see operator circularity).
GenParamValues: 0...1.0 (-1: featurenotused)
default: 0.8
’circularity min’ Minimum circularity.
GenParamValues: ’circularity max’ (-1: feature not used)
default: 0.45
’deviation min’ Minimum deviation of gray values (see operator intensity).
GenParamValues: 1.0 (-1: feature not used)
default: 20.0
’mean mask size’ Mask size for smoothing the image.
GenParamValues: 3
default:
½¼ £ ¼ ÑÓÙÐ ÛØ ¼
’area min’ Minimum size of the symbol in pixels squared.
GenParamValues: 0
default:
¼¾ £ ¼ ÑÓÙÐ ÛØ ¼¾ £ ¼ ÓÐÙÑÒ× ÑÒ ¼ £ ¼ ÖÓÛ× ÑÒ ¼
’area max’ Maximum size of the symbol in pixels squared.
GenParamValues: ’area min’
default:
¼¼ £ ¼ ÑÓÙÐ ÛØ ¼¾ £ ¼ ÓÐÙÑÒ× ÑÒ ¼ £ ¼ ÖÓÛ× ÑÒ ¼
’closing mask rad’ Mask size for calling the operator closing circle with a test region..
GenParamValues: 0
default:
’module width’
’opening mask rad’ Mask size for calling the operator opening circle with a test region..
GenParamValues: 0
default:
½ £ ¼ ÑÓÙÐ ÛØ ¼
Parameter
º Image (input object) ..............................................................image Hobject
Image of one or more bar codes.
º CodeRegion (output object) ..............................................region(-array) Hobject *
Regions that might contain a bar code.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a 2D bar code class to look for.
º GenParamNames (input control) ................................string(-array) Htuple . const char *
List of names of (optional) generic parameters controlling the image processing.
Default Value : ’[]’
º GenParamValues (input control) . . . . . . . . . . . . . . . number(-array) Htuple . double / long / const char *
List of values of generic parameters controlling the image processing.
Default Value : ’[]’
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 661
º CodeRegDescr (output control) ......................string-array Htuple . char * / long * / double *
Additional parameters describing the bar code regions. They can be used for extracting the data (see
T decode 2d bar code).
Result
The operator T find 2d bar code returns the value H MSG TRUE if the given parameters are correct. Otherwise,
an exception will be raised.
Parallelization Information
T find 2d bar code is reentrant and processed without parallelization.
T gen 2d bar code descr
Possible Predecessor Functions
Possible Successor Functions
T get 2d bar code, T get 2d bar code pos
Barcode reader
Module
T gen 1d bar code descr ( Htuple CodeName, Htuple MinCharacters,
Htuple MaxCharacters, Htuple *BarCodeDescr )
Generate a decscription of a 1D bar code.
T gen 1d bar code descr generates a description of a one dimensional bar code. This description
is used for the search (T find 1d bar code or T find 1d bar code region) and the decoding
(T decode 1d bar code) of the barcode. T gen 1d bar code descr is therefore the first operator in a
program sequence for barcode processing. T gen 1d bar code descr has only to be called once at the beginning
of a program. The descriptor can be used multiple times. In the case of different types of barcodes the
operator has to be called once for each type.
You have to be aware that this description contains only basic informations about the barcode. Thus an arbitrary
description can be used to extract almost every type of barcode. On the other hand a specific description is
important for the decoding of a barcode type.
Parameter
º CodeName (input control) ..............................................string Htuple . const char *
Name of bar code.
Default Value : ”EAN 13”
Value List : CodeName ¾”2/5 industrial”, ”2/5 interleaved”, ”code 39”, ”EAN 13”, ”EAN 8”, ”Codabar”
º MinCharacters (input control) .............................................integer Htuple . long
Minimum number of characters (if not fixed).
Default Value : 6
Value Suggestions : MinCharacters ¾-1, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 14, 16, 18, 20, 25, 30
º MaxCharacters (input control) .............................................integer Htuple . long
Maximum number of characters (if not fixed).
Default Value : 10
Value Suggestions : MaxCharacters ¾-1, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 14, 16, 18, 20, 25, 30, 35, 40,
50
º BarCodeDescr (output control) ......................string-array Htuple . char * / long * / double *
Description of a bar code class.
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple BarcodeFound,Elements,Orientation;
HTuple Characters,Reference,IsCorrect;
Hobject Image,CodeRegion;
gen_1d_bar_code_descr("EAN 13",13,13,&BarCodeDescr);
HALCON 6.0

662 CHAPTER 12. TOOLS
find_1d_bar_code(Image,&CodeRegion,BarCodeDescr,empty,empty,
&BarcodeFound,&Elements,&Orientation);
if (BarcodeFound[0].l)
{
decode_1d_bar_code(Elements,BarCodeDescr,
&Characters,&Reference,&IsCorrect);
if (IsCorrect[0].l)
for (int i=0; i

12.3. BARCODE 663
º StopElement (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) Htuple . long
List of elements of the stop sequence. The width of an element is given as the number of modules. Gaps are
given as negative values.
Default Value : ’[1,-1]’
º MaxSizeRatio (input control) ............................................number Htuple . double
Maximum ratio length to height.
Default Value : 2.5
Value List : MaxSizeRatio ¾-1,2,3,4,5,6
º DiscreteCode (input control) .........................................string Htuple . const char *
Discrete code (ignore white elements).
Default Value : ’false’
Value List : DiscreteCode ¾’true’, ’false’
º BarCodeDescr (output control) ......................string-array Htuple . char * / long * / double *
Description of a bar code class.
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple BarcodeFound,Elements,Orientation;
HTuple DiscreteBarCode;
Hobject Image,CodeRegion;
gen_1d_bar_code_descr_gen(20,40,2,empty,empty,-1.0,"false",&BarCodeDescr);
find_1d_bar_code(Image,&CodeRegion,BarCodeDescr,empty,empty,
&BarcodeFound,&Elements,&Orientation);
if (BarcodeFound[0].l)
{
discrete_1d_bar_code(Elements,BarCodeDescr,&DiscreteBarCode);
for (int i=0; i

664 CHAPTER 12. TOOLS
The bar code can be described more closely using the parameters GenParamNames and GenParamValues,
which form pairs of descriptors and values. The following parameters describe the size and the form of the symbols:
’columns’ Exact number of columns of the symbol.
GenParamValues: 10, 12, 14, 16, 18, 20, 22, 24, 26, 32, 36, 40,
44, 48, 52, 64, 72, 80, 88, 96, 104, 120, 132, 144
default: -
’columns min’ Minimum number of columns.
GenParamValues: 10...144 (even)
default: 10
’columns max’ Maximum number of columns.
GenParamValues: 10...144 (even)
’rows’ Exact number of rows of the symbol.
GenParamValues: 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 32, 36, 40,
44, 48, 52, 64, 72, 80, 88, 96, 104, 120, 132, 144
default: -
’rows min’ Minimum number of rows.
GenParamValues: 8...144 (even)
default: 8
’rows max’ Maximum number of rows.
GenParamValues: 8...144 (even)
default: 144
’shape’ Form of the symbol.
GenParamValues:
default:
’square’, ’rectangle’, ’any’
’any’
The following parameters describe the printing method and the appearance of the bar code:
’foreground’ Appearance of bits corresponding to a logical 1 (foreground).
2D bar codes can be printed dark on light or vice versa. If the appearance of bits corresponding to a logical
1 can be specified in advance, computing time will be significantly reduced, especially when looking for
regions that might contain a bar code (operator T find 2d bar code).
GenParamValues: ’any’: unknown appearance
’dark’,’black’: symbols are printed dark on light
’light’,’white’: symbols are printed light on dark
default:
’any’
’mode’ Method used for printing the 2D bar code.
By specifying this parameter, image processing can be optimized.
GenParamValues: ’printed’: Standard black-and-white printing. Modules appear as
square regions; neighboring modules with the same value
form one region.
’engraved darkfield’: Modules with the value 1 are engraved into the surface,
e.g. by a laser. Using dark field lighting these modules
appear as dark round dots with a white corona; neighboring
modules with the value 1 are therefore separated by
gaps.
’engraved lightfield’: Similar to ’engraved darkfield’, but using light field lighting.
Modules with the value 1 therefore appear as light
dots with a dark corona; neighboring modules with the
value 1 are again separated by gaps.
default:
’printed’
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 665
Parameter
º CodeType (input control) ..............................................string Htuple . const char *
Type of the 2D bar code.
Default Value : ”Data Matrix ECC 200”
Value List : CodeType ¾”Data Matrix ECC 200”
º GenParamNames (input control) ..................................string-array Htuple . const char *
List of names of generic parameters describing the 2D bar code class.
Default Value : ’[]’
Value List : GenParamNames ¾’columns’, ’columns min’, ’columns max’, ’rows’, ’rows min’,
’rows max’, ’foreground’, ’shape’, ’mode’
º GenParamValues (input control) .................integer-array Htuple . long / const char * / double
List of values of the generic parameters describing the 2D bar code class.
Default Value : ’[]’
Value List : GenParamValues ¾8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 32, 36, 40, 44, 48, 52, 64, 72, 80,
88, 96, 104, 120, 132, 144, ’dark’, ’light’, ’square’, ’rectangle’, ’printed’, ’engraved darkfield’,
’engraved lightfield’, ’any’
º BarCodeDescr (output control) ......................string-array Htuple . char * / long * / double *
Description of the 2D bar code class.
Example
gen_2d_bar_code_descr (’Data Matrix ECC 200’, [’mode’,’foreground’],
[’printed’,’dark’], BarCodeDescr)
Result
The operator T gen 2d bar code descr returns the value H MSG TRUE if the given parameters are correct.
Otherwise, an exception will be raised.
Parallelization Information
T gen 2d bar code descr is reentrant and processed without parallelization.
T find 2d bar code
Barcode reader
Possible Successor Functions
Module
T get 1d bar code ( Hobject BarCodeRegion, Htuple BarCodeDescr,
Htuple GenericName, Htuple GenericValue, Htuple Orientation,
Htuple *BarCodeElements )
Extract the widths of the elements inside a barcode region.
T get 1d bar code extracts the widths of the elements of a barcode inside the specified region.
The control of the processing is identical to T find 1d bar code. The description of the parameters
GenericName and GenericValue can be found at this operator.
Parameter
º BarCodeRegion (input object) ....................................................image Hobject
Region of bar code.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of a bar code class.
º GenericName (input control) ...................................string(-array) Htuple . const char *
Names of optional parameters.
Default Value : ’[]’
Value List : GenericName ¾’sigma project’, ’amplitude project’, ’width project’, ’add length project’,
’interpolation project’
º GenericValue (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double / long
Values of optional parameters.
Default Value : ’[]’
HALCON 6.0

666 CHAPTER 12. TOOLS
º Orientation (input control) ............................................angle.rad Htuple . double
Orientation of bar code.
º BarCodeElements (output control) ...............................number-array Htuple . double *
Widths of elements.
Example
HTuple empty; // empty list of values
HTuple BarCodeDescr;
HTuple Orientations, Elements;
HTuple Characters,Reference,IsCorrect;
Hobject Image,CodeRegions,CodeRegion,GrayRegion;
long num;
gen_1d_bar_code_descr("code 39",4,15,&BarCodeDescr);
find_1d_bar_code_region(Image,&CodeRegion,BarCodeDescr,empty,empty,
&Orientations);
count_obj(CodeRegions,&num);
for (long i=0; i

12.3. BARCODE 667
size of the data field is not to be confused with the size of the symbol which in turn encompasses additional finder
and alignment patterns.
If no 2D bar code could be extracted the operator returns a corresponding error code.
In difficult cases, the user can influence image processing with the help of the (optional) generic parameters
GenParamNames and GenParamValues. The width of a module in pixels (’module width’) does
not need to be specified, it is part of the region descriptor CodeRegDescr. As in the case of the operator
T find 2d bar code, for the different printing methods different image processing steps are applied, leading
to different parameters.
As a short overview, image processing falls into the following parts: First, the region BarCodeRegion is divided
into a dark and a light region by applying a thresholding operator. Because there must be a “silent” area around
each 2D bar code, this area can be examined to determine whether the bar code is printed black-on-white or vice
versa. With this information, the dark and the light region can be assigned to the logical data values. Next,
BarCodeRegion is approximated by a rectangle. Then, the special finder patterns that each each symbol must
contain are searched for in the border areas of the rectangle. From the finder pattern, the size of the data matrix
and the size and the position of the modules (data elements) can be determined. Finally, the value of the modules
is determined.
¯ Parameters controlling the classification of modules as being dark or light:
’module rad ratio’ Part of the module that is to be used for its classification.
This parameter controls which part of the module area (in percent, measured from the center) is used to
determine its value. With a ’module rad ratio’ of 1.0, the whole area of the module will be examined.
With very small ’module rad ratio’, only one point in the middle will be examined.
GenParamValues: 0 ’module rad ratio’ 1
default: printing method ’printed’, ’engraved lightfield’: 0.3
printing method ’engraved darkfield’: 0.7
’use grayvals’ Method for the classification of modules (Selectable only for the printing methods ’printed’
and ’engraved lightfield’; for the printing method ’engraved darkfield’, the gray-value-based method
is always used!).
The parameter ’use grayvals’ controls by which method the modules are classified. If ’use grayvals’ is
set to ’no’, the module’s value is determined by examining whether the part of the module specified by
’module rad ratio’ is part of the region that has been assigned the value 1. If more than half of the
module is part of this region, the module is interpreted as a logical one.
In the case ’use grayvals’ is set to ’yes’, the gray values inside ’module rad ratio’ are examined. For
this, the known border parts of the symbol are used to create classificators with the features “minimum
gray value”, “maximum gray value”, and “range of gray values”. A feature will be automatically excluded
if it cannot separate the known dark and light regions. It can also be excluded manually with
the help of the parameters below. The value of the modules is then determined by applying the trained
classificators. In case of ambiguous results, the majority decision is adopted.
If none of the gray value features can separate the test regions, the operator switches automatically
to the region-based method in case the printing method is set to ’printed’. This can be detected by
examining the data values returned in BarCodeData: The region-based method yields multiples of 4,
the gray-value-based method values between -3 and +3. If separation fails when the printing method is
’engraved darkfield’, an error code is returned. Note, that classification performance can be enhanced
by chosing a suitable value for ’module rad ratio’.
GenParamValues: ’yes’, ’no’
default:
’yes’
’use grayval min’ Use the feature “gray value minimum” for classifying module values.
GenParamValues: ’yes’, ’no’
default:
’yes’
’use grayval max’ Use the feature “gray value maximum” for classifying module values.
GenParamValues: ’yes’, ’no’
default: ’printed’, ’engraved lightfield’: ’yes’
’engraved darkfield’:
’no’
HALCON 6.0

668 CHAPTER 12. TOOLS
’use grayval range’ Use the feature “gray value range” for classifying module values.
GenParamValues: ’yes’, ’no’
default:
’yes’
¯ Parameters for the printing methods ’printed’ and ’engraved lightfield’:
’enlarge region rad’ Enlarge the symbol region.
GenParamValues: 0 ( 0: enlargment prohibited)
default: 2.5
’thresh percent’ Area of the histogram in which to look for an optimal threshold.
The threshold for separating dark and light regions will be searched for in the middle ’thresh percent’
percent of the gray value histogram. If ’thresh percent’ is set to 0, a threshold exactly in the middle of
the histogram is selected. If ’thresh percent’ is set to 100, the whole histogram will be searched. Note,
that the threshold influences not only the size of the data region, but also the position of the surrounding
rectangle and with it, slightly, the position of the modules.
GenParamValues: 0...100
default: 50
’thresh step width’ Step width for the search of the optimal threshold.
The histogram area specified in the parameter ’thresh percent’ will be stepped through using
’thresh step width’ until an optimal separation of dark and light regions is reached. The optimum
is declared to be found when the number of individual regions is at its maximum. The smaller
’thresh step width’ is, the better a threshold can be determined, however at the cost of rising computing
time, of course.
GenParamValues: 0
default: 10
’smooth cont’ Parameter for approximating the region by a polygon (rectangle).
The parameter ’smooth cont’ controls to which degree the contour is smoothed before approximating it
with a polygon (see operator segment contours xld).
GenParamValues: 0,3,5,7,9,. . .
default: 5
’max line dist1’, ’max line dist2’ Distance between the contour and its approximation.
The parameters ’max line dist1’ and ’max line dist2’ control the maximal distance between the contour
and its approximation (see operator segment contours xld).
GenParamValues: 0
default: 4
’min cont len’ Minimum length of the contour elements in pixel.
Contour elements shorter than ’min cont len’ will be ignored when approximating the region by a
rectangle. In the case of small symbols or low resolution, it can be helpful to decrease this parameter.
GenParamValues: 0
default: 50
’border width min’ Minimum width of the border search area.
The border area of the symbol region must contain the so-called finder patterns (ECC 200: two lines
with the value 1, two with alternating values). To find these patterns, a search region is constructed
along the sides of the rectangle. Starting with ’border width min’, the width of the seach region is
increased until the finder patterns have been detected, or until ’border width max’ has been reached.
GenParamValues: 0
default: 2
’border width max’ Maximum width of the border search area.
GenParamValues: ’border width min’
default: 5
’border width’ Exact width of the border search area.
Alternatively, the exact width of this search area can be specified in the parameter ’border width’. This
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 669
automatically sets ’border width min’ and ’border width max’.
GenParamValues: 0
default: -
Parameters for the printing method ’engraved darkfield’:
’median mask rad’ Mask size for the initial median filtering (see operator median image).
GenParamValues: 3,5,7,...,501
default: ’module width’*0.1 + 0.5
’gray erosion size’ Mask size for the subsequent gray value erosion (see operator gray erosion rect).
GenParamValues: 3,5,7,...,511
default: ’module width’*0.18 + 3.5
’measure sigma’ Parameter for the extraction of linear edge segment pairs (see operator
T measure pairs).
GenParamValues: 0.4...100
default: ’module width’ 20: 0.7
’module width’ 20: 1.4
’measure thresh’ Parameter for the extraction of linear edge segment pairs (see operator
T measure pairs).
GenParamValues: 1...255
default: 2.0
Attention
The operator T get 2d bar code returns error codes to signal that the candidate region did not contain a valid
2D bar code. As the region candidates extracted by the operator T find 2d bar code can perfectly well encompass
regions without a bar code, every call to T get 2d bar code should be surrounded by error handling
code (see example).
Parameter
º BarCodeRegion (input object) ...................................................region Hobject
Region that might contain a 2D bar code.
º Image (input object) ..............................................................image Hobject
Corresponding image.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of the bar code class.
º CodeRegDescr (input control) .....................string-array Htuple . const char * / long / double
Additional parameters describing the bar code region. They can be used for extracting the data
º GenParamNames (input control) ..................................string-array Htuple . const char *
List of names of (optional) generic control parameters.
Default Value : ’[]’
º GenParamValues (input control) .............................number-array Htuple . double / long
List of values of the generic parameters.
Default Value : ’[]’
º BarCodeDimension (output control) .................................integer-array Htuple . long *
Tuple with the dimension of the extracted symbol. In the case of ECC 200: data field width, height, symbol
index.
º BarCodeData (output control) ........................................integer-array Htuple . long *
Tuple with the data values of the extracted symbol. value 0: logical 1, value 0: logical 0, value =
0: module could not be classified.
Example
dev_error_var (ErrorCode, 1)
gen_2d_bar_code_descr (’Data Matrix ECC 200’, [’mode’], [’printed’],
BarCodeDescr)
HALCON 6.0

670 CHAPTER 12. TOOLS
read_image (Image, ’bar2d.tif’)
find_2d_bar_code (Image, CodeRegion, BarCodeDescr,
[’module_width’], [10], CodeRegDescr)
SymbolNum := |CodeRegion|
for i := 1 to SymbolNum by 1
ObjectSelected := CodeRegion[i]
dev_set_check (’˜give_error’)
get_2d_bar_code (ObjectSelected, Image, BarCodeDescr, CodeRegDescr,
[], [], BarCodeDimension, BarCodeData)
err := ErrorCode
dev_set_check (’give_error’)
if (err = 2)
decode_2d_bar_code (BarCodeDescr, BarCodeDimension, BarCodeData,
SymbolCharacters, CorrSymbolData, DecodedData,
DecodingError, StructuredAppend)
if (|DecodedData|)
tuple_chrt (DecodedData, String)
endif
endif
endfor
Result
The return value can signal incorrect parameters as well as the failure to extract a 2D bar code. Such a failure can be
due to different causes: If no surrounding rectangle was found, the operator returns the error code 8808. Error code
8807 signals that the rectangle does not lie completely inside the image. If no finder pattern was detected inside the
border search area, the error code 8810 is returned. If the two continuous lines forming the ’L’ of the finder pattern
could not be found, the error code 8809 is returned. In the case of the printing method ’engraved darkfield’, the
error code 8811 signals that none of the gray value features can separate the test regions, i.e. that modules cannot
be classified.
Parallelization Information
T get 2d bar code is reentrant and processed without parallelization.
T find 2d bar code
T decode 2d bar code
T get 2d bar code pos
Barcode reader
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
T get 2d bar code pos ( Hobject BarCodeRegion, Hobject Image,
Htuple BarCodeDescr, Htuple CodeRegDescr, Htuple GenParamNames,
Htuple GenParamValues, Htuple *BarCodeDimension, Htuple *BarCodeData,
Htuple *DataElementRow, Htuple *DataElementCol )
Extract the data values of the elements (in ECC 200: “modules”) inside a bar code region (“Data Matrix symbol”)
and their positions in the image.
T get 2d bar code pos extracts the 2D bar code data from a candidate symbol region given in
BarCodeRegion and the corresponding image given in Image elements. In contrast to T get 2d bar code,
this operator also returns the positions of the data elements in the image in the parameters DataElementRow
and DataElementCol. This can be used to check the result of the operator, e.g., by displaying the data in the
real image. For a description of the other parameters, see T get 2d bar code.
Attention
The operator T get 2d bar code pos returns error codes to signal that the candidate region did not contain a
valid 2D bar code. As the region candidates extracted by the operator T find 2d bar code can perfectly well
HALCON/C Reference Manual / 2000-11-15

12.3. BARCODE 671
encompass regions without a bar code, every call to T get 2d bar code pos should be surrounded by error
handling code (see example).
Parameter
º BarCodeRegion (input object) ...................................................region Hobject
Region that might contain a bar code.
º Image (input object) ..............................................................image Hobject
Corresponding image.
º BarCodeDescr (input control) .....................string-array Htuple . const char * / long / double
Description of the 2D bar code class.
º CodeRegDescr (input control) .....................string-array Htuple . const char * / long / double
Additional parameters describing the bar code region. They can be used for extracting the data.
º GenParamNames (input control) ..................................string-array Htuple . const char *
List of names of (optional) generic control parameters.
Default Value : ’[]’
º GenParamValues (input control) .............................number-array Htuple . double / long
List of values of the generic parameters.
Default Value : ’[]’
º BarCodeDimension (output control) .................................integer-array Htuple . long *
Tuple with the dimension of the extracted symbol. In the case of ECC 200: data field width, height, symbol
index.
º BarCodeData (output control) ........................................integer-array Htuple . long *
Tuple with the data values of the extracted symbol. value 0: logical 1, value 0: logical 0, value =
0: module could not be classified.
º DataElementRow (output control) ....................................real-array Htuple . double *
Tuple with the row positions of the data elements of the extracted symbol in the image.
º DataElementCol (output control) ....................................real-array Htuple . double *
Tuple with the column positions of the data elements of the extracted symbol in the image.
Example
dev_set_check (’˜give_error’)
get_2d_bar_code_pos (ObjectSelected, Image, BarCodeDescr,
CodeRegDescr, [], [], BarCodeDimension, BarCodeData,
DataElementRow, DataElementCol)
err := ErrorCode
dev_set_check (’give_error’)
if (err = 2)
idx := 0
dev_update_pc (’off’)
dev_update_time (’off’)
dev_update_var (’off’)
for m := 0 to BarCodeDimension[0]-1 by 1
for n := 0 to BarCodeDimension[1]-1 by 1
if (BarCodeData[idx]>0)
set_color (WindowHandle, ’green’)
else
if (BarCodeData[idx]

672 CHAPTER 12. TOOLS
dev_update_pc (’on’)
dev_update_time (’on’)
dev_update_var (’on’)
decode_2d_bar_code (BarCodeDescr, BarCodeDimension, BarCodeData,
SymbolCharacters, CorrSymbolData, DecodedData,
DecodingError, StructuredAppend)
endif
Result
The return value can signal incorrect parameters as well as the failure to extract a 2D bar code. Such a failure can be
due to different causes: If no surrounding rectangle was found, the operator returns the error code 8808. Error code
8807 signals that the rectangle does not lie completely inside the image. If no finder pattern was detected inside the
border search area, the error code 8810 is returned. If the two continuous lines forming the ’L’ of the finder pattern
could not be found, the error code 8809 is returned. In the case of the printing method ’engraved darkfield’, the
error code 8811 signals that none of the gray value features can separate the test regions, i.e., that modules cannot
be classified.
Parallelization Information
T get 2d bar code pos is reentrant and processed without parallelization.
T find 2d bar code
T decode 2d bar code
T get 2d bar code
T gen 2d bar code descr
Barcode reader
Possible Predecessor Functions
Possible Successor Functions
Alternatives
See Also
Module
12.4 Calibration
T caltab points ( Htuple CalTabDescrFile, Htuple *X, Htuple *Y,
Htuple *Z )
Read the mark center points from the calibration table description file.
T caltab points is used to read the mark center points from the calibration table description file
CalTabDescrFile. The mark center points are 3D coodinates in the calibration table coordinate system und describe
the 3D model of the calibration table. The application of the operator T camera calibration projects
these model points into the image. By minimizing the distance between the projected model points and the observed
2D coordinates in the image (see T find marks and pose) the exact values for the internal and external
camera parameters are computed.
Parameter
º CalTabDescrFile (input control) .....................................string Htuple . const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º X (output control) ......................................................real-array Htuple . double *
X-coordinates of the mark center points.
º Y (output control) ......................................................real-array Htuple . double *
Y-coordinates of the mark center points.
º Z (output control) ......................................................real-array Htuple . double *
Z-coordinates of the mark center points.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 673
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple StartPose,CamParam,FinalPose,Errors;
// read calibration image
HImage Image1("calib-01.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start pose
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
StartCamPar[4] = 384;
// Cx
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
::camera_calibration(NX,NY,NZ,RCoord1,CCoord1,StartCamPar,StartPose,
11,&CamParam,&FinalPose,&Errors);
// visualize calibration result
::disp_image(Image1,WindowHandle);
::set_color(WindowHandle,"red");
::disp_caltab("caltab.descr",CamParam,FinalPose,1.0);
Result
T caltab points returns H MSG TRUE if all parameter values are correct and the file CalTabDescrFile
has been read successfully. If necessary, an exception handling is raised.
Parallelization Information
T caltab points is reentrant and processed without parallelization.
T camera calibration
Possible Successor Functions
See Also
find caltab, T find marks and pose, T camera calibration, T disp caltab,
T sim caltab, T project 3d point, T get line of sight, create caltab
Camera calibration
Module
T camera calibration ( Htuple NX, Htuple NY, Htuple NZ, Htuple NRow,
Htuple NCol, Htuple StartCamParam, Htuple NStartPose,
Htuple EstimateParams, Htuple *CamParam, Htuple *NFinalPose,
Htuple *Errors )
Determine all camera parameters by a simultanous minimization process.
T camera calibration performs the calibration of a video camera. Thus, known 3D model points (with
coordinates NX, NY, NZ) are projected in the image and the sum of the squared distance between these projections
and the corresponding image points (with coordinates NRow, NCol) is minimized.
In case of converging, the exact internal (CamParam)andexternal(NFinalPose) camera parameters are determined
by this minimization algorithm. The parameters StartCamParam and NStartPose are used as initial
values for the minimization process. Since this algorithm simultaneously handles correspondences between image
and model points from different images, it is also called multi image calibration.
HALCON 6.0

674 CHAPTER 12. TOOLS
In general camera calibration means the exact determination of the parameters, which model the (optical) projection
of any 3D world point È Ï into a (sub-)pixel [r,c] on the CCD sensor of the camera. This is of importance, if
the original 3D pose of an object has to be computed using an image (e.g., measuring of industrial pieces).
The underlying camera model is a pinhole camera with radial distortions if the focal length passed in
StartCamParam is greater than 0. It describes the transform of a 3D world point È Ï into a (sub-)pixel [r,c] of
the video image by the following equations:
Ù
½·
È Ü Ý Þ℄ Ì Ê¡È Ï · Ì
Ù Focus ¡ Ü Þ
and Ú Focus ¡ Ý Þ
¾Ù Ô½ ´Ù ¾·Ú and Ú Ô ¾Ú
¾ µ
½·
Ù Ë Ü · Ü and Ö Ú
Ë Ý · Ý
½ ´Ù ¾·Ú ¾ µ
If the focal length is passed as 0 in StartCamParam, the camera model of a telecentric camera with radial
distortions is used, i.e., it is assumed that the optics of the lens of the camera performs a parallel projection. In
this case, the corresponding equations are:
Ù
È Ü Ý Þ℄ Ì Ê¡È Ï · Ì
Ù Ü and Ú Ý
¾Ù
½·
Ô½ ´Ù ¾·Ú bzw. Ú ¾Ú
¾ µ ½· ½ ´Ù ¾·Ú¾ µ
Ô
Ù Ë Ü · Ü bzw. Ö Ú
Ë Ý · Ý
These equations consist of a coordinate transform from the world coordinate system into the camera coordinate
system, a perspective or parallel projection into the image plane, a radial distortion of the projected point, and
finally a sampling and an image center displacement.
The total of 15 camera parameters can be divided into the internal and external camera parameters:
Internal camera parameters: These parameters describe the characterisctics of the used video camera, especially
the dimension of the CCD sensor itself and the projection properties of the used combination of lens, camera,
and frame grabber. The camera model (as described above) contains the following 8 parameters:
Focus: Focal length of the lens. 0 for telecentric lenses.
Kappa (): Distortion coefficient to model the pillow- or barrel-shaped distortions caused by the lens.
Sx: Scale factor, corresponds to the horizontal distance between two neighboring cells on the CCD sensor.
Attention: This value increases, if the image is subsampled!
Sy: Scale factor, corresponds to the vertical distance between two neighboring cells on the CCD sensor.
Since in most cases the image signal is sampled line-synchronously, this value is determined by the
dimension of the CCD sensor and needn’t be estimated for pinhole cameras by the calibration process.
Attention: This value increases, if the image is subsampled!
Cx: Column coordinate of the image center point (center of the radial distortion).
Cy: Row coordinate of the image center point (center of the radial distortion).
ImageWidth: Width of the sampled video image. Attention: This value decreases, if the image is subsampled!
ImageHeight: Height of the sampled video image. Attention: This value decreases, if the image is subsampled!
External camera parameters: These 7 parameters describe the position and orientation of the camera and are
also called as camera pose. The relative position of the camera with regard of a world or object coordinate
system is defined by a 3D translational vector (parameters 1, 2, and 3). The orientation of the camera is
described by the three rotation angles around the three coordinate axes (parameters 4, 5, and 6).
The last value within the camera pose encodes the representation type of the described 3D transform: E.g.,
the value ’0’ is the code of the representation type 1 and says, that the transform of a point is described,
the 3D rotation is performed before the 3D translation, that the three rotations are specified as angles (in
degree), and that the rotation order is ­-¬-«, i.e., the first rotation is around the Z-axis, the second one
around the new Y-axis, and the third one around the new X-axis, which is generated after the second rotation.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 675
T camera calibration operates with all types of 3D transform for NStartPose. The sense of the
other representation types are explained at T create pose.
Note, that in contrast to the external camera parameters the internal ones are the same for all positions and
orientations of the camera.
The use of T camera calibration leads to some questions, which are dealed with in the following sections:
How to generate a appropriate calibration table? The simplest method to determine the internal parameter of
a CCD camera is the use of the planar calibration table generated by the operator create caltab. In
case of small distances between object and lens it may be sufficient to print the calibration pattern by a laser
printer and to mount it on a cardboard. Otherwise – especially by using a wide-angle lens – it is possible to
print the PostScript file on a large inkjet printer and to mount it on a aluminum table. It is very important,
that the mark coordinates in the calibration table description file correspond to the real ones on the calibration
table with high accuracy. Thus, the calibration table description file has to be modified in accordance with
the measurement of the calibration table!
How to take a set of suitable images? If you use the planar calibration table, you can proceed in the following
way: With the combination of lens (fixed distance!), camera, and frame grabber to be calibrated a set of images
of the calibration table has to be taken, see open framegrabber and grab image. The following
items have to be considered:
¯ At least a total of 10 to 20 images should be taken into account.
¯ The calibration table has to be completely visible (incl. border!).
¯ Reflections etc. on the calibration table should be avoided.
¯ Within the set of images the calibration table should appear in different positions and orientations: Once
left in the image, once right, once (left and right) at the bottom, once (left or right) at the top, from
different distances etc. At this, the calibration table should be rotated a little around its X- and/or Y-axis,
so the perspective distortions of the calibration pattern are clearly visible. Thus, the external camera
parameters (camera pose with regard of the calibration table) should be set to a large variety of different
values!
¯ The calibration table should fill at least a quarter of the whole image to ensure the robust detection of the
marks.
How to extract the calibration marks in the images? If a planar calibration table is used, for each image the
operators find caltab and T find marks and pose can be used to determine the coordinates of the
calibration marks and to compute a rough estimate for the external camera parameters. The concatenation
of these values can directly be used as initial values for the external camera parameters (NStartPose) in
T camera calibration.
Obviously, images, on which the segmentation of the calibration table (find caltab) hasfailedorthe
calibration marks haven’t been determined successfully by T find marks and pose, should not be used.
How to find suitable initial values for the internal camera parameters ? The
operators
T find marks and pose (determination of initial values for the external camera parameters) and
T camera calibration require initial values for the internal camera parameters. These parameters
can be provided by a appropriate text file (see T read cam par), which can be generated by
T write cam par or can be edited manually.
The following should be considered for the initial values of the single parameters:
Focus: The initial value is the nominal focal length of the the used lens, e.g., 0.008 m.
Kappa: Use 0.0 as initial value. The calibratied value normally lies between -1000.0 and -50000.0 1/Ñ ¾
depending on the used lens.
Sx: The initial value for the horizontal distance between two neighboring CCD cells depends on the dimension
of the used CCD chip of the camera (see technical specifications of the camera). Generally, common
CCD chips are either 1/3”-Chips (e.g., SONY XC-73, SONY XC-777), 1/2”-Chips (e.g., SONY XC-
999, Panasonic WV-CD50), or 2/3”-Chips (e.g., SONY DXC-151, SONY XC-77). Notice: The value
of Sx increases, if the image is subsampled! Appropriate initial values are:
Full image (768*576) Subsampling (384*288)
1/3"-Chip 0.0000055 m 0.0000110 m
1/2"-Chip 0.0000086 m 0.0000172 m
2/3"-Chip 0.0000110 m 0.0000220 m
HALCON 6.0

676 CHAPTER 12. TOOLS
The value for Sx is calibrated, since the video signal of a CCD camera normally isn’t sampled pixelsynchronously.
Sy: Since most off-the-shelf cameras have quadratic pixels, the same values for Sy are valid as for Sx. In
contrast to Sx the value for Sy will NOT be calibrated for pinhole cameras, because the video signal of a
CCD camera normally is sampled line-synchronously. Thus, the initial value is equal to the final value.
Appropriate initial values are:
Full image (768*576) Subsampling (384*288)
1/3"-Chip 0.0000055 m 0.0000110 m
1/2"-Chip 0.0000086 m 0.0000172 m
2/3"-Chip 0.0000110 m 0.0000220 m
Cx and Cy: Initial values for the coordinates of the image center is the half image width and half image
height. Notice: The values of Cx and Cy decrease, if the image is subsampled! Appropriate initial
values are:
Full image (768*576) Subsampling (384*288)
Cx 384.0 192.0
Cy 288.0 144.0
ImageWidth and ImageHeight: These two parameters are set by the the used frame grabber and therefore
are not calibrated. Appropriate initial values are:
Full image (768*576) Subsampling (384*288)
ImageWidth 768 384
ImageHeight 576 288
Which camera parameters have to be estimated? The input parameter EstimateParams is used to select
which camera parameters to estimate. Usually this parameter is set to ’all’, i.e., all 6 external camera parameters
(translation and rotation) and all internal camera parameters have to be determined. Otherwise,
EstimateParams contains a tuple of strings indicating the combination of parameters to estimate.
What is the order within the single parameters? The length of the tuple NStartPose corresponds to the
number of calibration images, e.g., using 15 images leads to a length of the tuple NStartPose equal to
½ ¡ ½¼ (15 times the 7 external camera parameters). The first 7 values correspond to the camera pose
of the first image, the next 7 values to the pose of the second one, etc.
This fixed number of calibration images has to be considered within the tuples with the coordinates of the 3D
model marks and the extracted 2D marks. If 15 images are used, the length of the tuples NRow and NCol
is 15 times the length of the tuples with the coordinates of the 3D model marks (NX, NY, andNZ). If every
image consists 49 marks, the length of the tuples NRow and NCol is ½ ¡ ¿, while the length of the
tuples NX, NY, andNZ is 49. The order of the values in NRow and NCol is “image after image”, i.e., using
49 marks the first 3D model point corresponds to the 1st, 50th, 99th, 148th, 197th, 246th, etc. extracted 2D
mark.
The 3D model points can be read from a calibration table description file using the operator
T caltab points. Initial values for the camera pose can be determined by applying
T find marks and pose for each image. The tuple NStartPose is set by the concatenation of all
these camera poses.
What is the meaning of the output parameters? If the camera calibration process is finished successfully, i.e.,
the minimization process is converged, the output parameters CamParam and NFinalPose contain the
computed exact values for the internal and external camera parameters. The length of the tuple NFinalPose
corresponds to the length of the tuple NStartPose.
The representation types of NFinalPose correspond to the representation type of the first tuple of
NStartPose. You can convert the representation type by T convert pose type. The sense of all
kind of representation types for the 3D transform are explained at T create pose.
The computed average errors (Errors) give an impression of the accuracy of the calibration. The error
values (deviations in x- and y-coordinates) are measured in pixels.
Must I use a planar calibration table? No. The operator T camera calibration is designed in a way, that
the input tuples NX, NY, NZ, NRow, andNCol can contain any 3D/2D correspondences, see the above paragraph
explaining the order of the single parameters.
Thus, it makes no difference, how the required 3D model marks and the corresponding extracted 2D marks
are determined. On the one hand it is possible to use a 3D calibration pattern, on the other hand you
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 677
also can use any characteristic points (natural landmarks) with known position in the world. By setting
EstimateParams to 6, it is possible to compute the world position of the camera! Hereby at least
three 3D/2D-correspondences are necessary as input. Homogeneous transformation matrices are useful
to generate NStartPose, see program example in T hom mat3d to pose and/or program example in
T create pose for generating NStartPose directly.
Attention
The minimization process of the calibration depends on the initial values of the internal (StartCamParam)and
external (NStartPose) camera parameters. The computed average errors Errors give an impression of the
accuracy of the calibration. The errors (deviations in x- and y-coordinates) are measured in pixels.
Parameter
º NX (input control) .......................................................real-array Htuple . double
Ordered Tuple with all X-coordinates of the calibration marks (in meters).
º NY (input control) .......................................................real-array Htuple . double
Ordered Tuple with all Y-coordinates of the calibration marks (in meters).
º NZ (input control) .......................................................real-array Htuple . double
Ordered Tuple with all Z-coordinates of the calibration marks (in meters).
º NRow (input control) .....................................................real-array Htuple . double
Ordered Tuple with all row-coordinates of the extracted calibration marks (in pixels).
º NCol (input control) .....................................................real-array Htuple . double
Ordered Tuple with all column-coordinates of the extracted calibration marks (in pixels).
º StartCamParam (input control) ..................................real-array Htuple . double / long
Initial values for the internal camera parameters.
º NStartPose (input control) .....................................pose-array Htuple . double / long
Ordered tuple with all initial values for the external camera parameters.
º EstimateParams (input control) ................................string Htuple . const char * / long
Camera parameters to be estimated.
Default Value : ’all’
Value List : EstimateParams ¾’all’, ’alpha’, ’beta’, ’gamma’, ’transx’, ’transy’, ’transz’, ’focus’,
’kappa’, ’cx’, ’cy’, ’sx’, ’sy’
º CamParam (output control) .................................number-array Htuple . double * / long *
Internal camera parameters.
º NFinalPose (output control) .................................pose-array Htuple . double * / long *
Ordered tuple with all external camera parameters.
º Errors (output control) ...............................................real-array Htuple . double *
Average error distances in pixels.
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple RCoord2,CCoord2,StartPose2;
HTuple RCoord3,CCoord3,StartPose3;
HTuple StartPoses, RCoords, CCoords;
HTuple CamParam,NFinalPose,Errors;
// read calibration images
HImage Image1("calib-01.tiff");
HImage Image2("calib-02.tiff");
HImage Image3("calib-03.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab2 = Image2.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab3 = Image3.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start poses
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
HALCON 6.0

678 CHAPTER 12. TOOLS
StartCamPar[4] = 384;
// Cx
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose1);
RCoord2 = Image2.FindMarksAndPose(Caltab2,"caltab.descr",StartCamPar,
128,10,&CCoord2,&StartPose2);
RCoord3 = Image3.FindMarksAndPose(Caltab3,"caltab.descr",StartCamPar,
128,10,&CCoord3,&StartPose3);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
StartPoses = (StartPose1.Append(StartPose2)).Append(StartPose3);
RCoords = (RCoord1.Append(RCoord2)).Append(RCoord3);
CCoords = (CCoord1.Append(CCoord2)).Append(CCoord3);
::camera_calibration(NX,NY,NZ,RCoords,CCoords,StartCamPar,StartPoses,
11,&CamParam,&NFinalPose,&Errors);
// write internal camera parameters to file
::write_cam_par(CamParam,"campar.dat");
Result
T camera calibration returns H MSG TRUE if all parameter values are correct and the desired camera
parameters have been determined by the minimization algorithm. If necessary, an exception handling is raised.
Parallelization Information
T camera calibration is reentrant and processed without parallelization.
Possible Predecessor Functions
T find marks and pose, T caltab points, T read cam par
Possible Successor Functions
T write pose, T pose to hom mat3d, T disp caltab, T sim caltab
See Also
find caltab, T find marks and pose, T disp caltab, T sim caltab, T write cam par,
T read cam par, T create pose, T convert pose type, T write pose, T read pose,
T pose to hom mat3d, T hom mat3d to pose, T caltab points, create caltab
Camera calibration
Module
T change radial distortion cam par ( Htuple Mode, Htuple CamParIn,
Htuple Kappa, Htuple *CamParOut )
Determine new camera parameters in accordance to the specified radial distortion.
T change radial distortion cam par modifies the internal camera parameters in accordance to the specified
radial distortion Kappa. ViaMode one of the following modes can be selected:
¯ ’fixed’: OnlyKappa is modified, the other internal camera parameters remain unchanged. In general this
leads to a change of the visible part of the scene.
¯ ’fullsize’: The scale factors Ë Ü and Ë Ý and the image center point Ü Ý℄ Ì are modified in order to
preserve the visible part of the scene. Thus, all points visible in the original video image are also visible in
the modified (rectified) image. In general this leads to undefined pixels in the modified image.
¯ ’adaptive’: A trade off between the other modes: The visible part of the scene is slightly reduced to prevent
undefined pixels in the modified image. Similiar to ’fullsize’ the scale factors and the image center point are
modified.
In all modes the radial distortion coefficient in CamParOut is set to Kappa. The transformation of a pixel in
the modified image into the image plane using CamParOut results in the same point as the transformation of a
pixel in the original image via CamParIn.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 679
Parameter
º Mode (input control) ....................................................string Htuple . const char *
Mode
Default Value : ’adaptive’
Value Suggestions : Mode ¾’fullsize’, ’adaptive’, ’fixed’
º CamParIn (input control) ...............................................real-array Htuple . double
Internal camera parameters (original).
º Kappa (input control) .........................................................real Htuple . double
Desired radial distortion.
Default Value : 0.0
º CamParOut (output control) ...........................................real-array Htuple . double *
Internal camera parameters (modified).
Result
T change radial distortion cam par returns H MSG TRUE if all parameter values are correct. If necessary,
an exception handling is raised.
Parallelization Information
T change radial distortion cam par is reentrant and processed without parallelization.
Possible Predecessor Functions
T camera calibration, T read cam par
Possible Successor Functions
T change radial distortion image, T change radial distortion contours xld
See Also
T camera calibration, T read cam par, T change radial distortion image,
T change radial distortion contours xld
Module
Camera calibration
T change radial distortion contours xld ( Hobject Contours,
Hobject *ContoursRectified, Htuple CamParIn, Htuple CamParOut )
Change the radial distortion of contours.
T change radial distortion contours xld changes the radial distortion of the input contours
Contours in accordance to the internal camera parameters CamParIn and CamParOut. Each subpixel of
an input contour is transformed into the image plane using CamParIn and subsequently projected into a subpixel
of the corresponding contour in ContoursRectified using CamParOut.
If CamParOut was computed via T change radial distortion cam par, the contours
ContoursRectified are equivalent to Contours obtained with a lense with a modified radial distortion.
If is ¼ , the contours are rectified. A subsequent pose estimation (determination of the external camera
parameters) is not affected by this operation.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Original contours.
º ContoursRectified (output object) ..................................xld cont(-array) Hobject *
Resulting contours with modified radial distortion.
º CamParIn (input control) ...............................................real-array Htuple . double
Internal camera parameter for Contours.
º CamParOut (input control) ..............................................real-array Htuple . double
Internal camera parameter for ContoursRectified.
Parallelization Information
T change radial distortion contours xld is reentrant and processed without parallelization.
Possible Predecessor Functions
T change radial distortion cam par, gen contours skeleton xld, edges sub pix,
smooth contours xld
HALCON 6.0

680 CHAPTER 12. TOOLS
Possible Successor Functions
gen polygons xld, smooth contours xld
See Also
T change radial distortion cam par, T camera calibration, T read cam par,
T change radial distortion image
Module
Camera calibration
T change radial distortion image ( Hobject Image, Hobject Region,
Hobject *ImageRectified, Htuple CamParIn, Htuple CamParOut )
Change the radial distortion of an image.
T change radial distortion image changes the radial distortion of the input image Image in accordance
to the internal camera parameters CamParIn and CamParOut. The image size remains unchanged. Each
pixel of the output image is transformed into the image plane using CamParOut and subsequently projected into
a subpixel of Image using CamParIn. The resulting grayvalue is determined by bilinear interpolation. If the
subpixel is outside of Image, the corresponding pixel in ImageRectified is set to ’black’ and eliminated from
the image domain.
If CamParOut was computed via T change radial distortion cam par, ImageRectified is equivalent
to Image obtained with a lense with a modified radial distortion. If is ¼ , the image is rectified. A
subsequent pose estimation (determination of the external camera parameters) is not affected by this operation.
Parameter
º Image (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject
Original image.
º Region (input object) .............................................................region Hobject
Region of interest in Image.
º ImageRectified (output object) . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) Hobject *
Resulting image with modified radial distortion.
º CamParIn (input control) ...............................................real-array Htuple . double
Internal camera parameter for Image.
º CamParOut (input control) ..............................................real-array Htuple . double
Internal camera parameter for Image.
Result
T change radial distortion image returns H MSG TRUE if all parameter values are correct and the
input is not empty. If necessary, an exception handling is raised.
Parallelization Information
T change radial distortion image is reentrant and processed without parallelization.
Possible Predecessor Functions
T change radial distortion cam par, read image, grab image
edges image, threshold
Possible Successor Functions
See Also
T change radial distortion cam par, T camera calibration, T read cam par,
T change radial distortion contours xld
Module
Camera calibration
T contour to world plane xld ( Hobject Contours,
Hobject *ContoursTrans, Htuple CamParam, Htuple CamPose, Htuple Scale )
Transform an XLD contour to a world plane represented by external camera parameters.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 681
The operator T contour to world plane xld transforms contour points given in Contours into a plane
in the world coordinate system. The plane is either equal to the plane of the calibration table or parallel to it if
the operator T set origin pose has been applied previously to correct the thickness of the calibration table.
In the first step the line of sight between the projection center and the image point is computed in the camera
system, taking into account the radial distortion using the internal camera parameters CamParam. The line of
sight is then transformed into the world coordinate system using the external camera parameters CamPose. By
intersecting the plane (Z=0) with the line of sight the pseudo 3d coordinates are obtained, of which the X- and the
Y-coordinates are stored in the transformed contour ContoursTrans. It is possible to scale the coordinates with
the parameter Scale. This is particularly useful when displaying the coordinates in an image. The parameter
Scale must be specified in [ÙÒØÔÜÐ]. The original unit is determined by the coordinates of the calibration
targets. In many cases this unit is introduced into the calibration as ’meters’, i.e., one meter in the world coordinate
system corresponds to one pixel in the image. In this case, it is possible to set the pixel size directly by selecting
’m’, ’cm’, ’mm’ or ’m’ for the parameter Scale.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input XLD contours to be transformed.
º ContoursTrans (output object) ........................................xld cont(-array) Hobject *
Transformed XLD contours.
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º CamPose (input control) .........................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
º Scale (input control) ...................................number Htuple . const char * / long / double
Scale oder dimension
Default Value : ’m’
Value Suggestions : Scale ¾’m’, ’cm’, ’mm’, ’microns’, ’m’, 1.0, 0.01, 0.001, ’1e-6’, 0.0254, 0.3048,
0.9144
Result
T contour to world plane xld returns H MSG TRUE if all parameter values are correct. If necessary, an
exception handling is raised.
Parallelization Information
T contour to world plane xld is reentrant and processed without parallelization.
Possible Predecessor Functions
T create pose, T hom mat3d to pose, T camera calibration, T hand eye calibration,
T set origin pose
See Also
T image points to world plane
Module
Camera calibration
T convert pose type ( Htuple PoseIn, Htuple OrderOfTransform,
Htuple OrderOfRotation, Htuple ViewOfTransform, Htuple *PoseOut )
Change the representation type of 3D pose parameters.
T convert pose type converts the 3D pose PoseIn into a 3D pose PoseOut with a different representation
type.
A 3D pose defines a 3D transformation consisting of a translation and a rotation. Halcon supports different representation
types for such a transformation. This can be, for example, external camera parameters, given by a 3D
translation vector (in meters), three rotation angles, and the code of the representation type of the 3D transformation.
For example, the value ’0’ is the code of representation type 1, and signifies that the transformation of a point
is described, that the 3D rotation is applied before the translation, that the rotation is given by angles (in degrees),
and that the order of the rotations is ­-¬-«, i.e., the first rotation is around the z-axis, the second rotation around
HALCON 6.0

682 CHAPTER 12. TOOLS
the y-axis, and the third roation around the x-axis. The meaning of the other representation types is described with
the operator T create pose.
The parameter ViewOfTransform determines, whether the new transformation PoseOut describes the
transformation of a point (’point’) or the transformation of a coordinate system (’coordinate system’).
OrderOfTransform determines whether the rotation (’Rp+T’) or the translation (’R(p-T)’) is applied first.
The meaning of the three rotation values is determined by OrderOfRotation. The values ’gba’ and ’abg’
signify that the rotation parameters describe the three rotation angles « (around the x-axis), ¬ (around the y-axis),
and ­ (around the z-axis) in the 3D transformation. For ’gba’, the rotation order is ­ , ¬ , « ,andfor’abg’ it is
« , ¬ , ­ .IfOrderOfRotation is passed as ’rodriguez’, the rotation parameters are interpreted as Rodriguez
rotation vector.
Parameter
º PoseIn (input control) ...........................................pose-array Htuple . double / long
3D transformation.
Parameter Number : 7
º OrderOfTransform (input control) ...................................string Htuple . const char *
Order of rotation and translation.
Default Value : ”Rp+T”
Value Suggestions : OrderOfTransform ¾”Rp+T”, ”R(p-T)”
º OrderOfRotation (input control) .....................................string Htuple . const char *
Meaning of the rotation values.
Default Value : ”gba”
Value Suggestions : OrderOfRotation ¾”gba”, ”abg”, ”rodriguez”
º ViewOfTransform (input control) .....................................string Htuple . const char *
View of transformation.
Default Value : ”point”
Value Suggestions : ViewOfTransform ¾”point”, ”coordinate system”
º PoseOut (output control) .....................................pose-array Htuple . double * / long *
3D transformation.
Parameter Number : 7
Example
HTuple Pose, Pose2;
// get pose (external camera parameters):
::read_pose ("campose.dat", &Pose) ;
// convert pose to a pose with desired semantic
::convert_pose_type ( Pose, "Rp+T", "abg", "coordinate_system", &Pose2);
Result
T convert pose type returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised.
Parallelization Information
T convert pose type is reentrant and processed without parallelization.
Possible Predecessor Functions
T create pose, T hom mat3d to pose, T camera calibration, T hand eye calibration
T write pose
Possible Successor Functions
See Also
T create pose, T get pose type, T write pose, T read pose
Camera calibration
Module
create caltab ( double Width, const char *CalTabDescrFile,
const char *CalTabFile )
Generate calibration table description file and corresponding PostScript file.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 683
create caltab generates the description of a plane calibration table. This calibration table consists of 49 black
circular marks on a white plane, which are surrounded by a black frame. The parameter Width sets the width
(equal to the height) of the whole calibration table in meters. Using a width of 0.8 m the distance between two
neighboring marks becomes 10 cm, and the mark radius and the frame width are set to 2.5 cm.
The file CalTabDescrFile contains the calibration table description, e.g., the number of rows and columns
of the calibration table, the geometry of the surrounding frame (see find caltab), and the coordinates and
the radius of all calibration table marks given in the calibration table coordinate system. A file generated by
create caltab looks like the following (comments are marked by a ’#’ at the beginning of a line):
#
# Description of the standard calibration table
# used for the CCD-camera calibration in Halcon
# (generated by create\_caltab())
#
# Halcon version 4.11 -- Fri Feb 7 16:13:56 1997
#
# 7 rows X 7 columns
# Distance between mark centers [meter]: 0.1
# Number of marks per row
r 7
# Number of marks per column
c 7
# Quadratic frame (with outer and inner border) around calibration table
w 0.025
o -0.41 0.41 0.41 -0.41
i -0.4 0.4 0.4 -0.4
# calibration marks: x y radius [Meter]
# calibration marks at y = -0.3 m
-0.3 -0.3 0.025
-0.2 -0.3 0.025
-0.1 -0.3 0.025
0 -0.3 0.025
0.1 -0.3 0.025
0.2 -0.3 0.025
0.3 -0.3 0.025
# calibration marks at y = -0.2 m
-0.3 -0.2 0.025
-0.2 -0.2 0.025
-0.1 -0.2 0.025
0 -0.2 0.025
0.1 -0.2 0.025
0.2 -0.2 0.025
0.3 -0.2 0.025
# calibration marks at y = -0.1 m
-0.3 -0.1 0.025
-0.2 -0.1 0.025
-0.1 -0.1 0.025
0 -0.1 0.025
0.1 -0.1 0.025
0.2 -0.1 0.025
0.3 -0.1 0.025
HALCON 6.0

684 CHAPTER 12. TOOLS
# calibration marks at y = 0 m
-0.3 0 0.025
-0.2 0 0.025
-0.1 0 0.025
0 0 0.025
0.1 0 0.025
0.2 0 0.025
0.3 0 0.025
# calibration marks at y = 0.1 m
-0.3 0.1 0.025
-0.2 0.1 0.025
-0.1 0.1 0.025
0 0.1 0.025
0.1 0.1 0.025
0.2 0.1 0.025
0.3 0.1 0.025
# calibration marks at y = 0.2 m
-0.3 0.2 0.025
-0.2 0.2 0.025
-0.1 0.2 0.025
0 0.2 0.025
0.1 0.2 0.025
0.2 0.2 0.025
0.3 0.2 0.025
# calibration marks at y = 0.3 m
-0.3 0.3 0.025
-0.2 0.3 0.025
-0.1 0.3 0.025
0 0.3 0.025
0.1 0.3 0.025
0.2 0.3 0.025
0.3 0.3 0.025
The file CalTabFile contains the corresponding PostScript description of the calibration table.
Attention
Dependent on the accuracy of the used output device (e.g. laser printer) the printed calibration table may not
match the values in the calibration table descripton file CalTabDescrFile exactly. Thus, the coordinates of the
calibration marks in the calibration table descripton file have to be corrected!
Parameter
º Width (input control) .................................................................real double
Width of the calibration table in meters.
Default Value : 0.8
Value Suggestions : Width ¾1.2, 0.8, 0.6, 0.4, 0.2, 0.1
Recommended Value Step : 0.1
Restriction : 0.0 Width
º CalTabDescrFile (input control) .............................................string const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º CalTabFile (input control) ...................................................string const char *
File name of the PostSript file.
Default Value : ’caltab.ps’
Example
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 685
// create calibration table with width = 80 cm
::create_caltab(0.8,"caltab.descr","caltab.ps");
Result
create caltab returns H MSG TRUE if all parameter values are correct and both files have been written
successfully. If necessary, an exception handling is raised.
Parallelization Information
create caltab is processed completely exclusively without parallelization.
Possible Successor Functions
T read cam par, T caltab points
See Also
find caltab, T find marks and pose, T camera calibration, T disp caltab, T sim caltab
Camera calibration
Module
T create pose ( Htuple TransX, Htuple TransY, Htuple TransZ,
Htuple Rot1, Htuple Rot2, Htuple Rot3, Htuple OrderOfTransform,
Htuple OrderOfRotation, Htuple ViewOfTransform, Htuple *Pose )
Create 3D pose parameters.
T create pose creates 3D pose parameters Pose, which define a 3D transformation. The translation and rotation
of the 3D pose are described by parameters (TransX, TransY, TransZ)and(Rot1, Rot2, Rot3), respectively.
The parameter ViewOfTransform determines whether the transformation describes the transformation
of a point (’point’) or of a coordinate system (’coordinate system’). OrderOfTransform determines whether
during the transformation the rotation is applied first (’Rp+T’) or whether the translation is applied first (’R(p-T)’).
The meaning of the three rotation parameters is determined by OrderOfRotation. Thevalues’gba’ and ’abg’
specify that Rot1 is the rotation angle « (around the x-axis), Rot2 is the rotation angle ¬ (around the y-axis), and
Rot3 is the rotation angle ­ (around the z-axis). For ’gba’, the order is ­ , ¬ , « , while for ’abg’ it is « , ¬ , ­
.IfOrderOfRotation is passed as ’rodriguez’, the rotation parameters are interpreted as Rodriguez rotation
vector.
Pose is a tuple of length seven. The first three values hold the translation vector [TransX, TransY, TransZ],
the following three parameters hold the rotations Rot1, Rot2, andRot3, and the last value holds the so-called
representation type of the 3D pose parameters, and thus the transformation.
The possible combinations of ViewOfTransform, OrderOfTransform,andOrderOfRotation lead to
12 different representation types for the 3D transformations. In particular, they are:
No. OrderOfTransform OrderOfRotation ViewOfTransform Code
1 ’Rp+T’ ’gba’ ’point’ 0
2 ’Rp+T’ ’abg’ ’point’ 2
3 ’Rp+T’ ’rodriguez’ ’point’ 4
4 ’Rp+T’ ’gba’ ’coordinate system’ 1
5 ’Rp+T’ ’abg’ ’coordinate system’ 3
6 ’Rp+T’ ’rodriguez’ ’coordinate system’ 5
7 ’R(p-T)’ ’gba’ ’point’ 8
8 ’R(p-T)’ ’abg’ ’point’ 10
9 ’R(p-T)’ ’rodriguez’ ’point’ 12
10 ’R(p-T)’ ’gba’ ’coordinate system’ 9
11 ’R(p-T)’ ’abg’ ’coordinate system’ 11
12 ’R(p-T)’ ’rodriguez’ ’coordinate system’ 13
Note, that in general the symbols R and T in the parameter OrderOfTransform are not the same as within the
common notation of a homogeneous transformation matrix.
The type of a 3D transformation can be queried with T get pose type. The output of this operator, however,
is not the code of the number of the transformation type, but the sight and order of the transformation, and the
HALCON 6.0

686 CHAPTER 12. TOOLS
order of the rotations, corresponding to the parameters of T create pose. Different representation types can be
converted into one another with T convert pose type. The description of these conversions is given below.
The representation type no. 1 with code ’0’ corresponds to a transformation using homogeneous transformation
matrices, see T pose to hom mat3d, because when multiplying a 3D vector by a homogeneous transformation
matrix, the rotation and translation as also determined first, a point is transformed, and the rotation order is set to
­ - ¬ - « by T pose to hom mat3d (see also T affine trans point 3d). The three rotation angles « , ¬
,and­ are determined by the parameters Rot1, Rot2,andRot3. Wehave:
Ê Ü´«µ
Ê Ý´¬µ
Ê Þ´­µ
µ
È ¾ Ü Ý Þ℄ Ì Ê´½µ ¡ È ½ · Ì ´½µ
Ê Ü´«µ ¡Ê Ý´¬µ ¡Ê Þ´­µ ¡ È ½ · Ì ´½µ
where:
¼
½ ¼ ¼
¼ Ó× « ×Ò «
¼ ×Ò « Ó× «
¼
¼
Ó× ¬ ¼ ×Ò ¬
¼ ½ ¼
×Ò ¬ ¼ Ó× ¬
Ó× ­ ×Ò ­ ¼
×Ò ­ Ó× ­ ¼
¼ ¼ ½
Ê´½µ
½
½
½
¼ ½
Ö ½½ Ö ½¾ Ö ½¿
Ö ¾½ Ö ¾¾ Ö ¾¿
Ö ¿½ Ö ¿¾ Ö ¿¿
where:
rotation around the x-axis
rotation around the y-axis
rotation around the z-axis
Ö ½½ Ó×´¬µÓ×´­µ
Ö ½¾ Ó×´¬µ ×Ò´­µ
Ö ½¿ ×Ò´¬µ
Ö ¾½ ×Ò´«µ ×Ò´¬µ Ó×´­µ · Ó×´«µ ×Ò´­µ
Ö ¾¾ ×Ò´«µ ×Ò´¬µ ×Ò´­µ · Ó×´«µ Ó×´­µ
Ö ¾¿ ×Ò´«µ Ó×´¬µ
Ö ¿½ Ó×´«µ ×Ò´¬µ Ó×´­µ · ×Ò´«µ ×Ò´­µ
Ö ¿¾ Ó×´«µ ×Ò´¬µ ×Ò´­µ · ×Ò´«µ Ó×´­µ
Ö ¿¿ Ó×´«µ Ó×´¬µ
The representation type no. 1 is the reference type for all calibration operators in HALCON. Therefore, the
conversions from all other representation types into type 1 will be given below. The inverse conversions can be
obtained by inverting the calculations below. For the conversions, several basic conversion types can be identified.
These are the conversions from the representation types 2, 3, 4, and 7. All other conversions are derived from these
basic conversions. The individual conversions are given by:
Type 2: (’Rp+T’, ’abg’, ’point’) With respect to type 1, the order of rotations is reversed. First, a rotation around
the x-axis, then around the new y-axis, and finally around the z-axis created by the 2nd rotation is performed.
As for type 1, the parameters Rot1, Rot2, Rot3 determine the rotation angles «, ¬, and­. The translation
vector [TransX, TransY, TransZ] is identical for types 1 and 2. For the conversion we have:
È ¾ Ü Ý Þ℄ Ì Ê¡È ½ · Ì
Ê Þ´­´¾µ µ ¡Ê Ý´¬´¾µ µ ¡Ê Ü´«´¾µ µ ¡ È ½ · Ì ´¾µ
Ê Ü´«´½µ µ ¡Ê Ý´¬´½µ µ ¡Ê Þ´­´½µ µ ¡ È ½ · Ì ´½µ
µ
Ê´½µ Ê´¾µ Ê Ü´«´½µ µ ¡Ê Ý´¬´½µ µ ¡Ê Þ´­´½µ µ ¡ È ½ · Ì ´½µ
Ê Þ´­´¾µ µ ¡Ê Ý´¬´¾µ µ ¡Ê Ü´«´¾µ µ ¡ È ½ · Ì ´¾µ
where:
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 687
Ê´¾µ
¼
Ö´¾µ
½½
Ö´¾µ
¾½
Ö´¾µ
½¾
Ö´¾µ
¾¾
Ö´¾µ
½¿
Ö´¾µ
¾¿
Ö´¾µ
Ö´¾µ
Ö´¾µ
¿½ ¿¾ ¿¿
where:
½
Ö´¾µ
½½
Ó×´­´¾µ µ Ó×´¬´¾µ µ
Ö´¾µ
½¾
Ó×´­´¾µ µ ×Ò´¬´¾µ µ ×Ò´«´¾µ µ ×Ò´­´¾µ µ Ó×´«´¾µ µ
Ö´¾µ
½¿
Ó×´­´¾µ µ ×Ò´¬´¾µ µ Ó×´«´¾µ µ · ×Ò´­´¾µ µ ×Ò´«´¾µ µ
Ö´¾µ
¾½
×Ò´­´¾µ µ Ó×´¬´¾µ µ
Ö´¾µ
¾¾
×Ò´­´¾µ µ ×Ò´¬´¾µ µ ×Ò´«´¾µ µ · Ó×´­´¾µ µ Ó×´«´¾µ µ
Ö´¾µ
¾¿
×Ò´­´¾µ µ ×Ò´¬´¾µ µ Ó×´«´¾µ µ Ó×´­´¾µ µ ×Ò´«´¾µ µ
Ó×´¬´½µ µ
µ
Ö´¾µ
¿½
×Ò´¬´¾µ µ
Ö´¾µ
¿¾
Ó×´¬´¾µ µ ×Ò´«´¾µ µ
Ö´¾µ
¿¿
Ó×´¬´¾µ µ Ó×´«´¾µ µ
Õ
Ö´¾µ
½½
­´½µ ÖØÒ ¾
¬´½µ ÖØÒ ¾
«´½µ ÖØÒ ¾
¾ ¾
· Ö´¾µ
½¾
Ê´¾µ
Ó×´¬´½µ
¾¿
Ê´¾µ
¿¿
µ Ó×´¬´½µ µ
Ê´¾µ
½¿ Ó×´¬´½µ µ
Ê´¾µ
Ó×´¬´½µ
½¾
Ê´¾µ
½½
µ Ó×´¬´½µ µ
Ì ´½µ Ì ´¾µ
Here, ÖØÒ ¾´Ý ܵ denotes ÖØÒ´ Ü
Ý
µ while taking into account the signs of Ü and Ý, in order to determine
the correct quadrant. For the pathological case Ó×´¬´½µ µ¼, the problem is unsolvable because the representation
of a rotation by three parameters exhibits a singularity. In this case, the rotation matrix is perturbed
minimally, thus avoiding the singularity. (The angle ¬ is modified in steps of 0.00001 degrees.)
Type 3: (’Rp+T’, ’rodriguez’, ’point’) The Rodriguez vector is an alternative representation of a rotation in
space. The direction of the vector defines the axis of rotation. The length of the vector usually defines the
rotation angle with positive orientation. Here, a variation of the Rodriguez vector is used, where the length
of the vector defines the tangent of half the rotation angle.
Thus, the parameters Rot1, Rot2, andRot3 do not describe rotation angles, but correspond to the three
values of the vector [Ö Ü Ö Ý Ö Þ ]. The translation vector [TransX, TransY, TransZ] is identical for types 1
and 3. The conversion of the rotation part of the transformation from type 3 to type 1 is given by converting
the Rodriguez vector to the rotation matrix Ê´½µ :
HALCON 6.0

688 CHAPTER 12. TOOLS
¾
½·Ö ¾ Ü·Ö¾ Ý·Ö¾ Þ
Ö ½½ ½ ´ÖÝ ¾ · Ö¾ Þ µ
Ö ½¾ ´Ö Ü Ö Ý Ö Þ µ
Ö ½¿ ´Ö Ü Ö Þ · Ö Ý µ
Ö ¾½ ´Ö Ý Ö Ü · Ö Þ µ
Ö ¾¾
Ö ¾¿
½ ´ÖÞ ¾ · Ö¾ Ü µ
´Ö Ý Ö Þ Ö Ü µ
Ö ¿½ ´Ö Þ Ö Ü Ö Ý µ
Ö ¿¾ ´Ö Þ Ö Ý · Ö Ü µ
Ö ¿¿ ½ ´ÖÜ ¾ · Ö¾ Ý µ
Type 4: (’Rp+T’, ’gba’, ’coordinate system’) In contrast to type 1, type 4 describes the transformation of a
coordinate system instead of the transformation of a point. As for type 1, the parameters Rot1, Rot2, Rot3
define the rotation angles «, ¬, and­. The translation vector [TransX, TransY, TransZ] is identical for
types 1 and 4. The only difference is that the rotation angles are negated. For the conversion we have:
È ¾ Ü Ý Þ℄ Ì Ê¡È ½ · Ì
Ê Ü´«´µ µ ¡Ê Ý´¬´µ µ ¡Ê Þ´­´µ µ ¡ È ½ · Ì ´µ
Ê Ü´«´½µ µ ¡Ê Ý´¬´½µ µ ¡Ê Þ´­´½µ µ ¡ È ½ · Ì ´½µ
where:
Ì ´½µ Ì ´µ
«´½µ «´µ
¬´½µ ¬´µ
­´½µ ­´µ
Type 5: (’Rp+T’, ’abg’, ’coordinate system’) For the conversion of type 5 into type 1, a conversion into type 2
can be done first, followed by a conversion from type 2 to type 1; see the explanations there. Types 5 and
2 differ in the sight of the transformation (ViewOfTransform). Thus, as was the case for the conversion
from type 4 to type 1, the signs of the rotation angles have to be changed. Again, the parameters Rot1,
Rot2, Rot3 denote the rotation angles «, ¬, and­. The translation vector [TransX, TransY, TransZ]
is identical for types 1 and 5. For the conversion to type 2 we have:
È ¾ Ü Ý Þ℄ Ì Ê¡È ½ · Ì
Ê Þ´­´µ µ ¡Ê Ý´¬´µ µ ¡Ê Ü´«´µ µ ¡ È ½ · Ì ´µ
Ê Þ´­´¾µ µ ¡Ê Ý´¬´¾µ µ ¡Ê Ü´«´¾µ µ ¡ È ½ · Ì ´¾µ
where:
Ì ´¾µ Ì ´µ
«´¾µ «´µ
¬´¾µ ¬´µ
­´¾µ ­´µ
Type 6: (’Rp+T’, ’rodriguez’, ’coordinate system’) As for type 3, the rotation for type 6 is given by a Rodrigues
vector. The parameters Rot1, Rot2,andRot3 do not describe angles, but correspond to the three values of
the vector [Ö Ü , Ö Ý , Ö Þ ]. The translation vector (TransX, TransY, TransZ) is identical to type 1. As above,
the conversion of the rotation part to type 1 is done in two steps: First, the vector [Ö Ü , Ö Ý , Ö Ü ]isconvertedto
a rotation matrix, resulting in a representation of type 4. See the explanations on the conversion from type 3
to type 1.
The second step is the conversion from type 4 to type 1, where additionally the rotation angles have to be
negated. See the explanations on the conversion from type 4 to type 1.
Type 7: (’R(p-T)’, ’gba’, ’point’) In contrast to type 1, type 7 describes a transformation in which the translation
is applied first, followed by the rotation. As for type 1, the parameters Rot1, Rot2, andRot3 define the
rotation angles «, ¬, and­. For the transformation we have:
È ¾ Ü Ý Þ℄ Ì Ê´½µ ¡ È ½ · Ì ´½µ
Ê´µ ¡ È Ì´µ¡
½
µ
Ê´µ ¡ È ½
Ê´µ
¡Ì´µ
Ê´½µ Ê´µ
Ì ´½µ Ê´µ
¡Ì´µ
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 689
Type 8: (’R(p-T)’, ’abg’, ’point’) The conversion from type 8 to type 1 is again carried out in two steps: First,
a conversion to type 7 is done. See the explanations on the conversion from type 2 to type 1. In the second
step, a conversion from type 7 to type 1 is done. See the explanations there. The parameters Rot1, Rot2,
and Rot3 again denote the rotation angles «, ¬,and­.
Type 9: (’R(p-T)’, ’rodriguez’, ’point’) The conversion from type 9 to type 1 is again carried out in two steps:
First, a conversion to type 7 is done. See the explanations on the conversion from type 3 to type 1. In the
second step, a conversion from type 7 to type 1 is done. See the explanations there. The parameters Rot1,
Rot2,andRot3 do not describe rotation angles, but correspond to the three values of the Rodriguez vector
[Ö Ü , Ö Ý , Ö Þ ].
Type 10: (’R(p-T)’, ’gba’, ’coordinate system’) The conversion from type 10 to type 1 is again carried out in
two steps: First, a conversion to type 7 is done. See the explanations on the conversion from type 4 to type
1. In the second step, a conversion from type 7 to type 1 is done. See the explanations there. The parameters
Rot1, Rot2,andRot3 again denote the rotation angles «, ¬, and­.
Type 11: (’R(p-T)’, ’abg’, ’coordinate system’) The conversion from type 11 to type 1 is carried out in three
steps: First, a conversion to type 8 is done. See the explanations on the conversion from type 5 to type 1. In
the second step, a conversion from type 8 to type 7 is done. See the explanations on the conversion from type
2 to type 1. In the third step, the conversion from type 7 to type 1 is done. See the explanations there. The
parameters Rot1, Rot2,andRot3 again denote the rotation angles «, ¬, and­.
Type 12: (’R(p-T)’, ’rodriguez’, ’coordinate system’) The conversion from type 11 to type 1 is also carried out
in three steps: First, a conversion to type 10 is done. See the explanations on the conversion from type 6
to type 1. In the second step, a conversion from type 10 to Type 7 is done. See the explanations on the
conversion from type 4 to type 1. In the third step, the conversion from type 7 to type 1 is done. See the
explanations there. The parameters Rot1, Rot2,andRot3 do not describe rotation angles, but correspond
to the three values of the Rodriguez vector [Ö Ü , Ö Ý , Ö Þ ].
Useful hint: For the description of the pose of a new coordinate system within a base coordinate system, it is
usually easiest to start by visualizing both coordinate systems to be identical, i.e., to lie exactly on top of one
another. After this, the new coordinate system is translated until its origin rests in the correct position. The vector
describing this translation is given by [TransX, TransY, TransZ]. After this, the rotations are applied until the
desired orientation of the new coordinate system is achieved within the base coordinate system. If the rotation
order is chosen as ­ - ¬ - « , first a rotation around the z-axis in positive orientation is done. Then, a rotation
around the new y-axis, and finally a rotation around the x-axis resulting from the second rotation is done. The
rotation angle around the x-axis corresponds to « , and must be passed in Rot1, the rotation angle around the
y-axis corresponds to ¬ , and must be passed in Rot2, while the rotation angle around the z-axis corresponds to ­
and has to be passed in Rot3. This description of a 3D transformation corresponds to type 10 with code ’9’. Thus,
ViewOfTransform = ’coordinate system’, OrderOfTransform = ’R(p-T)’, andOrderOfRotation =
’gba’ have to be passed to the operator.
In the programming example below, it is shown how the initial camera pose for a subsequent call to
T camera calibration can be determined, if the position of the camera is coarsly measured in the world
coordinate system. This is of special interest if the standard planar calibration target (see create caltab)
is not used, and thus the operator T find marks and pose cannot be applied. Instead, natural or artificial
landmarks with known world coordinates can, of course, be used for calibration.
Let, for example, the relative camera position with respect to the origin of the world coordinate system be given by
x = 1.08 m, y = 0.25 m, z = 0.62 m, i.e., the origin of the camera coordinate system has the world coordinates [1.08,
0.25, 0.62]. Let the camera coordinate system be oriented such that the line of sight of the camera corresponds to
the positive z-axis. The orientation of the camera coordinate system with respect to the world coordinate system
can be described by three rotation angles. In the example, the camera coordinate system is first rotated around
the z-axis of the world coordinate system by 100 degrees, followed by a rotation around the new x-axis by -120
degrees. See also the example for T hom mat3d to pose.
Parameter
º TransX (input control) .......................................................real Htuple . double
Translation along the x-axis.
Default Value : 0.1
Value Suggestions : TransX ¾-1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0, 0.01, 0.125,
0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0
Typical Range of Values : 0.05 TransX
Recommended Value Step : 0.05
HALCON 6.0

690 CHAPTER 12. TOOLS
º TransY (input control) .......................................................real Htuple . double
Translation along the y-axis.
Default Value : 0.1
Value Suggestions : TransY ¾-1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0, 0.01, 0.125,
0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0
Typical Range of Values : 0.05 TransY
Recommended Value Step : 0.05
º TransZ (input control) .......................................................real Htuple . double
Translation along the z-axis.
Default Value : 0.1
Value Suggestions : TransZ ¾-1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0, 0.01, 0.125,
0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0
Typical Range of Values : 0.05 TransZ
Recommended Value Step : 0.05
º Rot1 (input control) ..........................................................real Htuple . double
First rotation value.
Default Value : 90
Value Suggestions : Rot1 ¾90, 180, 270
Typical Range of Values : 0 Rot1 360
Minimal Value Step : 0.001
Recommended Value Step : 0.2
º Rot2 (input control) ..........................................................real Htuple . double
Second rotation value.
Default Value : 90
Value Suggestions : Rot2 ¾90, 180, 270
Typical Range of Values : 0 Rot2 360
Minimal Value Step : 0.001
Recommended Value Step : 0.2
º Rot3 (input control) ..........................................................real Htuple . double
Third rotation value.
Default Value : 90
Value Suggestions : Rot3 ¾90, 180, 270
Typical Range of Values : 0 Rot3 360
Minimal Value Step : 0.001
Recommended Value Step : 0.2
º OrderOfTransform (input control) ...................................string Htuple . const char *
Order of rotation and translation.
Default Value : ”Rp+T”
Value Suggestions : OrderOfTransform ¾”Rp+T”, ”R(p-T)”
º OrderOfRotation (input control) .....................................string Htuple . const char *
Meaning of the rotation values.
Default Value : ”gba”
Value Suggestions : OrderOfRotation ¾”gba”, ”abg”, ”rodriguez”
º ViewOfTransform (input control) .....................................string Htuple . const char *
View of transformation.
Default Value : ”point”
Value Suggestions : ViewOfTransform ¾”point”, ”coordinate system”
º Pose (output control) ..........................................pose-array Htuple . double * / long *
3D-Transformation.
Parameter Number : 7
Example
HTuple CamParam, StartPose, FinalPose, Errors, Dummy;
// get the following parameter (landmark positions in world and image
// coordinates) by suitable operations
HTuple WorldPointsX, WorldPointsY, WorldPointsZ, PixelsRow, PixelsColumn;
// get internal camera parameters: */
::read_cam_par ("campar.dat", &CamParam) ;
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 691
// get rough camera start pose from relative camera pose:
::create_pose(1.08, 0.25, 0.62, -120, 0, 100, "R(p-T)", "gba",
"coordinate_system", &StartPose);
// calibration of external camera params:
::camera_calibration (WorldPointsX, WorldPointsY, WorldPointsZ,
PixelsRow, PixelsColumn, CamParam, StartPose, 6,
&Dummy, &FinalPose, &Errors) ;
Result
T create pose returns H MSG TRUE if all parameter values are correct. If necessary, an exception handling
is raised.
Parallelization Information
T create pose is reentrant and processed without parallelization.
Possible Successor Functions
T pose to hom mat3d, T write pose, T camera calibration, T hand eye calibration
T read pose, T hom mat3d to pose
Alternatives
See Also
T convert pose type, T get pose type, T hom mat3d to pose, T pose to hom mat3d,
T write pose, T read pose
Camera calibration
Module
T disp caltab ( Htuple WindowHandle, Htuple CalTabDescrFile,
Htuple CamParam, Htuple CamPose, Htuple ScaleFac )
Project and visualize the 3D model of the calibration table in the image.
T disp caltab is used to visualize the calibration marks and the connecting lines between the marks of the
used calibration table (CalTabDescrFile) in the actual output window. Thus, the 3D model of the calibration
table is projected into the image plane using the internal camera parameters (CamParam) and the camera pose
(external camera parameters (CamPose). The underlying camera model (pinhole camera with radial distortion) is
described in T write cam par.
Typically T disp caltab is used to verificate the result of the camera calibration (see
T camera calibration) by superimposing it onto the original image. The actual linewidth can be set
by set line width, the actual color can be set by set color.
The parameter ScaleFac influences the number of supporting points to approximate the elliptic contours of the
calibration marks. You should increase the number of supporting points, if the image part in the actual output
window is displayed with magnification (see set part).
Parameter
º WindowHandle (input control) .............................................window Htuple . long
Window id.
º CalTabDescrFile (input control) .....................................string Htuple . const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º CamPose (input control) .........................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
HALCON 6.0

692 CHAPTER 12. TOOLS
º ScaleFac (input control) .....................................................real Htuple . double
Scaling factor for the visualization.
Default Value : 1.0
Value Suggestions : ScaleFac ¾0.5, 1.0, 2.0, 3.0
Recommended Value Step : 0.05
Restriction : 0.0 ScaleFac
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple StartPose,CamParam,FinalPose,Errors;
// read calibration image
HImage Image1("calib-01.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start pose
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
StartCamPar[4] = 384;
// Cx
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
::camera_calibration(NX,NY,NZ,RCoord1,CCoord1,StartCamPar,StartPose,
11,&CamParam,&FinalPose,&Errors);
// visualize calibration result
::disp_image(Image1,WindowHandle);
::set_color(WindowHandle,"red");
::disp_caltab("caltab.descr",CamParam,FinalPose,1.0);
Result
T disp caltab returns H MSG TRUE if all parameter values are correct. If necessary, an exception handling
is raised.
Parallelization Information
T disp caltab is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
T camera calibration, T read cam par, T read pose
See Also
T find marks and pose, T camera calibration, T sim caltab, T write cam par,
T read cam par, T create pose, T write pose, T read pose, T project 3d point,
T get line of sight
Module
Camera calibration
find caltab ( Hobject Image, Hobject *Caltab,
const char *CalTabDescrFile, long SizeGauss, long MarkThresh,
long MinDiamMarks )
Segment the calibration table region in the image.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 693
find caltab is used to determine the region of a plane calibration table with circular marks in the input image
Image. First the input image is smoothed (see gauss image); the size of the used filter mask is given by
SizeGauss. Afterwards a thresholding operator (see threshold) with minimum gray value MarkThresh
and maximum gray value 255 is applied. Among the extracted connected regions the most convex region with
almost correct number of holes (corresponding to the dark marks of the calibration table) is selected. Holes with
a diameter smaller than the expected size of the marks MinDiamMarks are eliminated to reduce the impact of
noise. The number of marks is read from the calibration table description file CalTabDescrFile. The complete
explanation of this file can be found within the description of create caltab.
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º Caltab (output object) ..........................................................region Hobject *
Output region.
º CalTabDescrFile (input control) .............................................string const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º SizeGauss (input control) ...........................................................integer long
Filter size of the Gaussian.
Default Value : 3
Value List : SizeGauss ¾0, 3, 5, 7, 9, 11, 13
º MarkThresh (input control) .........................................................integer long
Threshold value for mark extraction.
Default Value : 112
Value List : MarkThresh ¾48, 64, 80, 96, 112, 128, 144, 160
º MinDiamMarks (input control) ......................................................integer long
Expected minimal diameter of the marks on the calibration table.
Default Value : 5
Value List : MinDiamMarks ¾3, 5, 9, 15, 30, 50, 70
Example
// read calibration image
HImage Image("calib-01.tiff") ;
// find calibration pattern
HRegion Caltab = Image.FindCaltab("caltab.descr",3,112,5);
Result
find caltab returns H MSG TRUE if all parameter values are correct and an image region is
found. The behavior in case of empty input (no image given) can be set via set system
(’no object result’,) and the behavior in case of an empty result region via set system
(’store empty region’,). If necessary, an exception handling is raised.
Parallelization Information
find caltab is reentrant and processed without parallelization.
read image
T find marks and pose
Possible Predecessor Functions
Possible Successor Functions
See Also
T find marks and pose, T camera calibration, T disp caltab, T sim caltab,
T caltab points, create caltab
Camera calibration
Module
HALCON 6.0

694 CHAPTER 12. TOOLS
T find marks and pose ( Hobject Image, Hobject CalTabRegion,
Htuple CalTabDescrFile, Htuple StartCamParam, Htuple StartThresh,
Htuple DeltaThresh, Htuple MinThresh, Htuple Alpha, Htuple MinContLength,
Htuple MaxDiamMarks, Htuple *RCoord, Htuple *CCoord, Htuple *StartPose )
Extract the 2D calibration marks from the video image and calculate initial values for the external camera parameters.
T find marks and pose is used to determine the necessary input data for the subsequent camera calibration
(see T camera calibration): On the one hand the 2D center points [RCoord,CCoord] of the calibration
marks within the region CalTabRegion of the input image Image are extracted and ordered. On the other hand
a rough estimate for the external camera parameters (StartPose) is computed, i.e., the 3D pose of the camera
in the calibration table coordinate system.
In the input image Image an edge detector is applied (see edges image, mode ’lanser2’) to the region
CalTabRegion, which may have been found by applying the operator find caltab. The filter parameter for
this edge detection can be tuned via Alpha. In the edge image closed contours are searched for: The number of
closed contours must correspond to the number of calibration marks as described in the calibration table description
file CalTabDescrFile and the contours have to be ellipticly shaped. Contours shorter than MinContLength
are discarded, just as contours enclosing regions with a diameter larger than MaxDiamMarks (e.g., the border of
the calibration table).
For the detection of contours a threshold operator is applied to amplitude of the edge detector. All points with a
high amplitude (i.e. borders of marks) are selected.
First, the threshold value is set to StartThresh. If the search for the closed contours or the successive pose
estimate fails, this threshold value is successively decreased by DeltaThresh down to a minimum value of
MinThresh.
Each of the found contours is refined with subpixel accuracy (see edges sub pix) and subsequently approximated
by an ellipse. The center points of these ellipses represent a good approximation of the desired 2D image
coordinates [RCoord,CCoord] of the calibration mark center points. The order of the values within these two
tuples is in row-major order beginning at the upper left in the image. This order must correspond to the order of
the 3D coordinates of the calibration marks in the calibration table description file CalTabDescrFile, since
this fixes the correspondences between extracted image marks and known model marks!
Based on the ellipse parameters for each calibration mark a rough estimate for the external camera parameters is
computed finally. For that purpose the fixed correspondences between extracted image marks and known model
marks are used. The estimate StartPose describes the pose of the camera in the calibration table coordinate
system (see T create pose) as desired by the operator T camera calibration.
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º CalTabRegion (input object) .....................................................region Hobject
Region of the calibration table.
º CalTabDescrFile (input control) .....................................string Htuple . const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º StartCamParam (input control) ...............................number-array Htuple . double / long
Initial values for the internal camera parameters.
º StartThresh (input control) ...............................................number Htuple . long
Initial threshold value for contour detection.
Default Value : 128
Value List : StartThresh ¾80, 96, 112, 128, 144, 160
º DeltaThresh (input control) ...............................................number Htuple . long
Loop value for successive reduction of StartThresh.
Default Value : 10
Value List : DeltaThresh ¾6, 8, 10, 12, 14, 16, 18, 20, 22
º MinThresh (input control) ..................................................number Htuple . long
Minimum threshold for contour detection.
Default Value : 18
Value List : MinThresh ¾8, 10, 12, 14, 16, 18, 20, 22
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 695
º Alpha (input control) .........................................................real Htuple . double
Filter parameter for contour detection, see edges image.
Default Value : 0.9
Value Suggestions : Alpha ¾0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1
Typical Range of Values : 0.2 Alpha 50.0
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Alpha 0.0
º MinContLength (input control) ..............................................real Htuple . double
Minimum length of the contours of the marks.
Default Value : 15.0
Value Suggestions : MinContLength ¾10.0, 15.0, 20.0, 30.0, 40.0, 100.0
Restriction : MinContLength 0.0
º MaxDiamMarks (input control) ...............................................real Htuple . double
Maximum expected diameter of the marks.
Default Value : 100.0
Value Suggestions : MaxDiamMarks ¾50.0, 100.0, 150.0, 200.0, 300.0
Restriction : MaxDiamMarks 0.0
º RCoord (output control) ...............................................real-array Htuple . double *
Tuple with row-coordinates of the detected marks.
º CCoord (output control) ...............................................real-array Htuple . double *
Tuple with column-coordinates of the detected marks.
º StartPose (output control) ...................................pose-array Htuple . double * / long *
Estimation for the external camera parameters.
Parameter Number : 7
Example
HTuple StartCamPar,RCoord,CCoord,StartPose;
// read calibration image
HImage Image("calib-01.tiff");
// find calibration pattern
HRegion Caltab = Image.FindCaltab("caltab.descr",3,112,5);
// read internal camera parameters from file
::read_cam_par("campar.dat",&StartCamPar);
// find calibration marks and start pose
RCoord = Image.FindMarksAndPose(Caltab,"caltab.descr",StartCamPar,
128,10,18,0.9,15.0,100.0,
&CCoord,&StartPose);
Result
T find marks and pose returns H MSG TRUE if all parameter values are correct and an estimation for the
external camera parameters has been determined successfully. If necessary, an exception handling is raised.
Parallelization Information
T find marks and pose is reentrant and processed without parallelization.
find caltab
T camera calibration
Possible Predecessor Functions
Possible Successor Functions
See Also
find caltab, T camera calibration, T disp caltab, T sim caltab, T read cam par,
T read pose, T create pose, T pose to hom mat3d, T caltab points, create caltab,
edges sub pix, edges image
Camera calibration
Module
HALCON 6.0

696 CHAPTER 12. TOOLS
T get line of sight ( Htuple Row, Htuple Column, Htuple CamParam,
Htuple *PX, Htuple *PY, Htuple *PZ, Htuple *QX, Htuple *QY, Htuple *QZ )
Compute the line of sight corresponding to a point in the image.
T get line of sight computes the line of sight corresponding to a pixel (Row, Column) in the image plane.
The line of sight is a (straight) line in the camera coordinate system, which is described by two points (PX,PY,PZ)
and (QX,QY,QZ) on the line. A pinhole or telecentric camera model with radial distortions described by the internal
camera parameters CamParam is used (see T camera calibration). If a pinhole camera is used, the second
point lies on the focal plane, i.e., the output parameter QZ is equivalent to the focal length of the camera. The
equation of the line of sight is given by
¼
Ü Ý
Þ
½ ¼
Ô Ü
Ô Ý
Ô Þ
½ ¼
· Ø
Õ Ü
Õ Ý
Õ Þ
The advantage of representing the line of sight as two points is that with this, it is easier to transform the line in
3D. To do so, all that is necessary is to apply the operator T affine trans point 3d to the two points.
Parameter
º Row (input control) ......................................................real-array Htuple . double
Row coordinate of the pixel.
º Column (input control) ..................................................real-array Htuple . double
Column coordinate of the pixel.
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º PX (output control) .....................................................real-array Htuple . double *
X coordinate of the first point on the line of sight
º PY (output control) .....................................................real-array Htuple . double *
Y coordinate of the first point on the line of sight
º PZ (output control) .....................................................real-array Htuple . double *
Z coordinate of the first point on the line of sight
º QX (output control) .....................................................real-array Htuple . double *
X coordinate of the second point on the line of sight
º QY (output control) .....................................................real-array Htuple . double *
Y coordinate of the second point on the line of sight
º QZ (output control) .....................................................real-array Htuple . double *
Z coordinate of the second point on the line of sight
Example
Ô Ü
Ô Ý
Ô Þ
½
HTuple CamParam,Row,Column,PX,PY,PZ,QX,QY,QZ;
// get internal camera parameters
::read_cam_par("campar.dat",&CamParam);
// inverse projection
Row[1] = 100;
Row[0] = 50;
Column[1] = 200;
Column[0] = 100;
::get_line_of_sight(Row,Column,CamParam,&PX,&PY,&PZ,&QX,&QY,&QZ);
Result
T get line of sight returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised.
Parallelization Information
T get line of sight is reentrant and processed without parallelization.
Possible Predecessor Functions
T read cam par, T camera calibration
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 697
T affine trans point 3d
Possible Successor Functions
See Also
T camera calibration, T disp caltab, T read cam par, T project 3d point,
T affine trans point 3d
Module
Camera calibration
T get pose type ( Htuple Pose, Htuple *OrderOfTransform,
Htuple *OrderOfRotation, Htuple *ViewOfTransform )
Get the representation type of 3D pose parameters.
With T get pose type, the representation type of the 3D pose Pose can be queried.
A 3D pose defines a 3D transformation consisting of a translation and a rotation. Halcon supports different representation
types for such a transformation. This can be, for example, external camera parameters, given by a 3D
translation vector (in meters), three rotation angles, and the code of the representation type of the 3D transformation.
For example, the value ’0’ is the code of representation type 1, and signifies that the transformation of a point
is described, that the 3D rotation is applied before the translation, that the rotations are given as angles (in degrees),
and that the order of the rotations is ­-¬-«, i.e., the first rotation is around the z-axis, the second rotation around
the new y-axis, and the third rotation around the x-axis created by the previous two rotations. The meaning of the
other representation types is described with the operator T create pose.
The returned parameter ViewOfTransform determines, whether the transformation Pose describes the
transformation of a point (’point’) or the transformation of a coordinate system (’coordinate system’).
OrderOfTransform determines whether the rotation (’Rp+T’) or the translation (’R(p-T)’) is applied first.
The meaning of the three rotation values is determined by OrderOfRotation. The values ’gba’ and ’abg’
signify that the rotation values describe the three rotation angles « (around the x-axis), ¬ (around the y-axis), and
­ (around the z-axis) in the 3D transformation. For ’gba’, the rotation order is ­ , ¬ , « ,andfor’abg’ it is « , ¬ ,
­ .IfOrderOfRotation is ’rodriguez’, the rotation values are interpreted as Rodriguez rotation vector.
Parameter
º Pose (input control) ..............................................pose-array Htuple . double / long
3D transformation.
Parameter Number : 7
º OrderOfTransform (output control) .......................................string Htuple . char *
Order of rotation and translation.
º OrderOfRotation (output control) .........................................string Htuple . char *
Meaning of the rotation values.
º ViewOfTransform (output control) .........................................string Htuple . char *
View of transformation.
Example
HTuple Pose, OrderT, OrderR, SightT;
// get pose (external camera parameters):
::read_pose("campose.dat", &CamPose) ;
/* get semantic type of pose */
::get_pose_type(CamPose, &OrderT, &OrderR, &SightT);
Result
T create pose returns H MSG TRUE if all parameter values are correct. If necessary, an exception handling
is raised.
Parallelization Information
T get pose type is reentrant and processed without parallelization.
Possible Predecessor Functions
T create pose, T hom mat3d to pose, T camera calibration, T hand eye calibration
HALCON 6.0

698 CHAPTER 12. TOOLS
T convert pose type
Possible Successor Functions
See Also
T create pose, T convert pose type, T write pose, T read pose
Camera calibration
Module
T hand eye calibration ( Htuple NX, Htuple NY, Htuple NZ, Htuple NRow,
Htuple NCol, Htuple MPointsOfImage, Htuple MRelPoses,
Htuple BaseStartPose, Htuple CamStartPose, Htuple CamParam,
Htuple ToEstimate, Htuple StopCriterion, Htuple MaxIterations,
Htuple MinError, Htuple *BaseFinalPose, Htuple *CamFinalPose,
Htuple *NumErrors )
Perform a hand-eye-calibration.
The operator T hand eye calibration can be used to determine the 3D pose of the origin of the camera
coordinate system with respect to the origin of the manipulator coordinate system (tool center point). This is typically
used for robots equipped with a camera, where the pose of the camera (the “eye”) relative to the manipulator
(the “hand”) has to be determined, in order to enable a video-based gripping of objects.
The assumption for the following desciption is, that the camera is fixed to the end-effector of the manipulator
(hand-in-eye-configuration). In this case the calibration determines the (constant) pose of the camera in respect to
the tool coordination system of the end-effector. In the other case (the camera is stationary and looks to the moving
manipulator) the (constant) pose of the base coordination system of the manipulator in respect to the camera is
computed. This can be performed by using T hand eye calibration, too.
T hand eye calibration works in a similar manner to the conventional calibration of the exterior camera
parameters (camera pose); see T camera calibration. However, T hand eye calibration not only
determines the camera pose as a simple transformation, but as a chain of transformations from the world coordinate
system to the base coordinate system of the active system (robot or vehicle) to the manipulator coordinate system,
and finally to the camera coordinate system. Thus, the transformation of a point È Ï in world coordinates to the
camera coordinate system can be described by:
È Ü Ý Þ℄ Ì Ê¡È Ï · Ì
Ê ´Ê Ñ ´Ê Ú ¡ È Ï · Ì Ú µ·Ì Ñ µ·Ì
where
Ê Ú , Ì Ú :
Ê Ñ , Ì Ñ :
Ê , Ì :
Rotation and translation from the world coordinate system
to the base coordinate system of the active system (vehicle)
Rotation and translation from the base coordinate system
to the manipulator coordinate system
Rotation and translation from the manipulator coordinate system
to the camera coordinate system
The goal of the hand-eye-calibration is to determine (Ê , Ì ). In order to avoid having to construct an exactly
measured set-up, a least-squares error adjustment is used, which estimates (Ê Ú , Ì Ú ) as well. Therefore, measurements
referring to different positions of the manipulator are used. Hence, it must be possible to determine the
different positions of the manipulator with sufficient accuracy. For a robot arm, they can be determined from the
angle positions of the individual joints of the arm. Analogously to the determination of the interior camera parameters
(see T camera calibration), a large number of different manipulator positions is used to achieve more
robust results.
A Newton-type algorithm is used to minimize an error function based on normal equations. Therefore, suitable
starting values have to be passed for (Ê , Ì ), and (Ê Ú , Ì Ú ) by the user.
Starting values for (Ê , Ì ) can be obtained by a coarse measurement of the set-up. Starting values for (Ê Ú , Ì Ú )
can be obtained from the starting values for (Ê , Ì ), the exterior camera parameters (Ê , Ì ) (pose of the camera
in the entire transformation chain; see T camera calibration), and the corresponding pose (Ê Ñ , Ì Ñ )ofthe
manipulator. We have:
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 699
È Ê ¡ È Ï · Ì
Ê ´Ê Ñ ´Ê Ú ¡ È Ï · Ì Ú µ·Ì Ñ µ·Ì
where
Ê , Ì :
Rotation and translation from the world coordinate system
to the camera coordinate system (camera pose).
The following sections discuss individual questions arising from the use of T hand eye calibration and
are intended to be a guide line for using the operator in an application, as well as to aid the understanding of the
operator.
HowdoIget3Dmodelpoints? 3D model points, given in the world coordinate system (NX, NY, NZ), and their
associated projections to the camera coordinate system (NRow, NCol) form the basis of the hand-eyecalibration.
In order ro be able to perform a successful hand-eye-calibration, 3D model points must be
used, which were obtained from sufficiently many different positions of the manipulator.
Arbitrary known points in the world coordinate system along with their associated projections to the camera
coordinate system can be used for the calibration. However, it is usually most convenient to use a standard
calibration table, e.g., the one that can be generated with create caltab. By using this calibration table,
the calibration table and position of the calibration marks can be extracted by using find caltab and
T find marks and pose, respectively.
Please refer to T camera calibration for a description of the extraction of the calibration table and its
associated 3D model points.
The parameter MPointsOfImage detemines the number of 3D model points used for each pose of the
manipulator, i.e., for each image. With this, the 3D model points, which are stored in a linearized fashion
in NX, NY, NZ, and their corresponding projections (NRow, NCol) can be associated with the corresponding
position of the manipulator (MRelPoses).
The 3D model points can be read from a calibration table description file for the standard calibration table
with the operator T caltab points.
How do I acquire a suitable set of images? If a planar standard calibration table is used, the following procedure
should be used: Images of the calibration table are taken with the active system to be calibrated, i.e., the
combination of the base of the manipulator (the vehicle, in case of mobile systems, which is used as a
fixed point for the manipulator), the manipulator (robot arm, pan-tilt-head, etc.), and the camera system; see
open framegrabber and grab image. For the image acquisition, the following points should be taken
into account:
¯ At least 10 to 20 images from different positions should be taken in which the position of the camera
with respect to the calibration table is sufficiently different. The position of the calibration table must
not be changed between images.
¯ In each image, the calibration table must be completely visible (including its border).
¯ No reflections or other disturbances should be visible on the calibration table.
¯ The set of images must show the calibration table from very different positions of the manipulator.
The calibration table can and should be visible in different parts of the images. Furthermore, it should
be slightly to moderately rotated around its x- or y-axis, in order to clearly exhibit distortions of the
calibration marks. In other words, the corresponding exterior camera parameters (pose of the camera
with respect to the calibration table) should take on many different values. Consider that the manipulator
only has six degrees of freedom (three for rotation and three for translation), while twelve degrees of
freedom have to be estimated for BaseFinalPose and CamFinalPose. This means that the space
of the degrees of freedom for the manipulator has to be used as exhaustively as possible.
¯ In each image, the calibration table should fill at least one quarter of the entire image, in order to ensure
the robust detection of the calibration marks.
¯ The interior camera parameters of the camera to be used must have been determined earlier and must be
passed in CamParam; seeT camera calibration. Note that changes of the image size, the focal
length, the aperture, or the focus effect a change of the interior camera parameters.
¯ The camera must not be modified between the acquisition of the individual images, i.e., neither focal
length, nor aperture, nor focus must be changed, because all calibration images use the same interior
camera parameters. Please make sure that the focus is sufficient for the expected changes of the distance
the camera from the calibration table. Therefore, bright lighting conditions for the calibration table are
important because smaller apertures result in larger depth of focus.
HALCON 6.0

700 CHAPTER 12. TOOLS
How do I obtain suitable starting values? The starting values for (Ê , Ì )and(Ê Ú , Ì Ú ) are passed as 3D poses
in the parameters CamStartPose and BaseStartPose, just like the exterior camera parameters.
CamStartPose can be obtained by measuring the pose of the camera in the manipulator coordinate system.
This is the same procedure as the determination of starting values for the calibration of the exterior camera
parameters without using the standard calibration table. Use T create pose to create a pose from your
measurements. For the measurement, it is usually easier to determine the translation of the origin of the
camera coordinate system within the manipulator coordinate system first, followed by the determination of
the orientation.
The camera coordinate system is oriented such that the line of sight of the camera corresponds to the positive
z-axis. The orientation of the camera coordinate system with respect to the world coordinate system can
be described by three rotation angles. In order to determine the orientation, one can, for example, first
“rotate” around the z-axis of the manipulator coordinate system, then around the new y-axis, and finally
around the new x-axis created by the previous two rotations. In this case, the rotation angles around the x-,
y-, and z-axis correspond directly to the rotation parameters of T create pose. Hence, according to this
description of the pose, the following settings must be passed to T create pose: ’coordinate system’
for the sight of the transformation (a transformation of a coordinate system is described), ’R(p-T)’ for the
order of the transformations (first a translation, then a rotation), and ’gba’ for the order of rotations (­, ¬,
«). This corresponds to representation type 10. For further information, please refer to the description of
T create pose.
In order to determine BaseStartPose, a calibration of the exterior camera parameters
(T camera calibration) should be performed for one of the acquired images. From the pose of
the camera coordinate system in the world coordinate system thus determined, and from the other poses
in the transformation chain (starting values for (Ê , Ì ) and exact values for the corresponding position of
the manipulator (Ê Ñ , Ì Ñ )), the starting value can be determined very elegantly and easily by the use of
homogeneous 3D transformation matrices. We have:
È Ê¡È Ï · Ì
À¡È Ï
and
À Ú À Ñ ½ ¡À ´×ØÖص ½ ¡À
where
À Ú : Transformation from world coordinate system to
base coordinate system (starting value)
À Ñ : Transformation from base coordinate system and
manipulator coordinate system
À ´×ØÖص : Transformation from manipulator coordinate system
to camera coordinate system (starting value, measured)
À : Transformation from world coordinate system to camera
coordinate system (determined from exterior calibration).
See T pose to hom mat3d, T affine trans point 3d, T hom mat3d invert,
T hom mat3d compose,andT hom mat3d to pose.
How do I obtain the poses of the manipulator? The parameter MRelPoses determines the positions of the
manipulator. If Ñ positions were obtained by positioning the manipulator, these Ñ positions must be passed
linearized. The representation of these 3D poses is the same as for the exterior camera parameters and
the starting parameters CamStartPose and BaseStartPose. 3D poses are tuples of length 7, see
T create pose.
It is extremely important for the algorithm of the hand-eye-calibration that the poses MRelPoses can be
obtained exactly from the manipulator. The transformation of the angles of a robot arm to the representation
of a pose (rotation and translation) can be performed with T create pose. It is advisable to use the
same procedure as for the determination of the starting value CamStartPose of the camera pose in the
manipulator coordinate system. The manipulator coordinate system must be oriented such that it is identical
or at least parallel to the base coordinate system in the initial position of the manipulator. In order to determine
the poses of the individual manipulator positions, first the three translation parameters between the origin
of the base coordinate system and the origin of the manipulator coordinate system should be determined.
The translations should be determined along the axes of the base coordinate system when passing them
to T create pose. For the orientation of the coordinate systems with respect to each other, one first
“rotates” around the z-axis of the translated coordinate system, then around the new y-axis, and finally around
the new x-axis created by the previous two rotations. The three rotation angles are used as parameters to
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 701
T create pose. Hence, according to this description of the pose, the following settings must be passed
to T create pose: ’coordinate system’ for the sight of the transformation, ’R(p-T)’ for the order of the
transformations, and ’gba’ for the order of rotations. This corresponds to representation type 10. See also
the description of T create pose.
How can I exclude individual pose parameters from the estimation? T hand eye calibration estimates
a maximum of 12 pose parameters. They are three rotation and three translation parameters each
for the pose of the base coordinate system in the world coordinate system and for the pose of the camera
coordinate system in the manipulator coordinate system. However, it is possible to exclude some of these
pose parameters from the estimation. This means that the starting values of the poses remain unchanged
and are assumed constant for the estimation of all other pose parameters. The parameter ToEstimate is
used to determine which pose parameters should be estimated. In ToEstimate, a list of keywords for the
parameters to be estimated is passed. They are:
For the pose of the base coordinate system in the world coordinate system:
’baseTx’ = translation along the x-axis
’baseTy’ = translation along the y-axis
’baseTz’ = translation along the z-axis
’baseRa’ = rotation around the x-axis
’baseRb’ = rotation around the y-axis
’baseRg’ = rotation around the z-axis
For the pose of the camera coordinate system in the manipulator coordinate system:
’camTx’ = translation along the x-axis
’camTy’ = translation along the y-axis
’camTz’ = translation along the z-axis
’camRa’ = rotation around the x-axis
’camRb’ = rotation around the y-axis
’camRg’ = rotation around the z-axis
In order to estimate all 12 of the pose parameters, all 12 keywords can be passed. Alternatively, the keyword
’all’ can be used.
It is useful to exclude individual parameters from the estimation if some of the pose parameters have been
measured exactly. On the other hand, fixing some parameters reduces the degrees of freedom in the estimation,
and thus increases the robustness to the estimated parameters, if the manipulator only has limited
movement abilities, e.g., a pan-tilt head.
Which terminating criteria can be used for the error minimization? The error minimization terminates either
after a fixed number of iterations or if the error falls below a given minimum error. The parameter
StopCriterion is used to choose between these two alternatives. If ’CountIterations’ is passed, the
algorithm terminates after MaxIterations iterations.
If StopCriterion is passed as ’MinError’, the algorithm runs until the error falls below the error
threshold given in MinError. If, however, the number of iterations reaches the number given in
MaxIterations, the algorithm terminates with an error message.
What is the order of the individual parameters? The length of the tuple MPointsOfImage corresponds to
the number of different positions of the manipulator. The parameter MPointsOfImage determines the
number of model points used in the individual positions. If the standard calibration table is used, this means
49 points per position (image). If 15 images were acquired, MPointsOfImage is a tuple of length 15,
where all elements of the tuple have the value 49.
The number of calibration images, which is determined by the length of MPointsOfImage, mustalsobe
taken into account for the 3D model point tuples and the extracted 2D marks tuples, respectively. Hence,
for 15 calibration images with 49 model points each, the tuples NX, NY, NZ, NRow, andNCol must contain
½ ¡ ¿ values each. These tuples are ordered according to the image the respective points lie in, i.e.,
the first 49 values correspond to the 49 model points in the first image. The order of the 3D model points and
the extracted 2D model points must be the same in each image.
The length of the tuple MRelPoses corresponds to the number of calibration images. If, for example, 15
images from different positions were acquired, the length of the tuple MRelPoses is ½ ¡ ½¼ (15 times
7 pose parameters). The first seven parameters thus determine the pose of the manipulator in the first image,
and so on.
HALCON 6.0

702 CHAPTER 12. TOOLS
What do the output parameters mean? If StopCriterion was set to ’CountIterations’, the output parameters
are returned, even if the algorithm didn’t converge. If, however, StopCriterion was set to ’Min-
Error’, the error must fall below ’MinError’ in order for output parameters to be returned.
The output parameters are the pose of the base coordinate system in the world coordinate system
(BaseFinalPose) and the pose of the camera coordinate system in the manipulator coordinate system
(CamFinalPose).
The representation type of BaseFinalPose and CamFinalPose is the same as the corresponding starting
values. It can be changed with the operator T convert pose type. The description of the different
representation types and of their conversion can be found with the documentation of the operator
T create pose.
The parameter NumErrors contains a list of (numerical) errors from the individual iterations of the algorithm.
Based on the evolution of the errors, it can be decided whether the algorithm has converged for the
given starting values. The error values are returned as 3D deviations in meters. Thus, the last entry of the
error list corresponds to an estimate of the accuracy of the returned pose parameters.
Attention
The quality of the calibration depends on the accuracy of the input parameters (position of the calibration marks and
the starting positions BaseStartPose, CamStartPose). Based on the returned error measures NumErrors,
it can be decided, whether the algorithm has converged. Furthermore, the accuracy of the returned pose can be
estimated. The error measures are 3D differences in meters.
Parameter
º NX (input control) .......................................................real-array Htuple . double
Linear list containing all the X-coordinates of the calibration points (in the order of the image).
º NY (input control) .......................................................real-array Htuple . double
Linear list containing all the Y-coordinates of the calibration points (in the order of the image).
º NZ (input control) .......................................................real-array Htuple . double
Linear list containing all the Z-coordinates of the calibration points (in the order of the image).
º NRow (input control) .....................................................real-array Htuple . double
Linear list containing all the labelled abscissas (in the order of the image).
º NCol (input control) .....................................................real-array Htuple . double
Linear list containing all the labelled ordinates (in the order of the image).
º MPointsOfImage (input control) ......................................integer-array Htuple . long
Number of the calibration points for each image.
º MRelPoses (input control) .......................................pose-array Htuple . double / long
Measured values of relative pose of gripping device for each image.
º BaseStartPose (input control) .................................pose-array Htuple . double / long
Initial value for robot pose in world coordinate system.
º CamStartPose (input control) ...................................pose-array Htuple . double / long
Initial value for camera pose relative to end-effector.
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
º ToEstimate (input control) ......................................string-array Htuple . const char *
Parameters to be estimated (max. 12 free degrees).
Default Value : ”all”
Value List : ToEstimate ¾”all”, ”baseTx”, ”baseTy”, ”baseTz”, ”baseRa”, ”baseRb”, ”baseRg”,
”camTx”, ”camTy”, ”camTz”, ”camRa”, ”camRb”, ”camRg”
º StopCriterion (input control) .......................................string Htuple . const char *
Type of stopping criterion.
Default Value : ”CountIterations”
Value List : StopCriterion ¾”CountIterations”, ”MinError”
º MaxIterations (input control) .............................................integer Htuple . long
Maximum number of iterations to be executed.
Default Value : 15
Value Suggestions : MaxIterations ¾10, 15, 20, 25, 30
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 703
º MinError (input control) .....................................................real Htuple . double
Minimum error used as the stopping criterion.
Default Value : 0.0005
Value Suggestions : MinError ¾0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1
º BaseFinalPose (output control) .............................pose-array Htuple . double * / long *
Computed pose of base system to world coodinate system.
º CamFinalPose (output control) ...............................pose-array Htuple . double * / long *
Computed pose of the camera relative to the coodinate system of the gripping device .
º NumErrors (output control) ..........................................real(-array) Htuple . double *
Error measures for each iteration.
Example
HTuple
HTuple
HTuple
HTuple
HTuple
Hobject
char
char
CamParam, RCoord, CCoord;
ManuPose, NumMarker, X, Y, Z, XPositions, YPositions;
ZPositions, RCoordTmp, CCoordTmp, StartPose;
ManuPoseTmp, BaseStartPose, CamStartPose, BaseFinalPose;
CamFinalPose, NumErrors;
Image, Caltab;
Datname[256];
CaltabName[256];
sprintf(CaltabName, "Caltab.descr");
::read_cam_par("CamParam.cal",&CamParam);
RCoord = HTuple();
CCoord = HTuple();
ManuPose = HTuple();
NumMarker = HTuple();
::caltab_points(CaltabName,&X,&Y,&Z);
XPositions = HTuple();
YPositions = HTuple();
ZPositions = HTuple();
// find landmarks in every image
for (long i=0; i

704 CHAPTER 12. TOOLS
Result
T hand eye calibration returns H MSG TRUE if all parameter values are correct and the method coverges
with an error less than the specified minimum error (if StopCriterion = ’MinError’). If necessary, an
exception handling is raised.
Parallelization Information
T hand eye calibration is reentrant and processed without parallelization.
T find marks and pose
Possible Predecessor Functions
Possible Successor Functions
T write pose, T convert pose type, T pose to hom mat3d, T disp caltab, T sim caltab
See Also
find caltab, T find marks and pose, T disp caltab, T sim caltab, T write cam par,
T read cam par, T create pose, T convert pose type, T write pose, T read pose,
T pose to hom mat3d, T hom mat3d to pose, T caltab points, create caltab
Camera calibration
Module
T hom mat3d to pose ( Htuple HomMat3D, Htuple *Pose )
Convert homogeneous transformation matrix into 3D pose parameter.
T hom mat3d to pose is used to convert a homogeneous transformation matrix into the correspondent representation
of the transformation as translational vector and rotational angles.
The homogeneous 4x3 transformation matrix is given as a tupel HomMat3D in the following order: The first four
values describe the first row of the rotation matrix and x-value of the translation vector. The next four values
describe the second row of the rotation matrix and the y-value of the translation vector. These are followed by the
values of the third row of the rotation matrix and the z-value of the translation vector.
The output tupel Pose describes the external camera parameter by the 3D translational vector (in meters), the
three rotation angles and the representation type of the 3D transform. The representation type of a 3D transform
generated by T hom mat3d to pose has Type 1 with code ’0’. This means, that the transform of a point is
described, hereby the 3D rotation is performed before the 3D translation, that the three rotations are specified as
angles (in degrees), and that the rotation order is ­-¬-«, i.e., the first rotation is around the Z-axis, the second one
around the new Y-axis, and the third one around the new X-axis, which is generated after the second rotation. This
corrensponds to the transformation by homogenous matixes directly. This can be explained by the following holds:
È Ü Ý Þ℄ Ì À¡È Ï
Ê´½µ ¡ È Ï · Ì ´½µ
The sense of the other representation types are explained at T create pose. With T convert pose type
you can convert Pose to every other kind of representation type.
The subsequent program example shows how to generate an appropriate initial camera pose for
T camera calibration, if the camera pose is roughly measured in the world coordinate system. This is
especially important if no planar calibration table (see create caltab) is used and therefore the operator
T find marks and pose cannot be applied. Instead of this natural or artificial landmarks with known world
position can be used.
Let for example the relative camera position in the world coordinate system be the following: x = 1.08 m, y = 0.25
m, z = 0.62 m. This means, that the origin of the camera coordinate system in world coordinates has the value
[1.08, 0.25, 0.62]. The camera coordinate system is oriented that way, that the line of sight of the camera is along
the positive Z-axis. The orientation of the camera coordinate system is given by three rotational angles. In the
program example the camera coordinate system is first rotated by 100 degrees around the Z-axis. Subsequently
it is rotated by -120 degree around the new (!!!) X-axis. Note that the parameter with the rotation angle in
T hom mat3d rotate is negated. This is because the description of a point transfomation and the description
of a coordinate system transformation differs in the sign of the rotational angles. See also explanation and example
at T create pose.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 705
Parameter
º HomMat3D (input control) ...........................................affine3d-array Htuple . double
Homogeneous transformation matrix.
Parameter Number : 12
º Pose (output control) ..........................................pose-array Htuple . double * / long *
External camera parameters.
Parameter Number : 7
Example
HTuple CamParam,StartPose,FinalPose,Errors,Dummy;
HTuple HomMat3DIdent,HomMat3DWorldStart;
HTuple HomMat3DTransX,HomMat3DTransY,HomMat3DTransZ;
HTuple HomMat3DRotX,HomMat3DRotY,HomMat3DRotZ;
HTuple WorldPointsX,WorldPointsY,WorldPointsZ,PixelsRow,PixelsColumn;
// read 3D world points [WorldPointsX,WorldPointsY,WorldPointsZ]
// extract correspondent 2D image points [PixelsRow,PixelsColumn]
// read internal camera parameters:
::read_cam_par("campar.dat",&CamParam);
// get rough camera pose from relative camera pose:
::hom_mat3d_identity(&HomMat3DIdent);
::hom_mat3d_translate(HomMat3DIdent,-1.08,-0.25,-0.62,&HomMat3DTrans);
::hom_mat3d_rotate(HomMat3DTrans,-100.0*3.14159/180.0,"z",0,0,0,
&HomMat3DRotZ);
::hom_mat3d_rotate(HomMat3DRotZ,+120.0*3.14159/180.0,"x",0,0,0,
&HomMat3DWorldStart);
// convert transformation matrix to pose (rotation and translation)
::hom_mat3d_to_pose(HomMat3DWorldStart,&StartPose);
// calibration of external camera params:
::camera_calibration(WorldPointsX,WorldPointsY,WorldPointsZ,
PixelsRow,PixelsColumn,CamParam,StartPose,6,
&Dummy,&FinalPose,&Errors);
Result
T hom mat3d to pose returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised
Parallelization Information
T hom mat3d to pose is reentrant and processed without parallelization.
Possible Predecessor Functions
T hom mat3d rotate, T hom mat3d translate, T hom mat3d invert
Possible Successor Functions
T camera calibration, T write pose, T disp caltab, T sim caltab
See Also
T create pose, T camera calibration, T disp caltab, T sim caltab, T write pose,
T read pose, T pose to hom mat3d, T project 3d point, T get line of sight,
T hom mat3d rotate, T hom mat3d translate, T hom mat3d invert,
T affine trans point 3d
Module
Camera calibration
T image points to world plane ( Htuple CamParam, Htuple CamPose,
Htuple Rows, Htuple Cols, Htuple Scale, Htuple *X, Htuple *Y )
Transform image points to a world plane represented by external camera parameters.
The operator T image points to world plane transforms image points which are given in Rows and Cols
into a plane in the world coordinate system. The plane is either equal to the plane of the calibration plate or parallel
HALCON 6.0

706 CHAPTER 12. TOOLS
to it if the operator T set origin pose has been applied previously to correct the thickness of the calibration
plate. In the first step the line of sight between the projection center and the image point is computed in the camera
coordinate system, taking into account the radial distortions using the internal camera parameters CamParam. The
line of sight is then transformed into the world coordinate system using the external camera parameters CamPose.
By intersecting the plane (Z=0) with the line of sight the pseudo 3d coordinates X and Y are obtained. It is possible
to scale the coordinates with the parameter Scale. This is particularly useful when displaying the coordinates
in an image. The parameter Scale must be specified in [ÙÒØÔÜÐ]. The original unit is determined by the
coordinates of the calibration targets. In many cases this unit is introduced into the calibration as ’meters’, i.e. one
meter in the world coordinate system corresponds to one pixel in the image. In this case, it is possible to set the
pixel size directly by selecting ’m’, ’cm’, ’mm’ or ’m’ for the parameter Scale.
Parameter
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º CamPose (input control) .........................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
º Rows (input control) ......................................coordinates.y-array Htuple . double / long
line indices of the points to be transformed
Default Value : 100.0
º Cols (input control) ......................................coordinates.x-array Htuple . double / long
column indices of the points to be transformed
Default Value : 100.0
º Scale (input control) ...................................number Htuple . const char * / long / double
Scale or dimension
Default Value : ’m’
Value Suggestions : Scale ¾’m’, ’cm’, ’mm’, ’microns’, ’m’, 1.0, 0.01, 0.001, ’1e-6’, 0.0254, 0.3048,
0.9144
º X (output control) .............................................coordinates.x-array Htuple . double *
x-coordinate in the world coordinate system.
º Y (output control) .............................................coordinates.y-array Htuple . double *
y-coordinate in the world coordinate system.
Result
T image points to world plane returns H MSG TRUE if all parameter values are correct. If necessary,
an exception handling is raised.
Parallelization Information
T image points to world plane is reentrant and processed without parallelization.
Possible Predecessor Functions
T create pose, T hom mat3d to pose, T camera calibration, T hand eye calibration,
T set origin pose
See Also
T contour to world plane xld
Module
Camera calibration
T pose to hom mat3d ( Htuple Pose, Htuple *HomMat3D )
Convert 3d pose parameters into homogeneous transformation matrix.
T pose to hom mat3d is used to convert 3D pose parameters, like external camera parameter (camera pose
Pose) into the equivalent homogeneous 4x3 transformation matrix HomMat3D.
This transformation matrix consists of a 3x3 rotation matrix and a translational vector. The values are given as a
tupel HomMat3D in the following order: The first four values describe the first row of the rotation matrix and x-
value of the translation vector. The next four values describe the second row of the rotation matrix and the y-value
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 707
of the translation vector. These are followed by the values of the third row of the rotation matrix and the z-value of
the translation vector.
The input tupel Pose describes 3D pose parameters which describe a 3D transform, for example the external
camera parameter. These are given by the 3D translational vector (in meters), the three rotational angles and the
code of the representation type of the 3D transform: E.g., the value ’0’ is the code of the representation type 1 and
says, that the transform of a point is described, hereby the 3D rotation is performed before the 3D translation, that
the three rotations are specified as angles (in degrees), and that the rotation order is ­-¬-«, i.e., the first rotation
is around the Z-axis, the second one around the new Y-axis, and the third one around the new X-axis, which
is generated after the second rotation. T pose to hom mat3d operates with all types of 3D transform. The
sense of the other representation types are explained at T create pose. The 3D transform with type 1 directly
corrensponds to the transformation by homogenous matixes. This can be explained by the following holds:
È Ü Ý Þ℄ Ì Ê´½µ ¡ È Ï · Ì ´½µ
À¡È Ï
Parameter
º Pose (input control) ..............................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
º HomMat3D (output control) ........................................affine3d-array Htuple . double *
Homogeneous transformation matrix.
Parameter Number : 12
Example
HTuple CamParam,StartCamPose,FinalCamPose,Errors,Dummy;
HTuple HomMat3DWorldCam;
HTuple WorldPointsX,WorldPointsY,WorldPointsZ,PixelsRow,PixelsColumn;
// read 3D world points [WorldPointsX,WorldPointsY,WorldPointsZ]
// extract correspondent 2D image points [PixelsRow,PixelsColumn]
// read internal camera parameters:
::read_cam_par("campar.dat",&CamParam);
// read initial camera pose
::read_pose(::"campose.initial":StartCamPose);
// calibration of external camera params:
::camera_calibration(WorldPointsX,WorldPointsY,WorldPointsZ,
PixelsRow,PixelsColumn,CamParam,StartCamPose,6,
&Dummy,&FinalCamPose,&Errors);
// transform FinalCamPose to 4x3 transformation matrix
::pose_to_hom_mat3d(FinalCamPose,&HomMat3DWorldCam);
Result
T pose to hom mat3d returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised
Parallelization Information
T pose to hom mat3d is reentrant and processed without parallelization.
Possible Predecessor Functions
T camera calibration, T read pose
Possible Successor Functions
T affine trans point 3d, T hom mat3d invert, T hom mat3d translate,
T hom mat3d rotate, T hom mat3d to pose
See Also
T create pose, T camera calibration, T write pose, T read pose, T hom mat3d to pose,
T project 3d point, T get line of sight, T hom mat3d rotate, T hom mat3d translate,
T hom mat3d invert, T affine trans point 3d
Camera calibration
Module
HALCON 6.0

708 CHAPTER 12. TOOLS
T project 3d point ( Htuple X, Htuple Y, Htuple Z, Htuple CamParam,
Htuple *Row, Htuple *Column )
Project 3D points into (sub-)pixels.
T project 3d point is used to project one or more 3D points (with coordinates X, Y, andZ) into the image
plane (in pixels). The coordinates X, Y, andZ are given in the camera coordinate system, i.e., they describe the
position of the point relative to the camera.
The internal camera parameters CamParam (Focus, Sx, Sy, Cx, Cy, Kappa (), ImageWidth and ImageHeight)
describe the projection characteristics of the camera. The underlying camera model is a pinhole camera with
radial distortions if the focal length passed in CamParam is greater than 0. It describes the transform of a 3D
point È into a (sub-)pixel [r,c] of the video image by the following equations:
Ù
½·
È Ü Ý Þ℄ Ì
Ù Focus ¡ Ü Þ
and Ú Focus ¡ Ý Þ
¾Ù
Ô½ ´Ù ¾·Ú and Ú Ô
¾Ú
¾ µ
½·
Ù Ë Ü · Ü and Ö Ú
Ë Ý · Ý
½ ´Ù ¾·Ú ¾ µ
If the focal length is passed as 0 in CamParam, the camera model of a telecentric camera with radial distortions
is used, i.e., it is assumed that the optics of the lens of the camera performs a parallel projection. In this case, the
corresponding equations are:
Ù
È Ü Ý Þ℄ Ì Ê¡È Ï · Ì
Ù Ü and Ú Ý
¾Ù
½·
Ô½ ´Ù ¾·Ú bzw. Ú ¾Ú
¾ µ ½· ½ ´Ù ¾·Ú¾ µ
Ô
Ù Ë Ü · Ü bzw. Ö Ú
Ë Ý · Ý
These equations consist of a coordinate transform from the world coordinate system into the camera coordinate
system, a perspective or parallel projection into the image plane, a radial distortion of the projected point, and
finally a sampling and an image center displacement.
Parameter
º X (input control) .........................................................real-array Htuple . double
X-coordinates of the 3D points to be projected.
º Y (input control) .........................................................real-array Htuple . double
Y-coordinates of the 3D points to be projected.
º Z (input control) .........................................................real-array Htuple . double
Z-coordinates of the 3D points to be projected.
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º Row (output control) ...................................................real-array Htuple . double *
Row-coordinates of pixels.
Default Value : ’ProjectedRow’
º Column (output control) ...............................................real-array Htuple . double *
Column-coordinates of pixels.
Default Value : ’ProjectedCol’
Example
HTuple CamPose,HomMat3D,X1,Y1,Z1,X2,Y2,Z2,CamParam,Row,Column;
// read camera pose
::read_pose("campose.dat",&CamPose);
// transform camera pose to transformation matrix
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 709
::pose_to_hom_mat3d(CamPose,&HomMat3D);
// transform 3D points from source into destination coordinate system
X1[1] = 3.2;
X1[0] = 3.0;
Y1[1] = 4.5;
Y1[0] = 4.5;
Z1[1] = 6.2;
Z1[0] = 5.8;
::affine_trans_point_3d(X1,Y1,Z1,HomMat3D,&X2,&Y2,&Z2);
// read internal camera parameters
::read_cam_par("campar.dat",&CamParam);
// project 3D points into image
::project_3d_point(X2,Y2,Z2,CamParam,&Row,&Column);
Result
T project 3d point returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised.
Parallelization Information
T project 3d point is reentrant and processed without parallelization.
Possible Predecessor Functions
T read cam par, T affine trans point 3d
Possible Successor Functions
gen region points, gen region polygon, disp polygon
See Also
T camera calibration, T disp caltab, T read cam par, T get line of sight,
T affine trans point 3d
Module
Camera calibration
T read cam par ( Htuple CamParFile, Htuple *CamParam )
Read the internal camera parameters from text file.
T read cam par is used to read the internal camera parameters CamParam from a text file with name
CamParFile.
The format of the text file is a (Halcon-independent) generic parameter description. Thus, arbitrary sets of parameters
can be grouped together in a hierarchical way. The description of a single parameter within a parameter group
consists of the following 3 lines:
Name : Shortname : Actual value ;
Type : Lower bound (optional) : Upper bound (optional) ;
Description (optional) ;
The Halcon operator T write cam par expects in the file CamParFile the parameter group Camera:
Parameter. This parameter group consists of the 8 parameters Focus, Sx, Sy, Cx, Cy, Kappa (), ImageWidth
and ImageHeight. Comments are marked by a ’#’ at the beginning of a line. A suitable file can look like the
following:
# INTERNAL CAMERA PARAMETERS
ParGroup: Camera: Parameter;
"Internal CCD-camera parameters";
Focus:foc: 0.00806039;
DOUBLE:0.0:;
"Focal length of the lens [meter]";
HALCON 6.0

710 CHAPTER 12. TOOLS
Sx:sx: 1.0629e-05;
DOUBLE:0.0:;
"Width of a cell on the CCD-chip [meter]";
Sy:sy: 1.1e-05;
DOUBLE:0.0:;
"Height of a cell on the CCD-chip [meter]";
Cx:cx: 378.236;
DOUBLE:0.0:;
"X-coordinate of the image center [pixel]";
Cy:cy: 297.587;
DOUBLE:0.0:;
"Y-coordinate of the image center [pixel]";
Kappa:kappa: -2253.5;
DOUBLE::;
"Radial distortion coefficient [1/(meter*meter)]";
ImageWidth:imgw: 768;
INT:0:2048;
"Width of the used calibration images [pixel]";
ImageHeight:imgh: 576;
INT:0:2048;
"Height of the used calibration images [pixel]";
The underlying camera model is a pinhole or telecentric camera with radial distortions. A detailed description
of these camera models can be found with description of T write cam par.
Parameter
º CamParFile (input control) ...........................................string Htuple . const char *
File name of internal camera parameters.
Default Value : ’campar.dat’
Value List : CamParFile ¾’campar.dat’, ’campar.initial’, ’campar.final’
º CamParam (output control) .................................number-array Htuple . double * / long *
Internal camera parameters.
Parameter Number : 8
Example
HTuple CamParam;
// get internal camera parameters:
::read_cam_par("campar.dat",&CamParam);
Result
T read cam par returns H MSG TRUE if all parameter values are correct and the file has been read successfully.
If necessary an exception handling is raised.
Parallelization Information
T read cam par is reentrant and processed without parallelization.
Possible Successor Functions
T find marks and pose, T sim caltab, create caltab, T disp caltab,
T camera calibration
See Also
find caltab, T find marks and pose, T camera calibration, T disp caltab,
T sim caltab, T write cam par, T write pose, T read pose, T project 3d point,
T get line of sight
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 711
Camera calibration
Module
T read pose ( Htuple PoseFile, Htuple *Pose )
Read 3D pose data from text file.
T read pose is used to read the 3D pose Pose from a text file with the name PoseFile.
The output tupel Pose describes 3D pose parameters which describe a 3D transform, for example the external
camera parameters. These are given by the 3D translational vector (in meters), the three rotation angles and the
code of the representation type of the 3D transform: E.g., the value ’0’ is the code of the representation type 1 and
says, that the transform of a point is described, hereby the 3D rotation is performed before the 3D translation, that
the three rotations are specified as angles (in degrees), and that the rotation order is ­-¬-«, i.e., the first rotation
is around the Z-axis, the second one around the new Y-axis, and the third one around the new X-axis, which is
generated after the second rotation. T pose to hom mat3d operates with all types of 3D transforms. The sense
of the other representation types is explained at T create pose.
A suitable file can be generated by the operator T write pose and looks like the following:
# 3D POSE PARAMETERS: rotation and translation
# Used representation type:
f 0
# Rotation angles [deg] or Rodriguez-vector:
r -17.8134 1.83816 0.288092
# Translational vector (x y z [m]):
t 0.280164 0.150644 1.7554
Parameter
º PoseFile (input control) ...........................................filename Htuple . const char *
File name of the external camera parameters.
Default Value : ’campose.dat’
Value List : PoseFile ¾’campose.dat’, ’campose.initial’, ’campose.final’
º Pose (output control) ..........................................pose-array Htuple . double * / long *
External camera parameters.
Parameter Number : 7
Example
HTuple CamPose;
// get pose (external camera parameters):
::read_pose("campose.dat",&CamPose);
Result
T read pose returns H MSG TRUE if all parameter values are correct and the file has been read successfully.
If necessary an exception handling is raised.
Parallelization Information
T read pose is reentrant and processed without parallelization.
T read cam par
Possible Predecessor Functions
Possible Successor Functions
T pose to hom mat3d, T camera calibration, T disp caltab, T sim caltab
See Also
T create pose, T find marks and pose, T camera calibration, T disp caltab,
T sim caltab, T write pose, T pose to hom mat3d, T hom mat3d to pose
HALCON 6.0

712 CHAPTER 12. TOOLS
Camera calibration
Module
T set origin pose ( Htuple PoseIn, Htuple DX, Htuple DY, Htuple DZ,
Htuple *PoseNewOrigin )
Translate the origin of the external camera parameters.
T set origin pose translates the origin of the external camera parameters (pose) by a vector, determined
by DX, DY and DZ. This can be used, for example, to correct the obtained parameters from camera calibration
(PoseIn) with respect to the thickness of the calibration plate. To achieve this, the translation vector
must have the form (0,0,-), where is the thickness of the calibration plate. The resulting new parameters
PoseNewOrigin correspond to a calibration with a calibration plate of infinitely small thickness. Therefore, it is
possible to measure points in the world coordinate system (e.g., by calling T image points to world plane
or T contour to world plane xld) directly in the requested measurement plane instead of the plane of the
calibration plate). In this context it is now also possible to avoid negative coordinates in the world coordinate
system by choosing suitable values for DX and DY.
Parameter
º PoseIn (input control) ...........................................pose-array Htuple . double / long
original 3D transformation.
Parameter Number : 7
º DX (input control) .............................................................real Htuple . double
translation of the origin in x-direction.
Default Value : 0
º DY (input control) .............................................................real Htuple . double
translation of the origin in y-direction.
Default Value : 0
º DZ (input control) .............................................................real Htuple . double
translation of the origin in z-direction.
Default Value : 0
º PoseNewOrigin (output control) .............................pose-array Htuple . double * / long *
new 3D description after applying the translation.
Parameter Number : 7
Result
T set origin pose returns H MSG TRUE if all parameter values are correct. If necessary, an exception
handling is raised.
Parallelization Information
T set origin pose is reentrant and processed without parallelization.
Possible Predecessor Functions
T create pose, T hom mat3d to pose, T camera calibration, T hand eye calibration
Possible Successor Functions
T write pose, T pose to hom mat3d, T image points to world plane,
T contour to world plane xld
Module
Camera calibration
T sim caltab ( Hobject *SimImage, Htuple CalTabDescrFile,
Htuple CamParam, Htuple CamPose, Htuple GrayBackground, Htuple GrayCaltab,
Htuple GrayMarks, Htuple ScaleFac )
Simulate a video image with calibration table.
T sim caltab is used to generate a simulated calibration image. The calibration table description is read from
the file CalTabDescrFile and will be projected into the image plane using the given camera parameters (internal
camera parameters CamParam and external camera parameters CamPose), see also T project 3d point.
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 713
In the simulated image only the calibration table is shown. The image background is set to the gray value
GrayBackground, the calibration table background is set to GrayCaltab, and the calibration marks are
set to the gray value GrayMarks. The parameter ScaleFac influences the number of supporting points to
approximate the elliptic contours of the calibration marks, see also T disp caltab. Increasing the number of
supporting points causes a more accurate determination of the mark boundary, but increases the computation time,
too. For each pixel of the simulated video image, which touches a subpixel-boundary of this kind, the gray value
is set linearly between GrayMarks and GrayCaltab dependent on the proportion Inside/Outside.
By applying the operator T sim caltab you can generate synthetic calibration images (with known camera
parameters!) to test the quality of the calibration algorithm (see T camera calibration).
Parameter
º SimImage (output object) .................................................image Hobject * : byte
Simulated calibration image.
º CalTabDescrFile (input control) .....................................string Htuple . const char *
File name of the calibration table description.
Default Value : ’caltab.descr’
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º CamPose (input control) .........................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
º GrayBackground (input control) ............................................integer Htuple . long
Gray value of image background.
Default Value : 128
Value Suggestions : GrayBackground ¾0, 32, 64, 96, 128, 160
Restriction : ´0 GrayBackgroundµ 255
º GrayCaltab (input control) .................................................integer Htuple . long
Gray value of calibration table.
Default Value : 224
Value Suggestions : GrayCaltab ¾144, 160, 176, 192, 208, 224, 240
Restriction : ´0 GrayCaltabµ 255
º GrayMarks (input control) ...................................................integer Htuple . long
Gray value of calibration marks.
Default Value : 80
Value Suggestions : GrayMarks ¾16, 32, 48, 64, 80, 96, 112
Restriction : ´0 GrayMarksµ 255
º ScaleFac (input control) .....................................................real Htuple . double
Scaling factor to reduce oversampling.
Default Value : 1.0
Value Suggestions : ScaleFac ¾1.0, 0.5, 0.25, 0.125
Recommended Value Step : 0.05
Restriction : 1.0 ScaleFac
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple StartPose,RCoords,CCoords;
HTuple CamParam,FinalPose,Errors;
// read calibration image
HImage Image1("calib-01.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and initial pose
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
HALCON 6.0

714 CHAPTER 12. TOOLS
StartCamPar[4] = 384;
// Cx
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
::camera_calibration(NX,NY,NZ,RCoord1,CCoord1,StartCamPar,StartPose,
11,&CamParam,&FinalPose,&Errors);
HImage Image1Sim = HImage::SimCaltab("caltab.descr",CamParam,FinalPose,
128,224,80,1.0);
Result
T sim caltab returns H MSG TRUE if all parameter values are correct. If necessary, an exception handling is
raised.
Parallelization Information
T sim caltab is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
T camera calibration, T find marks and pose, T read pose, T read cam par,
T hom mat3d to pose
Possible Successor Functions
find caltab
See Also
find caltab, T find marks and pose, T camera calibration, T disp caltab,
T create pose, T hom mat3d to pose, T project 3d point, create caltab
Camera calibration
Module
T write cam par ( Htuple CamParam, Htuple CamParFile )
Write the internal camera parameters to text file.
T write cam par is used to write the internal camera parameters CamParam to a text file with name
CamParFile.
The format of the text file is a (Halcon-independent) generic parameter description. Thus, arbitrary sets of parameters
can be grouped together in a hierarchical way. The description of a single parameter within a parameter group
consists of the following 3 lines:
Name : Shortname : Actual value ;
Type : Lower bound (optional) : Upper bound (optional) ;
Description (optional) ;
The following parameter types are supported in this generic format: BOOL, XBOOL (exclusive BOOL), INT,
FLOAT, DOUBLE, STRING and FILE SELECTOR. Comments are marked by a ’#’ at the beginning of a line.
The operator T write cam par writes the parameter group Camera:Parameter into the text file CamParFile.
This parameter group consists of the 8 parameters Focus, Sx, Sy, Cx, Cy, Kappa (), ImageWidth and ImageHeight.
The underlying camera model is a pinhole camera with radial distortions if the focal length passed in
CamParam is greater than 0. It describes the transform of a 3D point È into a (sub-)pixel [r,c] of the video
image by the following equations:
È Ü Ý Þ℄ Ì
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 715
Ù
½·
Ù Focus ¡ Ü Þ
and Ú Focus ¡ Ý Þ
¾Ù
Ô½ ´Ù ¾·Ú and Ú Ô
¾Ú
¾ µ
½·
Ù Ë Ü · Ü and Ö Ú
Ë Ý · Ý
½ ´Ù ¾·Ú ¾ µ
If the focal length is passed as 0 in CamParam, the camera model of a telecentric camera with radial distortions
is used, i.e., it is assumed that the optics of the lens of the camera performs a parallel projection. In this case, the
corresponding equations are:
Ù
È Ü Ý Þ℄ Ì Ê¡È Ï · Ì
Ù Ü and Ú Ý
¾Ù
½·
Ô½ ´Ù ¾·Ú bzw. Ú ¾Ú
¾ µ ½· ½ ´Ù ¾·Ú¾ µ
Ô
Ù Ë Ü · Ü bzw. Ö Ú
Ë Ý · Ý
These equations consist of a coordinate transform from the world coordinate system into the camera coordinate
system, a perspective or parallel projection into the image plane, a radial distortion of the projected point, and
finally a sampling and an image center displacement.
The parameter Ê and Ì describe the 3D pose of the camera coordinate system in the world coordinate system.
They are called external camera parameters, see also T hom mat3d to pose and T create pose.
The internal camera parameters consist of the focal length (Focus), the radial distortion coefficient (), the scale
factor Ë Ü and Ë Ý (horizontal and vertical distance between cells on the CCD chip), the image center Ü Ý ℄ Ì ,
and the used image width and height. The internal camera parameters are - in contrast to the external parameters -
independent of the actual pose of the CCD camera. They describe the projection process of the used combination
of camera, lens, and frame grabber. The determination of these parameters is done by the camera calibration, see
T camera calibration.
Parameter
º CamParam (input control) .....................................number-array Htuple . double / long
Internal camera parameters.
Parameter Number : 8
º CamParFile (input control) ...........................................string Htuple . const char *
File name of internal camera parameters.
Default Value : ’campar.dat’
Value List : CamParFile ¾’campar.dat’, ’campar.initial’, ’campar.final’
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple RCoord2,CCoord2,StartPose2;
HTuple RCoord3,CCoord3,StartPose3;
HTuple StartPoses,RCoords,CCoords;
HTuple CamParam,NFinalPose,Errors;
// read calibration images
HImage Image1("calib-01.tiff");
HImage Image2("calib-02.tiff");
HImage Image3("calib-03.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab2 = Image2.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab3 = Image3.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start poses
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
StartCamPar[4] = 384;
// Cx
HALCON 6.0

716 CHAPTER 12. TOOLS
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose1);
RCoord2 = Image2.FindMarksAndPose(Caltab2,"caltab.descr",StartCamPar,
128,10,&CCoord2,&StartPose2);
RCoord3 = Image3.FindMarksAndPose(Caltab3,"caltab.descr",StartCamPar,
128,10,&CCoord3,&StartPose3);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
StartPoses = (StartPose1.Append(StartPose2)).Append(StartPose3);
RCoords = (RCoord1.Append(RCoord2)).Append(RCoord3);
CCoords = (CCoord1.Append(CCoord2)).Append(CCoord3);
::camera_calibration(NX,NY,NZ,RCoords,CCoords,StartCamPar,StartPoses,
11,&CamParam,&NFinalPose,&Errors);
// write internal camera parameters to file
::write_cam_par(CamParam,"campar.dat");
Result
T write cam par returns H MSG TRUE if all parameter values are correct and the file has been written successfully.
If necessary an exception handling is raised.
Parallelization Information
T write cam par is local and processed completely exclusively without parallelization.
T camera calibration
Possible Predecessor Functions
See Also
find caltab, T find marks and pose, T camera calibration, T disp caltab,
T sim caltab, T read cam par, T write pose, T read pose, T project 3d point,
T get line of sight
Module
Camera calibration
T write pose ( Htuple Pose, Htuple PoseFile )
Write 3D pose data to text file.
T write pose is used to write 3D pose data Pose into a text file with the name PoseFile.
The input tupel Pose describes 3D pose parameters which describe a 3D transform, for example the external
camera parameters. These are given by the 3D translational vector (in meters), the three rotation angles and the
code of the representation type of the 3D transform: E.g., the value ’0’ is the code of the representation type 1 and
says, that the transform of a point is described, hereby the 3D rotation is performed before the 3D translation, that
the three rotations are specified as angles (in degrees), and that the rotation order is ­-¬-«, i.e., the first rotation
is around the Z-axis, the second one around the new Y-axis, and the third one around the new X-axis, which is
generated after the second rotation. T pose to hom mat3d operates with all types of 3D transform. The sense
of the other representation types are explained at T create pose.
A file generated by T write pose looks like the following:
# 3D POSE PARAMETERS: rotation and translation
# Used representation type:
f 0
# Rotation angles [deg] or Rodriguez-vector:
HALCON/C Reference Manual / 2000-11-15

12.4. CALIBRATION 717
r -17.8134 1.83816 0.288092
# Translational vector (x y z [m]):
t 0.280164 0.150644 1.7554
Parameter
º Pose (input control) ..............................................pose-array Htuple . double / long
External camera parameters.
Parameter Number : 7
º PoseFile (input control) ...........................................filename Htuple . const char *
File name of the external camera parameters.
Default Value : ’campose.dat’
Value List : PoseFile ¾’campose.dat’, ’campose.initial’, ’campose.final’
Example
HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple RCoord2,CCoord2,StartPose2;
HTuple RCoord3,CCoord3,StartPose3;
HTuple StartPoses,RCoords,CCoords;
HTuple CamParam,NFinalPose,FinalPose,Errors;
// read calibration images
HImage Image1("calib-01.tiff");
HImage Image2("calib-02.tiff");
HImage Image3("calib-03.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab2 = Image2.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab3 = Image3.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start poses
StartCamPar[7] = 576;
// ImageHeight
StartCamPar[6] = 768;
// ImageWidth
StartCamPar[5] = 288;
// Cy
StartCamPar[4] = 384;
// Cx
StartCamPar[3] = 0.000011; // Sy
StartCamPar[2] = 0.000011; // Sx
StartCamPar[1] = 0.0;
// Kappa
StartCamPar[0] = 0.008; // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
128,10,&CCoord1,&StartPose1);
RCoord2 = Image2.FindMarksAndPose(Caltab2,"caltab.descr",StartCamPar,
128,10,&CCoord2,&StartPose2);
RCoord3 = Image3.FindMarksAndPose(Caltab3,"caltab.descr",StartCamPar,
128,10,&CCoord3,&StartPose3);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration
StartPoses = (StartPose1.Append(StartPose2)).Append(StartPose3);
RCoords = (RCoord1.Append(RCoord2)).Append(RCoord3);
CCoords = (CCoord1.Append(CCoord2)).Append(CCoord3);
::camera_calibration(NX,NY,NZ,RCoords,CCoords,StartCamPar,StartPoses,
11,&CamParam,&NFinalPose,&Errors);
/* write external camera parameters of first calibration image */
FinalPose[6] = NFinalPose[6];
FinalPose[5] = NFinalPose[5];
FinalPose[4] = NFinalPose[4];
FinalPose[3] = NFinalPose[3];
FinalPose[2] = NFinalPose[2];
HALCON 6.0

718 CHAPTER 12. TOOLS
FinalPose[1] = NFinalPose[1];
FinalPose[0] = NFinalPose[0];
::write_pose(FinalPose,"campose.dat");
Result
T write pose returns H MSG TRUE if all parameter values are correct and the file has been written successfully.
If necessary an exception handling is raised.
Parallelization Information
T write pose is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
T camera calibration, T hom mat3d to pose
See Also
T create pose, T find marks and pose, T camera calibration, T disp caltab,
T sim caltab, T read pose, T pose to hom mat3d, T hom mat3d to pose
Camera calibration
Module
12.5 Fourier-Descriptor
T abs invar fourier coeff ( Htuple RealInvar, Htuple ImaginaryInvar,
Htuple CoefP, Htuple CoefQ, Htuple AZInvar, Htuple *RealAbsInvar,
Htuple *ImaginaryAbsInvar )
Normalizing of the Fourier coefficients with respect to the displacment of the starting point.
The operator T abs invar fourier coeff normalizes the Fourier coefficients with regard to the displacements
of the starting point. These occur when an object is rotated. The contour tracer get region contour
starts with recording the contour in the upper lefthand corner of the region and follows the contour clockwise. If
the object is rotated, the starting value for the contour point chain is different which leads to a phase shift in the
frequency space. The following two kinds of normalizing are available:
abs amount: The phase information will be eliminated; the normalizing does not retain the structure, i.e. if the
AZ-invariants are backtransformed, no similarity with the pattern can be recognized anymore.
az invar1: AZ-invariants of the 1st order execute the normalizing with respect to displacing the starting point so
that the structure is retained; they are however more prone to local and global disturbances, in particular to
projective distortions.
Parameter
º RealInvar (input control) ..............................................real-array Htuple . double
Real parts of the normalized Fourier coefficients.
º ImaginaryInvar (input control) .......................................real-array Htuple . double
Imaginary parts of the normalized Fourier coefficients.
º CoefP (input control) ........................................................integer Htuple . long
Normalizing coefficients p.
Default Value : 1
Value Suggestions : CoefP ¾1, 2
Restriction : CoefP 1
º CoefQ (input control) ........................................................integer Htuple . long
Normalizing coefficients q.
Default Value : 1
Value Suggestions : CoefQ ¾1, 2
Restriction : ´CoefQ 1µ ´CoefQ CoefPµ
º AZInvar (input control) ...............................................string Htuple . const char *
Order of the AZ-invariants.
Default Value : ’abs amount’
Value List : AZInvar ¾’abs amount’, ’az invar1’
HALCON/C Reference Manual / 2000-11-15

12.5. FOURIER-DESCRIPTOR 719
º RealAbsInvar (output control) .......................................real-array Htuple . double *
Real parts of the normalized Fourier coefficients.
º ImaginaryAbsInvar (output control) ................................real-array Htuple . double *
Imaginary parts of the normalized Fourier coefficients.
Example
get_region_contour(single,&row,&col);
length_of_contour = length_tuple(row);
move_contour_orig(row,col,&trow,&tcol);
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,50,&frow,&fcol);
invar_fourier_coeff(frow,fcol,1,"affine_invar",&invrow,&invcol);
abs_invar_fourier_coeff(invrow,invcol,1,2,"az_invar1",&absrow,&abscol);
fourier_1dim_inv(absrow,abscol,length_of_contour,&fsynrow,&fsyncol);
Parallelization Information
T abs invar fourier coeff is reentrant and processed without parallelization.
T invar fourier coeff
Possible Predecessor Functions
Possible Successor Functions
T fourier 1dim inv, T match fourier coeff
Fourier descriptors
Module
T fourier 1dim ( Htuple Rows, Htuple Columns, Htuple ParContour,
Htuple MaxCoef, Htuple *RealCoef, Htuple *ImaginaryCoef )
Calculate the Fourier coefficients of a parameterized contour.
The operator T fourier 1dim calculates the Fourier coefficients of a parameterized contour by using a
valid parameter scale. This parameter scale may, for instance, be created with the help of the procedure
T prep contour fourier. This function serves to calculate the Fourier coefficients of closed contours which
are treated like complex-valued curves. Therefore, in order to determine the Fourier coefficients, the Fourier transform
for periodical functions is used. Hereby the parameter MaxCoef determines the ×ÓÐÙØÚÐÙ ·½of
the maximal number of Fourier coefficients, i.e. if Ò coefficients are indicated, the procedure will calculate coefficients
ranging from Ò to Ò. The contour will be approximated without loss, if Ò ÒÙÑÖÓØÓÒØÓÙÖÔÓÒØ×,
whereby Ò ½¼¼ approximates the contour so well that an error can hardly be distinguished; Ò ¾ ¼ ¼℄ however
is sufficient for most applications. If the parameter MaxCoef is set to 0, all coefficients will be determined.
Parameter
º Rows (input control) ..................................................contour.y-array Htuple . long
Row coordinates of the contour.
º Columns (input control) ..............................................contour.x-array Htuple . long
Colmumn coordinates of the contour.
º ParContour (input control) ............................................real-array Htuple . double
Parameter scale.
º MaxCoef (input control) .....................................................integer Htuple . long
Desired number of Fourier coefficients or all of them (0).
Default Value : 50
Value Suggestions : MaxCoef ¾0, 5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 150, 200, 400
Restriction : MaxCoef 0
º RealCoef (output control) ............................................real-array Htuple . double *
Real parts of the Fourier coefficients.
º ImaginaryCoef (output control) ......................................real-array Htuple . double *
Imaginary parts of the Fourier coefficients.
HALCON 6.0

720 CHAPTER 12. TOOLS
Example
get_region_contour(single,&row,&col);
move_contour_orig(row,col,&trow,&tcol);
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,&frow,&fcol);
invar_fourier_coeff(frow,fcol,1,"affine_invar",&invrow,&invcol);
abs_invar_fourier_coeff(invrow,invcol,1,2,"az_invar1",&absrow,&abscol);
Parallelization Information
T fourier 1dim is reentrant and processed without parallelization.
T prep contour fourier
Possible Predecessor Functions
Possible Successor Functions
T invar fourier coeff, disp polygon
Fourier descriptors
Module
T fourier 1dim inv ( Htuple RealCoef, Htuple ImaginaryCoef,
Htuple MaxCoef, Htuple *Rows, Htuple *Columns )
One dimensional Fourier synthesis (inverse Fourier transform).
Backtransformation of Fourier coefficients respectively of Fourier descriptors. The number of values to be backtransformed
should not exceed the length of the transformed contour.
Parameter
º RealCoef (input control) ...............................................real-array Htuple . double
Real parts.
º ImaginaryCoef (input control) ........................................real-array Htuple . double
Imaginary parts.
º MaxCoef (input control) .....................................................integer Htuple . long
Input of the steps for the backtransformation.
Default Value : 100
Value Suggestions : MaxCoef ¾5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 150, 200, 400
Restriction : MaxCoef 1
º Rows (output control) .............................................contour.y-array Htuple . double *
Row coordinates.
º Columns (output control) .........................................contour.x-array Htuple . double *
Column coordinates.
Example
get_region_contour(single,&row,&col);
length_of_contour = row.Num();
move_contour_orig(row,col,&trow,&tcol);
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,50,&frow,&fcol);
invar_fourier_coeff(frow,fcol,1,"affine_invar",&invrow,&invcol);
abs_invar_fourier_coeff(invrow,invcol,1,2,"az_invar1",&absrow,&abscol);
fourier_1dim_inv(absrow,abscol,length_of_contour,&fsynrow,&fsyncol);
Parallelization Information
T fourier 1dim inv is reentrant and processed without parallelization.
Possible Predecessor Functions
T invar fourier coeff, T fourier 1dim
HALCON/C Reference Manual / 2000-11-15

12.5. FOURIER-DESCRIPTOR 721
disp polygon
Fourier descriptors
Possible Successor Functions
Module
T invar fourier coeff ( Htuple RealCoef, Htuple ImaginaryCoef,
Htuple NormPar, Htuple InvarType, Htuple *RealInvar,
Htuple *ImaginaryInvar )
Normalize the Fourier coefficients.
Elimination of affine information from the Fourier coefficients, determination of affine invariants. The Fourier
coefficients will be normalized suitably so that all affine correlated contours will be projected to one and the same
contour. The following levels of affine mappings are available:
1. Translations (InvarType =’translinvar’)
2. + Rotations (InvarType = ’congr invar’)
3. + Scalings (InvarType =’similinvar’)
4. + Slanting (InvarType =’affineinvar’)
The control parameter InvarType indicates up to which level the affine representation shall be normalized.
Please note that indicating a certain level implies that the normalizing is executed with regard to all levels below.
For most applications a subsequent normalizing of the starting point is recommended!
Parameter
º RealCoef (input control) ...............................................real-array Htuple . double
Real parts of the Fourier coefficients.
º ImaginaryCoef (input control) ........................................real-array Htuple . double
Imaginary parts of the Fourier coefficients.
º NormPar (input control) .....................................................integer Htuple . long
Input of the normalizing coefficients.
Default Value : 1
Value Suggestions : NormPar ¾1, 2
Restriction : NormPar 1
º InvarType (input control) .............................................string Htuple . const char *
Indicates the level of the affine mappings.
Default Value : ’affine invar’
Value List : InvarType ¾’affine invar’, ’simil invar’, ’congr invar’, ’transl invar’
º RealInvar (output control) ...........................................real-array Htuple . double *
Real parts of the normalized Fourier coefficients.
º ImaginaryInvar (output control) ....................................real-array Htuple . double *
Imaginary parts of the normalized Fourier coefficients.
Example
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,&frow,&fcol);
invar_fourier_coeff(frow,fcol,1,"affine_invar",&invrow,&invcol);
abs_invar_fourier_coeff(invrow,invcol,1,2,"az_invar1",&absrow,&abscol);
Parallelization Information
T invar fourier coeff is reentrant and processed without parallelization.
T fourier 1dim
T invar fourier coeff
Fourier descriptors
Possible Predecessor Functions
Possible Successor Functions
Module
HALCON 6.0

722 CHAPTER 12. TOOLS
T match fourier coeff ( Htuple RealCoef1, Htuple ImaginaryCoef1,
Htuple RealCoef2, Htuple ImaginaryCoef2, Htuple MaxCoef, Htuple Damping,
Htuple *Distance )
Similarity of two contours.
The operator T match fourier coeff calculates the Euclidean distance between two contours which are
available as Fourier coefficients. In order to avoid that the higher frequencies are in some way too dominant, the
following attenuation can be used:
none: No attenuation.
1/index: Absolute amounts of the Fourier coefficients will be divided by their index.
1/(index*index): Absolute amounts of the Fourier coefficients will be divided by their square index.
The higher the result value, the greater the differences between the pattern and the test contour. If the number of
coefficients is not the same, only the first Ò coefficients will be compared. The parameter MaxCoef indicates the
number of the coefficients to be compared. If MaxCoef is set to zero, all coefficients will be used.
Parameter
º RealCoef1 (input control) ..............................................real-array Htuple . double
Real parts of the pattern Fourier coefficients.
º ImaginaryCoef1 (input control) .......................................real-array Htuple . double
Imaginary parts of the pattern Fourier coefficients.
º RealCoef2 (input control) ..............................................real-array Htuple . double
Real parts of the Fourier coefficients to be compared.
º ImaginaryCoef2 (input control) .......................................real-array Htuple . double
Imaginary parts of the Fourier coefficients to be compared.
º MaxCoef (input control) .....................................................integer Htuple . long
Total number of Fourier coefficients.
Default Value : 50
Value Suggestions : MaxCoef ¾0, 5, 10, 15, 20, 30, 40, 50, 70, 100, 200, 400
Restriction : MaxCoef 0
º Damping (input control) ...............................................string Htuple . const char *
Kind of attenuation.
Default Value : ”1/index”
Value Suggestions : Damping ¾’none’, ”1/index”, ”1/(index*index)”
º Distance (output control) ..................................................real Htuple . double *
Similarity of the contours.
Example
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,50,&frow,&fcol);
invar_fourier_coeff(frow,fcol,1,"affine_invar",&invrow,&invcol);
abs_invar_fourier_coeff(invrow,invcol,1,2,
"az_invar1",&absrow,&abscol);
match_fourier_coeff(contur1_row, contur1_col,
contur2_row, contur2_col, 50,
"1/index", &Distance_wert);
Parallelization Information
T match fourier coeff is reentrant and processed without parallelization.
T invar fourier coeff
Fourier descriptors
Possible Predecessor Functions
Module
HALCON/C Reference Manual / 2000-11-15

12.5. FOURIER-DESCRIPTOR 723
T move contour orig ( Htuple Rows, Htuple Columns, Htuple *RowsMoved,
Htuple *ColumnsMoved )
Transformation of the origin into the centre of gravity.
The operator T move contour orig relocates the input contour so that the origin lies in the centre of gravity.
Parameter
º Rows (input control) ..................................................contour.y-array Htuple . long
Row coordinates of the contour.
º Columns (input control) ..............................................contour.x-array Htuple . long
Column coordinates of the contour.
º RowsMoved (output control) ........................................contour.y-array Htuple . long *
Row coordinates of the displaced contour.
º ColumnsMoved (output control) ....................................contour.x-array Htuple . long *
Column coordinates of the displaced contour.
Parallelization Information
T move contour orig is processed completely exclusively without parallelization.
get region contour
T prep contour fourier
Fourier descriptors
Possible Predecessor Functions
Possible Successor Functions
Module
T prep contour fourier ( Htuple Rows, Htuple Columns, Htuple TransMode,
Htuple *ParContour )
Parameterize the passed contour.
The operator T prep contour fourier parameterizes the transmitted contour in order to prepare it for the
one dimensional Fourier transformation. Hereby the contour must be available in closed form. Three parameter
functions are available for the control parameter TransMode:
arc: Parameterization by the radian.
signed area: Parameterization by the signed area.
unsigned area: Parameterization by the absolute area.
Please note that in contrast to the signed or unsigned area the affine mapping of the radian will not be transformed
linearly.
Parameter
º Rows (input control) ..................................................contour.y-array Htuple . long
Row indices of the contour.
º Columns (input control) ..............................................contour.x-array Htuple . long
Column indices of the contour.
º TransMode (input control) .............................................string Htuple . const char *
Kind of parameterization.
Default Value : ’signed area’
Value Suggestions : TransMode ¾’arc’, ’unsigned area’, ’signed area’
º ParContour (output control) ..........................................real-array Htuple . double *
Parameterized contour.
Example
get_region_contour(single,&row,&col);
move_contour_orig(row,col,&trow,&tcol);
prep_contour_fourier(trow,tcol,"unsigned_area",&param_scale);
fourier_1dim(trow,tcol,param_scale,&frow,&fcol);
HALCON 6.0

724 CHAPTER 12. TOOLS
Parallelization Information
T prep contour fourier is reentrant and processed without parallelization.
T move contour orig
T fourier 1dim
Fourier descriptors
Possible Predecessor Functions
Possible Successor Functions
Module
12.6 Function
T abs funct 1d ( Htuple Function, Htuple *FunctionAbsolute )
Absolute value of the y values.
T abs funct 1d calculates the absolute values of all y values of Function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º FunctionAbsolute (output control) ...................function 1d-array Htuple . double * / long *
Function with the absolute values of the y values.
Parallelization Information
T abs funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T create funct 1d array ( Htuple YValues, Htuple *Function )
Create a function from a sequence of y-values.
T create funct 1d array creates a one-dimensional function from a set of y-values YValues. The resulting
function can then be processed and analyzed with the operators for 1d functions. YValues is interpreted as
follows: the first value of YValues is the function value at zero, the second value is the function value at one, etc.
Thus, the values define a function at equidistant x values (with distance 1), starting at 0.
Alternatively, the operator T create funct 1d pairs can be used to create a function.
T create funct 1d pairs also allows to define a function with non-equidistant x valus by specifiying
them explicitely. Thus to get the same definition as with T create funct 1d array, one would pass a tuple
of x values to T create funct 1d pairs that has the same length as YValues and contains values starting
at 0 and increasing by 1 in each position. Note, however, that T create funct 1d pairs leads to a different
internal representation of the function which needs more storage (because all (x,y) pairs are stored) and sometimes
cannot be processed as efficiently as functions created by T create funct 1d array.
Parameter
º YValues (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double / long
X value for function points.
º Function (output control) ..............................function 1d-array Htuple . double * / long *
Created function.
Parallelization Information
T create funct 1d array is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

12.6. FUNCTION 725
Possible Successor Functions
T write funct 1d, gnuplot plot funct 1d, T y range funct 1d, T get pair funct 1d,
T transform funct 1d
Alternatives
T create funct 1d pairs, (T )read funct 1d
T funct 1d to pairs
Tools
See Also
Module
T create funct 1d pairs ( Htuple XValues, Htuple YValues,
Htuple *Function )
Create a function from a set of (x,y) pairs.
T create funct 1d pairs creates a one-dimensional function from a set of pairs of (x,y) values. The
XValues of the functions have to be passed in ascending order. The resulting function can then be processed
and analyzed with the operators for 1d functions.
Alternatively, functions can be created with the operator T create funct 1d array. In contrast to this operator,
x values with arbitrary positions can be specified with T create funct 1d pairs. Hence, it is the more
general operator. It should be noted, however, that because of this generality the processing of a function created
with T create funct 1d pairs cannot be carried out as efficiently as for equidistant functions. In particular,
not all operators accept such functions. If necessary, a function can be transformed into an equidistant function
with the operator T sample funct 1d.
Parameter
º XValues (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double / long
X value for function points.
º YValues (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double / long
Y-value for function points.
º Function (output control) ..............................function 1d-array Htuple . double * / long *
Created function.
Parallelization Information
T create funct 1d pairs is reentrant and processed without parallelization.
Possible Successor Functions
T write funct 1d, gnuplot plot funct 1d, T y range funct 1d, T get pair funct 1d
Alternatives
T create funct 1d array, (T )read funct 1d
T funct 1d to pairs
Tools
See Also
Module
T distance funct 1d ( Htuple Function1, Htuple Function2, Htuple Mode,
Htuple Sigma, Htuple *Distance )
Compute the distance of two functions.
T distance funct 1d calculates the distance of two functions. The two functions may differ in length.
Parameter
º Function1 (input control) ................................function 1d-array Htuple . double / long
Input function 1.
º Function2 (input control) ................................function 1d-array Htuple . double / long
Input function 2.
HALCON 6.0

726 CHAPTER 12. TOOLS
º Mode (input control) .............................................string(-array) Htuple . const char *
Modes of invariants.
Default Value : ’length’
Value List : Mode ¾’length’, ’mean’
º Sigma (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double
Variance of the optional smoothing with a Gaussian filter.
Default Value : 0.0
Value Suggestions : Sigma ¾0.0, 0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 7.0, 10.0, 15.0, 20.0, 25.0, 30.0, 40.0,
50.0
º Distance (output control) .....................................real-array Htuple . double * / long *
Distance of the functions.
Parallelization Information
T distance funct 1d is reentrant and processed without parallelization.
Tools
Module
T funct 1d to pairs ( Htuple Function, Htuple *XValues,
Htuple *YValues )
Access to the x/y values of a function.
T funct 1d to pairs splits the input function Function into tuples for the x and y values.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º XValues (output control) ...................................number-array Htuple . double * / long *
X values of the function.
º YValues (output control) ...................................number-array Htuple . double * / long *
Y values of the function.
Parallelization Information
T funct 1d to pairs is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T get pair funct 1d ( Htuple Function, Htuple Index, Htuple *X,
Htuple *Y )
Access a function value using the index of the control points.
T get pair funct 1d accesses a function value of Function. This is done by specifying the index of one or
more control points of the function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º Index (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) Htuple . long
Index of the control points.
º X (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double *
X value at the given control points.
º Y (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) Htuple . double *
Y value at the given control points.
HALCON/C Reference Manual / 2000-11-15

12.6. FUNCTION 727
Parallelization Information
T get pair funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T integrate funct 1d ( Htuple Function, Htuple *Positive,
Htuple *Negative )
Compute the positive and negative areas of a function.
T integrate funct 1d integrates the function Function (see T create funct 1d array and
T create funct 1d pairs) and returns the integral of the positive and negative parts of the function in
Positive and Negative, respectively. Hence, the integral of the function is the difference Positive -
Negative. The integration is done on the interval on which the function is defined. For the integration, the
function is interpolated linearly.
Parameter
º Function (input control) ........................................function 1d-array Htuple . double
Input function.
º Positive (output control) ..............................................number Htuple . double *
Area under the positive part of the function.
º Negative (output control) .........................................number-array Htuple . double *
Area under the negative part of the function.
Parallelization Information
T integrate funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
See Also
T create funct 1d array, T create funct 1d pairs
Tools
Module
T match funct 1d trans ( Htuple Function1, Htuple Function2,
Htuple Border, Htuple ParamsConst, Htuple UseParams, Htuple *Params,
Htuple *ChiSquare, Htuple *Covar )
Calculate transformation parameters between two functions.
T match funct 1d trans calculates the transformation parameters between two functions given as the tuples
Function1 and Function2 (see T create funct 1d array und T create funct 1d pairs). The
following model is used for the transformation between the two functions:
Ý ½´Üµ ½ Ý ¾´ ¿ Ü · µ· ¾
The transformation parameters are determined by a least-squares minimization of the following function:
Ò
½
¼
Ý ½´Ü µ ½ Ý ¾´ ¿ Ü · µ· ¾
¡ ¾
The values of the function Ý ¾ are obtained by linear interpolation. The parameter Border determines the values
of the function Function2 outside of its domain. For Border=’zero’ these values are set to 0, for
Border=’constant’ they are set to the corresponding value at the border, for Border=’mirror’ they are mirrored
HALCON 6.0

728 CHAPTER 12. TOOLS
at the border, and for Border=’cyclic’ they are continued cyclically. The calculated transformation parameters
are returned as a 4-tuple in Params. If some of the parameter values are known, the respective parameters can
be excluded from the least-squares adjustment by setting the corresponding value in the tuple UseParams to the
value ’false’. In this case, the tuple ParamsConst must contain the known value of the respective parameter. If
a parameter is used for the adjustment (UseParams = ’true’), the corresponding parameter in ParamsConst is
ignored. On output, T match funct 1d trans additionally returns the sum of the squared errors ChiSquare
of the resulting function, i.e., the function obtained by transforming the input function with the transformation parameters,
as well as the covariance matrix Covar of the transformation parameters Params. These parameters
can be used to decide whether a successful matching of the functions was possible.
Parameter
º Function1 (input control) ................................function 1d-array Htuple . double / long
Function 1.
º Function2 (input control) ................................function 1d-array Htuple . double / long
Function 2.
º Border (input control) .................................................string Htuple . const char *
Border treatment for function 2.
Default Value : ’constant’
Value List : Border ¾’zero’, ’constant’, ’mirror’, ’cyclic’
º ParamsConst (input control) ........................................number-array Htuple . double
Values of the parameters to remain constant.
Default Value : ’[1.0,0.0,1.0,0.0]’
Parameter Number : 4
º UseParams (input control) .......................................string-array Htuple . const char *
Should a parameter be adapted for it?
Default Value : ’[’true’,’true’,’true’,’true’]’
Value List : UseParams ¾’true’, ’false’
Parameter Number : 4
º Params (output control) ............................................number-array Htuple . double *
Transformation parameters between the functions.
Parameter Number : 4
º ChiSquare (output control) .............................................number Htuple . double *
Quadratic error of the output function.
º Covar (output control) .............................................number-array Htuple . double *
Covariance Matrix of the transformation parameters.
Parameter Number : 16
Parallelization Information
T match funct 1d trans is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d array, T create funct 1d pairs
gray projections
Tools
See Also
Module
T negate funct 1d ( Htuple Function, Htuple *FunctionInverted )
Negation of the y values.
T negate funct 1d negates all y values of Function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º FunctionInverted (output control) ...................function 1d-array Htuple . double * / long *
Function with the negated y values.
HALCON/C Reference Manual / 2000-11-15

12.6. FUNCTION 729
Parallelization Information
T negate funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T num points funct 1d ( Htuple Function, Htuple *Length )
Number of control points of the function.
T num points funct 1d calculates the number of control points of Function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º Length (output control) ....................................................integer Htuple . long *
Number of control points.
Parallelization Information
T num points funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
read funct 1d ( const char *FileName, double *Function )
T read funct 1d ( Htuple FileName, Htuple *Function )
Read a function from a file.
The operator (T )read funct 1d reads the contents of FileName and converts it into the function
Function. The file has be generated by T write funct 1d.
Parameter
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the file to be read.
º Function (output control) ...........................function 1d(-array) (Htuple .) double * / long *
Function from the file.
Result
If the parameters are correct the operator (T )read funct 1d returns the value H MSG TRUE. If the file could
not be opened (T )read funct 1d returns H MSG FAIL. Otherwise an exception handling is raised.
Parallelization Information
(T )read funct 1d is reentrant and processed without parallelization.
fread string, read tuple
Alternatives
See Also
T write funct 1d, gnuplot plot ctrl, write image, write region, open file
Basic operators
Module
HALCON 6.0

730 CHAPTER 12. TOOLS
T sample funct 1d ( Htuple Function, Htuple XMin, Htuple XMax,
Htuple XDist, Htuple Border, Htuple *SampledFunction )
Sample a function equidistantly in an interval.
T sample funct 1d samples the input function Function in the interval [XMin,XMax] at equidistant points
with the distance XDist. The last point lies in the interval if XMax-XMin is not an integer multiple of XDist. To
obtain the samples, the input function is interpolated linearly. The parameter Border determines the values of the
function Function outside of its domain. For Border=’zero’ these values are set to 0, for Border=’constant’
they are set to the corresponding value at the border, for Border=’mirror’ they are mirrored at the border, and
for Border=’cyclic’ they are continued cyclically.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º XMin (input control) ................................................number Htuple . double / long
Minimum x value of the output function.
º XMax (input control) ................................................number Htuple . double / long
Maximum x value of the output function.
Restriction : XMax XMin
º XDist (input control) ...............................................number Htuple . double / long
Distance of the samples.
Restriction : XDist 0
º Border (input control) .................................................string Htuple . const char *
Border treatment for the input function.
Default Value : ’constant’
Value List : Border ¾’zero’, ’constant’, ’mirror’, ’cyclic’
º SampledFunction (output control) ............................function 1d-array Htuple . double *
Sampled function.
Parallelization Information
T sample funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T transform funct 1d, T create funct 1d array, T create funct 1d pairs
Tools
Module
T scale y funct 1d ( Htuple Function, Htuple Mult, Htuple Add,
Htuple *FunctionScaled )
Multiplication and addition of the y values.
T scale y funct 1d multiplies and adds the y values of Function with the parameters Mult and Add.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º Mult (input control) .......................................................number Htuple . double
Factor for scaling of the y values.
Default Value : 2
Value Suggestions : Mult ¾0.1, 0.3, 0.5, 1, 2, 5, 10
º Add (input control) ........................................................number Htuple . double
Constant which is added to the y values.
Default Value : 0
Value Suggestions : Add ¾-10,-5,1,0,5,10
º FunctionScaled (output control) .....................function 1d-array Htuple . double * / long *
Transformed function.
HALCON/C Reference Manual / 2000-11-15

12.6. FUNCTION 731
Parallelization Information
T scale y funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T smooth funct 1d gauss ( Htuple Function, Htuple Sigma,
Htuple *SmoothedFunction )
Smooth an equidistant function with a Gaussian function.
The operator T smooth funct 1d gauss smooths a one-dimensional function with a Gaussian function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Function to be smoothed.
º Sigma (input control) .....................................................number Htuple . double
Sigma of the Gaussian function for the smoothing.
Default Value : 2.0
Value Suggestions : Sigma ¾0.5, 1.0, 2.0, 3.0, 4.0, 5.0
Typical Range of Values : 0.1 Sigma 50.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.2
º SmoothedFunction (output control) ..........................function 1d-array Htuple . double *
Smoothed function.
Parallelization Information
T smooth funct 1d gauss is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Possible Successor Functions
T match funct 1d trans, T distance funct 1d
Tools
Module
T smooth funct 1d mean ( Htuple Function, Htuple SmoothSize,
Htuple Iterations, Htuple *SmoothedFunction )
Smooth a 1D function by averaging its values.
The operator T smooth funct 1d mean smooths a one dimensional function by applying an average (mean)
filter multiple times.
Parameter
º Function (input control) ..................................function 1d-array Htuple . long / double
1D function.
º SmoothSize (input control) .................................................integer Htuple . long
Size of the averaging mask.
Default Value : 10
Value Suggestions : SmoothSize ¾1, 3, 5, 7, 9, 11, 13, 15, 21, 31, 51
Typical Range of Values : 1 SmoothSize 1000 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : SmoothSize 0
HALCON 6.0

732 CHAPTER 12. TOOLS
º Iterations (input control) .................................................integer Htuple . long
Number of iterations for the smoothing.
Default Value : 3
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9
Typical Range of Values : 1 Iterations 100 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Restriction : Iterations 1
º SmoothedFunction (output control) ..........................function 1d-array Htuple . double *
Smoothed function.
Parallelization Information
T smooth funct 1d mean is reentrant and processed without parallelization.
T create funct 1d array
T smooth funct 1d gauss
Tools
Possible Predecessor Functions
Alternatives
Module
T transform funct 1d ( Htuple Function, Htuple Params,
Htuple *TransformedFunction )
Transform a function using given transformation parameters.
T transform funct 1d transforms the input function Function using the transformation parameters
given in Params. The function Function is passed as a tuple (see T create funct 1d array und
T create funct 1d pairs). The following model is used for the transformation between the two functions
(see T match funct 1d trans):
Ý Ø´Üµ ½ Ý´ ¿ Ü · µ· ¾
The output function TransformedFunction is obtained by transforming the x and y values of the input function
separately with the above formula, i.e., the output function is not sampled again. To do so, the operator
T sample funct 1d can be used.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º Params (input control) ..............................................number-array Htuple . double
Transformation parameters between the functions.
Parameter Number : 4
º TransformedFunction (output control) ...............function 1d-array Htuple . double * / long *
Transformed function.
Parallelization Information
T transform funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array, T match funct 1d trans
Tools
Module
T write funct 1d ( Htuple Function, Htuple FileName )
Write a function to a file.
HALCON/C Reference Manual / 2000-11-15

12.6. FUNCTION 733
The operator T write funct 1d writes the contents of Function to a file. The data is written in an ASCII
format. Therefore, the file can be exchanged between different architectures. The data can be read by the operator
(T )read funct 1d. There is no specific extension for this kind of file.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Function to be written.
º FileName (input control) ...........................................filename Htuple . const char *
Name of the file to be written.
Result
If the parameters are correct the operator T write funct 1d returns the value H MSG TRUE. If the file could
not be opened T write funct 1d returns H MSG FAIL. Otherwise an exception handling is raised.
Parallelization Information
T write funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
write tuple, fwrite string
Alternatives
See Also
(T )read funct 1d, write image, write region, open file
Basic operators
Module
T x range funct 1d ( Htuple Function, Htuple *XMin, Htuple *XMax )
Smallest and largest x value of the function.
T x range funct 1d calculates the smallest and the largest x value of Function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º XMin (output control) ....................................................number Htuple . double *
Smallest x value.
º XMax (output control) ....................................................number Htuple . double *
Largest x value.
Parallelization Information
T x range funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
T y range funct 1d ( Htuple Function, Htuple *YMin, Htuple *YMax )
Smallest and largest y value of the function.
T y range funct 1d calculates the smallest and the largest y value of Function.
Parameter
º Function (input control) ..................................function 1d-array Htuple . double / long
Input function.
º YMin (output control) ....................................................number Htuple . double *
Smallest y value.
HALCON 6.0

734 CHAPTER 12. TOOLS
º YMax (output control) ....................................................number Htuple . double *
Largest y value.
Parallelization Information
T y range funct 1d is reentrant and processed without parallelization.
Possible Predecessor Functions
T create funct 1d pairs, T create funct 1d array
Tools
Module
12.7 Geometry
angle ll ( double RowA1, double ColumnA1, double RowA2, double ColumnA2,
double RowB1, double ColumnB1, double RowB2, double ColumnB2,
double *Angle )
T angle ll ( Htuple RowA1, Htuple ColumnA1, Htuple RowA2,
Htuple ColumnA2, Htuple RowB1, Htuple ColumnB1, Htuple RowB2,
Htuple ColumnB2, Htuple *Angle )
Calculate the angle between two lines.
The operator (T )angle ll calculates the angle between two lines. As input the rows and columns of the first
line (RowA1,ColumnA1, RowA2,ColumnA2) and of the second line (RowB1,ColumnB1, RowB2,ColumnB2)
are expected. The calculation in done as follows: We interpret the lines as vectors with starting points
RowA1,ColumnA1 and RowB1,ColumnB1 and end points RowA2,ColumnA2 and RowB2,ColumnB2, respectively.
Turning the vector counterclockwise onto the vector (the center of rotation is the intersection point of
the two lines) yields the angle. The result depends on the order of the points and on the order of the lines. The
parameter Angle returns the angle in radians. The angles range from ÒÐ .
Parameter
º RowA1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the first line.
º ColumnA1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the first line.
º RowA2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the first line.
º ColumnA2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the first line.
º RowB1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the second line.
º ColumnB1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the second line.
º RowB2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the second line.
º ColumnB2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the second line.
º Angle (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Angle between the lines.
Example
RowA1 := 255
ColumnA1 := 10
RowA2 := 255
ColumnA2 := 501
disp_line (WindowHandle, RowA1, ColumnA1, RowA2, ColumnA2)
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 735
RowB1 := 255
ColumnB1 := 255
for i := 1 to 360 by 1
RowB2 := 255 + sin(rad(i)) * 200
ColumnB2 := 255 + cos(rad(i)) * 200
disp_line (WindowHandle, RowB1, ColumnB1, RowB2, ColumnB2)
angle_ll (RowA1, ColumnA1, RowA2, ColumnA2,
RowB1, ColumnB1, RowB2, ColumnB2, Angle)
endfor
(T )angle ll returns H MSG TRUE.
Result
Parallelization Information
(T )angle ll is reentrant and processed without parallelization.
(T )angle lx
Basic operators
Alternatives
Module
angle lx ( double Row1, double Column1, double Row2, double Column2,
double *Angle )
T angle lx ( Htuple Row1, Htuple Column1, Htuple Row2, Htuple Column2,
Htuple *Angle )
Calculate the angle between one line and the vertical axis.
The operator (T )angle lx calculates the angle between one line and the abscissa. As input the row and column
of the line (Row1,Column1, Row2,Column2) are expected. The calculation in done as follows: We interprete
the line as a vector with starting point Row1,Column1 and end point Row2,Column2. Turning the vector counter
clockwise onto the abscissa (center of rotation is the intersection point of the abscissa) yields the angle. The result
is dependant on the order of points of line. The parameters Angle returns the angle in radians. The angles range
from ÒÐ .
Parameter
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º Angle (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Angle between the line and the abscissa.
Example
RowX1 := 255
ColumnX1 := 10
RowX2 := 255
ColumnX2 := 501
disp_line (WindowHandle, RowX1, ColumnX1, RowX2, ColumnX2)
Row1 := 255
Column1 := 255
for i := 1 to 360 by 1
Row2 := 255 + sin(rad(i)) * 200
HALCON 6.0

736 CHAPTER 12. TOOLS
Column2 := 255 + cos(rad(i)) * 200
disp_line (WindowHandle, Row1, Column1, Row2, Column2)
angle_lx (Row1, Column1, Row2, Column2, Angle)
endfor
(T )angle lx returns H MSG TRUE.
Result
Parallelization Information
(T )angle lx is reentrant and processed without parallelization.
(T )angle ll
Basic operators
Alternatives
Module
distance lr ( Hobject Region, double Row1, double Column1, double Row2,
double Column2, double *DistanceMin, double *DistanceMax )
T distance lr ( Hobject Region, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distance between one line and one region.
The operator (T )distance lr calculates the orthogonal distance between one line and one region. As input
the coordinates of 2 points that the line represent (Row1,Column1, Row2,Column2) and one region are expected.
The parameters DistanceMin and DistanceMax return the result of the calculation.
Attention
Due to efficiency of (T )distance lr holes are ignored. Furthermore, if the lines intersects the region a
minimal distance larger than 0.5 can be returned.
Parameter
º Region (input object) .............................................................region Hobject
Input region.
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the line and the region
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the line and the region
Example
dev_close_window ()
read_image (Image, ’fabrik’)
dev_open_window (0, 0, 512, 512, ’white’, WindowHandle)
threshold (Image, Region, 180, 255)
connection (Region, ConnectedRegions)
select_shape (ConnectedRegions, SelectedRegions, ’area’, ’and’,
5000, 100000000)
dev_clear_window ()
dev_set_color (’black’)
dev_display (SelectedRegions)
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 737
dev_set_color (’red’)
Row1 := 100
Row2 := 400
for Col := 50 to 400 by 4
disp_line (WindowHandle, Row1, Col+100, Row2, Col)
distance_lr (SelectedRegions, Row1, Col+100, Row2, Col,
DistanceMin, DistanceMax)
endfor
(T )distance lr returns H MSG TRUE.
Result
Parallelization Information
(T )distance lr is reentrant and processed without parallelization.
Alternatives
(T )distance pr, (T )distance sr, diameter region
See Also
hamming distance, select region point, test region point, smallest rectangle2
Basic operators
Module
distance pl ( double Row, double Column, double Row1, double Column1,
double Row2, double Column2, double *Distance )
T distance pl ( Htuple Row, Htuple Column, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple *Distance )
Calculate the distance between one point and one line.
The operator (T )distance pl calculates the orthogonal distance between a point (Row,Column) and a line,
given by two arbitrary points of the line. The result is passed in Distance.
Parameter
º Row (input control) ..........................................point.y(-array) (Htuple .) double / long
Row of the point.
º Column (input control) ......................................point.x(-array) (Htuple .) double / long
Column of the point.
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º Distance (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Distance between the points
Example
double row,column,row1,column1,row2,column2,distance;
draw_point(WindowHandle,&row,&column);
draw_line(WindowHandle,&row1,&column1,&row2,&column2);
distance_pl(row,column,row1,column1,row2,column2,&distance);
(T )distance pl returns H MSG TRUE.
Result
HALCON 6.0

738 CHAPTER 12. TOOLS
Parallelization Information
(T )distance pl is reentrant and processed without parallelization.
(T )distance ps
(T )distance pp, (T )distance pr
Basic operators
Alternatives
See Also
Module
distance pp ( double Row1, double Column1, double Row2, double Column2,
double *Distance )
T distance pp ( Htuple Row1, Htuple Column1, Htuple Row2,
Htuple Column2, Htuple *Distance )
Calculate the distance between two points.
The operator (T )distance pp calculates the distance between pairs of points according to the following formula:
Ô
×ØÒ ´´ÊÓÛ½ ÊÓÛ¾µ ¾ ·´ÓÐÙÑÒ½ ÓÐÙÑÒ¾µ ¾ µ
The result is passed in Distance.
Parameter
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point.
º Distance (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Distance between the points
Example
double
row1,column1,row2,column2,distance;
draw_point(WindowHandle,&row1,&column1);
draw_point(WindowHandle,&row2,&column2);
distance_pp(row1,column1,row2,column2,&distance);
(T )distance pp returns H MSG TRUE.
Result
Parallelization Information
(T )distance pp is reentrant and processed without parallelization.
(T )distance ps
(T )distance pl, (T )distance pr
Basic operators
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 739
distance pr ( Hobject Region, double Row, double Column,
double *DistanceMin, double *DistanceMax )
T distance pr ( Hobject Region, Htuple Row, Htuple Column,
Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distance between one point and one region.
The operator (T )distance pr calculates the distance between one point and one region. As input the column
und Row of the point (Row,Column) and one region are expected. If the pint is inside the region the minimal
distance is zero. The parameters DistanceMin and DistanceMax return the result of the calculation.
Parameter
º Region (input object) .............................................................region Hobject
Input region.
º Row (input control) ..........................................point.y(-array) (Htuple .) double / long
Row of the point.
º Column (input control) ......................................point.x(-array) (Htuple .) double / long
Column of the point.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the point and the region
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the point and the region
Example
dev_close_window ()
read_image (Image, ’mreut’)
dev_open_window (0, 0, 512, 512, ’white’, WindowHandle)
dev_set_color (’black’)
threshold (Image, Region, 180, 255)
connection (Region, ConnectedRegions)
select_shape (ConnectedRegions, SelectedRegions, ’area’, ’and’,
10000, 100000000)
Row1 := 255
Column1 := 255
dev_clear_window ()
dev_display (SelectedRegions)
dev_set_color (’red’)
for i := 1 to 360 by 1
Row2 := 255 + sin(rad(i)) * 200
Column2 := 255 + cos(rad(i)) * 200
disp_line (WindowHandle, Row1, Column1, Row2, Column2)
distance_pr (SelectedRegions, Row2, Column2,
DistanceMin, DistanceMax)
endfor
(T )distance pr returns H MSG TRUE.
Result
Parallelization Information
(T )distance pr is reentrant and processed without parallelization.
Alternatives
(T )distance lr, (T )distance sr, diameter region
See Also
hamming distance, select region point, test region point, smallest rectangle2
Basic operators
Module
HALCON 6.0

740 CHAPTER 12. TOOLS
distance ps ( double Row, double Column, double Row1, double Column1,
double Row2, double Column2, double *DistanceMin, double *DistanceMax )
T distance ps ( Htuple Row, Htuple Column, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distances between a point and a line segment.
The operator (T )distance ps calculates the minimal and maximal distance between a point (Row,Column)
and a line segment which is represented by the start point (Row1,Column1) and the end point (Row2,Column2).
DistanceMax is the maximal distance between the point and the end points of the line segment. DistanceMin
is identical to (T )distance pl in the case that the point is “between” the two endpoints. Otherwise the
minimal distance to one of the endpoints is used.
Parameter
º Row (input control) ..........................................point.y(-array) (Htuple .) double / long
Row of the first point.
º Column (input control) ......................................point.x(-array) (Htuple .) double / long
Column of the first point.
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line segment.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line segment.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line segment.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line segment.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the point and the line segment
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the point and the line segment
Example
double row,column,row1,column1,row2,column2;
double distance_min,distance_max;
distance_ps(row,column,row1,column1,row2,column2,
&distance_min,&distance_max);
(T )distance ps returns H MSG TRUE.
Result
Parallelization Information
(T )distance ps is reentrant and processed without parallelization.
(T )distance pl
(T )distance pp, (T )distance pr
Basic operators
Alternatives
See Also
Module
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 741
distance rr min ( Hobject Regions1, Hobject Regions2,
double *MinDistance, long *Row1, long *Column1, long *Row2,
long *Column2 )
T distance rr min ( Hobject Regions1, Hobject Regions2,
Htuple *MinDistance, Htuple *Row1, Htuple *Column1, Htuple *Row2,
Htuple *Column2 )
Minimum distance between the contour pixels of two regions each.
The operator (T )distance rr min calculates the minimum distance of pairs of regions. If several regions are
passed in Regions1 and Regions2 the distance between the contour pixels of each i-th element is calculated
and then forms the i-th entry in the output parameter MinDistance. The calculation is carried out by comparing
all contour pixels. The Euclidean distance is used. The parameters (Row1,Column1) and(Row2, Column2)
indicate the position on the contour of Regions1 and Regions2, respectively, the distance between which is
the minimum distance.
Attention
Each region must consist of exactly one connection component. Both input parameters must contain the same
number of regions. The regions must not be empty. If the regions overlap the distance is indicated as 0.0. In this
case the positions are not reliable.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º Regions2 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º MinDistance (output control) .....................................real(-array) (Htuple .) double *
Minimum distance between contours of the regions.
Assertion : 0 MinDistance
º Row1 (output control) ..............................................point.y(-array) (Htuple .) long *
Line index on contour in Regions1.
º Column1 (output control) ..........................................point.x(-array) (Htuple .) long *
Column index on contour in Regions1.
º Row2 (output control) ..............................................point.y(-array) (Htuple .) long *
Line index on contour in Regions2.
º Column2 (output control) ..........................................point.x(-array) (Htuple .) long *
Column index on contour in Regions2.
Complexity
If Æ ½,Æ ¾ are the lengths of the contours the runtime complexity is Ç´Æ ½ £ Æ ¾µ.
Result
The operator (T )distance rr min returns the value H MSG TRUE if the input is not empty. Otherwise an
exception handling is raised.
Parallelization Information
(T )distance rr min is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
(T )distance rr min dil, dilation1, intersection
Region processing
Module
HALCON 6.0

742 CHAPTER 12. TOOLS
distance rr min dil ( Hobject Regions1, Hobject Regions2,
long *MinDistance )
T distance rr min dil ( Hobject Regions1, Hobject Regions2,
Htuple *MinDistance )
Minimum distance between two regions with the help of dilatation.
The operator (T )distance rr min dil calculates the minimum distance between pairs of regions. If several
regions are passed in Regions1 and Regions2 the distance between the i-th elements in each case is calculated.
It then forms the i-th entry in the output parameter MinDistance. The calculation is carried out with the help of
dilatation with the Golay element ’h’. The result is:
ÆÙÑÖØÖØÓÒ× £ ¾ ½
.
The mask ’h’ has the effect that precisely the maximum metrics are calculated.
Attention
Both parameters must contain the same number of regions. The regions must not be empty.
Parameter
º Regions1 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º Regions2 (input object) ...................................................region(-array) Hobject
Regions to be examined.
º MinDistance (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Minimum distances of the regions.
Assertion : -1 MinDistance
Result
The operator (T )distance rr min dil returns the value H MSG TRUE if the input is not empty. Otherwise
an exception handling is raised.
Parallelization Information
(T )distance rr min dil is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, regiongrowing, connection
Alternatives
(T )distance rr min, dilation1, intersection
Region processing
Module
distance sl ( double RowA1, double ColumnA1, double RowA2,
double ColumnA2, double RowB1, double ColumnB1, double RowB2,
double ColumnB2, double *DistanceMin, double *DistanceMax )
T distance sl ( Htuple RowA1, Htuple ColumnA1, Htuple RowA2,
Htuple ColumnA2, Htuple RowB1, Htuple ColumnB1, Htuple RowB2,
Htuple ColumnB2, Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distances between one line segment and one line.
The operator (T )distance sl calculates the minimal and maximal orthogonal distance between one line segment
and one line. As input the columns and rows of the line segment (RowA1,ColumnA1,RowA2,ColumnA2)
and of the line (RowB1,ColumnB1,RowB2,ColumnB2) are expected. The parameters DistanceMin and
DistanceMax return the result of the calculation. If the line segments are intersecting DistanceMin returns
zero.
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 743
Parameter
º RowA1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the line segment.
º ColumnA1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the line segment.
º RowA2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the line segment.
º ColumnA2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the line segment.
º RowB1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º ColumnB1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º RowB2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º ColumnB2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the line segment and the line
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the line segment and the line
Example
create_tuple(&RowA1, 1);
set_i(RowA1, 8, 0);
create_tuple(&ColumnA1, 1);
set_i(ColumnA1, 7, 0);
create_tuple(&RowA2, 1);
set_i(RowA2, 15, 0);
create_tuple(&ColumnA2, 1);
set_i(ColumnA2, 11, 0);
create_tuple(&RowB1, 1);
set_i(RowB1, 2, 0);
create_tuple(&ColumnB1, 1);
set_i(ColumnB1, 4, 0);
create_tuple(&RowB2, 1);
set_i(RowB2, 6, 0);
create_tuple(&ColumnB2, 1);
set_i(ColumnB2, 10, 0);
T_distance_sl(RowA1,ColumnA1,RowA2,ColumnA2,RowB1,ColumnB1,RowB2,ColumnB2,
&distance_min,&distance_max);
aa_min = get_d(distance_min,0);
aa_max = get_d(distance_max,0);
(T )distance sl returns H MSG TRUE.
Result
Parallelization Information
(T )distance sl is reentrant and processed without parallelization.
(T )distance pl
(T )distance ps, (T )distance pp
Basic operators
Alternatives
See Also
Module
HALCON 6.0

744 CHAPTER 12. TOOLS
distance sr ( Hobject Region, double Row1, double Column1, double Row2,
double Column2, double *DistanceMin, double *DistanceMax )
T distance sr ( Hobject Region, Htuple Row1, Htuple Column1,
Htuple Row2, Htuple Column2, Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distance between one line segment and one region.
The operator (T )distance sr calculates the distance between one line segment and one region. Row1,
Column1, Row2, Column2 are the the initial and end coordinates of the line segment. The parameters
DistanceMin and DistanceMax contain the resulting distances.
Attention
Due to efficiency of (T )distance sr holes are ignored. Furthermore, if the lines intersects the region a
minimal distance larger than 0.5 can be returned.
Parameter
º Region (input object) .............................................................region Hobject
Input region.
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line segment.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line segment.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line segment.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line segment.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the line segment and the region
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the line segment and the region
Example
threshold(Image, &Region, 0.0, 120.0);
distance_sr(Region,row1,column1,row2,column2
&distance_min, &distance_max);
(T )distance sr returns H MSG TRUE.
Result
Parallelization Information
(T )distance sr is reentrant and processed without parallelization.
Alternatives
(T )distance lr, (T )distance pr, diameter region
See Also
hamming distance, select region point, test region point, smallest rectangle2
Basic operators
Module
distance ss ( double RowA1, double ColumnA1, double RowA2,
double ColumnA2, double RowB1, double ColumnB1, double RowB2,
double ColumnB2, double *DistanceMin, double *DistanceMax )
T distance ss ( Htuple RowA1, Htuple ColumnA1, Htuple RowA2,
Htuple ColumnA2, Htuple RowB1, Htuple ColumnB1, Htuple RowB2,
Htuple ColumnB2, Htuple *DistanceMin, Htuple *DistanceMax )
Calculate the distances between two line segments.
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 745
The operator (T )distance ss calculates the minimal and maximal distance between two line segments.
As input the rows and columns of the first line segments (RowA1,ColumnA1, RowA2,ColumnA2) and of the
second line segment (RowB1,ColumnB1,RowB2,ColumnB2) are used. The parameters DistanceMin and
DistanceMax return the result of the calculation. If the line segments are intersecting DistanceMin returns
zero.
Parameter
º RowA1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the line segment.
º ColumnA1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the line segment.
º RowA2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the line segment.
º ColumnA2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the line segment.
º RowB1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º ColumnB1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º RowB2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º ColumnB2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º DistanceMin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Minimal distance between the line segments
º DistanceMax (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Maximal distance between the line segments
Example
create_tuple(&RowA1, 1);
set_i(RowA1, 8, 0);
create_tuple(&ColumnA1, 1);
set_i(ColumnA1, 7, 0);
create_tuple(&RowA2, 1);
set_i(RowA2, 15, 0);
create_tuple(&ColumnA2, 1);
set_i(ColumnA2, 11, 0);
create_tuple(&RowB1, 1);
set_i(RowB1, 2, 0);
create_tuple(&ColumnB1, 1);
set_i(ColumnB1, 4, 0);
create_tuple(&RowB2, 1);
set_i(RowB2, 6, 0);
create_tuple(&ColumnB2, 1);
set_i(ColumnB2, 10, 0);
T_distance_ss(RowA1,ColumnA1,RowA2,ColumnA2,RowB1,ColumnB1,RowB2,ColumnB2,
&distance_min,&distance_max);
aa_min = get_d(distance_min,0);
aa_max = get_d(distance_max,0);
(T )distance ss returns H MSG TRUE.
Result
Parallelization Information
(T )distance ss is reentrant and processed without parallelization.
(T )distance pp
Alternatives
HALCON 6.0

746 CHAPTER 12. TOOLS
(T )distance pl, (T )distance ps
Basic operators
See Also
Module
get points ellipse ( double Angle, double Row, double Column,
double Phi, double Radius1, double Radius2, double *RowPoint,
double *ColPoint )
T get points ellipse ( Htuple Angle, Htuple Row, Htuple Column,
Htuple Phi, Htuple Radius1, Htuple Radius2, Htuple *RowPoint,
Htuple *ColPoint )
Points of an ellipse corresponding to specific angles.
(T )get points ellipse returns the points (RowPoint,ColPoint) on the specified ellipse corresponding
to the angles in Angle, which refer to the main axis of the ellipse. The ellipse itself is characterized by the center
(Row, Column), the orientation of the main axis Phi, the length of the larger half axis Radius1, and the length
of the smaller half axis Radius2.
Parameter
º Angle (input control) ................................................real(-array) (Htuple .) double
Angles corresponding to the resulting points [rad].
Default Value : 0
Restriction : ´Angle 0µ ´Angle 6.283185307µ
º Row (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y (Htuple .) double
Row coordinate of the center of the ellipse.
º Column (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.center.x (Htuple .) double
Column coordinate of the center of the ellipse.
º Phi (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad (Htuple .) double
Orientation of the main axis [rad].
Restriction : ´Phi 0µ ´Phi 6.283185307µ
º Radius1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1 (Htuple .) double
Length of the larger half axis.
Restriction : Radius1 0
º Radius2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2 (Htuple .) double
Length of the smaller half axis.
Restriction : Radius2 0
º RowPoint (output control) ....................................point.row(-array) (Htuple .) double *
Row coordinates of the points on the ellipse.
º ColPoint (output control) .................................point.column(-array) (Htuple .) double *
Column coordinates of the points on the ellipse.
Example
draw_ellipse(WindowHandle,Row,Column,Phi,Radius1,Radius2)
get_points_ellipse([0,3.14],Row,Column,Phi,Radius1,Radius2,RowPoint,ColPoint)
Result
(T )get points ellipse returns H MSG TRUE if all parameter values are correct. If necessary, an exception
is raised.
Parallelization Information
(T )get points ellipse is reentrant and processed without parallelization.
Possible Predecessor Functions
fit ellipse contour xld, draw ellipse, gen ellipse contour xld
gen ellipse contour xld
See Also
HALCON/C Reference Manual / 2000-11-15

12.7. GEOMETRY 747
Basic operators
Module
intersection ll ( double RowA1, double ColumnA1, double RowA2,
double ColumnA2, double RowB1, double ColumnB1, double RowB2,
double ColumnB2, double *Row, double *Column, long *IsParallel )
T intersection ll ( Htuple RowA1, Htuple ColumnA1, Htuple RowA2,
Htuple ColumnA2, Htuple RowB1, Htuple ColumnB1, Htuple RowB2,
Htuple ColumnB2, Htuple *Row, Htuple *Column, Htuple *IsParallel )
Calculate the intersection point of two lines.
The operator (T )intersection ll calculates the intersection point of two lines. As input the columns
and rows of the lines (RowA1,ColumnA1, RowA2,ColumnA2) and(RowB1,ColumnB1, RowB2,ColumnB2)
are expected. The parameters Row and Column return the result of the calculation. If the lines are parallel
IsParallel is 1 else 0. In addition the values of Row and Column are undefined.
Attention
If the lines are parallel the values of Row and Column are undefined.
Parameter
º RowA1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the first line.
º ColumnA1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the first line.
º RowA2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the first line.
º ColumnA2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the first line.
º RowB1 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the first point of the second line.
º ColumnB1 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the first point of the second line.
º RowB2 (input control) .......................................point.y(-array) (Htuple .) double / long
Row of the second point of the second line.
º ColumnB2 (input control) ...................................point.x(-array) (Htuple .) double / long
Column of the second point of the second line.
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row of the intersection point
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column of the intersection point
º IsParallel (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long *
Are the two lines parallel?
create_tuple(&rowA1, 1);
set_i(rowA1, 8, 0);
create_tuple(&columnA1, 1);
set_i(columnA1, 7, 0);
create_tuple(&rowA2, 1);
set_i(rowA2, 15, 0);
create_tuple(&columnA2, 1);
set_i(columnA2, 11, 0);
create_tuple(&RowB1, 1);
set_i(RowB1, 2, 0);
create_tuple(&ColumnB1, 1);
Example
HALCON 6.0

748 CHAPTER 12. TOOLS
set_i(ColumnB1, 4, 0);
create_tuple(&RowB2, 1);
set_i(RowB2, 6, 0);
create_tuple(&ColumnB2, 1);
set_i(ColumnB2, 10, 0);
T_intersection_ll(rowA1,columnA1,rowA2,columnA2,RowB1,ColumnB1,RowB2,ColumnB2,
&row_i,&column_i,&parallel);
aa_min = get_d(row_i,0);
aa_max = get_d(column_i,0);
(T )intersection ll returns H MSG TRUE.
Result
Parallelization Information
(T )intersection ll is reentrant and processed without parallelization.
Basic operators
Module
projection pl ( double Row, double Column, double Row1, double Column1,
double Row2, double Column2, double *RowProj, double *ColProj )
T projection pl ( Htuple Row, Htuple Column, Htuple Row1,
Htuple Column1, Htuple Row2, Htuple Column2, Htuple *RowProj,
Htuple *ColProj )
Calculate the projection of a point onto a line.
The operator (T )projection pl calculates the projection of a point (Row,Column) onto a line which is
represent by the start point (Row1,Column1) and the end point (Row2,Column2). RowProj is the row of the
projection point and ColProj is the column of the projection point.
Parameter
º Row (input control) ..........................................point.y(-array) (Htuple .) double / long
Row of the point.
º Column (input control) ......................................point.x(-array) (Htuple .) double / long
Column of the point.
º Row1 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the first point of the line.
º Column1 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the first point of the line.
º Row2 (input control) ........................................point.y(-array) (Htuple .) double / long
Row of the second point of the line.
º Column2 (input control) ....................................point.x(-array) (Htuple .) double / long
Column of the second point of the line.
º RowProj (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Row of the projection
º ColProj (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Column of the projection
Example
projection_pl(row,column,row1,column1,row2,column2,
&row_proj,&col_proj);
(T )projection pl returns H MSG TRUE.
Result
Parallelization Information
(T )projection pl is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

12.8. HOUGH 749
Basic operators
Module
12.8 Hough
hough circle trans ( Hobject Region, Hobject *HoughImage, long Radius )
T hough circle trans ( Hobject Region, Hobject *HoughImage,
Htuple Radius )
Return the Hough-Transform for circles with a given radius.
The operator (T )hough circle trans calculates the Hough transform for circles with a certain Radius
in the regions passed by Region. Hereby the centres of all possible circles in the parameter space (the Hough
or accumulator space respectively) will be accumulated for each point in the image space. Circle hypotheses
supported by many points in the input region thereby generate a maximum in the area showing the circle’s centre
in the output image (HoughImage). The circles’ centres in the image space can be deduced from the coordinates
of these maximums by subtracting the Radius. If more than one radius is transmitted, all Hough images will be
shifted according to the maximal radius.
Parameter
º Region (input object) .............................................................region Hobject
Binary edge image in which the circles are to be detected.
º HoughImage (output object) ........................................image(-array) Hobject * :int2
Hough transform for circles with a given radius.
Parameter Number : HoughImage Radius
º Radius (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Radius of the circle to be searched in the image.
Default Value : 12
Typical Range of Values : 3 Radius (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : ´1 Radiusµ 500
Result
The operator (T )hough circle trans returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )hough circle trans is reentrant and processed without parallelization.
Region processing
Module
hough circles ( Hobject RegionIn, Hobject *RegionOut, long Radius,
long Percent, long Mode )
T hough circles ( Hobject RegionIn, Hobject *RegionOut, Htuple Radius,
Htuple Percent, Htuple Mode )
Centres of circles for a specific radius.
(T )hough circle trans detects the centres of circles in regions with the help of the Hough transform for
circles with a specific radius.
HALCON 6.0

750 CHAPTER 12. TOOLS
Parameter
º RegionIn (input object) ..........................................................region Hobject
Binary edge image in which the circles are to be detected.
º RegionOut (output object) ...............................................region(-array) Hobject *
Centres of those circles which are included in the edge image by Percent percent.
Parameter Number : RegionOut ´´Radius ¡ Percentµ ¡ Modeµ
º Radius (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Radius of the circle to be searched in the image.
Default Value : 12
Typical Range of Values : 2 Radius 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parameter Number : ´1 Radiusµ 500
º Percent (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Indicates the percentage (approximately) of the (ideal) circle which must be present in the edge image
RegionIn.
Default Value : 60
Typical Range of Values : 10 Percent 100 (lin)
Minimal Value Step : 1
Recommended Value Step : 5
Parameter Number : ´1 Percentµ 100
º Mode (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
The modus defines the position of the circle in question:
0 - the radius is equivalent to the outer border of the set pixels.
1 - the radius is equivalent to the centres of the circle lines pixels.
2 - both 0 and 1 (a little more fuzzy, but more reliable in contrast to circles set slightly differently, necessitates
50 % more processing capacity compared to 0 or 1 alone).
Value List : Mode ¾0, 1, 2
Parameter Number : ´1 Modeµ 3
Result
The operator (T )hough circles returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
(T )hough circles is reentrant and processed without parallelization.
Region processing
Module
hough line trans ( Hobject Region, Hobject *HoughImage,
long AngleResolution )
Produce the Hough transform for lines within regions.
The operator hough line trans calculates the Hough transform for lines in those regions transmitted by
Region. Thereby the angles and the lengths of the lines normal vectors are registered in the parameter space
(the Hough- or accumulator space respectively). This means that the parameterization is executed according to the
HNF.
The result is registered in a newly generated Int2-Image (HoughImage), whereby the x-axis is equivalent to the
angle between the normal vector and the x-axis (in the original image), and the y-axis is equivalent to the distance
of the line from the origin.
The angle ranges from -90 to 180 degrees and will be registered with a resolution of ½ÒÐÊ×ÓÐÙØÓÒ,which
means that one pixel in x-direction is equivalent to ½ÒÐÊ×ÓÐÙØÓÒand that the HoughImage has a width of
¾¼£ÒÐÊ×ÓÐÙØÓÒ·½ pixel. The height of the HoughImage corresponds to the diagonal of the surrounding
rectangle of the input region.
HALCON/C Reference Manual / 2000-11-15

12.8. HOUGH 751
The maxima in the result image are equivalent to the parameter values of the lines in the original image.
Parameter
º Region (input object) .............................................................region Hobject
Binary edge image in which lines are to be detected.
º HoughImage (output object) ...............................................image Hobject * :int2
Hough transform for lines.
º AngleResolution (input control) ..................................................integer long
Adjusting the resolution in the angle area.
Default Value : 4
Value List : AngleResolution ¾1, 2, 4, 8
Result
The operator hough line trans returns the value H MSG TRUE if the input is not empty. The
behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
hough line trans is reentrant and processed without parallelization.
threshold, skeleton
threshold, local max
Possible Predecessor Functions
Possible Successor Functions
See Also
(T )hough circle trans, gen region hline
Region processing
Module
T hough lines ( Hobject RegionIn, Htuple AngleResolution,
Htuple Threshold, Htuple AngleGap, Htuple DistGap, Htuple *Angle,
Htuple *Dist )
Detect lines in edge images with the help of the Hough transform and returns it in HNF.
The operator T hough lines allows the selection of linelike structures in a region, whereby it is not necessary
that the individual points of a line are connected. This process is based on the Hough transform. The lines are
returned in HNF, that is by the direction and length of their normal vector.
The parameter AngleResolution defines the degree of exactness concerning the determination of the angles.
It amounts to ½ÒÐÊ×ÓÐÙØÓÒ degree. The parameter Threshold determines by how many points of the
original region a line’s hypothesis has to be supported at least in order to be taken over into the output. The parameters
AngleGap and DistGap define a neighborhood of the points in the Hough image in order to determine the
local maxima. The lines are returned in HNF.
Parameter
º RegionIn (input object) ..........................................................region Hobject
Binary edge image in which the lines are to be detected.
º AngleResolution (input control) ..........................................integer Htuple . long
Adjusting the resolution in the angle area.
Default Value : 4
Value List : AngleResolution ¾1, 2, 4, 8
º Threshold (input control) ...................................................integer Htuple . long
Threshold value in the Hough image.
Default Value : 100
Typical Range of Values : 1 Threshold
º AngleGap (input control) ....................................................integer Htuple . long
Minimal distance of two maxima in the Hough image (direction: angle).
Default Value : 5
Typical Range of Values : 0 AngleGap
HALCON 6.0

752 CHAPTER 12. TOOLS
º DistGap (input control) .....................................................integer Htuple . long
Minimal distance of two maxima in the Hough image (direction: distance).
Default Value : 5
Typical Range of Values : 0 DistGap
º Angle (output control) ...................................hesseline.angle.rad-array Htuple . double *
Angles (in radians) of the detected lines’ normal vectors.
Typical Range of Values : -1.5707963 Angle 3.1415927
º Dist (output control) .....................................hesseline.distance-array Htuple . double *
Distance of the detected lines from the origin.
Typical Range of Values : -1.5707963 Dist 3.1415927
Parameter Number : Dist Angle
Result
The operator T hough lines returns the value H MSG TRUE if the input is not empty. The behavior
in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T hough lines is reentrant and processed without parallelization.
threshold, skeleton
T select matching lines
Possible Predecessor Functions
Possible Successor Functions
See Also
hough line trans, gen region hline, (T )hough circles
Region processing
Module
T select matching lines ( Hobject RegionIn, Hobject *RegionLines,
Htuple AngleIn, Htuple DistIn, Htuple LineWidth, Htuple Thresh,
Htuple *AngleOut, Htuple *DistOut )
Select those lines from a set of lines (in HNF) which fit best into a region.
Lines which fit best into a region can be selected from a set of lines which are available in HNF with the help of the
operator T select matching lines; the region itself is also transmitted as a parameter (RegionIn). The
width of the lines can be indicated by the parameter LineWidth. The selected lines will be returned in HNF and
as regions (RegionLines).
The lines are selected iteratively in a loop: At first, the line showing the greatest overlap with the input region
is selected from the set of input lines. This line will then be taken over into the ouput set whereby all points
belonging to that line will not be considered in the further steps determining overlaps. The loop will be left when
the maximum overlap value of the region and the lines falls below a certain threshold value (Thresh). The
selected lines will be returned as regions as well as in HNF.
Parameter
º RegionIn (input object) ..........................................................region Hobject
Region in which the lines are to be matched.
º RegionLines (output object) ..............................................region-array Hobject *
Region array containing the matched lines.
º AngleIn (input control) ...................................hesseline.angle.rad-array Htuple . double
Angles (in radians) of the normal vectors of the input lines.
Typical Range of Values : -1.5707963 AngleIn 3.1415927
º DistIn (input control) .....................................hesseline.distance-array Htuple . double
Distances of the input lines form the origin.
Typical Range of Values : -1.5707963 DistIn 3.1415927
Parameter Number : DistIn AngleIn
HALCON/C Reference Manual / 2000-11-15

12.9. KALMAN-FILTER 753
º LineWidth (input control) ...................................................integer Htuple . long
Widths of the lines.
Default Value : 7
Typical Range of Values : 1 LineWidth
º Thresh (input control) .......................................................integer Htuple . long
Threshold value for the number of line points in the region.
Default Value : 100
Typical Range of Values : 1 Thresh
º AngleOut (output control) ..............................hesseline.angle.rad-array Htuple . double *
Angles (in radians) of the normal vectors of the selected lines.
Typical Range of Values : -1.5707963 AngleOut 3.1415927
Parameter Number : AngleOut AngleIn
º DistOut (output control) .................................hesseline.distance-array Htuple . double *
Distances of the selected lines from the origin.
Typical Range of Values : -1.5707963 DistOut 3.1415927
Parameter Number : DistOut AngleOut
Result
The operator T select matching lines returns the value H MSG TRUE if the input is not empty.
The behavior in case of empty input (no input regions available) is set via the operator set system
(’no object result’,), the behavior in case of empty region is set via set system
(’empty region result’,). If necessary an exception handling is raised.
Parallelization Information
T select matching lines is reentrant and processed without parallelization.
T hough lines
Region processing
Possible Predecessor Functions
Module
12.9 Kalman-Filter
T filter kalman ( Htuple Dimension, Htuple Model, Htuple Measurement,
Htuple PredictionIn, Htuple *PredictionOut, Htuple *Estimate )
Estimate the current state of a system with the help of the Kalman filtering.
The operator T filter kalman returns an estimate of the current state (or also a prediction of a future state)
of a discrete, stochastically disturbed, linear system. In practice, Kalman filters are used successfully in image
processing in the analysis of image sequences (background identification, lane tracking with the help of line tracing
or region analysis, etc.). A short introduction concerning the theory of the Kalman filters will be followed by a
detailed description of the routine T filter kalman itself.
KALMAN FILTER: A discrete, stochastically disturbed, linear system is characterized by the following markers:
¯ State ܴص: Describes the current state of the system (speeds, temperatures,...).
¯ Parameter ٴص: Inputs from outside into the system.
¯ Measurement ݴص: Measurements gained by observing the system. They indicate the state of the system (or
at least parts of it).
¯ An output function describing the dependence of the measurements on the state.
¯ A transition function indicating how the state changes with regard to time, the current value and the parameters.
The output function and the transition function are linear. Their application can therefore be written as a multiplication
with a matrix.
The transition function is described with the help of the transition matrix ´Øµ and the parameter matrix , the initial
function is described by the measurement matrix ´Øµ. Hereby ´Øµ characterizes the dependency of the new state
HALCON 6.0

754 CHAPTER 12. TOOLS
on the old, ´Øµ indicates the dependency on the parameters. In practice it is rarely possible (or at least too time
consuming) to describe a real system and its behaviour in a complete and exact way. Normally only a relatively
small number of variables will be used to simulate the behaviour of the system. This leads to an error, the so called
system error (also called system disturbance) ڴص.
The output function, too, is usually not exact. Each measurement is faulty. The measurement errors will be called
۴ص. Therefore the following system equations arise:
Ü´Ø ·½µ´ØµÜ´Øµ ·´ØµÙ´Øµ ·Ú´Øµ
ݴص ´ØµÜ´Øµ ·Û´Øµ
The system error ڴص and the measurement error ۴ص are not known. As far as systems are concerned which
are interpreted with the help of the Kalman filter, these two errors are considered as Gaussian distributed random
vectors (therefore the expression ”‘stochastically disturbed systems”’). Therefore the system can be calculated, if
the corresponding expected values for ڴص and ۴ص as well as the covariance matrices are known.
The estimation of the state of the system is carried out in the same way as in the Gaussian-Markov-estimation.
However, the Kalman filter is a recursive algorithm which is based only on the current measurements ݴص and the
latest state ܴص. The latter implicitly also includes the knowlegde about earlier measurements.
A suitable estimate value Ü ¼, which is interpreted as the expected value of a random variable for Ü´¼µ, mustbe
indicated for the initial value Ü´¼µ. This variable should have an expected error value of 0 and the covariance
matrix È ¼ which also has to be indicated. At a certain time Ø the expected values of both disturbances ڴص and
۴ص should be 0 and their covariances should be ɴص and ʴص. ܴص, ڴص and ۴ص will usually be assumed to be
not correlated (any kind of noise-process can be modelled - however the development of the necessary matrices by
the user will be considerably more demanding). The following conditions must be met by the searched estimate
values Ü Ø :
¯ The estimate values Ü Ø are linearly dependent on the actual value ܴص and on the measurement sequence
Ý´¼µ, Ý´½µ, ¡¡¡, ݴص.
¯ Ü Ø being hereby considered to meet its expectations, i.e. Ü Ø Ü´Øµ.
¯ The grade criterion for Ü Ø is the criterion of minimal variance, i.e. the variance of the estimation error defined
as ܴص Ü Ø , being as small as possible.
After the initialization
Ü´¼µ Ü ¼ , È ´¼µ È ¼
at each point in time Ø the Kalman filter executes the following calculation steps:
È ´Øµ ¼´Øµ
´Ã ÁÁÁµ ôص
´Øµ È ´Øµ ¼´Øµ·Ê´Øµ
´Ã ÁÎ µ Ü Ø Ü´Øµ ·Ã´Øµ´Ý´Øµ ´ØµÜ´Øµµ
´Ã Î µ È ´Øµ È ´Øµ ôص´Øµ È ´Øµ
´Ã Áµ Ü´Ø ·½µ ´ØµÜ Ø · ´ØµÙ´Øµ
´Ã ÁÁµ È ´Ø ·½µ ´Øµ È ´Øµ ¼´Øµ ·É´Øµ
Hereby È ´Øµ is the covariance matrix of the estimation error, ܴص is the extrapolation value respective the prediction
value of the state, È ´Øµ are the covariances of the prediction error Ü Ü, à is the amplifier matrix (the so
called Kalman gain), and ¼ is the transposed of a matrix .
Please note that the prediction of the future state is also possible with the equation (K-I). Somtimes this is very
useful in image processing in order to determine ”‘regions of interest”’ in the next image.
As mentioned above, it is much more demanding to model any kind of noise processes. If for example the system
noise and the measurement noise are correlated with the corresponding covariance matrix Ä, the equations for the
Kalman gain and the error covariance matrix have to be modified:
È ´Øµ ¼´Øµ·Ä´Øµ
´Ã ÁÁÁµ ôص
´Øµ È ´Øµ·´ØµÐ´Øµ·Ä ¼ ¼´Øµ·Ê´Øµ
´Ã Î µ È ´Øµ ´ È ´Øµ ôص´Øµ È ´Øµµ È ´Øµ ôصĴص
This means that the user himself has to establish the linear system equations from (K-I) up to (K-V) with respect to
the actual problem. The user must therefore develop a mathematical model upon which the solution to the problem
can be based. Statistical characteristics describing the inaccuracies of the system as well as the measurement
errors, which are to be expected, thereby have to be estimated if they cannot be calculated exactly. Therefore the
following individual steps are necessary:
HALCON/C Reference Manual / 2000-11-15

12.9. KALMAN-FILTER 755
1. Developing a mathematical model
2. Selecting characteristic state variables
3. Establishing the equations describing the changes of these state variables and their linearization (matrices
and )
4. Establishing the equations describing the dependency of the measurement values of the system on the state
variables and their linearization (matrix )
5. Developing or estimating of statistical dependencies between the system disturbances (matrix É)
6. Developing or estimating of statistical dependencies between the measurement errors (matrix Ê)
7. Initialization of the initial state
As mentioned above, the initialization of the system (point 7) hereby necessitates to indicate an estimate Ü ¼ of the
state of the system at the time 0 and the corresponding covariance matrix È ¼ . If the exact initial state is not known,
it is recommendable to set the components of the vector Ü ¼ to the average values of the corresponding range, and
to set high values for È ¼ (about the size of the squares of the range). After a few iterations (when the number of the
accumulated measurement values in total has exceeded the number of the system values), the values which have
been determined in this way are also useable.
If on the other hand the initial state is known exactly, all entries for È ¼ have to be set to 0, because È ¼ describes
the covariances of the error between the estimated value Ü ¼ and the actual value Ü´¼µ.
THE FILTER ROUTINE:
A Kalman filter is dependent on a range of data which can be organized in four groups:
Model parameter: transition matrix , control matrix including the parameter Ù and the measurement matrix
Model stochastic: system-error covariance matrix É, system-error - measurement-error covariance matrix Ä,and
measurement-error covariance matrix Ê
Measurement vector: Ý
History of the system: extrapolation vector Ü and extrapolation-error covariance matrix È
Thereby many systems can work without input ”‘from outside”’, i.e. without and Ù. Further, system errors and
measurement errors are normally not correlated (Ä is dropped).
Actually the data necessary for the routine will be set by the following parameters:
Dimension: This parameter includes the dimensions of the status vector, the measurement vector and the controller
vector. Dimension thereby is a vector [n,m,p], whereby n indicates the number of the state variables,
m the number of the measurement values and p the number of the controller members. For a system without
determining control (i.e. without influence ”‘from outside”’) therefore [n,m,0] has to be passed.
Model: This parameter includes the lined up matrices (vectors) A,C,Q,G,u and (if necessary) L having been
stored in row-major order. Model therefore is a vector of the length ҢҷҢѷҢҷҢԷԷҢÑ℄.
The last summand is dropped, in case the system errors and measurement errors are not correlated, i.e. there
is no value for L.
Measurement: This parameter includes the matrix R which has been stored in row-major order, and the measurement
vector y lined up. Measurement therefore is a vector of the dimension Ñ ¢ Ñ · Ñ.
PredictionIn / PredictionOut: These two parameters include the matrix È (the extrapolation-error covariance
matrix) which has been stored in row-major order and the extrapolation vector Ü lined up. This
means, they are vectors of the length Ò ¢ Ò · Ò. PredictionIn therefore is an input parameter, which
must contain È ´Øµ and ܴص at the current time Ø. With PredictionOut the routine returns the corresponding
predictions È ´Ø ·½µand Ü´Ø ·½µ.
Estimate: With this parameter the routine returns the matrix È (the estimation-error covariance matrix) which
has been stored in row-major order and the estimated state Ü lined up. Estimate therefore is a vector of
the length Ò ¢ Ò · Ò.
Please note that the covariance matrices (É Ê È È ) must of course be symmetric.
HALCON 6.0

756 CHAPTER 12. TOOLS
Parameter
º Dimension (input control) .............................................integer-array Htuple . long
The dimensions of the state vector, the measurement and the controller vector.
Default Value : ’[3,1,0]’
Typical Range of Values : 0 Dimension 30
º Model (input control) ...................................................real-array Htuple . double
The lined up matrices É, possibly and Ù, and if necessary Ä which have been stored in row-major
order.
Default Value : ’[1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]’
Typical Range of Values : 0.0 Model 10000.0
º Measurement (input control) ...........................................real-array Htuple . double
The matrix Ê stored in row-major order and the measurement vector Ý lined up.
Default Value : ’[1.2,1.0]’
Typical Range of Values : 0.0 Measurement 10000.0
º PredictionIn (input control) ..........................................real-array Htuple . double
The matrix È (the extrapolation-error covariances) stored in row-major order and the extrapolation vector Ü
lined up.
Default Value : ’[0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,0.0]’
Typical Range of Values : 0.0 PredictionIn 10000.0
º PredictionOut (output control) ......................................real-array Htuple . double *
The matrix P£ (the extrapolation-error covariances)stored in row-major order and the extrapolation vector Ü
lined up.
º Estimate (output control) ............................................real-array Htuple . double *
The matrix È (the estimation-error covariances) stored in row-major order and the estimated state Ü lined up.
Example
/* Typical procedure: */
/* 1. To initialize the variables
which describe the model, e.g. with */
read_kalman("kalman.init",Dim,Mod,Meas,Pred) ;
/* Generation of the first measurements (typically of the
first image of an image series) with an appropriate
problem-specific routine (there is a fictitious routine
extract_features in this example): */
extract_features(Image1,Meas,&Meas1) ;
/* first Kalman-Filtering: */
filter_kalman(Dim,Mod,Meas1,Pred,&Pred1,&Est1) ;
/* To use the estimate value (if need be the prediction too) */
/* with a problem-specific routine (here use_est): */
use_est(Est1) ;
/* To get the next measurements (e.g. from the next image): */
extract_next_features(Image2,Meas1,&Meas2) ;
/* if need be Update of the model parameter (a constant model) */
/* second Kalman-Filtering: */
filter_kalman(Dim,Mod,Meas2,Pred1,&Pred2,&Est2) ;
use_est(Est2) ;
HALCON/C Reference Manual / 2000-11-15

12.9. KALMAN-FILTER 757
extract_next_features(Image3,Meas2,&Meas3) ;
/* etc. */
Result
If the parameter values are correct, the operator T filter kalman returns the value H MSG TRUE. Otherwise
an exception handling will be raised.
Parallelization Information
T filter kalman is reentrant and processed without parallelization.
Possible Predecessor Functions
T read kalman, T sensor kalman
T update kalman
Possible Successor Functions
See Also
T read kalman, T update kalman, T sensor kalman
Bibliography
W.Hartinger: ”‘Entwurf eines anwendungsunabh”angigen Kalman-Filters mit Untersuchungen im Bereich der
Bildfolgenanalyse”’; Diplomarbeit; Technische Universit”at M”unchen, Institut f”ur Informatik, Lehrstuhl Prof.
Radig; 1991.
R.E.Kalman: ”‘A New Approach to Linear Filtering and Prediction Problems”’; Transactions ASME, Ser.D: Journal
of Basic Engineering; Vol. 82, S.34-45; 1960.
R.E.Kalman, P.l.Falb, M.A.Arbib: ”‘Topics in Mathematical System Theory”’; McGraw-Hill Book Company,
New York; 1969.
K-P. Karmann, A.von Brandt: ”‘Moving Object Recognition Using an Adaptive Background Memory”’; Time-
Varying Image Processing and Moving Object Recognition 2 (ed.: V. Cappellini), Proc. of the 3rd Interantional
Workshop, Florence, Italy, May, 29th - 31st, 1989; Elsevier, Amsterdam; 1990.
Module
Tools
T read kalman ( Htuple FileName, Htuple *Dimension, Htuple *Model,
Htuple *Measurement, Htuple *Prediction )
Read the description file of a Kalman filter.
The operator T read kalman reads the description file FileName of a Kalman filter. Kalman filters return
an estimate of the current state (or even the prediction of a future state) of a discrete, stochastically disturbed,
linear system. They are successfully used in image processing, especially in the analysis of image sequences. A
Kalman filtering is based on a mathematical model of the system to be examined which at any point in time has
the following characteristics:
Model parameter: transition matrix , control matrix including the controller output Ù and the measurement
matrix
Model stochastic: system-error covariance matrix É, system-error - measurement-error covariance matrix Ä and
measurement-error covariance matrix Ê
Estimate of the initial state of the system: state Ü ¼ and corresponding covariance matrix È ¼
Many systems do not need entries ”‘from outside”’, and therefore and Ù can be dropped. Further, system errors
and measurement errors are normally not correlated (Ä is dropped). The characteristics mentioned above can be
stored in an ASCII-file and then can be read with the help of the operator T read kalman. This ASCII-file must
have the following structure:
+ content row
+matrix
+ atrix
+matrixÉ
Dimension row
HALCON 6.0

758 CHAPTER 12. TOOLS
[ + matrix + vector Ù ]
[ + matrix Ä ]
+matrixÊ
[ + matrix È ¼ ]
[ + vector Ü ¼ ]
The dimension row thereby is always of the following form:
n=integer m=integer p=integer
whereby n indicates the number of the state variables, m the number of the measurement values and p the number
of the controller members (see also Dimension). The maximal dimension will hereby be limited by a system
constant (= 30 for the time being).
The content row has the following form:
£ £ É £ £ Ù £ Ä £ Ê £ È £ Ü£
and describes the following content of the file. Instead of ’£’, ’+’ (= parameter is available) respectively ’-’ (=
parameter is missing) have to be set. Please note that only the parameters marked by [...] in the above list may be
left out in the description file. If the initial state estimate ¼ is missing (i.e. ’x-’), the components of the vector will
supposed to be 0.0. If the covariance matrix È ¼ of the initial state estimate is missing (i.e. ’P-’), the error will be
supposed to be tremendous. In this case the matrix elements will be set to 10000.0. This value seems to be very
high, however, it is only sufficient if the range of components of the state vector x is smaller to the tenth power.
´Ö ¢ ×µ matrices will be stored per row in the following form:
ÃÓÑÑÒØÖ ×ØÖÒ
½½ ½¾ ¡¡¡ ½×
.
. .. . Ö½ Ö¾ ¡¡¡ Ö×
(the spaces and line feed characters can be chosen at will),
vectors will be stored correspondingly in the following form:
ÓÑÑÒØ ×ØÖÒ
½ ¡¡¡
The following parameter values are returned by the operator T read kalman:
Dimension: This parameter includes the dimensions of the status vector, the measurement vector and the controller
vector. Dimension thereby is a vector [n,m,p], whereby n indicates the number of the state variables,
m the number of the measurement values and p the number of the controller members. For a system without
determining control (i.e. without influence ”‘from outside”’) therefore Dimension = [n,m,0].
Model: This parameter includes the lined up matrices (vectors) A, C, Q, G, u and (if necessary) L having been
stored in row-major order. Model therefore is a vector of the length ҢҷҢѷҢҷҢԷԷҢÑ℄.
The last summand is dropped, in case the system errors and measurement errors are not correlated, i.e. there
is no value for L.
Measurement: This parameter includes the matrix Ê which has been stored in row-major order.
Measurement therefore is vector of the dimension Ñ ¢ Ñ.
Prediction: This parameter includes the matrix È ¼ (the error covariance matrix of the initial state estimate)
and the initial state estimate Ü ¼ lined up. This means, it is a vector of the length Ò ¢ Ò · Ò.
Parameter
º FileName (input control) ...........................................filename Htuple . const char *
Description file for a Kalman filter.
Default Value : ”kalman.init”
º Dimension (output control) ..........................................integer-array Htuple . long *
The dimensions of the state vector, the measurement vector and the controller vector.
º Model (output control) ................................................real-array Htuple . double *
The lined up matrices É, possibly and Ù, and if necessary Ä stored in row-major order.
HALCON/C Reference Manual / 2000-11-15

12.9. KALMAN-FILTER 759
º Measurement (output control) ........................................real-array Htuple . double *
The matrix Ê stored in row-major order.
º Prediction (output control) ..........................................real-array Htuple . double *
The matrix È ¼ (error covariance matrix of the initial state estimate) stored in row-major order and the initial
state estimate Ü ¼ lined up.
Example
/*An example of the description-file: */
/* */
/*n=3 m=1 p=0 */
/*A+C+Q+G-u-L-R+P+x+ */
/*transition matrix A: */
/*1 1 0.5 */
/*0 1 1 */
/*0 0 1 */
/*measurement matrix C: */
/*1 0 0 */
/*system-error covariance matrix Q: */
/*54.3 37.9 48.0 */
/*37.9 34.3 42.5 */
/*48.0 42.5 43.7 */
/*measurement-error covariance matrix R: */
/*1.2 */
/*estimation-error covariance matrix (for the initial estimate) P0: */
/*0 0 0 */
/*0 180.5 0 */
/*0 0 100 */
/*initial estimate x0: */
/*0 100 0 */
/* */
/*the result of read_kalman with the upper descriptionfile */
/*as inputparameter: */
/* */
/*Dimension = [3,1,0] */
/*Model = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0, */
/* 54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7] */
/*Measurement = [1.2] */
/*Prediction = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0, */
/* 0.0] */
Result
If the description file is readable and correct, the operator T read kalman returns the value H MSG TRUE.
Otherwise an exception handling will be raised.
Parallelization Information
T read kalman is reentrant and processed without parallelization.
T filter kalman
Possible Successor Functions
See Also
T update kalman, T filter kalman, T sensor kalman
Tools
Module
T sensor kalman ( Htuple Dimension, Htuple MeasurementIn,
Htuple *MeasurementOut )
Interactive input of measurement values for a Kalman filtering.
HALCON 6.0

760 CHAPTER 12. TOOLS
The operator T sensor kalman supports the interactive input of measurement values for a Kalman filtering.
Kalman filters return an estimate of the current state (or even the prediction of a future state) of a discrete, stochastically
disturbed, linear system. They are successfully used in image processing, especially in the analysis of image
sequences.
Each filtering is hereby based on certain measurement values. How these values are extracted from images or
sensor data depends strongly on the individual application and therefore must be entirely up to the user. However,
the operator T sensor kalman allows an interactive input of (fictitious) measurement values Ý and the corresponding
measurement-error covariance matrix Ê. Especially the testing of Kalman filters during the development
can hereby be facilitated.
The parameters MeasurementIn and MeasurementOut include the matrix Ê which has been stored in rowmajor
order and the measurement vector Ý lined up, i.e. they are vectors of the length ÑÒ×ÓÒ¢ ÑÒ×ÓÒ ·
ÑÒ×ÓÒ
Parameter
º Dimension (input control) ...................................................integer Htuple . long
Number of measurement values.
Default Value : 1
Typical Range of Values : 0 Dimension 30
º MeasurementIn (input control) ........................................real-array Htuple . double
The matrix Ê stored in row-major order and the measurement vector Ý lined up.
Default Value : ’[1.2,1.0]’
Typical Range of Values : 0.0 MeasurementIn 10000.0
º MeasurementOut (output control) ....................................real-array Htuple . double *
The matrix Ê stored in row-major order and the measurement vector Ý lined up.
Result
If the parameters are correct, the operator T sensor kalman returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
T sensor kalman is reentrant and processed without parallelization.
T filter kalman
Possible Successor Functions
See Also
T filter kalman, T read kalman, T update kalman
Tools
Module
T update kalman ( Htuple FileName, Htuple DimensionIn, Htuple ModelIn,
Htuple MeasurementIn, Htuple *DimensionOut, Htuple *ModelOut,
Htuple *MeasurementOut )
Read an update file of a Kalman filter.
The operator T update kalman reads the update file FileName of a Kalman filter. Kalman filters return an
estimate of the current state (or even the prediction of a future state) of a discrete, stochastically disturbed, linear
system.
A Kalman filtering is based on a mathematical model of the system to be examined which at any point in time has
the following characteristics:
Model parameter: transition matrix , control matrix including the controller output Ù and the measurement
matrix
Model stochastic: system-error covariance matrix É, system-error - measurement-error covariance matrix Ä and
measurement-error covariance matrix Ê
Measurement vector: Ý
History of the system: extrapolation vector Ü and extrapolation-error covariance matrix È
HALCON/C Reference Manual / 2000-11-15

12.9. KALMAN-FILTER 761
Many systems do not need entries ”‘from outside”’ and therefore and Ù can be dropped. Further, system errors
and measurement errors are normally not correlated (Ä is dropped). Some of the characteristics mentioned above
may change dynamically (from one iteration to the next). The operator T update kalman serves to modify
parts of the system according to an update file (ASCII) with the following structure (see also T read kalman):
Dimension row
+ content row
+matrix
+matrix
+matrixÉ
+matrix + vector Ù
+matrixÄ
+matrixÊ
The dimension row thereby has the following form:
n=integer m=integer p=integer
whereby n indicates the number of the state variables, m the number of the measurement values and p the number
of the controller members (see also DimensionIn / DimensionOut). The maximal dimension will hereby be
limited by a system constant (= 30 for the time being). As in this case changes should take effect at a valid model,
the dimensions Ò and Ñ are invariant (and will only be indicated for purposes of control).
The content row has the following form:
£ £ É £ £ Ù £ Ä £ Ê£
and describes the further content of the file. Instead of ’£’, ’+’ (= parameter is available) respectively ’-’ (=
parameter is missing) has to be set. In contrast to description files for T read kalman, the system description
needs not be complete in this case. Only those parts of the system which are changed must be indicated. The
indication of estimated values is unnecessary, as these values must stem from the latest filtering according to the
structure of the filter.
´Ö ¢ ×µ matrices will be stored in row-major order in the following form:
ÓÑÑÒØ ×ØÖÒ
½½ ½¾ ¡¡¡ ½×
.
. .. .
Ö½ Ö¾ ¡¡¡ Ö×
(the spaces/line feed characters can be chosen at will),
vectors will be stored correspondingly in the following form:
ÓÑÑÒØÖ ×ØÖÒ
½ ¡¡¡
The following parameter values of the operator T read kalman will be changed:
DimensionIn / DimensionOut: These parameters include the dimensions of the state vector, measurement
vector and controller vector and therefore are vectors [n,m,p], whereby n indicates the number of the state
variables, m the number of the measurement values and p the number of the controller members. n and m
are invariant for a given system, i.e. they must not differ from corresponding input values of the update file.
For a system without without influence ”‘from outside”’ p=0.
ModelIn / ModelOut: These parameters include the lined up matrices (vectors) A, C, Q, G, u and if necessary
L which have been stored in row-major order. ModelIn / ModelOut therefore are vectors of the length
ҢҷҢѷҢҷҢԷԷҢÑ℄. The last summand is dropped if system errors and measurement
errors are not correlated, i.e. no value has been set for L.
MeasurementIn / MeasurementOut: These parameters include the matrix R stored in row-major order, and
therefore are vectors of the dimension Ñ ¢ Ñ.
HALCON 6.0

762 CHAPTER 12. TOOLS
Parameter
º FileName (input control) ...........................................filename Htuple . const char *
Update file for a Kalman filter.
Default Value : ”kalman.updt”
º DimensionIn (input control) ..........................................integer-array Htuple . long
The dimensions of the state vector, measurement vector and controller vector.
Default Value : ’[3,1,0]’
Typical Range of Values : 0 DimensionIn 30
º ModelIn (input control) .................................................real-array Htuple . double
The lined up matrices A,C,Q, possibly G and u, and if necessary L which all have been stored in row-major
order.
Default Value : ’[1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]’
Typical Range of Values : 0.0 ModelIn 10000.0
º MeasurementIn (input control) ........................................real-array Htuple . double
The matrix R stored in row-major order.
Default Value : ’[1,2]’
Typical Range of Values : 0.0 MeasurementIn 10000.0
º DimensionOut (output control) ......................................integer-array Htuple . long *
The dimensions of the state vector, measurement vector and controller vector.
º ModelOut (output control) ............................................real-array Htuple . double *
The lined up matrices A,C,Q, possibly G and u, and if necessary L which all have been stored in row-major
order.
º MeasurementOut (output control) ....................................real-array Htuple . double *
The matrix R stored in row-major order.
Example
/* The following values are describing the system */
/* */
/*DimensionIn = [3,1,0] */
/*ModelIn = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0, */
/* 54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7] */
/*MeasurementIn = [1,2] */
/* */
/*An example of the Updatefile: */
/* */
/*n=3 m=1 p=0 */
/*A+C-Q-G-u-L-R- */
/*transitions at time t=15: */
/*2 1 1 */
/*0 2 2 */
/*0 0 2 */
/* */
/*the results of update_kalman: */
/* */
/*DimensionOut = [3,1,0] */
/*ModelOut = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0, */
/* 54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7] */
/*MeasurementOut = [1.2] */
Result
If the update file is readable and correct, the operator T update kalman returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
T update kalman is reentrant and processed without parallelization.
T filter kalman
Possible Successor Functions
HALCON/C Reference Manual / 2000-11-15

12.10. MATCHING 763
See Also
T read kalman, T filter kalman, T sensor kalman
Tools
Module
12.10 Matching
clear shape model ( long ModelID )
Free the memory of a shape model.
The operator clear shape model frees the memory of a shape model which has been created by
create shape model. After execution of the operator clear shape model the model can no longer be
used. The handle ModelID becomes invalid.
Parameter
º ModelID (input control) ........................................................shape model long
Handle of the model.
Result
If the handle of the model is valid, the operator clear shape model returns the value H MSG TRUE. If
necessary an exception handling is raised.
Parallelization Information
clear shape model is processed completely exclusively without parallelization.
Possible Predecessor Functions
create shape model, read shape model, write shape model
Template matching
Module
create shape model ( Hobject Template, long NumLevels,
double AngleStart, double AngleExtent, double AngleStep,
const char *Optimization, const char *Metric, long Contrast,
long MinContrast, long *ModelID )
Prepare a shape model for matching.
The operator create shape model prepares a template, which is passed in the image Template, asashape
model used for matching.
The model is generated using multiple image pyramid levels and multiple rotations and is stored in memory.
The output parameter ModelID is a handle for this model, which is used in subsequent calls to
T find shape model.
The number of pyramid levels is determined with the parameter NumLevels. It should be chosen as large as possible
because by this the time necessary to find the object is significantly reduced. On the other hand, NumLevels
must be chosen such that the model is still recognizable and contains a sufficient number of points (at least four)
on the highest pyramid level. This can be checked using the output of inspect shape model. If not enough
model points are generated, create shape model returns with an error message.
The parameters AngleStart and AngleExtent determine the range of possible rotations, in which the model
can occur in the image. Note that the model can only be found in this range of angles by T find shape model.
The parameter AngleStep determines the step length within the selected range of angles. Hence, if subpixel
accuracy is not specified in T find shape model, this parameter specifies the accuracy that is achievable for
the angles in T find shape model. AngleStep should be chosen based on the size of the object. Smaller
models do not possess many (discrete) rotations in the image, and hence AngleStep should be chosen larger
for smaller models. If AngleExtent is not an integer multiple of AngleStep, AngleStep is modified
accordingly. The model is pre-generated for the selected angle range and stored in memory. The memory required
HALCON 6.0

764 CHAPTER 12. TOOLS
to store the model is proportional to the number of angle steps and the number of points in the model. Hence, if
AngleStep is too small or AngleExtent too big, it may happen that the model no longer fits into the (virtual)
memory. In this case, either AngleStep must be enlarged or AngleExtent must be reduced. In any case,
it is desirable that the model completely fits into the main memory, because this avoids paging by the operating
system, and hence the time to find the object will be much smaller. Since angles can be determined with subpixel
resolution by T find shape model, ÒÐËØÔ ½ can be selected for models of a diameter smaller than 300
pixels.
For particularly large models, it may be useful to reduce the number of model points by setting Optimization
to a value different from ’none’. IfÇÔØÑÞØÓÒ ¼ ÒÓÒ ¼ , all model points are stored. In all other cases, the
number of points is reduced according to the value of Optimization. If the number of points is reduced, it may
be necessary in T find shape model to set the parameter Greediness to a smaller value, e.g., 0.7 or 0.8. For
small models, the reduction of the number of model points does not result in a speed-up of the search because in
this case usually significantly more potential instances of the model must be examined.
The parameter Contrast determines, which contrast the model points must have. The contrast is a measure
for local gray value differences between the object and the background and between different parts of the object.
Contrast should be chosen such that only the significant features of the template are used for the model. The
effect of this parameter can be checked in advance with inspect shape model.
With MinContrast, it can be determined which contrast the model must at least have in the recognition performed
by T find shape model. In other words, this parameter separates the model from the noise in the
image. Therefore, a good choice is the range of gray value changes caused by the noise in the image. If, for
example, the gray values fluctuate within a range of 10 gray levels, MinContrast should be set to 10. Obviously,
MinContrast must be smaller than Contrast. If the model should be recognized in very low contrast
images, MinContrast must be set to a correspondingly small value. If the model should be recognized even if
it is severely occluded, MinContrast should be slightly larger than the range of gray value fluctuations created
by noise in order to ensure that the position and rotation of the model are extracted robustly and accurately by
T find shape model.
The parameter Metric determines the conditions under which the model is recognized in the image. If ÅØÖ
¼ Ù× ÔÓÐÖØÝ ¼ , the object in the image and the model must have the same contrast. If, for example, the model is a
bright object on a dark background, the object is found only if it is also brighter than the background. If ÅØÖ
¼ ÒÓÖ ÐÓÐ ÔÓÐÖØÝ ¼ , the object is found in the image also if the the contrast reverses globally. In the above
example, the object hence is also found if it is darker than the background. The runtime of T find shape model
will increase slightly in this case. If ÅØÖ ¼ ÒÓÖ ÐÓÐ ÔÓÐÖØÝ ¼ , the model is found even if the contrast
changes locally. This mode can, for example, be useful if the object consists of a part with medium gray value,
within which either darker of brighter sub-objects lie. Since in this case the runtime of T find shape model
increases significantly, it is usually better to create several models that reflect the possible contrast variations of the
object with create shape model, and to match them separately with T find shape model.
Parameter
º Template (input object) .....................................................image Hobject : byte
Input image whose domain will be used to create the model.
º NumLevels (input control) ...........................................................integer long
Maximum number of pyramid levels.
Default Value : 4
Value List : NumLevels ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
º AngleStart (input control) .....................................................angle.rad double
Smallest rotation of the pattern.
Default Value : -0.39
Value Suggestions : AngleStart ¾-3.14, -1.57, -0.79, -0.39, -0.20, 0.0
º AngleExtent (input control) ....................................................angle.rad double
Extent of the rotation angles.
Default Value : 0.79
Value Suggestions : AngleExtent ¾6.28, 3.14, 1.57, 0.79, 0.39
Restriction : AngleExtent 0
º AngleStep (input control) ......................................................angle.rad double
Step length of the angles (resolution).
Default Value : 0.0982
Value Suggestions : AngleStep ¾0.3927, 0.1963, 0.0982, 0.0491, 0.0245
Restriction : AngleStep 0
HALCON/C Reference Manual / 2000-11-15

12.10. MATCHING 765
º Optimization (input control) .................................................string const char *
Kind of optimization.
Default Value : ’none’
Value List : Optimization ¾’none’, ’point reduction low’, ’point reduction medium’,
’point reduction high’
º Metric (input control) .........................................................string const char *
Match metric.
Default Value : ’use polarity’
Value List : Metric ¾’use polarity’, ’ignore global polarity’, ’ignore local polarity’
º Contrast (input control) ...........................................................number long
Contrast of the object in the template image.
Default Value : 60
Value Suggestions : Contrast ¾20, 40, 60, 80, 100, 120, 140, 160
º MinContrast (input control) .......................................................number long
Minimum contrast of the objects in the search images.
Default Value : 10
Value Suggestions : MinContrast ¾10, 20, 20, 40
Restriction : MinContrast Contrast
º ModelID (output control) .....................................................shape model long *
Handle of the model.
Result
If the parameters are valid, the operator create shape model returns the value H MSG TRUE. If necessary
an exception handling is raised. If the parameters NumLevels and Contrast are chosen such that the model
contains too few points, the error 8510 is raised.
Parallelization Information
create shape model is processed completely exclusively without parallelization.
Possible Predecessor Functions
draw region, reduce domain, threshold
Possible Successor Functions
T find shape model, clear shape model, write shape model
create template rot
Template matching
Alternatives
Module
T find shape model ( Hobject Image, Htuple ModelID, Htuple AngleStart,
Htuple AngleExtent, Htuple MinScore, Htuple NumMatches, Htuple MaxOverlap,
Htuple SubPixel, Htuple NumLevels, Htuple Greediness, Htuple *Row,
Htuple *Column, Htuple *Angle, Htuple *Score )
Find the best matches of a shape model in an image.
The operator T find shape model finds the best NumMatches instances of the shape model ModelID in
the input image Image. The model must have been created previously by calling create shape model or
read shape model.
The position and rotation of the found instances of the model is returned in Row, Column and Angle. Additionally,
the score of each found instance is returned in Score. The score is a number between 0 and 1, which is
an approximate measure of how much of the model is visible in the image. If, for example, half of the model is
occluded, the score cannot exceed 0.5.
The model is searched within those points of the domain of the image, in which the model lies completely within
the image. This means that the model will not be found if it extends beyond the borders of the image, even if it
would achieve a score greater than MinScore (see below). The parameters AngleStart and AngleExtent
determine the range of rotations for which the model is searched. If necessary, the range of rotations is clipped to
the range given when the model was created with create shape model.
HALCON 6.0

766 CHAPTER 12. TOOLS
The parameter MinScore determines what score a potential match must at least have to be regarded as an instance
of the model in the image. The larger MinScore is chosen, the faster the search is. If the model can be expected
never to be occluded in the images, MinScore may be set as high as 0.8 or even 0.9.
The maximum number of instances to be found can be determined with NumMatches. If more than
NumMatches instances with a score greater than MinScore are found in the image, only the best NumMatches
instances are returned. If fewer than NumMatches are found, only that number is returned, i.e., the parameter
MinScore takes precedence over NumMatches.
If the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations
are found in the image. The parameter MaxOverlap determines by what fraction (i.e., a number between
0 and 1) two instances may at most overlap in order to consider them as different instances, and hence to be
returned separately. If two instances overlap each other by more than MaxOverlap only the best instance is
returned. The calculation of the overlap is based on the smallest enclosing rectangle of arbitrary orientation (see
smallest rectangle2) of the found instances. If ÅÜÇÚÖÐÔ ¼, the found instances may not overlap at
all, while for ÅÜÇÚÖÐÔ ½all instances are returned.
The parameter SubPixel determines whether the instances should be extracted with subpixel accuracy. If
SubPixel is set to ’true’, the position as well as the rotation is determined with subpixel accuracy.
The number of pyramid levels used during the search is determined with NumLevels. If necessary, the number
of levels is clipped to the range given when the template was created with create shape model.
The parameter Greediness determines how “greedily” the search should be carried out. If ÖÒ×× ¼,a
safe search heuristic is used, which always finds the model if it is visible in the image. However, the search will be
relatively time consuming in this case. If ÖÒ×× ½, an unsafe search heuristic is used, which may cause
the model not to be found in rare cases, even though it is visible in the image. For ÖÒ×× ½, the maximum
search speed is achieved. In almost all cases, the template will always be found for ÖÒ×× ¼.
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image in which the model should be found.
º ModelID (input control) ................................................shape model Htuple . long
Handle of the model.
º AngleStart (input control) .............................................angle.rad Htuple . double
Smallest rotation of the model.
Default Value : -0.39
Value Suggestions : AngleStart ¾-3.14, -1.57, -0.78, -0.39, -0.20, 0.0
º AngleExtent (input control) ............................................angle.rad Htuple . double
Extent of the rotation angles.
Default Value : 0.78
Value Suggestions : AngleExtent ¾6.28, 3.14, 1.57, 0.78, 0.39, 0.0
Restriction : AngleExtent 0
º MinScore (input control) .....................................................real Htuple . double
Minumum score of the instances of the model to be found.
Default Value : 0.5
Value Suggestions : MinScore ¾0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical Range of Values : 0 MinScore 1
Minimal Value Step : 0.01
Recommended Value Step : 0.05
º NumMatches (input control) .................................................integer Htuple . long
Number of instances of the model to be found.
Default Value : 1
Value Suggestions : NumMatches ¾0, 1, 2, 3, 4, 5, 10, 20
º MaxOverlap (input control) ..................................................real Htuple . double
Maximum overlap of the instances of the model to be found.
Default Value : 0.5
Value Suggestions : MaxOverlap ¾0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical Range of Values : 0 MaxOverlap 1
Minimal Value Step : 0.01
Recommended Value Step : 0.05
HALCON/C Reference Manual / 2000-11-15

12.10. MATCHING 767
º SubPixel (input control) ..............................................string Htuple . const char *
Subpixel accuracy if ’true’.
Default Value : ’false’
Value List : SubPixel ¾’true’, ’false’
º NumLevels (input control) ...................................................integer Htuple . long
Number of pyramid levels used in the matching.
Default Value : 3
Value List : NumLevels ¾1, 2, 3, 4, 5, 6
º Greediness (input control) ..................................................real Htuple . double
“Greediness” of the search heuristic (0: safe but slow; 1: fast but matches may be missed).
Default Value : 0.9
Value Suggestions : Greediness ¾0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical Range of Values : 0 Greediness 1
Minimal Value Step : 0.01
Recommended Value Step : 0.05
º Row (output control) ................................................point.y-array Htuple . double *
Row coordinate of the found instances of the model.
º Column (output control) ............................................point.x-array Htuple . double *
Column coordinate of the found instances of the model.
º Angle (output control) ...........................................angle.rad-array Htuple . double *
Rotation angle of the found instances of the model.
º Score (output control) ................................................real-array Htuple . double *
Score of the found instances of the model.
Result
If the parameter values are correct, the operator T find shape model returns the value H MSG TRUE.
If the input is empty (no input images are available) the behaviour can be set via set system
(’no object result’,). If necessary, an exception handling is raised.
Parallelization Information
T find shape model is reentrant and processed without parallelization.
Possible Predecessor Functions
create shape model, read shape model
best match rot mg
Template matching
Alternatives
Module
inspect shape model ( Hobject Image, Hobject *ModelImages,
Hobject *ModelRegions, long NumLevels, long Contrast )
Create the representation of a shape model.
inspect shape model creates a representation of a shape model. The operator is particularly useful in order
to determine the parameters NumLevels and Contrast, which are used in create shape model, quickly
and conveniently. The representation of the model is created on multiple image pyramid levels, where the number
of levels is determined by NumLevels. In contrast to create shape model, the model is only created
for the rotation of the object in the input image, i.e., ¼ Æ . As output, inspect shape model creates an image
object ModelImages containing the images of the individual levels of the image pyramid as well as a region
in ModelRegions for each pyramid level that represents the model at the respective pyramid level. The individual
objects can be accessed with select obj. As described for create shape model, the number of
pyramid levels should be chosen as large as possible, while taking into account that the model must be recognizable
on the highest pyramid level and must have enough model points. The parameter Contrast should be
chosen such that only the significant features of the template object are used for the model. In its typical use,
inspect shape model is called interactively multiple times with different parameters for NumLevels and
Contrast, until a satisfactory model is obtained. After this, create shape model is called with the parameters
thus obtained.
HALCON 6.0

768 CHAPTER 12. TOOLS
Parameter
º Image (input object) .........................................................image Hobject : byte
Input image.
º ModelImages (output object) ........................................image-array Hobject * : byte
Image pyramid of the input image
º ModelRegions (output object) ............................................region-array Hobject *
Model region pyramid
º NumLevels (input control) ...........................................................integer long
Number of pyramid levels.
Default Value : 4
Value List : NumLevels ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10
º Contrast (input control) ...........................................................number long
Contrast of the object in the image.
Default Value : 60
Value Suggestions : Contrast ¾20, 40, 60, 80, 100, 120, 140, 160
Result
If the parameters are valid, the operator inspect shape model returns the value H MSG TRUE. If necessary
an exception handling is raised.
Parallelization Information
inspect shape model is reentrant and processed without parallelization.
reduce domain
select obj
create shape model
Template matching
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
read shape model ( const char *FileName, long *ModelID )
Read a shape model from a file.
The operator read shape model reads a shape model, which has been written with write shape model,
from the file FileName.
Parameter
º FileName (input control) ...................................................filename const char *
File name.
º ModelID (output control) .....................................................shape model long *
Handle of the model.
Result
If the file name is valid, the operator read shape model returns the value H MSG TRUE. If necessary an
exception handling is raised.
Parallelization Information
read shape model is processed completely exclusively without parallelization.
T find shape model
Possible Successor Functions
See Also
create shape model, clear shape model
Template matching
Module
HALCON/C Reference Manual / 2000-11-15

12.11. MEASURE 769
write shape model ( long ModelID, const char *FileName )
Write a shape model to a file.
The operator write shape model writes a shape model to the file FileName. The model can be read again
with read shape model.
Parameter
º ModelID (input control) ........................................................shape model long
Handle of the model.
º FileName (input control) ...................................................filename const char *
File name.
Result
If the file name is valid (write permission), the operator write shape model returns the value H MSG TRUE.
If necessary an exception handling is raised.
Parallelization Information
write shape model is reentrant and processed without parallelization.
create shape model
Template matching
Possible Predecessor Functions
Module
12.11 Measure
close measure ( long MeasureHandle )
Delete a measure object.
close measure deletes the measure object given by MeasureHandle. The memory used for the measure
object is freed.
Parameter
º MeasureHandle (input control) .................................................measureid long
Measure object handle.
Result
If the parameter values are correct the operator close measure returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
close measure is reentrant and processed without parallelization.
Possible Predecessor Functions
gen measure rectangle2, T measure pos, T measure pairs
Sub-pixel operators
Module
gen measure arc ( double CenterRow, double CenterCol, double Radius,
double AngleStart, double AngleExtent, double AnnulusRadius, long Width,
long Height, const char *Interpolation, long *MeasureHandle )
Prepare the extraction of straight edges perpendicular to an annular arc.
gen measure arc prepares the extraction of straight edges which lie perpendicular to an annular arc. Here,
annular arc denotes a circular arc with an associated width. The center of the arc is passed in the parameters
CenterRow and CenterCol, its radius in Radius, the starting angle in AngleStart, and its angular extent
HALCON 6.0

770 CHAPTER 12. TOOLS
relative to the starting angle in AngleExtent. IfÒÐÜØÒØ ¼, an arc with counterclockwise orientation
is generated, otherwise an arc with clockwise orientation. The radius of the annular arc, i.e., half its width, is
determined by AnnulusRadius.
The edge extraction algorithm is described in the documentation of the operator T measure pos. As discussed
there, different types of interpolation can be used for the calculation of the one-dimensional gray value profile. For
Interpolation = ’nearest neighbor’, the gray values in the measurement are obtained from the gray values
of the closest pixel, i.e., by constant interpolation. For Interpolation = ’bilinear’, bilinear interpolation is
used, while for Interpolation = ’bicubic’, bicubic interpolation is used.
With gen measure rectangle2, all computations which can be used for multiple measurements are removed
from the actual measurement. To effect this, an optimized data structure, a so-called measure object,
is constructed and returned in MeasureHandle. In order to perform the measurement at the optimum
speed, the size of the images for which subsequent measurements will be made must already be specified in
gen measure rectangle2 with the parameters Width and Height. This technique increases the speed of
the actual measurement significantly.
Parameter
º CenterRow (input control) ..................................................point.y double / long
Row coordinate of the center of the arc.
Default Value : 100.0
Value Suggestions : CenterRow ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 CenterRow 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º CenterCol (input control) ..................................................point.x double / long
Column coordinate of the center of the arc.
Default Value : 100.0
Value Suggestions : CenterCol ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 CenterCol 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Radius (input control) .....................................................number double / long
Radius of the arc.
Default Value : 50.0
Value Suggestions : Radius ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 Radius 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º AngleStart (input control) ...............................................angle.rad double / long
Start angle of the arc in radians.
Default Value : 0.0
Value Suggestions : AngleStart ¾-3.14159265359, -2.35619449019, -1.5707963268,
-0.785398163398, 0.0, 0.785398163398, 1.5707963268, 2.35619449019, 3.14159265359
Typical Range of Values : -3.14159265359 AngleStart 3.14159265359 (lin)
Minimal Value Step : 0.0314159265359
Recommended Value Step : 0.314159265359
º AngleExtent (input control) .............................................angle.rad double / long
Angular extent of the arc in radians.
Default Value : 6.28318530718
Value Suggestions : AngleExtent ¾-6.28318530718, -5.49778714378, -4.71238898038, -3.926990817,
-3.14159265359, -2.35619449019, -1.5707963268, -0.785398163398, 0.785398163398, 1.5707963268,
2.35619449019, 3.14159265359, 3.926990817, 4.71238898038, 5.49778714378, 6.28318530718
Typical Range of Values : -6.28318530718 AngleExtent 6.28318530718 (lin)
Minimal Value Step : 0.0314159265359
Recommended Value Step : 0.314159265359
Restriction : AngleExtent 0.0
HALCON/C Reference Manual / 2000-11-15

12.11. MEASURE 771
º AnnulusRadius (input control) ............................................number double / long
Radius (half width) of the the annulus.
Default Value : 10.0
Value Suggestions : AnnulusRadius ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 AnnulusRadius 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : AnnulusRadius Radius
º Width (input control) ...............................................................extent.x long
Width of the image to be processed subsequently.
Default Value : 512
Value Suggestions : Width ¾128, 160, 192, 256, 320, 384, 512, 640, 768
Typical Range of Values : 0 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
º Height (input control) ..............................................................extent.y long
Height of the image to be processed subsequently.
Default Value : 512
Value Suggestions : Height ¾120, 128, 144, 240, 256, 288, 480, 512, 576
Typical Range of Values : 0 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
º Interpolation (input control) ...............................................string const char *
Type of interpolation to be used.
Default Value : ’nearest neighbor’
Value List : Interpolation ¾’nearest neighbor’, ’bilinear’, ’bicubic’
º MeasureHandle (output control) ..............................................measure id long *
Measure object handle.
Result
If the parameter values are correct, the operator gen measure arc returns the value H MSG TRUE. Otherwise
an exception handling is raised.
Parallelization Information
gen measure arc is reentrant and processed without parallelization.
draw circle
Possible Predecessor Functions
Possible Successor Functions
T measure pos, T measure pairs
edges sub pix
Sub-pixel operators
Alternatives
Module
gen measure rectangle2 ( double Row, double Column, double Phi,
double Length1, double Length2, long Width, long Height,
const char *Interpolation, long *MeasureHandle )
Prepare the extraction of straight edges perpendicular to a rectangle.
gen measure rectangle2 prepares the extraction of straight edges which lie perpendicular to the major axis
of a rectangle. The center of the rectangle is passed in the parameters Row and Column, the direction of the major
axis of the rectangle in Phi, and the length of the two axes, i.e., half the diameter of the rectangle, in Length1
and Length2.
The edge extraction algorithm is described in the documentation of the operator T measure pos. As discussed
there, different types of interpolation can be used for the calculation of the one-dimensional gray value profile. For
Interpolation = ’nearest neighbor’, the gray values in the measurement are obtained from the gray values
HALCON 6.0

772 CHAPTER 12. TOOLS
of the closest pixel, i.e., by constant interpolation. For Interpolation = ’bilinear’, bilinear interpolation is
used, while for Interpolation = ’bicubic’, bicubic interpolation is used.
With gen measure rectangle2, all computations which can be used for multiple measurements are removed
from the actual measurement. To effect this, an optimized data structure, a so-called measure object,
is constructed and returned in MeasureHandle. In order to perform the measurement at the optimum
speed, the size of the images for which subsequent measurements will be made must already be specified in
gen measure rectangle2 with the parameters Width and Height. This technique increases the speed of
the actual measurement significantly.
Parameter
º Row (input control) ...............................................rectangle2.center.y double / long
Row coordinate of the center of the rectangle.
Default Value : 50.0
Value Suggestions : Row ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 Row 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Column (input control) ...........................................rectangle2.center.x double / long
Column coordinate of the center of the rectangle.
Default Value : 100.0
Value Suggestions : Column ¾10.0, 20.0, 50.0, 100.0, 200.0, 300.0, 400.0, 500.0
Typical Range of Values : 0.0 Column 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Phi (input control) ..............................................rectangle2.angle.rad double / long
Angle of longitudinal axis to horizontal (radians).
Default Value : 0.0
Value Suggestions : Phi ¾-1.178097, -0.785398, -0.392699, 0.0, 0.392699, 0.785398, 1.178097
Typical Range of Values : -1.178097 Phi 1.178097 (lin)
Minimal Value Step : 0.001
Recommended Value Step : 0.1
Restriction : ´ pi Phiµ ´Phi piµ
º Length1 (input control) ...........................................rectangle2.hwidth double / long
Half width.
Default Value : 200.0
Value Suggestions : Length1 ¾3.0, 5.0, 10.0, 15.0, 20.0, 50.0, 100.0, 200.0, 300.0, 500.0
Typical Range of Values : 0.0 Length1 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Length2 (input control) ..........................................rectangle2.hheight double / long
Half height.
Default Value : 100.0
Value Suggestions : Length2 ¾1.0, 2.0, 3.0, 5.0, 10.0, 15.0, 20.0, 50.0, 100.0, 200.0
Typical Range of Values : 0.0 Length2 511.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
Restriction : Length2 Length1
º Width (input control) ...............................................................extent.x long
Width of the image to be processed subsequently.
Default Value : 512
Value Suggestions : Width ¾128, 160, 192, 256, 320, 384, 512, 640, 768
Typical Range of Values : 0 Width 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
HALCON/C Reference Manual / 2000-11-15

12.11. MEASURE 773
º Height (input control) ..............................................................extent.y long
Height of the image to be processed subsequently.
Default Value : 512
Value Suggestions : Height ¾120, 128, 144, 240, 256, 288, 480, 512, 576
Typical Range of Values : 0 Height 1024 (lin)
Minimal Value Step : 1
Recommended Value Step : 16
º Interpolation (input control) ...............................................string const char *
Type of interpolation to be used.
Default Value : ’nearest neighbor’
Value List : Interpolation ¾’nearest neighbor’, ’bilinear’, ’bicubic’
º MeasureHandle (output control) ..............................................measure id long *
Measure object handle.
Result
If the parameter values are correct the operator gen measure rectangle2 returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
gen measure rectangle2 is reentrant and processed without parallelization.
draw rectangle2
Possible Predecessor Functions
Possible Successor Functions
T measure pos, T measure pairs, T measure thresh
edges sub pix
Sub-pixel operators
Alternatives
Module
T measure pairs ( Hobject Image, Htuple MeasureHandle, Htuple Sigma,
Htuple Threshold, Htuple Transition, Htuple Select, Htuple *RowEdgeFirst,
Htuple *ColumnEdgeFirst, Htuple *AmplitudeFirst, Htuple *RowEdgeSecond,
Htuple *ColumnEdgeSecond, Htuple *AmplitudeSecond, Htuple *IntraDistance,
Htuple *InterDistance )
Extract straight edge pairs perpendicular to a rectangle.
T measure pairs serves to extract straight edge pairs which lie perpendicular to the major axis of a rectangle.
The extraction algorithm is identical to T measure pos. In addition the edges are grouped to pairs: If
Transition = ’positive’, the edge points with a dark-to-light transition in the direction of the major axis of
the rectangle are returned in RowEdgeFirst and ColumnEdgeFirst. In this case, the corresponding edges
with a light-to-dark transition are returned in RowEdgeSecond and ColumnEdgeSecond. IfTransition =
’negative’, the behavior is exactly opposite. If Transition = ’all’, the first detected edge defines the transition
for RowEdgeFirst and ColumnEdgeFirst. If more than one edge with the same transition is found, the first
one is used as a pair element. Finally, it is possible to select which edge pairs are returned. If Select is set to
’all’, all edge pairs are returned. If it is set to ’first’, only the first of the extracted edge pairs is returned, while it
is set to ’last’, only the last one is returned.
The extracted edges are returned as single points which lie on the major axis of the rectangle. The corresponding
edge amplitudes are returned in AmplitudeFirst and AmplitudeSecond. In addition, the distance between
each edge pair is returned in IntraDistance and the distance between consecutive edge pairs is returned
in InterDistance. Here, IntraDistance[i] corresponds to the distance between EdgeFirst[i] and EdgeSecond[i],
while InterDistance[i] corresponds to the distance between EdgeSecond[i] and EdgeFirst[i+1], i.e., the
tuple InterDistance contains one element less than the tuples of the edge pairs.
Attention
T measure pairs only returns meaningful results if the assumptions that the edges are straight and perpendicular
to the major axis of the rectangle are fulfilled. Thus, it should not be used to extract edges from curved objects,
HALCON 6.0

774 CHAPTER 12. TOOLS
for example. Furthermore, the user should ensure that the rectangle is as close to perpendicular as possible to the
edges in the image.
Parameter
º Image (input object) ...........................................singlechannel-image Hobject : byte
Input image.
º MeasureHandle (input control) .........................................measure id Htuple . long
Measure object handle.
º Sigma (input control) .....................................................number Htuple . double
Sigma of gaussian smoothing.
Default Value : 1.0
Value Suggestions : Sigma ¾0.4, 0.6, 0.8, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 7.0, 10.0
Typical Range of Values : 0.4 Sigma 100 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.4
º Threshold (input control) ................................................number Htuple . double
Minimum edge amplitude.
Default Value : 30.0
Value Suggestions : Threshold ¾5.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 90.0, 110.0
Typical Range of Values : 1 Threshold 255 (lin)
Minimal Value Step : 0.5
Recommended Value Step : 2
º Transition (input control) ...........................................string Htuple . const char *
Light/dark or dark/light edge.
Default Value : ’all’
Value List : Transition ¾’all’, ’positive’, ’negative’
º Select (input control) .................................................string Htuple . const char *
Selection of end points.
Default Value : ’all’
Value List : Select ¾’all’, ’first’, ’last’
º RowEdgeFirst (output control) ....................................point.y-array Htuple . double *
Row coordinate of the center of the edge.
º ColumnEdgeFirst (output control) ................................point.x-array Htuple . double *
Column coordinate of the center of the edge.
º AmplitudeFirst (output control) ....................................real-array Htuple . double *
Edge amplitude of found edges (with sign).
º RowEdgeSecond (output control) ...................................point.y-array Htuple . double *
Row coordinate of the center of the edge.
º ColumnEdgeSecond (output control) ..............................point.x-array Htuple . double *
Column coordinate of the center of the edge.
º AmplitudeSecond (output control) ...................................real-array Htuple . double *
Edge amplitude of found edges (with sign).
º IntraDistance (output control) ......................................real-array Htuple . double *
Distance between edges of an edge pair.
º InterDistance (output control) ......................................real-array Htuple . double *
Distance between consecutive edge pairs.
Result
If the parameter values are correct the operator T measure pairs returns the value H MSG TRUE. Otherwise
an exception handling is raised.
Parallelization Information
T measure pairs is reentrant and processed without parallelization.
gen measure rectangle2
close measure
Possible Predecessor Functions
Possible Successor Functions
HALCON/C Reference Manual / 2000-11-15

12.11. MEASURE 775
edges sub pix, T measure pos
Sub-pixel operators
Alternatives
Module
T measure pos ( Hobject Image, Htuple MeasureHandle, Htuple Sigma,
Htuple Threshold, Htuple Transition, Htuple Select, Htuple *RowEdge,
Htuple *ColumnEdge, Htuple *Amplitude, Htuple *Distance )
Extract straight edges perpendicular to a rectangle.
T measure pos extracts straight edges which lie perpendicular to the major axis of a rectangle.
The algorithm works by averaging the gray values in “slices” perpendicular to the major axis of the rectangle in
order to obtain a one-dimensional edge profile. The sampling is done at subpixel positions in the image Image
at integer row and column distances (in the coordinate frame of the rectangle) from the center of the rectangle.
Since this involves some calculations which can be used repeatedly in several mesurements, the operator
gen measure rectangle2 is used to perform these calculations only once, and thus to increase the speed of
T measure pos significantly. Since there is a trade-off between accuracy and speed in the subpixel calculations
of the gray values, and thus in the accuracy of the extracted edge positions, different interpolation schemes can
be selected in gen measure rectangle2. (The interpolation only influences rectangles not aligned with the
image axes.) The measure object generated with gen measure rectangle2 is passed in MeasureHandle.
After the one-dimensional edge profile has been calculated, subpixel edge locations are computed by convolving
the profile with the derivatives of a Gaussian smoothing kernel of standard deviation Sigma. Salient edges can be
selected with the parameter Threshold, which constitutes a thresold on the amplitude, i.e., the absolute value of
the first derivative, of the edge. Additionally, it is possible to select only positive edges, i.e., edges which constitute
a dark-to-light transition in the direction of the major axis of the rectangle (Transition = ’positive’), only
negative edges, i.e., light-to-dark transitions (Transition = ’negative’), or both types of edges (Transition
= ’all’). Finally, it is possible to select which edge points are returned. If Select is set to ’all’, all edge points
are returned. If it is set to ’first’, only the first of the extracted edge points is returned, while it is set to ’last’, only
the last one is returned.
The extracted edges are returned as single points which lie on the major axis of the rectangle in
(RowEdge,ColumnEdge). The corresponding edge amplitudes are returned in Amplitude. In addition, the
distance between consecutive edge points is returned in Distance. Here, Distance[i] corresponds to the distance
between Edge[i] and Edge[i+1], i.e., the tuple Distance contains one element less than the tuples RowEdge and
ColumnEdge.
Attention
T measure pos only returns meaningful results if the assumptions that the edges are straight and perpendicular
to the major axis of the rectangle are fulfilled. Thus, it should not be used to extract edges from curved objects,
for example. Furthermore, the user should ensure that the rectangle is as close to perpendicular as possible to the
edges in the image.
Parameter
º Image (input object) ...........................................singlechannel-image Hobject : byte
Input image.
º MeasureHandle (input control) .........................................measure id Htuple . long
Measure object handle.
º Sigma (input control) .....................................................number Htuple . double
Sigma of gaussian smoothing.
Default Value : 1.0
Value Suggestions : Sigma ¾0.4, 0.6, 0.8, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 7.0, 10.0
Typical Range of Values : 0.4 Sigma 100 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.4
HALCON 6.0

776 CHAPTER 12. TOOLS
º Threshold (input control) ................................................number Htuple . double
Minimum edge amplitude.
Default Value : 30.0
Value Suggestions : Threshold ¾5.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 90.0, 110.0
Typical Range of Values : 1 Threshold 255 (lin)
Minimal Value Step : 2
Recommended Value Step : 0.5
º Transition (input control) ...........................................string Htuple . const char *
Light/dark or dark/light edge.
Default Value : ’all’
Value List : Transition ¾’all’, ’positive’, ’negative’
º Select (input control) .................................................string Htuple . const char *
Selection of end points.
Default Value : ’all’
Value List : Select ¾’all’, ’first’, ’last’
º RowEdge (output control) ...........................................point.y-array Htuple . double *
Row coordinate of the center of the edge.
º ColumnEdge (output control) .......................................point.x-array Htuple . double *
Column coordinate of the center of the edge.
º Amplitude (output control) ...........................................real-array Htuple . double *
Edge amplitude of found edges (with sign).
º Distance (output control) ............................................real-array Htuple . double *
Distance between consecutive edges.
Result
If the parameter values are correct the operator T measure pos returns the value H MSG TRUE. Otherwise an
exception handling is raised.
Parallelization Information
T measure pos is reentrant and processed without parallelization.
gen measure rectangle2
close measure
edges sub pix, T measure pairs
Sub-pixel operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
T measure projection ( Hobject Image, Htuple MeasureHandle,
Htuple *GrayValues )
Extract a gray value profile perpendicular to a rectangle.
T measure projection extracts a one-dimensional gray value profile perpendicular to a rectangle. This is
done by averaging the gray values in “slices” perpendicular to the major axis of the rectangle. The sampling is
done at subpixel positions in the image Image at integer row and column distances (in the coordinate frame of the
rectangle) from the center of the rectangle. Since this involves some calculations which can be used repeatedly in
several projections, the operator gen measure rectangle2 is used to perform these calculations only once,
and thus to increase the speed of T measure projection significantly. Since there is a trade-off between
accuracy and speed in the subpixel calculations of the gray values, different interpolation schemes can be selected
in gen measure rectangle2 (the interpolation only influences rectangles not aligned with the image axes).
The measure object generated with gen measure rectangle2 is passed in MeasureHandle.
Parameter
º Image (input object) ...........................................singlechannel-image Hobject : byte
Input image.
HALCON/C Reference Manual / 2000-11-15

12.11. MEASURE 777
º MeasureHandle (input control) .........................................measure id Htuple . long
Measure object handle.
º GrayValues (output control) ......................................number-array Htuple . double *
Gray value profile.
Result
If the parameter values are correct the operator T measure projection returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
T measure projection is reentrant and processed without parallelization.
gen measure rectangle2
close measure
gray projections
Sub-pixel operators
Possible Predecessor Functions
Possible Successor Functions
Alternatives
Module
T measure thresh ( Hobject Image, Htuple MeasureHandle, Htuple Sigma,
Htuple Threshold, Htuple Select, Htuple *RowThresh, Htuple *ColumnThresh,
Htuple *Distance )
Extracting points with a particular grey value along a rectangle.
T measure thresh extracts points for which the gray value within an one-dimensional gray value profile is
equal to the specified threshold Threshold. The gray value profile is projected onto the major axis of the measure
rectangle which is passed with the parameter MeasureHandle, so the threshold points calculated within the gray
value profile correspond to certain image coordinates on the rectangle’s major axis. These coordinates are returned
as the operator results in RowThresh and ColumnThresh.
If the gray value profile intersects the threshold line for several times, the parameter Select determines which
values to return. Possible settings are ’first’, ’last’, ’first last’ (first and last) or ’all’. For the last two cases
Distance returns the distances between the calculated points.
The gray value profile is created by averaging the gray values along all line segments, which are defined by the
measure rectangle as follows:
1. The segments are perpendicular to the major axis of the rectangle,
2. they have an integer distance to the center of the rectangle,
3. the rectangle bounds the segments.
For every line segment, the average of the gray values of all points with an integer distance to the major axis is
calculated. Due to translation and rotation of the measure rectangle with respect to the image coordinates the input
image Image is in general sampled at subpixel positions.
Since this involves some calculations which can be used repeatedly in several projections, the operator
gen measure rectangle2 is used to perform these calculations only once in advance. Here, the measure
object MeasureHandle is generated and different interpolation schemes can be selected.
Attention
T measure thresh only returns meaningful results if the assumptions that the edges are straight and perpendicular
to the major axis of the rectangle are fulfilled. Thus, it should not be used to extract edges from curved
objects, for example. Furthermore, the user should ensure that the rectangle is as close to perpendicular as possible
to the edges in the image.
HALCON 6.0

778 CHAPTER 12. TOOLS
Parameter
º Image (input object) ...........................................singlechannel-image Hobject : byte
Input image.
º MeasureHandle (input control) .........................................measure id Htuple . long
Measure object handle.
º Sigma (input control) .....................................................number Htuple . double
Sigma of gaussian smoothing.
Default Value : 1.0
Value Suggestions : Sigma ¾0.0, 0.4, 0.6, 0.8, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 7.0, 10.0
Typical Range of Values : 0.4 Sigma 100 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Sigma 0.0
º Threshold (input control) ................................................number Htuple . double
Threshold.
Default Value : 128.0
Typical Range of Values : 0 Threshold 255 (lin)
Minimal Value Step : 1
Recommended Value Step : 0.5
º Select (input control) .................................................string Htuple . const char *
Selection of points.
Default Value : ’all’
Value List : Select ¾’all’, ’first’, ’last’, ’first last’
º RowThresh (output control) ........................................point.y-array Htuple . double *
Row coordinates of points with threshold value.
º ColumnThresh (output control) ....................................point.x-array Htuple . double *
Column coordinates of points with threshold value.
º Distance (output control) ............................................real-array Htuple . double *
Distance between consecutive points.
Result
If the parameter values are correct the operator T measure thresh returns the value H MSG TRUE. Otherwise,
an exception handling is raised.
Parallelization Information
T measure thresh is reentrant and processed without parallelization.
gen measure rectangle2
close measure
Possible Predecessor Functions
Possible Successor Functions
Alternatives
T measure pos, edges sub pix, T measure pairs
Sub-pixel operators
Module
12.12 OCR
append ocr trainf ( Hobject Character, Hobject Image,
const char *Class, const char *FileName )
T append ocr trainf ( Hobject Character, Hobject Image, Htuple Class,
Htuple FileName )
Adding characters to a training file.
HALCON/C Reference Manual / 2000-11-15

12.12. OCR 779
The operator (T )append ocr trainf serves to prepare the training with the operator
(T )trainf ocr class box. Hereby regions, representing characters, including their grayvalues (region
and pixel) and the corresponding classname will be written into a file. An arbitrary number of regions
within one image is supported. For each character (region) in Character the corresponding class name must be
specified in Class. The grayvalues are passed via the parameter Image. The file name can be chosen at will. In
contrast to (T )write ocr trainf the characters are appended to the file. If the file does not exist a new file
is generated.
Parameter
º Character (input object) ..................................................region(-array) Hobject
Characters to be trained.
º Image (input object) ..............................................................image Hobject
Grayvalues of the characters.
º Class (input control) ..........................................string(-array) (Htuple .) const char *
Class (name) of the characters.
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the training file.
Default Value : ”train ocr”
Example
char
char
name[128];
class[128];
read_image(&Image,"character.tiff");
bin_threshold(Image,&Dark);
connection(Dark,&Character);
count_obj(Character,&num);
create_tuple(&Class,num);
open_window(0,0,-1,-1,0,"","",&WindowHandle);
set_color(WindowHandle,"red");
for (i=0; i

780 CHAPTER 12. TOOLS
close all ocrs ( )
Destroy all OCR classificators.
close all ocrs deletes all OCR classificators and frees the used memory space. All the trained data will be
lost.
Attention
Since all classificators are closed by close all ocrs all handles become invalid.
Result
If it is possible to close the OCR classificators the operator close all ocrs returns the value H MSG TRUE.
Otherwise an exception handling is raised.
Parallelization Information
close all ocrs is processed completely exclusively without parallelization.
close ocr
Optical character recognition
Alternatives
Module
close ocr ( long OcrHandle )
Deallocation of the memory of an OCR classifier.
The operator close ocr deallocates the memory of the classifier having the number OcrHandle. Hereby
all corresponding data will be deleted. However, if necessary, they can be saved in advance using the operator
write ocr. The number OcrHandle will be invalid after the call; but later the system can use it again for new
classifiers.
Attention
All data of the classifier will be deleted in main memory (not on the hard disk).
Parameter
º OcrHandle (input control) ..............................................................ocr long
ID of the OCR classifier to be deleted.
Example
HTuple
long
OcrHandle,Class,Confidence;
orc_handle;
read_ocr("testnet",&orc_handle);
/* image processing */
create_tuple(&OcrHandle,1);
set_i(OcrHandle,orc_handle,0);
T_do_ocr_multi(Character,Image,OcrHandle,&Class,&Confidence);
close_ocr(orc_handle);
Result
If the parameter OcrHandle is valid, the operator close ocr returns the value H MSG TRUE. Otherwise an
exception will be raised.
Parallelization Information
close ocr is reentrant and processed without parallelization.
(T )write ocr trainf
read ocr
Optical character recognition
Possible Predecessor Functions
Possible Successor Functions
Module
HALCON/C Reference Manual / 2000-11-15

12.12. OCR 781
T concat ocr trainf ( Htuple SingleFiles, Htuple ComposedFile )
Concatenation of trainings files.
The operator T concat ocr trainf stores all characters which are contained in the files SingleFiles into
a new file with the name ComposedFile.
Parameter
º SingleFiles (input control) ..................................filename-array Htuple . const char *
Name of the single training files.
Default Value : ”
º ComposedFile (input control) ......................................filename Htuple . const char *
Name of the composed training file.
Default Value : ’all characters’
Result
If the parameters are correct, the operator T concat ocr trainf returns the value H MSG TRUE. Otherwise
an exception will be raised.
Parallelization Information
T concat ocr trainf is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
(T )write ocr trainf, (T )append ocr trainf
Possible Successor Functions
(T )trainf ocr class box, T info ocr class box, write ocr, (T )do ocr multi,
T do ocr single
Module
Optical character recognition
T create ocr class box ( Htuple WidthPattern, Htuple HeightPattern,
Htuple Interpolation, Htuple Features, Htuple Character,
Htuple *OcrHandle )
Creating a new OCR-classifier.
The operator T create ocr class box creates a new OCR classifier. For a description of this classifier
see operator learn class box. This classifier must then be trained with the help of the operators
(T )traind ocr class box or (T )trainf ocr class box.
The parameters WidthPattern and HeightPattern indicate the size of the input-layer of the network. This
size is used for the features ’projection horizontal’, ’projection vertical’ and ’pixel’. The bigger it is, the more
characters can be distinguished. Hereby the amount of time necessary for the training (as well as the number of
training random samples) and the time necessary for the recognition, however, will increase as well. The larger
the input level, the more specifical the training is for a certain font. The parameter Interpolation indicates
the interpolation mode concerning the adaptation of characters in the image to the network. For more detailed
information on this parameter see also affine trans image.
The parameter Character determines all the characters which have to be recognized. Normally the transmitted
strings consist of one character (e.g. alphabet). But also strings of any length can be learned. The number of
distinguishable characters (number of strings in Character) is limited to 2048.
The parameter Features helps to chose additional features besides grayvalues in order to recognize
characters. By using ’default’ the features ’ratio’, ’projection horizontal’, ’projection vertical’, ’moments
region 2nd invar’,and’moments region 2nd rel invar’ will be set.
The following features are available:
’ratio’ Ratio of the character.
’width’ Width of the character (not invariant to scaling).
’height’ Height of the character (not invariant to scaling).
HALCON 6.0

782 CHAPTER 12. TOOLS
’zoom factor’ Difference in size between the current character and the values of WidthPattern and
HeightPattern (not invariant to scaling).
’foreground’ Relative number of pixels in the foreground.
’foreground grid 9’ Relative number of foreground pixels in a ¿ ¢ ¿ grid within the surrounding rectangle of the
character.
’foreground grid 16’ Relative number of foreground pixels in a ¢ grid within the surrounding rectangle of
the character.
’anisometry’ Form feature anisometry.
’compactness’ Form feature compactness.
’convexity’ Form feature convexity.
’moments region 2nd invar’ Normed 2nd geometric moments of the region. See also
moments region 2nd invar.
’moments region 2nd rel invar’ Normed 2nd relativ geometric moments of the region. See also
moments region 2nd rel invar.
’moments region 3rd invar’ Normed 3rd geometric moments of the region. See also
moments region 3rd invar.
’moments central’ Normed central geometric moments of the region. See also moments region central.
’phi’ Orientation (angle) of the character.
’num connect’ Number of connecting components.
’num holes’ Number of holes.
’projection horizontal’ Horizontal projection of the grayvalues.
’projection horizontal invar’ Horizontal projection of the grayvalues with are automatically scaled to maximum
range.
’projection vertical’ Vertical projection of the grayvalues.
’projection vertical invar’ Vertical projection of the grayvalues with are automatically scaled to maximum
range.
’cooc’ Values of the binary cooccurrence matrix.
’moments gray plane’ Normed grayvalue moments and the angles of the grayvalue level.
’num runs’ Number of chords in the region normed to the area.
’chord histo’ Frequency of the chords per row.
’pixel’ Grayvalue of the character.
’pixel invar’ Grayvalues of the character with automatic maximal scaling of the gray values.
Parameter
º WidthPattern (input control) ..............................................integer Htuple . long
Width of the input layer of the network.
Default Value : 8
Value Suggestions : WidthPattern ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20
Typical Range of Values : 1 WidthPattern 100
º HeightPattern (input control) .............................................integer Htuple . long
Height of the input layer of the network.
Default Value : 10
Value Suggestions : HeightPattern ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20
Typical Range of Values : 1 HeightPattern 100
º Interpolation (input control) .............................................integer Htuple . long
Interpolation mode concerning scaling of characters.
Default Value : 0
Value List : Interpolation ¾0, 1, 2
HALCON/C Reference Manual / 2000-11-15

12.12. OCR 783
º Features (input control) .......................................string(-array) Htuple . const char *
Additional features.
Default Value : ’default’
Value List : Features ¾’default’, ’zoom factor’, ’ratio’, ’width’, ’height’, ’foreground’,
’foreground grid 9’, ’foreground grid 16’, ’anisometry’, ’compactness’, ’convexity’,
’moments region 2nd invar’, ’moments region 2nd rel invar’, ’moments region 3rd invar’,
’moments central’, ’phi’, ’num connect’, ’num holes’, ’projection horizontal’, ’projection vertical’,
’projection horizontal invar’, ’projection vertical invar’, ’chord histo’, ’num runs’, ’pixel’, ’pixel invar’,
’cooc’, ’moments gray plane’
º Character (input control) .......................................string-array Htuple . const char *
All characters of a set.
Default Value : ’[’a’,’b’,’c’]’
º OcrHandle (output control) ...................................................ocr Htuple . long *
ID of the created OCR classifier.
Example
HTuple WidthPattern,HeightPattern,Interpolation,
Features,OcrHandle;
create_tuple(&WidthPattern,1);
set_i(WidthPattern,8,0);
create_tuple(&HeightPattern,1);
set_i(HeightPattern,10,0);
create_tuple(&Interpolation,1);
set_i(Interpolation,1,0);
create_tuple(&Features,1);
set_s(Features,"default",0);
create_tuple(&Character,26+26+10);
set_s(Character,"a",0);
set_s(Character,"b",1);
/* ... */
set_s(Character,"A",27);
set_s(Character,"B",28);
/* ... */
set_s(Character,"1",53);
set_s(Character,"2",54);
/* ... */
T_create_ocr_class_box(WidthPattern,HeightPattern,Interpolation,
Features,Character,&OcrHandle);
Result
If the parameters are correct, the operator T create ocr class box returns the value H MSG TRUE. Otherwise
an exception will be raised.
Parallelization Information
T create ocr class box is processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )traind ocr class box, (T )trainf ocr class box, T info ocr class box, write ocr,
T ocr change char
See Also
affine trans image, T ocr change char, moments region 2nd invar,
moments region 2nd rel invar, moments region 3rd invar, moments region central
Optical character recognition
Module
HALCON 6.0

784 CHAPTER 12. TOOLS
do ocr multi ( Hobject Character, Hobject Image, long OcrHandle,
char *Class, double *Confidence )
T do ocr multi ( Hobject Character, Hobject Image, Htuple OcrHandle,
Htuple *Class, Htuple *Confidence )
Classification of characters.
The operator (T )do ocr multi assigns a class to every Character (character). For grayvalue features
the grayvalues from the surrounding rectangles of the regions are used. The grayvalues will be taken from the
parameter Image. For each character the corresponding class will be returned in Class and a confidence value
will be returned in Confidence. The confidence value indicates the similarity between the input pattern and the
assigned character.
Parameter
º Character (input object) ..................................................region(-array) Hobject
Characters to be recognized.
º Image (input object) ..............................................................image Hobject
Grayvalues for the characters.
º OcrHandle (input control) ....................................................ocr (Htuple .) long
ID of the OCR classifier.
º Class (output control) ..............................................string(-array) (Htuple .) char *
Class (name) of the characters.
Parameter Number : Class Character
º Confidence (output control) .......................................real(-array) (Htuple .) double *
Confidence values of the characters.
Parameter Number : Confidence Character
Example
char Class[128];
long orc_handle;
read_ocr("testnet",&orc_handle);
read_image(&Image,"character.tiff");
bin_threshold(Image,&Dark);
connection(Dark,&Character);
count_obj(Character,&num);
open_window(0,0,-1,-1,0,"","",&WindowHandle);
for (i=0; i

12.12. OCR 785
T do ocr single ( Hobject Character, Hobject Image, Htuple OcrHandle,
Htuple *Classes, Htuple *Confidences )
Classification of a character.
The operator T do ocr single assigns classes to the Character (characters). For grayvalue features grayvalues
of the surrounding rectangles of the regions will be used. The grayvalues will be taken from the paramter
Image. For each character the two classes with the highest confidencenses will be returned in Classes. Thecorresponding
confidences will be returned in Confidences. The confidence value indicates the similarity between
the input pattern and the assigned character.
Parameter
º Character (input object) .........................................................region Hobject
Character to be recognized.
º Image (input object) ..............................................................image Hobject
Grayvalues of the characters.
º OcrHandle (input control) ......................................................ocr Htuple . long
ID of the OCR classifier.
º Classes (output control) ..............................................string-array Htuple . char *
Classes (names) of the characters.
Parameter Number : 2
º Confidences (output control) ........................................real-array Htuple . double *
Confidence values of the characters.
Parameter Number : 2
Example
HTuple
long
HTuple
Classes,Confidences;
orc_handle;
OcrHandle;
read_ocr("testnet",&orc_handle);
create_tuple(&OcrHandle,1);
set_i(OcrHandle,orc_handle,0);
read_image(&Image,"character.tiff");
bin_threshold(Image,&Dark);
connection(Dark,&Character);
count_obj(Character,&num);
open_window(0,0,-1,-1,0,"","",&WindowHandle);
for (i=0; i

786 CHAPTER 12. TOOLS
write ocr
Optical character recognition
See Also
Module
T info ocr class box ( Htuple OcrHandle, Htuple *WidthPattern,
Htuple *HeightPattern, Htuple *Interpolation, Htuple *WidthMaxChar,
Htuple *HeightMaxChar, Htuple *Features, Htuple *Characters )
Information about an OCR classifier.
The operator T info ocr class box returns some information about an OCR classifier. The parameters are
equivalent to those of T create ocr class box. The parameters WidthMaxChar and HeightMaxChar
indicate the extension of the largest trained character. These values can be used to control the segmentation.
Parameter
º OcrHandle (input control) ......................................................ocr Htuple . long
ID of the OCR classifier.
º WidthPattern (output control) ............................................integer Htuple . long *
Width of the scaled characters.
º HeightPattern (output control) ..........................................integer Htuple . long *
Height of the scaled characters.
º Interpolation (output control) ..........................................integer Htuple . long *
Interpolation mode for scaling the characters.
º WidthMaxChar (output control) ............................................integer Htuple . long *
Width of the largest trained character.
º HeightMaxChar (output control) ..........................................integer Htuple . long *
Height of the largest trained character.
º Features (output control) .............................................string-array Htuple . char *
Used features.
º Characters (output control) ..........................................string-array Htuple . char *
All characters of the set.
Example
HTuple
OcrHandle,WidthPattern,HeightPattern,Interpolation,
WidthMaxChar,HeightMaxChar,Features,Characters;
T_info_ocr_class_box(OcrHandle,&WidthPattern,&HeightPattern,&Interpolation,
&WidthMaxChar,&HeightMaxChar,&Features,&Characters);
printf("NetSize: %d x %d\n",get_i(WidthPattern,0),get_i(HeightPattern,0));
printf("MaxChar: %d x %d\n",get_i(WidthMaxChar,0),get_i(HeightMaxChar,0));
printf("Interpolation: %d\n",get_i(Interpolation,0));
printf("Features: ");
for (i=0; i

12.12. OCR 787
write ocr
Optical character recognition
Possible Successor Functions
Module
T ocr change char ( Htuple OcrHandle, Htuple Character )
Defining a new conversion table for the characters.
The operator T ocr change char establishes a new look-up table for the characters. Hereby the number of
strings of Character must be the same as of the classifier OcrHandle. In order to enlarge the font, the
operator T ocr change char may be used as follows: More characters than actually needed will be indicated
when creating a network using (T create ocr class box). The last Ò characters will not be used so far. If
more characters are needed at a later stage, these unused characters will be allocated and then trained with the help
of the operator T ocr change char.
Parameter
º OcrHandle (input control) ......................................................ocr Htuple . long
ID of the OCR-network to be changed.
º Character (input control) .......................................string-array Htuple . const char *
New assign of characters.
Default Value : ’[’a’,’b’,’c’]’
Example
HTuple Character1, Character2, OcrHandle;
create_tuple(&Character1,26);
set_s(Character1,"a",0);
set_s(Character1,"b",1);
/* set parameter values */
T_create_ocr_net(WidthPattern,HeightPattern,Interpolation,
Features,HiddenLayer,Init,Character1,&OcrHandle);
/* later... */
create_tuple(&Character2,26);
set_s(Character2,"alpha",0);
set_s(Character2,"beta",1);
T_ocr_change_char(OcrHandle,Character2);
Result
If the number of characters in Character is identical with the number of the characters of the network, the
operator T ocr change char returns the value H MSG TRUE. Otherwise an exception will be raised.
Parallelization Information
T ocr change char is processed completely exclusively without parallelization.
read ocr
Possible Predecessor Functions
Possible Successor Functions
(T )do ocr multi, T do ocr single, write ocr
Optical character recognition
Module
T ocr get features ( Hobject Character, Htuple OcrHandle,
Htuple *FeatureVector )
Access the features which correspond to a character.
HALCON 6.0

788 CHAPTER 12. TOOLS
The operator T ocr get features calculates the features for the given Character. The type and number of
features is determined by the classifier OcrHandle. FeatureVector contains the same values which are used
inside operators like (T )traind ocr class box or (T )trainf ocr class box.
Parameter
º Character (input object) .........................................................image Hobject
Characters to be trained.
º OcrHandle (input control) ......................................................ocr Htuple . long
ID of the desired OCR-classifier.
º FeatureVector (output control) ......................................real-array Htuple . double *
Feature vector.
Result
If the parameters are correct, the operator T ocr get features returns the value H MSG TRUE. Otherwise
an exception will be raised.
Parallelization Information
T ocr get features is reentrant and processed without parallelization.
Possible Predecessor Functions
T create ocr class box, read ocr, reduce domain, threshold, connection
learn class box
Possible Successor Functions
See Also
(T )trainf ocr class box, (T )traind ocr class box
Optical character recognition
Module
read ocr ( const char *FileName, long *OcrHandle )
Reading of an OCR classifier from a file.
The operator read ocr reads an OCR classifier from a file FileName. This file will hereby be searched in
the directory ($HALCONROOT/ocr/) as well as in the currently used directory. If too many classifiers have been
loaded, an error message will be displayed.
Parameter
º FileName (input control) ...................................................filename const char *
Name of the OCR classifier file.
Default Value : ’testnet’
º OcrHandle (output control) ...........................................................ocr long *
ID of the read OCR classifier.
Result
If the indicated file is available and the format is correct, the operator read ocr returns the value H MSG TRUE.
Otherwise an exception will be raised.
Parallelization Information
read ocr is processed completely exclusively without parallelization.
reset obj db
Possible Predecessor Functions
Possible Successor Functions
(T )do ocr multi, T do ocr single, (T )traind ocr class box, (T )trainf ocr class box
See Also
write ocr, (T )do ocr multi, (T )traind ocr class box, (T )trainf ocr class box
Optical character recognition
Module
HALCON/C Reference Manual / 2000-11-15

12.12. OCR 789
T read ocr trainf ( Hobject *Characters, Htuple TrainFileNames,
Htuple *CharacterNames )
Read training characters from files and convert to images.
T read ocr trainf reads all characters from the specified file names and converts them into images. The
domain is defined according to the foreground of the characters (as specified in (T )write ocr trainf). The
names of the characters are returned in CharacterNames. If more than one file name is given the files are
processed in the order the file names.
Parameter
º Characters (output object) .........................................image-array Hobject * : byte
Images read from file.
º TrainFileNames (input control) ......................filename.named(-array) Htuple . const char *
Names of the training files.
Default Value : ”
º CharacterNames (output control) .....................................string-array Htuple . char *
Names of the read characters.
Result
If the parameter values are correct the operator T read ocr trainf returns the value H MSG TRUE. Otherwise
an exception handling is raised.
Parallelization Information
T read ocr trainf is reentrant and processed without parallelization.
(T )write ocr trainf
Possible Predecessor Functions
Possible Successor Functions
disp image, select obj, zoom image size
(T )read ocr trainf select
(T )trainf ocr class box
Optical character recognition
Alternatives
See Also
Module
read ocr trainf names ( const char *TrainFileNames,
char *CharacterNames, long *CharacterCount )
T read ocr trainf names ( Htuple TrainFileNames,
Htuple *CharacterNames, Htuple *CharacterCount )
Query which characters are stored in a training file.
(T )read ocr trainf names extracts the names and frequency of all characters in the specified training files.
Parameter
º TrainFileNames (input control) ....................filename.named(-array) (Htuple .) const char *
Names of the training files.
Default Value : ”
º CharacterNames (output control) ..................................string(-array) (Htuple .) char *
Names of the read characters.
º CharacterCount (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Number of the characters.
Result
If the parameter values are correct the operator (T )read ocr trainf names returns the value
H MSG TRUE. Otherwise an exception handling is raised.
HALCON 6.0

790 CHAPTER 12. TOOLS
Parallelization Information
(T )read ocr trainf names is reentrant and processed without parallelization.
(T )write ocr trainf
(T )trainf ocr class box
Optical character recognition
Possible Predecessor Functions
See Also
Module
read ocr trainf select ( Hobject *Characters,
const char *TrainFileNames, const char *SearchNames, char *FoundNames )
T read ocr trainf select ( Hobject *Characters, Htuple TrainFileNames,
Htuple SearchNames, Htuple *FoundNames )
Read training specific characters from files and convert to images.
(T )read ocr trainf select reads the characters given in SearchNames from the specified files and
converts them into images. It works simimalr to T read ocr trainf but here the characters which are extracted
can be specified.
Parameter
º Characters (output object) .........................................image-array Hobject * : byte
Images read from file.
º TrainFileNames (input control) ....................filename.named(-array) (Htuple .) const char *
Names of the training files.
Default Value : ”
º SearchNames (input control) ..................................string(-array) (Htuple .) const char *
Names of the characters to be extracted.
Default Value : ’0’
º FoundNames (output control) .......................................string(-array) (Htuple .) char *
Names of the read characters.
Result
If the parameter values are correct the operator (T )read ocr trainf select returns the value
H MSG TRUE. Otherwise an exception handling is raised.
Parallelization Information
(T )read ocr trainf select is reentrant and processed without parallelization.
(T )write ocr trainf
Possible Predecessor Functions
Possible Successor Functions
disp image, select obj, zoom image size
T read ocr trainf
(T )trainf ocr class box
Optical character recognition
Alternatives
See Also
Module
testd ocr class box ( Hobject Character, Hobject Image, long OcrHandle,
const char *Class, double *Confidence )
T testd ocr class box ( Hobject Character, Hobject Image,
Htuple OcrHandle, Htuple Class, Htuple *Confidence )
Training of an OCR classifier by the input of regions.
HALCON/C Reference Manual / 2000-11-15

12.12. OCR 791
The operator (T )testd ocr class box tests the confidence with which a character belongs to a given class.
Any number of regions of an image can be passed. For each character (region) in Character the corresponding
name (class) Class must be specified. The grayvalues are passed in Image. When the operator has finished the
parameter Confidence provides information about how sure a character belongs to the (arbitrary chosen) class.
Parameter
º Character (input object) ..................................................region(-array) Hobject
Characters to be trained.
º Image (input object) ..............................................................image Hobject
Grayvalues for the characters.
º OcrHandle (input control) ....................................................ocr (Htuple .) long
ID of the desired OCR-classifier.
º Class (input control) ..........................................string(-array) (Htuple .) const char *
Class (name) of the characters.
Default Value : ”a”
º Confidence (output control) .......................................real(-array) (Htuple .) double *
Confidence for the character to belong to the class.
Result
If the parameters are correct, the operator (T )testd ocr class box returns the value H MSG TRUE. Otherwise
an exception will be raised.
Parallelization Information
(T )testd ocr class box is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
read ocr, (T )trainf ocr class box, (T )traind ocr class box
Optical character recognition
Module
traind ocr class box ( Hobject Character, Hobject Image,
long OcrHandle, const char *Class, double *AvgConfidence )
T traind ocr class box ( Hobject Character, Hobject Image,
Htuple OcrHandle, Htuple Class, Htuple *AvgConfidence )
Training of an OCR classifier by the input of regions.
The operator (T )traind ocr class box trains the classifier directly via the input of regions in an image.
Any number of regions of an image can be passed. For each character (region) in Character the corresponding
name (class) Class must be specified. The grayvalues are passed in Image. When the procedure has finished
the parameter AvgConfidence provides information about the success of the training: It contains the average
confidence of the trained characters measured by a re-classification. The confidence of mismatched characters is
set to 0 (thus, the average confidence will be decreased significantly).
Parameter
º Character (input object) ..................................................region(-array) Hobject
Characters to be trained.
º Image (input object) ..............................................................image Hobject
Grayvalues for the characters.
º OcrHandle (input control) ....................................................ocr (Htuple .) long
ID of the desired OCR-classifier.
º Class (input control) ..........................................string(-array) (Htuple .) const char *
Class (name) of the characters.
Default Value : ”a”
º AvgConfidence (output control) .........................................real (Htuple .) double *
Average confidence during a re-classification of the trained characters.
Example
HALCON 6.0

792 CHAPTER 12. TOOLS
char name[128];
long orc_handle;
read_ocr("testnet",&orc_handle);
read_image(&Image,"character.tiff");
bin_threshold(Image,&Dark);
connection(Dark,&Character);
count_obj(Character,&num);
open_window(0,0,-1,-1,0,"","",&WindowHandle);
set_color(WindowHandle,"red");
for (i=0; i

12.12. OCR 793
Example
HTuple FileName, OcrHandle, AvgConfidence;
T_create_ocr_class_box(WidthPattern,HeightPattern,Interpolation,
Features,\Character,&OcrHandle);
create_tuple(&FileName,2);
set_s(FileName,"data1",0);
set_s(FileName,"data2",1);
T_trainf_ocr_class_box(OcrHandle,FileName,&AvgConfidence);
Result
If the file name is correct and the data fit the network, the operator (T )trainf ocr class box returns the
value H MSG TRUE. Otherwise an exception will be raised.
Parallelization Information
(T )trainf ocr class box is processed completely exclusively without parallelization.
Possible Predecessor Functions
T create ocr class box, read ocr
Possible Successor Functions
(T )traind ocr class box, write ocr, (T )do ocr multi, T do ocr single
(T )traind ocr class box
Optical character recognition
Alternatives
Module
write ocr ( long OcrHandle, const char *FileName )
Writing an OCR classifier into a file.
The operator write ocr writes the OCR classifier OcrHandle into the file FileName. Since the data of the
classifier will be lost when the program is finished, they have to be stored after the training if the user wants to use
them again at a later execution of the program. The data can then be read with the help of the operator read ocr.
The extension will be added automatically to the parameter FileName.
Attention
The output file FileName must be given without extension.
Parameter
º OcrHandle (input control) ..............................................................ocr long
ID of the OCR classifier.
º FileName (input control) ...................................................filename const char *
Name of the file for the OCR classifier (without extension).
Default Value : ’my ocr’
Result
If the parameter OcrHandle is valid and the indicated file can be written, the operator write ocr returns the
value H MSG TRUE. Otherwise an exception will be raised.
Parallelization Information
write ocr is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )traind ocr class box, (T )trainf ocr class box
Possible Successor Functions
(T )do ocr multi, T do ocr single
See Also
read ocr, (T )do ocr multi, (T )traind ocr class box, (T )trainf ocr class box
Optical character recognition
Module
HALCON 6.0

794 CHAPTER 12. TOOLS
write ocr trainf ( Hobject Character, Hobject Image, const char *Class,
const char *FileName )
T write ocr trainf ( Hobject Character, Hobject Image, Htuple Class,
Htuple FileName )
Storing of trained characters into a file.
The operator (T )write ocr trainf serves to prepare the training with the operator
(T )trainf ocr class box. Hereby regions, representing characters, including their grayvalues (region
and pixel) and the corresponding classname will be written into a file. An arbitrary number of regions
within one image is supported. For each character (region) in Character the corresponding class name must be
specified in Class. The grayvalues are passed via the parameter Image. The file name can be chosen at will.
Parameter
º Character (input object) ..................................................region(-array) Hobject
Characters to be trained.
º Image (input object) ..............................................................image Hobject
Grayvalues of the characters.
º Class (input control) ..........................................string(-array) (Htuple .) const char *
Class (name) of the characters.
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the training file.
Default Value : ”train ocr”
Example
char
HTuple
name[128];
Class,Name;
read_image(&Image,"character.tiff");
bin_threshold(Image,&Dark);
connection(Dark,&Character);
count_obj(Character,&num);
create_tuple(&Class,num);
open_window(0,0,-1,-1,0,"","",&WindowHandle);
set_color(WindowHandle,"red");
for (i=0; i

12.13. OCV 795
Optical character recognition
Module
write ocr trainf image ( Hobject Character, const char *Class,
const char *FileName )
T write ocr trainf image ( Hobject Character, Htuple Class,
Htuple FileName )
Write characters into a training file.
The operator (T )write ocr trainf image is used to prepare the training with the operator
(T )trainf ocr class box. Hereby regions, representing characters, including their grayvalues (region and
pixel) and the corresponding classname will be written into a file. An arbitrary number of regions within one
image is supported. For each character (region) in Character the corresponding class name must be specified in
Class. The file name can be chosen at will. In contrast to (T )write ocr trainf one image per character
is passed. The domain of this image defines the pixels which belong to the character.
Parameter
º Character (input object) ..................................................image(-array) Hobject
Characters to be trained.
º Class (input control) ..........................................string(-array) (Htuple .) const char *
Class (name) of the characters.
º FileName (input control) ..........................................filename (Htuple .) const char *
Name of the training file.
Default Value : ”train ocr”
Result
If the parameters are correct, the operator (T )write ocr trainf image returns the value H MSG TRUE.
Otherwise an exception will be raised.
Parallelization Information
(T )write ocr trainf image is reentrant and processed without parallelization.
Possible Predecessor Functions
threshold, connection, T create ocr class box, read ocr
Possible Successor Functions
(T )trainf ocr class box, T info ocr class box, write ocr, (T )do ocr multi,
T do ocr single
Alternatives
(T )write ocr trainf, (T )append ocr trainf
Optical character recognition
Module
12.13 OCV
close all ocvs ( )
Clear all OCV tools.
close all ocvs closes all OCV tools which have been opened using (T )create ocv proj or read ocv.
All handles are invalid after this call.
Attention
This operator is only for internal use (like e.g. a reset program in HDevelop).
Result
close all ocvs returns always H MSG TRUE.
HALCON 6.0

796 CHAPTER 12. TOOLS
Parallelization Information
close all ocvs is processed completely exclusively without parallelization.
read ocv, (T )create ocv proj
close ocv
Optical character verification
Possible Predecessor Functions
Alternatives
Module
close ocv ( long OCVHandle )
Clear an OCV tool.
close ocv closes an open OCV tool and frees the memory. The OCV tool has been created using
(T )create ocv proj or read ocv. The handle is after this call no longer valid.
Parameter
º OCVHandle (input control) ..............................................................ocv long
Handle of the OCV tool which has to be freed.
Example
read_ocv("ocv_file",&ocv_handle);
for (i=0; i

12.13. OCV 797
The pattern comparison is based on the gray projections: For every traing pattern the horizontal and vertical gray
projections are calculated by summing up the gray values along the rows and columns inside the region of the
pattern. This operation is applied to the training patterns and the test patterns. For the training patterns the result
is stored inside the OCV tool to save runtime while comparing patterns. The OCV is done by comparing the
corresponding projections. The Quality is the similarity of the projections.
Input for (T )create ocv proj are the names of the patterns (PatternNames) which have to be trained.
The number and the names can be chosen arbitrary. In most case only one pattern will be trained, thus only one
name has to be specified. The names will be used when doing the OCV ((T )do ocv simple). It is possible to
specify more names than actually used. These might be trained later.
To close the OCV tool, i.e. to free the memory, the operator close ocv is called.
Parameter
º PatternNames (input control) ................................string(-array) (Htuple .) const char *
List of names for patterns to be trained.
Default Value : ”a”
º OCVHandle (output control) .................................................ocv (Htuple .) long *
Handle of the created OCV tool.
Example
create_ocv_proj("A",&ocv_handle);
draw_region(&ROI,window_handle);
reduce_domain(Image,ROI,&Sample);
traind_ocv_proj(Sample,ocv_handle,"A","single");
Result
(T )create ocv proj returns H MSG TRUE, if the parameters are correct. Otherwise, an exception handling
is raised.
Parallelization Information
(T )create ocv proj is processed completely exclusively without parallelization.
Possible Successor Functions
(T )traind ocv proj, write ocv, close ocv
read ocv
T create ocr class box
Optical character verification
Alternatives
See Also
Module
do ocv simple ( Hobject Pattern, long OCVHandle,
const char *PatternName, const char *AdaptPos, const char *AdaptSize,
const char *AdaptAngle, const char *AdaptGray, double Threshold,
double *Quality )
T do ocv simple ( Hobject Pattern, Htuple OCVHandle, Htuple PatternName,
Htuple AdaptPos, Htuple AdaptSize, Htuple AdaptAngle, Htuple AdaptGray,
Htuple Threshold, Htuple *Quality )
Verification of a pattern using an OCV tool.
(T )do ocv simple evaluates the pattern in (Pattern). Before the evaluation the good-pattern has be trained
by using the operator (T )traind ocv proj. Both patterns should have roughly the same (relative) extent and
shape. To specify which of the trained patterns is used as reference its name is specified in PatternName. The
next four parameters influence the automatic adaption: AdaptPos and AdaptSize refer to the geometry of the
pattern. AdaptPos specifies whether a shift of the position will be adapted automatically. AdaptSize is used
to adapt to changes in the size of the pattern. AdaptAngle is not yet implemented. The parameter AdaptGray
HALCON 6.0

798 CHAPTER 12. TOOLS
controls the adaption to changes of the grayvalues. This comprises additive and multiplicative changes of the
intensity.
The parameter Threshold specifies the minimum difference of the gray values to be treated as an error. In this
case the percentage of wrong pixels is returned. If the value is below 0 the sum of all errors normalized with
respect to the size is returned.
The result of the operator is the Quality of the pattern with a value between 0 and 1. The value 1 corresponds to
a pattern with no faults. The value 0 corresponds to a very big fault.
Parameter
º Pattern (input object) .....................................................image(-array) Hobject
Characters to be verified.
º OCVHandle (input control) ....................................................ocv (Htuple .) long
Handle of the OCV tool.
º PatternName (input control) ..................................string(-array) (Htuple .) const char *
Name of the character.
Default Value : ”a”
º AdaptPos (input control) .............................................string (Htuple .) const char *
Adaption to vertical and horizontal translation.
Default Value : ”true”
Value List : AdaptPos ¾”true”, ”false”
º AdaptSize (input control) ...........................................string (Htuple .) const char *
Adaption to vertical and horizontal scaling of the size.
Default Value : ”true”
Value List : AdaptSize ¾”true”, ”false”
º AdaptAngle (input control) ..........................................string (Htuple .) const char *
Adaption to changes of the orientation (not yet implemented).
Default Value : ”false”
Value List : AdaptAngle ¾”false”
º AdaptGray (input control) ...........................................string (Htuple .) const char *
Adaption to additive and scaling gray value changes.
Default Value : ”true”
Value List : AdaptGray ¾”true”, ”false”
º Threshold (input control) ..............................................number (Htuple .) double
Minimum difference between objects.
Default Value : 10
Value Suggestions : Threshold ¾-1, 0, 1, 5, 10, 15, 20, 30, 40, 50, 60, 80, 100, 150
º Quality (output control) ...........................................real(-array) (Htuple .) double *
Evaluation of the character.
Typical Range of Values : 0.0 Quality 1.0
Result
(T )do ocv simple returns H MSG TRUE, if the handle and the characters are correct. Otherwise, an exception
handling is raised.
Parallelization Information
(T )do ocv simple is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
(T )traind ocr class box, (T )trainf ocr class box, read ocv, threshold, connection,
select shape
Possible Successor Functions
close ocv
See Also
(T )create ocv proj
Module
Optical character verification
HALCON/C Reference Manual / 2000-11-15

12.13. OCV 799
read ocv ( const char *FileName, long *OCVHandle )
Reading an OCV tool from file.
read ocv reads an OCV tool from file. The tool will contain the same information that it contained when saving
it with write ocv. After reading the tool the training can be completed for those patterns which have not been
trained so far. Otherwise a pattern comparison can be applied directly by calling (T )do ocv simple.
As extension ’.ocv’ is used. If this extension is not given with the file name it will be added automatically.
Parameter
º FileName (input control) ...................................................filename const char *
Name of the file which has to be read.
Default Value : ’test ocv’
º OCVHandle (output control) ...........................................................ocv long *
Handle of read OCV tool.
Example
read_ocv("ocv_file",&ocv_handle);
for (i=0; i

800 CHAPTER 12. TOOLS
If more than one pattern has to be trained this can be achieved by multiple calls (one for each pattern) or by calling
(T )traind ocv proj once with all patterns and a tuple of the corresponding names. The result will be in
both cases the same. However using multiple calls will normally result in a longer execution time than using one
call with all patterns.
Parameter
º Pattern (input object) .....................................................image(-array) Hobject
Pattern to be trained.
º OCVHandle (input control) ....................................................ocv (Htuple .) long
Handle of the OCV tool to be trained.
º Name (input control) ...........................................string(-array) (Htuple .) const char *
Name(s) of the object(s) to analyse.
Default Value : ”a”
º Mode (input control) ..................................................string (Htuple .) const char *
Mode for training (only one mode implemented).
Default Value : ’single’
Value List : Mode ¾’single’
Example
create_ocv_proj("A",&ocv_handle);
draw_region(&ROI,window_handle);
reduce_domain(Image,ROI,&Sample);
traind_ocv_proj(Sample,ocv_handle,"A","single");
Result
(T )traind ocv proj returns H MSG TRUE, if the handle and the training pattern(s) are correct. Otherwise,
an exception handling is raised.
Parallelization Information
(T )traind ocv proj is processed completely exclusively without parallelization.
Possible Predecessor Functions
(T )write ocr trainf, (T )create ocv proj, read ocv, threshold, connection,
select shape
Possible Successor Functions
close ocv
See Also
(T )traind ocr class box
Module
Optical character verification
write ocv ( long OCVHandle, const char *FileName )
Saving an OCV tool to file.
write ocv writes an OCV tool to file. This can be used to save the result of a training
((T )traind ocv proj). The whole information contained in the OCV tool is stored in the file. The file
can be reloaded afterwards using the operator read ocv.
As file extension ’.ocv’ is used. If this extension is not given with the file name, it will be added automatically.
Parameter
º OCVHandle (input control) ..............................................................ocv long
Handle of the OCV tool to be written.
º FileName (input control) ...................................................filename const char *
Name of the file where the tool has to be saved.
Default Value : ’test ocv’
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 801
Result
write ocv returns H MSG TRUE, if the data is correct and the file can be written. Otherwise, an exception
handling is raised.
Parallelization Information
write ocv is reentrant and processed without parallelization.
(T )traind ocv proj
close ocv
write ocr
Optical character verification
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
12.14 Shape-from
depth from focus ( Hobject MultiFocusImage, Hobject *Depth,
Hobject *Confidence, const char *Filter, const char *Selection )
T depth from focus ( Hobject MultiFocusImage, Hobject *Depth,
Hobject *Confidence, Htuple Filter, Htuple Selection )
Extract depth using mutiple focus levels.
The operator (T )depth from focus extracts the depth using a focus sequence. The images of the focus
sequence have to passed as a multi channel image (MultiFocusImage). The depth for each pixel will be
returned in Depth as the channel number. The parameter Confidence returns a confidence value for each
depth estimation: The larger this value, the higher the confidence of the depth estimation is.
(T )depth from focus selects the pixels with the best focus of all focus levels. The method used to extract
these pixels is specified by the parameters Filter and Selection:
’highpass’ The value of the focus is estimated by a highpass filter.
’bandpass’ The value of the focus is estimated by a bandpass filter.
’next maximum’ To decide which focus level has be selected, the pixel in the neighborhood with the best confidence
is used to determine this value.
’local’ The decision for a focus level is based only on the locally calculated focus values.
Parameter
º MultiFocusImage (input object) . . . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject : byte
Multichannel gray image consisting of multiple focus levels.
º Depth (output object) .................................singlechannel-image(-array) Hobject * : byte
Depth image.
º Confidence (output object) ..........................singlechannel-image(-array) Hobject * : byte
Confidence of depth estimation.
º Filter (input control) ........................................string(-array) (Htuple .) const char *
Filter used to find sharp pixels.
Default Value : ’highpass’
Value List : Filter ¾’highpass’, ’bandpass’
º Selection (input control) ....................................string(-array) (Htuple .) const char *
Method used to find sharp pixels.
Default Value : ’next maximum’
Value List : Selection ¾’next maximum’, ’local’
HALCON 6.0

802 CHAPTER 12. TOOLS
Example
compose3(Focus0,Focus1,Focus2,&MultiFocus);
depth_from_focus(MultiFocus,&Depth,&Confidence,’highpass’,’next_maximum’);
mean_image(Depth,&Smooth,15,15);
select_grayvalues_from_channels(MultiChannel,Smooth,SharpImage);
threshold(Confidence,HighConfidence,10,255);
reduce_domain(SharpImage,HighConfidence,ConfidentSharp);
Parallelization Information
(T )depth from focus is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
compose2, compose3, compose4, add channels, read image, read sequence
Possible Successor Functions
select grayvalues from channels, mean image, gauss image, threshold
count channels
Tools
See Also
Module
estimate al am ( Hobject Image, double *Albedo, double *Ambient )
T estimate al am ( Hobject Image, Htuple *Albedo, Htuple *Ambient )
Estimate the albedo of a surface and the amount of ambient light.
(T )estimate al am estimates the Albedo of a surface, i.e. the percentage of light reflected by the surface,
and the amount of ambient light Ambient by using the maximum and minimum gray values of the image.
Attention
It is assumed that the image contains at least one point for which the reflection function assumes its minimum, e.g.,
points in shadows. Furthermore, it is assumed that the image contains at least one point for which the reflection
function assumes its maximum. If this is not the case, wrong values will be estimated.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image for which albedo and ambient are to be estimated.
º Albedo (output control) ............................................real(-array) (Htuple .) double *
Amount of light reflected by the surface.
º Ambient (output control) ...........................................real(-array) (Htuple .) double *
Amount of ambient light.
Result
(T )estimate al am always returns the value H MSG TRUE.
Parallelization Information
(T )estimate al am is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo, shade height field
Tools
Module
estimate sl al lr ( Hobject Image, double *Slant, double *Albedo )
T estimate sl al lr ( Hobject Image, Htuple *Slant, Htuple *Albedo )
Estimate the slant of a light source and the albedo of a surface.
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 803
(T )estimate sl al lr estimates the Slant of a light source, i.e., the angle between the light source and
the positive z-axis, and the albedo of the surface in the input image Image, i.e. the percentage of light reflected
by the surface, using the algorithm of Lee and Rosenfeld.
Attention
The Albedo is assumed constant for the entire surface depicted in the image.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image for which slant and albedo are to be estimated.
º Slant (output control) ........................................angle.deg(-array) (Htuple .) double *
Angle between the light sources and the positive z-axis (in degrees).
º Albedo (output control) ............................................real(-array) (Htuple .) double *
Amount of light reflected by the surface.
Result
(T )estimate sl al lr always returns the value H MSG TRUE.
Parallelization Information
(T )estimate sl al lr is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo, shade height field
Tools
Module
estimate sl al zc ( Hobject Image, double *Slant, double *Albedo )
T estimate sl al zc ( Hobject Image, Htuple *Slant, Htuple *Albedo )
Estimate the slant of a light source and the albedo of a surface.
(T )estimate sl al zc estimates the Slant of a light source, i.e. the angle between the light source and the
positive z-axis, and the albedo of the surface in the input image Image, i.e. the percentage of light reflected by
the surface, using the algorithm of Zheng and Chellappa.
Attention
The Albedo is assumed constant for the entire surface depicted in the image.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image for which slant and albedo are to be estimated.
º Slant (output control) ........................................angle.deg(-array) (Htuple .) double *
Angle of the light sources and the positive z-axis (in degrees).
º Albedo (output control) ............................................real(-array) (Htuple .) double *
Amount of light reflected by the surface.
Result
(T )estimate sl al zc always returns the value H MSG TRUE.
Parallelization Information
(T )estimate sl al zc is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo, shade height field
Tools
Module
HALCON 6.0

804 CHAPTER 12. TOOLS
estimate tilt lr ( Hobject Image, double *Tilt )
T estimate tilt lr ( Hobject Image, Htuple *Tilt )
Estimate the tilt of a light source.
(T )estimate tilt lr estimates the tilt of a light source, i.e. the angle between the light source and the
x-axis after projection into the xy-plane, from the image Image using the algorithm of Lee and Rosenfeld.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image for which the tilt is to be estimated.
º Tilt (output control) .........................................angle.deg(-array) (Htuple .) double *
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Result
(T )estimate tilt lr always returns the value H MSG TRUE.
Parallelization Information
(T )estimate tilt lr is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo, shade height field
Tools
Module
estimate tilt zc ( Hobject Image, double *Tilt )
T estimate tilt zc ( Hobject Image, Htuple *Tilt )
Estimate the tilt of a light source.
(T )estimate tilt zc estimates the tilt of a light source, i.e. the angle between the light source and the
x-axis after projection into the xy-plane, from the image Image using the algorithm of Zheng and Chellappa.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Image for which the tilt is to be estimated.
º Tilt (output control) .........................................angle.deg(-array) (Htuple .) double *
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Result
(T )estimate tilt zc always returns the value H MSG TRUE.
Parallelization Information
(T )estimate tilt zc is reentrant and automatically parallelized (on tuple level).
Possible Successor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo, shade height field
Tools
Module
T phot stereo ( Hobject Images, Hobject *Height, Htuple Slants,
Htuple Tilts )
Reconstruct a surface from at least three gray value images.
T phot stereo reconstructs a surface (i.e., the relative height of each image point) using the algorithm of
Woodham from at least three gray value images given by the multi-channel image Images. The light sources
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 805
corresponding to the individual images are given by the parameters Slants and Tilts and are assumed to lie
infinitely far away.
Attention
T phot stereo assumes that the heights are to be extracted on a lattice with step width 1. If this is not the
case, the calculated heights must be multiplied by the step width after the call to T phot stereo. ACartesian
coordinate system with the origin in the lower left corner of the image is used internally. Since the operator is
based on the Fast Fourier Transform, only square images with an edge length being a power of 2 are accepted. All
given images must be byte-images. At least three images must be given in a multi-channel image. Slants and
Tilts must contain exactly as many light sources as the number of channels in Images. At least three of the
light source directions must be linearly independent.
Parameter
º Images (input object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image Hobject
Shaded input image with at least three channels.
º Height (output object) ..........................................................image Hobject *
Reconstructed height field.
º Slants (input control) ......................................angle.deg-array Htuple . double / long
Angle between the light sources and the positive z-axis (in degrees).
Default Value : 45.0
Value Suggestions : Slants ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Slants 180.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Tilts (input control) ........................................angle.deg-array Htuple . double / long
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Default Value : 45.0
Value Suggestions : Tilts ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Tilts 360.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
Result
If all parameters are correct T phot stereo returns the value H MSG TRUE. Otherwise, an exception is raised.
Parallelization Information
T phot stereo is reentrant and processed without parallelization.
Possible Predecessor Functions
(T )estimate sl al lr, (T )estimate sl al zc, (T )estimate tilt lr,
(T )estimate tilt zc
Possible Successor Functions
shade height field
Module
Tools
select grayvalues from channels ( Hobject MultichannelImage,
Hobject IndexImage, Hobject *Selected )
Selection of gray values of a multi channel image using an index image.
The operator select grayvalues from channels selects gray values from a MultichannelImage.
The channel number for each pixel is determined by using IndexImage: The gray value in IndexImage is
used as the channel number in MultichannelImage.
Parameter
º MultichannelImage (input object) . . . . . . . . . . . . . . . . . . . . . multichannel-image(-array) Hobject : byte
Multichannel gray image.
º IndexImage (input object) ..............................singlechannel-image(-array) Hobject : byte
Image, where gray values are interpreted als indexes.
HALCON 6.0

806 CHAPTER 12. TOOLS
º Selected (output object) .............................singlechannel-image(-array) Hobject * : byte
Depth image.
Example
compose3(Focus0,Focus1,Focus2,&MultiFocus);
depth_from_focus(MultiFocus,&Depth,&Confidence,’highpass’,’next_maximum’);
mean_image(Depth,&Smooth,15,15);
select_grayvalues_from_channels(MultiChannel,Smooth,SharpImage);
Parallelization Information
select grayvalues from channels is reentrant and automatically parallelized (on tuple level, domain
level).
Possible Predecessor Functions
(T )depth from focus, mean image
disp image
count channels
Tools
Possible Successor Functions
See Also
Module
sfs mod lr ( Hobject Image, Hobject *Height, double Slant, double Tilt,
double Albedo, double Ambient )
Reconstruct a surface from a gray value image.
sfs mod lr reconstructs a surface (i.e. the relative height of each image point) using the modified algorithm of
Lee and Rosenfeld. The surface is reconstructed from the input image Image, and the light source given by the
parameters Slant, Tilt, Albedo and Ambient, and is assumed to lie infinitely far away in the direction given
by Slant and Tilt. The parameter Albedo determines the albedo of the surface, i.e. the percentage of light
reflected in all directions. Ambient determines the amount of ambient light falling onto the surface. It can be set
to values greater than zero if, for example, the white balance of the camera was badly adjusted at the moment the
image was taken.
Attention
sfs mod lr assumes that the heights are to be extracted on a lattice with step width 1. If this is not the case, the
calculated heights must be multiplied with the step width after the call to sfs mod lr. A Cartesian coordinate
system with the origin in the lower left corner of the image is used internally. Since the operator is based on the
Fast Fourier Transform, only square images with the edge length being a power of 2 are accepted. sfs mod lr
can only handle byte-images.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Shaded input image.
º Height (output object) ...................................................image(-array) Hobject *
Reconstructed height field.
º Slant (input control) .....................................................angle.deg double / long
Angle between the light source and the positive z-axis (in degrees).
Default Value : 45.0
Value Suggestions : Slant ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Slant 180.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 807
º Tilt (input control) ......................................................angle.deg double / long
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Default Value : 45.0
Value Suggestions : Tilt ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Tilt 360.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Albedo (input control) .....................................................number double / long
Amount of light reflected by the surface.
Default Value : 1.0
Value Suggestions : Albedo ¾0.1, 0.5, 1.0, 5.0
Typical Range of Values : 0.0 Albedo 5.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Albedo 0.0
º Ambient (input control) ....................................................number double / long
Amount of ambient light.
Default Value : 0.0
Value Suggestions : Ambient ¾0.1, 0.5, 1.0
Typical Range of Values : 0.0 Ambient 1.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Ambient 0.0
Result
If all parameters are correct sfs mod lr returns the value H MSG TRUE. Otherwise, an exception is raised.
Parallelization Information
sfs mod lr is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
(T )estimate al am, (T )estimate sl al lr, (T )estimate sl al zc,
(T )estimate tilt lr, (T )estimate tilt zc
shade height field
Tools
Possible Successor Functions
Module
sfs orig lr ( Hobject Image, Hobject *Height, double Slant, double Tilt,
double Albedo, double Ambient )
Reconstruct a surface from a gray value image.
sfs orig lr reconstructs a surface (i.e. the relative height of each image point) using the original algorithm of
Lee and Rosenfeld. The surface is reconstructed from the input image Image. The light source is to be given by
the parameters Slant, Tilt, Albedo and Ambient, and is assumed to lie infinitely far away in the direction
given by Slant and Tilt. The parameter Albedo determines the albedo of the surface, i.e. the percentage of
light reflected in all directions. Ambient determines the amount of ambient light falling onto the surface. It can
be set to values greater than zero if, for example, the white balance of the camera was badly adjusted at the moment
the image was taken.
Attention
sfs orig lr assumes that the heights are to be extracted on a lattice with step width 1. If this is not the case, the
calculated heights must be multiplied with the step width after the call to sfs orig lr. A Cartesian coordinate
system with the origin in the lower left corner of the image is used internally. Since the operator is based on the
Fast Fourier Transform, only square images with the edge length being a power of 2 are accepted. sfs orig lr
can only handle byte-images.
HALCON 6.0

808 CHAPTER 12. TOOLS
Parameter
º Image (input object) ........................................................image(-array) Hobject
Shaded input image.
º Height (output object) ...................................................image(-array) Hobject *
Reconstructed height field.
º Slant (input control) .....................................................angle.deg double / long
Angle between the light source and the positive z-axis (in degrees).
Default Value : 45.0
Value Suggestions : Slant ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Slant 180.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Tilt (input control) ......................................................angle.deg double / long
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Default Value : 45.0
Value Suggestions : Tilt ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Tilt 360.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Albedo (input control) .....................................................number double / long
Amount of light reflected by the surface.
Default Value : 1.0
Value Suggestions : Albedo ¾0.1, 0.5, 1.0, 5.0
Typical Range of Values : 0.0 Albedo 5.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Albedo 0.0
º Ambient (input control) ....................................................number double / long
Amount of ambient light.
Default Value : 0.0
Value Suggestions : Ambient ¾0.1, 0.5, 1.0
Typical Range of Values : 0.0 Ambient 1.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Ambient 0.0
Result
If all parameters are correct sfs orig lr returns the value H MSG TRUE. Otherwise, an exception is raised.
Parallelization Information
sfs orig lr is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
(T )estimate al am, (T )estimate sl al lr, (T )estimate sl al zc,
(T )estimate tilt lr, (T )estimate tilt zc
shade height field
Tools
Possible Successor Functions
Module
sfs pentland ( Hobject Image, Hobject *Height, double Slant,
double Tilt, double Albedo, double Ambient )
Reconstruct a surface from a gray value image.
sfs pentland reconstructs a surface (i.e. the relative height of each image point) using the algorithm of Pentland.
The surface is reconstructed from the input image Image. The light source must be given by the parameters
Slant, Tilt, Albedo and Ambient, and is assumed to lie infinitely far away in the direction given by Slant
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 809
and Tilt. The parameter Albedo determines the albedo of the surface, i.e. the percentage of light reflected in
all directions. Ambient determines the amount of ambient light falling onto the surface. It can be set to values
greater than zero if, for example, the white balance of the camera was badly adjusted at the moment the image was
taken.
Attention
sfs pentland assumes that the heights are to be extracted on a lattice with step width 1. If this is not the
case, the calculated heights must be multiplied with the step width after the call to sfs pentland. ACartesian
coordinate system with the origin in the lower left corner of the image is used internally. Since the operator is
based on the Fast Fourier Transform, only square images with the edge length being a power of 2 are accepted.
sfs pentland can only handle byte-images.
Parameter
º Image (input object) ........................................................image(-array) Hobject
Shaded input image.
º Height (output object) ...................................................image(-array) Hobject *
Reconstructed height field.
º Slant (input control) .....................................................angle.deg double / long
Angle between the light source and the positive z-axis (in degrees).
Default Value : 45.0
Value Suggestions : Slant ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Slant 180.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Tilt (input control) ......................................................angle.deg double / long
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Default Value : 45.0
Value Suggestions : Tilt ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Tilt 360.0 (lin)
Minimal Value Step : 1.0
Recommended Value Step : 10.0
º Albedo (input control) .....................................................number double / long
Amount of light reflected by the surface.
Default Value : 1.0
Value Suggestions : Albedo ¾0.1, 0.5, 1.0, 5.0
Typical Range of Values : 0.0 Albedo 5.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Albedo 0.0
º Ambient (input control) ....................................................number double / long
Amount of ambient light.
Default Value : 0.0
Value Suggestions : Ambient ¾0.1, 0.5, 1.0
Typical Range of Values : 0.0 Ambient 1.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Ambient 0.0
Result
If all parameters are correct sfs pentland returns the value H MSG TRUE. Otherwise, an exception is raised.
Parallelization Information
sfs pentland is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
(T )estimate al am, (T )estimate sl al lr, (T )estimate sl al zc,
(T )estimate tilt lr, (T )estimate tilt zc
shade height field
Tools
Possible Successor Functions
Module
HALCON 6.0

810 CHAPTER 12. TOOLS
shade height field ( Hobject ImageHeight, Hobject *ImageShade,
double Slant, double Tilt, double Albedo, double Ambient,
const char *Shadows )
Shade a height field.
shade height field computes a shaded image from the height field ImageHeight as if the image were
illuminated by an infinitely far away light source. It is assumed that the surface described by the height field has
Lambertian reflection properties determined by Albedo and Ambient. The parameter Shadows determines
whether shadows are to be calculated.
Attention
shade height field assumes that the heights are given on a lattice with step width 1. If this is not the case, the
heights must be divided by the step width before the call to shade height field. Otherwise, the derivatives
used internally to compute the orientation of the surface will be estimated to steep or too flat. Example: The height
field is given on 100*100 points on the square [0,1]*[0,1]. Then the heights must be divided by 1/100 first. A
Cartesian coordinate system with the origin in the lower left corner of the image is used internally.
Parameter
º ImageHeight (input object) ...............................................image(-array) Hobject
Height field to be shaded.
º ImageShade (output object) ..............................................image(-array) Hobject *
Shaded image.
º Slant (input control) .....................................................angle.deg double / long
Angle between the light source and the positive z-axis (in degrees).
Default Value : 0.0
Value Suggestions : Slant ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Slant 180.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Tilt (input control) ......................................................angle.deg double / long
Angle between the light source and the x-axis after projection into the xy-plane (in degrees).
Default Value : 0.0
Value Suggestions : Tilt ¾1.0, 5.0, 10.0, 20.0, 40.0, 60.0, 90.0
Typical Range of Values : 0.0 Tilt 360.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 10.0
º Albedo (input control) .....................................................number double / long
Amount of light reflected by the surface.
Default Value : 1.0
Value Suggestions : Albedo ¾0.1, 0.5, 1.0, 5.0
Typical Range of Values : 0.0 Albedo 5.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Albedo 0.0
º Ambient (input control) ....................................................number double / long
Amount of ambient light.
Default Value : 0.0
Value Suggestions : Ambient ¾0.1, 0.5, 1.0
Typical Range of Values : 0.0 Ambient 1.0 (lin)
Minimal Value Step : 0.01
Recommended Value Step : 0.1
Restriction : Ambient 0.0
º Shadows (input control) .......................................................string const char *
Should shadows be calculated?
Default Value : ’false’
Value Suggestions : Shadows ¾’true’, ’false’
Result
If all parameters are correct shade height field returns the value H MSG TRUE. Otherwise, an exception
is raised.
HALCON/C Reference Manual / 2000-11-15

12.14. SHAPE-FROM 811
Parallelization Information
shade height field is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
sfs mod lr, sfs orig lr, sfs pentland, T phot stereo
Tools
Module
HALCON 6.0

812 CHAPTER 12. TOOLS
HALCON/C Reference Manual / 2000-11-15

Chapter 13
Tuple
13.1 Arithmetic
tuple abs ( double T, double *Abs )
T tuple abs ( Htuple T, Htuple *Abs )
Compute the absolute value of a tuple.
(T )tuple abs computes the absolute value of the input tuple T. The absolute value of an integer number is
again an integer number. The absolute value of a floating point number is a floating point number. The absolute
value of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Abs (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Absolute value of the input tuple.
Parallelization Information
(T )tuple abs is reentrant and processed without parallelization.
(T )tuple fabs
Operators not requiring licensing
Alternatives
Module
tuple acos ( double T, double *ACos )
T tuple acos ( Htuple T, Htuple *ACos )
Compute the arccosine of a tuple.
(T )tuple acos computes the arccosine of the input tuple T. The arccosine is always returned as a floating
point number. The arccosine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
Restriction : ´-1 Tµ 1
º ACos (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Arccosine of the input tuple.
813

814 CHAPTER 13. TUPLE
Parallelization Information
(T )tuple acos is reentrant and processed without parallelization.
Alternatives
(T )tuple asin, (T )tuple atan, (T )tuple atan2
(T )tuple cos
Operators not requiring licensing
See Also
Module
tuple add ( double S1, double S2, double *Sum )
T tuple add ( Htuple S1, Htuple S2, Htuple *Sum )
Add two tuples.
(T )tuple add computes the sum of the input tuples S1 and S2. If both tuples have the same length the
corresponding elements of both tuples are added. Otherwise, either S1 or S2 must have length 1. In this case, the
addition is performed for each element of the longer tuple with the single element of the other tuple. If two integer
numbers are added, the result is again an integer number. If a floating point number is added to another number,
the result is a floating point number. If two strings are added, the addition corresponds to a string concatenation. If
a number and a string are added, the number is converted to a string first. Thus, the addition also corresponds to a
string concatenation in this case.
Parameter
º S1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long / const char *
Input tuple 1.
º S2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long / const char *
Input tuple 2.
º Sum (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long * / char *
Sum of the input tuples.
Parallelization Information
(T )tuple add is reentrant and processed without parallelization.
(T )tuple sub
Operators not requiring licensing
Alternatives
Module
tuple asin ( double T, double *ASin )
T tuple asin ( Htuple T, Htuple *ASin )
Compute the arcsine of a tuple.
(T )tuple asin computes the arcsine of the input tuple T. The arcsine is always returned as a floating point
number. The arcsine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
Restriction : ´-1 Tµ 1
º ASin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Arcsine of the input tuple.
HALCON/C Reference Manual / 2000-11-15

13.1. ARITHMETIC 815
Parallelization Information
(T )tuple asin is reentrant and processed without parallelization.
Alternatives
(T )tuple acos, (T )tuple atan, (T )tuple atan2
(T )tuple sin
Operators not requiring licensing
See Also
Module
tuple atan ( double T, double *ATan )
T tuple atan ( Htuple T, Htuple *ATan )
Compute the arctangent of a tuple.
(T )tuple atan computes the arctangent of the input tuple T. The arctangent is always returned as a floating
point number. The arctangent of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º ATan (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Arctangent of the input tuple.
Parallelization Information
(T )tuple atan is reentrant and processed without parallelization.
Alternatives
(T )tuple atan2, (T )tuple asin, (T )tuple acos
(T )tuple tan
Operators not requiring licensing
See Also
Module
tuple atan2 ( double Y, double X, double *ATan )
T tuple atan2 ( Htuple Y, Htuple X, Htuple *ATan )
Compute the arctangent of a tuple for all four quadrants.
(T )tuple atan2 computes the arctangent of the input tuples while treating all four quadrants correctly.
The arctangent is always returned as a floating point number. The arctangent of a string is not allowed.
Parameter
º Y (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple of the y-values.
º X (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple of the x-values.
º ATan (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Arctangent of the input tuple.
Parallelization Information
(T )tuple atan2 is reentrant and processed without parallelization.
Alternatives
(T )tuple atan, (T )tuple asin, (T )tuple acos
HALCON 6.0

816 CHAPTER 13. TUPLE
(T )tuple tan
Operators not requiring licensing
See Also
Module
tuple cos ( double T, double *Cos )
T tuple cos ( Htuple T, Htuple *Cos )
Compute the cosine of a tuple.
(T )tuple cos computes the cosine of the input tuple T. The cosine is always returned as a floating point
number. The cosine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Cos (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Cosine of the input tuple.
Parallelization Information
(T )tuple cos is reentrant and processed without parallelization.
(T )tuple sin, (T )tuple tan
(T )tuple acos
Operators not requiring licensing
Alternatives
See Also
Module
tuple cosh ( double T, double *Cosh )
T tuple cosh ( Htuple T, Htuple *Cosh )
Compute the hyperbolic cosine of a tuple.
(T )tuple cosh computes the hyperbolic cosine of the input tuple T. The hyperbolic cosine is always returned
as a floating point number. The hyperbolic cosine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Cosh (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Hyperbolic cosine of the input tuple.
Parallelization Information
(T )tuple cosh is reentrant and processed without parallelization.
(T )tuple sinh, (T )tuple tanh
Operators not requiring licensing
Alternatives
Module
HALCON/C Reference Manual / 2000-11-15

13.1. ARITHMETIC 817
tuple div ( double Q1, double Q2, double *Quot )
T tuple div ( Htuple Q1, Htuple Q2, Htuple *Quot )
Divide two tuples.
(T )tuple div computes the quotient of the input tuples Q1 and Q2. If both tuples have the same length the
corresponding elements of both tuples are divided. Otherwise, either Q1 or Q2 must have length 1. In this case, the
division is performed for each element of the longer tuple with the single element of the other tuple. If two integer
numbers are divided, the result is again an integer number. If one of the operands is a floating point number, the
result is a floating point number. The division of strings is not allowed.
Parameter
º Q1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º Q2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
Restriction : Q2 0
º Quot (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Quotient of the input tuples.
Parallelization Information
(T )tuple div is reentrant and processed without parallelization.
(T )tuple mult
Operators not requiring licensing
Alternatives
Module
tuple exp ( double T, double *Exp )
T tuple exp ( Htuple T, Htuple *Exp )
Compute the exponential of a tuple.
(T )tuple exp computes the exponential of the input tuple T. The exponential is always returned as a floating
point number. The exponential of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Exp (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Exponential of the input tuple.
Parallelization Information
(T )tuple exp is reentrant and processed without parallelization.
(T )tuple pow
(T )tuple log, (T )tuple log10
Operators not requiring licensing
Alternatives
See Also
Module
HALCON 6.0

818 CHAPTER 13. TUPLE
tuple fabs ( double T, double *Abs )
T tuple fabs ( Htuple T, Htuple *Abs )
Compute the absolute value of a tuple (as floating point numbers).
(T )tuple fabs computes the absolute value of the input tuple T. In contrast to (T )tuple abs, the absolute
value is always returned as a floating point number by (T )tuple fabs. The absolute value of a string is not
allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Abs (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Absolute value of the input tuple.
Parallelization Information
(T )tuple fabs is reentrant and processed without parallelization.
(T )tuple abs
Operators not requiring licensing
Alternatives
Module
tuple fmod ( double T1, double T2, double *Fmod )
T tuple fmod ( Htuple T1, Htuple T2, Htuple *Fmod )
Calculate the remainder of the floating point division of two tuples.
(T )tuple fmod computes the remainder of the floating point division of the input tuples ̽̾. If both tuples
have the same length the division is performed for the corresponding elements of both tuples. Otherwise, either
T1 or T2 must have length 1. In this case, the division is performed for each element of the longer tuple with
the single element of the other tuple. The result is always a floating point number. The division of strings is not
allowed.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
Restriction : T2 0.0
º Fmod (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Remainder of the division of the input tuples.
Parallelization Information
(T )tuple fmod is reentrant and processed without parallelization.
(T )tuple floor, (T )tuple ceil
Operators not requiring licensing
See Also
Module
tuple ldexp ( double T1, double T2, double *Ldexp )
T tuple ldexp ( Htuple T1, Htuple T2, Htuple *Ldexp )
Calculate the ldexp function of two tuples.
HALCON/C Reference Manual / 2000-11-15

13.1. ARITHMETIC 819
(T )tuple ldexp computes the ldexp function of the input tuples, i.e., ̽ £ ¾ ̾ . If both tuples have the same
length the operation is performed for the corresponding elements of both tuples. Otherwise, either T1 or T2 must
have length 1. In this case, the operation is performed for each element of the longer tuple with the single element
of the other tuple. The result is always a floating point number. The ldexp function of strings is not allowed.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
º Ldexp (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Ldexp function of the input tuples.
Parallelization Information
(T )tuple ldexp is reentrant and processed without parallelization.
(T )tuple exp
Operators not requiring licensing
See Also
Module
tuple log ( double T, double *Log )
T tuple log ( Htuple T, Htuple *Log )
Compute the natural logarithm of a tuple.
(T )tuple log computes the natural logarithm of the input tuple T. The natural logarithm is always returned as
a floating point number. The natural logarithm of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
Restriction : T 0
º Log (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Natural logarithm of the input tuple.
Parallelization Information
(T )tuple log is reentrant and processed without parallelization.
(T )tuple log10
(T )tuple exp, (T )tuple pow
Operators not requiring licensing
Alternatives
See Also
Module
tuple log10 ( double T, double *Log )
T tuple log10 ( Htuple T, Htuple *Log )
Compute the base 10 logarithm of a tuple.
(T )tuple log10 computes the base 10 logarithm of the input tuple T. The logarithm is always returned as a
floating point number. The logarithm of a string is not allowed.
HALCON 6.0

820 CHAPTER 13. TUPLE
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
Restriction : T 0
º Log (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Base 10 logarithm of the input tuple.
Parallelization Information
(T )tuple log10 is reentrant and processed without parallelization.
(T )tuple log
(T )tuple exp, (T )tuple pow
Operators not requiring licensing
Alternatives
See Also
Module
tuple mult ( double P1, double P2, double *Prod )
T tuple mult ( Htuple P1, Htuple P2, Htuple *Prod )
Multiply two tuples.
(T )tuple mult computes the product of the input tuples P1 and P2. If both tuples have the same length the
corresponding elements of both tuples are subtracted. Otherwise, either P1 or P2 must have length 1. In this case,
the multiplication is performed for each element of the longer tuple with the single element of the other tuple. If
two integer numbers are multiplied, the result is again an integer number. If one of the operands is a floating point
number, the result is a floating point number. The multiplication of strings is not allowed.
Parameter
º P1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º P2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
º Prod (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Product of the input tuples.
Parallelization Information
(T )tuple mult is reentrant and processed without parallelization.
(T )tuple div
Operators not requiring licensing
Alternatives
Module
tuple neg ( double T, double *Neg )
T tuple neg ( Htuple T, Htuple *Neg )
Negate a tuple.
(T )tuple neg computes the negation of the input tuple T, i.e., Æ Ì. The negation of an integer number
is again an integer number. The negation of a floating point number is a floating point number. The negation of a
string is not allowed. The negation of an empty input tuple results in an empty output tuple.
HALCON/C Reference Manual / 2000-11-15

13.1. ARITHMETIC 821
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Neg (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Negation of the input tuple.
Parallelization Information
(T )tuple neg is reentrant and processed without parallelization.
Operators not requiring licensing
Module
tuple pow ( double T1, double T2, double *Pow )
T tuple pow ( Htuple T1, Htuple T2, Htuple *Pow )
Calculate the power function two tuples.
(T )tuple pow computes the power function of the input tuples ̽ ̾ . If both tuples have the same length the
power function is applied to the corresponding elements of both tuples. Otherwise, either T1 or T2 must have
length 1. In this case, the power function is performed for each element of the longer tuple with the single element
of the other tuple. The result is always a floating point number. The power function of strings is not allowed.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
º Pow (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Power function of the input tuples.
Parallelization Information
(T )tuple pow is reentrant and processed without parallelization.
(T )tuple exp
(T )tuple log, (T )tuple log10
Operators not requiring licensing
Alternatives
See Also
Module
tuple rad ( double Deg, double *Rad )
T tuple rad ( Htuple Deg, Htuple *Rad )
Convert a tuple from degrees to radians.
(T )tuple rad converts the input tuple Deg from degrees to radians. The result is always returned as a floating
point number. The conversion of a string is not allowed.
Parameter
º Deg (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Rad (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Input tuple in radians.
HALCON 6.0

822 CHAPTER 13. TUPLE
Parallelization Information
(T )tuple rad is reentrant and processed without parallelization.
(T )tuple deg
Operators not requiring licensing
See Also
Module
tuple sin ( double T, double *Sin )
T tuple sin ( Htuple T, Htuple *Sin )
Compute the sine of a tuple.
(T )tuple sin computes the sine of the input tuple T. The sine is always returned as a floating point number.
The sine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Sin (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Sine of the input tuple.
Parallelization Information
(T )tuple sin is reentrant and processed without parallelization.
(T )tuple cos, (T )tuple tan
(T )tuple asin
Operators not requiring licensing
Alternatives
See Also
Module
tuple sinh ( double T, double *Sinh )
T tuple sinh ( Htuple T, Htuple *Sinh )
Compute the hyperbolic sine of a tuple.
(T )tuple sin computes the hyperbolic sine of the input tuple T. The hyperbolic sine is always returned as a
floating point number. The hyperbolic sine of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Sinh (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Hyperbolic sine of the input tuple.
Parallelization Information
(T )tuple sinh is reentrant and processed without parallelization.
(T )tuple cosh, (T )tuple tanh
Operators not requiring licensing
Alternatives
Module
HALCON/C Reference Manual / 2000-11-15

13.1. ARITHMETIC 823
tuple sqrt ( double T, double *Sqrt )
T tuple sqrt ( Htuple T, Htuple *Sqrt )
Compute the square root of a tuple.
(T )tuple sqrt computes the square root of the input tuple T. The square root is always returned as a floating
point number. The square root of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
Restriction : T 0
º Sqrt (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Square root of the input tuple.
Parallelization Information
(T )tuple sqrt is reentrant and processed without parallelization.
Operators not requiring licensing
Module
tuple sub ( double D1, double D2, double *Diff )
T tuple sub ( Htuple D1, Htuple D2, Htuple *Diff )
Subtract two tuples.
(T )tuple sub computes the difference of the input tuples D1 and D2. If both tuples have the same length the
corresponding elements of both tuples are subtracted. Otherwise, either D1 or D2 must have length 1. In this case,
the subtraction is performed for each element of the longer tuple with the single element of the other tuple. If two
integer numbers are subtracted, the result is again an integer number. If one of the operands is a floating point
number, the result is a floating point number. The subtraction of strings is not allowed.
Parameter
º D1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 1.
º D2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple 2.
º Diff (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double * / long *
Difference of the input tuples.
Parallelization Information
(T )tuple sub is reentrant and processed without parallelization.
(T )tuple add
Operators not requiring licensing
Alternatives
Module
tuple tan ( double T, double *Tan )
T tuple tan ( Htuple T, Htuple *Tan )
Compute the tangent of a tuple.
(T )tuple tan computes the tangent of the input tuple T. The tangent is always returned as a floating point
number. The tangent of a string is not allowed.
HALCON 6.0

824 CHAPTER 13. TUPLE
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Tan (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Tangent of the input tuple.
Parallelization Information
(T )tuple tan is reentrant and processed without parallelization.
(T )tuple sin, (T )tuple cos
(T )tuple atan, (T )tuple atan2
Operators not requiring licensing
Alternatives
See Also
Module
tuple tanh ( double T, double *Tanh )
T tuple tanh ( Htuple T, Htuple *Tanh )
Compute the hyperbolic tangent of a tuple.
(T )tuple tanh computes the hyperbolic tangent of the input tuple T. The hyperbolic tangent is always returned
as a floating point number. The hyperbolic tangent of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Tanh (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Hyperbolic tangent of the input tuple.
Parallelization Information
(T )tuple tanh is reentrant, local, and processed without parallelization.
(T )tuple sinh, (T )tuple cosh
Operators not requiring licensing
Alternatives
Module
13.2 Bit-Operations
tuple band ( long T1, long T2, long *BAnd )
T tuple band ( Htuple T1, Htuple T2, Htuple *BAnd )
Compute the bitwise and of two tuples.
(T )tuple band computes the bitwise and of the input tuples T1 and T2. If both tuples have the same length
the operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must have
length 1. In this case, the operation is performed for each element of the longer tuple with the single element of
the other tuple. The input tuples must contain only integer numbers.
HALCON/C Reference Manual / 2000-11-15

13.2. BIT-OPERATIONS 825
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º BAnd (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary and of the input tuples.
Parallelization Information
(T )tuple band is reentrant and processed without parallelization.
Alternatives
(T )tuple bor, (T )tuple bxor, (T )tuple bnot
See Also
(T )tuple and, (T )tuple or, (T )tuple xor, (T )tuple not
Operators not requiring licensing
Module
tuple bnot ( long T, long *BNot )
T tuple bnot ( Htuple T, Htuple *BNot )
Compute the bitwise not of two tuples.
(T )tuple bnot computes the bitwise not of the input tuple T. The input tuple must contain only integer
numbers.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
º BNot (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary not of the input tuple.
Parallelization Information
(T )tuple bnot is reentrant and processed without parallelization.
Alternatives
(T )tuple band, (T )tuple bor, (T )tuple bxor
See Also
(T )tuple and, (T )tuple or, (T )tuple xor, (T )tuple not
Operators not requiring licensing
Module
tuple bor ( long T1, long T2, long *BOr )
T tuple bor ( Htuple T1, Htuple T2, Htuple *BOr )
Compute the bitwise or of two tuples.
(T )tuple bor computes the bitwise or of the input tuples T1 and T2. If both tuples have the same length the
operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must have length
1. In this case, the operation is performed for each element of the longer tuple with the single element of the other
tuple. The input tuples must contain only integer numbers.
HALCON 6.0

826 CHAPTER 13. TUPLE
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º BOr (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary or of the input tuples.
Parallelization Information
(T )tuple bor is reentrant and processed without parallelization.
Alternatives
(T )tuple band, (T )tuple bxor, (T )tuple bnot
See Also
(T )tuple and, (T )tuple or, (T )tuple xor, (T )tuple not
Operators not requiring licensing
Module
tuple bxor ( long T1, long T2, long *BXor )
T tuple bxor ( Htuple T1, Htuple T2, Htuple *BXor )
Compute the bitwise exclusive or of two tuples.
(T )tuple bxor computes the bitwise exclusive or of the input tuples T1 and T2. If both tuples have the same
length the operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must
have length 1. In this case, the operation is performed for each element of the longer tuple with the single element
of the other tuple. The input tuples must contain only integer numbers.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º BXor (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary exclusive or of the input tuples.
Parallelization Information
(T )tuple bxor is reentrant and processed without parallelization.
Alternatives
(T )tuple band, (T )tuple bor, (T )tuple bnot
See Also
(T )tuple and, (T )tuple or, (T )tuple xor, (T )tuple not
Operators not requiring licensing
Module
tuple lsh ( long T, long Shift, long *Lsh )
T tuple lsh ( Htuple T, Htuple Shift, Htuple *Lsh )
Shift a tuple bitwise to the left.
(T )tuple lsh shifts the tuple T bitwise to the left by Shift places. If no overflow occurs, this operation is
equivalent to a multiplication by ¾ ËØ .IfT is negative, the result depends on the hardware. If Shift is negative
or larger than 32, the result is undefined. If both tuples have the same length the corresponding elements of both
HALCON/C Reference Manual / 2000-11-15

13.2. BIT-OPERATIONS 827
tuples are shifted. Otherwise, either T or Shift must have length 1. In this case, the operation is performed for
each element of the longer tuple with the single element of the other tuple. The input tuples must contain only
integer numbers.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
º Shift (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Number of places to shift the input tuple.
º Lsh (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Shifted input tuple.
Parallelization Information
(T )tuple lsh is reentrant and processed without parallelization.
(T )tuple mult
(T )tuple rsh
Operators not requiring licensing
Alternatives
See Also
Module
tuple rsh ( long T, long Shift, long *Rsh )
T tuple rsh ( Htuple T, Htuple Shift, Htuple *Rsh )
Shift a tuple bitwise to the right.
(T )tuple rsh shifts the tuple T bitwise to the right by Shift places. This operation is equivalent to a division
by ¾ ËØ .IfT is negative, the result depends on the hardware. If Shift is negative or larger than 32, the result is
undefined. If both tuples have the same length the corresponding elements of both tuples are shifted. Otherwise,
either T or Shift must have length 1. In this case, the operation is performed for each element of the longer tuple
with the single element of the other tuple. The input tuples must contain only integer numbers.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
º Shift (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Number of places to shift the input tuple.
º Rsh (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Shifted input tuple.
Parallelization Information
(T )tuple rsh is reentrant and processed without parallelization.
(T )tuple div
(T )tuple lsh
Operators not requiring licensing
Alternatives
See Also
Module
HALCON 6.0

828 CHAPTER 13. TUPLE
13.3 Comparison
tuple equal ( long T1, long T2, long *Equal )
T tuple equal ( Htuple T1, Htuple T2, Htuple *Equal )
Test, whether two tuples are equal.
(T )tuple equal tests whether the two input tuples T1 and T2 are equal by comparing the tuples elementwise.
Two tuples are equal, if they have got the same number of elements and if their elements are equal. Two tuple
elements are equal, if they are both (integer or floating point) numbers or both are strings and contain the same
value.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Equal (output control) ....................................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple equal is reentrant and processed without parallelization.
Alternatives
(T )tuple not equal, (T )tuple less, (T )tuple greater, (T )tuple less equal,
(T )tuple greater equal
Module
Operators not requiring licensing
tuple greater ( long T1, long T2, long *Greater )
T tuple greater ( Htuple T1, Htuple T2, Htuple *Greater )
Test, whether a tuple is greater than another tuple.
(T )tuple greater tests whether the input tuple T1 is greater than T2. A tuple T1 is said to be greater than
a tuple T2, ifT1 has been found to be greater when comparing it elementwise to T2 or (for the case that the
elementwise comparison did not show that T1 is greater than T2) ifT1 has got more elements than T2. With the
elementwise comparison the single elements of T1 and T2 are compared with each other one after another (i.e., the
first element of T1 is compared to the first element of T2 and the second element of T1 is compared to the second
element of T2 etc.). If an element of T1 is greater than its counterpart of T2, T1 is said to be greater than T2. As
a precondition for comparing the tuples elementwise two corresponding elements must either both be (integer or
floating point) numbers or both be strings. Otherwise (T )tuple greater returns an error.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Greater (output control) .................................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple greater is reentrant and processed without parallelization.
Alternatives
(T )tuple greater equal, (T )tuple less, (T )tuple less equal, (T )tuple equal,
(T )tuple not equal
HALCON/C Reference Manual / 2000-11-15

13.3. COMPARISON 829
Operators not requiring licensing
Module
tuple greater equal ( long T1, long T2, long *Greatereq )
T tuple greater equal ( Htuple T1, Htuple T2, Htuple *Greatereq )
Test, whether a tuple is greater or equal to another tuple.
(T )tuple greater equal tests whether the input tuple T1 is greater or equal to T2. A tuple T1 is said to
be greater or equal to a tuple T2,ifT1 is not less than T2. A tuple T1 is said to be less than a tuple T2, ifT1 has
been found to be less when comparing it elementwise to T2 or (for the case that the elementwise comparison did
not show that T1 is less than T2)ifT1 has got less elements than T2. With the elementwise comparison the single
elements of T1 and T2 are compared with each other one after another (i.e., the first element of T1 is compared to
the first element of T2 and the second element of T1 is compared to the second element of T2 etc.). If an element
of T1 is less than its counterpart of T2, T1 is said to be less than T2. As a precondition for comparing the tuples
elementwise two corresponding elements must either both be (integer or floating point) numbers or both be strings.
Otherwise (T )tuple greater equal returns an error.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Greatereq (output control) ..............................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple greater equal is reentrant and processed without parallelization.
Alternatives
(T )tuple greater, (T )tuple less, (T )tuple less equal, (T )tuple equal,
(T )tuple not equal
Module
Operators not requiring licensing
tuple less ( long T1, long T2, long *Less )
T tuple less ( Htuple T1, Htuple T2, Htuple *Less )
Test, whether a tuple is less than another tuple.
(T )tuple less tests whether the input tuple T1 is less than T2. A tuple T1 is said to be less than a tuple T2,if
T1 has been found to be less when comparing it elementwise to T2 or (for the case that the elementwise comparison
did not show that T1 is less than T2) ifT1 has got less elements than T2. With the elementwise comparison the
single elements of T1 and T2 are compared with each other one after another (i.e., the first element of T1 is
compared to the first element of T2 and the second element of T1 is compared to the second element of T2 etc.). If
an element of T1 is less than its counterpart of T2, T1 is said to be less than T2. As a precondition for comparing
the tuples elementwise two corresponding elements must either both be (integer or floating point) numbers or both
be strings. Otherwise (T )tuple less returns an error.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
HALCON 6.0

830 CHAPTER 13. TUPLE
º Less (output control) .....................................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple less is reentrant and processed without parallelization.
Alternatives
(T )tuple less equal, (T )tuple greater, (T )tuple greater equal, (T )tuple equal,
(T )tuple not equal
Module
Operators not requiring licensing
tuple less equal ( long T1, long T2, long *Lesseq )
T tuple less equal ( Htuple T1, Htuple T2, Htuple *Lesseq )
Test, whether a tuple is less or equal to another tuple.
(T )tuple less equal tests whether the input tuple T1 is less or equal to T2. A tuple T1 is said to be less or
equal to a tuple T2, ifT1 is not greater than T2. A tuple T1 is said to be greater than a tuple T2, ifT1 has been
found to be greater when comparing it elementwise to T2 or (for the case that the elementwise comparison did not
show that T1 is greater than T2)ifT1 has got more elements than T2. With the elementwise comparison the single
elements of T1 and T2 are compared with each other one after another (i.e., the first element of T1 is compared to
the first element of T2 and the second element of T1 is compared to the second element of T2 etc.). If an element
of T1 is greater than its counterpart of T2, T1 is said to be greater than T2. As a precondition for comparing the
tuples elementwise two corresponding elements must either both be (integer or floating point) numbers or both be
strings. Otherwise (T )tuple less equal returns an error.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Lesseq (output control) ..................................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple less equal is reentrant and processed without parallelization.
Alternatives
(T )tuple less, (T )tuple greater, (T )tuple greater equal, (T )tuple equal,
(T )tuple not equal
Module
Operators not requiring licensing
tuple not equal ( long T1, long T2, long *Nequal )
T tuple not equal ( Htuple T1, Htuple T2, Htuple *Nequal )
Test, whether two tuples are not equal.
(T )tuple not equal tests whether the two input tuples T1 and T2 are not equal. Two tuples are not equal, if
they consist of a different number of elements or if they differ when compared elementwise. Two tuple elements
differ, if they are of types that may not be compared (e.g. one string and one integer) or if they differ in their values.
HALCON/C Reference Manual / 2000-11-15

13.4. CONVERSION 831
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Nequal (output control) ..................................................integer (Htuple .) long *
Result of the comparison of the input tuples.
Parallelization Information
(T )tuple not equal is reentrant and processed without parallelization.
Alternatives
(T )tuple equal, (T )tuple less, (T )tuple greater, (T )tuple less equal,
(T )tuple greater equal
Module
Operators not requiring licensing
13.4 Conversion
tuple chr ( long T, char *Chr )
T tuple chr ( Htuple T, Htuple *Chr )
Convert a tuple of integers into strings with the corresponding ASCII codes.
(T )tuple chr converts the input tuple T, consisting of integer numbers, into a tuple of strings of length 1, the
characters of which have the ASCII code of the corresponding input number.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
Restriction : ´0 Tµ 255
º Chr (output control) .................................................string(-array) (Htuple .) char *
Strings corresponding to the ASCII code of the input tuple.
Parallelization Information
(T )tuple chr is reentrant and processed without parallelization.
(T )tuple chrt
(T )tuple ord, (T )tuple ords
Operators not requiring licensing
Alternatives
See Also
Module
tuple chrt ( long T, char *Chrt )
T tuple chrt ( Htuple T, Htuple *Chrt )
Convert a tuple of integers into strings with the corresponding ASCII codes.
(T )tuple chrt converts the input tuple T, consisting of integer numbers, into a tuple of strings and integer
numbers (where only the number 0 can occur in the output), the characters of which have the ASCII code of the
corresponding input number. The operator tries to pack as many of the input numbers into one string as possible.
Only if the value 0 occurs in T the current string is terminated at this point, the integer number 0 is inserted into
HALCON 6.0

832 CHAPTER 13. TUPLE
the output, and a new string with the remaining input values is started. This operator can be used to convert data
read with read serial into strings. With this mechanism it is possible to read bytes with the value 0.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
Restriction : ´0 Tµ 255
º Chrt (output control) ........................................string(-array) (Htuple .) char * / long *
Strings corresponding to the ASCII code of the input tuple.
Example
read_serial (SerialHandle, 100, Data)
tuple_chrt (Data, Strings)
Parallelization Information
(T )tuple chrt is reentrant and processed without parallelization.
(T )tuple chr
Alternatives
See Also
(T )tuple ord, (T )tuple ords, read serial
Operators not requiring licensing
Module
tuple deg ( double Rad, double *Deg )
T tuple deg ( Htuple Rad, Htuple *Deg )
Convert a tuple from radians to degrees.
(T )tuple deg converts the input tuple Rad from radians to degrees. The result is always returned as a floating
point number. The conversion of a string is not allowed.
Parameter
º Rad (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Deg (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Input tuple in degrees.
Parallelization Information
(T )tuple deg is reentrant and processed without parallelization.
(T )tuple rad
Operators not requiring licensing
See Also
Module
tuple number ( double T, double *Number )
T tuple number ( Htuple T, Htuple *Number )
Convert a tuple (of strings) into a tuple of numbers.
(T )tuple number converts the input tuple T into a tuple of numbers. If the input tuple contains numbers,
they are simply copied into the output tuple. Strings are converted into the appropriate type of number (integer or
floating point numbers) or are copied as strings if they do not represent a number.
HALCON/C Reference Manual / 2000-11-15

13.4. CONVERSION 833
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long / const char *
Input tuple.
º Number (output control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double * / long * / char *
Input tuple as numbers.
Parallelization Information
(T )tuple number is reentrant and processed without parallelization.
(T )tuple is number, (T )tuple string
Operators not requiring licensing
See Also
Module
tuple ord ( const char *T, long *Ord )
T tuple ord ( Htuple T, Htuple *Ord )
Convert a tuple of strings of length 1 into a tuple of their ASCII codes.
(T )tuple ord converts the input tuple T, which may only contain strings of length 1, into a tuple of integer
numbers that represent the ASCII code of the characters of the strings.
Parameter
º T (input control) ...............................................string(-array) (Htuple .) const char *
Input tuple.
º Ord (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
ASCII code of the input tuple.
Parallelization Information
(T )tuple ord is reentrant and processed without parallelization.
(T )tuple ords
(T )tuple chr, (T )tuple chrt
Operators not requiring licensing
Alternatives
See Also
Module
tuple ords ( const char *T, long *Ords )
T tuple ords ( Htuple T, Htuple *Ords )
Convert a tuple of strings into a tuple of their ASCII codes.
(T )tuple ords converts the input tuple T, which may only contain strings and integer numbers, into a tuple
of integer numbers that represent the ASCII code of the characters of the strings. The characters of the individual
strings are output according to their order within the string and within the tuple. Integer numbers are simply copied
to an appropriate position in the output string. This operator can be used to prepare outputs with write serial.
In particular, a byte with value 0 can be written by inserting the integer number 0 into T.
Parameter
º T (input control) .........................................string(-array) (Htuple .) const char * / long
Input tuple.
º Ords (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
ASCII code of the input tuple.
HALCON 6.0

834 CHAPTER 13. TUPLE
Example
tuple_ords (["String 1", 0, "String 2", 0], Data)
write_serial (SerialHandle, Data)
Parallelization Information
(T )tuple ords is reentrant and processed without parallelization.
(T )tuple ord
Alternatives
See Also
(T )tuple chr, (T )tuple chrt, write serial
Operators not requiring licensing
Module
tuple real ( double T, double *Real )
T tuple real ( Htuple T, Htuple *Real )
Convert a tuple into a tuple of floating point numbers.
(T )tuple real converts the input tuple T into a tuple of floating point numbers. The conversion of a string is
not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Real (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Input tuple as floating point numbers.
Parallelization Information
(T )tuple real is reentrant and processed without parallelization.
Operators not requiring licensing
Module
tuple round ( double T, long *Round )
T tuple round ( Htuple T, Htuple *Round )
Convert a tuple into a tuple of integer numbers.
(T )tuple round converts the input tuple T into a tuple of integer numbers by rounding T to the nearest integer.
The conversion of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Round (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long *
Input tuple as integer numbers.
Parallelization Information
(T )tuple round is reentrant and processed without parallelization.
Operators not requiring licensing
Module
HALCON/C Reference Manual / 2000-11-15

13.4. CONVERSION 835
tuple string ( double T, const char *Format, char *String )
T tuple string ( Htuple T, Htuple Format, Htuple *String )
Convert a tuple into a tuple of strings.
(T )tuple string converts numbers to strings or modifies strings. The operator has two parameters: T is the
number or string that has to be converted. Format specifies the conversion. This format string consists of the
following four parts
So a conversion might look like
tuple\_string(1332.4554, ’.6e’, String)
flags Zero or more flags, in any order, which modify the meaning of the conversion specification. Flags may
consist of the following characters:
- The result of the conversion is left justified within the field.
+ The result of a signed conversion always begins with a sign, + or -.
space If the first character of a signed conversion is not a sign, a space character is prefixed to the
result. This means that if the space flag and + flag both appear, the space flag is ignored.
# The value is to be converted to an “alternate form”. For d and s conversions, this flag has no effect. For
o conversion (see below), it increases the precision to force the first digit of the result to be a zero. For
x or X conversion (see below), a non- zero result has 0x or 0X prefixed to it. For e, E, f, g, andG
conversions, the result always contains a radix character, even if no digits follow the radix character. For
g and G conversions, trailing zeros are not removed from the result, contrary to usual behavior.
field width An optional string of decimal digits to specify a minimum field width. For an output field, if
the converted value has fewer characters than the field width, it is padded on the left (or right, if the leftadjustment
flag, - has been given) to the field width.
precision The precision specifies the minimum number of digits to appear for the d, o, x, orX conversions
(the field is padded with leading zeros), the number of digits to appear after the radix character for the e and
f conversions, the maximum number of significant digits for the g conversion, or the maximum number of
characters to be printed from a string in s conversion. The precision takes the form of a period . followed
by a decimal digit string. A null digit string is treated as a zero.
conversion characters A conversion character indicates the type of conversion to be applied:
d,o,x,X The integer argument is printed in signed decimal (d), unsigned octal (o), or unsigned hexadecimal
notation (x and X). The x conversion uses the numbers and letters 0123456789abcdef, and
the X conversion uses the numbers and letters 0123456789ABCDEF. The precision component of the
argument specifies the minimum number of digits to appear. If the value being converted can be represented
in fewer digits than the specified minimum, it is expanded with leading zeroes. The default
precision is 1. The result of converting a zero value with a precision of 0 is no characters.
f The floating-point number argument is printed in decimal notation in the style [-]dddrddd, wherethe
number of digits after the radix character, r, is equal to the precision specification. If the precision is
omitted from the argument, six digits are output; if the precision is explicitly 0, no radix appears.
e,E The floating-point-number argument is printed in the style [-]drddde¦dd, where there is one digit
before the radix character, and the number of digits after it is equal to the precision. When the precision
is missing, six digits are produced; if the precision is 0, no radix character appears. The E conversion
character produces a number with E introducing the exponent instead of e. The exponent always contains
at least two digits. However, if the value to be printed requires an exponent greater than two digits,
additional exponent digits are printed as necessary.
g,G The floating-point-number argument is printed in style f or e (or in style E in the case of a G conversion
character), with the precision specifying the number of significant digits. The style used depends on the
value converted; style e is used only if the exponent resulting from the conversion is less than -4 or
greater than or equal to the precision. Trailing zeros are removed from the result. A radix character
appears only if it is followed by a digit.
HALCON 6.0

836 CHAPTER 13. TUPLE
s The argument is taken to be a string, and characters from the string are printed until the end of the string
or the number of characters indicated by the precision specification of the argument is reached. If the
precision is omitted from the argument, it is interpreted as infinite and all characters up to the end of the
string are printed.
b Similar to the s conversion specifier, except that the string can contain backslash-escape sequences which
are then converted to the characters they represent.
In no case does a nonexistent or insufficient field width cause truncation of a field; if the result of a conversion
is wider than the field width, the field is simply expanded to contain the conversion result.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long / const char *
Input tuple.
º Format (input control) ...............................................string (Htuple .) const char *
Format string.
º String (output control) .............................................string(-array) (Htuple .) char *
Input tuple converted to strings.
Parallelization Information
(T )tuple string is reentrant and processed without parallelization.
(T )tuple sub
Operators not requiring licensing
Alternatives
Module
13.5 Creation
tuple concat ( long T1, long T2, long *Concat )
T tuple concat ( Htuple T1, Htuple T2, Htuple *Concat )
Concatenate two tuple to a new one.
(T )tuple concat concatenates the input tuples T1 and T2 to a new tuple Concat. The first elements of
Concat conform to the elements of T1 and the remaining elements of Concat conform to those of T2
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple 2.
º Concat (output control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long * / double * / char *
Concatentaion of input tuples.
Parallelization Information
(T )tuple concat is reentrant and processed without parallelization.
Alternatives
(T )tuple gen const, (T )tuple str bit select, (T )tuple select,
(T )tuple str first n, (T )tuple str last n
Operators not requiring licensing
Module
tuple gen const ( long Length, long Const, long *Newtuple )
T tuple gen const ( Htuple Length, Htuple Const, Htuple *Newtuple )
Generate a tuple of a specific length and initialize its elements.
HALCON/C Reference Manual / 2000-11-15

13.6. ELEMENT-ORDER 837
(T )tuple gen const generates a new tuple in Newtuple. The input parameter Length determines the
number of elements for the new tuple. Thus Length may only consist of a single number. If Length contains a
floating point number, this may only represent an integer value (without fraction). The data type and value of each
element of the new generated tuple is determined by the input parameter Const that may only consist of a single
element. All elements in Newtuple have got the same data type and value as the single element in Const.
Parameter
º Length (input control) ............................................number (Htuple .) long / double
Length of tuple to generate.
º Const (input control) .................................number (Htuple .) long / double / const char *
Konstante f”ur die Initialisierung der Tupelelemente.: description.english: Constant for initializing the tuple
elements.
º Newtuple (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
New Tuple.
Parallelization Information
(T )tuple gen const is reentrant and processed without parallelization.
Alternatives
(T )tuple str bit select, (T )tuple select, (T )tuple str first n,
(T )tuple str last n, (T )tuple concat
Operators not requiring licensing
Module
13.6 Element-Order
tuple inverse ( long Tuple, long *Inverted )
T tuple inverse ( Htuple Tuple, Htuple *Inverted )
Invert a tuple.
(T )tuple inverse inverts the input tuple Tuple. Thus Inverted contains the same elements as Tuple
but with the reverse order.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Inverted (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
Inverted input tuple.
Parallelization Information
(T )tuple inverse is reentrant and processed without parallelization.
(T )tuple sort, (T )tuple sort index
Operators not requiring licensing
Alternatives
Module
tuple sort ( long Tuple, long *Sorted )
T tuple sort ( Htuple Tuple, Htuple *Sorted )
Sorts the elements of a tuple in ascending order.
(T )tuple sort sorts all elements of Tuple in ascending order and returns the result with Sorted. As a
precondition the single elements of Tuple must be comparable. Thus Tuple must either exclusively consist of
HALCON 6.0

838 CHAPTER 13. TUPLE
strings or it must only contain (integer or floating point) numbers. In the latter case integers and floating point
numbers may be mixed.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Sorted (output control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long * / double * / char *
Sorted tuple.
Parallelization Information
(T )tuple sort is reentrant and processed without parallelization.
Alternatives
(T )tuple sort index, (T )tuple inverse
Operators not requiring licensing
Module
tuple sort index ( long Tuple, long *Indices )
T tuple sort index ( Htuple Tuple, Htuple *Indices )
Sorts the elements of a tuple and returns the indices of the sorted tuple.
(T )tuple sort index sorts all elements of Tuple in ascending order and returns the indices of the elements
of the sorted tuple (in relation to the input tuple Tuple) with Indices. As a precondition the single elements
of Tuple must be comparable. Thus Tuple must either exclusively consist of strings or it must only contain
(integer or floating point) numbers. In the latter case integers and floating point numbers may be mixed.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Indices (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long *
Sorted tuple.
Parallelization Information
(T )tuple sort index is reentrant and processed without parallelization.
(T )tuple sort, (T )tuple inverse
Operators not requiring licensing
Alternatives
Module
13.7 Features
tuple ceil ( double T, double *Ceil )
T tuple ceil ( Htuple T, Htuple *Ceil )
Compute the ceiling function of a tuple.
(T )tuple ceil computes the ceiling function of the input tuple T, i.e., the smallest integer greater than or
equal to T. The ceiling function is always returned as a floating point number. The ceiling function of a string is
not allowed.
HALCON/C Reference Manual / 2000-11-15

13.7. FEATURES 839
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Ceil (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Ceiling function of the input tuple.
Parallelization Information
(T )tuple ceil is reentrant and processed without parallelization.
(T )tuple ceil
Operators not requiring licensing
Alternatives
Module
tuple deviation ( long Tuple, double *Deviation )
T tuple deviation ( Htuple Tuple, Htuple *Deviation )
Return the standard deviation of the elements of a tuple.
(T )tuple deviation calculates the standard derivation of all elements of the input tuple Tuple. It returns
the derivation as a floating point number in the output parameter Deviation. The input tuple may only consist
of numbers (integer or floating point numbers).
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Deviation (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Standard deviation of tuple elements.
Parallelization Information
(T )tuple deviation is reentrant and processed without parallelization.
Alternatives
(T )tuple mean, (T )tuple sum, (T )tuple min, (T )tuple max, (T )tuple length
Operators not requiring licensing
Module
tuple floor ( double T, double *Floor )
T tuple floor ( Htuple T, Htuple *Floor )
Compute the floor function of a tuple.
(T )tuple floor computes the floor function of the input tuple T, i.e., the largest integer less than or equal to
T. The floor function is always returned as a floating point number. The floor function of a string is not allowed.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long
Input tuple.
º Floor (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Floor function of the input tuple.
Parallelization Information
(T )tuple floor is reentrant and processed without parallelization.
(T )tuple ceil
Alternatives
HALCON 6.0

840 CHAPTER 13. TUPLE
Operators not requiring licensing
Module
tuple is number ( double T, long *IsNumber )
T tuple is number ( Htuple T, Htuple *IsNumber )
Check a tuple (of strings) whether it represents numbers.
(T )tuple is number checks each element of the input tuple T whether it represents a number. If the element
is a number (real or integer), 1 is returned for that element. If the element is a string, it is checked whether the
string represents a number. If so, 1 is returned, otherwise 0.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double / long / const char *
Input tuple.
º IsNumber (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Tuple with boolean numbers.
Parallelization Information
(T )tuple is number is reentrant and processed without parallelization.
(T )tuple number
Operators not requiring licensing
See Also
Module
tuple length ( long Tuple, double *Length )
T tuple length ( Htuple Tuple, Htuple *Length )
Returns the number of elements of a tuple.
(T )tuple length returns the number of elements of the input tuple Tuple.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Length (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Number of elements of input tuple.
Parallelization Information
(T )tuple length is reentrant and processed without parallelization.
Alternatives
(T )tuple min, (T )tuple max, (T )tuple mean, (T )tuple deviation, (T )tuple sum
Operators not requiring licensing
Module
tuple max ( long Tuple, double *Max )
T tuple max ( Htuple Tuple, Htuple *Max )
Returns the maximal element of a tuple.
HALCON/C Reference Manual / 2000-11-15

13.7. FEATURES 841
(T )tuple max returns the maximal element of all elements of the input tuple Tuple. All elements of Tuple
either have to be strings or numbers (integer or floating point numbers). It is not allowed to mix strings with
numerical values. The result parameter Max will contain a floating point number, if at least one element of Tuple
is a floating point number. If all elements of Tuple are integer numbers the resulting sum will also be an integer
number.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Max (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Maximal element of the input tuple elements.
Parallelization Information
(T )tuple max is reentrant and processed without parallelization.
Alternatives
(T )tuple min, (T )tuple mean, (T )tuple deviation, (T )tuple sum, (T )tuple length
Operators not requiring licensing
Module
tuple mean ( long Tuple, double *Mean )
T tuple mean ( Htuple Tuple, Htuple *Mean )
Return the mean value of a tuple of numbers.
(T )tuple mean returns the mean value of all elements of the input tuple Tuple as a floating point number in
the output parameter Mean. The input tuple may only consist of numbers (integer or floating point numbers).
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Mean (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Mean value of tuple elements.
Parallelization Information
(T )tuple mean is reentrant and processed without parallelization.
Alternatives
(T )tuple deviation, (T )tuple sum, (T )tuple min, (T )tuple max, (T )tuple length
Operators not requiring licensing
Module
tuple min ( long Tuple, double *Min )
T tuple min ( Htuple Tuple, Htuple *Min )
Returns the minimal element of a tuple.
(T )tuple min returns the minimal element of all elements of the input tuple Tuple. All elements of Tuple
either have to be strings or numbers (integer or floating point numbers). It is not allowed to mix strings with
numerical values. The result parameter Min will contain a floating point number, if at least one element of Tuple
is a floating point number. If all elements of Tuple are integer numbers the resulting sum will also be an integer
number.
HALCON 6.0

842 CHAPTER 13. TUPLE
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Min (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Minimal element of the input tuple elements.
Parallelization Information
(T )tuple min is reentrant and processed without parallelization.
Alternatives
(T )tuple max, (T )tuple mean, (T )tuple deviation, (T )tuple sum, (T )tuple length
Operators not requiring licensing
Module
tuple sum ( long Tuple, double *Sum )
T tuple sum ( Htuple Tuple, Htuple *Sum )
Return the sum of all elements of a tuple.
(T )tuple sum returns the sum of all elements of the input tuple Tuple. All elements of Tuple either have
to be strings or numbers (integer or floating point numbers). It is not allowed to mix strings with numerical values.
The result parameter Sum will contain a floating point number, if at least one element of Tuple is a floating point
number. If all elements of Tuple are integer numbers the resulting sum will also be an integer number. If Tuple
contains strings, the concatenation will be used for building the sum.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Sum (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) double *
Sum of tuple elements.
Parallelization Information
(T )tuple sum is reentrant and processed without parallelization.
Alternatives
(T )tuple mean, (T )tuple deviation, (T )tuple min, (T )tuple max, (T )tuple length
Operators not requiring licensing
Module
13.8 Logical-Operations
tuple and ( long T1, long T2, long *And )
T tuple and ( Htuple T1, Htuple T2, Htuple *And )
Compute the logical and of two tuples.
(T )tuple and computes the logical and of the input tuples T1 and T2. If both tuples have the same length the
operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must have length
1. In this case, the operation is performed for each element of the longer tuple with the single element of the other
tuple. The input tuples must contain only integer numbers.
HALCON/C Reference Manual / 2000-11-15

13.8. LOGICAL-OPERATIONS 843
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º And (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Logical and of the input tuples.
Parallelization Information
(T )tuple and is reentrant and processed without parallelization.
Alternatives
(T )tuple or, (T )tuple xor, (T )tuple not
See Also
(T )tuple band, (T )tuple bor, (T )tuple bxor, (T )tuple bnot
Operators not requiring licensing
Module
tuple not ( long T, long *Not )
T tuple not ( Htuple T, Htuple *Not )
Compute the logical not of two tuples.
(T )tuple not computes the logical not of the input tuple T. The input tuple must contain only integer numbers.
Parameter
º T (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long
Input tuple.
º Not (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary not of the input tuple.
Parallelization Information
(T )tuple not is reentrant, local, and processed without parallelization.
Alternatives
(T )tuple and, (T )tuple or, (T )tuple xor
See Also
(T )tuple band, (T )tuple bor, (T )tuple bxor, (T )tuple bnot
Operators not requiring licensing
Module
tuple or ( long T1, long T2, long *Or )
T tuple or ( Htuple T1, Htuple T2, Htuple *Or )
Compute the logical or of two tuples.
(T )tuple or computes the logical or of the input tuples T1 and T2. If both tuples have the same length the
operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must have length
1. In this case, the operation is performed for each element of the longer tuple with the single element of the other
tuple. The input tuples must contain only integer numbers.
HALCON 6.0

844 CHAPTER 13. TUPLE
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º Or (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Logical or of the input tuples.
Parallelization Information
(T )tuple or is reentrant and processed without parallelization.
Alternatives
(T )tuple and, (T )tuple xor, (T )tuple not
See Also
(T )tuple band, (T )tuple bor, (T )tuple bxor, (T )tuple bnot
Operators not requiring licensing
Module
tuple xor ( long T1, long T2, long *Xor )
T tuple xor ( Htuple T1, Htuple T2, Htuple *Xor )
Compute the logical exclusive or of two tuples.
(T )tuple xor computes the logical exclusive or of the input tuples T1 and T2. If both tuples have the same
length the operation is performed on the corresponding elements of both tuples. Otherwise, either T1 or T2 must
have length 1. In this case, the operation is performed for each element of the longer tuple with the single element
of the other tuple. The input tuples must contain only integer numbers.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long
Input tuple 2.
º Xor (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Binary exclusive or of the input tuples.
Parallelization Information
(T )tuple xor is reentrant and processed without parallelization.
Alternatives
(T )tuple and, (T )tuple or, (T )tuple not
See Also
(T )tuple band, (T )tuple bor, (T )tuple bxor, (T )tuple bnot
Operators not requiring licensing
Module
13.9 Selection
tuple first n ( long Tuple, long Index, long *Selected )
T tuple first n ( Htuple Tuple, Htuple Index, Htuple *Selected )
Select the first elements of a tuple.
HALCON/C Reference Manual / 2000-11-15

13.9. SELECTION 845
(T )tuple first n selects the first elements of Tuple and returns them with Selected. Thus Selected
contains all elements of Tuple from the first element up to the “n-th” element of Tuple (including the “n-th”
element). The index “n” is determined by the input parameter Index. Thus Index must contain a single integer
value (if Index consists of a floating point number, this must represent an integer value without fraction). Indices
of tuple elements start at 0, that means, the first tuple element has got the index 0.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Index (input control) .............................................number (Htuple .) long / double
Index of the first element to select.
º Selected (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
Selected tuple elements.
Parallelization Information
(T )tuple first n is reentrant and processed without parallelization.
Alternatives
(T )tuple last n, (T )tuple select, (T )tuple last n, (T )tuple str bit select,
(T )tuple concat
Module
Operators not requiring licensing
tuple last n ( long Tuple, long Index, long *Selected )
T tuple last n ( Htuple Tuple, Htuple Index, Htuple *Selected )
Select all elements from index “n” to the end of a tuple.
Starting with the “n-th” element of the tuple Tuple, (T )tuple last n selects every element of Tuple and
returns it with Selected. Thus Selected contains all elements of Tuple from index “n” up to the last element
of Tuple (including the element at position “n”). The index “n” is determined by the input parameter Index.
Thus Index must contain a single integer value (if Index consists of a floating point number, this must represent
an integer value without fraction). Indices of tuple elements start at 0, that means, the first tuple element has got
the index 0.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Index (input control) .............................................number (Htuple .) long / double
Index of the first element to select.
º Selected (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
Selected tuple elements.
Parallelization Information
(T )tuple last n is reentrant and processed without parallelization.
Alternatives
(T )tuple first n, (T )tuple select, (T )tuple str bit select, (T )tuple concat
Operators not requiring licensing
Module
tuple select ( long Tuple, long Index, long *Selected )
T tuple select ( Htuple Tuple, Htuple Index, Htuple *Selected )
Select single elements of a tuple.
HALCON 6.0

846 CHAPTER 13. TUPLE
(T )tuple select selects one or more single elements of the tuple Tuple and returns them with Selected.
At this, Index determines the indices of the elements to select. Thus Index may only contain integer values (any
floating point number within Index must represent an integer value without fraction). Indices of tuple elements
start at 0, that means, the first tuple element has got the index 0.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Index (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double
Indices of the elements to select.
º Selected (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
Selected tuple element.
Parallelization Information
(T )tuple select is reentrant and processed without parallelization.
Alternatives
(T )tuple first n, (T )tuple last n, (T )tuple str bit select, (T )tuple concat
Operators not requiring licensing
Module
tuple select range ( long Tuple, long Leftindex, long Rightindex,
long *Selected )
T tuple select range ( Htuple Tuple, Htuple Leftindex,
Htuple Rightindex, Htuple *Selected )
Select several elements of a tuple.
(T )tuple select range selects several consecutive elements of the input tuple Tuple and returns them
with Selected. Atthis,Leftindex determines the index of the first element and Rightindex determines
the index of the last element to select. Thus both parameters Leftindex and Rightindex must contain a
single integer value (any floating point number must represent an integer value without fraction). Indices of tuple
elements start at 0, that means, the first tuple element has got the index 0. The result tuple Selected contains
every element from the tuple Tuple that has got an index between Leftindex and Rightindex (including
the elements at position Leftindex and Rightindex). The index Rightindex must be greater or equal to
Leftindex. If the parameters contain equal values, only one element is selected.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double / const char *
Input tuple.
º Leftindex (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double
Index of first element to select.
º Rightindex (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) long / double
Index of last element to select.
º Selected (output control) . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long * / double * / char *
Selected tuple elements.
Parallelization Information
(T )tuple select range is reentrant and processed without parallelization.
Alternatives
(T )tuple select, (T )tuple first n, (T )tuple last n, (T )tuple str bit select,
(T )tuple concat
Module
Operators not requiring licensing
HALCON/C Reference Manual / 2000-11-15

13.10. STRING-OPERATORS 847
tuple str bit select ( const char *Tuple, long Index, char *Selected )
T tuple str bit select ( Htuple Tuple, Htuple Index, Htuple *Selected )
Select single character or bit from a tuple.
(T )tuple str bit select selects a single character or bit from a tuple Tuple of integer numbers and/or
strings. The input parameter Index determines the character or bit position to select. Index must contain a single
number. If Index contains a floating point number, this may only represent an integer value (without fraction).
The result tuple Selected contains a new element for each element of Tuple. LetIndex contain the number
“n” then each element of Selected consists of the “n-th” character (for strings) or “n-th” bit (for integers) of the
corresponding element of Tuple.
Parameter
º Tuple (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) const char * / long
Input tuple.
º Index (input control) .............................................number (Htuple .) long / double
Position of character or bit to select.
º Selected (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .number(-array) (Htuple .) char * / long *
Tuple containing the selected characters and bits.
Parallelization Information
(T )tuple str bit select is reentrant and processed without parallelization.
Alternatives
(T )tuple str bit select, (T )tuple select, (T )tuple first n, (T )tuple last n,
(T )tuple concat, (T )tuple strchr, (T )tuple strrchr, (T )tuple str first n,
(T )tuple str last n, (T )tuple and, (T )tuple or, (T )tuple xor, (T )tuple not
Operators not requiring licensing
Module
13.10 String-Operators
tuple environment ( const char *Names, char *Values )
T tuple environment ( Htuple Names, Htuple *Values )
Read one or more environment variables.
(T )tuple environment reads the content of all environment variables that are referenced by their names in
the input tuple Names and returns the content with the output tuple Values. The input tuple may only contain
strings. An empty string is returned for every name within Names that does not denote a valid environment
variable.
Parameter
º Names (input control) ..........................................string(-array) (Htuple .) const char *
Tuple containing name(s) of the environment variable(s).
º Values (output control) .............................................string(-array) (Htuple .) char *
Content of the environment variable(s).
Parallelization Information
(T )tuple environment is reentrant and processed without parallelization.
Alternatives
(T )tuple strstr, (T )tuple strrstr, (T )tuple strchr, (T )tuple strrchr,
(T )tuple strlen, (T )tuple str first n, (T )tuple str last n, (T )tuple split
Operators not requiring licensing
Module
HALCON 6.0

848 CHAPTER 13. TUPLE
tuple split ( const char *T1, const char *T2, char *Splitted )
T tuple split ( Htuple T1, Htuple T2, Htuple *Splitted )
Split strings into substrings between predefined separator symbol(s).
(T )tuple split searches within the strings of the input tuple T1 for one or more separators defined in the
input tuple T2. (T )tuple split then splits the examined strings into the substrings between the separators.
Both input tuples may only consist of strings. Otherwise (T )tuple split returns an error. If the elements of
T2 contain more than one character, each character defines a separator. If T1 consists only of one string, this is split
up several times according to the elements of T2. For example: If T1 consists of the string “data1;data2:7;data3”
and T2 contains the strings “;” and “:;”, the output tuple Splitted will comprise the strings “data1”, “data2:7”,
“data3” as the result of splitting the string of T1 according to the first element of T2 and “data1”, “data2”, “7” und
“data3” as the result of splitting according to the second element of T2. If both input tuples show the same number
of elements, the search is done elementwise. I.e., (T )tuple split will split the first string of T1 according to
the separators in the first element of T2, the second string of T1 according to the separators in the second element
of T2 and so on. If T2 only contains one string, the separators defined in this string will be used to split up all the
strings of T1. If both input tuples contain more than one element and the number of elements differs for the input
tuples, (T )tuple split returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 2.
º Splitted (output control) ..........................................string(-array) (Htuple .) char *
Substrings after splitting the input strings.
Parallelization Information
(T )tuple split is reentrant and processed without parallelization.
Alternatives
(T )tuple strstr, (T )tuple strrstr, (T )tuple strchr, (T )tuple strrchr,
(T )tuple strlen, (T )tuple str first n, (T )tuple str last n, (T )tuple environment
Operators not requiring licensing
Module
tuple str first n ( const char *T1, long T2, char *Substring )
T tuple str first n ( Htuple T1, Htuple T2, Htuple *Substring )
Cut the first characters up to position “n” out of string tuple.
(T )tuple str first n cuts the first characters up to position “n” out of each string of the input tuple T1 and
returns them as new strings in the output tuple Substring (remark: the position within strings starts with 0 for
the first character of a string). The number “n” is determined by the second input tuple T2. IfT2 only contains
one element, this element contains the number “n”. If T1 and T2 have got the same number of elements, the first
element of T2 determines the number “n” of characters to cut out of the first string of T1, the second element of
T2 does so for the second string of T1 andsoon. IfT2 contains more than one element and T1 contains only
one string, (T )tuple str first n cuts more than one substrings out of this string. The elements of T2 then
determine the lengths of these substrings. If both input tuples contain more than one element but differ in the
number of elements, (T )tuple str first n returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double
Input tuple 2.
HALCON/C Reference Manual / 2000-11-15

13.10. STRING-OPERATORS 849
º Substring (output control) ........................................string(-array) (Htuple .) char *
The first characters up to position “n” of each string.
Parallelization Information
(T )tuple str first n is reentrant and processed without parallelization.
Alternatives
(T )tuple str last n, (T )tuple strstr, (T )tuple strrstr, (T )tuple strlen,
(T )tuple strchr, (T )tuple strrchr, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple str last n ( const char *T1, long T2, char *Substring )
T tuple str last n ( Htuple T1, Htuple T2, Htuple *Substring )
Cut all characters starting at position “n” out of string tuple.
(T )tuple str last n cuts all characters from positiion “n” to the end of the string out of each string of the
input tuple T1 and returns them as new strings in the output tuple Substring. The position “n” is determined
by the second input tuple T2. IfT2 only contains one element, this element contains “n”. If T1 and T2 have got
the same number of elements, the first element of T2 determines the start position for the first string of T1, the
second element of T2 does so for the second string of T1 and so on. If T2 contains more than one element and T1
contains only one string, (T )tuple str last n cuts more than one substrings out of this string. The elements
of T2 then determine the start positions for these substrings. If both input tuples contain more than one element
but differ in the number of elements, (T )tuple str last n returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double
Input tuple 2.
º Substring (output control) ........................................string(-array) (Htuple .) char *
The last characters starting at position “n”.
Parallelization Information
(T )tuple str last n is reentrant and processed without parallelization.
Alternatives
(T )tuple str last n, (T )tuple strstr, (T )tuple strrstr, (T )tuple strlen,
(T )tuple strchr, (T )tuple strrchr, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple strchr ( const char *T1, const char *T2, long *Position )
T tuple strchr ( Htuple T1, Htuple T2, Htuple *Position )
Forward search for a character within a string tuple.
(T )tuple strchr searches within the strings of the input tuple T1 for the characters of the input tuple T2.
Both input tuples may only consist of strings. Otherwise (T )tuple strchr returns an error. If the elements
of T2 contain more than one character, only the first character of each element is considered for searching. If T1
contains only one string, all the characters defined in T2 are searched in this string. Thus the output tuple consists
of as many elements as T2. Whenever a searched character has been found, the position of its first occurence
gets stored in the output tuple Position (remark: the position starts at 0 for the first character of a string). If a
character can not be found, -1 will be returned instead of its position. If both input tuples show the same number
HALCON 6.0

850 CHAPTER 13. TUPLE
of elements, the search is done elementwise. I.e., the first character of the first element of T2 is searched within
the first string of T1, the first character of the second element of T2 is searched within the second string of T1
and so on. The results of the elementwise searches are returned with Position that contains as many elements
as T1 and T2. IfT2 only contains one string, its first character is searched within all strings of T1. Thus in this
case Position consists of as many elements as T1. If both input tuples contain more than one element and the
number of elements differs for the input tuples, (T )tuple strchr returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 2.
º Position (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Position of searched character(s) within the string(s).
Parallelization Information
(T )tuple strchr is reentrant and processed without parallelization.
Alternatives
(T )tuple strrchr, (T )tuple strstr, (T )tuple strrstr, (T )tuple strlen,
(T )tuple str first n, (T )tuple str last n, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple strlen ( long T1, long *Length )
T tuple strlen ( Htuple T1, Htuple *Length )
Length of every string within a tuple of strings.
(T )tuple strlen checks the length of every string within the input tuple T1 and returns the length of
each string with the output tuple Length. All elements of T1 may only consist of strings. Otherwise
(T )tuple strlen returns an error.
Parameter
º T1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) long / double / const char *
Input tuple.
º Length (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) (Htuple .) long *
Length of the single strings of the input tuple.
Parallelization Information
(T )tuple strlen is reentrant and processed without parallelization.
Alternatives
(T )tuple strstr, (T )tuple strrstr, (T )tuple strchr, (T )tuple strrchr,
(T )tuple str first n, (T )tuple str last n, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple strrchr ( const char *T1, const char *T2, long *Position )
T tuple strrchr ( Htuple T1, Htuple T2, Htuple *Position )
Backward search for a character within a string tuple.
(T )tuple strrchr searches within the strings of the input tuple T1 for the characters of the input tuple
T2. Both input tuples may only consist of strings. Otherwise (T )tuple strrchr returns an error. In any
HALCON/C Reference Manual / 2000-11-15

13.10. STRING-OPERATORS 851
case backward search is used, i.e., every string is examined from its last to its first character. If the elements of
T2 contain more than one character, only the first character of each element is considered for searching. If T1
contains only one string, all the characters defined in T2 are searched in this string. Thus the output tuple consists
of as many elements as T2. Whenever a searched character has been found, the position of its first occurence gets
stored in the output tuple Position . If a character can not be found, -1 will be returned instead of its position
(remark: the position starts at 0 for the first character of a string). If both input tuples show the same number of
elements, the search is done elementwise. I.e., the first character of the first element of T2 is searched within the
first string of T1, the first character of the second element of T2 is searched within the second string of T1 and
so on. The results of the elementwise searches are returned with Position that contains as many elements as
T1 and T2. If T2 only contains one string, its first character is searched within all strings of T1. Thus in this
case Position consists of as many elements as T1. If both input tuples contain more than one element and the
number of elements differs for the input tuples, (T )tuple strrchr returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 2.
º Position (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Position of searched character within the string.
Parallelization Information
(T )tuple strrchr is reentrant and processed without parallelization.
Alternatives
(T )tuple strchr, (T )tuple strstr, (T )tuple strrstr, (T )tuple strlen,
(T )tuple str first n, (T )tuple str last n, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple strrstr ( const char *T1, const char *T2, long *Position )
T tuple strrstr ( Htuple T1, Htuple T2, Htuple *Position )
Backward search for string(s) within a string tuple.
(T )tuple strrstr searches within the strings of the input tuple T1 for the strings of the input tuple T2. Both
input tuples may only consist of strings. Otherwise (T )tuple strrstr returns an error. In any case backward
search is used, i.e., every string is examined from its last to its first character. If T1 contains only one string, all
strings of T2 are searched in it. Thus the output tuple consists of as many elements as T2. Whenever a searched
string has been found, the position of its first occurence gets stored in the output tuple Position (positions in
strings are counted starting with 0). If a string can not be found, -1 will be returned instead of its position. If both
input tuples show the same number of elements, the strings are searched elementwise. I.e., the first string of T2 is
searched within the first string of T1, the second string of T2 is searched within the second string of T1 and so on.
The results of the elementwise searches are returned with Position that contains as many elements as T1 and
T2. IfT2 only contains one string, this is searched within all strings of T1. Thus in this case Position consists
of as many elements as T1. If both input tuples contain more than one element and the number of elements differs
for the input tuples, (T )tuple strrstr returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 2.
º Position (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Position of searched string(s) within the examined string(s).
Parallelization Information
(T )tuple strrstr is reentrant and processed without parallelization.
HALCON 6.0

852 CHAPTER 13. TUPLE
Alternatives
(T )tuple strstr, (T )tuple strlen, (T )tuple strchr, (T )tuple strrchr,
(T )tuple str first n, (T )tuple str last n, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
tuple strstr ( const char *T1, const char *T2, long *Position )
T tuple strstr ( Htuple T1, Htuple T2, Htuple *Position )
Forward search for string(s) within a string tuple.
(T )tuple strstr searches within the strings of the input tuple T1 for the strings of the input tuple T2. Both
input tuples may only consist of strings. Otherwise (T )tuple strstr returns an error. If T1 contains only
one string, all strings of T2 are searched in it. Thus the output tuple consists of as many elements as T2. Whenever
a searched string has been found, the position of its first occurence gets stored in the output tuple Position
(positions in strings are counted starting with 0). If a string can not be found, -1 will be returned instead of its
position. If both input tuples show the same number of elements, the strings are searched elementwise. I.e., the
first string of T2 is searched within the first string of T1, the second string of T2 is searched within the second
string of T1 and so on. The results of the elementwise searches are returned with Position that contains as
many elements as T1 and T2. IfT2 only contains one string, this is searched within all strings of T1. Thus in this
case Position consists of as many elements as T1. If both input tuples contain more than one element and the
number of elements differs for the input tuples, (T )tuple strstr returns an error.
Parameter
º T1 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 1.
º T2 (input control) ..............................................string(-array) (Htuple .) const char *
Input tuple 2.
º Position (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) (Htuple .) long *
Position of searched string(s) within the examined string(s).
Parallelization Information
(T )tuple strstr is reentrant and processed without parallelization.
Alternatives
(T )tuple strrstr, (T )tuple strlen, (T )tuple strchr, (T )tuple strrchr,
(T )tuple str first n, (T )tuple str last n, (T )tuple split, (T )tuple environment
Operators not requiring licensing
Module
HALCON/C Reference Manual / 2000-11-15

Chapter 14
XLD
14.1 Access
T get contour xld ( Hobject Contour, Htuple *Row, Htuple *Col )
Return the coordinates of an XLD contour.
T get contour xld returns the following values of the XLD contour Contour:
Row Row coordinate of the contour’s points
Col Column coordinate of the contour’s points
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input XLD contour.
º Row (output control) ................................................point.y-array Htuple . double *
Row coordinate of the contour’s points.
º Col (output control) ................................................point.x-array Htuple . double *
Column coordinate of the contour’s points.
Parallelization Information
T get contour xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
See Also
T get contour attrib xld, T query contour attribs xld,
T get contour global attrib xld, T query contour global attribs xld
Sub-pixel operators
Module
T get lines xld ( Hobject Polygon, Htuple *BeginRow, Htuple *BeginCol,
Htuple *EndRow, Htuple *EndCol, Htuple *Length, Htuple *Phi )
Return an XLD polygon’s data (as lines).
T get lines xld returns the XLD polygon Polygon as a set of lines. The following values are returned:
BeginRow: Rows coordinates of the lines’ start points
BeginCol: Columns coordinates of the lines’ start points
EndRow: Row coordinates of the lines’ end points
EndCol: Column coordinates of the lines’ end points
Length: Lengths of the line segments
Phi: Angles of the line segments
853

854 CHAPTER 14. XLD
Parameter
º Polygon (input object) ...................................................xld poly(-array) Hobject
Input XLD polygons.
º BeginRow (output control) .....................................line.begin.y-array Htuple . double *
Row coordinates of the lines’ start points.
º BeginCol (output control) .....................................line.begin.x-array Htuple . double *
Column coordinates of the lines’ start points.
º EndRow (output control) ..........................................line.end.y-array Htuple . double *
Column coordinates of the lines’ end points.
º EndCol (output control) ..........................................line.end.x-array Htuple . double *
Column coordinates of the lines’ end points.
º Length (output control) ...............................................real-array Htuple . double *
Lengths of the line segments.
º Phi (output control) ..............................................angle.rad-array Htuple . double *
Angles of the line segments.
Parallelization Information
T get lines xld is reentrant and automatically parallelized (on tuple level).
gen polygons xld
T get polygon xld
Sub-pixel operators
Possible Predecessor Functions
Alternatives
Module
T get parallels xld ( Hobject Parallels, Htuple *Row1, Htuple *Col1,
Htuple *Length1, Htuple *Phi1, Htuple *Row2, Htuple *Col2,
Htuple *Length2, Htuple *Phi2 )
Return an XLD parallel’s data (as lines).
T get parallels xld returns the following values of the XLD parallels Parallels:
Row1: Row coordinates of the points on polygon P1
Col1: Column coordinates of the points on polygon P1
Length1: Lengths of the line segments on polygon P1
Phi1: Angles of the line segments on polygon P1
Row2: Row coordinates of the points on polygon P2
Col2: Column coordinates of the points on polygon P2
Length2: Lengths of the line segments on polygon P2
Phi2: Angles of the line segments on polygon P2
Parameter
º Parallels (input object) ............................................................xld Hobject
Input XLD parallels.
º Row1 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long *
Row coordinates of the points on polygon P1.
º Col1 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long *
Column coordinates of the points on polygon P1.
º Length1 (output control) ..............................................real-array Htuple . double *
Lengths of the line segments on polygon P1.
º Phi1 (output control) .............................................angle.rad-array Htuple . double *
Angles of the line segments on polygon P1.
º Row2 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.y-array Htuple . long *
Row coordinates of the points on polygon P2.
º Col2 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polygon.x-array Htuple . long *
Column coordinates of the points on polygon P2.
HALCON/C Reference Manual / 2000-11-15

14.2. CREATION 855
º Length2 (output control) ..............................................real-array Htuple . double *
Lengths of the line segments on polygon P2.
º Phi2 (output control) .............................................angle.rad-array Htuple . double *
Angles of the line segments on polygon P2.
Parallelization Information
T get parallels xld is reentrant and processed without parallelization.
gen parallels xld
T get polygon xld, T get lines xld
Sub-pixel operators
Possible Predecessor Functions
See Also
Module
T get polygon xld ( Hobject Polygon, Htuple *Row, Htuple *Col,
Htuple *Length, Htuple *Phi )
Return an XLD polygon’s data.
T get polygon xld returns the following values of the XLD polygon Polygon:
Row Row coordinates of the polygons’ points
Col Column coordinates of the polygons’ points
Length Lengths of the line segments between points and ·½, respectively
Phi Angles of the line segments between points and ·½, respectively
Parameter
º Polygon (input object) ..........................................................xld poly Hobject
Input XLD polygon.
º Row (output control) ................................................point.y-array Htuple . double *
Row coordinates of the polygons’ points.
º Col (output control) ................................................point.x-array Htuple . double *
Column coordinates of the polygons’ points.
º Length (output control) ...............................................real-array Htuple . double *
Lengths of the line segments.
º Phi (output control) ..............................................angle.rad-array Htuple . double *
Angles of the line segments.
Parallelization Information
T get polygon xld is reentrant and processed without parallelization.
gen polygons xld
T get lines xld
Sub-pixel operators
Possible Predecessor Functions
Alternatives
Module
14.2 Creation
T gen contour polygon xld ( Hobject *Contour, Htuple Row, Htuple Col )
Generate an XLD contour from a polygon (given as tuples).
T gen contour polygon xld generates an XLD contour Contour from a polygon given in the tuples Row
and Col. This operator is useful if contours have been obtained from routines outside the core library, but higher
level operators, e.g., polygon approximation and extraction of parallels, are to be performed on the contours.
HALCON 6.0

856 CHAPTER 14. XLD
Parameter
º Contour (output object) .......................................................xld cont Hobject *
Resulting contour.
º Row (input control) ............................................number-array Htuple . double / long
Row coordinates of the polygon.
Default Value : ’[0,1,2,2,2]’
Value Suggestions : Row ¾0, 1, 2, 3, 4, 5, 10, 20, 50, 100, 200, 500
º Col (input control) ............................................number-array Htuple . double / long
Column coordinates of the polygon.
Default Value : ’[0,0,0,1,2]’
Value Suggestions : Col ¾0, 1, 2, 3, 4, 5, 10, 20, 50, 100, 200, 500
Parallelization Information
T gen contour polygon xld is reentrant and processed without parallelization.
get region contour
Possible Predecessor Functions
Possible Successor Functions
smooth contours xld, gen polygons xld
gen contours skeleton xld
Sub-pixel operators
See Also
Module
gen contour region xld ( Hobject Regions, Hobject *Contours,
const char *Mode )
Generate XLD contours from regions.
gen contour region xld generates XLD contours Contours from the regions given in Regions. This
operator is useful if regions have been obtained from segmentation operations, but higher level operators, e.g.,
polygon approximation and extraction of parallels, are to be performed on their boundaries. For each connected
component of the input regions a closed contour of the boundary is generated. The parameter Mode can take on
the following values:
¯ ’center’: The centers of the border pixels are used as contour points.
¯ ’border’: The outer border of the border pixels is used as contour points.
The difference between the two modes can be seen by considering the following region:
where ¾ symbolizes a single pixel.
Then, computing the contour with ’border’ and ’center’ results in the following two contours, respectively:
’border’
’center’
HALCON/C Reference Manual / 2000-11-15

14.2. CREATION 857
This means, for example, that countours generated with ’border’ will in general have a much larger Euclidean
length (see (T )length xld) than countours generated with ’center’. This results from the fact that for diagonal
border elements ’border’ uses two contour segments of length 1 each, whereas ’center’ uses a single segment of
length Ô ¾. Other features, e.g., the area (see (T )area center xld), will obviously also have different values.
Parameter
º Regions (input object) .....................................................region(-array) Hobject
Input regions.
º Contours (output object) ...............................................xld cont(-array) Hobject *
Resulting contours.
º Mode (input control) ............................................................string const char *
Mode of contour generation.
Default Value : ’border’
Value List : Mode ¾’border’, ’center’
Parallelization Information
gen contour region xld is reentrant and processed without parallelization.
Possible Successor Functions
smooth contours xld, gen polygons xld
Alternatives
T gen contour polygon xld, get region contour
gen contours skeleton xld
Sub-pixel operators
See Also
Module
gen contours skeleton xld ( Hobject Skeleton, Hobject *Contours,
long Length, const char *Mode )
Convert a skeleton into XLD contours.
gen contours skeleton xld converts the input skeleton (e.g., edges) Skeleton, which is assumed to
contain mostly one pixel wide regions (see skeleton), into XLD contours. The regions are first transformed
to contain only line segments in 8-neighborhood. In the process 12 special configurations are taken into account:
Points for which there is a junction of three or more lines in 8-neighborhood are preserved (in all four rotations):
¼ ¼ ½
½ ½ ¼
¼ ½ ¼
¼ ½ ¼
¼ ½ ½
¼ ½ ¼
¼ ½ ¼
½ ½ ½
¼ ½ ¼
In a second step, all junction points are labelled, taking six different characteristic configurations of all four possible
rotations into account:
½ ¼ ½
¼ ¾ ¼
¼ ¼ ½
½ ¼ ½
¼ ¾ ¼
½ ¼ ½
½ ¼ ¼
¼ ¾ ½
¼ ½ ¼
½ ¼ ¼
¼ ¾ ½
½ ¼ ¼
¼ ½ ¼
¼ ¾ ½
¼ ½ ¼
¼ ½ ¼
½ ¾ ½
¼ ½ ¼
where 0 = background, 1 = foreground, and 2 = junction point.
After this, all contours having at least Length points are returned. The contours generated by
gen contours skeleton xld always end in junction or end points. For closed contours the first point lies in
the 8-neighborhood of the last point of the contour. Therefore, in order to determine the adjacency of contours it is
sufficient to just take the end points into account.
Since contours are split at junction points, possibly long contours may be split into several short segments because
of short adjacent lines, even if they are longer than Length points, if Mode = ’filter’ was selected. This can be
avoided by setting Mode = ’generalize1’. In this case, the contours are generated as if the segments shorter than
Length were not contained in the input region. In order to preserve line segments, which are split into very short
HALCON 6.0

858 CHAPTER 14. XLD
segments by the crossing of short lines, Mode = ’generalize2’ can be selected. In this case, line segments are
preserved if they end in two junction points, even if they are shorter than Length.
Parameter
º Skeleton (input object) ..........................................................region Hobject
Skeleton of which the contours are to be determined.
º Contours (output object) ................................................xld cont-array Hobject *
Resulting contours.
º Length (input control) ...............................................................integer long
Minimum number of points a contour has to have.
Default Value : 1
Value Suggestions : Length ¾1, 2, 3, 5, 10, 20
º Mode (input control) ............................................................string const char *
Contour filter mode.
Default Value : ’filter’
Value List : Mode ¾’filter’, ’generalize1’, ’generalize2’
Parallelization Information
gen contours skeleton xld is reentrant and processed without parallelization.
skeleton
Possible Predecessor Functions
Possible Successor Functions
smooth contours xld, T get contour xld, gen polygons xld
See Also
edges image, threshold, get region contour
Sub-pixel operators
Module
gen ellipse contour xld ( Hobject *ContEllipse, double Row,
double Column, double Phi, double Radius1, double Radius2,
double StartPhi, double EndPhi, const char *PointOrder,
double Resolution )
T gen ellipse contour xld ( Hobject *ContEllipse, Htuple Row,
Htuple Column, Htuple Phi, Htuple Radius1, Htuple Radius2,
Htuple StartPhi, Htuple EndPhi, Htuple PointOrder, Htuple Resolution )
Creation of an XLD contour corresponding to an elliptic arc.
(T )gen ellipse contour xld creates one or more elliptic arcs or closed ellipses. Ellipses are specified by
their center (Row, Column), the orientation of the main axis Phi, the length of the larger half axis Radius1,
and the length of the smaller half axis Radius2. In addition to that, elliptic arcs are characterized by the angle
of the start point StartPhi, the angle of the end point EndPhi, and the point order PointOrder along the
boundary. The angles in the interval ¼ ¾℄ are measured in the coordinate system of the ellipse relative to the
main axis. Thus, the two main poles correspond to the angles ¼ and , the two other poles to the angles ¾ and
¿¾. To create a closed ellipse the values ¼ and ¾ (with positive point order) have to be passed to the operator.
The resolution of the resulting contours ContEllipse is controlled via Resolution containing the maximum
Euclidean distance between neighboring contour points.
Parameter
º ContEllipse (output object) ..........................................xld cont(-array) Hobject *
Resulting contour.
º Row (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y(-array) (Htuple .) double
Row coordinate of the center of the ellipse.
º Column (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x(-array) (Htuple .) double
Column coordinate of the center of the ellipse.
HALCON/C Reference Manual / 2000-11-15

14.2. CREATION 859
º Phi (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.angle.rad(-array) (Htuple .) double
Orientation of the main axis [rad].
Restriction : ´Phi 0µ ´Phi 6.283185307µ
º Radius1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1(-array) (Htuple .) double
Length of the larger half axis.
Restriction : Radius1 0
º Radius2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2(-array) (Htuple .) double
Length of the smaller half axis.
Restriction : Radius2 0
º StartPhi (input control) ............................................real(-array) (Htuple .) double
Angle of the start point [rad].
Restriction : ´StartPhi 0µ ´StartPhi 6.283185307µ
º EndPhi (input control) ...............................................real(-array) (Htuple .) double
Angle of the end point [rad].
Restriction : ´EndPhi 0µ ´EndPhi 6.283185307µ
º PointOrder (input control) ...................................string(-array) (Htuple .) const char *
point order along the boundary.
Value List : PointOrder ¾’positive’, ’negative’
º Resolution (input control) ................................................real (Htuple .) double
Resolution: Maximum distance bewteen neighboring contour points.
Default Value : 1.5
Restriction : Resolution 0
Example
draw_ellipse(WindowHandle,&Row,&Column,&Phi,&Radius1,&Radius2);
gen_ellipse_contour_xld(&Ellipse,Row,Column,Phi,Radius1,Radius2,0,6.28319,
"positive");
length_xld(Ellipse,&Length);
Result
(T )gen ellipse contour xld returns H MSG TRUE if all parameter values are correct. If necessary, an
exception is raised.
Parallelization Information
(T )gen ellipse contour xld is reentrant and processed without parallelization.
draw ellipse
disp xld, get points ellipse
Sub-pixel operators
Possible Predecessor Functions
Possible Successor Functions
Module
gen parallels xld ( Hobject Polygons, Hobject *Parallels, double Len,
double Dist, double Alpha, const char *Merge )
Extract parallel XLD polygons.
gen parallels xld examines the XLD polygons passed in Polygons for parallelism. The resulting parallel
polygons are returned in Parallels. If the parameter Merge is set to ’true’, adjacent parallel polygons are
returned in a single parallel relation. Otherwise, one parallel relation is returned for each pair of parallel line
segments. Whether two polygon segments are parallel depends on their distance (smaller than Dist), a maximum
allowed angle difference (Alpha, in radians), and a minimum length of the two polygon segments. Furthermore,
the two segments have to overlap. As a side effect, a quality factor is calculated for each pair of parallels. It is
based on the normalized angular difference and the normalized length of the overlapping area:
ÕÙÐØÝ Æ«
¾
¾ÓÚÖÐÔ
with ¼ Õ ½
ÐÒ ½ · ÐÒ ¾
HALCON 6.0

860 CHAPTER 14. XLD
Here, Æ« is the angle difference of the polygon segments, ÓÚÖÐÔ is the length of the overlap area, ÐÒ ½ and Ð ¾ the
length of the polygon segments, and ÕÙÐØÝ the resulting quality factor.
The quality factor is a measure of parallelism (the larger its value, the “more parallel” the polygons). Finally, the
quality factors of all parallel polygon segments contained in a single polygon are added, weighted with their length
of the overlapping area.
Parameter
º Polygons (input object) ...................................................xld poly-array Hobject
Input polygons.
º Parallels (output object) ...............................................xld para-array Hobject *
Parallel polygons.
º Len (input control) ..........................................................number double / long
Mimimum length of the individual polygon segments.
Default Value : 10.0
Value Suggestions : Len ¾5.0, 10.0, 15.0, 20.0
Restriction : Len 0.0
º Dist (input control) ........................................................number double / long
Maximum distance between the polygon segments.
Default Value : 30.0
Value Suggestions : Dist ¾20.0, 25.0, 30.0, 40.0, 50.0, 75.0
Restriction : Dist 0.0
º Alpha (input control) .......................................................number double / long
Maximum angle difference of the polygon segments.
Default Value : 0.15
Value Suggestions : Alpha ¾0.05, 0.10, 0.15, 0.20, 0.30
Restriction : ´0 Alphaµ ´Alpha ´pi2µµ
º Merge (input control) ..........................................................string const char *
Should adjacent parallel relations be merged?
Default Value : ’true’
Value List : Merge ¾’true’, ’false’
Parallelization Information
gen parallels xld is reentrant and processed without parallelization.
gen polygons xld
Possible Predecessor Functions
Possible Successor Functions
mod parallels xld, T get parallels xld
Sub-pixel operators
Module
gen polygons xld ( Hobject Contours, Hobject *Polygons,
const char *Type, double Alpha )
Approximate XLD contours by polygons.
gen polygons xld approximates XLD contours (Contours) by polygons. The type of the approximation
can be set by Type. The threshold for the approximation is set via Alpha. The procedure is able to process open
as well as closed contours. The resulting approximating XLD polygons are returned in Polygons.
Contours can be approximated by the algorithms of Ramer, Ray, and Sato. The algorithm of Ramer approximates
contours such that the Euclidian distance of the approximating polygon to the contour is at most Alpha pixel units.
The algorithm of Ray does not need a threshold, and hence Alpha is ignored. Here, the contour is approximated
by maximizing the line length, while minimizing the sum of the distances of the line segment from the contour.
The algorithm of Sato produces a polygon point at the point of the contour in which the distance to the end points
of the contour is maximal. The total approximation error for each iteration is then given by ´Ä Ä ¼ µÄ, whereÄ
is the Euclidian contour length, and Ä ¼ is the length of the approximating polygon.
HALCON/C Reference Manual / 2000-11-15

14.2. CREATION 861
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Contours to be approximated.
º Polygons (output object) ................................................xld poly-array Hobject *
Approximating polygons.
º Type (input control) ............................................................string const char *
Type of approximation.
Default Value : ’ramer’
Value List : Type ¾’ramer’, ’ray’, ’sato’
º Alpha (input control) .......................................................number double / long
Threshold for the approximation.
Default Value : 2.0
Value Suggestions : Alpha ¾1.0, 1.5, 2.0, 3.0, 4.0
Restriction : Alpha 0.0
Parallelization Information
gen polygons xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
gen parallels xld
get region polygon
Sub-pixel operators
Possible Successor Functions
See Also
Module
mod parallels xld ( Hobject Parallels, Hobject Image,
Hobject *ModParallels, Hobject *ExtParallels, double Quality,
long MinGray, long MaxGray, double MaxStandard )
Extract parallel XLD polygons enclosing a homogeneous area.
mod parallels xld selects XLD parallels enclosing homogeneous areas from the input parallels
Parallels. The parameter Image contains the corresponding gray value image.
Only parallels having a quality factor larger than Quality are examined. The algorithm performs parallel cross
sections one pixel apart, and parallel to the line segments in the area of overlap between two parallel line segments.
In the first iteration, the mean gray value for each of the lines in the cross section is calculated. In the second
iteration, the standard deviations of the gray values along each line are computed.
If the mean gray value of an area between parallels lies in the interval [MinGray,MaxGray], and if the mean of all
standard deviations is smaller than the upper threshold MaxStandard, the corresponding parallels are returned
as modified parallels in ModParallels.
In a second step, all polygon segments adjacent to parallels bordering homogeneous areas are checked for homogeneity.
To do so, a rectangle having the witdth of the last area enclosed by a modified parallel is constructed,
and checked for homogeneity using the algorithm described above. This process is continued as long as there are
adjacent polygon segments. The polygons thus found are returned as extended parallels in ExtParallels.
Parameter
º Parallels (input object) ..................................................xld para-array Hobject
Input XLD parallels.
º Image (input object) ..............................................................image Hobject
Corresponding gray value image.
º ModParallels (output object) ......................................xld mod para-array Hobject *
Modified XLD parallels.
º ExtParallels (output object) .......................................xld ext para-array Hobject *
Modified XLD parallels.
HALCON 6.0

862 CHAPTER 14. XLD
º Quality (input control) ....................................................number double / long
Minimum quality factor (measure of parallelism).
Default Value : 0.4
Value Suggestions : Quality ¾0.1, 0.2, 0.3, 0.4, 0.5, 0.6
Restriction : ´0.0 Qualityµ ´Quality 1.0µ
º MinGray (input control) .............................................................integer long
Minimum mean gray value.
Default Value : 160
Value Suggestions : MinGray ¾80, 100, 120, 140, 160, 180
Restriction : ´0 MinGrayµ ´MinGray 255µ
º MaxGray (input control) .............................................................integer long
Maximum mean gray value.
Default Value : 220
Value Suggestions : MaxGray ¾140, 160, 180, 200, 220, 240
Restriction : ´´0 MaxGrayµ ´MaxGray 255µµ ´MaxGray MinGrayµ
º MaxStandard (input control) ...............................................number double / long
Maximum allowed standard deviation.
Default Value : 10.0
Value Suggestions : MaxStandard ¾5.0, 10.0, 15.0, 20.0
Restriction : MaxStandard 0.0
Parallelization Information
mod parallels xld is reentrant and processed without parallelization.
gen parallels xld
max parallels xld
info parallels xld
Sub-pixel operators
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
14.3 Features
area center xld ( Hobject XLD, double *Area, double *Row,
double *Column, char *PointOrder )
T area center xld ( Hobject XLD, Htuple *Area, Htuple *Row,
Htuple *Column, Htuple *PointOrder )
Area and center of gravity (centroid) of contours and polygons.
(T )area center xld calculates the area and center of gravity (centroid) of the region enclosed by the contours
or polygons XLD as well as the order of the points along the boundary. The area and centroid are computed
by applying Green’s theorem using only the points on the contour or polygon, i.e., no region is generated explicitly
for the purpose of calculating the features. It is assumed that the contours or polygons are closed. If this is not the
case (T )area center xld will add one point to artificially produce a closed shape. If more than one contour
or polygon is passed the results are stored as tuples in which the index of a value corresponds to the index of the
respective contour or polygon in XLD.
Parameter
º XLD (input object) .............................................................xld(-array) Hobject
Contours or polygons to be examined.
º Area (output control) ...............................................real(-array) (Htuple .) double *
Area enclosed by the contour or polygon.
º Row (output control) .............................................point.y(-array) (Htuple .) double *
Row coordinate of the centroid.
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 863
º Column (output control) .........................................point.x(-array) (Htuple .) double *
Column coordinate of the centroid.
º PointOrder (output control) .......................................string(-array) (Htuple .) char *
point order along the boundary (”positive”/”negative”).
Complexity
Let Ò be the number of points of the contour or polygon. Then the run time is Ç´Òµ.
Result
(T )area center xld returns H MSG TRUE if the input is not empty. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )area center xld is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gen contours skeleton xld, smooth contours xld, gen polygons xld
See Also
(T )moments xld, area center, moments region 2nd
Sub-pixel operators
Module
contour point num xld ( Hobject Contour, long *Length )
Return the number of points in an XLD contour.
contour point num xld returns the length of the input contour Contour, i.e.
Length.
Parameter
its number of points, in
º Contour (input object) ..........................................................xld cont Hobject
Input XLD contour.
º Length (output control) ............................................................integer long *
Number of contour points.
Parallelization Information
contour point num xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
Possible Successor Functions
T get contour xld, T get contour attrib xld
T get regress params xld
T query contour attribs xld
Sub-pixel operators
Alternatives
See Also
Module
dist ellipse contour xld ( Hobject Contours, const char *Mode,
long MaxNumPoints, long ClippingEndPoints, double Row, double Column,
double Phi, double Radius1, double Radius2, double *MinDist,
double *MaxDist, double *AvgDist, double *SigmaDist )
T dist ellipse contour xld ( Hobject Contours, Htuple Mode,
Htuple MaxNumPoints, Htuple ClippingEndPoints, Htuple Row, Htuple Column,
Htuple Phi, Htuple Radius1, Htuple Radius2, Htuple *MinDist,
Htuple *MaxDist, Htuple *AvgDist, Htuple *SigmaDist )
Distance of contours to an ellipse.
HALCON 6.0

864 CHAPTER 14. XLD
(T )dist ellipse contour xld determines the distance between the contours in Contours and an ellipse
specified by the center (Row, Column), the orientation of the main axis Phi, the length of the larger half axis
Radius1, and the length of the smaller half axis Radius2. Different measures for the distance of a contour
point ´Ü Ý µ to the ellipse are available (Mode):
’algebraic’ The distance is measured by the algebraic distance Ü ¾ · Ü Ý · Ý ¾ · Ü · Ý · ,wherethe
parameters - describing the ellipse are normalized in order to obtain Radius2 as distance of the
center of the ellipse. This measure shows a high curvature bias: Near points of high curvature on the
ellipse (like the poles on the main axis) the distance is smaller than near points with low curvature.
’geometric’ The distance is measured by the deviation ½ · ¾ ¾,where ½ , ¾ are the focal points and
corresponds to Radius1. This measure shows a low curvature bias: Near points of high curvature
on the ellipse (like the poles on the main axis) the distance is larger than near points with low curvature.
’bisec’ The distance is measured by the distance between and the intersection of the angular bisector of the
two lines through and the focal points with the ellipse. This is a very good approximation of the
orthogonal distance from to the ellipse.
The operator returns the minimum absolute distance MinDist, the maximum absolute distance MaxDist, the
average absolute distance AvgDist, and the standard deviation of the absolute distances SigmaDist of all
contour points.
To reduce the computational load, the computation of the distances can be restricted to a subset of the contour
points: If a value other than -1 is assigned to MaxNumPoints, only up to MaxNumPoints points - uniformly
distributed over the contour - are used. Due to artefacts in the pre-processing the start and end points of a contour
might be faulty. Therefore, it is possible to exclude ClippingEndPoints at the beginning and at the end of a
contour from the computation.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input contours.
º Mode (input control) ..................................................string (Htuple .) const char *
Method for the determination of the distances.
Default Value : ’bisec’
Value List : Mode ¾’geometric’, ’algebraic’, ’bisec’
º MaxNumPoints (input control) .............................................integer (Htuple .) long
Maximum number of contour points used for the computation (-1 for all points).
Default Value : -1
Restriction : MaxNumPoints 3
º ClippingEndPoints (input control) ......................................integer (Htuple .) long
Number of points at the beginning and the end of the contours to be ignored for the computation of distances.
Default Value : 0
Restriction : ClippingEndPoints 0
º Row (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y (Htuple .) double
Row coordinate of the center of the ellipse of the ellipse.
º Column (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ellipse.center.x (Htuple .) double
Column coordinate of the center of the ellipse.
º Phi (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad (Htuple .) double
Orientation of the main axis [rad].
Restriction : ´Phi 0µ ´Phi 6.283185307µ
º Radius1 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1 (Htuple .) double
Length of the larger half axis.
Restriction : Radius1 0
º Radius2 (input control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2 (Htuple .) double
Length of the smaller half axis.
Restriction : Radius2 0
º MinDist (output control) ...........................................real(-array) (Htuple .) double *
Minimaler Abstand.
º MaxDist (output control) ...........................................real(-array) (Htuple .) double *
Maximaler Abstand.
º AvgDist (output control) ...........................................real(-array) (Htuple .) double *
Mittlerer Abstand.
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 865
º SigmaDist (output control) ........................................real(-array) (Htuple .) double *
Standardabweichung des Abstands.
Example
read_image (Image, "caltab");
find_caltab (Image, &Caltab, "caltabBig.descr", 3, 112, 5)
reduce_domain (Image, Caltab, &ImageReduced);
edges_sub_pix (ImageReduced, &Edges, "lanser2", 0.5, 20, 40);
select_contours_xld (Edges, &EdgesClosed, "closed", 0, 2.0, 0, 0);
select_contours_xld (EdgesClosed, &EdgesMarks, "length", 20, 80, 0, 0);
fit_ellipse_contour_xld (EdgesMarks, "fitzgibbon", -1, 2, 0, 200, 3, 2.0,
&Row, &Column, &Phi, &Radius1, &Radius2, &StartPhi,
&EndPhi, &PointOrder);
Result
(T )dist ellipse contour xld returns H MSG TRUE if all parameter values are correct. If necessary, an
exception is raised.
Parallelization Information
(T )dist ellipse contour xld is local and processed completely exclusively without parallelization.
(T )fit ellipse contour xld
Sub-pixel operators
Possible Predecessor Functions
Module
fit circle contour xld ( Hobject Contours, const char *Algorithm,
long MaxNumPoints, double MaxClosureDist, long ClippingEndPoints,
long Iterations, double ClippingFactor, double *Row, double *Column,
double *Radius, double *StartPhi, double *EndPhi, char *PointOrder )
T fit circle contour xld ( Hobject Contours, Htuple Algorithm,
Htuple MaxNumPoints, Htuple MaxClosureDist, Htuple ClippingEndPoints,
Htuple Iterations, Htuple ClippingFactor, Htuple *Row, Htuple *Column,
Htuple *Radius, Htuple *StartPhi, Htuple *EndPhi, Htuple *PointOrder )
Approximation of XLD contours by circles.
(T )fit circle contour xld approximates the XLD contours Contours by circles. It does not perform
a segmentation of the input contours. Thus, one has to make sure that each contour corresponds to one and only
one circle. The operator returns for each contour the center (Row, Column), and the Radius.
The algorithm used for the fitting of circles can be selected via Algorithm:
’algebraic’ This approach minimizes the algebraic distance between the contour points and the resulting circle.
’ahuber’ Similar to ’algebraic’. Here the contour points are weighted to decrease the impact of outliers based
on the approach of Huber.
’atukey’ Similar to ’algebraic’. Here the contour points are weighted to decrease the impact of outliers based
on the approach of Tukey.
For ’ahuber’ and ’atukey’ a robust error statistics is used to estimate the standard deviation of the distances from
the contour points without outliers from the approximating circle. The parameter ClippingFactor (a scaling
factor for the standard deviation) controls the amount of damping outliers: The smaller the value chosen for
ClippingFactor the more outliers are detected. The detection of outliers and the least squares fitting is repeated.
The parameter Iterations specifies the number of iterations.
To reduce the computational load, the fitting of circles can be restricted to a subset of the contour points: If a value
other than -1 is assigned to MaxNumPoints, only up to MaxNumPoints points - uniformly distributed over the
contour - are used.
For circular arcs, the points on the circle closest to the start points and end points of the original contours are chosen
as start and end points. The corresponding angles refering to the X-axis are returned in StartPhi and EndPhi,
HALCON 6.0

866 CHAPTER 14. XLD
see also (T )gen ellipse contour xld. Contours, for which the distance between their start points and
their end points is less or equal MaxClosureDist are considered to be closed. Thus, they are approximated by
circles instead of circular arcs. Due to artefacts in the pre-processing the start and end points of a contour might be
faulty. Therefore, it is possible to exclude ClippingEndPoints at the beginning and at the end of a contour
from the fitting of circles. However, they are still used for the determination of StartPhi and EndPhi.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input contours.
º Algorithm (input control) ...........................................string (Htuple .) const char *
Algorithm for the fitting of circles.
Default Value : ’algebraic’
Value List : Algorithm ¾’algebraic’, ’ahuber’, ’atukey’
º MaxNumPoints (input control) .............................................integer (Htuple .) long
Maximum number of contour points used for the computation (-1 for all points).
Default Value : -1
Restriction : MaxNumPoints 3
º MaxClosureDist (input control) ...........................................real (Htuple .) double
Maximum distance between the end points of a contour to be considered as ’closed’.
Default Value : 0.0
Restriction : MaxClosureDist 0.0
º ClippingEndPoints (input control) ......................................integer (Htuple .) long
Number of points at the beginning and at the end of the contours to be ignored for the fitting.
Default Value : 0
Restriction : ClippingEndPoints 0
º Iterations (input control) ................................................integer (Htuple .) long
Maximum number of iterations.
Default Value : 3
Restriction : Iterations 0
º ClippingFactor (input control) ...........................................real (Htuple .) double
Clipping factor for the elimination of outliers (typical: 1.0 for Huber and 2.0 for Tukey).
Default Value : 2.0
Value List : ClippingFactor ¾1.0, 1.5, 2.0, 2.5, 3.0
Restriction : ClippingFactor 0
º Row (output control) .......................................circle.center.y(-array) (Htuple .) double *
Row coordinate of the center of the circle.
º Column (output control) ...................................circle.center.x(-array) (Htuple .) double *
Column coordinate of the center of the circle.
º Radius (output control) ....................................circle.radius(-array) (Htuple .) double *
Radius of circle.
º StartPhi (output control) .........................................real(-array) (Htuple .) double *
Angle of the start point [rad].
º EndPhi (output control) ............................................real(-array) (Htuple .) double *
Angle of the end point [rad].
º PointOrder (output control) .......................................string(-array) (Htuple .) char *
Point order along the boundary.
Value List : PointOrder ¾’positive’, ’negative’
Result
(T )fit circle contour xld returns H MSG TRUE if all parameter values are correct, and circles
could be fitted to the input contours. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )fit circle contour xld is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
smooth contours xld
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 867
Possible Successor Functions
(T )gen ellipse contour xld, disp circle, get points ellipse
See Also
(T )fit ellipse contour xld, (T )fit line contour xld
Sub-pixel operators
Module
fit ellipse contour xld ( Hobject Contours, const char *Algorithm,
long MaxNumPoints, double MaxClosureDist, long ClippingEndPoints,
long VossTabSize, long Iterations, double ClippingFactor, double *Row,
double *Column, double *Phi, double *Radius1, double *Radius2,
double *StartPhi, double *EndPhi, char *PointOrder )
T fit ellipse contour xld ( Hobject Contours, Htuple Algorithm,
Htuple MaxNumPoints, Htuple MaxClosureDist, Htuple ClippingEndPoints,
Htuple VossTabSize, Htuple Iterations, Htuple ClippingFactor, Htuple *Row,
Htuple *Column, Htuple *Phi, Htuple *Radius1, Htuple *Radius2,
Htuple *StartPhi, Htuple *EndPhi, Htuple *PointOrder )
Approximation of XLD contours by ellipses or elliptic arcs.
(T )fit ellipse contour xld approximates the XLD contours Contours by elliptic arcs or closed ellipses.
It does not perform a segmentation of the input contours. Thus, one has to make sure that each contour corresponds
to one and only one elliptic structure. The operator returns for each contour the center (Row, Column),
the orientation of the main axis Phi, the length of the larger half axis Radius1, and the length of the smaller half
axis Radius2 of the underlying ellipse. In addition to that, the angle corresponding to the start point and the end
point StartPhi, EndPhi, and the point order along the boundary PointOrder is returned for elliptic arcs.
These parameters are set to ¼, ¾, and ’positive’ for closed ellipses. The algorithm used for the fitting of ellipses
can be selected via Algorithm:
’fitzgibbon’ This approach minimizes the algebraic distance Ü ¾ · Ü Ý · Ý ¾ · Ü · Ý · between the
contour points ´Ü Ý µ and the resulting ellipse. The constraint ¾ ½guarantees that the resulting
polynom characterizes an ellipse (instead of a hyperbola or a parabola).
’fhuber’ Similar to ’fitzgibbon’. Here the contour points are weighted to decrease the impact of outliers based
on the approach of Huber.
’ftukey’ Similar to ’fitzgibbon’. Here the contour points are weighted to decrease the impact of outliers based
on the approach of Tukey.
’voss’ Each input contour is transformed in an affine standard position. Based on the moments of the transformed
contour (that is of the enclosed image region) the standard circular segment is choosen whose
standard position matches best with the standard position of the contour. The ellipse corresponding to
the standard position of the selected circular segment is re-transformed based on the affine transformation
which produced the standard position of the contour resulting in the ellipse matching the original
contour. VossTabSize standard circular segments are used for this computation. To speed up the
process the corresponding moments and other data is stored in a table which is created during the first
call (with a specific value for VossTabSize)to(T )fit ellipse contour xld.
’focpoints’ Each point È on an ellipse satisfies the constraint that the sum of distances to the focal points ½ , ¾
equals twice the length of the larger half axis . In this approach, the deviation È ½ · È ¾ ¾ is
minimized for all contour points by a least squares optimization.
’fphuber’ Similar to ’focpoints’. Here a weighted least squares optimization is done to decrease the impact of
outliers based on the approach of Huber.
’fptukey’ Similar to ’focpoints’. Here a weighted least squares optimization is done to decrease the impact of
outliers based on the approach of Tukey.
For ’*Huber’ and ’*Tukey’ a robust error statistics is used to estimate the standard deviation of the distances
from the contour points without outliers from the approximating ellipse. The parameter ClippingFactor (a
scaling factor for the standard deviation) controls the amount of damping outliers: The smaller the value chosen
for ClippingFactor the more outliers are detected. The detection of outliers and the least squares fitting in the
mode ’focpoints’ is repeated. The parameter Iterations specifies the number of iterations.
HALCON 6.0

868 CHAPTER 14. XLD
To reduce the computational load, the fitting of ellipses can be restricted to a subset of the contour points: If a
value other than -1 is assigned to MaxNumPoints, only up to MaxNumPoints points - uniformly distributed
over the contour - are used.
For elliptic arcs, the points on the ellipse closest to the start points and end points of the original contours are
chosen as start and end points. The corresponding angles refering to the main axis of the ellipse are returned
in StartPhi and EndPhi, see also (T )gen ellipse contour xld. Contours, for which the distance
between their start points and their end points is less or equal MaxClosureDist are considered to be closed.
Thus, they are approximated by ellipses instead of elliptic arcs. Due to artefacts in the pre-processing the start
and end points of a contour might be faulty. Therefore, it is possible to exclude ClippingEndPoints at the
beginning and at the end of a contour from the fitting of ellipses. However, they are still used for the determination
of StartPhi and EndPhi.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input contours.
º Algorithm (input control) ...........................................string (Htuple .) const char *
Algorithm for the fitting of ellipses.
Default Value : ’fitzgibbon’
Value List : Algorithm ¾’fitzgibbon’, ’fhuber’, ’ftukey’, ’voss’, ’focpoints’, ’fphuber’, ’fptukey’
º MaxNumPoints (input control) .............................................integer (Htuple .) long
Maximum number of contour points used for the computation (-1 for all points).
Default Value : -1
Restriction : MaxNumPoints 3
º MaxClosureDist (input control) ...........................................real (Htuple .) double
Maximum distance between the end points of a contour to be considered as ’closed’.
Default Value : 0.0
Restriction : MaxClosureDist 0.0
º ClippingEndPoints (input control) ......................................integer (Htuple .) long
Number of points at the beginning and at the end of the contours to be ignored for the fitting.
Default Value : 0
Restriction : ClippingEndPoints 0
º VossTabSize (input control) ..............................................integer (Htuple .) long
Number of circular segments used for the Voss approach.
Default Value : 200
Restriction : ´VossTabSize 25µ ´VossTabSize 5000µ
º Iterations (input control) ................................................integer (Htuple .) long
Maximum number of iterations (unused for ’fitzgibbon’ and ’voss’).
Default Value : 3
Restriction : Iterations 0
º ClippingFactor (input control) ...........................................real (Htuple .) double
Clipping factor for the elimination of outliers (typical: 1.0 for ’*Huber’ and 2.0 for ’*Tukey’).
Default Value : 2.0
Value List : ClippingFactor ¾1.0, 1.5, 2.0, 2.5, 3.0
Restriction : ClippingFactor 0
º Row (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.y(-array) (Htuple .) double *
Row coordinate of the center of the ellipse.
º Column (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.center.x(-array) (Htuple .) double *
Column coordinate of the center of the ellipse.
º Phi (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.angle.rad(-array) (Htuple .) double *
Orientation of the main axis [rad].
º Radius1 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius1(-array) (Htuple .) double *
Length of the larger half axis.
º Radius2 (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ellipse.radius2(-array) (Htuple .) double *
Length of the smaller half axis.
º StartPhi (output control) .........................................real(-array) (Htuple .) double *
Angle of the start point [rad].
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 869
º EndPhi (output control) ............................................real(-array) (Htuple .) double *
Angle of the end point [rad].
º PointOrder (output control) .......................................string(-array) (Htuple .) char *
point order along the boundary.
Value List : PointOrder ¾’positive’, ’negative’
Example
read_image (Image, "caltab");
find_caltab (Image, &Caltab, "caltabBig.descr", 3, 112, 5)
reduce_domain (Image, Caltab, &ImageReduced);
edges_sub_pix (ImageReduced, &Edges, "lanser2", 0.5, 20, 40);
select_contours_xld (Edges, &EdgesClosed, "closed", 0, 2.0, 0, 0);
select_contours_xld (EdgesClosed, &EdgesMarks, "length", 20, 80, 0, 0);
fit_ellipse_contour_xld (EdgesMarks, "fitzgibbon", -1, 2, 0, 200, 3, 2.0,
&Row, &Column, &Phi, &Radius1, &Radius2, &StartPhi,
&EndPhi, &PointOrder);
gen_ellipse_contour_xld (&EllMarks, Row, Column, Phi, Radius1, Radius2,
StartPhi, EndPhi, PointOrder, 1.5);
length_xld(EllMarks,&Length);
Result
(T )fit ellipse contour xld returns H MSG TRUE if all parameter values are correct, and ellipses
could be fitted to the input contours. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )fit ellipse contour xld is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
smooth contours xld
Possible Successor Functions
(T )gen ellipse contour xld, disp ellipse, get points ellipse
(T )fit line contour xld
Sub-pixel operators
See Also
Module
fit line contour xld ( Hobject Contours, const char *Algorithm,
long MaxNumPoints, long ClippingEndPoints, long Iterations,
double ClippingFactor, double *RowBegin, double *ColBegin, double *RowEnd,
double *ColEnd, double *Nr, double *Nc, double *Dist )
T fit line contour xld ( Hobject Contours, Htuple Algorithm,
Htuple MaxNumPoints, Htuple ClippingEndPoints, Htuple Iterations,
Htuple ClippingFactor, Htuple *RowBegin, Htuple *ColBegin, Htuple *RowEnd,
Htuple *ColEnd, Htuple *Nr, Htuple *Nc, Htuple *Dist )
Approximation of XLD contours by line segments.
(T )fit line contour xld approximates the XLD contours Contours by line segments. It does not perform
a segmentation of the input contours. Thus, one has to make sure that each contour corresponds to one and
only one line segment. The operator returns for each contour the start point (RowBegin, ColBegin), the end
point (RowEnd, ColEnd), and the regression line to the contour given by the normal vector (Nr, Nc) oftheline
and its distance Dist from the origin, i.e., the line equation is given by ÖÒ Ö · Ò ¼.
The algorithm used for the fitting of lines can be selected via Algorithm:
’regression’ Standard ’least squares’ line fitting.
HALCON 6.0

870 CHAPTER 14. XLD
’huber’ Weighted ’least squares’ line fitting, where the impact of outliers is decreased based on the approach
of Huber.
’tukey’ Weighted ’least squares’ line fitting, where the impact of outliers is decreased based on the approach of
Tukey.
’drop’ Weighted ’least squares’ line fitting, where outliers are eliminated.
’gauss’ Weighted ’least squares’ line fitting, where the impact of outliers is decreased based on the mean value
and the standard deviation of the distances of all contour points from the approximating line.
For ’huber’, ’tukey’, and ’drop’ a robust error statistics is used to estimate the standard deviation of the distances
from the contour points without outliers from the approximating line. The parameter ClippingFactor (a
scaling factor for the standard deviation) controls the amount of damping outliers: The smaller the value chosen
for ClippingFactor the more outliers are detected. The detection of outliers is repeated. The parameter
Iterations specifies the number of iterations. In the modus ’regression’ this value is ignored.
To reduce the computational load, the fitting of lines can be restricted to a subset of the contour points: If a value
other than -1 is assigned to MaxNumPoints, only up to MaxNumPoints points - uniformly distributed over the
contour - are used.
The start point and the end point of a line segment is determined by projecting the first and the last point of the
corresponding contour to the approximating line. Due to artefacts in the pre-processing the start and end points of
a contour might be faulty. Therefore, it is possible to exclude ClippingEndPoints at the beginning and at the
end of a contour from the line fitting. However, they are still used for the determination of the start point and the
end point of the line segment.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input contours.
º Algorithm (input control) ...........................................string (Htuple .) const char *
Algorithm for the fitting of lines.
Default Value : ’tukey’
Value List : Algorithm ¾’regression’, ’huber’, ’tukey’, ’gauss’, ’drop’
º MaxNumPoints (input control) .............................................integer (Htuple .) long
Maximum number of contour points used for the computation (-1 for all points).
Default Value : -1
Restriction : MaxNumPoints 3
º ClippingEndPoints (input control) ......................................integer (Htuple .) long
Number of points at the beginning and at the end of the contours to be ignored for the fitting.
Default Value : 0
Restriction : ClippingEndPoints 0
º Iterations (input control) ................................................integer (Htuple .) long
Maximum number of iterations (unused for ’regression’).
Default Value : 5
Restriction : Iterations 0
º ClippingFactor (input control) ...........................................real (Htuple .) double
Clipping factor for the elimination of outliers (typical: 1.0 for ’huber’ and ’drop’ and 2.0 for ’tukey’).
Default Value : 2.0
Value List : ClippingFactor ¾1.0, 1.5, 2.0, 2.5, 3.0
Restriction : ClippingFactor 0
º RowBegin (output control) ..................................line.begin.y(-array) (Htuple .) double *
Row coordinates of the starting points of the line segments.
º ColBegin (output control) ..................................line.begin.x(-array) (Htuple .) double *
Column coordinates of the starting points of the line segments.
º RowEnd (output control) .......................................line.end.y(-array) (Htuple .) double *
Row coordinates of the end points of the line segments.
º ColEnd (output control) .......................................line.end.x(-array) (Htuple .) double *
Column coordinates of the end points of the line segments.
º Nr (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Line parameter: Row coordinate of the normal vector
º Nc (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Line parameter: Column coordinate of the normal vector
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 871
º Dist (output control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) (Htuple .) double *
Line parameter: Distance of the line from the origin
Example
draw_ellipse(WindowHandle,Row,Column,Phi,Radius1,Radius2);
read_image (Image, ’mreut’);
edges_sub_pix (Image, Edges, ’lanser2’, 0.5, 20, 40);
gen_polygons_xld (Edges, Polygons, ’ramer’, 2);
split_contours_xld (Polygons, Contours, ’polygon’, 1, 5);
fit_line_contour_xld (Contours, ’regression’, -1, 0, 5, 2, RowBegin, ColBegin,
RowEnd, ColEnd, Nr, Nc);
Result
(T )fit line contour xld returns H MSG TRUE if all parameter values are correct, and line segments
could be fitted to the input contours. If the input is empty the behaviour can be set via set system
(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )fit line contour xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
smooth contours xld
Possible Successor Functions
disp line, select lines, line orientation
See Also
regress contours xld, T get regress params xld
Sub-pixel operators
Module
T get contour angle xld ( Hobject Contour, Htuple AngleMode,
Htuple CalcMode, Htuple Lookaround, Htuple *Angles )
Calculate the direction of an XLD contour for each contour point.
T get contour angle xld calculates for each point of the XLD contour Contour the direction of its tangent.
Two modes for the output values can be chosen: By passing ’abs’ for AngleMode, the resulting angles
are returned relative to the horizontal axis as angles between 0 and ¾ (counter-clockwise). By passing ’rel’, the
absolute value of the difference of angles to the previous contour point is returned. In this case the range of values
is between 0 and .
There are three different ways of calculating the tangent direction (CalcMode) of the contour point using the
contour points in the interval from Lookaround to · Lookaround. Byusing’range’, the angle of the
line segment between the first and last point of the interval is used. For ’mean’, the average of all angles between
consecutive points of the contour is used. Finally, for ’regress’, the direction of the regression line (the least
squares fit of a line to the contour points in the interval) is used. Lookaround is a measure of how strongly the
contour is smoothed. The angles are returned in Angles in radians.
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input contour.
º AngleMode (input control) .............................................string Htuple . const char *
Return type of the angles.
Default Value : ’abs’
Value List : AngleMode ¾’abs’, ’rel’
º CalcMode (input control) ..............................................string Htuple . const char *
Method for computing the angles.
Default Value : ’range’
Value List : CalcMode ¾’range’, ’mean’, ’regress’
HALCON 6.0

872 CHAPTER 14. XLD
º Lookaround (input control) .................................................integer Htuple . long
Number of points to take into account.
Default Value : 3
Restriction : Lookaround 0
º Angles (output control) ...............................................real-array Htuple . double *
Direction of the tangent to the contour points.
Parallelization Information
T get contour angle xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
See Also
T get contour xld, T get contour attrib xld
Sub-pixel operators
Module
T get contour attrib xld ( Hobject Contour, Htuple Name,
Htuple *Attrib )
Return point attribute values of an XLD contour.
T get contour attrib xld returns the values of the attribute Name of the XLD contour Contour in
Attrib. Attributes are additional values defined for each contour point, e.g. the direction perpendicular to
the contour (’angle’). Operators which define this kind of attributes, e.g., lines gauss and edges sub pix,
contain a description of the name and semantics of the defined values. T query contour attribs xld can
be used to query which attributes are defined for a particular contour.
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input XLD contour.
º Name (input control) ....................................................string Htuple . const char *
Name of the attribute.
Default Value : ’angle’
Value Suggestions : Name ¾’angle’, ’edge direction’, ’width right’, ’width left’, ’response’, ’contrast’,
’asymmetry’
º Attrib (output control) ...............................................real-array Htuple . double *
Attribute values.
Parallelization Information
T get contour attrib xld is reentrant and processed without parallelization.
Possible Predecessor Functions
lines gauss, lines facet, edges sub pix
See Also
T query contour attribs xld, T get contour global attrib xld,
T query contour global attribs xld
Module
Sub-pixel operators
T get contour global attrib xld ( Hobject Contour, Htuple Name,
Htuple *Attrib )
Return global attributes values of an XLD contour.
T get contour global attrib xld returns the values of the global attribute Name of the XLD contour
Contour in Attrib. Global attributes are additional values defined for each contour, e.g., the
normal vector of the regression line of a contour (’regr norm row’ and ’regr norm col’). Operators
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 873
which define this kind of attributes contain a description of the name and semantics of the defined values.
T query contour global attribs xld can be used to query which attributes are defined for a particular
contour.
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input XLD contour.
º Name (input control) .............................................string(-array) Htuple . const char *
Name of the attribute.
Default Value : ’regr norm row’
Value Suggestions : Name ¾’regr norm row’, ’regr norm col’, ’regr mean dist’, ’regr dev dist’,
’cont approx’
º Attrib (output control) ...............................................real-array Htuple . double *
Attribute values.
Parallelization Information
T get contour global attrib xld is reentrant and processed without parallelization.
Possible Predecessor Functions
lines gauss, lines facet, edges sub pix
See Also
T query contour global attribs xld, T get contour attrib xld,
T query contour attribs xld
Module
Sub-pixel operators
T get regress params xld ( Hobject Contours, Htuple *Length,
Htuple *Nx, Htuple *Ny, Htuple *Dist, Htuple *Fpx, Htuple *Fpy,
Htuple *Lpx, Htuple *Lpy, Htuple *Mean, Htuple *Deviation )
Return XLD contour parameters.
T get regress params xld returns the following parameters for all XLD contours given in Contours:
¯ the number of contour points Length,
¯ the coordinates Nx and Ny of the normal vector of the regression line (i.e., least-squares approximating line),
¯ the distance Dist of the regression line to the origin
¯ the sub-pixel precise coordinates Fpx and Fpy of the perpendicular projection of the start point of the contour
onto the regression line,
¯ the sub-pixel precise coordinates Lpx and Lpy of the perpendicular projection of the end point of the contour
onto the regression line,
¯ the mean of the Euclidian distance of the contour points from the regression line,
¯ the standard deviation of these distances.
Attention
Before the contour parameters can be returned by T get regress params xld, the parameters of the regression
line to the contour must be calculated by calling regress contours xld.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Input XLD contours.
º Length (output control) ..............................................integer-array Htuple . long *
Number of contour points.
º Nx (output control) ..................................................point.x-array Htuple . double *
X-coordinate of the normal vector of the regression line.
º Ny (output control) ..................................................point.y-array Htuple . double *
Y-coordinate of the normal vector of the regression line.
HALCON 6.0

874 CHAPTER 14. XLD
º Dist (output control) ..............................................number-array Htuple . double *
Distance of the regression line from the origin.
º Fpx (output control) ................................................point.x-array Htuple . double *
X-coordinate of the projection of the start point of the contour onto the regression line.
º Fpy (output control) ................................................point.y-array Htuple . double *
Y-coordinate of the projection of the start point of the contour onto the regression line.
º Lpx (output control) ................................................point.x-array Htuple . double *
X-coordinate of the projection of the end point of the contour onto the regression line.
º Lpy (output control) ................................................point.y-array Htuple . double *
Y-coordinate of the projection of the end point of the contour onto the regression line.
º Mean (output control) ..................................................real-array Htuple . double *
Mean distance of the contour points from the regression line.
º Deviation (output control) ...........................................real-array Htuple . double *
Standard deviation of the distances from the regression line.
Parallelization Information
T get regress params xld is reentrant and processed without parallelization.
regress contours xld
Possible Predecessor Functions
Possible Successor Functions
disp line, select lines, line orientation
See Also
(T )fit line contour xld, T get contour global attrib xld,
T query contour global attribs xld, T get contour xld, T get contour attrib xld,
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
Sub-pixel operators
Module
info parallels xld ( Hobject Parallels, Hobject Image,
double *QualityMin, double *QualityMax, long *GrayMin, long *GrayMax,
double *StandardMin, double *StandardMax )
Return information about the gray values of the area enclosed by XLD parallels.
info parallels xld calculates various gray value features of the area enclosed by the XLD parallels
Parallels. The input image Image is used to get the gray values needed for this. The algorithm used in
this operator is very similar to the one used in mod parallels xld. The operator returns ranges for the quality
factor (QualityMin and QualityMax), the mean gray value (GrayMin and GrayMax), and the standard
deviation with respect to the mean gray value (StandardMin and StandardMax).
This operator serves to determine appropriate thresholds for mod parallels xld.
Parameter
º Parallels (input object) ..................................................xld para-array Hobject
Input XLD Parallels.
º Image (input object) ..............................................................image Hobject
Corresponding gray value image.
º QualityMin (output control) .......................................................real double *
Minimum quality factor.
º QualityMax (output control) .......................................................real double *
Maximum quality factor.
º GrayMin (output control) ..........................................................integer long *
Minimum mean gray value.
º GrayMax (output control) ..........................................................integer long *
Maximum mean gray value.
º StandardMin (output control) ......................................................real double *
Minimum standard deviation.
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 875
º StandardMax (output control) ......................................................real double *
Maximum standard deviation.
Parallelization Information
info parallels xld is reentrant and processed without parallelization.
gen parallels xld
mod parallels xld
intensity, min max gray
Sub-pixel operators
Possible Predecessor Functions
Possible Successor Functions
See Also
Module
length xld ( Hobject XLD, double *Length )
T length xld ( Hobject XLD, Htuple *Length )
Length of contours or polygons.
(T )length xld calculates the length of the contours or polygons XLD. The length is calculated as the sum
of the euclidian distances of successive points on the contour or polygon. If more than one contour or polygon
is passed the results are stored as tuples in which the index of a value corresponds to the index of the respective
contour or polygon in XLD.
Parameter
º XLD (input object) .............................................................xld(-array) Hobject
Contours or polygons to be examined.
º Length (output control) ............................................real(-array) (Htuple .) double *
Length of the contour or polygon.
Assertion : Length 0
Complexity
Let Ò be the number of points of the contour or polygon. Then the run time is Ç´Òµ.
Result
(T )length xld returns H MSG TRUE if the input is not empty. If the input is empty the behaviour can be set
via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )length xld is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gen contours skeleton xld, smooth contours xld, gen polygons xld
See Also
(T )area center xld, (T )moments any xld, (T )moments xld, contlength
Sub-pixel operators
Module
local max contours xld ( Hobject Contours, Hobject Image,
Hobject *LocalMaxContours, long MinPercent, long MinDiff, long Distance )
Select XLD contours with a local maximum of gray values.
local max contours xld selects XLD contours from the contours passed in Contours, which have a local
maximum in gray values across the direction of the contour. In order to be selected, at least MinPercent of the
contour points must have a local maximum perpendicular to the direction of the contour. The contours’ direction
is determined by fitting a regression line through five neighboring points of the contour. In order to decide whether
HALCON 6.0

876 CHAPTER 14. XLD
there is a local maximum for a contour point, a gray value profile that is Distance points wide and perpendicular
to the contour is computed on both sides of the contour. If the gray value at the countour point is at least MinDiff
larger than the gray value at at least one point on each side of the profile, the contour point is labeled as a local
maximum. The selected contours are returned in LocalMaxContours.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
XLD contours to be examined.
º Image (input object) ..............................................................image Hobject
Corresponding gray value image.
º LocalMaxContours (output object) .....................................xld cont-array Hobject *
Selected contours.
º MinPercent (input control) ................................................number long / double
Minumum percentage of maximum points.
Default Value : 70
Value Suggestions : MinPercent ¾60, 70, 75, 80, 85, 90, 95
Restriction : ´0.0 MinPercentµ ´MinPercent 100.0µ
º MinDiff (input control) .............................................................integer long
Minimum amount by which the gray value at the maximum must be larger than in the profile.
Default Value : 15
Value Suggestions : MinDiff ¾5, 8, 10, 12, 15, 20
Restriction : ´0 MinDiffµ ´MinDiff 255µ
º Distance (input control) ............................................................integer long
Maximum width of profile used to check for maxima.
Default Value : 4
Value Suggestions : Distance ¾2, 3, 4, 5, 6
Restriction : Distance 1
Parallelization Information
local max contours xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
gen polygons xld
smooth contours xld
Sub-pixel operators
Possible Successor Functions
See Also
Module
max parallels xld ( Hobject ExtParallels, Hobject *MaxPolygons )
Join modified XLD parallels lying on the same polygon.
max parallels xld joins all modified XLD parallels in ExtParallels into a polygon if they lie on the
same original polygon segment. This means that polgons exhibiting parallelism and enclosing homogeneous areas
in several places are joined into one long polygon (from the first parallel line to the last parallel line). The resulting
polygons are returned in MaxPolygons.
Parameter
º ExtParallels (input object) ..........................................xld ext para-array Hobject
Extended XLD parallels.
º MaxPolygons (output object) ............................................xld poly-array Hobject *
Maximally extended parallels.
Parallelization Information
max parallels xld is reentrant and processed without parallelization.
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 877
mod parallels xld
Possible Predecessor Functions
Possible Successor Functions
T get polygon xld, T get lines xld
Sub-pixel operators
Module
moments any xld ( Hobject XLD, const char *Mode, const char *PointOrder,
double Area, double CenterRow, double CenterCol, long P, long Q,
double *M )
T moments any xld ( Hobject XLD, Htuple Mode, Htuple PointOrder,
Htuple Area, Htuple CenterRow, Htuple CenterCol, Htuple P, Htuple Q,
Htuple *M )
Arbitrary geometric moments of contours or polygons.
(T )moments any xld calculates arbitrary moments M of the region enclosed by the contours or polygons XLD.
The moments are computed by applying Green’s theorem using only the points on the contour or polygon, i.e.,
no region is generated explicitly for the purpose of calculating the features. It is assumed that the contours or
polygons are closed. If this is not the case (T )moments any xld will add one point to artificially produce a
closed shape. The computed moments are normalized depending on the desired mode Mode:
¯ ’unnormalized’: No normalization. Let Ê be the enclosed image region. Then the computed moment Å ÔÕ
is equivalent to
Å ÔÕ
Ê
Ö Ô Õ Ö
¯ ’normalized’: Normalization by the area Area of the enclosed image region:
Å ÔÕ ½
Ê
Ö Ô Õ Ö
¯ ’central’:Normalization by the area Area of the enclosed image region and a shift of the region by it’s
centroid Ö ℄ [CenterRow, CenterCol]:
Å ÔÕ ½
Ê
´Ö Öµ Ô´ µ Õ Ö
For the normalization of the moments three specific moments are used: The area Area of the enclosed image
region and the coordinates CenterRow,CenterRow of it’s centroid, see (T )area center xld. In addition
to that (T )moments any xld ecpects information about the point order of the input contours/polygons in
PointOrder, see(T )area center xld again. If more than one contour or polygon is passed, M contains
all desired moments of the first contour/polygon followed by all the moments of the second contour/polygon and
so forth.
Parameter
º XLD (input object) .............................................................xld(-array) Hobject
Contours or polygons to be examined.
º Mode (input control) ..................................................string (Htuple .) const char *
computation mode.
Default Value : ’unnormalized’
Value Suggestions : Mode ¾’unnormalized’, ’normalized’, ’central’
º PointOrder (input control) ...................................string(-array) (Htuple .) const char *
point order along the boundary.
Default Value : ’positive’
Value Suggestions : PointOrder ¾’positive’, ’negative’
HALCON 6.0

878 CHAPTER 14. XLD
º Area (input control) ..................................................real(-array) (Htuple .) double
Area enclosed by the contour or polygon.
º CenterRow (input control) ........................................point.y(-array) (Htuple .) double
Row coordinate of the centroid.
º CenterCol (input control) ........................................point.x(-array) (Htuple .) double
Column coordinate of the centroid.
º P (input control) .....................................................point.x(-array) (Htuple .) long
first index of the desired moments M[P,Q].
Default Value : 1
º Q (input control) .....................................................point.x(-array) (Htuple .) long
second index of the desired moments M[P,Q].
Default Value : 1
º M (output control) ...................................................real(-array) (Htuple .) double *
the computed moments.
Complexity
Let Ò be the number of points of the contour or polygon. Then the run time is Ç´Òµ.
Result
(T )moments any xld returns H MSG TRUE if the input is not empty. If the input is empty the behaviour can
be set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )moments any xld is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
(T )area center xld, gen contours skeleton xld, smooth contours xld,
gen polygons xld
Alternatives
(T )moments xld
See Also
(T )moments xld, (T )area center xld, moments region 2nd, area center
Sub-pixel operators
Module
moments xld ( Hobject XLD, double *M11, double *M20, double *M02 )
T moments xld ( Hobject XLD, Htuple *M11, Htuple *M20, Htuple *M02 )
Geometric moments M20, M02, and M11 of contours or polygons.
(T )moments xld calculates the moments (M20, M02, andM11) of the region enclosed by the contours or
polygons XLD. Seemoments region 2nd for the definition of these features. The moments are computed by
applying Green’s theorem using only the points on the contour or polygon, i.e., no region is generated explicitly
for the purpose of calculating the features. It is assumed that the contours or polygons are closed. If this is not
the case (T )moments xld will add one point to artificially produce a closed shape. If more than one contour
or polygon is passed the results are stored as tuples in which the index of a value corresponds to the index of the
respective contour or polygon in XLD.
Parameter
º XLD (input object) .............................................................xld(-array) Hobject
Contours or polygons to be examined.
º M11 (output control) ................................................real(-array) (Htuple .) double *
Mixed second order moment.
º M20 (output control) ................................................real(-array) (Htuple .) double *
Second order moment along the row axis.
º M02 (output control) ................................................real(-array) (Htuple .) double *
Second order moment along the column axis.
HALCON/C Reference Manual / 2000-11-15

14.3. FEATURES 879
Complexity
Let Ò be the number of points of the contour or polygon. Then the run time is Ç´Òµ.
Result
(T )moments xld returns H MSG TRUE if the input is not empty. If the input is empty the behaviour can be
set via set system(’no object result’,). If necessary, an exception is raised.
Parallelization Information
(T )moments xld is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
gen contours skeleton xld, smooth contours xld, gen polygons xld
(T )moments any xld
Alternatives
See Also
(T )moments any xld, (T )area center xld, moments region 2nd, area center
Sub-pixel operators
Module
T query contour attribs xld ( Hobject Contour, Htuple *Attribs )
Return the names of the defined attributes of an XLD contour.
T query contour attribs xld returns the names of the defined attributes of an XLD contour Contour in
Attribs. Attributes are additional values defined for each contour point, e.g. the direction perpendicular to the
contour (’angle’). Operators which define this kind of attributes contain a description of the name and semantics
of the defined values. T get contour attrib xld can be used to access the values of a particular attribute.
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input contour.
º Attribs (output control) ..............................................string-array Htuple . char *
List of the defined contour attributes.
Parallelization Information
T query contour attribs xld is reentrant and processed without parallelization.
Possible Predecessor Functions
lines gauss, lines facet, edges sub pix
See Also
T get contour attrib xld, T get contour global attrib xld,
T query contour global attribs xld
Module
Sub-pixel operators
T query contour global attribs xld ( Hobject Contour,
Htuple *Attribs )
Return the names of the defined global attributes of an XLD contour.
T query contour global attribs xld returns the names of the globally defined attributes of an XLD
contour Contour in Attribs. Global attributes are additional values defined for each contour, e.g.,
the normal vector of the regression line of a contour (’regr norm row’ and ’regr norm col’). Operators
which define this kind of attributes contain a description of the name and semantics of the defined values.
T get contour global attrib xld can be used to access the value of a particular attribute.
HALCON 6.0

880 CHAPTER 14. XLD
Parameter
º Contour (input object) ..........................................................xld cont Hobject
Input contour.
º Attribs (output control) ..............................................string-array Htuple . char *
List of the defined global contour attributes.
Parallelization Information
T query contour global attribs xld is reentrant and processed without parallelization.
Possible Predecessor Functions
lines gauss, lines facet, edges sub pix
See Also
T get contour global attrib xld, T get contour attrib xld,
T query contour attribs xld
Module
Sub-pixel operators
select contours xld ( Hobject Contours, Hobject *SelectedContours,
const char *Feature, double Min1, double Max1, double Min2, double Max2 )
Select XLD contours according to several features.
select contours xld selects XLD contours from the input contours Contours according to the following
features (parameter Feature):
’length’ all contours whose maximum extent (as measured by their eight extremal points in row and column
direction, according to Haralick und Shapiro: Computer and Robot Vision, Addison-Wesley 1992, chapter
3.2) is smaller than Min1 or larger than Max1 are not returned (Min2 and Max2 have no influence
here).
’direction’ only contours for which the direction of the regression line is between Min1 and Max1 (in radians,
counter-clockwise) are returned. Min1 and Max1 are mapped to the range of [0,2*PI[. (Min2 and
Max2 have no influence here).
’curvature’ only contours for which the mean distance from the regression line lies between Min1 and Max1,
and for which the standard deviation of the distances is between Min2 and Max2 are returned.
’closed’ only contours for which the distance between their start point and their end point is less or equal Max2
pixels are returned.
If Min1 = Max1 =0orMin2 = Max2 = 0 is used for the selection according to curvature, the respective feature
has no influence on the selection.
Attention
Before contour can be filtered by select contours xld according to ’direction’ or ’curvature’, the parameters
of the regression lines to the contours must be calculated by calling regress contours xld.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Input XLD contours.
º SelectedContours (output object) .....................................xld cont-array Hobject *
Output XLD contours.
º Feature (input control) .......................................................string const char *
Feature to select contours with.
Default Value : ’length’
Value List : Feature ¾’length’, ’direction’, ’curvature’, ’closed’
º Min1 (input control) ..................................................................real double
Lower threshold.
Default Value : 0.5
º Max1 (input control) ..................................................................real double
Upper threshold.
Default Value : 200.0
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 881
º Min2 (input control) ..................................................................real double
Lower threshold.
Default Value : -0.5
º Max2 (input control) ..................................................................real double
Upper threshold.
Default Value : 0.5
Parallelization Information
select contours xld is reentrant and processed without parallelization.
regress contours xld
Possible Predecessor Functions
See Also
T get contour xld, T get contour attrib xld, gen contours skeleton xld, lines gauss,
lines facet, edges sub pix, T get regress params xld,
T get contour global attrib xld, T query contour global attribs xld
Bibliography
R. Haralick, L. Shapiro: ”‘Computer and Robot Vision”’ Vol. 1; Kapitel 3.2, Addison-Wesley 1992
Sub-pixel operators
Module
14.4 Transformation
add noise white contour xld ( Hobject Contours,
Hobject *NoisyContours, long NumRegrPoints, double Amp )
Add noise to XLD contours.
add noise white contour xld adds noise to the input XLD contours Contours and returns the noisy
contours in NoisyContours. For each point along the original contours the local regression line (i.e. a leastsquares
approximating line) based on NumRegrPoints neighboring points is determined. Then the point is
shifted perpendicular to this line. The length of the shifts corresponds to white noise, equally distributed in the
interval [-Amp,Amp] generated by using the C function “drand48” with an initial time dependent seed.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Original contours.
º NoisyContours (output object) ........................................xld cont(-array) Hobject *
Noisy contours.
º NumRegrPoints (input control) .....................................................integer long
Number of points used to calculate the regression line.
Default Value : 5
Value Suggestions : NumRegrPoints ¾3, 5, 7, 9
Restriction : ´NumRegrPoints 3µ odd´NumRegrPointsµ
º Amp (input control) ...................................................................real double
Maximum amplitude of the added noise (equally distributed in [-Amp,Amp]).
Default Value : 1.0
Value Suggestions : Amp ¾0.25, 0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 10.0
Restriction : Amp 0
Example
draw_ellipse(WindowHandle,&Row,&Column,&Phi,&Radius1,&Radius2);
gen_ellipse_contour_xld(&Ellipse,Row,Column,Phi,Radius1,Radius2,0,6.28319,
"positive");
add_noise_white_contour_xld(Ellipse,&NoisyEllipse,5,0.5);
fit_ellipse_contour_xld (NoisyEllipse, "fitzgibbon", -1, 2, 0, 200, 3, 2.0,
&ERow, &EColumn, &EPhi, &ERadius1, &ERadius2,
&EStartPhi, &EEndPhi, &EPointOrder);
HALCON 6.0

882 CHAPTER 14. XLD
Result
add noise white contour xld returns H MSG TRUE if all parameter values are correct. If the input is
empty the behaviour can be set via set system(’no object result’,). If necessary, an exception
is raised.
Parallelization Information
add noise white contour xld is reentrant, local, and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
(T )gen ellipse contour xld
Possible Successor Functions
smooth contours xld
See Also
smooth contours xld, add noise white
Sub-pixel operators
Module
T affine trans contour xld ( Hobject Contours,
Hobject *ContoursAffinTrans, Htuple HomMat2D )
Apply an arbitrary affine transformation to an XLD contour.
T affine trans contour xld applies an arbitrary affine transformation, i.e., scaling, rotation, translation,
and skewing, to an XLD contour. The affine map is described by the transformation matrix given in
HomMat2D , which is built up by using hom mat2d identity, hom mat2d scale, hom mat2d rotate,
and hom mat2d translate. The components of the homogeneous transformation matrix are interpreted as follows:
the row coordinate of the image corresponds to the Ü coordinate of the matrix, while the column coordinate
of the image corresponds to the Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate
system, which is assumed for the homogeneous transformation matrices, also for the image. In particular, by doing
so roatations are performed in the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally
corresponds to the usual (row,column) order for coordinates in the image.
Attention
The components of the homogeneous transformation matrix are interpreted as follows: the row coordinate of the
image corresponds to the Ü coordinate of the matrix, while the column coordinate of the image corresponds to the
Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate system, which is assumed for the
homogeneous transformation matrices, also for the image. In particular, by doing so roatations are performed in
the correct direction. Note that the (Ü,Ý) order of the matrices quite naturally corresponds to the usual (row,column)
order for coordinates in the image.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Input XLD contours.
º ContoursAffinTrans (output object) .................................xld cont(-array) Hobject *
Transformed XLD contours.
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
Result
T affine trans contour xld returns H MSG TRUE if all parameter values are correct. If necessary, an
exception is raised.
Parallelization Information
T affine trans contour xld is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
hom mat2d identity, hom mat2d translate, hom mat2d rotate, hom mat2d scale
See Also
affine trans image, affine trans region
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 883
Sub-pixel operators
Module
T affine trans polygon xld ( Hobject Polygons,
Hobject *PolygonsAffinTrans, Htuple HomMat2D )
Apply an arbitrary affine transformation to an XLD polygon.
T affine trans polygon xld applies an arbitrary affine transformation, i.e., scaling, rotation, translation,
and skewing, to an XLD polygon. The affine map is described by the transformation matrix given in
HomMat2D , which is built up by using hom mat2d identity, hom mat2d scale, hom mat2d rotate,
and hom mat2d translate.
Attention
The components of the homogeneous transformation matrix are interpreted as follows: the row coordinate of the
image corresponds to the Ü coordinate of the matrix, while the column coordinate of the image corresponds to the
Ý coordinate of the matrix. This is necessary to obtain a right-handed coordinate system, which is assumed for the
homogeneous transformation matrices, also for the image. In particular, by doing so rotations are performed in the
correct direction. Note that the (Ü,Ý) order of the matrices quite naturally corresponds to the usual (row,column)
order for coordinates in the image.
The XLD contours that are possibly referenced by Polygons are neither transformed nor stored with the output
polygons, since this is generally impossible without creating inconsistencies for the attributes of the XLD contours.
Hence, operators that access the contours associated with a polygon, e.g., split contours xld will not work
correctly.
Parameter
º Polygons (input object) .................................................xld poly(-array) Hobject
Input XLD polygons.
º PolygonsAffinTrans (output object) .................................xld poly(-array) Hobject *
Transformed XLD polygons.
º HomMat2D (input control) ...........................................affine2d-array Htuple . double
Input transformation matrix.
Parameter Number : 6
Result
T affine trans polygon xld returns H MSG TRUE if all parameter values are correct. If necessary, an
exception is raised.
Parallelization Information
T affine trans polygon xld is reentrant and automatically parallelized (on tuple level).
Possible Predecessor Functions
hom mat2d identity, hom mat2d translate, hom mat2d rotate, hom mat2d scale
See Also
affine trans image, affine trans region, T affine trans contour xld
Sub-pixel operators
Module
clip contours xld ( Hobject Contours, Hobject *ClippedContours,
long Row1, long Column1, long Row2, long Column2 )
Clip an XLD contour.
clip contours xld clips all XLD contours given in Contours, i.e., only contour points contained in the
rectangle given by Row1, Column1, Row2, andColumn2 are returned on output. If necessary, coutours are
split, and several new contours are produced. The resulting contours are returned in ClippedContours.
HALCON 6.0

884 CHAPTER 14. XLD
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Contours to be clipped.
º ClippedContours (output object) .....................................xld cont(-array) Hobject *
Clipped contours.
º Row1 (input control) ........................................................rectangle.origin.y long
Row coordinate of the upper left corner of the clip rectangle.
Default Value : 0
Value Suggestions : Row1 ¾0, 500, 1000, 1500, 2000
º Column1 (input control) ....................................................rectangle.origin.x long
Column coordinate of the upper left corner of the clip rectangle.
Default Value : 0
Value Suggestions : Column1 ¾0, 500, 1000, 1500, 2000
º Row2 (input control) .......................................................rectangle.corner.y long
Row coordinate of the lower right corner of the clip rectangle.
Default Value : 512
Value Suggestions : Row2 ¾512, 1024, 1536, 2048
º Column2 (input control) ...................................................rectangle.corner.x long
Column coordinate of the lower right corner of the clip rectangle.
Default Value : 512
Value Suggestions : Column2 ¾512, 1024, 1536, 2048
Parallelization Information
clip contours xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
gen polygons xld
clip region, crop part
Sub-pixel operators
Possible Successor Functions
See Also
Module
combine roads xld ( Hobject EdgePolygons, Hobject ModParallels,
Hobject ExtParallels, Hobject CenterLines, Hobject *RoadSides,
double MaxAngleParallel, double MaxAngleColinear,
double MaxDistanceParallel, double MaxDistanceColinear )
Combine road hypotheses from two resolution levels.
combine roads xld combines road hypotheses obtained from two different resolution levels. The algorithm
selects only those hypotheses which mutually support each other in both resolution levels. The parameters
EdgePolygons, ModParallels and ExtParallels correspond to the road hypotheses from the highest
resolution level. The parameter CenterLines is the result of road extraction in a lower resolution level.
Those of the polygons EdgePolygons are returned for which evidence of being roadsides is found in both resolution
levels. The parameters MaxAngleParallel and MaxAngleColinear determine the angle, that may
be formed by two parallel collinear line segments, respectively. The parameters MaxDistanceParallel and
MaxDistanceColinear determine the maximum allowed distance of two parallel or colliear line segments,
respectively. The combination is done using a number of rules.
Parameter
º EdgePolygons (input object) .............................................xld poly-array Hobject
XLD polygons to be examined.
º ModParallels (input object) .........................................xld mod para-array Hobject
Modified parallels obtained from EdgePolygons.
º ExtParallels (input object) ..........................................xld ext para-array Hobject
Extended parallels obtained from EdgePolygons.
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 885
º CenterLines (input object) ...............................................xld poly-array Hobject
Road-center-line polygons to be examined.
º RoadSides (output object) ...............................................xld poly-array Hobject *
Roadsides found.
º MaxAngleParallel (input control) ......................................angle.rad double / long
Maximum angle between two parallel line segments.
Default Value : 0.523598775598
Value Suggestions : MaxAngleParallel ¾0.349065850399, 0.523598775598, 0.6981317008
Restriction : ´0 MaxAngleParallelµ ´pi2µ
º MaxAngleColinear (input control) ......................................angle.rad double / long
Maximum angle between two collinear line segments.
Default Value : 0.261799387799
Value Suggestions : MaxAngleColinear ¾0.174532925199, 0.261799387799, 0.349065850399
Restriction : ´0 MaxAngleColinearµ ´pi2µ
º MaxDistanceParallel (input control) .......................................real double / long
Maximum distance between two parallel line segments.
Default Value : 40
Value Suggestions : MaxDistanceParallel ¾20, 30, 40, 50, 60
Restriction : MaxDistanceParallel 0
º MaxDistanceColinear (input control) .......................................real double / long
Maximum distance between two collinear line segments.
Default Value : 40
Value Suggestions : MaxDistanceColinear ¾20, 30, 40, 50, 60
Restriction : MaxDistanceColinear 0
Parallelization Information
combine roads xld is processed under mutual exclusion against itself and without parallelization.
Possible Predecessor Functions
mod parallels xld, gen polygons xld, T affine trans contour xld
Possible Successor Functions
T get polygon xld, T get lines xld
See Also
lines gauss, lines facet, get channel info, edges sub pix
Bibliography
C. Steger, C. Glock, W. Eckstein, H. Mayer, B. Radig; ”‘Model-based Road Extraction from Images”’; in ”‘Automatic
Extraction of Man-Made Objects from Aerial and Space Images”’; A. Gruen, O. Kuebler, P. Agouris
(Editors); Birkh”auser Verlag (1995), pp. 275-284.
C. Heipke, C. Steger, R. Multhammer; ”‘A Hierarchical Approach to Automatic Road Extraction from Aerial
Imagery”’; in ”‘Integrating Photogrammetric Techniques with Scene Analysis and Machine Vision II”’; D. M.
McKeown, Jr., I. J. Dowman (Editors); Proc. SPIE 2486 (1995), pp. 222-231.
Module
Sub-pixel operators
gen parallel contour xld ( Hobject Contours,
Hobject *ParallelContours, const char *Mode, double Distance )
Compute the parallel contour of an XLD contour.
gen parallel contour xld computes for each of the input contours Contours a parallel contour with
distance Distance. The resulting contours are returned in ParallelContours. To calculate the parallel
contour, the normal vector of the input contour is needed in every contour point. The parameter Mode detemines
how these normal vectors are computed. If Mode = ’gradient’, it is assumed that the input contours are edges,
and the normal information is obtained from the gradient direction of the edge (see edges sub pix). For
this, the attribute ’edge direction’ must exist for the input contour. If Mode = ’contour normal’, a possibly
existing normal information is used to determine the normals. For this, the contour attribute ’angle’ must exist
(see lines gauss, lines facet,oredges sub pix). Finally, if Mode = ’regression normal’, the normal
HALCON 6.0

886 CHAPTER 14. XLD
vectors are determined from a local line fit to each contour point. Here, the normal vectors are oriented such that
they point to the right side of the contour when the contour is traversed from start to end. In contrast to the first
two modes, this mode can be used for all XLD contours, no matter how they were generated.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Contours to be transformed.
º ParallelContours (output object) .....................................xld cont-array Hobject *
Parallel contours.
º Mode (input control) ............................................................string const char *
Mode, with which the direction information is computed.
Default Value : ’regression normal’
Value Suggestions : Mode ¾’gradient’, ’contour normal’, ’regression normal’
º Distance (input control) ...................................................number double / long
Distance of the parallel contour.
Default Value : 1
Value List : Distance ¾0.2, 0.4, 0.6, 0.8, 1, 2, 3, 4, 5, 7, 10, 15, 20, 30, 40, 50
Parallelization Information
gen parallel contour xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
gen polygons xld
T get contour xld
Sub-pixel operators
Possible Successor Functions
See Also
Module
merge cont line scan xld ( Hobject CurrConts, Hobject PrevConts,
Hobject *CurrMergedConts, Hobject *PrevMergedConts, long ImageHeight,
double Margin, const char *MergeBorder, long MaxImagesCont )
Merge XLD contours from successive line scan images.
The operator merge cont line scan xld connects adjacent XLD contours, which were extracted from adjacent
images with the height ImageHeight. This operator was especially designed to connect contours that were
extracted from images grabbed by a line scan camera. CurrConts contains the contours from the current image
and PrevConts the contours from the previous one.
With the help of the parameter MergeBorder two cases can be distinguished: If the top (first) line of the current
image touches the bottom (last) line of the previous image, MergeBorder must be set to ’top’, otherwise set
MergeBorder to ’bottom’. MergeBorder defines a margin to the border. Only those end points of the
contours which are inside this margin are considered for the following merging process.
If the operator merge cont line scan xld is used recursivly, the parameter MaxImagesCont determines
the maximum number of images which are covered by a merged contour. All points of the merged contour from
an older image are removed.
The operator merge cont line scan xld returns two contour arrays. PrevMergedConts contains all
those contours from the previous input contours PrevConts, which could not be merged with a current contour.
CurrMergedConts collects all current contours together with the merged parts from the previous
images. Merged contours will exceed the original image, because the previous contours are moved upward
(MergeBorder=’top’)ordownward(MergeBorder=’bottom’) according to the image height.
Parameter
º CurrConts (input object) ................................................xld cont(-array) Hobject
Current input contours.
º PrevConts (input object) ................................................xld cont(-array) Hobject
Merged contours from the previous iteration.
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 887
º CurrMergedConts (output object) .....................................xld cont(-array) Hobject *
Current contours, merged with old ones where applicable.
º PrevMergedConts (output object) .....................................xld cont(-array) Hobject *
Contours from the previous iteration which could not be merged with the current ones.
º ImageHeight (input control) ........................................................integer long
Height of the line scan images.
Default Value : 512
Value List : ImageHeight ¾240, 480, 512
º Margin (input control) ...............................................................real double
Maximum distance of contours from the image border.
Default Value : 0
Value List : Margin ¾0, 1, 2, 3, 4, 5
º MergeBorder (input control) ..................................................string const char *
Image line of the current image, which touches the previous image.
Default Value : ”top”
Value List : MergeBorder ¾”top”, ”bottom”
º MaxImagesCont (input control) .....................................................integer long
Maximum number of images covered by one contour.
Default Value : 3
Value Suggestions : MaxImagesCont ¾1, 2, 3, 4, 5
Result
The operator merge cont line scan xld returns the value H MSG TRUE if the given parameters are correct.
Otherwise, an exception will be raised.
Parallelization Information
merge cont line scan xld is reentrant and processed without parallelization.
Sub-pixel operators
Module
regress contours xld ( Hobject Contours, Hobject *RegressContours,
const char *Mode, long Iterations )
Calculate the parameters of a regression line to an XLD contour.
regress contours xld calculates the following parameters for the input XLD contours Contours, and
stores them with the resulting contours as global attributes:
¯ the coordinates of the normal vector of the regression line, i.e., the least-squares approximating line, of all
contour points; the normal vector always points from the origin to the line (attributes: ’regr norm row’,
’regr norm col’),
¯ the mean of the Euclidian distance of the contour points from the regression line (attribute:
’regr mean dist’),
¯ the standard deviation of these distances to the regression line (attribute: ’regr dev dist’).
For Mode = ’no’, the parameters of the regression line are calculated for all points of the contour. In addition,
three different kinds of outlier treatment can be applied. Outliers are contour points which do not lie on the general
contour direction in an “obvious” manner, and thus “distort” the resulting regression line.
Mode =
¯ ’drop’: All contour points further away from the contour than the mean distance to the regression line are
ignored for the calculation of the undistorted regression line.
¯ ’gauss’: The distances of the contour points are weighted according to their probability of occurence in a
Gaussian distribution around the normal regression line.
¯ ’median’: Here, also a normal distribution is assumed for the distances to the normal regression line, however
with the outlier-independent standard deviation ÑÒ´ÐÐ×ص . Again, the distances are weighted, and points
¼
further away than a certain distance are ignored for the undistorted regression line.
HALCON 6.0

888 CHAPTER 14. XLD
The calculation of the undistorted regression line can be iterated several times (Iterations).
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Input XLD contours.
º RegressContours (output object) .......................................xld cont-array Hobject *
Resulting XLD contours.
º Mode (input control) ............................................................string const char *
Type of outlier treatment.
Default Value : ’no’
Value List : Mode ¾’no’, ’drop’, ’gauss’, ’median’
º Iterations (input control) .........................................................integer long
Number of iterations for the outlier treatment.
Default Value : 1
Value Suggestions : Iterations ¾1, 2, 3, 5, 10, 20
Parallelization Information
regress contours xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
T get regress params xld
Possible Successor Functions
See Also
smooth contours xld, T get contour global attrib xld,
T query contour global attribs xld
Bibliography
H. Suesse, K. Voss: ”‘Adaptive Ausgleichsrechnung und Ausrei”serproblematik f”ur die digitale Bildverarbeitung”’;
Proc. 15. DAGM Symposium, Springer Verlag, L”ubeck 1993
R. Haralick, L. Shapiro: ”‘Computer and Robot Vision”’ Vol. 2; Kapitel 14.9, Addison-Wesley 1992
Module
Sub-pixel operators
segment contours xld ( Hobject Contours, Hobject *ContoursSplit,
const char *Mode, long SmoothCont, double MaxLineDist1,
double MaxLineDist2 )
Segment XLD contours into line segments and circular or elliptic arcs.
segment contours xld segments the input contours Contours into lines if Mode=’lines’, into lines and circular
arcs if Mode=’lines circles’, or into lines and elliptic arcs if Mode=’lines ellipses’. The segmented contours
are returned in ContoursSplit. The information on whether an output contour represents a line or a circular of
elliptic arc is done via the global contour attribute ’cont approx’ (see T get contour global attrib xld).
If ’cont approx’=-1, the coutour is best approximated by a line segment, if ’cont approx’=0, by an elliptic arc,
and if ’cont approx’=1, by a circular arc.
segment contours xld first approximates the input contours by polygons. With this, the contours are oversegmented
in curved areas. After this, neighboring line segments are substituted by circular or elliptic arcs, respectively,
if the contour can be approximated better by an arc. If SmoothCont is set to a value ¼, the input
contours are first smoothed (see smooth contours xld). This can be necessary to prevent very short segments
in the polygonal approximation and to achieve a more robust fit with circular or elliptic arcs, because the smoothing
suppresses outliers on the contours.
The initial polygonal approximation is done by using the Ramer algorithm (see gen polygons xld) with a
maximum distance of MaxLineDist1. After this, circular or elliptic arcs are fit into neighboring line segments.
If the maximum distance of the resulting arc to the contour is smaller than the maximum distance of the two line
segments, the two line segments are replaced with the arc. This procedure is iterated until no more changes occur.
After this, the parts of the contour that are still approximated by line segments are again segmented with a
polygonal approximation with maximum distance MaxLineDist2, and the newly created line segments are
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 889
merged to circular or elliptical arcs where possible. Obviously, this changes the output only if ÅÜÄÒ×ؾ
ÅÜÄÒ×ؽ. This two-step approach is more efficient than a one-step approach with MaxLineDist2,since
fewer line segments are generated in the first step, and hence the circle or ellipse fit has to be performed less often.
Therefore, parts of the input contours that can be approximated by long arcs can be found more efficiently. In the
second step, parts of the input contours that can be approximated by short arcs are found and the end parts of long
arcs are refined.
Parameter
º Contours (input object) .................................................xld cont(-array) Hobject
Contours to be segmented.
º ContoursSplit (output object) .........................................xld cont-array Hobject *
Segmented contours.
º Mode (input control) ............................................................string const char *
Mode for the segmentation of the contours.
Default Value : ’lines circles’
Value List : Mode ¾’lines’, ’lines circles’, ’lines ellipses’
º SmoothCont (input control) .........................................................integer long
Number of points used for smoothing the contours.
Default Value : 5
Value Suggestions : SmoothCont ¾0, 3, 5, 7, 9
Restriction : ´SmoothCont 0µ ´´SmoothCont 3µ odd´SmoothContµµ
º MaxLineDist1 (input control) .......................................................real double
Maximum distance between a contour and the approximating line (first iteration).
Default Value : 4.0
Value Suggestions : MaxLineDist1 ¾1.0, 1.5, 2.0, 2.5, 3.0, 3.5
Restriction : MaxLineDist1 0.0
º MaxLineDist2 (input control) .......................................................real double
Maximum distance between a contour and the approximating line (second iteration).
Default Value : 2.0
Value Suggestions : MaxLineDist2 ¾1.0, 1.5, 2.0, 2.5, 3.0, 3.5
Restriction : MaxLineDist2 0.0
Example
read_image (Image, ’pumpe’)
edges_sub_pix (Image, Edges, ’canny’, 1.5, 15, 40)
segment_contours_xld (Edges, ContoursSplit, ’lines_circles’, 5, 4, 2)
count_obj (ContoursSplit, Number)
gen_empty_obj (Lines)
gen_empty_obj (Circles)
for I := 1 to Number by 1
select_obj (ContoursSplit, Contour, I)
get_contour_global_attrib_xld (Contour, ’cont_approx’, Type)
if (Type = -1)
concat_obj (Lines, Contour, Lines)
else
concat_obj (Circles, Contour, Circles)
endif
endfor
fit_line_contour_xld (Lines, ’tukey’, -1, 0, 5, 2, RowBegin, ColBegin,
RowEnd, ColEnd, Nr, Nc)
fit_circle_contour_xld (Circles, ’atukey’, -1, 2, 0, 3, 2, Row, Column,
Radius, StartPhi, EndPhi, PointOrder)
Parallelization Information
segment contours xld is local and processed completely exclusively without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, edges sub pix
HALCON 6.0

890 CHAPTER 14. XLD
Possible Successor Functions
(T )fit line contour xld, (T )fit ellipse contour xld, (T )fit circle contour xld
See Also
split contours xld, T get contour global attrib xld, smooth contours xld,
gen polygons xld
Module
Sub-pixel operators
smooth contours xld ( Hobject Contours, Hobject *SmoothedContours,
long NumRegrPoints )
Smooth an XLD contour.
smooth contours xld smooths the input XLD contours Contours and returns the smoothed contours in
SmoothedContours. The smoothing is done by projecting the contours’ points onto a local regression line
(i.e. a least-squares approximating line), which is computed from NumRegrPoints on each side of the current
contour point. This operator should be called, for example, before contours are scaled.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Contour to be smoothed.
º SmoothedContours (output object) .....................................xld cont-array Hobject *
Smoothed contour.
º NumRegrPoints (input control) .....................................................integer long
Number of points used to calculate the regression line.
Default Value : 5
Value Suggestions : NumRegrPoints ¾3, 5, 7, 9
Restriction : ´NumRegrPoints 3µ odd´NumRegrPointsµ
Parallelization Information
smooth contours xld is reentrant and processed without parallelization.
Possible Predecessor Functions
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
Possible Successor Functions
T affine trans contour xld, gen polygons xld, local max contours xld
T get contour xld
Sub-pixel operators
See Also
Module
split contours xld ( Hobject Polygons, Hobject *Contours,
const char *Mode, long Weight, long Smooth )
Split XLD contours at dominant points.
split contours xld splits the contours which were used to generate the polygons Polygons at prominent
points. If the mode ’polygon’ is selected, the contours are split at the polygons’ control points. In mode ’dominant’,
they are split at dominant points, i.e., at points for which the calculated change of direction is larger than
the (empirically determined) threshold ¾Weightcontour length, and for which in the (empirically determined)
neighborhood of Ô Smooth £ ÐÓ´contour lengthµ points no larger change of direction occurs. The contour direction
is determined from the direction of the regression line (i.e. the least-squares approximating line) through all
points in a neighborhood of Smooth points around a contour point. The directions thus determined are smoothed
with a Gaussian of width Smooth. Weight is a weighting factor for the sensitiveness of the operator. The larger
Weight is selected, the less dominant points are found.
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 891
Parameter
º Polygons (input object) .................................................xld poly(-array) Hobject
Polygons for which the corresponding contours are to be split.
º Contours (output object) ...............................................xld cont(-array) Hobject *
Split contours.
º Mode (input control) ............................................................string const char *
Mode for the splitting of the contours.
Default Value : ’polygon’
Value List : Mode ¾’polygon’, ’dominant’
º Weight (input control) ...............................................................integer long
Weight for the sensitiveness.
Default Value : 1
º Smooth (input control) ...............................................................integer long
Width of the smoothing mask.
Default Value : 5
Parallelization Information
split contours xld is reentrant and processed without parallelization.
gen polygons xld
regress contours xld
Possible Predecessor Functions
Possible Successor Functions
See Also
gen contours skeleton xld, lines gauss, lines facet, edges sub pix
Sub-pixel operators
Module
T union straight contours histo xld ( Hobject Contours,
Hobject *UnionContours, Hobject *SelectedContours, Htuple RefLineStartY,
Htuple RefLineStartX, Htuple RefLineEndY, Htuple RefLineEndX,
Htuple nWidth, Htuple MaxWidth, Htuple FilterSize, Htuple *HistoValues )
Merge neighboring straight contours having a similar distance from a given line.
T union straight contours histo xld merges neighboring XLD contours Contours if certain criteria
are fulfilled.
The maximum and minium distance of the contours to an given reference line are calculated. From this distances
a histogram is created. If the histogram should be smoothed, FilterSize must be greater then one. Afterwards
the resulting histogram is diveded into ranges.( from minima to minima) Contours which lie in the same range are
concatenated to a new contour. If the width of Range is greater than MaxWidth, all contours in this range are
ignored. (removed) Lies an contour in two ranges or more it is also ignored. In case there are parallel contours,
there is a danger of merging neighboring contours.
The parameters of the regression line are calculated new for merged contours.
The resulting contours cannot be displayed.
Attention
Before the contour parameters can be returned by T union straight contours histo xld, the parameters
of the regression line to the contour must be calculated by calling regress contours xld.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Input XLD contours.
º UnionContours (output object) .........................................xld cont-array Hobject *
Output XLD contours.
º SelectedContours (output object) .....................................xld cont-array Hobject *
Output XLD contours.
HALCON 6.0

892 CHAPTER 14. XLD
º RefLineStartY (input control) .............................................integer Htuple . long
y coordinate of the starting point of the reference line.
Default Value : 0
º RefLineStartX (input control) .............................................integer Htuple . long
x coordinate of the starting point of the reference line.
Default Value : 0
º RefLineEndY (input control) ................................................integer Htuple . long
y coordinate of the endpoint of the reference line.
Default Value : 0
º RefLineEndX (input control) ................................................integer Htuple . long
x coordinate of the endpoint of the reference line.
Default Value : 0
º nWidth (input control) .......................................................integer Htuple . long
Maximum distance.
Default Value : 1
º MaxWidth (input control) ....................................................integer Htuple . long
Maximum Width between two minimas.
Default Value : 1
º FilterSize (input control) .................................................integer Htuple . long
Size of Smoothfilter
Default Value : 1
Typical Range of Values : 1 FilterSize 63
º HistoValues (output control) ........................................integer-array Htuple . long *
Output Values of Histogram.
Parallelization Information
T union straight contours histo xld is reentrant and processed without parallelization.
regress contours xld
Possible Predecessor Functions
See Also
(T )fit line contour xld, T get contour xld, T get contour attrib xld,
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
T get regress params xld, T get contour global attrib xld,
T query contour global attribs xld
Module
Sub-pixel operators
union straight contours xld ( Hobject Contours,
Hobject *UnionContours, double MaxDist, double MaxDiff, double Percent,
const char *Mode, const char *Iterations )
Merge neighboring straight contours having a similar direction.
union straight contours xld merges neighboring XLD contours Contours if certain criteria are fulfilled.
The merging is not done recursively, and only between two contours. The parameter Iterations controls
how often this union step is executed.
Two contours are merged if the shortest distance between their end points (end points are the projections of the
contours’ first and last points onto its regression line) is smaller than MaxDist, and if the difference in direction
(i.e. the regression lines’ direction) is smaller than MaxDiff (radians).
If only one of the criteria is fulfilled, the decision on merging can be influenced by the weighting factor Percent,
which allows the exceeding of one limit to be balanced by the other value remaining below the limit by the
same amount. The end point distance is weighted by Percent, while the directional difference is weighted by
½¼¼ Percent.
If, for example, two contours have an end point distance of 5.0 and a directional difference of 0.5 (with the limits
chosen being MaxDist = 4.0 und MaxDiff = 0.625), both values differ from the limits by 25%. By choosing
HALCON/C Reference Manual / 2000-11-15

14.4. TRANSFORMATION 893
Percent = 60%, the larger end point distance is weigthed more than the smaller directional difference, and thus
the contours are not merged. Contrary, if Percent = 40% is chosen, the contours are merged.
For Percent = 100%, only the end point distance is taken into account, while for Percent = 0% only the
difference of direction is used. If Percent = 50% both criteria are equally valid.
In case there are parallel contours, there is a danger of merging neighboring contours. If this is to be avoided, Mode
= ’noparallel’ has to be chosen, while otherwise Mode = ’paralleltoo’ suffices. For Mode = ’every’, contours are
merged unconditionally. All other parameters have no influence in this case.
The parameters of the regression line are calculated anew for merged contours.
Attention
Before the contour parameters can be returned by T get regress params xld, the parameters of the regression
line to the contour must be calculated by calling regress contours xld.
Parameter
º Contours (input object) ...................................................xld cont-array Hobject
Input XLD contours.
º UnionContours (output object) .........................................xld cont-array Hobject *
Output XLD contours.
º MaxDist (input control) ..............................................................real double
Maximum distance of the contours’ endpoints.
Default Value : 5.0
º MaxDiff (input control) .........................................................angle.rad double
Maximum difference in direction.
Default Value : 0.5
º Percent (input control) ..............................................................real double
Weighting factor for the two selection criteria.
Default Value : 50.0
º Mode (input control) ............................................................string const char *
Should parallel contours be taken into account?
Default Value : ’noparallel’
Value List : Mode ¾’noparallel’, ’paralleltoo’, ’every’
º Iterations (input control) ..............................................string const char * / long
Number of iterations or ’maximum’.
Default Value : ’maximum’
Value Suggestions : Iterations ¾1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ’maximum’
Typical Range of Values : 1 Iterations 500 (lin)
Minimal Value Step : 1
Recommended Value Step : 1
Parallelization Information
union straight contours xld is reentrant and processed without parallelization.
regress contours xld
Possible Predecessor Functions
See Also
(T )fit line contour xld, T get contour xld, T get contour attrib xld,
gen contours skeleton xld, lines gauss, lines facet, edges sub pix,
T get regress params xld, T get contour global attrib xld,
T query contour global attribs xld
Module
Sub-pixel operators
HALCON 6.0

894 CHAPTER 14. XLD
HALCON/C Reference Manual / 2000-11-15

Index
2D-Transformation, 15, 27, 449, 621, 623–629, 882,
883
3D-Projection, 696
3D-Transformation, 622, 629, 631, 632, 634, 635
3D-projection, 708
abs funct 1d, 724
abs image,33
abs invar fourier coeff, 718
Absolute-Value, 33, 724, 813, 818
abstract, 589
Access, 726
access channel, 285
Aceess, 726
adapt template, 107
add channels, 309
add image,33
add noise distribution, 136
add noise white, 137
add noise white contour xld, 881
Addition, 33, 730, 814
Affine-Map, 27, 29–32, 449, 623, 637–639, 882, 883
Affine-Transformation, 451
Affine-Transformation., 450, 453
affine trans contour xld, 882
affine trans image,27
affine trans point 2d, 621
affine trans point 3d, 622
affine trans polygon xld, 883
affine trans region, 449
Albedo, 802, 803
Ambient, 802
and, 41
angle ll, 734
angle lx, 735
Anisometry, 479, 500
anisotrope diff, 140
Anisotropy, 317, 330
append channel, 286
append ocr trainf, 778
approx chain, 361
approx chain simple, 364
Approximation, 361, 364
Arc, 205, 361
Arccosine, 813
Arcs, 364
Arcsine, 814
Arctangent, 815
Area, 313, 473, 500, 506, 862
area center, 473
area center gray, 313
area center xld, 862
Arithmetic, 33, 35–40
Arrow, 206
assurance, 589, 591
Attributes, 872, 879
Ausgabe, 226
auto threshold, 537
Average, 308, 841, 861, 871, 873, 874, 880
Background, 514, 519
background, 640, 641, 644–647, 649
background-estimation, 640, 641, 644–647, 649
background seg, 514
Band-Filter, 91
Bandpass-Filter, 92, 97, 98, 103
bandpass image, 103
Barcode, 650, 652, 653, 657, 661, 662, 665
Barcode-description, 661, 662
Best-Match, 108–111, 113, 121, 122, 765
best match, 108
best match mg, 109
best match pre mg, 110
best match rot, 111
best match rot mg, 113
bin threshold, 538
Binary-image, 16
Bit, 41–46
Bit-Operations, 824–827, 847
bit and,41
bit lshift,42
bit mask,42
bit not,43
bit or, 44
bit rshift,44
bit slice,45
bit xor,46
Blurring, 162, 163, 165, 166
BMP, 11, 14, 16, 266
Border-Treatment, 129
Bottom-Hat, 375, 382, 416
bottom hat, 382
Boundary, 383
boundary, 383
Branches, 425
Buffer, 273, 277, 600, 603
Bulkiness, 479
C-procedure, 593
Calibration, 622, 629, 631, 632, 635, 696
895

896 Index
calibration, 672, 673, 678–682, 685, 691, 692, 694,
697, 698, 704–706, 708, 709, 711, 712,
714, 716
caltab points, 672
camera calibration, 673
Canny-Filter, 60, 63
Ceiling-Function, 838
Center, 313, 455, 473, 500, 506
Center-of-Gravity, 368, 369
Centroid, 862
Chain-code, 445
Chaincode, 361
Chaincodes, 364
change domain, 310
change format, 333
change radial distortion cam par, 678
change radial distortion contours xld,
679
change radial distortion image, 680
Channels, 581
channels to image, 286
Chapter, 588
chapter, 589
char threshold, 538
Character, 795–797, 799, 800
Character-sequence, 19
Characters, 789, 790
check difference, 539
check par hw potential, 598
Checkerboard, 454
Choice-of-regions, 500
Chord, 496, 497
Chord-representation, 449
Circle, 209, 385, 391, 399, 420, 455, 461, 486, 495,
505, 888
circle, 176, 252, 865
circularity, 474
Class, 436
class 2dim sup, 541
class 2dim unsup, 543
class ndim box, 544
class ndim norm, 545
Classification, 135, 541, 543–545, 558, 559
clear obj, 439
clear rectangle, 262
clear sampset,1
clear serial, 608
clear shape model, 763
clear template, 114
clear window, 263
Clearing, 303, 439
clip contours xld, 883
clip region, 515
clip region rel, 516
Clipping, 515, 516, 518, 528, 883
Close, 795, 796
close all bg esti, 640
close all class box,1
close all files,17
close all framegrabbers, 340
close all ocrs, 780
close all ocvs, 795
close all serials, 608
close bg esti, 640
close class box,2
close edges,55
close edges length,56
close file,18
close framegrabber, 340
close measure, 769
close ocr, 780
close ocv, 796
close serial, 609
close socket, 613
close window, 263
Closing, 263, 373, 375, 376, 382, 384, 385, 387, 403,
404, 416
closing, 384
closing circle, 385
closing golay, 387
closing rectangle1, 388
Clustering, 543–545, 558, 559
Co-occurence-Matrix, 314, 315, 317, 322
Coding, 497
Coincidence, 461
Color, 194, 196–198, 200
color, 48, 52, 223, 228–231, 234, 235, 239, 250
color-coding, 223, 239
Color-Image, 210
color-image, 47
color-lookup-table, 228
color-space, 48, 52
color-space-transformation, 47, 48, 52
Color-Table, 600, 603
combine roads xld, 884
Compactness, 474, 475, 500
compactness, 475
Comparison, 437, 797
Comparison-Operators, 828–830
Complement, 510
complement, 510
complex to real, 358
Components, 435
compose2, 286
compose3, 287
compose4, 287
compose5, 288
compose6, 289
compose7, 289
concat obj, 440
concat ocr trainf, 781
Concatenation, 440
Configuration, 280
configuration, 229–233, 256
connect and holes, 475
Connected-Components, 331, 332, 514, 517
connection, 517
Connection-component, 475, 481
HALCON/C Reference Manual / 2000-11-15

Index 897
contlength, 476
Contour, 445, 446, 448, 476, 741
contour, 225, 237, 242
Contour-Length, 875
Contour-length, 475, 476, 500
contour-output, 243
contour point num xld, 863
contour to world plane xld, 680
Contours, 55, 56, 383, 853, 855–860, 863, 865, 867,
869, 871–873, 875, 879–883, 885, 887,
888, 890–892
contours, 679
Contrast, 87
contrast, 82
Contrast-enhancement, 83, 84
Control, 583, 598–600, 603
Control-Modes, 584
control-parameter, 593
Conversion, 831–835, 840
convert image type, 358
convert pose type, 681
Convex, 446
Convexity, 477, 500
convexity, 477
convol fft,85
convol gabor,86
convol image, 129
Convolution, 85, 86, 93, 94, 129
cooc feature image, 314
cooc feature matrix, 315
Coordinate-System, 271, 273, 277, 622, 629, 631,
632, 635
copy image, 295
copy obj, 441
copy rectangle, 264
Copying, 295, 303, 355, 356, 440, 441, 443
corner response, 114
Corners, 114
Correlation, 108–111, 113, 118, 120–122
Cosine, 816
count channels, 290
count obj, 435
count relation, 579
count seconds, 596
Create, 796
create bg esti, 641
create caltab, 682
create class box,2
create funct 1d array, 724
create funct 1d pairs, 725
create ocr class box, 781
create ocv proj, 796
create pose, 685
create shape model, 763
create template, 115
create template rot, 117
Creation, 836
crop domain, 334
crop domain rel, 518
crop part, 334
crop rectangle1, 335
cross-reference, 589, 596
Cursor, 203, 204
cursor-position, 254
Database, 295, 439–443, 579, 581
Debugging, 583, 584
Decode, 650, 652
decode 1d bar code, 650
decode 2d bar code, 651
decompose2, 290
decompose3, 291
decompose4, 292
decompose5, 292
decompose6, 293
decompose7, 293
default-type, 591
Degrees, 821, 832
Delete, 438
Deletion, 262, 263
depth from focus, 801
Deriche-Filter, 60, 63, 156
derivate gauss,57
descript class box,2
Description-file, 11
description-file, 757
detect edge segments, 546
Deviation, 326, 329, 330
deviation image, 159
Devicecontext, 281
Diameter, 478
diameter region, 478
diff of gauss,59
Difference, 511
difference, 511
Differential-Geometry, 57
Diffusion-Filter, 140
Dilatation, 742
Dilation, 377, 382, 384, 385, 387, 389–392, 394,
395, 411, 412, 416, 419, 420, 422–424,
433
dilation1, 389
dilation2, 390
dilation circle, 391
dilation golay, 392
dilation rectangle1, 394
dilation seq, 395
Direction, 853–855, 871, 873, 880, 881, 885, 890–
892
Direction-code, 445
Discrete, 652
discrete 1d bar code, 652
disp arc, 205
disp arrow, 206
disp caltab, 691
disp channel, 208
disp circle, 209
disp color, 210
HALCON 6.0

898 Index
disp distribution, 210
disp ellipse, 211
disp image, 213
disp info, 587
disp line, 214
disp lut, 193
disp obj, 215
disp polygon, 216
disp rectangle1, 217
disp rectangle2, 219
disp region, 220
disp xld, 221
Displacement-Vector-Field, 123, 126, 359
DISPLAY, 273, 277
Display, 221
display, 224, 232, 241
dist ellipse contour xld, 863
Distance, 478, 519, 725, 741, 742, 863
distance funct 1d, 725
distance lr, 736
distance pl, 737
distance pp, 738
distance pr, 739
distance ps, 740
distance rr min, 741
distance rr min dil, 742
distance sl, 742
distance sr, 744
distance ss, 744
distance transform, 519
Distribution, 317, 323, 325, 326, 496
div image,35
Division, 35, 817, 818
do ocr multi, 784
do ocr single, 785
do ocv simple, 797
Documentation, 600, 603
Domain, 309–312
drag region1, 173
drag region2, 174
drag region3, 175
draw circle, 176
draw circle mod, 176
draw ellipse, 177
draw ellipse mod, 178
draw line, 180
draw line mod, 181
draw lut, 194
draw point, 182
draw point mod, 183
draw polygon, 184
draw rectangle1, 184
draw rectangle1 mod, 186
draw rectangle2, 187
draw rectangle2 mod, 188
draw region, 189
drawing, 176, 180–184, 186–189
dual rank, 373
dual threshold, 548
dump window, 266
dvf to hom mat2d, 623
dvf to int1, 359
dyn threshold, 549
Dynamic-Threshold, 539, 549
eccentricity, 479
Edge-Amplitude, 60, 63, 65, 66, 69, 70, 74, 75, 77–
80
Edge-Closing, 55, 56
Edge-Detection, 55–57, 59, 60, 65–70, 72–80, 546,
561, 562
Edge-Direction, 60, 63, 66, 70, 75, 78, 80, 885
Edge-Preservation, 140, 155
Edge-Thinning, 60, 561, 562
Edges, 55, 56, 546, 548, 561, 562, 575, 576, 769,
771, 773, 775–777
edges image,60
edges sub pix,63
Elements, 653
eliminate min max, 141
eliminate runs, 520
eliminate sp, 143
Ellipse, 211, 316, 457, 461, 479, 480, 746, 863, 888
ellipse, 177, 178, 252, 858, 867
elliptic axis, 480
elliptic axis gray, 316
emphasize,82
End-Points, 526
Energy, 87
energy gabor,87
enquire class box,3
enquire reject class box,4
Entropy, 160, 317, 320, 330
entropy gray, 317
entropy image, 160
equ histo image,83
Erosion, 378, 382, 384, 385, 387, 396, 397, 399–
402, 408–410, 414–416, 419, 420, 422–
424, 426–431, 433
erosion1, 396
erosion2, 397
erosion circle, 399
erosion golay, 400
erosion rectangle1, 401
erosion seq, 402
Error-Control, 582
Error-Message, 582
Error-Text, 582
Errors, 584
estimate, 753, 757, 760
estimate al am, 802
estimate sl al lr, 802
estimate sl al zc, 803
estimate tilt lr, 804
estimate tilt zc, 804
Estimation, 802–804
estimation, 753, 757, 760
Euler-number, 481
HALCON/C Reference Manual / 2000-11-15

Index 899
euler number, 481
Evaluation, 795–797, 799, 800
example, 589
Exception, 582
exhaustive match, 118
exhaustive match mg, 120
expand domain gray, 130
expand gray, 551
expand gray ref, 552
expand line, 554
expand region, 521
Expansion, 521, 551, 552, 554
Exponential, 817
Extension, 11
Extern, 271, 281
fast match, 121
fast match mg, 122
fast threshold, 555
Feature, 313–321, 326, 328, 329, 473–477, 480, 481,
484–496, 499, 504–508, 840–842, 861,
862, 874, 875, 877, 878
Feature-Space, 541, 544, 545, 558, 559
Features, 839, 841
FFT, 85–92, 94, 96–102
fft generic,88
fft image,89
fft image inv,90
File, 600, 603
file-access, 15
File-Format, 16
file exists,15
File format, 14
Fileheader, 12
fill dvf, 123
fill interlace, 144
fill up, 522
fill up shape, 523
Filter, 85, 86, 93, 94, 114, 130, 284
Filter-Mask, 129
Filter-Width, 68, 146
filter kalman, 753
find 1d bar code, 653
find 1d bar code region, 657
find 2d bar code, 658
find caltab, 692
find marks and pose, 694
find neighbors, 482
find shape model, 765
fit circle contour xld, 865
fit ellipse contour xld, 867
fit line contour xld, 869
fit surface first order, 318
fit surface second order, 319
Fitting, 403, 404
fitting, 403
Floor-Function, 839
fnew line,18
Font, 600, 603
font, 253, 256, 259
font-size, 253
Foreground, 519
foreground, 640, 641, 644–647, 649
Form, 500
Form-feature, 488–493
Fourier-Transformation, 88–92, 96–102
fourier 1dim, 719
fourier 1dim inv, 720
Framegrabber, 340–346, 348, 350, 351
fread char,19
fread string,19
Frei-Filter, 65, 66
frei amp,65
frei dir,66
Frequency, 323, 325, 326
Frequency-Domain, 85, 86, 88, 89, 91, 92, 94, 96–98
full domain, 310
funct 1d to pairs, 726
Function, 725
Functions, 724, 726–730, 732, 733
Fuzzy-Sets, 320, 321
fuzzy entropy, 320
fuzzy perimeter, 321
fwrite string,20
Gabor-Filter, 86, 87, 94
Gaps, 521, 551, 552
Gauss-Filter, 145, 156
Gauss-Pyramid, 124
gauss distribution, 138
gauss image, 145
Gaussian, 57, 59, 72, 73, 79, 80, 98, 145, 156, 537,
538, 556
Gaussian-Function, 731
gen 1d bar code descr, 661
gen 1d bar code descr gen, 662
gen 2d bar code descr, 663
gen bandfilter,91
gen bandpass,92
gen checker region, 454
gen circle, 455
gen contour polygon xld, 855
gen contour region xld, 856
gen contours skeleton xld, 857
gen cooc matrix, 322
gen disc se, 374
gen ellipse, 457
gen ellipse contour xld, 858
gen empty obj, 442
gen empty region, 458
gen filter mask,93
gen gabor,94
gen gauss pyramid, 124
gen grid region, 459
gen highpass,96
gen image1, 295
gen image1 extern, 296
gen image1 rect, 298
HALCON 6.0

900 Index
gen image3, 299
gen image const, 301
gen image gray ramp, 302
gen image proto, 303
gen image surface second order, 304
gen lowpass,96
gen measure arc, 769
gen measure rectangle2, 771
gen parallel contour xld, 885
gen parallels xld, 859
gen polygons xld, 860
gen psf defocus, 162
gen psf motion, 163
gen random region, 460
gen random regions, 461
gen rectangle1, 463
gen rectangle2, 464
gen region histo, 465
gen region hline, 466
gen region line, 467
gen region points, 468
gen region polygon, 469
gen region polygon filled, 470
gen region runs, 471
gen sin bandpass,97
gen std bandpass,98
gen struct elements, 404
generic, 662
Geocoding, 15, 23–25
Geometry, 734–740, 742, 744, 746–748
get 1d bar code, 665
get 2d bar code, 666
get 2d bar code pos, 670
get bg esti params, 644
get channel info, 435
get chapter info, 588
get check, 582
get class box param,4
get comprise, 221
get contour angle xld, 871
get contour attrib xld, 872
get contour global attrib xld, 872
get contour xld, 853
get domain, 311
get draw, 222
get error text, 582
get fix, 222
get fixed lut, 195
get font, 253
get framegrabber lut, 341
get framegrabber param, 341
get grayval, 351
get hsi, 223
get icon, 223
get image pointer1, 352
get image pointer1 rect, 353
get image pointer3, 354
get image time, 306
get insert, 224
get keywords, 589
get line approx, 225
get line of sight, 696
get line style, 225
get line width, 225
get lines xld, 853
get lut, 196
get lut style, 196
get mbutton, 202
get modules, 580
get mposition, 203
get mshape, 203
get next socket data type, 613
get obj class, 436
get operator info, 589
get operator name, 590
get paint, 226
get pair funct 1d, 726
get parallels xld, 854
get param info, 591
get param names, 593
get param num, 593
get param types, 594
get part, 226
get part style, 227
get pixel, 228
get points ellipse, 746
get polygon xld, 855
get pose type, 697
get region chain, 445
get region contour, 446
get region convex, 446
get region index, 483
get region points, 447
get region polygon, 448
get region runs, 449
get region thickness, 483
get regress params xld, 873
get rgb, 228
get serial param, 609
get shape, 229
get spy, 583
get string extents, 253
get system, 600
get tposition, 254
get tshape, 255
get window extents, 267
get window pointer3, 268
get window type, 268
give bg esti, 645
Gnuplot, 190–192
gnuplot close, 190
gnuplot open file, 190
gnuplot open pipe, 191
gnuplot plot ctrl, 191
gnuplot plot funct 1d, 192
gnuplot plot image, 192
Golay-Alphabet, 387, 392, 395, 400, 402, 405, 409,
410, 417, 418, 422, 427, 428, 430, 431
HALCON/C Reference Manual / 2000-11-15

Index 901
golay elements, 405
grab image, 342
grab image async, 343
grab image start, 344
grab region, 345
grab region async, 346
Graphic, 600, 603
graphic, 221, 224
Graphics, 205, 206, 209, 211, 271, 273, 277, 281
graphics, 232, 691
Graphics-Software, 268
Grauwert, 226
Gray-Channels, 285–294
Gray-Projections, 653, 657, 665
gray-scale-image, 47
Gray-surface, 304
Gray-Value, 213, 215, 308
Gray-Value-Feature, 313–321, 326, 328, 329, 861,
874
Gray-Value-Morphology, 377, 379, 380
Gray-value-scaling, 85
gray-value-spreading, 85
Gray-Value-Threshold, 537–539, 549, 555, 556, 573
Gray-Values, 132, 303, 314, 315, 317, 322, 326, 329,
355–357, 374–381, 551, 552, 861, 874
Gray-values, 323, 325, 326, 330, 351
gray bothat, 375
gray closing, 376
gray dilation, 377
gray dilation rect, 377
gray erosion, 378
gray erosion rect, 379
gray histo, 323
gray inside, 131
gray opening, 379
gray projections, 324
gray range rect, 380
gray skeleton, 132
gray tophat, 381
grayvalue, 221, 226, 228, 231, 233, 238, 244, 250
grayvalue-interpolation, 227, 249
Grayvalues, 114
Half-axis, 316, 480
Half-Images, 144
Hammin-distance, 484, 485
Hamming-Distance, 524
hamming change region, 524
hamming distance, 484
hamming distance norm, 485
hand eye calibration, 698
Height-Field, 804, 806–808, 810
height-plot, 244
help, 587, 589, 591, 595
Hesse, 466
High-Pass-Filter, 67
Highpass-Filter, 96
highpass image,67
Hilbert-Transform, 86, 87, 94
histo 2dim, 325
histo to thresh, 556
Histogram, 323, 325, 326, 331, 332, 465, 537, 538,
541, 543, 556
histogram, 244
Histogram-linearisation, 83
Histogram-spreading, 83
Hit-Or-Miss-Transformation, 405, 408–410, 426–
431
hit or miss, 408
hit or miss golay, 409
hit or miss seq, 410
HNF, 750–752
hole, 475, 481
Holes, 522, 523
hom mat2d compose, 623
hom mat2d identity, 624
hom mat2d invert, 624
hom mat2d rotate, 625
hom mat2d scale, 626
hom mat2d slant, 627
hom mat2d to affine par, 628
hom mat2d translate, 629
hom mat3d compose, 629
hom mat3d identity, 631
hom mat3d invert, 631
hom mat3d rotate, 632
hom mat3d scale, 634
hom mat3d to pose, 704
hom mat3d translate, 635
Homogeneous-Coordinates, 15, 27, 449, 621–629,
631, 632, 634, 635, 882, 883
homogeneous-coordinates, 704, 706
Hopfield, 484, 485
Hough-Transform, 749–752
hough circle trans, 749
hough circles, 749
hough line trans, 750
hough lines, 751
Hull, 446, 486, 505, 507
hull, 252
Hyper-Cube, 545, 559
Hyper-Cuboid, 544, 558
Hyper-Sphere, 545, 559
Hyperbolic-Cosine, 816
Hyperbolic-Sine, 822
Hyperbolic-Tangent, 824
Hysteresis, 557
Hysteresis-Thresholding, 60, 63
hysteresis threshold, 557
Iconic-Object, 295, 439–443, 579
illuminate,84
Illumination, 84
Image, 215, 295, 296, 298, 299, 301, 302, 304, 600,
603, 616, 617
image-clipping, 226, 227, 248, 249
Image-directory, 11
Image-Generation, 306, 307
HALCON 6.0

902 Index
Image-grabbing, 341–346, 351
image-matrix, 236
Image-Object, 213, 220, 600, 603
Image-object, 11, 295, 296, 298, 299, 301, 302, 304,
435–438
image-object, 236
Image-Part, 334, 335
image-part, 226, 227, 248, 249
Image-Plane, 318, 319, 328, 329
Image-plane, 302
image-repeat-memory, 241
Image-Restoration, 167, 169
image-sequences, 640, 641, 644–647, 649
Image-Size, 333–338
Image-Types, 358
Image data, 12
image points to world plane, 705
image to channels, 294
Images, 581
info edges,68
info framegrabber, 346
info ocr class box, 786
info parallels xld, 874
info smooth, 146
Information, 317, 346, 435–438
information, 589
Initialization, 581, 598–600, 603
Inner-circle, 486, 500
inner circle, 486
input, 257, 258
input-parameter, 593
inquiry, 595
Inside, 131
inspect shape model, 767
int1 to dvf, 359
integer to obj, 442
integrate funct 1d, 727
intensity, 326
Interaction, 202, 203, 284
interaction, 173–178, 180–184, 186–189
interjacent, 525
Interlace, 144
Interpolation, 27, 144, 882, 883
interpolation, 227
Intersection, 512, 515, 516, 518
intersection, 512
intersection ll, 747
invar fourier coeff, 721
Inversion, 36
invert image,36
Iteration, 140
JPEG, 11, 14, 266
Junctions, 526
junctions skeleton, 526
Kalman-filter, 640, 644–647, 649, 753, 757, 759, 760
keyword, 589, 596
Kirsch-Filter, 69, 70
kirsch amp,69
kirsch dir,70
kKalmanfilter, 641
Label-Image, 307, 472
label to region, 472
Lanser-Filter, 60, 63
laplace,72
Laplace-Filter, 57, 59, 72, 73
Laplace-of-Gaussian, 57, 59, 73
Laplace-Operator, 548
laplace of gauss,73
Laws-Filter, 161
Ldexp, 818
learn class box,5
learn ndim box, 558
learn ndim norm, 559
learn sampset box,6
Least-Squares-Adjustment, 727
Length, 853–855
length xld, 875
Level-Crossings, 574
Licence, 580
Light-Source, 802–804, 806–808, 810
Line, 214, 361, 869, 888
line, 180
Line-Extraction, 103, 105
Line-feed, 18
Line-Length, 368, 369
Line-length, 370
Line-segments, 869, 888
line-width, 243
line orientation, 366
line position, 367
Lines, 364, 366–370, 459, 461, 466, 467, 533, 535,
546, 853
lines facet, 103
lines gauss, 105
load par knowledge, 599
Local-Maximum, 561, 562, 875
Local-Threshold, 539, 549
local max, 560
local max contours xld, 875
LoG, 57, 59, 73
Logarithm, 819
Logical-Operations, 842–844
Look-Up-Table, 133, 193, 194, 196–198, 200, 201,
222, 237
Lowpass-Filter, 96
LUT, 133, 193, 194, 196–198, 200, 201, 222, 237,
341, 350, 600
lut, 250
lut trans, 133
Main-axes-of-inertia, 487–493
Main-radius, 500
Manipulation, 837, 838
Manual, 588
manual, 587, 595
HALCON/C Reference Manual / 2000-11-15

Index 903
Map, 27, 29–32, 449, 623, 637–639, 882, 883
Mask, 42
match fourier coeff, 722
match funct 1d trans, 727
Matching, 107–111, 113–115, 117, 118, 120–122,
125, 127–129, 752, 763, 765, 767–769
Matrices, 581
max image,36
max parallels xld, 876
Maxima, 560, 563, 564
Maximum, 36, 125, 132, 326, 330, 377, 733, 840
Mean, 326, 330, 731
Mean-Filter, 141, 143, 147, 148
mean image, 147
mean n, 148
mean sp, 148
measure pairs, 773
measure pos, 775
measure projection, 776
measure thresh, 777
Measurement, 769, 771, 773, 775–777
measurements, 753, 757, 759, 760
Medial-Axis, 532
Median, 529
Median-Filter, 141, 149, 151–154, 158, 373
median image, 149
median separate, 151
median weighted, 152
Memory, 600
merge cont line scan xld, 886
merge regions line scan, 527
Metric, 519
Mexican-Hat-Operator, 57, 59, 73
Midrange-Filter, 153
midrange image, 153
min image,37
min max gray, 326
Minima, 537, 538, 556
Minimum, 37, 125, 326, 330, 379, 733, 741, 742,
841
Minkowski-Addition, 411, 412, 419, 420, 422–424
Minkowski-Subtraction, 384, 385, 387, 414, 415
minkowski add1, 411
minkowski add2, 412
minkowski sub1, 414
minkowski sub2, 415
mirror image,29
mirror region, 450
mod parallels xld, 861
Modules, 580, 652
Moments, 316, 318, 319, 328, 479, 480, 487–493,
877, 878
moments any xld, 877
moments gray plane, 328
moments region 2nd, 487
moments region 2nd invar, 488
moments region 2nd rel invar, 489
moments region 3rd, 490
moments region 3rd invar, 491
moments region central, 492
moments region central invar, 493
moments xld, 878
Monotony, 125
monotony, 125
morph hat, 416
morph skeleton, 417
morph skiz, 418
Morphology, 374–385, 387, 389–392, 394–397,
399–405, 408–412, 414–420, 422–431,
433, 452
Motion-Blur, 163, 166, 167, 169
Mouse, 202–204
move contour orig, 723
move rectangle, 269
move region, 451
movement, 173–175
mult image,38
multichannel, 208
Multiplication, 38, 730, 820
negate funct 1d, 728
Negation, 728, 820
Neighborhood, 123, 482
neighborhood, 499, 508
new extern window, 271
new line, 255
Noise, 136–139, 167, 169, 881
noise, 141
Noise-Distribution, 136–139, 210, 881
Noise-Removal, 530
noise distribution mean, 138
Non-linear-Filter, 140
Non-Maximum-Suppression, 60, 561, 562
nonmax suppression amp, 561
nonmax suppression dir, 562
not, 43
num points funct 1d, 729
obj to integer, 443
Object, 215, 438, 442
object, 12
Object-choice, 483, 498
Object-comparison, 437, 438
Object-Key, 442, 443
Object-Selection, 330
OCR, 789, 790
ocr change char, 787
ocr get features, 787
online-text, 589, 595, 596
open file,21
open framegrabber, 348
open serial, 610
open socket accept, 614
open socket connect, 615
open textwindow, 273
open window, 277
Opening, 373, 379, 381, 403, 404, 416, 419, 420,
422–424, 433
HALCON 6.0

904 Index
opening, 419
opening circle, 420
opening golay, 422
opening rectangle1, 423
opening seg, 424
Optical-Flow, 126, 359
optical flow match, 126
or, 44
Orientatio, 500
Orientation, 316, 366–369, 457, 464, 480, 494, 507,
653
orientation region, 494
Out-Of-Focus-Blur, 162, 165, 167, 169
Outer-circle, 500
Outliers, 887
Output, 205, 206, 208–211, 213–215, 217, 219
output, 221, 225, 226, 241, 260, 261, 691
output-parameter, 593
Overlap, 503
paint, 184
paint gray, 355
paint region, 356
Parallelization, 598–600
Parallels, 854, 859, 861, 874, 876, 884
parameter, 225, 589, 591, 593–595
parameter-number, 593
Partition, 528
partition dynamic, 528
partition lines, 368
partition rectangle, 528
Pattern, 454, 459, 795–797, 799, 800
Perimeter, 321
Phase, 99, 100
phase deg,99
phase rad, 100
phot stereo, 804
Photometric-Stereo, 804
Pixel, 447, 468
Pixel-Relations, 600, 603
Pixel-Types, 358
Pixel types, 12
Pixels, 459, 461
plane deviation, 329
Plateaus, 563
plateaus, 563
plateaus center, 563
plot, 244
point, 182, 183
Polar-Transformation, 29
polar trans image,29
Polygon, 216, 469, 470, 495
polygon, 184
Polygon-Approximation, 860
Polygon-approximation, 448
polygon-approximation, 242
Polygon-Length, 875
Polygons, 853–856, 860, 876, 883, 884, 890
Polyline, 216
Pose-relation, 499, 508
pose to hom mat3d, 706
PostScript, 266
Pouring, 564
pouring, 564
Power-Function, 821
Power-Spectrum, 99–102
power byte, 100
power ln, 101
power real, 102
prediction, 753, 757, 760
prep contour fourier, 723
Prewitt-Filter, 74, 75
prewitt amp,74
prewitt dir,75
Principal-Components, 134
principal comp, 134
procedure, 593, 595
Procedure-Chapters, 588
procedure-name, 590
Product-of-inertia, 487–493
project 3d point, 708
projection, 244
projection pl, 748
Pruning, 425
pruning, 425
Pyramid, 120
query all colors, 229
query color, 230
query colored, 231
query contour attribs xld, 879
query contour global attribs xld, 879
query font, 256
query gray, 231
query insert, 232
query line width, 232
query lut, 197
query mshape, 204
query operator info, 595
query paint, 233
query param info, 595
query shape, 233
query spy, 584
query tshape, 257
query window type, 280
Radians, 821, 832
Radius, 316, 455, 457, 480
Random-pattern, 460
Range, 326, 380
Range-Filter, 153
Rank-Filter, 149, 152–154, 158, 373
Rank-Gray-Value, 149, 152–154, 158, 373
Rank-Operator, 529
rank image, 154
rank region, 529
read cam par, 709
read char, 257
HALCON/C Reference Manual / 2000-11-15

Index 905
read class box,7
read contour xld arc info,23
read funct 1d, 729
read gray se, 381
read image,11
read kalman, 757
read ocr, 788
read ocr trainf, 789
read ocr trainf names, 789
read ocr trainf select, 790
read ocv, 799
read polygon xld arc info,24
read pose, 711
read region,16
read sampset,7
read sequence,12
read serial, 610
read shape model, 768
read string, 258
read template, 127
read tuple,22
read world file,15
real to complex, 360
receive image, 616
receive region, 616
receive tuple, 617
receive xld, 617
Rectangle, 217, 219, 394, 401, 423, 461, 463, 464,
507, 515, 516, 518, 528
rectangle, 181, 184, 186–188, 252
rectangle1 domain, 311
rectification, 678–680
Recursive-Filter, 156
reduce domain, 312
reference, 589
Reflection, 29, 450, 452
Region, 16, 17, 215, 220, 435, 438, 445–449, 454,
458, 459, 461, 466, 467, 519, 600, 603,
856
region, 173–175, 189, 222, 229, 233
Region-choice, 503
region to bin, 306
region to label, 307
region to mean, 308
Regiongrowing, 566–568
regiongrowing, 566
regiongrowing mean, 567
regiongrowing n, 568
Regions, 306, 307, 382–385, 387, 389–392, 394–
397, 399–405, 408–412, 414–420, 422–
431, 433, 452, 510–513, 522, 523, 531,
581, 616, 618, 857
regress contours xld, 887
Regression, 869, 871, 873, 875, 880, 881, 885, 887,
890–892
Rekursive-Filters, 60, 63
Relation, 579
Relations, 581
Remainder, 818
remove noise region, 530
reset obj db, 581
Resolution-Pyramid, 120
Restoration, 162, 163, 165, 166
return-value, 589
RGB, 47, 48, 52
rgb1 to gray,47
rgb3 to gray,47
Ridge, 125
roberts,76
Roberts-Filter, 76
Robinson-Filter, 77, 78
robinson amp,77
robinson dir,78
rotate image,30
Rotation, 30, 625, 627, 628, 632
Roundness, 474, 475
roundness, 495
Run, 496, 497, 520
run bg esti, 646
Runlength-Code, 603
Runlength-Coding, 600
Runlength-coding, 449, 471, 497
runlength-encoding, 520
runlength distribution, 496
runlength features, 497
Runtime, 596
sample funct 1d, 730
Save, 799, 800
scale image,39
scale image max,85
scale y funct 1d, 730
Scaling, 31, 32, 39, 626, 634
scaling, 85
search operator, 596
Secondary-radius, 500
segment contours xld, 888
Segmentation, 308, 345, 346, 361, 364, 472, 514,
541, 543–545, 564, 575, 888
segmentation, 692
select contours xld, 880
select gray, 330
select grayvalues from channels, 805
select lines, 369
select lines longest, 370
select matching lines, 752
select obj, 443
select region point, 498
select region spatial, 499
select shape, 500
select shape proto, 503
select shape std, 504
Selection, 441, 443, 844–847
send image, 617
send region, 618
send tuple, 618
send xld, 619
sensor kalman, 759
HALCON 6.0

906 Index
Separating-Lines, 525
Serial-Interface, 608–612
set bg esti params, 647
set check, 584
set class box param,8
set color, 234
set colored, 235
set comprise, 236
set draw, 237
set fix, 237
set fixed lut, 197
set font, 259
set framegrabber lut, 350
set framegrabber param, 351
set gray, 238
set grayval, 357
set hsi, 239
set icon, 240
set insert, 241
set line approx, 242
set line style, 242
set line width, 243
set lut, 198
set lut style, 200
set mshape, 204
set offset template, 128
set origin pose, 712
set paint, 244
set part, 248
set part style, 249
set pixel, 250
set reference template, 128
set rgb, 251
set serial param, 611
set shape, 252
set spy, 585
set system, 603
set tposition, 260
set tshape, 260
set window attr, 280
set window dc, 281
set window extents, 282
set window type, 283
sfs mod lr, 806
sfs orig lr, 807
sfs pentland, 808
shade height field, 810
Shading, 804, 806–808, 810
Shadows, 810
Shape, 503
Shape-Feature, 875, 877, 878
Shape-feature, 474, 475, 477, 479, 480, 484, 485,
487, 494, 495, 504
Shape-Features, 523
Shape-from-Shading, 804, 806–808
Shape-Transformation, 531
shape histo all, 331
shape histo point, 332
shape trans, 531
Sharpness, 82
Shen-Filter, 60, 63, 156
Shift, 42, 44
Sigma-Filter, 155
sigma image, 155
sim caltab, 712
Similarity, 504, 725
simulate defocus, 165
simulate motion, 166
Sine, 97, 98, 822
Skeleton, 417, 418, 425, 429–431, 532, 857
skeleton, 532
Slant, 802, 803
slide image, 284
Slope, 125
smallest circle, 505
smallest rectangle1, 506
smallest rectangle2, 507
smooth contours xld, 890
smooth funct 1d gauss, 731
smooth funct 1d mean, 731
smooth image, 156
Smoothing, 57, 140, 141, 143–149, 151–156, 158,
373, 731, 890
Sobel-Filter, 79, 80
sobel amp,79
sobel dir,80
socket accept connect, 620
Sockets, 613–620
sort region, 533
sp distribution, 139
Spatial-Domain, 88, 90, 93
spatial relation, 508
Split-And-Merge, 533, 535
split contours xld, 890
split skeleton lines, 533
split skeleton region, 535
spreading, 85
Square-Root, 823
Standard-Deviation, 159, 839, 861, 873, 874, 880
Store, 799, 800
store par knowledge, 600
Storing-Capacity, 603
String, 19, 20
String-Operators, 847–852
Structure-factor, 479
Structuring-Elements, 374, 381
sub image,40
Subtraction, 40, 823
Sum, 842
Surrogate, 438, 442, 443
Surrounding-circle, 500, 505
surrounding-circle, 252
Surrounding-rectangle, 500, 506, 507
Symmetry, 134
symmetry, 134
System-Call., 597
System-Parameter, 600, 603
system call, 597
HALCON/C Reference Manual / 2000-11-15

Index 907
systems, 753, 757, 760
T abs funct 1d, 724
T abs invar fourier coeff, 718
T add noise distribution, 136
T affine trans contour xld, 882
T affine trans image,27
T affine trans point 2d, 621
T affine trans point 3d, 622
T affine trans polygon xld, 883
T affine trans region, 449
T angle ll, 734
T angle lx, 735
T append ocr trainf, 778
T approx chain, 361
T approx chain simple, 364
T area center, 473
T area center gray, 313
T area center xld, 862
T best match, 108
T best match rot, 111
T best match rot mg, 113
T caltab points, 672
T camera calibration, 673
T change radial distortion cam par,
678
T change radial distortion contours xld,
679
T change radial distortion image, 680
T char threshold, 538
T circularity, 474
T class ndim norm, 545
T clear rectangle, 262
T compactness, 475
T concat ocr trainf, 781
T connect and holes, 475
T contlength, 476
T contour to world plane xld, 680
T convert pose type, 681
T convexity, 477
T cooc feature image, 314
T copy rectangle, 264
T count channels, 290
T create funct 1d array, 724
T create funct 1d pairs, 725
T create ocr class box, 781
T create ocv proj, 796
T create pose, 685
T decode 1d bar code, 650
T decode 2d bar code, 651
T depth from focus, 801
T detect edge segments, 546
T diameter region, 478
T discrete 1d bar code, 652
T disp arc, 205
T disp arrow, 206
T disp caltab, 691
T disp channel, 208
T disp circle, 209
T disp distribution, 210
T disp ellipse, 211
T disp line, 214
T disp polygon, 216
T disp rectangle1, 217
T disp rectangle2, 219
T dist ellipse contour xld, 863
T distance funct 1d, 725
T distance lr, 736
T distance pl, 737
T distance pp, 738
T distance pr, 739
T distance ps, 740
T distance rr min, 741
T distance rr min dil, 742
T distance sl, 742
T distance sr, 744
T distance ss, 744
T do ocr multi, 784
T do ocr single, 785
T do ocv simple, 797
T dump window, 266
T dvf to hom mat2d, 623
T eccentricity, 479
T elliptic axis, 480
T elliptic axis gray, 316
T enquire class box,3
T enquire reject class box,4
T entropy gray, 317
T estimate al am, 802
T estimate sl al lr, 802
T estimate sl al zc, 803
T estimate tilt lr, 804
T estimate tilt zc, 804
T euler number, 481
T expand gray, 551
T expand gray ref, 552
T fast match mg, 122
T filter kalman, 753
T find 1d bar code, 653
T find 1d bar code region, 657
T find 2d bar code, 658
T find marks and pose, 694
T find neighbors, 482
T find shape model, 765
T fit circle contour xld, 865
T fit ellipse contour xld, 867
T fit line contour xld, 869
T fit surface first order, 318
T fit surface second order, 319
T fourier 1dim, 719
T fourier 1dim inv, 720
T funct 1d to pairs, 726
T fuzzy entropy, 320
T fuzzy perimeter, 321
T fwrite string,20
T gauss distribution, 138
T gen 1d bar code descr, 661
T gen 1d bar code descr gen, 662
HALCON 6.0

908 Index
T gen 2d bar code descr, 663
T gen circle, 455
T gen contour polygon xld, 855
T gen ellipse, 457
T gen ellipse contour xld, 858
T gen rectangle1, 463
T gen rectangle2, 464
T gen region histo, 465
T gen region hline, 466
T gen region line, 467
T gen region points, 468
T gen region polygon, 469
T gen region polygon filled, 470
T gen region runs, 471
T get 1d bar code, 665
T get 2d bar code, 666
T get 2d bar code pos, 670
T get channel info, 435
T get chapter info, 588
T get check, 582
T get contour angle xld, 871
T get contour attrib xld, 872
T get contour global attrib xld, 872
T get contour xld, 853
T get framegrabber lut, 341
T get framegrabber param, 341
T get grayval, 351
T get hsi, 223
T get keywords, 589
T get line of sight, 696
T get line style, 225
T get lines xld, 853
T get lut, 196
T get modules, 580
T get obj class, 436
T get operator info, 589
T get operator name, 590
T get paint, 226
T get pair funct 1d, 726
T get parallels xld, 854
T get param info, 591
T get param names, 593
T get param types, 594
T get pixel, 228
T get points ellipse, 746
T get polygon xld, 855
T get pose type, 697
T get region chain, 445
T get region contour, 446
T get region convex, 446
T get region index, 483
T get region points, 447
T get region polygon, 448
T get region runs, 449
T get region thickness, 483
T get regress params xld, 873
T get rgb, 228
T get string extents, 253
T get system, 600
T gnuplot plot ctrl, 191
T gnuplot plot funct 1d, 192
T gray histo, 323
T gray projections, 324
T hamming distance, 484
T hamming distance norm, 485
T hand eye calibration, 698
T histo to thresh, 556
T hom mat2d compose, 623
T hom mat2d identity, 624
T hom mat2d invert, 624
T hom mat2d rotate, 625
T hom mat2d scale, 626
T hom mat2d slant, 627
T hom mat2d to affine par, 628
T hom mat2d translate, 629
T hom mat3d compose, 629
T hom mat3d identity, 631
T hom mat3d invert, 631
T hom mat3d rotate, 632
T hom mat3d scale, 634
T hom mat3d to pose, 704
T hom mat3d translate, 635
T hough circle trans, 749
T hough circles, 749
T hough lines, 751
T image points to world plane, 705
T info edges,68
T info framegrabber, 346
T info ocr class box, 786
T info smooth, 146
T inner circle, 486
T integer to obj, 442
T integrate funct 1d, 727
T intensity, 326
T intersection ll, 747
T invar fourier coeff, 721
T learn class box,5
T learn ndim norm, 559
T length xld, 875
T line orientation, 366
T line position, 367
T lut trans, 133
T match fourier coeff, 722
T match funct 1d trans, 727
T measure pairs, 773
T measure pos, 775
T measure projection, 776
T measure thresh, 777
T min max gray, 326
T moments any xld, 877
T moments gray plane, 328
T moments region 2nd, 487
T moments region 2nd invar, 488
T moments region 2nd rel invar, 489
T moments region 3rd, 490
T moments region 3rd invar, 491
T moments region central, 492
T moments region central invar, 493
HALCON/C Reference Manual / 2000-11-15

Index 909
T moments xld, 878
T move contour orig, 723
T move rectangle, 269
T negate funct 1d, 728
T noise distribution mean, 138
T num points funct 1d, 729
T obj to integer, 443
T ocr change char, 787
T ocr get features, 787
T open framegrabber, 348
T optical flow match, 126
T orientation region, 494
T partition lines, 368
T phot stereo, 804
T plane deviation, 329
T pose to hom mat3d, 706
T prep contour fourier, 723
T principal comp, 134
T project 3d point, 708
T projection pl, 748
T query all colors, 229
T query color, 230
T query colored, 231
T query contour attribs xld, 879
T query contour global attribs xld,
879
T query font, 256
T query gray, 231
T query insert, 232
T query lut, 197
T query mshape, 204
T query operator info, 595
T query paint, 233
T query param info, 595
T query shape, 233
T query spy, 584
T query tshape, 257
T query window type, 280
T read cam par, 709
T read funct 1d, 729
T read image,11
T read kalman, 757
T read ocr trainf, 789
T read ocr trainf names, 789
T read ocr trainf select, 790
T read pose, 711
T read serial, 610
T read tuple,22
T read world file,15
T regiongrowing mean, 567
T roundness, 495
T runlength distribution, 496
T runlength features, 497
T sample funct 1d, 730
T scale y funct 1d, 730
T search operator, 596
T select gray, 330
T select lines, 369
T select lines longest, 370
T select matching lines, 752
T select region spatial, 499
T select shape, 500
T select shape proto, 503
T sensor kalman, 759
T set check, 584
T set color, 234
T set framegrabber lut, 350
T set framegrabber param, 351
T set gray, 238
T set grayval, 357
T set hsi, 239
T set line style, 242
T set lut, 198
T set origin pose, 712
T set paint, 244
T set pixel, 250
T set rgb, 251
T set system, 603
T shape histo all, 331
T shape histo point, 332
T sim caltab, 712
T smallest circle, 505
T smallest rectangle1, 506
T smallest rectangle2, 507
T smooth funct 1d gauss, 731
T smooth funct 1d mean, 731
T sp distribution, 139
T spatial relation, 508
T split skeleton lines, 533
T testd ocr class box, 790
T texture laws, 161
T threshold, 573
T tile images offset, 338
T traind ocr class box, 791
T traind ocv proj, 799
T trainf ocr class box, 792
T transform funct 1d, 732
T tuple abs, 813
T tuple acos, 813
T tuple add, 814
T tuple and, 842
T tuple asin, 814
T tuple atan, 815
T tuple atan2, 815
T tuple band, 824
T tuple bnot, 825
T tuple bor, 825
T tuple bxor, 826
T tuple ceil, 838
T tuple chr, 831
T tuple chrt, 831
T tuple concat, 836
T tuple cos, 816
T tuple cosh, 816
T tuple deg, 832
T tuple deviation, 839
T tuple div, 817
T tuple environment, 847
HALCON 6.0

910 Index
T tuple equal, 828
T tuple exp, 817
T tuple fabs, 818
T tuple first n, 844
T tuple floor, 839
T tuple fmod, 818
T tuple gen const, 836
T tuple greater, 828
T tuple greater equal, 829
T tuple inverse, 837
T tuple is number, 840
T tuple last n, 845
T tuple ldexp, 818
T tuple length, 840
T tuple less, 829
T tuple less equal, 830
T tuple log, 819
T tuple log10, 819
T tuple lsh, 826
T tuple max, 840
T tuple mean, 841
T tuple min, 841
T tuple mult, 820
T tuple neg, 820
T tuple not, 843
T tuple not equal, 830
T tuple number, 832
T tuple or, 843
T tuple ord, 833
T tuple ords, 833
T tuple pow, 821
T tuple rad, 821
T tuple real, 834
T tuple round, 834
T tuple rsh, 827
T tuple select, 845
T tuple select range, 846
T tuple sin, 822
T tuple sinh, 822
T tuple sort, 837
T tuple sort index, 838
T tuple split, 848
T tuple sqrt, 823
T tuple str bit select, 847
T tuple str first n, 848
T tuple str last n, 849
T tuple strchr, 849
T tuple string, 835
T tuple strlen, 850
T tuple strrchr, 850
T tuple strrstr, 851
T tuple strstr, 852
T tuple sub, 823
T tuple sum, 842
T tuple tan, 823
T tuple tanh, 824
T tuple xor, 844
T union straight contours histo xld,
891
T update kalman, 760
T vector angle to rigid, 637
T vector to hom mat2d, 638
T vector to rigid, 639
T vector to similarity, 639
T write cam par, 714
T write funct 1d, 732
T write image,14
T write ocr trainf, 794
T write ocr trainf image, 795
T write pose, 716
T write serial, 612
T write string, 261
T write tuple,23
T x range funct 1d, 733
T y range funct 1d, 733
Tangent, 823
Test-pixel, 483, 498, 509
test equal obj, 437
test equal region, 438
test obj def, 438
test region point, 509
test sampset box,9
testd ocr class box, 790
Text, 273
text, 253–259, 261
text-cursor, 255, 257, 260
Text-file, 17–21
text-position, 260
text-size, 253
Texture, 151, 159–161, 314, 315, 317, 322
Texture-Transformation, 161
texture laws, 161
Thickening, 426–428
thickening, 426
thickening golay, 427
thickening seq, 428
Thinning, 132, 417, 418, 429–431, 532
thinning, 429
thinning golay, 430
thinning seq, 431
Threshold, 331, 332, 537–539, 548, 549, 555–557,
573, 777
threshold, 573
threshold sub pix, 574
Thresholding, 537, 538, 556
TIFF, 11, 266
Tiff, 14, 16
tile channels, 336
tile images, 337
tile images offset, 338
Tiling, 336–338
Tilt, 804
Time-Measure, 596
Top-Hat, 381, 416, 433
top hat, 433
Topographic-Primal-Sketch, 135
topographic sketch, 135
Trace, 583
HALCON/C Reference Manual / 2000-11-15

Index 911
traind ocr class box, 791
traind ocv proj, 799
trainf ocr class box, 792
Training, 558, 559, 789, 790, 799
trans from rgb,48
trans to rgb,52
transform funct 1d, 732
Transformation, 27, 29–32, 133, 449, 519, 637–639,
727, 730, 732, 882, 883
transformation, 705
Transformation-Matrix, 27, 449, 623, 637–639, 882,
883
Translation, 451, 629, 635
transpose region, 452
Transposition, 452
trimmed mean, 158
truecolor, 244
Tuple, 442, 458, 813–852
Tuple-Length, 840
Tuple-length, 435
tuple abs, 813
tuple acos, 813
tuple add, 814
tuple and, 842
tuple asin, 814
tuple atan, 815
tuple atan2, 815
tuple band, 824
tuple bnot, 825
tuple bor, 825
tuple bxor, 826
tuple ceil, 838
tuple chr, 831
tuple chrt, 831
tuple concat, 836
tuple cos, 816
tuple cosh, 816
tuple deg, 832
tuple deviation, 839
tuple div, 817
tuple environment, 847
tuple equal, 828
tuple exp, 817
tuple fabs, 818
tuple first n, 844
tuple floor, 839
tuple fmod, 818
tuple gen const, 836
tuple greater, 828
tuple greater equal, 829
tuple inverse, 837
tuple is number, 840
tuple last n, 845
tuple ldexp, 818
tuple length, 840
tuple less, 829
tuple less equal, 830
tuple log, 819
tuple log10, 819
tuple lsh, 826
tuple max, 840
tuple mean, 841
tuple min, 841
tuple mult, 820
tuple neg, 820
tuple not, 843
tuple not equal, 830
tuple number, 832
tuple or, 843
tuple ord, 833
tuple ords, 833
tuple pow, 821
tuple rad, 821
tuple real, 834
tuple round, 834
tuple rsh, 827
tuple select, 845
tuple select range, 846
tuple sin, 822
tuple sinh, 822
tuple sort, 837
tuple sort index, 838
tuple split, 848
tuple sqrt, 823
tuple str bit select, 847
tuple str first n, 848
tuple str last n, 849
tuple strchr, 849
tuple string, 835
tuple strlen, 850
tuple strrchr, 850
tuple strrstr, 851
tuple strstr, 852
tuple sub, 823
tuple sum, 842
tuple tan, 823
tuple tanh, 824
tuple xor, 844
type, 591
Type-Conversion, 358–360
types, 594
Union, 513
union1, 513
union2, 513
union straight contours histo xld, 891
union straight contours xld, 892
update-file, 760
update bg esti, 649
update kalman, 760
vector angle to rigid, 637
vector to hom mat2d, 638
vector to rigid, 639
vector to similarity, 639
Verification, 795–797, 799, 800
wait seconds, 597
Watersheds, 131, 575
HALCON 6.0

912 Index
watersheds, 575
Weighting, 152
Wiener-Filter, 162, 163, 167, 169
wiener filter, 167
wiener filter ni, 169
Window, 263, 271, 273, 277, 280, 281, 600, 603
Window-Dump, 266
Window-Position, 282
Window-Size, 267, 282
Window-Types, 280
World-File, 15, 23–25
write cam par, 714
write class box,9
write contour xld arc info,25
write funct 1d, 732
write image,14
write lut, 201
write ocr, 793
write ocr trainf, 794
write ocr trainf image, 795
write ocv, 800
write polygon xld arc info,25
write pose, 716
write region,17
write serial, 612
write shape model, 769
write string, 261
write template, 129
write tuple,23
X-Window, 600, 603
x range funct 1d, 733
XLD, 215, 221, 617, 619, 679, 853–861, 863, 865,
867, 869, 871–876, 879–885, 887, 888,
890–892
XLD-Contours, 23, 25, 221, 617, 619, 853, 855–860,
863, 865, 867, 869, 871–873, 875, 879–
883, 885, 887, 888, 890–892
XLD-contours, 679
XLD-Parallels, 221, 617, 619, 854, 859, 861, 874,
876, 884
XLD-Polygons, 24, 25, 221, 617, 619, 853–855,
860, 876, 883, 884, 890
xor, 46
y range funct 1d, 733
Zero-Crossings, 548, 575, 576
zero crossing, 575
zero crossing sub pix, 576
zoom image factor,31
zoom image size,32
zoom region, 453
Zooming, 453
HALCON/C Reference Manual / 2000-11-15

Index 913
HALCON 6.0