"""

visualization_utils.py

Rendering functions shared across visualization scripts

"""

#%% Constants and imports

import time
import numpy as np
import requests
import os
import cv2

from io import BytesIO
from PIL import Image, ImageFile, ImageFont, ImageDraw, ImageFilter
from multiprocessing.pool import ThreadPool
from multiprocessing.pool import Pool
from tqdm import tqdm
from functools import partial

from megadetector.utils.path_utils import find_images
from megadetector.data_management.annotations import annotation_constants
from megadetector.data_management.annotations.annotation_constants import \
    detector_bbox_category_id_to_name
from megadetector.utils.ct_utils import sort_list_of_dicts_by_key

ImageFile.LOAD_TRUNCATED_IMAGES = True

# Maps EXIF standard rotation identifiers to degrees.  The value "1" indicates no
# rotation; this will be ignored.  The values 2, 4, 5, and 7 are mirrored rotations,
# which are not supported (we'll assert() on this when we apply rotations).
EXIF_IMAGE_NO_ROTATION = 1
EXIF_IMAGE_ROTATIONS = {
    3: 180,
    6: 270,
    8: 90
}

TEXTALIGN_LEFT = 0
TEXTALIGN_RIGHT = 1
TEXTALIGN_CENTER = 2

VTEXTALIGN_TOP = 0
VTEXTALIGN_BOTTOM = 1

# Convert category ID from int to str
DEFAULT_DETECTOR_LABEL_MAP = {
    str(k): v for k, v in detector_bbox_category_id_to_name.items()
}

# Constants controlling retry behavior when fetching images from URLs
n_retries = 10
retry_sleep_time = 0.01

# If we try to open an image from a URL, and we encounter any error in this list,
# we'll retry, otherwise it's just an error.
error_names_for_retry = ['ConnectionError']

DEFAULT_BOX_THICKNESS = 4
DEFAULT_LABEL_FONT_SIZE = 16

# Default color map for mapping integer category IDs to colors when rendering bounding
# boxes
DEFAULT_COLORS = [
    'AliceBlue', 'Red', 'RoyalBlue', 'Gold', 'Chartreuse', 'Aqua', 'Azure',
    'Beige', 'Bisque', 'BlanchedAlmond', 'BlueViolet', 'BurlyWood', 'CadetBlue',
    'AntiqueWhite', 'Chocolate', 'Coral', 'CornflowerBlue', 'Cornsilk', 'Crimson',
    'Cyan', 'DarkCyan', 'DarkGoldenRod', 'DarkGrey', 'DarkKhaki', 'DarkOrange',
    'DarkOrchid', 'DarkSalmon', 'DarkSeaGreen', 'DarkTurquoise', 'DarkViolet',
    'DeepPink', 'DeepSkyBlue', 'DodgerBlue', 'FireBrick', 'FloralWhite',
    'ForestGreen', 'Fuchsia', 'Gainsboro', 'GhostWhite', 'GoldenRod',
    'Salmon', 'Tan', 'HoneyDew', 'HotPink', 'IndianRed', 'Ivory', 'Khaki',
    'Lavender', 'LavenderBlush', 'LawnGreen', 'LemonChiffon', 'LightBlue',
    'LightCoral', 'LightCyan', 'LightGoldenRodYellow', 'LightGray', 'LightGrey',
    'LightGreen', 'LightPink', 'LightSalmon', 'LightSeaGreen', 'LightSkyBlue',
    'LightSlateGray', 'LightSlateGrey', 'LightSteelBlue', 'LightYellow', 'Lime',
    'LimeGreen', 'Linen', 'Magenta', 'MediumAquaMarine', 'MediumOrchid',
    'MediumPurple', 'MediumSeaGreen', 'MediumSlateBlue', 'MediumSpringGreen',
    'MediumTurquoise', 'MediumVioletRed', 'MintCream', 'MistyRose', 'Moccasin',
    'NavajoWhite', 'OldLace', 'Olive', 'OliveDrab', 'Orange', 'OrangeRed',
    'Orchid', 'PaleGoldenRod', 'PaleGreen', 'PaleTurquoise', 'PaleVioletRed',
    'PapayaWhip', 'PeachPuff', 'Peru', 'Pink', 'Plum', 'PowderBlue', 'Purple',
    'RosyBrown', 'Aquamarine', 'SaddleBrown', 'Green', 'SandyBrown',
    'SeaGreen', 'SeaShell', 'Sienna', 'Silver', 'SkyBlue', 'SlateBlue',
    'SlateGray', 'SlateGrey', 'Snow', 'SpringGreen', 'SteelBlue', 'GreenYellow',
    'Teal', 'Thistle', 'Tomato', 'Turquoise', 'Violet', 'Wheat', 'White',
    'WhiteSmoke', 'Yellow', 'YellowGreen'
]


#%% Functions

def open_image(input_file, ignore_exif_rotation=False):
    """
    Opens an image in binary format using PIL.Image and converts to RGB mode.

    Supports local files or URLs.

    This operation is lazy; image will not be actually loaded until the first
    operation that needs to load it (for example, resizing), so file opening
    errors can show up later.  load_image() is the non-lazy version of this function.

    Args:
        input_file (str or BytesIO): can be a path to an image file (anything
            that PIL can open), a URL, or an image as a stream of bytes
        ignore_exif_rotation (bool, optional): don't rotate the loaded pixels,
            even if we are loading a JPEG and that JPEG says it should be rotated

    Returns:
        PIL.Image.Image: A PIL Image object in RGB mode
    """

    if (isinstance(input_file, str)
            and input_file.startswith(('http://', 'https://'))):
        try:
            response = requests.get(input_file)
        except Exception as e:
            print(f'Error retrieving image {input_file}: {e}')
            success = False
            if e.__class__.__name__ in error_names_for_retry:
                for i_retry in range(0,n_retries):
                    try:
                        time.sleep(retry_sleep_time)
                        response = requests.get(input_file)
                    except Exception as e:
                        print(f'Error retrieving image {input_file} on retry {i_retry}: {e}')
                        continue
                    print('Succeeded on retry {}'.format(i_retry))
                    success = True
                    break
            if not success:
                raise
        try:
            image = Image.open(BytesIO(response.content))
        except Exception as e:
            print(f'Error opening image {input_file}: {e}')
            raise

    else:
        image = Image.open(input_file)

    # Convert to RGB if necessary
    if image.mode not in ('RGBA', 'RGB', 'L', 'I;16'):
        raise AttributeError(
            f'Image {input_file} uses unsupported mode {image.mode}')
    if image.mode == 'RGBA' or image.mode == 'L':
        # PIL.Image.convert() returns a converted copy of this image
        image = image.convert(mode='RGB')

    if not ignore_exif_rotation:
        # Alter orientation as needed according to EXIF tag 0x112 (274) for Orientation
        #
        # https://gist.github.com/dangtrinhnt/a577ece4cbe5364aad28
        # https://www.media.mit.edu/pia/Research/deepview/exif.html
        #
        try:
            exif = image._getexif()
            orientation: int = exif.get(274, None)
            if (orientation is not None) and (orientation != EXIF_IMAGE_NO_ROTATION):
                assert orientation in EXIF_IMAGE_ROTATIONS, \
                    'Mirrored rotations are not supported'
                image = image.rotate(EXIF_IMAGE_ROTATIONS[orientation], expand=True)
        except Exception:
            pass

    return image

# ...def open_image(...)


