Adding the new operators available from the August OS update (#3)

## Summary

Update the sample codes and utilities corresponding to the latest PICO
OS update (5.14.0U)

## Details

- [x] Readme updated: latest ROM version
- [x] OpenXR header file updates, containing the latest ROM update
- [x] Add the newly-added operators as pipeline methods:
  1. SVD
  1. Norm
  1. HWC <-> CHW swaping

Author: EE-LiuYunhao

README.md

@@ -85,7 +85,7 @@ deploy your own algorithm packages.
 
 #### (A) To run the demo, you will need
 
-1. A PICO 4 Ultra device with the latest system update
+1. A PICO 4 Ultra device with the latest system update (OS version >= 5.14.0U)
 1. Android Studio, with Android NDK installed, suggested NDK version = 25
 1. Gradle and Android Gradle plugin (usually bundled with Android Studio install),
    suggested Gradle version = 8.7, Android Gradle Plugin version = 8.3.2

base/securemr_utils/pipeline.cpp

@@ -382,20 +382,20 @@ Pipeline& Pipeline::uv2Cam(const std::shared_ptr<PipelineTensor>& uv, const std:
                            const std::shared_ptr<PipelineTensor>& rightImg,
                            const std::shared_ptr<PipelineTensor>& result) {
   // Check for null pointers
-  CHECK_MSG(uv != nullptr, "uv2Cam uvPlaceholder1 is null");
-  CHECK_MSG(timestamp != nullptr, "uv2Cam timestampPlaceholder1 is null");
-  CHECK_MSG(cameraMatrix != nullptr, "uv2Cam cameraMatrixPlaceholder1 is null");
-  CHECK_MSG(leftImg != nullptr, "uv2Cam leftImagePlaceholder is null");
-  CHECK_MSG(rightImg != nullptr, "uv2Cam rightImagePlaceholder is null");
-  CHECK_MSG(result != nullptr, "uv2Cam pointXYZ is null");
+  CHECK_MSG(uv != nullptr, "uv2Cam uvPlaceholder1 is null")
+  CHECK_MSG(timestamp != nullptr, "uv2Cam timestampPlaceholder1 is null")
+  CHECK_MSG(cameraMatrix != nullptr, "uv2Cam cameraMatrixPlaceholder1 is null")
+  CHECK_MSG(leftImg != nullptr, "uv2Cam leftImagePlaceholder is null")
+  CHECK_MSG(rightImg != nullptr, "uv2Cam rightImagePlaceholder is null")
+  CHECK_MSG(result != nullptr, "uv2Cam pointXYZ is null")
 
   XrSecureMrOperatorPICO opHandle = XR_NULL_HANDLE;
   XrSecureMrOperatorUVTo3DPICO uvTo3DOperatorPico{XR_TYPE_SECURE_MR_OPERATOR_UV_TO_3D_PICO, nullptr};
   XrSecureMrOperatorCreateInfoPICO uvTo3DCreateInfoPico{
       XR_TYPE_SECURE_MR_OPERATOR_CREATE_INFO_PICO, nullptr,
       reinterpret_cast<XrSecureMrOperatorBaseHeaderPICO*>(&uvTo3DOperatorPico),
       XR_SECURE_MR_OPERATOR_TYPE_UV_TO_3D_IN_CAM_SPACE_PICO};
-  CHECK_XRCMD(xrCreateSecureMrOperatorPICO(m_handle, &uvTo3DCreateInfoPico, &opHandle));
+  CHECK_XRCMD(xrCreateSecureMrOperatorPICO(m_handle, &uvTo3DCreateInfoPico, &opHandle))
 
   CHECK_XRCMD(xrSetSecureMrOperatorOperandByNamePICO(m_handle, opHandle, (XrSecureMrPipelineTensorPICO)*uv, "uv"))
   CHECK_XRCMD(
@@ -587,6 +587,62 @@ Pipeline& Pipeline::sortMatByColumn(const std::shared_ptr<PipelineTensor>& srcMa
   return *this;
 }
 
+Pipeline& Pipeline::singularValueDecomposition(const std::shared_ptr<PipelineTensor>& src,
+                                               const std::shared_ptr<PipelineTensor>& result_w,
+                                               const std::shared_ptr<PipelineTensor>& result_u,
+                                               const std::shared_ptr<PipelineTensor>& result_vt) {
+  XrSecureMrOperatorPICO opHandle = XR_NULL_HANDLE;
+  XrSecureMrOperatorCreateInfoPICO operatorCreateInfo{
+      .type = XR_TYPE_SECURE_MR_OPERATOR_CREATE_INFO_PICO,
+      .operatorType = XR_SECURE_MR_OPERATOR_TYPE_SVD_PICO,
+  };
+  CHECK_XRCMD(xrCreateSecureMrOperatorPICO(m_handle, &operatorCreateInfo, &opHandle))
+  xrSetSecureMrOperatorOperandByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*src), "src");
+  if (result_w != nullptr) {
+    xrSetSecureMrOperatorResultByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*result_w),
+                                          "w");
+  }
+  if (result_u != nullptr) {
+    xrSetSecureMrOperatorResultByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*result_u),
+                                          "u");
+  }
+  if (result_vt != nullptr) {
+    xrSetSecureMrOperatorResultByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*result_vt),
+                                          "vt");
+  }
+  return *this;
+}
+
+Pipeline& Pipeline::norm(const std::shared_ptr<PipelineTensor>& src,
+                         const std::shared_ptr<PipelineTensor>& result_norm) {
+  XrSecureMrOperatorPICO opHandle = XR_NULL_HANDLE;
+  XrSecureMrOperatorCreateInfoPICO operatorCreateInfo{
+      .type = XR_TYPE_SECURE_MR_OPERATOR_CREATE_INFO_PICO,
+      .operatorType = XR_SECURE_MR_OPERATOR_TYPE_NORM_PICO,
+  };
+  CHECK_XRCMD(xrCreateSecureMrOperatorPICO(m_handle, &operatorCreateInfo, &opHandle))
+  xrSetSecureMrOperatorOperandByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*src),
+                                         "operand0");
+  xrSetSecureMrOperatorResultByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*result_norm),
+                                        "result0");
+  return *this;
+}
+
+Pipeline& Pipeline::convertHWC_CHW(const std::shared_ptr<PipelineTensor>& src,
+                                   const std::shared_ptr<PipelineTensor>& result) {
+  XrSecureMrOperatorPICO opHandle = XR_NULL_HANDLE;
+  XrSecureMrOperatorCreateInfoPICO operatorCreateInfo{
+      .type = XR_TYPE_SECURE_MR_OPERATOR_CREATE_INFO_PICO,
+      .operatorType = XR_SECURE_MR_OPERATOR_TYPE_SWAP_HWC_CHW_PICO,
+  };
+  CHECK_XRCMD(xrCreateSecureMrOperatorPICO(m_handle, &operatorCreateInfo, &opHandle))
+  xrSetSecureMrOperatorOperandByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*src),
+                                         "operand0");
+  xrSetSecureMrOperatorResultByNamePICO(m_handle, opHandle, static_cast<XrSecureMrPipelineTensorPICO>(*result),
+                                        "result0");
+  return *this;
+}
+
 Pipeline& Pipeline::inversion(const std::shared_ptr<PipelineTensor>& srcMat,
                               const std::shared_ptr<PipelineTensor>& result_inverted) {
   XrSecureMrOperatorPICO opHandle = XR_NULL_HANDLE;

base/securemr_utils/pipeline.h

@@ -430,6 +430,58 @@ class Pipeline final : public XrHandleAdapter<XrSecureMrPipelinePICO>, public st
   Pipeline& sortMatByColumn(const std::shared_ptr<PipelineTensor>& srcMat,
                             const std::shared_ptr<PipelineTensor>& result_sortedMat,
                             const std::shared_ptr<PipelineTensor>& result_indicesPerColumn);
+
+  /**
+   *
+   * Perform the singularity value decomposition (SVD) of a matrix
+   *
+   * @param src required, the matrix to be decomposed, must be a multi-dimensional tensor with 2 dimensions, therefore
+   *    usage flag <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required銆?The shapes along the 2 dimensions
+   *    must be same, i.e., must be a square matrix.
+   * @param result_w An optional result, the w result of the decomposition, usage flag
+   *    <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required, and the tensor must have only two dimensions.
+   * @param result_u An optional result, the u result of the decomposition, usage flag
+   *    <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required, and the tensor must have only two dimensions.
+   * @param result_vt An optional result, the vt result of the decomposition, usage flag
+   *    <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required, and the tensor must have only two dimensions.
+   * @return Reference to this pipeline
+   */
+  Pipeline& singularValueDecomposition(const std::shared_ptr<PipelineTensor>& src,
+                                       const std::shared_ptr<PipelineTensor>& result_w,
+                                       const std::shared_ptr<PipelineTensor>& result_u,
+                                       const std::shared_ptr<PipelineTensor>& result_vt);
+
+  /**
+   * Compute the norm of a tensor (by default, L2 norm)
+   *
+   * @param src required, the tensor whose norm will be computed銆?It can be any tensor but the glTF tensor, i.e.,
+   *    the src tensor must not have <code>XR_SECURE_MR_TENSOR_TYPE_GLTF_PICO</code> usage flag.
+   * @param result_norm required, the tensor to store the norm of <code>src</code>. It must be of only 1 channel, and
+   *    contains only one element. Hence, the tensor can only be: <ol>
+   *    <li>A scalar array tensor with usage flag <code>XR_SECURE_MR_TENSOR_TYPE_SCALAR_PICO</code>, of size 1, or</li>
+   *    <li>A scalar array tensor with usage flag <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code>, with
+   *        dimensions = <code>(1, 1)</code></li>
+   *    </ol>
+   * @return Reference to this pipeline
+   */
+  Pipeline& norm(const std::shared_ptr<PipelineTensor>& src, const std::shared_ptr<PipelineTensor>& result_norm);
+
+  /**
+   * Convert the HWC and CHW tensors. An HWC tensor is a 2-dimension tensor, with dimensions = <code>(H, W)</code> and
+   * <code>C</code> channels. A CHW tensor is a 3-dimension tensor, with dimensions = <code>(C, H, W)</code> and
+   * only 1 channel. If the input is an HWC tensor, the method converts it to a CHW one; otherwise, converting the
+   * CHW input to HWC output.
+   *
+   * @param src required, the input tensor to be converted. Must either be a CHW or an HWC tensor, usage flag
+   *    <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required, and number of dimensions must be either 2 or 3.
+   * @param result required, the output of the conversion. If the <code>src</code> is a CHW tensor, the
+   * <code>result</code> must be an HWC tensor. If the <code>src</code> is an HWC tensor, the <code>result</code> must
+   * be a CHW tensor. usage flag <code>XR_SECURE_MR_TENSOR_TYPE_MAT_PICO</code> required, and number of dimensions must
+   * be either 2 or 3. The last 2 dimensions of <code>result</code> must be the same as those of <code>src</code>
+   * @return Reference to this pipeline
+   */
+  Pipeline& convertHWC_CHW(const std::shared_ptr<PipelineTensor>& src, const std::shared_ptr<PipelineTensor>& result);
+
   /**
    * Add to the pipeline an operator to conduct matrix inversion
    * Encapsulating operator of type <code>XR_SECURE_MR_OPERATOR_TYPE_INVERSION_PICO</code>