megadetector 5.0.26__py3-none-any.whl → 5.0.28__py3-none-any.whl

megadetector/utils/wi_utils.py

@@ -15,6 +15,8 @@ Functions related to working with the WI insights platform, specifically for:
 import os
 import requests
 import json
+import tempfile
+import uuid
 
 import numpy as np
 import pandas as pd
@@ -26,14 +28,15 @@ from functools import partial
 from tqdm import tqdm
 
 from megadetector.utils.path_utils import insert_before_extension
+from megadetector.utils.path_utils import find_images
+
 from megadetector.utils.ct_utils import split_list_into_n_chunks
 from megadetector.utils.ct_utils import round_floats_in_nested_dict
 from megadetector.utils.ct_utils import is_list_sorted
 from megadetector.utils.ct_utils import invert_dictionary
 from megadetector.utils.ct_utils import sort_list_of_dicts_by_key
 from megadetector.utils.ct_utils import sort_dictionary_by_value
-from megadetector.utils.ct_utils import sort_dictionary_by_key
-from megadetector.utils.path_utils import find_images
+
 from megadetector.postprocessing.validate_batch_results import \
     validate_batch_results, ValidateBatchResultsOptions
 
@@ -70,7 +73,8 @@ def is_valid_prediction_string(s):
 
 def is_valid_taxonomy_string(s):
     """
-    Determine whether [s] is a valid 5-token WI taxonomy string.  Taxonmy strings look like:
+    Determine whether [s] is a valid 5-token WI taxonomy string.  Taxonomy strings 
+    look like:
     
     'mammalia;rodentia;;;;rodent'
     'mammalia;chordata;canidae;canis;lupus dingo'
@@ -331,7 +335,7 @@ def read_images_from_download_bundle(download_folder):
             * filename (str, the filename without path at the time of upload)
             * location (str, starting with gs://)
             
-        May also contain clasification fields: wi_taxon_id (str), species, etc.        
+        May also contain classification fields: wi_taxon_id (str), species, etc.        
     """
     
     print('Reading images from {}'.format(download_folder))
@@ -1147,7 +1151,8 @@ def generate_md_results_from_predictions_json(predictions_json_file,
                                               md_results_file,
                                               base_folder=None,
                                               max_decimals=5,
-                                              convert_human_to_person=True):
+                                              convert_human_to_person=True,
+                                              convert_homo_species_to_human=True):
     """
     Generate an MD-formatted .json file from a predictions.json file, generated by the 
     SpeciesNet ensemble.  Typically, MD results files use relative paths, and predictions.json 
@@ -1176,6 +1181,9 @@ def generate_md_results_from_predictions_json(predictions_json_file,
         convert_human_to_person (bool, optional): WI predictions.json files sometimes use the
             detection category "human"; MD files usually use "person".  If True, switches "human"
             to "person".
+        convert_homo_species_to_human (bool, optional): the ensemble often rolls human predictions
+            up to "homo species", which isn't wrong, but looks odd.  This forces these back to
+            "homo sapiens".
     """
         
     # Read predictions file    
