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

classification/crop_detections.py

@@ -1,58 +1,43 @@
-########
-#
-# crop_detections.py
-#
-# Given a detections JSON file from MegaDetector, crops the bounding boxes above
-# a certain confidence threshold.
-# 
-# This script takes as input a detections JSON file, usually the output of
-# detection/run_tf_detector_batch.py or the output of the Batch API in the
-# "Batch processing API output format".
-# 
-# See https://github.com/agentmorris/MegaDetector/tree/master/api/batch_processing.
-# 
-# The script can crop images that are either available locally or that need to be
-# downloaded from an Azure Blob Storage container.
-# 
-# We assume that no image contains over 100 bounding boxes, and we always save
-# crops as RGB .jpg files for consistency. For each image, each bounding box is
-# cropped and saved to a file with a suffix "___cropXX_mdvY.Y.jpg" added to the
-# filename as the original image. "XX" ranges from "00" to "99" and "Y.Y"
-# ndicates the MegaDetector version. Based on the given confidence threshold, we
-# may skip saving certain bounding box crops, but we still increment the bounding
-# box number for skipped boxes.
-# 
-# Example cropped image path (with MegaDetector bbox):
-#
-#   "path/to/image.jpg___crop00_mdv4.1.jpg"
-# 
-# By default, the images are cropped exactly per the given bounding box
-# coordinates. However, if square crops are desired, pass the --square-crops
-# flag. This will always generate a square crop whose size is the larger of the
-# bounding box width or height. In the case that the square crop boundaries exceed
-# the original image size, the crop is padded with 0s.
-# 
-# This script outputs a log file to:
-#    
-#    <output_dir>/crop_detections_log_{timestamp}.json
-#
-# ...which contains images that failed to download and crop properly.
-# 
-########
+"""
 
-#%% Example usage
+crop_detections.py
+
+Given a detections JSON file from MegaDetector, crops the bounding boxes above
+a certain confidence threshold.
+
+This script takes as input a detections JSON file, usually the output of
+detection/run_tf_detector_batch.py or the output of the Batch API in the
+"Batch processing API output format".
+
+See https://github.com/agentmorris/MegaDetector/tree/master/api/batch_processing.
+
+The script can crop images that are either available locally or that need to be
+downloaded from an Azure Blob Storage container.
+
+We assume that no image contains over 100 bounding boxes, and we always save
+crops as RGB .jpg files for consistency. For each image, each bounding box is
+cropped and saved to a file with a suffix "___cropXX_mdvY.Y.jpg" added to the
+filename as the original image. "XX" ranges from "00" to "99" and "Y.Y"
+ndicates the MegaDetector version. Based on the given confidence threshold, we
+may skip saving certain bounding box crops, but we still increment the bounding
+box number for skipped boxes.
+
+Example cropped image path (with MegaDetector bbox):
+
+  "path/to/image.jpg___crop00_mdv4.1.jpg"
+
+By default, the images are cropped exactly per the given bounding box
+coordinates. However, if square crops are desired, pass the --square-crops
+flag. This will always generate a square crop whose size is the larger of the
+bounding box width or height. In the case that the square crop boundaries exceed
+the original image size, the crop is padded with 0s.
+
+This script outputs a log file to:
+   
+   <output_dir>/crop_detections_log_{timestamp}.json
+
+...which contains images that failed to download and crop properly.
 
-"""
-python crop_detections.py \
-    detections.json \
-    /path/to/crops \
-    --images-dir /path/to/images \
-    --container-url "https://account.blob.core.windows.net/container?sastoken" \
-    --detector-version "4.1" \
-    --threshold 0.8 \
-    --save-full-images --square-crops \
-    --threads 50 \
-    --logdir "."
 """
 
 #%% Imports
@@ -73,6 +58,22 @@ from PIL import Image, ImageOps
 from tqdm import tqdm
 
 
+#%% Example usage
+
+"""
+python crop_detections.py \
+    detections.json \
+    /path/to/crops \
+    --images-dir /path/to/images \
+    --container-url "https://account.blob.core.windows.net/container?sastoken" \
+    --detector-version "4.1" \
+    --threshold 0.8 \
+    --save-full-images --square-crops \
+    --threads 50 \
+    --logdir "."
+"""
+
+
 #%% Main function
 
 def main(detections_json_path: str,

classification/csv_to_json.py

@@ -1,105 +1,101 @@
-########
-#
-# csv_to_json.py
-#
-# Converts CSV to JSON format for label specification.
-# 
-# There are 3 possible values for the 'type' column in the CSV:
-#
-# - "row": this selects a specific rowfrom the master taxonomy CSV
-#     content syntax: <dataset_name>|<dataset_label>
-#
-# - "datasettaxon": this selects all animals in a taxon from a particular dataset
-#     content syntax: <dataset_name>|<taxon_level>|<taxon_name>
-#
-# - <taxon_level>: this selects all animals in a taxon across all datasets
-#     content syntax: <taxon_name>
-# 
-# Example CSV input:
-#
-"""   
-    # comment lines starting with '#' are allowed
-    output_label,type,content
-
-    cervid,row,idfg|deer
-    cervid,row,idfg|elk
-    cervid,row,idfg|prong
-    cervid,row,idfg_swwlf_2019|elk
-    cervid,row,idfg_swwlf_2019|muledeer
-    cervid,row,idfg_swwlf_2019|whitetaileddeer
-    cervid,max_count,50000
-
-    cervid,family,cervidae
-    cervid,datasettaxon,idfg|family|cervidae
-    cervid,datasettaxon,idfg_swwlf_2019|family|cervidae
-
-    bird,row,idfg_swwlf_2019|bird
-    bird,class,aves
-    bird,max_count,50000
-    bird,prioritize,"[['idfg_swwlf_2019'], ['idfg']]"
-
-    !bird,row,idfg_swwlf_2019|turkey
-    !bird,genus,meleagris
 """
-#
-# Example JSON output:
-#
-"""    
-    {
-        "cervid": {
-            "dataset_labels": {
-                "idfg": ["deer", "elk", "prong"],
-                "idfg_swwlf_2019": ["elk", "muledeer", "whitetaileddeer"]
-            },
-            "taxa": [
-                {
-                    "level": "family",
-                    "name": "cervidae"
-                },
-                {
-                    "level": "family",
-                    "name": "cervidae"
-                    "datasets": ["idfg"]
-                },
-                {
-                    "level": "family",
-                    "name": "cervidae"
-                    "datasets": ["idfg_swwlf_2019"]
-                }
-            ],
-            "max_count": 50000
-        },
-        "bird": {
-            "dataset_labels": {
-                "idfg_swwlf_2019": ["bird"]
-            },
-            "taxa": [
-                {
-                    "level": "class",
-                    "name": "aves"
-                }
-            ],
-            "exclude": {
-                "dataset_labels": {
-                    "idfg_swwlf_2019": ["turkey"]
-                },
-                "taxa": [
-                    {
-                        "level": "genus",
-                        "name": "meleagris"
-                    }
-                ]
-            },
-            "max_count": "50000",
-            "prioritize": [
-                ["idfg_swwlf_2019"],
-                ["idfg"]
-            ],
-        }
-    }
+
+csv_to_json.py
+
+Converts CSV to JSON format for label specification.
+
+There are 3 possible values for the 'type' column in the CSV:
+
+- "row": this selects a specific rowfrom the master taxonomy CSV
+    content syntax: <dataset_name>|<dataset_label>
+
+- "datasettaxon": this selects all animals in a taxon from a particular dataset
+    content syntax: <dataset_name>|<taxon_level>|<taxon_name>
+
+- <taxon_level>: this selects all animals in a taxon across all datasets
+    content syntax: <taxon_name>
+
+Example CSV input:
+
+"
+  # comment lines starting with '#' are allowed
+  output_label,type,content
+  cervid,row,idfg|deer
+  cervid,row,idfg|elk
+  cervid,row,idfg|prong
+  cervid,row,idfg_swwlf_2019|elk
+  cervid,row,idfg_swwlf_2019|muledeer
+  cervid,row,idfg_swwlf_2019|whitetaileddeer
+  cervid,max_count,50000
+  cervid,family,cervidae
+  cervid,datasettaxon,idfg|family|cervidae
+  cervid,datasettaxon,idfg_swwlf_2019|family|cervidae
+  bird,row,idfg_swwlf_2019|bird
+  bird,class,aves
+  bird,max_count,50000
+  bird,prioritize,"[['idfg_swwlf_2019'], ['idfg']]"
+  !bird,row,idfg_swwlf_2019|turkey
+  !bird,genus,meleagris
+"
+
+Example JSON output:
+
+"    
+  {
+      "cervid": {
+          "dataset_labels": {
+              "idfg": ["deer", "elk", "prong"],
+              "idfg_swwlf_2019": ["elk", "muledeer", "whitetaileddeer"]
+          },
+          "taxa": [
+              {
+                  "level": "family",
+                  "name": "cervidae"
+              },
+              {
+                  "level": "family",
+                  "name": "cervidae"
+                  "datasets": ["idfg"]
+              },
+              {
+                  "level": "family",
+                  "name": "cervidae"
+                  "datasets": ["idfg_swwlf_2019"]
+              }
+          ],
+          "max_count": 50000
+      },
+      "bird": {
+          "dataset_labels": {
+              "idfg_swwlf_2019": ["bird"]
+          },
+          "taxa": [
+              {
+                  "level": "class",
+                  "name": "aves"
+              }
+          ],
+          "exclude": {
+              "dataset_labels": {
+                  "idfg_swwlf_2019": ["turkey"]
+              },
+              "taxa": [
+                  {
+                      "level": "genus",
+                      "name": "meleagris"
+                  }
+              ]
+          },
+          "max_count": "50000",
+          "prioritize": [
+              ["idfg_swwlf_2019"],
+              ["idfg"]
+          ],
+      }
+  }
+"
+
 """
-#
-########
 
 #%% Imports
 
@@ -125,6 +121,7 @@ def main():
 
 
 #%% Support functions
+
 def parse_csv_row(obj: dict[str, Any], rowtype: str, content: str) -> None:
     """
     Parses a row in the CSV.

