awc-helpers 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

awc_helpers/__init__.py

@@ -1,14 +1,22 @@
 """AWC Helpers - Wildlife detection and classification inference tools."""
 
+from importlib.metadata import version
+
 from .awc_inference import (
     DetectAndClassify,
     SpeciesClasInference,
     format_md_detections,
     load_classification_model,
 )
+from .format_utils import (
+    output_csv,
+    output_timelapse_json,
+    truncate_float,
+    truncate_float_array,
+)
 from .math_utils import crop_image, pil_to_tensor
 
-__version__ = "0.1.0"
+__version__ = version("awc_helpers")
 
 __all__ = [
     "DetectAndClassify",
@@ -17,4 +25,8 @@ __all__ = [
     "load_classification_model",
     "crop_image",
     "pil_to_tensor",
+    "output_csv",
+    "output_timelapse_json",
+    "truncate_float",
+    "truncate_float_array",
 ]

awc_helpers/awc_inference.py

@@ -26,6 +26,7 @@ from megadetector.detection import run_detector
 from typing import List, Tuple, Union
 from PIL import Image
 from .math_utils import crop_image, pil_to_tensor
+from .format_utils import output_csv, output_timelapse_json
 import logging
 
 logger = logging.getLogger(__name__)
@@ -124,7 +125,6 @@ class SpeciesClasInference:
         model: The loaded classification model.
         label_names: List of class label names.
         clas_threshold: Minimum confidence threshold for predictions.
-        pred_topn: Number of top predictions to return per image.
         prob_round: Decimal places to round probabilities.
         use_fp16: Whether to use FP16 mixed precision inference.
         resize_size: Target size for image resizing before inference.
@@ -136,14 +136,13 @@ class SpeciesClasInference:
         ...     classifier_base='tf_efficientnet_b5.ns_jft_in1k',
         ...     label_names=['cat', 'dog', 'bird']
         ... )
-        >>> results = classifier.predict_batch([(image_path, bbox)])
+        >>> results = classifier.predict_batch([(image_path, bbox_conf,bbox)])
     """
 
     def __init__(self,
                  classifier_path: str,
                  classifier_base: str,
                  label_names: List[str] = None,
-                 pred_topn: int = 1,
                  prob_round: int = 4,
                  clas_threshold: float = 0.5,
                  resize_size: int = 300,
@@ -167,7 +166,6 @@ class SpeciesClasInference:
         self.model.eval()
         
         self.clas_threshold = clas_threshold
-        self.pred_topn=pred_topn
         self.prob_round=prob_round
         self.use_fp16=use_fp16 and self.device.type=='cuda'
         self.resize_size=resize_size
@@ -197,7 +195,7 @@ class SpeciesClasInference:
             img = source.convert('RGB') if source.mode != 'RGB' else source
             return crop_image(img, bbox_norm, square_crop=True)
     
-    def _predict(self, input_tensor: torch.Tensor) -> torch.Tensor:
+    def _predict(self, input_tensor: torch.Tensor, pred_topn: int) -> torch.Tensor:
         """
         Run classification model on input tensor.
         
@@ -219,7 +217,7 @@ class SpeciesClasInference:
             # Softmax in fp32 for numerical stability
             probs = torch.nn.functional.softmax(logits.float(), dim=1)
 
-            top_probs, top_indices = torch.topk(probs, k=self.pred_topn, dim=1)
+            top_probs, top_indices = torch.topk(probs, k=pred_topn, dim=1)
             return (top_probs.cpu().numpy().round(self.prob_round),
                     top_indices.cpu().numpy())    
 
