megadetector 5.0.7__py3-none-any.whl → 5.0.9__py3-none-any.whl

md_visualization/visualize_db.py

@@ -1,101 +1,135 @@
-########
-#
-# visualize_db.py
-# 
-# Outputs an HTML page visualizing annotations (class labels and/or bounding boxes)
-# on a sample of images in a database in the COCO Camera Traps format.
-#
-########
+"""
+
+visualize_db.py
+
+Outputs an HTML page visualizing annotations (class labels and/or bounding boxes)
+on a sample of images in a database in the COCO Camera Traps format.
+
+"""
 
 #%% Imports
 
 import argparse
 import inspect
+import random
 import json
 import math
 import os
 import sys
 import time
+
+import pandas as pd
+import numpy as np
+
+import humanfriendly
+
 from itertools import compress
 from multiprocessing.pool import ThreadPool
 from multiprocessing.pool import Pool
-
-import pandas as pd
 from tqdm import tqdm
-import humanfriendly
 
 from md_utils.write_html_image_list import write_html_image_list
+from data_management.cct_json_utils import IndexedJsonDb
 
 import md_visualization.visualization_utils as vis_utils
-from data_management.cct_json_utils import IndexedJsonDb
 
 
 #%% Settings
 
 class DbVizOptions:
+    """
+    Parameters controlling the behavior of visualize_db().
+    """
     
-    # Set to None to visualize all images
+    #: Number of images to sample from the database, or None to visualize all images
     num_to_visualize = None
     
-    # Target size for rendering; set either dimension to -1 to preserve aspect ratio
-    #
-    # If viz_size is None or (-1,-1), the original image size is used.
-    viz_size = (675, -1)
-    
-    # The most relevant option one might want to set here is:
-    #
-    # htmlOptions['maxFiguresPerHtmlFile']
-    #
-    # ...which can be used to paginate previews to a number of images that will load well
-    # in a browser (5000 is a reasonable limit).
+    #: Target size for rendering; set either dimension to -1 to preserve aspect ratio.
+    #:
+    #: If viz_size is None or (-1,-1), the original image size is used.
+    viz_size = (800, -1)
+    
+    #: HTML rendering options; see write_html_image_list for details
+    #:
+    #:The most relevant option one might want to set here is:
+    #:
+    #: htmlOptions['maxFiguresPerHtmlFile']
+    #:
+    #: ...which can be used to paginate previews to a number of images that will load well
+    #: in a browser (5000 is a reasonable limit).
     htmlOptions = write_html_image_list()
     
+    #: Whether to sort images by filename (True) or randomly (False)
     sort_by_filename = True
+    
+    #: Only show images that contain bounding boxes
     trim_to_images_with_bboxes = False
     
-    random_seed = 0 # None
+    #: Random seed to use for sampling images
+    random_seed = 0
     
-    # Should we include Web search links for each category name?    
+    #: Should we include Web search links for each category name?    
     add_search_links = False
     
-    # Should each thumbnail image link back to the original image?
+    #: Should each thumbnail image link back to the original image?
     include_image_links = False
     
-    # Should there be a text link back to each original image?
+    #: Should there be a text link back to each original image?
     include_filename_links = False
     
+    #: Line width in pixels
     box_thickness = 4
+    
+    #: Number of pixels to expand each bounding box
     box_expansion = 0
     
-    # These are mutually exclusive; both are category names, not IDs
-    classes_to_exclude = None
+    #: Only include images that contain annotations with these class names (not IDs)
+    #:
+    #: Mutually exclusive with classes_to_exclude
     classes_to_include = None
     
-    # Special tag used to say "show me all images with multiple categories"
+    #: Exclude images that contain annotations with these class names (not IDs)
+    #:
+    #: Mutually exclusive with classes_to_include
+    classes_to_exclude = None
+    
+    #: Special tag used to say "show me all images with multiple categories"
+    #:
+    #: :meta private:
     multiple_categories_tag = '*multiple*'
 
-    # We sometimes flatten image directories by replacing a path separator with 
-    # another character.  Leave blank for the typical case where this isn't necessary.
+    #: We sometimes flatten image directories by replacing a path separator with 
+    #: another character.  Leave blank for the typical case where this isn't necessary.
     pathsep_replacement = '' # '~'
 
-    # Control rendering parallelization
-    parallelize_rendering_n_cores = 25
+    #: Parallelize rendering across multiple workers
+    parallelize_rendering = False
     
