Rerun Mat4x4 编码类型详解列主序存储、Arrow 数据表示与多语言构造实践【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读Mat4x4是 Rerun 数据模型中最底层的编码encodings类型之一负责承载 4×4 浮点矩阵——这是三维空间变换、相机投影、姿态描述等机器人多模态数据中反复出现的核心数据结构。本文以 docs/content/reference/types/encodings/mat4x4.md 为骨架结合仓库内 Rust/Python 的生成代码与类型定义源码完整讲解 Mat4x4 的存储约定列主序、Arrow 数据表示、Python 的rows/columns构造语义以及 Rust 侧的常用操作与生态转换帮助读者在使用 Rerun 记录、序列化与读取 4×4 矩阵时避免行列混淆并正确高效地落地。定位数据模型最底层的「编码」层在 Rerun 的数据模型层级中Mat4x4属于 encodings编码层。正如 docs/content/reference/types/encodings.md 所述Data types are the lowest layer of the data model hierarchy. They are re-usable types used by the components.数据类型是数据模型层级的最底层是被组件复用的可复用类型。也就是说Mat4x4不是最终面向用户记录的原语组件而是被更上层组件例如变换类组件、相机投影类组件复用的基础构造块与Vec3D、Quaternion、RotationAxisAngle等共同构成 Rerun 记录三维几何信息的底座。存储约定列主序column-major扁平化Mat4x4的本质定义非常简洁——它是一个包含 16 个f32的扁平数组。其类型定义位于 crates/build/re_type_definitions/rerun/encodings/mat4x4.def.rs#[rerun::rerun_type] #[arrow(transparent)] #[python(aliases npt.ArrayLike)] #[rust(derive(Copy, PartialEq, PartialOrd))] #[rust(tuple_struct)] #[rerun(state stable)] pub struct Mat4x4 { /// Flat list of matrix coefficients in column-major order. pub flat_columns: [f32; 16], }关键点是字段注释中的column-major order列主序。也就是说16 个系数在flat_columns中的排列方式为先填满第 0 列索引 0-3再填第 1 列索引 4-7依此类推。原文档给出了精确的映射表column 0 column 1 column 2 column 3 -------------------------------------------------------------------- row 0 | flat_columns[0] flat_columns[4] flat_columns[8] flat_columns[12] row 1 | flat_columns[1] flat_columns[5] flat_columns[9] flat_columns[13] row 2 | flat_columns[2] flat_columns[6] flat_columns[10] flat_columns[14] row 3 | flat_columns[3] flat_columns[7] flat_columns[11] flat_columns[15]换算成公式即位于第r行、第c列的系数对应flat_columns[c * 4 r]。这一点与许多图形学库如 OpenGL 传统约定一致但与 NumPy 默认的行主序row-major内存布局相反——这也是后续 Python 构造 API 需要做转换的根本原因。Arrow 数据表示FixedSizeList(16 x non-null Float32)Mat4x4在 Arrow 层面对应一个固定长度的列表原文档给出的类型为FixedSizeList(16 x non-null Float32)该表示由re_types_builder依据#[arrow(transparent)]与[f32; 16]字段自动生成可在 crates/store/re_sdk_types/src/encodings/mat4x4.rs 中看到 Rust 侧的ArrowDataType实现impl ::re_types_core::ArrowDataType for Mat4x4 { fn arrow_data_type() - arrow::datatypes::DataType { use arrow::datatypes::*; DataType::FixedSizeList( std::sync::Arc::new(Field::new(item, DataType::Float32, false)), 16, ) } }即每个元素是一个固定长度为 16、子元素为非空Float32的FixedSizeList。使用固定长度列表而非可变长度列表List的好处在于每个矩阵占用的字节数恒定16 × 4 64 字节反序列化时可以借助bytemuck::try_cast_slice直接把连续内存批量转换为[f32; 16]切片性能开销极低。反序列化端mat4x4.rs也做了双重校验先将 Arrow 数据强转为FixedSizeListArray再检查value_length() ! 16并返回datatype_mismatch错误从而保证读取到的数据一定符合 4×4 语义。Python 构造语义rows与columns两种约定虽然内存与 Arrow 表示是列主序但 Rerun 的 Python SDK 在设计构造 API 时遵循了 NumPy 的用户直觉默认按「行」输入内部自动转置为列主序存储。这一约定在类型定义文档 mat4x4.def.rs 中附带了可运行的断言示例。默认按行构造传入扁平列表时前 4 个元素被视为第 0 行import numpy as np import rerun as rr # 扁平列表按行解读1..4 为第 0 行5..8 为第 1 行…… m rr.encodings.Mat4x4([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15, 4, 8, 12, 16], dtypenp.float32), )可以看到输入按行读取1,2,3,4 是第一行但flat_columns中实际按列存储1,5,9,13 是第一列输入与输出互为转置关系。二维嵌套列表同样按行解读m rr.encodings.Mat4x4([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15, 4, 8, 12, 16], dtypenp.float32), )显式按列构造columns关键字如果你的数据本身就以列为单位组织例如直接来自列主序的图形库矩阵可以通过命名参数columns跳过转置逻辑实现直通存储# 扁平列表按列解读1..4 为第 0 列 m rr.encodings.Mat4x4(columns[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], dtypenp.float32), ) m rr.encodings.Mat4x4(columns[[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], dtypenp.float32), )实现细节上述行为的实现位于 Python 扩展类 rerun_py/rerun_sdk/rerun/encodings/mat4x4_ext.py若同时传入rows与columns抛出警告/异常Cant specify both columns and rows of matrix.按行构造时先np.asarray(rows, dtypenp.float32).reshape(4, 4)再arr.flatten(F)Fortran 序即列主序得到flat_columns按列构造时np.asarray(columns, ...).reshape(4, 4)后直接arr.flatten()C 序即行主序由于输入本身已按列组织扁平结果正好是列主序的flat_columns两者都不传时发出警告并以 4×4 单位阵np.identity(4)兜底。序列化入口native_to_pa_array_overridemat4x4_ext.py负责把单个或批量矩阵统一收集为扁平float32数组再通过pa.FixedSizeListArray.from_arrays(float_arrays, typedata_type)组装成上文所述的 Arrow 表示与 Rust 侧的FixedSizeList(16 x Float32)完全对齐。Rust 侧类型与常用操作Rust 中Mat4x4被生成为元组结构体pub struct Mat4x4(pub [f32; 16])见 crates/store/re_sdk_types/src/encodings/mat4x4.rs并派生Clone, Debug, Copy, PartialEq, PartialOrd以及re_byte_size::SizeBytes。其余常用能力由手写扩展文件 crates/store/re_sdk_types/src/encodings/mat4x4_ext.rs 提供单位矩阵常量pub const IDENTITY: Self Self([ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, ]);对应 mat4x4_ext.rs语义为乘性单位元、表示无变换。按列取值pub fn col(self, index: usize) - Vec4D对应 mat4x4_ext.rscol(0)返回[self.0[0..4]]col(1)返回[self.0[4..8]]依次类推index大于 3 时 panic。这与列主序存储直接呼应——每一列的 4 个元素在flat_columns中是连续存放的取列近乎零开销。下标访问与多维数组转换实现了std::ops::IndexIdx for Mat4x4Idx: SliceIndex[f32]可以直接m[0]、m[..4]等方式访问底层切片与[Vec4D; 4]4 个列向量双向互转From[Vec4D; 4] for Mat4x4与FromMat4x4 for [Vec4D; 4]与[[f32; 4]; 4]4×4 二维数组互转此时每一行视为一个Vec4D列向量。生态互转glam 与 mint在开启对应 feature 时Mat4x4还支持与 Rust 图形生态的常见矩阵类型互转glamFromMat4x4 for glam::Mat4按列from_cols构造与Fromglam::Mat4 for Mat4x4to_cols_array_2d见 mat4x4_ext.rsmintFromMat4x4 for mint::ColumnMatrix4f32与反向转换见 mat4x4_ext.rs。这些转换通过 crates/store/re_sdk_types/tests/types/mint_conversions.rs 中的mat4测试用例验证一个[[f32; 4]; 4]矩阵可以经Mat4x4 → mint::ColumnMatrix4或反向路径往返且保持一致保证了与既有数学库对接时行列语义不失真。使用注意事项行列混淆是最大的坑底层flat_columns永远是列主序Python 默认的rows构造会做一次隐式转置。若你的矩阵数据来自 NumPy 数组行主序直接传入即可若来自列主序库如某些 C 图形库导出请使用columns以避免意外转置。类型别名与广播Python 侧Mat4x4Like接受npt.ArrayLike别名#[python(aliases npt.ArrayLike)]即可传入 NumPy 数组同时Mat4x4Ext的构造函数会自动尝试把单个元素与批量序列区分开批量传入时按序列逐个构造。单位矩阵兜底Python 端既不传rows也不传columns时会告警并回退为单位阵避免静默产生未定义数据——实际业务中应显式传参。无空值约束Arrow 类型标注为non-null Float32Rust 反序列化使用err_on_nulls拒绝空值见 mat4x4.rs因此写入前应确保 16 个系数全部有效。小结Mat4x4是 Rerun encodings 层中承载 4×4 矩阵的稳定state stable类型存储与传输采用列主序扁平f32×16Arrow 表示为FixedSizeList(16 x non-null Float32)Python 侧默认按行构造并自动转置、亦支持columns直通按列输入Rust 侧则提供IDENTITY、按列访问以及与glam/mint的互转。理解这三层约定用户输入 → 扁平存储 → Arrow 表示即可在 Rerun 中安全、高效地记录与读取 4×4 矩阵数据。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rerun Mat4x4 编码类型详解：列主序存储、Arrow 数据表示与多语言构造实践
Rerun Mat4x4 编码类型详解列主序存储、Arrow 数据表示与多语言构造实践【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读Mat4x4是 Rerun 数据模型中最底层的编码encodings类型之一负责承载 4×4 浮点矩阵——这是三维空间变换、相机投影、姿态描述等机器人多模态数据中反复出现的核心数据结构。本文以 docs/content/reference/types/encodings/mat4x4.md 为骨架结合仓库内 Rust/Python 的生成代码与类型定义源码完整讲解 Mat4x4 的存储约定列主序、Arrow 数据表示、Python 的rows/columns构造语义以及 Rust 侧的常用操作与生态转换帮助读者在使用 Rerun 记录、序列化与读取 4×4 矩阵时避免行列混淆并正确高效地落地。定位数据模型最底层的「编码」层在 Rerun 的数据模型层级中Mat4x4属于 encodings编码层。正如 docs/content/reference/types/encodings.md 所述Data types are the lowest layer of the data model hierarchy. They are re-usable types used by the components.数据类型是数据模型层级的最底层是被组件复用的可复用类型。也就是说Mat4x4不是最终面向用户记录的原语组件而是被更上层组件例如变换类组件、相机投影类组件复用的基础构造块与Vec3D、Quaternion、RotationAxisAngle等共同构成 Rerun 记录三维几何信息的底座。存储约定列主序column-major扁平化Mat4x4的本质定义非常简洁——它是一个包含 16 个f32的扁平数组。其类型定义位于 crates/build/re_type_definitions/rerun/encodings/mat4x4.def.rs#[rerun::rerun_type] #[arrow(transparent)] #[python(aliases npt.ArrayLike)] #[rust(derive(Copy, PartialEq, PartialOrd))] #[rust(tuple_struct)] #[rerun(state stable)] pub struct Mat4x4 { /// Flat list of matrix coefficients in column-major order. pub flat_columns: [f32; 16], }关键点是字段注释中的column-major order列主序。也就是说16 个系数在flat_columns中的排列方式为先填满第 0 列索引 0-3再填第 1 列索引 4-7依此类推。原文档给出了精确的映射表column 0 column 1 column 2 column 3 -------------------------------------------------------------------- row 0 | flat_columns[0] flat_columns[4] flat_columns[8] flat_columns[12] row 1 | flat_columns[1] flat_columns[5] flat_columns[9] flat_columns[13] row 2 | flat_columns[2] flat_columns[6] flat_columns[10] flat_columns[14] row 3 | flat_columns[3] flat_columns[7] flat_columns[11] flat_columns[15]换算成公式即位于第r行、第c列的系数对应flat_columns[c * 4 r]。这一点与许多图形学库如 OpenGL 传统约定一致但与 NumPy 默认的行主序row-major内存布局相反——这也是后续 Python 构造 API 需要做转换的根本原因。Arrow 数据表示FixedSizeList(16 x non-null Float32)Mat4x4在 Arrow 层面对应一个固定长度的列表原文档给出的类型为FixedSizeList(16 x non-null Float32)该表示由re_types_builder依据#[arrow(transparent)]与[f32; 16]字段自动生成可在 crates/store/re_sdk_types/src/encodings/mat4x4.rs 中看到 Rust 侧的ArrowDataType实现impl ::re_types_core::ArrowDataType for Mat4x4 { fn arrow_data_type() - arrow::datatypes::DataType { use arrow::datatypes::*; DataType::FixedSizeList( std::sync::Arc::new(Field::new(item, DataType::Float32, false)), 16, ) } }即每个元素是一个固定长度为 16、子元素为非空Float32的FixedSizeList。使用固定长度列表而非可变长度列表List的好处在于每个矩阵占用的字节数恒定16 × 4 64 字节反序列化时可以借助bytemuck::try_cast_slice直接把连续内存批量转换为[f32; 16]切片性能开销极低。反序列化端mat4x4.rs也做了双重校验先将 Arrow 数据强转为FixedSizeListArray再检查value_length() ! 16并返回datatype_mismatch错误从而保证读取到的数据一定符合 4×4 语义。Python 构造语义rows与columns两种约定虽然内存与 Arrow 表示是列主序但 Rerun 的 Python SDK 在设计构造 API 时遵循了 NumPy 的用户直觉默认按「行」输入内部自动转置为列主序存储。这一约定在类型定义文档 mat4x4.def.rs 中附带了可运行的断言示例。默认按行构造传入扁平列表时前 4 个元素被视为第 0 行import numpy as np import rerun as rr # 扁平列表按行解读1..4 为第 0 行5..8 为第 1 行…… m rr.encodings.Mat4x4([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15, 4, 8, 12, 16], dtypenp.float32), )可以看到输入按行读取1,2,3,4 是第一行但flat_columns中实际按列存储1,5,9,13 是第一列输入与输出互为转置关系。二维嵌套列表同样按行解读m rr.encodings.Mat4x4([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 5, 9, 13, 2, 6, 10, 14, 3, 7, 11, 15, 4, 8, 12, 16], dtypenp.float32), )显式按列构造columns关键字如果你的数据本身就以列为单位组织例如直接来自列主序的图形库矩阵可以通过命名参数columns跳过转置逻辑实现直通存储# 扁平列表按列解读1..4 为第 0 列 m rr.encodings.Mat4x4(columns[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], dtypenp.float32), ) m rr.encodings.Mat4x4(columns[[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]) np.testing.assert_array_equal( m.flat_columns, np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], dtypenp.float32), )实现细节上述行为的实现位于 Python 扩展类 rerun_py/rerun_sdk/rerun/encodings/mat4x4_ext.py若同时传入rows与columns抛出警告/异常Cant specify both columns and rows of matrix.按行构造时先np.asarray(rows, dtypenp.float32).reshape(4, 4)再arr.flatten(F)Fortran 序即列主序得到flat_columns按列构造时np.asarray(columns, ...).reshape(4, 4)后直接arr.flatten()C 序即行主序由于输入本身已按列组织扁平结果正好是列主序的flat_columns两者都不传时发出警告并以 4×4 单位阵np.identity(4)兜底。序列化入口native_to_pa_array_overridemat4x4_ext.py负责把单个或批量矩阵统一收集为扁平float32数组再通过pa.FixedSizeListArray.from_arrays(float_arrays, typedata_type)组装成上文所述的 Arrow 表示与 Rust 侧的FixedSizeList(16 x Float32)完全对齐。Rust 侧类型与常用操作Rust 中Mat4x4被生成为元组结构体pub struct Mat4x4(pub [f32; 16])见 crates/store/re_sdk_types/src/encodings/mat4x4.rs并派生Clone, Debug, Copy, PartialEq, PartialOrd以及re_byte_size::SizeBytes。其余常用能力由手写扩展文件 crates/store/re_sdk_types/src/encodings/mat4x4_ext.rs 提供单位矩阵常量pub const IDENTITY: Self Self([ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, ]);对应 mat4x4_ext.rs语义为乘性单位元、表示无变换。按列取值pub fn col(self, index: usize) - Vec4D对应 mat4x4_ext.rscol(0)返回[self.0[0..4]]col(1)返回[self.0[4..8]]依次类推index大于 3 时 panic。这与列主序存储直接呼应——每一列的 4 个元素在flat_columns中是连续存放的取列近乎零开销。下标访问与多维数组转换实现了std::ops::IndexIdx for Mat4x4Idx: SliceIndex[f32]可以直接m[0]、m[..4]等方式访问底层切片与[Vec4D; 4]4 个列向量双向互转From[Vec4D; 4] for Mat4x4与FromMat4x4 for [Vec4D; 4]与[[f32; 4]; 4]4×4 二维数组互转此时每一行视为一个Vec4D列向量。生态互转glam 与 mint在开启对应 feature 时Mat4x4还支持与 Rust 图形生态的常见矩阵类型互转glamFromMat4x4 for glam::Mat4按列from_cols构造与Fromglam::Mat4 for Mat4x4to_cols_array_2d见 mat4x4_ext.rsmintFromMat4x4 for mint::ColumnMatrix4f32与反向转换见 mat4x4_ext.rs。这些转换通过 crates/store/re_sdk_types/tests/types/mint_conversions.rs 中的mat4测试用例验证一个[[f32; 4]; 4]矩阵可以经Mat4x4 → mint::ColumnMatrix4或反向路径往返且保持一致保证了与既有数学库对接时行列语义不失真。使用注意事项行列混淆是最大的坑底层flat_columns永远是列主序Python 默认的rows构造会做一次隐式转置。若你的矩阵数据来自 NumPy 数组行主序直接传入即可若来自列主序库如某些 C 图形库导出请使用columns以避免意外转置。类型别名与广播Python 侧Mat4x4Like接受npt.ArrayLike别名#[python(aliases npt.ArrayLike)]即可传入 NumPy 数组同时Mat4x4Ext的构造函数会自动尝试把单个元素与批量序列区分开批量传入时按序列逐个构造。单位矩阵兜底Python 端既不传rows也不传columns时会告警并回退为单位阵避免静默产生未定义数据——实际业务中应显式传参。无空值约束Arrow 类型标注为non-null Float32Rust 反序列化使用err_on_nulls拒绝空值见 mat4x4.rs因此写入前应确保 16 个系数全部有效。小结Mat4x4是 Rerun encodings 层中承载 4×4 矩阵的稳定state stable类型存储与传输采用列主序扁平f32×16Arrow 表示为FixedSizeList(16 x non-null Float32)Python 侧默认按行构造并自动转置、亦支持columns直通按列输入Rust 侧则提供IDENTITY、按列访问以及与glam/mint的互转。理解这三层约定用户输入 → 扁平存储 → Arrow 表示即可在 Rerun 中安全、高效地记录与读取 4×4 矩阵数据。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考