Rerun TimeInt 类型全解析用单一 64 位整数统一表达纳秒时间与序列号【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 官方类型参考文档 docs/content/reference/types/encodings/time_int.md 为核心系统讲解TimeInt编码类型的定义、Arrow 映射、边界语义、多语言 API以及它在AbsoluteTimeRange、TimeRangeBoundary、Timestamp等下游类型中的实际用途。读完本文你将理解 Rerun 内部为何用一个整数同时表示纳秒时间戳与序列号并能在 Rust / Python / C 三种 SDK 中正确构造与使用它。核心定义纳秒时间与序列号的统一编码根据官方类型参考TimeInt被定义为A 64-bit number describing either nanoseconds OR sequence numbers.即一个 64 位整数既可以描述纳秒nanoseconds也可以描述序列号sequence numbers。至于这个整数到底代表纳秒还是序列号必须结合它所挂载的时间轴Timeline的类型TimeType才能确定——单纯的TimeInt本身并不携带语义。这一设计贯穿 Rerun 的整个时间体系在timestamp 时间轴如log_time上TimeInt表示自 Unix 纪元1970-01-01 00:00:00 UTC以来的纳秒数在duration 时间轴上它表示纳秒计的时长在sequence 序列时间轴如log_tick、帧号上它表示单调递增的序号。Arrow 数据类型直接映射为 Int64文档中明确给出了TimeInt对应的 Arrow 数据类型Int64即TimeInt在 Arrow 层就是一个int64原生整数不做任何封装。这一点在三个 SDK 的实现中都有印证Rust SDK 侧crates/store/re_types_core/src/encodings/time_int.rs 中TimeInt(pub i64)其ArrowDataType::arrow_data_type()返回DataType::Int64Python 侧rerun_py/rerun_sdk/rerun/encodings/time_int.py 中TimeIntBatch._ARROW_DATATYPE pa.int64()C 侧rerun_cpp/src/rerun/encodings/time_int.hpp 中struct TimeInt { int64_t value; }位于rerun::encodings命名空间。由于直接映射为Int64序列化路径非常轻量Rust 侧ToArrow将TimeInt逐元素解包为i64组成PrimitiveArrayInt64TypeFromArrow则从Int64Array逐个还原见 time_int.rs。语义边界STATIC / MIN / MAX 特殊值虽然从外部看TimeInt就是i64但在 Rerun 的内部存储层TimeInt被实现为OptionNonMinI64见 crates/store/re_log_types/src/index/time_int.rs这使得它能够表达一个特殊的静态数据static状态TimeInt::STATIC内部为None用于表示静态数据不随时间变化的数据。文档强调SDK 用户不能显式地在某个时间戳上记录这种值——只有通过静态 API 才能产生静态数据任何时间上下文temporal context中构造该值都是非法的TimeInt::MIN不是i64::MIN因为i64::MIN已被保留作为静态数据的标记MIN实际为NonMinI64::MIN即i64::MIN 1见 crates/store/re_types_core/src/encodings/time_int_ext.rsTimeInt::MAX最大时间值即i64::MAXTimeInt::ZERO/TimeInt::ONE常用的小常数。对应地as_i64()对STATIC返回i64::MINas_f64()对STATIC返回f64::MIN见 time_int.rs。这也带来一个重要的边界行为TimeInt::new_temporal(time)在传入i64::MIN时会收敛为TimeInt::MIN且永远不可能返回STATIC测试用例saturated_temporal验证了i64::MIN、i64::MIN 1均饱和到MINi64::MAX保持为MAX见 time_int.rs。与 TimeType 的配对它到底是时间还是序号TimeInt必须与TimeType一起理解。TimeType是一个三值枚举见 crates/store/re_log_types/src/index/time_type.rs变体含义Arrow 数据类型Sequence序列号如影片帧号Int64DurationNs纳秒计时的时长Duration(Nanosecond)TimestampNs自 Unix 纪元以来的纳秒Timestamp(Nanosecond, None)有趣的是TimeType::datatype()在 Arrow 层把三种类型分别编码为Int64、Duration、Timestamp三种不同数据类型time_type.rs而TimeInt本身总是Int64——也就是说这是不是时间的语义信息存放在时间轴/时间类型上而非整数本身。make_arrow_array与from_arrow_array负责在这些数据类型与裸的ScalarBufferi64之间来回转换。多语言构造 APIPython 的关键字式构造PythonPython 侧TimeInt的构造函数要求seq、seconds、nanos三者恰好提供其一见 rerun_py/rerun_sdk/rerun/encodings/time_int_ext.py# 序列号 rr.TimeInt(seq42) # 秒按时间轴类型解释为时长或纪元后秒数内部转为 int(seconds * 1e9) rr.TimeInt(seconds0.5) # 纳秒按时间轴类型解释为时长或纪元后纳秒数 rr.TimeInt(nanos500_000_000)若传入多个关键字或一个都不传会抛出ValueError(Exactly one of seq, seconds, or nanos must be provided.)。seconds参数内部执行int(seconds * 1e9)的换算nanos则原样保留。RustRust 侧TimeInt提供了一组语义化的构造方法见 crates/store/re_log_types/src/index/time_int.rsTimeInt::from_sequence(seq) // 序列时间轴 TimeInt::from_nanos(nanos) // 时间时间轴纳秒 TimeInt::from_millis(millis) // 时间时间轴毫秒内部 saturating_mul 1_000_000 TimeInt::from_secs(seconds_f64) // 时间时间轴秒内部 (seconds * 1e9).round() TimeInt::new_temporal(i64) // 通用构造永不返回 STATIC此外还实现了TryFromi64拒绝i64::MIN、FromNonMinI64、Add/Sub饱和运算static 参与运算结果仍为 static、Neg、midpoint、closest_multiple_of、saturating_add/saturating_sub、inc/dec等运算time_int.rs。Duration与Timestamp也可与TimeInt相互转换如FromTimeInt for Duration调用Duration::from_nanos。CC 侧最直接TimeInt就是带一个int64_t value的 POD 结构体可用int64_t隐式构造或赋值rerun_cpp/src/rerun/encodings/time_int.hpprerun::encodings::TimeInt t1{42}; // 序列号 rerun::encodings::TimeInt t2; // 默认构造 t2 1640995203000000000; // 纳秒时间轴Timeline中的角色log_time 与 log_tickTimeInt是Timeline上承载的时间值的载体。Rerun SDK 会为每次日志调用自动维护两条内置时间轴见 crates/store/re_log_types/src/index/timeline.rslog_time类型为TimeType::TimestampNs记录数据被记录时的墙钟时间log_tick类型为TimeType::Sequence每次调用RecordingStream的日志方法时单调递增的 tick 序号。两条时间轴的取值正是以TimeInt形式存储的前者是纪元纳秒后者是序列号这也直接呼应了文档开头nanoseconds OR sequence numbers的定义。被谁使用TimeRange 体系与 Timestamp 组件文档末尾列出了TimeInt的三个下游使用者它们的关联文档与结构如下类型关联文档与 TimeInt 的关系AbsoluteTimeRangeabsolute_time_range.md由两个非空TimeInt字段min/max组成描述一个时间范围max为闭区间Arrow 层为Struct(min: non-null Int64, max: non-null Int64)TimeRangeBoundarytime_range_boundary.md时间范围的左/右边界CursorRelative 1相对时间游标的TimeInt偏移、Absolute 2绝对TimeInt值、Infinite 3无限延伸Timestamptimestamp.md录制开始时刻应为相对 Unix 纪元的时间其 Rerun 编码即为TimeIntArrow 数据类型为Int64被McapStatistics、RecordingInfo等 archetype 使用TimeRangeBoundary进一步被 time_range.md 中的TimeRangestart/end两个边界引用构成可见时间范围的完整表达链TimeInt→TimeRangeBoundary→TimeRange→VisibleTimeRange。实战示例在 DataframeView 中按时间范围过滤TimeInt最直观的落地场景是 Dataframe View 的filter_by_range。仓库示例 rerun_py/rerun_sdk/rerun/blueprint/views/dataframe_view.py 中这样使用rrb.DataframeView( origin/trig, queryrrb.archetypes.DataframeQuery( timelinet, filter_by_range(rr.TimeInt(seconds0), rr.TimeInt(seconds20)), # ... ), )这里rr.TimeInt(seconds0)与rr.TimeInt(seconds20)分别表示时间轴t上的起始与结束时间底层被编码为纪元纳秒0与20 * 1e9再通过AbsoluteTimeRange/TimeRangeBoundary的 Arrow 结构送入查询管线。小结TimeInt是 Rerun 时间体系的原子单位一个 64 位整数语义由所在时间轴的TimeType决定Arrow 层恒为Int64跨 Rust / Python / C 三端保持一致内部以OptionNonMinI64实现保留STATIC标记静态数据并因此牺牲了i64::MIN作为合法时间值它是AbsoluteTimeRange、TimeRangeBoundary、Timestamp的组成基础贯穿查询过滤、蓝图时间范围与录制元数据等场景。在阅读 类型参考索引 时可以顺着Used by的链接继续深入AbsoluteTimeRange、TimeRangeBoundary与Timestamp从而完整掌握 Rerun 的时间与范围编码体系。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rerun TimeInt 类型全解析：用单一 64 位整数统一表达纳秒时间与序列号
Rerun TimeInt 类型全解析用单一 64 位整数统一表达纳秒时间与序列号【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 官方类型参考文档 docs/content/reference/types/encodings/time_int.md 为核心系统讲解TimeInt编码类型的定义、Arrow 映射、边界语义、多语言 API以及它在AbsoluteTimeRange、TimeRangeBoundary、Timestamp等下游类型中的实际用途。读完本文你将理解 Rerun 内部为何用一个整数同时表示纳秒时间戳与序列号并能在 Rust / Python / C 三种 SDK 中正确构造与使用它。核心定义纳秒时间与序列号的统一编码根据官方类型参考TimeInt被定义为A 64-bit number describing either nanoseconds OR sequence numbers.即一个 64 位整数既可以描述纳秒nanoseconds也可以描述序列号sequence numbers。至于这个整数到底代表纳秒还是序列号必须结合它所挂载的时间轴Timeline的类型TimeType才能确定——单纯的TimeInt本身并不携带语义。这一设计贯穿 Rerun 的整个时间体系在timestamp 时间轴如log_time上TimeInt表示自 Unix 纪元1970-01-01 00:00:00 UTC以来的纳秒数在duration 时间轴上它表示纳秒计的时长在sequence 序列时间轴如log_tick、帧号上它表示单调递增的序号。Arrow 数据类型直接映射为 Int64文档中明确给出了TimeInt对应的 Arrow 数据类型Int64即TimeInt在 Arrow 层就是一个int64原生整数不做任何封装。这一点在三个 SDK 的实现中都有印证Rust SDK 侧crates/store/re_types_core/src/encodings/time_int.rs 中TimeInt(pub i64)其ArrowDataType::arrow_data_type()返回DataType::Int64Python 侧rerun_py/rerun_sdk/rerun/encodings/time_int.py 中TimeIntBatch._ARROW_DATATYPE pa.int64()C 侧rerun_cpp/src/rerun/encodings/time_int.hpp 中struct TimeInt { int64_t value; }位于rerun::encodings命名空间。由于直接映射为Int64序列化路径非常轻量Rust 侧ToArrow将TimeInt逐元素解包为i64组成PrimitiveArrayInt64TypeFromArrow则从Int64Array逐个还原见 time_int.rs。语义边界STATIC / MIN / MAX 特殊值虽然从外部看TimeInt就是i64但在 Rerun 的内部存储层TimeInt被实现为OptionNonMinI64见 crates/store/re_log_types/src/index/time_int.rs这使得它能够表达一个特殊的静态数据static状态TimeInt::STATIC内部为None用于表示静态数据不随时间变化的数据。文档强调SDK 用户不能显式地在某个时间戳上记录这种值——只有通过静态 API 才能产生静态数据任何时间上下文temporal context中构造该值都是非法的TimeInt::MIN不是i64::MIN因为i64::MIN已被保留作为静态数据的标记MIN实际为NonMinI64::MIN即i64::MIN 1见 crates/store/re_types_core/src/encodings/time_int_ext.rsTimeInt::MAX最大时间值即i64::MAXTimeInt::ZERO/TimeInt::ONE常用的小常数。对应地as_i64()对STATIC返回i64::MINas_f64()对STATIC返回f64::MIN见 time_int.rs。这也带来一个重要的边界行为TimeInt::new_temporal(time)在传入i64::MIN时会收敛为TimeInt::MIN且永远不可能返回STATIC测试用例saturated_temporal验证了i64::MIN、i64::MIN 1均饱和到MINi64::MAX保持为MAX见 time_int.rs。与 TimeType 的配对它到底是时间还是序号TimeInt必须与TimeType一起理解。TimeType是一个三值枚举见 crates/store/re_log_types/src/index/time_type.rs变体含义Arrow 数据类型Sequence序列号如影片帧号Int64DurationNs纳秒计时的时长Duration(Nanosecond)TimestampNs自 Unix 纪元以来的纳秒Timestamp(Nanosecond, None)有趣的是TimeType::datatype()在 Arrow 层把三种类型分别编码为Int64、Duration、Timestamp三种不同数据类型time_type.rs而TimeInt本身总是Int64——也就是说这是不是时间的语义信息存放在时间轴/时间类型上而非整数本身。make_arrow_array与from_arrow_array负责在这些数据类型与裸的ScalarBufferi64之间来回转换。多语言构造 APIPython 的关键字式构造PythonPython 侧TimeInt的构造函数要求seq、seconds、nanos三者恰好提供其一见 rerun_py/rerun_sdk/rerun/encodings/time_int_ext.py# 序列号 rr.TimeInt(seq42) # 秒按时间轴类型解释为时长或纪元后秒数内部转为 int(seconds * 1e9) rr.TimeInt(seconds0.5) # 纳秒按时间轴类型解释为时长或纪元后纳秒数 rr.TimeInt(nanos500_000_000)若传入多个关键字或一个都不传会抛出ValueError(Exactly one of seq, seconds, or nanos must be provided.)。seconds参数内部执行int(seconds * 1e9)的换算nanos则原样保留。RustRust 侧TimeInt提供了一组语义化的构造方法见 crates/store/re_log_types/src/index/time_int.rsTimeInt::from_sequence(seq) // 序列时间轴 TimeInt::from_nanos(nanos) // 时间时间轴纳秒 TimeInt::from_millis(millis) // 时间时间轴毫秒内部 saturating_mul 1_000_000 TimeInt::from_secs(seconds_f64) // 时间时间轴秒内部 (seconds * 1e9).round() TimeInt::new_temporal(i64) // 通用构造永不返回 STATIC此外还实现了TryFromi64拒绝i64::MIN、FromNonMinI64、Add/Sub饱和运算static 参与运算结果仍为 static、Neg、midpoint、closest_multiple_of、saturating_add/saturating_sub、inc/dec等运算time_int.rs。Duration与Timestamp也可与TimeInt相互转换如FromTimeInt for Duration调用Duration::from_nanos。CC 侧最直接TimeInt就是带一个int64_t value的 POD 结构体可用int64_t隐式构造或赋值rerun_cpp/src/rerun/encodings/time_int.hpprerun::encodings::TimeInt t1{42}; // 序列号 rerun::encodings::TimeInt t2; // 默认构造 t2 1640995203000000000; // 纳秒时间轴Timeline中的角色log_time 与 log_tickTimeInt是Timeline上承载的时间值的载体。Rerun SDK 会为每次日志调用自动维护两条内置时间轴见 crates/store/re_log_types/src/index/timeline.rslog_time类型为TimeType::TimestampNs记录数据被记录时的墙钟时间log_tick类型为TimeType::Sequence每次调用RecordingStream的日志方法时单调递增的 tick 序号。两条时间轴的取值正是以TimeInt形式存储的前者是纪元纳秒后者是序列号这也直接呼应了文档开头nanoseconds OR sequence numbers的定义。被谁使用TimeRange 体系与 Timestamp 组件文档末尾列出了TimeInt的三个下游使用者它们的关联文档与结构如下类型关联文档与 TimeInt 的关系AbsoluteTimeRangeabsolute_time_range.md由两个非空TimeInt字段min/max组成描述一个时间范围max为闭区间Arrow 层为Struct(min: non-null Int64, max: non-null Int64)TimeRangeBoundarytime_range_boundary.md时间范围的左/右边界CursorRelative 1相对时间游标的TimeInt偏移、Absolute 2绝对TimeInt值、Infinite 3无限延伸Timestamptimestamp.md录制开始时刻应为相对 Unix 纪元的时间其 Rerun 编码即为TimeIntArrow 数据类型为Int64被McapStatistics、RecordingInfo等 archetype 使用TimeRangeBoundary进一步被 time_range.md 中的TimeRangestart/end两个边界引用构成可见时间范围的完整表达链TimeInt→TimeRangeBoundary→TimeRange→VisibleTimeRange。实战示例在 DataframeView 中按时间范围过滤TimeInt最直观的落地场景是 Dataframe View 的filter_by_range。仓库示例 rerun_py/rerun_sdk/rerun/blueprint/views/dataframe_view.py 中这样使用rrb.DataframeView( origin/trig, queryrrb.archetypes.DataframeQuery( timelinet, filter_by_range(rr.TimeInt(seconds0), rr.TimeInt(seconds20)), # ... ), )这里rr.TimeInt(seconds0)与rr.TimeInt(seconds20)分别表示时间轴t上的起始与结束时间底层被编码为纪元纳秒0与20 * 1e9再通过AbsoluteTimeRange/TimeRangeBoundary的 Arrow 结构送入查询管线。小结TimeInt是 Rerun 时间体系的原子单位一个 64 位整数语义由所在时间轴的TimeType决定Arrow 层恒为Int64跨 Rust / Python / C 三端保持一致内部以OptionNonMinI64实现保留STATIC标记静态数据并因此牺牲了i64::MIN作为合法时间值它是AbsoluteTimeRange、TimeRangeBoundary、Timestamp的组成基础贯穿查询过滤、蓝图时间范围与录制元数据等场景。在阅读 类型参考索引 时可以顺着Used by的链接继续深入AbsoluteTimeRange、TimeRangeBoundary与Timestamp从而完整掌握 Rerun 的时间与范围编码体系。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考