{Feature} Core - Sync EyeGazeConfigurationLayout to v2

Summary:
Explanation:
Extend `EyeGazeConfigurationLayout` to v2 so `EyeGazePlayer` surfaces three additional per-stream configuration fields:

- `user_calibration_params_json`: verbatim per-user calibration parameters JSON for the ML eye-tracking source; empty for the geometric source or when the user has not been calibrated.
- `field_provenance_single`: packed uint32 (2 bits per slot, indexed by `SingleFieldId`) describing where each per-eye field comes from — direct sensor output, hardcoded constant, calculated from other fields, or not produced at all.
- `field_provenance_combined`: same idea for combined / whole-frame fields, indexed by `CombinedFieldId`.

Also closes a pre-existing gap where `algorithm_name` / `algorithm_version` were declared in the DataLayout but never copied into `EyeGazeConfiguration`, so downstream consumers could not tell which eye-tracking implementation produced the data.

New types under `projectaria::tools::datalayout`:

- `enum class FieldProvenance : uint8_t` with values `SUPPORTED (0)`, `CALCULATED (1)`, `HARDCODED (2)`, `NOT_PRODUCED (3)` — the numeric values ARE the on-disk wire format (2 bits per slot).
- `enum class SingleFieldId : uint32_t` (5 slots: `GazeOrigin`, `GazeDirection`, `EntrancePupilPosition`, `PupilDiameter`, `Blink`).
- `enum class CombinedFieldId : uint32_t` (6 slots: `GazeOriginCombined`, `GazeDirectionCombined`, `ConvergenceDistance`, `InterocularDistance`, `FoveatedGaze`, `SpatialGazePoint`).
- `constexpr` template helpers `getFieldProvenance(packed, id)` / `setFieldProvenance(packed, id, provenance)` to unpack / pack a single slot.

The `EyeGazeConfiguration` struct exposes the raw packed uint32s as `field_provenance_single` / `field_provenance_combined` and typed accessor methods `getSingleFieldProvenance(SingleFieldId)` / `getCombinedFieldProvenance(CombinedFieldId)` that return `FieldProvenance` values directly.

Backwards-compatible with recordings that pre-date these fields: VRS `DataPiece::get()` returns each field's default (empty string / 0) when the field is absent on disk. `0` decodes as `SUPPORTED` for every slot, which is the correct semantics for a source that produces every signal directly.

Python bindings under `projectaria_tools.core.sensor_data` expose the same enums (as `enum.IntEnum` in the type stubs) and the same wrapper methods, so Python callers can either read `config.field_provenance_single` as an `int` or call `config.get_single_field_provenance(SingleFieldId.GAZE_ORIGIN)` for a typed result.

Reproducibility:
Four new C++ tests in `core/data_provider/test/EyeGazePlayerTest.cpp` cover the packed-uint32 helpers (round-trip + cross-slot non-interference), the numeric wire-format contract, an end-to-end v2 config read via `EyeGazePlayer`, and a v1 back-compat read using a locally-defined stripped config layout. One new Python test in `core/python/test/corePyBindTest.py` reads the checked-in Gen2 fixture, asserts the v2 fields fall back to defaults on that (v1-era) fixture, and pins the Python-visible enum values against the wire format.

Reviewed By: PiotrBrzyski

Differential Revision: D113303274

fbshipit-source-id: 5f1233fbd651785ab8e34ddbce4c9c2b979e7ec8

Author: kongchen1992

core/data_provider/data_layout/EyeGazeMetadata.h

