DAVID4 SDK  1.9.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Introduction

Overview

The DAVID4 SDK allows you to write own software programs that use the DAVID functionality, e.g. for batch scanning, bin picking, quality inspection, etc.

There are two modes how to use the SDK: DLL Mode and Client/Server Mode. Both use the same interface, so it's easy for you to switch.

DLL Mode

A DLL is a usual way to include software libraries into your own software: We supply header files and a DLL, and you include/link them into your project. The DLL has a low-level C API, but we recommend to use our C++ wrapper classes, which are included in our SDK package.

Client/Server Mode

Your client program remotely controls one or several DAVID4 servers. This concept is illustrated in this figure:

client-server.png
Client application sends requests to DAVID servers running on the same PC as the client or on different PCs. TCP/IP connection handling is mostly hidden within the DAVID SDK.

Each DAVID server is a DAVID4 Enterprise Edition software instance, running on a Windows PC and started in server mode. It is usually invisible, but can be made visible via its Systray icon or by a command from the client.

The user application (client) is connected to the DAVID servers via TCP/IP connections. But don't worry, connection handling is mostly hidden within the DAVID SDK. This way, you can remote control several DAVID servers from one client at once. The DAVID servers can be located on the same machine as the client (local host) or on different machines that are connected over network. The client can run on any operating system with TCP support. There is a low-level JsonRpc interface you can access, but the easiest way is to use our C++ wrapper which is included in our SDK package.

Client Example Code

Before we go into details within the next sections, let's have a look at a simple example.

#include "davidSDK/david.h"
void main()
{
try
{
david.Connect();
for (double angle=0.0; angle < 360.0; angle += 45.0)
{
david.sls().Scan();
int meshID = david.sls().AddToShapeFusion();
david.fusion().Rotate(meshID, david::TransformGlobalY, -angle);
david.turntable().Rotate(45.0);
}
int fusionMeshID = david.fusion().Fuse(1000);
david.fusion().ExportMesh(fusionMeshID, "FusionResult.stl");
}
catch (david::Exception& e)
{
e.Print();
}
}

This is a completely working example including simple error handling. It makes several scans from different views, fuses them, and exports the fusion result as 'FusionResult.stl'. The single include

#include "davidSDK/david.h"

at the beginning is the only include you need. It will give you access to all important DAVID SDK functions and classes. The most important class is david::Client. It stores all information about the connection between exactly one client and one server. In

david.Connect();

a client instance is generated and a connection between our application client and a running DAVID server is established using 'localhost' at a DAVID standard port. You always need a reference to this client instance in order to get access to the module interfaces. See david.h to switch to DLL Mode.

By

david.sls()

an interface to the david::StructuredLightScanner module is requested so you can e.g. make a new scan:

david.sls().Scan();

This new scan is then copied to the david::ShapeFusion module via the function call

int meshID = david.sls().AddToShapeFusion();

It returns a mesh ID so you can do some operations on this mesh. In this case, we want to rotate our new scan so that all scans are correctly aligned within the same coordinate systems:

david.fusion().Rotate(meshID, david::TransformGlobalY, -angle);
Warning
In this example, we assume that we exactly know the rotation axis (here y axis), since we are using a perfectly calibrated turntable scan system.

The function call

david.turntable().Rotate(angle);

tells the turntable to rotate by 'angle' degrees.

After finishing all scans, we fuse all scans with resolution "1000" by

int fusionMeshID = david.fusion().Fuse(1000);

Here again, we get a mesh ID. In this case, we use it to export the fusion result as a STL file:

david.fusion().ExportMesh(fusionMeshID, "FusionResult.stl");
Warning
File paths like "c:\\meshes\\FusionResult.stl" are interpreted as files located on the server. For files located on the client you have to use a shared network path like "\\\\mycomputer\\meshes\\FusionResult.stl".

DAVID Server

A client connects to a running server. This server is an instance of the DAVID4 Enterprise software started with the parameter "server":

DAVID4E_x64.exe -server

On 32-bit systems, use:

DAVID4E_Win32.exe -server
Note
By default, DAVID uses the TCP/IP ports 10500 and 10501 (10500+1) for communication between client and server. If you want to run several DAVID servers on the same machine or the standard port is blocked by another program, you can also supply a different port.

Example:

DAVID4E_x64.exe -server -port 10600

