Use consistent time unit names for our API

CODE_STYLE.md

@@ -229,6 +229,19 @@ Avoid negations in names. A lot of people struggle with double negations, so thi
 
 For UI functions (functions taking an `&mut egui::Ui` argument), we use the name `ui` or `_ui` suffix, e.g. `blueprint_ui(…)` or `blueprint.ui(…)`.
 
+### Units
+* When in doubt, be explicit (`duration_secs: f32` is better than `duration: f32`)
+* All things being equal, prefer SI base units (seconds over milliseconds, Hz over RPM, etc)
+* When precision matters, prefer `nanos: i64` over `secs: f64`
+* Store angles in radians (but you may print/display them as degrees)
+
+Follow the conventions set by Rust stdlib:
+* `secs` instead of `seconds`
+* `millis` instead of `ms` or `milliseconds`
+* `micros` instead of `us` or `microseconds`
+* `nanos` instead of `ns` or `nanoseconds`
+
+
 ### Spaces
 Points, vectors, rays etc all live in different _spaces_. Whenever there is room for ambiguity, we explicitly state which space something is in, e.g. with `ray_in_world`.
 

crates/store/re_chunk/src/chunk.rs

@@ -987,7 +987,7 @@ impl TimeColumn {
     }
 
     /// Creates a new [`TimeColumn`] of duration type, in seconds.
