Zivid SDK Interoperability

This article explains how to use Zivid SDK and Zivid Motion together in the same application. These integration details are planned to be addressed in the future for a more seamless experience, but for now, this article provides guidance on how to use both SDKs together effectively.

For a full sample application combining Zivid Motion and the Zivid SDK, see the Obstacle from Zivid Point Cloud sample.


Units: millimeters vs meters

Note that:

  • Zivid SDK point cloud coordinates are in millimeters.

  • Zivid Motion geometry and obstacle coordinates are in meters.

Always convert coordinates from millimeters to meters before creating Motion obstacles from SDK point clouds.

const Zivid::Matrix4x4 millimetersToMetersTransform{ {
    { 0.001f,    0.f,    0.f, 0.f },
    {    0.f, 0.001f,    0.f, 0.f },
    {    0.f,    0.f, 0.001f, 0.f },
    {    0.f,    0.f,    0.f, 1.f },
} };
frame.pointCloud().transform(millimetersToMetersTransform);

millimeters_to_meters_transform = np.diag([0.001, 0.001, 0.001, 1])
frame.point_cloud().transform(millimeters_to_meters_transform)

C++ integration details

CMake differences

When building a Motion-only CMake application, use Motion as the package and link target. When building an application that uses both SDK and Motion, use the Zivid package with both components.

find_package(ZividMotion COMPONENTS Motion REQUIRED)
target_link_libraries(${PROJECT_NAME} PRIVATE Zivid::Motion)

find_package(
    Zivid
    COMPONENTS
        Core
        Motion
    REQUIRED
)
target_link_libraries(
    ${PROJECT_NAME}
    PRIVATE
        Zivid::Core
        Zivid::Motion
)

Application instantiation order

When using Zivid SDK and Zivid Motion in the same C++ process, create a Zivid::Application first and a Zivid::Motion::Application application second, to avoid an initialization error.

Use this order:

Zivid::Application zividApp;
Zivid::Motion::Application motionApp;

Data type conversion

Even when type names look similar, SDK and Motion types are different C++ types.

For example:

  • Zivid::PointXYZ is an SDK point type.

  • Zivid::Motion::PointXYZ is a Motion point type.

Convert explicitly when creating Motion obstacles from SDK point cloud data:

// Ensure that the point cloud is in meters, not millimeters, before copying the XYZ data.
// Also, make sure to use an unorganized point cloud, as Motion always expects unorganized point clouds.
const auto xyzData = unorganizedPointCloud.copyPointsXYZ();
std::vector<Zivid::Motion::PointXYZ> points;
points.reserve(xyzData.size());
for(const auto &p : xyzData)
{
    points.emplace_back(Zivid::Motion::PointXYZ{ p.x, p.y, p.z });
}
planner.setObstacles({ Zivid::Motion::Obstacle::fromPointCloud("point_cloud_obstacle", points) });

Python integration details

In Python, interoperability is simpler:

  • Zivid SDK and Zivid Motion both work naturally with NumPy-compatible data.

  • Aside from the millimeter-to-meter conversion, no special data conversion step is needed.

  • There is no instantiation-order restriction between zivid.Application() and zividmotion.Application().