megadetector 5.0.20__py3-none-any.whl → 5.0.22__py3-none-any.whl

megadetector/visualization/visualize_db.py

@@ -32,6 +32,9 @@ from megadetector.utils.write_html_image_list import write_html_image_list
 from megadetector.data_management.cct_json_utils import IndexedJsonDb
 from megadetector.visualization import visualization_utils as vis_utils
 
+def isnan(x):
+    return (isinstance(x,float) and np.isnan(x))
+
 
 #%% Settings
 
@@ -84,12 +87,12 @@ class DbVizOptions:
         #: Number of pixels to expand each bounding box
         self.box_expansion = 0
         
-        #: Only include images that contain annotations with these class names (not IDs)
+        #: Only include images that contain annotations with these class names (not IDs) (list)
         #:
         #: Mutually exclusive with classes_to_exclude
         self.classes_to_include = None
         
-        #: Exclude images that contain annotations with these class names (not IDs)
+        #: Exclude images that contain annotations with these class names (not IDs) (list)
         #:
         #: Mutually exclusive with classes_to_include
         self.classes_to_exclude = None
@@ -117,6 +120,12 @@ class DbVizOptions:
         #: Should we show absolute (True) or relative (False) paths for each image?
         self.show_full_paths = False
         
+        #: List of additional fields in the image struct that we should print in image headers
+        self.extra_image_fields_to_print = None
+        
+        #: List of additional fields in the annotation struct that we should print in image headers
+        self.extra_annotation_fields_to_print = None
+        
         #: Set to False to skip existing images
         self.force_rendering = True
         
@@ -164,6 +173,12 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
     if options is None:
         options = DbVizOptions()
     
+    # Consistency checking for fields with specific format requirements
+    
+    # This should be a list, but if someone specifies a string, do a reasonable thing
+    if isinstance(options.extra_image_fields_to_print,str):
+        options.extra_image_fields_to_print = [options.extra_image_fields_to_print]
+        
     if not options.parallelize_rendering_with_threads:
         print('Warning: process-based parallelization is not yet supported by visualize_db')
         options.parallelize_rendering_with_threads = True
@@ -190,61 +205,69 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
     annotations = image_db['annotations']
     images = image_db['images']
     categories = image_db['categories']
-    
+        
     # Optionally remove all images without bounding boxes, *before* sampling
     if options.trim_to_images_with_bboxes:
         
-        bHasBbox = [False] * len(annotations)
-        for iAnn,ann in enumerate(annotations):
+        b_has_bbox = [False] * len(annotations)
+        for i_ann,ann in enumerate(annotations):
             if 'bbox' in ann:
                 assert isinstance(ann['bbox'],list)
-                bHasBbox[iAnn] = True
-        annotationsWithBboxes = list(compress(annotations, bHasBbox))
+                b_has_bbox[i_ann] = True
+        annotations_with_boxes = list(compress(annotations, b_has_bbox))
         
-        imageIDsWithBboxes = [x['image_id'] for x in annotationsWithBboxes]
-        imageIDsWithBboxes = set(imageIDsWithBboxes)
+        image_ids_with_boxes = [x['image_id'] for x in annotations_with_boxes]
+        image_ids_with_boxes = set(image_ids_with_boxes)
         
-        bImageHasBbox = [False] * len(images)
-        for iImage,image in enumerate(images):
+        image_has_box = [False] * len(images)
+        for i_image,image in enumerate(images):
             imageID = image['id']
-            if imageID in imageIDsWithBboxes:
-                bImageHasBbox[iImage] = True
-        imagesWithBboxes = list(compress(images, bImageHasBbox))
-        images = imagesWithBboxes
+            if imageID in image_ids_with_boxes:
+                image_has_box[i_image] = True
+        images_with_bboxes = list(compress(images, image_has_box))
+        images = images_with_bboxes
                 
     # Optionally include/remove images with specific labels, *before* sampling
         
     assert (not ((options.classes_to_exclude is not None) and \
                  (options.classes_to_include is not None))), \
                  'Cannot specify an inclusion and exclusion list'
-        
+    
+    if options.classes_to_exclude is not None:
+        assert isinstance(options.classes_to_exclude,list), \
+            'If supplied, classes_to_exclude should be a list'
+    
+    if options.classes_to_include is not None:
+        assert isinstance(options.classes_to_include,list), \
+            'If supplied, classes_to_include should be a list'
+            
     if (options.classes_to_exclude is not None) or (options.classes_to_include is not None):
      
         print('Indexing database')
         indexed_db = IndexedJsonDb(image_db)