@@ -254,6 +252,7 @@ class SpeciesClasInference:
     def predict_batch(
         self,
         inputs: List[Union[Tuple[str, float, Tuple[float, float, float, float]], Tuple[Image.Image, str, float, Tuple[float, float, float, float]]]],
+        pred_topn: int = 1,
         batch_size: int = 1,
     ) -> List[Tuple]:
         """
@@ -262,7 +261,6 @@ class SpeciesClasInference:
         Args:
             inputs: List of (img_path, bbox_confidence, bbox) tuples, or (PIL Image, id, bbox_confidence, bbox) tuples for streaming 
             pred_topn: Number of top predictions to return
-            prob_round: Decimal places to round probabilities
             batch_size: Number of images to process at once
             
         Returns:
@@ -296,7 +294,7 @@ class SpeciesClasInference:
             
             # Stack and run inference
             batch_tensor = torch.cat(batch_tensors, dim=0)
-            top_probs, top_indices = self._predict(batch_tensor)
+            top_probs, top_indices = self._predict(batch_tensor, pred_topn=pred_topn)
             
             for i, (identifier, bbox_conf, bbox) in enumerate(batch_metadata):
                 result = self._format_output(
@@ -337,7 +335,6 @@ class DetectAndClassify:
                  classifier_base: str = 'tf_efficientnet_b5.ns_jft_in1k',
                  detection_threshold: float = 0.1,
                  clas_threshold: float = 0.5,
-                 pred_topn: int = 1,
                  resize_size: int = 300,
                  force_cpu: bool = False,
                  skip_clas_errors: bool = True):
@@ -351,7 +348,6 @@ class DetectAndClassify:
             classifier_base: Name of the base timm model architecture.
             detection_threshold: Minimum confidence for animal detections.
             clas_threshold: Minimum confidence for classification predictions.
-            pred_topn: Number of top classification predictions to return.
             resize_size: Target image size for classification model input.
             force_cpu: If True, use CPU even if CUDA is available.
             skip_clas_errors: If True, skip classification errors instead of raising.
@@ -362,7 +358,6 @@ class DetectAndClassify:
                                                    classifier_base=classifier_base,
                                                    clas_threshold=clas_threshold,
                                                    label_names=label_names,
-                                                   pred_topn=pred_topn,
                                                    resize_size=resize_size,
                                                    force_cpu=force_cpu,
                                                    skip_errors=skip_clas_errors)
@@ -410,7 +405,9 @@ class DetectAndClassify:
         self,
         inp: Union[str, Image.Image, List[Union[str, Image.Image]]],
         identifier: Union[str, List[str], None] = None,
-        clas_bs: int = 4
+        clas_bs: int = 4,
+        topn: int = 1,
+        output_name: str = None,
     ) -> List[Tuple]:
         """
         Run detection and classification on input images.
@@ -424,11 +421,14 @@ class DetectAndClassify:
             identifier: Optional identifier(s) for tracking results back to
                 source images. If None, uses file paths or timestamps.
             clas_bs: Batch size for classification inference.
