megadetector 5.0.8__py3-none-any.whl → 5.0.10__py3-none-any.whl

md_visualization/visualize_db.py

@@ -1,16 +1,17 @@
-########
-#
-# 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
@@ -36,74 +37,99 @@ import md_visualization.visualization_utils as vis_utils
 #%% 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.
+    #: 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)
     
-    # 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).
+    #: 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
+    #: 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)        
@@ -114,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:
@@ -249,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
     
@@ -431,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')
     
@@ -500,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.8.dist-info → megadetector-5.0.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: megadetector
-Version: 5.0.8
+Version: 5.0.10
 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](https://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