ultralytics 8.3.14__py3-none-any.whl → 8.3.16__py3-none-any.whl

ultralytics/solutions/object_counter.py

@@ -1,18 +1,40 @@
 # Ultralytics YOLO 🚀, AGPL-3.0 license
 
-from shapely.geometry import LineString, Point
-
-from ultralytics.solutions.solutions import BaseSolution  # Import a parent class
+from ultralytics.solutions.solutions import BaseSolution
 from ultralytics.utils.plotting import Annotator, colors
 
 
 class ObjectCounter(BaseSolution):
-    """A class to manage the counting of objects in a real-time video stream based on their tracks."""
+    """
+    A class to manage the counting of objects in a real-time video stream based on their tracks.
+
+    This class extends the BaseSolution class and provides functionality for counting objects moving in and out of a
+    specified region in a video stream. It supports both polygonal and linear regions for counting.
+
+    Attributes:
+        in_count (int): Counter for objects moving inward.
+        out_count (int): Counter for objects moving outward.
+        counted_ids (List[int]): List of IDs of objects that have been counted.
+        classwise_counts (Dict[str, Dict[str, int]]): Dictionary for counts, categorized by object class.
+        region_initialized (bool): Flag indicating whether the counting region has been initialized.
+        show_in (bool): Flag to control display of inward count.
+        show_out (bool): Flag to control display of outward count.
+
+    Methods:
+        count_objects: Counts objects within a polygonal or linear region.
+        store_classwise_counts: Initializes class-wise counts if not already present.
+        display_counts: Displays object counts on the frame.
+        count: Processes input data (frames or object tracks) and updates counts.
+
+    Examples:
+        >>> counter = ObjectCounter()
+        >>> frame = cv2.imread("frame.jpg")
+        >>> processed_frame = counter.count(frame)
+        >>> print(f"Inward count: {counter.in_count}, Outward count: {counter.out_count}")
+    """
 
     def __init__(self, **kwargs):
-        """Initialization function for Count class, a child class of BaseSolution class, can be used for counting the
-        objects.
-        """
+        """Initializes the ObjectCounter class for real-time object counting in video streams."""
         super().__init__(**kwargs)
 
         self.in_count = 0  # Counter for objects moving inward
@@ -26,14 +48,23 @@ class ObjectCounter(BaseSolution):
 
     def count_objects(self, track_line, box, track_id, prev_position, cls):
         """
-        Helper function to count objects within a polygonal region.
+        Counts objects within a polygonal or linear region based on their tracks.
 
         Args:
-            track_line (dict): last 30 frame track record
-            box (list): Bounding box data for specific track in current frame
-            track_id (int): track ID of the object
-            prev_position (tuple): last frame position coordinates of the track
-            cls (int): Class index for classwise count updates
+            track_line (Dict): Last 30 frame track record for the object.
+            box (List[float]): Bounding box coordinates [x1, y1, x2, y2] for the specific track in the current frame.
+            track_id (int): Unique identifier for the tracked object.
+            prev_position (Tuple[float, float]): Last frame position coordinates (x, y) of the track.
+            cls (int): Class index for classwise count updates.
+
+        Examples:
+            >>> counter = ObjectCounter()
+            >>> track_line = {1: [100, 200], 2: [110, 210], 3: [120, 220]}
+            >>> box = [130, 230, 150, 250]
+            >>> track_id = 1
+            >>> prev_position = (120, 220)
+            >>> cls = 0
+            >>> counter.count_objects(track_line, box, track_id, prev_position, cls)
         """
         if prev_position is None or track_id in self.counted_ids:
             return
@@ -42,7 +73,7 @@ class ObjectCounter(BaseSolution):
         dx = (box[0] - prev_position[0]) * (centroid.x - prev_position[0])
         dy = (box[1] - prev_position[1]) * (centroid.y - prev_position[1])
 
-        if len(self.region) >= 3 and self.r_s.contains(Point(track_line[-1])):
+        if len(self.region) >= 3 and self.r_s.contains(self.Point(track_line[-1])):
             self.counted_ids.append(track_id)
             # For polygon region
             if dx > 0:
@@ -52,7 +83,7 @@ class ObjectCounter(BaseSolution):
                 self.out_count += 1
                 self.classwise_counts[self.names[cls]]["OUT"] += 1
 
