fastbbox 0.1.0__tar.gz

fastbbox-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,122 @@
+name: Build and Publish
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*'        # release:  v1.2.3   → publish to PyPI
+      - 'v*-rc*'    # candidate: v1.2.3-rc1 → publish to TestPyPI
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:   # allow manual trigger from the Actions UI
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Build wheels
+      uses: pypa/cibuildwheel@v2.21.0
+      env:
+        CIBW_BUILD: cp39-* cp310-* cp311-* cp312-*
+        # Skip 32-bit, PyPy, and musl builds
+        CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux_* pp*"
+        # Use modern manylinux_2_28
+        CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+        CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+        # Install build dependencies
+        CIBW_BEFORE_BUILD: pip install nanobind scikit-build-core cmake ninja numpy
+        # Linux: Install C++ compiler and CMake
+        CIBW_BEFORE_ALL_LINUX: |
+          if command -v dnf >/dev/null; then
+            dnf install -y gcc-c++ cmake ninja-build
+          else
+            yum install -y gcc-c++ cmake ninja-build
+          fi
+        # Windows: Use delvewheel for repair
+        CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: pip install delvewheel && delvewheel repair -w {dest_dir} {wheel}
+        # Smoke test
+        CIBW_TEST_COMMAND: >-
+          python -c "from fastbbox import bbox_overlaps; import numpy as np;
+          boxes = np.array([[0,0,10,10]], dtype=np.float32);
+          result = bbox_overlaps(boxes, boxes);
+          assert result[0,0] > 0.99, 'IoU test failed';
+          print('fastbbox import OK')"
+        # nanobind requires macos 10.13 or higher
+        CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=10.13
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: wheels-${{ matrix.os }}
+        path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Build sdist
+      run: pipx run build --sdist
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: sdist
+        path: dist/*.tar.gz
+
+  upload_testpypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Only on release-candidate tags: v1.2.3-rc1, v1.2.3-rc2, etc.
+    if: github.event_name == 'push' && contains(github.ref, '-rc')
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/fastbbox
+    steps:
+    - name: Download all artifacts
+      uses: actions/download-artifact@v8
+      with:
+        path: dist
+        merge-multiple: true
+
+    - name: Publish to TestPyPI
+      run: |
+        pip install twine
+        twine upload --repository testpypi dist/*
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+  upload_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastbbox
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all artifacts
+      uses: actions/download-artifact@v8
+      with:
+        path: dist
+        merge-multiple: true
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

fastbbox-0.1.0/.gitignore

@@ -0,0 +1,157 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+*.pyd
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Exclude auto-generated C/C++ files
+*.c
+*.cpp
+*.html
+# Track nanobind C++ sources (intentional committed sources, not generated)
+!src/fastbbox/*_nb.cpp
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp

fastbbox-0.1.0/CMakeLists.txt

@@ -0,0 +1,34 @@
+cmake_minimum_required(VERSION 3.15...3.27)
+project(fastbbox_nanobind LANGUAGES CXX)
+
+# Detect Python with Development.Module component
+if (CMAKE_VERSION VERSION_LESS 3.18)
+  set(DEV_MODULE Development)
+else()
+  set(DEV_MODULE Development.Module)
+endif()
+
+find_package(Python 3.9 COMPONENTS Interpreter ${DEV_MODULE} REQUIRED)
+
+# Configure optimized release build by default
+if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
+endif()
+
+# Detect the installed nanobind package and import it into CMake
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+
+# Build bbox module
+# Use NOMINSIZE since our binding layer contains significant computational logic
+# that benefits from speed optimization rather than size optimization
+nanobind_add_module(bbox NOMINSIZE ${CMAKE_CURRENT_SOURCE_DIR}/src/fastbbox/bbox_nb.cpp)
+
+# Build obb_bbox module
+nanobind_add_module(obb_bbox NOMINSIZE ${CMAKE_CURRENT_SOURCE_DIR}/src/fastbbox/obb_bbox_nb.cpp)
+
+# Install the modules
+install(TARGETS bbox obb_bbox LIBRARY DESTINATION fastbbox)

fastbbox-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CMakeLists.txt
+recursive-include src/fastbbox *_nb.cpp
+global-exclude *.pyc
+global-exclude *.so

fastbbox-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.2
+Name: fastbbox
+Version: 0.1.0
+Summary: Fast IoU/overlap computations for bounding boxes
+Author-Email: Gerry Lim <gerrylimwk@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Homepage, https://github.com/gerrylwk/fastbbox
+Project-URL: Repository, https://github.com/gerrylwk/fastbbox
+Project-URL: Issues, https://github.com/gerrylwk/fastbbox/issues
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: scikit-build-core>=0.5.0; extra == "dev"
+Requires-Dist: nanobind>=1.0.0; extra == "dev"
+Requires-Dist: cmake>=3.15; extra == "dev"
+Description-Content-Type: text/markdown
+
+# FastBBox
+
+Fast IoU/overlap computations for axis-aligned and oriented bounding boxes, powered by nanobind C++ extensions.
+
+## Benchmark
+```
+Function Python (ms)    FastBBox (ms)  Speedup
+--------------------------------------------------
+IoU           1994.19          4.19     475.7x
+GIoU          3028.40          5.99     505.8x
+DIoU          4104.21          6.21     661.3x
+CIoU          6436.51         17.55     366.7x
+EIoU          5211.51          7.04     740.5x
+NWD           2427.36         13.31     182.4x
+OBB          21729.42         31.29     694.5x
+--------------------------------------------------
+TOTAL        44931.61         85.58     525.1x
+```
+
+## Installation
+
+```bash
+pip install fastbbox
+```
+
+### Building from Source
+
+Requires CMake 3.15+ and a C++17 compiler.
+
+```bash
+git clone https://github.com/gerrylwk/fastbbox
+cd fastbbox
+pip install .
+```
+
+## Usage
+
+### Axis-Aligned Bounding Boxes
+
+```python
+import numpy as np
+from fastbbox import (bbox_overlaps, generalized_iou, distance_iou,
+                      complete_iou, efficient_iou, normalized_wasserstein_distance)
+
+# Bounding boxes in [x1, y1, x2, y2] format
+boxes = np.array([
+    [0, 0, 10, 10],
+    [5, 5, 15, 15],
+    [20, 20, 30, 30]
+], dtype=np.float32)
+
+query_boxes = np.array([
+    [0, 0, 10, 10],
+    [12, 12, 22, 22]
+], dtype=np.float32)
+
+iou = bbox_overlaps(boxes, query_boxes)
+giou = generalized_iou(boxes, query_boxes)
+diou = distance_iou(boxes, query_boxes)
+ciou = complete_iou(boxes, query_boxes)
+eiou = efficient_iou(boxes, query_boxes)
+nwd = normalized_wasserstein_distance(boxes, query_boxes)
+```
+
+### Oriented Bounding Boxes (OBB)
+
+```python
+import numpy as np
+import math
+from fastbbox import bbox_overlaps_obb
+
+# Oriented bounding boxes in [center_x, center_y, width, height, angle_radians] format
+obb_boxes = np.array([
+    [0, 0, 4, 2, 0],
+    [1, 0, 4, 2, math.pi/4],
+    [0, 0, 2, 2, math.pi/6],
+], dtype=np.float32)
+
+obb_query_boxes = np.array([
+    [0, 0, 4, 2, 0],
+    [2, 2, 2, 2, 0],
+], dtype=np.float32)
+
+obb_iou = bbox_overlaps_obb(obb_boxes, obb_query_boxes)
+```
+
+## Features
+
+### Axis-Aligned Bounding Box IoU Variants
+
+All variants accept boxes in `[x1, y1, x2, y2]` top-left-bottom-right format:
+
+- **Standard IoU**: Classic Intersection over Union
+- **Generalized IoU (GIoU)**: Considers enclosing area; values in `[-1, 1]`
+  - Reference: [Generalized Intersection over Union](https://arxiv.org/abs/1902.09630)
+- **Distance IoU (DIoU)**: Penalizes center point distance
+  - Reference: [Distance-IoU Loss](https://arxiv.org/abs/1911.08287)
+- **Complete IoU (CIoU)**: Adds aspect ratio consistency penalty to DIoU
+  - Reference: [Distance-IoU Loss](https://arxiv.org/abs/1911.08287)
+- **Efficient IoU (EIoU)**: Separate width/height penalties for faster convergence
+  - Reference: [Focal and Efficient IOU Loss](https://arxiv.org/abs/2101.08158)
+- **Normalized Wasserstein Distance (NWD)**: Optimal transport-based similarity, values in `[0, 1]`
+  - Effective for tiny object detection
+  - Reference: [Normalized Gaussian Wasserstein Distance](https://arxiv.org/abs/2110.13389)
+
+### Oriented Bounding Box (OBB) IoU
+
+Accepts boxes in `[center_x, center_y, width, height, angle_radians]` format:
+
+- Exact calculation for axis-aligned boxes (angle = 0)
+- Approximation-based calculation for rotated boxes using AABB intersection with angle-based scaling
+- Batch processing support
+
+## Performance
+
+FastBBox provides significant speedup over pure Python implementations, especially for large numbers of bounding boxes.
+
+Run `python benchmark_fastbbox.py` to benchmark on your system.
+
+### When to Use Each Variant
+
+- **IoU**: Standard evaluation, NMS (Non-Maximum Suppression)
+- **GIoU**: Training loss for non-overlapping boxes
+- **DIoU**: Object detection training where center distance matters
+- **CIoU**: Bounding box regression with aspect ratio consistency
+- **EIoU**: Fast convergence with separate width/height penalties
+- **NWD**: Tiny object detection
+- **OBB IoU**: Rotated object detection, text detection, aerial imagery
+
+## OBB Implementation Details
+
+The OBB IoU implementation uses different strategies based on box orientations:
+
+1. **Axis-Aligned Boxes** (angle = 0): Exact intersection calculation
+2. **Rotated Boxes**: AABB intersection with scaling factor `cos(|angle1|) * cos(|angle2|)`, minimum 50% retention
+
+For exact rotated box IoU, consider implementing Sutherland-Hodgman clipping or the Separating Axes Theorem (SAT).
+
+## Development
+
+### Building Locally
+
+```bash
+pip install build scikit-build-core cmake nanobind
+python -m build
+```
+
+### Testing Your Build
+
+```bash
+# Correctness tests (compares fastbbox against Python reference implementations)
+python test_fastbbox.py              # Summary output
+python test_fastbbox.py --verbose    # Detailed output with values
+python test_fastbbox.py -f iou giou  # Test specific functions
+
+# Performance benchmarks
+python benchmark_fastbbox.py              # Summary output
+python benchmark_fastbbox.py --verbose    # Detailed timing per run
+python benchmark_fastbbox.py --size 1000  # Test with 1000 boxes
+python benchmark_fastbbox.py --runs 10    # 10 iterations
+```
+
+#### Test File Options
+
+**test_fastbbox.py** - Correctness validation:
+- `--verbose, -v`: Show detailed output with expected/actual values
+- `--function, -f`: Test specific functions (iou, giou, diou, ciou, eiou, nwd, obb)
+- `--tolerance, -t`: Tolerance threshold (default: 1e-5)
+- `--obb-tolerance`: OBB-specific tolerance (default: 1e-3)
+- `--size, -s`: Number of test boxes (default: 100)
+
+**benchmark_fastbbox.py** - Performance benchmarks:
+- `--verbose, -v`: Show individual run times and statistics
+- `--function, -f`: Benchmark specific functions
+- `--size, -s`: Number of boxes (default: 500)
+- `--runs, -r`: Number of iterations (default: 5)
+
+## Requirements
+
+- Python 3.9+
+- NumPy >= 1.19.0
+
+## License
+
+MIT License - see LICENSE file for details.