megadetector 5.0.7__py3-none-any.whl → 5.0.9__py3-none-any.whl

data_management/resize_coco_dataset.py

@@ -1,11 +1,11 @@
-########
-#
-# resize_coco_dataset.py
-#
-# Given a COCO-formatted dataset, resize all the images to a target size,
-# scaling bounding boxes accordingly.
-#
-########
+"""
+
+resize_coco_dataset.py
+
+Given a COCO-formatted dataset, resizes all the images to a target size,
+scaling bounding boxes accordingly.
+
+"""
 
 #%% Imports and constants
 
@@ -26,31 +26,31 @@ from md_visualization.visualization_utils import \
 def resize_coco_dataset(input_folder,input_filename,
                         output_folder,output_filename,
                         target_size=(-1,-1),
-                        correct_size_image_handling='copy',
-                        right_edge_quantization_threshold=None):
+                        correct_size_image_handling='copy'):
     """
-    Given a COCO-formatted dataset (images in input_folder, data in input_filename), resize 
-    all the images to a target size (in output_folder) and scale bounding boxes accordingly
-    (in output_filename).
-    
-    target_size should be a tuple/list of ints, length 2.  If either dimension is -1, aspect ratio
-    will be preserved.  If both dimensions are -1, this means "keep the original size".  If 
-    both dimensions are -1 and correct_size_image_handling is copy, this function is basically 
-    a no-op, although you might still use it for right_edge_quantization_threshold.
-    
-    correct_size_image_handling can be 'copy' (in which case the original image is just copied 
-    to the output folder) or 'rewrite' (in which case the image is opened via PIL and re-written,
-    attempting to preserve the same quality).  The only reason to do this is the case where 
-    you're superstitious about biases coming from images in a training set being written
-    by different image encoders.
+    Given a COCO-formatted dataset (images in input_folder, data in input_filename), resizes
+    all the images to a target size (in output_folder) and scales bounding boxes accordingly.
+    
+    Args:
+        input_folder (str): the folder where images live; filenames in [input_filename] should 
+            be relative to [input_folder]
+        input_filename (str): the (input) COCO-formatted .json file containing annotations
+        output_folder (str): the folder to which we should write resized images; can be the
+            same as [input_folder], in which case images are over-written
+        output_filename (str): the COCO-formatted .json file we should generate that refers to
+            the resized images
+        target_size (list or tuple of ints): this should be tuple/list of ints, with length 2 (w,h).
+            If either dimension is -1, aspect ratio will be preserved.  If both dimensions are -1, this means 
+            "keep the original size".  If  both dimensions are -1 and correct_size_image_handling is copy, this 
+            function is basically a no-op.    
+        correct_size_image_handling (str): can be 'copy' (in which case the original image is just copied 
+            to the output folder) or 'rewrite' (in which case the image is opened via PIL and re-written,
+            attempting to preserve the same quality).  The only reason to do use 'rewrite' 'is the case where 
+            you're superstitious about biases coming from images in a training set being written by different 
+            image encoders.
    
-    right_edge_quantization_threshold is an off-by-default hack to adjust large datasets where 
-    boxes that really should be running off the right side of the image only extend like 99%
-    of the way there, due to what appears to be a slight bias inherent to MD.  If a box extends
-    within [right_edge_quantization_threshold] (a small number, from 0 to 1, but probably around 
-    0.02) of the right edge of the image, it will be extended to the far right edge.
-    
-    Returns the COCO database with resized images.
+    Returns:
+        dict: the COCO database with resized images, identical to the content of [output_filename]
     """
     
     # Read input data
@@ -126,15 +126,6 @@ def resize_coco_dataset(input_folder,input_filename,
                             bbox[2] * width_scale,
                             bbox[3] * height_scale]
                 
-                # Do we need to quantize this box?
-                if right_edge_quantization_threshold is not None and \
-                    right_edge_quantization_threshold > 0:
-                    bbox_right_edge_abs = bbox[0] + bbox[2]
-                    bbox_right_edge_norm = bbox_right_edge_abs / output_w
-                    bbox_right_edge_distance = (1.0 - bbox_right_edge_norm)
-                    if bbox_right_edge_distance < right_edge_quantization_threshold:
-                        bbox[2] = output_w - bbox[0]
-                
                 ann['bbox'] = bbox
             
             # ...if this annotation has a box
@@ -169,13 +160,10 @@ if False:
     
     correct_size_image_handling = 'rewrite'
     
