Rerun 0.18 版本迁移指南图像编码重构、Transform3D 大改与 SDK 破坏性变更详解【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本篇技术指南基于 Rerun 仓库中的迁移文档 migration-0-18.md系统讲解从 Rerun 0.17 升级到 0.18 时必须处理的全部破坏性变更Breaking Changes。读完后你将掌握图像类 ArchetypeImage、DepthImage、SegmentationImage、EncodedImage底层从张量编码切换为「字节 Blob ImageFormat元数据」后的正确用法、Transform3D从 Arrow Union 重构为细粒度组件组合的完整 API 迁移方式以及Mesh3D、Boxes3D、InstancePoses3D等 3D 原语的关键变化并能在 Python、Rust、C 三种 SDK 中完成等价改写。1. 0.18 变更总览0.18 是一次以「类型系统现代化」为主线的版本升级核心变更集中在四大块图像类 Archetype 的编码方式重构Image、DepthImage、SegmentationImage不再编码为张量tensor改为字节 Blob ImageFormat元数据分辨率统一改为[width, height]顺序Transform3D全面重构移除嵌套的 Arrow Union 表示拆分为可并存的细粒度组件Mesh3D材质字段改名mesh_material: Material更名为albedo_factor: AlbedoFactorOutOfTreeTransform3D移除由功能更强的InstancePoses3D取代Boxes3D的字段类型同步调整。这些变更的共同动因是旧版「一切皆张量」的表示方式限制了 chroma 下采样图像NV12/YUY2等特殊像素格式的表达能力且Transform3D的多层 Union 嵌套使 SDK 类型转换频繁失败。0.18 用「显式编码元数据」和「细粒度组件」解决了这两个问题。2. 图像编码重构从张量到 Blob ImageFormat2.1 新的底层表示在 0.18 中DepthImage与SegmentationImage以及Image的原始像素数据被编码为一段字节blob of bytes其含义由ImageFormat组件决定。ImageFormat由分辨率和像素类型组成且分辨率统一按[width, height]顺序书写——这是与 0.17 最大的差异点C 用户尤其需要注意。从源码结构看ImageFormat的完整定义位于 encodings/image_format.rs它是一个结构体包含以下字段pub struct ImageFormat { pub width: u32, // 宽度像素 pub height: u32, // 高度像素 pub pixel_format: OptionPixelFormat, // 特殊格式如 NV12指定后优先于下面两个字段 pub color_model: OptionColorModel, // L, RGB, RGBA, … pub channel_datatype: OptionChannelDatatype, // 每通道数据类型U8, F16, … }值得注意的是pixel_format字段的注释明确写道一旦指定它优先于takes precedence overcolor_model和channel_datatype后两者将被忽略。这正是文档中「特殊格式如NV12由PixelFormat枚举指定并优先于ImageFormat中的数据类型和颜色模型」这一描述的底层依据。2.2 DepthImage 与 SegmentationImagePython 与 Rust 的 API 基本保持不变但 C 的构造函数签名发生了变化第一个参数从「分辨率 数据」改为「rerun::Collection或裸指针 分辨率」。当前 C SDK 中的构造实现位于 depth_image.hpp签名形如DepthImage(CollectionTElement pixels, WidthHeight resolution)与文档描述一致。迁移前0.17rec.log(segmentation, rerun::SegmentationImage({HEIGHT, WIDTH}, data)); rec.log(depth, rerun::DepthImage({HEIGHT, WIDTH}, data).with_meter(10000.0));迁移后0.18rec.log(segmentation, rerun::SegmentationImage(data.data(), {WIDTH, HEIGHT})); rec.log(depth, rerun::DepthImage(pixels.data(), {WIDTH, HEIGHT}).with_meter(10000.0));两处要点参数顺序调换数据在前、分辨率在后分辨率从{HEIGHT, WIDTH}纠正为{WIDTH, HEIGHT}。with_meter等链式方法保持不变参见 depth_image.hpp 中with_meter的定义。2.3 Image ArchetypeImage的变化与上述两个 Archetype 同源但 API 层面调整更多。PythonImage()构造函数的data参数被移除。第一个默认参数改为image接受numpy.ArrayLike并会从中自动提取相关元数据分辨率、格式也可以改用bytes参数构造但此时必须显式提供分辨率和像素格式。C参数顺序变化且必须使用纠正后的分辨率顺序// 之前 rec.log(image, rerun::Image({HEIGHT, WIDTH, 3}, data)); // 之后 rec.log(image, rerun::Image(data, {WIDTH, HEIGHT}, datatypes::ColorModel::RGB));仓库中的当前实现位于 image.hpp构造函数会校验字节长度与W * H * bytes_per_pixel是否一致不一致时以InvalidTensorDimension错误码报错这为「Blob 编码」提供了运行期保护。此外还提供了便捷的静态工厂方法from_rgb24image.hpprec.log(image, rerun::Image::from_rgb24(data, {WIDTH, HEIGHT}));from_rgb24封装了 RGB U8 的常见组合是从旧代码迁移时最不容易写错分辨率顺序的方式。2.4 新增 EncodedImage Archetype0.18 引入了专门用于记录图像文件PNG、JPEG 等压缩格式的新 ArchetypeEncodedImage。此前的压缩图数据被塞在Image体系里Rust 侧甚至存在TensorBuffer::JPEG这样的变体现在语义被清晰分离原始像素数据含 NV12/YUY2 等 chroma 下采样格式→ 新的ImageArchetype压缩图像文件→ 新的EncodedImageArchetype。Pythonrr.ImageEncoded已废弃。图像文件改用EncodedImage记录NV12/YUY2 这类 chroma 下采样图像则改用新ImageArchetype 的bytespixel_format方式# 之前 rr.log(NV12, rr.ImageEncoded(contentsnv12_bytes, formatrr.ImageFormat.NV12((height, width)))) # 之后 rr.log(NV12, rr.Image(bytesnv12_bytes, widthwidth, heightheight, pixel_formatrr.PixelFormat.NV12))Rust侧同步清理了旧 API移除TensorBuffer::JPEG移除TensorData::from_jpeg_bytes废弃Image::from_file_path与from_file_contents。以上所有场景统一改用EncodedImage。3. Mesh3Dmesh_material 更名为 albedo_factorMesh3D中的字段mesh_material类型Material被更名为albedo_factor类型为AlbedoFactor内部包装一个datatypes.Rgba32。构造Mesh3D时的各语言迁移方式为C 与 Rust.with_mesh_material(Material::from_albedo_factor(color))改为with_albedo_factor(color)Pythonmesh_materialrr.Material(albedo_factorcolor)改为albedo_factorcolor。这是一次纯命名层面的变更旧的Material概念被收窄为仅表达反照率因子albedo factor字段名与实际语义对齐。4. Transform3D 全面重构从嵌套 Union 到细粒度组件这是 0.18 中影响面最大的变更涉及数据模型、序列化行为和三语言 API 三个层面。4.1 设计动因与新的组件集合在 0.17 及之前Transform3D的数据表示是一个 Arrow UnionRust 中为enum根据变换的书写方式选择其中一个变体且某些变体内部还嵌套了更深层的 Union——例如TranslationRotationScale3D变体内部的 rotation 和 scale 各自又是多态的。这种「套娃」结构使得反序列化、类型推断和 SDK 自动类型转换都很脆弱。0.18 将其替换为一组可以并存side-by-side的独立组件共同组成Transform3DArchetype组件说明Translation3D平移TransformMat3x33x3 矩阵Scale3D缩放见 4.2 关于统一为 3 个浮点数的说明RotationAxisAngle轴角旋转复用同名 datatypeRotationQuat四元数旋转复用QuaterniondatatypeTransformRelation变换关系取代旧的from_parent布尔值被移除的类型包括TranslationRotationScale3D与TranslationAndMat3x3两个 datatype 及其对应组件它们的表达能力被上述新组件完整覆盖。from_parent在所有 SDK 语言中仍然可用但已被标记为废弃应改用TransformRelation。4.2 应用顺序与「全组件写入」语义两条行为规则对理解迁移后的语义至关重要应用顺序所有组件按文档列表中相反的顺序应用到最终变换上。即若同时设置了 translation、rotation、scale则对象先被缩放、再被旋转、最后被平移从父空间视角看——这与 0.17 及之前的行为一致保证既有场景数据语义不漂移。全组件写入发送一个Transform3DArchetype 时所有组件都会被写入即使你没有显式设置。这意味着先记录一个只含Translation3D的Transform3D之后再记录一个只含RotationQuat的Transform3D最终实体只有旋转——后一次写入会清除前一次的平移。这条规则直接决定了 Rust 侧工厂方法被命名为clear的原因见 4.4。此外还有两项数据表示层面的收敛缩放不再区分 uniform 与 3D无论是否均匀缩放数据一律表示为 3 个浮点数均匀缩放即三个值相同SDK 提供辅助函数构造均匀缩放角度统一为弧度RotationAxisAngle中的角度始终以弧度存储SDK 提供度数转换函数。4.3 Python 迁移Transform3DArchetype 不再有transform参数直接使用细粒度参数# 之前 rr.log(myentity, rr.Transform3D(rr.TranslationRotationScale3D(translationVec3D([1, 2, 3]), from_parentTrue))) # 之后 rr.log(myentity, rr.Transform3D(translationVec3D([1, 2, 3]), relationrr.TransformRelation.ChildFromParent))from_parentTrue的语义被relationrr.TransformRelation.ChildFromParent显式化——TransformRelation用枚举取代布尔可读性显著更好。4.4 Rust 迁移rerun::archetypes::Transform3D不再有new方法需改用工厂方法如from_translation_rotation_scale、from_mat3x3// 之前 rec.log(myentity, rerun::archetypes::Transform3D::new(translation))?; // 之后 rec.log(myentity, rerun::archetypes::Transform3D::from_translation(translation))?;另一个常见场景是对外部变换结构实现From转换。由于components::Transform3D组件本身被移除转换目标应直接改为 Archetype// 之前 impl FromGltfTransform for rerun::components::Transform3D { fn from(transform: GltfTransform) - Self { rerun::components::Transform3D::from_translation_rotation_scale( transform.t, rerun::datatypes::Quaternion::from_xyzw(transform.r), transform.s, ) } } // 之后 impl FromGltfTransform for rerun::Transform3D { fn from(transform: GltfTransform) - Self { rerun::Transform3D::from_translation_rotation_scale( transform.t, rerun::Quaternion::from_xyzw(transform.r), transform.s, ) } }与 C 一样各维度可以用with_方法自由链式组合rerun::Transform3D::clear().with_mat3x3(matrix).with_translation(translation)需要强调方法调用的先后顺序不影响变换实际应用的顺序——应用顺序由第 4.2 节的固定规则决定而不是链式书写顺序。Transform3D::clear这个命名正是为了提示前述「全组件写入」语义每发送一次 Archetype所有组件含未设置项以空值都会被重新写入。因此Transform3D::from_rotation(…)之后紧接Transform3D::from_translation(…)最终只保留平移旋转会被后一次调用清除。4.5 C 迁移rerun::Transform3D的大部分旧构造函数仍然存在但它们现在期望具体的组件类型这经常导致隐式类型转换失败。官方建议改用显式工厂方法// 之前 rec.log(myentity, rerun::Transform3D({1.0f, 2.0f, 3.0f})); // 之后 rec.log(myentity, rerun::Transform3D::from_translation({1.0f, 2.0f, 3.0f}));当前 C SDK 中的实现印证了这些工厂方法的存在包括from_translation_rotation_scale、from_mat3x3等参见 transform3d.hpp。各维度同样支持with_链式调用rerun::Transform3D().with_mat3x3(matrix).with_translation(translation)方法调用顺序同样不影响变换应用顺序。另外两点 C 专属注意rerun::Transform3D::IDENTITY被移除改用默认构造rerun::Transform3D()得到一个空 Archetype再按需填充例如rerun::Transform3D().with_mat3x3(rerun::datatypes::Mat3x3::IDENTITY)Scale3D不再是枚举 datatype而是携带 3 维向量的组件// 之前 auto scale_uniform rerun::Scale3D::Uniform(2.0); auto scale_y rerun::Scale3D::ThreeD([1.0, 2.0, 1.0]); // 之后 auto scale_uniform rerun::Scale3D::uniform(2.0); auto scale_y rerun::Scale3D::from([1.0, 2.0, 1.0]);5. OutOfTreeTransform3D 移除改用 InstancePoses3DOutOfTreeTransform3D在 0.18 中被移除由InstancePoses3D取代。后者的角色被扩展行为上更接近Transform3DArchetype被所有 3D 空间原语支持同时可用于 3D 网格的实例化instancing也是 box 和 ellipsoid/sphere 位姿的表示方式。对Asset3D的影响是三语言一致的Asset3D不再携带transform字段需要在同一实体上额外发送InstancePoses3D或Transform3D。Python# 之前 rr.log( world/asset, rr.Asset3D( pathpath, transformrr.OutOfTreeTransform3DBatch(rr.TranslationRotationScale3D(translationcenter, scalescale)), ), ) # 之后 rr.log(world/asset, rr.Asset3D(pathpath), rr.InstancePoses3D(translationcenter, scalescale))C// 之前 rec.log(world/asset, rerun::Asset3D::from_file(path).value_or_throw() .with_transform(rerun::OutOfTreeTransform3D(translation)) ); // 之后 rec.log(world/asset, rerun::Asset3D::from_file(path).value_or_throw(), rerun::InstancePoses3D().with_translations(translation) );Rust// 之前 rec.log(world/asset, rerun::Asset3D::from_file(path)? .with_transform(rerun::OutOfTreeTransform3D::from(rerun::TranslationRotationScale3D(translation))) )?; // 之后 rec.log(world/asset, rerun::Asset3D::from_file(path)?)?; rec.log(world/asset, rerun::InstancePoses3D::default().with_translations([translation]))?;6. Boxes3D 字段类型调整Boxes3D的变更与InstancePoses3D的引入直接相关centers类型变更由Position3D组件改为PoseTranslation3D。行为上的主要区别是它与InstancePoses3DArchetype 的语义重叠可以视为向新体系靠拢的过渡rotation字段被移除由rotation_axis_anglesPoseRotationAxisAngle组件和quaternionsPoseRotationQuat组件取代。相应的 API 调整C/Rust 中with_rotations改为with_quaternions或with_rotation_axis_anglesPython 中rotation改为quaternions或rotation_axis_angles。这一变化使 box 的旋转表示与Transform3D/InstancePoses3D体系轴角 四元数两种细粒度组件保持一致消除了「单一 rotation 字段到底是轴角还是矩阵」的歧义。7. 迁移检查清单升级 0.17 → 0.18 时建议按以下顺序逐点核对代码图像全局搜索{HEIGHT, WIDTH}形式的分辨率字面量改为{WIDTH, HEIGHT}C 中Image/DepthImage/SegmentationImage的构造调用调整为「数据在前」RGB24 图像优先改用Image::from_rgb24NV12/YUY2 改用Image(bytes…, pixel_format…)Python或PixelFormat构造CPNG/JPEG 文件记录全部切换到EncodedImage删除rr.ImageEncoded、TensorBuffer::JPEG、TensorData::from_jpeg_bytes、Image::from_file_path的使用Mesh3Dmesh_material/with_mesh_material全部替换为albedo_factor/with_albedo_factorTransform3D删除对TranslationRotationScale3D、TranslationAndMat3Rust、Transform3D::new、Transform3D::IDENTITY、from_parentC 中Scale3D::Uniform/Scale3D::ThreeD的引用改用工厂方法与with_链式调用特别注意「发送即全量写入」的清除语义动画循环中每次 log 的变换必须是完整状态而非增量3D 资源位姿OutOfTreeTransform3D/OutOfTreeTransform3DBatch及Asset3D的transform字段全部改为在同一实体上额外 logInstancePoses3DBoxes3Drotation/with_rotations替换为quaternions或rotation_axis_angles两个新字段。所有代码示例均出自仓库内的 迁移文档API 签名已与当前仓库源码交叉核对C 侧的 image.hpp、depth_image.hpp、transform3d.hpp 与 Rust 类型定义 encodings/image_format.rs 均与文档描述一致可作为迁移时确认目标签名的权威参照。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
