bird-crop 0.1.3__tar.gz

bird_crop-0.1.3/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Kammerhofer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bird_crop-0.1.3/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: bird-crop
+Version: 0.1.3
+Summary: Detect and crop birds and other objects from images with YOLO models.
+Author-email: Martin Kammerhofer <mkamm@gmx.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/variance/bird_crop
+Project-URL: Repository, https://github.com/variance/bird_crop
+Project-URL: Issues, https://github.com/variance/bird_crop/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: piexif
+Requires-Dist: ultralytics
+Dynamic: license-file
+
+# BirdCrop 🐦✂️
+
+**BirdCrop** is a Python command-line utility and library designed to automatically detect objects (like birds, people, etc.) in images using YOLO models and save cropped images of those detections. It offers flexible configuration for targeting specific classes, adding margins, sorting detections, and customizing output filenames and locations using powerful templating.
+
+Originally developed to rapidly identify and extract avian subjects from high-speed burst photography, the system has since been expanded to support multiple and diverse object classes beyond birds. It excels in its primary application: processing large volumes of in-flight bird imagery where subjects occupy only a small pixel area within the frame. By automating detection and cropping workflows for burst sequences, the tool eliminates time-intensive manual adjustments like zooming and panning while retaining analytical accuracy, making it ideal for rapid wildlife surveys and high-throughput curation of still-image datasets.
+
+## Key Features
+
+*   **YOLO-Powered Detection:** Uses YOLO26 models by default for faster, more accurate bird detection. You can also provide a YOLOv8 or custom model with `--model`.
+*   **Flexible Class Targeting:** Specify which object classes to detect using their names (e.g., `"bird,dog,cat"`) or their model-specific IDs (e.g., `"14,16,15"`). The tool adapts to the classes present in the loaded model.
+*   **List Model Classes:** Easily list all classes and their IDs available within a specific YOLO model file using the `--list-classes` option.
+*   **Customizable Output Paths:** Define complex output file paths and names using Python's format string syntax via `--output-template`. Access detailed information about the input file, detection, and crop (see Template Variables below).
+*   **Cropping Margin:** Add a specified pixel margin around the detected bounding box before cropping using `--margin`.
+*   **Detection Sorting:** Sort multiple detections within an image by `confidence` or bounding box `size` (default) using `--sortby`.
+*   **Single or Multiple Crops:** Choose to save only the single "best" detection (highest confidence or largest size) per image or save crops for *all* detected objects using `--multiple`.
+*   **Per-Category Numbering:** Use the `{pcnr}` template variable for sequential numbering *within* each category for a given input image.
+*   **Directory Processing:** Process all supported images within specified directories, optionally searching recursively (`-r`).
+*   **Concurrent Processing:** Speed up processing on multi-core systems using parallel worker threads (`-w`).
+*   **Overwrite Control:** Prevent accidental data loss by default; use `--force` (`-f`) to allow overwriting existing crop files.
+
+## Installation
+
+Install the package and its runtime dependencies from PyPI:
+
+```bash
+python -m pip install bird-crop
+```
+
+For development from a checkout:
+
+```bash
+git clone https://github.com/variance/bird_crop.git
+cd bird_crop
+python -m pip install .
+```
+
+This installs the `birdcrop` library and the `birdcrop` and `birdcrop-upgrade`
+command-line commands. The legacy `run_birdcrop.py` and
+`upgrade_birdcrop.py` launchers remain available when running from a checkout.
+
+BirdCrop uses `yolo26n.pt` by default. If the selected model is not present,
+the CLI downloads it automatically from the Ultralytics assets release. You
+can select another YOLO26 size with `--model-size` (`nano`, `small`, `medium`,
+`large`, or `xlarge`), or specify an existing YOLOv8/custom model with
+`--model`.
+
+### Model Selection
+
+The default model is `yolo26n.pt`. Use `--model-size` to choose another YOLO26 model:
+
+```bash
+# default: yolo26n.pt
+python run_birdcrop.py path/to/images
+
+# use the large YOLO26 model
+python run_birdcrop.py --model-size large path/to/images
+
+# use a specific model file, including YOLOv8 or a custom model
+python run_birdcrop.py --model path/to/model.pt path/to/images
+```
+
+When using `--model-size`, a missing model file is downloaded automatically. A user-specified `--model` must already exist locally.
+
+## Usage
+
+The installed command is `birdcrop`:
+
+```bash
+birdcrop [options] [INPUT_PATH ...]
+```
+
+The equivalent checkout command is `python run_birdcrop.py [options] [INPUT_PATH ...]`.
+
+## Update Checks
+
+BirdCrop can check for upstream updates at startup.
+
+- Package versions: https://pypi.org/pypi/ultralytics/json
+- YOLO asset release tags: https://api.github.com/repos/ultralytics/assets/releases/latest
+
+CLI flags:
+
+```bash
+# enabled by default
+python run_birdcrop.py --check-updates [options] [INPUT_PATH ...]
+
+# disable all online checks
+python run_birdcrop.py --no-update-check [options] [INPUT_PATH ...]
+
+# network timeout per endpoint in seconds
+python run_birdcrop.py --update-check-timeout 2.0 [options] [INPUT_PATH ...]
+```
+
+## Upgrading
+
+To keep BirdCrop and its YOLO models up to date, use the `birdcrop-upgrade` command:
+
+```bash
+# upgrade both the ultralytics package and download latest models
+birdcrop-upgrade
+
+# upgrade package only
+birdcrop-upgrade --package-only
+
+# download latest models only
+birdcrop-upgrade --models-only
+
+# download specific YOLO26 models
+birdcrop-upgrade --models yolo26n.pt,yolo26l.pt
+
+# download models to a specific directory
+birdcrop-upgrade --output-dir ./models
+
+# verbose output
+birdcrop-upgrade --verbose
+```
+
+From a checkout, `python upgrade_birdcrop.py` remains an equivalent launcher.
+
+The upgrade utility:
+- Updates `ultralytics` package via `pip install --upgrade ultralytics`
+- Downloads the latest YOLO model files from the latest [ultralytics/assets](https://github.com/ultralytics/assets) release
+- Skips models that already exist locally (use `--package-only` or `--models-only` to update just one component)
+
+## Building and publishing
+
+To build distributable artifacts locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+This creates a source distribution and wheel in `dist/`. After configuring
+your PyPI credentials, upload them with:
+
+```bash
+python -m pip install twine
+python -m twine upload dist/*
+```

bird_crop-0.1.3/README.md

@@ -0,0 +1,140 @@
+# BirdCrop 🐦✂️
+
+**BirdCrop** is a Python command-line utility and library designed to automatically detect objects (like birds, people, etc.) in images using YOLO models and save cropped images of those detections. It offers flexible configuration for targeting specific classes, adding margins, sorting detections, and customizing output filenames and locations using powerful templating.
+
+Originally developed to rapidly identify and extract avian subjects from high-speed burst photography, the system has since been expanded to support multiple and diverse object classes beyond birds. It excels in its primary application: processing large volumes of in-flight bird imagery where subjects occupy only a small pixel area within the frame. By automating detection and cropping workflows for burst sequences, the tool eliminates time-intensive manual adjustments like zooming and panning while retaining analytical accuracy, making it ideal for rapid wildlife surveys and high-throughput curation of still-image datasets.
+
+## Key Features
+
+*   **YOLO-Powered Detection:** Uses YOLO26 models by default for faster, more accurate bird detection. You can also provide a YOLOv8 or custom model with `--model`.
+*   **Flexible Class Targeting:** Specify which object classes to detect using their names (e.g., `"bird,dog,cat"`) or their model-specific IDs (e.g., `"14,16,15"`). The tool adapts to the classes present in the loaded model.
+*   **List Model Classes:** Easily list all classes and their IDs available within a specific YOLO model file using the `--list-classes` option.
+*   **Customizable Output Paths:** Define complex output file paths and names using Python's format string syntax via `--output-template`. Access detailed information about the input file, detection, and crop (see Template Variables below).
+*   **Cropping Margin:** Add a specified pixel margin around the detected bounding box before cropping using `--margin`.
+*   **Detection Sorting:** Sort multiple detections within an image by `confidence` or bounding box `size` (default) using `--sortby`.
+*   **Single or Multiple Crops:** Choose to save only the single "best" detection (highest confidence or largest size) per image or save crops for *all* detected objects using `--multiple`.
+*   **Per-Category Numbering:** Use the `{pcnr}` template variable for sequential numbering *within* each category for a given input image.
+*   **Directory Processing:** Process all supported images within specified directories, optionally searching recursively (`-r`).
+*   **Concurrent Processing:** Speed up processing on multi-core systems using parallel worker threads (`-w`).
+*   **Overwrite Control:** Prevent accidental data loss by default; use `--force` (`-f`) to allow overwriting existing crop files.
+
+## Installation
+
+Install the package and its runtime dependencies from PyPI:
+
+```bash
+python -m pip install bird-crop
+```
+
+For development from a checkout:
+
+```bash
+git clone https://github.com/variance/bird_crop.git
+cd bird_crop
+python -m pip install .
+```
+
+This installs the `birdcrop` library and the `birdcrop` and `birdcrop-upgrade`
+command-line commands. The legacy `run_birdcrop.py` and
+`upgrade_birdcrop.py` launchers remain available when running from a checkout.
+
+BirdCrop uses `yolo26n.pt` by default. If the selected model is not present,
+the CLI downloads it automatically from the Ultralytics assets release. You
+can select another YOLO26 size with `--model-size` (`nano`, `small`, `medium`,
+`large`, or `xlarge`), or specify an existing YOLOv8/custom model with
+`--model`.
+
+### Model Selection
+
+The default model is `yolo26n.pt`. Use `--model-size` to choose another YOLO26 model:
+
+```bash
+# default: yolo26n.pt
+python run_birdcrop.py path/to/images
+
+# use the large YOLO26 model
+python run_birdcrop.py --model-size large path/to/images
+
+# use a specific model file, including YOLOv8 or a custom model
+python run_birdcrop.py --model path/to/model.pt path/to/images
+```
+
+When using `--model-size`, a missing model file is downloaded automatically. A user-specified `--model` must already exist locally.
+
+## Usage
+
+The installed command is `birdcrop`:
+
+```bash
+birdcrop [options] [INPUT_PATH ...]
+```
+
+The equivalent checkout command is `python run_birdcrop.py [options] [INPUT_PATH ...]`.
+
+## Update Checks
+
+BirdCrop can check for upstream updates at startup.
+
+- Package versions: https://pypi.org/pypi/ultralytics/json
+- YOLO asset release tags: https://api.github.com/repos/ultralytics/assets/releases/latest
+
+CLI flags:
+
+```bash
+# enabled by default
+python run_birdcrop.py --check-updates [options] [INPUT_PATH ...]
+
+# disable all online checks
+python run_birdcrop.py --no-update-check [options] [INPUT_PATH ...]
+
+# network timeout per endpoint in seconds
+python run_birdcrop.py --update-check-timeout 2.0 [options] [INPUT_PATH ...]
+```
+
+## Upgrading
+
+To keep BirdCrop and its YOLO models up to date, use the `birdcrop-upgrade` command:
+
+```bash
+# upgrade both the ultralytics package and download latest models
+birdcrop-upgrade
+
+# upgrade package only
+birdcrop-upgrade --package-only
+
+# download latest models only
+birdcrop-upgrade --models-only
+
+# download specific YOLO26 models
+birdcrop-upgrade --models yolo26n.pt,yolo26l.pt
+
+# download models to a specific directory
+birdcrop-upgrade --output-dir ./models
+
+# verbose output
+birdcrop-upgrade --verbose
+```
+
+From a checkout, `python upgrade_birdcrop.py` remains an equivalent launcher.
+
+The upgrade utility:
+- Updates `ultralytics` package via `pip install --upgrade ultralytics`
+- Downloads the latest YOLO model files from the latest [ultralytics/assets](https://github.com/ultralytics/assets) release
+- Skips models that already exist locally (use `--package-only` or `--models-only` to update just one component)
+
+## Building and publishing
+
+To build distributable artifacts locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+This creates a source distribution and wheel in `dist/`. After configuring
+your PyPI credentials, upload them with:
+
+```bash
+python -m pip install twine
+python -m twine upload dist/*
+```

bird_crop-0.1.3/bird_crop.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: bird-crop
+Version: 0.1.3
+Summary: Detect and crop birds and other objects from images with YOLO models.
+Author-email: Martin Kammerhofer <mkamm@gmx.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/variance/bird_crop
+Project-URL: Repository, https://github.com/variance/bird_crop
+Project-URL: Issues, https://github.com/variance/bird_crop/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: piexif
+Requires-Dist: ultralytics
+Dynamic: license-file
+
+# BirdCrop 🐦✂️
+
+**BirdCrop** is a Python command-line utility and library designed to automatically detect objects (like birds, people, etc.) in images using YOLO models and save cropped images of those detections. It offers flexible configuration for targeting specific classes, adding margins, sorting detections, and customizing output filenames and locations using powerful templating.
+
+Originally developed to rapidly identify and extract avian subjects from high-speed burst photography, the system has since been expanded to support multiple and diverse object classes beyond birds. It excels in its primary application: processing large volumes of in-flight bird imagery where subjects occupy only a small pixel area within the frame. By automating detection and cropping workflows for burst sequences, the tool eliminates time-intensive manual adjustments like zooming and panning while retaining analytical accuracy, making it ideal for rapid wildlife surveys and high-throughput curation of still-image datasets.
+
+## Key Features
+
+*   **YOLO-Powered Detection:** Uses YOLO26 models by default for faster, more accurate bird detection. You can also provide a YOLOv8 or custom model with `--model`.
+*   **Flexible Class Targeting:** Specify which object classes to detect using their names (e.g., `"bird,dog,cat"`) or their model-specific IDs (e.g., `"14,16,15"`). The tool adapts to the classes present in the loaded model.
+*   **List Model Classes:** Easily list all classes and their IDs available within a specific YOLO model file using the `--list-classes` option.
+*   **Customizable Output Paths:** Define complex output file paths and names using Python's format string syntax via `--output-template`. Access detailed information about the input file, detection, and crop (see Template Variables below).
+*   **Cropping Margin:** Add a specified pixel margin around the detected bounding box before cropping using `--margin`.
+*   **Detection Sorting:** Sort multiple detections within an image by `confidence` or bounding box `size` (default) using `--sortby`.
+*   **Single or Multiple Crops:** Choose to save only the single "best" detection (highest confidence or largest size) per image or save crops for *all* detected objects using `--multiple`.
+*   **Per-Category Numbering:** Use the `{pcnr}` template variable for sequential numbering *within* each category for a given input image.
+*   **Directory Processing:** Process all supported images within specified directories, optionally searching recursively (`-r`).
+*   **Concurrent Processing:** Speed up processing on multi-core systems using parallel worker threads (`-w`).
+*   **Overwrite Control:** Prevent accidental data loss by default; use `--force` (`-f`) to allow overwriting existing crop files.
+
+## Installation
+
+Install the package and its runtime dependencies from PyPI:
+
+```bash
+python -m pip install bird-crop
+```
+
+For development from a checkout:
+
+```bash
+git clone https://github.com/variance/bird_crop.git
+cd bird_crop
+python -m pip install .
+```
+
+This installs the `birdcrop` library and the `birdcrop` and `birdcrop-upgrade`
+command-line commands. The legacy `run_birdcrop.py` and
+`upgrade_birdcrop.py` launchers remain available when running from a checkout.
+
+BirdCrop uses `yolo26n.pt` by default. If the selected model is not present,
+the CLI downloads it automatically from the Ultralytics assets release. You
+can select another YOLO26 size with `--model-size` (`nano`, `small`, `medium`,
+`large`, or `xlarge`), or specify an existing YOLOv8/custom model with
+`--model`.
+
+### Model Selection
+
+The default model is `yolo26n.pt`. Use `--model-size` to choose another YOLO26 model:
+
+```bash
+# default: yolo26n.pt
+python run_birdcrop.py path/to/images
+
+# use the large YOLO26 model
+python run_birdcrop.py --model-size large path/to/images
+
+# use a specific model file, including YOLOv8 or a custom model
+python run_birdcrop.py --model path/to/model.pt path/to/images
+```
+
+When using `--model-size`, a missing model file is downloaded automatically. A user-specified `--model` must already exist locally.
+
+## Usage
+
+The installed command is `birdcrop`:
+
+```bash
+birdcrop [options] [INPUT_PATH ...]
+```
+
+The equivalent checkout command is `python run_birdcrop.py [options] [INPUT_PATH ...]`.
+
+## Update Checks
+
+BirdCrop can check for upstream updates at startup.
+
+- Package versions: https://pypi.org/pypi/ultralytics/json
+- YOLO asset release tags: https://api.github.com/repos/ultralytics/assets/releases/latest
+
+CLI flags:
+
+```bash
+# enabled by default
+python run_birdcrop.py --check-updates [options] [INPUT_PATH ...]
+
+# disable all online checks
+python run_birdcrop.py --no-update-check [options] [INPUT_PATH ...]
+
+# network timeout per endpoint in seconds
+python run_birdcrop.py --update-check-timeout 2.0 [options] [INPUT_PATH ...]
+```
+
+## Upgrading
+
+To keep BirdCrop and its YOLO models up to date, use the `birdcrop-upgrade` command:
+
+```bash
+# upgrade both the ultralytics package and download latest models
+birdcrop-upgrade
+
+# upgrade package only
+birdcrop-upgrade --package-only
+
+# download latest models only
+birdcrop-upgrade --models-only
+
+# download specific YOLO26 models
+birdcrop-upgrade --models yolo26n.pt,yolo26l.pt
+
+# download models to a specific directory
+birdcrop-upgrade --output-dir ./models
+
+# verbose output
+birdcrop-upgrade --verbose
+```
+
+From a checkout, `python upgrade_birdcrop.py` remains an equivalent launcher.
+
+The upgrade utility:
+- Updates `ultralytics` package via `pip install --upgrade ultralytics`
+- Downloads the latest YOLO model files from the latest [ultralytics/assets](https://github.com/ultralytics/assets) release
+- Skips models that already exist locally (use `--package-only` or `--models-only` to update just one component)
+
+## Building and publishing
+
+To build distributable artifacts locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+This creates a source distribution and wheel in `dist/`. After configuring
+your PyPI credentials, upload them with:
+
+```bash
+python -m pip install twine
+python -m twine upload dist/*
+```

bird_crop-0.1.3/bird_crop.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE.txt
+README.md
+pyproject.toml
+bird_crop.egg-info/PKG-INFO
+bird_crop.egg-info/SOURCES.txt
+bird_crop.egg-info/dependency_links.txt
+bird_crop.egg-info/entry_points.txt
+bird_crop.egg-info/requires.txt
+bird_crop.egg-info/top_level.txt
+birdcrop/__init__.py
+birdcrop/__main__.py
+birdcrop/cli.py
+birdcrop/cropper.py
+birdcrop/exceptions.py
+birdcrop/upgrade.py
+birdcrop/utils.py

bird_crop-0.1.3/bird_crop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bird_crop-0.1.3/bird_crop.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+birdcrop = birdcrop.cli:main
+birdcrop-upgrade = birdcrop.upgrade:main

bird_crop-0.1.3/bird_crop.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+opencv-python
+piexif
+ultralytics

bird_crop-0.1.3/bird_crop.egg-info/top_level.txt

@@ -0,0 +1 @@
+birdcrop

bird_crop-0.1.3/birdcrop/__init__.py

@@ -0,0 +1,32 @@
+# birdcrop/__init__.py
+"""
+BirdCrop Library: Detect and crop birds from images using YOLO models.
+"""
+
+# Import key components to make them available directly from the package
+from .cropper import BirdCropper
+from .utils import find_image_files
+from .exceptions import (
+    BirdCropError,
+    DirectoryCreationError,
+    FileWriteError,
+    ImageProcessingError,
+    ModelLoadError,
+    PredictionError,
+)
+
+__version__ = "0.1.3"
+__date__ = "2026-09-29"
+
+__all__ = [
+    'BirdCropper',
+    'find_image_files',
+    'BirdCropError',
+    'DirectoryCreationError',
+    'FileWriteError',
+    'ImageProcessingError',
+    'ModelLoadError',
+    'PredictionError',
+    '__version__',
+    '__date__',
+]

bird_crop-0.1.3/birdcrop/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m birdcrop`` to invoke the BirdCrop CLI."""
+
+import sys
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())