birder 0.4.2__tar.gz → 0.4.4__tar.gz

{birder-0.4.2 → birder-0.4.4}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: birder
-Version: 0.4.2
+Version: 0.4.4
 Summary: An open-source computer vision framework for wildlife image analysis, featuring state-of-the-art models for species classification and detection.
 Author: Ofer Hasson
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://gitlab.com/birder/birder
 Project-URL: Documentation, https://birder.gitlab.io/birder/
 Project-URL: Issues, https://gitlab.com/birder/birder/-/issues
-Keywords: computer-vision,image-classification,object-detection,pytorch,deep-learning
-Classifier: Development Status :: 3 - Alpha
+Keywords: computer-vision,image-classification,object-detection,self-supervised learning,masked image modeling,pytorch,deep-learning,artificial intelligence
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -48,7 +48,7 @@ Requires-Dist: black~=26.1.0; extra == "dev"
 Requires-Dist: build~=1.4.0; extra == "dev"
 Requires-Dist: bumpver~=2025.1131; extra == "dev"
 Requires-Dist: captum~=0.7.0; extra == "dev"
-Requires-Dist: coverage~=7.13.2; extra == "dev"
+Requires-Dist: coverage~=7.13.3; extra == "dev"
 Requires-Dist: debugpy; extra == "dev"
 Requires-Dist: flake8-pep585~=0.1.7; extra == "dev"
 Requires-Dist: flake8~=7.3.0; extra == "dev"
