herosdevices.hardware.dummy.cameras
===================================

.. py:module:: herosdevices.hardware.dummy.cameras

.. autoapi-nested-parse::

   Dummy camera devices for use in testing. Do not use in production.





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

.. py:class:: ImageGeneratorDummy

   Act like a real camera, no one will notice.


   .. py:attribute:: width
      :value: 800



   .. py:attribute:: height
      :value: 600



   .. py:attribute:: frame_count
      :value: 1



   .. py:method:: set_shape(width: int = 800, height: int = 600) -> None

      Set the image shape.



   .. py:method:: generate_gaussian_image(w: int, h: int, amplitude: float = 65535, noise_level: float = 0.05) -> numpy.typing.NDArray[numpy.unit16]
      :staticmethod:


      Generate a 2D Gaussian image with added random noise.

      The Gaussian is centered in the image with a fixed standard deviation,
      scaled to the specified amplitude. Additive Gaussian noise is applied
      and the result is clipped to the valid `uint16` range.

      :param w: Width of the image.
      :param h: Height of the image.
      :param amplitude: Peak value of the Gaussian. Defaults to 65535.
      :param noise_level: Standard deviation of noise relative to
                          the amplitude (e.g., 0.05 means ±5% noise). Defaults to 0.05.

      :returns: A (h, w) image array of dtype `np.uint16`.
      :rtype: np.ndarray



   .. py:method:: arm() -> None

      Arm the dummy device.



   .. py:method:: trigger() -> None

      Append an image to the buffer.



   .. py:method:: get_image() -> numpy.ndarray

      Get the last image from the buffer.



   .. py:method:: clear_buffer() -> None

      Clear the image buffer.



   .. py:method:: abort() -> None

      Abort the acquisition.



.. py:class:: CameraDummy

   Bases: :py:obj:`herosdevices.core.templates.CameraTemplate`


   A dummy camera.


   .. py:attribute:: default_config_dict
      :type:  dict


   .. py:attribute:: get_camera


   .. py:attribute:: acquisition_running
      :type:  bool
      :value: False



   .. py:attribute:: payload_metadata
      :type:  dict


   .. py:attribute:: keep_device_open
      :value: True



   .. py:attribute:: default_config
      :type:  str


   .. py:method:: get_device() -> collections.abc.Iterator[None]

      Yield a device handle.

      .. code-block:: python

          # use the device in a with statement
          with self.get_device() as camera:
              camera.do_something()



   .. py:method:: open() -> Any

      Open the device handler and assign it to `self._device`.



   .. py:method:: teardown() -> None

      Release the device handler and potentially de-initialize the API.



   .. py:method:: start() -> bool

      Fire a software trigger.

      :returns: True if successful



   .. py:method:: stop() -> bool

      Abort the exposure and release queued buffers.

      :returns: True if successful



   .. py:method:: reset() -> None

      Reset the device by aborting any ongoing exposure, closing and re-opening the handler.



   .. py:method:: get_status() -> dict

      Get a dict with the current device status.

      :returns: A dict with the device status



   .. py:property:: config_dict
      :type: dict


      Get a copy of the configuration dict.

      :returns: Copy of the configuration dict


   .. py:method:: update_configuration(new_config_dict: dict, merge: bool = True) -> None

      Update the configuration dict with new configuration.

      Each dict key corresponds a (new) configuration name.
      Each value is a dict with config property -> config value.

      :param new_config_dict: A dict of configurations where the keys are the configuration names
      :param merge: If ``True``, the new dict is recursively merged with the current set config dict. If ``False`` the
                    old configurations with the provided names (keys) are overwritten.



   .. py:method:: get_configuration() -> dict

      Get the currently active configuration.

      :returns: The currently active configuration.



   .. py:method:: configure(config: str = '', metadata: dict | None = None) -> bool

      Configure the device with the known configuration `config`.

      To add a configuration to the device, use :meth:`update_configuration`.

      :param config: Key (name) of the configuration
      :param metadata: Metadata that is merged into the current payload metadata dict which is send with every emitted
                       :code:`acquisition_data` event.



   .. py:attribute:: set_configuration


   .. py:method:: update_payload_metadata(metadata: dict, merge: bool = True) -> None

      Update metadata dict send with every emitted frame by the :code:`acquisition_data` event method.

      :param metadata: Metadata that is merged into the current payload metadata dict which is send with every emitted
                       :code:`acquisition_data` event.
      :param merge: If ``True``, the new dict is merged with the current set metadata dict. If ``False`` the old
                    metadata is overwritten by the given dict.



   .. py:method:: arm(metadata: dict | None = None, kill_running: bool = False) -> bool

      Arm the device with the currently active configuration.

      :param metadata: Metadata that is merged into the current payload metadata dict which is send with every emitted
                       :code:`acquisition_data` event.
      :param kill_running: If ``True`` any running acquisition will be stopped. If ``False`` and an acquisition is
      :param already running:
      :param an error will be raised.:

      :returns: True if arming was successful else False



   .. py:method:: acquisition_data(frame: numpy.ndarray, metadata: dict | None = None) -> tuple

      Event to emit new frames.

      .. note::
          The dtype of the frame is not changed here.

      :param frame: The frame payload data (for example an image or an scope trace)
      :param metadata: The metadata which is passed along the payload. This argument takes precedence over the
                       :code:`payload_metadata` attribute (for example set by the :code:`update_payload_metadata` method)
                       while merging the two dicts.

      :returns: A tuple of image and metadata(-dict)



   .. py:method:: acquisition_started(metadata: dict | None = None) -> dict

      Event emitted when the acquisition thread starts.

      :returns: A dict with acquisition metadata



   .. py:method:: acquisition_stopped(metadata: dict | None = None) -> dict

      Event emitted when the acquisition thread stops.

      :returns: A dict with acquisition metadata