-        elif len(self.region) < 3 and LineString([prev_position, box[:2]]).intersects(self.l_s):
+        elif len(self.region) < 3 and self.LineString([prev_position, box[:2]]).intersects(self.r_s):
             self.counted_ids.append(track_id)
             # For linear region
             if dx > 0 and dy > 0:
@@ -64,20 +95,34 @@ class ObjectCounter(BaseSolution):
 
     def store_classwise_counts(self, cls):
         """
-        Initialize class-wise counts if not already present.
+        Initialize class-wise counts for a specific object class if not already present.
 
         Args:
-            cls (int): Class index for classwise count updates
+            cls (int): Class index for classwise count updates.
+
+        This method ensures that the 'classwise_counts' dictionary contains an entry for the specified class,
+        initializing 'IN' and 'OUT' counts to zero if the class is not already present.
+
+        Examples:
+            >>> counter = ObjectCounter()
+            >>> counter.store_classwise_counts(0)  # Initialize counts for class index 0
+            >>> print(counter.classwise_counts)
+            {'person': {'IN': 0, 'OUT': 0}}
         """
         if self.names[cls] not in self.classwise_counts:
             self.classwise_counts[self.names[cls]] = {"IN": 0, "OUT": 0}
 
     def display_counts(self, im0):
         """
-        Helper function to display object counts on the frame.
+        Displays object counts on the input image or frame.
 
         Args:
-            im0 (ndarray): The input image or frame
+            im0 (numpy.ndarray): The input image or frame to display counts on.
+
+        Examples:
+            >>> counter = ObjectCounter()
+            >>> frame = cv2.imread("image.jpg")
+            >>> counter.display_counts(frame)
         """
         labels_dict = {
             str.capitalize(key): f"{'IN ' + str(value['IN']) if self.show_in else ''} "
@@ -91,12 +136,21 @@ class ObjectCounter(BaseSolution):
 
     def count(self, im0):
         """
-        Processes input data (frames or object tracks) and updates counts.
+        Processes input data (frames or object tracks) and updates object counts.
+
+        This method initializes the counting region, extracts tracks, draws bounding boxes and regions, updates
+        object counts, and displays the results on the input image.
 
         Args:
-            im0 (ndarray): The input image that will be used for processing
-        Returns
-            im0 (ndarray): The processed image for more usage
+            im0 (numpy.ndarray): The input image or frame to be processed.
+
+        Returns:
+            (numpy.ndarray): The processed image with annotations and count information.
+
+        Examples:
+            >>> counter = ObjectCounter()
+            >>> frame = cv2.imread("path/to/image.jpg")
+            >>> processed_frame = counter.count(frame)
         """
         if not self.region_initialized:
             self.initialize_region()
@@ -122,7 +176,9 @@ class ObjectCounter(BaseSolution):
             )
 
             # store previous position of track for object counting
-            prev_position = self.track_history[track_id][-2] if len(self.track_history[track_id]) > 1 else None
+            prev_position = None
+            if len(self.track_history[track_id]) > 1:
+                prev_position = self.track_history[track_id][-2]
             self.count_objects(self.track_line, box, track_id, prev_position, cls)  # Perform object counting
 
         self.display_counts(im0)  # Display the counts on the frame

ultralytics/solutions/parking_management.py

@@ -5,237 +5,232 @@ import json
 import cv2
 import numpy as np
 
-from ultralytics.utils.checks import check_imshow, check_requirements
+from ultralytics.solutions.solutions import LOGGER, BaseSolution, check_requirements
 from ultralytics.utils.plotting import Annotator
 
 
 class ParkingPtsSelection:
