megadetector 5.0.11__py3-none-any.whl → 5.0.12__py3-none-any.whl

megadetector/classification/train_utils.py

@@ -0,0 +1,323 @@
+"""
+
+train_utils.py
+
+Utility functions useful for training a classifier.
+
+This script should NOT depend on any other file within this repo. It should
+especially be agnostic to PyTorch vs. TensorFlow.
+
+"""
+
+#%% Imports
+
+from __future__ import annotations
+
+import dataclasses
+import heapq
+import io
+import json
+
+import matplotlib.figure
+import numpy as np
+import pandas as pd
+import PIL.Image
+import scipy.interpolate
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional
+
+
+#%% Classes
+
+@dataclasses.dataclass(order=True)
+class HeapItem:
+    """
+    A wrapper over non-comparable data with a comparable priority value.
+    """
+    
+    priority: Any
+    data: Any = dataclasses.field(compare=False, repr=False)
+
+
+def add_to_heap(h: list[Any], item: HeapItem, k: Optional[int] = None) -> None:
+    """
+    Tracks the max k elements using a heap.
+
+    We use a min-heap for this task. When a new element comes in, we compare it
+    to the smallest node in the heap, h[0]. If the new value is greater than
+    h[0], we pop h[0] and add the new element in.
+
+    Args:
+        h: list, either empty [] or already heapified
+        item: HeapItem
+        k: int, desired capacity of the heap, or None for no limit
+    """
+    
+    if k is None or len(h) < k:
+        heapq.heappush(h, item)
+    else:
+        heapq.heappushpop(h, item)
+
+
+#%% Functions
+
+def prefix_all_keys(d: Mapping[str, Any], prefix: str) -> dict[str, Any]:
+    """
+    Returns a new dict where the keys are prefixed by <prefix>.
+    """
+    
+    return {f'{prefix}{k}': v for k, v in d.items()}
+
+
+def fig_to_img(fig: matplotlib.figure.Figure) -> np.ndarray:
+    """
+    Converts a matplotlib figure to an image represented by a numpy array.
+    
+    Returns: np.ndarray, type uint8, shape [H, W, 3]
+    """
+    
+    with io.BytesIO() as b:
+        fig.savefig(b, transparent=False, bbox_inches='tight', pad_inches=0,
+                    format='png')
+        b.seek(0)
+        fig_img = np.asarray(PIL.Image.open(b).convert('RGB'))
+    assert fig_img.dtype == np.uint8
+    return fig_img
+
+
+def imgs_with_confidences(imgs_list: list[tuple[Any, ...]],
+                          label_names: Sequence[str],
+                          ) -> tuple[matplotlib.figure.Figure, list[str]]:
+    """
+    Args:
+        imgs_list: list of tuple, each tuple consists of:
+            img: array_like, shape [H, W, C], type either float [0, 1] or uint8
+            label_id: int, label index
+            topk_conf: list of float, confidence scores for topk predictions
+            topk_preds: list of int, label indices for topk predictions
+            img_file: str, path to image file
+        label_names: list of str, label names in order of label id
+
+    Returns:
+        fig: matplotlib.figure.Figure
+        img_files: list of str
+    """
+    
+    imgs, img_files, tags, titles = [], [], [], []
+    for img, label_id, topk_conf, topk_preds, img_file in imgs_list:
+        imgs.append(img)
+        img_files.append(img_file)
+        tags.append(label_names[label_id])
+
+        lines = []
+        for pred, conf in zip(topk_preds, topk_conf):
+            pred_name = label_names[pred]
+            lines.append(f'{pred_name}: {conf:.03f}')
+        titles.append('\n'.join(lines))
+
+    fig = plot_img_grid(imgs=imgs, row_h=3, col_w=2.5, tags=tags, titles=titles)
+    return fig, img_files
+
+
+def plot_img_grid(imgs: Sequence[Any], row_h: float, col_w: float,
+                  ncols: Optional[int] = None,
+                  tags: Optional[Sequence[str]] = None,
+                  titles: Optional[Sequence[str]] = None
+                  ) -> matplotlib.figure.Figure:
+    """
+    Plots a grid of images.
+
+    Args:
+        imgs: list of images, each image is either an array or a PIL Image,
+            see matplotlib.axes.Axes.imshow() documentation for supported shapes
+        row_h: float, row height in inches
+        col_w: float, col width in inches
+        ncols: optional int, number of columns, defaults to len(imgs)
+        tags: optional list of str, tags are displayed in upper-left corner of
+            each image on a white background
+        titles: optional list of str, text displayed above each image
+
+    Returns: matplotlib.figure.Figure
+    """
+    
+    # input validation
+    num_images = len(imgs)
+    if tags is not None:
+        assert len(tags) == len(imgs)
+    if titles is not None:
+        assert len(titles) == len(imgs)
+
+    if ncols is None:
+        ncols = num_images
+
+    nrows = int(np.ceil(len(imgs) / ncols))
+    fig = matplotlib.figure.Figure(figsize=(ncols * col_w, nrows * row_h),
+                                   tight_layout=True)
+    axs = fig.subplots(nrows, ncols, squeeze=False)
+
+    # plot the images
+    for i in range(num_images):
+        r, c = i // ncols, i % ncols
+        ax = axs[r, c]
+        ax.imshow(imgs[i])
+        if tags is not None:
+            ax.text(-0.2, -0.2, tags[i], ha='left', va='top',
+                    bbox=dict(lw=0, facecolor='white'))
+        if titles is not None:
+            ax.set_title(titles[i])
+
+    # adjust the figure
+    for r in range(nrows):
+        for c in range(ncols):
+            axs[r, c].set_axis_off()
+            axs[r, c].set_aspect('equal')
+    fig.subplots_adjust(wspace=0, hspace=0)
+    return fig
+
+
+def load_splits(splits_json_path: str) -> dict[str, set[tuple[str, str]]]:
+    """
+    Loads location splits from JSON file and assert that there are no
+    overlaps between splits.
+
+    Args:
+        splits_json_path: str, path to JSON file
+
+    Returns: dict, maps split to set of (dataset, location) tuples
+    """
+    
+    with open(splits_json_path, 'r') as f:
+        split_to_locs_js = json.load(f)
+    split_to_locs = {
+        split: set((loc[0], loc[1]) for loc in locs)
+        for split, locs in split_to_locs_js.items()
+    }
+    assert split_to_locs['train'].isdisjoint(split_to_locs['val'])
+    assert split_to_locs['train'].isdisjoint(split_to_locs['test'])
+    assert split_to_locs['val'].isdisjoint(split_to_locs['test'])
+    return split_to_locs
+
+
+def load_dataset_csv(dataset_csv_path: str,
+                     label_index_json_path: str,
+                     splits_json_path: str,
+                     multilabel: bool,
+                     weight_by_detection_conf: bool | str,
+                     label_weighted: bool
+                     ) -> tuple[pd.DataFrame,
+                                list[str],
+                                dict[str, set[tuple[str, str]]]
+                               ]:
+    """
+    Args:
+        dataset_csv_path: str, path to CSV file with columns
+            ['dataset', 'location', 'label', 'confidence'], where label is a
+            comma-delimited list of labels
+        label_index_json_path: str, path to label index JSON file
+        splits_json_path: str, path to splits JSON file
+        multilabel: bool, whether a single example can have multiple labels
+        weight_by_detection_conf: bool or str
+            - if True: assumes classification CSV's 'confidence' column
+                represents calibrated scores
+            - if str: path the .npz file containing x/y values for isotonic
+                regression calibration function
+        label_weighted: bool, whether to give each label equal weight
+
+    Returns:
+        df: pd.DataFrame, with columns
+            dataset_location: tuples of (dataset, location)
+            label: str if not multilabel, list of str if multilabel
+            label_index: int if not multilabel, list of int if multilabel
+            weights: float, weight for each example
+                column exists if and only if label_weighted=True or
+                weight_by_detection_conf is not False
+        label_names: list of str, label names in order of label id
+        split_to_locs: dict, maps split to set of (dataset, location) tuples
+    """
+    
+    # read in dataset CSV and create merged (dataset, location) col
+    df = pd.read_csv(dataset_csv_path, index_col=False, float_precision='high')
+    df['dataset_location'] = list(zip(df['dataset'], df['location']))
+
+    with open(label_index_json_path, 'r') as f:
+        idx_to_label = json.load(f)
+    label_names = [idx_to_label[str(i)] for i in range(len(idx_to_label))]
+    label_to_idx = {label: idx for idx, label in enumerate(label_names)}
+
+    # map label to label_index
+    if multilabel:
+        df['label'] = df['label'].map(lambda x: x.split(','))
+        df['label_index'] = df['label'].map(
+            lambda labellist: tuple(sorted(label_to_idx[y] for y in labellist)))
+    else:
+        assert not any(df['label'].str.contains(','))
+        df['label_index'] = df['label'].map(label_to_idx.__getitem__)
+
+    # load the splits
+    split_to_locs = load_splits(splits_json_path)
+
+    if weight_by_detection_conf:
+        df['weights'] = 1.0
+
+        # only weight the training set by detection confidence
+        train_mask = df['dataset_location'].isin(split_to_locs['train'])
+        df.loc[train_mask, 'weights'] = df.loc[train_mask, 'confidence']
+
+        if isinstance(weight_by_detection_conf, str):
+            # isotonic regression calibration of MegaDetector confidence
+            with np.load(weight_by_detection_conf) as npz:
+                calib = scipy.interpolate.interp1d(
+                    x=npz['x'], y=npz['y'], kind='linear')
+            df.loc[train_mask, 'weights'] = calib(df.loc[train_mask, 'weights'])
+
+    if label_weighted:
+        if multilabel:
+            raise NotImplementedError
+
+        if 'weights' not in df.columns:
+            df['weights'] = 1.0
+
+        # treat each split separately
+        # new_weight[i] = confidence[i] * (n / c) / total_confidence(i's label)
+        # - n = # examples in split (weighted by confidence); c = # labels
+        # - weight allocated to each label is n/c
+        # - within each label, weigh each example proportional to confidence
+        # - new weights sum to n
+        c = len(label_names)
+        for split, locs in split_to_locs.items():
+            split_mask = df['dataset_location'].isin(locs)
+            n = df.loc[split_mask, 'weights'].sum()
+            per_label_conf = df[split_mask].groupby('label')['weights'].sum()
+            assert len(per_label_conf) == c, (
+                f'{split} split only has {len(per_label_conf)}/{c} labels')
+            scaling = (n / c) / per_label_conf[df.loc[split_mask, 'label']]
+            df.loc[split_mask, 'weights'] *= scaling.to_numpy()
+            w_sum = df.loc[split_mask, 'weights'].sum()
+            assert np.isclose(w_sum, n), (
+                f'Expected {split} weights to sum to {n}, got {w_sum} instead')
+
+        # error checking
+        assert (df['weights'] > 0).all()
+
+    return df, label_names, split_to_locs
+
+
+def recall_from_confusion_matrix(
+        confusion_matrix: np.ndarray,
+        label_names: Sequence[str],
+        ) -> dict[str, float]:
+    """
+    Args:
+        confusion_matrix: np.ndarray, shape [n_classes, n_classes], type int
+            C[i, j] = # of samples with true label i, predicted as label j
+        label_names: list of str, label names in order by label id
+
+    Returns: dict, label_name => recall
+    """
+    
+    result = {
+        label_name: confusion_matrix[i, i] / (confusion_matrix[i].sum() + 1e-8)
+        for i, label_name in enumerate(label_names)
+    }
+    return result

