torchdrivesim.utils
===================

.. py:module:: torchdrivesim.utils

.. autoapi-nested-parse::

   Miscellaneous utilities, including for geometric operations on tensors.



Classes
-------

.. autoapisummary::

   torchdrivesim.utils.Resolution


Functions
---------

.. autoapisummary::

   torchdrivesim.utils.isin
   torchdrivesim.utils.normalize_angle
   torchdrivesim.utils.rotation_matrix
   torchdrivesim.utils.rotate
   torchdrivesim.utils.relative
   torchdrivesim.utils.transform
   torchdrivesim.utils.is_inside_polygon
   torchdrivesim.utils.merge_dicts
   torchdrivesim.utils.assert_equal
   torchdrivesim.utils.line_circle_intersection


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

.. py:class:: Resolution

   Bases: :py:obj:`tuple`


   .. py:attribute:: width


   .. py:attribute:: height


.. py:function:: isin(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor

   Checks whether elements of tensor x are contained in tensor y.
   This function is built-in in torch >= 1.10
   and will be removed from here in the future.

   :param x: any tensor
   :param y: a one-dimensional tensor

   :returns: a boolean tensor with the same shape as x


.. py:function:: normalize_angle(angle)

   Normalize to <-pi, pi) range by shifting by a multiple of 2*pi.
   Works with floats, numpy arrays, and torch tensors.


.. py:function:: rotation_matrix(theta: torch.Tensor) -> torch.Tensor

   Counterclockwise rotation matrix in 2D.

   :param theta: tensor of shape Sx1 with rotation angle in radians

   :returns: Sx2x2 tensor with the rotation matrix.


.. py:function:: rotate(v: torch.Tensor, angle: torch.Tensor) -> torch.Tensor

   Rotate the vector counterclockwise (from x towards y).
   Works correctly in batch mode.

   :param v: tensor of shape Sx2 representing points
   :param angle: tensor of shape Sx1 representing rotation angle

   :returns: Sx2 tensor of rotated points


.. py:function:: relative(origin_xy: torch.Tensor, origin_psi: torch.Tensor, target_xy: torch.Tensor, target_psi: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]

   Computes position and orientation of the target relative to origin.
   Points are represented as Sx2 tensors of coordinates and Sx1 tensors of orientations in radians.


.. py:function:: transform(points: torch.Tensor, pose: torch.Tensor) -> torch.Tensor

   Given points relative to a pose, produce absolute positions of the points.
   There can be zero or more batch dimensions.

   :param points: BxNx2 tensor
   :param pose: Bx3 tensor of position (x,y) and orientation (yaw angle in radians)

   :returns: Bx2 tensor of absolute positions


.. py:function:: is_inside_polygon(point: torch.Tensor, polygon: torch.Tensor) -> torch.Tensor

   Checks whether a given point is inside a given convex polygon.
   B and P can be zero or more batch dimensions, the former being batch and the latter points.

   :param point: BxPx2 tensor of x-y coordinates
   :param polygon: BxNx2 tensor of points specifying a convex polygon in either clockwise or counter-clockwise fashion.

   :returns: boolean tensor of shape BxP indicating whether the point is inside the polygon


.. py:function:: merge_dicts(ds: List[Dict]) -> Dict

   Merges a sequence of dictionaries, giving preference to entries earlier in the sequence.


.. py:function:: assert_equal(x, y)

.. py:function:: line_circle_intersection(p1: torch.Tensor, p2: torch.Tensor, circle_center: torch.Tensor, radius: torch.Tensor) -> torch.Tensor

   Determine intersections between batched line segments and circles in 2D.

   :param p1: Start points of line segments [..., 2]
   :type p1: torch.Tensor
   :param p2: End points of line segments [..., 2]
   :type p2: torch.Tensor
   :param circle_center: Circle centers [..., 2]
   :type circle_center: torch.Tensor
   :param radius: Circle radii [..., 1]
   :type radius: torch.Tensor

   :returns: Boolean tensor indicating intersections [..., 1]
   :rtype: torch.Tensor