-    """Class for selecting and managing parking zone points on images using a Tkinter-based UI."""
+    """
+    A class for selecting and managing parking zone points on images using a Tkinter-based UI.
+
+    This class provides functionality to upload an image, select points to define parking zones, and save the
+    selected points to a JSON file. It uses Tkinter for the graphical user interface.
+
+    Attributes:
+        tk (module): The Tkinter module for GUI operations.
+        filedialog (module): Tkinter's filedialog module for file selection operations.
+        messagebox (module): Tkinter's messagebox module for displaying message boxes.
+        master (tk.Tk): The main Tkinter window.
+        canvas (tk.Canvas): The canvas widget for displaying the image and drawing bounding boxes.
+        image (PIL.Image.Image): The uploaded image.
+        canvas_image (ImageTk.PhotoImage): The image displayed on the canvas.
+        rg_data (List[List[Tuple[int, int]]]): List of bounding boxes, each defined by 4 points.
+        current_box (List[Tuple[int, int]]): Temporary storage for the points of the current bounding box.
+        imgw (int): Original width of the uploaded image.
+        imgh (int): Original height of the uploaded image.
+        canvas_max_width (int): Maximum width of the canvas.
+        canvas_max_height (int): Maximum height of the canvas.
+
+    Methods:
+        setup_ui: Sets up the Tkinter UI components.
+        initialize_properties: Initializes the necessary properties.
+        upload_image: Uploads an image, resizes it to fit the canvas, and displays it.
+        on_canvas_click: Handles mouse clicks to add points for bounding boxes.
+        draw_box: Draws a bounding box on the canvas.
+        remove_last_bounding_box: Removes the last bounding box and redraws the canvas.
+        redraw_canvas: Redraws the canvas with the image and all bounding boxes.
+        save_to_json: Saves the bounding boxes to a JSON file.
+
+    Examples:
+        >>> parking_selector = ParkingPtsSelection()
+        >>> # Use the GUI to upload an image, select parking zones, and save the data
+    """
 
     def __init__(self):
-        """Initializes the UI for selecting parking zone points in a tkinter window."""
+        """Initializes the ParkingPtsSelection class, setting up UI and properties for parking zone point selection."""
         check_requirements("tkinter")
+        import tkinter as tk
+        from tkinter import filedialog, messagebox
 
-        import tkinter as tk  # scope for multi-environment compatibility
+        self.tk, self.filedialog, self.messagebox = tk, filedialog, messagebox
+        self.setup_ui()
+        self.initialize_properties()
+        self.master.mainloop()
 
-        self.tk = tk
-        self.master = tk.Tk()
+    def setup_ui(self):
+        """Sets up the Tkinter UI components for the parking zone points selection interface."""
+        self.master = self.tk.Tk()
         self.master.title("Ultralytics Parking Zones Points Selector")
-
-        # Disable window resizing
         self.master.resizable(False, False)
 
-        # Setup canvas for image display
+        # Canvas for image display
         self.canvas = self.tk.Canvas(self.master, bg="white")
+        self.canvas.pack(side=self.tk.BOTTOM)
 
-        # Setup buttons
+        # Button frame with buttons
         button_frame = self.tk.Frame(self.master)
         button_frame.pack(side=self.tk.TOP)
 
-        self.tk.Button(button_frame, text="Upload Image", command=self.upload_image).grid(row=0, column=0)
-        self.tk.Button(button_frame, text="Remove Last BBox", command=self.remove_last_bounding_box).grid(
-            row=0, column=1
-        )
-        self.tk.Button(button_frame, text="Save", command=self.save_to_json).grid(row=0, column=2)
-
-        # Initialize properties
-        self.image_path = None
-        self.image = None
-        self.canvas_image = None
-        self.rg_data = []  # region coordinates
-        self.current_box = []
-        self.imgw = 0  # image width
-        self.imgh = 0  # image height
+        for text, cmd in [
+            ("Upload Image", self.upload_image),
+            ("Remove Last BBox", self.remove_last_bounding_box),
+            ("Save", self.save_to_json),
+        ]:
+            self.tk.Button(button_frame, text=text, command=cmd).pack(side=self.tk.LEFT)
 
-        # Constants
-        self.canvas_max_width = 1280
-        self.canvas_max_height = 720
-
-        self.master.mainloop()
+    def initialize_properties(self):
+        """Initialize properties for image, canvas, bounding boxes, and dimensions."""
+        self.image = self.canvas_image = None
+        self.rg_data, self.current_box = [], []
+        self.imgw = self.imgh = 0
+        self.canvas_max_width, self.canvas_max_height = 1280, 720
 
     def upload_image(self):
-        """Upload an image and resize it to fit canvas."""
-        from tkinter import filedialog
-
+        """Uploads and displays an image on the canvas, resizing it to fit within specified dimensions."""
         from PIL import Image, ImageTk  # scope because ImageTk requires tkinter package
 
