zensvi.cv.ObjectDetector
========================

.. py:class:: zensvi.cv.ObjectDetector(config_path: str = os.path.join(current_dir, 'config/GroundingDINO_SwinT_OGC.py'), weights_path: str = str(models_dir / 'groundingdino' / 'groundingdino_swint_ogc.pth'), text_prompt: str = 'tree . building .', box_threshold: float = 0.35, text_threshold: float = 0.25, verbosity: int = 1, device=None)

   Class for detecting objects in images using GroundingDINO model.

   This class provides functionality to detect objects in images using the GroundingDINO model.
   It can process single images or directories of images, annotate them with bounding boxes and labels,
   and save detection summaries in various formats.

   :param config_path: Path to GroundingDINO config file. Defaults to included config.
   :type config_path: str, optional
   :param weights_path: Path to model weights file. Defaults to included weights.
   :type weights_path: str, optional
   :param text_prompt: Text prompt for object detection. Defaults to "tree . building .".
   :type text_prompt: str, optional
   :param box_threshold: Confidence threshold for box detection. Defaults to 0.35.
   :type box_threshold: float, optional
   :param text_threshold: Confidence threshold for text. Defaults to 0.25.
   :type text_threshold: float, optional
   :param verbosity: Level of verbosity for progress bars. Defaults to 1.
                     0 = no progress bars, 1 = outer loops only, 2 = all loops.
   :type verbosity: int, optional

   .. attribute:: model

      The loaded GroundingDINO model.

   .. attribute:: text_prompt

      Text prompt used for detection.

      :type: str

   .. attribute:: box_threshold

      Box confidence threshold.

      :type: float

   .. attribute:: text_threshold

      Text confidence threshold.

      :type: float

   .. attribute:: model_lock

      Lock for thread-safe model inference.

      :type: threading.Lock

   .. attribute:: verbosity

      Level of verbosity for progress reporting.

      :type: int

   .. attribute:: device

      The device used for inference. Options: "cpu", "cuda", or "mps".


   .. py:method:: detect_objects(dir_input: Union[str, pathlib.Path], dir_image_output: Union[str, pathlib.Path, None] = None, dir_summary_output: Union[str, pathlib.Path, None] = None, save_format: str = 'json', max_workers: int = 4, verbosity: int = None, group_by_object: bool = False)

      Detect objects in images and save results.

      Processes images from input directory/file, saves annotated images and detection summaries.
      Only processes unprocessed images (those without existing annotated versions).

      :param dir_input: Input image file or directory path.
      :type dir_input: Union[str, Path]
      :param dir_image_output: Directory to save annotated images.
                               If None, no images are saved, only summary data (dir_summary_output must be provided).
      :type dir_image_output: Union[str, Path, None], optional
      :param dir_summary_output: Directory to save detection summaries.
                                 If None, no summary data is saved, only annotated images (dir_image_output must be provided).
      :type dir_summary_output: Union[str, Path, None], optional
      :param save_format: Format for saving summaries ("json", "csv", or "json csv").
                          Defaults to "json".
      :type save_format: str, optional
      :param max_workers: Maximum number of parallel workers. Defaults to 4.
      :type max_workers: int, optional
      :param verbosity: Level of verbosity for progress bars.
                        If None, uses the instance's verbosity level.
                        0 = no progress bars, 1 = outer loops only, 2 = all loops.
      :type verbosity: int, optional
      :param group_by_object: If True, groups detections by object type per image and
                              counts occurrences. If False, returns detailed detection data. Defaults to False.
      :type group_by_object: bool, optional

      :raises ValueError: If dir_input is neither a file nor directory.
      :raises ValueError: If neither dir_image_output nor dir_summary_output is provided.