timor.task.Obstacle
===================

.. py:module:: timor.task.Obstacle


Classes
-------

.. autoapisummary::

   timor.task.Obstacle.Obstacle


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

.. py:class:: Obstacle(ID, collision, visual = None, name = None)


   .. autoapi-inheritance-diagram:: timor.task.Obstacle.Obstacle
      :parts: 1
      :private-bases:


   A wrapper class to integrate hppfcl obstacles in custom Environments.

   Generate an obstacle:

   :param ID: Unique identifier
   :param collision: The collision geometry of the object
   :param visual: The visual geometry of the object. Defaults to the collision geometry.
   :param name: Optional display name


   .. py:method:: __copy__()
      :abstractmethod:


      Not supported!



   .. py:method:: __eq__(other)

      Compare two obstacles by their ID, name, and geometry



   .. py:method:: __getstate__()

      Return objects which will be pickled and saved.



   .. py:method:: __hash__()

      The ID is sufficient to hash an obstacle



   .. py:method:: __setstate__(state)

      Take object from parameter and use it to retrieve class state.



   .. py:method:: _deduce_package_dir(filepath, content)
      :staticmethod:


      Logic for deducing the package directory if the JSONable object is loaded from a file.

      :param filepath: The path to the file.
      :param content: The content of the file parsed into a dictionary.
      :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py.



   .. py:attribute:: _id
      :value: ''



   .. py:attribute:: _visual
      :value: None



   .. py:method:: collides(other)

      Check if this obstacle collides with another obstacle.

      Be careful, this is probably slow due to the initialisation of a new request/result pair and should only be used
      for debugging. Use the collision checking of the environment / robot instead.

      :param other: The other obstacle
      :return: True if the obstacles collide, False otherwise



   .. py:attribute:: collision


   .. py:property:: display_name
      :type: str


      Used for visualization and debugging. If a diplay name is explicitly given, use it, if not, it's the ID.



   .. py:method:: from_hppfcl(ID, fcl, visual_representation = None, name = None)
      :classmethod:


      Create a Timor obstacle from a hppfcl obstacle

      A helper function that transforms a generic hppfcl collision object to an Obstacle with the according geometry.
        (Which allows plotting, composing a task of multiple obstacles, ...)

      :param ID: The id that shall be given to the Obstacle.
      :param fcl: The hppfcl collision object
      :param visual_representation: An optional, differing visual representation of the collision object.
      :param name: The obstacle display name
      :return: An instance of the according Obstacle class, based on the kind of collision object handed over.



   .. py:method:: from_json_data(d, *args, **kwargs)
      :classmethod:


      Takes a json geometry specification and returns the according Obstacle.

      :param d: The serialized obstacle information, containing:

          * ID: The obstacle unique ID
          * collision: A Geometry used for collision detection
          * visual: A Geometry for visualization of this Obstacle - defaults to collision if not given
          * name: The obstacle display name
      :return: The obstacle class instance that matches the specification



   .. py:method:: from_json_file(filepath, *args, **kwargs)
      :classmethod:


      Factory method to load a class instance from a json file.

      :param filepath: The path to the json file.
      :param args: Additional arguments to pass to the from_json_data factory method of the specific class.
      :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class.



   .. py:method:: from_json_string(s, *args, **kwargs)
      :classmethod:


      Create from a json string.



   .. py:property:: id
      :type: str


      Returns the ID of the obstacle



   .. py:attribute:: mesh_material


   .. py:attribute:: mesh_material_vertex_color


   .. py:attribute:: name
      :type:  Optional[str]
      :value: None



   .. py:method:: to_json_data()

      Interface to write a list of geometry-dictionaries that is serializable to json.

      :return: A dictionary of the format described in the task documentation



   .. py:method:: to_json_file(save_at, *args, **kwargs)

      Writes the instance to a json file.

      :param save_at: File location or folder to write the class to.



   .. py:method:: to_json_string()

      Return the json string representation.



   .. py:property:: visual
      :type: timor.Geometry.Geometry


      Defaults to collision



   .. py:method:: visualize(viz, material = None)

      A custom visualization should be implemented by children.

      :param viz: MeshcatVisualizer to add this obstacle to.
      :param material: Material to use for this obstacle; default: light red / mesh color if provided