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

detection/run_inference_with_yolov5_val.py

@@ -1,39 +1,47 @@
-########
-# 
-# run_inference_with_yolov5_val.py
-#
-# Runs a folder of images through MegaDetector (or another YOLOv5 model) with YOLOv5's 
-# val.py, converting the output to the standard MD format.  The main goal is to leverage
-# YOLO's test-time augmentation tools.
-#
-# YOLOv5's val.py uses each file's base name as a unique identifier, which doesn't work 
-# when you have typical camera trap images like:
-#
-# a/b/c/RECONYX0001.JPG
-# d/e/f/RECONYX0001.JPG
-#
-# ...so this script jumps through a bunch of hoops to put a symlinks in a flat
-# folder, run YOLOv5 on that folder, and map the results back to the real files.
-#
-# Currently requires the user to supply the path where a working YOLOv5 install lives,
-# and assumes that the current conda environment is all set up for YOLOv5.
-#
-# By default, this script uses symlinks to format the input images in a way that YOLOv5's 
-# val.py likes.  This requires admin privileges on Windows... actually technically this only 
-# requires permissions to create symbolic links, but I've never seen a case where someone has
-# that permission and *doesn't* have admin privileges.  If you are running this script on
-# Windows and you don't have admin privileges, use --no_use_symlinks.
-#
-# TODO:
-#
-# * Multiple GPU support
-#
-# * Checkpointing
-#
-# * Support alternative class names at the command line (currently defaults to MD classes,
-#   though other class names can be supplied programmatically)
-#
-########
+"""
+
+run_inference_with_yolov5_val.py
+
+Runs a folder of images through MegaDetector (or another YOLOv5/YOLOv8 model) with YOLO's
+val.py, converting the output to the standard MD format.  The reasons this script exists,
+as an alternative to the standard run_detector_batch.py are:
+    
+* This script provides access to YOLO's test-time augmentation tools.
+* This script serves a reference implementation: by any reasonable definition, YOLOv5's
+  val.py produces the "correct" result for any image, since it matches what was used in 
+  training.
+* This script works for any Ultralytics detection model, including YOLOv8 models  
+
+YOLOv5's val.py uses each file's base name as a unique identifier, which doesn't work 
+when you have typical camera trap images like:
+
+* a/b/c/RECONYX0001.JPG
+* d/e/f/RECONYX0001.JPG
+
+...both of which would just be "RECONYX0001.JPG".  So this script jumps through a bunch of 
+hoops to put a symlinks in a flat folder, run YOLOv5 on that folder, and map the results back 
+to the real files.
+
+If you are running a YOLOv5 model, this script currently requires the caller to supply the path
+where a working YOLOv5 install lives, and assumes that the current conda environment is all set up for 
+YOLOv5.  If you are running a YOLOv8 model, the folder doesn't matter, but it assumes that ultralytics
+tools are available in the current environment.
+
+By default, this script uses symlinks to format the input images in a way that YOLO's 
+val.py likes, as per above.  This requires admin privileges on Windows... actually technically this 
+only requires permissions to create symbolic links, but I've never seen a case where someone has
+that permission and *doesn't* have admin privileges.  If you are running this script on
+Windows and you don't have admin privileges, use --no_use_symlinks, which will make copies of images,
+rather than using symlinks.
+
+TODO:
+
+* Multiple GPU support
+* Checkpointing
+* Support alternative class names at the command line (currently defaults to MD classes,
+  though other class names can be supplied programmatically)
+
+"""
 
 #%% Imports
 
@@ -60,57 +68,112 @@ default_image_size_with_no_augmentation = 1280
 #%% Options class
 
 class YoloInferenceOptions:
-        
+    """
+    Parameters that control the behavior of run_inference_with_yolov5_val(), including 
+    the input/output filenames.
+    """
+    
     ## Required ##
     
+    #: Folder of images to process
     input_folder = None
+    
+    #: Model filename (ending in .pt), or a well-known model name (e.g. "MDV5A")
     model_filename = None
+    
+    #: .json output file, in MD results format
     output_file = None
     
+    
     ## Optional ##
     
-    # Required for older YOLOv5 inference, not for newer ulytralytics inference
+    #: Required for older YOLOv5 inference, not for newer ulytralytics/YOLOv8 inference
     yolo_working_folder = None
     