@@ -1216,7 +1224,6 @@ def generate_md_results_from_predictions_json(predictions_json_file,
     # im_in = predictions[0]
     for im_in in predictions:
         
-        # blank_prediction_string
         im_out = {}
         
         fn = im_in['filepath']
@@ -1275,8 +1282,11 @@ def generate_md_results_from_predictions_json(predictions_json_file,
                 
             if 'prediction' in im_in:
                 
+                class_to_assign = None
                 im_out['top_classification_common_name'] = top_classification_common_name
                 class_to_assign = im_in['prediction']
+                if convert_homo_species_to_human and class_to_assign.endswith('homo species'):
+                    class_to_assign = human_prediction_string
                 class_confidence = im_in['prediction_score']
             
             if class_to_assign is not None:
@@ -1605,6 +1615,50 @@ def merge_prediction_json_files(input_prediction_files,output_prediction_file):
 # ...def merge_prediction_json_files(...)    
 
 
+def load_md_or_speciesnet_file(fn,verbose=True):
+    """
+    Load a .json file that may be in MD or SpeciesNet format.  Typically used so
+    SpeciesNet files can be supplied to functions originally written to support MD
+    format.
+
+    Args:
+        fn (str): a .json file in predictions.json (MD or SpeciesNet) format
+        verbose (bool, optional): enable additional debug output
+    
+    Returns:
+        dict: the contents of [fn], in MD format.
+    """
+
+    with open(fn,'r') as f:
+        detector_output = json.load(f)
+
+    # Convert to MD format if necessary
+    if 'predictions' in detector_output:
+        if verbose:
+            print('This appears to be a SpeciesNet output file, converting to MD format')
+        md_temp_dir = os.path.join(tempfile.gettempdir(), 'megadetector_temp_files')
+        os.makedirs(md_temp_dir,exist_ok=True)
+        temp_results_file = os.path.join(md_temp_dir,str(uuid.uuid1()) + '.json')
+        print('Writing temporary results to {}'.format(temp_results_file))
+        generate_md_results_from_predictions_json(predictions_json_file=fn,
+                                                  md_results_file=temp_results_file,
+                                                  base_folder=None)
+        with open(temp_results_file,'r') as f:
+            detector_output = json.load(f)
+        try:
+            os.remove(temp_results_file)
+        except Exception:
+            if verbose:
+                print('Warning: error removing temporary .json {}'.format(temp_results_file))    
+
+    assert 'images' in detector_output, \
+        'Detector output file should be a json file with an "images" field.'
+    
+    return detector_output
+
+# ...def load_md_or_speciesnet_file(...)
+
+
 def validate_predictions_file(fn,instances=None,verbose=True):
     """
     Validate the predictions.json file [fn].
@@ -2315,402 +2369,6 @@ def species_allowed_in_country(species,country,state=None,return_status=False):
 # ...def species_allowed_in_country(...)
 
 
-def restrict_to_taxa_list(taxa_list,
-                          speciesnet_taxonomy_file,
-                          input_file,
-                          output_file,
-                          allow_walk_down=False):
-    """
-    Given a prediction file in MD .json format, likely without having had
-    a geofence applied, apply a custom taxa list.
-    
-    Args:
-        taxa_list (str or list): list of latin names, or a text file containing
-            a list of latin names.  Optionally may contain a second (comma-delimited)
-            column containing common names, used only for debugging.  Latin names
-            must exist in the SpeciesNet taxonomy.
-        taxonomy_file (str): taxonomy filename, in the same format used for model
-            release (with 7-token taxonomy entries)            
-        output_file (str): .json file to write, in MD format      
-        allow_walk_down (bool, optional): should we walk down the taxonomy tree
-            when making mappings if a parent has only a single allowable child?
-            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?
-    """
-
-    ##%% Read target taxa list
-    
-    if isinstance(taxa_list,str):
-        assert os.path.isfile(taxa_list), \
-            'Could not find taxa list file {}'.format(taxa_list)
-        with open(taxa_list,'r') as f:
-            taxa_list = f.readlines()
-    
-    taxa_list = [s.strip().lower() for s in taxa_list]
-    taxa_list = [s for s in taxa_list if len(s) > 0]
-    
-    target_latin_to_common = {}
-    for s in taxa_list:
-        if s.strip().startswith('#'):
-            continue
-        tokens = s.split(',')
-        assert len(tokens) <= 2
-        binomial_name = tokens[0]
-        assert len(binomial_name.split(' ')) in (1,2,3), \
-            'Illegal binomial name in species list: {}'.format(binomial_name)
-        if len(tokens) > 0:
-            common_name = tokens[1].strip().lower()
-        else:
-            common_name = None
-        assert binomial_name not in target_latin_to_common
-        target_latin_to_common[binomial_name] = common_name
-    
-
-    ##%% Read taxonomy file
-    
-    with open(speciesnet_taxonomy_file,'r') as f:
-        speciesnet_taxonomy_list = f.readlines()
-    speciesnet_taxonomy_list = [s.strip() for s in \
-                                speciesnet_taxonomy_list if len(s.strip()) > 0]
-    
-    # Maps the latin name of every taxon to the corresponding full taxon string
-    #
-    # For species, the key is a binomial name
-    speciesnet_latin_name_to_taxon_string = {}
-    speciesnet_common_name_to_taxon_string = {}
-    
-    def _insert_taxonomy_string(s):
-        
-        tokens = s.split(';')
-        assert len(tokens) == 7
-        
-        guid = tokens[0] # noqa
-        class_name = tokens[1]
-        order = tokens[2]
-        family = tokens[3]
-        genus = tokens[4]
-        species = tokens[5]        
-        common_name = tokens[6]
-        
-        if len(class_name) == 0:
-            assert common_name in ('animal','vehicle','blank')
-            return
-        
-        if len(species) > 0:
-            assert all([len(s) > 0 for s in [genus,family,order]])
-            binomial_name = genus + ' ' + species
-            if binomial_name not in speciesnet_latin_name_to_taxon_string:
-                speciesnet_latin_name_to_taxon_string[binomial_name] = s
-        elif len(genus) > 0:
-            assert all([len(s) > 0 for s in [family,order]])
-            if genus not in speciesnet_latin_name_to_taxon_string:
-                speciesnet_latin_name_to_taxon_string[genus] = s
-        elif len(family) > 0:
-            assert len(order) > 0
-            if family not in speciesnet_latin_name_to_taxon_string:
-                speciesnet_latin_name_to_taxon_string[family] = s
-        elif len(order) > 0:
-            if order not in speciesnet_latin_name_to_taxon_string:
-                speciesnet_latin_name_to_taxon_string[order] = s
-        else:
-            if class_name not in speciesnet_latin_name_to_taxon_string:
-                speciesnet_latin_name_to_taxon_string[class_name] = s
-        
-        if len(common_name) > 0:
-            if common_name not in speciesnet_common_name_to_taxon_string:
-                speciesnet_common_name_to_taxon_string[common_name] = s
-    
-    for s in speciesnet_taxonomy_list:
-        
-        _insert_taxonomy_string(s)
-    
-    
-    ##%% Make sure all parent taxa are represented in the taxonomy
-    
-    # In theory any taxon that appears as the parent of another taxon should
-    # also be in the taxonomy, but this isn't always true, so we fix it here.
-    
-    new_taxon_string_to_missing_tokens = defaultdict(list)
-    
-    # latin_name = next(iter(speciesnet_latin_name_to_taxon_string.keys()))
-    for latin_name in speciesnet_latin_name_to_taxon_string.keys():
-        
-        if 'no cv result' in latin_name:
-            continue
-        
-        taxon_string = speciesnet_latin_name_to_taxon_string[latin_name]
-        tokens = taxon_string.split(';')
-        
-        # Don't process GUID, species, or common name
-        # i_token = 6
-        for i_token in range(1,len(tokens)-2):
-            
-            test_token = tokens[i_token]            
-            if len(test_token) == 0:
-                continue
-            
-            # Do we need to make up a taxon for this token?
-            if test_token not in speciesnet_latin_name_to_taxon_string:
-                
-                new_tokens = [''] * 7
-                new_tokens[0] = 'fake_guid'
-                for i_copy_token in range(1,i_token+1):
-                    new_tokens[i_copy_token] = tokens[i_copy_token]
-                new_tokens[-1] = test_token + ' species'
-                assert new_tokens[-2] == ''
-                new_taxon_string = ';'.join(new_tokens)
-                # assert new_taxon_string not in new_taxon_strings
-                new_taxon_string_to_missing_tokens[new_taxon_string].append(test_token)
-                
-        # ...for each token
-        
-    # ...for each taxon
-        
-    print('Found {} taxa that need to be inserted to make the taxonomy valid:\n'.format(
-        len(new_taxon_string_to_missing_tokens)))
-    
-    new_taxon_string_to_missing_tokens = \
-        sort_dictionary_by_key(new_taxon_string_to_missing_tokens)
-    for taxon_string in new_taxon_string_to_missing_tokens:
-        missing_taxa = ','.join(new_taxon_string_to_missing_tokens[taxon_string])
-        print('{} ({})'.format(taxon_string,missing_taxa))
-        
-    for new_taxon_string in new_taxon_string_to_missing_tokens:
-        _insert_taxonomy_string(new_taxon_string)
-        
-        
-    ##%% Make sure all species on the allow-list are in the taxonomy
-    
-    n_failed_mappings = 0
-    
-    for target_taxon_latin_name in target_latin_to_common.keys():
-        if target_taxon_latin_name not in speciesnet_latin_name_to_taxon_string:
-            common_name = target_latin_to_common[target_taxon_latin_name]
-            s = '{} ({}) not in speciesnet taxonomy'.format(
-                target_taxon_latin_name,common_name)
-            if common_name in speciesnet_common_name_to_taxon_string:
-                s += ' (common name maps to {})'.format(
-                    speciesnet_common_name_to_taxon_string[common_name])
-            print(s)
-            n_failed_mappings += 1
-    
-    if n_failed_mappings > 0:
-        raise ValueError('Cannot continue with geofence generation')
-    
-    
-    ##%% For the allow-list, map each parent taxon to a set of allowable child taxa
-    
-    # Maps parent names to all allowed child names, or None if this is the 
-    # lowest-level allowable taxon on this path
-    allowed_parent_taxon_to_child_taxa = defaultdict(set)
-    
-    # latin_name = next(iter(target_latin_to_common.keys()))
-    for latin_name in target_latin_to_common:
-        
-        taxon_string = speciesnet_latin_name_to_taxon_string[latin_name]
-        tokens = taxon_string.split(';')
-        assert len(tokens) == 7
-        
-        # Remove GUID and common mame
-        #
-        # This is now always class/order/family/genus/species
-        tokens = tokens[1:-1]
-        
-        child_taxon = None
-        
-        # If this is a species
-        if len(tokens[-1]) > 0:
-            binomial_name = tokens[-2] + ' ' + tokens[-1]
-            assert binomial_name == latin_name
-            allowed_parent_taxon_to_child_taxa[binomial_name].add(None)
-            child_taxon = binomial_name
-            
-        # The first candidate parent is the genus        
-        parent_token_index = len(tokens) - 2
-
-        while(parent_token_index >= 0):
-            
-            parent_taxon = tokens[parent_token_index]
-            allowed_parent_taxon_to_child_taxa[parent_taxon].add(child_taxon)
-            child_taxon = parent_taxon
-            parent_token_index -= 1                
-    
-    # ...for each allowed latin name
-    
-    allowed_parent_taxon_to_child_taxa = \
-        sort_dictionary_by_key(allowed_parent_taxon_to_child_taxa)
-    
-    
-    ##%% Map all predictions that exist in this dataset...
-    
-    # ...to the prediction we should generate.
-    
-    with open(input_file,'r') as f:
-        input_data = json.load(f)
-    
-    input_category_id_to_common_name = input_data['classification_categories'] #noqa
-    input_category_id_to_taxonomy_string = \
-        input_data['classification_category_descriptions']
-    
-    input_category_id_to_output_taxon_string = {}
-    
-    # input_category_id = next(iter(input_category_id_to_taxonomy_string.keys()))
-    for input_category_id in input_category_id_to_taxonomy_string.keys():
-        
-        input_taxon_string = input_category_id_to_taxonomy_string[input_category_id]
-        input_taxon_tokens = input_taxon_string.split(';')
-        assert len(input_taxon_tokens) == 7
-    
-        # Don't mess with blank/no-cv-result/animal/human
-        if (input_taxon_string in non_taxonomic_prediction_strings) or \
-           (input_taxon_string == human_prediction_string):
-            input_category_id_to_output_taxon_string[input_category_id] = \
-                input_taxon_string
-            continue
-    
-        # Remove GUID and common mame
-        #
-        # This is now always class/order/family/genus/species
-        input_taxon_tokens = input_taxon_tokens[1:-1]
-        
-        test_index = len(input_taxon_tokens) - 1
-        target_taxon = None
-        
-        # Start at the species level, and see whether each taxon is allowed
-        while((test_index >= 0) and (target_taxon is None)):
-            
-            # Species are represented as binomial names
-            if (test_index == (len(input_taxon_tokens) - 1)) and \
-                (len(input_taxon_tokens[-1]) > 0):
-                test_taxon_name = \
-                    input_taxon_tokens[-2] + ' ' + input_taxon_tokens[-1]
-            else:
-                test_taxon_name = input_taxon_tokens[test_index]
-            
-            # If we haven't yet found the level at which this taxon is non-empty,
-            # keep going up
-            if len(test_taxon_name) == 0:            
-                test_index -= 1
-                continue
-            
-            assert test_taxon_name in speciesnet_latin_name_to_taxon_string
-            
-            # Is this taxon allowed according to the custom species list?
-            if test_taxon_name in allowed_parent_taxon_to_child_taxa:
-                
-                allowed_child_taxa = allowed_parent_taxon_to_child_taxa[test_taxon_name]
-                assert allowed_child_taxa is not None
-                
-                # If this is the lowest-level allowable token or there is not a 
-                # unique child, don't walk any further, even if walking down
-                # is enabled.
-                if (None in allowed_child_taxa):
-                    assert len(allowed_child_taxa) == 1
-                
-                if (None in allowed_child_taxa) or (len(allowed_child_taxa) > 1):
-                    target_taxon = test_taxon_name
-                elif not allow_walk_down:
-                    target_taxon = test_taxon_name
-                else:
-                    # If there's a unique child, walk back *down* the allowable
-                    # taxa until we run out of unique children
-                    while ((next(iter(allowed_child_taxa)) is not None) and \
-                          (len(allowed_child_taxa) == 1)):
-                        candidate_taxon = next(iter(allowed_child_taxa))
-                        assert candidate_taxon in allowed_parent_taxon_to_child_taxa
-                        assert candidate_taxon in speciesnet_latin_name_to_taxon_string
-                        allowed_child_taxa = \
-                            allowed_parent_taxon_to_child_taxa[candidate_taxon]
-                    target_taxon = candidate_taxon
-                    
-            # ...if this is an allowed taxon
-                    
-            test_index -= 1
-    
-        # ...for each token
-        
-        if target_taxon is None:
-            output_taxon_string = animal_prediction_string                        
-        else:
-            output_taxon_string = speciesnet_latin_name_to_taxon_string[target_taxon]
-        input_category_id_to_output_taxon_string[input_category_id] = output_taxon_string        
-    
-    # ...for each category
-        
-    
-    ##%% Build the new tables
-    
-    input_category_id_to_output_category_id = {}
-    output_taxon_string_to_category_id = {}
-    output_category_id_to_common_name = {}
-    
-    for input_category_id in input_category_id_to_output_taxon_string:
-        
-        original_common_name = \
-            input_category_id_to_common_name[input_category_id]
-        original_taxon_string = \
-            input_category_id_to_taxonomy_string[input_category_id]
-        output_taxon_string = \
-            input_category_id_to_output_taxon_string[input_category_id]
-    
-        output_common_name = output_taxon_string.split(';')[-1]
-        
-        # Do we need to create a new output category?
-        if output_taxon_string not in output_taxon_string_to_category_id:
-            output_category_id = str(len(output_taxon_string_to_category_id))
-            output_taxon_string_to_category_id[output_taxon_string] = \
-                output_category_id
-            output_category_id_to_common_name[output_category_id] = \
-                output_common_name            
-        else:
-            output_category_id = \
-                output_taxon_string_to_category_id[output_taxon_string]
-        
-        input_category_id_to_output_category_id[input_category_id] = \
-            output_category_id
-            
-        if False:
-            print('Mapping {} ({}) to:\n{} ({})\n'.format(
-                original_common_name,original_taxon_string,
-                output_common_name,output_taxon_string))
-        if False:    
-            print('Mapping {} to {}'.format(
-                original_common_name,output_common_name,))
-    
-    # ...for each category
-    
-    
-    ##%% Remap all category labels
-    
-    assert len(set(output_taxon_string_to_category_id.keys())) == \
-           len(set(output_taxon_string_to_category_id.values()))
-           
-    output_category_id_to_taxon_string = \
-        invert_dictionary(output_taxon_string_to_category_id)
-        
-    with open(input_file,'r') as f:
-        output_data = json.load(f)
-        
-    for im in tqdm(output_data['images']):
-        if 'detections' in im and im['detections'] is not None:
-            for det in im['detections']:
-                if 'classifications' in det:
-                    for classification in det['classifications']:
-                        classification[0] = \
-                            input_category_id_to_output_category_id[classification[0]]
-    
-    output_data['classification_categories'] = output_category_id_to_common_name
-    output_data['classification_category_descriptions'] = \
-        output_category_id_to_taxon_string
-        
-        
-    ##%% Write output
-    
-    with open(output_file,'w') as f:
-        json.dump(output_data,f,indent=1)
-    
-    
 #%% Interactive driver(s)
 
 if False:
@@ -2729,7 +2387,9 @@ if False:
     from megadetector.utils.wi_utils import taxonomy_string_to_taxonomy_info # noqa
     from megadetector.utils.wi_utils import common_name_to_taxonomy_info # noqa
     from megadetector.utils.wi_utils import binomial_name_to_taxonomy_info # noqa
-    
+    from megadetector.utils.wi_utils import country_to_country_code # noqa
+    from megadetector.utils.wi_utils import country_code_to_country # noqa
+
     model_base = os.path.expanduser('~/models/speciesnet')
     geofencing_file = os.path.join(model_base,'crop','geofence_release.2025.02.27.0702.json')
     country_code_file = os.path.join(model_base,'country-codes.csv')
@@ -2740,10 +2400,10 @@ if False:
     initialize_taxonomy_info(taxonomy_file, force_init=True, encoding=encoding)
         
     
-    #%% Test driver for geofence_fixes.csv function
+    #%% Generate a block-except list
     
-    block_except_list = 'AUS, PNG, THA, IDN, MYS'
-    species = 'dingo'
+    block_except_list = 'ALB,AND,ARM,AUT,AZE,BEL,BGR,BIH,BLR,CHE,CYP,CZE,DEU,DNK,ESP,EST,FIN,FRA,GBR,GEO,GRC,HRV,HUN,IRL,IRN,IRQ,ISL,ISR,ITA,KAZ,LIE,LTU,LUX,LVA,MDA,MKD,MLT,MNE,NLD,NOR,POL,PRT,ROU,RUS,SMR,SRB,SVK,SVN,SWE,TUR,UKR,UZB'
+    species = 'eurasian badger'
     species_string = _species_string_to_canonical_species_string(species)
     rows = _generate_csv_rows_to_block_all_countries_except(species_string,block_except_list)
     
@@ -2751,7 +2411,7 @@ if False:
     print(rows)
     
     
-    #%%
+    #%% Generate an allow-list
     
     taxon_name = 'hippopotamus amphibius'
     taxonomy_info = binomial_name_to_taxonomy_info[taxon_name]    
@@ -2763,9 +2423,7 @@ if False:
                                   block_countries=None,
                                   allow_states=None,
                                   block_states=None,
-                                  blockexcept_countries=None)
-        
-    # _generate_csv_rows_to_block_all_countries_except(species_string,'AUS')
+                                  blockexcept_countries=None)            
     
     
     #%% Test the effects of geofence changes

megadetector/visualization/visualization_utils.py

@@ -183,7 +183,7 @@ def exif_preserving_save(pil_image,output_file,quality='keep',default_quality=85
     ...for more ways to preserve jpeg quality if quality='keep' doesn't do the trick.
 
     Args:
-        pil_image (Image): the PIL Image objct to save
+        pil_image (Image): the PIL Image object to save
         output_file (str): the destination file
         quality (str or int, optional): can be "keep" (default), or an integer from 0 to 100. 
             This is only used if PIL thinks the the source image is a JPEG.  If you load a JPEG
@@ -1285,8 +1285,14 @@ def gray_scale_fraction(image,crop_size=(0.1,0.1)):
 
 
 def _resize_relative_image(fn_relative,
-                          input_folder,output_folder,
-                          target_width,target_height,no_enlarge_width,verbose,quality):
+                          input_folder,
+                          output_folder,
+                          target_width,
+                          target_height,
+                          no_enlarge_width,
+                          verbose,
+                          quality,
+                          overwrite=True):
     """
     Internal function for resizing an image from one folder to another,
     maintaining relative path.
@@ -1294,6 +1300,12 @@ def _resize_relative_image(fn_relative,
     
     input_fn_abs = os.path.join(input_folder,fn_relative)
     output_fn_abs = os.path.join(output_folder,fn_relative)
+
+    if (not overwrite) and (os.path.isfile(output_fn_abs)):
+        status = 'skipped'
+        error = None
+        return {'fn_relative':fn_relative,'status':status,'error':error}
+    
     os.makedirs(os.path.dirname(output_fn_abs),exist_ok=True)
     try:
         _ = resize_image(input_fn_abs, 
@@ -1435,7 +1447,8 @@ def resize_image_folder(input_folder,
                         pool_type='process', 
                         n_workers=10, 
                         recursive=True,
-                        image_files_relative=None):
+                        image_files_relative=None,
+                        overwrite=True):
     """
     Resize all images in a folder (defaults to recursive).
     
@@ -1461,12 +1474,13 @@ def resize_image_folder(input_folder,
             to disable parallelization
         recursive (bool, optional): whether to search [input_folder] recursively for images.
         image_files_relative (list, optional): if not None, skips any relative paths not
-            in this list.
+            in this list
+        overwrite (bool, optional): whether to overwrite existing target images
             
     Returns:
         list: a list of dicts with keys 'input_fn', 'output_fn', 'status', and 'error'.
-        'status' will be 'success' or 'error'; 'error' will be None for successful cases, 
-        otherwise will contain the image-specific error.
+        'status' will be 'success', 'skipped', or 'error'; 'error' will be None for successful 
+        cases, otherwise will contain the image-specific error.
     """
 
     assert os.path.isdir(input_folder), '{} is not a folder'.format(input_folder)
@@ -1502,7 +1516,8 @@ def resize_image_folder(input_folder,
                                   target_height=target_height,
                                   no_enlarge_width=no_enlarge_width,
                                   verbose=verbose,
-                                  quality=quality))
+                                  quality=quality,
+                                  overwrite=overwrite))
 
     else:
         
@@ -1522,7 +1537,8 @@ def resize_image_folder(input_folder,
                 target_height=target_height,
                 no_enlarge_width=no_enlarge_width,
                 verbose=verbose,
-                quality=quality)
+                quality=quality,
+                overwrite=overwrite)
         
         results = list(tqdm(pool.imap(p, image_files_relative),total=len(image_files_relative)))