classification/detect_and_crop.py

@@ -1,111 +1,97 @@
-########
-#
-# detect_and_crop.py
-#
-# Run MegaDetector on images via Batch API, then save crops of the detected
-# bounding boxes.
-# 
-# The input to this script is a "queried images" JSON file, whose keys are paths
-# to images and values are dicts containing information relevant for training
-# a classifier, including labels and (optionally) ground-truth bounding boxes.
-# The image paths are in the format `<dataset-name>/<blob-name>` where we assume
-# that the dataset name does not contain '/'.
-# 
-# {
-#     "caltech/cct_images/59f79901-23d2-11e8-a6a3-ec086b02610b.jpg": {
-#         "dataset": "caltech",
-#         "location": 13,
-#         "class": "mountain_lion",  # class from dataset
-#         "bbox": [{"category": "animal",
-#                   "bbox": [0, 0.347, 0.237, 0.257]}],   # ground-truth bbox
-#         "label": ["monutain_lion"]  # labels to use in classifier
-#     },
-#     "caltech/cct_images/59f5fe2b-23d2-11e8-a6a3-ec086b02610b.jpg": {
-#         "dataset": "caltech",
-#         "location": 13,
-#         "class": "mountain_lion",  # class from dataset
-#         "label": ["monutain_lion"]  # labels to use in classifier
-#     },
-#     ...
-# }
-# 
-# We assume that no image contains over 100 bounding boxes, and we always save
-# crops as RGB .jpg files for consistency. For each image, each bounding box is
-# cropped and saved to a file with a suffix "___cropXX.jpg" (ground truth bbox) or
-# "___cropXX_mdvY.Y.jpg" (detected bbox) added to the filename of the original
-# image. "XX" ranges from "00" to "99" and "Y.Y" indicates the MegaDetector
-# version. If an image has ground truth bounding boxes, we assume that they are
-# exhaustive--i.e., there are no other objects of interest, so we don't need to
-# run MegaDetector on the image. If an image does not have ground truth bounding
-# boxes, we run MegaDetector on the image and label the detected boxes in order
-# from 00 up to 99. Based on the given confidence threshold, we may skip saving
-# certain bounding box crops, but we still increment the bounding box number for
-# skipped boxes.
-# 
-# Example cropped image path (with ground truth bbox from MegaDB)
-#
-#     "path/to/crops/image.jpg___crop00.jpg"
-#
-# Example cropped image path (with MegaDetector bbox)
-#
-#     "path/to/crops/image.jpg___crop00_mdv4.1.jpg"
-# 
-# By default, the images are cropped exactly per the given bounding box
-# coordinates. However, if square crops are desired, pass the --square-crops
-# flag. This will always generate a square crop whose size is the larger of the
-# bounding box width or height. In the case that the square crop boundaries exceed
-# the original image size, the crop is padded with 0s.
-# 
-# This script currently only supports running MegaDetector via the Batch Detection
-# API. See the classification README for instructions on running MegaDetector
-# locally. If running the Batch Detection API, set the following environment
-# variables for the Azure Blob Storage container in which we save the intermediate
-# task lists:
-# 
-#     BATCH_DETECTION_API_URL                  # API URL
-#     CLASSIFICATION_BLOB_STORAGE_ACCOUNT      # storage account name
-#     CLASSIFICATION_BLOB_CONTAINER            # container name
-#     CLASSIFICATION_BLOB_CONTAINER_WRITE_SAS  # SAS token, without leading '?'
-#     DETECTION_API_CALLER                     # allow-listed API caller
-# 
-# This script allows specifying a directory where MegaDetector outputs are cached
-# via the --detector-output-cache-dir argument. This directory must be
-# organized as:
-#
-#   <cache-dir>/<MegaDetector-version>/<dataset-name>.json
-# 
-#     Example: If the `cameratrapssc/classifier-training` Azure blob storage
-#     container is mounted to the local machine via blobfuse, it may be used as
-#     a MegaDetector output cache directory by passing
-#         "cameratrapssc/classifier-training/mdcache/"
-#     as the value for --detector-output-cache-dir.
-# 
-# This script outputs either 1 or 3 files, depending on whether the Batch Detection API
-# is run:
-# 
-# - <output_dir>/detect_and_crop_log_{timestamp}.json
-#     log of images missing detections and images that failed to properly
-#     download and crop
-# - <output_dir>/batchapi_tasklists/{task_id}.json
-#     (if --run-detector) task lists uploaded to the Batch Detection API
-# - <output_dir>/batchapi_response/{task_id}.json
-#     (if --run-detector) task status responses for completed tasks
-# 
-########
+"""
 
-#%% Example usage
+detect_and_crop.py
+
+Run MegaDetector on images via Batch API, then save crops of the detected
+bounding boxes.
+
+The input to this script is a "queried images" JSON file, whose keys are paths
+to images and values are dicts containing information relevant for training
+a classifier, including labels and (optionally) ground-truth bounding boxes.
+The image paths are in the format `<dataset-name>/<blob-name>` where we assume
+that the dataset name does not contain '/'.
+
+{
+    "caltech/cct_images/59f79901-23d2-11e8-a6a3-ec086b02610b.jpg": {
+        "dataset": "caltech",
+        "location": 13,
+        "class": "mountain_lion",  # class from dataset
+        "bbox": [{"category": "animal",
+                  "bbox": [0, 0.347, 0.237, 0.257]}],   # ground-truth bbox
+        "label": ["monutain_lion"]  # labels to use in classifier
+    },
+    "caltech/cct_images/59f5fe2b-23d2-11e8-a6a3-ec086b02610b.jpg": {
+        "dataset": "caltech",
+        "location": 13,
+        "class": "mountain_lion",  # class from dataset
+        "label": ["monutain_lion"]  # labels to use in classifier
+    },
+    ...
+}
+
+We assume that no image contains over 100 bounding boxes, and we always save
+crops as RGB .jpg files for consistency. For each image, each bounding box is
+cropped and saved to a file with a suffix "___cropXX.jpg" (ground truth bbox) or
+"___cropXX_mdvY.Y.jpg" (detected bbox) added to the filename of the original
+image. "XX" ranges from "00" to "99" and "Y.Y" indicates the MegaDetector
+version. If an image has ground truth bounding boxes, we assume that they are
+exhaustive--i.e., there are no other objects of interest, so we don't need to
+run MegaDetector on the image. If an image does not have ground truth bounding
+boxes, we run MegaDetector on the image and label the detected boxes in order
+from 00 up to 99. Based on the given confidence threshold, we may skip saving
+certain bounding box crops, but we still increment the bounding box number for
+skipped boxes.
+
+Example cropped image path (with ground truth bbox from MegaDB)
+
+    "path/to/crops/image.jpg___crop00.jpg"
+
+Example cropped image path (with MegaDetector bbox)
+
+    "path/to/crops/image.jpg___crop00_mdv4.1.jpg"
+
+By default, the images are cropped exactly per the given bounding box
+coordinates. However, if square crops are desired, pass the --square-crops
+flag. This will always generate a square crop whose size is the larger of the
+bounding box width or height. In the case that the square crop boundaries exceed
+the original image size, the crop is padded with 0s.
+
+This script currently only supports running MegaDetector via the Batch Detection
+API. See the classification README for instructions on running MegaDetector
+locally. If running the Batch Detection API, set the following environment
+variables for the Azure Blob Storage container in which we save the intermediate
+task lists:
+
+    BATCH_DETECTION_API_URL                  # API URL
+    CLASSIFICATION_BLOB_STORAGE_ACCOUNT      # storage account name
+    CLASSIFICATION_BLOB_CONTAINER            # container name
+    CLASSIFICATION_BLOB_CONTAINER_WRITE_SAS  # SAS token, without leading '?'
+    DETECTION_API_CALLER                     # allow-listed API caller
+
+This script allows specifying a directory where MegaDetector outputs are cached
+via the --detector-output-cache-dir argument. This directory must be
+organized as:
+
+  <cache-dir>/<MegaDetector-version>/<dataset-name>.json
+
+    Example: If the `cameratrapssc/classifier-training` Azure blob storage
+    container is mounted to the local machine via blobfuse, it may be used as
+    a MegaDetector output cache directory by passing
+        "cameratrapssc/classifier-training/mdcache/"
+    as the value for --detector-output-cache-dir.
+
+This script outputs either 1 or 3 files, depending on whether the Batch Detection API
+is run:
+
+- <output_dir>/detect_and_crop_log_{timestamp}.json
+    log of images missing detections and images that failed to properly
+    download and crop
+- <output_dir>/batchapi_tasklists/{task_id}.json
+    (if --run-detector) task lists uploaded to the Batch Detection API
+- <output_dir>/batchapi_response/{task_id}.json
+    (if --run-detector) task status responses for completed tasks
 
 """
