Rerun 图像编码之 ColorModel颜色分量模型与像素格式定义详解【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunColorModel是 Rerun 数据模型rerun.encodings.ColorModel中用于描述图像颜色分量构成的核心枚举类型它声明一幅图像里到底有哪些颜色通道并与ChannelDatatype每个通道的数据类型共同决定图像的像素格式。无论你是通过 Python、Rust 还是 C SDK 记录 RGB 相机帧、灰度深度图还是 OpenCV 产出的 BGR 数据都需要理解ColorModel的五个取值及其在ImageFormat中的组合规则。读完本文你将掌握ColorModel每个变体的语义、数值编码、Arrow 序列化方式、与PixelFormat/ChannelDatatype的优先级关系以及在 Rerun 中正确声明与转换图像格式的完整方法。一、ColorModel 是什么ColorModel的官方定义位于 color_model.md其作用是Specifies what color components are present in anarchetypes.Image.声明Image图元中存在的颜色分量。更关键的一句话是This combined withencodings.ChannelDatatypedetermines the pixel format of an image.它与ChannelDatatype共同决定图像的像素格式。也就是说ColorModel回答的是图像有哪几种颜色通道以及通道顺序而ChannelDatatype回答的是每个通道用什么数值类型存储U8、F16……。两者缺一不可仅有RGB无法确定一个像素占多少字节仅有U8也无法知道一个像素由几个字节组成。在 Rerun 的类型体系里ColorModel属于Encoding编码层类型被ImageFormat结构体引用见 image_format.md 的 Used by 一节而ImageFormat又是components.ImageFormat的载体随archetypes.Image一起被记录、传输与渲染。二、五个变体语义与枚举值ColorModel共定义了 5 个变体每个变体对应一个固定的u8数值。下表汇总了官方文档与 color_model.rs 源码中的完整定义变体数值含义通道数是否含 AlphaL1灰度亮度/强度/明度Grayscale luminance intensity/brightness/value有时称为Y1否RGB2红、绿、蓝Red, Green, Blue3否RGBA3红、绿、蓝、透明度Red, Green, Blue, Alpha4是BGR4蓝、绿、红Blue, Green, Red3否BGRA5蓝、绿、红、透明度Blue, Green, Red, Alpha4是几点值得注意L是默认变体。在 Rust 实现中L带有#[default]属性color_model.rs 第 35 行这意味着未显式指定颜色模型时默认按单通道灰度处理。L即 Y。文档明确指出灰度分量sometimes calledY这与 YUV 色彩空间中的亮度分量 Y 概念一致也呼应了PixelFormat中Y8_FullRange、Y8_LimitedRange等单色格式的命名详见 pixel_format.md。BGR/BGRA 的存在是为了兼容 OpenCV 等以 BGR 为内存顺序的视觉库避免在记录前手动翻转通道顺序。通道数与 Alpha 的派生逻辑Rust 侧通过扩展方法提供了两个派生属性见 color_model_ext.rsnum_channels()L返回 1RGB | BGR返回 3RGBA | BGRA返回 4has_alpha()RGBA | BGRA返回true其余返回false。Python 侧在 color_model_ext.py 中提供了等价的num_channels()方法逻辑与 Rust 完全一致未知值会抛出ValueError。这两个派生属性在图像缓冲区的尺寸校验、as_pil_image转换等场景中被大量使用见下文。三、Arrow 序列化单个 UInt8 即可表达ColorModel的 Arrow 数据类型被定义为UInt8color_model.rs 第 57-63 行的arrow_data_type()实现UInt8由于枚举在 Rust 中以#[repr(u8)]布局序列化时直接把*datum as u8写入PrimitiveArrayUInt8Type反序列化时则通过Enum::try_from_integer(val)将整数映射回变体try_from_integer的实现是variants().get((value as usize).wrapping_sub(1))即用值 - 1索引变体数组值 1 对应第 0 个变体L依次类推。无法映射的整数会报missing_union_arm错误color_model.rs 第 110-127 行。这意味着5 个颜色模型在数据层只占用每像素 1 字节作为元数据时更是微乎其微并且可以安全地与ChannelDatatype、PixelFormat一样用UInt8承载在 Arrow 记录中。Rust 端的Display实现color_model.rs 第 133-143 行会输出L、RGB、RGBA、BGR、BGRA这些字符串方便日志与调试。四、与 ChannelDatatype 组合像素格式的两要素ChannelDatatype见 channel_datatype.md定义每个颜色通道内部的数据编码共 11 个变体类别变体与数值无符号整型U86、U168、U3210、U6412有符号整型I87、I169、I3211、I6413浮点型F1633半精度、F3234、F6435双精度官方文档给出的组合示例是RGBU8红绿蓝各 8 位即常见的 24 位真彩同理LU8→ 8 位灰度LU16→ 16 位深度/灰度图RGBF32→ 浮点 RGB例如 HDR 或科学可视化数据RGBAU8→ 32 位带透明度图像。两者合起来恰好回答像素格式的所有问题ColorModel决定通道结构与顺序ChannelDatatype决定每通道位宽与数值语义是否带符号、是否浮点。五、ImageFormat承载三者并定义优先级ColorModel并非孤立使用它最终会被装入ImageFormat结构体Rust 实现见 image_format.rs该结构体由五个字段组成字段类型说明widthu32非空图像宽度像素heightu32非空图像高度像素pixel_formatPixelFormat可空主要用于色度下采样格式或每通道位数不一致的格式color_modelColorModel可空L、RGB、RGBA……需配合channel_datatype才能完整描述像素格式channel_datatypeChannelDatatype可空每个通道的数据类型U8、F16……优先级规则在 image_format.md 中有明确说明也体现在pixel_format字段的 doc 注释中若指定了pixel_format则它优先于color_model与channel_datatype后两者被忽略。也就是说存在两条描述像素格式的路径常规路径color_modelchannel_datatype适用于绝大多数未压缩、无色度下采样的图像特殊路径pixel_format适用于 YUV 4:2:0 / 4:2:2 / 4:4:4 等色度下采样格式以及每通道位数不一致的格式如NV12、YUY2、I420系列共 10 个变体详见 pixel_format.md。ImageFormat的 Arrow 表示为五字段Structwidth、height为UInt32其余三个编码字段均为UInt8与文档中的描述完全对应。六、源码级验证SDK 如何自动推断与校验 ColorModel理解ColorModel的最佳方式之一是看 SDK 在记录图像时如何推断、校验并消费它。Python 端的自动推断在 image_ext.py 的Image构造逻辑中当未显式传入color_model时SDK 依据通道数自动推断if color_model is None: if channels 1: color_model ColorModel.L elif channels 3: color_model ColorModel.RGB elif channels 4: color_model ColorModel.RGBA else: _send_warning_or_raise(fExpected 1, 3, or 4 channels; got {channels})如果显式指定了color_model则用channel_count_from_color_model校验实际通道数与模型要求的通道数L→1、RGB/BGR→3、RGBA/BGRA→4是否匹配不匹配时给出告警或报错。随后ChannelDatatype由 NumPy dtypefrom_np_dtype自动推导最终组装成ImageFormat(width, height, channel_datatype, color_model)并写入buffer。单元测试佐证test_image.py 中直接构造了color_model: rr.encodings.ColorModel.RGB的测试用例验证了 RGB 模型在记录-序列化-反序列化全链路上的正确性。BGR/BGRA 的转换与压缩限制由于as_pil_image假设 PIL 使用 L 或 RGB(A) 通道顺序因此在 image_ext.py 的as_pil_image()中对 BGR/BGRA 数据做了通道重排if image_format.color_model ColorModel.BGR: image image[:, :, ::-1] # BGR - RGB elif image_format.color_model ColorModel.BGRA: image image[:, :, [2, 1, 0, 3]] # BGRA - RGBA同时compress()JPEG 压缩只接受L、RGB、BGR三种模型且通道数据类型必须为U8遇到RGBA/BGRA会抛出 Cannot JPEG compress an image of type … 的错误——这再次体现了ColorModel在 SDK 各个功能点中的实际约束作用。七、各语言 API 中的使用方式ColorModel在三种官方 SDK 中都有对应类型原文档的 API 链接指向 C、Python、Rust 三个入口Pythonrerun.encodings.ColorModelColorModel.RGB、ColorModel.L等类型定义与扩展逻辑位于 encodings/color_model.py 与 encodings/color_model_ext.pyRustrerun::encodings::ColorModel生成代码位于 color_model.rs扩展方法在 color_model_ext.rsCrerun::encodings::ColorModel可通过rerun::Image记录图像。一个典型的使用场景是从 OpenCV 读入的帧是 BGR 内存布局若不转换而直接记录渲染端会得到错误的颜色通道。正确的做法是要么在记录时显式声明ColorModel.BGR配合ChannelDatatype.U8让 Rerun 知道通道顺序并正确渲染要么先转换成 RGB 再以ColorModel.RGB记录。Python 端as_pil_image的通道重排逻辑image_ext.py 第 302-313 行证明渲染管线确实会按ColorModel声明的顺序解释字节。八、总结与延伸阅读ColorModel虽只是一个小枚举却是 Rerun 图像数据模型的基石之一它定义了颜色通道的结构与顺序L/RGB/RGBA/BGR/BGRA与ChannelDatatype一起构成像素格式的完整描述并在ImageFormat中被PixelFormat所覆盖。理解它就能正确记录灰度图、RGB 相机帧、OpenCV BGR 数据与带透明度图像也能读懂 SDK 在通道数校验、PIL 转换和 JPEG 压缩中的种种行为。想进一步深入可继续阅读仓库内的这些资料数据类型参考channel_datatype.md、pixel_format.md、image_format.md图元定义archetypes.Image与其扩展实现 image_ext.pyRust 类型定义color_model.rs、color_model_ext.rsPython 测试用例test_image.py。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rerun 图像编码之 ColorModel：颜色分量模型与像素格式定义详解
Rerun 图像编码之 ColorModel颜色分量模型与像素格式定义详解【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunColorModel是 Rerun 数据模型rerun.encodings.ColorModel中用于描述图像颜色分量构成的核心枚举类型它声明一幅图像里到底有哪些颜色通道并与ChannelDatatype每个通道的数据类型共同决定图像的像素格式。无论你是通过 Python、Rust 还是 C SDK 记录 RGB 相机帧、灰度深度图还是 OpenCV 产出的 BGR 数据都需要理解ColorModel的五个取值及其在ImageFormat中的组合规则。读完本文你将掌握ColorModel每个变体的语义、数值编码、Arrow 序列化方式、与PixelFormat/ChannelDatatype的优先级关系以及在 Rerun 中正确声明与转换图像格式的完整方法。一、ColorModel 是什么ColorModel的官方定义位于 color_model.md其作用是Specifies what color components are present in anarchetypes.Image.声明Image图元中存在的颜色分量。更关键的一句话是This combined withencodings.ChannelDatatypedetermines the pixel format of an image.它与ChannelDatatype共同决定图像的像素格式。也就是说ColorModel回答的是图像有哪几种颜色通道以及通道顺序而ChannelDatatype回答的是每个通道用什么数值类型存储U8、F16……。两者缺一不可仅有RGB无法确定一个像素占多少字节仅有U8也无法知道一个像素由几个字节组成。在 Rerun 的类型体系里ColorModel属于Encoding编码层类型被ImageFormat结构体引用见 image_format.md 的 Used by 一节而ImageFormat又是components.ImageFormat的载体随archetypes.Image一起被记录、传输与渲染。二、五个变体语义与枚举值ColorModel共定义了 5 个变体每个变体对应一个固定的u8数值。下表汇总了官方文档与 color_model.rs 源码中的完整定义变体数值含义通道数是否含 AlphaL1灰度亮度/强度/明度Grayscale luminance intensity/brightness/value有时称为Y1否RGB2红、绿、蓝Red, Green, Blue3否RGBA3红、绿、蓝、透明度Red, Green, Blue, Alpha4是BGR4蓝、绿、红Blue, Green, Red3否BGRA5蓝、绿、红、透明度Blue, Green, Red, Alpha4是几点值得注意L是默认变体。在 Rust 实现中L带有#[default]属性color_model.rs 第 35 行这意味着未显式指定颜色模型时默认按单通道灰度处理。L即 Y。文档明确指出灰度分量sometimes calledY这与 YUV 色彩空间中的亮度分量 Y 概念一致也呼应了PixelFormat中Y8_FullRange、Y8_LimitedRange等单色格式的命名详见 pixel_format.md。BGR/BGRA 的存在是为了兼容 OpenCV 等以 BGR 为内存顺序的视觉库避免在记录前手动翻转通道顺序。通道数与 Alpha 的派生逻辑Rust 侧通过扩展方法提供了两个派生属性见 color_model_ext.rsnum_channels()L返回 1RGB | BGR返回 3RGBA | BGRA返回 4has_alpha()RGBA | BGRA返回true其余返回false。Python 侧在 color_model_ext.py 中提供了等价的num_channels()方法逻辑与 Rust 完全一致未知值会抛出ValueError。这两个派生属性在图像缓冲区的尺寸校验、as_pil_image转换等场景中被大量使用见下文。三、Arrow 序列化单个 UInt8 即可表达ColorModel的 Arrow 数据类型被定义为UInt8color_model.rs 第 57-63 行的arrow_data_type()实现UInt8由于枚举在 Rust 中以#[repr(u8)]布局序列化时直接把*datum as u8写入PrimitiveArrayUInt8Type反序列化时则通过Enum::try_from_integer(val)将整数映射回变体try_from_integer的实现是variants().get((value as usize).wrapping_sub(1))即用值 - 1索引变体数组值 1 对应第 0 个变体L依次类推。无法映射的整数会报missing_union_arm错误color_model.rs 第 110-127 行。这意味着5 个颜色模型在数据层只占用每像素 1 字节作为元数据时更是微乎其微并且可以安全地与ChannelDatatype、PixelFormat一样用UInt8承载在 Arrow 记录中。Rust 端的Display实现color_model.rs 第 133-143 行会输出L、RGB、RGBA、BGR、BGRA这些字符串方便日志与调试。四、与 ChannelDatatype 组合像素格式的两要素ChannelDatatype见 channel_datatype.md定义每个颜色通道内部的数据编码共 11 个变体类别变体与数值无符号整型U86、U168、U3210、U6412有符号整型I87、I169、I3211、I6413浮点型F1633半精度、F3234、F6435双精度官方文档给出的组合示例是RGBU8红绿蓝各 8 位即常见的 24 位真彩同理LU8→ 8 位灰度LU16→ 16 位深度/灰度图RGBF32→ 浮点 RGB例如 HDR 或科学可视化数据RGBAU8→ 32 位带透明度图像。两者合起来恰好回答像素格式的所有问题ColorModel决定通道结构与顺序ChannelDatatype决定每通道位宽与数值语义是否带符号、是否浮点。五、ImageFormat承载三者并定义优先级ColorModel并非孤立使用它最终会被装入ImageFormat结构体Rust 实现见 image_format.rs该结构体由五个字段组成字段类型说明widthu32非空图像宽度像素heightu32非空图像高度像素pixel_formatPixelFormat可空主要用于色度下采样格式或每通道位数不一致的格式color_modelColorModel可空L、RGB、RGBA……需配合channel_datatype才能完整描述像素格式channel_datatypeChannelDatatype可空每个通道的数据类型U8、F16……优先级规则在 image_format.md 中有明确说明也体现在pixel_format字段的 doc 注释中若指定了pixel_format则它优先于color_model与channel_datatype后两者被忽略。也就是说存在两条描述像素格式的路径常规路径color_modelchannel_datatype适用于绝大多数未压缩、无色度下采样的图像特殊路径pixel_format适用于 YUV 4:2:0 / 4:2:2 / 4:4:4 等色度下采样格式以及每通道位数不一致的格式如NV12、YUY2、I420系列共 10 个变体详见 pixel_format.md。ImageFormat的 Arrow 表示为五字段Structwidth、height为UInt32其余三个编码字段均为UInt8与文档中的描述完全对应。六、源码级验证SDK 如何自动推断与校验 ColorModel理解ColorModel的最佳方式之一是看 SDK 在记录图像时如何推断、校验并消费它。Python 端的自动推断在 image_ext.py 的Image构造逻辑中当未显式传入color_model时SDK 依据通道数自动推断if color_model is None: if channels 1: color_model ColorModel.L elif channels 3: color_model ColorModel.RGB elif channels 4: color_model ColorModel.RGBA else: _send_warning_or_raise(fExpected 1, 3, or 4 channels; got {channels})如果显式指定了color_model则用channel_count_from_color_model校验实际通道数与模型要求的通道数L→1、RGB/BGR→3、RGBA/BGRA→4是否匹配不匹配时给出告警或报错。随后ChannelDatatype由 NumPy dtypefrom_np_dtype自动推导最终组装成ImageFormat(width, height, channel_datatype, color_model)并写入buffer。单元测试佐证test_image.py 中直接构造了color_model: rr.encodings.ColorModel.RGB的测试用例验证了 RGB 模型在记录-序列化-反序列化全链路上的正确性。BGR/BGRA 的转换与压缩限制由于as_pil_image假设 PIL 使用 L 或 RGB(A) 通道顺序因此在 image_ext.py 的as_pil_image()中对 BGR/BGRA 数据做了通道重排if image_format.color_model ColorModel.BGR: image image[:, :, ::-1] # BGR - RGB elif image_format.color_model ColorModel.BGRA: image image[:, :, [2, 1, 0, 3]] # BGRA - RGBA同时compress()JPEG 压缩只接受L、RGB、BGR三种模型且通道数据类型必须为U8遇到RGBA/BGRA会抛出 Cannot JPEG compress an image of type … 的错误——这再次体现了ColorModel在 SDK 各个功能点中的实际约束作用。七、各语言 API 中的使用方式ColorModel在三种官方 SDK 中都有对应类型原文档的 API 链接指向 C、Python、Rust 三个入口Pythonrerun.encodings.ColorModelColorModel.RGB、ColorModel.L等类型定义与扩展逻辑位于 encodings/color_model.py 与 encodings/color_model_ext.pyRustrerun::encodings::ColorModel生成代码位于 color_model.rs扩展方法在 color_model_ext.rsCrerun::encodings::ColorModel可通过rerun::Image记录图像。一个典型的使用场景是从 OpenCV 读入的帧是 BGR 内存布局若不转换而直接记录渲染端会得到错误的颜色通道。正确的做法是要么在记录时显式声明ColorModel.BGR配合ChannelDatatype.U8让 Rerun 知道通道顺序并正确渲染要么先转换成 RGB 再以ColorModel.RGB记录。Python 端as_pil_image的通道重排逻辑image_ext.py 第 302-313 行证明渲染管线确实会按ColorModel声明的顺序解释字节。八、总结与延伸阅读ColorModel虽只是一个小枚举却是 Rerun 图像数据模型的基石之一它定义了颜色通道的结构与顺序L/RGB/RGBA/BGR/BGRA与ChannelDatatype一起构成像素格式的完整描述并在ImageFormat中被PixelFormat所覆盖。理解它就能正确记录灰度图、RGB 相机帧、OpenCV BGR 数据与带透明度图像也能读懂 SDK 在通道数校验、PIL 转换和 JPEG 压缩中的种种行为。想进一步深入可继续阅读仓库内的这些资料数据类型参考channel_datatype.md、pixel_format.md、image_format.md图元定义archetypes.Image与其扩展实现 image_ext.pyRust 类型定义color_model.rs、color_model_ext.rsPython 测试用例test_image.py。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
