HALCON Version 5.2 HALCON / COM interface User`s Manual
Contents
1. HALCON 5 1 whereas the release Version is an integral part of HALCON 5 2 This means that both the old HALCON version and the old HALCON COM interface must be removed before installing the current version Usually an old HALCON installation is detected when installing a newer one and can be removed automatically but that is not true for an old COM interface Hav ing both the old and the current COM interface installed can lead to unpredictable results or to a complete malfunction of the interface Thus it is very important to remove any existing older COM interface before the current HALCON version is installed If you have installed the beta version of the COM interface by using its installshield wizard it is quite easy to re move it again Select Add Remove Software from the windows control panel then select Halcon COM from the software list and finally click on Add Remove If you have installed the beta version of the COM interface by hand you have to unregister it by hand Locate the place where you copied the interface file HalconX d11 to then unregister it by a com mand line call REGSVR32 EXE This should reside in your WindowsNT system directory e g C WINNT System32 REGSVR32 EXE You have to set the U switch to unregister the DLL Your command line should look like this C gt REGSVR32 U lt location you copied the DLL to gt HalconX DLL After a while a message box should pop up containing something like this DLLUnRegi2. State 2 Then Set Eyes Region SelectShape area and 500 50000 Set Eyes Eyes SelectShape anisometry and 1 1 7 Call Window DispObj Monkey Call Window DispObj Eyes Label1 Caption click Finish to terminate Commandi Caption Finish State 3 End If If State 1 Then Set Region Monkey Threshold 128 256 Set Region Region Connection Call Window SetColored 12 Call Window DispObj Region Label1 Caption Next the ape s eyes will be selected State 2 End If If State 0 Then Call Monkey ReadImage monkey Call Window DispObj Monkey Label1 Caption Next the image will be segmented into several regions State 1 End If End Sub 3 Run your little program and enjoy a guided tour through a very common image processing example 4 5 Other Examples There are some more pre coded examples so you can discover how things work with HALCON COM These examples can be found under the following directory HALCONROOT Nexampleslvb The following list shows all the supplied examples and explains their topics in short 4 5 OTHER EXAMPLES 27 1 HALCONROOT examples vb Applications Monitoring An example showing how to use a background estimator for traffic monitoring HALCONROOTY examples vb Online Barcode An online example showing how to read barcode HALCONROOT examples vb Online Measure An interactive example showing how to use the measure tool HALCONROOTY examples vb
3. distinction should be made between the instantiation and the initialization of ob jects Even more important we should also distinguish objects from object reference variables An object reference variable 15 set up by its declaration with the keyword Dim Dim imagel As HImageX This statement does not yet create a COM object 1t just declares a variable able to reference a HImageX object If we want to declare a reference variable and immediately create an object it refers to we should write Dim As New HImageX Now a new HImageX object is created and the variable image refers it Note variable declaration is not a must with VisualBasic but should always be done anyway Undeclared variables get declared automatically when referenced and that can lead to errors which are very hard to discover It is good idea to place the statement Option Explicit on top of every VisualBasic module because then variable declaration is forced We now have a valid COM object to which the declared variable refers To initialize this object we could call a constructor method Dim imagel As New HImageX Call image1 ReadImage some_file_name Note the Call keyword It s necessary in VisualBasic if the called method doesn t return a value The other way of initialization would be using another object s method Dim imagel As New HImageX Dim regioni As HRegionX Call image1 ReadImage some_file_name Set regi
4. step de struction process to destruct an object it must be uninitialized before being destroyed which is the opposite of being instantiated The latter is done by COM and the client environment the first must be performed by some automatic destruction process To pick up the HImageX example again the automatic destructor must free the image data using the HALCON memory management Another example if a top level HALCON window gets initialized it is physi cally opened The automatic destructor must take care of the window getting closed before the according COM object finally gets destroyed CHAPTER 3 THE HALCON COM INTERFACE 14 one 1 iz lt gt ES Be N a e ES ES HUntypedObjectx ES ES HBarcodeX ES lt gt HFramegrabberX HBgEstiX HFilex HClassBoxX HFeatureSetX HHistogramX HSerialX HSystemX EFunctionldX HHomMat3dX HTemplateX HHomMat2dX HGnuplotx Ea Ea HSocketX E ES i i HwindowxCtr1 gt HOperatorSetX Figure 3 1 An overview ofthe HALCON COM Class hierarchy CD Abstract Class T Aggregation m Class instantiating objects which have an internal state NN lt gt Class instantiating objects which have no internal state 3 4 INTERFACES AND INHERITANCE 15 3 4 Interfaces and Inheritance As said before COM classes are built up from interfaces which in turn contain methods and properties Each HALCON COM class has
5. them just like data members With C they still are only methods thus there is no way to modify and retrieve data members directly From this point of view COM class data members can be compared with C private class members 2 1 3 Inheritance and Polymorphism As COM is a binary standard inheritance must also take place at binary level which makes the process slightly uncomfortable Without going into detail one can say that the only thing of interest here is that there are two methods of reusing existent components containment and aggregation Both techniques are commonly used by C programmers as well contain ment corresponds to C classes instantiated as a member object in other classes whereas 2 2 HALCON AND 7 aggregation roughly corresponds to inheritance The main difference between containment and aggregation is the way the interface s of the contained aggregated component s are handled the methods and properties of a contained component are hidden to the outside so that only the containing component can use them Any method that should be visible from outside has to be re defined in the outer component In contrast to this the interface s of an aggregated com ponent are merged with the interfaces of the aggregating one thus automatically making their methods visible to the outside The object oriented feature of polymorphism is also achieved through interfaces different COM classes exposing the same interface can be u
6. use of interfaces to simulate inheritance we will discuss this topic more detailled afterwards Naming Conventions classes are capitalized and begin with an H They always end with an upper case for example HFramegrabberX interfaces are also capitalized and end with X but begin with an P for example IHObjectX methods properties and parameters are capitalized for example GrabImage FileName 3 2 More about Classes Classes are the essential items to deal with when writing HALCON COM applications There are quite a lot of them and there are different types of classes thus we will have a closer look 9 10 CHAPTER 3 THE HALCON COM INTERFACE on how classes are used and what attributes they have The classes of the HALCON COM interface are partly related in a way which could be described as inheritance Therefore it 15 important to get an impression of how inheritance is achieved within HALCON COM and how to use it 3 2 1 Different Types of Classes There are two major categories of classes 1 classes instantiating objects that have an internal state and 2 classes instantiating objects with no internal state The first category 15 used to implement special data structures like images files frame grab bers etc and the operators belonging to this data whereas the second category 15 only used to group operators belonging together If several objects of a class belonging to the first ca
7. will discover an area titled Properties Formi Here you can set and retrieve the active GUI object s in this case the form s properties Click on Form1 right beside Caption and change the string toHalconX example You should see the effect of your action immediately in the caption text of the below form Grab the form and resize it to a suitable extent Have a look at the tool bar to the left here you can find all the control elements you can place inside your form They are represented as small icons Move the mouse cursor over the different icons to see the bubble help revealing their names You should find an icon showing the HALCON symbol named HWindowXCtrl You guessed it That is our ActiveX control HALCON window Activate the HWindowXCtrl icon Draw a rectangular region inside the form make sure it is approximately square When releasing the mouse button the square area should turn black Switch to the CommandButton icon looking like a brick in the left tool bar Draw a but ton inside the form beside or below the HALCON window Change the button s caption text to Next gt gt in the properties box Now switch to Label in the tool bar and draw a longish rectangular area at the bottom of the form If you encounter placement difficulties due to lack of form space you can always resize the form to fit your needs Resize the form so that it fits around the before created items Now you have the entire G
8. you wish to do so see figure 4 2 You will also get assistance in supplying the parameter values for a method call in the right order and with the right types see figure 4 3 6 Start your application by pressing F5 and see what happens Private Sub Commandl Click Call Monkey Re Call Monke s End sub Readlmage ReadSequence RealToComplex Rectangle 1 Domain ReduceDomain Regiongrowing Figure 4 2 VisualBasic helping you to select a method Private Sub Commandl1 Click Call Monkey ReadImage monkey Call Monkey Display End sub Display Window As HWindowX Figure 4 3 VisualBasic helping you with the correct parameters 4 4 Final Step More Functionality What we have now is a very basic application which can t do very much but it needs only 10 lines of code Thus we will extend the functionality turning our application into a small image processing demo 1 Extend the variable declaration section at the beginning of your listing so 1t looks like this Dim Monkey As New HImageX Dim Window As HWindowX Dim Region As HRegionX Dim Eyes As HRegionX Dim State As Integer Although these declarations are not necesary Basic declares variables automatically it is nevertheless a good idea to do so 2 Check the Command1_Click subroutine and modify it like this 26 CHAPTER 4 EXAMPLE SESSION VISUAL BASIC Private Sub Commandi_Click State 3 Then End End If If
9. 11 33
10. 5 0 installed If you are prepared this way you can start making your first HALCON application using Visu alBasic Note the little program developed in this chapter is also available ready to go in the HALCONROOTY examples vb Manual directory together with other examples However it is recommended to follow the steps below and program it yourself as you will get a better impres sion of how VisualBasic program development works and gain a lot of additional information with the single steps 4 2 First Step The GUI Go ahead and 1 launch VisualBasic A dialog named New Project should appear allowing you to select the type of project you want Switch to New in the tab list select Standard EXE and click Open 2 Select Project from the menu bar and click Components A dialogue box shows up listing the components installed on your system Switch to Controls in the tab list and place a check next to the item HalconX typelibrary V1 0 21 22 10 CHAPTER 4 EXAMPLE SESSION VISUAL BASIC Press F2 The object browser should appear See if you can find HImageX and browse through some of the corresponding methods Clicking on a method shows its parameteri zation as well as a short help text about what it will do in the status area at the bottom of the object browser Close the object browser Have a look at the dialogue template form showing in the lower half of the screen it should be titled Formi In the upper half you
11. 7 DirectX 5 double 16 early binding 7 encapsulation 6 error handling 16 error offset 16 ErrorBaseCOM 16 ErrorBaseHalcon 16 example 21 form 22 get properties 16 group class 10 32 GUI 21 HALCON window 11 HalconX 9 HDevelop 11 HImagex 11 12 24 HWindowX 24 HObjectX 11 HOperatorSetX 11 12 HRegionX 11 HSystemX 16 HTuple 16 HUntypedObjectX 11 12 HWindowX 11 HWindowXCtrl 11 IDispatch 6 IHImageX 15 IHObjectX 15 implementation 6 inheritance 6 9 15 inheritance simulation 9 initialization 12 instantiation 12 interface 6 interfaces 9 15 internal state 10 IUnknown 6 Java 6 Label 22 language independence 5 late binding 7 library 9 location transparency 5 long 16 meaning of objects 10 member 6 memory management 13 INDEX method 6 methods 9 15 naming convention 9 New 18 24 Nothing 18 object 6 object browser 21 object copying 13 object destruction 13 object duplication 13 object initialization 24 object instantiation 24 object orientation 5 OLE 5 On Error 18 pointer 12 15 polymorphism 6 properties 9 16 property 6 put properties 16 reference 15 Resume Next 19 semantics of objects 10 Set 18 special classes 11 strong typed 11 top level window 11 type conversion 12 variable 13 variable declaration 24 25 VARIANT 16 versioning 5 VisualBasic 6 17 VisualC 6 weak typed
12. Another way to initialize an object is to get it as result after calling another object s method For ex ample an uninitialized HImageX object becomes initialized when it is returned from a call to MeanImage which does a convolution an image and produces another image Note the mechanism is indeed slightly more complicated and again depends on the client lan guage In fact an object variable needs not refer to a living COM object when being used as a return value of a method call Even more if it does the referred object gets destroyed before the new object is assigned to the variable Actually there is yet another way to initialize a HALCON COM object by using the Cast method mentioned before The cast method takes another object of a related derived from HObjectX class as parameter which in turn has to be initialized Then the object the calling method belongs to gets initialized with the internal state of the other object Because no copying or duplication takes place the other object gets uninitialized Note Not all HALCON COM objects can have this initialized state An object can only be initialized if it has an internal state Thus all the group classes from 3 2 1 must be excluded Therefore they have no constructor methods 3 3 2 Destruction We have seen that creating a valid HALCON COM object is a two step process first the COM object needs to be instantiated then it must be initialized This implies also a two
13. Basic Delphi and other tools stands open for the development of HALCON applications Beside this another important advantage of a COM interface lies in the widespread standard HALCON is joining with it nearly any piece of software related to Windows is also related to COM This will not change in the near future and upcoming new de velopment tools will be firmly bound to COM anyway Further versions of the HALCON COM interface might also support COM s ability to enable multi client multi threaded application development with method calls across process and machine boundaries 2 2 2 Disadvantages Of course COM can also show some disadvantages and using HALCON in a component based way can be rather tricky depending on the language and tool one is using for development For 8 CHAPTER 2 INTRODUCTION example it is really easy to use software components with VisualBasic but this is not neces sarily the case when considering VisualC here the classic HALCON C interface is far more convenient As said before COM shows some other powerful features like options for distributed computing that may be supported in future HALCON releases Then the HAL CON COM interface should be a big step ahead the other language interfaces 2 2 3 Important Notes for users of the Beta Version If you have installed the pre release beta version of the HALCON COM interface you should mind the following The old pre release COM interface was an add on to
14. HALCON Version 5 2 MT MVTec Software GmbH HALCON COM interface User s Manual April 21 1999 Understanding and using the interface 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 1st Edition April 1999 MIT Copyright 1999 MVTec Software GmbH Munich Germany Software GmbH Information concerning HALCON http www mvtec com Address MVTec Software GmbH Orleansstr 34 D 81667 Munich Germany E mail mvtec mvtec com Contents 1 About this Manual 1 A A A EE EEE 1 1 2 Organization of this Manual 1 e u eed ae id RS 2 1 4 Additional Sources of Information 2 1 32 Release Noles onc a SS 3 2 Introduction 5 2 1 Why Components cercos De De ONS OR A 5 21 Imerfaces and COM 20 6 2 1 2 Objects Methods and Data Members 6 2 1 3 6 2 1 4 Early and late Binding 7 2222 HALCON and COM 7 2 2 1 ee 7 2 2 2 Disadvantages sh A
15. Online Movement An example showing how to discover movement by using the difference of images HALCONROOT examples vb Segmentation An example illustrating the possibilities for interactive image processing applications HALCONROOT examples vb Tools Measure A real world measurement example showing how to measure the pins of an IC HALCONROOTY examples vb Manual The example described in this chapter 28 CHAPTER 4 EXAMPLE SESSION VISUAL BASIC Bibliography Brock95 Kraig Brockschmidt Inside OLE Microsoft Press Redmond Washington 1995 Arm98 Tom Armstrong Active Template Library A Developer s Guide M amp T Books Foster City CA 1998 29 30 BIBLIOGRAPHY List of Figures 3 1 4 1 4 2 4 3 HALCON COM Class 14 VisualBasic environment with newly created GUI 23 VisualBasic s method selection assistance 25 VisualBasic s parameter list assistance o o 25 31 Index abstract class 9 12 ActiveX 5 ActiveX container 11 ActiveX control 11 aggregation 6 11 base class 9 11 12 binary reuseability 5 binding 7 BSTR 16 11 17 Cast O 11 13 class definition 6 classes 9 code generation 12 CommandButton 22 component 5 constructor 13 15 containment 6 data members 16 data type 10 11 default interface 15 Delphi 6 derived class 11 15 Dim 1
16. UI for your application ready to go and your screen should look similar to figure 4 1 4 2 FIRST STEP THE GUI 23 rs Project Microsoft Visual Basic design Form1 Form 1512 amp Eile Edit View Project Format Debug Run Tools Add Ins Window Help 18 x Bu Bon o 120 5280 4332 492 x ee lx General Label1 Label 7 cala Alphabetic categorized 5 Project Project1 5 5 Forms A Label1 per 0 Left Justify Formi 1 a 1 30 False 8 amp H8000000F amp 1 Opaque 2 0 None a Labell E E Caption qn Returns sets the text displayed in an object s title bar or below an object s icon D le HalconX examp FormLayout Figure 4 1 Having performed all steps from 4 2 you should end up with a setup like this 24 CHAPTER 4 EXAMPLE SESSION VISUAL BASIC 4 3 Second Step Functionality Now you have the GUI finished you should go ahead and make the application do something 1 Right click somewhere inside the form and select View Code Another window will pop up over the form with two combo boxes at its top border Select Form from the left combo box You will see the code to be executed when the form is created 2 Insert a line into the subroutine Private Sub Form_Load Label1 Caption Click Next to start End Sub You just changed the text the label at the bot
17. VisualBasic command Resume Next The next line of code then would be responsible for checking the error code stored in LastErrorCode Of course this method is a little long winded and not quite up to date an exception handling mechanism in general is much more flexible and robust but it s quite easy to understand We have seen that there are two types of errors HALCON related errors and COM interface related ones Since the COM interface errors have smaller error numbers than the HALCON error codes the above mechanism would lead to negative numbers In that case the produced error code would have to be subtracted from SysObject ErrorBaseCOM to get the correct then interface related error code 20 CHAPTER 3 THE HALCON COM INTERFACE Chapter 4 Example Session Visual Basic In this chapter you will learn how to quickly develop HALCON applications using VisualBasic and the HALCON COM interface There will be simple steps describing what to do The result will be a very small exemplary vision application with doubtful value but equipped with a graphical user interface As an additional source of information you are strongly encouraged to have a look at the other examples as well those are supplied as VisualBasic sources together with the current version 4 1 Prerequisites What you need is a running WindowsNT workstation with ServicePack 3 installation being recommended Furthermore you should have HALCON 5 2 and VisualBasic
18. ary level 2 Object orientation 3 Robust versioning 4 Location Transparency In fact the first topic 1s the most important in our case Binary reuseability implies that an exist ing component can be used within virtually any software development tool in any language as long as there is a certain basic support for COM in it Furthermore it does not matter what tool 5 6 CHAPTER 2 INTRODUCTION was used to implement the component as it is a binary standard There are numerous different tools for developing COM components e g MS Visual C Borland C and Delphi MS Visual Basic MS J and a lot more The object oriented characteristics of COM components such as encapsulation inheritance and polymorphism ease the development of software espe cially for those programmers that are already familiar with object oriented programming e g with C The versioning and location transparency features of COM components will not be discussed any further here as they are less important for developing software with HALCON and as they are not yet completely tested and implemented with the current revesion 2 1 1 Interfaces and COM An important aspect of COM is the usage of component interfaces Compared to the C ter minology an interface corresponds to the declaration of a class thus showing its functionality and hiding the internal implementation details This encapsulating feature makes it possible to efficiently use a COM component witho
19. bber from which to retrieve the data In the second case the method takes the HImageX object into which the image should be grabbed as parameter 16 CHAPTER 3 THE HALCON COM INTERFACE Properties are a special COM feature and can be treated like data members by tools like Visu alBasic There are two kinds of them put and get properties put property allows the user to change the internal state of an object whereas the get property only allows to read out the internal state Usually but not always both types are present acting like an ordinary variable class member in C The properties in the HALCON COM interface are just for convenience purposes since they always map to an existing method The HWindowX class for example has quite a lot of properties Width and Height define the window s extent Draw sets or gets the current drawing mode and so on All of these properties are mapped to their corresponding methods Reading out the draw mode for example results in a call to the Method GetDraw whereas Width Height both are mapped to the method GetWindowExtent when retrieving values and SetWindowExtent for changing values respectively 3 6 closer Look at Data Types We have seen that a lot of the data types used within the HALCON COM interface are actually the classes themselves But there are also more basic everyday types being used A widely used data type in the COM world and thus in VisualBasic is the VARIANT
20. dard COM error handling technique where every method call passes both a numerical and a textual representation of the error to the calling framework It is then up to the caller to react to this information Since low error numbers are reserved for COM HALCON COM uses a very high offset to its own error codes To get the correct HALCON error code this offset must be subtracted from the received code The offset is a read only property of the HSystemX class There are two offsets one for the HALCON COM interface and one for HALCON itself Those properties are named 3 8 HALCON COM AND VISUALBASIC 17 e HSystemX ErrorBaseCOM and e HSystemX ErrorBaseHalcon In order to get the correct HALCON error code a HSystemX object must be instantiated one 15 enough for the whole application anyway since HSystemX objects have no identity Then the value of the respective HSystemX property must be subtracted from the returned error code to get the correct HALCON error code For an example how to deal with error codes see section 3 6 2 3 8 HALCON COM and VisualBasic So far the important basics of the HALCON COM interface have been explained Now let s have a look at what things behave like when using VisualBasic 3 8 1 Object Instantiation There are many different ways to instantiate COM objects in VisualBasic We will discuss only one of them because it has certain advantages over all the others We have seen in the sections before that a
21. got one default interface named accordingly to the class For example the class HImageX contains the default interface IHimageX which provides all the relevant methods Dealing with interfaces is strongly related to the client environment used so we will not have a too close look at this topic now For example VisualBasic tries to completly hide the whole interface topic from the user in that case an interface and the related class are the same most of the time Actually an interface behaves similar to a C pointer or reference to an object and that is exactly what VisualBasic tries to hide As said before interfaces are used for inheritance simulation within HALCON COM the way this works 15 simple We have seen that HObjectX is an abstract and thus not instantiable class On the other hand the derived classes HImageX HRegionX etc have to supply their own functionality plus the inherited HObjectX functionality This 15 done with the help of interfaces currently there is no COM class named HObjectX thus no HObjectX object can be initialized only an interface named IHObjectX This interface appears in all derived classes together with their default interfaces HImageX for example has two interfaces in fact 1t has a hidden third one 1 IHImageX the default interface and 2 IHObjectX the inherited interface This allows to satisfy every method which expects a HObjectX parameter actually it expects a reference to that clas
22. ject model is a Microsoft standard for component based language independent software develop ment This manual contains all necessary information to install the COM interface and under stand its main concepts a guided example shows how to develop HALCON applications using Visual Basic Attention if you have the pre release beta version of the COM interface installed you have to make sure to properly remove it from your system before installing the release version see section 2 2 3 for details 1 1 Readers This manual is intended for the advanced HALCON user You should be familiar with the main HALCON package and have experience in developing image analysis applications with HDevelop see section 1 4 Of course you must have knowledge about the language tool you plan to develop with e g Visual Basic 1 2 Organization of this Manual This manual 1 divided into the following parts e Introduction This chapter provides a short overview of COM concepts in general The HALCON COM Interface This chapter describes the structure of the HALCON COM interface giving a quick overview though not getting very deep into the details e Example Session In this chapter a small image processing demo application is developed stepwise with VisualBasic 2 CHAPTER 1 ABOUT THIS MANUAL 1 3 Notation Since COM is only available for the Windows operating systems family all file paths and envi ronment variables in this manual are prin
23. method parameter Beseides the first two groups we can categorize classes in another way well known in the object oriented world 1 abstract classes and 2 non abstract classes A class is called abstract 1f 1t can not be instantiated Thus an abstract class must be the base class for other classes 1f 1t should be of any use The idea behind this concept is that abstract classes provide a semantic base for their derived classes without being concrete enough for instantiation A look on real world terms reveals many analogous cases there is for example the class animal which can be seen as an abstract base class for classes like fish bird and 3 2 MORE ABOUT CLASSES 11 horse Any existing being can not be only an animal it is always either a fish a bird or a horse or whatever else There is only one such abstract class in the HALCON COM interface HObjectX It represents a HALCON iconic object such as an image a region or XLD The derived classes HImageX HRegionX and so on then specify the exact type of the HALCON iconic object see also the class overview in figure 3 1 3 2 2 Classes for Special Purposes There are some HALCON COM classes that have special jobs Although they do fit into the above systematics they are worth mentioning because they have to be used in a specific way or show some specific semantics HWindowXCtrl This class is a HALCON window in the form of an ActiveX control Its advantage against
24. nderstood as showing polymorphic behaviour as they act differently responding to the same methods 2 1 4 Early and late Binding Binding is the process of resolving the call adresses of a component s exposed methods This can be done at compilation time early binding or at runtime late binding Thus when using a component a programmer can take a specification of the contained methods and integrate it directly into the application Therefore the specification must be available in a format that fits the used programming language e g when using C as client language one would typically include the header files containing the method declarations Otherwise the programmer could make the methods being bound at runtime then no language dependent information is needed for compiling and the calling mechanism is totally different Again we will not go into details and thus only point out the main aspect that runtime bound methods calls are somewhat slower than their early bound counterparts The HALCON COM interface supports both early and late binding so that special needs of different applications can be satisfied 2 2 HALCON and COM 2 2 1 Advantages How can the user of HALCON profit from a COM interface The main advantage is that with a COM interface the powerfull image processing features of HALCON can be used by a wide range of applications and development tools so that its usage is no longer restricted to C and C The world of Visual
25. oe ee 7 2 2 3 Important Notes for users of the Beta Version 8 2 24 A A ADA A ES 8 3 The Halcon COM Interface 9 Preface at ee 9 2 3 More about Class s o s no es 9 3 2 1 Disterent Iypes OF Classes ea da Vivek a 10 3 2 2 Classes for Special Purposes 11 3 3 Object Construction and 12 331 a ehe 12 3 3 27 DESTRUCCI N as Way E e Bele e a 13 3 4 Interfaces and 15 3 5 15 3 6 A closer Look at Data Types 16 3 4 Handling es ea Bete as Eee Bei 16 3 8 HALCON COM and 1 17 3 8 1 17 382 BrrorcHandling Ba En 18 11 CONTENTS 4 Example Session Visual Basic 21 4 PrETE QUISE Se or Se ge Be ay Sut ae Sy Bate as 21 4 2 First Step The GUI au eRe Re 21 4 3 Second Step Functionality 24 4 4 Final Step More 25 Se e E 26 Figures 30 Index 32 Chapter 1 About this Manual This manual gives an overview of the HALCON COM interface COM component ob
26. onl image1 Threshold 128 255 18 CHAPTER 3 THE HALCON COM INTERFACE There are two important things here First the Set keyword it replaces the Ca11 keyword when the called method returns another COM object in this case a region Furthermore the second variable declaration omits the New keyword This is because the corresponding variable need not instantiate an object at declaration time This is done within the Threshold method which creates anew COM object itself and passes a reference to this object as its return value HALCON COM objects get destroyed as soon as no variable references them anymore For local variables this is the case when they go out of scope e g a subroutine is left For global variables or if an explicit destruction is desired this has to be done by the user Dim imagel As New HImageX Dim regioni As HRegionX Call image1 ReadImage some_file_name Set regioni imagel Threshold 128 255 Set imagel Nothing Set Nothing Here both variables are assigned the special VisualBasic keyword Nothing which denotes that they do not reference their related COM objects anymore These COM objects thus are not referenced at all which leads to their immediate destruction There is of course a lot more to say about VisualBasic HALCON programming Some further aspects might become clear in the following example session 3 8 2 Error Handling When using VisualBasic errors can be tra
27. pped by an error handler If no custom error handler 1s present VisualBasic itself supplies a default one which shows a message box containing the textual error description Error handlers in VisualBasic can be set with the keyword On Error To trap an error in a portion of code the apropriate construct could look like this Dim LastErrorCode As Long Dim SysObject As New HSystemX On Error Goto myErrorHandler lt some code gt myErrorHandler do something with the error information for example Debug Print Error occurred Err Description LastErrorCode Err Number SysObject ErrorBaseHalcon Resume Next If an error occurs in lt some code gt an immediate jump to the label myErrorHandler is made where an arbitrary error processing mechanism can be placed The scheme used in the exam ple tries to model a traditional procedural error recovery strategy where every function call returns an error code which has to be checked before program execution can continue When an error occurs the error handling code at the corresponding label takes over writes a status 3 8 HALCON COM AND VISUALBASIC 19 message the textual error representation to the VisualBasic Immediate window and stores the error code in a global integer variable The global VisualBasic object Err 15 the source of information in this case Afterwards control is put back to the line following the statement which produced the error This is done by the
28. s in form of the THObjectX interface with any derived class object as such an object always has the THObjectX interface too This corresponds to a certain object oriented rule which allows an automatic cast from the derived class to the base class not the other way How intuitive this feature can be used again depends on the client language tool VisualBasic 5 0 for example only regards the default interface an object supplies and treats that as 1f 1t was the class itself That implies that only the methods contained in the default interface seem to belong to a class Thus to also use the inherited methods contained in the IHObjectX interface an explicit cast to the base class is necessary This is a widely known VisualBasic weakness and may get improved by Microsoft in forthcoming versions 3 5 Methods and Properties There is not much to say about methods since they can be used quite intuitively The only interesting aspect here is the fact that different classes can have methods with the same name but with a different parameter configuration These methods perform the same action as their identical names let expect but show a different point of view For example the method GrabImage that retrieves an image from a framegrabber is part of the HImageX as well as of the HFramegrabberX class In the first case the method is a constructor for an image object and takes a HFramegrabberX object as parameter that denotes the framegra
29. st method an image object can be turned into a region an XLD can become a HUntypedObjectX object and so on The reason for that is as mentioned above the need to convert back and forth to the HUntypedObjectX objects used by the HOperatorSetX methods For example if an automatically generated code fraction produces an object variable of type HUntypedObjectX which shall be used in some hand written code as an image it can be forced to become a HImageX object Of course it must be assured that the variable really does contain an image it is the programmer s task to take care for that We will have a closer look on how to use the Cast method later on 3 3 Object Construction and Destruction 3 3 1 Construction HALCON COM object can be in different states It can be instantiated and it can be ini tialized An instantiated object need not necessarily be initialized but an initialized object 15 always instantiated Instantiation means using an appropriate technique to produce a living COM object this technige differs according to what client language is used Initializing means giving the object a well defined internal state There is another state an object can have it is neither instantiated nor initialized Since not being instantiated means not existing what exactly does this condition mean The answer depends somewhat on the client language used but is rather easy to understand if we realize that COM object variables actuall
30. sterServer in halconX dll succeeded Now you may delete the file itself 2 2 4 Limitations Although the complete functionality of the HALCON library can be used without limitations there exist some limitations for the current version of the HALCON COM interface e currently the extension packages can not be used whereas framegrabber interfaces work well with the HALCON COM interface Chapter 3 The Halcon COM Interface This chapter describes the structure of the HALCON COM interface more detailled Note Of course there are several interesting facts to know about COM that are not discussed here because they are not directly relevant for working with the HALCON COM interface Thus you are recommended to read additional COM related literature and or the documentation of your preferred development tool e g VisualBasic At least you should be familiar with ob ject oriented concepts like inheritance classes and methods in order to understand the following chapter 3 1 Preface Let s have a closer look at the HALCON COM interface The whole package called the Hal conX library contains all the functionality partitioned into several classes Each class has one or more interfaces that are built up from methods and properties The HALCON COM interface uses inheritance and thus contains derived classes and also an abstract base class Since COM is not meant to supply a standardized inheritance mechanism HALCON COM makes extensive
31. tec com 1 5 RELEASE NOTES 1 5 Release Notes Please note the latest updates of this manual e first release CHAPTER 1 ABOUT THIS MANUAL Chapter 2 Introduction This chapter provides a short overview of the main aspects of component based software de velopment and shows how this can be done with COM The advantages and disadvantages of component based software engineering are discussed as well as the limitations as far as HAL CON is concerned Note it is not intended to discuss all aspects of COM in detail in this manual Thus anyone who wants to know further details about programming with COM is recommended to read the corresponding literature 2 1 Why Components Component based software engineering has been discussed intensively in the past few years Concrete standards evolving from this discussion include DCE CORBA and COM The fas cination about components is their ability to be reused at binary level With their slight not always very complete object oriented features and the option for location transparency they form a good base for the development of modern distributed software systems In fact COM is the base for nearly every software technology Microsoft is dealing with ActiveX OLE and DirectX for example base on COM thus large parts of the Microsoft operating systems are component based Let s have a look on what a COM component looks like The main features of COM components are 1 Reuseability at bin
32. ted in the Windows NT convention e g HALCONROOT examples vb Manual to denote a subdirectory containing an example package within the HALCON base directory referenced by the environment variable HALCONROOT 1 4 Additional Sources of Information For further information you may consult the following manuals Getting Started Manual Please read this manual as a first introduction to the HALCON system e HDevelop User s Manual An introduction to the graphical development environment of the HALCON system e HALCON HDevelop The reference manual for all HALCON operators HDevelop version e HALCON C User s Manual How to use the HALCON library in your C programs HALCON C The reference manual for all HALCON operators C version e HALCON C User s Manual How to use the HALCON library in your C programs e HALCON C The reference manual for all HALCON operators C version e Framegrabber Integration Programmers Manual A guide on how to integrate a new framegrabber in the HALCON system Note that in some cases you might define new operators using the C Interface instead of using the standard HALCON framegrabber interface in order to exploit specific hardware features of a framegrabber board All these manuals are available as PostScript ps and Acrobat Reader pdf docu ments The reference manuals are available as HTML documents as well For the latest version of the manuals please check http www mv
33. tegory are instantiated they are all different from the HALCON point of view whereas the second category does not have this quality For example if we consider several objects instantiated from the image class HImageX they all denote something different they represent different HALCON images However if we have an object of a class like HSystemX that represents the internal state of the HALCON kernel it does not matter how many of those objects will be instantiated because all of them denote the same there is only one HALCON kernel to be rep resented Those classes can be understood as group classes denoting that they supply a bunch of methods that all have some semantic peculiarities in common In contrast to this methods of the first category classes may share a common semantics but work on different data For example if an object of the HImageX class is instantiated its methods always work exactly on one specific HALCON image the one that is represented by the object to be precise a HImageX object may also represent an array of images Different HImageX objects represent different images and therefore work on different data From an object oriented point of view classes and data types are the same so that all of the HALCON COM classes can be seen as data types To make a long story short 1t does not make much sense to see the second category classes as data types because they have no meaning That s why they will never show up as a
34. the ordinary HALCON window HWindowX is the possibility to exist inside an ActiveX con tainer An ActiveX container is a part of a window which can contain GUI elements such as buttons sliders and so on When developing complex image processing applications it 15 often necessary to integrate all user interaction components input and output seamlessly into one surface The HWindowX type HALCON window does not provide this flexibility since it always appears as a top level window In order to behave like an ordinary HWindowX HAL CON window HWindowXCtr1 uses the COM technique of aggregation Thus any new created HWindowXCtrl type ActiveX control automatically instantiates HWindowX object which is bound to the control HUntypedObjectX HUntypedObjectX is derived from HObjectX just like HImageX HRegionX and so on Its purpose is to get an instantiable form of the abstract base class The class does not have any members as it just consists of a polymorphic data type without any special meaning As it is this weak typed it can not be used together with the strong typed methods of the other classes except by using the Cast method which allows arbitrary type conversions between all HObjectX derived classes explained later HUntypedObjectX is meant to be a generic data type used by the special class HOperatorSetX HOperatorSetX This is basically a group class for all existing HALCON operators HOperatorSetX 15 meant to provide access
35. to a procedural way of HALCON programming The reason for that 15 the fact that it is easier for some object oriented tools like HDevelop to generate COM code automatically when using a procedural technique The specificity about HOperatorSetX 15 that all its methods exclusively use HObjectX type input iconic parameters and return HUntypedObjectX type output iconic objects Note it is allowed to have input parameters 12 CHAPTER 3 THE HALCON COM INTERFACE of an abstract type C programmers will know this concept it corresponds to passing objects through a pointer to their abstract base class However this is not allowed for output parameters Here the data type must be specified because there has to be some typed vari able which can store the output object Since HOperatorSetX methods must use a generic data type scheme output iconic objects are always of type HUntypedObjectX Hand written COM code should not make use of the HOperatorSetX HUntypedObjectX concept since it weakens the otherwise strong typed object oriented approach it becomes relevant only in cases where automatically generated code is involved The Cast Method All classes derived from HObjectX supply the Cast method which is used for type conver sions between the concerned classes This method breaks up the well defined data type scheme evolving from the class hierarchy so it should not be used except when there is no other possi bility By using the Ca
36. tom will show when the application 15 launched 3 Next we will declare some important variables switch back to General in the left combo box above the source code window and insert in the following lines at the top Dim Monkey As New HImageX Dim Window As HWindowX Some online selection boxes for the desired object type will assist you We have just created two objects a HImageX and a HWindowX The reason for the New keyword in the first line is that we want the HImageX object to be instantiated e g memory being allocated for it This is not necessary for the HWindowX since it is already instantiated it is the ActiveX control we have drawn inside the form 4 The object Monkey is instantiated as we know although it is not yet initialized with image but the Window variable still refers to nowhere Insert another line into the Form_Load subroutine Private Sub Form_Load Set Window HWindowXCtr11 Object Label1 Caption Click Next to start End Sub Now the Window variable refers to the HWindowX part of our ActiveX control 5 Switch to Command1 Another subroutine shows up which you have to complete like this Private Sub Command1_Click Call Monkey ReadImage monkey Call Window DispObj Monkey End Sub 4 4 FINAL STEP MORE FUNCTIONALITY 25 While typing you will notice a very convenient VisualBasic feature since it knows the methods of a class it allows you to select one from a list if
37. type All users of the HALCON C interface will know the HTuple data type which is both polymorphic it can be one of several different subtypes and supplies array functionality it can hold several data items at once VARIANTs behave analogously and are the COM equivalent for HTuples Exactly like a HTuple a VARIANT is able to hold data of different basic types plus the information what kind of data it contains Also a combination of different or equal values is possible just like with HTuples The main difference is that a VARIANT is no class This implies the complete absence of any methods So all the additional functionality of the very powerful HTuple class must be accessed in another way For that reason there is HTupleX class which groups methods for tuple operations like vector addition string concatenation and so on Another important and widely used COM data type is BSTR This standard COM flavor of character strings is not directly compatible with standard C like string implementations mainly because it uses wide chars This means that auxiliary functions must be used to access or modify BSTRs when using C C Again this means no problem with VisualBasic as it is the default string data type there Additionally there are integral data types like long and double as well They are used in situations where array or multitype parameters are not allowed or make no sense 3 7 Error Handling The HALCON COM interface uses the stan
38. ut the need to know anything about its implementation However unlike a C class a COM component can have multiple interfaces Seeming rather strange at first glance the motivation for this gets clearer when looking at the versioning aspect once defined an interface stays exactly the way it is newer versions of the component then de fine enhanced or extended functionality by new interfaces allowing existing software to remain unchanged because it can still use the older interfaces Another reason for multiple interfaces is the ability to partition a component s functionality into several well defined portions There are also a couple of standard COM interfaces every component has by default those are mainly IUnknown and IDispatch They are not described in this manual so that interested readers are refered to the appropriate literature 2 1 2 Objects Methods and Data Members Keeping the C point of view we come now to the question what are the objects methods and data members of a class in terms of COM Just as with C classes there are interfaces in COM and those interfaces are made up from some methods Several objects of a class correspond to several instances of a component each with its own internal state However there are some differences with data members as their handling within COM depends on the tool the component is used by COM follows a concept of properties that are special methods allowing tools like VisualBasic to treat
39. y are references to an existing or not existing object Thus if such a variable is declared there is not necessarily yet an object created it refers to As we like to mix up the terms reference to an object and object in this manual we may speak of an uninstantiated object in that case For example if an HImageX object is created not only the referring variable is declared it is useable in terms of COM since it is instantiated but it does not yet contain any HALCON image To be a valid HALCON COM object it still must be initialized This can be done in two different ways e the object can initialize itself or e the object can be initialized by another object s method 3 3 OBJECT CONSTRUCTION AND DESTRUCTION 13 In the first case a so called constructor is executed The term constructor is somewhat mis leading here since it has a slightly different meaning than for example a C constructor In C terms a constructor is a special method always named exactly as the class which does the object construction automatically without the need to be called explicitly In the HAL CON COM case a constructor is an ordinary method which initializes the object s internal state and must be called explicitly For that reason a HALCON COM class can have many differently named constructors One of the constructors of our example HImageX class 15 ReadImage which initializes the object by reading an image file from the hard disk
Download Pdf Manuals
Related Search