megadetector 5.0.2__tar.gz → 5.0.4__tar.gz

megadetector-5.0.4/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: megadetector
+Version: 5.0.4
+Summary: MegaDetector is an AI model that helps conservation folks spend less time doing boring things with camera trap images.
+Author-email: Your friendly neighborhood MegaDetector team <cameratraps@lila.science>
+Maintainer-email: Your friendly neighborhood MegaDetector team <cameratraps@lila.science>
+License:     MIT License
+        
+            Permission is hereby granted, free of charge, to any person obtaining a copy
+            of this software and associated documentation files (the "Software"), to deal
+            in the Software without restriction, including without limitation the rights
+            to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+            copies of the Software, and to permit persons to whom the Software is
+            furnished to do so, subject to the following conditions:
+        
+            The above copyright notice and this permission notice shall be included in all
+            copies or substantial portions of the Software.
+        
+            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+            AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+            LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+            OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+            SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/agentmorris/MegaDetector
+Project-URL: Bug Reports, https://github.com/agentmorris/MegaDetector/issues
+Project-URL: Source, https://github.com/agentmorris/MegaDetector
+Keywords: camera traps,conservation,wildlife,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.5
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: jsonpickle>=3.0.2
+Requires-Dist: humanfriendly>=10.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyqtree>=1.0.0
+Requires-Dist: seaborn>=0.12.2
+Requires-Dist: scikit-learn>=1.3.1
+Requires-Dist: pandas>=2.1.1
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: torch>=2.0.1
+Requires-Dist: torchvision>=0.15.2
+Requires-Dist: yolov5>=7.0.12
+
+# MegaDetector
+
+This package is a pip-installable version of the support/inference code for [MegaDetector](https://github.com/agentmorris/MegaDetector), an object detection model that helps conservation biologists spend less time doing boring things with camera trap images.
+
+If you want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector).
+
+
+## Reasons you probably aren't looking for this package
+
+### If you are an ecologist...
+
+If you are an ecologist looking to use MegaDetector to help you get through your camera trap images, you probably don't want this package.  We recommend starting with our "[Getting started with MegaDetector](https://github.com/agentmorris/MegaDetector/blob/main/collaborations.md)" page, then digging in to the [MegaDetector User Guide](https://github.com/agentmorris/MegaDetector/blob/main/megadetector.md), which will walk you through the process of using MegaDetector.  That journey will <i>not</i> involve this package.
+
+### If you are a computer-vision-y type...
+
+If you are a computer-vision-y person looking to run or fine-tune MegaDetector programmatically, you still probably don't want this package.  MegaDetector is just a fine-tuned version of [YOLOv5](https://github.com/ultralytics/yolov5), and the [ultralytics](https://github.com/ultralytics/ultralytics/) package (from the developers of YOLOv5) has a zillion bells and whistles for both inference and fine-tuning that this package doesn't.
+
+## Reasons you might want to use this package
+
+If you want to programatically interact with the postprocessing tools from the MegaDetector repo, or programmatically run MegaDetector in a way that produces [Timelapse](https://saul.cpsc.ucalgary.ca/timelapse)-friendly output (i.e., output in the standard [MegaDetector output format](https://github.com/agentmorris/MegaDetector/tree/main/api/batch_processing#megadetector-batch-output-format)), this package might be for you.
+
+Although even if that describes you, you <i>still</i> might be better off cloning the MegaDetector repo.  Pip-installability requires that some dependencies be newer than what was available at the time MDv5 was trained, so results are <i>very slightly</i> different than results produced in the "official" environment.  These differences <i>probably</i> don't matter much, but they have not been formally characterized.
+
+## If I haven't talked you out of using this package...
+
+To install:
+
+`pip install megadetector`
+
+MegaDetector model weights aren't downloaded at pip-install time, but they will be (optionally) automatically downloaded the first time you run the model.
+
+### Examples of things you can do with this package
+
+#### Run MegaDetector on one image and count the number of detections
+
+```
+from md_utils import url_utils
+from md_visualization import visualization_utils as vis_utils
+from detection import run_detector
+
+# This is the image at the bottom of this page, it has one animal in it
+image_url = 'https://github.com/agentmorris/MegaDetector/raw/main/images/orinoquia-thumb-web.jpg'
+temporary_filename = url_utils.download_url(image_url)
+
+image = vis_utils.load_image(temporary_filename)
+
+# This will automatically download MDv5a to the system temp folder;
+# you can also specify a filename explicitly, or set the $MDV5A
+# environment variable to point to the model file.
+model = run_detector.load_detector('MDV5A')
+
+result = model.generate_detections_one_image(image)
+
+detections_above_threshold = [d for d in result['detections'] if d['conf'] > 0.2]
+print('Found {} detection above threshold'.format(len(detections_above_threshold)))
+```
+
+#### Run MegaDetector on a folder of images
+
+```
+from detection.run_detector_batch import load_and_run_detector_batch,write_results_to_file
+from md_utils import path_utils
+import os
+
+# Pick a folder to run MD on recursively, and an output file
+image_folder = os.path.expanduser('~/megadetector_test_images')
+output_file = os.path.expanduser('~/megadetector_output_test.json')
+
+# Recursively find images
+image_file_names = path_utils.find_images(image_folder,recursive=True)
+
+# This will automatically download MDv5a to the system temp folder;
+# you can also specify a filename explicitly, or set the $MDV5A
+# environment variable to point to the model file.
+results = load_and_run_detector_batch('MDV5A', image_file_names)
+
+# Write results as relative filenames, this is what Timelapse
+# and other downstream tools expect.
+write_results_to_file(results,output_file,relative_path_base=image_folder)
+```
+
+## Contact
+
+Contact <a href="cameratraps@lila.science">cameratraps@lila.science</a> with questions.
+
+## Gratuitous animal picture
+
+<img src="https://github.com/agentmorris/MegaDetector/raw/main/images/orinoquia-thumb-web_detections.jpg"><br/>Image credit University of Minnesota, from the [Orinoquía Camera Traps](http://lila.science/datasets/orinoquia-camera-traps/) data set.

megadetector-5.0.4/README-package.md

@@ -0,0 +1,88 @@
+# MegaDetector
+
+This package is a pip-installable version of the support/inference code for [MegaDetector](https://github.com/agentmorris/MegaDetector), an object detection model that helps conservation biologists spend less time doing boring things with camera trap images.
+
+If you want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector).
+
+
+## Reasons you probably aren't looking for this package
+
+### If you are an ecologist...
+
+If you are an ecologist looking to use MegaDetector to help you get through your camera trap images, you probably don't want this package.  We recommend starting with our "[Getting started with MegaDetector](https://github.com/agentmorris/MegaDetector/blob/main/collaborations.md)" page, then digging in to the [MegaDetector User Guide](https://github.com/agentmorris/MegaDetector/blob/main/megadetector.md), which will walk you through the process of using MegaDetector.  That journey will <i>not</i> involve this package.
+
+### If you are a computer-vision-y type...
+
+If you are a computer-vision-y person looking to run or fine-tune MegaDetector programmatically, you still probably don't want this package.  MegaDetector is just a fine-tuned version of [YOLOv5](https://github.com/ultralytics/yolov5), and the [ultralytics](https://github.com/ultralytics/ultralytics/) package (from the developers of YOLOv5) has a zillion bells and whistles for both inference and fine-tuning that this package doesn't.
+
+## Reasons you might want to use this package
+
+If you want to programatically interact with the postprocessing tools from the MegaDetector repo, or programmatically run MegaDetector in a way that produces [Timelapse](https://saul.cpsc.ucalgary.ca/timelapse)-friendly output (i.e., output in the standard [MegaDetector output format](https://github.com/agentmorris/MegaDetector/tree/main/api/batch_processing#megadetector-batch-output-format)), this package might be for you.
+
+Although even if that describes you, you <i>still</i> might be better off cloning the MegaDetector repo.  Pip-installability requires that some dependencies be newer than what was available at the time MDv5 was trained, so results are <i>very slightly</i> different than results produced in the "official" environment.  These differences <i>probably</i> don't matter much, but they have not been formally characterized.
+
+## If I haven't talked you out of using this package...
+
+To install:
+
+`pip install megadetector`
+
+MegaDetector model weights aren't downloaded at pip-install time, but they will be (optionally) automatically downloaded the first time you run the model.
+
+### Examples of things you can do with this package
+
+#### Run MegaDetector on one image and count the number of detections
+
+```
+from md_utils import url_utils
+from md_visualization import visualization_utils as vis_utils
+from detection import run_detector
+
+# This is the image at the bottom of this page, it has one animal in it
+image_url = 'https://github.com/agentmorris/MegaDetector/raw/main/images/orinoquia-thumb-web.jpg'
+temporary_filename = url_utils.download_url(image_url)
+
+image = vis_utils.load_image(temporary_filename)
+
+# This will automatically download MDv5a to the system temp folder;
+# you can also specify a filename explicitly, or set the $MDV5A
+# environment variable to point to the model file.
+model = run_detector.load_detector('MDV5A')
+
+result = model.generate_detections_one_image(image)
+
+detections_above_threshold = [d for d in result['detections'] if d['conf'] > 0.2]
+print('Found {} detection above threshold'.format(len(detections_above_threshold)))
+```
+
+#### Run MegaDetector on a folder of images
+
+```
+from detection.run_detector_batch import load_and_run_detector_batch,write_results_to_file
+from md_utils import path_utils
+import os
+
+# Pick a folder to run MD on recursively, and an output file
+image_folder = os.path.expanduser('~/megadetector_test_images')
+output_file = os.path.expanduser('~/megadetector_output_test.json')
+
+# Recursively find images
+image_file_names = path_utils.find_images(image_folder,recursive=True)
+
+# This will automatically download MDv5a to the system temp folder;
+# you can also specify a filename explicitly, or set the $MDV5A
+# environment variable to point to the model file.
+results = load_and_run_detector_batch('MDV5A', image_file_names)
+
+# Write results as relative filenames, this is what Timelapse
+# and other downstream tools expect.
+write_results_to_file(results,output_file,relative_path_base=image_folder)
+```
+
+## Contact
+
+Contact <a href="cameratraps@lila.science">cameratraps@lila.science</a> with questions.
+
+## Gratuitous animal picture
+
+<img src="https://github.com/agentmorris/MegaDetector/raw/main/images/orinoquia-thumb-web_detections.jpg"><br/>Image credit University of Minnesota, from the [Orinoquía Camera Traps](http://lila.science/datasets/orinoquia-camera-traps/) data set.

{megadetector-5.0.2 → megadetector-5.0.4}/README.md

@@ -122,7 +122,7 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [Bavarian Forest National Park](https://www.nationalpark-bayerischer-wald.bayern.de/english/index.htm) ([story](https://customers.microsoft.com/en-au/story/1667539539271247797-nationalparkbayerischerwald-azure-en))
 * [Felidae Conservation Fund](https://felidaefund.org/) ([WildePod platform](https://wildepod.org/)) ([blog post](https://abhaykashyap.com/blog/ai-powered-camera-trap-image-annotation-system/))
 * [Alberta Biodiversity Monitoring Institute (ABMI)](https://www.abmi.ca/home.html) ([WildTrax platform](https://www.wildtrax.ca/)) (blog posts [1](https://wildcams.ca/blog/the-abmi-visits-the-zoo/),[2](http://blog.abmi.ca/2023/06/14/making-wildtrax-its-not-a-kind-of-magic-behind-the-screen/))
-* [Shan Shui Conservation Center](http://en.shanshui.org/) ([blog post](https://mp.weixin.qq.com/s/iOIQF3ckj0-rEG4yJgerYw?fbclid=IwAR0alwiWbe3udIcFvqqwm7y5qgr9hZpjr871FZIa-ErGUukZ7yJ3ZhgCevs)) ([translated blog post](https://mp-weixin-qq-com.translate.goog/s/iOIQF3ckj0-rEG4yJgerYw?fbclid=IwAR0alwiWbe3udIcFvqqwm7y5qgr9hZpjr871FZIa-ErGUukZ7yJ3ZhgCevs&_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=en&_x_tr_pto=wapp))
+* [Shan Shui Conservation Center](http://en.shanshui.org/) ([blog post](https://mp.weixin.qq.com/s/iOIQF3ckj0-rEG4yJgerYw?fbclid=IwAR0alwiWbe3udIcFvqqwm7y5qgr9hZpjr871FZIa-ErGUukZ7yJ3ZhgCevs)) ([translated blog post](https://mp-weixin-qq-com.translate.goog/s/iOIQF3ckj0-rEG4yJgerYw?fbclid=IwAR0alwiWbe3udIcFvqqwm7y5qgr9hZpjr871FZIa-ErGUukZ7yJ3ZhgCevs&_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=en&_x_tr_pto=wapp)) ([Web demo](https://cameratrap-ai.hinature.cn/home))
 * [Irvine Ranch Conservancy](http://www.irconservancy.org/) ([story](https://www.ocregister.com/2022/03/30/ai-software-is-helping-researchers-focus-on-learning-about-ocs-wild-animals/))
 * [Wildlife Protection Solutions](https://wildlifeprotectionsolutions.org/) ([story](https://customers.microsoft.com/en-us/story/1384184517929343083-wildlife-protection-solutions-nonprofit-ai-for-earth), [story](https://www.enterpriseai.news/2023/02/20/ai-helps-wildlife-protection-solutions-safeguard-endangered-species/))
 * [Q42](https://www.q42.nl/en) ([blog post](https://engineering.q42.nl/ai-bear-repeller/))

{megadetector-5.0.2 → megadetector-5.0.4}/api/batch_processing/postprocessing/md_to_labelme.py

@@ -3,8 +3,8 @@
 # md_to_labelme.py
 #
 # "Converts" a MegaDetector output .json file to labelme format (one .json per image
-# file).  "Convert" is in quotes because this is an opinionated transformation, that requires a 
-# confidence threshold.
+# file).  "Convert" is in quotes because this is an opinionated transformation that 
+# requires a confidence threshold.
 #
 # TODO:
 #    
@@ -24,13 +24,65 @@ from md_visualization.visualization_utils import open_image
 from md_utils.ct_utils import truncate_float
 
 output_precision = 3
+default_confidence_threshold = 0.15
 
 
 #%% Functions
 
-def md_to_labelme(results_file,image_base,confidence_threshold,overwrite=False):
+def get_labelme_dict_for_image(im,image_base_name,category_id_to_name,info=None,confidence_threshold=None):
+    """
+    For the given image struct in MD results format, reformat the detections into
+    labelme format.  Returns a dict.
+    """
     
-    #%%
+    if confidence_threshold is None:
+        confidence_threshold = -1.0
+        
+    output_dict = {}
+    if info is not None:
+        output_dict['md_info'] = info
+    output_dict['version'] = '5.3.0a0'
+    output_dict['flags'] = {}
+    output_dict['shapes'] = []
+    output_dict['imagePath'] = image_base_name
+    output_dict['imageHeight'] = im['height']
+    output_dict['imageWidth'] = im['width']
+    output_dict['imageData'] = None
+    
+    for det in im['detections']:
+        
+        if det['conf'] < confidence_threshold:
+            continue
+        
+        shape = {}
+        shape['conf'] = det['conf']
+        shape['label'] = category_id_to_name[det['category']] 
+        shape['shape_type'] = 'rectangle'
+        shape['description'] = ''
+        shape['group_id'] = None
+        
+        # MD boxes are [x_min, y_min, width_of_box, height_of_box] (relative)
+        # 
+        # labelme boxes are [[x0,y0],[x1,y1]] (absolute)
+        x0 = truncate_float(det['bbox'][0] * im['width'],output_precision)
+        y0 = truncate_float(det['bbox'][1] * im['height'],output_precision)
+        x1 = truncate_float(x0 + det['bbox'][2] * im['width'],output_precision)
+        y1 = truncate_float(y0 + det['bbox'][3] * im['height'],output_precision)
+        shape['points'] = [[x0,y0],[x1,y1]]
+        output_dict['shapes'].append(shape)
+    
+    # ...for each detection
+    
+    return output_dict
+
+# ...def get_labelme_dict_for_image()
+
+
+def md_to_labelme(results_file,image_base,confidence_threshold=None,overwrite=False):
+    """
+    For all the images in [results_file], write a .json file in labelme format alongside the
+    corresponding relative path within image_base.
+    """
     
     # Load MD results
     with open(results_file,'r') as f:
@@ -57,45 +109,20 @@ def md_to_labelme(results_file,image_base,confidence_threshold,overwrite=False):
             print('Skipping existing file {}'.format(json_path))
             continue
     
-        output_dict = {}
-        output_dict['md_info'] = md_results['info']
-        output_dict['version'] = '5.3.0a0'
-        output_dict['flags'] = {}
-        output_dict['shapes'] = []
-        output_dict['imagePath'] = os.path.basename(im_full_path)
-        output_dict['imageHeight'] = im['height']
-        output_dict['imageWidth'] = im['width']
-        output_dict['imageData'] = None
-        
-        for det in im['detections']:
-            
-            if det['conf'] < confidence_threshold:
-                continue
-            
-            shape = {}
-            shape['conf'] = det['conf']
-            shape['label'] = md_results['detection_categories'][det['category']] 
-            shape['shape_type'] = 'rectangle'
-            shape['description'] = ''
-            shape['group_id'] = None
-            
-            # MD boxes are [x_min, y_min, width_of_box, height_of_box] (relative)
-            # 
-            # labelme boxes are [[x0,y0],[x1,y1]] (absolute)
-            x0 = truncate_float(det['bbox'][0] * im['width'],output_precision)
-            y0 = truncate_float(det['bbox'][1] * im['height'],output_precision)
-            x1 = truncate_float(x0 + det['bbox'][2] * im['width'],output_precision)
-            y1 = truncate_float(y0 + det['bbox'][3] * im['height'],output_precision)
-            shape['points'] = [[x0,y0],[x1,y1]]
-            output_dict['shapes'].append(shape)
-            
-        # ...for each detection
+        output_dict = get_labelme_dict_for_image(im,
+                                                 image_base_name=os.path.basename(im_full_path),
+                                                 category_id_to_name=md_results['detection_categories'],
+                                                 info=md_results['info'],
+                                                 confidence_threshold=confidence_threshold)
         
         with open(json_path,'w') as f:
             json.dump(output_dict,f,indent=1)
             
     # ...for each image
 
+# ...def md_to_labelme()
+
+
 #%% Interactive driver
 
 if False:
@@ -131,7 +158,9 @@ def main():
     parser.add_argument(
         'confidence_threshold',
         type=float,
-        help='Confidence threshold')
+        default=default_confidence_threshold,
+        help='Confidence threshold (default {})'.format(default_confidence_threshold)
+        )
     
     parser.add_argument(
         '--overwrite',

{megadetector-5.0.2 → megadetector-5.0.4}/classification/merge_classification_detection_output.py

@@ -85,7 +85,7 @@ from typing import Any
 import pandas as pd
 from tqdm import tqdm
 
-from ct_utils import truncate_float
+from md_utils.ct_utils import truncate_float
 
 
 #%% Support functions

{megadetector-5.0.2 → megadetector-5.0.4}/data_management/importers/cacophony-thermal-importer.py

@@ -484,7 +484,7 @@ def process_file(fn_relative,verbose=False):
             if tag['label'] in tag_mappings:
                 tag['label'] = tag_mappings[tag['label']]
                 
-            # Discard tags below the minumum confidence
+            # Discard tags below the minimum confidence
             if tag['confidence'] >= confidence_threshold:
                 valid_tags.append(tag)
             else:

{megadetector-5.0.2 → megadetector-5.0.4}/detection/process_video.py

@@ -103,7 +103,7 @@ def process_video(options):
     # TODO:
     # 
     # This is a lazy fix to an issue... if multiple users run this script, the
-    # "process_camera_trap_video" is owned by the first person who creates it, and others
+    # "process_camera_trap_video" folder is owned by the first person who creates it, and others
     # can't write to it.  I could create uniquely-named folders, but I philosophically prefer
     # to put all the individual UUID-named folders within a larger folder, so as to be a 
     # good tempdir citizen.  So, the lazy fix is to make this world-writable.

{megadetector-5.0.2 → megadetector-5.0.4}/detection/pytorch_detector.py

@@ -40,7 +40,8 @@ if try_yolov5_import and not utils_imported:
         utils_imported = True
         print('Imported YOLOv5 from YOLOv5 package')
     except Exception:
-        print('YOLOv5 module import failed, falling back to path-based import')
+        # print('YOLOv5 module import failed, falling back to path-based import')
+        pass
 
 # If we haven't succeeded yet, import from the ultralytics package        
 if try_ultralytics_import and not utils_imported:
@@ -59,7 +60,8 @@ if try_ultralytics_import and not utils_imported:
         utils_imported = True
         print('Imported YOLOv5 from ultralytics package')
     except Exception:
-        print('Ultralytics module import failed, falling back to yolov5 import')
+        # print('Ultralytics module import failed, falling back to yolov5 import')
+        pass
 
 # If we haven't succeeded yet, import from the YOLOv5 repo
 if not utils_imported:
@@ -83,7 +85,7 @@ assert utils_imported, 'YOLOv5 import error'
 
 print(f'Using PyTorch version {torch.__version__}')
 
-
+    
 #%% Classes
 
 class PTDetector:
@@ -114,7 +116,19 @@ class PTDetector:
 
     @staticmethod
     def _load_model(model_pt_path, device):
-        checkpoint = torch.load(model_pt_path, map_location=device)
+        
+        # There are two very slightly different ways to load the model, (1) using the
+        # map_location=device parameter to torch.load and (2) calling .to(device) after
+        # loading the model.  The former is what we did for a zillion years, but is not
+        # supported on Apple silicon at of 2029.09.  Switching to the latter causes
+        # very slight changes to the output, which always make me nervous, so I'm not
+        # doing a wholesale swap just yet.  Instead, we'll just do this on M1 hardware.
+        use_map_location = (device != 'mps')        
+        
+        if use_map_location:
+            checkpoint = torch.load(model_pt_path, map_location=device)
+        else:
+            checkpoint = torch.load(model_pt_path)
         
         # Compatibility fix that allows us to load older YOLOv5 models with 
         # newer versions of YOLOv5/PT
@@ -122,12 +136,16 @@ class PTDetector:
             t = type(m)
             if t is torch.nn.Upsample and not hasattr(m, 'recompute_scale_factor'):
                 m.recompute_scale_factor = None
+        
+        if use_map_location:
+            model = checkpoint['model'].float().fuse().eval()
+        else:
+            model = checkpoint['model'].float().fuse().eval().to(device)
             
-        model = checkpoint['model'].float().fuse().eval()  # FP32 model
         return model
 
-    def generate_detections_one_image(self, img_original, image_id, 
-                                      detection_threshold, image_size=None,
+    def generate_detections_one_image(self, img_original, image_id='unknown', 
+                                      detection_threshold=0.00001, image_size=None,
                                       skip_image_resizing=False):
         """
         Apply the detector to an image.

{megadetector-5.0.2 → megadetector-5.0.4}/detection/run_detector.py

@@ -127,6 +127,15 @@ DEFAULT_BOX_EXPANSION = 0
 DEFAULT_LABEL_FONT_SIZE = 16
 DETECTION_FILENAME_INSERT = '_detections'
 
+# The model filenames "MDV5A", "MDV5B", and "MDV4" are special; they will trigger an 
+# automatic model download to the system temp folder, or they will use the paths specified in the 
+# $MDV4, $MDV5A, or $MDV5B environment variables if they exist.
+downloadable_models = {
+    'MDV4':'https://github.com/agentmorris/MegaDetector/releases/download/v4.1/md_v4.1.0.pb',
+    'MDV5A':'https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5a.0.0.pt',
+    'MDV5B':'https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5b.0.0.pt'
+}
+
 
 #%% Utility functions
 
@@ -257,6 +266,9 @@ def load_detector(model_file, force_cpu=False):
     Load a TF or PT detector, depending on the extension of model_file.
     """
     
+    # Possibly automatically download the model
+    model_file = try_download_known_detector(model_file)
+    
     start_time = time.time()
     if model_file.endswith('.pb'):
         from detection.tf_detector import TFDetector
@@ -290,6 +302,9 @@ def load_and_run_detector(model_file, image_file_names, output_dir,
         print('Warning: no files available')
         return
 
+    # Possibly automatically download the model
+    model_file = try_download_known_detector(model_file)
+
     print('GPU available: {}'.format(is_gpu_available(model_file)))
     
     detector = load_detector(model_file)
@@ -429,6 +444,55 @@ def load_and_run_detector(model_file, image_file_names, output_dir,
 # ...def load_and_run_detector()
 
 
+def download_model(model_name,force_download=False):
+    """
+    Download one of the known models to local temp space if it hasn't already been downloaded
+    """
+    
+    import tempfile
+    from md_utils.url_utils import download_url
+    model_tempdir = os.path.join(tempfile.gettempdir(), 'megadetector_models')    
+    os.makedirs(model_tempdir,exist_ok=True)
+    
+    # This is a lazy fix to an issue... if multiple users run this script, the
+    # "megadetector_models" folder is owned by the first person who creates it, and others
+    # can't write to it.  I could create uniquely-named folders, but I philosophically prefer
+    # to put all the individual UUID-named folders within a larger folder, so as to be a 
+    # good tempdir citizen.  So, the lazy fix is to make this world-writable.
+    try:
+        os.chmod(model_tempdir,0o777)
+    except Exception:
+        pass
+    if model_name not in downloadable_models:
+        print('Unrecognized downloadable model {}'.format(model_name))
+        return None
+    url = downloadable_models[model_name]
+    destination_filename = os.path.join(model_tempdir,url.split('/')[-1])
+    local_file = download_url(url, destination_filename=destination_filename, progress_updater=None, 
+                     force_download=force_download, verbose=True)
+    return local_file
+
+
+def try_download_known_detector(detector_file):
+    """
+    Check whether detector_file is really the name of a known model, in which case we will
+    either read the actual filename from the corresponding environment variable or download
+    (if necessary) to local temp space.  Otherwise just returns the input string.
+    """
+    
+    if detector_file in downloadable_models:
+        if detector_file in os.environ:
+            fn = os.environ[detector_file]
+            print('Reading MD location from environment variable {}: {}'.format(
+                detector_file,fn))
+            detector_file = fn
+        else:
+            print('Downloading model {}'.format(detector_file))
+            detector_file = download_model(detector_file)
+    return detector_file
+        
+    
+
 #%% Command-line driver
 
 def main():
@@ -438,7 +502,7 @@ def main():
     
     parser.add_argument(
         'detector_file',
-        help='Path to TensorFlow (.pb) or PyTorch (.pt) detector model file')
+        help='Path detector model file (.pb or .pt).  Can also be MDV4, MDV5A, or MDV5B to request automatic download.')
     
     # Must specify either an image file or a directory
     group = parser.add_mutually_exclusive_group(required=True)    
@@ -506,6 +570,10 @@ def main():
 
     args = parser.parse_args()
 
+    # If the specified detector file is really the name of a known model, find 
+    # (and possibly download) that model
+    args.detector_file = try_download_known_detector(args.detector_file)
+    
     assert os.path.exists(args.detector_file), 'detector file {} does not exist'.format(
         args.detector_file)
     assert 0.0 < args.threshold <= 1.0, 'Confidence threshold needs to be between 0 and 1'

{megadetector-5.0.2 → megadetector-5.0.4}/detection/run_detector_batch.py

@@ -64,6 +64,7 @@ from multiprocessing.pool import Pool as workerpool
 import detection.run_detector as run_detector
 from detection.run_detector import is_gpu_available,\
     load_detector,\
+    try_download_known_detector,\
     get_detector_version_from_filename,\
     get_detector_metadata_from_version_string
 
@@ -413,6 +414,8 @@ def load_and_run_detector_batch(model_file, image_file_names, checkpoint_path=No
 
     already_processed = set([i['file'] for i in results])
 
+    model_file = try_download_known_detector(model_file)
+        
     print('GPU available: {}'.format(is_gpu_available(model_file)))
     
     if n_cores > 1 and is_gpu_available(model_file):
@@ -743,7 +746,7 @@ def main():
         description='Module to run a TF/PT animal detection model on lots of images')
     parser.add_argument(
         'detector_file',
-        help='Path to detector model file (.pb or .pt)')
+        help='Path to detector model file (.pb or .pt).  Can also be MDV4, MDV5A, or MDV5B to request automatic download.')
     parser.add_argument(
         'image_file',
         help='Path to a single image file, a JSON file containing a list of paths to images, or a directory')
@@ -838,6 +841,10 @@ def main():
 
     args = parser.parse_args()
 
+    # If the specified detector file is really the name of a known model, find 
+    # (and possibly download) that model
+    args.detector_file = try_download_known_detector(args.detector_file)
+    
     assert os.path.exists(args.detector_file), \
         'detector file {} does not exist'.format(args.detector_file)
     assert 0.0 < args.threshold <= 1.0, 'Confidence threshold needs to be between 0 and 1'

{megadetector-5.0.2 → megadetector-5.0.4}/md_utils/url_utils.py

@@ -17,9 +17,6 @@ import requests
 from tqdm import tqdm
 from urllib.parse import urlparse
 
-# pip install progressbar2
-import progressbar
-
 url_utils_temp_dir = None
 max_path_len = 255
 
@@ -36,6 +33,10 @@ class DownloadProgressBar():
 
     def __call__(self, block_num, block_size, total_size):
         if not self.pbar:
+            # This is a pretty random import I'd rather not depend on outside of the
+            # rare case where it's used, so importing locally
+            # pip install progressbar2
+            import progressbar            
             self.pbar = progressbar.ProgressBar(max_value=total_size)
             self.pbar.start()
             

{megadetector-5.0.2 → megadetector-5.0.4}/md_visualization/visualization_utils.py

@@ -160,7 +160,7 @@ def resize_image(image, target_width, target_height=-1):
             # w = ar * h
             target_width = int(aspect_ratio * target_height)
 
-    # This parameter changed between Pillow vesions 9 and 10, and for a bit, I'd like to
+    # This parameter changed between Pillow versions 9 and 10, and for a bit, I'd like to
     # support both.
     try:
         resized_image = image.resize((target_width, target_height), Image.ANTIALIAS)