-    python detect_and_crop.py \
-        base_logdir/queried_images.json \
-        base_logdir \
-        --detector-output-cache-dir /path/to/classifier-training/mdcache \
-        --detector-version 4.1 \
-        --run-detector --resume-file base_logdir/resume.json \
-        --cropped-images-dir /path/to/crops --square-crops --threshold 0.9 \
-        --save-full-images --images-dir /path/to/images --threads 50
-"""
-
 
 #%% Imports
 
@@ -134,6 +120,20 @@ from md_utils import path_utils
 from md_utils import sas_blob_utils
 
 
+#%% Example usage
+
+"""
+    python detect_and_crop.py \
+        base_logdir/queried_images.json \
+        base_logdir \
+        --detector-output-cache-dir /path/to/classifier-training/mdcache \
+        --detector-version 4.1 \
+        --run-detector --resume-file base_logdir/resume.json \
+        --cropped-images-dir /path/to/crops --square-crops --threshold 0.9 \
+        --save-full-images --images-dir /path/to/images --threads 50
+"""
+
+
 #%% Main function
 
 def main(queried_images_json_path: str,

classification/evaluate_model.py

@@ -1,47 +1,36 @@
-########
-# 
-# evaluate_model.py
-#
-# Evaluate a species classifier.
-# 
-# Currently the implementation of multi-label multi-class classification is
-# non-functional.
-# 
-# Outputs the following files:
-# 
-# 1) outputs_{split}.csv, one file per split, contains columns:
-#     - 'path': str, path to cropped image
-#     - 'label': str
-#     - 'weight': float
-#     - [label names]: float, confidence in each label
-# 
-# 2) overall_metrics.csv, contains columns:
-#     - 'split': str
-#     - 'loss': float, mean per-example loss over entire epoch
-#     - 'acc_top{k}': float, accuracy@k over the entire epoch
-#     - 'loss_weighted' and 'acc_weighted_top{k}': float, weighted versions
-# 
-# 3) confusion_matrices.npz
-#     - keys ['train', 'val', 'test']
-#     - values are np.ndarray, confusion matrices
-# 
-# 4) label_stats.csv, per-label statistics, columns
-#     - 'split': str
-#     - 'label': str
-#     - 'precision': float
-#     - 'recall': float
-#
-########
+"""
 
