megadetector 5.0.8__tar.gz → 5.0.9__tar.gz

{megadetector-5.0.8/megadetector.egg-info → megadetector-5.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: megadetector
-Version: 5.0.8
+Version: 5.0.9
 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>
@@ -25,6 +25,7 @@ License:     MIT License
             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
@@ -51,16 +52,16 @@ 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), an object detection model that helps conservation biologists spend less time doing boring things with camera trap images.
+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.  Complete documentation for this Python package is available at <megadetector.readthedocs.io>.
 
-If you want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector).
+If you aren't looking for the Python package specificaly, and you just 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 Python package.
+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/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.  That journey will <i>not</i> involve this Python package.
 
 ### If you are a computer-vision-y type...
 
@@ -80,9 +81,14 @@ To install:
 
 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
+## Package reference
 
-#### Run MegaDetector on one image and count the number of detections
+See <megadetector.readthedocs.io>.
+
+
+## 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
@@ -104,7 +110,7 @@ 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
+### Run MegaDetector on a folder of images
 
 ```
 from detection.run_detector_batch import load_and_run_detector_batch,write_results_to_file

{megadetector-5.0.8 → megadetector-5.0.9}/README-package.md

@@ -1,15 +1,15 @@
 # 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.
+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.  Complete documentation for this Python package is available at <megadetector.readthedocs.io>.
 
-If you want to learn more about what MegaDetector is all about, head over to the [MegaDetector repo](https://github.com/agentmorris/MegaDetector).
+If you aren't looking for the Python package specificaly, and you just 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 Python package.
+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/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.  That journey will <i>not</i> involve this Python package.
 
 ### If you are a computer-vision-y type...
 
@@ -29,9 +29,14 @@ To install:
 
 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
+## Package reference
 
-#### Run MegaDetector on one image and count the number of detections
+See <megadetector.readthedocs.io>.
+
+
+## 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
@@ -53,7 +58,7 @@ 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
+### Run MegaDetector on a folder of images
 
 ```
 from detection.run_detector_batch import load_and_run_detector_batch,write_results_to_file

{megadetector-5.0.8 → megadetector-5.0.9}/README.md

@@ -23,7 +23,7 @@ Here's a “teaser” image of what MegaDetector output looks like:
 ## How do I get started with MegaDetector?
 
 * If you are looking for a convenient tool to run MegaDetector, you don't need anything from this repository: check out [EcoAssist](https://github.com/PetervanLunteren/EcoAssist?tab=readme-ov-file).
-* If you're just <i>considering</i> the use of AI in your workflow, and you aren't even sure yet whether MegaDetector would be useful to you, we recommend reading the "[getting started with MegaDetector](collaborations.md)" page.
+* If you're just <i>considering</i> the use of AI in your workflow, and you aren't even sure yet whether MegaDetector would be useful to you, we recommend reading the "[getting started with MegaDetector](getting-started.md)" page.
 * If you're already familiar with MegaDetector and you're ready to run it on your data, see the [MegaDetector User Guide](megadetector.md) for instructions on running MegaDetector.
 * If you're a programmer-type looking to use tools from this repo, check out the [Python package](https://pypi.org/project/megadetector/) that provides access to everything in this repo (yes, you guessed it, "pip install megadetector").
 * If you have any questions, or you want to tell us that MegaDetector was amazing/terrible on your images, <a href="mailto:cameratraps@lila.science">email us</a>!
@@ -33,7 +33,7 @@ MegaDetector is just one of many tools that aims to make conservation biologists
 
 ## Who is using MegaDetector?
 
-We work with ecologists all over the world to help them spend less time annotating images and more time thinking about conservation.  You can read a little more about how this works on our [getting started with MegaDetector](collaborations.md) page.
+We work with ecologists all over the world to help them spend less time annotating images and more time thinking about conservation.  You can read a little more about how this works on our [getting started with MegaDetector](getting-started.md) page.
 
 Here are a few of the organizations that have used MegaDetector... we're only listing organizations who (a) we know about and (b) have given us permission to refer to them here (or have posted publicly about their use of MegaDetector), so if you're using MegaDetector or other tools from this repo and would like to be added to this list, <a href="mailto:cameratraps@lila.science">email us</a>!
 
