megadetector 10.0.6__tar.gz → 10.0.8__tar.gz

{megadetector-10.0.6/megadetector.egg-info → megadetector-10.0.8}/PKG-INFO

@@ -1,134 +1,134 @@
-Metadata-Version: 2.4
-Name: megadetector
-Version: 10.0.6
-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: Programming Language :: Python :: 3
-Requires-Python: <3.14,>=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: mkl==2024.0; sys_platform != "darwin"
-Requires-Dist: numpy>=1.26.4
-Requires-Dist: Pillow>=9.5
-Requires-Dist: tqdm>=4.64.0
-Requires-Dist: jsonpickle>=3.0.2
-Requires-Dist: humanfriendly>=2.1
-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: scikit-learn>=1.3.1
-Requires-Dist: pandas>=2.1.1
-Requires-Dist: python-dateutil
-Requires-Dist: send2trash
-Requires-Dist: clipboard
-Requires-Dist: dill
-Requires-Dist: ruff
-Requires-Dist: pytest
-Requires-Dist: ultralytics-yolov5==0.1.1
-Requires-Dist: yolov9pip==0.0.4
-Dynamic: license-file
-
-# 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).
-
-If you don't want to run MegaDetector, and you just want to use the utilities in this package - postprocessing, manipulating large volumes of camera trap images, etc. - you may want to check out the [megadetector-utils](https://pypi.org/project/megadetector-utils/) package, which is identical to this one, but excludes all of the PyTorch/YOLO dependencies, and is thus approximately one zillion times smaller.
-
-## Installation
-
-Install with:
-
-`pip install megadetector`
-
-MegaDetector model weights aren't downloaded at the time you install the package, 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.4
+Name: megadetector
+Version: 10.0.8
+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: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkl==2024.0; sys_platform != "darwin"
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: Pillow>=9.5
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: jsonpickle>=3.0.2
+Requires-Dist: humanfriendly>=2.1
+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: scikit-learn>=1.3.1
+Requires-Dist: pandas>=2.1.1
+Requires-Dist: python-dateutil
+Requires-Dist: send2trash
+Requires-Dist: clipboard
+Requires-Dist: dill
+Requires-Dist: ruff
+Requires-Dist: pytest
+Requires-Dist: ultralytics-yolov5==0.1.1
+Requires-Dist: yolov9pip==0.0.4
+Dynamic: license-file
+
+# 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).
+
+If you don't want to run MegaDetector, and you just want to use the utilities in this package - postprocessing, manipulating large volumes of camera trap images, etc. - you may want to check out the [megadetector-utils](https://pypi.org/project/megadetector-utils/) package, which is identical to this one, but excludes all of the PyTorch/YOLO dependencies, and is thus approximately one zillion times smaller.
+
+## Installation
+
+Install with:
+
+`pip install megadetector`
+
+MegaDetector model weights aren't downloaded at the time you install the package, 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.

{megadetector-10.0.6 → megadetector-10.0.8}/README.md

