New YOLOv8 Results() class for prediction outputs (#314)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: Laughing-q <1185102784@qq.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Laughing <61612323+Laughing-q@users.noreply.github.com>
Co-authored-by: Viet Nhat Thai <60825385+vietnhatthai@users.noreply.github.com>
Co-authored-by: Paula Derrenger <107626595+pderrenger@users.noreply.github.com>

docs/README.md

@@ -1,6 +1,6 @@
 # Ultralytics Docs
 
-Deployed to https://docs.ultralytics.com
+Ultralytics Docs are deployed to [https://docs.ultralytics.com](https://docs.ultralytics.com).
 
 ### Install Ultralytics package
 

docs/cli.md

@@ -83,7 +83,7 @@ yolo cfg=default.yaml
         yolo task=init
         yolo cfg=default.yaml
         ```
-    === "Result"
+    === "Results"
         TODO: add terminal output
 
 

docs/predict.md

@@ -0,0 +1,72 @@
+Inference or prediction of a task returns a list of `Results` objects. Alternatively, in the streaming mode, it returns a generator of `Results` objects which is memory efficient. Streaming mode can be enabled by passing `stream=True` in predictor's call method.
+
+!!! example "Predict"
+    === "Getting a List"
+        ```python
+        inputs = [img, img] # list of np arrays
+        results = model(inputs) # List of Results objects
+        for result in results:
+            boxes = results.boxes # Boxes object for bbox outputs
+            masks = results.masks # Masks object for segmenation masks outputs
+            probs = results.probs # Class probabilities for classification outputs
+            ...
+        ```
+    === "Getting a Generator"
+        ```python
+        inputs = [img, img] # list of np arrays
+        results = model(inputs, stream="True") # Generator of Results objects
+        for result in results:
+            boxes = results.boxes # Boxes object for bbox outputs
+            masks = results.masks # Masks object for segmenation masks outputs
+            probs = results.probs # Class probabilities for classification outputs
+            ...
+        ```
+
+## Working with Results
+
+Results object consists of these component objects:
+
+- `results.boxes` : It is an object of class `Boxes`. It has properties and methods for manipulating bboxes
+- `results.masks` : It is an object of class `Masks`. It can be used to index masks or to get segment coordinates.
+- `results.prob`  : It is a `Tensor` object. It contains the class probabilities/logits.
+
+Each result is composed of torch.Tensor by default, in which you can easily use following functionality:
+```python
+results = results.cuda()
+results = results.cpu()
+results = results.to("cpu")
+results = results.numpy()
+```
+### Boxes
+`Boxes` object can be used index, manipulate and convert bboxes to different formats. The box format conversion operations are cached, which means they're only calculated once per object and those values are reused for future calls.
+
+- Indexing a `Boxes` objects returns a `Boxes` object
+```python
+boxes = results.boxes
+box = boxes[0] # returns one box
+box.xyxy 
+```
+- Properties and conversions
+```
+results.boxes.xyxy   # box with xyxy format, (N, 4)
+results.boxes.xywh   # box with xywh format, (N, 4)
+results.boxes.xyxyn  # box with xyxy format but normalized, (N, 4)
+results.boxes.xywhn  # box with xywh format but normalized, (N, 4)
+results.boxes.conf   # confidence score, (N, 1)
+results.boxes.cls    # cls, (N, 1)
+```
+### Masks
+`Masks` object can be used index, manipulate and convert masks to segments. The segment conversion operation is cached.
+
+```python
+results.masks.masks     # masks, (N, H, W)
+results.masks.segments  # bounding coordinates of masks, List[segment] * N
+```
+
+### probs
+`probs` attribute of `Results` class is a `Tensor` containing class probabilities of a classification operation.
+```python
+results.probs     # cls prob, (num_class, )
+```
+
+Class reference documentation for `Results` module and its components can be found [here](reference/results.md)

docs/python.md

@@ -1,5 +1,4 @@
-This is the simplest way of simply using YOLOv8 models in a Python environment. It can be imported from
-the `ultralytics` module.
+The simplest way of simply using YOLOv8 directly in a Python environment.
 
 !!! example "Train"
 
@@ -51,35 +50,60 @@ the `ultralytics` module.
     === "From source"
         ```python
         from ultralytics import YOLO
+        from PIL import Image
+        import cv2
 
         model = YOLO("model.pt")
-        model.predict(source="0") # accepts all formats - img/folder/vid.*(mp4/format). 0 for webcam
-        model.predict(source="folder", show=True) # Display preds. Accepts all yolo predict arguments
+        # accepts all formats - image/dir/Path/URL/video/PIL/ndarray. 0 for webcam
+        results = model.predict(source="0")
+        results = model.predict(source="folder", show=True) # Display preds. Accepts all YOLO predict arguments
 
+        # from PIL
+        im1 = Image.open("bus.jpg")
+        results = model.predict(source=im1, save=True)  # save plotted images
+
+        # from ndarray
+        im2 = cv2.imread("bus.jpg")
+        results = model.predict(source=im2, save=True, save_txt=True)  # save predictions as labels
+
+        # from list of PIL/ndarray
+        results = model.predict(source=[im1, im2])
         ```
 
-    === "From image/ndarray/tensor"
+    === "Results usage"
         ```python
-        # TODO, still working on it.
-        ```
+        # results would be a list of Results object including all the predictions by default
+        # but be careful as it could occupy a lot memory when there're many images, 
+        # especially the task is segmentation.
+        # 1. return as a list
+        results = model.predict(source="folder")
 
+        # results would be a generator which is more friendly to memory by setting stream=True
+        # 2. return as a generator
+        results = model.predict(source=0, stream=True)
 
-    === "Return outputs"
-        ```python
-        from ultralytics import YOLO
+        for result in results:
+            # detection
+            result.boxes.xyxy   # box with xyxy format, (N, 4)
+            result.boxes.xywh   # box with xywh format, (N, 4)
+            result.boxes.xyxyn  # box with xyxy format but normalized, (N, 4)
+            result.boxes.xywhn  # box with xywh format but normalized, (N, 4)
+            result.boxes.conf   # confidence score, (N, 1)
+            result.boxes.cls    # cls, (N, 1)
 
-        model = YOLO("model.pt")
-        outputs = model.predict(source="0", return_outputs=True) # treat predict as a Python generator
-        for output in outputs:
-          # each output here is a dict.
-          # for detection
-          print(output["det"])  # np.ndarray, (N, 6), xyxy, score, cls
-          # for segmentation
-          print(output["det"])  # np.ndarray, (N, 6), xyxy, score, cls
-          print(output["segment"])  # List[np.ndarray] * N, bounding coordinates of masks
-          # for classify
-          print(output["prob"]) # np.ndarray, (num_class, ), cls prob
+            # segmentation
+            result.masks.masks     # masks, (N, H, W)
+            result.masks.segments  # bounding coordinates of masks, List[segment] * N
 
+            # classification
+            result.probs     # cls prob, (num_class, )
+
+        # Each result is composed of torch.Tensor by default, 
+        # in which you can easily use following functionality:
+        result = result.cuda()
+        result = result.cpu()
+        result = result.to("cpu")
+        result = result.numpy()
         ```
 
 !!! note "Export and Deployment"

docs/reference/results.md

@@ -0,0 +1,11 @@
+### Results API Reference
+
+:::ultralytics.yolo.engine.results.Results
+
+### Boxes API Reference
+
+:::ultralytics.yolo.engine.results.Boxes
+
+### Masks API Reference
+
+:::ultralytics.yolo.engine.results.Masks