edgeval 0.1.0__tar.gz

edgeval-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+*.so
+
+# CUDA
+*.fatbin
+*.cubin
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Edge evaluation output
+*-eval/
+*-eval-*/
+*-eval-gpu/
+
+# Benchmark and test artifacts
+benchmark_*.py
+test_*.py
+single_img_benchmark.py
+run_hed_benchmark.py
+generate_chart.py
+*.json
+*.npy
+*.html
+gpu_eval_precise.py
+
+# Compiled libraries (keep source .cu and .cc, ignore local builds)
+cxx/lib/*.so
+cxx/cxx
+cxx/lib/lib
+gpu_eval/auction_cuda.so
+
+# Environment
+.env
+.venv/
+venv/

edgeval-0.1.0/LICENSE

@@ -0,0 +1,196 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, and merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by
+      reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      If you develop a new file, and you want it to be of the greatest
+      possible use to the public, we recommend making it Apache-2.0.
+      To do so, attach the following boilerplate notice:
+
+   Copyright 2026 0xrjman
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

edgeval-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: edgeval
+Version: 0.1.0
+Summary: GPU-accelerated edge detection evaluation (ODS/OIS/AP/R50)
+Home-page: https://github.com/0xrjman/edgeval.cu
+Author: 0xrjman & Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/0xrjman/edgeval.cu
+Project-URL: Repository, https://github.com/0xrjman/edgeval.cu
+Keywords: edge-detection,evaluation,cuda,gpu,ods,ois,bsds500
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy>=1.6.0
+Requires-Dist: opencv-python
+Requires-Dist: tqdm
+Requires-Dist: click
+Requires-Dist: torch>=2.0
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.8+-blue?logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/CUDA-12.x-76B900?logo=nvidia" alt="CUDA">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
+</p>
+
+<p align="center">
+  <h1 align="center">edgeval.cu</h1>
+  <p align="center">GPU-accelerated edge detection evaluation</p>
+  <p align="center"><strong>20 min → 1.6 min</strong> on BSDS500 &nbsp;|&nbsp; <strong>12.8×</strong> faster than CPU</p>
+</p>
+
+---
+
+## What Problem Does This Solve?
+
+Evaluating an edge detection model on BSDS500 means solving **~99,000 independent assignment problems** — matching every predicted edge pixel to every ground truth pixel, at 99 thresholds, across 5 human annotations, for 200 images.
+
+The standard CPU pipeline takes **20 minutes**. That's fine for a final paper. It's terrible when you're training and want to check your model's progress every few epochs.
+
+**edgeval.cu** brings it down to **1.6 minutes** — fast enough to run every epoch without slowing down training.
+
+---
+
+## How It Works
+
+Edge matching is a **minimum-cost bipartite assignment problem**:
+
+```
+Predicted edges ──→  Match (cost = distance)  ←── Ground truth edges
+                     Or pay outlier penalty
+```
+
+We solve it with the **Auction Algorithm** (Bertsekas, 1979), perfectly suited for GPU parallelism. Each predicted pixel iteratively bids on ground truth pixels; the highest bidder wins each round. Repeat until convergence.
+
+```mermaid
+flowchart LR
+    subgraph Input["📥 Input"]
+        EP["Edge Map\n.png"]
+        GT["Ground Truth\n.mat"]
+    end
+
+    subgraph Pre["🎯 Preprocessing"]
+        THR["99 Thresholds"]
+        THIN["Zhang-Suen\nThinning"]
+    end
+
+    subgraph Graph["🔗 Graph Construction"]
+        EDGE["CUDA Edge Builder\nSingle Kernel Launch"]
+        SORT["GPU Sort + Split\nby Annotator"]
+    end
+
+    subgraph Solve["⚔️ Solver"]
+        AUCT["Auction Algorithm\nε-Scaling 8→0\n485 problems/parallel"]
+    end
+
+    subgraph Out["📊 Output"]
+        ODS["ODS · OIS"]
+        AP["AP · R50"]
+    end
+
+    EP --> THR --> THIN --> EDGE
+    GT -.-> EDGE
+    EDGE --> SORT --> AUCT --> ODS
+    AUCT --> AP
+```
+
+### ε-Scaling Strategy
+
+```
+ε = 8  →  coarse solution in ~100 rounds
+ε = 4  →  refine in ~200 rounds
+ε = 2  →  refine in ~400 rounds
+ε = 1  →  refine in ~500 rounds
+ε = 0  →  exact optimality in ~300 rounds ← tuned!
+```
+
+Most problems converge within 200-300 rounds at ε=0. We detect convergence by counting **consecutive** no-change rounds — avoiding the trap of mistaking temporary bid-stalemates for convergence.
+
+### Two Modes for Two Needs
+
+| | Simple (Training) | Extended (Paper) |
+|---|---|---|
+| Graph | Bipartite, real edges only | n×n, kOfN + diagonal overlay |
+| Speed | **0.47s/img** | ~5.7s/img |
+| ΔODS vs reference | +0.003 | <0.001 |
+| Use case | Every-epoch monitoring | Final evaluation |
+
+---
+
+## Performance
+
+<p align="center">
+  <strong>BSDS500 — 200 images, 99 thresholds, RTX 4090</strong>
+</p>
+
+| | CPU CSA (MATLAB) | GPU Simple | Speedup |
+|---|---|---|---|
+| Per image | ~6s | **0.47s** | **12.8×** |
+| Full dataset | ~20 min | **1.6 min** | **12.8×** |
+| ODS accuracy | 0 (reference) | Δ = +0.003 | Stable |
+
+### Pipeline Breakdown
+
+```
+GPU Thinning     ████████░░░░░░░░░░░░  0.12s (25%)
+Edge Builder     █░░░░░░░░░░░░░░░░░░░  0.02s ( 4%)
+GPU Sort+Split   █████░░░░░░░░░░░░░░░  0.08s (17%)
+Problem Build    ██░░░░░░░░░░░░░░░░░░  0.04s ( 9%)
+Auction Solve    ██████████░░░░░░░░░░  0.14s (30%)
+Overhead         █████░░░░░░░░░░░░░░░  0.07s (15%)
+                 ────────────────────
+TOTAL            0.47s
+```
+
+> Detailed breakdown and configuration sweep: [docs/benchmarks.md](docs/benchmarks.md)
+
+---
+
+## Quick Start
+
+```bash
+pip install edgeval
+```
+
+Requires Python 3.8+, PyTorch, CUDA toolkit (nvcc), NumPy, SciPy, OpenCV, tqdm, click.
+
+CUDA kernels are compiled at install time — your machine needs a GPU and nvcc. If compilation fails:
+
+```bash
+# Debian/Ubuntu
+sudo apt install nvidia-cuda-toolkit build-essential
+
+# Verify nvcc
+nvcc --version
+```
+
+```bash
+# CLI — one command
+edgeval eval results/ --gpu --dataset BSDS
+
+# Python API — one function call
+from edgeval_cu.eval import gpu_edges_eval_img
+info, _ = gpu_edges_eval_img(edge_map, "GT/100007.mat", thrs=99, mode='simple')
+```
+
+---
+
+## Accuracy
+
+The +0.003 ODS bias comes from the Auction solver's `atomicMax` tie-breaking. It is systematic and stable across images. In practice:
+
+- Training monitoring: GPU simple mode — ~0.003 won't affect your model ranking
+- Final evaluation: CPU CSA mode — exact match to MATLAB reference
+
+| Image | GPU ODS | CSA ODS | Δ |
+|-------|---------|---------|---|
+| 100007 | 0.8601 | 0.8570 | +0.0031 |
+| 100039 | 0.7358 | 0.7347 | +0.0011 |
+| 100099 | 0.8091 | 0.8056 | +0.0035 |
+| 10081 | 0.7655 | 0.7631 | +0.0024 |
+| 101027 | 0.8749 | 0.8724 | +0.0026 |
+
+---
+
+## Project Structure
+
+```
+edgeval.cu/
+├── edgeval_cu/              # Package
+│   ├── eval.py              # Main pipeline — gpu_edges_eval_img()
+│   ├── auction.py           # GPU Auction wrapper
+│   ├── _compile.py          # Lazy CUDA kernel compilation
+│   ├── metrics.py           # ODS/OIS/AP/R50 computation
+│   ├── csa.py               # CPU CSA solver (exact reference)
+│   ├── nms_thin.py          # Zhang-Suen thinning LUTs
+│   ├── cli.py               # CLI: edgeval eval / show / nms
+│   └── cuda/                # CUDA kernels
+│       ├── auction_kernel.cu    # ε-Scaling Auction solver
+│       ├── edge_builder.cu      # Fused edge builder
+│       └── Makefile
+├── cxx/                     # CPU CSA C++ solver
+│   └── lib/solve_csa.so
+├── docs/
+│   ├── benchmarks.md        # Detailed benchmarks & config sweep
+│   └── optimization.md      # 8-stage optimization journey (5.7s→0.47s)
+└── README.md
+```
+
+---
+
+## Optimization Journey
+
+We went from 5.7s to 0.47s per image — a **12× within-GPU speedup** — through 8 systematic optimizations:
+
+| # | What | Speedup | Key Insight |
+|---|------|---------|-------------|
+| 1 | Simple bipartite graph | 4.9× | kOfN adds edges but not accuracy |
+| 2 | Fused CUDA edge builder | 1.2× | Merge cdist+mask+nonzero into 1 kernel |
+| 3 | GPU batched thinning | 1.0× | 99 masks in one conv2d batch |
+| 4 | Consecutive stall detection | 1.3× | Wait for real convergence, not first silence |
+| 5 | GPU annotator split | 1.3× | Sort by annotator on GPU, download once |
+| 6 | GPU nonzero | 1.03× | Keep masks on GPU, extract coords there |
+| 7 | Tuned ITERS_EPS0 | 1.2× | 500 iterations is plenty — system sweep proves it |
+| 8 | Directory restructure | — | Flat modules, clean imports |
+
+Details: [docs/optimization.md](docs/optimization.md)
+
+---
+
+## References
+
+- [Bertsekas, "Auction Algorithms" (1979)](https://web.mit.edu/dimitrib/www/Auction_Encycl.pdf) — Auction algorithm for assignment problems
+- [Guo & Hall, "Parallel Thinning" (1989)](https://gist.github.com/joefutrelle/562f25bbcf20691217b8) — Zhang-Suen morphological thinning
+- [HED Evaluation (MATLAB)](https://github.com/s9xie/hed_release-deprecated) — Original reference implementation
+- [edge-eval-python](https://github.com/Walstruzz/edge_eval_python) — Python CSA port
+- [Extended BSDS Benchmark](https://github.com/davidstutz/extended-berkeley-segmentation-benchmark) — C++ CSA solver
+
+---