def exif_preserving_save(pil_image,output_file,quality='keep',default_quality=85,verbose=False):
    """
    Saves [pil_image] to [output_file], making a moderate attempt to preserve EXIF
    data and JPEG quality.  Neither is guaranteed.

    Also see:

    https://discuss.dizzycoding.com/determining-jpg-quality-in-python-pil/

    ...for more ways to preserve jpeg quality if quality='keep' doesn't do the trick.

    Args:
        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
            and resize it in memory, for example, it's no longer a JPEG.
        default_quality (int, optional): determines output quality when quality == 'keep' and we are
            saving a non-JPEG source to a JPEG file
        verbose (bool, optional): enable additional debug console output
    """

    # Read EXIF metadata
    exif = pil_image.info['exif'] if ('exif' in pil_image.info) else None

    # Quality preservation is only supported for JPEG sources.
    if pil_image.format != "JPEG":
        if quality == 'keep':
            if verbose:
                print('Warning: quality "keep" passed when saving a non-JPEG source (during save to {})'.format(
                    output_file))
            quality = default_quality

    # Some output formats don't support the quality parameter, so we try once with,
    # and once without.  This is a horrible cascade of if's, but it's a consequence of
    # the fact that "None" is not supported for either "exif" or "quality".

    try:

        if exif is not None:
            pil_image.save(output_file, exif=exif, quality=quality)
        else:
            pil_image.save(output_file, quality=quality)

    except Exception:

        if verbose:
            print('Warning: failed to write {}, trying again without quality parameter'.format(output_file))
        if exif is not None:
            pil_image.save(output_file, exif=exif)
        else:
            pil_image.save(output_file)

# ...def exif_preserving_save(...)


def load_image(input_file, ignore_exif_rotation=False):
    """
    Loads an image file.  This is the non-lazy version of open_file(); i.e.,
    it forces image decoding before returning.

    Args:
        input_file (str or BytesIO): can be a path to an image file (anything
            that PIL can open), a URL, or an image as a stream of bytes
        ignore_exif_rotation (bool, optional): don't rotate the loaded pixels,
            even if we are loading a JPEG and that JPEG says it should be rotated

    Returns:
        PIL.Image.Image: a PIL Image object in RGB mode
    """

    image = open_image(input_file, ignore_exif_rotation=ignore_exif_rotation)
    image.load()
    return image


def resize_image(image,
                 target_width=-1,
                 target_height=-1,
                 output_file=None,
                 no_enlarge_width=False,
                 verbose=False,
                 quality='keep'):
    """
    Resizes a PIL Image object to the specified width and height; does not resize
    in place. If either width or height are -1, resizes with aspect ratio preservation.

    If target_width and target_height are both -1, does not modify the image, but
    will write to output_file if supplied.

    If no resizing is required, and an Image object is supplied, returns the original Image
    object (i.e., does not copy).

    Args:
        image (Image or str): PIL Image object or a filename (local file or URL)
        target_width (int, optional): width to which we should resize this image, or -1
            to let target_height determine the size
        target_height (int, optional): height to which we should resize this image, or -1
            to let target_width determine the size
        output_file (str, optional): file to which we should save this image; if None,
            just returns the image without saving
        no_enlarge_width (bool, optional): if [no_enlarge_width] is True, and
            [target width] is larger than the original image width, does not modify the image,
            but will write to output_file if supplied
        verbose (bool, optional): enable additional debug output
        quality (str or int, optional): passed to exif_preserving_save, see docs for more detail

    Returns:
        PIL.Image.Image: the resized image, which may be the original image if no resizing is
            required
    """

    image_fn = 'in_memory'
    if isinstance(image,str):
        image_fn = image
        image = load_image(image)

    if target_width is None:
        target_width = -1

    if target_height is None:
        target_height = -1

    resize_required = True

    # No resize was requested, this is always a no-op
    if target_width == -1 and target_height == -1:

        resize_required = False

    # Does either dimension need to scale according to the other?
    elif target_width == -1 or target_height == -1:

        # Aspect ratio as width over height
        # ar = w / h
        aspect_ratio = image.size[0] / image.size[1]

        if target_width != -1:
            # h = w / ar
            target_height = int(target_width / aspect_ratio)
        else:
            # w = ar * h
            target_width = int(aspect_ratio * target_height)

    # If we're not enlarging images and this would be an enlarge operation
    if (no_enlarge_width) and (target_width > image.size[0]):

        if verbose:
            print('Bypassing image enlarge for {} --> {}'.format(
                image_fn,str(output_file)))
        resize_required = False

    # If the target size is the same as the original size
    if (target_width == image.size[0]) and (target_height == image.size[1]):

        resize_required = False

    if not resize_required:

        if output_file is not None:
            if verbose:
                print('No resize required for resize {} --> {}'.format(
                    image_fn,str(output_file)))
            exif_preserving_save(image,output_file,quality=quality,verbose=verbose)
        return image

    assert target_width > 0 and target_height > 0, \
        'Invalid image resize target {},{}'.format(target_width,target_height)

    # The antialiasing parameter changed between Pillow versions 9 and 10, and for a bit,
    # I'd like to support both.
    try:
        resized_image = image.resize((target_width, target_height), Image.ANTIALIAS)
    except Exception:
        resized_image = image.resize((target_width, target_height), Image.Resampling.LANCZOS)

    if output_file is not None:
        exif_preserving_save(resized_image,output_file,quality=quality,verbose=verbose)

    return resized_image

# ...def resize_image(...)


def crop_image(detections, image, confidence_threshold=0.15, expansion=0):
    """
    Crops detections above [confidence_threshold] from the PIL image [image],
    returning a list of PIL Images, preserving the order of [detections].

    Args:
        detections (list): a list of dictionaries with keys 'conf' and 'bbox';
            boxes are length-four arrays formatted as [x,y,w,h], normalized,
            upper-left origin (this is the standard MD detection format)
        image (Image or str): the PIL Image object from which we should crop detections,
            or an image filename
        confidence_threshold (float, optional): only crop detections above this threshold
        expansion (int, optional): a number of pixels to include on each side of a cropped
            detection

    Returns:
        list: a possibly-empty list of PIL Image objects
    """

    ret_images = []

    if isinstance(image,str):
        image = load_image(image)

    for detection in detections:

        score = float(detection['conf'])

        if (confidence_threshold is None) or (score >= confidence_threshold):

            x1, y1, w_box, h_box = detection['bbox']
            ymin,xmin,ymax,xmax = y1, x1, y1 + h_box, x1 + w_box

            # Convert to pixels so we can use the PIL crop() function
            im_width, im_height = image.size
            (left, right, top, bottom) = (xmin * im_width, xmax * im_width,
                                          ymin * im_height, ymax * im_height)

            if expansion > 0:
                left -= expansion
                right += expansion
                top -= expansion
                bottom += expansion

            # PIL's crop() does surprising things if you provide values outside of
            # the image, clip inputs
            left = max(left,0); right = max(right,0)
            top = max(top,0); bottom = max(bottom,0)

            left = min(left,im_width-1); right = min(right,im_width-1)
            top = min(top,im_height-1); bottom = min(bottom,im_height-1)

            ret_images.append(image.crop((left, top, right, bottom)))

        # ...if this detection is above threshold

    # ...for each detection

    return ret_images

# ...def crop_image(...)


def blur_detections(image,detections,blur_radius=40):
    """
    Blur the regions in [image] corresponding to the MD-formatted list [detections].
    [image] is modified in place.

    Args:
        image (PIL.Image.Image): image in which we should blur specific regions
        detections (list): list of detections in the MD output format, see render
            detection_bounding_boxes for more detail.
        blur_radius (int, optional): radius of blur kernel in pixels
    """

    img_width, img_height = image.size

    for d in detections:

        bbox = d['bbox']
        x_norm, y_norm, width_norm, height_norm = bbox

        # Calculate absolute pixel coordinates
        x = int(x_norm * img_width)
        y = int(y_norm * img_height)
        width = int(width_norm * img_width)
        height = int(height_norm * img_height)

        # Calculate box boundaries
        left = max(0, x)
        top = max(0, y)
        right = min(img_width, x + width)
        bottom = min(img_height, y + height)

        # Crop the region, blur it, and paste it back
        region = image.crop((left, top, right, bottom))
        blurred_region = region.filter(ImageFilter.GaussianBlur(radius=blur_radius))
        image.paste(blurred_region, (left, top))

    # ...for each detection