@@ -85,6 +85,7 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [Hamaarag](https://hamaarag.org.il/), The Steinhardt Museum of Natural History, Tel Aviv University
 * [Institut des Science de la Forêt Tempérée](https://isfort.uqo.ca/) (ISFORT), Université du Québec en Outaouais
 * [Lab of Dr. Bilal Habib](https://bhlab.in/about), the Wildlife Institute of India
+* [Landscape Ecology Lab](https://www.concordia.ca/artsci/geography-planning-environment/research/labs/lel.html), Concordia University
 * [Mammal Spatial Ecology and Conservation Lab](https://labs.wsu.edu/dthornton/), Washington State University
 * [McLoughlin Lab in Population Ecology](http://mcloughlinlab.ca/lab/), University of Saskatchewan
 * [National Wildlife Refuge System, Southwest Region](https://www.fws.gov/about/region/southwest), U.S. Fish & Wildlife Service
@@ -184,7 +185,7 @@ Code for:
 
 ### detection
 
-Code for training, running, and evaluating MegaDetector.
+Code for running models, especially MegaDetector.
 
 
 ### envs
@@ -204,7 +205,7 @@ Small utility functions for string manipulation, filename manipulation, download
 
 ### md_visualization
 
-Shared tools for visualizing images with ground truth and/or predicted annotations.
+Tools for visualizing images with ground truth and/or predicted annotations.
 
 
 ### sandbox

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/api_core/batch_service/score.py

@@ -435,6 +435,5 @@ def main():
     with open(task_output_path, 'w', encoding='utf-8') as f:
         json.dump(detections, f, ensure_ascii=False)
 
-
 if __name__ == '__main__':
     main()

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/api_core/server_job_status_table.py

@@ -148,6 +148,5 @@ class TestJobStatusTable(unittest.TestCase):
         item_read = table.read_job_status(job_id)
         self.assertIsNone(item_read)
 
-
 if __name__ == '__main__':
     unittest.main()

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/api_core_support/aggregate_results_manually.py

@@ -42,6 +42,5 @@ def main():
     output_file_urls_str = json.dumps(output_file_urls)
     print(output_file_urls_str)
 
-
 if __name__ == '__main__':
     main()

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/api_support/summarize_daily_activity.py

@@ -148,6 +148,5 @@ def main():
         send_message()
         time.sleep(24 * 60 * 60)
 
-
 if __name__ == '__main__':
     main()

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/data_preparation/manage_local_batch.py

@@ -1,64 +1,64 @@
-########
-#
-# manage_local_batch.py
-#    
-# Semi-automated process for managing a local MegaDetector job, including
-# standard postprocessing steps.
-#
-# This script is not intended to be run from top to bottom like a typical Python script,
-# it's a notebook disguised with a .py extension.  It's the Bestest Most Awesome way to
-# run MegaDetector, but it's also pretty subtle; if you want to play with this, you might
-# want to check in with cameratraps@lila.science for some tips.  Otherwise... YMMV.
-#
-# Some general notes on using this script, which I do in Spyder, though everything will be
-# the same if you are reading this in Jupyter Notebook (using the .ipynb version of the 
-# script):
-#
-# * Typically when I have a MegaDetector job to run, I make a copy of this script.  Let's 
-#   say I'm running a job for an organization called "bibblebop"; I have a big folder of
-#   job-specific copies of this script, and I might save a new one called "bibblebop-2023-07-26.py" 
-#   (the filename doesn't matter, it just helps me keep these organized).
-#
-# * There are three variables you need to set in this script before you start running code:
-#   "input_path", "organization_name_short", and "job_date".  You will get a sensible error if you forget 
-#   to set any of these.  In this case I might set those to "/data/bibblebobcamerastuff",
-#   "bibblebop", and "2023-07-26", respectively.
-#
-# * The defaults assume you want to split the job into two tasks (this is the default because I have 
-#   two GPUs).  Nothing bad will happen if you do this on a zero-GPU or single-GPU machine, but if you
-#   want everything to run in one logical task, change "n_gpus" and "n_jobs" to 1 (instead of 2).
-#
-# * After setting the required variables, I run the first few cells - up to and including the one 
-#   called "Generate commands" - which collectively take basically zero seconds.  After you run the
-#   "Generate commands" cell, you will have a folder that looks something like:
-#
-#   ~/postprocessing/bibblebop/bibblebop-2023-07-06-mdv5a/
-#  
-#   On Windows, this means:
-#
-#   ~/postprocessing/bibblebop/bibblebop-2023-07-06-mdv5a/    
-#
-#   Everything related to this job - scripts, outputs, intermediate stuff - will be in this folder.
-#   Specifically, after the "Generate commands" cell, you'll have scripts in that folder called something
-#   like:
-#
-#   run_chunk_000_gpu_00.sh (or .bat on Windows)
-#
-#   Personally, I like to run that script directly in a command prompt (I just leave Spyder open, though 
-#   it's OK if Spyder gets shut down while MD is running).  
-#
-#   At this point, once you get the hang of it, you've invested about zero seconds of human time,
-#   but possibly several days of unattended compute time, depending on the size of your job.
-#   
-# * Then when the jobs are done, back to the interactive environment!  I run the next few cells,
-#   which make sure the job finished OK, and the cell called "Post-processing (pre-RDE)", which 
-#   generates an HTML preview of the results.  You are very plausibly done at this point, and can ignore
-#   all the remaining cells.  If you want to do things like repeat detection elimination, or running 
-#   a classifier, or splitting your results file up in specialized ways, there are cells for all of those
-#   things, but now you're in power-user territory, so I'm going to leave this guide here.  Email
-#   cameratraps@lila.science with questions about the fancy stuff.
-#
-########
+"""
+
+manage_local_batch.py
+   
+Semi-automated process for managing a local MegaDetector job, including
+standard postprocessing steps.
+
+This script is not intended to be run from top to bottom like a typical Python script,
+it's a notebook disguised with a .py extension.  It's the Bestest Most Awesome way to
+run MegaDetector, but it's also pretty subtle; if you want to play with this, you might
+want to check in with cameratraps@lila.science for some tips.  Otherwise... YMMV.
+
+Some general notes on using this script, which I do in Spyder, though everything will be
+the same if you are reading this in Jupyter Notebook (using the .ipynb version of the 
+script):
+
+* Typically when I have a MegaDetector job to run, I make a copy of this script.  Let's 
+  say I'm running a job for an organization called "bibblebop"; I have a big folder of
+  job-specific copies of this script, and I might save a new one called "bibblebop-2023-07-26.py" 
+  (the filename doesn't matter, it just helps me keep these organized).
+
+* There are three variables you need to set in this script before you start running code:
+  "input_path", "organization_name_short", and "job_date".  You will get a sensible error if you forget 
+  to set any of these.  In this case I might set those to "/data/bibblebobcamerastuff",
+  "bibblebop", and "2023-07-26", respectively.
+
+* The defaults assume you want to split the job into two tasks (this is the default because I have 
+  two GPUs).  Nothing bad will happen if you do this on a zero-GPU or single-GPU machine, but if you
+  want everything to run in one logical task, change "n_gpus" and "n_jobs" to 1 (instead of 2).
+
+* After setting the required variables, I run the first few cells - up to and including the one 
+  called "Generate commands" - which collectively take basically zero seconds.  After you run the
+  "Generate commands" cell, you will have a folder that looks something like:
+
+  ~/postprocessing/bibblebop/bibblebop-2023-07-06-mdv5a/
+ 
+  On Windows, this means:
+
+  ~/postprocessing/bibblebop/bibblebop-2023-07-06-mdv5a/    
+
+  Everything related to this job - scripts, outputs, intermediate stuff - will be in this folder.
+  Specifically, after the "Generate commands" cell, you'll have scripts in that folder called something
+  like:
+
+  run_chunk_000_gpu_00.sh (or .bat on Windows)
+
+  Personally, I like to run that script directly in a command prompt (I just leave Spyder open, though 
+  it's OK if Spyder gets shut down while MD is running).  
+
+  At this point, once you get the hang of it, you've invested about zero seconds of human time,
+  but possibly several days of unattended compute time, depending on the size of your job.
+  
+* Then when the jobs are done, back to the interactive environment!  I run the next few cells,
+  which make sure the job finished OK, and the cell called "Post-processing (pre-RDE)", which 
+  generates an HTML preview of the results.  You are very plausibly done at this point, and can ignore
+  all the remaining cells.  If you want to do things like repeat detection elimination, or running 
+  a classifier, or splitting your results file up in specialized ways, there are cells for all of those
+  things, but now you're in power-user territory, so I'm going to leave this guide here.  Email
+  cameratraps@lila.science with questions about the fancy stuff.
+
+"""
 
 #%% Imports and constants
 
@@ -803,7 +803,7 @@ if render_animals_only:
 os.makedirs(output_base, exist_ok=True)
 print('Processing to {}'.format(output_base))
 
-options.api_output_file = combined_api_output_file
+options.md_results_file = combined_api_output_file
 options.output_dir = output_base
 ppresults = process_batch_results(options)
 html_output_file = ppresults.output_html_file
@@ -939,7 +939,7 @@ os.makedirs(output_base, exist_ok=True)
 
 print('Processing post-RDE to {}'.format(output_base))
 
-options.api_output_file = filtered_output_filename
+options.md_results_file = filtered_output_filename
 options.output_dir = output_base
 ppresults = process_batch_results(options)
 html_output_file = ppresults.output_html_file
@@ -2014,7 +2014,7 @@ output_base = os.path.join(postprocessing_output_folder, folder_token + \
 os.makedirs(output_base, exist_ok=True)
 print('Processing {} to {}'.format(base_task_name, output_base))
 
-options.api_output_file = sequence_smoothed_classification_file
+options.md_results_file = sequence_smoothed_classification_file
 options.output_dir = output_base
 ppresults = process_batch_results(options)
 path_utils.open_file(ppresults.output_html_file,attempt_to_open_in_wsl_host=True,browser_name='chrome')
@@ -2134,7 +2134,7 @@ output_base_large_boxes = os.path.join(postprocessing_output_folder,
 os.makedirs(output_base_large_boxes, exist_ok=True)
 print('Processing post-RDE, post-size-separation to {}'.format(output_base_large_boxes))
 
-options.api_output_file = size_separated_file
+options.md_results_file = size_separated_file
 options.output_dir = output_base_large_boxes
 
 ppresults = process_batch_results(options)

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/data_preparation/manage_video_batch.py

@@ -1,11 +1,11 @@
-########
-#
-# manage_video_batch.py
-#
-# Notebook-esque script to manage the process of running a local batch of videos
-# through MD.  Defers most of the heavy lifting to manage_local_batch.py .
-#
-########
+"""
+
+manage_video_batch.py
+
+Notebook-esque script to manage the process of running a local batch of videos
+through MD.  Defers most of the heavy lifting to manage_local_batch.py .
+
+"""
 
 #%% Imports and constants
 

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/integration/digiKam/xmp_integration.py

@@ -460,7 +460,6 @@ def main():
     else:
         process_input_data(options)
 
-
 if __name__ == '__main__':
     
     main()

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/integration/eMammal/test_scripts/push_annotations_to_emammal.py

@@ -121,7 +121,6 @@ def main():
             update_data(sql)
             mysql_connection.commit()
 
-
 if __name__ == '__main__':
     main()
 

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/postprocessing/add_max_conf.py

@@ -1,15 +1,15 @@
-########
-#
-# add_max_conf.py
-#
-# The MD output format included a "max_detection_conf" field with each image
-# up to and including version 1.2; it was removed as of version 1.3 (it's
-# redundant with the individual detection confidence values).
-#
-# Just in case someone took a dependency on that field, this script allows you
-# to add it back to an existing .json file.
-#
-########
+"""
+
+add_max_conf.py
+
+The MD output format included a "max_detection_conf" field with each image
+up to and including version 1.2; it was removed as of version 1.3 (it's
+redundant with the individual detection confidence values).
+
+Just in case someone took a dependency on that field, this script allows you
+to add it back to an existing .json file.
+
+"""
 
 #%% Imports and constants
 

{megadetector-5.0.8 → megadetector-5.0.9}/api/batch_processing/postprocessing/categorize_detections_by_size.py

@@ -1,11 +1,11 @@
-########
-#
-# categorize_detections_by_size.py
-#
-# Given an API output .json file, creates a separate category for bounding boxes
-# above one or more size thresholds.
-# 
-########
+"""
+
+categorize_detections_by_size.py
+
+Given a MegaDetector .json file, creates a separate category for bounding boxes
+above one or more size thresholds.
+
+"""
 
 #%% Constants and imports
 
@@ -18,24 +18,42 @@ from tqdm import tqdm
 #%% Support classes
 
 class SizeCategorizationOptions:
-
-    # Should be sorted from smallest to largest
+    """
+    Options used to parameterize categorize_detections_by_size().
+    """
+    
+    #: Thresholds to use for separation, as a fraction of the image size.
+    #:
+    #: Should be sorted from smallest to largest.
     size_thresholds = [0.95]
     
-    # List of category numbers to use in separation; uses all categories if None
+    #: List of category numbers to use in separation; uses all categories if None
     categories_to_separate = None
     
-    # Can be "size", "width", or "height"
+    #: Dimension to use for thresholding; can be "size", "width", or "height"
     measurement = 'size'
     
-    # Should have the same length as "size_thresholds"
+    #: Categories to assign to thresholded ranges; should have the same length as
+    #: "size_thresholds".
     size_category_names = ['large_detection']
     
                                                  
 #%% Main functions
     
 def categorize_detections_by_size(input_file,output_file=None,options=None):
-    
+    """
+    Given a MegaDetector .json file, creates a separate category for bounding boxes
+    above one or more size thresholds, optionally writing results to [output_file].
+    
+    Args:
+        input_file (str): file to process
+        output_file (str, optional): optional output file
+        options (SizeCategorizationOptions): categorization parameters
+        
+    Returns:
+        dict: data loaded from [input_file], with the new size-based categories.        
+        Identical to what's written to [output_file], if [output_file] is not None.
+    """
     if options is None:
         options = SizeCategorizationOptions()