Dlib Integration🔗

The Dlib integration API provides a dlibImage function that wraps the VisionAppster image type (va_image*) to a Dlib-compatible template class. It makes it possible to call Dlib functions from your custom tool implementations without much boilerplate code.

Please see the tool C API for general instructions on how to set you your environment and build tool plugins. Since Dlib is implemented in C++, it is important to understand compiler requirements.

The VisionAppster SDK comes with the source code of the built-in Dlib plugin. To get started, have a look at sdk/examples/dlib under your installation. Modify the supplied Makefile to fit your setup. If you installed everything to default locations, building your first Dlib plugin on Linux can be as simple as this:

cd ~/VisionAppster/sdk/examples/dlib
make install

Windows (MinGW-w64), assuming you copied the SDK to your desktop folder:

cd %USERPROFILE%\Desktop\sdk\examples\dlib
mingw32-make
:: This may require admin rights.
mingw32-make install

Windows (MinGW-w64 + MSYS2), assuming you copied the SDK to your desktop folder:

cd /c/Users/$USERNAME/Desktop/sdk/examples/dlib
make
# This may require admin rights.
make install

If you use Dlib to implement your own tools, you are strongly encouraged to use the version that comes with the platform SDK. While it would be technically possible to use multiple different versions of shared libraries in a single process, it is not currently supported. If you absolutely need a different version, you may link the required parts of Dlib statically to your tool plugin.

Example🔗

The following example shows a complete implementation of a plugin and a tool that wraps the dlib::min_barrier_distance function. This is how the built-in Minimum Barrier Distance tool is actually implemented.

The SDK that comes with the VisionAppster platform contains this and other Dlib functions as examples. Please see the sdk/examples/dlib directory in your installation.

#include <va_tool.h>
#include <va_all_types.h>

#include <DlibImage.h>

#include <dlib/image_transforms.h>

VA_IMPLEMENT_PLUGIN("com.example.dlibtools", 1.0.0)

VA_REGISTER_TOOLS((IDENTIFIER(MinimumBarrierDistance),
                   NAME("Minimum Barrier Distance"),
                   PROCESS(MinBarrierDistance_process),
                   REQUIRED_INPUT(va_image, image),
                   OPTIONAL_INPUT(int32_t, iterations, 5),
                   OPTIONAL_INPUT(va_bool, horizontalScan, va_false),
                   OUTPUT(va_image, distance)))

using VisionAppster::dlibImage;

// The generic pattern for wrapping Dlib functions is to provide a
// functor template that can be applied to all supported image types.
template <class T>
struct DlibMinBarrierDistance
{
  int operator()(const va_image* imgIn,
                 va_image* imgOut,
                 int32_t iterations,
                 bool leftRightScan) const
  {
    dlib::min_barrier_distance(
      dlibImage<T>(imgIn), // Make va_image compatible with Dlib
      dlibImage<unsigned char>(imgOut).ref(), // Modifiable reference
      iterations,
      leftRightScan);
    return VA_SUCCESS;
  }
};

// This is the entry point function from calls from the VisionAppster
// platform. The first argument is the tool instance, which are not
// using here. The second one holds function arguments.
int MinimumBarrierDistance_process(void*, void* arguments)
{
  auto args = reinterpret_cast<MinimumBarrierDistance_args*>(arguments);
  // Initialize output image
  args->out.distance = va_image_alloc_typed_copy(args->in.image,
                                                 va_gray8_image_type);
  // The dlibCall function calls the functor template with the correct
  // template type.
  return dlibCall<DlibMinBarrierDistance>(
    args->in.image->type,
    args->in.image,
    args->out.distance,
    args->in.iterations,
    args->in.horizontalScan);
}