-    # Currently 'yolov5' and 'ultralytics' are supported, and really these are proxies for
-    # "the yolov5 repo" and "the ultralytics repo" (typically YOLOv8).
+    #: Currently 'yolov5' and 'ultralytics' are supported, and really these are proxies for
+    #: "the yolov5 repo" and "the ultralytics repo".
     model_type = 'yolov5' 
 
+    #: Image size to use; this is a single int, which in ultralytics's terminology means
+    #: "scale the long side of the image to this size, and preserve aspect ratio".
     image_size = default_image_size_with_augmentation
+    
+    #: Detections below this threshold will not be included in the output file
     conf_thres = '0.001'
+    
+    #: Batch size... has no impact on results, but may create memory issues if you set
+    #: this to large values
     batch_size = 1
+    
+    #: Device string: typically '0' for GPU 0, '1' for GPU 1, etc., or 'cpu'
     device_string = '0'
+    
+    #: Should we enable test-time augmentation?
     augment = True
+    
+    #: Should we enable half-precision inference?
     half_precision_enabled = None
     
+    #: Where should we stash the temporary symlinks used to give unique identifiers to image files?
+    #:
+    #: If this is None, we'll create a folder in system temp space.
     symlink_folder = None
+    
+    #: Should we use symlinks to give unique identifiers to image files (vs. copies)?
     use_symlinks = True
     
+    #: Temporary folder to stash intermediate YOLO results.
+    #:
+    #: If this is None, we'll create a folder in system temp space.    
     yolo_results_folder = None
     
+    #: Should we remove the symlink folder when we're done?
     remove_symlink_folder = True
+    
+    #: Should we remove the intermediate results folder when we're done?
     remove_yolo_results_folder = True
     
-    # These are deliberately offset from the standard MD categories; YOLOv5
-    # needs categories IDs to start at 0.
-    #
-    # This can also be a string that points to a YOLOv5 dataset.yaml file.
+    #: These are deliberately offset from the standard MD categories; YOLOv5
+    #: needs categories IDs to start at 0.
+    #:
+    #: This can also be a string that points to a YOLO dataset.yaml file.
     yolo_category_id_to_name = {0:'animal',1:'person',2:'vehicle'}
     
-    # 'error','skip','overwrite'
+    #: What should we do if the output file already exists?
+    #:
+    #: Can be 'error', 'skip', or 'overwrite'.
     overwrite_handling = 'skip'
     
+    #: If True, we'll do a dry run that lets you preview the YOLO val command, without
+    #: actually running it.
     preview_yolo_command_only = False
     
+    #: By default, if any errors occur while we're copying images or creating symlinks, it's
+    #: game over.  If this is True, those errors become warnings, and we plow ahead.
     treat_copy_failures_as_warnings = False
     
+    #: Save YOLO console output
     save_yolo_debug_output = False
+    
+    #: Whether to search for images recursively within [input_folder]
+    recursive = True
             
     
+# ...YoloInferenceOptions()
+
+    
 #%% Main function
 
 def run_inference_with_yolo_val(options):
-
+    """
+    Runs a folder of images through MegaDetector (or another YOLOv5/YOLOv8 model) with YOLO's
+    val.py, converting the output to the standard MD format.
+    
+    Args: 
+        options (YoloInferenceOptions): all the parameters used to control this process,
+            including filenames; see YoloInferenceOptions for details            
+    """
+    
     ##%% Input and path handling
     
     if options.model_type == 'yolov8':
@@ -203,7 +266,7 @@ def run_inference_with_yolo_val(options):
     ##%% Enumerate images
     
     if os.path.isdir(options.input_folder):
-        image_files_absolute = path_utils.find_images(options.input_folder,recursive=True)
+        image_files_absolute = path_utils.find_images(options.input_folder,recursive=options.recursive)
     else:
         assert os.path.isfile(options.input_folder)
         with open(options.input_folder,'r') as f:            
@@ -381,7 +444,7 @@ def run_inference_with_yolo_val(options):
     # YOLO console output contains lots of ANSI escape codes, remove them for easier parsing
     yolo_console_output = [string_utils.remove_ansi_codes(s) for s in yolo_console_output]
     