-        self.image_path = filedialog.askopenfilename(filetypes=[("Image Files", "*.png;*.jpg;*.jpeg")])
-        if not self.image_path:
+        self.image = Image.open(self.filedialog.askopenfilename(filetypes=[("Image Files", "*.png;*.jpg;*.jpeg")]))
+        if not self.image:
             return
 
-        self.image = Image.open(self.image_path)
         self.imgw, self.imgh = self.image.size
-
-        # Calculate the aspect ratio and resize image
         aspect_ratio = self.imgw / self.imgh
-        if aspect_ratio > 1:
-            # Landscape orientation
-            canvas_width = min(self.canvas_max_width, self.imgw)
-            canvas_height = int(canvas_width / aspect_ratio)
-        else:
-            # Portrait orientation
-            canvas_height = min(self.canvas_max_height, self.imgh)
-            canvas_width = int(canvas_height * aspect_ratio)
-
-        # Check if canvas is already initialized
-        if self.canvas:
-            self.canvas.destroy()  # Destroy previous canvas
-
-        self.canvas = self.tk.Canvas(self.master, bg="white", width=canvas_width, height=canvas_height)
-        resized_image = self.image.resize((canvas_width, canvas_height), Image.LANCZOS)
-        self.canvas_image = ImageTk.PhotoImage(resized_image)
-        self.canvas.create_image(0, 0, anchor=self.tk.NW, image=self.canvas_image)
+        canvas_width = (
+            min(self.canvas_max_width, self.imgw) if aspect_ratio > 1 else int(self.canvas_max_height * aspect_ratio)
+        )
+        canvas_height = (
+            min(self.canvas_max_height, self.imgh) if aspect_ratio <= 1 else int(canvas_width / aspect_ratio)
+        )
 
-        self.canvas.pack(side=self.tk.BOTTOM)
+        self.canvas.config(width=canvas_width, height=canvas_height)
+        self.canvas_image = ImageTk.PhotoImage(self.image.resize((canvas_width, canvas_height), Image.LANCZOS))
+        self.canvas.create_image(0, 0, anchor=self.tk.NW, image=self.canvas_image)
         self.canvas.bind("<Button-1>", self.on_canvas_click)
 
-        # Reset bounding boxes and current box
-        self.rg_data = []
-        self.current_box = []
+        self.rg_data.clear(), self.current_box.clear()
 
     def on_canvas_click(self, event):
-        """Handle mouse clicks on canvas to create points for bounding boxes."""
+        """Handles mouse clicks to add points for bounding boxes on the canvas."""
         self.current_box.append((event.x, event.y))
         self.canvas.create_oval(event.x - 3, event.y - 3, event.x + 3, event.y + 3, fill="red")
-
         if len(self.current_box) == 4:
-            self.rg_data.append(self.current_box)
-            [
-                self.canvas.create_line(self.current_box[i], self.current_box[(i + 1) % 4], fill="blue", width=2)
-                for i in range(4)
-            ]
-            self.current_box = []
+            self.rg_data.append(self.current_box.copy())
+            self.draw_box(self.current_box)
+            self.current_box.clear()
 
-    def remove_last_bounding_box(self):
-        """Remove the last drawn bounding box from canvas."""
-        from tkinter import messagebox  # scope for multi-environment compatibility
+    def draw_box(self, box):
+        """Draws a bounding box on the canvas using the provided coordinates."""
+        for i in range(4):
+            self.canvas.create_line(box[i], box[(i + 1) % 4], fill="blue", width=2)
 
-        if self.rg_data:
-            self.rg_data.pop()  # Remove the last bounding box
-            self.canvas.delete("all")  # Clear the canvas
-            self.canvas.create_image(0, 0, anchor=self.tk.NW, image=self.canvas_image)  # Redraw the image
+    def remove_last_bounding_box(self):
+        """Removes the last bounding box from the list and redraws the canvas."""
+        if not self.rg_data:
+            self.messagebox.showwarning("Warning", "No bounding boxes to remove.")
+            return
+        self.rg_data.pop()
+        self.redraw_canvas()
 