-    right_edge_quantization_threshold = 0.015
-    
     resize_coco_dataset(input_folder,input_filename,
                         output_folder,output_filename,
                         target_size=target_size,
-                        correct_size_image_handling=correct_size_image_handling,
-                        right_edge_quantization_threshold=right_edge_quantization_threshold)
+                        correct_size_image_handling=correct_size_image_handling)
     
     
     #%% Preview

data_management/wi_download_csv_to_coco.py

@@ -0,0 +1,246 @@
+"""
+
+wi_download_csv_to_coco.py
+
+Converts a .csv file from a Wildlife Insights project export to a COCO camera traps .json file.
+
+Currently assumes that common names are unique identifiers, which is convenient but unreliable.
+
+"""
+
+#%% Imports and constants
+
+import os
+import json
+import pandas as pd
+
+from tqdm import tqdm
+from collections import defaultdict
+
+from md_visualization import visualization_utils as vis_utils
+from md_utils.ct_utils import isnan
+
+wi_extra_annotation_columns = \
+    ('is_blank','identified_by','wi_taxon_id','class','order','family','genus','species','uncertainty',
+             'number_of_objects','age','sex','animal_recognizable','individual_id','individual_animal_notes',
+             'behavior','highlighted','markings')
+
+wi_extra_image_columns = ('project_id','deployment_id')
+
+def _make_location_id(project_id,deployment_id):    
+    return 'project_' + str(project_id) + '_deployment_' + deployment_id
+
+default_category_remappings = {
+    'Homo Species':'Human',
+    'Human-Camera Trapper':'Human',
+    'No CV Result':'Unknown'
+}
+
+
+#%% Main function
+
+def wi_download_csv_to_coco(csv_file_in,
+                            coco_file_out=None,
+                            image_folder=None,
+                            validate_images=False,
+                            gs_prefix=None,
+                            verbose=True,
+                            category_remappings=default_category_remappings):
+    """
+    Converts a .csv file from a Wildlife Insights project export to a COCO 
+    Camera Traps .json file.
+    
+    Args:
+        csv_file_in (str): the downloaded .csv file we should convert to COCO
+        coco_file_out (str, optional): the .json file we should write; if [coco_file_out] is None, 
+            uses [csv_file_in].json
+        image_folder (str, optional): the folder where images live, only relevant if 
+            [validate_images] is True
+        validate_images (bool, optional): whether to check images for corruption and load
+            image sizes; if this is True, [image_folder] must be a valid folder
+        gs_prefix (str, optional): a string to remove from GS URLs to convert to path names... 
+            for example, if your gs:// URLs look like:
+    
+            `gs://11234134_xyz/deployment/55554/dfadfasdfs.jpg`
+    
+            ...and you specify gs_prefix='11234134_xyz/deployment/', the filenames in
+            the .json file will look like:
+        
+            `55554/dfadfasdfs.jpg`
+        verbose (bool, optional): enable additional debug console output
+        category_remappings (dict, optional): str --> str dict that maps any number of
+            WI category names to output category names; for example defaults to mapping
+            "Homo Species" to "Human", but leaves 99.99% of categories unchanged.        
+            
+    Returns: 
+        dict: COCO-formatted data, identical to what's written to [coco_file_out]
+    """
+    
+    ##%% Create COCO dictionaries
+    
+    category_name_to_id = {}
+    category_name_to_id['empty'] = 0
+    
+    df = pd.read_csv(csv_file_in)
+    
+    print('Read {} rows from {}'.format(len(df),csv_file_in))
+    
+    image_id_to_image = {}
+    image_id_to_annotations = defaultdict(list)
+    
+    # i_row = 0; row = df.iloc[i_row]
+    for i_row,row in df.iterrows():
+        
+        image_id = row['image_id']
+        
+        if image_id not in image_id_to_image:
+            
+            im = {}
+            image_id_to_image[image_id] = im
+            
+            im['id'] = image_id
+            
+            gs_url = row['location']
+            assert gs_url.startswith('gs://')
+            
+            file_name = gs_url.replace('gs://','')
+            if gs_prefix is not None:
+                file_name = file_name.replace(gs_prefix,'')
+                
+            location_id = _make_location_id(row['project_id'],row['deployment_id'])
+            im['file_name'] = file_name
+            im['location'] = location_id
+            im['datetime'] = row['timestamp']
+            
+            im['wi_image_info'] = {}
+            for s in wi_extra_image_columns:
+                im['wi_image_info'][s] = str(row[s])
+            
+        else:
+            
+            im = image_id_to_image[image_id]
+            assert im['datetime'] == row['timestamp']
+            location_id = _make_location_id(row['project_id'],row['deployment_id'])
+            assert im['location'] == location_id
+            
+        category_name = row['common_name']
+        if category_remappings is not None and category_name in category_remappings:
+            category_name = category_remappings[category_name]
+            
+        if category_name == 'Blank':
+            category_name = 'empty'
+            assert row['is_blank'] == 1
+        else:
+            assert row['is_blank'] == 0
+        assert isinstance(category_name,str)
+        if category_name in category_name_to_id:
+            category_id = category_name_to_id[category_name]
+        else:
+            category_id = len(category_name_to_id)
+            category_name_to_id[category_name] = category_id
+        
+        ann = {}
+        ann['image_id'] = image_id
+        annotations_this_image = image_id_to_annotations[image_id]
+        annotation_number = len(annotations_this_image)
+        ann['id'] = image_id + '_' + str(annotation_number).zfill(2)        
+        ann['category_id'] = category_id
+        annotations_this_image.append(ann)
+        
+        extra_info = {}
+        for s in wi_extra_annotation_columns:            
+            v = row[s]
+            if not isnan(v):
+                extra_info[s] = v
+        ann['wi_extra_info'] = extra_info
+        
+    # ...for each row
+    
+    images = list(image_id_to_image.values())
+    categories = []
+    for category_name in category_name_to_id:
+        category_id = category_name_to_id[category_name]
+        categories.append({'id':category_id,'name':category_name})
+    annotations = []
+    for image_id in image_id_to_annotations:
+        annotations_this_image = image_id_to_annotations[image_id]
+        for ann in annotations_this_image:
+            annotations.append(ann)
+    info = {'version':'1.00','description':'converted from WI export'}
+    info['source_file'] = csv_file_in
+    coco_data = {}
+    coco_data['info'] = info
+    coco_data['images'] = images
+    coco_data['annotations'] = annotations
+    coco_data['categories'] = categories
+    
+    
+    ##%% Validate images, add sizes        
+    
+    if validate_images:
+        
+        print('Validating images')
+        # TODO: trivially parallelizable
+        
+        assert os.path.isdir(image_folder), \
+            'Must specify a valid image folder if you specify validate_images=True'
+            
+        # im = images[0]
+        for im in tqdm(images):
+            file_name_relative = im['file_name']
+            file_name_abs = os.path.join(image_folder,file_name_relative)
+            assert os.path.isfile(file_name_abs)
+                
+            im['corrupt'] = False
+            try:
+                pil_im = vis_utils.load_image(file_name_abs)
+            except Exception:
+                im['corrupt'] = True
+            if not im['corrupt']:
+                im['width'] = pil_im.width
+                im['height'] = pil_im.height
+    
+    
+    ##%% Write output json
+        
+    if coco_file_out is None:        
+        coco_file_out = csv_file_in + '.json'
+        
+    with open(coco_file_out,'w') as f:
+        json.dump(coco_data,f,indent=1)
+
+
+    ##%% Validate output
+    
+    from data_management.databases.integrity_check_json_db import \
+        IntegrityCheckOptions,integrity_check_json_db
+    options = IntegrityCheckOptions()
+    options.baseDir = image_folder
+    options.bCheckImageExistence = True
+    options.verbose = verbose
+    _ = integrity_check_json_db(coco_file_out,options)
+    
+    return coco_data
+
+# ...def wi_download_csv_to_coco(...)    
+
+
+#%% Interactive driver
+
+if False:
+    
+    #%%
+    
+    base_folder = r'a/b/c'
+    csv_file_in = os.path.join(base_folder,'images.csv')
+    coco_file_out = None
+    gs_prefix = 'a_b_c_main/'
+    image_folder = os.path.join(base_folder,'images')
+    validate_images = False
+    verbose = True
+    category_remappings = default_category_remappings
+
+
+#%% Command-line driver
+
+# TODO

