megadetector 5.0.29__py3-none-any.whl → 10.0.0__py3-none-any.whl

megadetector/detection/video_utils.py

@@ -431,7 +431,9 @@ def video_to_frames(input_video_file,
         frames_to_extract (list of int, optional): extract this specific set of frames;
             mutually exclusive with every_n_frames.  If all values are beyond the length
             of the video, no frames are extracted.  Can also be a single int, specifying
-            a single frame number.
+            a single frame number.  In the special case where frames_to_extract
+            is [], this function still reads video frame rates and verifies that videos
+            are readable, but no frames are extracted.
         allow_empty_videos (bool, optional): Just print a warning if a video appears to have no
             frames (by default, this is an error).
 
@@ -450,7 +452,10 @@ def video_to_frames(input_video_file,
     if (frames_to_extract is not None) and (every_n_frames is not None):
         raise ValueError('frames_to_extract and every_n_frames are mutually exclusive')
 
-    os.makedirs(output_folder,exist_ok=True)
+    bypass_extraction = ((frames_to_extract is not None) and (len(frames_to_extract) == 0))
+
+    if not bypass_extraction:
+        os.makedirs(output_folder,exist_ok=True)
 
     vidcap = cv2.VideoCapture(input_video_file)
     n_frames = int(vidcap.get(cv2.CAP_PROP_FRAME_COUNT))
@@ -464,7 +469,7 @@ def video_to_frames(input_video_file,
                 every_n_seconds,every_n_frames))
 
     # If we're not over-writing, check whether all frame images already exist
-    if not overwrite:
+    if (not overwrite) and (not bypass_extraction):
 
         missing_frame_number = None
         missing_frame_filename = None
@@ -514,7 +519,6 @@ def video_to_frames(input_video_file,
 
         # When specific frames are requested, if anything is missing, reprocess the video
         if (frames_to_extract is not None) and (missing_frame_number is not None):
-
             pass
 
         # If no frames are missing, or only frames very close to the end of the video are "missing",
@@ -572,6 +576,10 @@ def video_to_frames(input_video_file,
     # for frame_number in tqdm(range(0,n_frames)):
     for frame_number in range(0,n_frames):
 
+        # Special handling for the case where we're just doing dummy reads
+        if bypass_extraction:
+            break
+
         success,image = vidcap.read()
         if not success:
             assert image is None
@@ -643,9 +651,9 @@ def video_to_frames(input_video_file,
 
     if len(frame_filenames) == 0:
         if allow_empty_videos:
-            print('Warning: found no frames in file {}'.format(input_video_file))
+            print('Warning: no frames extracted from file {}'.format(input_video_file))
         else:
-            raise Exception('Error: found no frames in file {}'.format(input_video_file))
+            raise Exception('Error: no frames extracted from file {}'.format(input_video_file))
 
     if verbose:
         print('\nExtracted {} of {} frames for {}'.format(
@@ -726,7 +734,9 @@ def video_folder_to_frames(input_folder,
         frames_to_extract (list of int, optional): extract this specific set of frames from
             each video; mutually exclusive with every_n_frames.  If all values are beyond
             the length of a video, no frames are extracted. Can also be a single int,
-            specifying a single frame number.
+            specifying a single frame number.  In the special case where frames_to_extract
+            is [], this function still reads video frame rates and verifies that videos
+            are readable, but no frames are extracted.
         allow_empty_videos (bool, optional): Just print a warning if a video appears to have no
             frames (by default, this is an error).
 
@@ -762,9 +772,16 @@ def video_folder_to_frames(input_folder,
         for input_fn_relative in tqdm(input_files_relative_paths):
 
             frame_filenames,fs = \
-                _video_to_frames_for_folder(input_fn_relative,input_folder,output_folder_base,
-                                            every_n_frames,overwrite,verbose,quality,max_width,
-                                            frames_to_extract,allow_empty_videos)
+                _video_to_frames_for_folder(input_fn_relative,
+                                            input_folder,
+                                            output_folder_base,
+                                            every_n_frames,
+                                            overwrite,
+                                            verbose,
+                                            quality,
+                                            max_width,
+                                            frames_to_extract,
+                                            allow_empty_videos)
             frame_filenames_by_video.append(frame_filenames)
             fs_by_video.append(fs)
     else:
@@ -778,15 +795,15 @@ def video_folder_to_frames(input_folder,
                 print('Starting a worker pool with {} processes'.format(n_threads))
                 pool = Pool(n_threads)
             process_video_with_options = partial(_video_to_frames_for_folder,
-                                                input_folder=input_folder,
-                                                output_folder_base=output_folder_base,
-                                                every_n_frames=every_n_frames,
-                                                overwrite=overwrite,
-                                                verbose=verbose,
-                                                quality=quality,
-                                                max_width=max_width,
-                                                frames_to_extract=frames_to_extract,
-                                                allow_empty_videos=allow_empty_videos)
+                                                 input_folder=input_folder,
+                                                 output_folder_base=output_folder_base,
+                                                 every_n_frames=every_n_frames,
+                                                 overwrite=overwrite,
+                                                 verbose=verbose,
+                                                 quality=quality,
+                                                 max_width=max_width,
+                                                 frames_to_extract=frames_to_extract,
+                                                 allow_empty_videos=allow_empty_videos)
             results = list(tqdm(pool.imap(
                 partial(process_video_with_options),input_files_relative_paths),
                                 total=len(input_files_relative_paths)))
@@ -822,6 +839,9 @@ class FrameToVideoOptions:
         #: video; can be 'error' or 'skip_with_warning'
         self.non_video_behavior = 'error'
 
+        #: Are frame rates required?
+        self.frame_rates_are_required = False
+
 
 def frame_results_to_video_results(input_file,
                                    output_file,
@@ -839,13 +859,18 @@ def frame_results_to_video_results(input_file,
         output_file (str): the .json file to which we should write video-level results
         options (FrameToVideoOptions, optional): parameters for converting frame-level results
             to video-level results, see FrameToVideoOptions for details
-        video_filename_to_frame_rate (dict): maps (relative) video path names to frame rates,
-            used only to populate the output file
+        video_filename_to_frame_rate (dict, optional): maps (relative) video path names to frame
+            rates, used only to populate the output file
     """
 
     if options is None:
         options = FrameToVideoOptions()
 
+    if options.frame_rates_are_required:
+        assert video_filename_to_frame_rate is not None, \
+            'You specified that frame rates are required, but you did not ' + \
+            'supply video_filename_to_frame_rate'
+
     # Load results
     with open(input_file,'r') as f:
         input_data = json.load(f)
@@ -902,9 +927,13 @@ def frame_results_to_video_results(input_file,
         im_out = {}
         im_out['file'] = video_name
 
-        if (video_filename_to_frame_rate is not None) and \
-            (video_name in video_filename_to_frame_rate):
-            im_out['frame_rate'] = video_filename_to_frame_rate[video_name]
+        if (video_filename_to_frame_rate is not None):
+
+            if options.frame_rates_are_required:
+                assert video_name in video_filename_to_frame_rate, \
+                    'Could not determine frame rate for {}'.format(video_name)
+            if video_name in video_filename_to_frame_rate:
+                im_out['frame_rate'] = video_filename_to_frame_rate[video_name]
 
         # Find all detections for this video
         all_detections_this_video = []

megadetector/postprocessing/add_max_conf.py

@@ -26,6 +26,10 @@ from megadetector.utils import ct_utils
 def add_max_conf(input_file,output_file):
     """
     Add maximum confidence values to [input_file] and write the results to [output_file].
+
+    Args:
+        input_file (str): MD-formatted .json file to which we should add maxconf values
+        output_file (str): output .json file
     """
 
     assert os.path.isfile(input_file), "Can't find input file {}".format(input_file)

megadetector/postprocessing/categorize_detections_by_size.py

@@ -50,7 +50,7 @@ def categorize_detections_by_size(input_file,output_file=None,options=None):
     Args:
         input_file (str): file to process
         output_file (str, optional): optional output file
-        options (SizeCategorizationOptions): categorization parameters
+        options (SizeCategorizationOptions, optional): categorization parameters
 
     Returns:
         dict: data loaded from [input_file], with the new size-based categories.

megadetector/postprocessing/classification_postprocessing.py

@@ -121,9 +121,17 @@ class ClassificationSmoothingOptions:
         #: if this is True, we'll make a copy of the input dict before modifying.
         self.modify_in_place = False
 
+        #: Only include these categories in the smoothing process (None to use all categories)
+        self.detection_category_names_to_smooth = ['animal']
+
         #: Debug options
         self.break_at_image = None
 
+        ## Populated internally
+
+        #: #: Only include these categories in the smoothing process (None to use all categories)
+        self._detection_category_ids_to_smooth = None
+
 
 #%% Utility functions
 
@@ -149,6 +157,23 @@ def _sort_images_by_time(images):
     return sorted(images, key = lambda im: im['datetime'])
 
 
+def _detection_is_relevant_for_smoothing(det,options):
+    """
+    Determine whether [det] has classifications that might be meaningful for smoothing.
+    """
+
+    if ('classifications' not in det) or \
+        (det['conf'] < options.detection_confidence_threshold):
+        return False
+
+    # Ignore non-smoothed categories
+    if (options._detection_category_ids_to_smooth is not None) and \
+        (det['category'] not in options._detection_category_ids_to_smooth):
+        return False
+
+    return True
+
+
 def count_detections_by_classification_category(detections,options=None):
     """
     Count the number of instances of each classification category in the detections list
@@ -159,7 +184,7 @@ def count_detections_by_classification_category(detections,options=None):
     Only processes the top classification for each detection.
 
     Args:
-        detections: detections list
+        detections (list of dict): detections list
         options (ClassificationSmoothingOptions, optional): see ClassificationSmoothingOptions
 
     Returns:
@@ -175,11 +200,13 @@ def count_detections_by_classification_category(detections,options=None):
     category_to_count = defaultdict(int)
 
     for det in detections:
-        if ('classifications' in det) and (det['conf'] >= options.detection_confidence_threshold):
-            # assert len(det['classifications']) == 1
-            c = det['classifications'][0]
-            if c[1] >= options.classification_confidence_threshold:
-                category_to_count[c[0]] += 1
+
+        if not _detection_is_relevant_for_smoothing(det,options):
+            continue
+
+        c = det['classifications'][0]
+        if c[1] >= options.classification_confidence_threshold:
+            category_to_count[c[0]] += 1
 
     category_to_count = {k: v for k, v in sorted(category_to_count.items(),
                                                  key=lambda item: item[1],
@@ -233,6 +260,8 @@ def _prepare_results_for_smoothing(input_file,options):
     Load results from [input_file] if necessary, prepare category descriptions
     for smoothing.  Adds pre-smoothing descriptions to every image if the options
     say we're supposed to do that.
+
+    May modify some fields in [options].
     """
 
     if isinstance(input_file,str):
@@ -256,6 +285,16 @@ def _prepare_results_for_smoothing(input_file,options):
         if s in category_name_to_id:
             other_category_ids.append(category_name_to_id[s])
 
+    # Possibly update the list of category IDs we should smooth
+    if options.detection_category_names_to_smooth is None:
+        options._detection_category_ids_to_smooth = None
+    else:
+        detection_category_id_to_name = d['detection_categories']
+        detection_category_name_to_id = invert_dictionary(detection_category_id_to_name)
+        options._detection_category_ids_to_smooth = []
+        for category_name in options.detection_category_names_to_smooth:
+            options._detection_category_ids_to_smooth.append(detection_category_name_to_id[category_name])
+
     # Before we do anything else, get rid of everything but the top classification
     # for each detection, and remove the 'classifications' field from detections with
     # no classifications.
@@ -283,8 +322,9 @@ def _prepare_results_for_smoothing(input_file,options):
     # ...for each image
 
 
-    ## Clean up classification descriptions so we can test taxonomic relationships
-    ## by substring testing.
+    ## Clean up classification descriptions...
+
+    # ...so we can test taxonomic relationships by substring testing.
 
     classification_descriptions_clean = None
     classification_descriptions = None
@@ -395,8 +435,7 @@ def _smooth_classifications_for_list_of_detections(detections,
 
         for det in detections:
 
-            if ('classifications' not in det) or \
-                (det['conf'] < options.detection_confidence_threshold):
+            if not _detection_is_relevant_for_smoothing(det,options):
                 continue
 
             assert len(det['classifications']) == 1
@@ -450,8 +489,7 @@ def _smooth_classifications_for_list_of_detections(detections,
         # i_det = 0; det = detections[i_det]
         for i_det,det in enumerate(detections):
 
-            if ('classifications' not in det) or \
-                (det['conf'] < options.detection_confidence_threshold):
+            if not _detection_is_relevant_for_smoothing(det,options):
                 continue
 
             assert len(det['classifications']) == 1
@@ -532,8 +570,7 @@ def _smooth_classifications_for_list_of_detections(detections,
         # det = detections[3]
         for det in detections:
 
-            if ('classifications' not in det) or \
-                (det['conf'] < options.detection_confidence_threshold):
+            if not _detection_is_relevant_for_smoothing(det,options):
                 continue
 
             assert len(det['classifications']) == 1
@@ -660,8 +697,7 @@ def _smooth_classifications_for_list_of_detections(detections,
         # det = detections[0]
         for det in detections:
 
-            if ('classifications' not in det) or \
-                (det['conf'] < options.detection_confidence_threshold):
+            if not _detection_is_relevant_for_smoothing(det,options):
                 continue
 
             assert len(det['classifications']) == 1
@@ -720,7 +756,6 @@ def _smooth_classifications_for_list_of_detections(detections,
 
     # ...if the dominant category is legit and we have taxonomic information available
 
-
     return {'n_other_classifications_changed_this_image':n_other_classifications_changed_this_image,
             'n_detections_flipped_this_image':n_detections_flipped_this_image,
             'n_taxonomic_changes_this_image':n_taxonomic_changes_this_image,
@@ -894,8 +929,8 @@ def smooth_classification_results_sequence_level(input_file,
 
     Args:
         input_file (str or dict): MegaDetector-formatted classification results file to smooth
-          (or already-loaded results).  If you supply a dict, it's modified in place by default, but
-          a copy can be forced by setting options.modify_in_place=False.
+          (or already-loaded results).  If you supply a dict, it's copied by default, but
+          in-place modification is supported via options.modify_in_place.
         cct_sequence_information (str, dict, or list): COCO Camera Traps file containing sequence IDs for
           each image (or an already-loaded CCT-formatted dict, or just the 'images' list from a CCT dict).
         output_file (str, optional): .json file to write smoothed results
@@ -1074,7 +1109,7 @@ def restrict_to_taxa_list(taxa_list,
             For example, if only a single felid species is allowed, should other
             felid predictions be mapped to that species, as opposed to being mapped
             to the family?
-        add_pre_restriction_description (bool, optional): should we add a new metadata
+        add_pre_filtering_description (bool, optional): should we add a new metadata
             field that summarizes each image's classifications prior to taxonomic
             restriction?
     """

megadetector/postprocessing/combine_batch_outputs.py

@@ -43,8 +43,9 @@ def combine_batch_output_files(input_files,
     Args:
         input_files (list of str): paths to JSON detection files
         output_file (str, optional): path to write merged JSON
-        require_uniqueness (bool): whether to require that the images in
+        require_uniqueness (bool, optional): whether to require that the images in
             each list of images be unique
+        verbose (bool, optional): enable additional debug output
 
     Returns:
         dict: merged dictionaries loaded from [input_files], identical to what's
@@ -80,7 +81,7 @@ def combine_batch_output_dictionaries(input_dicts, require_uniqueness=True):
     Args:
         input_dicts (list of dicts): list of dicts in which each dict represents the
             contents of a MD output file
-        require_uniqueness (bool): whether to require that the images in
+        require_uniqueness (bool, optional): whether to require that the images in
             each input dict be unique; if this is True and image filenames are
             not unique, an error is raised.
 

megadetector/postprocessing/compare_batch_results.py

@@ -32,6 +32,7 @@ Operates in one of three modes, depending on whether ground truth labels/boxes a
 
 import json
 import os
+import re
 import random
 import copy
 import urllib
@@ -207,6 +208,9 @@ class BatchComparisonOptions:
         #: output page?
         self.parse_link_paths = True
 
+        #: Should we include a TOC?  TOC is always omitted if <=2 comparisons are performed.
+        self.include_toc = True
+
 # ...class BatchComparisonOptions
 
 
@@ -235,6 +239,12 @@ class PairwiseBatchComparisonResults:
         #: Values are dicts with fields 'im_a', 'im_b', 'sort_conf', and 'im_gt'
         self.categories_to_image_pairs = None
 
+        #: Short identifier for this comparison
+        self.comparison_short_name = None
+
+        #: Friendly identifier for this comparison
+        self.comparison_friendly_name = None
+
 # ...class PairwiseBatchComparisonResults
 
 
@@ -254,7 +264,7 @@ class BatchComparisonResults:
 # ...class BatchComparisonResults
 
 
-main_page_style_header = """<head>
+main_page_style_header = """<head><title>Results comparison</title>
     <style type="text/css">
     a { text-decoration: none; }
     body { font-family: segoe ui, calibri, "trebuchet ms", verdana, arial, sans-serif; }
@@ -375,7 +385,7 @@ def _render_image_pair(fn,image_pairs,category_folder,options,pairwise_options):
 
                 try:
                     font = ImageFont.truetype('arial.ttf', 25)
-                except IOError:
+                except OSError:
                     font = ImageFont.load_default()
 
                 draw = ImageDraw.Draw(im)
@@ -1456,14 +1466,35 @@ def _pairwise_compare_batch_results(options,output_index,pairwise_options):
         try:
             pool.close()
             pool.join()
-            print("Pool closed and joined for comparisong rendering")
+            print("Pool closed and joined for comparison rendering")
         except Exception:
             pass
     ##%% Write the top-level HTML file content
 
     html_output_string  = ''
 
-    html_output_string += '<p>Comparing <b>{}</b> (A, {}) to <b>{}</b> (B, {})</p>'.format(
+    def _sanitize_id_name(s, lower=True):
+        """
+        Remove characters in [s] that are not allowed in HTML id attributes
+        """
+
+        s = re.sub(r'[^a-zA-Z0-9_-]', '', s)
+        s = re.sub(r'^[^a-zA-Z]*', '', s)
+        if lower:
+            s = s.lower()
+        return s
+
+    comparison_short_name = '{}_vs_{}'.format(
+        _sanitize_id_name(pairwise_options.results_description_a),
+        _sanitize_id_name(pairwise_options.results_description_b))
+
+    comparison_friendly_name = '{} vs {}'.format(
+        pairwise_options.results_description_a,
+        pairwise_options.results_description_b
+    )
+
+    html_output_string += '<p id="{}">Comparing <b>{}</b> (A, {}) to <b>{}</b> (B, {})</p>'.format(
+        comparison_short_name,
         pairwise_options.results_description_a,color_string_a.lower(),
         pairwise_options.results_description_b,color_string_b.lower())
     html_output_string += '<div class="contentdiv">\n'
@@ -1515,6 +1546,8 @@ def _pairwise_compare_batch_results(options,output_index,pairwise_options):
 
     pairwise_results = PairwiseBatchComparisonResults()
 
+    pairwise_results.comparison_short_name = comparison_short_name
+    pairwise_results.comparison_friendly_name = comparison_friendly_name
     pairwise_results.html_content = html_output_string
     pairwise_results.pairwise_options = pairwise_options
     pairwise_results.categories_to_image_pairs = categories_to_image_pairs
@@ -1555,20 +1588,32 @@ def compare_batch_results(options):
     all_pairwise_results = []
 
     # i_comparison = 0; pairwise_options = pairwise_options_list[i_comparison]
-
     for i_comparison,pairwise_options in enumerate(pairwise_options_list):
+
         print('Running comparison {} of {}'.format(i_comparison,n_comparisons))
         pairwise_results = \
             _pairwise_compare_batch_results(options,i_comparison,pairwise_options)
         html_content += pairwise_results.html_content
         all_pairwise_results.append(pairwise_results)
 
+    # ...for each pairwise comparison
+
     html_output_string = main_page_header
     job_name_string = ''
     if len(options.job_name) > 0:
         job_name_string = ' for {}'.format(options.job_name)
     html_output_string += '<h2>Comparison of results{}</h2>\n'.format(
         job_name_string)
+
+    if options.include_toc and (len(pairwise_options_list) > 2):
+        toc_string = '<p><b>Contents</b></p>\n'
+        toc_string += '<div class="contentdiv">\n'
+        for r in all_pairwise_results:
+            toc_string += '<a href="#{}">{}</a><br/>'.format(r.comparison_short_name,
+                                                            r.comparison_friendly_name)
+        toc_string += '</div>\n'
+        html_output_string += toc_string
+
     html_output_string += html_content
     html_output_string += main_page_footer
 
@@ -1832,9 +1877,12 @@ def find_equivalent_threshold(results_a,
     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)))
+        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
 
@@ -1868,7 +1916,10 @@ if False:
     detection_thresholds = [0.15,0.15]
     rendering_thresholds = None
 
-    results = n_way_comparison(filenames,options,detection_thresholds,rendering_thresholds=rendering_thresholds)
+    results = n_way_comparison(filenames,
+                               options,
+                               detection_thresholds,
+                               rendering_thresholds=rendering_thresholds)
 
     from megadetector.utils.path_utils import open_file
     open_file(results.html_output_file)
@@ -1980,7 +2031,10 @@ def main(): # noqa
     if args.use_processes:
         options.parallelize_rendering_with_threads = False
 
-    results = n_way_comparison(args.results_files,options,args.detection_thresholds,args.rendering_thresholds)
+    results = n_way_comparison(args.results_files,
+                               options,
+                               args.detection_thresholds,
+                               args.rendering_thresholds)
 
     if args.open_results:
         path_utils.open_file(results.html_output_file)

megadetector/postprocessing/convert_output_format.py

@@ -51,12 +51,12 @@ def convert_json_to_csv(input_path,
             [input_path].csv
         min_confidence (float, optional): the minimum-confidence detection we should include
             in the "detections" column; has no impact on the other columns
-        omit_bounding_boxes (bool): whether to leave out the json-formatted bounding boxes
-            that make up the "detections" column, which are not generally useful for someone who
-            wants to consume this data as a .csv file
+        omit_bounding_boxes (bool, optional): whether to leave out the json-formatted bounding
+            boxes that make up the "detections" column, which are not generally useful for someone
+            who wants to consume this data as a .csv file
         output_encoding (str, optional): encoding to use for the .csv file
-        overwrite (bool): whether to overwrite an existing .csv file; if this is False and the
-            output file exists, no-ops and returns
+        overwrite (bool, optional): whether to overwrite an existing .csv file; if this is False and
+            the output file exists, no-ops and returns
 
     """
 
@@ -230,8 +230,8 @@ def convert_csv_to_json(input_path,output_path=None,overwrite=True):
         input_path (str): .csv filename to convert to .json
         output_path (str, optional): the output .json file to generate; if this is None, uses
             [input_path].json
-        overwrite (bool): whether to overwrite an existing .json file; if this is False and the
-            output file exists, no-ops and returns
+        overwrite (bool, optional): whether to overwrite an existing .json file; if this is
+            False and the output file exists, no-ops and returns
 
     """
 
@@ -365,7 +365,11 @@ if False:
 
 #%% Command-line driver
 
-def main(): # noqa
+def main():
+    """
+    Command-line driver for convert_output_format(), which converts
+    json <--> csv.
+    """
 
     parser = argparse.ArgumentParser()
     parser.add_argument('input_path',type=str,