megadetector 5.0.24__tar.gz → 5.0.25__tar.gz

{megadetector-5.0.24/megadetector.egg-info → megadetector-5.0.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: megadetector
-Version: 5.0.24
+Version: 5.0.25
 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>
@@ -58,6 +58,8 @@ This package is a pip-installable version of the support/inference code for [Meg
 
 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:

{megadetector-5.0.24 → megadetector-5.0.25}/README-package.md

@@ -4,6 +4,8 @@ This package is a pip-installable version of the support/inference code for [Meg
 
 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:

{megadetector-5.0.24 → megadetector-5.0.25}/README.md

@@ -10,12 +10,16 @@
 5. [Repo contents](#repo-contents)
 6. [Contact](#contact)
 7. [Gratuitous camera trap picture](#gratuitous-camera-trap-picture)
+8. [License](#license)
+9. [Contributing](#contributing)
 
 
 ## What's MegaDetector all about?
 
 [MegaDetector](megadetector.md) is an AI model that identifies animals, people, and vehicles in camera trap images (which also makes it useful for eliminating blank images).  This model is trained on several million images from a variety of ecosystems.
 
+MegaDetector only finds animals, it doesn't identify them to species level.  If you're looking for a species classifier, check out [SpeciesNet](https://github.com/google/cameratrapai), a species classifier that plays nicely with MegaDetector.
+
 Here's a “teaser” image of what MegaDetector output looks like:
 
 ![Red bounding box on fox](images/detector_example.jpg)<br/>Image credit University of Washington.
@@ -27,7 +31,7 @@ Here's a &ldquo;teaser&rdquo; image of what MegaDetector output looks like:
 * 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 [MegaDetector 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>!
+* If you have any questions, or you want to tell us that MegaDetector was amazing/terrible on your images, or you have a zillion images and you want some help digging out of that backlog, <a href="mailto:cameratraps@lila.science">email us</a>!
 
 MegaDetector is just one of many tools that aims to make conservation biologists more efficient with AI.  If you want to learn about other ways to use AI to accelerate camera trap workflows, check out our of the field, affectionately titled &ldquo;[Everything I know about machine learning and camera traps](https://agentmorris.github.io/camera-trap-ml-survey/)&rdquo;.
 
@@ -45,9 +49,9 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [Canadian Parks and Wilderness Society (CPAWS) Northern Alberta Chapter](https://cpawsnab.org/)
 * [Conservation X Labs](https://conservationxlabs.com/)
 * [Czech University of Life Sciences Prague](https://www.czu.cz/en)
-* [Dudek Camera Trap AI Image Toolkit (AIT)](https://dudek.com/services/wildlife-camera-trap-ai-image-processing-and-management/)
+* [Dudek Camera Trap AI Image Toolkit (AIT)](https://ait.dudek.com/)
 * [EcoLogic Consultants Ltd.](https://www.consult-ecologic.com/)
-* [Estación Biológica de Doñana](http://www.ebd.csic.es/inicio)
+* [Estación Biológica de Doñana](https://www.ebd.csic.es/)
 * [Indigenous Desert Alliance](https://www.indigenousdesertalliance.com/)
 * [Myall Lakes Dingo Project](https://carnivorecoexistence.info/myall-lakes-dingo-project/)
 * [Norwegian Institute for Nature Research](https://www.nina.no/english/Home)
@@ -84,7 +88,6 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [Department of Fish and Wildlife Sciences](https://www.uidaho.edu/cnr/departments/fish-and-wildlife-sciences), University of Idaho
 * [Department of Society & Conservation](https://www.umt.edu/environment/about/departments/socon/), W.A. Franke College of Forestry & Conservation, University of Montana
 * [Department of Wildlife Ecology and Conservation](https://wec.ifas.ufl.edu/), University of Florida
-* [Ecology and Conservation of Amazonian Vertebrates Research Group](https://www.researchgate.net/lab/Fernanda-Michalski-Lab-4), Federal University of Amapá
 * [Gola Forest Programme](https://www.rspb.org.uk/our-work/conservation/projects/scientific-support-for-the-gola-forest-programme/), Royal Society for the Protection of Birds (RSPB)
 * [Graeme Shannon's Research Group](https://wildliferesearch.co.uk/group-1), Bangor University 
 * [Grizzly Bear Recovery Program](https://www.fws.gov/office/grizzly-bear-recovery-program), U.S. Fish & Wildlife Service
@@ -102,12 +105,13 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [Santa Monica Mountains Recreation Area](https://www.nps.gov/samo/index.htm), National Park Service
 * [Seattle Urban Carnivore Project](https://www.zoo.org/seattlecarnivores), Woodland Park Zoo
 * [Serra dos Órgãos National Park](https://www.icmbio.gov.br/parnaserradosorgaos/), ICMBio
-* [Snapshot USA](https://emammal.si.edu/snapshot-usa), Smithsonian
+* [Snapshot USA](https://www.snapshot-usa.org/), Smithsonian
 * [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
+* Ecology and Conservation of Amazonian Vertebrates Research Group, Federal University of Amapá
 * Department of Ecology, TU Berlin
 * Ghost Cat Analytics
 * Protected Areas Unit, Canadian Wildlife Service
@@ -132,7 +136,7 @@ Here are a few of the organizations that have used MegaDetector... we're only li
 * [BirdLife Malta](https://birdlifemalta.org/) ([tweet](https://x.com/BirdLife_Malta/status/1817456839862173783?t=S-KRiZ5R1-CoW8-tbYNjqQ&s=03)) ([LI post](https://www.linkedin.com/posts/birdlifemalta_worldnatureconservationday-shearwater-colony-activity-7223220656589463553-X2Mc/?utm_source=share&utm_medium=member_android))
 * [Endangered Landscapes and Seascapes Programme](https://www.endangeredlandscapes.org/), Cambridge Conservation Initiative ([blog post](https://www.endangeredlandscapes.org/news/ai-for-wildlife-monitoring-a-real-time-alert-system-for-bears-and-wild-boars-in-romanias-carpathian-mountains/))
 
-* [Road Ecology Center](https://roadecology.ucdavis.edu/), University of California, Davis ([Wildlife Observer Network platform](https://wildlifeobserver.net/))
+* [Road Ecology Center](https://roadecology.ucdavis.edu/), University of California, Davis ([Wildlife Observer Network platform](https://roadecology.ucdavis.edu/research/projects/wildlife-observer-network))
 * [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))
@@ -202,9 +206,9 @@ Code for hosting our models as an API, either for synchronous operation (i.e., f
 
 #### megadetector/classification
 
-Experimental code for training species classifiers on new data sets, generally trained on MegaDetector crops.  Currently the main pipeline described in this folder relies on a large database of labeled images that is not publicly available; therefore, this folder is not yet set up to facilitate training of your own classifiers.  However, it is useful for <i>users</i> of the classifiers that we train, and contains some useful starting points if you are going to take a "DIY" approach to training classifiers on cropped images.  
+This folder is largely deprecated thanks to the release of [SpeciesNet](https://github.com/google/cameratrapai), a species classifier that is better than any of the classifiers we ever trained with the stuff in this folder.  That said, this folder contains code for training species classifiers on new data sets, generally trained on MegaDetector crops.
 
-All that said, here's another "teaser image" of what you get at the end of training and running a classifier:
+Here's another "teaser image" of what you get at the end of training and running a classifier:
 
 <img src="images/warthog_classifications.jpg" width="700"><br/>Image credit University of Minnesota, from the Snapshot Safari program.
 

megadetector-5.0.25/megadetector/data_management/lila/add_locations_to_island_camera_traps.py

@@ -0,0 +1,101 @@
+"""
+
+add_locations_to_island_camera_traps.py
+
+The Island Conservation Camera Traps dataset had unique camera identifiers embedded
+in filenames, but not in the proper metadata fields.  This script copies that information
+to metadata.
+
+"""
+
+#%% Imports and constants
+
+import os
+import json
+from tqdm import tqdm
+
+input_fn = os.path.expanduser('~/lila/metadata/island_conservation.json')
+output_fn = os.path.expanduser('~/tmp/island_conservation.json')
+preview_folder = os.path.expanduser('~/tmp/island_conservation_preview')
+image_directory = os.path.expanduser('~/data/icct/public/')
+
+
+#%% Prevent imports during testing
+
+if False:
+
+    #%% Read input file
+    
+    with open(input_fn,'r') as f:
+        d = json.load(f)
+        
+    d['info']
+    d['info']['version'] = '1.01'
+    
+    
+    #%% Find locations
+    
+    images = d['images']
+    
+    locations = set()
+    
+    for i_image,im in tqdm(enumerate(images),total=len(images)):
+        tokens_fn = im['file_name'].split('/')
+        tokens_id = im['id'].split('_')
+        assert tokens_fn[0] == tokens_id[0]
+        assert tokens_fn[1] == tokens_id[1]
+        location = tokens_fn[0] + '_' + tokens_fn[1]
+        im['location'] = location
+        locations.add(location)
+    
+    locations = sorted(list(locations))
+        
+    for s in locations:
+        print(s)
+        
+        
+    #%% Write output file
+    
+    with open(output_fn,'w') as f:
+        json.dump(d,f,indent=1)
+        
+    
+    #%% Validate .json files
+    
+    from megadetector.data_management.databases import integrity_check_json_db
+    
+    options = integrity_check_json_db.IntegrityCheckOptions()
+    options.baseDir = image_directory
+    options.bCheckImageSizes = False
+    options.bCheckImageExistence = True
+    options.bFindUnusedImages = True
+    
+    sorted_categories, data, error_info = integrity_check_json_db.integrity_check_json_db(output_fn, options)
+    
+    
+    #%% Preview labels
+    
+    from megadetector.visualization import visualize_db
+    
+    viz_options = visualize_db.DbVizOptions()
+    viz_options.num_to_visualize = 2000
+    viz_options.trim_to_images_with_bboxes = False
+    viz_options.add_search_links = False
+    viz_options.sort_by_filename = False
+    viz_options.parallelize_rendering = True
+    viz_options.classes_to_exclude = ['test']
+    html_output_file, image_db = visualize_db.visualize_db(db_path=output_fn,
+                                                             output_dir=preview_folder,
+                                                             image_base_dir=image_directory,
+                                                             options=viz_options)
+    
+    from megadetector.utils import path_utils
+    path_utils.open_file(html_output_file)
+    
+    
+    #%% Zip output file
+    
+    from megadetector.utils.path_utils import zip_file
+    
+    zip_file(output_fn, verbose=True)
+    assert os.path.isfile(output_fn + '.zip')

megadetector-5.0.25/megadetector/data_management/lila/add_locations_to_nacti.py

@@ -0,0 +1,151 @@
+"""
+
+add_locations_to_nacti.py
+
+As of 10.2023, NACTI metadata only has very coarse location information (e.g. "Florida"),
+but camera IDs are embedded in filenames.  This script pulls that information from filenames
+and adds it to metadata.
+
+"""
+
+#%% Imports and constants
+
+import os
+import json
+import shutil
+
+from tqdm import tqdm
+from collections import defaultdict
+
+input_file = r'd:\lila\nacti\nacti_metadata.json.1.13\nacti_metadata.json'
+output_file = r'g:\temp\nacti_metadata.1.14.json'
+
+
+#%% Prevent execution during testing
+
+if False:
+
+    #%% Read metadata
+    
+    with open(input_file,'r') as f:
+        d = json.load(f)
+        
+    assert d['info']['version'] == 1.13
+    
+    
+    #%% Map images to locations (according to the metadata)
+    
+    file_name_to_original_location = {}
+    
+    # im = dataset_labels['images'][0]
+    for im in tqdm(d['images']):
+        file_name_to_original_location[im['file_name']] = im['location']
+    
+    original_locations = set(file_name_to_original_location.values())
+    
+    print('Found {} locations in the original metadata:'.format(len(original_locations)))
+    for loc in original_locations:
+        print('[{}]'.format(loc))
+    
+    
+    #%% Map images to new locations
+    
+    def path_to_location(relative_path):
+        
+        relative_path = relative_path.replace('\\','/')
+        if relative_path in file_name_to_original_location:
+            location_name = file_name_to_original_location[relative_path]
+            if location_name == 'San Juan Mntns, Colorado':
+                # "part0/sub000/2010_Unit150_Ivan097_img0003.jpg"
+                tokens = relative_path.split('/')[-1].split('_')
+                assert tokens[1].startswith('Unit')
+                location_name = 'sanjuan_{}_{}_{}'.format(tokens[0],tokens[1],tokens[2])
+            elif location_name == 'Lebec, California':
+                # "part0/sub035/CA-03_08_13_2015_CA-03_0009738.jpg"
+                tokens = relative_path.split('/')[-1].split('_')
+                assert tokens[0].startswith('CA-') or tokens[0].startswith('TAG-')
+                location_name = 'lebec_{}'.format(tokens[0])   
+            elif location_name == 'Archbold, FL':
+                # "part1/sub110/FL-01_01_25_2016_FL-01_0040421.jpg"
+                tokens = relative_path.split('/')[-1].split('_')
+                assert tokens[0].startswith('FL-')
+                location_name = 'archbold_{}'.format(tokens[0])   
+            else:
+                assert location_name == ''
+                tokens = relative_path.split('/')[-1].split('_')
+                if tokens[0].startswith('CA-') or tokens[0].startswith('TAG-') or tokens[0].startswith('FL-'):
+                    location_name = '{}'.format(tokens[0])
+                
+        else:
+            
+            location_name = 'unknown'    
+        
+        # print('Returning location {} for file {}'.format(location_name,relative_path))          
+    
+        return location_name
+    
+    file_name_to_updated_location = {}
+    updated_location_to_count = defaultdict(int)
+    for im in tqdm(d['images']):
+        
+        updated_location = path_to_location(im['file_name'])
+        file_name_to_updated_location[im['file_name']] = updated_location
+        updated_location_to_count[updated_location] += 1
+    
+    updated_location_to_count = {k: v for k, v in sorted(updated_location_to_count.items(), 
+                             key=lambda item: item[1],
+                             reverse=True)}
+    
+    updated_locations = set(file_name_to_updated_location.values())
+    
+    print('Found {} updated locations in the original metadata:'.format(len(updated_locations)))
+    for loc in updated_location_to_count:
+        print('{}: {}'.format(loc,updated_location_to_count[loc]))
+    
+    
+    #%% Re-write metadata
+    
+    for im in d['images']:
+        im['location'] = file_name_to_updated_location[im['file_name']]
+    d['info']['version'] = 1.14
+    
+    with open(output_file,'w') as f:
+        json.dump(d,f,indent=1)
+        
+    
+    #%% For each location, sample some random images to make sure they look consistent
+    
+    input_base = r'd:\lila\nacti-unzipped'
+    assert os.path.isdir(input_base)
+    
+    location_to_images = defaultdict(list)
+    
+    for im in d['images']:
+        location_to_images[im['location']].append(im)
+        
+    n_to_sample = 10
+    import random
+    random.seed(0)
+    sampling_folder_base = r'g:\temp\nacti_samples'
+    
+    for location in tqdm(location_to_images):
+        
+        images_this_location = location_to_images[location]
+        if len(images_this_location) > n_to_sample:
+            images_this_location = random.sample(images_this_location,n_to_sample)
+            
+        for i_image,im in enumerate(images_this_location):
+            
+            fn_relative = im['file_name']
+            source_fn_abs = os.path.join(input_base,fn_relative)
+            assert os.path.isfile(source_fn_abs)
+            ext = os.path.splitext(fn_relative)[1]            
+            target_fn_abs = os.path.join(sampling_folder_base,'{}/{}'.format(
+                location,'image_{}{}'.format(str(i_image).zfill(2),ext)))
+            os.makedirs(os.path.dirname(target_fn_abs),exist_ok=True)
+            shutil.copyfile(source_fn_abs,target_fn_abs)
+            
+        # ...for each image
+        
+    # ...for each location
+                

megadetector-5.0.24/megadetector/data_management/wi_to_md.py → megadetector-5.0.25/megadetector/data_management/speciesnet_to_md.py

@@ -2,7 +2,7 @@
 
 wi_to_md.py
 
-Converts the WI predictions.json format to MD .json format.  This is just a 
+Converts the WI (SpeciesNet) predictions.json format to MD .json format.  This is just a 
 command-line wrapper around utils.wi_utils.generate_md_results_from_predictions_json.
 
 """
@@ -20,7 +20,7 @@ def main():
     
     parser = argparse.ArgumentParser()
     parser.add_argument('predictions_json_file', action='store', type=str, 
-                        help='.json file to convert from predictions.json format to MD format')
+                        help='.json file to convert from SpeciesNet predictions.json format to MD format')
     parser.add_argument('md_results_file', action='store', type=str, 
                         help='output file to write in MD format')
     parser.add_argument('--base_folder', action='store', type=str, default=None, 

{megadetector-5.0.24 → megadetector-5.0.25}/megadetector/detection/run_detector.py

@@ -96,6 +96,7 @@ model_string_to_model_version = {
     'cedar':'v1000.0.0-cedar',
     'larch':'v1000.0.0-larch',
     'default':'v5a.0.0',
+    'default-model':'v5a.0.0',
     'megadetector':'v5a.0.0'
 }
 

{megadetector-5.0.24 → megadetector-5.0.25}/megadetector/detection/run_detector_batch.py

@@ -735,7 +735,7 @@ def load_and_run_detector_batch(model_file,
     """
     
     # Validate input arguments
-    if n_cores is None:
+    if n_cores is None or n_cores <= 0:
         n_cores = 1
     
     if confidence_threshold is None:
@@ -1331,13 +1331,14 @@ def main():
     parser.add_argument(
         '--ncores',
         type=int,
-        default=0,
-        help='Number of cores to use for inference; only applies to CPU-based inference')
+        default=1,
+        help='Number of cores to use for inference; only applies to CPU-based inference (default 1)')
     parser.add_argument(
         '--loader_workers',
         type=int,
         default=default_loaders,
-        help='Number of image loader workers to use; only relevant when --use_image_queue is set')
+        help='Number of image loader workers to use; only relevant when --use_image_queue ' + \
+            'is set (default {})'.format(default_loaders))
     parser.add_argument(
         '--class_mapping_filename',
         type=str,

{megadetector-5.0.24 → megadetector-5.0.25}/megadetector/postprocessing/compare_batch_results.py

@@ -138,6 +138,9 @@ class BatchComparisonOptions:
         #: List of filenames to include in the comparison, or None to use all files
         self.filenames_to_include = None
         
+        #: List of category names to include in the comparison, or None to use all categories
+        self.category_names_to_include = None
+        
         #: Compare only detections/non-detections, ignore categories (still renders categories)
         self.class_agnostic_comparison = False
         
@@ -986,7 +989,32 @@ def _pairwise_compare_batch_results(options,output_index,pairwise_options):
             if invalid_category_error:
                 
                 continue
-                        
+            
+            # Should we be restricting the comparison to only certain categories?
+            if options.category_names_to_include is not None:
+                
+                # Just in case the user provided a single category instead of a list
+                if isinstance(options.category_names_to_include,str):
+                    options.category_names_to_include = [options.category_names_to_include]
+                    
+                category_name_to_id_a = invert_dictionary(detection_categories_a)
+                category_name_to_id_b = invert_dictionary(detection_categories_b)
+                category_ids_to_include_a = []
+                category_ids_to_include_b = []
+                
+                for category_name in options.category_names_to_include:
+                    if category_name in category_name_to_id_a:
+                        category_ids_to_include_a.append(category_name_to_id_a[category_name])
+                    if category_name in category_name_to_id_b:
+                        category_ids_to_include_b.append(category_name_to_id_b[category_name])
+                
+                # Restrict the categories we treat as above-threshold to the set we're supposed
+                # to be using
+                categories_above_threshold_a = [category_id for category_id in categories_above_threshold_a if \
+                                                category_id in category_ids_to_include_a]
+                categories_above_threshold_b = [category_id for category_id in categories_above_threshold_b if \
+                                                category_id in category_ids_to_include_b]
+            
             detection_a = (len(categories_above_threshold_a) > 0)
             detection_b = (len(categories_above_threshold_b) > 0)
                             
@@ -1609,7 +1637,72 @@ def n_way_comparison(filenames,
 # ...def n_way_comparison(...)
 
 
-def find_equivalent_threshold(results_a,results_b,threshold_a=0.2):
+def find_image_level_detections_above_threshold(results,threshold=0.2,category_names=None):
+    """
+    Returns images in the set of MD results [results] with detections above
+    a threshold confidence level, optionally only counting certain categories.
+    
+    Args:
+        results (str or dict): the set of results, either a .json filename or a results
+            dict
+        threshold (float, optional): the threshold used to determine the target number of 
+            detections in [results]
+        category_names (list or str, optional): the list of category names to consider (defaults
+            to using all categories), or the name of a single category.        
+    
+    Returns:
+        list: the images with above-threshold detections
+    """
+    if isinstance(results,str):
+        with open(results,'r') as f:
+            results = json.load(f)
+            
+    category_ids_to_consider = None
+    
+    if category_names is not None:
+        
+        if isinstance(category_names,str):
+            category_names = [category_names]
+        
+        category_id_to_name = results['detection_categories']
+        category_name_to_id = invert_dictionary(category_id_to_name)
+        
+        category_ids_to_consider = []
+        
+        # category_name = category_names[0]
+        for category_name in category_names:
+            category_id = category_name_to_id[category_name]
+            category_ids_to_consider.append(category_id)
+            
+        assert len(category_ids_to_consider) > 0, \
+            'Category name list did not map to any category IDs'
+        
+    images_above_threshold = []
+    
+    for im in results['images']:
+        
+        if ('detections' in im) and (im['detections'] is not None) and (len(im['detections']) > 0):
+            confidence_values_this_image = [0]
+            for det in im['detections']:
+                if category_ids_to_consider is not None:
+                    if det['category'] not in category_ids_to_consider:
+                        continue
+                confidence_values_this_image.append(det['conf'])
+            if max(confidence_values_this_image) >= threshold:
+                images_above_threshold.append(im)
+                
+    # ...for each image
+    
+    return images_above_threshold
+
+# ...def find_image_level_detections_above_threshold(...)
+
+
+def find_equivalent_threshold(results_a,
+                              results_b,
+                              threshold_a=0.2,
+                              category_names=None,
+                              verbose=False):
     """
     Given two sets of detector results, finds the confidence threshold for results_b
     that produces the same fraction of *images* with detections as threshold_a does for 
@@ -1622,6 +1715,9 @@ def find_equivalent_threshold(results_a,results_b,threshold_a=0.2):
             dict
         threshold_a (float, optional): the threshold used to determine the target number of 
             detections in results_a
+        category_names (list or str, optional): the list of category names to consider (defaults
+            to using all categories), or the name of a single category.
+        verbose (bool, optional): enable additional debug output
             
     Returns:
         float: the threshold that - when applied to results_b - produces the same number
@@ -1629,35 +1725,106 @@ def find_equivalent_threshold(results_a,results_b,threshold_a=0.2):
     """
     
     if isinstance(results_a,str):
+        if verbose:
+            print('Loading results from {}'.format(results_a))
         with open(results_a,'r') as f:
             results_a = json.load(f)
     
     if isinstance(results_b,str):
+        if verbose:
+            print('Loading results from {}'.format(results_b))
         with open(results_b,'r') as f:
             results_b = json.load(f)
+    
+    category_ids_to_consider_a = None
+    category_ids_to_consider_b = None
+    
+    if category_names is not None:
+        
+        if isinstance(category_names,str):
+            category_names = [category_names]
+        
+        categories_a = results_a['detection_categories']
+        categories_b = results_b['detection_categories']
+        category_name_to_id_a = invert_dictionary(categories_a)
+        category_name_to_id_b = invert_dictionary(categories_b)
+        
+        category_ids_to_consider_a = []
+        category_ids_to_consider_b = []
+        
+        # category_name = category_names[0]
+        for category_name in category_names:
+            category_id_a = category_name_to_id_a[category_name]
+            category_id_b = category_name_to_id_b[category_name]
+            category_ids_to_consider_a.append(category_id_a)
+            category_ids_to_consider_b.append(category_id_b)
             
-    def get_confidence_values_for_results(images):
+        assert len(category_ids_to_consider_a) > 0 and len(category_ids_to_consider_b) > 0, \
+            'Category name list did not map to any category IDs in one or both detection sets'
+    
+    def _get_confidence_values_for_results(images,category_ids_to_consider,threshold):
+        """
+        Return a list of the maximum confidence value for each image in [images].
+        Returns zero confidence for images with no detections (or no detections
+        in the specified categories).  Does not return anything for invalid images.
+        """
+        
         confidence_values = []
+        images_above_threshold = []
+        
         for im in images:
             if 'detections' in im and im['detections'] is not None:
                 if len(im['detections']) == 0:
                     confidence_values.append(0)
                 else:
-                    confidence_values_this_image = [det['conf'] for det in im['detections']]
-                    confidence_values.append(max(confidence_values_this_image))                
-        return confidence_values
+                    confidence_values_this_image = []
+                    for det in im['detections']:
+                        if category_ids_to_consider is not None:
+                            if det['category'] not in category_ids_to_consider:
+                                continue
+                        confidence_values_this_image.append(det['conf'])
+                    if len(confidence_values_this_image) == 0:
+                        confidence_values.append(0)
+                    else:
+                        max_conf_value = max(confidence_values_this_image)
+                        
+                        if threshold is not None and max_conf_value >= threshold:
+                            images_above_threshold.append(im)
+                        confidence_values.append(max_conf_value)
+        # ...for each image
+        
+        return confidence_values, images_above_threshold
     
-    confidence_values_a = get_confidence_values_for_results(results_a['images'])
+    confidence_values_a,images_above_threshold_a = \
+        _get_confidence_values_for_results(results_a['images'],
+                                          category_ids_to_consider_a,
+                                          threshold_a)
+        
+    # ...def _get_confidence_values_for_results(...)
+        
+    if verbose:
+        print('For result set A, considering {} of {} images'.format(
+            len(confidence_values_a),len(results_a['images'])))
     confidence_values_a_above_threshold = [c for c in confidence_values_a if c >= threshold_a]
     
-    confidence_values_b = get_confidence_values_for_results(results_b['images'])
-    confidence_values_b = sorted(confidence_values_b)                
+    confidence_values_b,_ = _get_confidence_values_for_results(results_b['images'],
+                                                              category_ids_to_consider_b,
+                                                              threshold=None)
+    if verbose:
+        print('For result set B, considering {} of {} images'.format(
+            len(confidence_values_b),len(results_b['images'])))
+    confidence_values_b = sorted(confidence_values_b)        
         
     target_detection_fraction = len(confidence_values_a_above_threshold) / len(confidence_values_a)
         
     detection_cutoff_index = round((1.0-target_detection_fraction) * len(confidence_values_b))    
     threshold_b = confidence_values_b[detection_cutoff_index]
     
+    if verbose:
+        print('{} confidence values above threshold (A)'.format(len(confidence_values_a_above_threshold)))
+        confidence_values_b_above_threshold = [c for c in confidence_values_b if c >= threshold_b]
+        print('{} confidence values above threshold (B)'.format(len(confidence_values_b_above_threshold)))
+            
     return threshold_b
 
 # ...def find_equivalent_threshold(...)