data_management/yolo_output_to_md_output.py

@@ -1,43 +1,38 @@
-########
-#
-# yolo_output_to_md_output.py
-#
-# Converts the output of YOLOv5's detect.py or val.py to the MD API output format.
-#
-# Command-line driver not done yet, this has only been run interactively.
-#
-########
-
-### Converting .txt files ###
-
-#
-# detect.py writes a .txt file per image, in YOLO training format.  Converting from this
-# format does not currently support recursive results, since detect.py doesn't save filenames
-# in a way that allows easy inference of folder names.  Requires access to the input
-# images, because the YOLO format uses the *absence* of a results file to indicate that
-# no detections are present.
-#
-# YOLOv5 output has one text file per image, like so:
-#
-# 0 0.0141693 0.469758 0.0283385 0.131552 0.761428 
-#
-# That's [class, x_center, y_center, width_of_box, height_of_box, confidence]
-#
-# val.py can write in this format as well, using the --save-txt argument.
-#
-# In both cases, a confidence value is only written to each line if you include the --save-conf
-# argument.  Confidence values are required by this conversion script.
-#
-
-### Converting .json files ###
-
-#
-# val.py can also write a .json file in COCO-ish format.  It's "COCO-ish" because it's
-# just the "images" portion of a COCO .json file.
-#
-# Converting from this format also requires access to the original images, since the format
-# written by YOLOv5 uses absolute coordinates, but MD results are in relative coordinates.
-#
+"""
+
+yolo_output_to_md_output.py
+
+Converts the output of YOLOv5's detect.py or val.py to the MD API output format.
+
+**Converting .txt files**
+
+detect.py writes a .txt file per image, in YOLO training format.  Converting from this
+format does not currently support recursive results, since detect.py doesn't save filenames
+in a way that allows easy inference of folder names.  Requires access to the input
+images, because the YOLO format uses the *absence* of a results file to indicate that
+no detections are present.
+
+YOLOv5 output has one text file per image, like so:
+
+0 0.0141693 0.469758 0.0283385 0.131552 0.761428 
+
+That's [class, x_center, y_center, width_of_box, height_of_box, confidence]
+
+val.py can write in this format as well, using the --save-txt argument.
+
+In both cases, a confidence value is only written to each line if you include the --save-conf
+argument.  Confidence values are required by this conversion script.
+
+
+**Converting .json files**
+
+val.py can also write a .json file in COCO-ish format.  It's "COCO-ish" because it's
+just the "images" portion of a COCO .json file.
+
+Converting from this format also requires access to the original images, since the format
+written by YOLOv5 uses absolute coordinates, but MD results are in relative coordinates.
+
+"""
 
 #%% Imports and constants
 
