You are on page 1of 1524

HALCON Version 8.0.

MVTec Software GmbH

HALCON/HDevelop
Reference Manual
This manual describes the operators of HALCON, version 8.0.2, in HDevelop syntax. It was generated on May
13, 2008.

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-2008 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
1.1 Gaussian-Mixture-Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
add_sample_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
classify_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
clear_all_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
clear_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
clear_samples_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
create_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
evaluate_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
get_params_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
get_prep_info_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
get_sample_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
get_sample_num_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
read_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
read_samples_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
train_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
write_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
write_samples_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.2 Hyperboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
clear_sampset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
close_all_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
close_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
create_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
descript_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
enquire_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
enquire_reject_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
get_class_box_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
learn_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
learn_sampset_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
read_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
read_sampset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
set_class_box_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
test_sampset_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
write_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3 Neural-Nets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
add_sample_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
classify_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
clear_all_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
clear_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
clear_samples_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
create_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
evaluate_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
get_params_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
get_prep_info_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
get_sample_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
get_sample_num_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
read_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
read_samples_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
train_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
write_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
write_samples_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.4 Support-Vector-Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
add_sample_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
classify_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
clear_all_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
clear_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
clear_samples_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
create_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
get_params_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
get_prep_info_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
get_sample_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
get_sample_num_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
get_support_vector_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
get_support_vector_num_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
read_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
read_samples_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
reduce_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
train_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
write_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
write_samples_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

2 Control 59
assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
elseif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
endfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
endif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
endwhile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ifelse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
until . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
while . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3 Develop 71
dev_clear_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
dev_clear_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
dev_close_inspect_ctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
dev_close_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
dev_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
dev_error_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
dev_get_preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
dev_inspect_ctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
dev_map_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
dev_map_prog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
dev_map_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
dev_open_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
dev_set_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
dev_set_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
dev_set_colored . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
dev_set_draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
dev_set_line_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
dev_set_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
dev_set_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
dev_set_part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
dev_set_preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
dev_set_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
dev_set_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
dev_set_window_extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
dev_unmap_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
dev_unmap_prog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
dev_unmap_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
dev_update_pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
dev_update_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
dev_update_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
dev_update_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

4 File 93
4.1 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
read_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
read_sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
write_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.2 Misc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
delete_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
file_exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
list_files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
read_world_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.3 Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
read_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
write_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.4 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
close_all_files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
close_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
fnew_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
fread_char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
fread_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
fread_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
fwrite_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
open_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.5 Tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
read_tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
write_tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.6 XLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
read_contour_xld_arc_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
read_contour_xld_dxf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
read_polygon_xld_arc_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
read_polygon_xld_dxf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
write_contour_xld_arc_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
write_contour_xld_dxf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
write_polygon_xld_arc_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
write_polygon_xld_dxf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

5 Filter 117
5.1 Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
abs_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
add_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
div_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
invert_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
max_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
min_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
mult_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
scale_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
sqrt_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
sub_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.2 Bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
bit_and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
bit_lshift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
bit_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
bit_not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
bit_or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
bit_rshift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
bit_slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
bit_xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.3 Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
cfa_to_rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
gen_principal_comp_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
linear_trans_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
principal_comp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
rgb1_to_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
rgb3_to_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
trans_from_rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
trans_to_rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.4 Edges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
close_edges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
close_edges_length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
derivate_gauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
diff_of_gauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
edges_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
edges_color_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
edges_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
edges_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
frei_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
frei_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
highpass_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
info_edges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
kirsch_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
kirsch_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
laplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
laplace_of_gauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
prewitt_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
prewitt_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
roberts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
robinson_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
robinson_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
sobel_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
sobel_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.5 Enhancement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
adjust_mosaic_images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
coherence_enhancing_diff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
emphasize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
equ_histo_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
illuminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
mean_curvature_flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
scale_image_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
shock_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.6 FFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
convol_fft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
convol_gabor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
correlation_fft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
energy_gabor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
fft_generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
fft_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
fft_image_inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
gen_bandfilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
gen_bandpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
gen_derivative_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
gen_filter_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
gen_gabor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
gen_gauss_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
gen_highpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
gen_lowpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
gen_sin_bandpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
gen_std_bandpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
optimize_fft_speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
optimize_rft_speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
phase_deg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
phase_rad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
power_byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
power_ln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
power_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
read_fft_optimization_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
rft_generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
write_fft_optimization_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
5.7 Geometric-Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
affine_trans_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
affine_trans_image_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
gen_bundle_adjusted_mosaic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
gen_cube_map_mosaic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
gen_projective_mosaic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
gen_spherical_mosaic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
map_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
mirror_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
polar_trans_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
polar_trans_image_ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
polar_trans_image_inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
projective_trans_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
projective_trans_image_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
rotate_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
zoom_image_factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
zoom_image_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
5.8 Inpainting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
harmonic_interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
inpainting_aniso . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
inpainting_ced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
inpainting_ct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
inpainting_mcf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
inpainting_texture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
5.9 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
bandpass_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
lines_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
lines_facet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
lines_gauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
5.10 Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
exhaustive_match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
exhaustive_match_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
gen_gauss_pyramid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
monotony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
5.11 Misc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
convol_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
expand_domain_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
gray_inside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
gray_skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
lut_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
symmetry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
topographic_sketch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
5.12 Noise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
add_noise_distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
add_noise_white . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
gauss_distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
noise_distribution_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
sp_distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
5.13 Optical-Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
optical_flow_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
unwarp_image_vector_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
vector_field_length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
5.14 Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
corner_response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
dots_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
points_foerstner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
points_harris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
points_sojka . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
5.15 Smoothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
anisotrope_diff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
anisotropic_diffusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
binomial_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
eliminate_min_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
eliminate_sp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
fill_interlace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
gauss_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
info_smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
isotropic_diffusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
mean_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
mean_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
mean_sp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
median_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
median_separate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
median_weighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
midrange_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
rank_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
sigma_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
smooth_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
trimmed_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.16 Texture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
deviation_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
entropy_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
texture_laws . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
5.17 Wiener-Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
gen_psf_defocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
gen_psf_motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
simulate_defocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
simulate_motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
wiener_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
wiener_filter_ni . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

6 Graphics 323
6.1 Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
drag_region1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
drag_region2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
drag_region3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
draw_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
draw_circle_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
draw_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
draw_ellipse_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
draw_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
draw_line_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
draw_nurbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
draw_nurbs_interp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
draw_nurbs_interp_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
draw_nurbs_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
draw_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
draw_point_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
draw_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
draw_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
draw_rectangle1_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
draw_rectangle2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
draw_rectangle2_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
draw_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
draw_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
draw_xld_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
6.2 Gnuplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
gnuplot_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
gnuplot_open_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
gnuplot_open_pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
gnuplot_plot_ctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
gnuplot_plot_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
gnuplot_plot_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
6.3 LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
disp_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
draw_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
get_fixed_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
get_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
get_lut_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
query_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
set_fixed_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
set_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
set_lut_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
write_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
6.4 Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
get_mbutton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
get_mposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
get_mshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
query_mshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
set_mshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
6.5 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
disp_arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
disp_arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
disp_channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
disp_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
disp_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
disp_cross . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
disp_distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
disp_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
disp_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
disp_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
disp_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
disp_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
disp_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
disp_rectangle2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
disp_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
disp_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
6.6 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
get_comprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
get_draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
get_fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
get_hsi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
get_icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
get_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
get_line_approx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
get_line_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
get_line_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
get_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
get_part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
get_part_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
get_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
get_rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
get_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
query_all_colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
query_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
query_colored . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
query_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
query_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
query_line_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
query_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
query_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
set_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
set_colored . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
set_comprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
set_draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
set_fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
set_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
set_hsi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
set_icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
set_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
set_line_approx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
set_line_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
set_line_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
set_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
set_part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
set_part_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
set_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
set_rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
set_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
6.7 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
get_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
get_string_extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
get_tposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
get_tshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
new_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
query_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
query_tshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
read_char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
read_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
set_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
set_tposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
set_tshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
write_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
6.8 Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
clear_rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
clear_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
close_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
copy_rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
dump_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
dump_window_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
get_os_window_handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
get_window_attr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
get_window_extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
get_window_pointer3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
get_window_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
move_rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
new_extern_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
open_textwindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
open_window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
query_window_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
set_window_attr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
set_window_dc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
set_window_extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
set_window_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
slide_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

7 Image 447
7.1 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
get_grayval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
get_image_pointer1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
get_image_pointer1_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
get_image_pointer3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
get_image_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
7.2 Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
close_all_framegrabbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
close_framegrabber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
get_framegrabber_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
get_framegrabber_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
grab_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
grab_data_async . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
grab_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
grab_image_async . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
grab_image_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
info_framegrabber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
open_framegrabber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
set_framegrabber_lut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
set_framegrabber_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
7.3 Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
access_channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
append_channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
channels_to_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
compose2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
compose3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
compose4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
compose5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
compose6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
compose7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
count_channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
decompose2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
decompose3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
decompose4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
decompose5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
decompose6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
decompose7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
image_to_channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
7.4 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
copy_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
gen_image1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
gen_image1_extern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
gen_image1_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
gen_image3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
gen_image_const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
gen_image_gray_ramp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
gen_image_interleaved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
gen_image_proto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
gen_image_surface_first_order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
gen_image_surface_second_order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
region_to_bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
region_to_label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
region_to_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
7.5 Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
add_channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
change_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
full_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
get_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
rectangle1_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
reduce_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
7.6 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
area_center_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
cooc_feature_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
cooc_feature_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
elliptic_axis_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
entropy_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
estimate_noise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
fit_surface_first_order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
fit_surface_second_order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
fuzzy_entropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
fuzzy_perimeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
gen_cooc_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
gray_histo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
gray_histo_abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
gray_projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
histo_2dim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
intensity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
min_max_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
moments_gray_plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
plane_deviation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
select_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
shape_histo_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
shape_histo_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
7.7 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
change_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
crop_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
crop_domain_rel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
crop_part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
crop_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
tile_channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
tile_images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
tile_images_offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
7.8 Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
overpaint_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
overpaint_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
paint_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
paint_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
paint_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
set_grayval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
7.9 Type-Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
complex_to_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
convert_image_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
real_to_complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
real_to_vector_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
vector_field_to_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

8 Lines 537
8.1 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
approx_chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
approx_chain_simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
8.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
line_orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
line_position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
partition_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
select_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
select_lines_longest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

9 Matching 549
9.1 Component-Based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
clear_all_component_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
clear_all_training_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
clear_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
clear_training_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
cluster_model_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
create_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
create_trained_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
find_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
gen_initial_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
get_component_model_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
get_component_model_tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
get_component_relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
get_found_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
get_training_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
inspect_clustered_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
modify_component_relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
read_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
read_training_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
train_model_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
write_component_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
write_training_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
9.2 Correlation-Based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
clear_all_ncc_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
clear_ncc_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
create_ncc_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
find_ncc_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
get_ncc_model_origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
get_ncc_model_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
read_ncc_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
set_ncc_model_origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
write_ncc_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
9.3 Gray-Value-Based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
adapt_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
best_match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
best_match_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
best_match_pre_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
best_match_rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
best_match_rot_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
clear_all_templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
clear_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
create_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
create_template_rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
fast_match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
fast_match_mg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
read_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
set_offset_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
set_reference_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
write_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
9.4 Shape-Based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
clear_all_shape_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
clear_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
create_aniso_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
create_scaled_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
create_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
determine_shape_model_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
find_aniso_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
find_aniso_shape_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
find_scaled_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
find_scaled_shape_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
find_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
find_shape_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
get_shape_model_contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
get_shape_model_origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
get_shape_model_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
inspect_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
read_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
set_shape_model_origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
write_shape_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

10 Matching-3D 649
affine_trans_object_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
clear_all_object_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
clear_all_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
clear_object_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
clear_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
convert_point_3d_cart_to_spher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
convert_point_3d_spher_to_cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
create_cam_pose_look_at_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
create_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
find_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
get_object_model_3d_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
get_shape_model_3d_contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
get_shape_model_3d_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
project_object_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
project_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
read_object_model_3d_dxf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
read_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
trans_pose_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
write_shape_model_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

11 Morphology 675
11.1 Gray-Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
dual_rank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
gen_disc_se . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
gray_bothat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
gray_closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
gray_closing_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
gray_closing_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
gray_dilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
gray_dilation_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
gray_dilation_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
gray_erosion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
gray_erosion_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
gray_erosion_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
gray_opening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
gray_opening_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
gray_opening_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
gray_range_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
gray_tophat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
read_gray_se . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
11.2 Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
bottom_hat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
closing_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
closing_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
closing_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
dilation1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
dilation2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
dilation_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
dilation_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
dilation_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
dilation_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
erosion1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
erosion2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
erosion_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
erosion_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
erosion_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
erosion_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
fitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
gen_struct_elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
golay_elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
hit_or_miss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
hit_or_miss_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
hit_or_miss_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
minkowski_add1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
minkowski_add2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
minkowski_sub1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
minkowski_sub2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
morph_hat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
morph_skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
morph_skiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
opening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
opening_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
opening_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
opening_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
opening_seg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
pruning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
thickening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
thickening_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
thickening_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
thinning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
thinning_golay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
thinning_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
top_hat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

12 OCR 743
12.1 Hyperboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
close_all_ocrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
close_ocr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
create_ocr_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
do_ocr_multi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
do_ocr_single . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
info_ocr_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
ocr_change_char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
ocr_get_features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
read_ocr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
testd_ocr_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
traind_ocr_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
trainf_ocr_class_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
write_ocr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
12.2 Lexica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
clear_all_lexica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
clear_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
create_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
import_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
inspect_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
lookup_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
suggest_lexicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
12.3 Neural-Nets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
clear_all_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
clear_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
create_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
do_ocr_multi_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
do_ocr_single_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
do_ocr_word_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
get_features_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
get_params_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
get_prep_info_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
read_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
trainf_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
write_ocr_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
12.4 Support-Vector-Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
clear_all_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
clear_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
create_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
do_ocr_multi_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
do_ocr_single_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
do_ocr_word_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
get_features_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
get_params_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
get_prep_info_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
get_support_vector_num_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
get_support_vector_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
read_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
reduce_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
trainf_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
write_ocr_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
12.5 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
segment_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
select_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
text_line_orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
text_line_slant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
12.6 Training-Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
append_ocr_trainf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
concat_ocr_trainf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
read_ocr_trainf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
read_ocr_trainf_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
read_ocr_trainf_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
write_ocr_trainf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
write_ocr_trainf_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

13 Object 795
13.1 Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
count_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
get_channel_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
get_obj_class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
test_equal_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
test_obj_def . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
13.2 Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
clear_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
concat_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
copy_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
gen_empty_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
integer_to_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
obj_to_integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
select_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

14 Regions 805
14.1 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
get_region_chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
get_region_contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
get_region_convex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
get_region_points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
get_region_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
get_region_runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
14.2 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
gen_checker_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
gen_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
gen_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
gen_empty_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
gen_grid_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
gen_random_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
gen_random_regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
gen_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
gen_rectangle2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
gen_region_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
gen_region_histo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
gen_region_hline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
gen_region_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
gen_region_points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
gen_region_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
gen_region_polygon_filled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
gen_region_polygon_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
gen_region_runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
label_to_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
14.3 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
area_center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
circularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
compactness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
connect_and_holes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
contlength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
convexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
diameter_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
eccentricity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
elliptic_axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
euler_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
find_neighbors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
get_region_index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
get_region_thickness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
hamming_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
hamming_distance_norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
inner_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
inner_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
moments_region_2nd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
moments_region_2nd_invar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
moments_region_2nd_rel_invar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
moments_region_3rd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847
moments_region_3rd_invar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
moments_region_central . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
moments_region_central_invar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
orientation_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
rectangularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
roundness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
runlength_distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
runlength_features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
select_region_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
select_region_spatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
select_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
select_shape_proto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
select_shape_std . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
smallest_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
smallest_rectangle1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
smallest_rectangle2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
spatial_relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
14.4 Geometric-Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
affine_trans_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
mirror_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
move_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
polar_trans_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
polar_trans_region_inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
projective_trans_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
transpose_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
zoom_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
14.5 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
complement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
intersection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
symm_difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
union1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
union2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
14.6 Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
test_equal_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
test_region_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
test_subset_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
14.7 Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
background_seg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
clip_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
clip_region_rel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
distance_transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
eliminate_runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
expand_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
fill_up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
fill_up_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
hamming_change_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
interjacent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
junctions_skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
merge_regions_line_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
partition_dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896
partition_rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
rank_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
remove_noise_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
shape_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
sort_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
split_skeleton_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
split_skeleton_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904

15 Segmentation 905
15.1 Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905
add_samples_image_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905
add_samples_image_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
add_samples_image_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
class_2dim_sup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
class_2dim_unsup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
class_ndim_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
class_ndim_norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
classify_image_class_gmm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
classify_image_class_mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
classify_image_class_svm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
learn_ndim_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
learn_ndim_norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
15.2 Edges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
detect_edge_segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
hysteresis_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
nonmax_suppression_amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
nonmax_suppression_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
15.3 Regiongrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
expand_gray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
expand_gray_ref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
expand_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
regiongrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
regiongrowing_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
regiongrowing_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
15.4 Threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
auto_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
bin_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
char_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
check_difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
dual_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
dyn_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
fast_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943
histo_to_thresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
threshold_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
var_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
zero_crossing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
zero_crossing_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
15.5 Topography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
critical_points_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
local_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
local_max_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
local_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
local_min_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
lowlands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
lowlands_center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
plateaus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
plateaus_center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
pouring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
saddle_points_sub_pix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
watersheds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
watersheds_threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963

16 System 965
16.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
count_relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
get_modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
reset_obj_db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
16.2 Error-Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
get_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
get_error_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
get_spy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
query_spy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
set_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
set_spy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
16.3 Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
get_chapter_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
get_keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
get_operator_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
get_operator_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
get_param_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
get_param_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
get_param_num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
get_param_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
query_operator_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
query_param_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
search_operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.4 Operating-System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
count_seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
system_call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
wait_seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
16.5 Parallelization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
check_par_hw_potential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
load_par_knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
store_par_knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
16.6 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
get_system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
set_system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
16.7 Serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
clear_serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
close_all_serials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
close_serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
get_serial_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
open_serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
read_serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
set_serial_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
write_serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
16.8 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
close_socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
get_next_socket_data_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
get_socket_descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
get_socket_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
open_socket_accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
open_socket_connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
receive_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
receive_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
receive_tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
receive_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
send_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
send_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
send_tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
send_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
set_socket_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
socket_accept_connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

17 Tools 1011
17.1 2D-Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
affine_trans_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
affine_trans_point_2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
bundle_adjust_mosaic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
hom_mat2d_compose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
hom_mat2d_determinant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
hom_mat2d_identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
hom_mat2d_invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
hom_mat2d_rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
hom_mat2d_rotate_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
hom_mat2d_scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
hom_mat2d_scale_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
hom_mat2d_slant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
hom_mat2d_slant_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
hom_mat2d_to_affine_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
hom_mat2d_translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
hom_mat2d_translate_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
hom_mat2d_transpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
hom_mat3d_project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
hom_vector_to_proj_hom_mat2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
proj_match_points_ransac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
projective_trans_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034
projective_trans_point_2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
vector_angle_to_rigid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
vector_field_to_hom_mat2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
vector_to_hom_mat2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
vector_to_proj_hom_mat2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
vector_to_rigid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
vector_to_similarity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
17.2 3D-Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
affine_trans_point_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
convert_pose_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
create_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
get_pose_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
hom_mat3d_compose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
hom_mat3d_identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
hom_mat3d_invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
hom_mat3d_rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
hom_mat3d_rotate_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
hom_mat3d_scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054
hom_mat3d_scale_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
hom_mat3d_to_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
hom_mat3d_translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
hom_mat3d_translate_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
pose_to_hom_mat3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060
read_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
set_origin_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
write_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.3 Background-Estimator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
close_all_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
close_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
create_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
get_bg_esti_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
give_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
run_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
set_bg_esti_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
update_bg_esti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
17.4 Barcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
clear_all_bar_code_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
clear_bar_code_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
create_bar_code_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
find_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
get_bar_code_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
get_bar_code_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
get_bar_code_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
set_bar_code_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
17.5 Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
caltab_points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
cam_mat_to_cam_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
cam_par_to_cam_mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
camera_calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
change_radial_distortion_cam_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
change_radial_distortion_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
change_radial_distortion_image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
contour_to_world_plane_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
create_caltab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
disp_caltab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
find_caltab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
find_marks_and_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101
gen_caltab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
gen_image_to_world_plane_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
gen_radial_distortion_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
get_circle_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109
get_line_of_sight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
get_rectangle_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
hand_eye_calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
image_points_to_world_plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123
image_to_world_plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
project_3d_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
radiometric_self_calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
read_cam_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
sim_caltab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
stationary_camera_self_calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
write_cam_par . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.6 Datacode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
clear_all_data_code_2d_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
clear_data_code_2d_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
create_data_code_2d_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
find_data_code_2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
get_data_code_2d_objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
get_data_code_2d_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
get_data_code_2d_results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
query_data_code_2d_params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
read_data_code_2d_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
set_data_code_2d_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
write_data_code_2d_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166
17.7 Fourier-Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167
abs_invar_fourier_coeff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167
fourier_1dim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1168
fourier_1dim_inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
invar_fourier_coeff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170
match_fourier_coeff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171
move_contour_orig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
prep_contour_fourier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.8 Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
abs_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
compose_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
create_funct_1d_array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
create_funct_1d_pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
derivate_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
distance_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
funct_1d_to_pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
get_pair_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177
get_y_value_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177
integrate_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
invert_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
local_min_max_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179
match_funct_1d_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179
negate_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180
num_points_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
read_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
sample_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182
scale_y_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182
smooth_funct_1d_gauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
smooth_funct_1d_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
transform_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
write_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
x_range_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185
y_range_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185
zero_crossings_funct_1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.9 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
angle_ll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
angle_lx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
distance_cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1188
distance_cc_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189
distance_lc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1190
distance_lr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1190
distance_pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191
distance_pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192
distance_pp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
distance_pr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194
distance_ps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
distance_rr_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
distance_rr_min_dil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1197
distance_sc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
distance_sl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
distance_sr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200
distance_ss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
get_points_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1202
intersection_ll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
projection_pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.10 Grid-Rectification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
connect_grid_points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
create_rectification_grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1206
find_rectification_grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207
gen_arbitrary_distortion_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207
gen_grid_rectification_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.11 Hough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
hough_circle_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
hough_circles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
hough_line_trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
hough_line_trans_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
hough_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
hough_lines_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
select_matching_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216
17.12 Image-Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217
clear_all_variation_models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217
clear_train_data_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217
clear_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218
compare_ext_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218
compare_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
create_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
get_thresh_images_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
get_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
prepare_direct_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
prepare_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
read_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
train_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
write_variation_model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.13 Kalman-Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
filter_kalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
read_kalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
sensor_kalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234
update_kalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235
17.14 Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
close_all_measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
close_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
fuzzy_measure_pairing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
fuzzy_measure_pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241
fuzzy_measure_pos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243
gen_measure_arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244
gen_measure_rectangle2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246
measure_pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1248
measure_pos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250
measure_projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
measure_thresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253
reset_fuzzy_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254
set_fuzzy_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254
set_fuzzy_measure_norm_pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
translate_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
17.15 OCV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
close_all_ocvs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
close_ocv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
create_ocv_proj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260
do_ocv_simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261
read_ocv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
traind_ocv_proj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
write_ocv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263
17.16 Shape-from . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
depth_from_focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
estimate_al_am . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
estimate_sl_al_lr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
estimate_sl_al_zc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
estimate_tilt_lr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
estimate_tilt_zc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267
phot_stereo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267
select_grayvalues_from_channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1268
sfs_mod_lr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269
sfs_orig_lr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270
sfs_pentland . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271
shade_height_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1272
17.17 Stereo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274
binocular_calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274
binocular_disparity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277
binocular_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
disparity_to_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283
disparity_to_point_3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283
distance_to_disparity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1284
essential_to_fundamental_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285
gen_binocular_proj_rectification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
gen_binocular_rectification_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288
intersect_lines_of_sight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1290
match_essential_matrix_ransac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291
match_fundamental_matrix_ransac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295
match_rel_pose_ransac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
reconst3d_from_fundamental_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301
rel_pose_to_fundamental_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
vector_to_essential_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
vector_to_fundamental_matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306
vector_to_rel_pose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308
17.18 Tools-Legacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310
decode_1d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310
decode_2d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
discrete_1d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
find_1d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
find_1d_bar_code_region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1317
find_1d_bar_code_scanline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1319
find_2d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
gen_1d_bar_code_descr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324
gen_1d_bar_code_descr_gen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326
gen_2d_bar_code_descr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327
get_1d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
get_1d_bar_code_scanline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330
get_2d_bar_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332
get_2d_bar_code_pos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336

18 Tuple 1339
18.1 Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
tuple_abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
tuple_acos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
tuple_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340
tuple_asin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340
tuple_atan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
tuple_atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
tuple_ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
tuple_cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342
tuple_cosh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342
tuple_cumul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
tuple_deg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
tuple_div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
tuple_exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
tuple_fabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
tuple_floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
tuple_fmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
tuple_ldexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
tuple_log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346
tuple_log10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346
tuple_max2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347
tuple_min2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347
tuple_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1348
tuple_mult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1348
tuple_neg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1348
tuple_pow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349
tuple_rad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349
tuple_sgn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350
tuple_sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350
tuple_sinh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350
tuple_sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
tuple_sub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
tuple_tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352
tuple_tanh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352
18.2 Bit-Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352
tuple_band . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352
tuple_bnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
tuple_bor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
tuple_bxor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
tuple_lsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
tuple_rsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
18.3 Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
tuple_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
tuple_greater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
tuple_greater_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
tuple_less . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
tuple_less_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
tuple_not_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
18.4 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
tuple_chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
tuple_chrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
tuple_int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
tuple_is_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
tuple_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
tuple_ord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
tuple_ords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
tuple_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
tuple_round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
tuple_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
18.5 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363
tuple_concat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363
tuple_gen_const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1364
tuple_rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1364
18.6 Element-Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
tuple_inverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
tuple_sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
tuple_sort_index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
18.7 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
tuple_deviation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
tuple_length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
tuple_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
tuple_mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
tuple_median . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
tuple_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
tuple_sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
18.8 Logical-Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
tuple_and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
tuple_not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
tuple_or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
tuple_xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
18.9 Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
tuple_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
tuple_first_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
tuple_last_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
tuple_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
tuple_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373
tuple_select_range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373
tuple_select_rank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
tuple_str_bit_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
tuple_uniq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
18.10 String-Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
tuple_environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
tuple_regexp_match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
tuple_regexp_replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
tuple_regexp_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
tuple_regexp_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
tuple_split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
tuple_str_first_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
tuple_str_last_n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
tuple_strchr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
tuple_strlen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
tuple_strrchr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
tuple_strrstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
tuple_strstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383

19 XLD 1385
19.1 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
get_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
get_lines_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
get_parallels_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386
get_polygon_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
19.2 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
gen_contour_nurbs_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
gen_contour_polygon_rounded_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
gen_contour_polygon_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390
gen_contour_region_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
gen_contours_skeleton_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
gen_cross_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
gen_ellipse_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
gen_parallels_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
gen_polygons_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
gen_rectangle2_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
mod_parallels_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
19.3 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
area_center_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
area_center_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
circularity_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
compactness_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
contour_point_num_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
convexity_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1402
diameter_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1402
dist_ellipse_contour_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1403
dist_ellipse_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
dist_rectangle2_contour_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406
eccentricity_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
eccentricity_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408
elliptic_axis_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408
elliptic_axis_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
fit_circle_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
fit_ellipse_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413
fit_line_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
fit_rectangle2_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
get_contour_angle_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419
get_contour_attrib_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1420
get_contour_global_attrib_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
get_regress_params_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
info_parallels_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422
length_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
local_max_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424
max_parallels_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424
moments_any_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
moments_any_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
moments_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428
moments_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
orientation_points_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
orientation_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
query_contour_attribs_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
query_contour_global_attribs_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
select_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
select_shape_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433
select_xld_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435
smallest_circle_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
smallest_rectangle1_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437
smallest_rectangle2_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1438
test_self_intersection_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
test_xld_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
19.4 Geometric-Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
affine_trans_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
affine_trans_polygon_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
gen_parallel_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
polar_trans_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
polar_trans_contour_xld_inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
projective_trans_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446
19.5 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447
difference_closed_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447
difference_closed_polygons_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
intersection_closed_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
intersection_closed_polygons_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
symm_difference_closed_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1450
symm_difference_closed_polygons_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1451
union2_closed_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
union2_closed_polygons_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
19.6 Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
add_noise_white_contour_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
clip_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455
close_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456
combine_roads_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456
crop_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
merge_cont_line_scan_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
regress_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
segment_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
shape_trans_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
smooth_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
sort_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
split_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
union_adjacent_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465
union_cocircular_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1466
union_collinear_contours_ext_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1468
union_collinear_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469
union_straight_contours_histo_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471
union_straight_contours_xld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1472

Index 1475
Chapter 1

Classification

1.1 Gaussian-Mixture-Models
add_sample_class_gmm ( : : GMMHandle, Features, ClassID,
Randomize : )

Add a training sample to the training data of a Gaussian Mixture Model.