-            # Redraw all bounding boxes
-            for box in self.rg_data:
-                [self.canvas.create_line(box[i], box[(i + 1) % 4], fill="blue", width=2) for i in range(4)]
-            messagebox.showinfo("Success", "Last bounding box removed.")
-        else:
-            messagebox.showwarning("Warning", "No bounding boxes to remove.")
+    def redraw_canvas(self):
+        """Redraws the canvas with the image and all bounding boxes."""
+        self.canvas.delete("all")
+        self.canvas.create_image(0, 0, anchor=self.tk.NW, image=self.canvas_image)
+        for box in self.rg_data:
+            self.draw_box(box)
 
     def save_to_json(self):
-        """Saves rescaled bounding boxes to 'bounding_boxes.json' based on image-to-canvas size ratio."""
-        from tkinter import messagebox  # scope for multi-environment compatibility
-
-        rg_data = []  # regions data
-        for box in self.rg_data:
-            rs_box = [
-                (
-                    int(x * self.imgw / self.canvas.winfo_width()),  # width scaling
-                    int(y * self.imgh / self.canvas.winfo_height()),  # height scaling
-                )
-                for x, y in box
-            ]
-            rg_data.append({"points": rs_box})
+        """Saves the selected parking zone points to a JSON file with scaled coordinates."""
+        scale_w, scale_h = self.imgw / self.canvas.winfo_width(), self.imgh / self.canvas.winfo_height()
+        data = [{"points": [(int(x * scale_w), int(y * scale_h)) for x, y in box]} for box in self.rg_data]
         with open("bounding_boxes.json", "w") as f:
-            json.dump(rg_data, f, indent=4)
+            json.dump(data, f, indent=4)
+        self.messagebox.showinfo("Success", "Bounding boxes saved to bounding_boxes.json")
 
-        messagebox.showinfo("Success", "Bounding boxes saved to bounding_boxes.json")
 
+class ParkingManagement(BaseSolution):
+    """
+    Manages parking occupancy and availability using YOLO model for real-time monitoring and visualization.
 
-class ParkingManagement:
-    """Manages parking occupancy and availability using YOLOv8 for real-time monitoring and visualization."""
+    This class extends BaseSolution to provide functionality for parking lot management, including detection of
+    occupied spaces, visualization of parking regions, and display of occupancy statistics.
 
-    def __init__(
-        self,
-        model,  # Ultralytics YOLO model file path
-        json_file,  # Parking management annotation file created from Parking Annotator
-        occupied_region_color=(0, 0, 255),  # occupied region color
-        available_region_color=(0, 255, 0),  # available region color
-    ):
-        """
-        Initializes the parking management system with a YOLOv8 model and visualization settings.
+    Attributes:
+        json_file (str): Path to the JSON file containing parking region details.
+        json (List[Dict]): Loaded JSON data containing parking region information.
+        pr_info (Dict[str, int]): Dictionary storing parking information (Occupancy and Available spaces).
+        arc (Tuple[int, int, int]): RGB color tuple for available region visualization.
+        occ (Tuple[int, int, int]): RGB color tuple for occupied region visualization.
+        dc (Tuple[int, int, int]): RGB color tuple for centroid visualization of detected objects.
 
-        Args:
-            model (str): Path to the YOLOv8 model.
-            json_file (str): file that have all parking slot points data
-            occupied_region_color (tuple): RGB color tuple for occupied regions.
-            available_region_color (tuple): RGB color tuple for available regions.
-        """
-        # Model initialization
-        from ultralytics import YOLO
+    Methods:
+        process_data: Processes model data for parking lot management and visualization.
 
-        self.model = YOLO(model)
+    Examples:
+        >>> from ultralytics.solutions import ParkingManagement
+        >>> parking_manager = ParkingManagement(model="yolov8n.pt", json_file="parking_regions.json")
+        >>> results = parking_manager(source="parking_lot_video.mp4")
+        >>> print(f"Occupied spaces: {parking_manager.pr_info['Occupancy']}")
+        >>> print(f"Available spaces: {parking_manager.pr_info['Available']}")
+    """
 
-        # Load JSON data
-        with open(json_file) as f:
-            self.json_data = json.load(f)
+    def __init__(self, **kwargs):
+        """Initializes the parking management system with a YOLO model and visualization settings."""
+        super().__init__(**kwargs)
 
-        self.pr_info = {"Occupancy": 0, "Available": 0}  # dictionary for parking information
+        self.json_file = self.CFG["json_file"]  # Load JSON data
+        if self.json_file is None:
+            LOGGER.warning("❌ json_file argument missing. Parking region details required.")
+            raise ValueError("❌ Json file path can not be empty")
 