# ...def blur_detections(...)


def render_detection_bounding_boxes(detections,
                                    image,
                                    label_map='show_categories',
                                    classification_label_map=None,
                                    confidence_threshold=0.0,
                                    thickness=DEFAULT_BOX_THICKNESS,
                                    expansion=0,
                                    classification_confidence_threshold=0.3,
                                    max_classifications=3,
                                    colormap=None,
                                    textalign=TEXTALIGN_LEFT,
                                    vtextalign=VTEXTALIGN_TOP,
                                    label_font_size=DEFAULT_LABEL_FONT_SIZE,
                                    custom_strings=None,
                                    box_sort_order='confidence',
                                    verbose=False):
    """
    Renders bounding boxes (with labels and confidence values) on an image for all
    detections above a threshold.

    Renders classification labels if present.

    [image] is modified in place.

    Args:
        detections (list): list of detections in the MD output format, for example:

            .. code-block::none

                [
                    {
                        "category": "2",
                        "conf": 0.996,
                        "bbox": [
                            0.0,
                            0.2762,
                            0.1234,
                            0.2458
                        ]
                    }
                ]

                ...where the bbox coordinates are [x, y, box_width, box_height].

                (0, 0) is the upper-left.  Coordinates are normalized.

            Supports classification results, in the standard format:

            .. code-block::none

                [
                    {
                        "category": "2",
                        "conf": 0.996,
                        "bbox": [
                            0.0,
                            0.2762,
                            0.1234,
                            0.2458
                        ]
                        "classifications": [
                            ["3", 0.901],
                            ["1", 0.071],
                            ["4", 0.025]
                        ]
                    }
                ]

        image (PIL.Image.Image): image on which we should render detections
        label_map (dict, optional): optional, mapping the numeric label to a string name. The type of the
            numeric label (typically strings) needs to be consistent with the keys in label_map; no casting is
            carried out. If [label_map] is None, no labels are shown (not even numbers and confidence values).
            If you want category numbers and confidence values without class labels, use the default value,
            the string 'show_categories'.
        classification_label_map (dict, optional): optional, mapping of the string class labels to the actual
            class names. The type of the numeric label (typically strings) needs to be consistent with the keys
            in label_map; no casting is  carried out. If [label_map] is None, no labels are shown (not even numbers
            and confidence values).
        confidence_threshold (float or dict, optional): threshold above which boxes are rendered.  Can also be a
            dictionary mapping category IDs to thresholds.
        thickness (int, optional): line thickness in pixels
        expansion (int, optional): number of pixels to expand bounding boxes on each side
        classification_confidence_threshold (float, optional): confidence above which classification results
            are displayed
        max_classifications (int, optional): maximum number of classification results rendered for one image
        colormap (list, optional): list of color names, used to choose colors for categories by
            indexing with the values in [classes]; defaults to a reasonable set of colors
        textalign (int, optional): TEXTALIGN_LEFT, TEXTALIGN_CENTER, or TEXTALIGN_RIGHT
        vtextalign (int, optional): VTEXTALIGN_TOP or VTEXTALIGN_BOTTOM
        label_font_size (float, optional): font size for labels
        custom_strings (list of str, optional): optional set of strings to append to detection labels, should
            have the same length as [detections].  Appended before any classification labels.
        box_sort_order (str, optional): sorting scheme for detection boxes, can be None, "confidence", or
            "reverse_confidence".  "confidence" puts the highest-confidence boxes on top.
        verbose (bool, optional): enable additional debug output
    """

    # Input validation
    if (label_map is not None) and (isinstance(label_map,str)) and (label_map == 'show_categories'):
        label_map = {}

    if custom_strings is not None:
        assert len(custom_strings) == len(detections), \
            '{} custom strings provided for {} detections'.format(
                len(custom_strings),len(detections))

    display_boxes = []

    # list of lists, one list of strings for each bounding box (to accommodate multiple labels)
    display_strs = []

    # for color selection
    classes = []

    if box_sort_order is not None:

        if box_sort_order == 'confidence':
            detections = sort_list_of_dicts_by_key(detections,k='conf',reverse=False)
        elif box_sort_order == 'reverse_confidence':
            detections = sort_list_of_dicts_by_key(detections,k='conf',reverse=True)
        else:
            raise ValueError('Unrecognized sorting scheme {}'.format(box_sort_order))

    for i_detection,detection in enumerate(detections):

        score = detection['conf']

        if isinstance(confidence_threshold,dict):
            rendering_threshold = confidence_threshold[detection['category']]
        else:
            rendering_threshold = confidence_threshold

        # Always render objects with a confidence of "None", this is typically used
        # for ground truth data.
        if (score is None) or (rendering_threshold is None) or (score >= rendering_threshold):

            x1, y1, w_box, h_box = detection['bbox']
            display_boxes.append([y1, x1, y1 + h_box, x1 + w_box])

            # The class index to use for coloring this box, which may be based on the detection
            # category or on the most confident classification category.
            clss = detection['category']

            # This will be a list of strings that should be rendered above/below this box
            displayed_label = []

            if label_map is not None:
                label = label_map[clss] if clss in label_map else clss
                if score is not None:
                    displayed_label = ['{}: {}%'.format(label, round(100 * score))]
                else:
                    displayed_label = ['{}'.format(label)]
            else:
                displayed_label = ['']

            if custom_strings is not None:
                custom_string = custom_strings[i_detection]
                if custom_string is not None and len(custom_string) > 0:
                    assert len(displayed_label) == 1
                    displayed_label[0] += ' ' + custom_string

            if ('classifications' in detection) and len(detection['classifications']) > 0:

                classifications = detection['classifications']

                if len(classifications) > max_classifications:
                    classifications = classifications[0:max_classifications]

                max_classification_category = 0
                max_classification_conf = -100

                for classification in classifications:

                    classification_conf = classification[1]
                    if classification_conf is None or \
                       classification_conf < classification_confidence_threshold:
                        continue

                    class_key = classification[0]

                    # Is this the most confident classification for this detection?
                    if classification_conf > max_classification_conf:
                        max_classification_conf = classification_conf
                        max_classification_category = int(class_key)

                    if (classification_label_map is not None) and (class_key in classification_label_map):
                        class_name = classification_label_map[class_key]
                    else:
                        class_name = class_key
                    if classification_conf is not None:
                        displayed_label += ['{}: {:5.1%}'.format(class_name.lower(), classification_conf)]
                    else:
                        displayed_label += ['{}'.format(class_name.lower())]

                # ...for each classification

                # To avoid duplicate colors with detection-only visualization, offset
                # the classification class index by the number of detection classes
                clss = annotation_constants.NUM_DETECTOR_CATEGORIES + max_classification_category

            # ...if we have classification results

            # display_strs is a list of labels for each box
            display_strs.append(displayed_label)
            classes.append(clss)

        # ...if the confidence of this detection is above threshold

    # ...for each detection

    display_boxes = np.array(display_boxes)

    if verbose:
        print('Rendering {} of {} detections'.format(len(display_boxes),len(detections)))

    draw_bounding_boxes_on_image(image,
                                 display_boxes,
                                 classes,
                                 display_strs=display_strs,
                                 thickness=thickness,
                                 expansion=expansion,
                                 colormap=colormap,
                                 textalign=textalign,
                                 vtextalign=vtextalign,
                                 label_font_size=label_font_size)

# ...render_detection_bounding_boxes(...)


