======
Sensor
======

.. py:class:: BackgroundMode

   .. py:attribute:: NONE
      :annotation: = 0

      No backround.

   .. py:attribute:: GRADIENT
      :annotation: = 1

      Use the specified background.

   .. py:attribute:: ENVIRONMENT
      :annotation: = 2

      Use the environment as background.

Sensor
------

.. py:class:: Sensor


   .. py:method:: id
      :property:

      The id of the sensor.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the sensor.

      :type: str
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: group
      :property:

      The group of the sensor.

      :type: SensorGroup
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: isometric
      :property:

      Wether the sensor uses isometric projection.

      :type: bool
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: width
      :property:

      The sensor width in millimeters.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative width or a width equal to 0.

   .. py:method:: height
      :property:

      The sensor height in millimeters.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative height or a height equal to 0.

   .. py:method:: aspect
      :property:

      The sensor aspect ratio.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative ratio or a ratio equal to 0.

   .. py:method:: dynamic_aspect
      :property:

      Wether the aspect ratio is dynamic (i.e. it corresponds to the viewport aspect ratio).

      :type: bool
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: postprocess
      :property:

      The postprocess of the sensor or :py:obj:`None` if there is no postprocess assigned.

      :type: Postprocess or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: overlay
      :property:

      The overlay of the sensor or :py:obj:`None` if there is no overlay assigned.

      :type: Overlay or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: background_mode
      :property:

      The background mode of the sensor.

      :type: BackgroundMode
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: background
      :property:

      The background of the sensor or :py:obj:`None` if there is no background assigned. It only has effect if :py:obj:`backgroundMode` is :py:obj:`GRADIENT`.

      :type: Background or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.


   .. py:method:: duplicate()

      Duplicate this sensor.


      :returns: The duplicated sensor.
      :rtype: Sensor

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: remove(force = False)

      Delete this sensor

      .. note::
         By default, only not used sensor can be deleted (:py:obj:`InUseError` is raised otherwise), use ``force`` to force deletion of used sensors.

      :param force: Force the deletion of the sensor even if it is in use.
      :type force: bool


      :raises InUseError: If ``force`` is :py:obj:`False` and the sensor is used.
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.