-    # Find errors that occrred during the initial corruption check; these will not be included in the
+    # Find errors that occurred during the initial corruption check; these will not be included in the
     # output.  Errors that occur during inference will be handled separately.
     yolo_read_failures = []
     
@@ -518,7 +581,7 @@ def main():
         help='inference batch size (default {})'.format(options.batch_size))
     parser.add_argument(
         '--half_precision_enabled', default=None, type=int,
-        help='use half-precision-inference (1 or 0) (default is the underlying model\'s default, probably half for YOLOv8 and full for YOLOv8')
+        help='use half-precision-inference (1 or 0) (default is the underlying model\'s default, probably full for YOLOv8 and half for YOLOv5')
     parser.add_argument(
         '--device_string', default=options.device_string, type=str,
         help='CUDA device specifier, typically "0" or "1" for CUDA devices, "mps" for M1/M2 devices, or "cpu" (default {})'.format(options.device_string))
@@ -553,6 +616,10 @@ def main():
         '--save_yolo_debug_output', action='store_true',
         help='write yolo console output to a text file in the results folder, along with additional debug files')
     
+    parser.add_argument(
+        '--nonrecursive', action='store_true',
+        help='Disable recursive folder processing')
+    
     parser.add_argument(
         '--preview_yolo_command_only', action='store_true',
         help='don\'t run inference, just preview the YOLO inference command (still creates symlinks)')
@@ -592,6 +659,7 @@ def main():
     if args.yolo_dataset_file is not None:
         options.yolo_category_id_to_name = args.yolo_dataset_file
         
+    options.recursive = (not options.nonrecursive)
     options.remove_symlink_folder = (not options.no_remove_symlink_folder)
     options.remove_yolo_results_folder = (not options.no_remove_yolo_results_folder)
     options.use_symlinks = (not options.no_use_symlinks)
@@ -599,8 +667,7 @@ def main():
             
     print(options.__dict__)
     
-    run_inference_with_yolo_val(options)
-    
+    run_inference_with_yolo_val(options)    
 
 if __name__ == '__main__':
     main()

detection/run_tiled_inference.py

@@ -1,24 +1,26 @@
-########
-#
-# run_tiled_inference.py
-#
-# Run inference on a folder, fist splitting each image up into tiles of size
-# MxN (typically the native inference size of your detector), writing those
-# tiles out to a temporary folder, then de-duplicating the results before merging
-# them back into a set of detections that make sense on the original images.
-#
-# This approach will likely fail to detect very large animals, so if you expect both large 
-# and small animals (in terms of pixel size), this script is best used in 
-# conjunction with a traditional inference pass that looks at whole images.
-#
-# Currently requires temporary storage at least as large as the input data, generally
-# a lot more than that (depending on the overlap between adjacent tiles).  This is 
-# inefficient, but easy to debug.
-#
-# Programmatic invocation supports using YOLOv5's inference scripts (and test-time
-# augmentation); the command-line interface only supports standard inference right now.
-#
-########
+"""
+
+run_tiled_inference.py
+
+**This script is experimental, YMMV.**
+
+Runs inference on a folder, fist splitting each image up into tiles of size
+MxN (typically the native inference size of your detector), writing those
+tiles out to a temporary folder, then de-duplicating the resulting detections before 
+merging them back into a set of detections that make sense on the original images.
+
+This approach will likely fail to detect very large animals, so if you expect both large 
+and small animals (in terms of pixel size), this script is best used in 
+conjunction with a traditional inference pass that looks at whole images.
+
+Currently requires temporary storage at least as large as the input data, generally
+a lot more than that (depending on the overlap between adjacent tiles).  This is 
+inefficient, but easy to debug.
+
+Programmatic invocation supports using YOLOv5's inference scripts (and test-time
+augmentation); the command-line interface only supports standard inference right now.
+
+"""
 
 #%% Imports and constants
 
