staysift 0.1.0__tar.gz

staysift-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sivakumar
+
+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.

staysift-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: staysift
+Version: 0.1.0
+Summary: GPU-resident SIFT with zero-copy DLPack handoff -- pure Python, OpenCV-accurate, faster end-to-end
+Author-email: Sivakumar <ce22s018@smail.iitm.ac.in>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SivaIITM/PySIFT
+Project-URL: Repository, https://github.com/SivaIITM/PySIFT
+Keywords: sift,gpu,cuda,feature-extraction,image-stitching,computer-vision
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: torch>=2.0
+Requires-Dist: numba>=0.57
+Provides-Extra: cuda11
+Requires-Dist: cupy-cuda11x; extra == "cuda11"
+Provides-Extra: cuda12
+Requires-Dist: cupy-cuda12x; extra == "cuda12"
+Provides-Extra: learned
+Requires-Dist: kornia>=0.7; extra == "learned"
+Provides-Extra: lightglue
+Requires-Dist: kornia>=0.7; extra == "lightglue"
+Provides-Extra: depth
+Requires-Dist: timm>=0.9; extra == "depth"
+Provides-Extra: config
+Requires-Dist: pyyaml; extra == "config"
+Provides-Extra: all
+Requires-Dist: kornia>=0.7; extra == "all"
+Requires-Dist: timm>=0.9; extra == "all"
+Requires-Dist: pyyaml; extra == "all"
+Dynamic: license-file
+
+# PySIFT
+
+**GPU-Resident Deterministic SIFT for Deep Learning Vision Pipelines**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![CUDA](https://img.shields.io/badge/CUDA-11.x%20%7C%2012.x-76B900.svg)](https://developer.nvidia.com/cuda-toolkit)
+
+A pure-Python, GPU-resident SIFT implementation that matches OpenCV SIFT accuracy while running **26% faster end-to-end** with **4x matching speedup**. Zero-copy DLPack interop keeps tensors on the GPU across the full pipeline -- no PCIe round-trips.
+
+## Architecture
+
+<p align="center">
+  <img src="docs/images/fig_architecture.png" alt="PySIFT Architecture" width="800"/>
+</p>
+
+## Key Features
+
+- **GPU-resident pipeline** -- Detection, description, matching, RANSAC, and blending all execute on the GPU via CuPy + Numba CUDA kernels
+- **Zero-copy DLPack handoff** -- CuPy arrays pass to PyTorch tensors without memory copies, enabling seamless integration with deep learning pipelines
+- **OpenCV-accurate** -- Numerically equivalent to OpenCV SIFT (Lowe 2004), verified across HPatches, Oxford 5K, IMC Phototourism, and MegaDepth-1500
+- **Modular descriptor/matcher backends** -- Swap in HardNet, HyNet (learned descriptors) or LightGlue (learned matching) with a single config flag
+- **Deterministic** -- Bitwise reproducible results via warp-shuffle reductions (no atomicAdd non-determinism)
+
+## Qualitative Results
+
+<p align="center">
+  <img src="docs/images/fig_qualitative.png" alt="Stitching Results" width="800"/>
+</p>
+
+## Installation
+
+### Prerequisites: CUDA dependencies
+
+PySIFT requires an NVIDIA GPU with CUDA. Two dependencies must be installed manually because they are CUDA-version-specific:
+
+```bash
+# Check your CUDA version
+nvcc --version
+
+# 1. Install CuPy (pick ONE matching your CUDA version)
+pip install cupy-cuda12x   # CUDA 12.x
+pip install cupy-cuda11x   # CUDA 11.x
+
+# 2. Install PyTorch with CUDA (default pip installs CPU-only!)
+pip install torch --index-url https://download.pytorch.org/whl/cu124   # CUDA 12.4
+pip install torch --index-url https://download.pytorch.org/whl/cu121   # CUDA 12.1
+pip install torch --index-url https://download.pytorch.org/whl/cu118   # CUDA 11.8
+```
+
+> **Important:** Both CuPy and PyTorch-CUDA are required runtime dependencies but cannot be auto-installed by pip because the correct package varies by CUDA version. Install them before installing PySIFT.
+
+### Install PySIFT
+
+```bash
+# From GitHub
+pip install git+https://github.com/SivaIITM/PySIFT.git
+
+# Or from source
+git clone https://github.com/SivaIITM/PySIFT.git
+cd PySIFT
+pip install -e .
+```
+
+### Full install (all dependencies at once)
+
+```bash
+pip install cupy-cuda12x   # or cupy-cuda11x
+pip install -r requirements.txt
+pip install git+https://github.com/SivaIITM/PySIFT.git
+```
+
+### Recommended: depth-aware stitching
+
+PySIFT uses MiDaS monocular depth estimation to split inliers into depth bands, giving each band its own homography. This significantly improves stitching quality for scenes with foreground/background parallax. Without `timm`, stitching falls back to a single global homography.
+
+```bash
+pip install timm>=0.9
+```
+
+### Optional dependencies
+
+```bash
+# Learned descriptors (HardNet, HyNet, OriNet)
+pip install kornia
+
+# YAML config file support
+pip install pyyaml
+
+# Or install all optional deps at once
+pip install -e ".[all]"
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from pysift import PySIFT, GPUPyStitch
+
+# Feature extraction
+sift = PySIFT()
+keypoints, descriptors = sift.detectAndCompute(gray_image)
+
+# Panoramic stitching (2 or 3 images)
+stitcher = GPUPyStitch()
+panorama = stitcher.stitch(img_left, img_right)
+```
+
+### CLI
+
+```bash
+# Basic stitching
+pysift-stitch left.jpg right.jpg
+
+# 3-image panorama with output directory
+pysift-stitch left.jpg center.jpg right.jpg -o results/
+
+# With config file
+pysift-stitch left.jpg right.jpg --config config.yaml
+
+# Learned pipeline
+pysift-stitch left.jpg right.jpg --descriptor hardnet --matcher lightglue
+```
+
+## Configuration Presets
+
+| Preset | Orientation | Descriptor | Matcher | Use Case |
+|--------|-------------|------------|---------|----------|
+| **Classic** | histogram | sift | ratio | Fastest. Full Lowe 2004 pipeline |
+| **Modern** | histogram | sift | lightglue | Best accuracy with proven detection |
+| **Learned** | orinet | hardnet | lightglue | Fully modern pipeline |
+| **Mobile** | histogram | sift | ratio | Large phone images (auto-resize + denoise) |
+
+See [`config.yaml`](config.yaml) for all parameters and presets.
+
+## Requirements
+
+### Hardware
+- NVIDIA GPU with CUDA support (tested on RTX 3050 4GB and above)
+- CUDA Toolkit 11.x or 12.x
+
+### Software
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| Python | >= 3.9 | Runtime |
+| PyTorch | >= 2.0 | Tensor ops, SVD, CUDA graphs |
+| CuPy | >= 12.0 | GPU arrays, CUDA kernels |
+| Numba | >= 0.57 | JIT-compiled CUDA kernels |
+| NumPy | >= 1.22 | CPU array operations |
+| OpenCV | >= 4.5 | Image I/O, CLAHE |
+| kornia | >= 0.7 | *Optional:* HardNet, HyNet, OriNet |
+| timm | >= 0.9 | *Optional:* MiDaS depth estimation |
+| PyYAML | any | *Optional:* config file support |
+
+## Citation
+
+```bibtex
+@article{sivakumar2026pysift,
+  title   = {PySIFT: GPU-Resident Deterministic SIFT for Deep Learning Vision Pipelines},
+  author  = {Sivakumar, K.S.},
+  journal = {arXiv preprint},
+  year    = {2026}
+}
+```
+
+## License
+
+This project is licensed under the MIT License -- see the [LICENSE](LICENSE) file for details.

staysift-0.1.0/README.md

@@ -0,0 +1,170 @@
+# PySIFT
+
+**GPU-Resident Deterministic SIFT for Deep Learning Vision Pipelines**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![CUDA](https://img.shields.io/badge/CUDA-11.x%20%7C%2012.x-76B900.svg)](https://developer.nvidia.com/cuda-toolkit)
+
+A pure-Python, GPU-resident SIFT implementation that matches OpenCV SIFT accuracy while running **26% faster end-to-end** with **4x matching speedup**. Zero-copy DLPack interop keeps tensors on the GPU across the full pipeline -- no PCIe round-trips.
+
+## Architecture
+
+<p align="center">
+  <img src="docs/images/fig_architecture.png" alt="PySIFT Architecture" width="800"/>
+</p>
+
+## Key Features
+
+- **GPU-resident pipeline** -- Detection, description, matching, RANSAC, and blending all execute on the GPU via CuPy + Numba CUDA kernels
+- **Zero-copy DLPack handoff** -- CuPy arrays pass to PyTorch tensors without memory copies, enabling seamless integration with deep learning pipelines
+- **OpenCV-accurate** -- Numerically equivalent to OpenCV SIFT (Lowe 2004), verified across HPatches, Oxford 5K, IMC Phototourism, and MegaDepth-1500
+- **Modular descriptor/matcher backends** -- Swap in HardNet, HyNet (learned descriptors) or LightGlue (learned matching) with a single config flag
+- **Deterministic** -- Bitwise reproducible results via warp-shuffle reductions (no atomicAdd non-determinism)
+
+## Qualitative Results
+
+<p align="center">
+  <img src="docs/images/fig_qualitative.png" alt="Stitching Results" width="800"/>
+</p>
+
+## Installation
+
+### Prerequisites: CUDA dependencies
+
+PySIFT requires an NVIDIA GPU with CUDA. Two dependencies must be installed manually because they are CUDA-version-specific:
+
+```bash
+# Check your CUDA version
+nvcc --version
+
+# 1. Install CuPy (pick ONE matching your CUDA version)
+pip install cupy-cuda12x   # CUDA 12.x
+pip install cupy-cuda11x   # CUDA 11.x
+
+# 2. Install PyTorch with CUDA (default pip installs CPU-only!)
+pip install torch --index-url https://download.pytorch.org/whl/cu124   # CUDA 12.4
+pip install torch --index-url https://download.pytorch.org/whl/cu121   # CUDA 12.1
+pip install torch --index-url https://download.pytorch.org/whl/cu118   # CUDA 11.8
+```
+
+> **Important:** Both CuPy and PyTorch-CUDA are required runtime dependencies but cannot be auto-installed by pip because the correct package varies by CUDA version. Install them before installing PySIFT.
+
+### Install PySIFT
+
+```bash
+# From GitHub
+pip install git+https://github.com/SivaIITM/PySIFT.git
+
+# Or from source
+git clone https://github.com/SivaIITM/PySIFT.git
+cd PySIFT
+pip install -e .
+```
+
+### Full install (all dependencies at once)
+
+```bash
+pip install cupy-cuda12x   # or cupy-cuda11x
+pip install -r requirements.txt
+pip install git+https://github.com/SivaIITM/PySIFT.git
+```
+
+### Recommended: depth-aware stitching
+
+PySIFT uses MiDaS monocular depth estimation to split inliers into depth bands, giving each band its own homography. This significantly improves stitching quality for scenes with foreground/background parallax. Without `timm`, stitching falls back to a single global homography.
+
+```bash
+pip install timm>=0.9
+```
+
+### Optional dependencies
+
+```bash
+# Learned descriptors (HardNet, HyNet, OriNet)
+pip install kornia
+
+# YAML config file support
+pip install pyyaml
+
+# Or install all optional deps at once
+pip install -e ".[all]"
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from pysift import PySIFT, GPUPyStitch
+
+# Feature extraction
+sift = PySIFT()
+keypoints, descriptors = sift.detectAndCompute(gray_image)
+
+# Panoramic stitching (2 or 3 images)
+stitcher = GPUPyStitch()
+panorama = stitcher.stitch(img_left, img_right)
+```
+
+### CLI
+
+```bash
+# Basic stitching
+pysift-stitch left.jpg right.jpg
+
+# 3-image panorama with output directory
+pysift-stitch left.jpg center.jpg right.jpg -o results/
+
+# With config file
+pysift-stitch left.jpg right.jpg --config config.yaml
+
+# Learned pipeline
+pysift-stitch left.jpg right.jpg --descriptor hardnet --matcher lightglue
+```
+
+## Configuration Presets
+
+| Preset | Orientation | Descriptor | Matcher | Use Case |
+|--------|-------------|------------|---------|----------|
+| **Classic** | histogram | sift | ratio | Fastest. Full Lowe 2004 pipeline |
+| **Modern** | histogram | sift | lightglue | Best accuracy with proven detection |
+| **Learned** | orinet | hardnet | lightglue | Fully modern pipeline |
+| **Mobile** | histogram | sift | ratio | Large phone images (auto-resize + denoise) |
+
+See [`config.yaml`](config.yaml) for all parameters and presets.
+
+## Requirements
+
+### Hardware
+- NVIDIA GPU with CUDA support (tested on RTX 3050 4GB and above)
+- CUDA Toolkit 11.x or 12.x
+
+### Software
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| Python | >= 3.9 | Runtime |
+| PyTorch | >= 2.0 | Tensor ops, SVD, CUDA graphs |
+| CuPy | >= 12.0 | GPU arrays, CUDA kernels |
+| Numba | >= 0.57 | JIT-compiled CUDA kernels |
+| NumPy | >= 1.22 | CPU array operations |
+| OpenCV | >= 4.5 | Image I/O, CLAHE |
+| kornia | >= 0.7 | *Optional:* HardNet, HyNet, OriNet |
+| timm | >= 0.9 | *Optional:* MiDaS depth estimation |
+| PyYAML | any | *Optional:* config file support |
+
+## Citation
+
+```bibtex
+@article{sivakumar2026pysift,
+  title   = {PySIFT: GPU-Resident Deterministic SIFT for Deep Learning Vision Pipelines},
+  author  = {Sivakumar, K.S.},
+  journal = {arXiv preprint},
+  year    = {2026}
+}
+```
+
+## License
+
+This project is licensed under the MIT License -- see the [LICENSE](LICENSE) file for details.

staysift-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "staysift"
+version = "0.1.0"
+description = "GPU-resident SIFT with zero-copy DLPack handoff -- pure Python, OpenCV-accurate, faster end-to-end"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Sivakumar", email = "ce22s018@smail.iitm.ac.in" },
+]
+keywords = ["sift", "gpu", "cuda", "feature-extraction", "image-stitching", "computer-vision"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "numpy",
+    "opencv-python>=4.5",
+    "torch>=2.0",
+    "numba>=0.57",
+]
+
+[project.optional-dependencies]
+cuda11 = ["cupy-cuda11x"]
+cuda12 = ["cupy-cuda12x"]
+learned = ["kornia>=0.7"]
+lightglue = ["kornia>=0.7"]
+depth = ["timm>=0.9"]
+config = ["pyyaml"]
+all = ["kornia>=0.7", "timm>=0.9", "pyyaml"]
+
+[project.scripts]
+pysift-stitch = "pysift.core:main"
+
+[project.urls]
+Homepage = "https://github.com/SivaIITM/PySIFT"
+Repository = "https://github.com/SivaIITM/PySIFT"
+
+[tool.setuptools.packages.find]
+include = ["pysift*"]

staysift-0.1.0/pysift/__init__.py

@@ -0,0 +1,7 @@
+"""PySIFT -- GPU-resident SIFT with zero-copy DLPack handoff."""
+
+__version__ = "0.1.0"
+
+from .core import PySIFT, GPUPyStitch, DepthEstimator, SmartLauncher
+
+__all__ = ["PySIFT", "GPUPyStitch", "DepthEstimator", "SmartLauncher"]