PolyWorks SDK

Creating External Modules

© 2007–2020 InnovMetric Software Inc. All rights reserved. PolyWorks® is a registered
trademark of InnovMetric Software Inc. InnovMetric, PolyWorks|Inspector,
PolyWorks|Modeler, PolyWorks|Talisman, PolyWorks|Reviewer, IMAlign, IMMerge,
PolyWorks|DataLoop, PolyWorks|PMI+Loop, PolyWorks|AR, PolyWorks|ReportLoop, "The
Universal 3D Metrology Software Platform", "The Smart 3D Metrology Digital Ecosystem",
and "Interconnecting Hardware, Software and People" are trademarks of InnovMetric
Software Inc.

SmartGD&T is a trademark of Multi Metrics Inc. NX is a trademark or registered trademark of

Siemens Product Lifecycle Management Software Inc. or its subsidiaries in the United States
and in other countries. Teamcenter is a trademark or registered trademark of Siemens
Product Lifecycle Management Software Inc. or its subsidiaries in the United States and in
other countries. All other trademarks are the property of their respective owners.

This manual, as well as the software described in it, is furnished under license and may be
used or copied only in accordance with the terms of such license. The content of this
document is furnished for informational use only, and is subject to change without notice.
InnovMetric Software Inc. assumes no responsibility or liability for any errors or inaccuracies
that may appear in this document.

Except as permitted by such license, reproduction in whole or in part in any way without
written permission from InnovMetric Software is strictly prohibited.

PolyWorks SDK Reference Guide

2020/03/17
PolyWorks® Metrology Suite 2020
Contents

5 1. Overview
6 1.1 External modules
6 1.2 Supported programming languages
7 1.3 Related documentation
7 1.4 Module names
7 1.5 Technical support

8 2. Essential COM Principles and Programming Techniques

9 2.1 What is COM?
9 2.2 What is a COM object?
10 2.3 Creating a COM object
13 2.4 Using COM interfaces
15 2.5 Managing a COM object’s lifetime

19 3. Using the PolyWorks SDK

20 3.1 Installation
20 3.2 Plug-ins vs. client applications
20 3.3 PolyWorks servers and external modules
21 3.4 External module samples
22 3.4.1 Client application samples
24 3.4.2 Plug-in samples
25 3.5 The API Reference Manual
26 3.6 Overview of certain COM interfaces

28 4. Plug-ins
29 4.1 Creating plug-ins
29 4.2 Using plug-ins
29 4.2.1 Plug-in location
29 4.2.2 Plug-in registration
30 4.2.3 Accessing plug-ins
30 4.3 Plug-in deployment
30 4.3.1 Deploying plug-ins using Microsoft’s Platform SDK for Windows Installer
33 4.3.2 Installing documentation for plug-ins
34 4.4 Advanced hints and tips
34 4.4.1 Plug-ins that use hardware or software resources

35 5. Client Applications
36 5.1 Creating client applications
37 5.1.1 Creating a client application using Visual Basic .NET in Visual Studio

PolyWorks SDK Reference Guide 2020 3

Contents

38 5.1.2 Creating a client application using Visual Basic for Applications macros
39 5.1.3 Creating a client application using Visual C++
40 5.1.4 Creating a client application using C# in Visual Studio
41 5.2 Using client applications
41 5.2.1 Client application location
41 5.2.2 Accessing client applications
41 5.3 Advanced hints and tips
41 5.3.1 Mixing 32-bit and 64-bit modules

42 Glossary

44 Index

PolyWorks SDK Reference Guide 2020 4

Overview 1
The PolyWorks SDK Reference Guide is intended for application developers who would like to develop
external modules in the PolyWorks® Metrology Suite 2020. It explains how to use the IMAlign™,
PolyWorks|Modeler™, and PolyWorks|Inspector™ modules as service providers for external applications.

This chapter presents a few basic notions, lists the supported programming languages, and explains how to
obtain technical support.

PolyWorks SDK Reference Guide 2020 5

Overview External modules

1.1 External modules

The expression external module is used to designate both plug-ins and client
applications.

Plug-ins are dynamic link libraries (DLLs) that directly add functionalities to a PolyWorks
Metrology Suite module, and client applications are independent applications that use
PolyWorks Metrology Suite modules without being integrated in them.

External modules can communicate with PolyWorks Metrology Suite modules with the
help of a software development kit (SDK) known as the PolyWorks SDK, presented in
Chapter 3 Using the PolyWorks SDK. It uses Microsoft’s COM architecture for most of the
functionalities (additional functionalities are also offered through a C++-only API).

See Section 3.2 Plug-ins vs. client applications to learn more about these two types of
external modules.

Essential COM principles and programming techniques are presented in Chapter 2

Essential COM Principles and Programming Techniques.

1.2 Supported programming languages

The PolyWorks SDK supports the following programming languages:

 Visual Basic .NET

 C++

 C#

 Visual Basic for Applications

When a section of this manual refers to one particular programming language, an