def draw_bounding_boxes_on_image(image,
                                 boxes,
                                 classes,
                                 thickness=DEFAULT_BOX_THICKNESS,
                                 expansion=0,
                                 display_strs=None,
                                 colormap=None,
                                 textalign=TEXTALIGN_LEFT,
                                 vtextalign=VTEXTALIGN_TOP,
                                 text_rotation=None,
                                 label_font_size=DEFAULT_LABEL_FONT_SIZE):
    """
    Draws bounding boxes on an image.  Modifies the image in place.

    Args:
        image (PIL.Image): the image on which we should draw boxes
        boxes (np.array): a two-dimensional numpy array of size [N, 4], where N is the
            number of boxes, and each row is (ymin, xmin, ymax, xmax).  Coordinates should be
            normalized to image height/width.
        classes (list): a list of ints or string-formatted ints corresponding to the
             class labels of the boxes. This is only used for color selection.  Should have the same
             length as [boxes].
        thickness (int, optional): line thickness in pixels
        expansion (int, optional): number of pixels to expand bounding boxes on each side
        display_strs (list, optional): list of list of strings (the outer list should have the
            same length as [boxes]).  Typically this is used to show (possibly multiple) detection
            or classification categories and/or confidence values.
        colormap (list, optional): list of color names, used to choose colors for categories by
            indexing with the values in [classes]; defaults to a reasonable set of colors
        textalign (int, optional): TEXTALIGN_LEFT, TEXTALIGN_CENTER, or TEXTALIGN_RIGHT
        vtextalign (int, optional): VTEXTALIGN_TOP or VTEXTALIGN_BOTTOM
        text_rotation (float, optional): rotation to apply to text
        label_font_size (float, optional): font size for labels
    """

    boxes_shape = boxes.shape
    if not boxes_shape:
        return
    if len(boxes_shape) != 2 or boxes_shape[1] != 4:
        return
    for i in range(boxes_shape[0]):
        display_str_list = None
        if display_strs:
            display_str_list = display_strs[i]
        draw_bounding_box_on_image(image,
                                   boxes[i, 0], boxes[i, 1], boxes[i, 2], boxes[i, 3],
                                   classes[i],
                                   thickness=thickness, expansion=expansion,
                                   display_str_list=display_str_list,
                                   colormap=colormap,
                                   textalign=textalign,
                                   vtextalign=vtextalign,
                                   text_rotation=text_rotation,
                                   label_font_size=label_font_size)

# ...draw_bounding_boxes_on_image(...)


def get_text_size(font,s):
    """
    Get the expected width and height when rendering the string [s] in the font
    [font].

    Args:
        font (PIL.ImageFont): the font whose size we should query
        s (str): the string whose size we should query

    Returns:
        tuple: (w,h), both floats in pixel coordinates
    """

    # This is what we did w/Pillow 9
    # w,h = font.getsize(s)

    # I would *think* this would be the equivalent for Pillow 10
    # l,t,r,b = font.getbbox(s); w = r-l; h=b-t

    # ...but this actually produces the most similar results to Pillow 9
    # l,t,r,b = font.getbbox(s); w = r; h=b

    try:
        l,t,r,b = font.getbbox(s); w = r; h=b # noqa
    except Exception:
        w,h = font.getsize(s)

    return w,h


def draw_bounding_box_on_image(image,
                               ymin,
                               xmin,
                               ymax,
                               xmax,
                               clss=None,
                               thickness=DEFAULT_BOX_THICKNESS,
                               expansion=0,
                               display_str_list=None,
                               use_normalized_coordinates=True,
                               label_font_size=DEFAULT_LABEL_FONT_SIZE,
                               colormap=None,
                               textalign=TEXTALIGN_LEFT,
                               vtextalign=VTEXTALIGN_TOP,
                               text_rotation=None):
    """
    Adds a bounding box to an image.  Modifies the image in place.

    Bounding box coordinates can be specified in either absolute (pixel) or
    normalized coordinates by setting the use_normalized_coordinates argument.

    Each string in display_str_list is displayed on a separate line above the
    bounding box in black text on a rectangle filled with the input 'color'.
    If the top of the bounding box extends to the edge of the image, the strings
    are displayed below the bounding box.

    Adapted from:

    https://github.com/tensorflow/models/blob/master/research/object_detection/utils/visualization_utils.py

    Args:
        image (PIL.Image.Image): the image on which we should draw a box
        ymin (float): ymin of bounding box
        xmin (float): xmin of bounding box
        ymax (float): ymax of bounding box
        xmax (float): xmax of bounding box
        clss (int, optional): the class index of the object in this bounding box, used for choosing
            a color; should be either an integer or a string-formatted integer
        thickness (int, optional): line thickness in pixels
        expansion (int, optional): number of pixels to expand bounding boxes on each side
        display_str_list (list, optional): list of strings to display above the box (each to be shown on its
            own line)
        use_normalized_coordinates (bool, optional): if True (default), treat coordinates
            ymin, xmin, ymax, xmax as relative to the image, otherwise coordinates as absolute pixel values
        label_font_size (float, optional): font size
        colormap (list, optional): list of color names, used to choose colors for categories by
            indexing with the values in [classes]; defaults to a reasonable set of colors
        textalign (int, optional): TEXTALIGN_LEFT, TEXTALIGN_CENTER, or TEXTALIGN_RIGHT
        vtextalign (int, optional): VTEXTALIGN_TOP or VTEXTALIGN_BOTTOM
        text_rotation (float, optional): rotation to apply to text
    """

    if colormap is None:
        colormap = DEFAULT_COLORS

    if display_str_list is None:
        display_str_list = []

    if clss is None:
        # Default to the MegaDetector animal class ID (1)
        color = colormap[1]
    else:
        color = colormap[int(clss) % len(colormap)]

    draw = ImageDraw.Draw(image)
    im_width, im_height = image.size
    if use_normalized_coordinates:
        (left, right, top, bottom) = (xmin * im_width, xmax * im_width,
                                      ymin * im_height, ymax * im_height)
    else:
        (left, right, top, bottom) = (xmin, xmax, ymin, ymax)

    if expansion > 0:

        left -= expansion
        right += expansion
        top -= expansion
        bottom += expansion

        # Deliberately trimming to the width of the image only in the case where
        # box expansion is turned on.  There's not an obvious correct behavior here,
        # but the thinking is that if the caller provided an out-of-range bounding
        # box, they meant to do that, but at least in the eyes of the person writing
        # this comment, if you expand a box for visualization reasons, you don't want
        # to end up with part of a box.
        #
        # A slightly more sophisticated might check whether it was in fact the expansion
        # that made this box larger than the image, but this is the case 99.999% of the time
        # here, so that doesn't seem necessary.
        left = max(left,0); right = max(right,0)
        top = max(top,0); bottom = max(bottom,0)

        left = min(left,im_width-1); right = min(right,im_width-1)
        top = min(top,im_height-1); bottom = min(bottom,im_height-1)

    # ...if we need to expand boxes

    draw.line([(left, top), (left, bottom), (right, bottom),
               (right, top), (left, top)], width=thickness, fill=color)

    if display_str_list is not None:

        try:
            font = ImageFont.truetype('arial.ttf', label_font_size)
        except OSError:
            font = ImageFont.load_default()

        display_str_heights = [get_text_size(font,ds)[1] for ds in display_str_list]

        # Each display_str has a top and bottom margin of 0.05x.
        total_display_str_height = (1 + 2 * 0.05) * sum(display_str_heights)

        # Reverse list and print from bottom to top
        for i_str,display_str in enumerate(display_str_list[::-1]):

            # Skip empty strings
            if len(display_str) == 0:
                continue

            text_width, text_height = get_text_size(font,display_str)
            margin = int(np.ceil(0.05 * text_height))

            if text_rotation is not None and text_rotation != 0:

                assert text_rotation == -90, \
                    'Only -90-degree text rotation is supported'

                image_tmp = Image.new('RGB',(text_width+2*margin,text_height+2*margin))
                image_tmp_draw = ImageDraw.Draw(image_tmp)
                image_tmp_draw.rectangle([0,0,text_width+2*margin,text_height+2*margin],fill=color)
                image_tmp_draw.text( (margin,margin), display_str, font=font, fill='black')
                rotated_text = image_tmp.rotate(text_rotation,expand=1)

                if textalign == TEXTALIGN_RIGHT:
                    text_left = right
                else:
                    text_left = left
                text_left = int(text_left + (text_height) * i_str)

                if vtextalign == VTEXTALIGN_BOTTOM:
                    text_top = bottom - text_width
                else:
                    text_top = top
                text_left = int(text_left)
                text_top = int(text_top)

                image.paste(rotated_text,[text_left,text_top])

            else:

                # If the total height of the display strings added to the top of the bounding
                # box exceeds the top of the image, stack the strings below the bounding box
                # instead of above, and vice-versa if we're bottom-aligning.
                #
                # If the text just doesn't fit outside the box, we don't try anything fancy,
                # it will just appear outside the image.
                if vtextalign == VTEXTALIGN_TOP:
                    text_bottom = top
                    if (text_bottom - total_display_str_height) < 0:
                        text_bottom = bottom + total_display_str_height
                else:
                    assert vtextalign == VTEXTALIGN_BOTTOM, \
                        'Unrecognized vertical text alignment {}'.format(vtextalign)
                    text_bottom = bottom + total_display_str_height
                    if (text_bottom + total_display_str_height) > im_height:
                        text_bottom = top

                text_bottom = int(text_bottom) - i_str * (int(text_height + (2 * margin)))

                text_left = left

                if textalign == TEXTALIGN_RIGHT:
                    text_left = right - text_width
                elif textalign == TEXTALIGN_CENTER:
                    text_left = ((right + left) / 2.0) - (text_width / 2.0)
                text_left = int(text_left)

                draw.rectangle(
                    [(text_left, (text_bottom - text_height) - (2 * margin)),
                     (text_left + text_width, text_bottom)],
                    fill=color)

                draw.text(
                    (text_left + margin, text_bottom - text_height - margin),
                    display_str,
                    fill='black',
                    font=font)

            # ...if we're rotating text

    # ...if we're rendering text