megadetector/data_management/annotations/annotation_constants.py

@@ -0,0 +1,34 @@
+"""
+
+annotation_constants.py
+
+Defines default categories for MegaDetector output boxes.
+
+Used throughout the repo; do not change unless you are Dan or Siyu.  In fact, do not change unless 
+you are both Dan *and* Siyu.
+
+We use integer IDs here; this is different from the MD .json file format,
+where indices are string integers.
+
+"""
+
+#%% Constants
+
+# MegaDetector output categories (the "empty" category is implicit)
+detector_bbox_categories = [
+    {'id': 0, 'name': 'empty'},
+    {'id': 1, 'name': 'animal'},
+    {'id': 2, 'name': 'person'},
+    {'id': 3, 'name': 'vehicle'}
+]
+
+# This is used for choosing colors, so it ignores the "empty" class.
+NUM_DETECTOR_CATEGORIES = len(detector_bbox_categories) - 1
+
+detector_bbox_category_id_to_name = {}
+detector_bbox_category_name_to_id = {}
+
+for cat in detector_bbox_categories:
+    detector_bbox_category_id_to_name[cat['id']] = cat['name']
+    detector_bbox_category_name_to_id[cat['name']] = cat['id']
+

megadetector/data_management/camtrap_dp_to_coco.py

