Artec 3D Scanning SDK offers 3D enthusiasts and professionals a comprehensive tool set for capturing and processing 3D surfaces. It's the shortest way to assimilate Eva or Spider scanners into your solution.
The illustration above shows how the SDK works. The purpose of the software is to enable programmers to scan 3D objects, process the captured surfaces and obtain the final model with optionally applied textures. The SDK provides an API designed to work with Artec 3D scanners, and it enables multicapture using several devices at the same time. The API consist of *.lib, *.dll and *.h files that you can compile in your software.
Understanding the SDK
Although Artec 3D Scanning SDK contains an arsenal of powerful algorithms for processing models, it lacks out-of-the-box interactivity, manual tools and uncommon algorithms. Check out the limitations of the software by consulting the What the SDK Doesn't Do page.
The SDK includes several logical parts, as the figure below illustrates.
The Base SDK includes classes that work with input and output files, raw data, points, textures, and UV coordinates, and it defines operation statuses—essentially everything that relates to data collection and processing. In other words, it includes components that cannot be directly associated with the Scanning or Algorithm SDK. For more information, consult the Base SDK page.
The Capturing SDK lacks any complex scanning procedures, but it does enable capture and reconstruction. At the same time it has a variety of interfaces that control modes and scanner settings. Capturing procedures are helpful when you need raw frames as an output or when you intend to apply your own registration algorithm.
The Scanning SDK provides interfaces for complex Artec scanning procedures, such as employing several devices simultaneously (see How to Bundle Artec Scanners), and registration.
The Algorithm SDK offers data types and classes for complex data processing.
Getting Started
Installation
You can freely install the SDK on as many computers as you want. Just follow these steps:
- Access your personal page at my.artec3d.com.
- Install Artec Installation Center and launch it.
- Connect your Artec 3D scanner to the computer and wait until it appears in the Hardware section.
- Click the Activate button.
- Click the Install button in the row titled Artec 3D Scanning SDK.
- Once the installation is complete, start working with the API.
- Note
- Scanner drivers are installed automatically.
Getting Started With the SDK
You can compile the files using Microsoft Visual Studio. We support Visual Studio 2010 and Visual Studio 2013, including Visual Studio Express.
- Note
- We do not offer ready-to-use wrappers. If you wish to use a wrapper for
C#, for instance, consider writing your own.
One good way to start using the SDK is to try a code sample. For your convenience, source code files along with libraries are packed in the archive.
Using the SDK
How to Scan
The easiest way to scan is to follow the Artec scanning procedure. In a number of cases, however, you can use simple capture. The procedures are as follows:
| Using only Capturing API | Using Scanning API | |
|---|---|---|
| Get list of connected scanners | enumerateScanners() | enumerateScanners() |
| Create the scanner | createScanner() | createScanner() |
| Capture (without registration) | createFrameProcessor then capture() | N/A |
| Sort captured frames | getFrameNumber() | N/A |
| Reconstruct a 3D surface from a frame | reconstructMesh() reconstructAndTexturizeMesh() | N/A |
| Scan (instead of capture) | N/A | createScanningProcedure() |
| Release each object that has been started, unless TRef was used | artec::sdk::base::IRef::release() | artec::sdk::base::IRef::release() |
You can apply additional settings if necessary; see Tweaking Scan Settings. Also consult the Examples page for details regarding the actual code.
How to Process 3D Data
The Algorithm SDK provides data types and interfaces for complex 3D-data processing. The artec::sdk::algorithms::IAlgorithm interface inherits from artec::sdk::base::IJob, which represents a basic multithreaded work item. To run an IJob-based algorithm task, use either of the following calls:
- launchJob()—An asynchronous call that returns control immediately after starting so you can proceed with another task. To receive notification regarding completion of an
IJob, implement your own completed() method for a JobObserverBase descendent. - executeJob()—A synchronous call that doesn't allow you to start an other task until the present one finishes.
The artec::sdk::algorithms::IAlgorithm interface implements various data-intensive calculations. The example below shows you how to call algorithms. First, select the appropriate settings, then use createXxXxAlgorithm and call executeJob() or launchJob().
The General Pipeline page page lists algorithms in their exact order. For more details, consult scanning-and-process-sample.cpp.
How to Store Results to File
If, for example, you wish to save a model into an OBJ file, use saveObjCompositeToFile(). The other functions related to storing and loading are in artec::sdk::base::io. Another way to save objects is by using C++ functions, as scanning-and-process-sample.cpp shows.
Understanding Data and Structure
Meshes
The scanner captures two-dimensional images that are objects of the IFrame class. Once reconstructed—that is, converted into 3D surfaces—these objects become IFrameMesh objects. A mesh obtained using the Fusion algorithm is an implementation of the IСompositeMesh interface.
Transformations
Since all frames are stored in the scanner coordinate system, their actual relative position are determined by transformation matrices. As a set of reconstructed frames, Scan may also have its own transformation matrices.
Containers
For simplicity and clarity, we will imply as an interface a particular object-instance being operated via interface.
In terms of SDK, FrameMeshes make sense when they are stored in a sequence container and feature information on their relative positions. IScan is a minimum unit for storing reconstructed frame-meshes with supplemental information. The structure is as follows: each FrameMesh is assigned a transformation matrix and undisclosed attributes. Scan as a single whole has its own attributes, transformation matrix and data on the source of the surfaces (ScannerType).
IСompositeСontainer mirrors the IScan's structure except for ScannerType. Another distinction is that the source of the surfaces (CompositeMeshes) is the fusion algorithm output or various mesh upload.
IModel is an array that includes both IScan and ICompositeContainer, although the latter might be empty. Don't confuse IModel with the concept of model in Artec Studio. Indeed, IModel is roughly equivalent to marking state for scans and models in the Workspace panel.
Textures
More specifically, IFrameMesh is designed to work with frames that have only a (single) texture obtained from the scanner. The IСompositeMesh interface, on the other hand, offers various methods for multiple textures that are outputs of an algorithm. If your focus is only on geometry (e.g., you didn't capture or don't intend to map texture), you can use the parent class IMesh.
- Note
- By default, the scanner doesn't capture texture for each frame, although this option is configurable.
How to Get Coordinates
To obtain coordinates for each point of a mesh, for example, call the artec::sdk::base::IMesh::getPoints()const method. This method returns IArrayPoint3F, which can return the point array using the getPointer()const method.
Contacting Artec Support
If you encounter a problem with Artec 3D Scanning SDK, email us at support@artec-group.com. To help us in assisting you, first try one of the provided examples.
- Note
- If your issue relates to sample code, try the sample once more after making sure that the setOutputLevel() function accepts the artec::sdk::base::VerboseLevel_Trace parameter as an input.