-
+            topn: Number of top classification predictions to return.
+            output_name: Optional name for saving results (CSV and Timelapse's JSON) instead of returning it.
         Returns:
             List of result tuples, one per detected animal. Each tuple contains:
-            (identifier, bbox, label1, prob1, label2, prob2, ...) where the
-            number of label/prob pairs depends on pred_topn and clas_threshold.
+            (identifier, bbox_conf, bbox, label1, prob1, label2, prob2, ...) where the
+            number of label/prob pairs depends on topn and clas_threshold.
+
+            If output_name is provided, results are saved to file, no results returned.
         """
         inp, identifier = self._validate_input(inp, identifier)
         if len(inp) == 0:
@@ -438,7 +438,11 @@ class DetectAndClassify:
         for item,id in zip(inp, identifier):
             img = item
             if isinstance(item,str):
-                img = Image.open(item)
+                try:
+                    img = Image.open(item)
+                except Exception as e:
+                    logger.warning(f"Failed to open image {item}: {e}")
+                    continue
             try:
                 md_result = self.md_detector.generate_detections_one_image(img,id,
                                                     detection_threshold=self.detection_threshold)
@@ -449,4 +453,11 @@ class DetectAndClassify:
                 if isinstance(item,str):
                     img.close()
 
-        return self.clas_inference.predict_batch(md_results, batch_size=clas_bs)
+        clas_results =  self.clas_inference.predict_batch(md_results, pred_topn=topn, batch_size=clas_bs)
+        if output_name is None:
+            return clas_results
+        
+        output_csv(clas_results, output_name)
+        output_timelapse_json(clas_results, output_name, self.clas_inference.label_names)
+    
+        

awc_helpers/format_utils.py

@@ -0,0 +1,149 @@
+import csv
+import json
+import math
+from datetime import datetime
+from typing import List, Tuple, Dict, Any
+from collections import OrderedDict
+
+
+def truncate_float(x: float, precision: int = 3) -> float:
+    """
+    Truncates the fractional portion of a floating-point value to a specific number of
+    floating-point digits.
+    Source: https://github.com/agentmorris/MegaDetector/blob/main/megadetector/utils/ct_utils.py
+
+    Args:
+        x (float): scalar to truncate
+        precision (int, optional): the number of significant digits to preserve, should be >= 1
+
+    Returns:
+        float: truncated version of [x]
+    """
+    return math.floor(x * (10 ** precision)) / (10 ** precision)
+
+
+def truncate_float_array(arr: List[float], precision: int = 4) -> List[float]:
+    return [truncate_float(x, precision) for x in arr]
+
+
+def output_timelapse_json(clas_results: List[Tuple], json_name: str, label_names: List[str]):
+    """
+    Convert classification results to timelapse JSON format.
+    
+    Args:
+        clas_results: List of result tuples, one per detected animal. Each tuple contains:
+            (identifier, bbox_conf, bbox, label1, prob1, label2, prob2, ...) where the
+            number of label/prob pairs depends on pred_topn and clas_threshold.
+        json_name: Output JSON file name.
+        label_names: List of all label names.
+    """
+    if not json_name.endswith('.json'):
+        json_name += '.json'
+    
+    # Group detections by file using OrderedDict to preserve order
+    images_dict: Dict[str, List[Dict[str, Any]]] = OrderedDict()
+    
+    for result in clas_results:
+        identifier = result[0]
+        bbox_conf = result[1]
+        bbox = result[2]
+        
+        # Initialize file entry if not exists
+        if identifier not in images_dict:
+            images_dict[identifier] = []
+        
+        # If bbox is None or empty, this image has no detections
+        if bbox is None or bbox_conf is None:
+            continue
+        
+        # Build detection object
+        detection = {
+            "category": "1",  # Always "1" for animal
+            "conf": truncate_float(bbox_conf, precision=3),
+            "bbox": truncate_float_array(list(bbox), precision=4)
+        }
+        
+        clas2idx = {name: str(i + 1) for i, name in enumerate(label_names)}
+
+        classifications = []
+        for i in range(3, len(result), 2):
+            if i + 1 < len(result):
+                label_str = result[i]
+                prob = result[i + 1]
+                if label_str is not None and prob is not None:
+                    classifications.append([clas2idx[label_str], truncate_float(prob, precision=3)])
+        
+        if classifications:
+            detection["classifications"] = classifications
+        
+        images_dict[identifier].append(detection)
+    
+    # Build images list
+    images = []
+    for file_path, detections in images_dict.items():
+        images.append({
+            "file": file_path,
+            "detections": detections
+        })
+    
+    idx2clas = {str(i + 1): name for i, name in enumerate(label_names)}
+    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    # Build output structure
+    output = {
+        "images": images,
+        "detection_categories": {
+            "1": "animal",
+            "2": "person",
+            "3": "vehicle"
+        },
+        "info": {
+            "detection_completion_time": current_time,
+            "format_version": "1.4",
+            "detector": "md_v1000.0.0-redwood.pt",
+            "detector_metadata": {
+            "megadetector_version": "1000-redwood"
+            },
+            "python_library": "awc-helpers"
+        },
+        "classification_categories": idx2clas
+    }
+    
+    # Write to file
+    with open(json_name, 'w') as f:
+        json.dump(output, f, indent=1)
+
+def output_csv(clas_results: List[Tuple],csv_name: str):
+    """
+    Convert classification results to CSV format.
+    Args:
+        clas_results: List of result tuples, one per detected animal. Each tuple contains:
+            (identifier, bbox_conf, bbox, label1, prob1, label2, prob2, ...) where the
+            number of label/prob pairs depends on pred_topn and clas_threshold.
+        csv_name: Output CSV file name.
+    """
+    if not csv_name.endswith('.csv'):
+        csv_name += '.csv'
+
+    # Determine the maximum number of label/prob pairs
+    max_pairs = 0
+    for result in clas_results:
+        num_pairs = (len(result) - 3) // 2
+        if num_pairs > max_pairs:
+            max_pairs = num_pairs
+
+    # Create CSV header
+    header = ['Image Path', 'Bounding Box Confidence', 'Bounding Box Normalized']
+    for i in range(1, max_pairs + 1):
+        header.append(f'Label {i}')
+        header.append(f'Confidence {i}')
+
+    # Write to CSV
+    with open(csv_name, mode='w', newline='') as csv_file:
+        writer = csv.writer(csv_file)
+        writer.writerow(header)
+        for result in clas_results:
+            row = list(result)
+            # Pad the row with empty strings if necessary
+            while len(row) < 3 + 2 * max_pairs:
+                row.append('')
+            writer.writerow(row)

{awc_helpers-0.1.1.dist-info → awc_helpers-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: awc-helpers
-Version: 0.1.1
+Version: 0.1.3
 Summary: Australian Wildlife Conservancy's Wildlife detection and species classification inference tools
 Author: Quan Tran
 License: CC-BY-NC-SA-4.0
@@ -51,11 +51,6 @@ pip install torch==2.9.1
 pip install awc-helpers
 ```
 
-**From GitHub:**
-```bash
-pip install git+https://github.com/Australian-Wildlife-Conservancy-AWC/awc_inference.git
-```
-
 ## Usage
 
 ```python
@@ -72,13 +67,19 @@ pipeline = DetectAndClassify(
 
 # Run inference on image paths
 results = pipeline.predict(
-    inp=["image1.jpg", "image2.jpg"],
+    inp=["path/to/image1.jpg", "path/to/image2.jpg"],
     clas_bs=4
 )
 
-# Results format: [(identifier, bbox, label, confidence), ...]
+# Results format: [(image_path, bbox_confidence, bbox, label, label_confidence), ...]
 for result in results:
     print(result)
+# print example:
+# ("path/to/image1.jpg",
+#  0.804,
+#  (0.2246, 0.5885, 0.0678, 0.1022),
+#  'Acanthagenys rufogularis | Spiny-cheeked Honeyeater',
+#  0.9948)
 ```
 
 ## License

awc_helpers-0.1.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+awc_helpers/__init__.py,sha256=0jyHX2tDNfTsmMXJzFXbVXzDuSczir6987zz5dW529w,757
+awc_helpers/awc_inference.py,sha256=w409rll5Ftnuxt9P5TdwvrxCMd-5pq9YgNRHgptBPQw,20036
+awc_helpers/format_utils.py,sha256=rk0ibOxhW8zqihe-0jHo5FUMRsiDUNWBtKGXLBXN1XQ,5292
+awc_helpers/math_utils.py,sha256=W3G5PGVkiMLM31qjsdJhmJq6KY46XZr6rj1SXWjK4Gk,2656
+awc_helpers-0.1.3.dist-info/LICENSE,sha256=-K8JM-Ym5RhIZI1Wh5soC8hkvOhgA4R0fNpbpucPizg,1659
+awc_helpers-0.1.3.dist-info/METADATA,sha256=l7-qS7oMGFuIDgos1wD_zn6uW1uP9jGXjUbt4NvU7nE,2789
+awc_helpers-0.1.3.dist-info/WHEEL,sha256=hPN0AlP2dZM_3ZJZWP4WooepkmU9wzjGgCLCeFjkHLA,92
+awc_helpers-0.1.3.dist-info/top_level.txt,sha256=_Xvw_DTZwJ6szEkcXxA1_AGYwKN-Uj6jfz0bF07-S8M,12
+awc_helpers-0.1.3.dist-info/RECORD,,

awc_helpers-0.1.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-awc_helpers/__init__.py,sha256=xStt2_-5rK5MvKtbFjMr6w2GqibT7EZWg7SgXmJ_gS8,474
-awc_helpers/awc_inference.py,sha256=x3Lrj7txQ5oaz7rpU_6aKoCIJYcFVyulUH7AMDBDIus,19533
-awc_helpers/math_utils.py,sha256=W3G5PGVkiMLM31qjsdJhmJq6KY46XZr6rj1SXWjK4Gk,2656
-awc_helpers-0.1.1.dist-info/LICENSE,sha256=-K8JM-Ym5RhIZI1Wh5soC8hkvOhgA4R0fNpbpucPizg,1659
-awc_helpers-0.1.1.dist-info/METADATA,sha256=t775UXQUnRNco6chjA8mQ50YcqRoupB-9gwMVxHEyoc,2710
-awc_helpers-0.1.1.dist-info/WHEEL,sha256=hPN0AlP2dZM_3ZJZWP4WooepkmU9wzjGgCLCeFjkHLA,92
-awc_helpers-0.1.1.dist-info/top_level.txt,sha256=_Xvw_DTZwJ6szEkcXxA1_AGYwKN-Uj6jfz0bF07-S8M,12
-awc_helpers-0.1.1.dist-info/RECORD,,