-    # Process-based parallelization in this function is currently unsupported
-    # due to pickling issues I didn't care to look at, but I'm going to just
-    # flip this with a warning, since I intend to support it in the future.
+    #: In theory, whether to parallelize with threads (True) or processes (False), but
+    #: process-based parallelization in this function is currently unsupported
     parallelize_rendering_with_threads = True
-    parallelize_rendering = False
     
-    # Should we show absolute (vs. relative) paths for each image?
+    #: Number of workers to use for parallelization; ignored if parallelize_rendering
+    #: is False
+    parallelize_rendering_n_cores = 25
+        
+    #: Should we show absolute (True) or relative (False) paths for each image?
     show_full_paths = False
     
+    #: Set to False to skip existing images
+    force_rendering = True
+    
+    #: Enable additionald debug console output
+    verbose = False
+    
 
 #%% Helper functions
 
-# Translate the file name in an image entry in the json database to a path, possibly doing
-# some manipulation of path separators
-def image_filename_to_path(image_file_name, image_base_dir, pathsep_replacement=''):
+def _image_filename_to_path(image_file_name, image_base_dir, pathsep_replacement=''):
+    """
+    Translates the file name in an image entry in the json database to a path, possibly doing
+    some manipulation of path separators.
+    """
     
     if len(pathsep_replacement) > 0:
         image_file_name = os.path.normpath(image_file_name).replace(os.pathsep,pathsep_replacement)        
@@ -106,14 +140,16 @@ def image_filename_to_path(image_file_name, image_base_dir, pathsep_replacement=
 
 def visualize_db(db_path, output_dir, image_base_dir, options=None):
     """
-    Writes images and html to output_dir to visualize the annotations in the json file
-    db_path.
+    Writes images and html to output_dir to visualize the annotations in a .json file.
     
-    db_path can also be a previously-loaded database.
+    Args:
+        db_path (str or dict): the .json filename to load, or a previously-loaded database
+        image_base_dir (str): the folder where the images live; filenames in [db_path] should
+            be relative to this folder.
+        options (DbVizOptions, optional): See DbVizOptions for details
     
-    Returns the html filename and the database:
-        
-    return htmlOutputFile,image_db
+    Returns:
+        tuple: A length-two tuple containing (the html filename) and (the loaded database).        
     """    
     
     if options is None:
@@ -241,7 +277,7 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
             img_path = image_base_dir + img_relative_path
         else:
             img_path = os.path.join(image_base_dir, 
-                                    image_filename_to_path(img_relative_path, image_base_dir))
+                                    _image_filename_to_path(img_relative_path, image_base_dir))
     
         annos_i = df_anno.loc[df_anno['image_id'] == img_id, :] # all annotations on this image
     
@@ -272,7 +308,7 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
             categoryName = label_map[categoryID]
             if options.add_search_links:
                 categoryName = categoryName.replace('"','')