@@ -51,9 +46,7 @@ from tqdm import tqdm
 
 from md_utils import path_utils
 from md_utils import ct_utils
-
 from md_visualization import visualization_utils as vis_utils
-
 from detection.run_detector import CONF_DIGITS, COORD_DIGITS
 
 
@@ -61,9 +54,16 @@ from detection.run_detector import CONF_DIGITS, COORD_DIGITS
 
 def read_classes_from_yolo_dataset_file(fn):
     """
-    Read a dictionary mapping integer class IDs to class names from a YOLOv5/YOLOv8
+    Reads a dictionary mapping integer class IDs to class names from a YOLOv5/YOLOv8
     dataset.yaml file or a .json file.  A .json file should contain a dictionary mapping
     integer category IDs to string category names.
+    
+    Args:
+        fn (str): YOLOv5/YOLOv8 dataset file with a .yml or .yaml extension, or a .json file 
+            mapping integer category IDs to category names.
+            
+    Returns:
+        dict: a mapping from integer category IDs to category names
     """
         
     if fn.endswith('.yml') or fn.endswith('.yaml'):
@@ -92,45 +92,42 @@ def read_classes_from_yolo_dataset_file(fn):
         raise ValueError('Unrecognized category file type: {}'.format(fn))
         
     assert len(category_id_to_name) > 0, 'Failed to read class mappings from {}'.format(fn)
+    
     return category_id_to_name
     
 