appropriate text in bold (i.e., Visual Basic .NET:, C++:, C#:) precedes the information.

The PolyWorks SDK is well supported by Visual Basic for Applications 6.0, and Visual
Studio 2013 or later. Samples have been developed for these specific versions but
might work for others as well. Visual Basic for Applications 6.0 is typically used to
develop Excel macros.

PolyWorks SDK Reference Guide 2020 6

Overview Related documentation

1.3 Related documentation

The following documents offered in PDF format, available from the Help > Reference
Guides menu of the Workspace Manager, offer related information:

 The PolyWorks® Reference Guide presents the PolyWorks Metrology Suite, including
the Workspace Manager, and explains how to customize the user interface by means
of visual layouts. It also explains how to open modules from the Workspace Manager.
Finally, it describes the installation procedure for both node-locked and floating
license key files.

All the PolyWorks reference documentation can be accessed from the Workspace
Manager. See its Help > Reference Guides submenu.

In addition, there is the API Reference Manual that can be found in the
\goodies\PolyWorksSDK\help folder located in the PolyWorks installation path. For more
information, see Section 3.5 The API Reference Manual.

Finally, the Microsoft Developer Network Library is mentioned as additional COM

documentation.

1.4 Module names

In 2017, InnovMetric Software Inc. changed the naming of two modules. The IMInspect
module was renamed PolyWorks|Inspector and the IMEdit module was renamed
PolyWorks|Modeler.

For reasons of backwards compatibility, certain elements (e.g., COM interfaces,

subdirectories) have retained the names of the original modules.

1.5 Technical support

Report any problems, or send your suggestions, directly to InnovMetric Software at
www.innovmetric.com. The InnovMetric Software PolyWorks SDK support team can
also be contacted by e-mail at supportsdk@innovmetric.com.

PolyWorks SDK Reference Guide 2020 7

Essential COM
Principles and
2
Programming
Techniques
This chapter is a brief overview of the COM architecture. Additional COM documentation, such as the
Microsoft Developer Network Library, is recommended.

PolyWorks SDK Reference Guide 2020 8

Essential COM Principles and Programming Techniques What is COM?

Figure 2.1 A COM class named AnyClass that implements the A, B, C, and IUnknown interfaces.

IUnknown

A
AnyClass
B
C

2.1 What is COM?

COM stands for Component Object Model. It is an object-oriented programming model
used by numerous applications. Essentially, it allows libraries and applications to share
some of theirs components with other applications. The library or application that
gives access to a component is called a server, while the library or application that uses
it is a client.

2.2 What is a COM object?

A COM object is an instance of a COM class that has been made available by a library or
an application through Microsoft’s COM architecture. The role of a COM class is to offer
functionalities to client applications.

COM objects can be created and accessed from a variety of programming languages.
However, the level of difficulty associated with the use of COM objects is dependent on
the COM support given by the chosen language’s integrated development
environment.

As opposed to regular objects, the public methods of COM objects cannot be accessed
directly. The public methods are encapsulated into one or more groups called
interfaces. Usually, an interface encapsulates methods that relate to a specific feature of
the underlying class. Interfaces are not exclusive to a single COM class. They only
represent the syntax of the methods and the rules associated with their usage. Any
COM class that would benefit from supporting an interface can implement it. A good
example is the IUnknown interface - every COM class has to implement it. The
IUnknown interface encapsulates all the basic functionalities that the COM architecture
needs.

To help visualize a COM class, it can be seen as a rectangle with rounded corners that
has a “plug-in jack” for each of its interfaces. The IUnknown “plug-in jack” is usually
located on top of the rectangle, while the others are connected to the sides (see Figure
2.1).

PolyWorks SDK Reference Guide 2020 9

Essential COM Principles and Programming Techniques Creating a COM object

2.3 Creating a COM object

There are two common ways to create COM objects: directly or indirectly.

Direct creation is done by asking COM to create an instance of a specific COM class.
Then, COM returns the default interface, or the interface specified in the creation
process. Indirect creation occurs when an object’s method creates a new object and
returns a specific object’s interface.

The examples that follow demonstrate direct and indirect COM creation.

Visual Basic .NET:

Example 1: Direct and indirect COM object creation.

…
Dim iminspect As IMInspectLib.IMInspect = Nothing
Dim currentProject As IMInspectLib.IIMInspectProject = Nothing
Dim commandCenter As IMInspectLib.IIMCommandCenter = Nothing

’create directly the PolyWorks|Inspector server’

iminspect = New IMInspectLib.IMInspect
’get the current project
iminspect.ProjectGetCurrent(currentProject)
’create indirectly a project’s Command Center
currentProject.CommandCenterCreate(commandCenter)
…

C++:

Example 1: Direct and indirect COM object creation.

Before using any COM functionality in a given thread, COM must be initialized by
calling the CoInitializeEx function. When you are finished, COM must be uninitialized by

PolyWorks SDK Reference Guide 2020 10

Essential COM Principles and Programming Techniques Creating a COM object

calling CoUninitialize. Refer to Microsoft’s documentation for information about the

COM API.

#include "IIMInspect.h"
#include "IIMInspect_i.c"

…
CoInitializeEx (NULL, COINIT_APARTMENTTHREADED);

HRESULT hr;
IIMInspect *pIMInspect = NULL;
//create directly the PolyWorks|Inspector server
hr = CoCreateInstance(CLSID_IMInspect, NULL, CLSCTX_SERVER,
IID_IIMInspect, (void**)&pIMInspect);
…

IIMInspectProject* pCurrentProject = NULL;

//get the current project
hr = pIMInspect->ProjectGetCurrent(&pCurrentProject);
…

IIMCommandCenter* pCommandCenter = NULL;

//create indirectly the project’s Command Center
pCurrentProject->CommandCenterCreate(&pCommandCenter);
…

C#:

Example 1: Direct and indirect COM object creation.

…
IMInspectLib.IIMInspect iminspect = null;
IMInspectLib.IIMInspectProject currentProject = null;
IMInspectLib.IIMCommandCenter commandCenter = null;

//create directly the PolyWorks|Inspector server

iminspect = new IMInspectLib.IMInspect();
//get the current project
iminspect.ProjectGetCurrent(out currentProject);
//create indirectly a project’s Command Center
currentProject.CommandCenterCreate(out commandCenter);
…

PolyWorks SDK Reference Guide 2020 11

Essential COM Principles and Programming Techniques Creating a COM object

Visual Basic for Applications:

Example 1: Direct and indirect COM object creation.

…
Dim IMInspectServer As IMInspect
Dim CurrentProject As IImInspectProject
Dim CommandCenter As IIMCommandCenter

’create directly the PolyWorks|Inspector server

Set IMInspectServer = New IMInspect
’get the current project
IMInspectServer.ProjectGetCurrent
CurrentProject
’create indirectly a project’s Command Center
Project.CommandCenterCreate CommandCenter

PolyWorks SDK Reference Guide 2020 12

Essential COM Principles and Programming Techniques Using COM interfaces

2.4 Using COM interfaces

When a COM object is created, an interface is returned. The syntax used to access the
interface’s methods is the same as the one used to access an object’s methods.

Interfaces have a common particularity - they all derive from Microsoft’s IUnknown
interface, which means that all interfaces have access to the functionalities offered by
IUnknown interface. One of these functionalities is the ability to request any interface a
COM object supports from any of its interfaces. This feature allows a developer to
access every aspect of a COM object from a single interface. An interface may meet the
developer’s needs, but it is important to know that this object might have something
else to offer.

When new functionalities are added to a COM class in use by developers, a new
interface is created. Then, if a developer wants to use the new features, it is possible to
ask for the new interface from the one being currently used. By convention, a new
version of an interface has the name of the original interface followed by a version
number. For example, new versions of ISomething would be ISomething2,
ISomething3, and so on.

The examples that follow show how one interface can be requested from another
interface.

Visual Basic .NET:

Example 2(a): Explicit interface request.

…
Dim currentProjectV1 As IMInspectLib.IIMInspectProject =
Nothing
Dim currentProjectV2 As IMInspectLib.IIMInspectProject2 =
Nothing
…
’get the basic project interface
iminspect.ProjectGetCurrent(currentProjectV1)
’ask for the second version of the project interface
currentProjectV2 = currentProjectV1
…

PolyWorks SDK Reference Guide 2020 13

Essential COM Principles and Programming Techniques Using COM interfaces

Example 2(b): Automatic interface request.

…
Dim currentProjectV2 As IMInspectLib.IIMInspectProject2 =
Nothing
…
’get the second version of the project interface even though the
method ‘IIMInspect::ProjectGetCurrent’ returns the
IIMInspectProject interface
iminspect.ProjectGetCurrent(currentProjectV2)
…

C++:

Example 2: Interface request.

The IUnknown method that allows the request of a specific interface is QueryInterface.
The following example shows how it can be used:

…
IIMInspectProject* pCurrentProject = NULL;
//get the basic project interface
hr = pIMInspect->ProjectGetCurrent(&pCurrentProject);
…

IIMInspectProject2* pCurrentProjectV2 = NULL;

//ask for the second version of the project interface
hr = pCurrentProject->QueryInterface(IID_IIMInspectProject2,
(void**)&pCurrentProjectV2);
…

C#:

Example 2: Interface request.

…
IMInspectLib.IIMInspectProject currentProjectV1 = null;
IMInspectLib.IIMInspectProject2 currentProjectV2 = null;
…
//get the basic project interface
iminspect.ProjectGetCurrent(out currentProjectV1);
//ask for the second version of the project interface
currentProjectV2 =
(IMInspectLib.IIMInspectProject2)currentProjectV1;
…

PolyWorks SDK Reference Guide 2020 14

Essential COM Principles and Programming Techniques Managing a COM object’s lifetime

Visual Basic for Applications:

Example 2: Interface request.

…
Dim currentProjectV1 As
IIMInspectProject
Dim currentProjectV2 As
IIMInspectProject2
…
’get the basic project interface
IMInspect.ProjectGetCurrent currentProjectV1
’ask for the second version of the project interface
Set currentProjectV2 = currentProjectV1

2.5 Managing a COM object’s lifetime

In every object-oriented programming language, objects can be created and
destroyed. Generally, developers control an object’s lifetime using functions. When an
object is created, memory is allocated. When the object is destroyed, the associated
memory is freed. However, it is different for COM objects, as they can be used by more
than one application simultaneously. As a result, a single application does not have
enough information to adequately control the lifetime of an object. To solve this
problem, a reference count system was put into place.

The reference count of a COM object is the number of interfaces currently in use. Each
time an object’s interface is requested, the reference count is incremented. When an
interface is released, the reference count is decremented. As long as the reference
count is greater than zero, the object stays in memory. When the reference count
reaches zero, the object destroys itself.

Each programming language has its own way of using the reference count system.

Visual Basic .NET or Visual Basic for Applications:

In this programming language, the reference count system is transparent. However,

developers should be careful not to leave a reference to an interface that is no longer
useful in a variable. One way to ensure this is to set the variable to Nothing (e.g.,
iminspect = Nothing), thereby releasing the interface.

C++:

As mentioned earlier, every COM class implements Microsoft’s IUnknown interface. Two
IUnknown methods are dedicated to controlling a COM object’s lifetime: AddRef and
Release. AddRef increments the reference count, while Release decrements it.

PolyWorks SDK Reference Guide 2020 15

Essential COM Principles and Programming Techniques Managing a COM object’s lifetime

Every function and method that returns an interface has the responsibility of calling the
AddRef method. As a result, when a COM object is created, and a QueryInterface is
performed, or when any other function returns a pointer to an interface, AddRef is
called.

Most of the time, developers don’t have to call AddRef unless they create a function
that returns an interface or copy an interface pointer directly into a variable. However,
developers will have to use the Release method much more. When an interface is no
longer useful, the Release method has to be called. For each AddRef, there should be a
Release.

If too many Releases are done, the COM object will be destroyed too early, and system
behavior will become unpredictable. To avoid this situation, the procedure that follows
is recommended. Set each interface pointer to NULL on initialization and on release.
Then, at the end of the application, call Release for all nonNULL interface pointers.

PolyWorks SDK Reference Guide 2020 16

Essential COM Principles and Programming Techniques Managing a COM object’s lifetime

Example 3: Use of the AddRef and Release methods.

…
IIMInspect* pIMInspect = NULL;
IIMInspectProject* pCurrentProject = NULL;
IIMInspectProject* pCurrentProjectCopy = NULL;
…

//create the PolyWorks|Inspector server

hr = CoCreateInstance(CLSID_IMInspect, NULL, CLSCTX_SERVER,
IID_IIMInspect, (void**)&pIMInspect);
…

//get the current project

hr = pIMInspect->ProjectGetCurrent(&pCurrentProject);
…
//get a copy of the project interface pointer, not a copy of
//the project
pCurrentProjectCopy = pCurrentProject;
pCurrentProjectCopy->AddRef();
…

//cleanup code
if(pCurrentProjectCopy != NULL)
{
pCurrentProjectCopy->Release();
pCurrentProjectCopy = NULL;
}

if(pCurrentProject != NULL)
{
pCurrentProject->Release();
pCurrentProject = NULL;
}

if(pIMInspect != NULL)
{
pIMInspect->Release();
pIMInspect = NULL;
}
…

PolyWorks SDK Reference Guide 2020 17

Essential COM Principles and Programming Techniques Managing a COM object’s lifetime

C#:

In C#, the reference count system is transparent. However, developers should be careful
not to leave a reference to an interface that is no longer useful in a variable. One way to
ensure this is to set the variable to null (e.g., iminspect = null), thereby releasing the
interface.

PolyWorks SDK Reference Guide 2020 18

Using the PolyWorks
SDK
3
This chapter explains how to use the PolyWorks SDK.

PolyWorks SDK Reference Guide 2020 19

Using the PolyWorks SDK Installation

3.1 Installation
The PolyWorks SDK installation is done during the PolyWorks installation, and is located
in the goodies\PolyWorksSDK folder of the PolyWorks installation path.

3.2 Plug-ins vs. client applications

There are two different types of external modules: plug-ins and client applications.

Plug-ins are dynamic link libraries (DLL files) that must be loaded by a PolyWorks
Metrology Suite module, and then queried to determine what functionalities they have
to offer to the module that loads them. In this context, both the plug-ins and the
PolyWorks Metrology Suite module are aware of each other through COM interfaces,
and they can be considered at the same time clients of, and servers to, each other. Plug-
ins are used to add specific functionalities to PolyWorks Metrology Suite modules, such
as probing devices and macro commands, and they are accessible through the
PolyWorks Metrology Suite module’s graphical user interface (GUI). Since plug-ins are
running in the same process as the PolyWorks Metrology Suite module, the
performance cost added by the COM layer is minimal.

Client applications usually are executable modules (EXE files) that communicate with a
PolyWorks Metrology Suite module through the COM objects exposed by the latter. In
this context, client applications are, obviously, clients, while PolyWorks Metrology Suite
modules are servers. A server is mostly unaware of the presence of client applications,
and cannot interact directly with them. Client applications can use PolyWorks
Metrology Suite modules to import, process, and export data that they use afterward,
for example. Unlike plug-ins, they do not directly add functionalities to a PolyWorks
Metrology Suite module, and must be located and executed manually by users.
Another difference with plug-ins is that since client applications are not running in the
same process as the PolyWorks Metrology Suite module, the performance cost added
by the COM layer can be significant when numerous methods are called, or when
transferring large amounts of data to and from the server.

Note that only plug-ins can make use of the additional functionalities offered by the
C++-only API, while client applications are limited to using the COM objects. Plug-ins
cannot be produced using Visual Basic for Applications since the language does not
allow the generation of a DLL library.

3.3 PolyWorks servers and external modules

The functionalities provided by the SDK come mainly from four server modules:
IMAlign, PolyWorks|Modeler, PolyWorks|Inspector, and Workspace Manager. The basic
rules associated with these servers are as follows:

 A server is usually started manually by starting the desired PolyWorks Metrology

Suite module. External modules (mostly client applications) can also start a server
automatically by creating a new COM object for which no appropriate server is

PolyWorks SDK Reference Guide 2020 20

Using the PolyWorks SDK External module samples

already running. Creating a COM object is not required for plug-ins since their life
begins when they are loaded by an already running PolyWorks server.

 A server will be up and running until the user or an external module shuts it down
(e.g., through a FILE EXIT command). Unlike most COM servers, automatically starting
a server through the creation of a COM object and then releasing this COM object will
not automatically close a PolyWorks server. This is because a PolyWorks Metrology
Suite module is also used by the Workspace Manager, which adds more references to
the PolyWorks server and thereby maintains it alive even though clients are no
longer using it.

 While plug-ins always use the server that loads them, client applications share their
servers. For client applications, only one server per module can be available at a
specific time on a specific computer. However, multiple instances of these PolyWorks
Metrology Suite modules may be running simultaneously, but only the first instance
will be considered the SDK server. If this server closes, the next running instance of
the module will become the SDK server for client applications, and if there is no
currently running instance, then the next one to be started will become the server.

 When a server is closed, all the plug-ins loaded by it are properly terminated and
unloaded. For client applications, however, it is impossible to know when a server
closes, and it can be dangerous to still have interface pointers to objects created on
the closed server. Care must be taken not to use such now-invalid pointers anymore.
Therefore, it is usually easier and safer to use plug-ins instead of client applications,
unless such applications have complete control over the server they use.

3.4 External module samples

The source code for plug-in and client application samples is available in the
\goodies\PolyWorksSDK\samples folder located in the PolyWorks installation path (see
Figure 3.1). Certain subfolders are of particular interest:

 \plugins\common: Contains plug-in samples usable by every server module.

 \applications: Contains client application samples, located in subfolders for each

PolyWorks Metrology Suite module.

 \data: Contains the data files shared by the samples.

The samples provided are described in documents found in the

\goodies\PolyWorksSDK\help folder of the PolyWorks Metrology Suite installation folder.
The C++ samples that use the C++ SDK are described in the following document:

 PolyWorksSDKReferenceGuideCpp.chm

The other examples are described in the following document in the Samples section:

 PolyWorksSDKReferenceGuideCOM.chm

PolyWorks SDK Reference Guide 2020 21

Using the PolyWorks SDK External module samples

Figure 3.1 The Goodies branch of the PolyWorks Metrology Suite installation folder.

3.4.1 Client application samples

Each sample is dedicated to showing distinct aspects of the PolyWorks SDK. Here is a
brief summary of what to expect of each sample in the subfolder:

Client application sample and description

Module
(...goodies\PolyWorksSDK\samples\applications...)

\IMAlign\CSharp\CSharpSimpleAlignment
\IMAlign\VisualBasic.Net\VBNetSimpleAlignment
\IMAlign\VisualCpp\VCppSimpleAlignment
IMAlign
This application launches a series of commands to read a group of
pif files into IMAlign. These files are then aligned and saved as an
IMAlign project.

PolyWorks SDK Reference Guide 2020 22

Using the PolyWorks SDK External module samples

Client application sample and description

Module
(...goodies\PolyWorksSDK\samples\applications...)

\IMEdit\CSharp\CSharpWallCreation
\IMEdit\VisualBasic.Net\VBNetWallCreation
PolyWorks| \IMEdit\VisualCpp\VCppWallCreation
Modeler
This application launches a series of commands to read a .pol
polygonal model file into PolyWorks|Modeler, and perform a wall
creation.

\IMInspect\CSharp\CSharpReadAndFit
\IMInspect\VisualBasic.Net\VBNetReadAndFit
\IMInspect\VisualCpp\VCppReadAndFit

This application reads an ASCII file of a point cloud containing

points with coordinates and normals. The points are sent to
PolyWorks|Inspector, and a sphere is fitted to them.
PolyWorks|
\IMInspect\VBAExcel\VBABlockInspection
Inspector
This Excel document uses VBA macros to control
PolyWorks|Inspector. Pressing the Start inspection button
launches the macro. Data are loaded and aligned, then a
comparison is made. A temporary comparison report is exported
from which the document obtains information to complete itself.

\WorkspaceManager\CSharp\CSharpManageModules
\WorkspaceManager\VisualCpp\VCppManageModules

This application demonstrates how to interact with the Workspace

Manager and its modules. The application shows how to run a
command, how to start a new module, how to get a list of the
already running modules, and how to get an access to a specific
Workspace module using its project name.
Manager
\WorkspaceManager\VBAExcel\VBAHelloWorld

This Excel document uses VBA macros to control the Workspace

Manager. Pressing the Say Hello button will echo a Hello World
message in the Workspace Manager command history. This
sample demonstrates how to send commands to the Workspace
Manager.

PolyWorks SDK Reference Guide 2020 23

Using the PolyWorks SDK External module samples

3.4.2 Plug-in samples

Each sample is dedicated to showing distinct aspects of the PolyWorks SDK. Here is a
brief summary of what to expect of each sample in the subfolder:

Plug-in sample and description

Language
(...\goodies\PolyWorksSDK\samples\plugins\common...)

\Visual\VCpp3DSceneRendering
Shows how to create and add the IM::IDrawNode derived class to
the host application draw nodes collection. When added, the draw
node will draw simple shapes, text, and annotations into the 3D
scene.
\VisualCpp\VCppBasic
Shows how to implement a basic plug-in supporting common
COM Interfaces such as IIMPlugin and IIMCommand.
\VisualCpp\VCppCommands
Shows how to implement MSCL commands with arguments
\VisualCpp\VCppDialog
Visual Studio Shows how to add a dialog box to the Dialog Zone and how to use
C++ the RedLabels associated with some of the controls of the dialog
box.

\VisualCpp\VCppLineScanFramework
Shows how to implement a new line scanning plug-in.
\VisualCpp\VCppPlanarScanFramework
Shows how to implement a new Planar Scanner plug-in.

\VisualCpp\VCppProbeFramework
Shows how to implement a new probing plug-in.
\VisualCpp\VCppRotaryTableFramework
Shows how to implement a new Rotary Table plug-in.

PolyWorks SDK Reference Guide 2020 24

Using the PolyWorks SDK The API Reference Manual

Plug-in sample and description

Language
(...\goodies\PolyWorksSDK\samples\plugins\common...)

\CSharp\CSharp3DSceneRendering
Shows how to create and add the IM::IDrawNode derived class to
the host application draw nodes collection. When added, the draw
node will draw simple shapes, text, and annotations into the 3D
Scene.
\CSharp\CSharpBasic
Shows how to implement a basic plug-in supporting common
Visual Studio C# COM Interfaces such as IIMPlugin and IIMCommand.

\CSharp\CSharpCommands
Shows how to implement MSCL commands with arguments.
\CSharp\CSharpLineScanFramework
Shows how to implement a new Line Scanner plug-in.
\CSharp\CSharpPlanarScanFramework
Shows how to implement a new Planar Scanner plug-in.

\VisualBasic.Net\VBNet3DSceneRendering
Shows how to create and add the IM::IDrawNode derived class to
the host application draw nodes collection. When added, the draw
node will draw simple shapes, text, and annotations into the 3D
Visual Studio Scene.
Visual Basic \VisualBasic.NET\VBNetBasic
.NET
Shows how to implement a basic plug-in supporting common
COM Interfaces such as IIMPlugin and IIMCommand.

\VisualBasic.NET\VBNetCommands
Shows how to implement MSCL commands with arguments.

3.5 The API Reference Manual

The COM Application Programming Interface (API) of the PolyWorks SDK is
documented in the API Reference Manual that can be found in the
\goodies\PolyWorksSDK\help subfolder of the PolyWorks Metrology Suite installation
folder.

Regarding the C++ API, the document PolyWorksSDKReferenceGuideCpp.chm provided

in the\goodies\PolyWorksSDK\help folder located in the PolyWorks Metrology Suite
installation folder contains the information necessary to its usage. This document also
explain how the C++ API can be used from managed code (e.g., Visual Basic .NET, C#).

PolyWorks SDK Reference Guide 2020 25

Using the PolyWorks SDK Overview of certain COM interfaces

3.6 Overview of certain COM interfaces

There are many different functionalities provided by the PolyWorks SDK through its
numerous COM interfaces. Here is an overview of certain interfaces. To learn more
about them or the rest of the interfaces, consult the API Reference Manual.

Table 1: Server interfaces usable by external modules

Interface Description

IIMAlign Gives the access to the IMAlign server. This is the default
interface of the IMAlign COM Class, which is usually the
starting point for IMAlign client applications.

IIMCommandCenter Gives access to the Macro Script Control Language (MSCL).

IIMEdit Gives the access to the PolyWorks|Modeler server. This is the

default interface of the IMEdit COM Class, which is usually
the starting point for PolyWorks|Modeler client applications.

IIMHost Allows to access a plug-in’s host application’s informations

and features. Note that this interface can be queried for a
specific module’s interface, such as IIMInspect or IIMAlign.
Since plug-ins receive a pointer to such an interface in their
Load method, they can adapt their behavior for specific
modules.

IIMInspect Gives the access to the PolyWorks|Inspector server. This is

the default interface of the IMInspect COM Class, which is
usually the starting point for PolyWorks|Inspector client
applications.

IIMLineScan Allows adding lines of points.

IIMMessageCenter Allows displaying message dialog boxes.

IIMPlanarGrid Allows adding planar-grid-organized points.

IIMPointCloud Allows directly adding points.

IIMRealTimeInspector Allows controlling the real-time inspection process.

IIMSceneCamera Allows controlling aspects of the scene visualization.

IIMSettingsRepository Allows manipulating a repository of IIMSettings (only

available to plug-ins.)

Table 2: Interfaces that can be implemented by plug-ins

Interface Description

Allows elaborating an InnovMetric command, including its

IIMCommand
menu item.

IIMLanguage Allows changing the language used by dialog boxes.

PolyWorks SDK Reference Guide 2020 26

Using the PolyWorks SDK Overview of certain COM interfaces

Table 2: Interfaces that can be implemented by plug-ins

Interface Description

IIMPlugin Allows manipulating a plug-in.

IIMProbe Allows manipulating a probing device.

IIMRotaryTable Allows manipulating a rotary table.

IIMScanner Allows manipulating a scanning device.

IIMSettings Exposes settings to be kept in a IIMSettingsRepository.

PolyWorks SDK Reference Guide 2020 27

Plug-ins 4
The chapter explains how to create and install plug-ins.

PolyWorks SDK Reference Guide 2020 28

Plug-ins Creating plug-ins

4.1 Creating plug-ins

To help you to create your plug-ins, you can use our samples in the
goodies\PolyWorksSDK\samples subfolder of the PolyWorks Metrology Suite installation
folder (typically, C:\Program Files\InnovMetric\PolyWorks MS 2020).

For instructions, follow the steps in the help files (i.e., HowToCreateYourOwnPlugin.txt or
readme.txt) provided with each sample.

4.2 Using plug-ins

4.2.1 Plug-in location

Plug-ins must be placed in the plugins subfolder of the PolyWorks Metrology Suite
installation folder (typically, C:\Program Files\InnovMetric\PolyWorks MS 2020).

Supporting files for a plug-in (i.e., other required DLLs) should be placed in a subfolder
(named after the related plug-in file, minus the “.dll” extension) of the plugins folder, if
at all possible. For Visual Basic .NET and C# plug-ins, required DLLs must instead each
be placed in a subfolder named after the required DLL, minus the ".dll" extension.

In particular cases where using a subfolder of the plugins is not an option, then
supporting files can be placed alongside the executable files that will load the plug-in,
in the bin folder (or a subfolder, again if at all possible).

4.2.2 Plug-in registration

The COM components of a new plug-in must be registered before the plug-in can be
used by the PolyWorks Metrology Suite.

Whenever a plug-in and any supporting files are first copied to the \plugins folder (as
mentioned in Section 4.2.1 Plug-in location), you must run the
RegisterIMCOMServers.bat file found in the \bin folder to register the plug-in.

To correctly take into account Windows security measures, the .bat file must be run
with elevated permissions. The exact steps required to do this depend on the version of
Windows you are using:

 Windows 7:

Right-click on the RegisterIMCOMServers.bat file and select Run as administrator. The

registration will be effective for all users.

 Windows 8 and later:

PolyWorks SDK Reference Guide 2020 29

Plug-ins Plug-in deployment

Right-click on the RegisterIMCOMServers.bat file and select Run as administrator. The

registration will be effective for the current user only.

4.2.3 Accessing plug-ins

Every PolyWorks Metrology Suite module that can be accessed from the PolyWorks SDK
has a submenu called Tools > Plug-ins.

The primary purpose of this document is to allow users to easily access new menu
items and commands added by plug-ins (see the IIMCommand interface for more
information).

Note that some types of plug-ins, such as probing devices plug-ins, do not add menu
items under the Tools > Plug-in submenu, but instead are accessed through some other
part of the PolyWorks Metrology Suite module’s GUI, such as the probing devices dialog
box in PolyWorks|Inspector.

4.3 Plug-in deployment

4.3.1 Deploying plug-ins using Microsoft’s Platform SDK for Windows

Installer

This section explains how to properly deploy and install your own plug-in into the
PolyWorks Metrology Suite installation folder. Microsoft Developer Network (MSDN)
contains all the information related to the functions that follow.

You can determine whether the PolyWorks Metrology Suite is installed and obtain the
path to the installation folder by using two functions: MsiEnumProductsW and
MsiGetProductInfoW.

The three important properties you will need to get are:

 INSTALLPROPERTY_PRODUCTNAME

 INSTALLPROPERTY_INSTALLLOCATION

 INSTALLPROPERTY_VERSION[STRING or MAJOR/MINOR]

The product name (from INSTALLPROPERTY_PRODUCTNAME) should begin with

PolyWorks and should not contain “Plug-ins”, “Translator” or “License Server”. A typical
valid name is “PolyWorks Metrology Suite 2020”.

When you get the location (from INSTALLPROPERTY_INSTALLLOCATION), add

“\plugins” to the returned path and that is where you should install the main dll for your
plug-in.

PolyWorks SDK Reference Guide 2020 30

Plug-ins Plug-in deployment

Ex: INSTALL_DIR\plugins\CompanyNamePlugin.dll

In most cases, any additional DLLs required by your plug-in should be installed in a
subfolder named like this:

INSTALL_DIR\plugins\[name of your plug-in without extension]

Ex: INSTALL_DIR\plugins\CompanyNamePlugin\Additional1.dll

INSTALL_DIR\plugins\CompanyNamePlugin\Additional2.dll

For Visual Basic and C#, assembly binding is different. Therefore, any additional DLLs
required by your plug-in should be installed in a subfolder named like this:

Ex: INSTALL_DIR\plugins\Additional1\Additional1.dll

INSTALL_DIR\plugins\Additional2\Additional2.dll

You can refer to the MSDN documentation for more information on assembly binding
in .NET.

The version of the PolyWorks Metrology Suite can be obtained with the
INSTALLPROPERTY_VERSION[STRING or MAJOR/MINOR] properties, and you should
only install your plug-in if the version of the PolyWorks Metrology Suite meets the
requirements for your plug-in.

For example, if you use a new COM interface that appeared in PolyWorks Metrology
Suite 2019, do not install your plug-in if the PolyWorks Metrology Suite major
version is 2018 or earlier.

Here is a sample application that demonstrates how to obtain the version, the platform,
and the path for installed PolyWorks products:

#include <windows.h>
#include <Msi.h>
#include <MsiDefs.h>
#include <MsiQuery.h>
#include <stdio.h>

PolyWorks SDK Reference Guide 2020 31

Plug-ins Plug-in deployment

int wmain(int argc, wchar_t* argv[])

{
// Enumerate all products installed on the system.
wchar_t productCode[256];
int i = 0;
while (ERROR_NO_MORE_ITEMS != MsiEnumProductsW(i++,
productCode))
{
DWORD count = 1024;
wchar_t productName[1024] = L"";
MsiGetProductInfoW(productCode,
INSTALLPROPERTY_PRODUCTNAME, productName, &count);

// Skip those whose ProductName doesn't contain

"PolyWorks".
if (wcsstr(productName, L"PolyWorks") == NULL)
{
continue;
}
// Skip those whose ProductName contains either
"License
// Server", "Plug-ins" or "Translator"
// (we're only interested in the main PolyWorks
product; not
// the add-ons).
if ( wcsstr(productName, L"License Server") != NULL
||
wcsstr(productName, L"Plug-ins") != NULL ||
wcsstr(productName, L"Translator") != NULL)
{
continue;
}

// Retrieve the version for this product

wchar_t version[1024] = L"";
MsiGetProductInfoW(productCode,
INSTALLPROPERTY_VERSIONSTRING, version, &count);

// Retrieve the package (MSI) for this product.

wchar_t productMSIPath[MAX_PATH] = L"";
count = _countof(productMSIPath);
MsiGetProductInfoW(productCode,
INSTALLPROPERTY_LOCALPACKAGE, productMSIPath,
&count);

// Retrieve its Summary Information stream.

MSIHANDLE hSummaryInfo = NULL;
MsiGetSummaryInformationW(NULL, productMSIPath, 0,
&hSummaryInfo);

PolyWorks SDK Reference Guide 2020 32

Plug-ins Plug-in deployment

// From the Summary Information stream, we can obtain

the
// Template Summary property.
// It indicates which platform the package targets.
wchar_t propValue[128] = L"";
count = _countof(propValue);
UINT propType = 0;
MsiSummaryInfoGetPropertyW(hSummaryInfo, PID_TEMPLATE,
&propType, NULL, NULL, propValue, &count);
const bool platformIsX64 = wcsstr(propValue,
L"x64") != NULL;

// Obtain the installation folder.

wchar_t productDir[1024] = L"";
count = _countof(productDir);
MsiGetProductInfoW(productCode, L"InstallLocation",
productDir, &count);

wprintf( L"\n+
%s"
L"\n - Version: %s"
L"\n - Platform: %s"
L"\n - Location: %s\n", productName,
version, (platformIsX64 ? L"x64" :
L"Win32"), productDir);
}
return 0;
}

Note that a new plug-in must also be registered before it can be used by the PolyWorks
Metrology Suite, as mentioned in Section 4.2.2 Plug-in registration. To do this, you can
either add the required registry keys to your installation program, or find a way for your
installation program to end with a call (with elevated permissions) to the
bin\RegisterIMCOMServers.bat file located in the PolyWorks Metrology Suite
installation folder.

4.3.2 Installing documentation for plug-ins

You can install a PDF document in "INSTALL_DIR\documentation" that respects our

naming scheme. If you do that, the documentation will be automatically available
using our menus.

Ex: INSTALL_DIR\documentation\PolyWorksPlug-in_[aei]_Company_Name.pdf

This adds the following menu item in the Workspace Manager: "Help\References
Guides\Plug-ins\Company Name".

PolyWorks SDK Reference Guide 2020 33

Plug-ins Advanced hints and tips

It also adds the following menu item in the IMAlign ([a]), the PolyWorks|Modeler ([e]),
and the PolyWorks|Inspector ([i]) modules (specified by [aei] in the file name):
"Help\References Guides\Company Name".

The letters in the file name, that designate the modules to which a PDF document is to
be added, can be given in any order and number. Valid examples include:

 PolyWorksPlug-in_[aie]_Company_Name.pdf

 PolyWorksPlug-in_[ia]_Company_Name.pdf

 PolyWorksPlug-in_[e]_Company_Name.pdf

4.4 Advanced hints and tips

4.4.1 Plug-ins that use hardware or software resources

In order to avoid conflict while accessing hardware or software resources that may be
used by another plug-in, it is recommended to send commands (if any exist) by means
of the IIMCommandCenter interface in order to close and disconnect any existing plug-
in that you know might use the same resources, before attempting to connect to those
resources in your plug-in.

PolyWorks SDK Reference Guide 2020 34

Client Applications 5
The chapter explains how to create client applications.

PolyWorks SDK Reference Guide 2020 35

Client Applications Creating client applications

5.1 Creating client applications

This section explains briefly how to create a client application using:

 Visual Basic .NET in Visual Studio

 Visual Basic for Applications macros

 Visual C++

 C# in Visual Studio

PolyWorks SDK Reference Guide 2020 36

Client Applications Creating client applications

5.1.1 Creating a client application using Visual Basic .NET in Visual Studio

To create a client application using Visual Studio, follow this procedure:

1. Start Visual Studio.

2. Create a new project, such as a Console Application, by choosing File > New >
Projects and choosing the Windows Forms App or Console App template for the
desired language.

3. Choose Project > Add References to display the References window.

4. Browse for your PolyWorks distribution bin folder and, in the list, select the Interop
DLL of the PolyWorks Metrology Suite module you want to use as a server and select
it. For example, selecting Interop.IMInspectLib.dll will enable PolyWorks|Inspector
COM objects in your project.

5. Press the OK button and start building the project itself.

6. You can then create an PolyWorks|Inspector server object with code similar to:

Dim iminspect As IMInspectLib.IMInspect = New IMInspectLib.IMInspect

PolyWorks SDK Reference Guide 2020 37

Client Applications Creating client applications

5.1.2 Creating a client application using Visual Basic for Applications

macros

To create a client application using Visual Basic for Applications macros, follow this
procedure:

1. Start Excel.

2. Enable the Developer Ribbon item by checking File > Options > Customize Ribbon >
Developer

3. Create a spreadsheet.

4. Choose Developer > Visual Basic.

5. In the Visual Basic Editor, select Tools > References to display the References window.

6. In the list of available references, look for the type library of the PolyWorks
Metrology Suite module you want to use as a server and select the check box beside
it. For example, checking the PolyWorks|Inspector 2020 (64-bit) Type Library
entry will enable PolyWorks|Inspector COM objects in your project.

7. You can then create an PolyWorks|Inspector server object with code similar to:

Dim iminspectServer As New IMInspect

PolyWorks SDK Reference Guide 2020 38

Client Applications Creating client applications

5.1.3 Creating a client application using Visual C++

To create a client application using Visual C++, follow this procedure:

1. Start Visual C++.

2. Create a new project, such as a Console Application, by choosing File > New >
Projects > Windows Console Application.

3. Modify the settings of the project. Choose Projects > Properties > C/C++ >
Preprocessor > Preprocessor definitions, and:

remove: _MBCS
add: _WIN32_DCOM; _UNICODE

4. Choose Tools > Properties > C/C++ > General > Additional Include Directories, and add
the %PolyWorks Path%\goodies\PolyWorksSDK\include\ folder to the
Additional Include Directories. %PolyWorks Path% must be replaced by your
PolyWorks Metrology Suite installation folder.

5. Start building your project.

6. Include the files (*.h and *.c) of the include folder that relate to the PolyWorks
Metrology Suite module that you want to use. An example for the
PolyWorks|Inspector server:

#include "IIMInspect.h"
#include "IIMInspect_i.c"
…

7. You can create an PolyWorks|Inspector server object with similar code placed
between "CoInitializeEx" and "CoUninitialize" statements:

IIMInspect* pIMInspect = NULL;

CoCreateInstance(CLSID_IMInspect, NULL, CLSCTX_SERVER,
IID_IIMInspect, (void**)&pIMInspect);

8. To let your client application work with the latest version of the PolyWorks
Metrology Suite installed on the user’s computer, you can create a
PolyWorks|Inspector server object with the following code placed between
"CoInitializeEx" and "CoUninitialize" statements:

IIMInspect* pIMInspect = NULL;

CLSID programID;
CLSIDFromProgID(L"InnovMetric.PolyWorks.IMInspect", &programID);
CoCreateInstance(programID, NULL, CLSCTX_SERVER,
IID_IIMInspect, (void**)&pIMInspect);

PolyWorks SDK Reference Guide 2020 39

Client Applications Creating client applications

5.1.4 Creating a client application using C# in Visual Studio

To create a client application using Visual Studio, follow this procedure:

1. Start Visual Studio.

2. Create a new project, such as a Console Application, by choosing File > New >
Projects and choosing the Windows Forms App or Console App template for the
desired language.

3. Choose Project > Add References to display the References window.

4. Browse for your PolyWorks distribution bin folder and, in the list, select the Interop
DLL of the PolyWorks Metrology Suite module you want to use as a server and select
it. For example, selecting Interop.IMInspectLib.dll will enable PolyWorks|Inspector
COM objects in your project.

5. Press the OK button and start building the project itself.

6. You can then create a PolyWorks|Inspector server object with code similar to:

IMInspectLib.IIMInspect iminspect = new IMInspectLib.IMInspect();

PolyWorks SDK Reference Guide 2020 40

Client Applications Using client applications

5.2 Using client applications

5.2.1 Client application location

Client applications can be executed from any location on a computer where the
PolyWorks SDK has been installed.

5.2.2 Accessing client applications

Since client applications are independent executables, they can usually not be
accessed through a PolyWorks Metrology Suite module’s GUI. Users must locate and
run client applications manually.

5.3 Advanced hints and tips

5.3.1 Mixing 32-bit and 64-bit modules

You can use a 32-bit client to communicate with the PolyWorks Metrology Suite (which
is a 64-bit software) thanks to the 32-bit marshaler DLLs that are available within the
distribution.

PolyWorks SDK Reference Guide 2020 41

Glossary

# Symbol used in dialog boxes to represent the term “Number

(of )”. For example, # displayed points should be read as
“Number of displayed points”.

API An abbreviation that stands for Application Programming

Interface.

Client Applications Client applications are independent applications that use

PolyWorks Metrology Suite modules without being
integrated in them.

COM An acronym that stands for Component Object Model. COM

is an object-oriented programming model used by
numerous applications. Essentially, it allows libraries and
applications to share some of their components with other
applications.

COM Interface An encapsulation of methods that relate to a specific feature

of the underlying class. Interfaces are not exclusive to a
single COM class; rather, they represent the syntax of the
methods and the rules associated with their usage.

COM Object A COM object is an instance of a COM class that has been
made available by a library or an application through
Microsoft’s COM architecture.

External Module External modules can communicate with PolyWorks

Metrology Suite modules with the help of a software
development kit (SDK) known as the PolyWorks SDK, which
uses Microsoft’s COM architecture. The expression external
module is used to designate both plug-ins and client
applications. See Plug-in and Client Applications.

NA An abbreviation that stands for Not Applicable. Used in

tables where no value can be attributed for a given item.

Plug-in Plug-ins are dynamic link libraries (DLLs) that directly add
functionalities to a PolyWorks Metrology Suite module.

SDK An abbreviation that stands for Software Development Kit.

PolyWorks SDK Reference Guide 2020 42

Glossary

Server A library or an application that provides services to external

applications.

PolyWorks SDK Reference Guide 2020 43

Index

A AddRef method 15
interface 13
AddRef, IUnknown method 15 Release method 15
API reference manual 25

P
C
plug-in SDK, installation 20
C# plug-ins
automatic interface requests 14, 15 creating 29
creating COM objects 11 menus 41
reference count system implementation 18 PolyWorks|Modeler server, basic rules 20
C++ programming languages, supported 6
creating COM objects 10
interface request 14
reference count system implementation 15 V-Z
COM
Visual Basic .NET
class 9
automatic interface requests 14
concept of 9
creating COM objects 10
interfaces 9
explicit interface requests 13
COM objects
reference count system implementation 15
creating directly and indirectly 10
definition of 9
interfaces 9
managing the lifetime of 15
reference count system 15
requesting interfaces 13
Component Object Model. See COM

E
External modules
samples 21

I
IMAlign server, basic rules 20
IMInspect server, basic rules 20
IUnknown

PolyWorks SDK Reference Guide 2020 44