@@ -0,0 +1,239 @@
+"""
+
+camtrap_dp_to_coco.py
+
+Parse a very limited subset of the Camtrap DP data package format:
+
+https://camtrap-dp.tdwg.org/
+
+...and convert to COCO format.  Assumes that all required metadata files have been
+put in the same directory (which is standard).
+
+Does not currently parse bounding boxes, just attaches species labels to images.
+
+Currently supports only sequence-level labeling.
+
+"""
+
+#%% Imports and constants
+
+import os
+import json
+import pandas as pd
+
+from dateutil import parser as dateparser
+
+from collections import defaultdict
+
+
+#%% Functions
+
+def camtrap_dp_to_coco(camtrap_dp_folder,output_file=None):
+    """
+    Convert the Camtrap DP package in [camtrap_dp_folder] to COCO.
+    
+    Does not validate images, just converts.  Use integrity_check_json_db to validate
+    the resulting COCO file.  
+    
+    Optionally writes the results to [output_file]
+    """
+    
+    required_files = ('datapackage.json','deployments.csv','events.csv','media.csv','observations.csv')
+    
+    for fn in required_files:
+        fn_abs = os.path.join(camtrap_dp_folder,fn)
+        assert os.path.isfile(fn_abs), 'Could not find required file {}'.format(fn_abs)
+        
+    with open(os.path.join(camtrap_dp_folder,'datapackage.json'),'r') as f:
+        datapackage = json.load(f)
+        
+    assert datapackage['profile'] == 'https://raw.githubusercontent.com/tdwg/camtrap-dp/1.0/camtrap-dp-profile.json', \
+        'I only know how to parse Camtrap DP 1.0 packages'
+
+    deployments_file = None
+    events_file = None
+    media_file = None
+    observations_file = None
+    
+    resources = datapackage['resources']
+    for r in resources:
+        if r['name'] == 'deployments':
+            deployments_file = r['path']
+        elif r['name'] == 'media':
+            media_file = r['path']
+        elif r['name'] == 'events':
+            events_file = r['path']
+        elif r['name'] == 'observations':
+            observations_file = r['path']
+
+    assert deployments_file is not None, 'No deployment file specified'
+    assert events_file is not None, 'No events file specified'
+    assert media_file is not None, 'No media file specified'
+    assert observations_file is not None, 'No observation file specified'
+    
+    deployments_df = pd.read_csv(os.path.join(camtrap_dp_folder,deployments_file))
+    events_df = pd.read_csv(os.path.join(camtrap_dp_folder,events_file))
+    media_df = pd.read_csv(os.path.join(camtrap_dp_folder,media_file))
+    observations_df = pd.read_csv(os.path.join(camtrap_dp_folder,observations_file))
+    
+    print('Read {} deployment lines'.format(len(deployments_df)))
+    print('Read {} events lines'.format(len(events_df)))
+    print('Read {} media lines'.format(len(media_df)))
+    print('Read {} observation lines'.format(len(observations_df)))
+    
+    media_id_to_media_info = {}
+    
+    # i_row = 0; row = media_df.iloc[i_row]
+    for i_row,row in media_df.iterrows():
+        media_info = {}
+        media_info['file_name'] = os.path.join(row['filePath'],row['fileName']).replace('\\','/')
+        media_info['location'] = row['deploymentID']
+        media_info['id'] = row['mediaID']
+        media_info['datetime'] = row['timestamp']
+        media_info['datetime'] = dateparser.parse(media_info['datetime'])
+        media_info['frame_num'] = -1
+        media_info['seq_num_frames'] = -1
+        media_id_to_media_info[row['mediaID']] = media_info
+        
+    event_id_to_media_ids = defaultdict(list)
+    
+    # i_row = 0; row = events_df.iloc[i_row]
+    for i_row,row in events_df.iterrows():
+        media_id = row['mediaID']
+        assert media_id in media_id_to_media_info
+        event_id_to_media_ids[row['eventID']].append(media_id)
+    
+    event_id_to_category_names = defaultdict(set)
+    
+    # i_row = 0; row = observations_df.iloc[i_row]
+    for i_row,row in observations_df.iterrows():
+        
+        if row['observationLevel'] != 'event':
+            raise ValueError("I don't know how to parse image-level events yet")
+            
+        if row['observationType'] == 'blank':
+            event_id_to_category_names[row['eventID']].add('empty')
+        elif row['observationType'] == 'unknown':
+            event_id_to_category_names[row['eventID']].add('unknown')
+        elif row['observationType'] == 'human':
+            assert row['scientificName'] == 'Homo sapiens'
+            event_id_to_category_names[row['eventID']].add(row['scientificName'])
+        else:
+            assert row['observationType'] == 'animal'
+            assert isinstance(row['scientificName'],str)
+            event_id_to_category_names[row['eventID']].add(row['scientificName'])
+    
+    # Sort images within an event into frame numbers
+    #
+    # event_id = next(iter(event_id_to_media_ids))
+    for event_id in event_id_to_media_ids.keys():
+        media_ids_this_event = event_id_to_media_ids[event_id]
+        media_info_this_event = [media_id_to_media_info[media_id] for media_id in media_ids_this_event]
+        media_info_this_event = sorted(media_info_this_event, key=lambda x: x['datetime'])
+        for i_media,media_info in enumerate(media_info_this_event):
+            media_info['frame_num'] = i_media
+            media_info['seq_num_frames'] = len(media_info_this_event)
+            media_info['seq_id'] = event_id
+            
+    # Create category names
+    category_name_to_category_id = {'empty':0}
+    for event_id in event_id_to_category_names:
+        category_names_this_event = event_id_to_category_names[event_id]
+        for name in category_names_this_event:
+            if name not in category_name_to_category_id:
+                category_name_to_category_id[name] = len(category_name_to_category_id)
+    
+    # Move everything into COCO format
+    images = list(media_id_to_media_info.values())
+    
+    categories = []
+    for name in category_name_to_category_id:
+        categories.append({'name':name,'id':category_name_to_category_id[name]})
+    info = {'version':1.0,'description':datapackage['name']}
+    
+    # Create annotations
+    annotations = []
+    
+    for event_id in event_id_to_media_ids.keys():
+        i_ann = 0
+        media_ids_this_event = event_id_to_media_ids[event_id]
+        media_info_this_event = [media_id_to_media_info[media_id] for media_id in media_ids_this_event]
+        categories_this_event = event_id_to_category_names[event_id]
+        for im in media_info_this_event:
+            for category_name in categories_this_event:
+                ann = {}
+                ann['id'] = event_id + '_' + str(i_ann)
+                i_ann += 1
+                ann['image_id'] = im['id']
+                ann['category_id'] = category_name_to_category_id[category_name]
+                ann['sequence_level_annotation'] = True
+                annotations.append(ann)
+    
+    coco_data = {}
+    coco_data['images'] = images
+    coco_data['annotations'] = annotations
+    coco_data['categories'] = categories
+    coco_data['info'] = info
+    
+    for im in coco_data['images']:
+        im['datetime'] = str(im['datetime'] )
+        
+    if output_file is not None:
+        with open(output_file,'w') as f:
+            json.dump(coco_data,f,indent=1)
+    
+    return coco_data
+            
+    
+#%% Interactive driver
+
+if False:
+
+    pass
+
+    #%%
+    
+    camtrap_dp_folder = r'C:\temp\pilot2\pilot2'
+    coco_file = os.path.join(camtrap_dp_folder,'test-coco.json')
+    coco_data = camtrap_dp_to_coco(camtrap_dp_folder,
+                                   output_file=coco_file)
+    
+    #%% Validate
+    
+    from megadetector.data_management.databases.integrity_check_json_db import \
+        integrity_check_json_db, IntegrityCheckOptions
+    
+    options = IntegrityCheckOptions()
+    
+    options.baseDir = camtrap_dp_folder
+    options.bCheckImageSizes = False
+    options.bCheckImageExistence = True
+    options.bFindUnusedImages = True
+    options.bRequireLocation = True
+    options.iMaxNumImages = -1
+    options.nThreads = 1
+    options.verbose = True
+    
+    sortedCategories, data, errorInfo = integrity_check_json_db(coco_file,options)
+
+    #%% Preview
+    
+    from megadetector.visualization.visualize_db import DbVizOptions, visualize_db
+    
+    options = DbVizOptions()
+    options.parallelize_rendering = True
+    options.parallelize_rendering_with_threads = True
+    options.parallelize_rendering_n_cores = 10
+    
+    preview_dir = r'c:\temp\camtrapdp-preview'
+    htmlOutputFile,image_db = visualize_db(coco_file, preview_dir, camtrap_dp_folder, options=options)
+    
+    from megadetector.utils.path_utils import open_file
+    open_file(htmlOutputFile)
+    
+    
+#%% Command-line driver
+
+# TODO
+
+