Extension Package Programmer's Manual
Total Page:16
File Type:pdf, Size:1020Kb
a product of MVTec Extension Package Programmer’s Manual HALCON 21.05 Progress This manual shows how to create HALCON extension packages based on new operators written in C, Version 21.05.0.0. 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 © 1997-2021 by MVTec Software GmbH, München, Germany MVTec Software GmbH Protected by the following patents: US 7,062,093, US 7,239,929, US 7,751,625, US 7,953,290, US 7,953,291, US 8,260,059, US 8,379,014, US 8,830,229. Further patents pending. Microsoft, Windows, Windows Server 2008/2012/2012 R2/2016, Windows 7/8/8.1/10, Microsoft .NET, Visual C++, and Visual Basic are either trademarks or registered trademarks of Microsoft Corporation. Linux is a trademark of Linus Torvalds. Sun is a trademark of Oracle Corporation. OpenGL is a trademark of Silicon Graphics, Inc. macOS and OpenCL are trademarks of Apple Inc. All other nationally and internationally recognized trademarks and tradenames are hereby recognized. More information about HALCON can be found at: http://www.halcon.com/ About This Manual This manual describes how to extend HALCON by additional operators encapsulated in HALCON packages us- ing the Extension Package Interface. Before starting to use the Extension Package Interface, MVTec strongly recommends that the user should be familiar with the normal HALCON system. This manual is written for the expert HALCON user who wants to extend the system for specific requirements. Thus, the reader should be familiar with the normal HALCON system. Furthermore, programming skills are required. Finally, the reader should know about his/her development environment (that is how to invoke the compiler/linker etc.). This manual is divided into the following parts: • Introduction This chapter provides a short overview of HALCON packages and their creation. Furthermore, an example showing the integration of a simple operator is presented. • Operator Description (def-file) This chapter summarizes the minimum required operator description used by the HALCON compiler hcomp as well as the complete operator description which is needed to provide a full integration of new operators in HDevelop and to generate documentation files. • Style Guide for Programming This chapter introduces basic style guides for how to program HALCON operators. Especially, the HALCON memory management is explained. • HALCON Data Types In this chapter the most important HALCON data structures to handle iconic data and control parameters are presented. • Handling Iconic Objects and Control Parameters This chapters contains a set of routines to facilitate the programming of the operator interface and accessing the basic HALCON data structures. • Special Routines for Typical Supply Procedures This chapter describes a set of convenience routines for standard situations. • Creating a New HALCON Package The last chapter explains how to use the HALCON compiler hcomp to generate HALCON packages for different platforms. Contents 1 Introduction 9 1.1 HALCON Operators.........................................9 1.1.1 Using HALCON Operators in C, C++, and .NET languages................ 10 1.1.2 Internal Structure of HALCON Operators.......................... 10 1.2 HALCON Packages.......................................... 11 1.2.1 Packages and HALCON XL................................. 12 1.2.2 Directory Structure of a HALCON Package......................... 12 1.2.3 How to Create and Use a HALCON Package........................ 13 1.3 Installing a HALCON Package.................................... 13 1.3.1 Windows........................................... 14 1.3.2 Linux............................................. 14 1.3.3 macOS............................................ 14 1.4 An Example.............................................. 14 2 Operator Description (def-File) 19 2.1 Short Operator Description...................................... 19 2.2 Extended Operator Description.................................... 20 2.2.1 Header............................................ 20 2.2.2 short............................................. 21 2.2.3 warning............................................ 21 2.2.4 abstract............................................ 21 2.2.5 module............................................ 22 2.2.6 chapter............................................ 22 2.2.7 functionality......................................... 23 2.2.8 keywords........................................... 23 2.2.9 predecessor, successor, alternatives............................. 23 2.2.10 see_also............................................ 23 2.2.11 attention........................................... 23 2.2.12 result_state.......................................... 24 2.2.13 parallelization......................................... 24 2.2.14 complexity.......................................... 27 2.2.15 example............................................ 27 2.2.16 references........................................... 27 2.2.17 Class Information....................................... 27 2.3 Describing the Parameters...................................... 28 2.3.1 Name............................................. 28 2.3.2 default_type.......................................... 29 2.3.3 sem_type........................................... 29 2.3.4 modified........................................... 30 2.3.5 multivalue........................................... 30 2.3.6 costs_weight......................................... 31 2.3.7 postprocessing........................................ 31 2.3.8 description.......................................... 32 2.3.9 type_list............................................ 32 2.3.10 default_value......................................... 32 2.3.11 values............................................. 33 2.3.12 value_list........................................... 33 2.3.13 value_min, value_max.................................... 33 2.3.14 step_rec, step_min, value_function.............................. 33 2.3.15 value_number......................................... 33 2.3.16 assertion........................................... 34 2.3.17 multichannel......................................... 34 2.3.18 multiinstance......................................... 35 2.3.19 file_ext, file_ext_descr.................................... 35 2.4 Text in def-Files............................................ 35 2.5 Chapter Description.......................................... 38 3 Style Guide for Programming 39 3.1 Basic Numeric Data Types...................................... 39 3.1.1 Attributes of Iconic Parameters................................ 39 3.1.2 Local Variables / Temporary Results............................. 40 3.1.3 Procedure Parameters..................................... 40 3.1.4 Arrays............................................. 40 3.2 Memory Management......................................... 41 3.2.1 Temporary Data....................................... 41 3.2.2 Permanent Data........................................ 43 3.2.3 Debugging.......................................... 45 3.3 Structuring Programs......................................... 46 3.4 Extension Package Initialization................................... 46 3.5 Name Conventions for Procedures.................................. 46 3.6 Input / Output............................................. 47 3.7 Error Handling............................................ 47 3.7.1 Defining own Error Codes.................................. 47 3.7.2 Extending Error Codes.................................... 47 3.8 Notes on Image Processing Operators................................ 48 4 HALCON Data Types 49 4.1 Pixel Data (Himage)......................................... 49 4.2 Region Data (Hrlregion)....................................... 50 4.3 XLDs (Hcont, Hpoly)......................................... 52 4.4 Control Parameters.......................................... 55 5 Handling Iconic Objects and Control Parameters 57 5.1 Basic Access to Iconic Input Objects................................. 57 5.1.1 HGetObj........................................... 57 5.1.2 HGetComp.......................................... 59 5.1.3 HGetRL............................................ 60 5.1.4 HGetImage.......................................... 61 5.1.5 HGetXLD........................................... 62 5.2 Additional Routines for Accessing Input Image Objects....................... 62 5.2.1 HGetDRL........................................... 62 5.2.2 HGetFDRL.......................................... 62 5.2.3 HGetURL........................................... 63 5.2.4 HGetDImage......................................... 64 5.2.5 HGetObjNum......................................... 65 5.3 Loop Macros for Accessing Single Input Objects.......................... 65 5.3.1 HAllObj........................................... 66 5.3.2 HAllComp.......................................... 66 5.4 Creating Objects and Writing Output Object Parameters....................... 67 5.4.1 HCrObj............................................ 67 5.4.2 HCopyObj.......................................... 68 5.4.3 HPutDRL........................................... 69 5.4.4 HPutImage.......................................... 69 5.4.5 HDefObj........................................... 69 5.4.6 HPutDImage........................................