<
>
<
>
<
>
<
>

tutorials

Tutorials

Prerequisites

Unresolved directive in tutorials.adoc - include::_prerequisites.adoc[]

Create your first SolAR Project

Unresolved directive in tutorials.adoc - include::_createSolARProject_sanscode.adoc[]

Write your first SolAR "Hello World"

This tutorial will help you to write a simple program that will display an image in a window. The tutorial will take approximately 15mn to complete.

Prerequisites

Unresolved directive in _hello_world.adoc - include::_prerequisites.adoc[] - You have followed the first tutorial on how to create and build your own SolAR project.

Objectives

  • Declare and instantiate SolAR components.

  • Declare SolAR data structures.

  • Create your first SolAR pipeline based on a loop.

Hello world pipeline overview

The hello world pipeline is very simple. It consists in two OpenCV components, the first one will load an image, the second one will display it in a window.

1200
Figure 1. Simple Hello World pipipeline

Instructions

To start, please replace the code of your main.cpp by the following one:

main.cpp
// ADD HERE:: header files of the components you want to use

using namespace SolAR;
using namespace SolAR::MODULES::OPENCV;
namespace xpcf = org::bcom::xpcf;

void main(int argc,char** argv){

    // To redirect log to the console
    LOG_ADD_LOG_TO_CONSOLE();

    // ADD HERE: declarations and instantiation of components
    // see API ref on SolAR website
    // Example to declare and create a camera:
     SRef<SolARCameraOpencv> camera = xpcf::utils::make_shared<SolARCameraopencv>());


    // ADD HERE: declarations of data structures used to connect components
    // Example to declare a SolARImage:
     SRef<SolAR::datastructure::SolARImage> inputImage;


    // ADD HERE: Find a way to load an image

    // ADD HERE: Find a way to display your image in a window

}

The executable should take as the only parameter the url of the image you want to display. First, you will need to include the components header files, here the two header files for SolARImageLoaderOpencv and SolARImageViewerOpencv.

header files declaration
// ADD HERE:: header files of the components you want to use
#include "SolARImageLoaderOpencv.h"
#include "SolARImageViewerOpencv.h"

Then, you need to declare and instantiate your components. To do it, you can use the xpcf framework provided with SolAR. It offers a tool to easily instantiate your components (xpcf::utils::createcomponent). Why using xpcf here ? Because it offers more safety in the handling of your components. Thanks to the provided shared reference called SRef, do not worry about memory management anymore. You will see that you do not have to delete your components and data structures anymore.

Components declaration and instantiation
// ADD HERE: declarations and instantiation of components
// see API ref on SolAR website
// Example to declare and create a camera:
SRef<SolARCameraOpencv> camera = xpcf::utils::make_shared<SolARCameraopencv>());

SRef<SolARImageLoaderOpencv> myImageLoader = xpcf::utils::make_shared<SolARImageLoaderOpencv>();
SRef<SolARImageViewerOpencv> myImageViewer = xpcf::utils::make_shared<SolARImageViewerOpencv>();

Great, your components are now instantiated. Now, you need to declare the data structure required for exchanging information between the components of your pipeline. This data structure corresponds to the arc of the pipeline schema presented above. Here, you need to declare an Image data structure to transmit the image from the SolARImageLoader component to the SolARImageViewer.

Data structures declaration
// ADD HERE: declarations of data structures used to connect components
// Example to declare a Keypoint:
SRef<SolAR::datastructure::Keypoint> keypoint;
SRef<SolAR::datastructure::Image> myImage;

You are now ready to start your pipeline. You can connect your components by loading an image, recovering it, and passing it to the Image viewer. Do not forget to test if your image has been well loaded. if not, send an info log message by calling the macro LOG_INFO("info message")

Hello World pipeline
// ADD HERE: Find a way to load an image
if (myImageLoader->loadImage("HelloWorld.png", myImage) == SolAR::FrameworkReturnCode::_ERROR_LOAD_IMAGE)
{
  LOG_INFO("load image KO");
  return;
}
else
{
  LOG_INFO("load image OK");
}

// ADD HERE: Find a way to display your image in a window
myImageViewer->display("image display", myImage);

You can test your program with the following hello world image, just save it under HelloWorld.png.

HelloWorldImage
Figure 2. Hellow world image.

Do not forget to set the path to your image as parameter of your executable (In QT creator, click on Projects, Run, and set the path of your image in Command line arguments).

You can click on run. If you have an eagle eye, perhaps you have seen the hello world image that has appeared in a window and has immediately disappeared. Why ? The display function of your ImageViewer component displays the image only once. If you want to let it displayed until you press a key, you need to create your first loop that will include your pipeline. To do it, you can use the display method but with a third parameter that corresponds to the key to press to close the viewer window. For example, you can use the escape key (code 27). If this key is pressed, the display function will return FrameworkReturnCode::_STOP.

main.cpp Hello World Solution
// ADD HERE:: header files of the components you want to use
#include "SolARImageLoaderOpencv.h"
#include "SolARImageViewerOpencv.h"

using namespace SolAR;
using namespace SolAR::MODULES::OPENCV;
namespace xpcf = org::bcom::xpcf;

void main(int argc,char** argv){

    // To redirect log to the console
    LOG_ADD_LOG_TO_CONSOLE();

    // ADD HERE: declarations and instantiation of components
    // see API ref on SolAR website
    // Example to declare and create a camera:
    SRef<SolARCameraOpencv> camera = xpcf::utils::make_shared<SolARCameraopencv>());
    SRef<SolARImageLoaderOpencv> myImageLoader = xpcf::utils::make_shared<SolARImageLoaderOpencv>();
    SRef<SolARImageViewerOpencv> myImageViewer = xpcf::utils::make_shared<SolARImageViewerOpencv>();

    // ADD HERE: declarations of data structures used to connect components
    // Example to declare a SolARImage:
    SRef<SolAR::datastructure::SolARImage> inputImage;
    SRef<SolAR::datastructure::Image> myImage;

    // ADD HERE: Find a way to load an image
    if (myImageLoader->loadImage("HelloWorld.png", myImage) == SolAR::FrameworkReturnCode::_ERROR_LOAD_IMAGE)
    {
      LOG_INFO("load image KO");
      return;
    }
    else
    {
      LOG_INFO("load image OK");
    }

    // ADD HERE: Find a way to display your image in a window

    // The escape key to exit the sample
   char escape_key = 27;
   bool process = true;

    while (process)
    {
        if (myImageViewer->display("image display", myImage, &escape_key) == FrameworkReturnCode::_STOP)
        {
            process = false;
        }
    }
}

Congratulation, you have implement your first SolAR pipeline. It is quite simple, but now, you know all you need to develop your own pipeline: the components declaration and instantiation, the data structures declaration, and finally the pipeline implementation based on a loop.

Detect keypoints in an image

Unresolved directive in tutorials.adoc - include::_keypoints_detection_sanscode.adoc[]

Match an image with your video stream

Unresolved directive in tutorials.adoc - include::_matching_sanscode.adoc[]

Calibrate your camera

Coming Soon ! Please contact us if you want a camera calibration tutorial.

Estimate a camera pose with a natural image marker

Coming Soon ! Please contact us if you want tutorial with a natural image marker.

Estimate a camera pose with a fiducial marker

Coming Soon ! Please contact us if you want camera pose with a fiducial marker tutorial.