@@ -112,7 +112,6 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [TROPECOLNET project](https://www.anabenitezlopez.com/research/global-change-biology/tropecolnet/), Museo Nacional de Ciencias Naturales
 * [Wildlife Coexistence Lab](https://wildlife.forestry.ubc.ca/), University of British Columbia
 * [Wildlife Research](https://www.dfw.state.or.us/wildlife/research/index.asp), Oregon Department of Fish and Wildlife
-* [Wildlife Division](https://www.michigan.gov/dnr/about/contact/wildlife), Michigan Department of Natural Resources
 * [Kohl Wildlife Lab](https://kohlwildlifelab.com/), University of Georgia
 * [SPEC Lab](https://thespeclab.weebly.com/) and [Cherry Lab](https://www.ckwri.tamuk.edu/about/michael-j-cherry-phd), Caesar Kleberg Wildlife Research Institute, Texas A&M Kingsville
 * Ecology and Conservation of Amazonian Vertebrates Research Group, Federal University of Amapá
@@ -148,10 +147,11 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [The Nature Conservancy in California](https://www.nature.org/en-us/about-us/where-we-work/united-states/california/) ([Animl platform](https://github.com/tnc-ca-geo/animl-frontend)) ([story](https://www.vision-systems.com/non-factory/environment-agriculture/article/14304433/the-nature-conservancy-brings-cameras-ai-to-invasive-species-prevention))
 * [San Diego Zoo Wildlife Alliance](https://science.sandiegozoo.org/)  ([Animl R package](https://github.com/conservationtechlab/animl))
 * [TerrOïko](https://www.terroiko.fr/) ([OCAPI platform](https://www.terroiko.fr/ocapi))
+* [Wildlife Division](https://www.michigan.gov/dnr/about/contact/wildlife), Michigan Department of Natural Resources ([blog post](https://www.michigan.gov/dnr/about/newsroom/releases/2025/08/18/dnr-researchers-to-test-trail-cameras-in-elk-survey))
 
 Also see:
 
-* The [list of MD-related GUIs, platforms, and GitHub repos](https://github.com/agentmorris/MegaDetector/blob/main/megadetector.md#is-there-a-gui) within the MegaDetector User Guide... although you can never have too many lists, so here they are in a concise comma-separated list: [Wildlife Insights](https://wildlifeinsights.org/), [Animal Detect](https://www.animaldetect.com), [TrapTagger](https://wildeyeconservation.org/trap-tagger-about/), [WildTrax](https://www.wildtrax.ca/), [Agouti](https://agouti.eu/), [Trapper](https://trapper-project.readthedocs.io/en/latest/overview.html), [Camelot](https://camelotproject.org/), [WildePod](https://wildepod.org/), [wpsWatch](https://wildlabs.net/inventory/products/wpswatch), [TNC Animl](https://animl.camera/) ([code](https://github.com/tnc-ca-geo/animl-frontend)), [Wildlife Observer Network](https://roadecology.ucdavis.edu/research/projects/wildlife-observer-network), [Zooniverse ML Subject Assistant](https://subject-assistant.zooniverse.org/#/intro), [Dudek AI Image Toolkit](https://ait.dudek.com), [Zamba Cloud](https://github.com/drivendataorg/zamba), [OCAPI](https://www.terroiko.fr/ocapi/).
+* The [list of MD-related GUIs, platforms, and GitHub repos](https://github.com/agentmorris/MegaDetector/blob/main/megadetector.md#is-there-a-gui) within the MegaDetector User Guide... although you can never have too many lists, so here they are in a concise comma-separated list: [Wildlife Insights](https://wildlifeinsights.org/), [Animal Detect](https://www.animaldetect.com), [TrapTagger](https://wildeyeconservation.org/trap-tagger-about/), [WildTrax](https://www.wildtrax.ca/), [Agouti](https://agouti.eu/), [Trapper](https://trapper-project.readthedocs.io/en/latest/overview.html), [Camelot](https://camelotproject.org/), [WildePod](https://wildepod.org/), [wpsWatch](https://wildlabs.net/inventory/products/wpswatch), [TNC Animl](https://animl.camera/) ([code](https://github.com/tnc-ca-geo/animl-frontend)), [Wildlife Observer Network](https://roadecology.ucdavis.edu/research/projects/wildlife-observer-network), [Zooniverse ML Subject Assistant](https://subject-assistant.zooniverse.org/#/intro), [Dudek AI Image Toolkit](https://ait.dudek.com), [Zamba Cloud](https://github.com/drivendataorg/zamba), [OCAPI](https://www.terroiko.fr/ocapi/), [BoquilaHUB](https://boquila.org/hub)
 
 * [Peter's map of AddaxAI (formerly EcoAssist) users](https://addaxdatascience.com/addaxai/) (who are also MegaDetector users!)
 

{megadetector-10.0.6 → megadetector-10.0.8}/megadetector/data_management/cct_json_utils.py

@@ -305,6 +305,9 @@ class SequenceOptions:
         #: How to handle invalid datetimes: 'error' or 'none'
         self.datetime_conversion_failure_behavior = 'none'
 
+        #: Enable additional debug output
+        self.verbose = False
+
 
 #%% Functions
 
@@ -331,7 +334,9 @@ def write_object_with_serialized_datetimes(d,json_fn):
         json.dump(d,f,indent=1,default=json_serialize_datetime)
 
 
-def parse_datetimes_from_cct_image_list(images,conversion_failure_behavior='error'):
+def parse_datetimes_from_cct_image_list(images,
+                                        conversion_failure_behavior='error',
+                                        verbose=False):
     """
     Given the "images" field from a COCO camera traps dictionary, converts all
     string-formatted datetime fields to Python datetimes, making reasonable assumptions
@@ -342,6 +347,7 @@ def parse_datetimes_from_cct_image_list(images,conversion_failure_behavior='erro
         conversion_failure_behavior (str, optional): determines what happens on a failed
             conversion; can be "error" (raise an error), "str" (leave as a string), or
             "none" (convert to None)
+        verbose (bool, optional): enable additional debug output
 
     Returns:
         images: the input list, with datetimes converted (after modifying in place)
@@ -359,14 +365,17 @@ def parse_datetimes_from_cct_image_list(images,conversion_failure_behavior='erro
             dt = dateutil.parser.parse(im['datetime'])
             im['datetime'] = dt
         except Exception as e:
-            s = 'could not parse datetime {}: {}'.format(str(im['datetime']),str(e))
+            s = 'could not parse datetime {} from {}: {}'.format(
+                str(im['datetime']),im['file_name'],str(e))
             if conversion_failure_behavior == 'error':
                 raise ValueError(s)
             elif conversion_failure_behavior == 'str':
-                print('Warning: {}'.format(s))
+                if verbose:
+                    print('Warning: {}'.format(s))
                 pass
             elif conversion_failure_behavior == 'none':
-                print('Warning: {}'.format(s))
+                if verbose:
+                    print('Warning: {}'.format(s))
                 im['datetime'] = None
 
     # ...for each image
@@ -450,7 +459,8 @@ def create_sequences(image_info,options=None):
 
     # Modifies the images in place
     _ = parse_datetimes_from_cct_image_list(image_info,
-            conversion_failure_behavior=options.datetime_conversion_failure_behavior)
+            conversion_failure_behavior=options.datetime_conversion_failure_behavior,
+            verbose=options.verbose)
 
     n_invalid_datetimes = 0
     for im in image_info:
@@ -505,7 +515,7 @@ def create_sequences(image_info,options=None):
                 delta = (im['datetime'] - previous_datetime).total_seconds()
 
             # Start a new sequence if necessary, including the case where this datetime is invalid
-            if delta is None or delta > options.episode_interval_seconds or invalid_datetime:
+            if (delta is None) or (delta > options.episode_interval_seconds) or (invalid_datetime):
                 next_frame_number = 0
                 current_sequence_id = 'location_{}_sequence_index_{}'.format(
                     location,str(next_sequence_number).zfill(5))

{megadetector-10.0.6 → megadetector-10.0.8}/megadetector/data_management/databases/subset_json_db.py

@@ -18,13 +18,20 @@ import json
 import argparse
 
 from tqdm import tqdm
-from megadetector.utils import ct_utils
 from copy import copy
 
+from megadetector.utils import ct_utils
+from megadetector.utils.ct_utils import sort_list_of_dicts_by_key
+
 
 #%% Functions
 
-def subset_json_db(input_json, query, output_json=None, ignore_case=False, verbose=False):
+def subset_json_db(input_json,
+                   query,
+                   output_json=None,
+                   ignore_case=False,
+                   remap_categories=True,
+                   verbose=False):
     """
     Given a json file (or dictionary already loaded from a json file), produce a new
     database containing only the images whose filenames contain the string 'query',
@@ -36,6 +43,8 @@ def subset_json_db(input_json, query, output_json=None, ignore_case=False, verbo
             contain this string.  If this is a list, test for exact matches.
         output_json (str, optional): file to write the resulting .json file to
         ignore_case (bool, optional): whether to perform a case-insensitive search for [query]
+        remap_categories (bool, optional): trim the category list to only the categores used
+            in the subset
         verbose (bool, optional): enable additional debug output
 
     Returns:
@@ -92,6 +101,52 @@ def subset_json_db(input_json, query, output_json=None, ignore_case=False, verbo
     output_data['images'] = images
     output_data['annotations'] = annotations
 
+    # Remap categories if necessary
+    if remap_categories:
+
+        category_ids_used = set()
+        for ann in annotations:
+            category_ids_used.add(ann['category_id'])
+
+        if verbose:
+            print('Keeping {} of {} categories'.format(
+                len(category_ids_used),len(input_data['categories'])))
+
+        input_category_id_to_output_category_id = {}
+
+        next_category_id = 0
+
+        # Build mappings from old to new category IDs
+        for input_category_id in category_ids_used:
+            assert isinstance(input_category_id,int), \
+                'Illegal category ID {}'.format(input_category_id)
+            output_category_id = next_category_id
+            next_category_id = next_category_id + 1
+            input_category_id_to_output_category_id[input_category_id] = output_category_id
+
+        # Modify the annotations
+        for ann in annotations:
+            assert ann['category_id'] in input_category_id_to_output_category_id
+            ann['category_id'] = input_category_id_to_output_category_id[ann['category_id']]
+
+        output_categories = []
+
+        # Re-write the category table
+        for cat in input_data['categories']:
+
+            if cat['id'] in input_category_id_to_output_category_id:
+
+                # There may be non-required fields, so don't just create an empty dict
+                # and copy the name/id field, keep the original dict other than "id"
+                output_category = copy(cat)
+                output_category['id'] = input_category_id_to_output_category_id[cat['id']]
+                output_categories.append(output_category)
+
+        output_categories = sort_list_of_dicts_by_key(output_categories,'id')
+        output_data['categories'] = output_categories
+
+    # ...if we need to remap categories
+
     # Write the output file if requested
     if output_json is not None:
         if verbose: