Documentation
Royale 5 API Update

Here you can find an overview of the changes to our API and what you will need to change, to run your exciting code when updating to Royale 5.

Royale Output Structures

For version 4 and before the DepthData format looked like this :

struct DepthPoint
   {
       float x; 
       float y;
       float z;
       float noise;
       uint16_t grayValue;
       uint8_t depthConfidence;
   };

royale::Vector<royale::DepthPoint> points;

So, each point had a position in space, a gray value and so on. This was nice from the object oriented point of view, but it had drawbacks on the performance side.

New Output Structures

From version 5 onward the output structures will contain exactly the pointers to the memory that was also used by our internal processing library Spectre:

float *coordinates;   //!< coordinates array with x, y, z and  confidence for every pixel
bool hasDepth;        //!< to check presence of depth information
uint16_t *amplitudes; //!< amplitude value for each pixel
bool hasAmplitudes;   //!< to check presence of amplitude information

By using the same memory we can eliminate redundant copies. This layout is also beneficial for smaller platforms and it allows us to only calculate the data needed for a certain case. For the transition from Royale 4 to Royale 5 we offer helper functions (e.g. getLegacyPoints) which should make it easier to work with the new structure.

Transition from Royale 4 to Royale 5

Royale 5 offers helper functions that should simplify the adaption of existing code. If your code used the DepthData::points Vector you can now call getLegacyPoints() to retrieve this Vector from every DepthData object. We also added functions that should make it easier to access the data in the new structure, e.g. this code:

for (int curWidth = 0; curWidth < maxWidth; curWidth++)  { 
    for (int curHeight = 0; curHeight < maxHeight; curHeight++)  {
        auto dataPos = curHeight * maxWidth + curWidth; 
        uint16_t curAmpl = depthData->points[dataPos].grayValue;

can be replaced with this:

for (int curWidth = 0; curWidth < maxWidth; curWidth++) {
    for (int curHeight = 0; curHeight < maxHeight; curHeight++) {
        auto dataPos = curHeight * maxWidth + curWidth;
        float curAmpl = depthData->getGrayValue(dataPos);

Changes to Processing Parameters

For Royale 5 we changed the setting/retrieval of processing parameters to use strings instead of the ProcessingFlag enum. This will make the handling easier and more consistent.

Before

typedef Vector< Pair<ProcessingFlag, Variant> > ProcessingParameterVector;

Now

typedef Vector< Pair<String, Variant> > ProcessingParameterVector;

That means instead of:

cameraDevice->setProcessingParameters({{ProcessingFlag::UseRemoveFlyingPixel_Bool,
										 Variant(false)}}

You now should use:

cameraDevice->setProcessingParameters({{"useRemoveFlyingPixel", Variant(false)}}

Documentation Royale 5 API Update