# ...def draw_bounding_box_on_image(...)


def render_megadb_bounding_boxes(boxes_info, image):
    """
    Render bounding boxes to an image, where those boxes are in the mostly-deprecated
    MegaDB format, which looks like:

    .. code-block::none

        {
            "category": "animal",
            "bbox": [
                0.739,
                0.448,
                0.187,
                0.198
            ]
        }

    Args:
        boxes_info (list): list of dicts, each dict represents a single detection
            where bbox coordinates are normalized [x_min, y_min, width, height]
        image (PIL.Image.Image): image to modify

    :meta private:
    """

    display_boxes = []
    display_strs = []
    classes = []  # ints, for selecting colors

    for b in boxes_info:
        x_min, y_min, w_rel, h_rel = b['bbox']
        y_max = y_min + h_rel
        x_max = x_min + w_rel
        display_boxes.append([y_min, x_min, y_max, x_max])
        display_strs.append([b['category']])
        classes.append(annotation_constants.detector_bbox_category_name_to_id[b['category']])

    display_boxes = np.array(display_boxes)
    draw_bounding_boxes_on_image(image, display_boxes, classes, display_strs=display_strs)

# ...def render_iMerit_boxes(...)


def render_db_bounding_boxes(boxes,
                             classes,
                             image,
                             original_size=None,
                             label_map=None,
                             thickness=DEFAULT_BOX_THICKNESS,
                             expansion=0,
                             colormap=None,
                             textalign=TEXTALIGN_LEFT,
                             vtextalign=VTEXTALIGN_TOP,
                             text_rotation=None,
                             label_font_size=DEFAULT_LABEL_FONT_SIZE,
                             tags=None,
                             boxes_are_normalized=False):
    """
    Render bounding boxes (with class labels) on an image.  This is a wrapper for
    draw_bounding_boxes_on_image, allowing the caller to operate on a resized image
    by providing the original size of the image; boxes will be scaled accordingly.

    This function assumes that bounding boxes are in absolute coordinates, typically
    because they come from COCO camera traps .json files, unless boxes_are_normalized
    is True.

    Args:
        boxes (list): list of length-4 tuples, foramtted as (x,y,w,h) (in pixels)
        classes (list): list of ints (or string-formatted ints), used to choose labels (either
            by literally rendering the class labels, or by indexing into [label_map])
        image (PIL.Image.Image): image object to modify
        original_size (tuple, optional): if this is not None, and the size is different than
            the size of [image], we assume that [boxes] refer to the original size, and we scale
            them accordingly before rendering
        label_map (dict, optional): int --> str dictionary, typically mapping category IDs to
            species labels; if None, category labels are rendered verbatim (typically as numbers)
        thickness (int, optional): line width
        expansion (int, optional): a number of pixels to include on each side of a cropped
            detection
        colormap (list, optional): list of color names, used to choose colors for categories by
            indexing with the values in [classes]; defaults to a reasonable set of colors
        textalign (int, optional): TEXTALIGN_LEFT, TEXTALIGN_CENTER, or TEXTALIGN_RIGHT
        vtextalign (int, optional): VTEXTALIGN_TOP or VTEXTALIGN_BOTTOM
        text_rotation (float, optional): rotation to apply to text
        label_font_size (float, optional): font size for labels
        tags (list, optional): list of strings of length len(boxes) that should be appended
            after each class name (e.g. to show scores)
        boxes_are_normalized (bool, optional): whether boxes have already been normalized
    """

    display_boxes = []
    display_strs = []

    if original_size is not None:
        image_size = original_size
    else:
        image_size = image.size

    img_width, img_height = image_size

    for i_box in range(0,len(boxes)):

        box = boxes[i_box]
        clss = classes[i_box]

        x_min_abs, y_min_abs, width_abs, height_abs = box[0:4]

        # Normalize boxes if necessary
        if boxes_are_normalized:

            xmin = x_min_abs
            xmax = x_min_abs + width_abs
            ymin = y_min_abs
            ymax = y_min_abs + height_abs

        else:

            ymin = y_min_abs / img_height
            ymax = ymin + height_abs / img_height

            xmin = x_min_abs / img_width
            xmax = xmin + width_abs / img_width

        display_boxes.append([ymin, xmin, ymax, xmax])

        if label_map:
            clss = label_map[int(clss)]

        display_str = str(clss)

        # Do we have a tag to append to the class string?
        if tags is not None and tags[i_box] is not None and len(tags[i_box]) > 0:
            display_str += ' ' + tags[i_box]

        # need to be a string here because PIL needs to iterate through chars
        display_strs.append([display_str])

    # ...for each box

    display_boxes = np.array(display_boxes)

    draw_bounding_boxes_on_image(image,
                                 display_boxes,
                                 classes,
                                 display_strs=display_strs,
                                 thickness=thickness,
                                 expansion=expansion,
                                 colormap=colormap,
                                 textalign=textalign,
                                 vtextalign=vtextalign,
                                 text_rotation=text_rotation,
                                 label_font_size=label_font_size)

# ...def render_db_bounding_boxes(...)


