Limiting Z-Depth Range through NxLib

[SebAndraos]

General Information

• Product: C-67-4-BL
• Serial Number: 260868
• Ensenso SDK Version: 4.3.991
• Operating System: Windows
• Data Attachments
  • Screenshots

Problem / Question

Hi,

I am using NxLib through C# (NuGetpackage version 4.3.1057) to capture some point cloud with a C-67. I am very close to having everything I want working directly through the NxLib library, settings values via the [ ] interfaces and calling commands. However, my clouds never seem to be cropped by their Z-depth. I can achieve that fine through NxView but not my own code and I suspect I’m just missing a toggle somewhere so I’m hoping for some clarification on this.

As far as I can read from the docs, I should be able to set the Z values of the Near and Far MeasurementVolumes to achieve this. That is done with:

// Depth Range
disparityMapNode[NxLib.itmMeasurementVolume][NxLib.itmNear][NxLib.itmLeftBottom][2].Set(1000);
disparityMapNode[NxLib.itmMeasurementVolume][NxLib.itmFar][NxLib.itmLeftBottom][2].Set(1390);

And those values appear to be correctly set in the Parameters when I review the JSON:

{
        "MeasurementVolume": {
            "Far": {
                "DisparityStep": 3.014694092202319542,
                "LeftBottom": [
                    151.411984891589554536,
                    157.246083012587803296,
                    1390.521882114909431039
                ],
                "LeftTop": [
                    151.411984891589554536,
                    -911.279691693013432996,
                    1390.521882114909431039
                ],
                "PixelSize": 0.890438145588001051,
                "RightBottom": [
                    730.196779523790269195,
                    157.246083012587803296,
                    1390.521882114909431039
                ],
                "RightTop": [
                    730.196779523790269195,
                    -911.279691693013432996,
                    1390.521882114909431039
                ]
            },
            "Near": {
                "DisparityStep": 1.423687579229886868,
                "LeftBottom": [
                    105.848491351957065376,
                    109.926969584371107658,
                    972.080535891070439902
                ],
                "LeftTop": [
                    105.848491351957065376,
                    -637.05380148371557425,
                    972.080535891070439902
                ],
                "PixelSize": 0.622483975890072205,
                "RightBottom": [
                    510.463075680504005049,
                    109.926969584371107658,
                    972.080535891070439902
                ],
                "RightTop": [
                    510.463075680504005049,
                    -637.05380148371557425,
                    972.080535891070439902
                ]
            }
        }
}

And for context this is how I am doing the capture and post processing:

// captures an image
new NxLibCommand(NxLib.cmdCapture).Execute(out var retCode);
if (!CheckPointCloudCalculationError("Capture failed", retCode, out var exception))
    throw exception;

// computes the stereo matching - this is the computationally intensive part of the process
new NxLibCommand(NxLib.cmdComputeDisparityMap).Execute(out retCode);
if (!CheckPointCloudCalculationError("Disparity matching failed", retCode, out exception))
    throw exception;

// converts the disparity map into XYZ data for each pixel
new NxLibCommand(NxLib.cmdComputePointMap).Execute(out retCode);
if (!CheckPointCloudCalculationError("Map to point conversion failed", retCode, out exception))
    throw exception;

// converts the image data into undistorted images
new NxLibCommand(NxLib.cmdRectifyImages).Execute(out retCode);
if (!CheckPointCloudCalculationError("Image rectification failed", retCode, out exception))
    throw exception;

I then read my points from the Camera[NxLib.itmImages][NxLib.itmPointMap] node but that appears to contain all of my points irrelevant of their Z-depth and whether they are in the MeasurementVolume or not. Am I missing something to activate that trimming?

For a bit of additional context, I am also Computing Texture, Rending Point Map and Computing Normals after this but the behaviour I am seeing is still present regardless of whether I have those enabled or not in our code.

Thanks

[daniel.saier]

You have to enable EnforceDisparityRange. This is what the “Limit Depth Range” Checkbox in NxView does. When it is disabled the PatchMatch matching methods (which don’t require a disparity range to work) don’t filter the depth.

Some further hints that might be useful:

• You can export the settings from NxView to a .ensparam file or save them on the device and load them in your application. See this guide in the manual.
• Instead of the simple depth clipping there is also a more flexible bounding box you can use, although there is currently no UI for setting it up yet.

[SebAndraos]

Amazing, thank you for the lightning fast reply @daniel.saier .

I assumed it would be a detail like that that I was missing. That works exactly as expected now.

As for the bonus tips:

• I am keen to allow users to configure the camera parameters through our software but using an .ensparam file for testing is a great idea.

• I saw the bounding box option but had misunderstood the documentation and couldn’t see a way to programmatically set the box centre, assuming that the Link had to be a pre-existing object. Having now seen that that is possible that does indeed seem like the better option and works really well. I am, however, having to inverse the Link Transformation unexpectedly to get the result I imagine. Would you be able to shed some light on that for me?
  Given that what I see in the NxView viewport has the Z-axis pointing out of the camera, I would expect that a positive Z value in the translation would move the box centre in that direction:

  
  
  However, I am finding that the only way to define a box in front of the camera is with Inverse: true or by negating the translations (and rotations but that’s less trivial by hand). I was testing with just translation to simplify but with Inverse set, all translations and rotations work exactly as I’d expect. Am I misunderstanding what the origin of that Transformation is? I can’t find any Links that have anything but default values that would be flipping the origin explicitly:
  
  
  This isn’t critical because, as I said, Inverse fixes it in one Boolean but I feel like I must be misunderstanding something.

Thanks again

[daniel.saier]

For the interpretation of transformations in the NxLib see this page. A “Link” always uses the object it is attached to as the reference coordinate system and allows you to specify the target system. A “Pose” is the inverse, which is also used in some places of the API.

Unfortunately most transformations in the NxLib are specified as Links for historic reasons, which is the opposite of what most users expect. Setting the Inverse flag ist the easiest way to use it.

[SebAndraos]

Perfect, thank you for the clarification. I’ll stick with Inverse.