艾萨克C API
Isaac C API允许您使用Isaac SDK功能，而无需将Isaac SDK完全集成到软件堆栈中。它还使您能够使用C ++以外的语言构建Isaac应用程序。
C API支持使用“JSON & buffers”格式向Isaac发送消息和从Isaac发送消息。以这种格式，大多数高级消息数据存储在JSON对象中，而大型数据块（例如图像和张量）存储在字节缓冲区(byte buffers)中。
示例
Isaac SDK包含两个示例应用程序，这些应用程序说明了如何使用C API：
//apps/tutorials/c_api/viewer.c//apps/tutorials/c_api/depth.c
这些示例使用虚拟图像并通过C API发布/接收消息。运行时 viewer.c，您可以在Sight中查看图像。
使用以下命令来运行示例：
bazel run //apps/tutorials/c_api:c_api_viewer
bazel run //apps/tutorials/c_api:c_api_depth
启动和停止应用程序
每个使用C API的Isaac应用程序都需要一个JSON应用文件 ; 例如，以上示例具有相应的viewer.app.json和depth.app.json文件。使用JSON应用程序文件的应用程序图来定义您希望使用C API与之通信的节点。
要启动Isaac应用程序，请按以下方式加载JSON文件：
isaac_handle_t app;
isaac_create_application("", "path/to/config.app.json", 0, 0, 0, 0, &app);
isaac_start_application(app);
要关闭该应用程序，请使用以下命令：
isaac_stop_application(app);
isaac_destroy_application(&app);
发布消息给以撒
以撒内部使用Cap'n Proto消息；但是，由于此消息格式不受普遍支持，因此C API将消息有效负载公开为JSON。如果接收消息的节点需要Cap'n Proto消息，则需要将消息转换为Cap'n Proto格式。
请按照以下步骤将消息发布到Isaac：
- 创建新消息，如下所示：
isaac_uuid_t uuid;
isaac_create_message(app, &uuid);
isaac_write_message_json(app, &uuid, &json);
- 设置消息的原始ID，并启用JSON到原始转换，如下所示：
isaac_set_message_proto_id(app, &uuid, proto_id);
isaac_set_message_auto_convert(app, &uuid, isaac_message_type_proto);
- 使用该
isaac_publish_message()呼叫将消息发布到Isaac应用程序节点。该消息将作为Cap'n Proto消息转发到该节点。
isaac_publish_message(app, "node_name", "component_name", "key", &uuid);
有关//apps/tutorials/c_api/viewer.c消息发布的示例，请参见。
接收以撒的消息
要从JSON应用文件中定义的任何节点接收最新消息，请使用以下调用：
isaac_receive_latest_new_message(app, "node_name", "component_name", "key", &uuid);
的isaac_receive_latest_new_message()呼叫传回“成功”的代码（isaac_error_success）或“无消息可用的”代码（isaac_error_no_message_available）。
获取消息的内容，如下所示：
isaac_const_json_t json = isaac_create_null_const_json();
isaac_get_message_json(app, &uuid, &json);
如果消息源使用Cap'n Proto发布消息，则消息将自动转换为JSON。
处理完消息后，立即使用该isaac_release_message()调用，该调用使Isaac可以回收用于该消息的任何资源：
isaac_release_message(app, &uuid);
如果要保留任何消息数据，请在释放消息之前将其复制。
请参阅//apps/tutorials/c_api/depth.c以获取接收消息的示例。
建立C API
使用以下命令来构建C API并将其部署到本地计算机上的文件夹中：
./engine/build/deploy.sh -p //engine/alice/c_api:isaac_engine_c_api-pkg -d x86_64 -h localhost --deploy_path ~
链接代码时，必须提供指向C API和“ sight”模块的共享库的路径，位于以下位置：
<deploy_path>/engine/alice/c_api/libisaac_c_api.so<deploy_path>/packages/sight/libsight_module.so
以下是使用GCC进行编译的命令行示例：
gcc c_api_example.c \
-L./engine/alice/c_api -lisaac_c_api \
-L./packages/sight -lsight_module \
-o c_api_example
export LD_LIBRARY_PATH=./engine/alice/c_api:./packages/sight:$LD_LIBRARY_PATH
./c_api_example
区域设置
Isaac应用程序的语言环境已自动设置为en_US.UTF-8防止在将JSON消息与原始消息之间进行转换时防止十进制转换错误。因此，为与Isaac节点通信而生成的JSON文件必须与en_US.UTF-8 语言环境兼容。
缓冲区布局
带有缓冲区的消息原型必须存储包含数据的缓冲区的索引。例如，ColorCameraProto中的“ dataBufferIndex”是包含图像数据的缓冲区的索引。
图像缓冲区
下图显示了720p RGB图像的缓冲区。每个（行，列）位置都包含有关像素的信息。Isaac图像缓冲区按行优先。
图像缓冲区示例
张量缓冲器
在一维张量中，元素按顺序堆叠：
图像缓冲区示例
二维张量类似于上述图像缓冲区：每个RGB值都可以表示为元组元素。如果图像是灰度的，则每个元素将改为一个数字。2D张量缓冲区上的第一个元素索引为（0,0），第二个元素索引为（0,1），依此类推。
同样，三维张量具有以下顺序：
哪里max_i是维度“ i”的最大索引。
3D张量可以表示RGB图像，每个（行，列，通道）索引指向0到255之间的值。
消息示例
执行以下命令以在/tmp文件夹中生成示例JSON文件：
bazel run apps/samples/proto_to_json
这些JSON文件（在下面进行详细介绍）与Isaac中使用的常见原型相对应。
ColorCameraProto
- 文件名：
color_camera_proto.json - 原型说明：ColorCameraProto
- 原型ID：12905539496848989000
有关二维缓冲区布局的说明，请参见上面的“ 图像缓冲区”部分。
RangeScanProto
- 文件名：
range_scan_proto.json - 原型说明：RangeScanProto
- 原型ID：11901202900662173387
有关缓冲区布局的说明，请参见上面的“ 张量缓冲区”部分。在这种情况下，有一个缓冲区用于范围，另一个缓冲区用于强度。在示例JSON中，缓冲区大小为16x8，因为垂直光束角度（theta）列表包含16个成员，而水平光束切片有8个（与phi 角度相关）。
StateProto（messages::DifferentialBaseDynamics）
- 文件名：
differential_base_state_proto.json - 原型说明：StateProto
- 原型ID：13177870757040999364
有关缓冲区布局的说明，请参见上面的“ 张量缓冲区”部分。在这种情况下，缓冲区是一个1x1x4张量，其中包含以下值：
- 线速度
- 角速度
- 线性加速度
- 角加速度
StateProto（messages::DifferentialBaseControl）
- 文件名：
differential_base_control_proto.json - 原型说明：StateProto
- 原型ID：13177870757040999364
有关缓冲区布局的说明，请参见上面的“ 张量缓冲区”部分。在这种情况下，缓冲区是一个1x1x2张量，其中包含以下值：
- 线速度
- 角速度
网友评论