-        bValidClass = [True] * len(images)        
-        for iImage,image in enumerate(images):
+        b_valid_class = [True] * len(images)        
+        for i_image,image in enumerate(images):
             classes = indexed_db.get_classes_for_image(image)
             if options.classes_to_exclude is not None:
-                for excludedClass in options.classes_to_exclude:
-                    if excludedClass in classes:
-                       bValidClass[iImage] = False
+                for excluded_class in options.classes_to_exclude:
+                    if excluded_class in classes:
+                       b_valid_class[i_image] = False
                        break
             elif options.classes_to_include is not None:
-                bValidClass[iImage] = False
+                b_valid_class[i_image] = False
                 if options.multiple_categories_tag in options.classes_to_include:
                     if len(classes) > 1:
-                        bValidClass[iImage] = True        
-                if not bValidClass[iImage]:
+                        b_valid_class[i_image] = True        
+                if not b_valid_class[i_image]:
                     for c in classes:
                         if c in options.classes_to_include:
-                            bValidClass[iImage] = True
+                            b_valid_class[i_image] = True
                             break                        
             else:
                 raise ValueError('Illegal include/exclude combination')
                 
-        imagesWithValidClasses = list(compress(images, bValidClass))
-        images = imagesWithValidClasses    
+        images_with_valid_classes = list(compress(images, b_valid_class))
+        images = images_with_valid_classes    
     
     # ...if we need to include/exclude categories
     
@@ -270,12 +293,12 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
     
     # Set of dicts representing inputs to render_db_bounding_boxes:
     #
-    # bboxes, boxClasses, image_path
+    # bboxes, box_classes, image_path
     rendering_info = []
     
     print('Preparing rendering list')
     
-    for iImage,img in tqdm(df_img.iterrows(),total=len(df_img)):
+    for i_image,img in tqdm(df_img.iterrows(),total=len(df_img)):
         
         img_id = img['id']
         assert img_id is not None
@@ -291,17 +314,27 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         annos_i = df_anno.loc[df_anno['image_id'] == img_id, :] # all annotations on this image
     
         bboxes = []
-        boxClasses = []
+        box_classes = []
         
         # All the class labels we've seen for this image (with out without bboxes)
-        imageCategories = set()
+        image_categories = set()
         
-        annotationLevelForImage = ''
+        extra_annotation_field_string = ''
+        annotation_level_for_image = ''
         
         # Iterate over annotations for this image
-        # iAnn = 0; anno = annos_i.iloc[iAnn]
-        for iAnn,anno in annos_i.iterrows():
-        
+        # i_ann = 0; anno = annos_i.iloc[i_ann]
+        for i_ann,anno in annos_i.iterrows():
+        
+            if options.extra_annotation_fields_to_print is not None:
+                field_names = list(anno.index)
+                for field_name in field_names:
+                    if field_name in options.extra_annotation_fields_to_print:
+                        field_value = anno[field_name]
+                        if (field_value is not None) and (not isnan(field_value)):
+                            extra_annotation_field_string += ' ({}:{})'.format(
+                                field_name,field_value)                        
+                    
             if options.confidence_threshold is not None:
                 assert options.confidence_field_name in anno, \
                     'Error: confidence thresholding requested, ' + \
@@ -316,18 +349,18 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
                     annLevel = 'sequence'
                 else:
                     annLevel = 'image'
-                if annotationLevelForImage == '':
-                    annotationLevelForImage = annLevel
-                elif annotationLevelForImage != annLevel:
-                    annotationLevelForImage = 'mixed'
+                if annotation_level_for_image == '':
+                    annotation_level_for_image = annLevel
+                elif annotation_level_for_image != annLevel:
+                    annotation_level_for_image = 'mixed'
                     
-            categoryID = anno['category_id']
-            categoryName = label_map[categoryID]
+            category_id = anno['category_id']
+            category_name = label_map[category_id]
             if options.add_search_links:
-                categoryName = categoryName.replace('"','')
-                categoryName = '<a href="https://www.google.com/search?tbm=isch&q={}">{}</a>'.format(
-                    categoryName,categoryName)
-            imageCategories.add(categoryName)
+                category_name = category_name.replace('"','')
+                category_name = '<a href="https://www.google.com/search?tbm=isch&q={}">{}</a>'.format(
+                    category_name,category_name)
+            image_categories.add(category_name)
             
             if 'bbox' in anno:
                 bbox = anno['bbox']        
@@ -335,11 +368,11 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
                     assert math.isnan(bbox), "I shouldn't see a bbox that's neither a box nor NaN"
                     continue
                 bboxes.append(bbox)
