Skip to content

README.md

Latest commit

 

History

History
192 lines (159 loc) · 7.74 KB

README.md

File metadata and controls

192 lines (159 loc) · 7.74 KB

Object Detection

This example performs object detection using a Hailo-8, Hailo-8L, or Hailo-10H device. It receives a HEF and images/video/camera as input, and returns the image\video with annotations of detected objects and bounding boxes.

output example

Requirements

  • HailoRT

    • For Hailo-8: HailoRT==4.23.0
    • For Hailo-10: HailoRT==5.3.0

  • Linux Dependencies

    • OpenCV >= 4.5.4 
      sudo apt-get install -y libopencv-dev python3-opencv
    • CMake >= 3.16
    • Gtk
    • g++-9 
      sudo apt-get install gcc-9 g++-9

  • Windows Dependencies

    • OpenCV >= 4.5.4 
      vcpkg install opencv
    • CMake >= 3.16
    • Visual Studio with MSVC C++ build tools

Supported Models

This example expects the HEF to contain HailoRT-Postprocess.

Because of that, this example only supports detections models that allow HailoRT-Postprocess:

  • YOLOv5, YOLOv6, YOLOv7, YOLOv8, YOLOv10, YOLOv11
  • YOLOX
  • SSD
  • CenterNet

Usage

  1. Make sure you have installed all of the requirements.

  2. Clone the repository:

    git clone https://github.com/hailo-ai/hailo-apps.git
cd hailo-apps/hailo_apps/cpp/object_detection

  3. Compile the project on the development machine

    • Linux 
      ./build.sh
    • Windows 
      cmake -S. -Bbuild -DCMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS=True
cmake --build build --config Release

    This creates the directory hierarchy build/Release and compile an executable file called object_detection

  4. Run the example:

    • Linux 
      ./build/Release/object_detection --net <hef_path> --input <image_or_video_or_camera_path>
    • Windows 
      .\build\Release\object_detection.exe --net <hef_path> --input <image_or_video_or_camera_path>

The output results will be saved under a folder named output, or in the directory specified by --output-dir.

Arguments

  • -n, --net:
    • A model name (e.g., yolov8n) → the script will automatically download and resolve the correct HEF for your device.
    • A file path to a local HEF → the script will use the specified network directly.
  • -i, --input:
    • An input source such as an image (bus.jpg), a video (video.mp4), a directory of images, or usb to auto-select the first available USB camera.
      • On Linux, you can also use /dev/vidoeX (e.g., /dev/video0) to select a specific camera.
      • On Windows, you can also use a camera index (0, 1, 2, ...) to select a specific camera.
      • On Raspberry Pi, you can also use rpi to enable the Raspberry Pi camera.
    • A predefined input name from resources_config.yaml (e.g., bus, street).
      • If you choose a predefined name, the input will be automatically downloaded if it doesn't already exist.
      • Use --list-inputs to display all available predefined inputs.
  • -b, --batch-size: [optional] Number of images in one batch. Defaults to 1.
  • -s, --save_stream_output: [optional] Save the output of the inference from a stream.
  • --no-display: [optional] Run without opening a display window.
  • -o, --output-dir: [optional] Directory where output images/videos will be saved.
  • --camera-resolution: [optional][Camera only] Input resolution: sd (640x480), hd (1280x720), or fhd (1920x1080).
  • --output-resolution: [optional] Set output size using sd|hd|fhd, or pass custom width/height (e.g., --output-resolution 1920 1080).
  • -f, --framerate: [optional][Camera only] Override the camera input framerate.
  • --list-models: [optional] Print all supported networks for this application from the shared resources_config.yaml, then exit.
  • --list-inputs: [optional] Print the available predefined input resources (images/videos) from the shared resources_config.yaml, then exit.

Example

  • List supported networks:

    ./build/x86_64/object_detection --list-nets

  • List available input resources:

    ./build/x86_64/object_detection --list-inputs

  • For a video:

    ./build/x86_64/object_detection --net yolov8n.hef --input full_mov_slow.mp4 --batch-size 16

    Output video is saved as processed_video.mp4

  • For a single image:

    ./build/x86_64/object_detection -n yolov8n.hef -i bus.jpg

    Output image is saved as processed_image_0.jpg

  • For a directory of images:

    ./build/x86_64/object_detection -n yolov8n.hef -i images -b 4

    Each image is saved as processed_image_i.jpg

  • For camera, enabling saving the output:

    ./build/x86_64/object_detection --net yolov8n.hef --input /dev/video0 --batch-size 2 -s

    Output video is saved as processed_video.mp4

Visualization Configuration

TThe application supports a simple configuration for controlling how detections are displayed. You can adjust these values in the configuration file to filter low-confidence detections and limit the number of boxes drawn per frame.

Example Configuration:

"visualization_params": {
    "score_thres": 0.42,
    "max_boxes_to_draw": 30,
}

Parameter Descriptions:

  • score_thres: Minimum confidence score required to display a detected object.
  • max_boxes_to_draw: Maximum number of detected objects to display per frame.

Notes

  • The script assumes that the image is in one of the following formats: .jpg, .jpeg, .png or .bmp
  • When using camera as input:
    • To exit gracefully from openCV window, press 'q'.
    • Camera path is usually found under /dev/video0.
    • Ensure you have the permissions for the camera. You may need to run, for example: 
      sudo chmod 777 /dev/video0
    • In case OpenCV is defaulting to GStreamer for video capture, warnings might occur. To solve, force OpenCV to use V4L2 instead of GStreamer by setting these environment variables: 
        export OPENCV_VIDEOIO_PRIORITY_GSTREAMER=0
  export OPENCV_VIDEOIO_PRIORITY_V4L2=100
  • Using multiple models on same device:
    • If you need to run multiple models on the same virtual device (vdevice), use the AsyncModelInfer constructor that accepts two arguments. Initialize each model using the same group_id.
    • Example: 
         std::string group_id = "<group_id>";
   AsyncModelInfer model1("<hef1_path>", group_id);
   AsyncModelInfer model2("<hef2_path>", group_id);
    • By assigning the same group_id to models from different HEF files, you enable the runtime to treat them as part of the same group, allowing them to share resources and run more efficiently on the same hardware.

Disclaimer

This code example is provided by Hailo solely on an “AS IS” basis and “with all faults”. No responsibility or liability is accepted or shall be imposed upon Hailo regarding the accuracy, merchantability, completeness or suitability of the code example. Hailo shall not have any liability or responsibility for errors or omissions in, or any business decisions made by you in reliance on this code example or any part of it. If an error occurs when running this example, please open a ticket in the "Issues" tab.

This example was tested on specific versions and we can only guarantee the expected results using the exact version mentioned above on the exact environment. The example might work for other versions, other environment or other HEF file, but there is no guarantee that it will.