Create mjcPhysics ImageableAPI for visual, non physical visual entities.

PiperOrigin-RevId: 786366034
Change-Id: Ifb72d2daf8f5963bb7007dda1685da94b456ff41

include/mujoco/experimental/usd/mjcPhysics/imageableAPI.h

@@ -0,0 +1,184 @@
+// Copyright 2025 DeepMind Technologies Limited
+//
+// 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.
+
+#ifndef MJCPHYSICS_GENERATED_IMAGEABLEAPI_H
+#define MJCPHYSICS_GENERATED_IMAGEABLEAPI_H
+
+/// \file mjcPhysics/imageableAPI.h
+
+#include <mujoco/experimental/usd/mjcPhysics/api.h>
+#include <mujoco/experimental/usd/mjcPhysics/tokens.h>
+#include <pxr/base/gf/matrix4d.h>
+#include <pxr/base/gf/vec3d.h>
+#include <pxr/base/gf/vec3f.h>
+#include <pxr/base/tf/token.h>
+#include <pxr/base/tf/type.h>
+#include <pxr/base/vt/value.h>
+#include <pxr/pxr.h>
+#include <pxr/usd/usd/apiSchemaBase.h>
+#include <pxr/usd/usd/prim.h>
+#include <pxr/usd/usd/stage.h>
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+class SdfAssetPath;
+
+// -------------------------------------------------------------------------- //
+// MJCIMAGEABLEAPI                                                            //
+// -------------------------------------------------------------------------- //
+
+/// \class MjcPhysicsImageableAPI
+///
+/// API describing attributes for visual entities in MuJoCo.
+///
+class MjcPhysicsImageableAPI : public UsdAPISchemaBase {
+ public:
+  /// Compile time constant representing what kind of schema this class is.
+  ///
+  /// \sa UsdSchemaKind
+  static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI;
+
+  /// Construct a MjcPhysicsImageableAPI on UsdPrim \p prim .
+  /// Equivalent to MjcPhysicsImageableAPI::Get(prim.GetStage(), prim.GetPath())
+  /// for a \em valid \p prim, but will not immediately throw an error for
+  /// an invalid \p prim
+  explicit MjcPhysicsImageableAPI(const UsdPrim &prim = UsdPrim())
+      : UsdAPISchemaBase(prim) {}
+
+  /// Construct a MjcPhysicsImageableAPI on the prim held by \p schemaObj .
+  /// Should be preferred over MjcPhysicsImageableAPI(schemaObj.GetPrim()),
+  /// as it preserves SchemaBase state.
+  explicit MjcPhysicsImageableAPI(const UsdSchemaBase &schemaObj)
+      : UsdAPISchemaBase(schemaObj) {}
+
+  /// Destructor.
+  MJCPHYSICS_API
+  virtual ~MjcPhysicsImageableAPI();
+
+  /// Return a vector of names of all pre-declared attributes for this schema
+  /// class and all its ancestor classes.  Does not include attributes that
+  /// may be authored by custom/extended methods of the schemas involved.
+  MJCPHYSICS_API
+  static const TfTokenVector &GetSchemaAttributeNames(
+      bool includeInherited = true);
+
+  /// Return a MjcPhysicsImageableAPI holding the prim adhering to this
+  /// schema at \p path on \p stage.  If no prim exists at \p path on
+  /// \p stage, or if the prim at that path does not adhere to this schema,
+  /// return an invalid schema object.  This is shorthand for the following:
+  ///
+  /// \code
+  /// MjcPhysicsImageableAPI(stage->GetPrimAtPath(path));
+  /// \endcode
+  ///
+  MJCPHYSICS_API
+  static MjcPhysicsImageableAPI Get(const UsdStagePtr &stage,
+                                    const SdfPath &path);
+
+  /// Returns true if this <b>single-apply</b> API schema can be applied to
+  /// the given \p prim. If this schema can not be a applied to the prim,
+  /// this returns false and, if provided, populates \p whyNot with the
+  /// reason it can not be applied.
+  ///
+  /// Note that if CanApply returns false, that does not necessarily imply
+  /// that calling Apply will fail. Callers are expected to call CanApply
+  /// before calling Apply if they want to ensure that it is valid to
+  /// apply a schema.
+  ///
+  /// \sa UsdPrim::GetAppliedSchemas()
+  /// \sa UsdPrim::HasAPI()
+  /// \sa UsdPrim::CanApplyAPI()
+  /// \sa UsdPrim::ApplyAPI()
+  /// \sa UsdPrim::RemoveAPI()
+  ///
+  MJCPHYSICS_API
+  static bool CanApply(const UsdPrim &prim, std::string *whyNot = nullptr);
+
+  /// Applies this <b>single-apply</b> API schema to the given \p prim.
+  /// This information is stored by adding "MjcImageableAPI" to the
+  /// token-valued, listOp metadata \em apiSchemas on the prim.
+  ///
+  /// \return A valid MjcPhysicsImageableAPI object is returned upon success.
+  /// An invalid (or empty) MjcPhysicsImageableAPI object is returned upon
+  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
+  /// resulting in failure.
+  ///
+  /// \sa UsdPrim::GetAppliedSchemas()
+  /// \sa UsdPrim::HasAPI()
+  /// \sa UsdPrim::CanApplyAPI()
+  /// \sa UsdPrim::ApplyAPI()
+  /// \sa UsdPrim::RemoveAPI()
+  ///
+  MJCPHYSICS_API
+  static MjcPhysicsImageableAPI Apply(const UsdPrim &prim);
+
+ protected:
+  /// Returns the kind of schema this class belongs to.
+  ///
+  /// \sa UsdSchemaKind
+  MJCPHYSICS_API
+  UsdSchemaKind _GetSchemaKind() const override;
+
+ private:
+  // needs to invoke _GetStaticTfType.
+  friend class UsdSchemaRegistry;
+  MJCPHYSICS_API
+  static const TfType &_GetStaticTfType();
+
+  static bool _IsTypedSchema();
+
+  // override SchemaBase virtuals.
+  MJCPHYSICS_API
+  const TfType &_GetTfType() const override;
+
+ public:
+  // --------------------------------------------------------------------- //
+  // GROUP
+  // --------------------------------------------------------------------- //
+  /// Integer MuJoCo group to which the imageable belongs.
+  ///
+  /// | ||
+  /// | -- | -- |
+  /// | Declaration | `uniform int mjc:group = 0` |
+  /// | C++ Type | int |
+  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Int |
+  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
+  MJCPHYSICS_API
+  UsdAttribute GetGroupAttr() const;
+
+  /// See GetGroupAttr(), and also
+  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+  /// If specified, author \p defaultValue as the attribute's default,
+  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+  /// the default for \p writeSparsely is \c false.
+  MJCPHYSICS_API
+  UsdAttribute CreateGroupAttr(VtValue const &defaultValue = VtValue(),
+                               bool writeSparsely = false) const;
+
+ public:
+  // ===================================================================== //
+  // Feel free to add custom code below this line, it will be preserved by
+  // the code generator.
+  //
+  // Just remember to:
+  //  - Close the class declaration with };
+  //  - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
+  //  - Close the include guard with #endif
+  // ===================================================================== //
+  // --(BEGIN CUSTOM CODE)--
+};
+
+PXR_NAMESPACE_CLOSE_SCOPE
+
+#endif

include/mujoco/experimental/usd/mjcPhysics/tokens.h

@@ -408,8 +408,8 @@ struct MjcPhysicsTokensType {
   const TfToken mjcGear;
   /// \brief "mjc:group"
   ///
-  /// MjcPhysicsSiteAPI, MjcPhysicsCollisionAPI, MjcPhysicsActuator,
-  /// MjcPhysicsJointAPI
+  /// MjcPhysicsSiteAPI, MjcPhysicsImageableAPI, MjcPhysicsCollisionAPI,
+  /// MjcPhysicsActuator, MjcPhysicsJointAPI
   const TfToken mjcGroup;
   /// \brief "mjc:inertia"
   ///
@@ -697,6 +697,10 @@ struct MjcPhysicsTokensType {
   ///
   /// Schema identifier and family for MjcPhysicsCollisionAPI
   const TfToken MjcCollisionAPI;
+  /// \brief "MjcImageableAPI"
+  ///
+  /// Schema identifier and family for MjcPhysicsImageableAPI
+  const TfToken MjcImageableAPI;
   /// \brief "MjcJointAPI"
   ///
   /// Schema identifier and family for MjcPhysicsJointAPI