-                categoryName = '<a href="https://www.bing.com/images/search?q={}">{}</a>'.format(
+                categoryName = '<a href="https://www.google.com/search?tbm=isch&q={}">{}</a>'.format(
                     categoryName,categoryName)
             imageCategories.add(categoryName)
             
@@ -317,14 +353,22 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         if options.include_filename_links:
             filename_text = '<a href="{}">{}</a>'.format(img_path,filename_text)
             
+        flagString = ''
+        
+        def isnan(x):
+            return (isinstance(x,float) and np.isnan(x))
+        
+        if ('flags' in img) and (not isnan(img['flags'])):
+            flagString = ', flags: {}'.format(str(img['flags']))
+            
         # We're adding html for an image before we render it, so it's possible this image will
         # fail to render.  For applications where this script is being used to debua a database
         # (the common case?), this is useful behavior, for other applications, this is annoying.
         image_dict = \
         {
             'filename': '{}/{}'.format('rendered_images', file_name),
-            'title': '{}<br/>{}, num boxes: {}, {}class labels: {}{}'.format(
-                filename_text, img_id, len(bboxes), frameString, imageClasses, labelLevelString),
+            'title': '{}<br/>{}, num boxes: {}, {}class labels: {}{}{}'.format(
+                filename_text, img_id, len(bboxes), frameString, imageClasses, labelLevelString, flagString),
             'textStyle': 'font-family:verdana,arial,calibri;font-size:80%;' + \
                 'text-align:left;margin-top:20;margin-bottom:5'
         }
@@ -341,7 +385,13 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         bboxes = rendering_info['bboxes']
         bboxClasses = rendering_info['boxClasses']
         output_file_name = rendering_info['output_file_name']
+        output_full_path = os.path.join(output_dir, 'rendered_images', output_file_name)
         
+        if (os.path.isfile(output_full_path)) and (not options.force_rendering):
+            if options.verbose:
+                print('Skipping existing image {}'.format(output_full_path))
+            return True
+            
         if not img_path.startswith('http'):
             if not os.path.exists(img_path):
                 print('Image {} cannot be found'.format(img_path))
@@ -356,7 +406,7 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
                 image = vis_utils.resize_image(original_image, options.viz_size[0],
                                                options.viz_size[1])
         except Exception as e:
-            print('Image {} failed to open. Error: {}'.format(img_path, e))
+            print('Image {} failed to open, error: {}'.format(img_path, e))
             return False
             
         vis_utils.render_db_bounding_boxes(boxes=bboxes, classes=bboxClasses,
@@ -365,7 +415,8 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
                                            thickness=options.box_thickness,
                                            expansion=options.box_expansion)
         
-        image.save(os.path.join(output_dir, 'rendered_images', output_file_name))
+        image.save(output_full_path)
+                
         return True
     
     # ...def render_image_info
@@ -408,6 +459,8 @@ def visualize_db(db_path, output_dir, image_base_dir, options=None):
         
     if options.sort_by_filename:    
         images_html = sorted(images_html, key=lambda x: x['filename'])
+    else:
+        random.shuffle(images_html)
         
     htmlOutputFile = os.path.join(output_dir, 'index.html')
     
@@ -477,9 +530,7 @@ def main():
         
     visualize_db(options.db_path,options.output_dir,options.image_base_dir,options) 
 
-
-if __name__ == '__main__':
-    
+if __name__ == '__main__':    
     main()
 
 

md_visualization/visualize_detector_output.py

@@ -1,11 +1,11 @@
-########
-#
-# visualize_detector_output.py
-#
-# Render images with bounding boxes annotated on them to a folder, based on a
-# detector output result file (json), optionally writing an HTML index file.
-#
-########
+"""
+
+visualize_detector_output.py
+
+Render images with bounding boxes annotated on them to a folder, based on a
+detector output result file (.json), optionally writing an HTML index file.
+
+"""
 
 #%% Imports
 
@@ -38,11 +38,14 @@ DEFAULT_DETECTOR_LABEL_MAP = {
 
 #%% Support functions
 
-def render_image(entry,
+def _render_image(entry,
                  detector_label_map,classification_label_map,
                  confidence_threshold,classification_confidence_threshold,
                  render_detections_only,preserve_path_structure,out_dir,images_dir,
                  output_image_width):
+    """
+    Internal function for rendering a single image.
+    """
     
     rendering_result = {'failed_image':False,'missing_image':False,
                         'skipped_image':False,'annotated_image_path':None,
@@ -97,38 +100,55 @@ def render_image(entry,
 
 #%% Main function
 
-def visualize_detector_output(detector_output_path: str,
-                              out_dir: str,
-                              images_dir: str,
-                              confidence_threshold: float = 0.15,
-                              sample: int = -1,
-                              output_image_width: int = 700,
-                              random_seed: int = None,
-                              render_detections_only: bool = False,
-                              classification_confidence_threshold = 0.1,
-                              html_output_file = None,
-                              html_output_options = None,
-                              preserve_path_structure = False,
-                              parallelize_rendering = False,
-                              parallelize_rendering_n_cores = 10,
-                              parallelize_rendering_with_threads = True) -> List[str]:
+def visualize_detector_output(detector_output_path,
+                              out_dir,
+                              images_dir,
+                              confidence_threshold=0.15,
+                              sample=-1,
+                              output_image_width=700,
+                              random_seed=None,
+                              render_detections_only=False,
+                              classification_confidence_threshold=0.1,
+                              html_output_file=None,
+                              html_output_options=None,
+                              preserve_path_structure=False,
+                              parallelize_rendering=False,
+                              parallelize_rendering_n_cores=10,
+                              parallelize_rendering_with_threads=True):
     
     """
-    Draw bounding boxes on images given the output of a detector.
+    Draws bounding boxes on images given the output of a detector.
 
     Args:
-        detector_output_path: str, path to detector output json file
-        out_dir: str, path to directory for saving annotated images
-        images_dir: str, path to images dir
-        confidence: float, threshold above which annotations will be rendered
-        sample: int, maximum number of images to annotate, -1 for all
-        random_seed: seed for sampling (not relevant if sample == -1)
-        output_image_width: int, width in pixels to resize images for display,
-            set to -1 to use original image width
-        random_seed: int, for deterministic image sampling when sample != -1
-        render_detections_only: bool, only render images with above-threshold detections
-
-    Returns: list of str, paths to annotated images
+        detector_output_path (str): path to detector output .json file
+        out_dir (str): path to directory for saving annotated images
+        images_dir (str): folder where the images live; filenames in 
+            [detector_output_path] should be relative to [image_dir]
+        confidence_threshold (float, optional): threshold above which detections will be rendered
+        sample (int, optional): maximum number of images to render, -1 for all
+        output_image_width (int, optional): width in pixels to resize images for display,
+            preserving aspect ration; set to -1 to use original image width
+        random_seed (int, optional): seed to use for choosing images when sample != -1
+        render_detections_only (bool): only render images with above-threshold detections
+        classification_confidence_threshold (float, optional): only show classifications
+            above this threshold; does not impact whether images are rendered, only whether
+            classification labels (not detection categories) are displayed
+        html_output_file (str, optional): output path for an HTML index file (not written
+            if None)
+        html_output_options (dict, optional): HTML formatting options; see write_html_image_list 
+            for details
+        preserve_path_structure (bool, optional): if False (default), writes images to unique
+            names in a flat structure in the output folder; if True, preserves relative paths
+            within the output folder
+        parallelize_rendering (bool, optional): whether to use concurrent workers for rendering
+        parallelize_rendering_n_cores (int, optional): number of concurrent workers to use 
+            (ignored if parallelize_rendering is False)
+        parallelize_rendering_with_threads (bool, optional): determines whether we use
+            threads (True) or processes (False) for parallelization (ignored if parallelize_rendering 
+            is False)
+
+    Returns:
+        list: list of paths to annotated images
     """
     
     assert os.path.exists(detector_output_path), \
@@ -209,7 +229,7 @@ def visualize_detector_output(detector_output_path: str,
             print('Rendering images with {} {}'.format(parallelize_rendering_n_cores,
                                                        worker_string))            
         rendering_results = list(tqdm(pool.imap(
-                                 partial(render_image,detector_label_map=detector_label_map,
+                                 partial(_render_image,detector_label_map=detector_label_map,
                                          classification_label_map=classification_label_map,
                                          confidence_threshold=confidence_threshold,
                                          classification_confidence_threshold=classification_confidence_threshold,
@@ -224,7 +244,7 @@ def visualize_detector_output(detector_output_path: str,
                 
         for entry in tqdm(images):
             
-            rendering_result = render_image(entry,detector_label_map,classification_label_map,
+            rendering_result = _render_image(entry,detector_label_map,classification_label_map,
                                             confidence_threshold,classification_confidence_threshold,
                                             render_detections_only,preserve_path_structure,out_dir,
                                             images_dir,output_image_width)
@@ -269,9 +289,8 @@ def visualize_detector_output(detector_output_path: str,
 
 #%% Command-line driver
 
-def main() -> None:
-    """Main function."""
-
+def main():
+    
     parser = argparse.ArgumentParser(
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
         description='Annotate the bounding boxes predicted by a detector above '

{megadetector-5.0.7.dist-info → megadetector-5.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: megadetector
-Version: 5.0.7
+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 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
@@ -95,18 +101,16 @@ temporary_filename = url_utils.download_url(image_url)
 
 image = vis_utils.load_image(temporary_filename)
 
-# This will automatically download MDv5a to the system temp folder;
-# you can also specify a filename explicitly, or set the $MDV5A
-# environment variable to point to the model file.
+# 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 {} detection above threshold'.format(len(detections_above_threshold)))
+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
@@ -120,14 +124,14 @@ 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 to the system temp folder;
-# you can also specify a filename explicitly, or set the $MDV5A
-# environment variable to point to the model file.
+# This will automatically download MDv5a; you can also specify a filename.
 results = load_and_run_detector_batch('MDV5A', image_file_names)
 
-# Write results as relative filenames, this is what Timelapse
-# and other downstream tools expect.
-write_results_to_file(results,output_file,relative_path_base=image_folder)
+# 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