@@ -21,9 +21,51 @@
 
 namespace projectaria::tools::datalayout {
 
+// 2 bits per slot on the packed uint32. Numeric values are the on-disk
+// wire format and must not be renumbered.
+enum class FieldProvenance : uint8_t {
+  SUPPORTED = 0, // direct sensor/model output
+  CALCULATED = 1, // derived on-device from other valid fields
+  HARDCODED = 2, // constant from device calibration; valid==true but does not track state
+  NOT_PRODUCED = 3, // source does not populate the field; valid==false
+};
+
+// Slot indices (2 bits each) inside EyeGazeConfigurationLayout::fieldProvenanceSingle.
+enum class SingleFieldId : uint32_t {
+  GazeOrigin = 0,
+  GazeDirection = 1,
+  EntrancePupilPosition = 2,
+  PupilDiameter = 3,
+  Blink = 4,
+};
+
+// Slot indices (2 bits each) inside EyeGazeConfigurationLayout::fieldProvenanceCombined.
+enum class CombinedFieldId : uint32_t {
+  GazeOriginCombined = 0,
+  GazeDirectionCombined = 1,
+  ConvergenceDistance = 2,
+  InterocularDistance = 3,
+  FoveatedGaze = 4,
+  SpatialGazePoint = 5,
+};
+
+template <typename FieldId>
+constexpr FieldProvenance getFieldProvenance(uint32_t packed, FieldId id) {
+  const auto shift = static_cast<uint32_t>(id) * 2u;
+  return static_cast<FieldProvenance>((packed >> shift) & 0b11u);
+}
+
+template <typename FieldId>
+constexpr uint32_t setFieldProvenance(uint32_t packed, FieldId id, FieldProvenance p) {
+  const auto shift = static_cast<uint32_t>(id) * 2u;
+  return (packed & ~(0b11u << shift)) | ((static_cast<uint32_t>(p) & 0b11u) << shift);
+}
+
 class EyeGazeConfigurationLayout : public vrs::AutoDataLayout {
  public:
-  static constexpr uint32_t kVersion = 1;
+  // v2 adds user_calibration_params_json + field_provenance_{single,combined};
+  // VRS field mapping is name-based so older readers skip transparently.
+  static constexpr uint32_t kVersion = 2;
   vrs::DataPieceValue<uint32_t> streamId{"stream_id"};
   // Algorithm version to distinguish different eye tracking implementations. Formatted in string
   // as "Major.minor",
@@ -37,6 +79,16 @@ class EyeGazeConfigurationLayout : public vrs::AutoDataLayout {
   // Indicates the accuracy of the user ET calibration. Lower is better
   vrs::DataPieceValue<float> userCalibrationError{"user_calibration_error"};
 
+  // v2: verbatim calibration_params.json for the ML eye-tracking source.
+  // Empty for the geometric source or when userCalibrated == false.
+  vrs::DataPieceString userCalibrationParamsJson{"user_calibration_params_json"};
+  // v2: per-field provenance for per-eye fields on SingleEyeGazeLayoutStruct.
+  // Packed 2 bits/slot, indexed by SingleFieldId. Applies to both eyes.
+  vrs::DataPieceValue<uint32_t> fieldProvenanceSingle{"field_provenance_single"};
+  // v2: per-field provenance for combined/whole-frame fields on EyeGazeLayout.
+  // Packed 2 bits/slot, indexed by CombinedFieldId.
+  vrs::DataPieceValue<uint32_t> fieldProvenanceCombined{"field_provenance_combined"};
+
   vrs::AutoDataLayoutEnd endLayout;
 };
 

core/data_provider/players/EyeGazePlayer.cpp

@@ -211,6 +211,14 @@ bool EyeGazePlayer::onDataLayoutRead(
     configRecord_.nominalRateHz = configLayout.nominalRateHz.get();
     configRecord_.userCalibrated = configLayout.userCalibrated.get();
     configRecord_.userCalibrationError = configLayout.userCalibrationError.get();
+    // v2 fields; VRS's no-arg .get() returns the DataPiece's default when
+    // the field is not present on disk (v1 recording), which matches our
+    // struct-member defaults (empty string / 0 == all-SUPPORTED).
+    configRecord_.algorithmName = configLayout.algorithmName.get();
+    configRecord_.algorithmVersion = configLayout.algorithmVersion.get();
+    configRecord_.userCalibrationParamsJson = configLayout.userCalibrationParamsJson.get();
+    configRecord_.fieldProvenanceSingle = configLayout.fieldProvenanceSingle.get();
+    configRecord_.fieldProvenanceCombined = configLayout.fieldProvenanceCombined.get();
     return true;
   } else if (header.recordType == vrs::Record::Type::DATA) {
     // Read data as datalayout data type

core/data_provider/players/EyeGazePlayer.h

@@ -22,6 +22,7 @@
 
 #include <sophus/se3.hpp>
 #include <optional>
+#include <string>
 #include <utility>
 
 namespace projectaria::tools::data_provider {
@@ -31,6 +32,23 @@ struct EyeGazeConfiguration {
   double nominalRateHz;
   bool userCalibrated;
   float userCalibrationError;
+
+  // Populated from EyeGazeConfigurationLayout v2. For v1 recordings, VRS
+  // returns each DataPiece's default (empty string / 0 == all-SUPPORTED).
+  std::string algorithmName;
+  std::string algorithmVersion;
+  std::string userCalibrationParamsJson;
+  uint32_t fieldProvenanceSingle{0};
+  uint32_t fieldProvenanceCombined{0};
+
+  [[nodiscard]] datalayout::FieldProvenance getSingleFieldProvenance(
+      datalayout::SingleFieldId id) const {
+    return datalayout::getFieldProvenance(fieldProvenanceSingle, id);
+  }
+  [[nodiscard]] datalayout::FieldProvenance getCombinedFieldProvenance(
+      datalayout::CombinedFieldId id) const {
+    return datalayout::getFieldProvenance(fieldProvenanceCombined, id);
+  }
 };
 
 using EyeGazeCallback =

core/data_provider/test/CompareDataHelper.h

@@ -401,6 +401,11 @@ inline void compare(
   EXPECT_DOUBLE_EQ(eyeGazeConfig1.nominalRateHz, eyeGazeConfig2.nominalRateHz);
   EXPECT_EQ(eyeGazeConfig1.userCalibrated, eyeGazeConfig2.userCalibrated);
   EXPECT_FLOAT_EQ(eyeGazeConfig1.userCalibrationError, eyeGazeConfig2.userCalibrationError);
+  EXPECT_EQ(eyeGazeConfig1.algorithmName, eyeGazeConfig2.algorithmName);
+  EXPECT_EQ(eyeGazeConfig1.algorithmVersion, eyeGazeConfig2.algorithmVersion);
+  EXPECT_EQ(eyeGazeConfig1.userCalibrationParamsJson, eyeGazeConfig2.userCalibrationParamsJson);
+  EXPECT_EQ(eyeGazeConfig1.fieldProvenanceSingle, eyeGazeConfig2.fieldProvenanceSingle);
+  EXPECT_EQ(eyeGazeConfig1.fieldProvenanceCombined, eyeGazeConfig2.fieldProvenanceCombined);
 }
 
 inline void compare(