TagConventions.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
// clang-format off
 
/*
  These tag names are pure conventions VRS users may want to follow when creating their VRS files.
*/
 
#include <vrs/RecordFileWriter.h>
#include <vrs/VrsExport.h>
 
namespace vrs {
 
namespace tag_conventions {
 
// Overall identification, HW & SW independent
 
  // Project name: overarching project name.
  constexpr const char* kProjectName = "project_name";
  // EPOCH time in seconds since Jan 1, 1970, associated with the capture.
  constexpr const char* kCaptureTimeEpoch = "capture_time_epoch";
  // Origin of kCaptureTimeEpoch: supplied by the caller or the source recording, or the host time
  // when the file was written, built offline, or merged from other recordings.
  constexpr const char* kCaptureTimeSource = "capture_time_source";
  constexpr const char* kCaptureTimeSourceExplicit = "explicit";
  constexpr const char* kCaptureTimeSourceHostWriterTime = "host_writer_time";
  constexpr const char* kCaptureTimeSourceHostBuildTime = "host_build_time";
  constexpr const char* kCaptureTimeSourceHostMergeTime = "host_merge_time";
  // Session ID: unique identifier which can be used to recognize the session
  constexpr const char* kSessionId = "session_id";
  // Capture type: description of the recording session context
  // Ex: "calibration", "data_collection", "test"
  constexpr const char* kCaptureType = "capture_type";
  // A set of tags.
  constexpr const char* kTagSet = "tag_set";
 
  VRS_API string addUniqueSessionId(RecordFileWriter& writer);
  VRS_API void addCaptureTime(RecordFileWriter& writer);
  VRS_API void addTagSet(RecordFileWriter& writer, const vector<string>& tags);
 
// Hardware components
// For dependent devices with their own id/serial (controllers?), tag at the stream level
 
  // Device Type: device type, maybe the code name of the device/prototype
  constexpr const char* kDeviceType = "device_type";
  // Device version: device version name. Ex: "proto0", "EVT2"
  constexpr const char* kDeviceVersion = "device_version";
  // Device Serial: serial number of the main HW (in case of multi part HW)
  constexpr const char* kDeviceSerial = "device_serial";
  // Device ID: user code identification of the device
  constexpr const char* kDeviceId = "device_id";
  // Hardware configuration: description of the hardware setup
  constexpr const char* kHardwareConfiguration = "hardware_configuration";
 
  template <class T> inline // vrs::RecordFileWriter or vrs::Recordable
  void addDevice(T& writer, const string& type, const string& serialNumber, const string& version) {
    writer.setTag(kDeviceType, type);
    writer.setTag(kDeviceSerial, serialNumber);
    writer.setTag(kDeviceVersion, version);
  }
  template <class T> inline // vrs::RecordFileWriter or vrs::Recordable
  void addDeviceId(T& writer, const string& id) {
    writer.setTag(kDeviceId, id);
  }
 
// Software components
// For dependent devices with their own SW/FW (controllers?), tag at the stream level
 
  // OS fingerprint: Operating system build signature
  constexpr const char* kOsFingerprint = "os_fingerprint";
  // OS version: Operating system version
  constexpr const char* kOsBuildVersion = "os_build_version";
  // OS build number: Operating system build number
  constexpr const char* kOsBranch = "os_branch";
  // Name of the software that produced the file or stream.
  constexpr const char* kSoftwareName = "software_name";
  // SW compile time: when the recording software was compiled
  constexpr const char* kSoftwareCompileDate = "software_compile_date";
  // SW revision: source control revision of the software
  constexpr const char* kSoftwareRevision = "software_revision";
  // FW compile time: when the recording firmware was compiled
  constexpr const char* kFirmwareCompileDate = "firmware_compile_date";
  // FW revision: source control revision of the firmware
  constexpr const char* kFirmwareRevision = "firmware_revision";
 
  VRS_API void addOsFingerprint(RecordFileWriter& writer);
  inline
  void addSoftwareDetails(RecordFileWriter& writer, const string& compileDate, const string& rev) {
    writer.setTag(kSoftwareCompileDate, compileDate);
    writer.setTag(kSoftwareRevision, rev);
  }
  template <class T> // vrs::RecordFileWriter or vrs::Recordable
  inline void addFirmwareDetails(T& writer, const string& fwCompileDate, const string& fwRevision) {
    writer.setTag(kFirmwareCompileDate, fwCompileDate);
    writer.setTag(kFirmwareRevision, fwRevision);
  }
 
// For streams which may have multiple instances in the same recording
 
  // Device role: which "role" has this device in the system.
  // Ex: "top-right camera", "left controller"
  constexpr const char* kDeviceRole = "device_role"; // When relevant
 
// Key configuration/settings (when relevant, never required)
 
  // Intensity target used by dynamic exposure control. How to fill it:
  // * Do not fill it or fill it with -1 when unknown.
  // * Fill it with 0 when using fixed exposure settings.
  // * Fill it with the right intensity target when using dynamic exposure
  constexpr const char* kDynamicExposureTarget = "iot_dynamic_exposure_target";
 
// Stream semantic conventions
 
  constexpr const char* kImageSemantic = "image_semantic";
 
    constexpr const char* kImageSemanticCamera = "image_semantic_camera"; 
    constexpr const char* kImageSemanticDepth = "image_semantic_depth"; 
    constexpr const char* kImageSemanticObjectClassSegmentation =
        "image_semantic_object_class_segmentation"; 
    constexpr const char* kImageSemanticObjectIdSegmentation =
        "image_semantic_object_id_segmentation"; 
 
  constexpr const char* kRenderDepthImagesRangeMin = "render_depth_images_range_min";
  constexpr const char* kRenderDepthImagesRangeMax = "render_depth_images_range_max";
 
// Helper functions
  VRS_API string makeTagSet(const vector<string>& tags);
  VRS_API bool parseTagSet(const string& jsonTagSet, vector<string>& outVectorTagSet);
 
/*
 * Sample: Santa Cruz + controllers
 *
 * File tags:
 *  kProjectName = "Santa Cruz"
 *  kCaptureTimeEpoch = "1520364293"
 *  kSessionId = "5584bdc43"
 *  kCaptureType = "calibration"   <- other use case: "INSIDE_OUT_TRACKER_RECORDING"...
 *
 *  kDeviceType = "Santa Cruz"
 *  kDeviceVersion = "EVT3"             <- main device (HMD for Santa Cruz)
 *  kDeviceSerial = "0ba3602ffbee80b9"  <- of HMD
 *  kHardwareConfiguration = "hmd + 2 hand controllers"
 *
 *  kOsFingerprint = "oculus/vr_santa_cruz_proto1/proto1:7.1.1/N9F27L/863:userdev/dev-keys"
 *  kSoftwareCompileDate = "Sep 26 2017 19:06:45"
 *  kSoftwareRevision = "185ea53a5584bdc43640ba3602ccbee80b91d33e"
 *  kFirmwareCompileDate = "Sep 20 2017 15:26:25"
 *  kFirmwareRevision = "265ea53b5584bdc43640ba3602ffbee80b91d43a"
 *
 * Controller stream tags (for each stream)
 *  kDeviceType = "Santa Cruz Controller"
 *  kDeviceVersion = "EVT0"
 *  kDeviceSerial = "bee80b91d3"
 *  kDeviceId = "left controller"
 *  kFirmwareCompileDate = "Sep 20 2017 15:26:25"
 *  kFirmwareRevision = "265ea53b5584bdc43640ba3602ffbee80b91d43a"
 */
 
} // namespace tag_conventions
} // namespace vrs