-#%% Example usage
+evaluate_model.py
+
+Evaluate a species classifier.
+
+Currently the implementation of multi-label multi-class classification is
+non-functional.
+
+Outputs the following files:
+
+1) outputs_{split}.csv, one file per split, contains columns:
+    - 'path': str, path to cropped image
+    - 'label': str
+    - 'weight': float
+    - [label names]: float, confidence in each label
+
+2) overall_metrics.csv, contains columns:
+    - 'split': str
+    - 'loss': float, mean per-example loss over entire epoch
+    - 'acc_top{k}': float, accuracy@k over the entire epoch
+    - 'loss_weighted' and 'acc_weighted_top{k}': float, weighted versions
+
+3) confusion_matrices.npz
+    - keys ['train', 'val', 'test']
+    - values are np.ndarray, confusion matrices
+
+4) label_stats.csv, per-label statistics, columns
+    - 'split': str
+    - 'label': str
+    - 'precision': float
+    - 'recall': float
 
-"""
-    python evaluate_model.py \
-        $BASE_LOGDIR/$LOGDIR/params.json \
-        $BASE_LOGDIR/$LOGDIR/ckpt_XX.pt \
-        --output-dir $BASE_LOGDIR/$LOGDIR \
-        --splits train val test \
-        --batch-size 256
 """
 
 #%% Imports and constants
@@ -64,6 +53,18 @@ import tqdm
 
 from classification import efficientnet, train_classifier
 
+
+#%% Example usage
+
+"""
+    python evaluate_model.py \
+        $BASE_LOGDIR/$LOGDIR/params.json \
+        $BASE_LOGDIR/$LOGDIR/ckpt_XX.pt \
+        --output-dir $BASE_LOGDIR/$LOGDIR \
+        --splits train val test \
+        --batch-size 256
+"""
+
 SPLITS = ['train', 'val', 'test']