@@ -54,17 +56,24 @@ parallelization_uses_threads = False
 
 def get_patch_boundaries(image_size,patch_size,patch_stride=None):
     """
-    Get a list of patch starting coordinates (x,y) given an image size (w,h)
-    and a stride (x,y).  Stride defaults to half the patch size.
+    Computes a list of patch starting coordinates (x,y) given an image size (w,h)
+    and a stride (x,y)
     
-    patch_stride can also be a single float, in which case that is interpreted 
-    as the stride relative to the patch size (0.1 == 10% stride).
-    
-    Patch size is guaranteed, stride may deviate to make sure all pixels are covered.
+    Patch size is guaranteed, but the stride may deviate to make sure all pixels are covered.
     I.e., we move by regular strides until the current patch walks off the right/bottom,
     at which point it backs up to one patch from the end.  So if your image is 15
     pixels wide and you have a stride of 10 pixels, you will get starting positions 
     of 0 (from 0 to 9) and 5 (from 5 to 14).
+    
+    Args:
+        image_size (tuple): size of the image you want to divide into patches, as a length-2 tuple (w,h)
+        patch_size (tuple): patch size into which you want to divide an image, as a length-2 tuple (w,h)
+        patch_stride (tuple or float, optional): stride between patches, as a length-2 tuple (x,y), or a 
+            float; if this is a float, it's interpreted as the stride relative to the patch size 
+            (0.1 == 10% stride).  Defaults to half the patch size.
+
+    Returns:
+        list: list of length-2 tuples, each representing the x/y start position of a patch        
     """
     
     if patch_stride is None:
@@ -163,23 +172,50 @@ def get_patch_boundaries(image_size,patch_size,patch_stride=None):
 
 
 def patch_info_to_patch_name(image_name,patch_x_min,patch_y_min):
+    """
+    Gives a unique string name to an x/y coordinate, e.g. turns ("a.jpg",10,20) into
+    "a.jpg_0010_0020".
     
+    Args:
+        image_name (str): image identifier
+        patch_x_min (int): x coordinate
+        patch_y_min (int): y coordinate
+    
+    Returns:
+        str: name for this patch, e.g. "a.jpg_0010_0020"
+    """
     patch_name = image_name + '_' + \
         str(patch_x_min).zfill(4) + '_' + str(patch_y_min).zfill(4)
     return patch_name
 
 
-def extract_patch_from_image(im,patch_xy,patch_size,
-                             patch_image_fn=None,patch_folder=None,image_name=None,overwrite=True):
+def extract_patch_from_image(im,
+                             patch_xy,
+                             patch_size,
+                             patch_image_fn=None,
+                             patch_folder=None,
+                             image_name=None,
+                             overwrite=True):
     """
-    Extracts a patch from the provided image, writing the patch out to patch_image_fn.
-    [im] can be a string or a PIL image.
-    
-    patch_xy is a length-2 tuple specifying the upper-left corner of the patch.
-    
-    image_name and patch_folder are only required if patch_image_fn is None.
-    
-    Returns a dictionary with fields xmin,xmax,ymin,ymax,patch_fn.
+    Extracts a patch from the provided image, and writes that patch out to a new file.
+    
+    Args:
+        im (str or Image): image from which we should extract a patch, can be a filename or
+            a PIL Image object.
+        patch_xy (tuple): length-2 tuple of ints (x,y) representing the upper-left corner 
+            of the patch to extract
+        patch_size (tuple): length-2 tuple of ints (w,h) representing the size of the 
+            patch to extract
+        patch_image_fn (str, optional): image filename to write the patch to; if this is None
+            the filename will be generated from [image_name] and the patch coordinates
+        patch_folder (str, optional): folder in which the image lives; only used to generate
+            a patch filename, so only required if [patch_image_fn] is None
+        image_name (str, optional): the identifier of the source image; only used to generate
+            a patch filename, so only required if [patch_image_fn] is None
+        overwrite (bool, optional): whether to overwrite an existing patch image
+    
+    Returns:
+        dict: a dictionary with fields xmin,xmax,ymin,ymax,patch_fn
     """
     
     if isinstance(im,str):
