docs: update 0412.md

@@ -65,18 +65,42 @@
 
 ### Precision & Recall
 * Precision은 관련 Object만을 식별하는 능력을 나타낸다. 
-Precision = TP / (TP + FP) 이며, 있는 것을 있다고 예측한 것을 있든 없든 있다고 예측한 것으로 나눈 값이다. 
+Precision = TP / (TP + FP) 이며, 모든 식별 결과 중 옳게 검출한 비율을 의미한다.
 * Recall은 모든 관련 케이스(모든 ground truth bounding boxes)를 찾는 능력을 나타낸다.
-Recall = TP / (TP + FN) 이며, 있는 것을 있다고 예측한 것을 있는 것을 있다고든 없다고든 예측한 결과로 나눈 값이다.
+Recall = TP / (TP + FN) 이며, 마땅히 검출해내야하는 물체들 중에서 제대로 검출된 것의 비율을 의미한다.
 
 ### PR Curve
-x축을 Recall, y축을 Precision으로 하여 나타낸 그래프이다. 이 그래프를 통해 object detector의 퍼포먼스를 측정할 수 있다. 
+PR Curve는 confidence 레벨에 대한 threshold 값의 변화에 의한 object detector의 성능을 평가하는 방법이다. 
+이는 x축을 Recall, y축을 Precision으로 하여 나타낸 그래프로 이 그래프를 통해 object detector의 퍼포먼스를 측정할 수 있다. 
+
+예를 들어, 15개의 얼굴이 존재하는 어떤 데이터넷에서 한 얼굴을 검출하는 알고리즘에 의해 총 10개의 얼굴이 검출되었다고 가정해보자. 여기서 confidence는 0% ~ 100%까지 모두 고려하였다.
+
+|Detections|Confidences|TP or FP|
+|--|--|--|
+|A|57%|TP|
+|B|78%|TP|
+|C|43%|FP|
+|D|85%|TP|
+|E|91%|TP|
+|F|13%|FP|
+|G|45%|TP|
+|H|68%|FP|
+|I|95%|TP|
+|J|81%|TP|
+
+10개 중 7개는 제대로 검출 (TP) 되었고, 3개는 잘못 검출되었다. (FP) 이때 Precision = 7 / 10 = 0.7이고, Recall은 7 / 15(실제 얼굴 개수) = 0.47이다. 
+
+위 결과를 confidence 레벨이 높은 순으로 재정렬하고, threshold를 95%로 정한다면 Precision = 1/1, Recall = 1/15 = 0.067이 된다. 
+threshold를 91%로 낮추면 두 개가 검출된 것으로 판단할 것이고, Precision = 1, Recall = 2/15가 된다.
+이렇게 threshold값을 검출들의 confidence 레벨에 맞게 낮춰가면 Precision과 Recall 값이 변화한다. 이 변화하는 Precision과 Recall 값들을 x축을 Recall, Y축을 Precision으로 그래프를 나타내면 그것이 바로 PR Curve이다.
+즉, PR 곡선에서는 **recall 값의 변화에 따른 precision 값을 확인할 수 있다.**
 
 ## Average Precision(AP)
-PR Curve 내부의 면적 값을 계산한다. 모든 Recall 값에서 평균화된 Precision을 나타내는 값이다. 
+PR Curve는 성능을 평가하기에 아주 좋은 방법이지만, 단 하나의 숫자로 성능을 평가할 수 있도록 하기 위해 AP가 도입되었다. AP는 PR Curve에서 선 아래쪽의 면적으로 계산된다. 주어진 PR Curve를 단조적으로 감소하는 그래프가 되게 하기 위해 살짝 손봐준뒤, 아래 면적을 계산함으로서 AP를 구한다. 
 
 ## mAP
