{Feature} Core - Replace EmgData with NeuralBandBatch for Meta Neural Band sensor stream

Summary:
Refactors the reader-side sensor type for the Meta Neural Band batch stream
(EMG + IMU accel + gyro) from `EmgData` into a new `NeuralBandBatch` type
family. The new API delivers pre-decoded per-sub-sample structs
(`NeuralBandEmgSample` / `NeuralBandAccelSample` / `NeuralBandGyroSample`)
with reader-synthesized device-timeline timestamps, eliminating (1) the
"one type for three semantically different things" confusion, (2) the raw
`packed_channel_data` exposure that no consumer benefits from, (3) the
silent shape-mismatch bug when malformed packets were skipped, and (4) the
misleading `samples_per_batch` field name.

Timestamp synthesis derives a batch-wide sub-sample period from wire packet
cadence (before decode skipping) and back-fills per-sub-sample timestamps
anchored at each wire packet's LAST-sub-sample time (the rebase convention).
Runtime log-warn guards catch firmware convention drift, non-monotonic
timestamps, single-packet-batch degradation, and post-rebase invariant
violations without throwing.

Wire schema and writer are unchanged; existing VRS recordings are read
without modification. `SensorDataType::Emg` is renamed to
`SensorDataType::NeuralBandBatch` (breaking); all in-tree consumers are
updated in this diff. Static label parity between the reader's
`NeuralBandBatchMetadata.h` and the writer's `EmgImuBatchLayout.h` is
verified (all 18 DataLayout labels match byte-for-byte). A new backward-
compat regression test
(`NeuralBandBatchPlayerTest.BackwardCompat_ReadsSyntheticGen2FixtureViaFullPipeline`)
exercises the full reader pipeline against a synthesized VRS fixture that
uses the production wire flavor tag and label.

Reproducibility:
`buck2 build` and `buck2 test` pass across:
- fbsource//arvr/projects/ariane/aria_research_kit/projectaria_tools/core/...
- fbsource//arvr/projects/oatmeal/client_sdk/...
- fbsource//arvr/projects/surreal/vrs_health_check/gen2_lib/...

Reviewed By: ryanfrawley

Differential Revision: D113434161

fbshipit-source-id: c720ef5acf55c97413d230a19e7f4e96e7536ef7

Author: kongchen1992

core/data_provider/RecordReaderInterface.cpp