def draw_bounding_boxes_on_file(input_file,
                                output_file,
                                detections,
                                confidence_threshold=0.0,
                                detector_label_map=DEFAULT_DETECTOR_LABEL_MAP,
                                thickness=DEFAULT_BOX_THICKNESS,
                                expansion=0,
                                colormap=None,
                                label_font_size=DEFAULT_LABEL_FONT_SIZE,
                                custom_strings=None,
                                target_size=None,
                                ignore_exif_rotation=False):
    """
    Renders detection bounding boxes on an image loaded from file, optionally writing the results to
    a new image file.

    Args:
        input_file (str): filename or URL to load
        output_file (str): filename to which we should write the rendered image
        detections (list): a list of dictionaries with keys 'conf', 'bbox', and 'category';
            boxes are length-four arrays formatted as [x,y,w,h], normalized,
            upper-left origin (this is the standard MD detection format). 'category' is a string-int.
        confidence_threshold (float, optional): only render detections with confidence above this
            threshold
        detector_label_map (dict, optional): a dict mapping category IDs to strings.  If this
            is None, no confidence values or identifiers are shown.  If this is {}, just category
            indices and confidence values are shown.
        thickness (int, optional): line width in pixels for box rendering
        expansion (int, optional): box expansion in pixels
        colormap (list, optional): list of color names, used to choose colors for categories by
            indexing with the values in [classes]; defaults to a reasonable set of colors
        label_font_size (float, optional): label font size
        custom_strings (list, optional): set of strings to append to detection labels, should have the
            same length as [detections].  Appended before any classification labels.
        target_size (tuple, optional): tuple of (target_width,target_height).  Either or both can be -1,
            see resize_image() for documentation.  If None or (-1,-1), uses the original image size.
        ignore_exif_rotation (bool, optional): don't rotate the loaded pixels,
            even if we are loading a JPEG and that JPEG says it should be rotated.

    Returns:
        PIL.Image.Image: loaded and modified image
    """

    image = open_image(input_file, ignore_exif_rotation=ignore_exif_rotation)

    if target_size is not None:
        image = resize_image(image,target_size[0],target_size[1])

    render_detection_bounding_boxes(
            detections,
            image,
            label_map=detector_label_map,
            confidence_threshold=confidence_threshold,
            thickness=thickness,
            expansion=expansion,
            colormap=colormap,
            custom_strings=custom_strings,
            label_font_size=label_font_size)

    if output_file is not None:
        image.save(output_file)

    return image


def draw_db_boxes_on_file(input_file,
                          output_file,
                          boxes,
                          classes=None,
                          label_map=None,
                          thickness=DEFAULT_BOX_THICKNESS,
                          expansion=0,
                          ignore_exif_rotation=False):
    """
    Render COCO-formatted bounding boxes (in absolute coordinates) on an image loaded from file,
    writing the results to a new image file.

    Args:
        input_file (str): image file to read
        output_file (str): image file to write
        boxes (list): list of length-4 tuples, foramtted as (x,y,w,h) (in pixels)
        classes (list, optional): list of ints (or string-formatted ints), used to choose
            labels (either by literally rendering the class labels, or by indexing into [label_map])
        label_map (dict, optional): int --> str dictionary, typically mapping category IDs to
            species labels; if None, category labels are rendered verbatim (typically as numbers)
        thickness (int, optional): line width
        expansion (int, optional): a number of pixels to include on each side of a cropped
            detection
        ignore_exif_rotation (bool, optional): don't rotate the loaded pixels,
            even if we are loading a JPEG and that JPEG says it should be rotated

    Returns:
        PIL.Image.Image: the loaded and modified image
    """

    image = open_image(input_file, ignore_exif_rotation=ignore_exif_rotation)

    if classes is None:
        classes = [0] * len(boxes)

    render_db_bounding_boxes(boxes,
                             classes,
                             image,
                             original_size=None,
                             label_map=label_map,
                             thickness=thickness,
                             expansion=expansion)

    image.save(output_file)

    return image

# ...def draw_bounding_boxes_on_file(...)


def gray_scale_fraction(image,crop_size=(0.1,0.1)):
    """
    Computes the fraction of the pixels in [image] that appear to be grayscale (R==G==B),
    useful for approximating whether this is a night-time image when flash information is not
    available in EXIF data (or for video frames, where this information is often not available
    in structured metadata at all).

    Args:
        image (str or PIL.Image.Image): Image, filename, or URL to analyze
        crop_size (tuple of floats, optional): a 2-element list/tuple, representing the fraction of
            the image to crop at the top and bottom, respectively, before analyzing (to minimize
            the possibility of including color elements in the image overlay)

    Returns:
        float: the fraction of pixels in [image] that appear to be grayscale (R==G==B)
    """

    if isinstance(image,str):
        image = Image.open(image)

    if image.mode == 'L':
        return 1.0

    if len(image.getbands()) == 1:
        return 1.0

    # Crop if necessary
    if crop_size[0] > 0 or crop_size[1] > 0:

        assert (crop_size[0] + crop_size[1]) < 1.0, \
            print('Illegal crop size: {}'.format(str(crop_size)))

        top_crop_pixels = int(image.height * crop_size[0])
        bottom_crop_pixels = int(image.height * crop_size[1])

        left = 0
        right = image.width

        # Remove pixels from the top
        first_crop_top = top_crop_pixels
        first_crop_bottom = image.height
        first_crop = image.crop((left, first_crop_top, right, first_crop_bottom))

        # Remove pixels from the bottom
        second_crop_top = 0
        second_crop_bottom = first_crop.height - bottom_crop_pixels
        second_crop = first_crop.crop((left, second_crop_top, right, second_crop_bottom))

        image = second_crop

    # It doesn't matter if these are actually R/G/B, they're just names
    r = np.array(image.getchannel(0))
    g = np.array(image.getchannel(1))
    b = np.array(image.getchannel(2))

    gray_pixels = np.logical_and(r == g, r == b)
    n_pixels = gray_pixels.size
    n_gray_pixels = gray_pixels.sum()

    return n_gray_pixels / n_pixels

    # Non-numpy way to do the same thing, briefly keeping this here for posterity
    if False:

        w, h = image.size
        n_pixels = w*h
        n_gray_pixels = 0
        for i in range(w):
            for j in range(h):
                r, g, b = image.getpixel((i,j))
                if r == g and r == b and g == b:
                    n_gray_pixels += 1

# ...def gray_scale_fraction(...)