DAVID will now use the ports 10600 and 10601. Do not forget to use this port in your client code, too.

You can also start a server on your local machine with the API function david::Client::StartServer:

david.StartServer("..\\DAVID4", 10600);

Alternatively, you can run the included Start_DAVID_SDK_Server_xxx.bat, which starts DAVID in Server Mode with the default port.

Note
Probably your desktop firewall will pop up when the DAVID Server tries to open TCP ports. Please allow that, otherwise no connections between server and client will be possible.

Important Classes

david::Client: Handles connection between client and server, initializes library, and gives you access to all module interfaces.

david::IStructuredLightScanner: Interface to the 'Structured Light Scanning' module.

david::IShapeFusion: Interface to the 'Shape Fusion' module.

david::ITurntable: Interface to the 'Turntable' module.

david::IMeasure: Interface to the 'Measurement' module.

david::IMainWindow: Interface to the 'Main Window' module.

Namespaces

Note
The important namespaces for the standard user are david and examples.

david: The standard namespace for most users.

examples: Here you can find source code examples separated from the normal code.

david::jsonrpc: The low level network code and TCP/IP communication protocol is located within this namespace. Only look here, if you want to implement remote functions on a specific platform that is not directly supported by our standard C++ API.

Error Handling

The high level error handling in DAVID SDK is via C++ exceptions. This allows the user to separate normal control flow from error control flow, thus making the programs much more readable. The basic concept is that at low level DAVID generates old school error codes (david::ErrorCode) that are packed into different categories of exceptions:

classdavid_1_1_exception.png
Inheritance diagram of david::Exception

All DAVID exceptions are inherited from david::Exception. Therefore, you can simply catch all DAVID exceptions by

catch (david::Exception& e) {}

In many cases you expect the connection between client and server to work correctly. And you might be only interested in the error codes provided by function itself, ignoring all connection stuff like david::Error_ConnectionLost. Therefore, all error codes are grouped into two categories:

  1. david::ConnectionException: All error codes related to connection failures between the client and server. Most of the time these errors are critical and might only be solved be trying a reconnect (e.g. with different port) or a complete restart of client/server.
  2. david::FunctionException: All error codes related to typical errors found in standard C++ function calls. The connection between client and server worked correctly, but the function produced a failure, because e.g. the provided filename for an import function was invalid.

Assuming a bug free implementation of DAVID SDK and DAVID4 server software, the exception david::ProtocolException should never occur. This exception indicates a mismatch of what the client transmits to server and what the server expects from the client.

Here is an example for one of the possible error handling patterns that distinguishes between connection and function exceptions: XXX

Requirements

The DAVID SDK is developed and tested using Microsoft Visual Studio 2012. But it should compile under other modern C++ compilers as well.

Minimum requirements:

  • C++11 compiler (only subset of features required)
  • Windows XP or higher, if you want to use our C++ API (network code)
  • DAVID4 Server needs Windows 7 or newer, and a DAVID4 Enterprise License, otherwise some functions (getting binary data, exporting to files) will be limited

Recommended:

  • Visual Studio 2012 or higher (the free "Express for Windows Desktop" version, or a "Community Edition", should suffice)
  • Windows 7 or higher (64 bit)

Next Steps (Examples)

Best way to learn more about the DAVID SDK is to study some examples. Within this documentation you find a list of all examples here and some more information in the namespace examples. We also provide a sample project for Visual Studio that includes all examples. You can find it in your DAVID SDK directory under

  • "davidSDK_Examples\workspace vc11\Examples.sln" (for Visual Studio 2012) or
  • "davidSDK_Examples\workspace vc12\Examples.sln" (for Visual Studio 2013) or
  • "davidSDK_Examples\workspace vc14\Examples.sln" (for Visual Studio 2015).

Those examples use the Client/Server Mode. You will find an example project for the DLL Mode in davidSDK_ExamplesDLL.

To switch an existing Client/Server project to DLL mode, you need to

  • remove project "davidSDK_ClientServer" from your Visual Studio solution
  • add project "davidSDK_DLL" to your Visual Studio solution
  • #define DAVID_SDK_USE_D4LIB in your project (Preprocessor settings) - see in david.h what effect that has
  • use david.InitLibrary("") instead of david.Connect()

If you want to integrate remote functions on a specific platform that is not directly supported by our standard C++ API, have a look at our Low Level Interface.