-모든 클래스들에 대한 AP의 평균 값이다. . . (https://towardsdatascience.com/map-mean-average-precision-might-confuse-you-5956f1bfa9e2) 
+물체 클래스가 여러개인 경우 각 클래스 당 AP를 구한 다음 그것을 모두 합한 값에 클래스의 갯수로 나눠줌으로서 mAP를 구할 수 있다.
+(https://towardsdatascience.com/map-mean-average-precision-might-confuse-you-5956f1bfa9e2) 
 다시 확인하고 글 남기기.
 
 ## MOTA (Multiple Object Tracking Accuracy)
@@ -278,7 +302,7 @@ print(torch.__version__, torch.cuda.is_available())
 # opencv is pre-installed on colab
 ```
 
-이제, detectron2를 설치해주자. 
+이제, detectron2를 설치해주고, 필요한 라이브러리들을 추가해주자.
 ```python
 # install detectron2: (Colab has CUDA 10.1 + torch 1.8)
 # See https://detectron2.readthedocs.io/tutorials/install.html for instructions
@@ -286,9 +310,253 @@ import torch
 assert torch.__version__.startswith("1.8")   # need to manually install torch 1.8 if Colab changes its default version
 !pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/torch1.8/index.html
 # exit(0)  # After installation, you need to "restart runtime" in Colab. This line can also restart runtime
+
+# Some basic setup:
+# Setup detectron2 logger
+import detectron2
+from detectron2.utils.logger import setup_logger
+setup_logger()
+
+# import some common libraries
+import numpy as np
+import os, json, cv2, random
+from google.colab.patches import cv2_imshow
+
+# import some common detectron2 utilities
+from detectron2 import model_zoo
+from detectron2.engine import DefaultPredictor
+from detectron2.config import get_cfg
+from detectron2.utils.visualizer import Visualizer
+from detectron2.data import MetadataCatalog, DatasetCatalog
+```
+
+먼저, pre-trained된 detectron2 모델을 돌려보자. 먼저 필요한 이미지는 COCO 데이터셋을 이용할 것이다.
+COCO 데이터셋에서 불러온 이미지는 다음과 같다.
+```python
+!wget http://images.cocodataset.org/val2017/000000439715.jpg -q -O input.jpg
+im = cv2.imread("./input.jpg")
+cv2_imshow(im)
+```
+![coco](./images/coco.png)
+
+그 다음, 우리는 detectron2 configuration과 detectron2 `DefaultPredictor`를 생성하여 위 이미지에 대해 inference를 수행할 것이다.
+```python
+cfg = get_cfg() # detectron2의 default config를 불러온다.
+cfg.merge_from_file(model_zoo.get_config_file("COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml")) # value들을 file로부터 불러온다.
+cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.5  # ROI_Heads의 threshold를 0.5로 지정한다.
+cfg.MODEL.WEIGHTS = model_zoo.get_checkpoint_url("COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml") # model의 가중치를 지정한다.
+predictor = DefaultPredictor(cfg) #  단일의 input 이미지에 대해 단일의 device에서 작동하는 주어진 config에 대해 간단한 end-to-end predictor를 생성한다. 
+outputs = predictor(im) # 해당 이미지를 모델에 넣어 얻은 결과물을 반환한다.
 ```
 
+Model의 Output Format에 대해 공식 문서로부터 알아보자. inference 모드에 있을 때, builtin 모델은 각 이미지에 대해 하나의 dict인 list[dict]를 출력한다. 모델이 수행하는 태스크에 따라 각 dict는 다음과 같은 필드를 포함할 수 있다.
+* pred_boxes : 탐지된 인스턴스 당 하나씩 N개의 boxes를 저장하는 Boxes
+* scores : `Tensor`이며, N개의 confidence scores 벡터를 나타낸다.
+* pred_classes : `Tensor`이며, [0,num_categories) 범위 내에 속하는 N개의 레이블 벡터
+* pred_masks : (N, H, W)의 shape를 갖는 `Tensor`로서 탐지된 각 인스턴스를 나타낸다.
+  
+.. 나머지는 [여기](https://detectron2.readthedocs.io/en/latest/tutorials/models.html#model-output-format)에서 자세히 확인할 수 있다.
+```python
+print(outputs["instances"].pred_classes)
+print(outputs["instances"].pred_boxes)
+
+# 결과
+tensor([17,  0,  0,  0,  0,  0,  0,  0, 25,  0, 25, 25,  0,  0, 24],
+       device='cuda:0')
+Boxes(tensor([[126.6035, 244.8977, 459.8291, 480.0000],
+        [251.1083, 157.8127, 338.9731, 413.6379],
+        [114.8496, 268.6864, 148.2352, 398.8111],
+        [  0.8217, 281.0327,  78.6072, 478.4210],
+        [ 49.3954, 274.1229,  80.1545, 342.9808],
+        [561.2248, 271.5816, 596.2755, 385.2552],
+        [385.9072, 270.3125, 413.7130, 304.0397],
+        [515.9295, 278.3744, 562.2792, 389.3802],
+        [335.2409, 251.9167, 414.7491, 275.9375],
+        [350.9300, 269.2060, 386.0984, 297.9081],
+        [331.6292, 230.9996, 393.2759, 257.2009],
+        [510.7349, 263.2656, 570.9865, 295.9194],
+        [409.0841, 271.8646, 460.5582, 356.8722],
+        [506.8767, 283.3257, 529.9403, 324.0392],
+        [594.5663, 283.4820, 609.0577, 311.4124]], device='cuda:0'))
+```
+Visualizer를 이용하여 예측된 결과를 이미지 위에 그릴 수 있다. 
+```python
+v = Visualizer(im[:, :, ::-1], MetadataCatalog.get(cfg.DATASETS.TRAIN[0]), scale=1.2)
+out = v.draw_instance_predictions(outputs["instances"].to("cpu"))
+cv2_imshow(out.get_image()[:, :, ::-1])
+```
+![coco_output](./images/coco_output.png)
+
+이제, COCO 데이터셋의 카테고리에는 존재하지 않는 ballon 데이터를 이용하여 detectron2 모델을 트레이닝 해 볼 것이다. balloon segementation dataset을 COCO 데이터셋을 이용해 pre-trained된 모델에 train시키고, 이 모델이 새로운 클래스인 balloon을 인지할 수 있도록 해 보자.
+먼저, 필요한 데이터를 다운로드 받는다.
+```python
+# download, decompress the data
+!wget https://github.com/matterport/Mask_RCNN/releases/download/v2.1/balloon_dataset.zip
+!unzip balloon_dataset.zip > /dev/null
+```
 
+다운받은 데이터셋을 detectron2의 트레이닝 시 요구되는 format에 맞게 변환하는 과정을 거친다.
+
+```python
+# if your dataset is in COCO format, this cell can be replaced by the following three lines:
+# from detectron2.data.datasets import register_coco_instances
+# register_coco_instances("my_dataset_train", {}, "json_annotation_train.json", "path/to/image/dir")
+# register_coco_instances("my_dataset_val", {}, "json_annotation_val.json", "path/to/image/dir")
+
+from detectron2.structures import BoxMode
+
+def get_balloon_dicts(img_dir):
+    json_file = os.path.join(img_dir, "via_region_data.json")
+    with open(json_file) as f:
+        imgs_anns = json.load(f)
+
+    dataset_dicts = []
+    for idx, v in enumerate(imgs_anns.values()):
+        record = {}
+        
+        filename = os.path.join(img_dir, v["filename"])
+        height, width = cv2.imread(filename).shape[:2]
+        
+        record["file_name"] = filename
+        record["image_id"] = idx
+        record["height"] = height
+        record["width"] = width
+      
+        annos = v["regions"]
+        objs = []
+        for _, anno in annos.items():
+            assert not anno["region_attributes"]
+            anno = anno["shape_attributes"]
+            px = anno["all_points_x"]
+            py = anno["all_points_y"]
+            poly = [(x + 0.5, y + 0.5) for x, y in zip(px, py)]
+            poly = [p for x in poly for p in x]
+
+            obj = {
+                "bbox": [np.min(px), np.min(py), np.max(px), np.max(py)],
+                "bbox_mode": BoxMode.XYXY_ABS,
+                "segmentation": [poly],
+                "category_id": 0,
+            }
+            objs.append(obj)
+        record["annotations"] = objs
+        dataset_dicts.append(record)
+    return dataset_dicts
+
+for d in ["train", "val"]:
+    DatasetCatalog.register("balloon_" + d, lambda d=d: get_balloon_dicts("balloon/" + d))
+    MetadataCatalog.get("balloon_" + d).set(thing_classes=["balloon"])
+balloon_metadata = MetadataCatalog.get("balloon_train")
+```
+
+데이터가 올바른지 확인하기 위해 training set에서 임의로 선택한 샘플을 시각화해보자.
+```python
+dataset_dicts = get_balloon_dicts("balloon/train")
+for d in random.sample(dataset_dicts, 3):
+    img = cv2.imread(d["file_name"])
+    visualizer = Visualizer(img[:, :, ::-1], metadata=balloon_metadata, scale=0.5)
+    out = visualizer.draw_dataset_dict(d)
+    cv2_imshow(out.get_image()[:, :, ::-1])
+```
+![ballon_sample](./images/balloon_sample.png)
+
+이제, 풍선 데이터셋을 COCO 데이터셋으로 pre-trained된 R50-FPN Mask R-CNN 모델에 fine-tune 되도록 트레이닝해보자. 트레이닝하는 코드는 다음과 같다. 위에서 `DefaultPredictor`를 사용할 때 이용했던 `get_cfg()`를 또 활용하여 트레이닝한다. 
+여기서 `DefaultTrainer`는 default training logic을 이용하여 train하도록 한다. 그 과정은 다음과 같다.
+1. 주어진 config에 의해 정의된 모델, optimizer, dataloader을 이용하여 `SimpleTrainer`를 생성한다. 또한 LR schedular를 생성한다.
+2. 이전에 트레이닝 된 적이 있는지 확인하고 있다면 불러온다.
+3. config에 의해 정의된 common hooks를 등록한다.
+
+```python
+from detectron2.engine import DefaultTrainer
+
+cfg = get_cfg()
+cfg.merge_from_file(model_zoo.get_config_file("COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml"))
+cfg.DATASETS.TRAIN = ("balloon_train",)
+cfg.DATASETS.TEST = () 
+cfg.DATALOADER.NUM_WORKERS = 2
+cfg.MODEL.WEIGHTS = model_zoo.get_checkpoint_url("COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml")  # Let training initialize from model zoo
+cfg.SOLVER.IMS_PER_BATCH = 2
+cfg.SOLVER.BASE_LR = 0.00025  # pick a good LR
+cfg.SOLVER.MAX_ITER = 300    # 300 iterations seems good enough for this toy dataset; you will need to train longer for a practical dataset
+cfg.SOLVER.STEPS = []        # do not decay learning rate
+cfg.MODEL.ROI_HEADS.BATCH_SIZE_PER_IMAGE = 128   # faster, and good enough for this toy dataset (default: 512)
+cfg.MODEL.ROI_HEADS.NUM_CLASSES = 1  # only has one class (ballon). (see https://detectron2.readthedocs.io/tutorials/datasets.html#update-the-config-for-new-datasets)
+# NOTE: this config means the number of classes, but a few popular unofficial tutorials incorrect uses num_classes+1 here.
+
+os.makedirs(cfg.OUTPUT_DIR, exist_ok=True)
+trainer = DefaultTrainer(cfg) 
+trainer.resume_or_load(resume=False)
+trainer.train()
+```
+
+트레이닝 한 결과 이미지를 확인하는 과정은 tutorial 코드에서 바로 확인할 수 있기 때문에 생략하고, AP를 통해 결과값을 평가하는 부분을 추가해보고자 한다.
+AP metric을 이용하여 퍼포먼스를 측정할 수 있다. AP는 보통 70% 이상이면 좋게 본다고 하는데, 이 부분은 정확하지 않다.
+```python
+from detectron2.evaluation import COCOEvaluator, inference_on_dataset
+from detectron2.data import build_detection_test_loader
+evaluator = COCOEvaluator("balloon_val", ("bbox", "segm"), False, output_dir="./output/")
+val_loader = build_detection_test_loader(cfg, "balloon_val")
+print(inference_on_dataset(trainer.model, val_loader, evaluator))
+
+# 결과
+Running per image evaluation...
+Evaluate annotation type *bbox*
+COCOeval_opt.evaluate() finished in 0.01 seconds.
+Accumulating evaluation results...
+COCOeval_opt.accumulate() finished in 0.00 seconds.
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.668
+ Average Precision  (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.847
+ Average Precision  (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.797
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.239
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.549
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.795
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.222
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.704
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.766
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.567
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.659
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.847
+[07/08 22:50:53 d2.evaluation.coco_evaluation]: Evaluation results for bbox: 
+|   AP   |  AP50  |  AP75  |  APs   |  APm   |  APl   |
+|:------:|:------:|:------:|:------:|:------:|:------:|
+| 66.758 | 84.719 | 79.685 | 23.917 | 54.933 | 79.514 |
+
+Running per image evaluation...
+Evaluate annotation type *segm*
+COCOeval_opt.evaluate() finished in 0.01 seconds.
+Accumulating evaluation results...
+COCOeval_opt.accumulate() finished in 0.00 seconds.
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.768
+ Average Precision  (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.842
+ Average Precision  (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.840
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.058
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.565
+ Average Precision  (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.936
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.248
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.782
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.842
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.600
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.688
+ Average Recall     (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.953
+[07/08 22:50:53 d2.evaluation.coco_evaluation]: Evaluation results for segm: 
+|   AP   |  AP50  |  AP75  |  APs  |  APm   |  APl   |
+|:------:|:------:|:------:|:-----:|:------:|:------:|
+| 76.799 | 84.203 | 83.958 | 5.838 | 56.506 | 93.572 |
+OrderedDict([('bbox',
+              {'AP': 66.7575984802854,
+               'AP50': 84.71906024215401,
+               'AP75': 79.6850976022887,
+               'APl': 79.51426848548515,
+               'APm': 54.933394319629045,
+               'APs': 23.917443214909724}),
+             ('segm',
+              {'AP': 76.79883944079043,
+               'AP50': 84.20295316611471,
+               'AP75': 83.95779282808186,
+               'APl': 93.57150630750836,
+               'APm': 56.50588544163433,
+               'APs': 5.8381956414264895})])
+```
 
 ### Reference
 * [갈아먹는 Object Detection](https://yeomko.tistory.com/13?category=888201)
@@ -297,4 +565,5 @@ assert torch.__version__.startswith("1.8")   # need to manually install torch 1.
 * [Understanding feature pyramid networks for object detection](https://jonathan-hui.medium.com/understanding-feature-pyramid-networks-for-object-detection-fpn-45b227b9106c)
 * [교수님 강의자료]()
 * [detectron2 github](https://github.com/facebookresearch/detectron2)
-* [detectron2 documentation](https://detectron2.readthedocs.io/en/latest/tutorials/getting_started.html)
\ No newline at end of file
+* [detectron2 documentation](https://detectron2.readthedocs.io/en/latest/tutorials/getting_started.html)
+* [물체 검출 알고리즘 성능 평가 방법 AP의 이해](https://bskyvision.com/465)
\ No newline at end of file