-def yolo_json_output_to_md_output(yolo_json_file, image_folder,
-                                  output_file, yolo_category_id_to_name,                              
+def yolo_json_output_to_md_output(yolo_json_file, 
+                                  image_folder,
+                                  output_file, 
+                                  yolo_category_id_to_name,                              
                                   detector_name='unknown',
                                   image_id_to_relative_path=None,
                                   offset_yolo_class_ids=True,
                                   truncate_to_standard_md_precision=True,
                                   image_id_to_error=None):
     """
-    Convert a YOLOv5 .json file to MD .json format.
+    Converts a YOLOv5/YOLOv8 .json file to MD .json format.
     
     Args:
         
-    - yolo_json_file: the .json file to convert from YOLOv5 format to MD output format.
-    
-    - image_folder: the .json file contains relative path names, this is the path base.
-    
-    - yolo_category_id_to_name: the .json file contains only numeric identifiers for
-      categories, but we want names and numbers for the output format; this is a 
-      dict mapping numbers to names.  Can also be a YOLOv5 dataset.yaml file.
-    
-    - detector_name: a string that gets put in the output file, not otherwise used within
-      this function.
-    
-    - image_id_to_relative_path: YOLOv5 .json uses only basenames (e.g. abc1234.JPG);
-      by default these will be appended to the input path to create pathnames, so if you
-      have a flat folder, this is fine.  If you want to map base names to relative paths, use
-      this dict.
-    
-    - offset_yolo_class_ids: YOLOv5 class IDs always start at zero; if you want to make the 
-      output classes start at 1, set offset_yolo_class_ids to True.
-    
-    - truncate_to_standard_md_precision: YOLOv5 .json includes lots of (not-super-meaningful)
-      precision, set this to truncate to COORD_DIGITS and CONF_DIGITS.
-    
-    - image_id_to_error: if you want to include image IDs in the output file for which you couldn't
-      prepare the input file in the first place due to errors, include them here.
+        yolo_json_file (str): the .json file to convert from YOLOv5 format to MD output format
+        image_folder (str): the .json file contains relative path names, this is the path base
+        yolo_category_id_to_name (str or dict): the .json results file contains only numeric 
+            identifiers for categories, but we want names and numbers for the output format; 
+            yolo_category_id_to_name provides that mapping either as a dict or as a YOLOv5 
+            dataset.yaml file.
+        detector_name (str, optional): a string that gets put in the output file, not otherwise 
+            used within this function
+        image_id_to_relative_path (dict, optional): YOLOv5 .json uses only basenames (e.g. 
+            abc1234.JPG); by default these will be appended to the input path to create pathnames.
+            If you have a flat folder, this is fine.  If you want to map base names to relative paths in
+            a more complicated way, use this parameter.   
+        offset_yolo_class_ids (bool, optional): YOLOv5 class IDs always start at zero; if you want to 
+            make the output classes start at 1, set offset_yolo_class_ids to True.    
+        truncate_to_standard_md_precision (bool, optional): YOLOv5 .json includes lots of 
+            (not-super-meaningful) precision, set this to truncate to COORD_DIGITS and CONF_DIGITS.
+        image_id_to_error (dict, optional): if you want to include image IDs in the output file for which 
+            you couldn't prepare the input file in the first place due to errors, include them here.
     """    
         
     assert os.path.isfile(yolo_json_file), \
@@ -314,14 +311,25 @@ def yolo_json_output_to_md_output(yolo_json_file, image_folder,
 # ...def yolo_json_output_to_md_output(...)
     
 
-def yolo_txt_output_to_md_output(input_results_folder, image_folder,
-                                 output_file, detector_tag=None):
+def yolo_txt_output_to_md_output(input_results_folder, 
+                                 image_folder,
+                                 output_file, 
+                                 detector_tag=None):
     """
-    Converts a folder of YOLO-outptu .txt files to MD .json format.
+    Converts a folder of YOLO-output .txt files to MD .json format.
     
     Less finished than the .json conversion function; this .txt conversion assumes 
     a hard-coded mapping representing the standard MD categories (in MD indexing, 
     1/2/3=animal/person/vehicle; in YOLO indexing, 0/1/2=animal/person/vehicle).
+    
+    Args:
+        input_results_folder (str): the folder containing YOLO-output .txt files
+        image_folder (str): the folder where images live, may be the same as
+            [input_results_folder]
+        output_file (str): the MD-formatted .json file to which we should write
+            results
+        detector_tag (str, optional): string to put in the 'detector' field in the
+            output file            
     """
     
     assert os.path.isdir(input_results_folder)
@@ -426,3 +434,8 @@ if False:
     image_folder = os.path.expanduser('~/data/KRU-test')
     output_file = os.path.expanduser('~/data/mdv5a-yolo-pt-kru.json')    
     yolo_txt_output_to_md_output(input_results_folder,image_folder,output_file)
+
+
+#%% Command-line driver
+
+# TODO