@@ -223,10 +259,20 @@ def extract_patch_from_image(im,patch_xy,patch_size,
     
     return patch_info
 
+# ...def extract_patch_from_image(...)
+
 
 def in_place_nms(md_results, iou_thres=0.45, verbose=True):
     """
-    Run torch.ops.nms in-place on MD-formatted detection results    
+    Run torch.ops.nms in-place on MD-formatted detection results.
+    
+    Args:
+        md_results (dict): detection results for a list of images, in MD results format (i.e., 
+            containing a list of image dicts with the key 'images', each of which has a list
+            of detections with the key 'detections')
+        iou_thres (float, optional): IoU threshold above which we will treat two detections as
+            redundant
+        verbose (bool, optional): enable additional debug console output
     """
     
     n_detections_before = 0
@@ -343,7 +389,7 @@ def run_tiled_inference(model_file, image_folder, tiling_folder, output_file,
                         overwrite_tiles=True,
                         image_list=None):
     """
-    Run inference using [model_file] on the images in [image_folder], fist splitting each image up 
+    Runs inference using [model_file] on the images in [image_folder], fist splitting each image up 
     into tiles of size [tile_size_x] x [tile_size_y], writing those tiles to [tiling_folder],
     then de-duplicating the results before merging them back into a set of detections that make 
     sense on the original images and writing those results to [output_file].  
@@ -360,7 +406,32 @@ def run_tiled_inference(model_file, image_folder, tiling_folder, output_file,
     
     if yolo_inference_options is supplied, it should be an instance of YoloInferenceOptions; in 
     this case the model will be run with run_inference_with_yolov5_val.  This is typically used to 
-    run the model with test-time augmentation.          
+    run the model with test-time augmentation.
+    
+    Args:
+        model_file (str): model filename (ending in .pt), or a well-known model name (e.g. "MDV5A")
+        image_folder (str): the folder of images to proess (always recursive)
+        tiling_folder (str): folder for temporary tile storage; see caveats above
+        output_file (str): .json file to which we should write MD-formatted results
+        tile_size_x (int, optional): tile width
+        tile_size_y (int, optional): tile height
+        tile_overlap (float, optional): overlap between adjacenet tiles, as a fraction of the
+            tile size
+        checkpoint_path (str, optional): checkpoint path; passed directly to run_detector_batch; see
+            run_detector_batch for details
+        checkpoint_frequency (int, optional): checkpoint frequency; passed directly to run_detector_batch; see
+            run_detector_batch for details
+        remove_tiles (bool, optional): whether to delete the tiles when we're done
+        yolo_inference_options (YoloInferenceOptions, optional): if not None, will run inference with
+            run_inference_with_yolov5_val.py, rather than with run_detector_batch.py, using these options
+        n_patch_extraction_workers (int, optional): number of workers to use for patch extraction;
+            set to <= 1 to disable parallelization
+        image_list (list, optional): .json file containing a list of specific images to process.  If 
+            this is supplied, and the paths are absolute, [image_folder] will be ignored. If this is supplied,
+            and the paths are relative, they should be relative to [image_folder].
+    
+    Returns:
+        dict: MD-formatted results dictionary, identical to what's written to [output_file]
     """
 
     ##%% Validate arguments
@@ -823,12 +894,12 @@ def main():
         '--overwrite_handling',
         type=str,
         default='skip',
-        help=('behavior when the targt file exists (skip/overwrite/error) (default skip)'))
+        help=('Behavior when the target file exists (skip/overwrite/error) (default skip)'))
     parser.add_argument(
         '--image_list',
         type=str,
         default=None,
-        help=('a .json list of relative filenames (or absolute paths contained within image_folder) to include'))
+        help=('A .json list of relative filenames (or absolute paths contained within image_folder) to include'))
         
     if len(sys.argv[1:]) == 0:
         parser.print_help()

detection/tf_detector.py

@@ -1,11 +1,12 @@
-########
-#
-# tf_detector.py
-#
-# Module containing the class TFDetector for loading a TensorFlow detection model and
-# running inference.
-# 
-########
+"""
+
+tf_detector.py
+
+Module containing the class TFDetector, for loading and running a TensorFlow detection model.
+
+"""
+
+#%% Imports and constants
 
 import numpy as np
 
@@ -18,36 +19,41 @@ print('TensorFlow version:', tf.__version__)
 print('Is GPU available? tf.test.is_gpu_available:', tf.test.is_gpu_available())
 
 
+#%% Classes
+
 class TFDetector:
     """
     A detector model loaded at the time of initialization. It is intended to be used with
-    the MegaDetector (TF). The inference batch size is set to 1; code needs to be modified
-    to support larger batch sizes, including resizing appropriately.
+    TensorFlow-based versions of MegaDetector (v2, v3, or v4).  If someone can find v1, I 
+    suppose you could use this class for v1 also.
     """
     