-                boxClasses.append(anno['category_id'])
+                box_classes.append(anno['category_id'])
         
         # ...for each of this image's annotations
         
-        imageClasses = ', '.join(imageCategories)
+        image_classes = ', '.join(image_categories)
                 
         img_id_string = str(img_id).lower()        
         file_name = '{}_gt.jpg'.format(os.path.splitext(img_id_string)[0])
@@ -349,19 +382,19 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         for c in illegal_characters:
             file_name = file_name.replace(c,'~')
         
-        rendering_info.append({'bboxes':bboxes, 'boxClasses':boxClasses, 'img_path':img_path,
+        rendering_info.append({'bboxes':bboxes, 'box_classes':box_classes, 'img_path':img_path,
                                'output_file_name':file_name})
                 
-        labelLevelString = ' '
-        if len(annotationLevelForImage) > 0:
-            labelLevelString = ' (annotation level: {})'.format(annotationLevelForImage)
+        label_level_string = ''
+        if len(annotation_level_for_image) > 0:
+            label_level_string = ' (annotation level: {})'.format(annotation_level_for_image)
             
         if 'frame_num' in img and 'seq_num_frames' in img:
-            frameString = ' frame: {} of {}, '.format(img['frame_num'],img['seq_num_frames'])
+            frame_string = ' frame: {} of {},'.format(img['frame_num'],img['seq_num_frames'])
         elif 'frame_num' in img:
-            frameString = ' frame: {}, '.format(img['frame_num'])
+            frame_string = ' frame: {},'.format(img['frame_num'])
         else:
-            frameString = ' '
+            frame_string = ''
         
         if options.show_full_paths:
             filename_text = img_path
@@ -370,22 +403,30 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         if options.include_filename_links:
             filename_text = '<a href="{}">{}</a>'.format(img_path,filename_text)
             
-        flagString = ''
-        
-        def isnan(x):
-            return (isinstance(x,float) and np.isnan(x))
+        flag_string = ''
         
         if ('flags' in img) and (not isnan(img['flags'])):
-            flagString = ', flags: {}'.format(str(img['flags']))
+            flag_string = ', flags: {}'.format(str(img['flags']))
             
+        extra_field_string = ''
+        
+        if options.extra_image_fields_to_print is not None:
+            for field_name in options.extra_image_fields_to_print:
+                if field_name in img:
+                    # Always include a leading comma; this either separates us from the
+                    # previous field in [extra_fields_to_print] or from the rest of the string
+                    extra_field_string += ', {}: {}'.format(
+                        field_name,str(img[field_name]))
+        
         # We're adding html for an image before we render it, so it's possible this image will
         # fail to render.  For applications where this script is being used to debua a database
         # (the common case?), this is useful behavior, for other applications, this is annoying.
         image_dict = \
         {
             'filename': '{}/{}'.format('rendered_images', file_name),
-            'title': '{}<br/>{}, num boxes: {}, {}class labels: {}{}{}'.format(
-                filename_text, img_id, len(bboxes), frameString, imageClasses, labelLevelString, flagString),
+            'title': '{}<br/>{}, num boxes: {},{} class labels: {}{}{}{}{}'.format(
+                filename_text, img_id, len(bboxes), frame_string, image_classes, 
+                label_level_string, flag_string, extra_field_string, extra_annotation_field_string),
             'textStyle': 'font-family:verdana,arial,calibri;font-size:80%;' + \
                 'text-align:left;margin-top:20;margin-bottom:5'
         }
@@ -400,7 +441,7 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         
         img_path = rendering_info['img_path']
         bboxes = rendering_info['bboxes']
-        bboxClasses = rendering_info['boxClasses']
+        bbox_classes = rendering_info['box_classes']
         output_file_name = rendering_info['output_file_name']
         output_full_path = os.path.join(output_dir, 'rendered_images', output_file_name)
         
@@ -426,7 +467,7 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
             print('Image {} failed to open, error: {}'.format(img_path, e))
             return False
             
-        vis_utils.render_db_bounding_boxes(boxes=bboxes, classes=bboxClasses,
+        vis_utils.render_db_bounding_boxes(boxes=bboxes, classes=bbox_classes,
                                            image=image, original_size=original_size,
                                            label_map=label_map,
                                            thickness=options.box_thickness,

{megadetector-5.0.20.dist-info → megadetector-5.0.22.dist-info}/METADATA

@@ -1,142 +1,143 @@
-Metadata-Version: 2.1
-Name: megadetector
-Version: 5.0.20
-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: Documentation, https://megadetector.readthedocs.io
-Project-URL: Bug Reports, https://github.com/agentmorris/MegaDetector/issues
-Project-URL: Source, https://github.com/agentmorris/MegaDetector
-Keywords: camera traps,conservation,wildlife,ai,megadetector
-Classifier: Development Status :: 3 - Alpha
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.12,>=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.24,>=1.22
-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: ultralytics-yolov5 ==0.1.1
-
-# MegaDetector
-
-This package is a pip-installable version of the support/inference code for [MegaDetector](https://github.com/agentmorris/MegaDetector/?tab=readme-ov-file#megadetector), an object detection model that helps conservation biologists spend less time doing boring things with camera trap images.  Complete documentation for this Python package is available at [megadetector.readthedocs.io](https://megadetector.readthedocs.io).
-
-If you aren't looking for the Python package specifically, and you just want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector/?tab=readme-ov-file#megadetector).
-
-
-## Reasons you might not be 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, or at least you probably don't want to start at this page.  We recommend starting with our "[Getting started with MegaDetector](https://github.com/agentmorris/MegaDetector/blob/main/getting-started.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.
-
-### 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 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 programmatically 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/megadetector/api/batch_processing#megadetector-batch-output-format)), this package might be for you.
-
-## 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.
-
-## Package reference
-
-See [megadetector.readthedocs.io](https://megadetector.readthedocs.io).
-
-
-## Examples of things you can do with this package
-
-### Run MegaDetector on one image and count the number of detections
-
-```
-from megadetector.utils import url_utils
-from megadetector.visualization import visualization_utils as vis_utils
-from megadetector.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; you can also specify a filename.
-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 {} detections above threshold'.format(len(detections_above_threshold)))
-```
-
-### Run MegaDetector on a folder of images
-
-```
-from megadetector.detection.run_detector_batch import \
-    load_and_run_detector_batch, write_results_to_file
-from megadetector.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; you can also specify a filename.
-results = load_and_run_detector_batch('MDV5A', image_file_names)
-
-# Write results to a format that Timelapse and other downstream tools like.
-write_results_to_file(results,
-                      output_file,
-                      relative_path_base=image_folder,
-                      detector_file=detector_filename)
-```
-
-## 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.
+Metadata-Version: 2.2
+Name: megadetector
+Version: 5.0.22
+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: Documentation, https://megadetector.readthedocs.io
+Project-URL: Bug Reports, https://github.com/agentmorris/MegaDetector/issues
+Project-URL: Source, https://github.com/agentmorris/MegaDetector
+Keywords: camera traps,conservation,wildlife,ai,megadetector
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.12,>=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.24,>=1.22
+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: ultralytics-yolov5==0.1.1
+Requires-Dist: python-dateutil
+
+# MegaDetector
+
+This package is a pip-installable version of the support/inference code for [MegaDetector](https://github.com/agentmorris/MegaDetector/?tab=readme-ov-file#megadetector), an object detection model that helps conservation biologists spend less time doing boring things with camera trap images.  Complete documentation for this Python package is available at [megadetector.readthedocs.io](https://megadetector.readthedocs.io).
+
+If you aren't looking for the Python package specifically, and you just want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector/?tab=readme-ov-file#megadetector).
+
+
+## Reasons you might not be 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, or at least you probably don't want to start at this page.  We recommend starting with our "[Getting started with MegaDetector](https://github.com/agentmorris/MegaDetector/blob/main/getting-started.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.
+
+### 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 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 programmatically 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/megadetector/api/batch_processing#megadetector-batch-output-format)), this package might be for you.
+
+## 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.
+
+## Package reference
+
+See [megadetector.readthedocs.io](https://megadetector.readthedocs.io).
+
+
+## Examples of things you can do with this package
+
+### Run MegaDetector on one image and count the number of detections
+
+```
+from megadetector.utils import url_utils
+from megadetector.visualization import visualization_utils as vis_utils
+from megadetector.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; you can also specify a filename.
+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 {} detections above threshold'.format(len(detections_above_threshold)))
+```
+
+### Run MegaDetector on a folder of images
+
+```
+from megadetector.detection.run_detector_batch import \
+    load_and_run_detector_batch, write_results_to_file
+from megadetector.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; you can also specify a filename.
+results = load_and_run_detector_batch('MDV5A', image_file_names)
+
+# Write results to a format that Timelapse and other downstream tools like.
+write_results_to_file(results,
+                      output_file,
+                      relative_path_base=image_folder,
+                      detector_file=detector_filename)
+```
+
+## 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.