-    pub fn new_duration_seconds(
+    pub fn new_duration_secs(
         name: impl Into<re_log_types::TimelineName>,
         seconds: impl IntoIterator<Item = impl Into<f64>>,
     ) -> Self {
@@ -999,7 +999,7 @@ impl TimeColumn {
                 re_log::warn!(
                     illegal_value = nanos,
                     new_value = clamped.get(),
-                    "TimeColumn::new_duration_seconds() called with out-of-range value. Clamped to valid range."
+                    "TimeColumn::new_duration_secs() called with out-of-range value. Clamped to valid range."
                 );
             }
             clamped.get()
@@ -1013,7 +1013,7 @@ impl TimeColumn {
     }
 
     /// Creates a new [`TimeColumn`] of duration type, in seconds.
-    pub fn new_timestamp_seconds_since_epoch(
+    pub fn new_timestamp_secs_since_epoch(
         name: impl Into<re_log_types::TimelineName>,
         seconds: impl IntoIterator<Item = impl Into<f64>>,
     ) -> Self {
@@ -1025,7 +1025,7 @@ impl TimeColumn {
                 re_log::warn!(
                     illegal_value = nanos,
                     new_value = clamped.get(),
-                    "TimeColumn::new_timestamp_seconds_since_epoch() called with out-of-range value. Clamped to valid range."
+                    "TimeColumn::new_timestamp_secs_since_epoch() called with out-of-range value. Clamped to valid range."
                 );
             }
             clamped.get()
@@ -1039,12 +1039,12 @@ impl TimeColumn {
     }
 
     /// Creates a new [`TimeColumn`] of duration type, in seconds.
-    #[deprecated = "Use `TimeColumn::new_duration_seconds` or `new_timestamp_seconds_since_epoch` instead"]
-    pub fn new_seconds(
+    #[deprecated = "Use `TimeColumn::new_duration_secs` or `new_timestamp_secs_since_epoch` instead"]
+    pub fn new_secs(
         name: impl Into<re_log_types::TimelineName>,
         seconds: impl IntoIterator<Item = impl Into<f64>>,
     ) -> Self {
-        Self::new_duration_seconds(name, seconds)
+        Self::new_duration_secs(name, seconds)
     }
 
     /// Creates a new [`TimeColumn`] measuring duration in nanoseconds.

crates/store/re_chunk_store/tests/formatting.rs

@@ -35,7 +35,7 @@ fn format_chunk_store() -> anyhow::Result<()> {
                 row_id,
                 [
                     build_frame_nr(1),
-                    build_log_time(Timestamp::from_ns_since_epoch(1_736_534_622_123_456_789)),
+                    build_log_time(Timestamp::from_nanos_since_epoch(1_736_534_622_123_456_789)),
                 ],
                 [indices1.try_serialized()?, colors1.try_serialized()?],
             )

crates/store/re_data_loader/src/loader_archetype.rs

@@ -191,16 +191,16 @@ fn load_video(
 
     let video_asset = AssetVideo::new(contents);
 
-    let video_frame_reference_chunk = match video_asset.read_frame_timestamps_ns() {
-        Ok(frame_timestamps_ns) => {
+    let video_frame_reference_chunk = match video_asset.read_frame_timestamps_nanos() {
+        Ok(frame_timestamps_nanos) => {
             // Time column.
             let is_sorted = Some(true);
-            let frame_timestamps_ns: arrow::buffer::ScalarBuffer<i64> = frame_timestamps_ns.into();
+            let frame_timestamps_nanos: arrow::buffer::ScalarBuffer<i64> = frame_timestamps_nanos.into();
             let time_column =
-                re_chunk::TimeColumn::new(is_sorted, video_timeline, frame_timestamps_ns.clone());
+                re_chunk::TimeColumn::new(is_sorted, video_timeline, frame_timestamps_nanos.clone());
 
             // VideoTimestamp component column.
-            let video_timestamps = frame_timestamps_ns
+            let video_timestamps = frame_timestamps_nanos
                 .iter()
                 .copied()
                 .map(VideoTimestamp::from_nanoseconds)

crates/store/re_data_loader/src/loader_lerobot.rs

@@ -387,11 +387,11 @@ fn load_episode_video(
     let video_asset = AssetVideo::new(contents.into_owned());
     let entity_path = observation;
 
-    let video_frame_reference_chunk = match video_asset.read_frame_timestamps_ns() {
-        Ok(frame_timestamps_ns) => {
-            let frame_timestamps_ns: arrow::buffer::ScalarBuffer<i64> = frame_timestamps_ns.into();
+    let video_frame_reference_chunk = match video_asset.read_frame_timestamps_nanos() {
+        Ok(frame_timestamps_nanos) => {
+            let frame_timestamps_nanos: arrow::buffer::ScalarBuffer<i64> = frame_timestamps_nanos.into();
 
-            let video_timestamps = frame_timestamps_ns
+            let video_timestamps = frame_timestamps_nanos
                 .iter()
                 .take(time_column.num_rows())
                 .copied()

crates/store/re_entity_db/src/entity_db.rs

@@ -838,8 +838,7 @@ impl IngestionStatistics {
             let nanos_since_epoch = duration_since_epoch.as_nanos() as u64;
 
             // This only makes sense if the clocks are very good, i.e. if the recording was on the same machine!
-            if let Some(nanos_since_log) =
-                nanos_since_epoch.checked_sub(row_id.nanoseconds_since_epoch())
+            if let Some(nanos_since_log) = nanos_since_epoch.checked_sub(row_id.nanos_since_epoch())
             {
                 let now = nanos_since_epoch as f64 / 1e9;
                 let sec_since_log = nanos_since_log as f32 / 1e9;

crates/store/re_grpc_server/src/lib.rs

@@ -651,7 +651,7 @@ mod tests {
                         re_chunk::RowId::new(),
                         re_log_types::TimePoint::default().with(
                             re_log_types::Timeline::new_sequence("blueprint"),
-                            re_log_types::TimeInt::from_milliseconds(re_log_types::NonMinI64::MIN),
+                            re_log_types::TimeInt::from_millis(re_log_types::NonMinI64::MIN),
                         ),
                         &re_types::blueprint::archetypes::Background::new(
                             re_types::blueprint::components::BackgroundKind::SolidColor,
@@ -700,7 +700,7 @@ mod tests {
                         re_chunk::RowId::new(),
                         re_log_types::TimePoint::default().with(
                             re_log_types::Timeline::new_sequence("log_time"),
-                            re_log_types::TimeInt::from_milliseconds(re_log_types::NonMinI64::MIN),
+                            re_log_types::TimeInt::from_millis(re_log_types::NonMinI64::MIN),
                         ),
                         &re_types::archetypes::Points2D::new([(0.0, 0.0), (1.0, 1.0), (2.0, 2.0)]),
                     )

crates/store/re_log_encoding/src/decoder/mod.rs

@@ -389,7 +389,7 @@ mod tests {
                 re_chunk::RowId::new(),
                 re_log_types::TimePoint::default().with(
                     re_log_types::Timeline::new_sequence("blueprint"),
-                    re_log_types::TimeInt::from_milliseconds(re_log_types::NonMinI64::MIN),
+                    re_log_types::TimeInt::from_millis(re_log_types::NonMinI64::MIN),
                 ),
                 &re_types::blueprint::archetypes::Background::new(
                     re_types::blueprint::components::BackgroundKind::SolidColor,

crates/store/re_log_types/src/index/duration.rs

@@ -47,7 +47,7 @@ impl Duration {
     }
 
     /// Format as seconds, approximately.
-    pub fn format_seconds(self) -> String {
+    pub fn format_secs(self) -> String {
         let nanos = self.as_nanos();
         let secs = nanos as f64 * 1e-9;
 
@@ -70,55 +70,55 @@ impl Duration {
             self.0
         };
 
-        let whole_seconds = total_nanos / Self::NANOS_PER_SEC;
-        let nanos = total_nanos - Self::NANOS_PER_SEC * whole_seconds;
+        let whole_secs = total_nanos / Self::NANOS_PER_SEC;
+        let nanos = total_nanos - Self::NANOS_PER_SEC * whole_secs;
 
-        let mut seconds_remaining = whole_seconds;
+        let mut secs_remaining = whole_secs;
         let mut did_write = false;
 
-        let days = seconds_remaining / Self::SEC_PER_DAY;
+        let days = secs_remaining / Self::SEC_PER_DAY;
         if days > 0 {
             write!(f, "{days}d")?;
-            seconds_remaining -= days * Self::SEC_PER_DAY;
+            secs_remaining -= days * Self::SEC_PER_DAY;
             did_write = true;
         }
 
-        let hours = seconds_remaining / Self::SEC_PER_HOUR;
+        let hours = secs_remaining / Self::SEC_PER_HOUR;
         if hours > 0 {
             if did_write {
                 write!(f, " ")?;
             }
             write!(f, "{hours}h")?;
-            seconds_remaining -= hours * Self::SEC_PER_HOUR;
+            secs_remaining -= hours * Self::SEC_PER_HOUR;
             did_write = true;
         }
 
-        let minutes = seconds_remaining / Self::SEC_PER_MINUTE;
+        let minutes = secs_remaining / Self::SEC_PER_MINUTE;
         if minutes > 0 {
             if did_write {
                 write!(f, " ")?;
             }
             write!(f, "{minutes}m")?;
-            seconds_remaining -= minutes * Self::SEC_PER_MINUTE;
+            secs_remaining -= minutes * Self::SEC_PER_MINUTE;
             did_write = true;
         }
 
         const MAX_MILLISECOND_ACCURACY: bool = true;
         const MAX_MICROSECOND_ACCURACY: bool = true;
 
-        if seconds_remaining > 0 || nanos > 0 || !did_write {
+        if secs_remaining > 0 || nanos > 0 || !did_write {
             if did_write {
                 write!(f, " ")?;
             }
 
             if nanos == 0 {
-                write!(f, "{seconds_remaining}s")?;
+                write!(f, "{secs_remaining}s")?;
             } else if MAX_MILLISECOND_ACCURACY || nanos % 1_000_000 == 0 {
-                write!(f, "{}.{:03}s", seconds_remaining, nanos / 1_000_000)?;
+                write!(f, "{}.{:03}s", secs_remaining, nanos / 1_000_000)?;
             } else if MAX_MICROSECOND_ACCURACY || nanos % 1_000 == 0 {
-                write!(f, "{}.{:06}s", seconds_remaining, nanos / 1_000)?;
+                write!(f, "{}.{:06}s", secs_remaining, nanos / 1_000)?;
             } else {
-                write!(f, "{seconds_remaining}.{nanos:09}s")?;
+                write!(f, "{secs_remaining}.{nanos:09}s")?;
             }
         }
 
@@ -131,27 +131,27 @@ impl Duration {
     pub fn format_subsecond_as_relative(self) -> String {
         let ns = self.as_nanos();
 
-        let fractional_ns = ns % 1_000_000_000;
-        let is_whole_second = fractional_ns == 0;
+        let fractional_nanos = ns % 1_000_000_000;
+        let is_whole_second = fractional_nanos == 0;
 
         if is_whole_second {
             self.to_string()
         } else {
             // We are in the sub-second resolution.
             // Showing the full time (HH:MM:SS.XXX or 3h 2m 6s …) becomes too long,
             // so instead we switch to showing the time as milliseconds since the last whole second:
-            let ms = fractional_ns as f64 * 1e-6;
-            if fractional_ns % 1_000_000 == 0 {
+            let ms = fractional_nanos as f64 * 1e-6;
+            if fractional_nanos % 1_000_000 == 0 {
                 format!("{ms:+.0} ms")
-            } else if fractional_ns % 100_000 == 0 {
+            } else if fractional_nanos % 100_000 == 0 {
                 format!("{ms:+.1} ms")
-            } else if fractional_ns % 10_000 == 0 {
+            } else if fractional_nanos % 10_000 == 0 {
                 format!("{ms:+.2} ms")
-            } else if fractional_ns % 1_000 == 0 {
+            } else if fractional_nanos % 1_000 == 0 {
                 format!("{ms:+.3} ms")
-            } else if fractional_ns % 100 == 0 {
+            } else if fractional_nanos % 100 == 0 {
                 format!("{ms:+.4} ms")
-            } else if fractional_ns % 10 == 0 {
+            } else if fractional_nanos % 10 == 0 {
                 format!("{ms:+.5} ms")
             } else {
                 format!("{ms:+.6} ms")
@@ -222,11 +222,11 @@ mod tests {
 
     #[test]
     fn test_formatting_duratuon() {
-        assert_eq!(&Duration::from_micros(42_000_000).format_seconds(), "+42s");
-        assert_eq!(&Duration::from_micros(69_000).format_seconds(), "+0.069s");
-        assert_eq!(&Duration::from_micros(69_900).format_seconds(), "+0.070s");
+        assert_eq!(&Duration::from_micros(42_000_000).format_secs(), "+42s");
+        assert_eq!(&Duration::from_micros(69_000).format_secs(), "+0.069s");
+        assert_eq!(&Duration::from_micros(69_900).format_secs(), "+0.070s");
         assert_eq!(
-            &Duration::from_micros(42_123_000_000).format_seconds(),
+            &Duration::from_micros(42_123_000_000).format_secs(),
             "+42 123s"
         );
     }

crates/store/re_log_types/src/index/time_cell.rs

@@ -47,8 +47,8 @@ impl TimeCell {
 
     /// Create a timestamp from number of seconds since the unix epoch, 1970-01-01 00:00:00 UTC.
     #[inline]
-    pub fn from_timestamp_seconds_since_epoch(seconds_since_epoch: f64) -> Self {
-        Self::from_timestamp_nanos_since_epoch((1e9 * seconds_since_epoch).round() as i64)
+    pub fn from_timestamp_secs_since_epoch(secs_since_epoch: f64) -> Self {
+        Self::from_timestamp_nanos_since_epoch((1e9 * secs_since_epoch).round() as i64)
     }
 
     /// A timestamp of the current clock time.
@@ -168,7 +168,7 @@ impl TimeCell {
                 crate::Duration::from_nanos(value.into()).format_subsecond_as_relative()
             }
 
-            TimeType::TimestampNs => crate::Timestamp::from_ns_since_epoch(value.into())
+            TimeType::TimestampNs => crate::Timestamp::from_nanos_since_epoch(value.into())
                 .format_time_compact(timestamp_format),
 
             TimeType::Sequence => typ.format(value, timestamp_format),
@@ -182,7 +182,7 @@ impl std::fmt::Display for TimeCell {
             // NOTE: we avoid special characters here so we can put these formats in an URI
             TimeType::Sequence => write!(f, "{}", self.value),
             TimeType::DurationNs => crate::Duration::from_nanos(self.value.get()).fmt(f),
-            TimeType::TimestampNs => crate::Timestamp::from_ns_since_epoch(self.value.get())
+            TimeType::TimestampNs => crate::Timestamp::from_nanos_since_epoch(self.value.get())
                 .format_iso()
                 .fmt(f),
         }

crates/store/re_log_types/src/index/time_int.rs

@@ -82,13 +82,13 @@ impl TimeInt {
 
     /// For time timelines.
     #[inline]
-    pub fn from_milliseconds(millis: NonMinI64) -> Self {
+    pub fn from_millis(millis: NonMinI64) -> Self {
         Self::new_temporal(millis.get().saturating_mul(1_000_000))
     }
 
     /// For time timelines.
     #[inline]
-    pub fn from_seconds(seconds: NonMinI64) -> Self {
+    pub fn from_secs(seconds: NonMinI64) -> Self {
         Self::new_temporal(seconds.get().saturating_mul(1_000_000_000))
     }
 

crates/store/re_log_types/src/index/time_real.rs

@@ -57,7 +57,7 @@ impl TimeReal {
     }
 
     #[inline]
-    pub fn from_seconds(v: f64) -> Self {
+    pub fn from_secs(v: f64) -> Self {
         Self::from(v * 1_000_000_000f64)
     }
 

crates/store/re_log_types/src/index/time_type.rs

@@ -108,7 +108,7 @@ impl TimeType {
             TimeInt::MAX => "+∞".into(),
             _ => match self {
                 Self::Sequence => format!("#{}", re_format::format_int(time_int.as_i64())),
-                Self::DurationNs => super::Duration::from(time_int).format_seconds(),
+                Self::DurationNs => super::Duration::from(time_int).format_secs(),
                 Self::TimestampNs => super::Timestamp::from(time_int).format(timestamp_format),
             },
         }