-    # MegaDetector was trained with batch size of 1, and the resizing function is a part
-    # of the inference graph
+    #: TF versions of MD were trained with batch size of 1, and the resizing function is a 
+    #: part of the inference graph, so this is fixed.
+    #:
+    #: :meta private:  
     BATCH_SIZE = 1
 
 
     def __init__(self, model_path):
         """
-        Loads model from model_path and starts a tf.Session with this graph. Obtains
+        Loads a model from [model_path] and starts a tf.Session with this graph. Obtains
         input and output tensor handles.
         """
         
         detection_graph = TFDetector.__load_model(model_path)
         self.tf_session = tf.Session(graph=detection_graph)
-
         self.image_tensor = detection_graph.get_tensor_by_name('image_tensor:0')
         self.box_tensor = detection_graph.get_tensor_by_name('detection_boxes:0')
         self.score_tensor = detection_graph.get_tensor_by_name('detection_scores:0')
         self.class_tensor = detection_graph.get_tensor_by_name('detection_classes:0')
 
+
     @staticmethod
-    def round_and_make_float(d, precision=4):
+    def __round_and_make_float(d, precision=4):
         return truncate_float(float(d), precision=precision)
 
+
     @staticmethod
     def __convert_coords(tf_coords):
         """
@@ -70,9 +76,10 @@ class TFDetector:
 
         # convert numpy floats to Python floats
         for i, d in enumerate(new):
-            new[i] = TFDetector.round_and_make_float(d, precision=COORD_DIGITS)
+            new[i] = TFDetector.__round_and_make_float(d, precision=COORD_DIGITS)
         return new
 
+
     @staticmethod
     def __load_model(model_path):
         """
@@ -96,7 +103,12 @@ class TFDetector:
 
         return detection_graph
 
+
     def _generate_detections_one_image(self, image):
+        """
+        Runs the detector on a single image.
+        """
+        
         np_im = np.asarray(image, np.uint8)
         im_w_batch_dim = np.expand_dims(np_im, axis=0)
 
@@ -111,29 +123,36 @@ class TFDetector:
 
         return box_tensor_out, score_tensor_out, class_tensor_out
 
+
     def generate_detections_one_image(self, image, image_id, detection_threshold, image_size=None,
                                       skip_image_resizing=False):
         """
-        Apply the detector to an image.
+        Runs the detector on an image.
 
         Args:
-            image: the PIL Image object
-            image_id: a path to identify the image; will be in the "file" field of the output object
-            detection_threshold: confidence above which to include the detection proposal
+            image (Image): the PIL Image object on which we should run the detector
+            image_id (str): a path to identify the image; will be in the "file" field of the output object            
+            detection_threshold (float): only detections above this threshold will be included in the return
+                value
+            image_size (tuple, optional): image size to use for inference, only mess with this
+                if (a) you're using a model other than MegaDetector or (b) you know what you're
+                doing
+            skip_image_resizing (bool, optional): whether to skip internal image resizing (and rely on external 
+                resizing)... not currently supported, but included here for compatibility with PTDetector.
 
         Returns:
-        A dict with the following fields, see the 'images' key in https://github.com/agentmorris/MegaDetector/tree/master/api/batch_processing#batch-processing-api-output-format
-            - 'file' (always present)
-            - 'max_detection_conf'
-            - 'detections', which is a list of detection objects containing keys 'category', 'conf' and 'bbox'
-            - 'failure'
+            dict: a dictionary with the following fields:
+                - 'file' (filename, always present)
+                - 'max_detection_conf' (removed from MegaDetector output files by default, but generated here)
+                - 'detections' (a list of detection objects containing keys 'category', 'conf', and 'bbox')
+                - 'failure' (a failure string, or None if everything went fine)
         """
         
         assert image_size is None, 'Image sizing not supported for TF detectors'
         assert not skip_image_resizing, 'Image sizing not supported for TF detectors'
-        result = {
-            'file': image_id
-        }
+        
+        result = { 'file': image_id }
+        
         try:
             b_box, b_score, b_class = self._generate_detections_one_image(image)
 
@@ -163,3 +182,7 @@ class TFDetector:
             print('TFDetector: image {} failed during inference: {}'.format(image_id, str(e)))
 
         return result
+
+    # ...def generate_detections_one_image(...)
+    
+# ...class TFDetector