mani_skill.utils.structs.pose
=============================

.. py:module:: mani_skill.utils.structs.pose


Classes
-------

.. autoapisummary::

   mani_skill.utils.structs.pose.Pose


Functions
---------

.. autoapisummary::

   mani_skill.utils.structs.pose.add_batch_dim
   mani_skill.utils.structs.pose.to_batched_tensor
   mani_skill.utils.structs.pose.to_sapien_pose
   mani_skill.utils.structs.pose.vectorize_pose


Module Contents
---------------

.. py:class:: Pose

   Wrapper around sapien.Pose that supports managing a batch of Poses and flexible creation of them from a variety of
   sources (list, numpy array, sapien.Pose). This pose object will also return information with a batch dimension, even if it is just holding
   a single position and quaternion.

   As a result pose.p and pose.q will return shapes (N, 3) and (N, 4) respectively for N poses being stored. pose.raw_pose stores all the pose data as a single
   2D array of shape (N, 7).

   All sapien.Pose API are re-implemented in batch mode here to support GPU simulation. E.g. pose multiplication and inverse with ``pose_1.inv() * pose_2``,
   or creating transformation matrices with ``pose_1.to_transformation_matrix()`` are suppported they same way they are in sapien.Pose.

   Pose Creation
   -------------

   To create a batched pose with a given position ``p`` and/or quaternion ``q``, you run:

   .. code-block:: python

       pose = Pose.create_from_pq(p=p, q=q)

   ``p`` and ``q`` can be a torch tensor, numpy array, and/or list, or None.

   If ``p`` or ``q`` have only 1 value/not batched, then we automatically repeat the value to the batch size of the other given value.
   For example, if ``p`` has a batch dimension of size > 1, and ``q`` has a batch dimension of size 1 or is a flat list, then the
   code automatically repeats the ``q`` value to the batch size of ``p``. Likewise in the reverse direction the same repeating occurs.

   If ``p`` and ``q`` have the same batch size, they are stored as so.

   If ``p`` and ``q`` have no batch dimensions, one is automatically added (e.g. ``p`` having shape (3,) now becomes (1, 3))

   If ``p`` is None, it is auto filled with zeros.

   If ``q`` is None, it is auto filled with the [1, 0, 0, 0] quaternion.

   If you have a sapien.Pose, another Pose object, or a raw pose tensor of shape (N, 7) or (7,) called ``x``, you can create this Pose object with:

   .. code-block:: python

       pose = Pose.create(x)

   If you want a sapien.Pose object instead of this batched Pose, you can do ``pose.sp`` to get the sapien.Pose version (which is not batched). Note that
   this is only permitted if this Pose has a batch size of 1.

   Pose Indexing
   -------------

   You can index into a Pose object like numpy/torch arrays to get a new Pose object with the indexed data.

   For example if ``pose`` has a batch size of 4, then ``pose[0]`` will be a Pose object with batch size of 1, and
   ``pose[1:3]`` will be a Pose object with batch size of 2.



   .. py:method:: __getitem__(i)


   .. py:method:: __len__()


   .. py:method:: __mul__(arg0)

      Multiply two poses. Supports multiplying singular poses like sapien.Pose or Pose object with batch size of 1 with Pose objects with batch size > 1.



   .. py:method:: create(pose, device = None)
      :classmethod:


      Creates a Pose object from a given ``pose``, which can be a torch tensor, sapien.Pose, list of sapien.Pose, or Pose



   .. py:method:: create_from_pq(p = None, q = None, device = None)
      :classmethod:


      Creates a Pose object from a given position ``p`` and/or quaternion ``q``



   .. py:method:: get_p()

      Returns self.p, the position



   .. py:method:: get_q()

      Returns self.q, the quaternion



   .. py:method:: inv()

      Returns the inverse of this pose



   .. py:method:: set_p(p)

      Sets the position of this pose



   .. py:method:: set_q(q)

      Sets the quaternion of this pose



   .. py:method:: to(device)

      Move the Pose object to a different device



   .. py:method:: to_transformation_matrix()

      Returns the (N, 4, 4) shaped transformation matrix equivalent to this pose



   .. py:property:: device
      :type: mani_skill.utils.structs.types.Device


      Torch Device the Pose object is on


   .. py:property:: p

      The position of this pose


   .. py:property:: q

      The quaternion of this pose


   .. py:attribute:: raw_pose
      :type:  torch.Tensor


   .. py:property:: shape
      :type: torch.Size


      Shape of the Pose object


   .. py:property:: sp

      Returns the equivalent sapien pose. Note that this is only permitted if this Pose has a batch size of 1.


.. py:function:: add_batch_dim(x)

.. py:function:: to_batched_tensor(x, device = None)

.. py:function:: to_sapien_pose(pose)

   Maps several formats to a sapien Pose


.. py:function:: vectorize_pose(pose, device = None)

   Maps several formats of Pose representation to the appropriate tensor representation