megadetector 5.0.21__tar.gz → 5.0.22__tar.gz

{megadetector-5.0.21/megadetector.egg-info → megadetector-5.0.22}/PKG-INFO

@@ -1,142 +1,143 @@
-Metadata-Version: 2.1
-Name: megadetector
-Version: 5.0.21
-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.

{megadetector-5.0.21 → megadetector-5.0.22}/README.md

@@ -107,7 +107,7 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [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
 * Department of Ecology, TU Berlin
 * Ghost Cat Analytics
 * Protected Areas Unit, Canadian Wildlife Service

{megadetector-5.0.21 → megadetector-5.0.22}/megadetector/data_management/cct_json_utils.py

@@ -12,6 +12,8 @@ https://github.com/agentmorris/MegaDetector/blob/main/megadetector/data_manageme
 
 import json
 import os
+import datetime
+import dateutil
 
 from tqdm import tqdm
 from collections import defaultdict, OrderedDict
@@ -302,6 +304,106 @@ class SequenceOptions:
     
 #%% Functions
 
+def write_object_with_serialized_datetimes(d,json_fn):
+    """
+    Writes the object [d] to the .json file [json_fn] with a standard approach
+    to serializing Python datetime objects.
+    
+    Args:
+        d (obj): the object to write, typically a dict
+        json_fn (str): the output filename        
+    """
+    
+    # This writes datetimes as:
+    #
+    # 2022-12-31T09:52:50
+    def json_serialize_datetime(obj):
+        if isinstance(obj, (datetime.datetime, datetime.date)):
+            return obj.isoformat()
+        raise TypeError('Object {} (type {}) not serializable'.format(
+            str(obj),type(obj)))
+        
+    with open(json_fn,'w') as f:
+        json.dump(d,f,indent=1,default=json_serialize_datetime)
+
+
+def parse_datetimes_from_cct_image_list(images,conversion_failure_behavior='error'):
+    """
+    Given the "images" field from a COCO camera traps dictionary, converts all
+    string-formatted datetime fields to Python datetimes, making reasonable assumptions 
+    about datetime representations.  Modifies [images] in place.
+    
+    Args:
+        images (list): a list of dicts in CCT images format
+        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)
+    
+    Returns:
+        images: the input list, with datetimes converted (after modifying in place)
+    """
+    
+    assert isinstance(images,list)
+    
+    for im in images:
+        
+        if 'datetime' not in im:
+            continue
+        if isinstance(im['datetime'],datetime.datetime):
+            continue
+        try:
+            dt = dateutil.parser.parse(im['datetime'])
+            im['datetime'] = dt
+        except Exception as e:
+            s = 'could not parse datetime {}: {}'.format(str(im['datetime']),str(e))
+            if conversion_failure_behavior == 'error':
+                raise ValueError(s)
+            elif conversion_failure_behavior == 'str':
+                print('Warning: {}'.format(s))
+                pass
+            elif conversion_failure_behavior == 'none':
+                print('Warning: {}'.format(s))
+                im['datetime'] = None
+                
+    # ...for each image        
+    
+    return images
+    
+# ...def parse_datetimes_from_cct_image_list(...)
+
+
+def parse_datetimes_from_cct_dict(d,conversion_failure_behavior='error'):
+    """
+    Given a COCO camera traps dictionary that may just have been loaded from file,
+    converts all string-formatted datetime fields to Python datetimes, making
+    reasonable assumptions about datetime representations.  Modifies [d] in place
+    if [d] is supplied as a dict
+    
+    Args:
+        d (dict or str): a dict in CCT format or a filename pointing to a CCT .json file
+        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)
+    
+    Returns:
+        dict: the CCT dict with converted datetimes.
+    """
+    
+    if isinstance(d,str):        
+        assert os.path.isfile(d), 'Could not find .json file {}'.format(d)
+        with open(d,'r') as f:
+            d = json.load(f)
+    
+    images = d['images']
+    
+    # Modifies in place
+    _ = parse_datetimes_from_cct_image_list(images)
+    
+    return d
+            
+# ...def parse_datetimes_from_cct_dict(...)
+
+
 def create_sequences(image_info,options=None):
     """
     Synthesizes episodes/sequences/bursts for the images in [image_info].
@@ -310,21 +412,41 @@ def create_sequences(image_info,options=None):
     fields for each image.
     
     Args:
-        image_info (str, dict, or list): a dict in CCT format, a CCT .json file, or just the 'images' component
-            of a CCT dataset (a list of dicts with  fields 'file_name' (str), 'datetime' (datetime), and
-            'location' (str)).
+        image_info (str, dict, or list): a dict in CCT format, a CCT .json file, or just the 
+            'images' component of a CCT dataset (a list of dicts with  fields 'file_name' (str), 
+            'datetime' (datetime), and 'location' (str)).
+        options (SequenceOptions): options parameterizing the assembly of images into sequences;
+            see the SequenceOptions class for details.
+            
+    Returns:
+        image_info: if [image_info] is passed as a list, returns the list, otherwise returns
+            a CCT-formatted dict.
     """
     
     if options is None:
         options = SequenceOptions()
     
-    if isinstance(image_info,str):
+    to_return = None
+    
+    if isinstance(image_info,list):
+        to_return = image_info
+        
+    elif isinstance(image_info,str):
         with open(image_info,'r') as f:
-            image_info = json.load(f)
+            d = json.load(f)
+            to_return = d
+            image_info = d['images']
         
-    if isinstance(image_info,dict):
+    elif isinstance(image_info,dict):
+        to_return = image_info
         image_info = image_info['images']
+    
+    else:
+        raise ValueError('Unrecognized type for [image_info]')
         
+    # Modifies the images in place
+    _ = parse_datetimes_from_cct_image_list(image_info)
+    
     # Find all unique locations
     locations = set()
     for im in image_info:
@@ -401,4 +523,18 @@ def create_sequences(image_info,options=None):
     
     print('Created {} sequences from {} images'.format(len(all_sequences),len(image_info)))
     
-# ...create_sequences()
+    return to_return
+
+# ...def create_sequences(...)
+
+
+#%% Test drivers
+
+if False:
+    
+    pass
+
+    #%% 
+    
+    fn = r'g:\temp\test.json'
+    d = parse_datetimes_from_cct_dict(fn,conversion_failure_behavior='error')