@@ -156,7 +156,7 @@ RecordReaderInterface::RecordReaderInterface(
     std::map<vrs::StreamId, std::shared_ptr<PpgPlayer>>& ppgPlayers,
     std::map<vrs::StreamId, std::shared_ptr<AlsPlayer>>& alsPlayers,
     std::map<vrs::StreamId, std::shared_ptr<TemperaturePlayer>>& temperaturePlayers,
-    std::map<vrs::StreamId, std::shared_ptr<EmgPlayer>>& emgPlayers,
+    std::map<vrs::StreamId, std::shared_ptr<NeuralBandBatchPlayer>>& neuralBandBatchPlayers,
     std::map<vrs::StreamId, std::shared_ptr<VioPlayer>>& vioPlayers,
     std::map<vrs::StreamId, std::shared_ptr<VioHighFrequencyPlayer>>& vioHighFreqPlayers,
     std::map<vrs::StreamId, std::shared_ptr<EyeGazePlayer>>& eyegazePlayers,
@@ -176,7 +176,7 @@ RecordReaderInterface::RecordReaderInterface(
       ppgPlayers_(ppgPlayers),
       alsPlayers_(alsPlayers),
       temperaturePlayers_(temperaturePlayers),
-      emgPlayers_(emgPlayers),
+      neuralBandBatchPlayers_(neuralBandBatchPlayers),
       vioPlayers_(vioPlayers),
       vioHighFreqPlayers_(vioHighFreqPlayers),
       eyegazePlayers_(eyegazePlayers),
@@ -248,9 +248,9 @@ RecordReaderInterface::RecordReaderInterface(
     streamIdToSensorDataType_.emplace(streamId, SensorDataType::Temperature);
   }
 
-  for (const auto& [streamId, _] : emgPlayers_) {
+  for (const auto& [streamId, _] : neuralBandBatchPlayers_) {
     streamIds_.insert(streamId);
-    streamIdToSensorDataType_.emplace(streamId, SensorDataType::Emg);
+    streamIdToSensorDataType_.emplace(streamId, SensorDataType::NeuralBandBatch);
   }
 
   for (const auto& [streamId, _] : vioPlayers_) {
@@ -324,7 +324,7 @@ std::optional<VrsMetadata> RecordReaderInterface::getMetadata() const {
     case calibration::DeviceVersion::Gen2:
       fillMetadataForGen2(metadata, metadataJson);
       break;
-    default:
+    case calibration::DeviceVersion::NotValid:
       throw std::runtime_error(
           fmt::format(
               "Unsupported device version for loading metadata: {}", getName(deviceVersion_)));
@@ -566,8 +566,8 @@ SensorData RecordReaderInterface::getLastCachedSensorData(const vrs::StreamId& s
       }
       return {streamId, std::move(data), sensorDataType, recordTimeNs, timeSyncData};
     }
-    case SensorDataType::Emg: {
-      auto data = getLastCachedEmgData(streamId);
+    case SensorDataType::NeuralBandBatch: {
+      auto data = getLastCachedNeuralBandBatch(streamId);
       std::map<TimeSyncMode, int64_t> timeSyncData;
       for (const auto& mode : timeSyncMapper_->getTimeSyncModes()) {
         const int64_t& syncTimeNs =
@@ -623,7 +623,6 @@ SensorData RecordReaderInterface::getLastCachedSensorData(const vrs::StreamId& s
       return {streamId, std::move(data), sensorDataType, recordTimeNs, timeSyncData};
     }
     case SensorDataType::NotValid:
-    default:
       break;
   }
   return {streamId, std::monostate{}, SensorDataType::NotValid, -1, {}};
@@ -728,11 +727,11 @@ BatteryStatusData RecordReaderInterface::getLastCachedBatteryStatusData(
   return batteryStatusData;
 }
 
-EmgData RecordReaderInterface::getLastCachedEmgData(const vrs::StreamId& streamId) {
+NeuralBandBatch RecordReaderInterface::getLastCachedNeuralBandBatch(const vrs::StreamId& streamId) {
   std::unique_lock<std::mutex> readLock(*(streamIdToPlayerMutex_.at(streamId)));
-  auto emgData = emgPlayers_[streamId]->getDataRecord();
+  auto neuralBandBatch = neuralBandBatchPlayers_[streamId]->getDataRecord();
   streamIdToCondition_.at(streamId)->notify_one();
-  return emgData;
+  return neuralBandBatch;
 }
 
 uint32_t RecordReaderInterface::getRgbIspTuningVersion() const {

core/data_provider/RecordReaderInterface.h

@@ -26,9 +26,9 @@
 #include <data_provider/TimeSyncMapper.h>
 #include <data_provider/VrsMetadata.h>
 #include <data_provider/players/AlsPlayer.h>
-#include <data_provider/players/EmgPlayer.h>
 #include <data_provider/players/EyeGazePlayer.h>
 #include <data_provider/players/HandPosePlayer.h>
+#include <data_provider/players/NeuralBandBatchPlayer.h>
 #include <data_provider/players/PpgPlayer.h>
 #include <data_provider/players/TemperaturePlayer.h>
 #include <data_provider/players/VioHighFrequencyPlayer.h>
@@ -66,7 +66,7 @@ class RecordReaderInterface {
       std::map<vrs::StreamId, std::shared_ptr<PpgPlayer>>& ppgPlayers,
       std::map<vrs::StreamId, std::shared_ptr<AlsPlayer>>& alsPlayers,
       std::map<vrs::StreamId, std::shared_ptr<TemperaturePlayer>>& temperaturePlayers,
-      std::map<vrs::StreamId, std::shared_ptr<EmgPlayer>>& emgPlayers,
+      std::map<vrs::StreamId, std::shared_ptr<NeuralBandBatchPlayer>>& neuralBandBatchPlayers,
       std::map<vrs::StreamId, std::shared_ptr<VioPlayer>>& vioPlayers,
       std::map<vrs::StreamId, std::shared_ptr<VioHighFrequencyPlayer>>& vioHighFreqPlayers,
       std::map<vrs::StreamId, std::shared_ptr<EyeGazePlayer>>& eyegazePlayers,
@@ -105,7 +105,7 @@ class RecordReaderInterface {
   PpgData getLastCachedPpgData(const vrs::StreamId& streamId);
   AlsData getLastCachedAlsData(const vrs::StreamId& streamId);
   TemperatureData getLastCachedTemperatureData(const vrs::StreamId& streamId);
-  EmgData getLastCachedEmgData(const vrs::StreamId& streamId);
+  NeuralBandBatch getLastCachedNeuralBandBatch(const vrs::StreamId& streamId);
 
   /* read the last cached on-device MP data in player */
   FrontendOutput getLastCachedVioData(const vrs::StreamId& streamId);
@@ -171,7 +171,7 @@ class RecordReaderInterface {
   std::map<vrs::StreamId, std::shared_ptr<PpgPlayer>> ppgPlayers_;
   std::map<vrs::StreamId, std::shared_ptr<AlsPlayer>> alsPlayers_;
   std::map<vrs::StreamId, std::shared_ptr<TemperaturePlayer>> temperaturePlayers_;
-  std::map<vrs::StreamId, std::shared_ptr<EmgPlayer>> emgPlayers_;
+  std::map<vrs::StreamId, std::shared_ptr<NeuralBandBatchPlayer>> neuralBandBatchPlayers_;
 
   std::map<vrs::StreamId, std::shared_ptr<VioPlayer>> vioPlayers_;
   std::map<vrs::StreamId, std::shared_ptr<VioHighFrequencyPlayer>> vioHighFreqPlayers_;

core/data_provider/SensorConfiguration.cpp

@@ -79,9 +79,11 @@ TemperatureConfiguration SensorConfiguration::temperatureConfiguration() const {
       sensorDataType_ == SensorDataType::Temperature, "Sensor data type is not Temperature");
   return std::get<TemperatureConfiguration>(sensorConfigurationVariant_);
 }
-EmgConfiguration SensorConfiguration::emgConfiguration() const {
-  checkAndThrow(sensorDataType_ == SensorDataType::Emg, "Sensor data type is not Emg");
-  return std::get<EmgConfiguration>(sensorConfigurationVariant_);
+NeuralBandBatchConfiguration SensorConfiguration::neuralBandBatchConfiguration() const {
+  checkAndThrow(
+      sensorDataType_ == SensorDataType::NeuralBandBatch,
+      "Sensor data type is not NeuralBandBatch");
+  return std::get<NeuralBandBatchConfiguration>(sensorConfigurationVariant_);
 }
 EyeGazeConfiguration SensorConfiguration::eyeGazeConfiguration() const {
   checkAndThrow(sensorDataType_ == SensorDataType::EyeGaze, "Sensor data type is not EyeGaze");
@@ -127,8 +129,9 @@ double SensorConfiguration::getNominalRateHz() const {
       return alsConfiguration().nominalRateHz;
     case SensorDataType::Temperature:
       return temperatureConfiguration().nominalRateHz;
-    case SensorDataType::Emg:
-      return emgConfiguration().nominalRateHz;
+    case SensorDataType::NeuralBandBatch:
+      // Sample rate not stored in config; infer from sample timestamps.
+      return -1;
     case SensorDataType::EyeGaze:
       return eyeGazeConfiguration().nominalRateHz;
     case SensorDataType::HandPose:
@@ -138,9 +141,9 @@ double SensorConfiguration::getNominalRateHz() const {
     case SensorDataType::VioHighFreq:
       return vioHighFreqConfiguration().nominalRateHz;
     case SensorDataType::NotValid:
-    default:
       return -1;
   }
+  return -1;
 }
 
 } // namespace projectaria::tools::data_provider

core/data_provider/SensorConfiguration.h

@@ -23,12 +23,12 @@
 #include <data_provider/players/BarometerPlayer.h>
 #include <data_provider/players/BatteryStatusPlayer.h>
 #include <data_provider/players/BluetoothBeaconPlayer.h>
-#include <data_provider/players/EmgPlayer.h>
 #include <data_provider/players/EyeGazePlayer.h>
 #include <data_provider/players/GpsPlayer.h>
 #include <data_provider/players/HandPosePlayer.h>
 #include <data_provider/players/ImageSensorPlayer.h>
 #include <data_provider/players/MotionSensorPlayer.h>
+#include <data_provider/players/NeuralBandBatchPlayer.h>
 #include <data_provider/players/PpgPlayer.h>
 #include <data_provider/players/TemperaturePlayer.h>
 #include <data_provider/players/VioHighFrequencyPlayer.h>
@@ -58,7 +58,7 @@ class SensorConfiguration {
       PpgConfiguration,
       AlsConfiguration,
       TemperatureConfiguration,
-      EmgConfiguration,
+      NeuralBandBatchConfiguration,
       EyeGazeConfiguration,
       HandPoseConfiguration,
       VioConfiguration,
@@ -145,10 +145,10 @@ class SensorConfiguration {
   [[nodiscard]] TemperatureConfiguration temperatureConfiguration() const;
 
   /**
-   * @brief Returns the sensor configuration as EmgConfiguration
-   * @pre type is Emg
+   * @brief Returns the sensor configuration as NeuralBandBatchConfiguration
+   * @pre type is NeuralBandBatch
    */
-  [[nodiscard]] EmgConfiguration emgConfiguration() const;
+  [[nodiscard]] NeuralBandBatchConfiguration neuralBandBatchConfiguration() const;
 
   /**
    * @brief Returns the sensor configuration as HandPoseConfiguration

core/data_provider/SensorData.cpp

@@ -92,9 +92,11 @@ TemperatureData SensorData::temperatureData() const {
   return std::get<TemperatureData>(dataVariant_);
 }
 
-EmgData SensorData::emgData() const {
-  checkAndThrow(sensorDataType_ == SensorDataType::Emg, "Sensor data type is not EMG");
-  return std::get<EmgData>(dataVariant_);
+NeuralBandBatch SensorData::neuralBandBatchData() const {
+  checkAndThrow(
+      sensorDataType_ == SensorDataType::NeuralBandBatch,
+      "Sensor data type is not NeuralBandBatch");
+  return std::get<NeuralBandBatch>(dataVariant_);
 }
 
 BatteryStatusData SensorData::batteryStatusData() const {
@@ -150,8 +152,8 @@ int64_t SensorData::getDeviceTime() const {
       return alsData().captureTimestampNs;
     case SensorDataType::Temperature:
       return temperatureData().captureTimestampNs;
-    case SensorDataType::Emg:
-      return emgData().captureTimestampNs;
+    case SensorDataType::NeuralBandBatch:
+      return neuralBandBatchData().captureTimestampNs;
     case SensorDataType::BatteryStatus:
       return batteryStatusData().captureTimestampNs;
 
@@ -194,7 +196,7 @@ int64_t SensorData::getHostTime() const {
     case SensorDataType::Ppg:
     case SensorDataType::Als:
     case SensorDataType::Temperature:
-    case SensorDataType::Emg:
+    case SensorDataType::NeuralBandBatch:
     case SensorDataType::Vio:
     case SensorDataType::VioHighFreq:
     case SensorDataType::EyeGaze:

core/data_provider/SensorData.h

@@ -24,10 +24,10 @@
 #include <data_provider/players/BarometerPlayer.h>
 #include <data_provider/players/BatteryStatusPlayer.h>
 #include <data_provider/players/BluetoothBeaconPlayer.h>
-#include <data_provider/players/EmgPlayer.h>
 #include <data_provider/players/GpsPlayer.h>
 #include <data_provider/players/ImageSensorPlayer.h>
 #include <data_provider/players/MotionSensorPlayer.h>
+#include <data_provider/players/NeuralBandBatchPlayer.h>
 #include <data_provider/players/PpgPlayer.h>
 #include <data_provider/players/TemperaturePlayer.h>
 #include <data_provider/players/VioPlayer.h>
@@ -70,7 +70,7 @@ class SensorData {
       PpgData,
       AlsData,
       TemperatureData,
-      EmgData,
+      NeuralBandBatch,
       /* on device MP data types*/
       FrontendOutput,
       OnDeviceVioHighFreqData,
@@ -171,10 +171,10 @@ class SensorData {
   [[nodiscard]] TemperatureData temperatureData() const;
 
   /**
-   * @brief Returns the sensor data as EmgData
-   * @pre type is Emg
+   * @brief Returns the sensor data as NeuralBandBatch
+   * @pre type is NeuralBandBatch
    */
-  [[nodiscard]] EmgData emgData() const;
+  [[nodiscard]] NeuralBandBatch neuralBandBatchData() const;
 
   /**
    * @brief Returns the sensor data as BatteryStatusData

core/data_provider/SensorDataType.cpp

@@ -40,7 +40,7 @@ std::string getName(const SensorDataType type) {
       {SensorDataType::VioHighFreq, "VIO high freq"},
       {SensorDataType::EyeGaze, "eyegaze"},
       {SensorDataType::HandPose, "hand pose"},
-      {SensorDataType::Emg, "EMG"},
+      {SensorDataType::NeuralBandBatch, "NeuralBandBatch"},
       {SensorDataType::NotValid, "invalid"}};
   return kTypeNameMap.at(type);
 }

core/data_provider/SensorDataType.h

@@ -47,7 +47,7 @@ enum class SensorDataType {
   VioHighFreq, /**< On Device VIO high frequency data streams*/
   EyeGaze, /**< On Device Eye gaze data streams*/
   HandPose, /**< On Device Hand tracking data streams*/
-  Emg, /**< Electromyography (EMG) IMU batch data streams */
+  NeuralBandBatch, /**< Meta Neural Band batch data streams (EMG + IMU accel + gyro) */
 };
 
 /** @brief converts the enum to readable std::string */

core/data_provider/StreamIdConfigurationMapper.cpp

@@ -37,7 +37,7 @@ StreamIdConfigurationMapper::StreamIdConfigurationMapper(
     std::map<vrs::StreamId, std::shared_ptr<PpgPlayer>>& ppgPlayers,
     std::map<vrs::StreamId, std::shared_ptr<AlsPlayer>>& alsPlayers,
     std::map<vrs::StreamId, std::shared_ptr<TemperaturePlayer>>& temperaturePlayers,
-    std::map<vrs::StreamId, std::shared_ptr<EmgPlayer>>& emgPlayers,
+    std::map<vrs::StreamId, std::shared_ptr<NeuralBandBatchPlayer>>& neuralBandBatchPlayers,
     std::map<vrs::StreamId, std::shared_ptr<EyeGazePlayer>>& EyeGazePlayers,
     std::map<vrs::StreamId, std::shared_ptr<HandPosePlayer>>& handPosePlayers,
     std::map<vrs::StreamId, std::shared_ptr<VioPlayer>>& vioPlayers,
@@ -90,8 +90,8 @@ StreamIdConfigurationMapper::StreamIdConfigurationMapper(
   for (const auto& [streamId, temperaturePlayer] : temperaturePlayers) {
     streamIdToTemperatureConfig_.emplace(streamId, temperaturePlayer->getConfigRecord());
   }
-  for (const auto& [streamId, emgPlayer] : emgPlayers) {
-    streamIdToEmgConfig_.emplace(streamId, emgPlayer->getConfigRecord());
+  for (const auto& [streamId, neuralBandBatchPlayer] : neuralBandBatchPlayers) {
+    streamIdToNeuralBandBatchConfig_.emplace(streamId, neuralBandBatchPlayer->getConfigRecord());
   }
 }
 
@@ -158,9 +158,9 @@ TemperatureConfiguration StreamIdConfigurationMapper::getTemperatureConfiguratio
   return streamIdToTemperatureConfig_.at(streamId);
 }
 
-EmgConfiguration StreamIdConfigurationMapper::getEmgConfiguration(
+NeuralBandBatchConfiguration StreamIdConfigurationMapper::getNeuralBandBatchConfiguration(
     const vrs::StreamId& streamId) const {
-  return streamIdToEmgConfig_.at(streamId);
+  return streamIdToNeuralBandBatchConfig_.at(streamId);
 }
 
 EyeGazeConfiguration StreamIdConfigurationMapper::getEyeGazeConfiguration(

core/data_provider/StreamIdConfigurationMapper.h

@@ -39,7 +39,7 @@ class StreamIdConfigurationMapper {
       std::map<vrs::StreamId, std::shared_ptr<PpgPlayer>>& ppgPlayers,
       std::map<vrs::StreamId, std::shared_ptr<AlsPlayer>>& alsPlayers,
       std::map<vrs::StreamId, std::shared_ptr<TemperaturePlayer>>& temperaturePlayers,
-      std::map<vrs::StreamId, std::shared_ptr<EmgPlayer>>& emgPlayers,
+      std::map<vrs::StreamId, std::shared_ptr<NeuralBandBatchPlayer>>& neuralBandBatchPlayers,
       std::map<vrs::StreamId, std::shared_ptr<EyeGazePlayer>>& EyeGazePlayers,
       std::map<vrs::StreamId, std::shared_ptr<HandPosePlayer>>& handPosePlayers,
       std::map<vrs::StreamId, std::shared_ptr<VioPlayer>>& vioPlayers,
@@ -64,7 +64,8 @@ class StreamIdConfigurationMapper {
   [[nodiscard]] AlsConfiguration getAlsConfiguration(const vrs::StreamId& streamId) const;
   [[nodiscard]] TemperatureConfiguration getTemperatureConfiguration(
       const vrs::StreamId& streamId) const;
-  [[nodiscard]] EmgConfiguration getEmgConfiguration(const vrs::StreamId& streamId) const;
+  [[nodiscard]] NeuralBandBatchConfiguration getNeuralBandBatchConfiguration(
+      const vrs::StreamId& streamId) const;
   [[nodiscard]] EyeGazeConfiguration getEyeGazeConfiguration(const vrs::StreamId& streamId) const;
   [[nodiscard]] HandPoseConfiguration getHandPoseConfiguration(const vrs::StreamId& streamId) const;
   [[nodiscard]] VioConfiguration getVioConfiguration(const vrs::StreamId& streamId) const;
@@ -84,7 +85,7 @@ class StreamIdConfigurationMapper {
   std::map<vrs::StreamId, PpgConfiguration> streamIdToPpgConfig_;
   std::map<vrs::StreamId, AlsConfiguration> streamIdToAlsConfig_;
   std::map<vrs::StreamId, TemperatureConfiguration> streamIdToTemperatureConfig_;
-  std::map<vrs::StreamId, EmgConfiguration> streamIdToEmgConfig_;
+  std::map<vrs::StreamId, NeuralBandBatchConfiguration> streamIdToNeuralBandBatchConfig_;
   std::map<vrs::StreamId, EyeGazeConfiguration> streamIdToEyeGazeConfig_;
   std::map<vrs::StreamId, HandPoseConfiguration> streamIdToHandPoseConfig_;
   std::map<vrs::StreamId, VioConfiguration> streamIdToVioConfig_;