add_sample_class_gmm adds a training sample to the Gaussian Mixture Model (GMM) given by
GMMHandle. The training sample is given by Features and ClassID. Features is the feature vector
of the sample, and consequently must be a real vector of length NumDim, as specified in create_class_gmm.
ClassID is the class of the sample, an integer between 0 and NumClasses-1 (set in create_class_gmm).
In the special case where the feature vectors are of integer type, they are lying in the feature space in a grid with
step width 1.0. For example, the RGB feature vectors typically used for color classification are triples having
integer values between 0 and 255 for each of their components. In fact, there might be even several feature vectors
representing the same point. When training a GMM with such data, the training algorithm may tend to align the
modelled Gaussians along linearly dependent lines or planes of data that are parallel to the grid dimensions. If
the number of Centers returned by train_class_gmm is unusually high, this indicates such a behavior of
the algorithm. The parameter Randomize can be used to handle such undesired effects. If Randomize > 0.0,
random Gaussian noise with mean 0 and standard deviation Randomize is added to each component of the
training data vectors, and the transformed training data is stored in the GMM. For values of Randomize ≤ 1.0,
the randomized data will look like small clouds around the grid points, which does not improve the properties of
the data cloud. For values of Randomize  2.0, the randomization might have a too strong influence on the
resulting GMM. For integer feature vectors, a value of Randomize between 1.5 and 2.0 is recommended, which
transfoms the integer data into homogeneous clouds, without modifying its general form in the feature space. If
the data has been created from integer data by scaling, the same problem may occur. Here, Randomize must be
scaled with the same scale factor that was used to scale the original data.
Before the GMM can be trained with train_class_gmm, all training samples must be added to the GMM with
add_sample_class_gmm.
The number of currently stored training samples can be queried with get_sample_num_class_gmm. Stored
training samples can be read out again with get_sample_class_gmm.
Normally, it is useful to save the training samples in a file with write_samples_class_gmm to facilitate
reusing the samples, and to facilitate that, if necessary, new training samples can be added to the data set, and
hence to facilitate that a newly created GMM can be trained anew with the extended data set.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample to be stored.
. ClassID (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer
Class of the training sample to be stored.

1
2 CHAPTER 1. CLASSIFICATION

. Randomize (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real


Standard deviation of the Gaussian noise added to the training data.
Default Value : 0.0
Suggested values : Randomize ∈ {0.0, 1.5, 2.0}
Restriction : Randomize ≥ 0.0
Result
If the parameters are valid, the operator add_sample_class_gmm returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
add_sample_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
create_class_gmm
Possible Successors
train_class_gmm, write_samples_class_gmm
Alternatives
read_samples_class_gmm, add_samples_image_class_gmm
See also
clear_samples_class_gmm, get_sample_num_class_gmm, get_sample_class_gmm
Module
Foundation

classify_class_gmm ( : : GMMHandle, Features, Num : ClassID,


ClassProb, Density, KSigmaProb )

Calculate the class of a feature vector by a Gaussian Mixture Model.


classify_class_gmm computes the best Num classes of the feature vector Features with the Gaussian
Mixture Model (GMM) GMMHandle and returns the classes in ClassID and the corresponding probabili-
ties of the classes in ClassProb. Before calling classify_class_gmm, the GMM must be trained with
train_class_gmm.
classify_class_gmm corresponds to a call to evaluate_class_gmm and an additional step that ex-
tracts the best Num classes. As described with evaluate_class_gmm, the output values of the GMM can
be interpreted as probabilities of the occurrence of the respective classes. However, here the posterior probabil-
ity ClassProb is further normalized as ClassProb = p(i|x)/p(x), where p(i|x) and p(x) are specified with
evaluate_class_gmm. In most cases it should be sufficient to use Num = 1 in order to decide whether the
probability of the best class is high enough. In some applications it may be interesting to also take the second best
class into account (Num = 2), particularly if it can be expected that the classes show a significant degree of overlap.
Density and KSigmaProb are explained with evaluate_class_gmm.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector.
. Num (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of best classes to determine.
Default Value : 1
Suggested values : Num ∈ {1, 2, 3, 4, 5}
. ClassID (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer
Result of classifying the feature vector with the GMM.
. ClassProb (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
A-posteriori probability of the classes.
. Density (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Probability density of the feature vector.

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 3

. KSigmaProb (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real


Normalized k-sigma-probability for the feature vector.
Result
If the parameters are valid, the operator classify_class_gmm returns the value 2 (H_MSG_TRUE). If nec-
essary an exception handling is raised.
Parallelization Information
classify_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
train_class_gmm, read_class_gmm
Alternatives
evaluate_class_gmm
See also
create_class_gmm
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Mario A.T. Figueiredo: “Unsupervised Learning of Finite Mixture Models”; IEEE Transactions on Pattern Analy-
sis and Machine Intelligence, Vol. 24, No. 3; March 2002.
Module
Foundation

clear_all_class_gmm ( : : : )

Clear all Gaussian Mixture Models.


clear_all_class_gmm clears all Gaussian Mixture Models (GMM) and frees all memory required for the
GMMs. After calling clear_all_class_gmm, no GMM can be used any longer.
Attention
clear_all_class_gmm exists solely for the purpose of implementing the “reset program” functionality in
HDevelop. clear_all_class_gmm must not be used in any application.
Result
clear_all_class_gmm always returns 2 (H_MSG_TRUE).
Parallelization Information
clear_all_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
classify_class_gmm, evaluate_class_gmm
Alternatives
clear_class_gmm
See also
create_class_gmm, read_class_gmm, write_class_gmm, train_class_gmm
Module
Foundation

clear_class_gmm ( : : GMMHandle : )

Clear a Gaussian Mixture Model.


clear_class_gmm clears the Gaussian Mixture Model (GMM) given by GMMHandle and frees all mem-
ory required for the GMM. After calling clear_class_gmm, the GMM can no longer be used. The handle
GMMHandle becomes invalid.

HALCON 8.0.2
4 CHAPTER 1. CLASSIFICATION

Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
Result
If the parameters are valid, the operator clear_class_gmm returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
clear_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
classify_class_gmm, evaluate_class_gmm
See also
create_class_gmm, read_class_gmm, write_class_gmm, train_class_gmm
Module
Foundation

clear_samples_class_gmm ( : : GMMHandle : )

Clear the training data of a Gaussian Mixture Model.


clear_samples_class_gmm clears all training samples that have been stored in the Gaussian Mixture
Model (GMM) GMMHandle. clear_samples_class_gmm should only be used if the GMM is trained
in the same process that uses the GMM for evaluation with evaluate_class_gmm or for classification
with classify_class_gmm. In this case, the memory required for the training samples can be freed
with clear_samples_class_gmm, and hence memory can be saved. In the normal usage, in which the
GMM is trained offline and written to a file with write_class_gmm, it is typically unnecessary to call
clear_samples_class_gmm because write_class_gmm does not save the training samples, and hence
the online process, which reads the GMM with read_class_gmm, requires no memory for the training samples.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
Result
If the parameters are valid, the operator clear_samples_class_gmm returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
clear_samples_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
train_class_gmm, write_samples_class_gmm
See also
create_class_gmm, clear_class_gmm, add_sample_class_gmm,
read_samples_class_gmm
Module
Foundation

create_class_gmm ( : : NumDim, NumClasses, NumCenters, CovarType,


Preprocessing, NumComponents, RandSeed : GMMHandle )

Create a Gaussian Mixture Model for classification


create_class_gmm creates a Gaussian Mixture Model (GMM) for classification. NumDim specifies the num-
ber of dimensions of the feature space, NumClasses specifies the number of classes. A GMM consists of
NumCenters Gaussian centers per class. NumCenters can not only be the exact number of centers to be used,
but, depending on the number of parameters, can specify upper and lower bounds for the number of centers:

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 5

exactly one parameter: The parameter determines the exact number of centers to be used for all classes.
exactly two parameters: The first parameter determines the mimimum number of centers, the second determines
the maximum number of centers for all classes.
exactly 2 · N umClasses parameters: Alternatingly every first parameter determines the minimum number of
centers per class and every second parameters determines the maximum number of centers per class.

When upper and lower bounds are specified, the optimum number of centers will be determined with the help of
the Mimimum Message Length Criterion (MML). In general, we recommend to start the training with (too) many
centers as maximum and the expected number of centers as minimum.
Each center is described by the parameters center mj , covariance matrix Cj , and mixing coefficient Pj . These pa-
rameters are calculated from the training data by means of the Expectation Maximization (EM) algorithm. A GMM
can approximate an arbitrary probability density, provided that enough centers are being used. The covariance ma-
trices Cj have the dimensions NumDim · NumDim (NumComponents · NumComponents if preprocessing is
used) and are symmetric. Further constraints can be given by CovarType:
For CovarType = ’spherical’, Cj is a scalar multiple of the identity matrix Cj = s2j I. The center density
function p(x|j) is

2
1 kx − mj k
p(x|j) = exp(− )
2
(2πsj )d/2 2s2j

For CovarType = ’diag’, Cj is a diagonal matrix Cj = diag(s2j,1 , ..., s2j,d ). The center density function p(x|j)
is

d
1 X (xi − mj,i )2
p(x|j) = exp(− )
d 2s2j,i
s2j,i )d/2
Q
(2π i=1
i=1

For CovarType = ’full’, Cj is a positive definite matrix. The center density function p(x|j) is

1 1
p(x|j) = 1 exp(− (x − mj )T C−1 (x − mj ))
(2π)d/2 |Cj | 2 2

The complexity of the calculations increases from CovarType = ’spherical’ over CovarType = ’diag’ to
CovarType = ’full’. At the same time the flexibility of the centers increases. In general, ’spherical’ therefore
needs higher values for NumCenters than ’full’.
The procedure to use GMM is as follows: First, a GMM is created by create_class_gmm. Then,
training vectors are added by add_sample_class_gmm, afterwards they can be written to disk with
write_samples_class_gmm. With train_class_gmm the classifier center parameters (defined above)
are determined. Furthermore, they can be saved with write_class_gmm for later classifications.
From the mixing probabilities Pj and the center density function p(x|j), the probability density function p(x) can
be calculated by:

ncomp
X
p(x) = P (j)p(x|j)
j=1

The probability density function p(x) can be evaluated with evaluate_class_gmm for a feature vector x.
classify_class_gmm sorts the p(x) and therefore discovers the most probable class of the feature vector.
The parameters Preprocessing and NumComponents can be used to preprocess the training data and reduce
its dimensions. These parameteters are explained in the description of the operator create_class_mlp.
create_class_gmm initializes the coordinates of the centers with random numbers. To ensure that the results of
training the classifier with train_class_gmm are reproducible, the seed value of the random number generator
is passed in RandSeed.

HALCON 8.0.2
6 CHAPTER 1. CLASSIFICATION

Parameter
. NumDim (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of dimensions of the feature space.
Default Value : 3
Suggested values : NumDim ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumDim ≥ 1
. NumClasses (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of classes of the GMM.
Default Value : 5
Suggested values : NumClasses ∈ {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
Restriction : NumClasses ≥ 1
. NumCenters (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer
Number of centers per class.
Default Value : 1
Suggested values : NumCenters ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30}
Restriction : NumClasses ≥ 1
. CovarType (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of the covariance matrices.
Default Value : ’spherical’
List of values : CovarType ∈ {’spherical’, ’diag’, ’full’}
. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
Default Value : ’normalization’
List of values : Preprocessing ∈ {’none’, ’normalization’, ’principal_components’,
’canonical_variates’}
. NumComponents (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Preprocessing parameter: Number of transformed features (ignored for Preprocessing = ’none’ and
Preprocessing = ’normalization’).
Default Value : 10
Suggested values : NumComponents ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumComponents ≥ 1
. RandSeed (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Seed value of the random number generator that is used to initialize the GMM with random values.
Default Value : 42
. GMMHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
Example

* Classification with Gaussian Mixture Models


create_class_gmm (NumDim, NumClasses, [1,5], ’full’, 42, GMMHandle)
* Add the training data
for J := 0 to NData-1 by 1
Features := [...]
Class := [...]
add_sample_class_gmm (GMMHandle, Features, Class)
endfor
* Train the GMM
train_class_gmm (GMMHandle, 100, 0.001, 0, Centers, Iter)
* Classify unknown data in ’Features’
classify_class_gmm (GMMHandle, Features, 1, ClassProb, Density, KSigmaProb)
clear_class_gmm (GMMHandle)

Result
If the parameters are valid, the operator create_class_gmm returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
create_class_gmm is processed completely exclusively without parallelization.

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 7

Possible Successors
add_sample_class_gmm, add_samples_image_class_gmm
Alternatives
create_class_mlp, create_class_svm, create_class_box
See also
clear_class_gmm, train_class_gmm, classify_class_gmm, evaluate_class_gmm,
classify_image_class_gmm
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Mario A.T. Figueiredo: “Unsupervised Learning of Finite Mixture Models”; IEEE Transactions on Pattern Analy-
sis and Machine Intelligence, Vol. 24, No. 3; March 2002.
Module
Foundation

evaluate_class_gmm ( : : GMMHandle, Features : ClassProb, Density,


KSigmaProb )

Evaluate a feature vector by a Gaussian Mixture Model.


evaluate_class_gmm computes three different probability values for a feature vector Features with the
Gaussian Mixture Model (GMM) GMMHandle.
The a-posteriori probablity of class i for the sample Features is computed as
ncomp
X
p(i|x) = P (j)p(x|j)
j=1

and returned for each class in ClassProb. The formulas for the calculation of the center density function p(x|j)
are described with create_class_gmm.
The probablity density of the feature vector is computed as a sum of the posterior class probabilities
nclasses
X
p(x) = P r(i)p(i|x)
i=1

and is returned in Density. Here, P r(i) are the prior classes probabilities as computed by
train_class_gmm. Density can be used for novelty detection, i.e., to reject feature vectors that do not
belong to any of the trained classes. However, since Density depends on the scaling of the feature vectors
and since Density is a probability density, and consequently does not need to lie between 0 and 1, the novelty
detection can typically be performed more easily with KSigmaProb (see below).
A k-sigma error ellipsoid is defined as a locus of points for which

(x − µ)T C −1 (x − µ) = k 2

In the one dimensional case this is the interval [µ − kσ, µ + kσ]. For any 1D Gaussian distribution, it is true
that approximately 65% of the occurrences of the random variable are within this range for k = 1, approximately
95% for k = 2, approximately 99% for k = 3, etc. Hence, the probability that a Gaussian distribution will
generate a random variable outside this range is approximately 35%, 5%, and 1%, respectively. This probability is
called k-sigma probability and is denoted by P [k]. P [k] can be computed numerically for univariate as well as for
multivariate Gaussian distributions, where it should be noted that for the same values of k, P (N ) [k] > P (N +1) [k]
(here N and (N+1) denote dimensions). For Gaussian mixture models the k-sigma probability is computed as:
ncomp
X
PGM M [x] = P (j)Pj [kj ], where kj2 = (x − µj )T Cj−1 (x − µj )
j=1

They then are weighted with the class priors, normalized, and returned for each class in KSigmaProb, such that

HALCON 8.0.2
8 CHAPTER 1. CLASSIFICATION

P r(i)
KSigmaProb[i] = PGM M [x]
P rmax

KSigmaProb can be used for novelty detection. Typically, feature vectors having values below 0.0001 should
be rejected. The parameter RejectionThreshold in classify_image_class_gmm is based on the
KSigmaProb values of the features.
Before calling evaluate_class_gmm, the GMM must be trained with train_class_gmm.
The position of the maximum value of ClassProb is usally interpreted as the class of the feature vector and the
corresponding value as the probability of the class. In this case, classify_class_gmm should be used instead
of evaluate_class_gmm, because classify_class_gmm directly returns the class and corresponding
probability.
Parameter
. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector.
. ClassProb (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
A-posteriori probability of the classes.
. Density (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .real ; real
Probability density of the feature vector.
. KSigmaProb (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Normalized k-sigma-probability for the feature vector.
Result
If the parameters are valid, the operator evaluate_class_gmm returns the value 2 (H_MSG_TRUE). If nec-
essary an exception handling is raised.
Parallelization Information
evaluate_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
train_class_gmm, read_class_gmm
Alternatives
classify_class_gmm
See also
create_class_gmm
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Mario A.T. Figueiredo: “Unsupervised Learning of Finite Mixture Models”; IEEE Transactions on Pattern Analy-
sis and Machine Intelligence, Vol. 24, No. 3; March 2002.
Module
Foundation

get_params_class_gmm ( : : GMMHandle : NumDim, NumClasses,


MinCenters, MaxCenters, CovarType )

Return the parameters of a Gaussian Mixture Model.


get_params_class_gmm returns the parameters of a Gaussian Mixture Model (GMM) that were specified
when the GMM was created with create_class_gmm. This is particularly useful if the GMM was read with
read_class_gmm. The output of get_params_class_gmm can, for example, be used to check whether
the feature vectors and/or the target data to be used have appropriate dimensions to be used with GMM. For a
description of the parameters, see create_class_gmm.

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 9

Parameter
. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
. NumDim (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of dimensions of the feature space.
. NumClasses (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of classes of the GMM.
. MinCenters (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Minimum number of centers per GMM class.
. MaxCenters (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Maximum number of centers per GMM class.
. CovarType (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of the covariance matrices.
Result
If the parameters are valid, the operator get_params_class_gmm returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
get_params_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
create_class_gmm, read_class_gmm
Possible Successors
add_sample_class_gmm, train_class_gmm
See also
evaluate_class_gmm, classify_class_gmm
Module
Foundation

get_prep_info_class_gmm ( : : GMMHandle,
Preprocessing : InformationCont, CumInformationCont )

Compute the information content of the preprocessed feature vectors of a GMM.


get_prep_info_class_gmm computes the information content of the training vectors that have been
transformed with the preprocessing given by Preprocessing. Preprocessing can be set to ’princi-
pal_components’ or ’canonical_variates’. The preprocessing methods are described with create_class_mlp.
The information content is derived from the variations of the transformed components of the feature vector, i.e., it
is computed solely based on the training data, independent of any error rate on the training data. The information
content is computed for all relevant components of the transformed feature vectors (NumComponents for ’princi-
pal_components’ and ’canonical_variates’, see create_class_gmm), and is returned in InformationCont
as a number between 0 and 1. To convert the information content into a percentage, it simply needs to be mul-
tiplied by 100. The cumulative information content of the first n components is returned in the n-th compo-
nent of CumInformationCont, i.e., CumInformationCont contains the sums of the first n elements of
InformationCont. To use get_prep_info_class_gmm, a sufficient number of samples must be added
to the GMM given by GMMHandle by using add_sample_class_gmm or read_samples_class_gmm.
InformationCont and CumInformationCont can be used to decide how many components of the
transformed feature vectors contain relevant information. An often used criterion is to require that the trans-
formed data must represent x% (e.g., 90%) of the data. This can be decided easily from the first value
of CumInformationCont that lies above x%. The number thus obtained can be used as the value for
NumComponents in a new call to create_class_gmm. The call to get_prep_info_class_gmm al-
ready requires the creation of a GMM, and hence the setting of NumComponents in create_class_gmm
to an initial value. However, if get_prep_info_class_gmm is called, it is typically not known how many
components are relevant, and hence how to set NumComponents in this call. Therefore, the following two-step
approach should typically be used to select NumComponents: In a first step, a GMM with the maximum num-
ber for NumComponents is created (NumComponents for ’principal_components’ and ’canonical_variates’).
Then, the training samples are added to the GMM and are saved in a file using write_samples_class_gmm.

HALCON 8.0.2
10 CHAPTER 1. CLASSIFICATION

Subsequently, get_prep_info_class_gmm is used to determine the information content of the compo-


nents, and with this NumComponents. After this, a new GMM with the desired number of components is
created, and the training samples are read with read_samples_class_gmm. Finally, the GMM is trained
with train_class_gmm.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
Default Value : ’principal_components’
List of values : Preprocessing ∈ {’principal_components’, ’canonical_variates’}
. InformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Relative information content of the transformed feature vectors.
. CumInformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Cumulative information content of the transformed feature vectors.
Example

* Create the initial GMM


create_class_gmm (NDim, NClasses, ’full’, ’principal_components’,
NDim, 42, GMMHandle)
* Generate and add the training data
for J := 0 to NData-1 by 1
* Generate training features and classes
* Data = [...]
* Class = [...]
add_sample_class_gmm (GMMHandle, Data, Class)
endfor
write_samples_class_gmm (GMMHandle, ’samples.gtf’)
* Compute the information content of the transformed features
get_prep_info_class_gmm (GMMHandle, ’principal_components’,
InformationCont, CumInformationCont)
* Determine NComp by inspecting InformationCont and CumInformationCont
* NComp = [...]
clear_class_gmm (GMMHandle)
* Create the actual GMM
create_class_gmm (NIn, NClasses, ’full’, ’principal_components’,
NComp, 42, GMMHandle)
* Train the GMM
read_samples_class_gmm (GMMHandle, ’samples.gtf’)
train_class_gmm (GMMHandle, 200, 0.0001, 0.0001, Centers,Iter)
write_class_gmm (GMMHandle, ’classifier.gmm’)
clear_class_gmm (GMMHandle)

Result
If the parameters are valid, the operator get_prep_info_class_gmm returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
get_prep_info_class_gmm may return the error 9211 (Matrix is not positive definite) if Preprocessing
= ’canonical_variates’ is used. This typically indicates that not enough training samples have been stored for each
class.
Parallelization Information
get_prep_info_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_gmm, read_samples_class_gmm
Possible Successors
clear_class_gmm, create_class_gmm

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 11

References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

get_sample_class_gmm ( : : GMMHandle, NumSample : Features,


ClassID )

Return a training sample from the training data of a Gaussian Mixture Models (GMM).
get_sample_class_gmm reads out a training sample from the Gaussian Mixture Model (GMM) given by
GMMHandle that was stored with add_sample_class_gmm or add_samples_image_class_gmm.
The index of the sample is specified with NumSample. The index is counted from 0, i.e., NumSample
must be a number between 0 and NumSamples − 1, where NumSamples can be determined with
get_sample_num_class_gmm. The training sample is returned in Features and ClassID. Features
is a feature vector of length NumDim, while ClassID is its class (see add_sample_class_gmm and
create_class_gmm).
get_sample_class_gmm can, for example, be used to reclassify the training data with
classify_class_gmm in order to determine which training samples, if any, are classified incorrectly.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. NumSample (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Index of the stored training sample.
. Features (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample.
. ClassID (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer
Class of the training sample.
Example

create_class_gmm (2, 2, [1,10], ’spherical’, ’none’, 2, 42, GMMHandle)


read_samples_class_gmm (GMMHandle, ’samples.gsf’)
train_class_gmm (GMMHandle, 100, 1e-4, ’training’, 1e-4, Centers, Iter)
* Reclassify the training samples
get_sample_num_class_gmm (GMMHandle, NumSamples)
for I := 0 to NumSamples-1 by 1
get_sample_class_gmm (GMMHandle, I, Features, Class)
classify_class_gmm (GMMHandle, Features, 2, ClassProb, Density,
KSigmaProb)
if (not (Class=ClassProb[0]))
* classified incorrectly
endif
endfor
clear_class_gmm (GMMHandle)

Result
If the parameters are valid, the operator get_sample_class_gmm returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
get_sample_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_gmm, add_samples_image_class_gmm, read_samples_class_gmm,
get_sample_num_class_gmm

HALCON 8.0.2
12 CHAPTER 1. CLASSIFICATION

Possible Successors
classify_class_gmm, evaluate_class_gmm
See also
create_class_gmm
Module
Foundation

get_sample_num_class_gmm ( : : GMMHandle : NumSamples )

Return the number of training samples stored in the training data of a Gaussian Mixture Model (GMM).
get_sample_num_class_gmm returns in NumSamples the number of training samples that are stored in the
Gaussian Mixture Model (GMM) given by GMMHandle. get_sample_num_class_gmm should be called
before the individual training samples are read out with get_sample_class_gmm, e.g., for the purpose of
reclassifying the training data (see get_sample_class_gmm).
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. NumSamples (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of stored training samples.
Result
If the parameters are valid, the operator get_sample_num_class_gmm returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
get_sample_num_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_gmm, add_samples_image_class_gmm, read_samples_class_gmm
Possible Successors
get_sample_class_gmm
See also
create_class_gmm
Module
Foundation

read_class_gmm ( : : FileName : GMMHandle )

Read a Gaussian Mixture Model from a file.


read_class_gmm reads a Gaussian Mixture Model (GMM) that has been stored with write_class_gmm.
Since the training of an GMM can consume a relatively long time, the GMM is typically trained in an of-
fline process and written to a file with write_class_gmm. In the online process the GMM is read with
read_class_gmm and subsequently used for evaluation with evaluate_class_gmm or for classification
with classify_class_gmm.
Parameter

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string


File name.
. GMMHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
Result
If the parameters are valid, the operator read_class_gmm returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 13

Parallelization Information
read_class_gmm is processed completely exclusively without parallelization.
Possible Successors
classify_class_gmm, evaluate_class_gmm
See also
create_class_gmm, write_class_gmm
Module
Foundation

read_samples_class_gmm ( : : GMMHandle, FileName : )

Read the training data of a Gaussian Mixture Model from a file.


read_samples_class_gmm reads training samples from the file given by FileName and adds them to the
training samples that have already been stored in the Gaussian Mixture Model (GMM) given by GMMHandle.
The GMM must be created with create_class_gmm before calling read_samples_class_gmm. As
described with train_class_gmm and write_samples_class_gmm, read_samples_class_gmm,
add_sample_class_gmm, and write_samples_class_gmm can be used to build up a database of train-
ing samples, and hence to improve the performance of the GMM by retraining the GMM with extended data
sets.
It should be noted that the training samples must have the correct dimensionality. The feature vectors stored in
FileName must have the lengths NumDim that was specified with create_class_gmm, and enough classes
must have been created in create_class_gmm. If this is not the case, an error message is returned.
It is possible to read files of samples that were written with write_samples_class_svm or
write_samples_class_mlp.
Parameter
. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
File name.
Result
If the parameters are valid, the operator read_samples_class_gmm returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
read_samples_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
create_class_gmm
Possible Successors
train_class_gmm
Alternatives
add_sample_class_gmm
See also
write_samples_class_gmm, write_samples_class_mlp, clear_samples_class_gmm
Module
Foundation

train_class_gmm ( : : GMMHandle, MaxIter, Threshold, ClassPriors,


Regularize : Centers, Iter )

Train a Gaussian Mixture Model.


train_class_gmm trains the Gaussian Mixture Model (GMM) referenced by GMMHandle. Before the
GMM can be trained, all training samples to be used for the training must be stored in the GMM using

HALCON 8.0.2
14 CHAPTER 1. CLASSIFICATION

add_sample_class_gmm, add_samples_image_class_gmm, or read_samples_class_gmm.


After the training, new training samples can be added to the GMM and the GMM can be trained again. Only
the classes with newly added training vectors will be calculated again.
During the training, the error that results from the GMM applied to the training vectors will be minimized with the
expectation maximization (EM) algorithm.
MaxIter specifies the maximum number of iterations per class for the EM algorithm. In practice, values between
20 and 200 should be sufficient for most problems. Threshold specifies a threshold for the relative changes
of the error. If the relative change in error exceeds the threshold after MaxIter iterations, the algorithm will be
canceled for this class. Because the algorithm starts with the maximum specified number of centers (parameter
NumCenters in create_class_gmm), in case of a premature termination the number of centers and the error
for this class will not be optimal. In this case, a new training with different parameters (e.g. another value for
RandSeed in create_class_gmm) can be tried.
ClassPriors specifies the method of calculation of the class priors in GMM. If ’training’ is specified, the
priors of the classes are taken from the proportion of the corresponding sample data during training. If ’uniform’
is specified, the priors are set equal to 1/NumClasses for all classes.
Regularize is used to regularize (nearly) singular covariance matrices during the training. A covariance matrix
might collapse to singularity if it is trained with linearly dependent data. To avoid this, a small value specified by
Regularize is added to each main diagonal element of the covariance matrix, which prevents this element from
becoming smaller than Regularize. A recommended value for Regularize is 0.0001. If Regularize is
set to 0.0, no regularization is performed.
The centers are initially randomly distributed. In individual cases, relatively high errors will result from the al-
gorithm because the initial random values determined by RandSeed in create_class_gmm lead to local
minima. In this case, a new GMM with a different value for RandSeed should be generated to test whether a
significantly smaller error can be obtained.
It should be noted that, depending on the number of centers, the type of covariance matrix, and the number of
training samples, the training can take from a few seconds to several hours.
On output, train_class_gmm returns in Centers the number of centers per class that have been
found to be optimal by the EM algorithm. This values can be used as a reference in NumCenters (in
create_class_gmm) for future GMMs. If the number of centers found by training a new GMM on integer
training data is unexpectedly high, this might be corrected by adding a Randomize noise to the training data in
add_sample_class_gmm. Iter contains the number of performed iterations per class. If a value in Iter
equals MaxIter, the training algorithm has been terminated prematurely (see above).
Parameter
. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer
GMM handle.
. MaxIter (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Maximum number of iterations of the expectation maximization algorithm
Default Value : 100
Suggested values : MaxIter ∈ {10, 20, 30, 50, 100, 200}
. Threshold (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Threshold for relative change of the error for the expectation maximization algorithm to terminate.
Default Value : 0.001
Suggested values : Threshold ∈ {0.001, 0.0001}
Restriction : (Threshold ≥ 0.0) ∧ (Threshold ≤ 1.0)
. ClassPriors (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Mode to determine the a-priori probabilities of the classes
Default Value : ’training’
List of values : ClassPriors ∈ {’training’, ’uniform’}
. Regularize (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Regularization value for preventing covariance matrix singularity.
Default Value : 0.0001
Restriction : (Regularize ≥ 0.0) ∧ (Regularize < 1.0)
. Centers (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Number of found centerss per class
. Iter (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Number of executed iterations per class

HALCON/HDevelop Reference Manual, 2008-5-13


1.1. GAUSSIAN-MIXTURE-MODELS 15

Example

create_class_gmm (NumDim, NumClasses, [1,5], ’full’, ’none’, 0, 42,


GMMHandle)
* Add the training data
read_samples_class_gmm (GMMHandle, ’samples.gsf’)
* Train the GMM
train_class_gmm (GMMHandle, 100, 1e-4, ’training’, 1e-4, Centers, Iter)
* Write the Gaussian Mixture Model to file
write_class_gmm (GMMHandle, ’gmmclassifier.gmm’)
clear_class_gmm (GMMHandle)

Result
If the parameters are valid, the operator train_class_gmm returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
train_class_gmm is processed completely exclusively without parallelization.
Possible Predecessors
add_sample_class_gmm, read_samples_class_gmm
Possible Successors
evaluate_class_gmm, classify_class_gmm, write_class_gmm
Alternatives
read_class_gmm
See also
create_class_gmm
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Mario A.T. Figueiredo: “Unsupervised Learning of Finite Mixture Models”; IEEE Transactions on Pattern Analy-
sis and Machine Intelligence, Vol. 24, No. 3; March 2002.
Module
Foundation

write_class_gmm ( : : GMMHandle, FileName : )

Write a Gaussian Mixture Model to a file.


write_class_gmm writes the Gaussian Mixture Model (GMM) GMMHandle to the file given by FileName.
write_class_gmm is typically called after the GMM has been trained with train_class_gmm. The GMM
can be read with read_class_gmm. write_class_gmm does not write any training samples that possibly
have been stored in the GMM. For this purpose, write_samples_class_gmm should be used.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid, the operator write_class_gmm returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
write_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
train_class_gmm

HALCON 8.0.2
16 CHAPTER 1. CLASSIFICATION

Possible Successors
clear_class_gmm
See also
create_class_gmm, read_class_gmm, write_samples_class_gmm
Module
Foundation

write_samples_class_gmm ( : : GMMHandle, FileName : )

Write the training data of a Gaussian Mixture Model to a file.


write_samples_class_gmm writes the training samples stored in the Gaussian Mixture Model (GMM)
GMMHandle to the file given by FileName. write_samples_class_gmm can be used to build up a
database of training samples, and hence to improve the performance of the GMM by training it with an extended
data set (see train_class_gmm).
The file FileName is overwritten by write_samples_class_gmm. Nevertheless, extending the database
of training samples is easy because read_samples_class_gmm and add_sample_class_gmm add the
training samples to the training samples that are already stored in memory with the GMM.
The created file can be read with read_samples_class_mlp if the classificator of a multilayer perceptron
(MLP) should be used. The class of a training sample in the GMM corresponds to a component of the target vector
in the MLP being 1.0.
Parameter

. GMMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_gmm ; integer


GMM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid, the operator write_samples_class_gmm returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
write_samples_class_gmm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_gmm
Possible Successors
clear_samples_class_gmm
See also
create_class_gmm, read_samples_class_gmm, read_samples_class_mlp,
write_samples_class_mlp
Module
Foundation

1.2 Hyperboxes

clear_sampset ( : : 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.

HALCON/HDevelop Reference Manual, 2008-5-13


1.2. HYPERBOXES 17

Parameter
. SampKey (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . feature_set ; integer
Number of the data set.
Result
clear_sampset returns 2 (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 Predecessors
create_class_box, enquire_class_box, learn_class_box, write_class_box
See also
test_sampset_box, learn_sampset_box, read_sampset
Module
Foundation

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
close_all_class_box exists solely for the purpose of implementing the “reset program” functionality in
HDevelop. close_all_class_box must not be used in any application.
Result
If it is possible to close the classificators the operator close_all_class_box returns the value 2
(H_MSG_TRUE). Otherwise an exception handling is raised.
Parallelization Information
close_all_class_box is local and processed completely exclusively without parallelization.
Alternatives
close_class_box
Module
Foundation

close_class_box ( : : 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 ; integer
Classificator’s handle number.
Result
close_class_box returns 2 (H_MSG_TRUE).
Parallelization Information
close_class_box is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, enquire_class_box, learn_class_box, write_class_box
See also
create_class_box, enquire_class_box, learn_class_box

HALCON 8.0.2
18 CHAPTER 1. CLASSIFICATION

Module
Foundation

create_class_box ( : : : ClassifHandle )

Create a new classificator.


create_class_box creates a new adaptive classificator. All procedures which are explained in chapter classi-
fication refer to such a initialized classificator (of type 2). See learn_class_box for more details about the
functionality of the classificator.
Parameter
. ClassifHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_box ; integer
Classificator’s handle number.
Result
create_class_box returns 2 (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 Successors
learn_class_box, enquire_class_box, write_class_box, close_class_box,
clear_sampset
See also
learn_class_box, enquire_class_box, close_class_box
Module
Foundation

descript_class_box ( : : ClassifHandle, 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’).
Parameter
. ClassifHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_box ; integer
Classificator’s handle number.
. Dimensions (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Highest dimension for output.
Default Value : 3
Result
descript_class_box returns 2 (H_MSG_TRUE).
Parallelization Information
descript_class_box is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, learn_class_box, set_class_box_param
Possible Successors
enquire_class_box, learn_class_box, write_class_box, close_class_box
See also
create_class_box, enquire_class_box, learn_class_box, read_class_box,
write_class_box
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


1.2. HYPERBOXES 19

enquire_class_box ( : : ClassifHandle, FeatureList : 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 ( 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 learn_class_box for more details about the functionality of the classificator.
You may call the procedures learn_class_box and 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 ; integer


Classificator’s handle number.
. FeatureList (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real / integer / string
Array of attributes which has to be classified.
Default Value : 1.0
. Class (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer ; integer
Number of the class to which the array of attributes had been assigned.
Result
enquire_class_box returns 2 (H_MSG_TRUE).
Parallelization Information
enquire_class_box is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, learn_class_box, set_class_box_param
Possible Successors
learn_class_box, write_class_box, close_class_box
Alternatives
enquire_reject_class_box
See also
test_sampset_box, learn_class_box, learn_sampset_box
Module
Foundation

enquire_reject_class_box ( : : ClassifHandle, FeatureList : 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 ( 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 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 learn_class_box for more details about the functionality of the classificator.
You may call the procedures learn_class_box and 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.

HALCON 8.0.2
20 CHAPTER 1. CLASSIFICATION

Parameter
. ClassifHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_box ; integer
Classificator’s handle number.
. FeatureList (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real / integer / string
Array of attributes which has to be classified.
Default Value : 1.0
. Class (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer ; integer
Number of the class, to which the array of attributes had been assigned or -1 for the rejection class.
Result
enquire_reject_class_box returns 2 (H_MSG_TRUE).
Parallelization Information
enquire_reject_class_box is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, learn_class_box, set_class_box_param
Possible Successors
learn_class_box, write_class_box, close_class_box
Alternatives
enquire_class_box
See also
test_sampset_box, learn_class_box, learn_sampset_box
Module
Foundation

get_class_box_param ( : : ClassifHandle, Flag : 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,
’split_error’ = 0.1,
’prop_constant’ = 0.25
Parameter
. ClassifHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_box ; integer
Classificator’s handle number.
. Flag (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Name of the system parameter.
Default Value : ’split_error’
List of values : Flag ∈ {’split_error’, ’prop_constant’, ’used_memory’, ’min_samples_for_split’}
. Value (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Value of the system parameter.
Result
get_class_box_param returns 2 (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 Predecessors
create_class_box, enquire_class_box, learn_class_box, write_class_box
Possible Successors
set_class_box_param, learn_class_box, enquire_class_box, write_class_box,
close_class_box, clear_sampset

HALCON/HDevelop Reference Manual, 2008-5-13


1.2. HYPERBOXES 21

See also
create_class_box, set_class_box_param
Module
Foundation

learn_class_box ( : : ClassifHandle, Features, 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 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 learn_class_box and 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 ; integer
Classificator’s handle number.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number-array ; real / integer / string
Array of attributes to learn.
Default Value : [1.0,1.5,2.0]
. Class (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Class to which the array has to be assigned.
Default Value : 1
Result
learn_class_box returns 2 (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
learn_class_box is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, enquire_class_box
Possible Successors
test_sampset_box, learn_class_box, enquire_class_box, write_class_box,
close_class_box, clear_sampset
See also
test_sampset_box, close_class_box, create_class_box, enquire_class_box,
learn_sampset_box
Module
Foundation

learn_sampset_box ( : : ClassifHandle, SampKey, Outfile, NSamples,


StopError, ErrorN : )

Train the classificator with one data set.

HALCON 8.0.2
22 CHAPTER 1. CLASSIFICATION

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 ; integer


Classificator’s handle number.
. SampKey (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . feature_set ; integer
Number of the data set to train.
. Outfile (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
Name of the protocol file.
Default Value : ’training_prot’
. NSamples (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of arrays of attributes to learn.
Default Value : 500
. StopError (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Classification error for termination.
Default Value : 0.05
. ErrorN (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Error during the assignment.
Default Value : 100
Result
learn_sampset_box returns 2 (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.
Possible Predecessors
create_class_box
Possible Successors
test_sampset_box, enquire_class_box, write_class_box, close_class_box,
clear_sampset
See also
test_sampset_box, enquire_class_box, learn_class_box, read_sampset
Module
Foundation

read_class_box ( : : ClassifHandle, 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 ; integer


Classificator’s handle number.

HALCON/HDevelop Reference Manual, 2008-5-13


1.2. HYPERBOXES 23

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string


Filename of the classificators.
Default Value : ’klassifikator1’
Result
read_class_box returns 2 (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.
Possible Predecessors
create_class_box
Possible Successors
test_sampset_box, enquire_class_box, write_class_box, close_class_box,
clear_sampset
See also
create_class_box, write_class_box
Module
Foundation

read_sampset ( : : FileName : 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.read ; string
Filename of the data set to train.
Default Value : ’sampset1’
. SampKey (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . feature_set ; integer
Identification of the data set to train.
Result
read_sampset returns 2 (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.
Possible Predecessors
create_class_box
Possible Successors
test_sampset_box, enquire_class_box, write_class_box, close_class_box,
clear_sampset
See also
test_sampset_box, clear_sampset, learn_sampset_box
Module
Foundation

set_class_box_param ( : : ClassifHandle, Flag, Value : )

Set system parameters for classification.

HALCON 8.0.2
24 CHAPTER 1. CLASSIFICATION

set_class_box_param modifies parameter which manipulate the training sequence while calling
learn_class_box. Only parameters of the classificator are modified, all other classificators remain unmodi-
fied. ’min_samples_for_split’ is the number of examples at least which have to train in one cuboid of this classi-
ficator, 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’ manipu-
lates 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 rea-
son. Parameters are only important during a learning sequence. They do not influence on the behavior of
enquire_class_box.
Default setting:
’min_samples_for_split’ = 80,
’split_error’ = 0.1,
’prop_constant’ = 0.25
Parameter
. ClassifHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_box ; integer
Classificator’s handle number.
. Flag (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Name of the wanted parameter.
Default Value : ’split_error’
Suggested values : Flag ∈ {’min_samples_for_split’, ’split_error’, ’prop_constant’}
. Value (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Value of the parameter.
Default Value : 0.1
Result
read_sampset returns 2 (H_MSG_TRUE).
Parallelization Information
set_class_box_param is local and processed completely exclusively without parallelization.
Possible Predecessors
create_class_box, enquire_class_box
Possible Successors
learn_class_box, test_sampset_box, write_class_box, close_class_box,
clear_sampset
See also
enquire_class_box, get_class_box_param, learn_class_box
Module
Foundation

test_sampset_box ( : : ClassifHandle, SampKey : 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 ; integer
Classificator’s handle number.
. SampKey (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . feature_set ; integer
Key of the test data.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 25

. Error (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real


Error during the assignment.
Result
test_sampset_box returns 2 (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 Predecessors
create_class_box, learn_class_box, set_class_box_param
Possible Successors
enquire_class_box, learn_class_box, write_class_box, close_class_box,
clear_sampset
See also
enquire_class_box, learn_class_box, learn_sampset_box, read_sampset
Module
Foundation

write_class_box ( : : ClassifHandle, 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 ; integer


Classificator’s handle number.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
Name of the file which contains the written data.
Default Value : ’klassifikator1’
Result
write_class_box returns 2 (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 Predecessors
create_class_box, enquire_class_box, learn_class_box, test_sampset_box,
write_class_box
Possible Successors
close_class_box, clear_sampset
See also
create_class_box, read_class_box
Module
Foundation

1.3 Neural-Nets
add_sample_class_mlp ( : : MLPHandle, Features, Target : )

Add a training sample to the training data of a multilayer perceptron.

HALCON 8.0.2
26 CHAPTER 1. CLASSIFICATION

add_sample_class_mlp adds a training sample to the multilayer perceptron (MLP) given by MLPHandle.
The training sample is given by Features and Target. Features is the feature vector of the sample, and
consequently must be a real vector of length NumInput, as specified in create_class_mlp. Target is
the target vector of the sample, which must have the length NumOutput (see create_class_mlp) for all
three types of activation functions of the MLP (exception: see below). If the MLP is used for regression (function
approximation), i.e., if OutputFunction = ’linear’, Target is the value of the function at the coordinate
Features. In this case, Target can contain arbitrary real numbers. For OutputFunction = ’logistic’,
Target can only contain the values 0.0 and 1.0. A value of 1.0 specifies that the attribute in question is present,
while a value of 0.0 specifies that the attribute is absent. Because in this case the attributes are independent,
arbitrary combinations of 0.0 and 1.0 can be passed. For OutputFunction = ’softmax’, Target also can only
contain the values 0.0 and 1.0. In contrast to OutputFunction = ’logistic’, the value 1.0 must be present for
exactly one element of the tuple Target. The location in the tuple designates the class of the sample. For ease of
use, a single integer value may be passed if OutputFunction = ’softmax’. This value directly designates the
class of the sample, which is counted from 0, i.e., the class must be an integer between 0 and NumOutput − 1.
The class is converted to a target vector of length NumOutput internally.
Before the MLP can be trained with train_class_mlp, all training samples must be added to the MLP with
add_sample_class_mlp.
The number of currently stored training samples can be queried with get_sample_num_class_mlp. Stored
training samples can be read out again with get_sample_class_mlp.
Normally, it is useful to save the training samples in a file with write_samples_class_mlp to facilitate
reusing the samples, and to facilitate that, if necessary, new training samples can be added to the data set, and
hence to facilitate that a newly created MLP can be trained anew with the extended data set.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample to be stored.
. Target (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) ; integer / real
Class or target vector of the training sample to be stored.
Result
If the parameters are valid, the operator add_sample_class_mlp returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
add_sample_class_mlp is processed completely exclusively without parallelization.
Possible Predecessors
create_class_mlp
Possible Successors
train_class_mlp, write_samples_class_mlp
Alternatives
read_samples_class_mlp
See also
clear_samples_class_mlp, get_sample_num_class_mlp, get_sample_class_mlp
Module
Foundation

classify_class_mlp ( : : MLPHandle, Features, Num : Class,


Confidence )

Calculate the class of a feature vector by a multilayer perceptron.


classify_class_mlp computes the best Num classes of the feature vector Features with the multilayer
perceptron (MLP) MLPHandle and returns the classes in Class and the corresponding confidences (probabili-
ties) of the classes in Confidence. Before calling classify_class_mlp, the MLP must be trained with
train_class_mlp.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 27

classify_class_mlp can only be called if the MLP is used as a classifier with OutputFunction = ’soft-
max’ (see create_class_mlp). Otherwise, an error message is returned. classify_class_mlp cor-
responds to a call to evaluate_class_mlp and an additional step that extracts the best Num classes. As
described with evaluate_class_mlp, the output values of the MLP can be interpreted as probabilities of the
occurrence of the respective classes. However, here the posterior probability ClassProb is further normalized as
ClassProb = p(i|x)/p(x), where p(i|x) and p(x) are defined as in evaluate_class_gmm. In most cases
it should be sufficient to use Num = 1 in order to decide whether the probability of the best class is high enough.
In some applications it may be interesting to also take the second best class into account (Num = 2), particularly if
it can be expected that the classes show a significant degree of overlap.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector.
. Num (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Number of best classes to determine.
Default Value : 1
Suggested values : Num ∈ {1, 2, 3, 4, 5}
. Class (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer
Result of classifying the feature vector with the MLP.
. Confidence (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real
Confidence(s) of the class(es) of the feature vector.
Result
If the parameters are valid, the operator classify_class_mlp returns the value 2 (H_MSG_TRUE). If nec-
essary an exception handling is raised.
Parallelization Information
classify_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
train_class_mlp, read_class_mlp
Alternatives
evaluate_class_mlp
See also
create_class_mlp
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

clear_all_class_mlp ( : : : )

Clear all multilayer perceptrons.


clear_all_class_mlp clears all multilayer perceptrons (MLP) and frees all memory required for the MLPs.
After calling clear_all_class_mlp, no MLP can be used any longer.
Attention
clear_all_class_mlp exists solely for the purpose of implementing the “reset program” functionality in
HDevelop. clear_all_class_mlp must not be used in any application.
Result
clear_all_class_mlp always returns 2 (H_MSG_TRUE).
Parallelization Information
clear_all_class_mlp is processed completely exclusively without parallelization.

HALCON 8.0.2
28 CHAPTER 1. CLASSIFICATION

Possible Predecessors
classify_class_mlp, evaluate_class_mlp
Alternatives
clear_class_mlp
See also
create_class_mlp, read_class_mlp, write_class_mlp, train_class_mlp
Module
Foundation

clear_class_mlp ( : : MLPHandle : )

Clear a multilayer perceptron.


clear_class_mlp clears the multilayer perceptron (MLP) given by MLPHandle and frees all memory re-
quired for the MLP. After calling clear_class_mlp, the MLP can no longer be used. The handle MLPHandle
becomes invalid.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
Result
If MLPHandle is valid, the operator clear_class_mlp returns the value 2 (H_MSG_TRUE). If necessary an
exception handling is raised.
Parallelization Information
clear_class_mlp is processed completely exclusively without parallelization.
Possible Predecessors
classify_class_mlp, evaluate_class_mlp
See also
create_class_mlp, read_class_mlp, write_class_mlp, train_class_mlp
Module
Foundation

clear_samples_class_mlp ( : : MLPHandle : )

Clear the training data of a multilayer perceptron.


clear_samples_class_mlp clears all training samples that have been added to the multilayer
perceptron (MLP) MLPHandle with add_sample_class_mlp or read_samples_class_mlp.
clear_samples_class_mlp should only be used if the MLP is trained in the same process that uses the
MLP for evaluation with evaluate_class_mlp or for classification with classify_class_mlp. In
this case, the memory required for the training samples can be freed with clear_samples_class_mlp,
and hence memory can be saved. In the normal usage, in which the MLP is trained offline and written to a
file with write_class_mlp, it is typically unnecessary to call clear_samples_class_mlp because
write_class_mlp does not save the training samples, and hence the online process, which reads the MLP
with read_class_mlp, requires no memory for the training samples.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
Result
If the parameters are valid, the operator clear_samples_class_mlp returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
clear_samples_class_mlp is processed completely exclusively without parallelization.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 29

Possible Predecessors
train_class_mlp, write_samples_class_mlp
See also
create_class_mlp, clear_class_mlp, add_sample_class_mlp,
read_samples_class_mlp
Module
Foundation

create_class_mlp ( : : NumInput, NumHidden, NumOutput, OutputFunction,


Preprocessing, NumComponents, RandSeed : MLPHandle )

Create a multilayer perceptron for classification or regression.


create_class_mlp creates a neural net in the form of a multilayer perceptron (MLP), which can be used for
classification or regression (function approximation), depending on how OutputFunction is set. The MLP
consists of three layers: an input layer with NumInput input variables (units, neurons), a hidden layer with
NumHidden units, and an output layer with NumOutput output variables. The MLP performs the following
steps to calculate the activations zj of the hidden units from the input data xi (the so-called feature vector):

ni
(1) (1) (1)
X
aj = wji xi + bj , j = 1, . . . , nh
i=1
(1) 
zj = tanh aj , j = 1, . . . , nh

(1) (1)
Here, the matrix wji and the vector bj are the weights of the input layer (first layer) of the MLP. In the hidden
layer (second layer), the activations zj are transformed in a first step by using linear combinations of the variables
in an analogous manner as above:

nh
(2) (2) (2)
X
ak = wkj zj + bk , k = 1, . . . , no
j=1

(2) (2)
Here, the matrix wkj and the vector bk are the weights of the second layer of the MLP.
The activation function used in the output layer can be determined by setting OutputFunction. For
OutputFunction = ’linear’, the data are simply copied:

(2)
yk = ak , k = 1, . . . , no

This type of activation function should be used for regression problems (function approximation). This activation
function is not suited for classification problems.
For OutputFunction = ’logistic’, the activations are computed as follows:

1
yk = (2) 
, k = 1, . . . , no
1 + exp − ak

This type of activation function should be used for classification problems with multiple (NumOutput) indepen-
dent logical attributes as output. This kind of classification problem is relatively rare in practice.
For OutputFunction = ’softmax’, the activations are computed as follows:

(2) 
exp ak
yk = Pno (2) , k = 1, . . . , no
l=1 al

HALCON 8.0.2
30 CHAPTER 1. CLASSIFICATION

This type of activation function should be used for common classification problems with multiple (NumOutput)
mutually exclusive classes as output. In particular, OutputFunction = ’softmax’ must be used for the classifi-
cation of pixel data with classify_image_class_mlp.
The parameters Preprocessing and NumComponents can be used to specify a preprocessing of the feature
vectors. For Preprocessing = ’none’, the feature vectors are passed unaltered to the MLP. NumComponents
is ignored in this case.
For all other values of Preprocessing, the training data set is used to compute a transformation of the feature
vectors during the training as well as later in the classification or evaluation.
For Preprocessing = ’normalization’, the feature vectors are normalized by subtracting the mean of the
training vectors and dividing the result by the standard deviation of the individual components of the training
vectors. Hence, the transformed feature vectors have a mean of 0 and a standard deviation of 1. The normalization
does not change the length of the feature vector. NumComponents is ignored in this case. This transformation
can be used if the mean and standard deviation of the feature vectors differs substantially from 0 and 1, respectively,
or for data in which the components of the feature vectors are measured in different units (e.g., if some of the data
are gray value features and some are region features, or if region features are mixed, e.g., ’circularity’ (unit: scalar)
and ’area’ (unit: pixel squared)). In these cases, the training of the net will typically require fewer iterations than
without normalization.
For Preprocessing = ’principal_components’, a principal component analysis is performed. First, the feature
vectors are normalized (see above). Then, an orthogonal transformation (a rotation in the feature space) that
decorrelates the training vectors is computed. After the transformation, the mean of the training vectors is 0 and
the covariance matrix of the training vectors is a diagonal matrix. The transformation is chosen such that the
transformed features that contain the most variation is contained in the first components of the transformed feature
vector. With this, it is possible to omit the transformed features in the last components of the feature vector,
which typically are mainly influenced by noise, without losing a large amount of information. The parameter
NumComponents can be used to detemine how many of the transformed feature vector components should be
used. Up to NumInput components can be selected. The operator get_prep_info_class_mlp can be
used to determine how much information each transformed component contains. Hence, it aids the selection of
NumComponents. Like data normalization, this transformation can be used if the mean and standard deviation of
the feature vectors differs substantially from 0 and 1, respectively, or for feature vectors in which the components
of the data are measured in different units. In addition, this transformation is useful if it can be expected that the
features are highly correlated.
In contrast to the above three transformations, which can be used for all MLP types, the transformation spec-
ified by Preprocessing = ’canonical_variates’ can only be used if the MLP is used as a classifier with
OutputFunction = ’softmax’). The computation of the canonical variates is also called linear discrimi-
nant analysis. In this case, a transformation that first normalizes the training vectors and then decorrelates the
training vectors on average over all classes is computed. At the same time, the transformation maximally sepa-
rates the mean values of the individual classes. As for Preprocessing = ’principal_components’, the trans-
formed components are sorted by information content, and hence transformed components with little informa-
tion content can be omitted. For canonical variates, up to min(NumOutput − 1, NumInput) components can
be selected. Also in this case, the information content of the transformed components can be determined with
get_prep_info_class_mlp. Like principal component analysis, canonical variates can be used to reduce
the amount of data without losing a large amount of information, while additionally optimizing the separability of
the classes after the data reduction.
For the last two types of transformations (’principal_components’ and ’canonical_variates’), the actual number of
input units of the MLP is determined by NumComponents, whereas NumInput determines the dimensionality
of the input data (i.e., the length of the untransformed feature vector). Hence, by using one of these two transfor-
mations, the number of input variables, and thus usually also the number of hidden units can be reduced. With this,
the time needed to train the MLP and to evaluate and classify a feature vector is typically reduced.
Usually, NumHidden should be selected in the order of magnitude of NumInput and NumOutput. In many
cases, much smaller values of NumHidden already lead to very good classification results. If NumHidden is
chosen too large, the MLP may overfit the training data, which typically leads to bad generalization properties, i.e.,
the MLP learns the training data very well, but does not return very good results on unknown data.
create_class_mlp initializes the above described weights with random numbers. To ensure that the results of
training the classifier with train_class_mlp are reproducible, the seed value of the random number generator
is passed in RandSeed. If the training results in a relatively large error, it sometimes may be possible to achieve
a smaller error by selecting a different value for RandSeed and retraining an MLP.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 31

After the MLP has been created, typically training samples are added to the MLP by repeatedly calling
add_sample_class_mlp or read_samples_class_mlp. After this, the MLP is typically trained us-
ing train_class_mlp. Hereafter, the MLP can be saved using write_class_mlp. Alternatively, the
MLP can be used immediately after training to evaluate data using evaluate_class_mlp or, if the MLP is
used as a classifier (i.e., for OutputFunction = ’softmax’), to classify data using classify_class_mlp.
A comparison of the MLP and the support vector machine (SVM) (see create_class_svm) typically shows
that SVMs are generally faster at training, especially for huge training sets, and achieve slightly better recognition
rates than MLPs. The MLP is faster at classification and should therefore be prefered in time critical applications.
Please note that this guideline assumes optimal tuning of the parameters.
Parameter

. NumInput (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer


Number of input variables (features) of the MLP.
Default Value : 20
Suggested values : NumInput ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumInput ≥ 1
. NumHidden (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of hidden units of the MLP.
Default Value : 10
Suggested values : NumHidden ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 120, 150}
Restriction : NumHidden ≥ 1
. NumOutput (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of output variables (classes) of the MLP.
Default Value : 5
Suggested values : NumOutput ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 120, 150}
Restriction : NumOutput ≥ 1
. OutputFunction (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of the activation function in the output layer of the MLP.
Default Value : ’softmax’
List of values : OutputFunction ∈ {’linear’, ’logistic’, ’softmax’}
. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
Default Value : ’normalization’
List of values : Preprocessing ∈ {’none’, ’normalization’, ’principal_components’,
’canonical_variates’}
. NumComponents (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Preprocessing parameter: Number of transformed features (ignored for Preprocessing = ’none’ and
Preprocessing = ’normalization’).
Default Value : 10
Suggested values : NumComponents ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumComponents ≥ 1
. RandSeed (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Seed value of the random number generator that is used to initialize the MLP with random values.
Default Value : 42
. MLPHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
Example

* Use the MLP for regression (function approximation)


create_class_mlp (1, NHidden, 1, ’linear’, ’none’, 1, 42, MLPHandle)
* Generate the training data
* D = [...]
* T = [...]
* Add the training data
for J := 0 to NData-1 by 1
add_sample_class_mlp (MLPHandle, D[J], T[J])
endfor

HALCON 8.0.2
32 CHAPTER 1. CLASSIFICATION

* Train the MLP


train_class_mlp (MLPHandle, 200, 0.001, 0.001, Error, ErrorLog)
* Generate test data
* X = [...]
* Compute the output of the MLP on the test data
for J := 0 to N-1 by 1
evaluate_class_mlp (MLPHandle, X[J], Y)
endfor
clear_class_mlp (MLPHandle)

* Use the MLP for classification


create_class_mlp (NIn, NHidden, NOut, ’softmax’, ’normalization’, NIn,
42, MLPHandle)
* Generate and add the training data
for J := 0 to NData-1 by 1
* Generate training features and classes
* Data = [...]
* Class = [...]
add_sample_class_mlp (MLPHandle, Data, Class)
endfor
* Train the MLP
train_class_mlp (MLPHandle, 100, 1, 0.01, Error, ErrorLog)
* Use the MLP to classify unknown data
for J := 0 to N-1 by 1
* Extract features
* Features = [...]
classify_class_mlp (MLPHandle, Features, 1, Class, Confidence)
endfor
clear_class_mlp (MLPHandle)

Result
If the parameters are valid, the operator create_class_mlp returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
create_class_mlp is processed completely exclusively without parallelization.
Possible Successors
add_sample_class_mlp
Alternatives
create_class_svm, create_class_gmm, create_class_box
See also
clear_class_mlp, train_class_mlp, classify_class_mlp, evaluate_class_mlp
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

evaluate_class_mlp ( : : MLPHandle, Features : Result )

Calculate the evaluation of a feature vector by a multilayer perceptron.


evaluate_class_mlp computes the result Result of evaluating the feature vector Features with
the multilayer perceptron (MLP) MLPHandle. The formulas used for the evaluation are described
with create_class_mlp. Before calling evaluate_class_mlp, the MLP must be trained with
train_class_mlp.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 33

If the MLP is used for regression (function approximation), i.e., if (OutputFunction = ’linear’), Result
is the value of the function at the coordinate Features. For OutputFunction = ’logistic’ and ’softmax’,
the values in Result can be interpreted as probabilities. Hence, for OutputFunction = ’logistic’ the ele-
ments of Result represent the probabilities of the presence of the respective independent attributes. Typically,
a threshold of 0.5 is used to decide whether the attribute is present or not. Depending on the application, other
thresholds may be used as well. For OutputFunction = ’softmax’ usually the position of the maximum value
of Result is interpreted as the class of the feature vector, and the corresponding value as the probability of the
class. In this case, classify_class_mlp should be used instead of evaluate_class_mlp because
classify_class_mlp directly returns the class and corresponding probability.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector.
. Result (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Result of evaluating the feature vector with the MLP.
Result
If the parameters are valid, the operator evaluate_class_mlp returns the value 2 (H_MSG_TRUE). If nec-
essary an exception handling is raised.
Parallelization Information
evaluate_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
train_class_mlp, read_class_mlp
Alternatives
classify_class_mlp
See also
create_class_mlp
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

get_params_class_mlp ( : : MLPHandle : NumInput, NumHidden,


NumOutput, OutputFunction, Preprocessing, NumComponents )

Return the parameters of a multilayer perceptron.


get_params_class_mlp returns the parameters of a multilayer perceptron (MLP) that were specified when
the MLP was created with create_class_mlp. This is particularly useful if the MLP was read from a file with
read_class_mlp. The output of get_params_class_mlp can, for example, be used to check whether the
feature vectors and, if necessary, the target data to be used with the MLP have the correct lengths. For a description
of the parameters, see create_class_mlp.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
. NumInput (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of input variables (features) of the MLP.
. NumHidden (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of hidden units of the MLP.
. NumOutput (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of output variables (classes) of the MLP.
. OutputFunction (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of the activation function in the output layer of the MLP.

HALCON 8.0.2
34 CHAPTER 1. CLASSIFICATION

. Preprocessing (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Type of preprocessing used to transform the feature vectors.
. NumComponents (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Preprocessing parameter: Number of transformed features.
Result
If the parameters are valid, the operator get_params_class_mlp returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
get_params_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
create_class_mlp, read_class_mlp
Possible Successors
add_sample_class_mlp, train_class_mlp
See also
evaluate_class_mlp, classify_class_mlp
Module
Foundation

get_prep_info_class_mlp ( : : MLPHandle,
Preprocessing : InformationCont, CumInformationCont )

Compute the information content of the preprocessed feature vectors of a multilayer perceptron.
get_prep_info_class_mlp computes the information content of the training vectors that have been
transformed with the preprocessing given by Preprocessing. Preprocessing can be set to ’princi-
pal_components’ or ’canonical_variates’. The preprocessing methods are described with create_class_mlp.
The information content is derived from the variations of the transformed components of the feature vector, i.e.,
it is computed solely based on the training data, independent of any error rate on the training data. The informa-
tion content is computed for all relevant components of the transformed feature vectors (NumInput for ’princi-
pal_components’ and min(NumOutput−1, NumInput) for ’canonical_variates’, see create_class_mlp),
and is returned in InformationCont as a number between 0 and 1. To convert the information content into
a percentage, it simply needs to be multiplied by 100. The cumulative information content of the first n compo-
nents is returned in the n-th component of CumInformationCont, i.e., CumInformationCont contains
the sums of the first n elements of InformationCont. To use get_prep_info_class_mlp, a suffi-
cient number of samples must be added to the multilayer perceptron (MLP) given by MLPHandle by using
add_sample_class_mlp or read_samples_class_mlp.
InformationCont and CumInformationCont can be used to decide how many components of the
transformed feature vectors contain relevant information. An often used criterion is to require that the trans-
formed data must represent x% (e.g., 90%) of the data. This can be decided easily from the first value
of CumInformationCont that lies above x%. The number thus obtained can be used as the value for
NumComponents in a new call to create_class_mlp. The call to get_prep_info_class_mlp al-
ready requires the creation of an MLP, and hence the setting of NumComponents in create_class_mlp to
an initial value. However, if get_prep_info_class_mlp is called it is typically not known how many com-
ponents are relevant, and hence how to set NumComponents in this call. Therefore, the following two-step ap-
proach should typically be used to select NumComponents: In a first step, an MLP with the maximum number for
NumComponents is created (NumInput for ’principal_components’ and min(NumOutput − 1, NumInput)
for ’canonical_variates’). Then, the training samples are added to the MLP and are saved in a file using
write_samples_class_mlp. Subsequently, get_prep_info_class_mlp is used to determine the
information content of the components, and with this NumComponents. After this, a new MLP with the de-
sired number of components is created, and the training samples are read with read_samples_class_mlp.
Finally, the MLP is trained with train_class_mlp.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 35

. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Type of preprocessing used to transform the feature vectors.
Default Value : ’principal_components’
List of values : Preprocessing ∈ {’principal_components’, ’canonical_variates’}
. InformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Relative information content of the transformed feature vectors.
. CumInformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Cumulative information content of the transformed feature vectors.
Example

* Create the initial MLP


create_class_mlp (NIn, NHidden, NOut, ’softmax’, ’principal_components’,
NIn, 42, MLPHandle)
* Generate and add the training data
for J := 0 to NData-1 by 1
* Generate training features and classes
* Data = [...]
* Class = [...]
add_sample_class_mlp (MLPHandle, Data, Class)
endfor
write_samples_class_mlp (MLPHandle, ’samples.mtf’)
* Compute the information content of the transformed features
get_prep_info_class_mlp (MLPHandle, ’principal_components’,
InformationCont, CumInformationCont)
* Determine NComp by inspecting InformationCont and CumInformationCont
* NComp = [...]
clear_class_mlp (MLPHandle)
* Create the actual MLP
create_class_mlp (NIn, NHidden, NOut, ’softmax’, ’principal_components’,
NComp, 42, MLPHandle)
* Train the MLP
read_samples_class_mlp (MLPHandle, ’samples.mtf’)
train_class_mlp (MLPHandle, 100, 1, 0.01, Error, ErrorLog)
write_class_mlp (MLPHandle, ’classifier.mlp’)
clear_class_mlp (MLPHandle)

Result
If the parameters are valid, the operator get_prep_info_class_mlp returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
get_prep_info_class_mlp may return the error 9211 (Matrix is not positive definite) if Preprocessing
= ’canonical_variates’ is used. This typically indicates that not enough training samples have been stored for each
class.
Parallelization Information
get_prep_info_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_mlp, read_samples_class_mlp
Possible Successors
clear_class_mlp, create_class_mlp
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

HALCON 8.0.2
36 CHAPTER 1. CLASSIFICATION

get_sample_class_mlp ( : : MLPHandle, IndexSample : Features,


Target )

Return a training sample from the training data of a multilayer perceptron.


get_sample_class_mlp reads out a training sample from the multilayer perceptron (MLP) given by
MLPHandle that was added with add_sample_class_mlp or read_samples_class_mlp. The
index of the sample is specified with IndexSample. The index is counted from 0, i.e., IndexSample
must be a number between 0 and IndexSamples − 1, where IndexSamples can be determined with
get_sample_num_class_mlp. The training sample is returned in Features and Target. Features
is a feature vector of length NumInput, while Target is a target vector of length NumOutput (see
add_sample_class_mlp and create_class_mlp).
get_sample_class_mlp can, for example, be used to reclassify the training data with
classify_class_mlp in order to determine which training samples, if any, are classified incorrectly.
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
. IndexSample (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Number of stored training sample.
. Features (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample.
. Target (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Target vector of the training sample.
Example

* Train an MLP
create_class_mlp (NIn, NHidden, NOut, ’softmax’, ’canonical_variates’,
NComp, 42, MLPHandle)
read_samples_class_mlp (MLPHandle, ’samples.mtf’)
train_class_mlp (MLPHandle, 100, 1, 0.01, Error, ErrorLog)
* Reclassify the training samples
get_sample_num_class_mlp (MLPHandle, NumSamples)
for I := 0 to NumSamples-1 by 1
get_sample_class_mlp (MLPHandle, I, Data, Target)
classify_class_mlp (MLPHandle, Data, 1, Class, Confidence)
Result := gen_tuple_const(NOut,0)
Result[Class] := 1
Diffs := Target-Result
if (sum(fabs(Diffs)) > 0)
* Sample has been classified incorrectly
endif
endfor
clear_class_mlp (MLPHandle)

Result
If the parameters are valid, the operator get_sample_class_mlp returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
get_sample_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_mlp, read_samples_class_mlp, get_sample_num_class_mlp
Possible Successors
classify_class_mlp, evaluate_class_mlp
See also
create_class_mlp
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 37

get_sample_num_class_mlp ( : : MLPHandle : NumSamples )

Return the number of training samples stored in the training data of a multilayer perceptron.
get_sample_num_class_mlp returns in NumSamples the number of training samples that are stored in
the multilayer perceptron (MLP) given by MLPHandle. get_sample_num_class_mlp should be called
before the individual training samples are accessed with get_sample_class_mlp, e.g., for the purpose of
reclassifying the training data (see get_sample_class_mlp).
Parameter
. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
. NumSamples (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of stored training samples.
Result
If MLPHandle is valid, the operator get_sample_num_class_mlp returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
get_sample_num_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_mlp, read_samples_class_mlp
Possible Successors
get_sample_class_mlp
See also
create_class_mlp
Module
Foundation

read_class_mlp ( : : FileName : MLPHandle )

Read a multilayer perceptron from a file.


read_class_mlp reads a multilayer perceptron (MLP) that has been stored with write_class_mlp.
Since the training of an MLP can consume a relatively long time, the MLP is typically trained in an of-
fline process and written to a file with write_class_mlp. In the online process the MLP is read with
read_class_mlp and subsequently used for evaluation with evaluate_class_mlp or for classification
with classify_class_mlp.
Parameter
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
File name.
. MLPHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer
MLP handle.
Result
If the parameters are valid, the operator read_class_mlp returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
read_class_mlp is processed completely exclusively without parallelization.
Possible Successors
classify_class_mlp, evaluate_class_mlp
See also
create_class_mlp, write_class_mlp
Module
Foundation

HALCON 8.0.2
38 CHAPTER 1. CLASSIFICATION

read_samples_class_mlp ( : : MLPHandle, FileName : )

Read the training data of a multilayer perceptron from a file.


read_samples_class_mlp reads training samples from the file given by FileName and adds them to
the training samples that have already been added to the multilayer perceptron (MLP) given by MLPHandle.
The MLP must be created with create_class_mlp before calling read_samples_class_mlp.
As described with train_class_mlp and write_samples_class_mlp, the operators
read_samples_class_mlp, add_sample_class_mlp, and write_samples_class_mlp
can be used to build up a extensive set of training samples, and hence to improve the performance of the MLP by
retraining the MLP with extended data sets.
It should be noted that the training samples must have the correct dimensionality. The feature vectors and tar-
get vectors stored in FileName must have the lengths NumInput and NumOutput that were specified with
create_class_mlp. If this is not the case an error message is returned.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
File name.
Result
If the parameters are valid, the operator read_samples_class_mlp returns the value 2 (H_MSG_TRUE). If
necessary an exception handling is raised.
Parallelization Information
read_samples_class_mlp is processed completely exclusively without parallelization.
Possible Predecessors
create_class_mlp
Possible Successors
train_class_mlp
Alternatives
add_sample_class_mlp
See also
write_samples_class_mlp, clear_samples_class_mlp
Module
Foundation

train_class_mlp ( : : MLPHandle, MaxIterations, WeightTolerance,


ErrorTolerance : Error, ErrorLog )

Train a multilayer perceptron.


train_class_mlp trains the multilayer perceptron (MLP) given in MLPHandle. Before the MLP
can be trained, all training samples to be used for the training must be stored in the MLP using
add_sample_class_mlp or read_samples_class_mlp. If after the training new additional training
samples should be used a new MLP must be created with create_class_mlp, in which again all training sam-
ples to be used (i.e., the original ones and the additional ones) must be stored. In these cases, it is useful to save and
read the training data with write_samples_class_mlp and read_samples_class_mlp, respectively.
A second training with additional training samples is not explicitly forbidden by train_class_mlp. However,
this typically does not lead to good results because the training of an MLP is a complex nonlinear optimization
problem, and consequently the second training with new data will very likely lead to the fact that the optimization
gets stuck in a local minimum.
During the training, the error the MLP achieves on the stored training samples is minimized by using a nonlin-
ear optimization algorithm. With this, the MLP weights described in create_class_mlp are determined.
create_class_mlp initializes the weights with random values to make it very likely that the optimization
converges to the global minimum of the error function. Nevertheless, in rare cases it may happen that the random

HALCON/HDevelop Reference Manual, 2008-5-13


1.3. NEURAL-NETS 39

values determined with RandSeed in create_class_mlp result in a relatively large optimum error, i.e., that
the optimization gets stuck in a local minimum. If it can be conjectured that this has happened the MLP should be
created anew with a different value for RandSeed in order to check whether a significantly smaller error can be
achieved.
The parameters MaxIterations, WeightTolerance, and ErrorTolerance control the nonlinear opti-
mization algorithm. MaxIterations specifies the maximum number of iterations of the optimization algorithm.
In practice, values between 100 and 200 should be sufficient for most problems. WeightTolerance specifies
a threshold for the change of the weights per iteration. Here, the absolute value of the change of the weights
between two iterations is summed. Hence, this value depends on the number of weights as well as the size of
the weights, which in turn depend on the scaling of the training data. Typically, values between 0.00001 and 1
should be used. ErrorTolerance specifies a threshold for the change of the error value per iteration. This
value depends on the number of training samples as well as the number of output variables of the MLP. Also here,
values between 0.00001 and 1 should typically be used. The optimization is terminated if the weight change is
smaller than WeightTolerance and the change of the error value is smaller than ErrorTolerance. In any
case, the optimization is terminated after at most MaxIterations iterations. It should be noted that, depending
on the size of the MLP and the number of training samples, the training can take from a few seconds to several
hours.
On output, train_class_mlp returns the error of the MLP with the optimal weights on the training samples
in Error. Furthermore, ErrorLog contains the error value as a function of the number of iterations. With
this, it is possible to decide whether a second training of the MLP with the same training data without creating
the MLP anew makes sense. If ErrorLog is regarded as a function, it should drop off steeply initially, while
leveling out very flatly at the end. If ErrorLog is still relatively steep at the end, it usually makes sense to call
train_class_mlp again. It should be noted, however, that this mechanism should not be used to train the
MLP successively with MaxIterations = 1 (or other small values for MaxIterations) because this will
substantially increase the number of iterations required to train the MLP.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.
. MaxIterations (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Maximum number of iterations of the optimization algorithm.
Default Value : 200
Suggested values : MaxIterations ∈ {20, 40, 60, 80, 100, 120, 140, 160, 180, 200, 220, 240, 260, 280,
300}
. WeightTolerance (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Threshold for the difference of the weights of the MLP between two iterations of the optimization algorithm.
Default Value : 1.0
Suggested values : WeightTolerance ∈ {1.0, 0.1, 0.01, 0.001, 0.0001, 0.00001}
Restriction : WeightTolerance ≥ 1.0e-8
. ErrorTolerance (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Threshold for the difference of the mean error of the MLP on the training data between two iterations of the
optimization algorithm.
Default Value : 0.01
Suggested values : ErrorTolerance ∈ {1.0, 0.1, 0.01, 0.001, 0.0001, 0.00001}
Restriction : ErrorTolerance ≥ 1.0e-8
. Error (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Mean error of the MLP on the training data.
. ErrorLog (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Mean error of the MLP on the training data as a function of the number of iterations of the optimization
algorithm.
Example

* Train an MLP
create_class_mlp (NIn, NHidden, NOut, ’softmax’, ’normalization’, 1,
42, MLPHandle)
read_samples_class_mlp (MLPHandle, ’samples.mtf’)
train_class_mlp (MLPHandle, 100, 1, 0.01, Error, ErrorLog)

HALCON 8.0.2
40 CHAPTER 1. CLASSIFICATION

write_class_mlp (MLPHandle, ’classifier.mlp’)


clear_class_mlp (MLPHandle)

Result
If the parameters are valid, the operator train_class_mlp returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
train_class_mlp may return the error 9211 (Matrix is not positive definite) if Preprocessing = ’canon-
ical_variates’ is used. This typically indicates that not enough training samples have been stored for each class.
Parallelization Information
train_class_mlp is processed completely exclusively without parallelization.
Possible Predecessors
add_sample_class_mlp, read_samples_class_mlp
Possible Successors
evaluate_class_mlp, classify_class_mlp, write_class_mlp
Alternatives
read_class_mlp
See also
create_class_mlp
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.
Module
Foundation

write_class_mlp ( : : MLPHandle, FileName : )

Write a multilayer perceptron to a file.


write_class_mlp writes the multilayer perceptron (MLP) MLPHandle to the file given by FileName.
write_class_mlp is typically called after the MLP has been trained with train_class_mlp. The MLP
can be read with read_class_mlp. write_class_mlp does not write any training samples that possibly
have been stored in the MLP. For this purpose, write_samples_class_mlp should be used.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid, the operator write_class_mlp returns the value 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
write_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
train_class_mlp
Possible Successors
clear_class_mlp
See also
create_class_mlp, read_class_mlp, write_samples_class_mlp
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 41

write_samples_class_mlp ( : : MLPHandle, FileName : )

Write the training data of a multilayer perceptron to a file.


write_samples_class_mlp writes the training samples stored in the multilayer perceptron (MLP)
MLPHandle to the file given by FileName. write_samples_class_mlp can be used to build up
a database of training samples, and hence to improve the performance of the MLP by training it with an ex-
tended data set (see train_class_mlp). For other possible uses of write_samples_class_mlp see
get_prep_info_class_mlp.
The file FileName is overwritten by write_samples_class_mlp. Nevertheless, extending the database of
training samples is easy to do because read_samples_class_mlp and add_sample_class_mlp add
the training samples to the training samples that are already stored in memory with the MLP.
Parameter

. MLPHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_mlp ; integer


MLP handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid, the operator write_samples_class_mlp returns the value 2 (H_MSG_TRUE).
If necessary an exception handling is raised.
Parallelization Information
write_samples_class_mlp is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_mlp
Possible Successors
clear_samples_class_mlp
See also
create_class_mlp, get_prep_info_class_mlp, read_samples_class_mlp
Module
Foundation

1.4 Support-Vector-Machines

add_sample_class_svm ( : : SVMHandle, Features, Class : )

Add a training sample to the training data of a support vector machine.


add_sample_class_svm adds a training sample to the support vector machine (SVM) given by SVMHandle.
The training sample is given by Features and Class. Features is the feature vector of the sample, and
consequently must be a real vector of length NumFeatures, as specified in create_class_svm. Class
is the target of the sample, which must be in the range of 0 to NumClasses-1 (see create_class_svm).
Before the SVM can be trained with train_class_svm, training samples must be added to the SVM with
add_sample_class_svm. The usage of support vectors of an already trained SVM as training samples is
described in train_class_svm.
The number of currently stored training samples can be queried with get_sample_num_class_svm. Stored
training samples can be read out again with get_sample_class_svm.
Normally, it is useful to save the training samples in a file with write_samples_class_svm to facilitate
reusing the samples and to facilitate that, if necessary, new training samples can be added to the data set, and hence
to facilitate that a newly created SVM can be trained with the extended data set.

HALCON 8.0.2
42 CHAPTER 1. CLASSIFICATION

Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample to be stored.
. Class (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer / real
Class of the training sample to be stored.
Result
If the parameters are valid the operator add_sample_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
add_sample_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
create_class_svm
Possible Successors
train_class_svm, write_samples_class_svm, get_sample_num_class_svm,
get_sample_class_svm
Alternatives
read_samples_class_svm
See also
clear_samples_class_svm, get_support_vector_class_svm
Module
Foundation

classify_class_svm ( : : SVMHandle, Features, Num : Class )

Classify a feature vector by a support vector machine.


classify_class_svm computes the best Num classes of the feature vector Features with the SVM
SVMHandle and returns them in Class. If the classifier was created in the Mode = ’one-versus-one’, the
classes are ordered by the number of votes of the sub-classifiers. If Mode = ’one-versus-all’ was used, the classes
are ordered by the value of each sub-classifier (see create_class_svm for more details). If the classifier was
created in the Mode = ’novelty-detection’, it determines whether the feature vector belongs to the same class as
the training data (Class = 1) or is regarded as outlier (Class = 0). In this case Num must be set to 1 as the
classifier only determines membership.
Before calling classify_class_svm, the SVM must be trained with train_class_svm.
Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. Features (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector.
. Num (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Number of best classes to determine.
Default Value : 1
Suggested values : Num ∈ {1, 2, 3, 4, 5}
. Class (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer
Result of classifying the feature vector with the SVM.
Result
If the parameters are valid the operator classify_class_svm returns the value 2 (H_MSG_TRUE). If nec-
essary, an exception handling is raised.
Parallelization Information
classify_class_svm is reentrant and processed without parallelization.

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 43

Possible Predecessors
train_class_svm, read_class_svm
See also
create_class_svm
References
John Shawe-Taylor, Nello Cristianini: “Kernel Methods for Pattern Analysis”; Cambridge University Press, Cam-
bridge; 2004.
Bernhard Schölkopf, Alexander J.Smola: “Lerning with Kernels”; MIT Press, London; 1999.
Module
Foundation

clear_all_class_svm ( : : : )

Clear all support vector machines.


clear_all_class_svm clears all support vector machines (SVM) and frees all memory required for the
SVMs. After calling clear_all_class_svm, no SVM can be used any longer.
Attention
clear_all_class_svm exists solely for the purpose of implementing the “reset program” functionality in
HDevelop. clear_all_class_svm must not be used in any application.
Result
clear_all_class_svm always returns 2 (H_MSG_TRUE).
Parallelization Information
clear_all_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
classify_class_svm
Alternatives
clear_class_svm
See also
create_class_svm, read_class_svm, write_class_svm, train_class_svm
Module
Foundation

clear_class_svm ( : : SVMHandle : )

Clear a support vector machine.


clear_class_svm clears the support vector machine (SVM) given by SVMHandle and frees all memory
required for the SVM. After calling clear_class_svm, the SVM can no longer be used. The handle
SVMHandle becomes invalid.
Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
Result
If SVMHandle is valid the operator clear_class_svm returns the value 2 (H_MSG_TRUE). If necessary, an
exception handling is raised.
Parallelization Information
clear_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
classify_class_svm

HALCON 8.0.2
44 CHAPTER 1. CLASSIFICATION

See also
create_class_svm, read_class_svm, write_class_svm, train_class_svm
Module
Foundation

clear_samples_class_svm ( : : SVMHandle : )

Clear the training data of a support vector machine.


clear_samples_class_svm clears all training samples that have been added to the support vec-
tor machine (SVM) SVMHandle with add_sample_class_svm or read_samples_class_svm.
clear_samples_class_svm should only be used if the SVM is trained in the same process that uses the
SVM for classification with classify_class_svm. In this case, the memory required for the training sam-
ples can be freed with clear_samples_class_svm, and hence memory can be saved. In the normal usage,
in which the SVM is trained offline and written to a file with write_class_svm, it is typically unnecessary
to call clear_samples_class_svm because write_class_svm does not save the training samples, and
hence the online process, which reads the SVM with read_class_svm, requires no memory for the training
samples.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
Result
If the parameters are valid the operator clear_samples_class_svm returns the value 2 (H_MSG_TRUE).
If necessary, an exception handling is raised.
Parallelization Information
clear_samples_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
train_class_svm, write_samples_class_svm
See also
create_class_svm, clear_class_svm, add_sample_class_svm,
read_samples_class_svm
Module
Foundation

create_class_svm ( : : NumFeatures, KernelType, KernelParam, Nu,


NumClasses, Mode, Preprocessing, NumComponents : SVMHandle )

Create a support vector machine for pattern classification.


create_class_svm creates a support vector machine that can be used for pattern classification. The dimension
of the patterns to be classified is specified in NumFeatures, the number of different classes in NumClasses.
For a binary classification problem in which the classes are linearly separable the SVM algorithm selects data
vectors from the training set that are utilized to construct the optimal separating hyperplane between different
classes. This hyperplane is optimal in the sense that the margin between the convex hulls of the different classes
is maximized. The training patterns that are located at the margin define the hyperplane and are called support
vectors (SV).
Classification of a feature vector z is performed with the following formula:

nsv
!
X
f (z) = sign αi yi < xi , z > +b
i=1

Here, xi are the support vectors, yi encodes their class membership (±1) and αi the weight coefficients. The dis-
tance of the hyperplane to the origin is b. The α and b are determined during training with train_class_svm.

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 45

Note that only a subset of the original training set (nsv : number of support vectors) is necessary for the definition
of the decision boundary and therefore data vectors that are not support vectors are discarded. The classification
speed depends on the evaluation of the dot product between support vectors and the feature vector to be classified,
and hence depends on the length of the feature vector and the number nsv of support vectors.
For classification problems in which the classes are not linearly separable the algorithm is extended in two ways.
First, during training a certain amount of errors (overlaps) is compensated with the use of slack variables. This
means that the α are upper bounded by a regularization constant. To enable an intuitive control of the amount of
training errors, the Nu-SVM version of the training algorithm is used. Here, the regularization parameter Nu is an
asymptotic upper bound on the number of training errors and an asymptotic lower bound on the number of support
vectors. As a rule of thumb, the parameter Nu should be set to the prior expectation of the application’s specific
error ratio, e.g., 0.01 (corresponding to a maximum training error of 1%). Please note that a too big value for Nu
might lead to an infeasible training problem, i.e., the SVM cannot be trained correctly (see train_class_svm
for more details). Since this can only be determined during training, an exception can only be raised there. In this
case, a new SVM with Nu chosen smaller must be created.
Second, because the above SVM exclusively calculates dot products between the feature vectors, it is possible to
incorporate a kernel function into the training and testing algorithm. This means that the dot products are substi-
tuted by a kernel function, which implicitly performs the dot product in a higher dimensional feature space. Given
the appropriate kernel transformation, an originally not linearly separable classification task becomes linearly sep-
arable in the higher dimensional feature space.
Different kernel functions can be selected with the parameter KernelType. For KernelType = ’linear’ the
dot product, as specified in the above formula is calculated. This kernel should solely be used for linearly or nearly
linearly separable classification tasks. The parameter KernelParam is ignored here.
The radial basis function (RBF) KernelType = ’rbf’ is the best choice for a kernel function because it achieves
good results for many classification tasks. It is defined as:

2
= e−γ·
x−z
K(x, z)

Here, the parameter KernelParam is used to select γ. The intuitive meaning of γ is the amount of influence of
a support vector upon its surroundings. A big value of γ (small influence on the surroundings) means that each
training vector becomes a support vector. The training algorithm learns the training data “by heart”, but lacks any
generalization ability (over-fitting). Additionally, the training/classification times grow significantly. A too small
value for γ (big influence on the surroundings) leads to few support vectors defining the separating hyperplane
(under-fitting). One typical strategy is to select a small γ-Nu pair and consecutively increase the values as long as
the recognition rate increases.
With KernelType = ’polynomial_homogeneous’ or ’polynomial_inhomogeneous’, polynomial kernels can be
selected. They are defined in the following way:

K(x, z) = (< x, z >)d


K(x, z) = (< x, z > +1)d

The degree of the polynomial kernel must be set with KernelParam. Please note that a too high degree polyno-
mial (d > 10) might result in numerical problems.
As a rule of thumb, the RBF kernel provides a good choice for most of the classification problems and should
therefore be used in almost all cases. Nevertheless, the linear and polynomial kernels might be better suited
for certain applications and can be tested for comparison. Please note that the novelty-detection Mode and the
reduce_class_svm operator are provided only for the RBF kernel.
Mode specifies the general classification task, which is either how to break down a multi-class decision problem to
binary sub-cases or whether to use a special classifier mode called ’novelty-detection’. Mode = ’one-versus-all’
creates a classifier where each class is compared to the rest of the training data. During testing the class with the
largest output (see the classification formula without sign) is chosen. Mode = ’one-versus-one’ creates a binary
classifier between each single class. During testing a vote is cast and the class with the majority of the votes
is selected. The optimal Mode for multi-class classification depends on the number of classes. Given n classes
’one-versus-all’ creates n classifiers, whereas ’one-versus-one’ creates n(n − 1)/2. Note that for a binary decision
task ’one-versus-one’ would create exactly one, whereas ’one-versus-all’ unnecessarily creates two symmetric

HALCON 8.0.2
46 CHAPTER 1. CLASSIFICATION

classifiers. For few classes (3-10) ’one-versus-one’ is faster for training and testing, because the sub-classifier all
consist of fewer training data and result in overall fewer support vectors. In case of many classes ’one-versus-all’
is preferable, because ’one-versus-one’ generates a prohibitively large amount of sub-classifiers, as their number
grows quadratically with the number of classes.
A special case of classification is Mode = 0 novelty − detection 0 , where the test data is classified with regard to
membership to the training data. The separating hyperplane lies around the training data and thereby implicitly
divides the training data from the rejection class. The advantage is that the rejection class is not defined explicitly,
which is difficult to do in certain applications like texture classification. The resulting support vectors are all lying
at the border. With the parameter Nu, the ratio of outliers in the training data set is specified.
The parameters Preprocessing and NumComponents can be used to specify a preprocessing of the feature
vectors. For Preprocessing = ’none’, the feature vectors are passed unaltered to the SVM. NumComponents
is ignored in this case.
For all other values of Preprocessing, the training data set is used to compute a transformation of the feature
vectors during the training as well as later in the classification.
For Preprocessing = ’normalization’, the feature vectors are normalized. In case of a polynomial kernel, the
minimum and maximum value of the training data set is transformed to -1 and +1. In case of the RBF kernel, the
data is normalized by subtracting the mean of the training vectors and dividing the result by the standard deviation
of the individual components of the training vectors. Hence, the transformed feature vectors have a mean of 0 and
a standard deviation of 1. The normalization does not change the length of the feature vector. NumComponents
is ignored in this case. This transformation can be used if the mean and standard deviation of the feature vectors
differs substantially from 0 and 1, respectively, or for data in which the components of the feature vectors are
measured in different units (e.g., if some of the data are gray value features and some are region features, or if
region features are mixed, e.g., ’circularity’ (unit: scalar) and ’area’ (unit: pixel squared)). The normalization
transformation should be performed in general, because it increases the numerical stability during training/testing.
For Preprocessing = ’principal_components’, a principal component analysis (PCA) is performed. First, the
feature vectors are normalized (see above). Then, an orthogonal transformation (a rotation in the feature space)
that decorrelates the training vectors is computed. After the transformation, the mean of the training vectors is
0 and the covariance matrix of the training vectors is a diagonal matrix. The transformation is chosen such that
the transformed features that contain the most variation is contained in the first components of the transformed
feature vector. With this, it is possible to omit the transformed features in the last components of the feature vector,
which typically are mainly influenced by noise, without losing a large amount of information. The parameter
NumComponents can be used to determine how many of the transformed feature vector components should be
used. Up to NumFeatures components can be selected. The operator get_prep_info_class_svm can
be used to determine how much information each transformed component contains. Hence, it aids the selection of
NumComponents. Like data normalization, this transformation can be used if the mean and standard deviation of
the feature vectors differs substantially from 0 and 1, respectively, or for feature vectors in which the components
of the data are measured in different units. In addition, this transformation is useful if it can be expected that the
features are highly correlated. Please note that the RBF kernel is very robust against the dimensionality reduction
performed by PCA and should therefore be the first choice when speeding up the classification time.
The transformation specified by Preprocessing = ’canonical_variates’ first normalizes the training vectors
and then decorrelates the training vectors on average over all classes. At the same time, the transformation maxi-
mally separates the mean values of the individual classes. As for Preprocessing = ’principal_components’,
the transformed components are sorted by information content, and hence transformed components with little infor-
mation content can be omitted. For canonical variates, up to min(NumClasses−1, NumFeatures) components
can be selected. Also in this case, the information content of the transformed components can be determined with
get_prep_info_class_svm. Like principal component analysis, canonical variates can be used to reduce
the amount of data without losing a large amount of information, while additionally optimizing the separability of
the classes after the data reduction. The computation of the canonical variates is also called linear discriminant
analysis.
For the last two types of transformations (’principal_components’ and ’canonical_variates’), the length of input
data of the SVM is determined by NumComponents, whereas NumFeatures determines the dimensionality of
the input data (i.e., the length of the untransformed feature vector). Hence, by using one of these two transforma-
tions, the size of the SVM with respect to data length is reduced, leading to shorter training/classification times by
the SVM.
After the SVM has been created with create_class_svm, typically training samples are added to the SVM
by repeatedly calling add_sample_class_svm or read_samples_class_svm. After this, the SVM is

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 47

typically trained using train_class_svm. Hereafter, the SVM can be saved using write_class_svm.
Alternatively, the SVM can be used immediately after training to classify data using classify_class_svm.
A comparison of the SVM and the multi-layer perceptron (MLP) (see create_class_mlp) typically shows
that SVMs are generally faster at training, especially for huge training sets, and achieve slightly better recognition
rates than MLPs. The MLP is faster at classification and should therefore be prefered in time critical applications.
Please note that this guideline assumes optimal tuning of the parameters.
Parameter
. NumFeatures (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of input variables (features) of the SVM.
Default Value : 10
Suggested values : NumFeatures ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumFeatures ≥ 1
. KernelType (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
The kernel type.
Default Value : ’rbf’
List of values : KernelType ∈ {’linear’, ’rbf’, ’polynomial_inhomogeneous’, ’polynomial_homogeneous’}
. KernelParam (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Additional parameter for the kernel function. In case of RBF kernel the value for γ. For polynomial kernel the
degree
Default Value : 0.02
Suggested values : KernelParam ∈ {0.01, 0.02, 0.05, 0.1, 0.5}
. Nu (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Regularisation constant of the SVM.
Default Value : 0.05
Suggested values : Nu ∈ {0.0001, 0.001, 0.01, 0.05, 0.1, 0.2, 0.3}
Restriction : (Nu > 0.0) ∧ (Nu < 1.0)
. NumClasses (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of classes.
Default Value : 5
Suggested values : NumClasses ∈ {2, 3, 4, 5, 6, 7, 8, 9, 10}
Restriction : NumClasses ≥ 1
. Mode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
The mode of the SVM.
Default Value : ’one-versus-one’
List of values : Mode ∈ {’novelty-detection’, ’one-versus-all’, ’one-versus-one’}
. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
Default Value : ’normalization’
List of values : Preprocessing ∈ {’none’, ’normalization’, ’principal_components’,
’canonical_variates’}
. NumComponents (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Preprocessing parameter: Number of transformed features (ignored for Preprocessing = ’none’ and
Preprocessing = ’normalization’).
Default Value : 10
Suggested values : NumComponents ∈ {1, 2, 3, 4, 5, 8, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100}
Restriction : NumComponents ≥ 1
. SVMHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
Example

create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,


’one-versus-all’, ’normalization’, NumFeatures,
SVMHandle)
* Generate and add the training data
for J := 0 to NData-1 by 1
* Generate training features and classes

HALCON 8.0.2
48 CHAPTER 1. CLASSIFICATION

* Data = [...]
* Class = ...
add_sample_class_svm (SVMHandle, Data, Class)
endfor
* Train the SVM
train_class_svm (SVMHandle, 0.001, ’default’)
* Use the SVM to classify unknown data
for J := 0 to N-1 by 1
* Extract features
* Features = [...]
classify_class_svm (SVMHandle, Features, 1, Class)
endfor
clear_class_svm (SVMHandle)

Result
If the parameters are valid the operator create_class_svm returns the value 2 (H_MSG_TRUE). If necessary,
an exception handling is raised.
Parallelization Information
create_class_svm is processed completely exclusively without parallelization.
Possible Successors
add_sample_class_svm
Alternatives
create_class_mlp, create_class_gmm, create_class_box
See also
clear_class_svm, train_class_svm, classify_class_svm
References
Bernhard Schölkopf, Alexander J.Smola: “Learning with Kernels”; MIT Press, London; 1999.
John Shawe-Taylor, Nello Cristianini: “Kernel Methods for Pattern Analysis”; Cambridge University Press, Cam-
bridge; 2004.
Module
Foundation

get_params_class_svm ( : : SVMHandle : NumFeatures, KernelType,


KernelParam, Nu, NumClasses, Mode, Preprocessing, NumComponents )

Return the parameters of a support vector machine.


get_params_class_svm returns the parameters of a support vector machine (SVM) that were specified when
the SVM was created with create_class_svm. This is particularly useful if the SVM was read from a file with
read_class_svm. The output of get_params_class_svm can, for example, be used to check whether the
feature vectors and, if necessary, the target data to be used with the SVM have the correct lengths. For a description
of the parameters, see create_class_svm.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. NumFeatures (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of input variables (features) of the SVM.
. KernelType (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
The kernel type.
. KernelParam (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Additional parameter for the kernel.
. Nu (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Regularization constant of the SVM.
. NumClasses (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of classes of the test data.

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 49

. Mode (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


The mode of the SVM.
. Preprocessing (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
. NumComponents (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Preprocessing parameter: Number of transformed features (ignored for Preprocessing = ’none’ and
Preprocessing = ’normalization’).
Result
If the parameters are valid the operator get_params_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
get_params_class_svm is reentrant and processed without parallelization.
Possible Predecessors
create_class_svm, read_class_svm
Possible Successors
add_sample_class_svm, train_class_svm
See also
classify_class_svm
Module
Foundation

get_prep_info_class_svm ( : : SVMHandle,
Preprocessing : InformationCont, CumInformationCont )

Compute the information content of the preprocessed feature vectors of a support vector machine
get_prep_info_class_svm computes the information content of the training vectors that have been
transformed with the preprocessing given by Preprocessing. Preprocessing can be set to ’princi-
pal_components’ or ’canonical_variates’. The preprocessing methods are described with create_class_svm.
The information content is derived from the variations of the transformed components of the feature vec-
tor, i.e., it is computed solely based on the training data, independent of any error rate on the training
data. The information content is computed for all relevant components of the transformed feature vec-
tors (NumFeatures for ’principal_components’ and min(NumClasses − 1, NumFeatures) for ’canoni-
cal_variates’, see create_class_svm), and is returned in InformationCont as a number between 0 and
1. To convert the information content into a percentage, it simply needs to be multiplied by 100. The cumulative
information content of the first n components is returned in the n-th component of CumInformationCont,
i.e., CumInformationCont contains the sums of the first n elements of InformationCont. To use
get_prep_info_class_svm, a sufficient number of samples must be added to the support vector machine
(SVM) given by SVMHandle by using add_sample_class_svm or read_samples_class_svm.
InformationCont and CumInformationCont can be used to decide how many components of the
transformed feature vectors contain relevant information. An often used criterion is to require that the trans-
formed data must represent x% (e.g., 90%) of the data. This can be decided easily from the first value
of CumInformationCont that lies above x%. The number thus obtained can be used as the value for
NumComponents in a new call to create_class_svm. The call to get_prep_info_class_svm al-
ready requires the creation of an SVM, and hence the setting of NumComponents in create_class_svm
to an initial value. However, when get_prep_info_class_svm is called, it is typically not known how
many components are relevant, and hence how to set NumComponents in this call. Therefore, the following two-
step approach should typically be used to select NumComponents: In a first step, an SVM with the maximum
number for NumComponents is created (NumFeatures for ’principal_components’ and min(NumClasses−
1, NumFeatures) for ’canonical_variates’). Then, the training samples are added to the SVM and are saved in
a file using write_samples_class_svm. Subsequently, get_prep_info_class_svm is used to deter-
mine the information content of the components, and with this NumComponents. After this, a new SVM with the
desired number of components is created, and the training samples are read with read_samples_class_svm.
Finally, the SVM is trained with train_class_svm.

HALCON 8.0.2
50 CHAPTER 1. CLASSIFICATION

Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. Preprocessing (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of preprocessing used to transform the feature vectors.
Default Value : ’principal_components’
List of values : Preprocessing ∈ {’principal_components’, ’canonical_variates’}
. InformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Relative information content of the transformed feature vectors.
. CumInformationCont (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Cumulative information content of the transformed feature vectors.
Example

* Create the initial SVM


create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,
’one-versus-all’, ’normalization’, NumFeatures,
SVMHandle)
* Generate and add the training data
for J := 0 to NData-1 by 1
* Generate training features and classes
* Data = [...]
* Class = ...
add_sample_class_svm (SVMHandle, Data, Class)
endfor
write_samples_class_svm (SVMHandle, ’samples.mtf’)
* Compute the information content of the transformed features
get_prep_info_class_svm (SVMHandle, ’principal_components’,
InformationCont, CumInformationCont)
* Determine NComp by inspecting InformationCont and CumInformationCont
* NComp = [...]
clear_class_svm (SVMHandle)
* Create the actual SVM
create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,
’one-versus-all’, ’principal_components’, NComp, SVMHandle)
* Train the SVM
read_samples_class_svm (SVMHandle, ’samples.mtf’)
train_class_svm (SVMHandle, 0.001, ’default’)
write_class_svm (SVMHandle, ’classifier.svm’)
clear_class_svm (SVMHandle)

Result
If the parameters are valid the operator get_prep_info_class_svm returns the value 2 (H_MSG_TRUE).
If necessary, an exception handling is raised.
get_prep_info_class_svm may return the error 9211 (Matrix is not positive definite) if Preprocessing
= ’canonical_variates’ is used. This typically indicates that not enough training samples have been stored for each
class.
Parallelization Information
get_prep_info_class_svm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_svm, read_samples_class_svm
Possible Successors
clear_class_svm, create_class_svm
References
Christopher M. Bishop: “Neural Networks for Pattern Recognition”; Oxford University Press, Oxford; 1995.
Andrew Webb: “Statistical Pattern Recognition”; Arnold, London; 1999.

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 51

Module
Foundation

get_sample_class_svm ( : : SVMHandle, IndexSample : Features,


Target )

Return a training sample from the training data of a support vector machine.
get_sample_class_svm reads out a training sample from the support vector machine (SVM) given by
SVMHandle that was added with add_sample_class_svm or read_samples_class_svm. The
index of the sample is specified with IndexSample. The index is counted from 0, i.e., IndexSample
must be a number between 0 and IndexSamples − 1, where IndexSamples can be determined with
get_sample_num_class_svm. The training sample is returned in Features and Target. Features
is a feature vector of length NumFeatures (see create_class_svm), while Target is the index of the
class, ranging between 0 and NumClasses-1 (see add_sample_class_svm).
get_sample_class_svm can, for example, be used to reclassify the training data with
classify_class_svm in order to determine which training samples, if any, are classified incorrectly.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. IndexSample (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Number of the stored training sample.
. Features (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Feature vector of the training sample.
. Target (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Target vector of the training sample.
Example

* Train an SVM
create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,
’one-versus-all’, ’normalization’, NumFeatures,
SVMHandle)
read_samples_class_svm (SVMHandle, ’samples.mtf’)
train_class_svm (SVMHandle, 0.001, ’default’)
* Reclassify the training samples
get_sample_num_class_svm (SVMHandle, NumSamples)
for I := 0 to NumSamples-1 by 1
get_sample_class_svm (SVMHandle, I, Data, Target)
classify_class_svm (SVMHandle, Data, 1, Class)
if (Class # Target)
* Sample has been classified incorrectly
endif
endfor
clear_class_svm (SVMHandle)

Result
If the parameters are valid the operator get_sample_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
get_sample_class_svm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_svm, read_samples_class_svm, get_sample_num_class_svm,
get_support_vector_class_svm
Possible Successors
classify_class_svm

HALCON 8.0.2
52 CHAPTER 1. CLASSIFICATION

See also
create_class_svm
Module
Foundation

get_sample_num_class_svm ( : : SVMHandle : NumSamples )

Return the number of training samples stored in the training data of a support vector machine.
get_sample_num_class_svm returns in NumSamples the number of training samples that are stored in
the support vector machine (SVM) given by SVMHandle. get_sample_num_class_svm should be called
before the individual training samples are accessed with get_sample_class_svm, e.g., for the purpose of
reclassifying the training data (see get_sample_class_svm).
Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. NumSamples (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of stored training samples.
Result
If SVMHandle is valid the operator get_sample_num_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
get_sample_num_class_svm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_svm, read_samples_class_svm
Possible Successors
get_sample_class_svm
See also
create_class_svm
Module
Foundation

get_support_vector_class_svm ( : : SVMHandle,
IndexSupportVector : Index )

Return the index of a support vector from a trained support vector machine.
The operator get_support_vector_class_svm maps support vectors of a trained SVM (given
in SVMHandle) to the original training data set. The index of the SV is specified with
IndexSupportVector. The index is counted from 0, i.e., IndexSupportVector must be a number
between 0 and IndexSupportVectors − 1, where IndexSupportVectors can be determined with
get_support_vector_num_class_svm. The index of this SV in the training data is returned in Index.
This Index can be used for a query with get_sample_class_svm to obtain the feature vectors that become
support vectors. get_sample_class_svm can, for example, be used to visualize the support vectors.
Note that when using train_class_svm with a mode different from ’default’ or reducing the SVM with
reduce_class_svm, the returned Index will always be -1, i.e., it will be invalid. The reason for this is that a
consistent mapping between SV and training data becomes impossible.
Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. IndexSupportVector (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Number of stored support vectors.

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 53

. Index (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real


Index of the support vector in the training set.
Result
If the parameters are valid the operator get_sample_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
get_support_vector_class_svm is reentrant and processed without parallelization.
Possible Predecessors
train_class_svm, get_support_vector_num_class_svm
Possible Successors
get_sample_class_svm
See also
create_class_svm
Module
Foundation

get_support_vector_num_class_svm
( : : SVMHandle : NumSupportVectors, NumSVPerSVM )

Return the number of support vectors of a support vector machine.


get_support_vector_num_class_svm returns in NumSupportVectors the number of
support vectors that are stored in the support vector machine (SVM) given by SVMHandle.
get_support_vector_num_class_svm should be called before the labels of individual support
vectors are read out with get_support_vector_class_svm, e.g., for visualizing which the training data
become a SV (see get_support_vector_class_svm). The number of SVs in each classifier is listed
in NumSVPerSVM. The reason that its sum differs from the Number obtained in NumSupportVectors is
that SV evaluations are reused throughout different sub-classifiers. NumSVPerSVM provides the possibility for
controlling the process of speeding up SVM classification time with the operator reduce_class_svm.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. NumSupportVectors (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Total number of support vectors.
. NumSVPerSVM (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer-array ; integer
Number of SV of each sub-SVM.
Result
If SVMHandle is valid the operator get_sample_num_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
get_support_vector_num_class_svm is reentrant and processed without parallelization.
Possible Predecessors
train_class_svm
Possible Successors
get_sample_class_svm
See also
create_class_svm
Module
Foundation

read_class_svm ( : : FileName : SVMHandle )

Read a support vector machine from a file.

HALCON 8.0.2
54 CHAPTER 1. CLASSIFICATION

read_class_svm reads a support vector machine (SVM) that has been stored with write_class_svm.
Since the training of an SVM can consume a relatively long time, the SVM is typically trained in an offline process
and written to a file with write_class_svm. In the online process the SVM is read with read_class_svm
and subsequently used for classification with classify_class_svm.
Parameter

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string


File name.
. SVMHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
Result
If the parameters are valid the operator read_class_svm returns the value 2 (H_MSG_TRUE). If necessary,
an exception handling is raised.
Parallelization Information
read_class_svm is processed completely exclusively without parallelization.
Possible Successors
classify_class_svm
See also
create_class_svm, write_class_svm
Module
Foundation

read_samples_class_svm ( : : SVMHandle, FileName : )

Read the training data of a support vector machine from a file.


read_samples_class_svm reads training samples from the file given by FileName and adds them to
the training samples that have already been added to the support vector machine (SVM) given by SVMHandle.
The SVM must be created with create_class_svm before calling read_samples_class_svm.
As described with train_class_svm and write_samples_class_svm, the operators
read_samples_class_svm, add_sample_class_svm, and write_samples_class_svm
can be used to build up a extensive set of training samples, and hence to improve the performance of the SVM by
retraining the SVM with extended data sets.
It should be noted that the training samples must have the correct dimensionality. The feature vectors and tar-
get vectors stored in FileName must have the lengths NumFeatures and NumClasses that were specified
with create_class_svm. The target is stored in vector form for compability reason with the MLP (see
read_samples_class_mlp). If the dimensions are incorrect an error message is returned.
Parameter

. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer


SVM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
File name.
Result
If the parameters are valid the operator read_samples_class_svm returns the value 2 (H_MSG_TRUE). If
necessary, an exception handling is raised.
Parallelization Information
read_samples_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
create_class_svm
Possible Successors
train_class_svm
Alternatives
add_sample_class_svm

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 55

See also
write_samples_class_svm, clear_samples_class_svm
Module
Foundation

reduce_class_svm ( : : SVMHandle, Method, MinRemainingSV,


MaxError : SVMHandleReduced )

Approximate a trained support vector machine by a reduced support vector machine for faster classification.
As described in create_class_svm, the classification time of a SVM depends on the number of kernel
evaluations between the support vectors and the feature vectors. While the length of the data vectors can be
reduced in a preprocessing step like ’pricipal_components’ or ’canonical_variates’ (see create_class_svm
for details), the number of resulting SV depends on the complexity of the classification problem. The number
of SVs is determined during training. To further reduce classification time, the number of SVs can be reduced
by approximating the original separating hyperplane with fewer SVs than originally required. For this purpose, a
copy of the original SVM provided by SVMHandle is created and returned in SVMHandleReduced. This new
SVM has the same parametrization as the original SVM, but a different SV expansion. The training samples that
are included in SVMHandle are not copied. The original SVM is not modified by reduce_class_svm.
The reduction method is selected with Method. Currently, only a bottom up approch is supported, which itera-
tively merges SVs. The algorithm stops if either the minimum number of SVs is reached (MinRemainingSV)
or if the accumulated maximum error exceeds the threshold MaxError. Note that the approximation reduces the
complexity of the hyperplane and thereby leads to a deteriorated classification rate. A common approch is therefore
to start from a small MaxError e.g., 0.001, and to increase its value step by step. To control the reduction ratio,
at each step the number of remaining SVs is determined with get_support_vector_num_class_svm and
the classification rate is checked on a separate test data set with classify_class_svm.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
Original SVM handle.
. Method (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Type of postprocessing to reduce number of SV.
Default Value : ’bottom_up’
List of values : Method ∈ {’bottom_up’}
. MinRemainingSV (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Minimum number of remaining SVs.
Default Value : 2
Suggested values : MinRemainingSV ∈ {2, 3, 4, 5, 7, 10, 15, 20, 30, 50}
Restriction : MinRemainingSV ≥ 2
. MaxError (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Maximum allowed error of reduction.
Default Value : 0.001
Suggested values : MaxError ∈ {0.0001, 0.0002, 0.0005, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05}
Restriction : MaxError > 0.0
. SVMHandleReduced (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVMHandle of reduced SVM.
Example

* Train an SVM
create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,
’one-versus-all’, ’normalization’, NumFeatures,
SVMHandle)
read_samples_class_svm (SVMHandle, ’samples.mtf’)
train_class_svm (SVMHandle, 0.001, ’default’)
* Create a reduced SVM
reduce_class_svm (SVMHandle, ’bottom_up’, 2, 0.01, SVMHandleReduced)
write_class_svm (SVMHandleReduced, ’classifier.svm)

HALCON 8.0.2
56 CHAPTER 1. CLASSIFICATION

clear_class_svm (SVMHandleReduced)
clear_class_svm (SVMHandle)

Result
If the parameters are valid the operator train_class_svm returns the value 2 (H_MSG_TRUE). If necessary,
an exception handling is raised.
Parallelization Information
reduce_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
train_class_svm, get_support_vector_num_class_svm
Possible Successors
classify_class_svm, write_class_svm, get_support_vector_num_class_svm
See also
train_class_svm
Module
Foundation

train_class_svm ( : : SVMHandle, Epsilon, TrainMode : )

Train a support vector machine.


train_class_svm trains the support vector machine (SVM) given in SVMHandle. Before the SVM
can be trained, the training samples to be used for the training must be added to the SVM using
add_sample_class_svm or read_samples_class_svm.
Technically, training an SVM means solving a convex quadratic optimization problem. This implies that it can
be assured that training terminates after finite steps at the global optimum. In order to recognize termination,
the gradient of the function that is optimized intenally must fall below a threshold, which is set in Epsilon.
By default, a value of 0.001 should be used for Epsilon since this yields the best results in practice. A too
big value leads to a too early termination and might result in suboptimal solutions. With a too small value the
optimization requires a longer time, often without changing the recognition rate significantly. Nevertheless, if
longer training times are possible, a smaller value than 0.001 might be chosen. There are two common reasons
for changing Epsilon: First, if you specified a very small value for Nu when calling ( create_class_svm),
e.g., Nu = 0.001, a smaller Epsilon might significantly improve the recognition rate. A second case is the
determination of the optimal kernel function and its parameterization (e.g., the KernelParam-Nu pair for the
RBF kernel) with the computationally intensive n-fold cross validation. Here, choosing a bigger Epsilon reduces
the computational time without changing the parameters of the optimal kernel that would be obtained when using
the default Epsilon. After the optimal KernelParam-Nu pair is obtained, the final training is conducted with
a small Epsilon.
The duration of the training depends on the training data, in particular on the number of resulting support vectors
(SVs), and Epsilon. It can lie between seconds and several hours. It is therefore recommended to choose the
SVM parameter Nu in create_class_svm so that as few SVs as possible are generated without decreasing
the recognition rate. Special care must be taken with the parameter Nu in create_class_svm so that the
optimization starts from a feasible region. If too many training errors are chosen with a too big Nu, an exception
handling is raised. In this case, an SVM with the same training data, but with smaller Nu must be trained.
With the parameter TrainMode you can choose between different training modes. Normally, you train an SVM
without additional information and TrainMode is set to ’default’. If multiple SVMs for the same data set but with
different kernels are trained, subsequent training runs can reuse optimization results and thus speedup the overall
training time of all runs. For this mode, in TrainMode a SVM handle of a previously trained SVM is passed.
Note that the SVM handle passed in SVMHandle and the SVMHandle passed in TrainMode must have the
same training data, the same mode and the same number of classes (see create_class_svm). The application
for this training mode is the evaluation of different kernel functions given the same training set. In the literature
this is referred to as alpha seeding.
With TrainMode = ’add_sv_to_train_set’ it is possible to append the support vectors that were generated by a
previous call of train_class_svm to the currently saved training set. This mode has two typical application
areas: First, it is possible to gradually train a SVM. For this, the complete training set is divided into disjunctive

HALCON/HDevelop Reference Manual, 2008-5-13


1.4. SUPPORT-VECTOR-MACHINES 57

chunks. The first chunk is trained normally using TrainMode = ’default’. Afterwards, the previous training set is
removed with clear_samples_class_svm, the next chunk is added with add_sample_class_svm and
trained with TrainMode = ’add_sv_to_train_set’. This is repeated until all chunks are trained. This approach has
the advantage that even huge training data sets can be trained efficiently with respect to memory consumption. A
second application area for this mode is that a general purpose classifier can be specialized by adding characteristic
training samples and then retraining it. Please note that the preprocessing (as described in create_class_svm)
is not changed when training with TrainMode = ’add_sv_to_train_set’.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. Epsilon (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Stop parameter for training.
Default Value : 0.001
Suggested values : Epsilon ∈ {0.00001, 0.0001, 0.001, 0.01, 0.1}
. TrainMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; string / integer
Mode of training. For normal operation: ’default’. If SVs already included in the SVM should be used for
training: ’add_sv_to_train_set’. For alpha seeding: the respective SVM handle.
Default Value : ’default’
List of values : TrainMode ∈ {’default’, ’add_sv_to_train_set’}
Example

* Train an SVM
create_class_svm (NumFeatures, ’rbf’, 0.01, 0.01, NumClasses,
’one-versus-all’, ’normalization’, NumFeatures,
SVMHandle)
read_samples_class_svm (SVMHandle, ’samples.mtf’)
train_class_svm (SVMHandle, 0.001, ’default’)
write_class_svm (SVMHandle, ’classifier.svm)
clear_class_svm (SVMHandle)

Result
If the parameters are valid the operator train_class_svm returns the value 2 (H_MSG_TRUE). If necessary,
an exception handling is raised.
Parallelization Information
train_class_svm is processed completely exclusively without parallelization.
Possible Predecessors
add_sample_class_svm, read_samples_class_svm
Possible Successors
classify_class_svm, write_class_svm
Alternatives
read_class_svm
See also
create_class_svm
References
John Shawe-Taylor, Nello Cristianini: “Kernel Methods for Pattern Analysis”; Cambridge University Press, Cam-
bridge; 2004.
Bernhard Schölkopf, Alexander J.Smola: “Lerning with Kernels”; MIT Press, London; 1999.
Module
Foundation

write_class_svm ( : : SVMHandle, FileName : )

Write a support vector machine to a file.

HALCON 8.0.2
58 CHAPTER 1. CLASSIFICATION

write_class_svm writes the support vector machine (SVM) SVMHandle to the file given by FileName.
write_class_svm is typically called after the SVM has been trained with train_class_svm. The SVM
can be read with read_class_svm. write_class_svm does not write any training samples that possibly
have been stored in the SVM. For this purpose, write_samples_class_svm should be used.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid the operator write_class_svm returns the value 2 (H_MSG_TRUE). If necessary,
an exception handling is raised.
Parallelization Information
write_class_svm is reentrant and processed without parallelization.
Possible Predecessors
train_class_svm
Possible Successors
clear_class_svm
See also
create_class_svm, read_class_svm, write_samples_class_svm
Module
Foundation

write_samples_class_svm ( : : SVMHandle, FileName : )

Write the training data of a support vector machine to a file.


write_samples_class_svm writes the training samples currently stored in the support vector machine
(SVM) SVMHandle to the file given by FileName. write_samples_class_svm can be used to build up
a database of training samples, and hence to improve the performance of the SVM by training it with an extended
data set (see train_class_svm). The file FileName is overwritten by write_samples_class_svm.
Nevertheless, extending the database of training samples is easy to do because read_samples_class_svm
and add_sample_class_svm add the training samples to the training samples that are already stored in mem-
ory with the SVM.
Parameter
. SVMHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . class_svm ; integer
SVM handle.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
File name.
Result
If the parameters are valid the operator write_samples_class_svm returns the value 2 (H_MSG_TRUE).
If necessary, an exception handling is raised.
Parallelization Information
write_samples_class_svm is reentrant and processed without parallelization.
Possible Predecessors
add_sample_class_svm
Possible Successors
clear_samples_class_svm
See also
create_class_svm, get_prep_info_class_svm, read_samples_class_svm
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


Chapter 2

Control

assign ( : : Input : Result )

Assign a new value to a control variable.


assign assigns a new value to a variable. In HDevelop an assignment is treated like an operator. To use an
assignment you have to select the operator assign(Input,Result). This operator has the following seman-
tics: It evaluates Input (right side of assignment) and stores it in Result (left side of assignment). However, in
the program text the assignment is represented by the usual syntax of the assignment operator: ’:=’. The following
example outlines the difference between an assignment in C syntax and its transformed version in HDevelop:
The assignment in C syntax

u = sin(x) + cos(y);

is defined in HDevelop using the assignment operator as

assign(sin(x) + cos(y), u)

which is displayed in the program window as:

u := sin(x) + cos(y)

Parameter
. Input (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real / integer / string
New value.
Default Value : 1
. Result (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real / integer / string
Variable that has to be changed.
Example

Tuple1 := [1,0,3,4,5,6,7,8,9]
Val := sin(1.2) + cos(1.2)
Tuple1[1] := 2
Tuple2 := []
for i := 0 to 10 by 1
Tuple2[i] := i
endfor

Result
assign returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error.
Parallelization Information
assign is reentrant, local, and processed without parallelization.

59
60 CHAPTER 2. CONTROL

Alternatives
insert
Module
Foundation

break ( : : : )

Terminate loop execution.


break terminates the smallest enclosing for, while or repeat.. until loop. Program execution is
continued at the next program line after the end of the loop or at the next line after the break statement in case
no enclosing loop exists.
Example

read_image (Image, ’monkey’)


threshold (Image, Region, 160, 180)
connection (Region, Regions)
Number := |Regions|
AllRegionsValid := 1
* check if for all regions area <=30
for i := 1 to Number by 1
ObjectSelected := Regions[i]
area_center (ObjectSelected, Area, Row, Column)
if (Area > 30)
AllRegionsValid := 0
break ()
endif
endfor

Result
break always returns 2 (H_MSG_TRUE)
Parallelization Information
break is reentrant, local, and processed without parallelization.
Alternatives
continue
See also
for, while, repeat, until
Module
Foundation

comment ( : : Comment : )

Add a comment of one line to the program.


comment allows to add a comment of one line to the program. As parameter value, i.e., as comment, all characters
are allowed. If there are newlines in this line, more comments are inserted. This operator has no effect on the
program execution.
Parameter

. Comment (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Arbitrary sequence of characters.
Example

HALCON/HDevelop Reference Manual, 2008-5-13


61

* This is a program with comments


* ’this is a string as comment’
* here are numbers: 4711, 0.815
stop ()

Result
comment always returns 2 (H_MSG_TRUE).
Parallelization Information
comment is reentrant, local, and processed without parallelization.
Module
Foundation

continue ( : : : )

Skip the current loop execution.


continue skips the smallest enclosing for, while or repeat.. until loop execution. Program execution
is continued at the condition line of the loop or at the next line after the continue statement in case no enclosing
loop exists.
Result
continue always returns 2 (H_MSG_TRUE)
Parallelization Information
continue is reentrant, local, and processed without parallelization.
Alternatives
break
See also
for, while, repeat, until
Module
Foundation

else ( : : : )

Alternative of conditional statement.


else is the alternative of a conditional statement. If the condition is false (i.e., 0) the part between else and
endif is executed.
Result
if returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. else and endif (as operators)
always return 2 (H_MSG_TRUE)
Parallelization Information
else is reentrant, local, and processed without parallelization.
Alternatives
if, elseif
See also
until, for, while
Module
Foundation

elseif ( : : Condition : )

Conditional statement with alternative.

HALCON 8.0.2
62 CHAPTER 2. CONTROL

elseif is a conditional statement with an alternative. If the condition is true (i.e., not 0), all expressions and calls
between the head and the operator else or the next elseif are performed. If the condition is false (i.e., 0) the
part between else and endif is executed.
Parameter
. Condition (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Condition for the if statement.
Default Value : 1
Result
elseif returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. else and endif (as
operators) always return 2 (H_MSG_TRUE)
Parallelization Information
elseif is reentrant, local, and processed without parallelization.
Alternatives
if
See also
else, elseif, for, while, until
Module
Foundation

endfor ( : : : )

End of for loop.


endfor is the last line of a for loop.
Result
endfor always returns 2 (H_MSG_TRUE)
Parallelization Information
endfor is reentrant, local, and processed without parallelization.
See also
for
Module
Foundation

endif ( : : : )

End of if command.
endif is the last line of a if, elseif and else command.
Result
endif always returns 2 (H_MSG_TRUE)
Parallelization Information
endif is reentrant, local, and processed without parallelization.
See also
if
Module
Foundation

endwhile ( : : : )

End of while loop.

HALCON/HDevelop Reference Manual, 2008-5-13


63

endwhile is the last line of a while loop.


Result
endwhile always returns 2 (H_MSG_TRUE)
Parallelization Information
endwhile is reentrant, local, and processed without parallelization.
See also
while
Module
Foundation

exit ( : : : )

Terminate HDevelop.
exit terminates HDevelop. The operator is aquivalent to the menu File . Quit. Internally and for exported
C++ code the C-function call exit(0) is used.
Example

read_image (Image, ’fabrik’)


intensity (Image, Image, Mean, Deviation)
open_file (’intensity.txt’, ’output’, FileHandle)
fwrite_string (FileHandle, Mean + ’ ’ + Deviation)
close_file (FileHandle)
exit ()

Result
exit returns 0 (o.k.) to the calling environment of HDevelop = operating system.
Parallelization Information
exit is reentrant, local, and processed without parallelization.
See also
stop
Module
Foundation

for ( : : Start, End, Step : Variable )

Execute the body for a fixed number.


The for loop is controlled by a start and termination value and an incrementation value that determines the
number of loop steps. These values may also be expressions which are evaluated immediately before the loop is
entered. The expressions may be of type integer or of type real. If all input values are of type integer
the loop variable will also be of type integer. In all other cases the loop variable will be of type real. If the
start value is less or equal to the termination value, the loop index is assigned with the starting value and the body
of the loop is entered. If the increment is less than zero the loop is entered if the start value is larger or equal to
the end value. Each time the body is executed, the loop index is incremented by the incrementation value. If the
loop index is equal to the termination value, the body of the loop is performed for the last time. If the loop index
is larger than the termination value the body will not be excecuted any longer. For negative increment values the
loop is terminated if the loop index is less than the termination value.
Please note that it is not necessary, that the loop index has to be equal to the termination value before terminating
the loop. Please note, that the expressions for start and termination value are evaluated only once when entering
the loop. A modification of a variable that appears within these expressions has no influence on the termination of
the loop. The same applies to the modifications of the loop index. It also has no influence on the termination. The
loop value is assigned to the correct value each time the for operator is executed.

HALCON 8.0.2
64 CHAPTER 2. CONTROL

If the for loop is left too early (e.g., if you press Stop and set the PC) and the loop is entered again, the
expressions will be evaluated, as if the loop were entered for the first time.
Parameter

. Start (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer / real


Start value for the loop variable.
Default Value : 1
. End (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer / real
End value for the loop variable.
Default Value : 5
. Step (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer / real
Increment value for the loop variable.
Default Value : 1
. Variable (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; integer / real
Loop variable.
Example

dev_update_window (’off’)
dev_close_window ()
dev_open_window (0, 0, 728, 512, ’black’, WindowID)
read_image (Bond, ’die3’)
dev_display (Bond)
stop ()
threshold (Bond, Bright, 100, 255)
shape_trans (Bright, Die, ’rectangle2’)
dev_set_color (’green’)
dev_set_line_width (3)
dev_set_draw (’margin’)
dev_display (Die)
stop ()
reduce_domain (Bond, Die, DieGrey)
threshold (DieGrey, Wires, 0, 50)
fill_up_shape (Wires, WiresFilled, ’area’, 1, 100)
dev_display (Bond)
dev_set_draw (’fill’)
dev_set_color (’red’)
dev_display (WiresFilled)
stop ()
opening_circle (WiresFilled, Balls, 15.5)
dev_set_color (’green’)
dev_display (Balls)
stop ()
connection (Balls, SingleBalls)
select_shape (SingleBalls, IntermediateBalls, ’circularity’, ’and’, 0.85, 1.0)
sort_region (IntermediateBalls, FinalBalls, ’first_point’, ’true’, ’column’)
dev_display (Bond)
dev_set_colored (12)
dev_display (FinalBalls)
stop ()
smallest_circle (FinalBalls, Row, Column, Radius)
NumBalls := |Radius|
Diameter := 2*Radius
meanDiameter := sum(Diameter)/NumBalls
mimDiameter := min(Diameter)
dev_display (Bond)
disp_circle (WindowID, Row, Column, Radius)
dev_set_color (’white’)
set_font (WindowID, ’system26’)

HALCON/HDevelop Reference Manual, 2008-5-13


65

for i := 1 to NumBalls by 1
if (fmod(i,2)=1)
set_tposition (WindowID, Row[i-1]-1.5*Radius[i-1], Column[i-1]-60)
else
set_tposition (WindowID, Row[i-1]+2.5*Radius[i-1], Column[i-1]-60)
endif
write_string (WindowID, ’Diam: ’+Diameter[i-1])
endfor
dev_set_color (’green’)
dev_update_window (’on’)

Result
for returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. endfor (as operator) always
returns 2 (H_MSG_TRUE)
Parallelization Information
for is reentrant, local, and processed without parallelization.
Alternatives
while, until
See also
repeat, break, continue, if, elseif, else
Module
Foundation

if ( : : Condition : )

Conditional statement.
if is a conditional statement. The condition contains a boolean expression. If the condition is true, the body is
executed. Otherwise the execution is continued at the first expression or operator call that follows the corresponding
elseif, else or endif.
Parameter

. Condition (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer


Condition for the if statement.
Default Value : 1
Result
if returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. endif (as operators) always
returns 2 (H_MSG_TRUE)
Parallelization Information
if is reentrant, local, and processed without parallelization.
Alternatives
elseif, else
See also
for, while, until
Module
Foundation

ifelse ( : : Condition : )

Conditional statement with alternative.


ifelse is obsolete and is only provided for reasons of backward compatibility.

HALCON 8.0.2
66 CHAPTER 2. CONTROL

ifelse is a conditional statement with an alternative. If the condition is true (i.e., not 0), all expressions and calls
between the head and operator else are performed. If the condition is false (i.e., 0) the part between else and
endif is executed. Note that the operator is called ifelse and it is displayed as if in the program text area.
Parameter

. Condition (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer


Condition for the if statement.
Default Value : 1
Result
ifelse returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. else and endif (as
operators) always return 2 (H_MSG_TRUE)
Parallelization Information
ifelse is reentrant, local, and processed without parallelization.
Alternatives
if
See also
else, elseif, for, while, repeat, until
Module
Foundation

insert ( : : Input, Value, Index : Result )

Assignment of a value into a tuple.


insert assigns a single value into an tuple. If the first input parameter and the first output parameter are identical,
the call:

insert (Areas, Area, Radius-1, Areas)

is not presented in the program text as an operator call, but in the more intuitive form as:

Areas[Radius-1] := Area

.
Parameter

. Input (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real / integer / string


Tuple, where the new value has to be inserted.
Default Value : []
. Value (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real / integer / string
Value that has to be inserted.
Default Value : 1
Typical range of values : 0 ≤ Value ≤ 1000000
. Index (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Index position for new value.
Default Value : 0
Suggested values : Index ∈ {0, 1, 2, 3, 4, 5, 6}
Minimum Increment : 1
. Result (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real / integer / string
Result tuple with inserted values.
Result
insert returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error.
Parallelization Information
insert is reentrant, local, and processed without parallelization.

HALCON/HDevelop Reference Manual, 2008-5-13


67

Alternatives
assign
Module
Foundation

repeat ( : : : )

Start of repeat..until loop.


repeat is the first line of an until loop.
Result
repeat always returns 2 (H_MSG_TRUE)
Parallelization Information
repeat is reentrant, local, and processed without parallelization.
Alternatives
for, while
See also
until, break, continue
Module
Foundation

return ( : : : )

Terminate procedure call.


return terminates the current procedure call and returns to the calling procedure. Program execution is continued
at the next active program line after the procedure call in the calling procedure. If the current procedure is the main
procedure, program execution is finished and the program counter jumps to the end of the program. Note that every
procedure except the main procedure has to contain at least one reachable return operator line in order to be
able to return from a call to the procedure.
Result
return always returns 2 (H_MSG_TRUE)
Parallelization Information
return is reentrant, local, and processed without parallelization.
Module
Foundation

stop ( : : : )

Stop program execution.


stop stops the program execution of HDevelop. The PC is then placed at the program line behind stop. The
operator is equivalent the pressing the stop button in the menu bar.
Attention
stop is not available in C++.
Example

read_image (Image, ’fabrik’)


regiongrowing (Image, Regions, 3, 3, 6, 100)
Number := |Regions|
dev_update_window (’off’)

HALCON 8.0.2
68 CHAPTER 2. CONTROL

for i := 1 to Number by 1
RegionSelected := Regions[i]
dev_clear_window ()
dev_display (RegionSelected)
stop ()
endfor

Result
stop always returns 2 (H_MSG_TRUE)
Parallelization Information
stop is reentrant, local, and processed without parallelization.
See also
exit
Module
Foundation

until ( : : Condition : )

Continue to execute the body as long as the condition is not true.


until executes the body as long as the condition is not true. The until loop has a boolean expression as the
conditional part. As long as it is false (i.e., equal 0), the body of the loop is performed. There is at least one
execution of the body, because the condition will be checked at the end of the body.
Parameter
. Condition (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Condition for loop.
Result
until returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. repeat (as operator)
always returns 2 (H_MSG_TRUE)
Parallelization Information
until is reentrant, local, and processed without parallelization.
Alternatives
for, while
See also
repeat, if, elseif, else, break, continue
Module
Foundation

while ( : : Condition : )

Continue to execute the body as long as the condition is true.


while executes the body as long as the condition is true. The while loop has a boolean expression as the
conditional part. As long as it is true (i.e., not equal 0), the body of the loop is performed. In order to enter the
loop, the condition has to be true in the first place.
Parameter
. Condition (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Condition for loop.
Example

dev_update_window (’off’)

HALCON/HDevelop Reference Manual, 2008-5-13


69

dev_close_window ()
dev_open_window (0, 0, 512, 512, ’black’, WindowID)
read_image (Image, ’particle’)
dev_display (Image)
stop ()
threshold (Image, Large, 110, 255)
dilation_circle (Large, LargeDilation, 7.5)
dev_display (Image)
dev_set_draw (’margin’)
dev_set_line_width (3)
dev_set_color (’green’)
dev_display (LargeDilation)
dev_set_draw (’fill’)
stop ()
complement (LargeDilation, NotLarge)
reduce_domain (Image, NotLarge, ParticlesRed)
mean_image (ParticlesRed, Mean, 31, 31)
dyn_threshold (ParticlesRed, Mean, SmallRaw, 3, ’light’)
opening_circle (SmallRaw, Small, 2.5)
connection (Small, SmallConnection)
dev_display (Image)
dev_set_colored (12)
dev_display (SmallConnection)
stop ()
dev_set_color (’green’)
dev_display (Image)
dev_display (SmallConnection)
Button := 1
while (Button = 1)
dev_set_color (’green’)
get_mbutton (WindowID, Row, Column, Button)
dev_display (Image)
dev_display (SmallConnection)
dev_set_color (’red’)
select_region_point (SmallConnection, SmallSingle, Row, Column)
dev_display (SmallSingle)
NumSingle := |SmallSingle|
if (NumSingle=1)
intensity (SmallSingle, Image, MeanGray, DeviationGray)
area_center (SmallSingle, Area, Row, Column)
dev_set_color (’yellow’)
set_tposition (WindowID, Row, Column)
write_string (WindowID, ’Area=’+Area+’, Int=’+MeanGray)
endif
endwhile
dev_set_line_width (1)
dev_update_window (’on’)

Result
while returns 2 (H_MSG_TRUE) if the evaluation of the expression yields no error. endwhile (as operator)
always returns 2 (H_MSG_TRUE)
Parallelization Information
while is reentrant, local, and processed without parallelization.
Alternatives
for, until
See also
repeat, break, continue, if, elseif, else

HALCON 8.0.2
70 CHAPTER 2. CONTROL

Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


Chapter 3

Develop

dev_clear_obj ( Objects : : : )

Delete an iconic object from the HALCON database.


dev_clear_obj deletes iconic objects, which are no longer needed, from the HALCON database. It should be
noted that dev_clear_obj cannot be exported to C++ due to the automatic memory management in C++.
Attention
Never use clear_obj to clear objects in HDevelop. The operator dev_clear_obj has to be used instead.
Parameter
. Objects (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . object(-array) ; Hobject
Objects to be deleted.
Result
dev_clear_obj returns 2 (H_MSG_TRUE) if the variable is instantiated. If necessary, an exception is raised.
Parallelization Information
dev_clear_obj is local and processed completely exclusively without parallelization.
See also
clear_obj, test_obj_def, dev_set_check, reset_obj_db
Module
Foundation

dev_clear_window ( : : : )

Clear the active graphics window.


dev_clear_window clears the graphics window content and the history of the active window. Parameters
assigned to this window (e.g., with dev_set_color, dev_set_draw, etc.) remain unmodified. The operator
is equivalent to pressing the Clear button of the active graphics window. A graphics window can be activated by
calling dev_set_window.
Attention
If dev_clear_window should be used for exported Code (C++), please note the description of
clear_window due to the different semantics in C++.
Example

read_image (Image, ’fabrik’)


regiongrowing (Image, Regions, 3, 3, 6, 100)
Number := |Regions|
dev_update_window (’off’)
for i := 1 to Number by 1

71
72 CHAPTER 3. DEVELOP

RegionSelected := Regions[i]
dev_clear_window ()
dev_display (RegionSelected)
* stop ()
endfor

Result
dev_clear_window always returns 2 (H_MSG_TRUE).
Parallelization Information
dev_clear_window is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_set_window, dev_open_window, dev_display
Possible Successors
dev_display
See also
clear_window
Module
Foundation

dev_close_inspect_ctrl ( : : Variable : )

Close an inspect window of a control variable.


dev_close_inspect_ctrl is the opposite operator to dev_inspect_ctrl, and closes the inspect win-
dow corresponding to Variable. The window can also be closed by pressing the Close-button of the dialog.
Attention
This operator is not supported for exported C++ code.
Parameter
. Variable (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real / integer / string
Name of the variable which inspect window has to be closed.
Example

Var := 1
dev_inspect_ctrl (Var)
Var := [1,2,3,9,5,6,7,8]
Var[3] := 4
stop
dev_close_inspect_ctrl (Var)

Result
If an inspect window associated with Variable is open dev_close_inspect_ctrl returns 2
(H_MSG_TRUE).
Parallelization Information
dev_close_inspect_ctrl is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_inspect_ctrl
Module
Foundation

dev_close_window ( : : : )

Close the active graphics window.

HALCON/HDevelop Reference Manual, 2008-5-13


73

dev_close_window closes the active graphics window which has been opened by dev_open_window or
by HDevelop (default window). The operator is equivalent to pressing the Close button of the active window. A
graphics window can be activated by calling dev_set_window.
Attention
If dev_close_window should be used for exported Code (C++), please note the description of
close_window due to the different semantics in C++.
Example

* close all windows


for i := 1 to 10 by 1
dev_close_window ()
endfor
read_image (For5, ’for5’)
get_image_pointer1 (For5, Pointer, Type, Width, Height)
dev_open_window (0, 0, Width, Height, ’black’, WindowHandle)
dev_display (For5)

Result
dev_close_window always returns 2 (H_MSG_TRUE).
Parallelization Information
dev_close_window is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_set_window, dev_open_window
Possible Successors
dev_open_window
See also
close_window
Module
Foundation

dev_display ( Object : : : )

Displays image objects in the current graphics window.


dev_display displays an image object (image, region, or XLD) in the active graphics window. This is equiva-
lent to a double click on an icon variable inside the variable window.
Attention
If dev_display should be used for exported Code (C++), please note the description of disp_obj due to the
different semantics in C++.
Parameter

. Object (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . object(-array) ; Hobject


Image objects to be displayed.
Example

read_image (Image, ’fabrik’)


regiongrowing (Image, Regions, 3, 3, 6, 100)
dev_clear_window ()
dev_display (Image)
dev_set_colored (12)
dev_set_draw (’margin’)
dev_display (Regions)

HALCON 8.0.2
74 CHAPTER 3. DEVELOP

Result
dev_display always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_display is local and processed completely exclusively without parallelization.
Alternatives
disp_obj, disp_image, disp_region, disp_xld
See also
dev_set_color, dev_set_colored, dev_set_draw, dev_set_line_width
Module
Foundation

dev_error_var ( : : ErrorVar, Mode : )

Define or undefine an error variable.


dev_error_var defines an error variable, i.e., a variable which contains the status of the last call of an operator.
ErrorVar will be H_MSG_TRUE (2) if no error had occured. The parameter Mode specifies if the error variable
should be used (1) or not (0). If an error variable is active it will be updated each time an operator execution is
finished. Thus a value is only valid until the next call of an operator. The value can be saved by assigning it to
another variable (see example) or by calling dev_error_var(ErrorVar,0).
Attention
If dev_error_var should be used for exported Code (C++), please note the different handling of return values
in C++.
Parameter
. ErrorVar (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer
Name of the variable which shall contain the error status.
. Mode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Switch the error variable on or off.
Default Value : 1
List of values : Mode ∈ {0, 1}
Example

dev_close_window ()
dev_open_window (0, 0, 512, 512, ’black’, WindowHandle)
dev_error_var (Error, 1)
dev_set_check (’~give_error’)
FileName := ’wrong_name’
read_image (Image, FileName)
ReadError := Error
if (ReadError # H_MSG_TRUE)
write_string (WindowHandle, ’wrong file name: ’+FileName)
endif

Result
dev_error_var always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_error_var is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_set_check
Possible Successors
dev_set_check, if, elseif, else, assign
See also
dev_set_check, set_check

HALCON/HDevelop Reference Manual, 2008-5-13


75

Module
Foundation

dev_get_preferences ( : : PreferenceNames : PreferenceValues )

Querying of HDevelop preferences by programming.


dev_get_preferences allows to query selected preferences of the HDevelop application by programming.
Until now the following preferences are supported:

’graphics_window_context_menu’: Returns whether a right click into the graphics window opens a context menu
or not. By default the context menu is enabled.

Attention
This operator is not supported for code exported.
Parameter
. PreferenceNames (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.name-array ; string
Selection of the preferences.
Default Value : ’graphics_window_context_menu’
List of values : PreferenceNames ∈ {’graphics_window_context_menu’}
. PreferenceValues (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.value-array ; string
Values of the selected preferences.
Parallelization Information
dev_get_preferences is local and processed completely exclusively without parallelization.
See also
dev_set_preferences
Module
Foundation

dev_inspect_ctrl ( : : Variable : )

Open a window to inspect a control variable.


dev_inspect_ctrl opens a dialog to check the contents of a control variable. This dialog has a scrolled list
with all the values of the variable. In the case of an frame grabber handle a specific dialog is opened which displays
the most important frame grabber parameters and can be used to switch the frame grabber only interactively. The
contents of the dilaog will be updated whenever the value(s) of variable changes. The update mode can influenced
by the operator dev_update_var. The dialog can be closed by pressing the Close-button or by calling
dev_close_inspect_ctrl.
Attention
This operator is not supported for exported C++ code.
Parameter
. Variable (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer(-array) ; integer / real / string
Name of the variable to be checked.
Example

read_image (Image, ’fabrik’)


regiongrowing (Image, Regions, 3, 3, 6, 100)
area_center (Regions, Area, Row, Column)
dev_inspect_ctrl (Area)

Result
dev_inspect_ctrl always returns 2 (H_MSG_TRUE)

HALCON 8.0.2
76 CHAPTER 3. DEVELOP

Parallelization Information
dev_inspect_ctrl is local and processed completely exclusively without parallelization.
See also
dev_update_var
Module
Foundation

dev_map_par ( : : : )

Open the dialog to specify the display parameters.


dev_map_par opens the dialog which can also be accessed from the menu Visualization . Set
Parameters.... The dialog is used to configure the modes to display data like images, regions, or polygons.
Attention
This operator is not supported for exported C++ code.
Example

read_image (Image, ’fabrik’)


threshold (Image, Region, 128, 255)
dev_map_par ()

Result
dev_map_par always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_map_par is local and processed completely exclusively without parallelization.
Possible Successors
dev_unmap_par
Module
Foundation

dev_map_prog ( : : : )

Make the main window of HDevelop visible.


dev_map_prog is used to map the main window of HDevelop after it has been unmapped by
dev_unmap_prog.
Attention
This operator is not supported for exported C++ code.
Depending on the operating system or the window manager the execution of dev_map_prog will result only in
a visible icon of the window. In this case it has to be opened by the user with mouse interaction.
Result
dev_map_prog always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_map_prog is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_unmap_prog
Possible Successors
dev_unmap_prog
See also
dev_map_par, dev_map_var
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


77

dev_map_var ( : : : )

Map the variable window on the screen.


dev_map_var maps the variable window on the screen (i.e., makes it visible) that has been unmapped using
dev_unmap_var.
Attention
This operator is not supported for exported C++ code.
Result
dev_map_var always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_map_var is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_unmap_var
Possible Successors
dev_unmap_var
See also
dev_map_par, dev_map_prog
Module
Foundation

dev_open_window ( : : Row, Column, Width, Height,


Background : WindowHandle )

Open a graphics window.


dev_open_window opens a new graphics window, which can be used to perform output of gray value data,
regions, and graphics as well as to perform textual output. This new window automatically becomes active, which
means that all output ( dev_display and automatical display of operator results) is redirected to this window.
This is shown by the green dot in the Active button.
In the case of the standard display operators (like disp_image, disp_region, disp_line, etc.) instead
of dev_display the logical window number WindowHandle has to be used.
The background of the created window is set to the color specified in Background.
Pressing the Clear button clears the graphics window contents and the history of the window. This can also be
achived by using the operator dev_clear_window. You close a graphics window using the Close button of
the window frame or by calling dev_close_window.
The origin of the graphics window is the upper left corner with the coordinates (0,0). The x values (column) in-
crease from left to right, the y values increase from top to bottom. Normally, the coordinate system of the graphics
window corresponds to the the most recently displayed image, which is automatically zoomed so that every pixel of
the image is visible. The coordinate system can be changed interactively using the menu Visualization.Set
Parameters.Zoom or with the operator dev_set_part. Every time an image with a different size is dis-
played, the coordinate system will be adapted automatically.
Each window has a history which contains all

• objects and
• display parameters

which have been displayed or changed since the most recent clear action or display of a full image. This history
is used for redrawing the contents of the window. Other output like text or general graphics like disp_line or
disp_circle or iconic data that is displayed using HALCON operators like disp_image or disp_region
are not part of the history, and are not redrawn. Only the object classes image, region, and XLD that are displayed
with the HDevelop operator dev_display or by double clicking on an icon are part of the history.
You may change the size of the graphics window interactively by “gripping” the window border with the mouse.
Then you can resize the window by dragging the mouse pointer. After this size modification the window content
is redisplayed. Now you see the same part of the window with changed zoom.

HALCON 8.0.2
78 CHAPTER 3. DEVELOP

If the mouse cursor is inside the window its look-up-table is reactivated. This is necessary if other programs use
their own look-up table. Thus if there is a “strange” graphics window presentation, you may load the proper
look-up table by placing the mouse inside the window.
Opening a window causes the assignment of a default font. It is used in connection with pro-
cedures like write_string and you may overwrite it by performing set_font after calling
dev_open_window. On the other hand you have the possibility to specify a default font by calling
set_system(’default_font’,<Fontname>) before opening a window (and all following windows; see
also query_font).
If you want to specify display parameters for a window you may select the menu item Visualization in the
menu bar. Here you can set the appropriate parameters by clicking the desired item. Parameters which you have set
in this way are used for all windows (in contrast to standard windows opened with open_window). The effects
of the new parameters will be applied direcly to the last object of the window history and alter its parameters only.
Attention
Never use close_window to close an HDevelop graphics window. The operator dev_close_window has
to be used instead.
If dev_open_window should be used for exported Code (C++), please note the description of open_window
due to the different semantics in C++.
Parameter
. Row (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.y ; integer
Row index of upper left corner.
Default Value : 0
Typical range of values : 0 ≤ Row
Minimum Increment : 1
Recommended Increment : 1
Restriction : Row ≥ 0
. Column (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .rectangle.origin.x ; integer
Column index of upper left corner.
Default Value : 0
Typical range of values : 0 ≤ Column
Minimum Increment : 1
Recommended Increment : 1
Restriction : Column ≥ 0
. Width (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.extent.x ; integer
Width of the window.
Default Value : 256
Typical range of values : 0 ≤ Width
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Width > 0) ∨ (Width = -1)
. Height (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.extent.y ; integer
Height of the window.
Default Value : 256
Typical range of values : 0 ≤ Height
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Height > 0) ∨ (Height = -1)
. Background (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer / string
Color of the background of the new window.
Default Value : ’black’
. WindowHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . window ; integer
Window identifier.
Example

dev_close_window ()
read_image (For5, ’for5’)
get_image_pointer1 (For5, Pointer, Type, Width, Height)

HALCON/HDevelop Reference Manual, 2008-5-13


79

dev_open_window (0, 0, Width, Height, ’black’, WindowHandle)


dev_display (For5)
dev_set_lut (’rainbow’)
dev_display (For5)
stop ()
dev_set_lut (’default’)
dev_display (For5)
stop ()
dev_set_part (100, 100, 300, 300)
dev_display (For5)

Result
If the values of the specified parameters are correct dev_open_window returns 2 (H_MSG_TRUE). If necessary
an exception handling is raised.
Parallelization Information
dev_open_window is local and processed completely exclusively without parallelization.
Possible Successors
dev_display, dev_set_lut, dev_set_color, dev_set_draw, dev_set_part
Alternatives
open_window
See also
query_color
Module
Foundation

dev_set_check ( : : Mode : )

Specify the error handling.


dev_set_check specifies how HDevelop should react if an error occures. If Mode has the value ’give_error’ –
which is the system default – HDevelop stops the program execution if an exception occures and displays an error
message. If you use ’˜give_error’ the exception will be ignored and the program continues. dev_set_check
is intended to be used in connection with dev_error_var, which allows to check for the result state of an
operator.
Attention
If dev_set_check should be used for exported Code (C++), please note the description of set_check due
to the different semantics in C++.
Parameter

. Mode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Mode of error handling.
Default Value : ’give_error’
Example

dev_close_window ()
dev_open_window (0, 0, 512, 512, ’black’, WindowHandle)
dev_error_var (Error, 1)
dev_set_check (’~give_error’)
FileName := ’wrong_name’
read_image (Image, FileName)
ReadError := Error
if (ReadError # H_MSG_TRUE)
write_string (WindowHandle, ’wrong file name: ’+FileName)
endif
* Now the program will stop with an exception

HALCON 8.0.2
80 CHAPTER 3. DEVELOP

dev_set_check (’give_error’)
read_image (Image, FileName)

Result
dev_set_check always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_check is local and processed completely exclusively without parallelization.
Possible Successors
dev_error_var
See also
set_check
Module
Foundation

dev_set_color ( : : ColorName : )

Set one or more output colors.


dev_set_color defines the colors for region and line oriented output in the graphics windows. The available
colors can be queried with the operator 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.
The defined colors are used until dev_set_color or dev_set_colored is called.
Colors are defined for all graphics windows in contrast to the operator set_color.
Attention
If dev_set_color should be used for exported Code (C++), please note the description of set_color due
to the different semantics in C++.
Parameter
. ColorName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string(-array) ; string
Output color names.
Default Value : ’white’
Suggested values : ColorName ∈ {’white’, ’black’, ’gray’, ’red’, ’green’, ’blue’}
Example

read_image(Image,’mreut’)
dev_set_draw(’fill’)
dev_set_color(’red’)
threshold(Image,Region,180,255)
dev_set_color(’green’)
threshold(Image,Region,0,179)

Result
dev_set_color always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_color is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_open_window, query_color, query_all_colors
Possible Successors
dev_display
Alternatives
dev_set_colored
See also
dev_set_draw, dev_set_line_width, set_color

HALCON/HDevelop Reference Manual, 2008-5-13


81

Module
Foundation

dev_set_colored ( : : NumColors : )

Set multiple output colors.


dev_set_colored allows the user to display a tuple of regions in different colors. NumColors defines the
number of colors that are used. Valid values for NumColors can be queried with query_colored.
Attention
If dev_set_colored should be used for exported Code (C++), please note the description of set_colored
due to the different semantics in C++.
Parameter
. NumColors (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of output colors.
Default Value : 6
List of values : NumColors ∈ {3, 6, 12}
Example

read_image(Image,’monkey’)
threshold(Image,Region,128,255)
dev_set_colored(6)
connection(Region,Regions)

Result
dev_set_colored always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_colored is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_open_window
Possible Successors
dev_display
Alternatives
dev_set_color
See also
dev_set_draw, dev_set_line_width, set_colored
Module
Foundation

dev_set_draw ( : : DrawMode : )

Define the region fill mode.


dev_set_draw defines the region fill mode. If DrawMode is set to ’fill’, output regions are filled, if set
to ’margin’, only contours are displayed. It is used by region output like dev_display, disp_region,
disp_circle, disp_rectangle1, disp_rectangle2, disp_arrow, etc. If the mode is ’margin’,
the contour can be affected by dev_set_line_width, set_line_approx and set_line_style.
Attention
If dev_set_draw should be used for exported Code (C++), please note the description of set_draw due to
the different semantics in C++.

HALCON 8.0.2
82 CHAPTER 3. DEVELOP

Parameter
. DrawMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Fill mode for region output.
Default Value : ’fill’
List of values : DrawMode ∈ {’fill’, ’margin’}
Example

read_image(Image,’monkey’)
threshold(Image,Region,128,255)
dev_clear_window
dev_set_color(’red’)
dev_set_draw(’fill’)
dev_display(Region)
dev_set_color(’white’)
dev_set_draw(’margin’)
dev_display(Region)

Result
dev_set_draw always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_draw is local and processed completely exclusively without parallelization.
Possible Successors
dev_set_line_width, dev_display
See also
set_draw
Module
Foundation

dev_set_line_width ( : : LineWidth : )

Define the line width for region contour output.


dev_set_line_width defines the line width (in pixel) in which a region contour or lines are displayed (e.g.,
with dev_display, disp_region, disp_line, disp_polygon, etc.).
Attention
If dev_set_line_width should be used for exported Code (C++), please note the description of
set_line_width due to the different semantics in C++.
Parameter
. LineWidth (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Line width for region output in contour mode.
Default Value : 1
Restriction : LineWidth ≥ 1
Example

read_image(Image,’monkey’)
threshold(Image,Region,128,255)
dev_set_draw(’margin’)
dev_set_line_width(5)
dev_clear_window
dev_display(Region)

Result
dev_set_line_width always returns 2 (H_MSG_TRUE)

HALCON/HDevelop Reference Manual, 2008-5-13


83

Parallelization Information
dev_set_line_width is local and processed completely exclusively without parallelization.
Possible Successors
dev_display
See also
set_line_width, query_line_width
Module
Foundation

dev_set_lut ( : : LutName : )

Set “look-up-table” (lut).


dev_set_lut sets look-up-table of the 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 screen-colors 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 look-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. truecolor).
For common monitors only one look-up-table can be loaded per screen. Whereas dev_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 placing the mouse inside
the window).
look-up-tables 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.
query_lut lists the names of all look-up-tables.
Attention
If dev_set_lut should be used for exported Code (C++), please note the description of set_lut due to the
different semantics in C++.
Parameter
. LutName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
Name of look-up-table, values of look-up-table (RGB) or file name.
Default Value : ’default’
Suggested values : LutName ∈ {’default’, ’linear’, ’inverse’, ’sqr’, ’inv_sqr’, ’cube’, ’inv_cube’, ’sqrt’,
’inv_sqrt’, ’cubic_root’, ’inv_cubic_root’, ’color1’, ’color2’, ’color3’, ’color4’, ’three’, ’six’, ’twelve’,
’twenty_four’, ’rainbow’, ’temperature’, ’cyclic_gray’, ’cyclic_temperature’, ’hsi’, ’change1’, ’change2’,
’change3’}
Example

read_image(Image,’mreut’)
dev_set_lut(’inverse’)
* For true color only:
dev_display(Image)

Result
dev_set_lut always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_lut is local and processed completely exclusively without parallelization.
Possible Successors
dev_display
See also
set_lut

HALCON 8.0.2
84 CHAPTER 3. DEVELOP

Module
Foundation

dev_set_paint ( : : Mode : )

Define the grayvalue output mode.


dev_set_paint defines the output mode for gray value display in the graphics window. The mode is used by
dev_display.
This page describes shortly the different modes, that can be used for gray value output. It should be noted, that the
mode ’default’ is the most suitable. For a detailed description of all possible options see set_paint.
A different way to display gray values is the histogram (mode: ’histogram’). This mode has three 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.
The modes ’row’ and ’column’ allow to display gray values along rows or columns, respecively. The position
(row and column index) is passed with the second parameter 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 gray value. To view these 3d plots, select
the modes ’contourline’, ’3D-plot’ or ’3D-plot_hidden’. For a detailed description of all parameter settings see
set_paint.
Parameters 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:
dev_set_paint(’contourline’)
• All values are passed: all output characteristics can be set. Example: dev_set_paint
([’contourline’,10,1])
• Only the first n values are passed: only the passed values are changed. Example: dev_set_paint
([’contourline’,10])

Attention
If dev_set_paint should be used for exported Code (C++), please note the description of set_paint due
to the different semantics in C++.
Parameter

. Mode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string-array ; string / integer


Grayvalue output name. Additional parameters possible.
Default Value : ’default’
List of values : Mode ∈ {’default’, ’histogram’, ’row’, ’column’, ’contourline’, ’3D-plot’, ’3D-plot_hidden’,
’3D-plot_point’}
Example

read_image(Image,’fabrik’)
dev_set_paint(’3D-plot’)
dev_display(Image)

Parallelization Information
dev_set_paint is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_open_window
Possible Successors
dev_set_color, dev_display

HALCON/HDevelop Reference Manual, 2008-5-13


85

See also
set_paint
Module
Foundation

dev_set_part ( : : Row1, Column1, Row2, Column2 : )

Modify the displayed image part.


dev_set_part modifies the image part that is displayed in the graphics window. (Row1,Column1) denotes
the upper left corner and (Row2,Column2) the lower right corner of the image part to display.
If Row1 is larger than Row2 the zooming will be reset. That means that the last displayed image will be completetly
visible. Please note that this is not possible with the operator set_part outside HDevelop.
Attention
If dev_set_part should be used for exported Code (C++), please note the description of set_part due to
the different semantics in C++.
Parameter
. Row1 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.y ; integer
Row of the upper left corner of the chosen image part.
Default Value : 0
. Column1 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.x ; integer
Column of the upper left corner of the chosen image part.
Default Value : 0
. Row2 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.corner.y ; integer
Row of the lower right corner of the chosen image part.
Default Value : 128
. Column2 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.corner.x ; integer
Column of the lower right corner of the chosen image part.
Default Value : 128
Example

read_image (Image, ’fabrik’)


for i := 1 to 240 by 10
dev_set_part (i, i, 511-i, 511-i)
dev_display (Image)
endfor
dev_set_part (1, 1, -1, -1)
dev_display (Image)

Result
dev_set_part always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_set_part is local and processed completely exclusively without parallelization.
Possible Successors
dev_display
See also
set_part
Module
Foundation

dev_set_preferences ( : : PreferenceNames, PreferenceValues : )

Setting of HDevelop preferences by programming.

HALCON 8.0.2
86 CHAPTER 3. DEVELOP

dev_set_preferences allows to set selected preferences of the HDevelop application by programming. Until
now the following preferences are supported:

’graphics_window_context_menu’: Controls whether a right click into the graphics window opens a context menu
or not. By default the context menu is enabled. Disabling the context menu may be sensible if the right mouse
button is used for controlling some kind of navigation in the graphics window, e.g., for moving or zooming
3D-objects.
Possible values: ’false’, ’true’.
Default value: ’false’.

Attention
This operator is not supported for code exported.
Parameter

. PreferenceNames (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.name-array ; string


Selection of the preferences.
Default Value : ’graphics_window_context_menu’
List of values : PreferenceNames ∈ {’graphics_window_context_menu’}
. PreferenceValues (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.value-array ; string
New values for the selected preferences.
Default Value : ’false’
List of values : PreferenceValues ∈ {’true’, ’false’}
Parallelization Information
dev_set_preferences is local and processed completely exclusively without parallelization.
See also
dev_get_preferences
Module
Foundation

dev_set_shape ( : : Shape : )

Define the region output shape.


dev_set_shape defines the shape for region output. The output shape is used by dev_display for regions.
The available shapes can be queried with query_shape.
Available modes:

’original’: The shape is displayed unchanged. Nevertheless modifications via parameters like
dev_set_line_width 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 shape_trans.)
’icon’ Each region is displayed by the icon set with set_icon in the center of gravity.

Attention
If dev_set_shape should be used for exported Code (C++), please note the description of set_shape due
to the different semantics in C++.

HALCON/HDevelop Reference Manual, 2008-5-13


87

Parameter
. Shape (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Region output mode.
Default Value : ’original’
List of values : Shape ∈ {’original’, ’convex’, ’outer_circle’, ’inner_circle’, ’rectangle1’, ’rectangle2’,
’ellipse’, ’icon’}
Example

read_image(Image,’monkey’)
threshold(Image,Region,128,255)
connection(Region,Regions)
dev_set_shape(’rectangle1’)
dev_set_draw(’margin’)
dev_display(Regions)

Parallelization Information
dev_set_shape is local and processed completely exclusively without parallelization.
Possible Successors
dev_display, dev_set_color
See also
set_shape, dev_set_line_width
Module
Foundation

dev_set_window ( : : WindowID : )

Activate a graphics window.


dev_set_window activates a graphics window. This is equivalent to pressing the Active button of the graphics
window.
Attention
If dev_set_window should be used for exported Code (C++), please note the different handling of windows in
C++.
dev_set_window is not supported for C++.
Parameter
. WindowID (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . window ; integer
Window_id.
Example

dev_open_window (1, 1, 200, 200, ’black’, WindowID1)


dev_open_window (1, 220, 200, 200, ’black’, WindowID2)
read_image(Image,’monkey’)
dev_set_window(WindowID1)
dev_display(Image)
dev_set_window(WindowID2)
dev_display(Image)

Parallelization Information
dev_set_window is local and processed completely exclusively without parallelization.
Possible Predecessors
dev_open_window
Possible Successors
dev_display
Module
Foundation

HALCON 8.0.2
88 CHAPTER 3. DEVELOP

dev_set_window_extents ( : : Row, Column, Width, Height : )

Change position and size of a graphics window.


dev_set_window_extents changes the position and/or the size of the currently active graphics window.
The parameters Row and Column specify the new position (upper left corner) of the window. If one of both values
is negative, the position will remain unchanged. The parameters Width and Height specify the new size of the
window. This is the size of the inner part that actually displayes the data. If one of the two values is negative, the
size will remain unchanged.
Attention
Never use set_window_extents to change the size and position of an HDevelop graphics window. The
operator dev_set_window_extents has to be used instead.
Parameter
. Row (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.y ; integer
Row index of upper left corner.
Default Value : 0
Typical range of values : 0 ≤ Row
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Row ≥ 0) ∨ (Row = -1)
. Column (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.x ; integer
Column index of upper left corner.
Default Value : 0
Typical range of values : 0 ≤ Column
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Column ≥ 0) ∨ (Column = -1)
. Width (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.extent.x ; integer
Width of the window.
Default Value : 256
Typical range of values : 0 ≤ Width
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Width > 0) ∨ (Width = -1)
. Height (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.extent.y ; integer
Height of the window.
Default Value : 256
Typical range of values : 0 ≤ Height
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Height > 0) ∨ (Height = -1)
Example

dev_close_window ()
read_image (For5, ’for5’)
get_image_pointer1 (For5, Pointer, Type, Width, Height)
dev_open_window (0, 0, Width, Height, ’black’, WindowHandle)
dev_display (For5)
stop ()
dev_set_window_extents (-1,-1,Width/2,Height/2)
dev_display (For5)
stop ()
dev_set_window_extents (200,200,-1,-1)

Result
If the values of the specified parameters are correct dev_set_window_extents returns 2 (H_MSG_TRUE).
If necessary an exception handling is raised.

HALCON/HDevelop Reference Manual, 2008-5-13


89

Parallelization Information
dev_set_window_extents is local and processed completely exclusively without parallelization.
Possible Successors
dev_display, dev_set_lut, dev_set_color, dev_set_draw, dev_set_part
See also
set_window_extents
Module
Foundation

dev_unmap_par ( : : : )

Hide the window for the graphic parameters.


dev_unmap_par hides the window for the graphic parameters so that it is no longer visible. It can be mapped
again using the operator dev_map_par.
Attention
This operator is not supported for exported C++ code.
Result
dev_unmap_par always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_unmap_par is local and processed completely exclusively without parallelization.
Possible Successors
dev_map_prog
See also
dev_map_par, dev_map_prog, dev_map_var
Module
Foundation

dev_unmap_prog ( : : : )

Hide the main window.


dev_unmap_prog hides the main window so that it is no longer visible. It can be mapped again using the
operator dev_map_prog.
Attention
This operator is not supported for exported C++ code.
Result
dev_unmap_prog always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_unmap_prog is local and processed completely exclusively without parallelization.
Possible Successors
dev_map_prog, stop
See also
dev_map_par, dev_map_prog, dev_map_var
Module
Foundation

dev_unmap_var ( : : : )

Hide the variable window.

HALCON 8.0.2
90 CHAPTER 3. DEVELOP

dev_unmap_var hides the variable window so that it is no longer visible. It can be mapped again using the
operator dev_map_var.
Attention
This operator is not supported for exported C++ code.
Result
dev_unmap_var always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_unmap_var is reentrant, local, and processed without parallelization.
Possible Successors
dev_map_var
See also
dev_map_par, dev_map_prog
Module
Foundation

dev_update_pc ( : : DisplayMode : )

Specify the behaviour of the PC during program execution.


dev_update_pc specifies the behaviour of the PC during program execution. In the mode ’on’ (default) the PC
is always displayed in front of the current operator. In addition the program text is scrolled – if necessary – so that
the current operator is visible. In the mode ’off’ the PC is not visible during program execution and the program
text will not be scrolled automatically.
This option can also be controled by the dialog
File . Options . Update PC.
Attention
This operator is not supported for exported C++ code.
Parameter

. DisplayMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Mode for runtime behaviour.
Default Value : ’off’
List of values : DisplayMode ∈ {’on’, ’off’}
Result
dev_update_pc always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_update_pc is reentrant, local, and processed without parallelization.
See also
dev_update_time, dev_update_window, dev_update_var
Module
Foundation

dev_update_time ( : : DisplayMode : )

Switch time measurement for operators on or off.


dev_update_time controls if the execution time of an operator has to be measured.
This option can also be controled by the dialog
File . Options . Show Processing Time.
Attention
This operator is not supported for exported C++ code.

HALCON/HDevelop Reference Manual, 2008-5-13


91

Parameter
. DisplayMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Mode for graphic output.
Default Value : ’off’
List of values : DisplayMode ∈ {’on’, ’off’}
Result
dev_update_time always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_update_time is reentrant, local, and processed without parallelization.
See also
dev_update_pc, dev_update_window, dev_update_var
Module
Foundation

dev_update_var ( : : DisplayMode : )

Specify the behaviour of the variable window during program execution.


dev_update_var specifies the behaviour of the variable window during program execution. Using the mode
’on’ (default) the contents of the variable window (iconic and control variables) is updated each time a variable
is modified by the program. In the mode ’off’ the variables are updated only when the execution is finished.
Please not that update in this contents only means the graphical representation of the internal values in the variable
window.
This option can also be controled by the dialog
File . Options . Update Variables.
Attention
This operator is not supported for exported C++ code.
Parameter
. DisplayMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Mode for graphic output.
Default Value : ’off’
List of values : DisplayMode ∈ {’on’, ’off’}
Result
dev_update_var always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_update_var is reentrant, local, and processed without parallelization.
See also
dev_update_pc, dev_update_window, dev_update_time
Module
Foundation

dev_update_window ( : : DisplayMode : )

Specify the output behaviour during program execution.


dev_update_window specifies the output behaviour during program execution. By default every object (image,
region, or XLD) is displayed in the active graphics window. This can be changed by using the value ’off’ for
DisplayMode. In this case objects are only displayed in single step mode. Here one would use the operator
dev_display to output objects.
This option can also be controled by the dialog
File . Options . Update Window.

HALCON 8.0.2
92 CHAPTER 3. DEVELOP

Attention
This operator is not supported for exported C++ code.
Parameter

. DisplayMode (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Mode for graphic output.
Default Value : ’off’
List of values : DisplayMode ∈ {’on’, ’off’}
Result
dev_update_window always returns 2 (H_MSG_TRUE)
Parallelization Information
dev_update_window is reentrant, local, and processed without parallelization.
Possible Successors
dev_display
See also
dev_update_pc, dev_update_var, dev_update_time
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


Chapter 4

File

4.1 Images

read_image ( : Image : FileName : )

Read an image with different file formats.


The operator read_image reads the indicated image files from the background storage and generates the image.
One or more file names can be passed in FileName. If more than one file name is passed, an image object tuple
with the corresponding number of image objects is returned.
For the image formats PNG and JPEG-2000, binary alpha channels are interpreted as regions. Otherwise the region
of the generated image object (= all pixels of the matrix) is chosen maximal.
All images files written by the operator 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, JPEG-2000, PNG, 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. If no extension is indicated, files with extension are preferred to files
without extension. 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 JPEG-2000 only ’jp2’ is 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 direc-
tory 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 ’im-
age_dir’). Example:

setenv HALCONIMAGES "/usr/images:/usr/local/halcon/images"\\*

HALCON also searches images in the subdirectory "‘images"’ (Images for the program examples). The environ-
ment variable HALCONROOT is used for the HALCON directory.
Attention
If CMYK or YCCK JPEG files are read, HALCON assumes that these files follow the Adobe Photoshop convention
that the CMYK channels are stored inverted, i.e., 0 represents 100% ink coverage, rather than 0% ink as one would
expect. The images are converted to RGB images using this convention. If the JPEG file does not follow this
convention, but stores the CMYK channels in the usual fashion, invert_image must be called after reading
the image.

93
94 CHAPTER 4. FILE

If PNG images that contain an alpha channel are read, the alpha channel is returned as the second or fourth channel
of the output image, unless the alpha channel contains exactly two different gray values, in which case a one or
three channel image with a reduced domain is returned, in which the points in the domain correspond to the points
with the higher gray value in the alpha channel.
Parameter

. Image (output_object) . . . . image(-array) ; Hobject : byte / direction / cyclic / int1 / int2 / uint2 / int4 / real
Read image.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read(-array) ; string
Name of the image to be read.
Default Value : ’fabrik’
Suggested values : FileName ∈ {’monkey’, ’fabrik’, ’mreut’}
Example

/* Reading an image: */
read_image(Image,’monkey’).

/* Reading 3 images into an image array: */


read_image(Images,[’ic_0’,’ic_1’,’ic_2’]).

/* 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 read_image returns the value 2 (H_MSG_TRUE). Otherwise an
exception handling is raised.
Parallelization Information
read_image is reentrant and processed without parallelization.
Possible Successors
disp_image, threshold, regiongrowing, count_channels, decompose3,
class_ndim_norm, gauss_image, fill_interlace, zoom_image_size,
zoom_image_factor, crop_part, write_image, rgb1_to_gray
Alternatives
read_sequence
See also
set_system, write_image
Module
Foundation

read_sequence ( : Image : HeaderSize, SourceWidth, SourceHeight,


StartRow, StartColumn, DestWidth, DestHeight, PixelType, BitOrder,
ByteOrder, Pad, Index, 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),
’swapped_long’ (32 bits, with swapped segments), and ’real’ (32 bit floating point numbers) are supported. Fur-
thermore, the operator read_sequence enables the extraction of components of a RBG image, if a triple of

HALCON/HDevelop Reference Manual, 2008-5-13


4.1. IMAGES 95

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 ’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 environment variable) and in the image direc-
tory 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 ’im-
age_dir’). Example:

setenv HALCONIMAGES "/usr/images:/usr/local/halcon/images"\\*

HALCON also searches images in the subdirectory "‘images"’ (Images for the program examples). The environ-
ment variable HALCONROOT is used for the HALCON directory.
Attention
If files of pixel type ’real’ are read and the byte order is chosen incorrectly (i.e., differently from the byte order in
which the data is stored in the file) program error and even crashes because of floating point exceptions may result.
Parameter
. Image (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image ; Hobject : byte / int2 / uint2 / int4
Image read.
. HeaderSize (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of bytes for file header.
Default Value : 0
Typical range of values : 0 ≤ HeaderSize
. SourceWidth (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .extent.x ; integer
Number of image columns of the filed image.
Default Value : 512
Typical range of values : 1 ≤ SourceWidth
. SourceHeight (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . extent.y ; integer
Number of image lines of the filed image.
Default Value : 512
Typical range of values : 1 ≤ SourceHeight
. StartRow (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . point.y ; integer
Starting point of image area (line).
Default Value : 0
Typical range of values : 0 ≤ StartRow
Restriction : StartRow < SourceHeight
. StartColumn (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . point.x ; integer
Starting point of image area (column).
Default Value : 0
Typical range of values : 0 ≤ StartColumn
Restriction : StartColumn < SourceWidth
. DestWidth (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . extent.x ; integer
Number of image columns of output image.
Default Value : 512
Typical range of values : 1 ≤ DestWidth
Restriction : DestWidth ≤ SourceWidth
. DestHeight (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . extent.y ; integer
Number of image lines of output image.
Default Value : 512
Typical range of values : 1 ≤ DestHeight
Restriction : DestHeight ≤ SourceHeight

HALCON 8.0.2
96 CHAPTER 4. FILE

. PixelType (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Type of pixel values.
Default Value : ’byte’
List of values : PixelType ∈ {’bit’, ’byte’, ’r_byte’, ’g_byte’, ’b_byte’, ’short’, ’signed_short’, ’long’,
’swapped_long’, ’real’}
. BitOrder (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Sequence of bits within one byte.
Default Value : ’MSBFirst’
List of values : BitOrder ∈ {’MSBFirst’, ’LSBFirst’}
. ByteOrder (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Sequence of bytes within one ’short’ unit.
Default Value : ’MSBFirst’
List of values : ByteOrder ∈ {’MSBFirst’, ’LSBFirst’}
. Pad (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Data units within one image line (alignment).
Default Value : ’byte’
List of values : Pad ∈ {’byte’, ’short’, ’long’}
. Index (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Number of images in the file.
Default Value : 1
Typical range of values : 1 ≤ Index (lin)
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
Name of input file.
Result
If the parameter values are correct the operator read_sequence returns the value 2 (H_MSG_TRUE). Other-
wise an exception handling is raised.
Parallelization Information
read_sequence is reentrant and processed without parallelization.
Possible Successors
disp_image, count_channels, decompose3, write_image, rgb1_to_gray
Alternatives
read_image
See also
read_image
Module
Foundation

write_image ( Image : : Format, FillColor, FileName : )

Write images in graphic formats.


The operator 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: *.tif
’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.

HALCON/HDevelop Reference Manual, 2008-5-13


4.2. MISC 97

’jp2’ : JPEG-2000 format (lossless and lossy compression); together with the format string the quality value
determing the compression rate can be provided (e.g., ’jp2 40’). This value corresponds to the ratio of the
size of the compressed image and the size of the uncompressed image (in percent). Since lossless JPEG-
2000 compression already reduces the file size significantly, only smaller values (typically smaller than 50)
influence the file size. If no value is provided for the compression (and only then), the image is compressed
lossless. The image can contain an arbitrary number of channels. Possible types are byte, cyclic, direction,
int1, uint2, int2, and int4. In the case of int4 it is only possible to store images with less or equal to 24
bits precision (otherwise an exception handling is raised). If an image with a reduced domain is written, the
region is stored as 1 bit alpha channel.
’png’ PNG format (lossless compression); together with the format string, a compresion level between 0 and 9 can
be specified, where 0 corresponds to no compression and 9 to the best possible compression. Alternatively,
the compression can be selected with the following strings: ’best’, ’fastest’, and ’none’. Hence, examples for
correct parameters are ’png’, ’png 7’, and ’png none’. Images of type byte and uint2 can be stored in PNG
files. If an image with a reduced domain is written, the region is stored as the alpha channel, where the points
within the domain are stored as the maximum gray value of the image type and the points outside the domain
are stored as the gray value 0. If an image with a full domain is written, no alpha channel is stored.
’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"’. All HALCON pixel types except complex
and vector_field can be written. Only the first channel of the image is stored in the file. The file extension
is: ’.ima’

Parameter

. Image (input_object) . . . . . image(-array) ; Hobject : byte / direction / cyclic / int1 / int2 / uint2 / int4 / real
Output image(s).
. Format (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Graphic format.
Default Value : ’tiff’
List of values : Format ∈ {’tiff’, ’bmp’, ’jpeg’, ’ima’, ’jpeg 100’, ’jpeg 80’, ’jpeg 60’, ’jpeg 40’, ’jpeg 20’,
’jp2’, ’jp2 50’, ’jp2 40’, ’jp2 30’, ’jp2 20’, ’png’, ’png best’, ’png fastest’, ’png none’}
. FillColor (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Fill gray value for pixels not belonging to the image region.
Default Value : 0
Suggested values : FillColor ∈ {-1, 0, 255, ’0xff0000’, ’0xff00’}
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write(-array) ; string
Name of graphic file.
Result
If the parameter values are correct the operator write_image returns the value 2 (H_MSG_TRUE). Otherwise
an exception handling is raised.
Parallelization Information
write_image is reentrant and processed without parallelization.
Possible Predecessors
open_window, read_image
Module
Foundation

4.2 Misc
delete_file ( : : FileName : )

Delete a file.
delete_file deletes the file given by FileName.

HALCON 8.0.2
98 CHAPTER 4. FILE

Parameter

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename ; string


Name of file to be checked.
Result
delete_file returns the value 2 (H_MSG_TRUE) if the file exists and could be deleted. Otherwise, an excep-
tion is raised.
Parallelization Information
delete_file is reentrant and processed without parallelization.
Module
Foundation

file_exists ( : : FileName : FileExists )

Check whether file exists.


The operator file_exists checks whether the indicated file already exists. If this is the case, the parameter
FileExists is set to TRUE, otherwise to FALSE.
Parameter

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename ; string


Name of file to be checked.
Default Value : ’/bin/cc’
. FileExists (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
boolean number.
Result
If the parameters are correct the operator file_exists returns the value 2 (H_MSG_TRUE). Otherwise, an
exception is raised.
Parallelization Information
file_exists is reentrant and processed without parallelization.
Possible Successors
open_file
Alternatives
open_file
Module
Foundation

list_files ( : : Directory, Options : Files )

List all files in a directory.


list_files returns all files in the directory given by Directory in the parameters Files. The current
directory can be specified with ” or ’.’. The parameter Options can be used to specify different processing
options by passing a tuple of values. If Options contains ’files’ only the files present in Directory are
returned. If ’directories’ is passed, only the directories present in Directory are returned. Directories are
marked by a trailing ’\’ (Windows) or a trailing ’/’ (Unix). If files as well as directories should be returned,
[’files’,’directories’] must be passed. If neither ’files’ nor ’directories’ is passed, list_files returns an empty
tuple. By passing ’recursive’, it can be specified that the directory tree should be searched recursively by examining
all sub-directories. On Unix systems, ’follow_links’ can be used to specify that symbolic links to files or directories
should be followed. In the default setting, symbolic links are not dereferenced, and hence are not searched if they
point to directories, and not returned if they point to files. For the recursive search, a maximum search depth can be
specified with ’max_depth <d>’, where ’<d>’ is a number that specifies the maximum depth. Hence, ’max_depth
2’ specifies that Directory and all immediate sub-directories should be searched. If symbolic links should be
followed it might happen that the search does not terminate if the symbolic links lead to a cycle in the directory

HALCON/HDevelop Reference Manual, 2008-5-13


4.2. MISC 99

structure. Because of this, at most 1000000 files (and directories) are returned in Files. By specifying a different
number with ’max_files <d>’, this value can be reduced.
Parameter

. Directory (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.dir ; string


Name of directory to be listed.
. Options (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string(-array) ; string
Processing options.
Default Value : ’files’
Suggested values : Options ∈ {’files’, ’directories’, ’recursive’, ’follow_links’, ’max_depth 5’, ’max_files
1000’}
. Files (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string-array ; string
Found files (and directories).
Result
list_files returns the value 2 (H_MSG_TRUE) if the directory exists and could be read. Otherwise, an
exception is raised.
Parallelization Information
list_files is reentrant and processed without parallelization.
Possible Successors
tuple_regexp_select
Module
Foundation

read_world_file ( : : FileName : WorldTransformation )

Read the geo coding from an ARC/INFO world file.


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 con-
tent of the environment variable HALCONIMAGES) are searched (see read_image). This transforma-
tion 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 call-
ing 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.read ; string


Name of the ARC/INFO world file.
. WorldTransformation (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hom_mat2d-array ; real
Transformation matrix from image to world coordinates.
Result
If the parameters are correct and the world file could be read, the operator read_world_file returns the value
2 (H_MSG_TRUE). Otherwise an exception is raised.
Parallelization Information
read_world_file is reentrant and processed without parallelization.
Possible Successors
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
Foundation

HALCON 8.0.2
100 CHAPTER 4. FILE

4.3 Region

read_region ( : Region : 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 one region. The color black is used as
foreground.
BMP: Binary Windows bitmap images with extension ’bmp’. The result is always one 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 read_image.
Attention
The clipping based on the current image format is set via the operator set_system
(’clip_region’,<’true’/’false’>). Consequently, if no image of suffcient size has been cre-
ated before the call to read_region, set_system(’clip_region’,’false’) should be called before
calling read_region to ensure that the region is not being clipped.
Parameter
. Region (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . region(-array) ; Hobject
Read region.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
Name of the region to be read.
Example

/* Reading of regions and giving them gray values. */


read_image(Img,’bild_test5’)
read_region(Regs,’reg_test5’)
reduce_domain(Img,Regs,Res)

Result
If the parameter values are correct the operator read_region returns the value 2 (H_MSG_TRUE). Otherwise
an exception handling is raised.
Parallelization Information
read_region is reentrant and processed without parallelization.
Possible Predecessors
read_image
Possible Successors
reduce_domain, disp_region
See also
write_region, read_image
Module
Foundation

write_region ( Region : : 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. If no extension has
been specified in FileName, the extension ’.reg’ is appended to FileName.

HALCON/HDevelop Reference Manual, 2008-5-13


4.4. TEXT 101

Parameter
. Region (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . region(-array) ; Hobject
Region of the images which are returned.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
Name of region file.
Default Value : ’region.reg’
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 2 (H_MSG_TRUE). Otherwise
an exception handling is raised.
Parallelization Information
write_region is reentrant and processed without parallelization.
Possible Predecessors
open_window, read_image, read_region, threshold, regiongrowing
See also
read_region
Module
Foundation

4.4 Text
close_all_files ( : : : )

Close all open files.


close_all_files closes all open files.
Attention
close_all_files exists solely for the purpose of implementing the “reset program” functionality in HDe-
velop. close_all_files must not be used in any application.
Result
If it is possible to close the files the operator close_all_files returns the value 2 (H_MSG_TRUE). Other-
wise an exception handling is raised.
Parallelization Information
close_all_files is processed completely exclusively without parallelization.
Alternatives
close_file
Module
Foundation

close_file ( : : 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 ; integer
File handle.

HALCON 8.0.2
102 CHAPTER 4. FILE

Example

open_file(’/tmp/data.txt’,’input’,FileHandle)
// ....
close_file(FileHandle).

Result
If the file handle is correct close_file returns the value 2 (H_MSG_TRUE). Otherwise an exception handling
is raised.
Parallelization Information
close_file is processed completely exclusively without parallelization.
Possible Predecessors
open_file
See also
open_file
Module
Foundation

fnew_line ( : : 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 ; integer
File handle.
Example

fwrite_string(FileHandle,’Good Morning’)
fnew_line(FileHandle)

Result
If an output file is open and it can be written to the file the operator fnew_line returns the value 2
(H_MSG_TRUE). Otherwise an exception handling is raised.
Parallelization Information
fnew_line is reentrant and processed without parallelization.
Possible Predecessors
fwrite_string
See also
fwrite_string
Module
Foundation

fread_char ( : : FileHandle : Char )

Read a character from a text file.


The operator fread_char reads a character from the current input file. If no character can be read because the
end of the file is reached, fread_char returns the character sequence ’eof’. At the end of a line the value ’nl’
is returned.

HALCON/HDevelop Reference Manual, 2008-5-13


4.4. TEXT 103

Parameter
. FileHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . file ; integer
File handle.
. Char (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Read character or control string (’nl’,’eof’).
Example

repeat >
fread_char(FileHandle:Char)
(if(Char = ’nl’) > fnew_line(FileHandle)) |
(if(Char != ’nl’) > fwrite_string(FileHandle,Char))
until(Char = ’eof’).

Result
If an input file is open the operator fread_char returns 2 (H_MSG_TRUE). Otherwise an exception handling is
raised.
Parallelization Information
fread_char is reentrant and processed without parallelization.
Possible Predecessors
open_file
Possible Successors
close_file
Alternatives
fread_string, read_string, fread_line
See also
open_file, close_file, fread_string, fread_line
Module
Foundation

fread_line ( : : FileHandle : OutLine, IsEOF )

Read a line from a text file.


The operator fread_line reads a line from the current input file (including the line skip). If the end of the file
is reached IsEOF returns the value 1, otherwise 0.
Attention
The maximum string length is 1024 character (including the end of string character).
Parameter
. FileHandle (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . file ; integer
File handle.
. OutLine (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Read line.
. IsEOF (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer ; integer
Reached end of file.
Example (Syntax: C)

do {
fread_line(FileHandle,&Line,&IsEOF) ;
} while(IsEOF==0) ;

Result
If the file is open and a suitable line is read fread_line returns the value 2 (H_MSG_TRUE). Otherwise an
exception handling is raised.

HALCON 8.0.2
104 CHAPTER 4. FILE

Parallelization Information
fread_line is reentrant and processed without parallelization.
Possible Predecessors
open_file
Possible Successors
close_file
Alternatives
fread_char, fread_string
See also
open_file, close_file, fread_char, fread_string
Module
Foundation

fread_string ( : : FileHandle : OutString, 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
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 ; integer


File handle.
. OutString (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Read character sequence.
. IsEOF (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer ; integer
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: ’,String])
fnew_line(FileHandle).

Result
If a file is open and a suitable string is read fread_string returns the value 2 (H_MSG_TRUE). Otherwise an
exception handling is raised.
Parallelization Information
fread_string is reentrant and processed without parallelization.
Possible Predecessors
open_file
Possible Successors
close_file
Alternatives
fread_char, read_string, fread_line
See also
open_file, close_file, fread_char, fread_line
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


4.4. TEXT 105

fwrite_string ( : : FileHandle, String : )

Write values in a text file.


The operator 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’, <boolean-value>:) 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 ; integer


File handle.
. String (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string(-array) ; string / integer / real
Values to be put out on the text file.
Default Value : ’hallo’
Example

fwrite_string(FileHandle,[’text with numbers:’,5,’ and ’,1.0]).


/* results in the following output: */
/* ’text with numbers:5 and 1.00000’ */

Result
If the writing procedure was carried out successfully the operator fwrite_string returns the value 2
(H_MSG_TRUE). Otherwise an exception handling is raised.
Parallelization Information
fwrite_string is reentrant and processed without parallelization.
Possible Predecessors
open_file
Possible Successors
close_file
Alternatives
write_string
See also
open_file, close_file, set_system
Module
Foundation

open_file ( : : FileName, FileType : FileHandle )

Open text file.


The operator open_file opens a file. FileType determines whether this file is an input (’input’) or output file
(’output’ or ’append’). open_file creates files which can be accessed either by reading (’input’) or by writing
(’output’ or ’append’) 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 ; string


Name of file to be opened.
Default Value : ’standard’
Suggested values : FileName ∈ {’standard’, ’error’, ’/tmp/dat.dat’}

HALCON 8.0.2
106 CHAPTER 4. FILE

. FileType (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string


Type of file.
Default Value : ’output’
List of values : FileType ∈ {’input’, ’output’, ’append’}
. FileHandle (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . file ; integer
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 2 (H_MSG_TRUE). Otherwise an ex-
ception handling is raised.
Parallelization Information
open_file is processed completely exclusively without parallelization.
Possible Successors
fwrite_string, fread_char, fread_string, fread_line, close_file
See also
close_file, fwrite_string, fread_char, fread_string, fread_line
Module
Foundation

4.5 Tuple

read_tuple ( : : FileName : Tuple )

Read a tuple from a file.


The operator read_tuple reads the contents of FileName and converts it into Tuple. The file has to be
generated by write_tuple.
Parameter

. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string


Name of the file to be read.
. Tuple (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number(-array) ; real / integer / string
Tuple with any kind of data.
Result
If the parameters are correct the operator read_tuple returns the value 2 (H_MSG_TRUE). Otherwise an
exception handling is raised.
Parallelization Information
read_tuple is reentrant and processed without parallelization.
Alternatives
fwrite_string
See also
write_tuple, gnuplot_plot_ctrl, write_image, write_region, open_file
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


4.6. XLD 107

write_tuple ( : : Tuple, FileName : )

Write a tuple to a file.


The operator 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) ; real / integer / string


Tuple with any kind of data.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
Name of the file to be written.
Result
If the parameters are correct the operator write_tuple returns the value 2 (H_MSG_TRUE). Otherwise an
exception handling is raised.
Parallelization Information
write_tuple is reentrant and processed without parallelization.
Alternatives
fwrite_string
See also
read_tuple, write_image, write_region, open_file
Module
Foundation

4.6 XLD
read_contour_xld_arc_info ( : Contours : 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
HALCON system variable ’image_dir’ (usually this is the content of the environment variable HALCONIMAGES)
are searched (see 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 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.read ; string
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_contour_xld_arc_info (LinesWorld, ’lines.gen’)
/* Transform the line data to image coordinates */
affine_trans_contour_xld (LinesWorld, Lines, ImageTransformation)

HALCON 8.0.2
108 CHAPTER 4. FILE

Result
If the parameters are correct and the file could be read, the operator read_contour_xld_arc_info returns
the value 2 (H_MSG_TRUE). Otherwise an exception is raised.
Parallelization Information
read_contour_xld_arc_info is reentrant and processed without parallelization.
Possible Successors
hom_mat2d_invert, affine_trans_contour_xld
See also
read_world_file, write_contour_xld_arc_info, read_polygon_xld_arc_info
Module
Foundation

read_contour_xld_dxf ( : Contours : FileName, GenParamNames,


GenParamValues : DxfStatus )

Read XLD contours from a DXF file.


read_contour_xld_dxf reads the contents of the DXF file FileName (DXF version AC1009, AutoCAD
Release 12) and converts them to the XLD contours Contours. If no absolute path is given in FileName the
DXF file is searched in the current directory of the HALCON process.
The output parameter DxfStatus contains information about the number of contours that were read and, if
necessary, warnings that parts of the DXF file could not be interpreted.
The operator read_contour_xld_dxf supports the following DXF entities:

• POLYLINE
– 2D curves made up of line segments
– Closed 2D curves made up of line segments
• LWPOLYLINE
• LINE
• POINT
• CIRCLE
• ARC
• ELLIPSE
• SPLINE
• BLOCK
• INSERT

The x and y coordinates of the DXF entities are stored in the column and row coordinates, respectively, of the XLD
contours Contours.
If the file has been created with the operator write_contour_xld_dxf, all attributes and global attributes that
were originally defined for the XLD contours are read. This means that read_contour_xld_dxf supports all
the extended data written by the operator write_contour_xld_dxf. The reading of these attributes can be
switched off by setting the generic parameter ’read_attributes’ to ’false’. Generic parameters are set by specifying
the parameter name(s) in GenParamNames and the corresponding value(s) in GenParamValues.
DXF entities of the type CIRCLE, ARC, ELLIPSE, and SPLINE are approximated by XLD contours. The
accuracy of this approximation can be controlled with the two generic parameters ’min_num_points’ and
’max_approx_error’ (for SPLINE only ’max_approx_error’). The parameter ’min_num_points’ defines the mini-
mum number of sampling points that are used for the approximation. Note that the parameter ’min_num_points’
always refers to the full circle or ellipse, respectively, even for ARCs or elliptical arcs, i.e., if ’min_num_points’ is
set to 50 and a DXF entity of the type ARC is read that represents a semi-circle, this semi-circle is approximated
by at least 25 sampling points. The parameter ’max_approx_error’ defines the maximum deviation of the XLD
contour from the ideal circle or ellipse, respectively (unit: pixel). For the determination of the accuracy of the

HALCON/HDevelop Reference Manual, 2008-5-13


4.6. XLD 109

approximation both criteria are evaluated. Then, the criterion that leads to the more accurate approximation is
used.
Internally, the following default values are used for the generic parameters:

’read_attributes’ = ’true’
’min_num_points’ = 20
’max_approx_error’ = 0.25

To achieve a more accurate approximation, either the value for ’min_num_points’ must be increased or the value
for ’max_approx_error’ must be decreased.
Parameter

. Contours (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_cont(-array) ; Hobject


Read XLD contours.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
Name of the DXF file.
. GenParamNames (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.name(-array) ; string
Names of the generic parameters that can be adjusted for the DXF input.
Default Value : []
List of values : GenParamNames ∈ {’read_attributes’, ’min_num_points’, ’max_approx_error’}
. GenParamValues (input_control) . . . . . . . . . . . . . . . . . . . . . . . . attribute.value(-array) ; real / integer / string
Values of the generic parameters that can be adjusted for the DXF input.
Default Value : []
Suggested values : GenParamValues ∈ {’true’, ’false’, 0.1, 0.25, 0.5, 1, 2, 5, 10, 20}
. DxfStatus (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string(-array) ; string
Status information.
Result
If the parameters are correct and the file could be read the operator read_contour_xld_dxf returns the value
2 (H_MSG_TRUE). Otherwise, an exception is raised.
Parallelization Information
read_contour_xld_dxf is reentrant and processed without parallelization.
Possible Predecessors
write_contour_xld_dxf
See also
write_contour_xld_dxf, read_polygon_xld_dxf, query_contour_attribs_xld,
query_contour_global_attribs_xld, get_contour_attrib_xld,
get_contour_global_attrib_xld
Module
Foundation

read_polygon_xld_arc_info ( : Polygons : 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
HALCON system variable ’image_dir’ (usually this is the content of the environment variable HALCONIMAGES)
are searched (see 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 read_world_file to read the transformation matrix from image to world
coordinates, and inverting this matrix by calling hom_mat2d_invert.

HALCON 8.0.2
110 CHAPTER 4. FILE

Parameter
. Polygons (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_poly(-array) ; Hobject
Read XLD polygons.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
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 2 (H_MSG_TRUE). Otherwise an exception is raised.
Parallelization Information
read_polygon_xld_arc_info is reentrant and processed without parallelization.
Possible Successors
hom_mat2d_invert, affine_trans_polygon_xld
See also
read_world_file, write_polygon_xld_arc_info, read_contour_xld_arc_info
Module
Foundation

read_polygon_xld_dxf ( : Polygons : FileName, GenParamNames,


GenParamValues : DxfStatus )

Read XLD polygons from a DXF file.


read_polygon_xld_dxf reads the contents of the DXF file FileName (DXF version AC1009, AutoCAD
Release 12) and converts them to the XLD polygons Polygons. If no absolute path is given in FileName the
DXF file is searched in the current directory of the HALCON process.
The output parameter DxfStatus contains information about the number of polygons that were read and, if
necessary, warnings that parts of the DXF file could not be interpreted.
The operator read_polygon_xld_dxf supports the following DXF entities:

• POLYLINE
– 2D curves made up of line segments
– Closed 2D curves made up of line segments
• LWPOLYLINE
• LINE
• POINT
• CIRCLE
• ARC
• ELLIPSE
• SPLINE
• BLOCK

HALCON/HDevelop Reference Manual, 2008-5-13


4.6. XLD 111

• INSERT

The x and y coordinates of the DXF entities are stored in the column and row coordinates, respectively, of the XLD
polygons Polygons.
DXF entities of the type CIRCLE, ARC, ELLIPSE, and SPLINE are approximated by XLD polygons. The
accuracy of this approximation can be controlled with the two generic parameters ’min_num_points’ and
’max_approx_error’ (for SPLINE only ’max_approx_error’). Generic parameters are set by specifying the pa-
rameter name(s) in GenParamNames and the corresponding value(s) in GenParamValues. The parameter
’min_num_points’ defines the minimum number of sampling points that are used for the approximation. Note that
the parameter ’min_num_points’ always refers to the full circle or ellipse, respectively, even for ARCs or elliptical
arcs, i.e., if ’min_num_points’ is set to 50 and a DXF entity of the type ARC is read that represents a semi-circle,
this semi-circle is approximated by at least 25 sampling points. The parameter ’max_approx_error’ defines the
maximum deviation of the XLD polygon from the ideal circle or ellipse, respectively (unit: pixel). For the deter-
mination of the accuracy of the approximation both criteria are evaluated. Then, the criterion that leads to the more
accurate approximation is used.
Internally, the following default values are used for the generic parameters:

’min_num_points’ = 20
’max_approx_error’ = 0.25

To achieve a more accurate approximation, either the value for ’min_num_points’ must be increased or the value
for ’max_approx_error’ must be decreased.
Note that reading a DXF file with read_polygon_xld_dxf results in exactly the same geometric information
as reading the file with read_contour_xld_dxf. However, the resulting data structure is different.
Parameter
. Polygons (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_poly(-array) ; Hobject
Read XLD polygons.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.read ; string
Name of the DXF file.
. GenParamNames (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attribute.name(-array) ; string
Names of the generic parameters that can be adjusted for the DXF input.
Default Value : []
List of values : GenParamNames ∈ {’min_num_points’, ’max_approx_error’}
. GenParamValues (input_control) . . . . . . . . . . . . . . . . . . . . . . . . attribute.value(-array) ; real / integer / string
Values of the generic parameters that can be adjusted for the DXF input.
Default Value : []
Suggested values : GenParamValues ∈ {0.1, 0.25, 0.5, 1, 2, 5, 10, 20}
. DxfStatus (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string(-array) ; string
Status information.
Result
If the parameters are correct and the file could be read the operator read_polygon_xld_dxf returns the value
2 (H_MSG_TRUE). Otherwise, an exception is raised.
Parallelization Information
read_polygon_xld_dxf is reentrant and processed without parallelization.
Possible Predecessors
write_polygon_xld_dxf
See also
write_polygon_xld_dxf, read_contour_xld_dxf
Module
Foundation

write_contour_xld_arc_info ( Contours : : FileName : )

Write XLD contours to a file in ARC/INFO generate format.

HALCON 8.0.2
112 CHAPTER 4. FILE

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 read_world_file.
Parameter

. Contours (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_cont(-array) ; Hobject


XLD contours to be written.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
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 2 (H_MSG_TRUE). Otherwise an exception is raised.
Parallelization Information
write_contour_xld_arc_info is reentrant and processed without parallelization.
Possible Predecessors
affine_trans_contour_xld
See also
read_world_file, read_contour_xld_arc_info, write_polygon_xld_arc_info
Module
Foundation

write_contour_xld_dxf ( Contours : : FileName : )

Write XLD contours to a file in DXF format.


write_contour_xld_dxf writes the XLD contours Contours to the file FileName in DXF format. If no
absolute path is given in FileName the output file is created in the current directory of the HALCON process.
Besides the geometry of the Contours, all attributes and global attributes that are defined for the Contours are
written to the file.
write_contour_xld_dxf writes the file according to the DXF version AC1009 (AutoCAD Release 12).
Each contour is stored as a POLYLINE. The attribute values are stored as extended data of each VERTEX of the
POLYLINE. The global attribute values are stored as extended data of the POLYLINE. All attribute names are also
stored as extended data of the POLYLINE.
The operator read_contour_xld_dxf can be used to read the XLD contours together with their attributes.
Other applications that are able to read DXF files only import the contour geometry, but they ignore the attribute
information.
Description of the format of the extended data
Each block of extended data starts with the following DXF group:
1001
HALCON

HALCON/HDevelop Reference Manual, 2008-5-13


4.6. XLD 113

The attributes are written in the following format as extended data of each VERTEX:

DXF Explanation
1000 Meaning
contour attributes
1002 Beginning of the value list
{
1070 Number of attributes (here: 3)
3
1040 Value of the first attribute
5.00434303
1040 Value of the second attribute
126.8638916
1040 Value of the third attribute
4.99164152
1002 End of the value list
}

The global attributes are written in the following format as extended data of each POLYLINE:

DXF Explanation
1000 Meaning
global contour attributes
1002 Beginning of the value list
{
1070 Number of global attributes (here: 5)
5
1040 Value of the first global attribute
0.77951831
1040 Value of the second global attribute
0.62637949
1040 Value of the third global attribute
103.94314575
1040 Value of the fourth global attribute
0.21434096
1040 Value of the fifth global attribute
0.21921949
1002 End of the value list
}

The names of the attributes are written in the following format as extended data of each POLYLINE:

DXF Explanation
1000 Meaning
names of contour attributes
1002 Beginning of the value list
{
1070 Number of attribute names (here: 3)
3
1000 Name of the first attribute
angle
1000 Name of the second attribute
response
1000 Name of the third attribute
edge_direction
1002 End of the value list
}

The names of the global attributes are written in the following format as extended data of each POLYLINE:

HALCON 8.0.2
114 CHAPTER 4. FILE

DXF Explanation
1000 Meaning
names of global contour attributes
1002 Beginning of the value list
{
1070 Number of global attribute names (here: 5)
5
1000 Name of the first global attribute
regr_norm_row
1000 Name of the second global attribute
regr_norm_col
1000 Name of the third global attribute
regr_dist
1000 Name of the fourth global attribute
regr_mean_dist
1000 Name of the fifth global attribute
regr_dev_dist
1002 End of the value list
}

Parameter

. Contours (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_cont(-array) ; Hobject


XLD contours to be written.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
Name of the DXF file.
Result
If the parameters are correct and the file could be written the operator write_contour_xld_dxf returns the
value 2 (H_MSG_TRUE). Otherwise, an exception is raised.
Parallelization Information
write_contour_xld_dxf is reentrant and processed without parallelization.
Possible Predecessors
edges_sub_pix
See also
read_contour_xld_dxf, write_polygon_xld_dxf, query_contour_attribs_xld,
query_contour_global_attribs_xld, get_contour_attrib_xld,
get_contour_global_attrib_xld
Module
Foundation

write_polygon_xld_arc_info ( Polygons : : 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
affine_trans_polygon_xld beforehand. The necessary transformation can be read from an ARC/INFO
world file with 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.

HALCON/HDevelop Reference Manual, 2008-5-13


4.6. XLD 115

Parameter

. Polygons (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_poly(-array) ; Hobject


XLD polygons to be written.
. FileName (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filename.write ; string
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 2 (H_MSG_TRUE). Otherwise an exception is raised.
Parallelization Information
write_polygon_xld_arc_info is reentrant and processed without parallelization.
Possible Predecessors
affine_trans_polygon_xld
See also
read_world_file, read_polygon_xld_arc_info, write_contour_xld_arc_info
Module
Foundation

write_polygon_xld_dxf ( Polygons : : FileName : )

Write XLD polygons to a file in DXF format.


write_polygon_xld_dxf writes the XLD polygons Polygons to the file FileName in DXF format. If no
absolute path is given in FileName the output file is created in the current directory of the HALCON process.
write_polygon_xld_dxf writes the file according to the DXF version AC1009 (AutoCAD Release 12).
Each polygon is stored as a POLYLINE.
The operator read_polygon_xld_dxf can be used to read the XLD polygon.
Attention
The XLD contours that are possibly referenced by Polygons are not stored in the DXF file. Therefore, when
the polygons are read again using read_polygon_xld_dxf, 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.write ; string
Name of the DXF file.
Result
If the parameters are correct and the file could be written the operator write_polygon_xld_dxf returns the
value 2 (H_MSG_TRUE). Otherwise, an exception is raised.
Parallelization Information
write_polygon_xld_dxf is reentrant and processed without parallelization.

HALCON 8.0.2
116 CHAPTER 4. FILE

Possible Predecessors
gen_polygons_xld
See also
read_polygon_xld_dxf, write_contour_xld_dxf
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


Chapter 5

Filter

5.1 Arithmetic
abs_image ( Image : 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 : int1 / int2 / int4 / real / complex
Image(s) for which the absolute gray values are to be calculated.
. ImageAbs (output_object) . . . . . . . . . . . . . . . (multichannel-)image(-array) ; Hobject : int1 / int2 / int4 / real
Result image(s).
Example

convert_image_type (Image, ImageInt2, ’int2’)


texture_laws (ImageInt2, ImageTexture, ’el’, 2, 5)
abs_image (ImageTexture, ImageTexture)

Result
The operator abs_image returns the value 2 (H_MSG_TRUE). The behavior in case of empty input (no input
images available) is set via the operator set_system(::’no_object_result’,<Result>:)
Parallelization Information
abs_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
See also
convert_image_type, power_byte
Module
Foundation

add_image ( Image1, Image2 : ImageResult : Mult, Add : )

Add two images.


The operator add_image adds two images. The gray values (g1, g2) of the input images (Image1 and Image2)
are transformed as follows:

g 0 := (g1 + g2) ∗ Mult + Add

117
118 CHAPTER 5. FILTER

If an overflow or an underflow occurs the values are clipped. This is not the case with int2 images if Mult is equal
to 1 and Add 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, uint2 or int4 images and to add int4 to int2 or uint2 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 combina-
tions special optimizations are used. Additionally, for byte, int2, uint2, and int4 images special optimizations are
implemented that use SIMD technology. The actual application of these special optimizations is controlled by the
system parameter ’mmx_enable’ (see set_system). If ’mmx_enable’ is set to ’true’ (and the SIMD instruction
set is available), the internal calculations are performed using SIMD technology.
Attention
Note that SIMD technology performs best on large, compact input regions. Depending on the input region and
the capabilities of the hardware the execution of add_image might even take significantly more time with
SIMD technology than without. In this case, the use of SIMD technology can be avoided by set_system(::
’mmx_enable’,’false’:).
Parameter
. Image1 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic / complex
Image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic / complex
Image(s) 2.
. ImageResult (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 /
int4 / real / direction / cyclic / com-
plex
Result image(s) by the addition.
. Mult (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Factor for gray value adaption.
Default Value : 0.5
Suggested values : 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
Minimum Increment : 0.001
Recommended Increment : 0.1
. Add (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Value for gray value range adaption.
Default Value : 0
Suggested values : Add ∈ {0, 64, 128, 255, 512}
Typical range of values : -512.0 ≤ Add ≤ 512.0
Minimum Increment : 0.01
Recommended Increment : 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 2 (H_MSG_TRUE) if the parameters are correct. The be-
havior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.

HALCON/HDevelop Reference Manual, 2008-5-13


5.1. ARITHMETIC 119

Parallelization Information
add_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
sub_image, mult_image
See also
sub_image, mult_image
Module
Foundation

div_image ( Image1, Image2 : ImageResult : Mult, Add : )

Divide two images.


The operator div_image divides two images. The gray values (g1, g2) of the input images (Image1) are
transformed as follows:

g 0 := g1/g2 ∗ Mult + Add

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 / uint2 / int4 / real
/ complex
Image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ complex
Image(s) 2.
. ImageResult (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 /
int4 / real / complex
Result image(s) by the division.
. Mult (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Factor for gray range adaption.
Default Value : 255
Suggested values : Mult ∈ {0.1, 0.2, 0.5, 1.0, 2.0, 3.0, 10, 100, 500, 1000}
Typical range of values : -1000 ≤ Mult ≤ 1000
Minimum Increment : 0.001
Recommended Increment : 1
. Add (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Value for gray range adaption.
Default Value : 0
Suggested values : Add ∈ {0.0, 128.0, 256.0, 1025}
Typical range of values : -1000 ≤ Add ≤ 1000
Minimum Increment : 0.01
Recommended Increment : 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)

HALCON 8.0.2
120 CHAPTER 5. FILTER

Result
The operator div_image returns the value 2 (H_MSG_TRUE) if the parameters are correct. The be-
havior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
div_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
add_image, sub_image, mult_image
See also
add_image, sub_image, mult_image
Module
Foundation

invert_image ( Image : 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:

g 0 = 255 − g

Images of the ’direction’ type are transformed by

g 0 = (g + 90) modulo 180

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 / direction / cyclic / int1 / int2 /


uint2 / int4 / real
Input image(s).
. ImageInvert (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic /
int1 / int2 / uint2 / int4 / real
Image(s) with inverted gray values.
Example

read_image(Orig,"fabrik")
invert_image(Orig,Invert)
disp_image(Invert,WindowHandle).

Parallelization Information
invert_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successors
watersheds
Alternatives
scale_image
See also
scale_image, add_image, sub_image
Module
Foundation

HALCON/HDevelop Reference Manual, 2008-5-13


5.1. ARITHMETIC 121

max_image ( Image1, Image2 : 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.
Attention
The two input images must be of the same type and size.
Parameter

. Image1 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic
Image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic
Image(s) 2.
. ImageMax (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 /
real / direction / cyclic
Result image(s) by the maximization.
Example

read_image(Bild1,"affe")
read_image(Bild2,"fabrik")
max_image(Bild1,Bild2,Max)
disp_image(Max,WindowHandle)

Result
If the parameter values are correct the operator max_image returns the value 2 (H_MSG_TRUE). The
behavior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:). If necessary an exception handling is raised.
Parallelization Information
max_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
max_image
See also
min_image
Module
Foundation

min_image ( Image1, Image2 : 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.

HALCON 8.0.2
122 CHAPTER 5. FILTER

Parameter

. Image1 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic
Image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic
Image(s) 2.
. ImageMin (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 /
real / direction / cyclic
Result image(s) by the minimization.
Result
If the parameter values are correct the operator min_image returns the value 2 (H_MSG_TRUE). The
behavior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
min_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
gray_erosion
See also
max_image, min_image
Module
Foundation

mult_image ( Image1, Image2 : ImageResult : Mult, Add : )

Multiply two images.


mult_image multiplies two images. The gray values (g1, g2) of the input images (Image1) are transformed as
follows:

g 0 := g1 ∗ g2 ∗ Mult + Add

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 / uint2 / int4 / real
/ direction / cyclic / complex
Image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
/ direction / cyclic / complex
Image(s) 2.
. ImageResult (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 /
int4 / real / direction / cyclic / com-
plex
Result image(s) by the product.
. Mult (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Factor for gray range adaption.
Default Value : 0.005
Suggested values : 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
Minimum Increment : 0.001
Recommended Increment : 0.1

HALCON/HDevelop Reference Manual, 2008-5-13


5.1. ARITHMETIC 123

. Add (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer


Value for gray range adaption.
Default Value : 0
Suggested values : Add ∈ {0.0, 128.0, 256.0}
Typical range of values : -512.0 ≤ Add ≤ 512.0
Minimum Increment : 0.01
Recommended Increment : 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)

Result
The operator mult_image returns the value 2 (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’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
mult_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
add_image, sub_image, div_image
See also
add_image, sub_image, div_image
Module
Foundation

scale_image ( Image : ImageScaled : Mult, Add : )

Scale the gray values of an image.


The operator scale_image scales the input images (Image) by the following transformation:

g 0 := g ∗ Mult + Add

If an overflow or an underflow occurs the values are clipped.


This operator can be applied, e.g., to map the gray values of an image, i.e., the interval [GMin,GMax], to the
maximum range [0:255]. For this, the parameters are chosen as follows:

255
Mult = Add = −Mult ∗ GMin
GMax − GMin
The values for GMin and GMax can be determined, e.g., with the operator min_max_gray.
Please note that the runtime of the operator varies with different control parameters. For frequently used combi-
nations special optimizations are used. Additionally, special optimizations are implemented that use fixed point
arithmetic (for int2 and uint2 images), and further optimizations that use SIMD technology (for byte, int2, and uint2
images). The actual application of these special optimizations is controlled by the system parameters ’int_zooming’
and ’mmx_enable’ (see set_system). If ’int_zooming’ is set to ’true’, the internal calculation is performed us-
ing fixed point arithmetic, leading to much shorter execution times. However, the accuracy of the transformed
gray values is slightly lower in this mode. The difference to the more accurate calculation (using ’int_zooming’
= ’false’) is typically less than two gray levels. If ’mmx_enable’ is set to ’true’(and the SIMD instruction set is
available), the internal calculations are performed using fixed point arithmetic and SIMD technology. In this case
the setting of ’int_zooming’ is ignored.

HALCON 8.0.2
124 CHAPTER 5. FILTER

Attention
Note that SIMD technology performs best on large, compact input regions. Depending on the input region and
the capabilities of the hardware the execution of scale_image might even take significantly more time with
SIMD technology than without. In this case, the use of SIMD technology can be avoided by set_system(::
’mmx_enable’,’false’:).
Parameter
. Image (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real /
direction / cyclic / complex
Image(s) whose gray values are to be scaled.
. ImageScaled (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 /
int4 / real / direction / cyclic / com-
plex
Result image(s) by the scale.
. Mult (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Scale factor.
Default Value : 0.01
Suggested values : 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}
Minimum Increment : 0.001
Recommended Increment : 0.1
. Add (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Offset.
Default Value : 0
Suggested values : Add ∈ {0, 10, 50, 100, 200, 500}
Minimum Increment : 0.01
Recommended Increment : 1.0
Example

/* Complement of the gray values: */


scale_image(Bild,Invert,-1.0,255.0,)

Result
The operator scale_image returns the value 2 (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’,<Result>:) Otherwise an exception treatment is carried out.
Parallelization Information
scale_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Predecessors
min_max_gray
Alternatives
mult_image, add_image, sub_image
See also
min_max_gray
Module
Foundation

sqrt_image ( Image : SqrtImage : : )

Calculate the square root of an image.


sqrt_image calculates the square root of an input image Image and stores the result in the image SqrtImage
of the same pixel type. In case the picture Image is of a signed pixel type, negative pixel values will be mapped
to zero in SqrtImage.

HALCON/HDevelop Reference Manual, 2008-5-13


5.1. ARITHMETIC 125

Parameter

. Image (input_object) . . . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 / real
Input image
. SqrtImage (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4
/ real
Output image
Parallelization Information
sqrt_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Module
Foundation

sub_image ( ImageMinuend, ImageSubtrahend : ImageSub : Mult, Add : )

Subtract two images.


The operator sub_image subtracts two images. The gray values (g1, g2) of the input images (ImageMinuend
and ImageSubtrahend) are transformed as follows:

g 0 := (g1 − g2) ∗ Mult + Add

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.
Please note that the runtime of the operator varies with different control parameters. For frequently used com-
binations special optimizations are used. Additionally, for byte, int2, and uint2 images special optimizations are
implemented that use SIMD technology. The actual application of these special optimizations is controlled by the
system parameter ’mmx_enable’ (see set_system). If ’mmx_enable’ is set to ’true’ (and the SIMD instruction
set is available), the internal calculations are performed using SIMD technology.
Attention
Note that SIMD technology performs best on large, compact input regions. Depending on the input region and
the capabilities of the hardware the execution of sub_image might even take significantly more time with
SIMD technology than without. In this case, the use of SIMD technology can be avoided by set_system(::
’mmx_enable’,’false’:).
Parameter

. ImageMinuend (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 /


int4 / real / direction / cyclic / com-
plex
Minuend(s).
. ImageSubtrahend (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 /
uint2 / int4 / real / direction /
cyclic / complex
Subtrahend(s).
. ImageSub (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / int1 / int2 / uint2 / int4 /
real / direction / cyclic / complex
Result image(s) by the subtraction.
. Mult (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Correction factor.
Default Value : 1.0
Suggested values : Mult ∈ {0.0, 1.0, 2.0, 3.0, 4.0}
Typical range of values : -255.0 ≤ Mult ≤ 255.0
Minimum Increment : 0.001
Recommended Increment : 0.1

HALCON 8.0.2
126 CHAPTER 5. FILTER

. Add (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer


Correction value.
Default Value : 128.0
Suggested values : Add ∈ {0.0, 128.0, 256.0}
Typical range of values : -512.0 ≤ Add ≤ 512.0
Minimum Increment : 0.01
Recommended Increment : 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)

Result
The operator sub_image returns the value 2 (H_MSG_TRUE) if the parameters are correct. The be-
havior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
sub_image is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successors
dual_threshold
Alternatives
mult_image, add_image, sub_image
See also
add_image, mult_image, dyn_threshold, check_difference
Module
Foundation

5.2 Bit
bit_and ( Image1, Image2 : 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, unsigned 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 / direction / cyclic / int1 / int2


/ uint2 / int4
Input image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 / int2
/ uint2 / int4
Input image(s) 2.
. ImageAnd (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 /
int2 / uint2 / int4
Result image(s) by AND-operation.

HALCON/HDevelop Reference Manual, 2008-5-13


5.2. BIT 127

Example

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).

Result
If the images are correct (type and number) the operator bit_and returns the value 2 (H_MSG_TRUE).
The behavior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_and is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
bit_mask, add_image, max_image
See also
bit_mask, add_image, max_image
Module
Foundation

bit_lshift ( Image : ImageLShift : 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 (“«“) for the respective types (signed char, unsigned char, short,
unsigned short, int/long). If an overflow occurs the result is limited to the maximum value of the respective pixel
type. 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 / direction / cyclic / int1 / int2 /
uint2 / int4
Input image(s).
. ImageLShift (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic /
int1 / int2 / uint2 / int4
Result image(s) by shift operation.
. Shift (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Shift value.
Default Value : 3
Suggested values : Shift ∈ {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
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Shift ≥ 1) ∧ (Shift ≤ 31)
Example (Syntax: C)

read_image(&ByteImage,"fabrik");
convert_image_type(ByteImage,&Int2Image,"int2");
bit_lshift(Int2Image,&FullInt2Image,8);

Result
If the images are correct (type) and if Shift has a valid value the operator bit_lshift returns the value

HALCON 8.0.2
128 CHAPTER 5. FILTER

2 (H_MSG_TRUE). The behavior in case of empty input (no input images available) is set via the operator
set_system(::’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_lshift is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
scale_image
See also
bit_rshift
Module
Foundation

bit_mask ( Image : ImageMask : BitMask : )

Logical “AND” of each pixel using a bit mask.


The operator bit_mask carries out an “and” operation of each pixel with a fixed mask. The semantics of the
“and” operation corresponds to that of C for the respective types (signed char, unsigned char, unsigned short, 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 / direction / cyclic / int1 / int2 /


uint2 / int4
Input image(s).
. ImageMask (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1
/ int2 / uint2 / int4
Result image(s) by combination with mask.
. BitMask (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Bit field
Default Value : 128
List of values : BitMask ∈ {1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096}
Suggested values : 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 2 (H_MSG_TRUE). The be-
havior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_mask is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successors
threshold, bit_or
Alternatives
bit_slice
See also
bit_and, bit_lshift
Module
Foundation

bit_not ( Image : 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,

HALCON/HDevelop Reference Manual, 2008-5-13


5.2. BIT 129

short, unsigned 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 / direction / cyclic / int1 / int2 /
uint2 / int4
Input image(s).
. ImageNot (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 /
int2 / uint2 / int4
Result image(s) by complement operation.
Example

read_image(Image0,’affe’)
disp_image(Image0,WindowHandle)
bit_not(Image0,ImageBitN)
disp_image(ImageBitN,WindowHandle).

Result
If the images are correct (type) the operator bit_not returns the value 2 (H_MSG_TRUE). The be-
havior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_not is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
bit_or, bit_and, add_image
See also
bit_slice, bit_mask
Module
Foundation

bit_or ( Image1, Image2 : 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, unsigned 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 / direction / cyclic / int1 / int2
/ uint2 / int4
Input image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 / int2
/ uint2 / int4
Input image(s) 2.
. ImageOr (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 /
int2 / uint2 / int4
Result image(s) by OR-operation.
Example

read_image(Image0,’affe’)
disp_image(Image0,WindowHandle)

HALCON 8.0.2
130 CHAPTER 5. FILTER

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 2 (H_MSG_TRUE).
The behavior in case of empty input (no input images available) is set via the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_or is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
bit_and, add_image
See also
bit_xor, bit_and
Module
Foundation

bit_rshift ( Image : ImageRShift : 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, unsigned 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 / direction / cyclic / int1 / int2 /
uint2 / int4
Input image(s).
. ImageRShift (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic /
int1 / int2 / uint2 / int4
Result image(s) by shift operation.
. Shift (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
shift value
Default Value : 3
Suggested values : 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
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Shift ≥ 1) ∧ (Shift ≤ 31)
Example (Syntax: C)

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
2 (H_MSG_TRUE). The behavior in case of empty input (no input images available) is set via the operator
set_system(::’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_rshift is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
scale_image

HALCON/HDevelop Reference Manual, 2008-5-13


5.2. BIT 131

See also
bit_lshift
Module
Foundation

bit_slice ( Image : ImageSlice : 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, unsigned 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 / direction / cyclic / int1 / int2 /


uint2 / int4
Input image(s).
. ImageSlice (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic /
int1 / int2 / uint2 / int4
Result image(s) by extraction.
. Bit (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Bit to be selected.
Default Value : 8
Suggested values : 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
Minimum Increment : 1
Recommended Increment : 1
Restriction : (Bit ≥ 1) ∧ (Bit ≤ 32)
Example (Syntax: C)

read_image(&ByteImage,"fabrik");
for (bit=1; bit<=8; i++)
{
bit_slice(ByteImage,&Slice,bit);
threshold(Slice,&Region,0,255);
disp_region(Region,WindowHandle);
clear(bit_slice); clear(Slice); clear(Region);
}

Result
If the images are correct (type) and Bit has a valid value, the operator bit_slice returns the value 2
(H_MSG_TRUE). The behavior in case of empty input (no input images available) is set via the operator
set_system(::’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_slice is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successors
threshold, bit_or
Alternatives
bit_mask
See also
bit_and, bit_lshift
Module
Foundation

HALCON 8.0.2
132 CHAPTER 5. FILTER

bit_xor ( Image1, Image2 : ImageXor : : )

Bit-by-bit XOR of all pixels of the input images.


The operator bit_xor calculates the “xor” of all pixels of the input images bit by bit. The semantics of the
“xor” operation corresponds to that of C for the respective types (signed char, unsigned char, short, unsigned 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 / direction / cyclic / int1 / int2
/ uint2 / int4
Input image(s) 1.
. Image2 (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 / int2
/ uint2 / int4
Input image(s) 2.
. ImageXor (output_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 /
int2 / uint2 / int4
Result image(s) by XOR-operation.
Example

read_image(Image0,’affe’)
disp_image(Image0,WindowHandle)
read_image(Image1,’fabrik’)
disp_image(Image1,WindowHandle)
bit_xor(Image0,Image1,ImageBitX)
disp_image(ImageBitX,WindowHandle).

Result
If the parameter values are correct the operator bit_xor returns the value 2 (H_MSG_TRUE). The behav-
ior in case of empty input (no input images available) can be determined by the operator set_system(::
’no_object_result’,<Result>:) If necessary an exception handling is raised.
Parallelization Information
bit_xor is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Alternatives
bit_or, bit_and, add_image
See also
bit_or, bit_and
Module
Foundation

5.3 Color
cfa_to_rgb ( CFAImage : RGBImage : CFAType, Interpolation : )

Convert a single-channel color filter array image into an RGB image.


cfa_to_rgb converts a single-channel color filter array image CFAImage into an RGB image RGBImage.
Color filter array images are typically generated by single-chip CCD cameras. The conversion from color filter
array image to RGB image is typically done on the camera itself or is performed by the device driver of the
frame grabber that is used to grab the image. In some cases, however, the device driver simply passes the color
filter array image through unchanged. In this case, the corresponding HALCON frame grabber interface typically
converts the image into an RGB image. Hence, the operator cfa_to_rgb is normally used if the images are not
being grabbed using the HALCON frame grabber interface ( grab_image or grab_image_async), but are

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 133

grabbed using function calls from the frame grabber SDK, and are passed to HALCON using gen_image1 or
gen_image1_extern.
In single-chip CCD cameras, a color filter array in front of the sensor provides (subsampled) color information.
The most frequently used filter is the so called Bayer filter. The color filter array has the following layout in this
case:

G B G B G B ···

R G R G R G ···

G B G B G B ···

R G R G R G ···
.. .. .. .. .. .. ..
. . . . . . .

Each gray value of the input image CFAImage corresponds to the brightness of the pixel behind the corresponding
color filter. Hence, in the above layout, the pixel (0,0) corresponds to a green color value, while the pixel (0,1)
corresponds to a blue color value. The layout of the Bayer filter is completely determined by the first two elements
of the first row of the image, and can be chosen with the parameter CFAType. In particular, this enables the correct
conversion of color filter array images that have been cropped out of a larger image (e.g., using crop_part or
crop_rectangle1). The algorithm that is used to interpolate the RGB values is determined by the parameter
Interpolation. Currently, the only possible choice is ’bilinear’.
Parameter
. CFAImage (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image ; Hobject : byte / uint2
Input image.
. RGBImage (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image ; Hobject : byte / uint2
Output image.
. CFAType (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Color filter array type.
Default Value : ’bayer_gb’
List of values : CFAType ∈ {’bayer_gb’, ’bayer_gr’, ’bayer_bg’, ’bayer_rg’}
. Interpolation (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Interpolation type.
Default Value : ’bilinear’
List of values : Interpolation ∈ {’bilinear’}
Result
cfa_to_rgb returns 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the behavior can
be set via set_system(::’no_object_result’,<Result>:). If necessary, an exception handling is
raised.
Parallelization Information
cfa_to_rgb is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessors
gen_image1_extern, gen_image1, grab_image
Possible Successors
decompose3
See also
trans_from_rgb
Module
Foundation

gen_principal_comp_trans ( MultichannelImage : : : Trans, TransInv,


Mean, Cov, InfoPerComp )

Compute the transformation matrix of the principal component analysis of multichannel images.

HALCON 8.0.2
134 CHAPTER 5. FILTER

gen_principal_comp_trans computes the transformation matrix of a principal components analysis of


multichannel 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 gen_principal_comp_trans takes one or more multichannel images
MultichannelImage and computes the transformation matrix Trans for the principal components
analysis, as well as its inverse TransInv. All input images must have the same number of channels.
The principal components analysis is performed based on the collection of data of all images. Hence,
gen_principal_comp_trans facilitates using the statistics of multiple images.
If n is the number of channels, Trans and TransInv are matrices of dimension n × (n + 1), which describe
an affine transformation of the multichannel gray values. They can be used to transform a multichannel image
with linear_trans_color. For information purposes, the mean gray value of the channels and the n × n
covariance matrix of the channels are returned in Mean and Cov, respectively. The parameter InfoPerComp
contains the relative information content of each output channel.
Parameter
. MultichannelImage (input_object) . . . . . . multichannel-image(-array) ; Hobject : byte / direction /
cyclic / int1 / int2 / uint2 / int4
/ real
Multichannel input image.
. Trans (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Transformation matrix for the computation of the PCA.
. TransInv (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Transformation matrix for the computation of the inverse PCA.
. Mean (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Mean gray value of the channels.
. Cov (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Covariance matrix of the channels.
. InfoPerComp (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Information content of the transformed channels.
Result
The operator gen_principal_comp_trans returns the value 2 (H_MSG_TRUE) if the parameters are cor-
rect. Otherwise an exception is raised.
Parallelization Information
gen_principal_comp_trans is reentrant and processed without parallelization.
Possible Successors
linear_trans_color
Alternatives
principal_comp
Module
Foundation

linear_trans_color ( Image : ImageTrans : TransMat : )

Compute an affine transformation of the color values of a multichannel image.


linear_trans_color performs an affine transformation of the color values of the multichannel image Image
and returns the result in ImageTrans. The affine transformation of the color values is described by the transfor-
mation matrix TransMat. If n is the number of channels in Image, TransMat is a homogeneous n × (n + 1)
that is stored row by row. Homogeneous means that the left n × n submatrix of TransMat describes a linear
transformation of the color values, while the last column of TransMat describes a constant offset of the color val-
ues. The transformation matrix is typically computed with gen_principal_comp_trans. It can, however,
also be specified directly. For example, a transformation from RGB to YIQ, which is described by the following
transformation

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 135

      
Y 0.299 0.587 0.144 R 0
 I  =  0.595 −0.276 −0.333   G  +  128 
Q 0.209 −0.522 0.287 B 128

can be achieved by setting TransMat to

[0.299, 0.587, 0.144, 0.0, 0.595, −0.276, −0.333, 128.0, 0.209, −0.522, 0.287, 128.0]

Here, it should be noted that the above transformation is unnormalized, i.e., the resulting color values can lie
outside the range [0, 255]. The transformation ’yiq’ in trans_from_rgb additionally scales the rows of the
matrix (except for the constant offset) appropriately.
To avoid a loss of information, linear_trans_color returns an image of type real. If a different image type
is desired, the image can be transformed with convert_image_type.
Parameter
. Image (input_object) . . . . . . multichannel-image(-array) ; Hobject : byte / direction / cyclic / int1 / int2 /
uint2 / int4 / real
Multichannel input image.
. ImageTrans (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .multichannel-image(-array) ; Hobject : real
Multichannel output image.
. TransMat (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real
Transformation matrix for the color values.
Result
The operator linear_trans_color returns the value 2 (H_MSG_TRUE) if the parameters are correct. Oth-
erwise an exception is raised.
Parallelization Information
linear_trans_color is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessors
gen_principal_comp_trans
Possible Successors
convert_image_type
Alternatives
principal_comp, trans_from_rgb, trans_to_rgb
Module
Foundation

principal_comp ( MultichannelImage : PCAImage : : InfoPerComp )

Compute the principal components of multichannel images.


principal_comp does a principal components analysis of multichannel 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 principal_comp takes a (multichannel) 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 / direction / cyclic /
int1 / int2 / uint2 / int4 / real
Multichannel input image.
. PCAImage (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multichannel-image ; Hobject : real
Multichannel output image.

HALCON 8.0.2
136 CHAPTER 5. FILTER

. InfoPerComp (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real-array ; real


Information content of each output channel.
Result
The operator principal_comp returns the value 2 (H_MSG_TRUE) if the parameters are correct. Otherwise
an exception is raised.
Parallelization Information
principal_comp is reentrant and processed without parallelization.
Alternatives
gen_principal_comp_trans
See also
linear_trans_color
Module
Foundation

rgb1_to_gray ( RGBImage : 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:

k = 0.299r + 0.587g + 0.114b .

Parameter

. RGBImage (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2


Three-channel RBG image.
. GrayImage (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2
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).
Possible Predecessors
compose3
Alternatives
trans_from_rgb, rgb3_to_gray
Module
Foundation

rgb3_to_gray ( ImageRed, ImageGreen, ImageBlue : 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/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 137

k = 0.299r + 0.587g + 0.114b .

Parameter

. ImageRed (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2


Input image (red channel).
. ImageGreen (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2
Input image (green channel).
. ImageBlue (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2
Input image (blue channel).
. ImageGray (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / int2 / uint2
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).
Possible Predecessors
decompose3
Alternatives
rgb1_to_gray, trans_from_rgb
Module
Foundation

trans_from_rgb ( ImageRed, ImageGreen, ImageBlue : ImageResult1,


ImageResult2, ImageResult3 : 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 operator trans_from_rgb supports the image types byte, uint2, int4, and real. In the case of int4 images,
the images should not contain negative values. In the case of real images, all values should lay within 0 and 1. If
not, the results of the transformation may not be reasonable.
Certain scalings are performed accordingly to the image type:

• Considering byte and uint2 images, the domain of color space values is generally mapped to the full domain
of [0..255] resp. [0..65535]. Because of this, the origin of signed values (e.g., CIELab or YIQ) may not be at
the center of the domain.
• Hue values are represented by angles of [0..2π] and are coded for the particular image types differently:
– byte-images map the angle domain on [0..255].
– uint2/int4-images are coded in angle minutes [0..21600].
– real-images are coded in radians [0..2π] .
• Saturation values are represented by percentages of [0..100] and are coded for the particular image type
differently:
– byte-images map the saturation values to [0..255].

HALCON 8.0.2
138 CHAPTER 5. FILTER

– uint2/int4-images map the the saturation values to [0..10000].


– real-images map the saturation values to [0..1].

The following transformations are supported:


(All range of values are based on RGB values scaled to [0;1]. To obtain the range of values for a certain image
type, they must be multiplied with the maximum of the image type, e.g., 255 in the case of a byte image)
’yiq’
    
Y 0.299 0.587 0.144 R
 I  =  0.595 −0.276 −0.333   G 
Q 0.209 −0.522 0.287 B

Range of values:
Y ∈ [0; 1.03], I ∈ [−0.609; 0.595], Q ∈ [−0.522; 0.496]

Point of origin for image type byte:


I0 = 128.89, Q0 = 130.71
’yuv’
    
Y 0.299 0.587 0.114 R
 U  =  −0.147 −0.289 0.436   G 
V 0.615 −0.515 0.100 B

Range of values:
Y ∈ [0; 1], U ∈ [−0.436; 0.436], V ∈ [−0.615; 0.496]

’argyb’
    
A 0.30 0.59 0.11 R
 Rg  =  0.50 −0.50 0.00   G 
Yb 0.25 0.25 −0.50 B

Range of values:
A ∈ [0; 1], Rg ∈ [−0.5; 0.5], Y b ∈ [−0.5; 0.5]

’ciexyz’
    
X 0.412453 0.357580 0.180423 R
 Y  =  0.212671 0.715160 0.072169   G 
Z 0.019334 0.119193 0.950227 B

The primary colors used correspond to sRGB respectively CIE Rec. 709. D65 is used as white point.
Used primary
 colors (x, y, z):      
0.6400 0.3000 0.1500 0.3127
red:= , green:= , blue:= , white65 :=
0.3300 0.6000 0.0600 0.3290
Range of values:
X ∈ [0; 0.950456], Y ∈ [0; 1], Z ∈ [0; 1.088754]
’hls’ 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)

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 139

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
Range of values:
H ∈ [0; 2π], L ∈ [0; 1], S ∈ [0; 1]

’hsi’
  √2 −1 −1

√ √
 
M1 6 6 6 R
√1 −1
 M2  = 
 0 2

2

 G 
I1 √1 √1 √1 B
3 3 3
   M2 
H √arctan M 1
 S  =  M 12 + M 22 
I1
I √
3

Range of values: q
2
H ∈ [0; 2π], S ∈ [0; 3 ], I ∈ [0; 1]

’hsv’ 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
Range of values:
H ∈ [0; 2π], S ∈ [0; 1], V ∈ [0; 1]

’ihs’ 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)
C = sqrt(B)
if (C == 0)
H = 0

HALCON 8.0.2
140 CHAPTER 5. FILTER

else
H = acos(A / C)
fi
if (B > G)
H = 2 * pi - H
fi
fi
fi
Range of values:
I ∈ [0; 1], H ∈ [0; 2π], S ∈ [0; 1]

’cielab’
    
X 0.412453 0.357580 0.180423 R
 Y  =  0.212671 0.715160 0.072169   G 
Z 0.019334 0.119193 0.950227 B

Y
L = 116 ∗ f () − 16
Yw
X Y
a = 500 ∗ (f ( ) − f ( ))
Xw Yw
Y Z
b = 200 ∗ (f ( ) − f ( ))
Yw Zw
where 1 24 3
f (t) = t 3 , t > ( 116 )
841 16
f (t) = 108 ∗ t + 116 , otherwise
Black point B:
(Rb , Gb , Bb ) = (0, 0, 0)
White point W = (Rw , Gw , Bw ), according to image type:
Wbyte = (255, 255, 255), Wuint2 = (216 − 1, 216 − 1, 216 − 1),
Wint4 = (231 − 1, 231 − 1, 231 − 1), Wreal = (1.0, 1.0, 1.0)
Range of values:
L ∈ [0; 100], a ∈ [−86.1813; 98.2352], b ∈ [−107.8617; 94.4758]
(Scaled to the maximum gray value in the case of byte and uint2. In the case of int4 L and a are scaled
to the maximum gray value, b is scaled to the minimum gray value, such that the origin stays at 0.)
’i1i2i3’
    
I1 0.333 0.333 0.333 R
 I2  =  1.0 0.0 −1.0   G 
I3 −0.5 1.0 −0.5 B

Range of values:
I1 ∈ [0; 1], I2 ∈ [−1; 1], I3 ∈ [−1; 1]

’ciexyz2’
    
X 0.620 0.170 0.180 R
 Y  =  0.310 0.590 0.110   G 
Z 0.000 0.066 1.020 B

Range of values:
X ∈ [0; 0.970], Y ∈ [0; 1.010], Z ∈ [0; 1.086]

’ciexyz3’
    
X 0.618 0.177 0.205 R
 Y  =  0.299 0.587 0.114   G 
Z 0.000 0.056 0.944 B

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 141

Range of values:
X ∈ [0; 1], Y ∈ [0; 1], Z ∈ [0; 1]

’ciexyz4’
    
X 0.476 0.299 0.175 R
 Y  =  0.262 0.656 0.082   G 
Z 0.020 0.161 0.909 B

 colors(x, y, z):
Used primary      
0.628 0.268 0.150 0.313
red:=  0.346  , green:=  0.588  , blue:=  0.070  , white65 :=  0.329 
0.026 0.144 0.780 0.358
Range of values:
X ∈ [0; 0.951], Y ∈ [0; 1], Z ∈ [0; 1.088]

Parameter
. ImageRed (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (red channel).
. ImageGreen (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (green channel).
. ImageBlue (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (blue channel).
. ImageResult1 (output_object) . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Color-transformed output image (channel 1).
. ImageResult2 (output_object) . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Color-transformed output image (channel 1).
. ImageResult3 (output_object) . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Color-transformed output image (channel 1).
. ColorSpace (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Color space of the output image.
Default Value : ’hsv’
List of values : ColorSpace ∈ {’cielab’, ’hsv’, ’hsi’, ’yiq’, ’yuv’, ’argyb’, ’ciexyz’, ’ciexyz2’, ’ciexyz3’,
’ciexyz4’, ’hls’, ’ihs’, ’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 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the behaviour
can be set via set_system(::’no_object_result’,<Result>:). If necessary, an exception handling
is raised.
Parallelization Information
trans_from_rgb is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessors
decompose3
Possible Successors
compose3
Alternatives
rgb1_to_gray, rgb3_to_gray

HALCON 8.0.2
142 CHAPTER 5. FILTER

See also
trans_to_rgb
Module
Foundation

trans_to_rgb ( ImageInput1, ImageInput2, ImageInput3 : ImageRed,


ImageGreen, ImageBlue : 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 operator trans_to_rgb supports the image types byte, uint2, int4, and real. The domain of the input
images must match the domain provided by a corresponding transformation with trans_from_rgb. If not, the
results of the transformation may not be reasonable.
This includes some scalings in the case of certain image types and transformations:

• Considering byte and uint2 images, the domain of color space values is expected to be spread to the full
domain of [0..255] resp. [0..65535]. This includes a shift in the case of signed values, such that the origin of
signed values (e.g. CIELab or YIQ) may not be at the center of the domain.
• Hue values are represented by angles of [0..2π] and are coded for the particular image types differently:
– byte-images map the angle domain on [0..255].
– uint2/int4-images are coded in angle minutes [0..21600].
– real-images are coded in radians [0..2π] .
• Saturation values are represented by percentages of [0..100] and are coded for the particular image type
differently:
– byte-images map the saturation values to [0..255].
– uint2/int4-images map the the saturation values to [0..10000].
– real-images map the saturation values to [0..1].
The following transformations are supported:
(All domains are based on RGB values scaled to [0;1]. To obtain the domains for a certain image type, they must
be multiplied with the maximum of the image type, e.g. 255 in the case of a byte image)
’yiq’
    
R 0.999 0.962 0.615 Y
 G  =  0.949 −0.220 −0.732   I 
B 0.999 −1.101 1.706 Q
Domain:
Y ∈ [0; 1.03], I ∈ [−0.609; 0.595], Q ∈ [−0.522; 0.496]

Point of origin for image type byte:


I0 = 128.89, Q0 = 130.71
’yuv’
    
R 1.0 0.0 1.140 Y
 G  =  1.0 −0.394 −0.581   U 
B 1.0 2.032 0.0 V
Domain:
Y ∈ [0; 1], U ∈ [−0.436; 0.436], V ∈ [−0.615; 0.496]

’argyb’
    
R 1.00 1.29 0.22 A
 G  =  1.00 −0.71 0.22   Rg 
B 1.00 0.29 −1.78 Yb

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 143

Domain:
A ∈ [0; 1], Rg ∈ [−0.5; 0.5], Y b ∈ [−0.5; 0.5]

’ciexyz’
    
R 3.240479 −1.53715 −0.498535 X
 G  =  −0.969256 1.875991 0.041556   Y 
B 0.055648 −0.204043 1.057311 Z

The primary colors used correspond to sRGB respectively CIE Rec. 709. D65 is used as white point.
Used primary
 colors (x, y, z):      
0.6400 0.3000 0.1500 0.3127
red:= , green:= , blue:= , white65 :=
0.3300 0.6000 0.0600 0.3290
Domain:
X ∈ [0; 0.950456], Y ∈ [0; 1], Z ∈ [0; 1.088754]
’cielab’
fy = (L + 16)/116
fx = a/500 + fy
fz = b/200 − fy

24
X = Xw ∗ fx3 , fx > 116
16 108
X = (fx − 116 ) ∗ Xw ∗ 841 , otherwise

24
Y = Yw ∗ fy3 , fy > 116
16 108
Y = (fy − 116 ) ∗ Yw ∗ 841 , otherwise

24
Z = Zw ∗ fz3 , fz > 116
16 108
Z = (fz − 116 ) ∗ Zw ∗ 841 , otherwise
    
R 3.240479 −1.53715 −0.498535 X
 G  =  −0.969256 1.875991 0.041556   Y 
B 0.055648 −0.204043 1.057311 Z

Black point B:
(Rb , Gb , Bb ) = (0, 0, 0)
White point W = (Rw , Gw , Bw ), according to image type:
Wbyte = (255, 255, 255), Wuint2 = (216 − 1, 216 − 1, 216 − 1),
Wint4 = (231 − 1, 231 − 1, 231 − 1), Wreal = (1.0, 1.0, 1.0)
Domain:
L ∈ [0; 100], a ∈ [−94.3383; 90.4746], b ∈ [−101.3636; 84.4473]
(Scaled to the maximum gray value in the case of byte and uint2. In the case of int4 L and a are scaled
to the maximum gray value, b is scaled to the minimum gray value, such that the origin stays at 0.)
’hls’ Hi = integer(H * 6)
Hf = fraction(H * 6)
if (L <= 0.5)
max = L * (S + 1)
else
max = L + S - (L * S)
fi
min = 2 * L - max
if (S == 0)
R = L
G = L
B = L
else
if (Hi == 0)
R = max
G = min + Hf * (max - min)
B = min

HALCON 8.0.2
144 CHAPTER 5. FILTER

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
Domain:
H ∈ [0; 2π], L ∈ [0; 1], S ∈ [0; 1]

’hsi’

M 1 = S ∗ sin H

M 2 = S ∗ cos H
I
I1 = √
3
  √2
0 √13
  
R 6 M1
 −1
 G = √ √1 1
√   M2 

6 2 3
B −1
√ −1
√ √1 I1
6 2 3

’hsv’ Domain: q
H ∈ [0; 2π], S ∈ [0; 23 ], I ∈ [0; 1]

if (S == 0)
R = V
G = V
B = V
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)))

HALCON/HDevelop Reference Manual, 2008-5-13


5.3. COLOR 145

elif (Hi == 3)
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
fi
Domain:
H ∈ [0; 2π], S ∈ [0; 1], V ∈ [0; 1]

’ciexyz4’
    
R 2.750 −1.149 −0.426 X
 G  =  −1.118 2.026 0.033   Y 
B 0.138 −0.333 1.104 Z
Domain:
X ∈ [0; 0.951], Y ∈ [0; 1], Z ∈ [0; 1.088]

Parameter
. ImageInput1 (input_object) . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (channel 1).
. ImageInput2 (input_object) . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (channel 2).
. ImageInput3 (input_object) . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Input image (channel 3).
. ImageRed (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Red channel.
. ImageGreen (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Green channel.
. ImageBlue (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . image(-array) ; Hobject : byte / uint2 / int4 / real
Blue channel.
. ColorSpace (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Color space of the input image.
Default Value : ’hsv’
List of values : ColorSpace ∈ {’hsi’, ’yiq’, ’yuv’, ’argyb’, ’ciexyz’, ’ciexyz4’, ’cielab’, ’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 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the behaviour can
be set via set_system(::’no_object_result’,<Result>:). If necessary, an exception handling is
raised.

HALCON 8.0.2
146 CHAPTER 5. FILTER

Parallelization Information
trans_to_rgb is reentrant and automatically parallelized (on tuple level, domain level).
Possible Predecessors
decompose3
Possible Successors
compose3, disp_color
See also
decompose3
Module
Foundation

5.4 Edges

close_edges ( Edges, EdgeImage : RegionResult : 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 / int4
Edge amplitude (gradient) image.
. RegionResult (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . region(-array) ; Hobject
Region containing closed edges.
. MinAmplitude (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Minimum edge amplitude.
Default Value : 16
Suggested values : MinAmplitude ∈ {5, 8, 10, 12, 16, 20, 25, 30, 40, 50}
Typical range of values : 1 ≤ MinAmplitude ≤ 255
Minimum Increment : 1
Recommended Increment : 1
Restriction : MinAmplitude ≥ 0
Example (Syntax: C)

sobel_amp(Image,&EdgeAmp,"sum_abs",5);
threshold(EdgeAmp,&EdgeRegion,40.0,255.0);
skeleton(EdgeRegion,&ThinEdge);
close_edges(ThinEdge,EdgeAmp,&CloseEdges,15);
skeleton(CloseEdges,&ThinCloseEdges);

Result
close_edges returns 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the behaviour can be
set via set_system(’no_object_result’,<Result>). If necessary, an exception handling is raised.
Parallelization Information
close_edges is reentrant and automatically parallelized (on tuple level).
Possible Predecessors
edges_image, sobel_amp, threshold, skeleton

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 147

Possible Successors
skeleton
Alternatives
close_edges_length, dilation1, closing
See also
gray_skeleton
Module
Foundation

close_edges_length ( Edges, Gradient : ClosedEdges : MinAmplitude,


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.
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 ; integer
Minimum edge amplitude.
Default Value : 16
Suggested values : MinAmplitude ∈ {5, 8, 10, 12, 16, 20, 25, 30, 40, 50}
Typical range of values : 1 ≤ MinAmplitude ≤ 255
Minimum Increment : 1
Recommended Increment : 1
Restriction : MinAmplitude ≥ 0
. MaxGapLength (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Maximal number of points by which edges are extended.
Default Value : 3
Suggested values : 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 ≤ 127
Minimum Increment : 1
Recommended Increment : 1
Restriction : (MaxGapLength > 0) ∧ (MaxGapLength ≤ 127)
Example (Syntax: C)

sobel_amp(Image,&EdgeAmp,"sum_abs",5);
threshold(EdgeAmp,&EdgeRegion,40.0,255.0);
skeleton(EdgeRegion,&ThinEdge);
close_edges_length(ThinEdge,EdgeAmp,&CloseEdges,15,3);

Result
close_edges_length returns 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the

HALCON 8.0.2
148 CHAPTER 5. FILTER

behaviour can be set via set_system(’no_object_result’,<Result>). If necessary, an exception


handling is raised.
Parallelization Information
close_edges_length is reentrant and automatically parallelized (on tuple level).
Possible Predecessors
edges_image, sobel_amp, threshold, skeleton
Alternatives
close_edges, dilation1, closing
References
M. Üsbeck: “Untersuchungen zur echtzeitfähigen Segmentierung”; Studienarbeit, Bayerisches Forschungszentrum
für Wissensbasierte Systeme (FORWISS), Erlangen, 1993.
Module
Foundation

derivate_gauss ( Image : DerivGauss : Sigma, 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
therefrom. Sigma is the parameter of the Gaussian (i.e., the amount of smoothing). If one value is passed in
Sigma the amount of smoothing in the column and row direction is identical. If two values are passed in Sigma
the first value specifies the amount of smoothing in the column direction, while the second value specifies the
amount of smoothing in the row direction. The possible values for Component are:

’none’ Smoothing only.


’x’ First derivative along x.
∂g(x, y)
g 0 (x, y) =
∂x
’y’ First derivative along y.
∂g(x, y)
g 0 (x, y) =
∂y
’gradient’ Absolute value of the gradient.
s
0 ∂g(x, y)2 ∂g(x, y)2
g (x, y) =
∂x ∂y

’gradient_dir’ Gradient direction in radians

∂g(x, y) ∂g(x, y)
φ = atan2( , )
∂y ∂x

’xx’ Second derivative along x.


∂ 2 g(x, y)
g 0 (x, y) =
∂x2
’yy’ Second derivative along y.
∂ 2 g(x, y)
g 0 (x, y) =
∂y 2
’xy’ Second derivative along x and y.
∂ 2 g(x, y)
g 0 (x, y) =
∂x∂y
’xxx’ Third derivative along x.
∂ 3 g(x, y)
g 0 (x, y) =
∂x3

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 149

’yyy’ Third derivative along y.


∂ 3 g(x, y)
g 0 (x, y) =
∂y 3
’xxy’ Third derivative along x, x and y.
∂ 3 g(x, y)
g 0 (x, y) =
∂x2 ∂y
’xyy’ Third derivative along x, y and y.
∂ 3 g(x, y)
g 0 (x, y) =
∂x∂y 2
’det’ Determinant of the Hessian matrix:
2
∂ 2 g(x, y) ∂ 2 g(x, y) ∂ 2 g(x, y)

DET = −
∂x2 ∂y 2 ∂y∂x

’laplace’ Laplace operator (trace of the Hessian matrix):

∂ 2 g(x, y) ∂ 2 g(x, y)
TR = +
∂x2 ∂y 2

’mean_curvatue’ Mean curvature H

∂g(x, y)2 ∂ 2 g(x, y)


a = (1 + )
∂x ∂y 2
∂g(x, y) ∂g(x, y) ∂ 2 g(x, y)
b = 2
∂x ∂y ∂y∂x
2 2
∂g(x, y) ∂ g(x, y)
c = (1 + )
∂y ∂x2
∂g(x, y)2 ∂g(x, y)2 3
d = (1 + + )2
∂x ∂y
a−b+c
H =
d
1
H = (κmin + κmax )
2
’gauss_curvatue’ Gaussian curvature K
DET
K= ∂g(x,y)2 ∂g(x,y)2 2
(1 + ∂x + ∂y )

’area’ Differential Area A

A = EG − F 2
2
∂g(x, y)
E = 1+
∂x
∂g(x, y) ∂g(x, y)
F =
∂x ∂y
2
∂g(x, y)
G = 1+
∂y

’eigenvalue1’ First eigenvalue


∂ 2 g(x,y) ∂ 2 g(x,y)
∂x2 + ∂y 2
a =
s 2
∂ 2 g(x, y) ∂ 2 g(x, y) ∂ 2 g(x, y)2
λ1 = a+ a2 − ( − )
∂x2 ∂y 2 ∂y∂x

HALCON 8.0.2
150 CHAPTER 5. FILTER

’eigenvalue2’ Second eigenvalue


∂ 2 g(x,y) ∂ 2 g(x,y)
∂x2 + ∂y 2
a =
s 2
∂ 2 g(x, y) ∂ 2 g(x, y) ∂ 2 g(x, y)2
λ2 = a− a2 − ( − )
∂x2 ∂y 2 ∂y∂x

’eigenvec_dir’ Direction of the eigenvector corresponding to the first eigenvalue in radians


’main1_curvature’ First principal curvature
p
κmax = H + H2 − K

’main2_curvature’ Second principal curvature


p
κmin = H − H2 − K

’kitchen_rosenfeld’ Second derivative perpendicular to the gradient


∂ 2 g(x,y) ∂g(x,y)2 ∂ 2 g(x,y) ∂g(x,y)2 2
g(x,y) ∂g(x,y)2 ∂g(x,y)2
∂x2 ∂y + ∂y 2 ∂x − 2 ∂ ∂y∂x ∂x ∂y
k= ∂g(x,y)2 ∂g(x,y)2
∂x + ∂y

’zuniga_haralick’ Normalized second derivative perpendicular to the gradient


∂ 2 g(x,y) ∂g(x,y)2 ∂ 2 g(x,y) ∂g(x,y)2 2 2
∂g(x,y)2
∂x2 ∂y + ∂y 2 ∂x − 2 ∂ ∂y∂x
g(x,y) ∂g(x,y)
∂x ∂y
k=   23
∂g(x,y)2 2
∂g(x,y)
∂x + ∂y

’2nd_ddg’ Second derivative along the gradient


∂ 2 g(x,y) ∂g(x,y)2 2
∂ 2 g(x,y) ∂g(x,y)2
∂x2 ∂x + 2 ∂g(x,y)
∂x
∂g(x,y) ∂ g(x,y)
∂y ∂y∂x + ∂y 2 ∂y
k= ∂g(x,y)2 ∂g(x,y)2
∂x + ∂y

’de_saint_venant’ Second derivative along and perpendicular to the gradient


∂g(x,y) ∂g(x,y) ∂ 2 g(x,y) ∂ 2 g(x,y) ∂g(x,y)2 ∂g(x,y)2 ∂ 2 g(x,y)
∂x ∂y ( ∂x2 − ∂y 2 ) − ( ∂x − ∂y ) ∂x∂y
k= ∂g(x,y)2 ∂g(x,y)2
∂x + ∂y

Parameter
. Image (input_object) . . . . . . (multichannel-)image(-array) ; Hobject : byte / direction / cyclic / int1 / int2 /
uint2 / int4 / real
Input image.
. DerivGauss (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) ; Hobject : real
Filtered result image.
. Sigma (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real(-array) ; real
Sigma of the Gaussian.
Default Value : 1.0
Suggested values : Sigma ∈ {0.7, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0}
Typical range of values : 0.2 ≤ Sigma ≤ 50.0
Minimum Increment : 0.01
Recommended Increment : 0.1
Restriction : Sigma > 0.0
. Component (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Derivative or feature to be calculated.
Default Value : ’x’
List of values : 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’}

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 151

Example (Syntax: C)

read_image(&Image,"mreut");
derivate_gauss(Image,&Gauss,3.0,"x");
zero_crossing(Gauss,&ZeroCrossings);

Parallelization Information
derivate_gauss is reentrant and automatically parallelized (on tuple level, channel level, domain level).
Possible Successors
zero_crossing, dual_threshold
Alternatives
laplace, laplace_of_gauss, binomial_filter, gauss_image, smooth_image,
isotropic_diffusion
See also
zero_crossing, dual_threshold
Module
Foundation

diff_of_gauss ( Image : DiffOfGauss : Sigma, SigFactor : )

Approximate the LoG operator (Laplace of Gaussian).


diff_of_gauss approximates the Laplace-of-Gauss operator by a difference of Gaussians. The standard de-
viations 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:

Sigma
sigma1 = r
log ( SigF1actor )
−2 SigFactor 2 −1

sigma1
sigma2 =
SigFactor
DiffOfGauss = (Image ∗ gauss(sigma1)) − (Image ∗ gauss(sigma2))

For a SigFactor = 1.6, 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 ; real
Smoothing parameter of the Laplace operator to approximate.
Default Value : 3.0
Suggested values : Sigma ∈ {2.0, 3.0, 4.0, 5.0}
Typical range of values : 0.2 ≤ Sigma ≤ 50.0
Minimum Increment : 0.01
Recommended Increment : 0.1
Restriction : Sigma > 0.0
. SigFactor (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Ratio of the standard deviations used (Marr recommends 1.6).
Default Value : 1.6
Typical range of values : 0.1 ≤ SigFactor ≤ 10.0
Minimum Increment : 0.01
Recommended Increment : 0.1
Restriction : SigFactor > 0.0

HALCON 8.0.2
152 CHAPTER 5. FILTER

Example

read_image(Image,’fabrik’)
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 2 (H_MSG_TRUE) if all parameters are correct. If the input is empty the behaviour
can be set via set_system(’no_object_result’,<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).
Possible Successors
zero_crossing, dual_threshold
Alternatives
laplace, derivate_gauss
References
D. Marr: “Vision (A computational investigation into human representation and processing of visual information)”;
New York, W.H. Freeman and Company; 1982.
Module
Foundation

edges_color ( Image : ImaAmp, ImaDir : Filter, Alpha, NMS, Low,


High : )

Extract color edges using Canny, Deriche, or Shen filters.


edges_color extracts color edges from the input image Image. To define color edges, the multi-channel image
Image is regarded as a mapping f : R2 7→ Rn , where n is the number of channels in Image. For such functions,
there is a natural extension of the gradient: the metric tensor G, which can be used to calculate for every direction,
given by the direction vector v, the rate of change of f in the direction v. For notational convenience, G will be
regarded as a two-dimensional matrix. Thus, the rate of change of the function f in the direction v is given by
v T Gv, where
 Xn n 
∂fi ∂fi X ∂fi ∂fi
fxT fx T
 i=1 ∂x ∂x ∂x ∂y 
  
fx fy i=1
G= = X  .

n n
fxT fy T
fy fy  ∂fi ∂fi X ∂fi ∂fi 
i=1
∂x ∂y i=1
∂y ∂y

The partial derivatives of the images, which are necessary to calculate the metric tensor, are calculated with the
corresponding edge filters, analogously to edges_image. For Filter = ’canny’, the partial derivatives of
the Gaussian smoothing masks are used (see derivate_gauss), for ’deriche1’ and Filter = ’deriche2’ the
corresponding Deriche filters, for Filter = ’shen’ the corresponding Shen filters, and for Filter = ’sobel_fast’
the Sobel filter. Analogously to single-channel images, the gradient direction is defined by the vector v in which the
rate of change f is maximum. The vector v is given by the eigenvector corresponding to the largest eigenvalue of
G. The square root of the eigenvalue is the equivalent of the gradient magnitude (the amplitude) for single-channel
images, and is returned in ImaAmp. For single-channel images, both definitions are equivalent. Since the gradient
magnitude may be larger than what can be represented in the input image data type (byte or uint2), it is stored in
the next larger data type (uint2 or int4) in ImaAmp. The eigenvector also is used to define the edge direction. In
contrast to single-channel images, the edge direction can only be defined modulo 180 degrees. Like in the output
of edges_image, the edge directions are stored in 2-degree steps, and are returned in ImaDir. Points with
edge amplitude 0 are assigned the edge direction 255 (undefined direction). For speed reasons, the edge directions
are not computed explicitly for Filter = ’sobel_fast’. Therefore, ImaDir is an empty object in this case.

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 153

The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarilyfor all filters except ’sobel_fast’ (where
the filter width is 3 × 3 and Alpha is ignored), and can be estimated by calling info_edges for concrete values
of the parameter Alpha. It decreases for increasing Alpha for the Deriche 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 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 are zero outside of the image, while the Canny operator
mirrors the gray value at the image border. Comparable filter widths can be obtained by the following choices of
Alpha:

Alpha(0 deriche20 ) = Alpha(0 deriche10 )/2


Alpha(0 shen0 ) = Alpha(0 deriche10 )/2
0 0
Alpha( canny ) = 1.77/Alpha(0 deriche10 )

edges_color 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,1000,...)

For ’sobel_fast’, the same non-maximum-suppression is performed for all values of NMS except ’none’. Further-
more, the hysteresis threshold operation is always performed. Additionally, for ’sobel_fast’ the resulting edges are
thinned to a width of one pixel.
Parameter
. Image (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image(-array) ; Hobject : byte / uint2
Input image.
. ImaAmp (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . singlechannel-image(-array) ; Hobject : uint2 / int4
Edge amplitude (gradient magnitude) image.
. ImaDir (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . singlechannel-image(-array) ; Hobject : direction
Edge direction image.
. Filter (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Edge operator to be applied.
Default Value : ’canny’
List of values : Filter ∈ {’canny’, ’deriche1’, ’deriche2’, ’shen’, ’sobel_fast’}
. Alpha (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Filter parameter: small values result in strong smoothing, and thus less detail (opposite for ’canny’).
Default Value : 1.0
Suggested values : Alpha ∈ {0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.9, 1.0, 1.1, 1.2, 1.5, 2.0, 2.5, 3.0}
Typical range of values : 0.2 ≤ Alpha ≤ 50.0
Minimum Increment : 0.01
Recommended Increment : 0.1
Restriction : Alpha > 0.0
. NMS (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Non-maximum suppression (’none’, if not desired).
Default Value : ’nms’
List of values : NMS ∈ {’nms’, ’inms’, ’hvnms’, ’none’}
. Low (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer
Lower threshold for the hysteresis threshold operation (negative if no thresholding is desired).
Default Value : 20
Suggested values : Low ∈ {5, 10, 15, 20, 25, 30, 40}
Typical range of values : 1 ≤ Low
Minimum Increment : 1
Recommended Increment : 5
Restriction : (Low ≥ 1) ∨ (Low < 0)

HALCON 8.0.2
154 CHAPTER 5. FILTER

. High (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . integer ; integer


Upper threshold for the hysteresis threshold operation (negative if no thresholding is desired).
Default Value : 40
Suggested values : High ∈ {10, 15, 20, 25, 30, 40, 50, 60, 70}
Typical range of values : 1 ≤ High
Minimum Increment : 1
Recommended Increment : 5
Restriction : ((High ≥ 1) ∨ (High < 0)) ∧ (High ≥ Low)
Result
edges_color returns 2 (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’,<Result>). If
necessary, an exception handling is raised.
Parallelization Information
edges_color is reentrant and automatically parallelized (on tuple level).
Possible Successors
threshold
Alternatives
edges_color_sub_pix
See also
edges_image, edges_sub_pix, info_edges, nonmax_suppression_amp,
hysteresis_threshold
References
C. Steger: “Subpixel-Precise Extraction of Lines and Edges”; International Archives of Photogrammetry and
Remote Sensing, vol. XXXIII, part B3; pp. 141-156; 2000.
C. Steger: “Unbiased Extraction of Curvilinear Structures from 2D and 3D Images”; Herbert Utz Verlag, München;
1998.
S. Di Zenzo: “A Note on the Gradient of a Multi-Image”; Computer Vision, Graphics, and Image Processing, vol.
33; pp. 116-125; 1986.
Aldo Cumani: “Edge Detection in Multispectral Images”; Computer Vision, Graphics, and Image Processing:
Graphical Models and Image Processing, vol. 53, no. 1; pp. 40-51; 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; pp. 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; pp. 167-187; 1987.
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelli-
gence; PAMI-12, no. 1; pp. 78-87; 1990.
J. Shen, S. Castan: “An Optimal Linear Operator for Step Edge Detection”; Computer Vision, Graphics, and Image
Processing: Graphical Models and Image Processing, vol. 54, no. 2; pp. 112-133; 1992.
Module
Foundation

edges_color_sub_pix ( Image : Edges : Filter, Alpha, Low, High : )

Extract subpixel precise color edges using Deriche, Shen, or Canny filters.
edges_color_sub_pix extracts subpixel precise color edges from the input image Image. The definition
of color edges is given in the description of edges_color. The same edge filters as in edges_color
can be selected: ’canny’, ’deriche1’, ’deriche2’, and ’shen’. In addition, a fast Sobel filter can be selected with
’sobel_fast’. The filters are specified by the parameter Filter.
The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarily. For a detailed description of this
parameter see edges_color. This parameter is ignored for Filter = ’sobel_fast’.

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 155

The extracted edges are returned as subpixel precise XLD contours in Edges. For all edge operators except for
’sobel_fast’, the following attributes are defined for each edge point (see get_contour_attrib_xld):
’edge_direction’ Edge direction
’angle’ Direction of the normal vectors to the contour (oriented such that the normal vectors point to
the right side of the contour as the contour is traversed from start to end point; the angles are
given with respect to the row axis of the image.)
’response’ Edge amplitude (gradient magnitude)
edges_color_sub_pix links the edge points into edges by using an algorithm similar to a hysteresis thresh-
old operation, which is also used in edges_sub_pix and lines_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).
Because edge extractors are often unable to extract certain junctions, a mode that tries to extract these missing
junctions by different means can be selected by appending ’_junctions’ to the values of Filter that are described
above. This mode is analogous to the mode for completing junctions that is available in edges_sub_pix and
lines_gauss.
The edge operator ’sobel_fast’ has the same semantics as all the other edge operators. Internally, howver, it is
based on significantly simplified variants of the individual processing steps (hysteresis thresholding, edge point
linking, and extraction of the subpixel edge positions). Therefore, ’sobel_fast’ in some cases may return slightly
less accurate edge positions and may select different edge parts.
Parameter

. Image (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . (multichannel-)image ; Hobject : byte / uint2


Input image.
. Edges (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xld_cont-array ; Hobject
Extracted edges.
. Filter (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string ; string
Edge operator to be applied.
Default Value : ’canny’
List of values : Filter ∈ {’canny’, ’deriche1’, ’deriche2’, ’shen’, ’sobel_fast’, ’canny_junctions’,
’deriche1_junctions’, ’deriche2_junctions’, ’shen_junctions’}
. Alpha (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real ; real
Filter parameter: small values result in strong smoothing, and thus less detail (opposite for ’canny’).
Default Value : 1.0
Suggested values : Alpha ∈ {0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.9, 1.0, 1.1, 1.2, 1.5, 2.0, 2.5, 3.0}
Typical range of values : 0.7 ≤ Alpha ≤ 50.0
Minimum Increment : 0.01
Recommended Increment : 0.1
Restriction : Alpha > 0.0
. Low (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Lower threshold for the hysteresis threshold operation.
Default Value : 20
Suggested values : Low ∈ {5, 10, 15, 20, 25, 30, 40}
Typical range of values : 1 ≤ Low
Minimum Increment : 1
Recommended Increment : 5
Restriction : Low > 0
. High (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . number ; real / integer
Upper threshold for the hysteresis threshold operation.
Default Value : 40
Suggested values : High ∈ {10, 15, 20, 25, 30, 40, 50, 60, 70}
Typical range of values : 1 ≤ High
Minimum Increment : 1
Recommended Increment : 5
Restriction : (High > 0) ∧ (High ≥ Low)
Result
edges_color_sub_pix returns 2 (H_MSG_TRUE) if all parameters are correct and no error oc-

HALCON 8.0.2
156 CHAPTER 5. FILTER

curs during execution. If the input is empty the behavior can be set via set_system
(’no_object_result’,<Result>). If necessary, an exception handling is raised.
Parallelization Information
edges_color_sub_pix is reentrant and processed without parallelization.
Alternatives
edges_color
See also
edges_image, edges_sub_pix, info_edges, hysteresis_threshold, lines_gauss,
lines_facet
References
C. Steger: “Subpixel-Precise Extraction of Lines and Edges”; International Archives of Photogrammetry and
Remote Sensing, vol. XXXIII, part B3; pp. 141-156; 2000.
C. Steger: “Unbiased Extraction of Curvilinear Structures from 2D and 3D Images”; Herbert Utz Verlag, München;
1998.
S. Di Zenzo: “A Note on the Gradient of a Multi-Image”; Computer Vision, Graphics, and Image Processing, vol.
33; pp. 116-125; 1986.
Aldo Cumani: “Edge Detection in Multispectral Images”; Computer Vision, Graphics, and Image Processing:
Graphical Models and Image Processing, vol. 53, no. 1; pp. 40-51; 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; pp. 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; pp. 167-187; 1987.
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelli-
gence; PAMI-12, no. 1; pp. 78-87; 1990.
J. Shen, S. Castan: “An Optimal Linear Operator for Step Edge Detection”; Computer Vision, Graphics, and Image
Processing: Graphical Models and Image Processing, vol. 54, no. 2; pp. 112-133; 1992.
Module
2D Metrology

edges_image ( Image : ImaAmp, ImaDir : Filter, Alpha, NMS, Low,


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. Further-
more, a very fast variant of the Sobel filter can be used. Thus, the following edge operators are available:
’deriche1’, ’lanser1’, ’deriche1_int4’, ’deriche2’, ’lanser2’, ’deriche2_int4’, ’shen’, ’mshen’, ’canny’, and ’so-
bel_fast’
(parameter Filter).
The edge amplitudes (gradient magnitude) are returned in ImaAmp. It should be noted that for ’sobel_fast’ for
speed reasons internally an algorithm is used that computes the x and y derivatives with a restricted value range of
[−128, 127] for byte images and [−32768, 32767] for uint2 images. Consequently, an ideal horizontal or vertical
step edge with an amplitude of more than 128 can assume a maximum amplitude of 128 or 32768, respectively,
in ImaAmp, while an ideal 45 degree step edge can assume a maximum amplitude of 181 or 46341, respectively.
Since ideal step edges typically never occur in real images because the edges are smoothed by the optics and
camera this limitation very rarely has any influence on the application.
For all filters except ’sobel_fast’, the edge directions are returned in ImaDir. For ’sobel_fast’, the edge direction
is not computed to speed up the filter. Consequently, ImaDir is an empty image object. The edge operators
’deriche1’ bzw. ’deriche2’ are also available for int4-images, and return the signed filter response instead of its

HALCON/HDevelop Reference Manual, 2008-5-13


5.4. EDGES 157

absolute value. This behavior can be obtained for byte-images as well by selecting ’deriche1_int4’ bzw. ’de-
riche2_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 x degrees with respect to the horizontal axis is stored as x/2 in the edge direction image. Furthermore,
the direction of the change of intensity is taken into account. Let [Ex , Ey ] denote the image gradient. Then the
following edge directions are returned as r/2:

intensity increase Ex /Ey

edge direction r
from bottom to top 0/+ 0
from lower right to upper left +/− ]0, 90[
from right to left +/0 90
from upper right to lower left +/+ ]90, 180[
from top to bottom 0/+ 180
from upper left to lower right −/+ ]180, 270[
from left to right +/0 270
from lower left to upper right −/− ]270, 360[

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 for all filters except ’sobel_fast’ (where
the filter width is 3 × 3 and Alpha is ignored), and can be estimated by calling 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:

Alpha(0 lanser10 ) = Alpha(0 deriche10 )


Alpha(0 deriche20 ) = Alpha(0 deriche10 )/2
Alpha(0 lanser20 ) = Alpha(0 deriche20 )
Alpha(0 shen0 ) = Alpha(0 deriche10 )/2
Alpha(0 mshen0 ) = Alpha(0 shen0 )
Alpha(0 canny 0 ) = 1.77/Alpha(0 deriche10 )

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 (11 × 11), 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,...)

For ’sobel_fast’, the same non-maximum-suppression is performed for all values of NMS except ’none’. Further-
more, the hysteresis threshold operation is always performed. Additionally, for ’sobel_fast’ the resulting edges are
thinned to a width of one pixel.

HALCON 8.0.2
158