def _resize_relative_image(fn_relative,
                           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.
    """

    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,
                         output_file=output_fn_abs,
                         target_width=target_width,
                         target_height=target_height,
                         no_enlarge_width=no_enlarge_width,
                         verbose=verbose,
                         quality=quality)
        status = 'success'
        error = None
    except Exception as e:
        if verbose:
            print('Error resizing {}: {}'.format(fn_relative,str(e)))
        status = 'error'
        error = str(e)

    return {'fn_relative':fn_relative,'status':status,'error':error}

# ...def _resize_relative_image(...)


def _resize_absolute_image(input_output_files,
                           target_width,
                           target_height,
                           no_enlarge_width,
                           verbose,
                           quality):
    """
    Internal wrapper for resize_image used in the context of a batch resize operation.
    """

    input_fn_abs = input_output_files[0]
    output_fn_abs = input_output_files[1]
    os.makedirs(os.path.dirname(output_fn_abs),exist_ok=True)
    try:
        _ = resize_image(input_fn_abs,
                         output_file=output_fn_abs,
                         target_width=target_width,
                         target_height=target_height,
                         no_enlarge_width=no_enlarge_width,
                         verbose=verbose,
                         quality=quality)
        status = 'success'
        error = None
    except Exception as e:
        if verbose:
            print('Error resizing {}: {}'.format(input_fn_abs,str(e)))
        status = 'error'
        error = str(e)

    return {'input_fn':input_fn_abs,'output_fn':output_fn_abs,status:'status',
            'error':error}

# ..._resize_absolute_image(...)


def resize_images(input_file_to_output_file,
                  target_width=-1,
                  target_height=-1,
                  no_enlarge_width=False,
                  verbose=False,
                  quality='keep',
                  pool_type='process',
                  n_workers=10):
    """
    Resizes all images the dictionary [input_file_to_output_file].

    TODO: This is a little more redundant with resize_image_folder than I would like;
    refactor resize_image_folder to call resize_images.  Not doing that yet because
    at the time I'm writing this comment, a lot of code depends on resize_image_folder
    and I don't want to rock the boat yet.

    Args:
        input_file_to_output_file (dict): dict mapping images that exist to the locations
            where the resized versions should be written
        target_width (int, optional): width to which we should resize this image, or -1
            to let target_height determine the size
        target_height (int, optional): height to which we should resize this image, or -1
            to let target_width determine the size
        no_enlarge_width (bool, optional): if [no_enlarge_width] is True, and
            [target width] is larger than the original image width, does not modify the image,
            but will write to output_file if supplied
        verbose (bool, optional): enable additional debug output
        quality (str or int, optional): passed to exif_preserving_save, see docs for more detail
        pool_type (str, optional): whether use use processes ('process') or threads ('thread') for
            parallelization; ignored if n_workers <= 1
        n_workers (int, optional): number of workers to use for parallel resizing; set to <=1
            to disable parallelization

    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.
    """

    assert pool_type in ('process','thread'), 'Illegal pool type {}'.format(pool_type)

    input_output_file_pairs = []

    # Reformat input files as (input,output) tuples
    for input_fn in input_file_to_output_file:
        input_output_file_pairs.append((input_fn,input_file_to_output_file[input_fn]))

    if n_workers == 1:

        results = []
        for i_o_file_pair in tqdm(input_output_file_pairs):
            results.append(_resize_absolute_image(i_o_file_pair,
                            target_width=target_width,
                            target_height=target_height,
                            no_enlarge_width=no_enlarge_width,
                            verbose=verbose,
                            quality=quality))

    else:

        pool = None

        try:
            if pool_type == 'thread':
                pool = ThreadPool(n_workers); poolstring = 'threads'
            else:
                assert pool_type == 'process'
                pool = Pool(n_workers); poolstring = 'processes'

            if verbose:
                print('Starting resizing pool with {} {}'.format(n_workers,poolstring))

            p = partial(_resize_absolute_image,
                    target_width=target_width,
                    target_height=target_height,
                    no_enlarge_width=no_enlarge_width,
                    verbose=verbose,
                    quality=quality)

            results = list(tqdm(pool.imap(p, input_output_file_pairs),total=len(input_output_file_pairs)))
        finally:
            pool.close()
            pool.join()
            print("Pool closed and joined for image resizing")

    return results

# ...def resize_images(...)


def resize_image_folder(input_folder,
                        output_folder=None,
                        target_width=-1,
                        target_height=-1,
                        no_enlarge_width=False,
                        verbose=False,
                        quality='keep',
                        pool_type='process',
                        n_workers=10,
                        recursive=True,
                        image_files_relative=None,
                        overwrite=True):
    """
    Resize all images in a folder (defaults to recursive).

    Defaults to in-place resizing (output_folder is optional).

    Args:
        input_folder (str): folder in which we should find images to resize
        output_folder (str, optional): folder in which we should write resized images.  If
            None, resizes images in place.  Otherwise, maintains relative paths in the target
            folder.
        target_width (int, optional): width to which we should resize this image, or -1
            to let target_height determine the size
        target_height (int, optional): height to which we should resize this image, or -1
            to let target_width determine the size
        no_enlarge_width (bool, optional): if [no_enlarge_width] is True, and
            [target width] is larger than the original image width, does not modify the image,
            but will write to output_file if supplied
        verbose (bool, optional): enable additional debug output
        quality (str or int, optional): passed to exif_preserving_save, see docs for more detail
        pool_type (str, optional): whether use use processes ('process') or threads ('thread') for
            parallelization; ignored if n_workers <= 1
        n_workers (int, optional): number of workers to use for parallel resizing; set to <=1
            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
        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', '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)

    if output_folder is None:
        output_folder = input_folder
    else:
        os.makedirs(output_folder,exist_ok=True)

    assert pool_type in ('process','thread'), 'Illegal pool type {}'.format(pool_type)

    if image_files_relative is None:

        if verbose:
            print('Enumerating images')

        image_files_relative = find_images(input_folder,recursive=recursive,
                                           return_relative_paths=True,convert_slashes=True)
        if verbose:
            print('Found {} images'.format(len(image_files_relative)))

    if n_workers == 1:

        if verbose:
            print('Resizing images')

        results = []
        for fn_relative in tqdm(image_files_relative):
            results.append(_resize_relative_image(fn_relative,
                                  input_folder=input_folder,
                                  output_folder=output_folder,
                                  target_width=target_width,
                                  target_height=target_height,
                                  no_enlarge_width=no_enlarge_width,
                                  verbose=verbose,
                                  quality=quality,
                                  overwrite=overwrite))

    else:

        if pool_type == 'thread':
            pool = ThreadPool(n_workers); poolstring = 'threads'
        else:
            assert pool_type == 'process'
            pool = Pool(n_workers); poolstring = 'processes'

        if verbose:
            print('Starting resizing pool with {} {}'.format(n_workers,poolstring))

        p = partial(_resize_relative_image,
                input_folder=input_folder,
                output_folder=output_folder,
                target_width=target_width,
                target_height=target_height,
                no_enlarge_width=no_enlarge_width,
                verbose=verbose,
                quality=quality,
                overwrite=overwrite)

        results = list(tqdm(pool.imap(p, image_files_relative),
                            total=len(image_files_relative)))

    return results

# ...def resize_image_folder(...)


def get_image_size(im,verbose=False):
    """
    Retrieve the size of an image.  Returns None if the image fails to load.

    Args:
        im (str or PIL.Image): filename or PIL image
        verbose (bool, optional): enable additional debug output

    Returns:
        tuple (w,h), or None if the image fails to load.
    """

    image_name = '[in memory]'

    try:
        if isinstance(im,str):
            image_name = im
            im = load_image(im)
        w = im.width
        h = im.height
        if w <= 0 or h <= 0:
            if verbose:
                print('Error reading width from image {}: {},{}'.format(
                    image_name,w,h))
            return None
        return (w,h)
    except Exception as e:
        if verbose:
            print('Error reading width from image {}: {}'.format(
                image_name,str(e)))
        return None

# ...def get_image_size(...)


def parallel_get_image_sizes(filenames,
                             max_workers=16,
                             use_threads=True,
                             recursive=True,
                             verbose=False):
    """
    Retrieve image sizes for a list or folder of images

    Args:
        filenames (list or str): a list of image filenames or a folder.  Non-image files and
            unreadable images will be returned with a file size of None.
        max_workers (int, optional): the number of parallel workers to use; set to <=1 to disable
            parallelization
        use_threads (bool, optional): whether to use threads (True) or processes (False) for
            parallelization
        recursive (bool, optional): if [filenames] is a folder, whether to search recursively
            for images. Ignored if [filenames] is a list.
        verbose (bool, optional): enable additional debug output

    Returns:
        dict: a dict mapping filenames to (w,h) tuples; the value will be None for images that fail
        to load.  Filenames will always be absolute.
    """

    if isinstance(filenames,str) and os.path.isdir(filenames):
        if verbose:
            print('Enumerating images in {}'.format(filenames))
        filenames = find_images(filenames,recursive=recursive,return_relative_paths=False)

    n_workers = min(max_workers,len(filenames))

    if verbose:
        print('Getting image sizes for {} images'.format(len(filenames)))

    if n_workers <= 1:

        results = []
        for filename in filenames:
            results.append(get_image_size(filename,verbose=verbose))

    else:

        if use_threads:
            pool = ThreadPool(n_workers)
        else:
            pool = Pool(n_workers)

        results = list(tqdm(pool.imap(
            partial(get_image_size,verbose=verbose),filenames), total=len(filenames)))

    assert len(filenames) == len(results), 'Internal error in parallel_get_image_sizes'

    to_return = {}
    for i_file,filename in enumerate(filenames):
        to_return[filename] = results[i_file]

    return to_return