@@ -87,6 +87,7 @@ An open-source computer vision framework for wildlife image analysis, featuring
 - [Getting Started](#getting-started)
 - [Pre-trained Models](#pre-trained-models)
 - [Detection](#detection)
+- [Evaluation](#evaluation)
 - [Project Status and Contributions](#project-status-and-contributions)
 - [Licenses](#licenses)
 - [Acknowledgments](#acknowledgments)
@@ -117,7 +118,9 @@ The same principle applies to Birder. We stand on the shoulders of giants in the
 
 ## Setup
 
-1. Ensure PyTorch 2.7 is installed on your system
+1. Ensure your environment meets the minimum requirements:
+   - Python 3.11 or newer
+   - PyTorch 2.7 or newer (installed for your hardware/driver stack)
 
 1. Install the latest Birder version:
 
@@ -212,6 +215,10 @@ For detailed information about these datasets, including descriptions, citations
 Detection training and inference are available, see [docs/training_scripts.md](docs/training_scripts.md) and
 [docs/inference.md](docs/inference.md). APIs and model coverage may evolve as detection support matures.
 
+## Evaluation
+
+Evaluation workflows are documented in [docs/evaluation.md](docs/evaluation.md).
+
 ## Project Status and Contributions
 
 Birder is currently a personal project in active development. As the sole developer, I am focused on building and refining the core functionalities of the framework. At this time, I am not actively seeking external contributors.
@@ -240,15 +247,15 @@ Files subject to additional license restrictions are marked in their headers. So
 
 If you think we've missed a reference or a license, please create an issue.
 
-### Pretrained Weights
+### Pre-trained Weights
 
-Some of the pretrained weights available here are pretrained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications of that are for the use of pretrained weights from that dataset. It's best to seek legal advice if you intend to use the pretrained weights in a commercial product.
+Some of the pre-trained weights available here are pre-trained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications are for the use of pre-trained weights from that dataset. It's best to seek legal advice if you intend to use the pre-trained weights in a commercial product.
 
 ### Disclaimer
 
-If you intend to use Birder, its pretrained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.
+If you intend to use Birder, its pre-trained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.
 
-It's the user's responsibility to ensure that their use of this project, including any pretrained weights or datasets, complies with all applicable licenses and legal requirements.
+It's the user's responsibility to ensure that their use of this project, including any pre-trained weights or datasets, complies with all applicable licenses and legal requirements.
 
 ## Acknowledgments
 

{birder-0.4.2 → birder-0.4.4}/README.md

@@ -7,6 +7,7 @@ An open-source computer vision framework for wildlife image analysis, featuring
 - [Getting Started](#getting-started)
 - [Pre-trained Models](#pre-trained-models)
 - [Detection](#detection)
+- [Evaluation](#evaluation)
 - [Project Status and Contributions](#project-status-and-contributions)
 - [Licenses](#licenses)
 - [Acknowledgments](#acknowledgments)
@@ -37,7 +38,9 @@ The same principle applies to Birder. We stand on the shoulders of giants in the
 
 ## Setup
 
-1. Ensure PyTorch 2.7 is installed on your system
+1. Ensure your environment meets the minimum requirements:
+   - Python 3.11 or newer
+   - PyTorch 2.7 or newer (installed for your hardware/driver stack)
 
 1. Install the latest Birder version:
 
@@ -132,6 +135,10 @@ For detailed information about these datasets, including descriptions, citations
 Detection training and inference are available, see [docs/training_scripts.md](docs/training_scripts.md) and
 [docs/inference.md](docs/inference.md). APIs and model coverage may evolve as detection support matures.
 
+## Evaluation
+
+Evaluation workflows are documented in [docs/evaluation.md](docs/evaluation.md).
+
 ## Project Status and Contributions
 
 Birder is currently a personal project in active development. As the sole developer, I am focused on building and refining the core functionalities of the framework. At this time, I am not actively seeking external contributors.
@@ -160,15 +167,15 @@ Files subject to additional license restrictions are marked in their headers. So
 
 If you think we've missed a reference or a license, please create an issue.
 
-### Pretrained Weights
+### Pre-trained Weights
 
-Some of the pretrained weights available here are pretrained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications of that are for the use of pretrained weights from that dataset. It's best to seek legal advice if you intend to use the pretrained weights in a commercial product.
+Some of the pre-trained weights available here are pre-trained on ImageNet. ImageNet was released for non-commercial research purposes only (<https://image-net.org/download>). It's not clear what the implications are for the use of pre-trained weights from that dataset. It's best to seek legal advice if you intend to use the pre-trained weights in a commercial product.
 
 ### Disclaimer
 
-If you intend to use Birder, its pretrained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.
+If you intend to use Birder, its pre-trained weights, or any associated datasets in a commercial product, we strongly recommend seeking legal advice to ensure compliance with all relevant licenses and terms of use.
 
-It's the user's responsibility to ensure that their use of this project, including any pretrained weights or datasets, complies with all applicable licenses and legal requirements.
+It's the user's responsibility to ensure that their use of this project, including any pre-trained weights or datasets, complies with all applicable licenses and legal requirements.
 
 ## Acknowledgments
 

{birder-0.4.2 → birder-0.4.4}/birder/__init__.py

@@ -1,5 +1,6 @@
 from birder.common.fs_ops import load_model_with_cfg
 from birder.common.fs_ops import load_pretrained_model
+from birder.common.fs_ops import load_pretrained_model_and_transform
 from birder.common.lib import get_channels_from_signature
 from birder.common.lib import get_size_from_signature
 from birder.data.transforms.classification import inference_preset as classification_transform
@@ -17,5 +18,6 @@ __all__ = [
     "list_pretrained_models",
     "load_model_with_cfg",
     "load_pretrained_model",
+    "load_pretrained_model_and_transform",
     "__version__",
 ]

{birder-0.4.2 → birder-0.4.4}/birder/common/fs_ops.py

@@ -2,6 +2,7 @@ import json
 import logging
 import os
 import re
+from collections.abc import Callable
 from collections.abc import Iterator
 from pathlib import Path
 from typing import Any
@@ -24,6 +25,8 @@ from birder.common.lib import get_network_name
 from birder.common.lib import get_pretrained_model_url
 from birder.conf import settings
 from birder.data.transforms.classification import RGBType
+from birder.data.transforms.classification import inference_preset
+from birder.data.transforms.detection import InferenceTransform
 from birder.model_registry import Task
 from birder.model_registry import registry
 from birder.model_registry.manifest import FileFormatType
@@ -801,7 +804,8 @@ def load_detection_model(
         for param in net.parameters():
             param.requires_grad_(False)
 
-        net.eval()
+        if pt2 is False:  # NOTE: Remove when GraphModule add support for 'eval'
+            net.eval()
 
     if len(backbone_loaded_config) == 0:
         backbone_custom_config = None
@@ -918,6 +922,82 @@ def load_pretrained_model(
     raise ValueError(f"Unknown model type: {model_metadata['task']}")
 
 
+def load_pretrained_model_and_transform(
+    weights: str,
+    *,
+    dst: Optional[str | Path] = None,
+    file_format: FileFormatType = "pt",
+    inference: bool = True,
+    device: Optional[torch.device] = None,
+    dtype: Optional[torch.dtype] = None,
+    custom_config: Optional[dict[str, Any]] = None,
+    progress_bar: bool = True,
+    classification_kwargs: Optional[dict[str, Any]] = None,
+    detection_kwargs: Optional[dict[str, Any]] = None,
+) -> tuple[BaseNet | DetectionBaseNet, ModelInfo | DetectionModelInfo, Callable[..., torch.Tensor]]:
+    """
+    Loads a pre-trained model and builds the matching inference transform
+
+    This is a convenience helper for the common inference path where the model and
+    its default preprocessing are needed together. Classification models use
+    inference_preset, detection models use InferenceTransform.
+
+    Parameters
+    ----------
+    weights
+        Name of the pre-trained weights to load from the model registry.
+    dst
+        Destination path where the model weights will be downloaded or loaded from.
+    file_format
+        Model format (e.g. pt, pt2, safetensors, etc.)
+    inference
+        Flag to prepare the model for inference mode.
+    device
+        The device to load the model on (cpu/cuda).
+    dtype
+        Data type for model parameters and computations (e.g., torch.float32, torch.float16).
+    custom_config
+        Additional model configuration that overrides or extends the predefined configuration.
+    progress_bar
+        Whether to display a progress bar during file download.
+    classification_kwargs
+        Optional keyword arguments forwarded to inference_preset.
+    detection_kwargs
+        Optional keyword arguments forwarded to InferenceTransform. If dynamic_size is
+        not provided it defaults to the model signature value.
+
+    Returns
+    -------
+    A tuple containing three elements:
+    - A PyTorch module (neural network model) loaded with pre-trained weights.
+    - Model info containing class mappings, signature, and RGB stats.
+    - An inference transform matching the model task.
+    """
+
+    net, model_info = load_pretrained_model(
+        weights,
+        dst=dst,
+        file_format=file_format,
+        inference=inference,
+        device=device,
+        dtype=dtype,
+        custom_config=custom_config,
+        progress_bar=progress_bar,
+    )
+
+    size = lib.get_size_from_signature(model_info.signature)
+    transform: Callable[..., torch.Tensor]
+    if isinstance(model_info, DetectionModelInfo):
+        detection_args = {} if detection_kwargs is None else dict(detection_kwargs)
+        detection_args.setdefault("dynamic_size", model_info.signature["dynamic"])
+        transform = InferenceTransform(size, model_info.rgb_stats, **detection_args)
+    else:
+        classification_args = {} if classification_kwargs is None else dict(classification_kwargs)
+        transform = inference_preset(size, model_info.rgb_stats, **classification_args)
+
+    return (net, model_info, transform)
+
+
 def load_model_with_cfg(
     cfg: dict[str, Any] | str | Path, weights_path: Optional[str | Path]
 ) -> tuple[torch.nn.Module, dict[str, Any]]:

{birder-0.4.2 → birder-0.4.4}/birder/common/training_cli.py

@@ -485,8 +485,13 @@ def add_dataloader_args(
         )
 
 
-def add_precision_args(parser: argparse.ArgumentParser) -> None:
+def add_precision_args(parser: argparse.ArgumentParser, channels_last: bool = False) -> None:
     group = parser.add_argument_group("Precision parameters")
+    if channels_last is True:
+        group.add_argument(
+            "--channels-last", default=False, action="store_true", help="use channels-last memory format"
+        )
+
     group.add_argument(
         "--model-dtype",
         type=str,

{birder-0.4.2 → birder-0.4.4}/birder/common/training_utils.py

@@ -1165,12 +1165,16 @@ def init_training(
         device_id = torch.cuda.current_device()
 
     if args.use_deterministic_algorithms is True:
+        log.debug("Turning on deterministic algorithms")
         torch.backends.cudnn.benchmark = False
         torch.use_deterministic_algorithms(True)
     elif cudnn_dynamic_size is True:
         # Dynamic sizes: avoid per-size algorithm selection overhead.
+        log.debug("Turning off cudnn")
         torch.backends.cudnn.enabled = False
+        torch.backends.cudnn.benchmark = False
     else:
+        log.debug("Turning on cudnn")
         torch.backends.cudnn.enabled = True
         torch.backends.cudnn.benchmark = True
 

{birder-0.4.2 → birder-0.4.4}/birder/data/collators/detection.py

@@ -15,7 +15,9 @@ def collate_fn(batch: list[tuple[Any, ...]]) -> tuple[Any, ...]:
     return tuple(zip(*batch))
 
 
-def batch_images(images: list[torch.Tensor], size_divisible: int) -> tuple[torch.Tensor, torch.Tensor, list[list[int]]]:
+def batch_images(
+    images: list[torch.Tensor], size_divisible: int
+) -> tuple[torch.Tensor, torch.Tensor, list[tuple[int, int]]]:
     """
     Batch list of image tensors of different sizes into a single batch.
     Pad with zeros all images to the shape of the largest image in the list.

{birder-0.4.2 → birder-0.4.4}/birder/datahub/_lib.py

@@ -1,5 +1,6 @@
 import logging
 import tarfile
+import zipfile
 from pathlib import Path
 
 from birder.common import cli
@@ -26,9 +27,17 @@ def download_url(url: str, target: str | Path, sha256: str, progress_bar: bool =
 
 def extract_archive(from_path: str | Path, to_path: str | Path) -> None:
     logger.info(f"Extracting {from_path} to {to_path}")
-    with tarfile.open(from_path, "r") as tar:
-        if hasattr(tarfile, "data_filter") is True:
-            tar.extractall(to_path, filter="data")
-        else:
-            # NOTE: Remove once minimum Python version is 3.12 or above
-            tar.extractall(to_path)  # nosec # tarfile_unsafe_members
+    if isinstance(from_path, str):
+        from_path = Path(from_path)
+
+    if from_path.suffix == ".zip":
+        with zipfile.ZipFile(from_path, "r") as zf:
+            zf.extractall(to_path)  # nosec # tarfile_unsafe_members
+
+    else:
+        with tarfile.open(from_path, "r") as tar:
+            if hasattr(tarfile, "data_filter") is True:
+                tar.extractall(to_path, filter="data")
+            else:
+                # NOTE: Remove once minimum Python version is 3.12 or above
+                tar.extractall(to_path)  # nosec # tarfile_unsafe_members