-        self.occ = occupied_region_color
-        self.arc = available_region_color
+        with open(self.json_file) as f:
+            self.json = json.load(f)
 
-        self.env_check = check_imshow(warn=True)  # check if environment supports imshow
+        self.pr_info = {"Occupancy": 0, "Available": 0}  # dictionary for parking information
 
-    def process_data(self, im0):
-        """
-        Process the model data for parking lot management.
+        self.arc = (0, 0, 255)  # available region color
+        self.occ = (0, 255, 0)  # occupied region color
+        self.dc = (255, 0, 189)  # centroid color for each box
 
-        Args:
-            im0 (ndarray): inference image
+    def process_data(self, im0):
         """
-        results = self.model.track(im0, persist=True, show=False)  # object tracking
+        Processes the model data for parking lot management.
 
-        es, fs = len(self.json_data), 0  # empty slots, filled slots
-        annotator = Annotator(im0)  # init annotator
+        This function analyzes the input image, extracts tracks, and determines the occupancy status of parking
+        regions defined in the JSON file. It annotates the image with occupied and available parking spots,
+        and updates the parking information.
 
-        # extract tracks data
-        if results[0].boxes.id is None:
-            self.display_frames(im0)
-            return im0
+        Args:
+            im0 (np.ndarray): The input inference image.
 
-        boxes = results[0].boxes.xyxy.cpu().tolist()
-        clss = results[0].boxes.cls.cpu().tolist()
+        Examples:
+            >>> parking_manager = ParkingManagement(json_file="parking_regions.json")
+            >>> image = cv2.imread("parking_lot.jpg")
+            >>> parking_manager.process_data(image)
+        """
+        self.extract_tracks(im0)  # extract tracks from im0
+        es, fs = len(self.json), 0  # empty slots, filled slots
+        annotator = Annotator(im0, self.line_width)  # init annotator
 
-        for region in self.json_data:
+        for region in self.json:
             # Convert points to a NumPy array with the correct dtype and reshape properly
             pts_array = np.array(region["points"], dtype=np.int32).reshape((-1, 1, 2))
             rg_occupied = False  # occupied region initialization
-            for box, cls in zip(boxes, clss):
-                xc = int((box[0] + box[2]) / 2)
-                yc = int((box[1] + box[3]) / 2)
-                annotator.display_objects_labels(
-                    im0, self.model.names[int(cls)], (104, 31, 17), (255, 255, 255), xc, yc, 10
-                )
+            for box, cls in zip(self.boxes, self.clss):
+                xc, yc = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)
                 dist = cv2.pointPolygonTest(pts_array, (xc, yc), False)
                 if dist >= 0:
+                    # cv2.circle(im0, (xc, yc), radius=self.line_width * 4, color=self.dc, thickness=-1)
+                    annotator.display_objects_labels(
+                        im0, self.model.names[int(cls)], (104, 31, 17), (255, 255, 255), xc, yc, 10
+                    )
                     rg_occupied = True
                     break
-            if rg_occupied:
-                fs += 1
-                es -= 1
-
+            fs, es = (fs + 1, es - 1) if rg_occupied else (fs, es)
             # Plotting regions
-            color = self.occ if rg_occupied else self.arc
-            cv2.polylines(im0, [pts_array], isClosed=True, color=color, thickness=2)
+            cv2.polylines(im0, [pts_array], isClosed=True, color=self.occ if rg_occupied else self.arc, thickness=2)
 
-        self.pr_info["Occupancy"] = fs
-        self.pr_info["Available"] = es
+        self.pr_info["Occupancy"], self.pr_info["Available"] = fs, es
 
         annotator.display_analytics(im0, self.pr_info, (104, 31, 17), (255, 255, 255), 10)
-
-        self.display_frames(im0)
-        return im0
-
-    def display_frames(self, im0):
-        """
-        Display frame.
-
-        Args:
-            im0 (ndarray): inference image
-        """
-        if self.env_check:
-            cv2.imshow("Ultralytics Parking Manager", im0)
-            # Break Window
-            if cv2.waitKey(1) & 0xFF == ord("q"):
-                return
+        self.display_output(im0)  # display output with base class function
+        return im0  # return output image for more usage