#%% Image integrity checking functions

def check_image_integrity(filename,modes=None):
    """
    Check whether we can successfully load an image via OpenCV and/or PIL.

    Args:
        filename (str): the filename to evaluate
        modes (list, optional): a list containing one or more of:

            - 'cv'
            - 'pil'
            - 'skimage'
            - 'jpeg_trailer'

            'jpeg_trailer' checks that the binary data ends with ffd9.  It does not check whether
            the image is actually a jpeg, and even if it is, there are lots of reasons the image might not
            end with ffd9.  It's also true the JPEGs that cause "premature end of jpeg segment" issues
            don't end with ffd9, so this may be a useful diagnostic.  High precision, very low recall
            for corrupt jpegs.

            Set to None to use all modes.

    Returns:
        dict: a dict with a key called 'file' (the value of [filename]), one key for each string in
        [modes] (a success indicator for that mode, specifically a string starting with either
        'success' or 'error').
    """

    if modes is None:
        modes = ('cv','pil','skimage','jpeg_trailer')
    else:
        if isinstance(modes,str):
            modes = [modes]
        for mode in modes:
            assert mode in ('cv','pil','skimage'), 'Unrecognized mode {}'.format(mode)

    assert os.path.isfile(filename), 'Could not find file {}'.format(filename)

    result = {}
    result['file'] = filename

    for mode in modes:

        result[mode] = 'unknown'
        if mode == 'pil':
            try:
                pil_im = load_image(filename) # noqa
                assert pil_im is not None
                result[mode] = 'success'
            except Exception as e:
                result[mode] = 'error: {}'.format(str(e))
        elif mode == 'cv':
            try:
                cv_im = cv2.imread(filename)
                assert cv_im is not None, 'Unknown opencv read failure'
                numpy_im = np.asarray(cv_im) # noqa
                result[mode] = 'success'
            except Exception as e:
                result[mode] = 'error: {}'.format(str(e))
        elif mode == 'skimage':
            try:
                # This is not a standard dependency
                from skimage import io as skimage_io # type: ignore # noqa
            except Exception:
                result[mode] = 'could not import skimage, run pip install scikit-image'
                return result
            try:
                skimage_im = skimage_io.imread(filename) # noqa
                assert skimage_im is not None
                result[mode] = 'success'
            except Exception as e:
                result[mode] = 'error: {}'.format(str(e))
        elif mode == 'jpeg_trailer':
            # https://stackoverflow.com/a/48282863/16644970
            try:
                with open(filename, 'rb') as f:
                    check_chars = f.read()[-2:]
                if check_chars != b'\xff\xd9':
                    result[mode] = 'invalid jpeg trailer: {}'.format(str(check_chars))
                else:
                    result[mode] = 'success'
            except Exception as e:
                result[mode] = 'error: {}'.format(str(e))

    # ...for each mode

    return result

# ...def check_image_integrity(...)


def parallel_check_image_integrity(filenames,
                                   modes=None,
                                   max_workers=16,
                                   use_threads=True,
                                   recursive=True,
                                   verbose=False):
    """
    Check whether we can successfully load a list of images via OpenCV and/or PIL.

    Args:
        filenames (list or str): a list of image filenames or a folder
        modes (list, optional): see check_image_integrity() for documentation on the [modes] parameter
        max_workers (int, optional): the number of parallel workers to use; set to <=1 to disable
            parallelization
        use_threads (bool, optional): whether to use threads (True) or processes (False) for
            parallelization
        recursive (bool, optional): if [filenames] is a folder, whether to search recursively for images.
            Ignored if [filenames] is a list.
        verbose (bool, optional): enable additional debug output

    Returns:
        list: a list of dicts, each with a key called 'file' (the value of [filename]), one key for
        each string in [modes] (a success indicator for that mode, specifically a string starting
        with either 'success' or 'error').
    """

    if isinstance(filenames,str) and os.path.isdir(filenames):
        if verbose:
            print('Enumerating images in {}'.format(filenames))
        filenames = find_images(filenames,recursive=recursive,return_relative_paths=False)

    n_workers = min(max_workers,len(filenames))

    if verbose:
        print('Checking image integrity for {} filenames'.format(len(filenames)))

    if n_workers <= 1:

        results = []
        for filename in filenames:
            results.append(check_image_integrity(filename,modes=modes))

    else:

        if use_threads:
            pool = ThreadPool(n_workers)
        else:
            pool = Pool(n_workers)

        results = list(tqdm(pool.imap(
            partial(check_image_integrity,modes=modes),filenames), total=len(filenames)))

    return results


#%% Test drivers

if False:

    #%% Text rendering tests

    import os # noqa
    import numpy as np # noqa
    from megadetector.visualization.visualization_utils import \
        draw_bounding_boxes_on_image, exif_preserving_save, load_image, \
        TEXTALIGN_LEFT,TEXTALIGN_RIGHT,VTEXTALIGN_BOTTOM,VTEXTALIGN_TOP, \
        DEFAULT_LABEL_FONT_SIZE

    fn = os.path.expanduser('~/AppData/Local/Temp/md-tests/md-test-images/ena24_7904.jpg')
    output_fn = r'g:\temp\test.jpg'

    image = load_image(fn)

    w = 0.2; h = 0.2
    all_boxes = [[0.05, 0.05, 0.25, 0.25],
                 [0.05, 0.35, 0.25, 0.6],
                 [0.35, 0.05, 0.6, 0.25],
                 [0.35, 0.35, 0.6, 0.6]]

    alignments = [
        [TEXTALIGN_LEFT,VTEXTALIGN_TOP],
        [TEXTALIGN_LEFT,VTEXTALIGN_BOTTOM],
        [TEXTALIGN_RIGHT,VTEXTALIGN_TOP],
        [TEXTALIGN_RIGHT,VTEXTALIGN_BOTTOM]
        ]

    labels = ['left_top','left_bottom','right_top','right_bottom']

    text_rotation = -90
    n_label_copies = 2

    for i_box,box in enumerate(all_boxes):

        boxes = [box]
        boxes = np.array(boxes)
        classes = [i_box]
        display_strs = [[labels[i_box]]*n_label_copies]
        textalign = alignments[i_box][0]
        vtextalign = alignments[i_box][1]
        draw_bounding_boxes_on_image(image,
                                     boxes,
                                     classes,
                                     thickness=2,
                                     expansion=0,
                                     display_strs=display_strs,
                                     colormap=None,
                                     textalign=textalign,
                                     vtextalign=vtextalign,
                                     label_font_size=DEFAULT_LABEL_FONT_SIZE,
                                     text_rotation=text_rotation)

    exif_preserving_save(image,output_fn)
    from megadetector.utils.path_utils import open_file
    open_file(output_fn)


    #%% Recursive resize test

    from megadetector.visualization.visualization_utils import resize_image_folder # noqa

    input_folder = r"C:\temp\resize-test\in"
    output_folder = r"C:\temp\resize-test\out"

    resize_results = resize_image_folder(input_folder,output_folder,
                         target_width=1280,verbose=True,quality=85,no_enlarge_width=True,
                         pool_type='process',n_workers=10)


    #%% Integrity checking test

    from megadetector.utils import md_tests
    options = md_tests.download_test_data()
    folder = options.scratch_dir

    results = parallel_check_image_integrity(folder,max_workers=8)

    modes = ['cv','pil','skimage','jpeg_trailer']

    for r in results:
        for mode in modes:
            if r[mode] != 'success':
                s = r[mode]
                print('Mode {} failed for {}:\n{}\n'.format(mode,r['file'],s))
