findcrack 0.0.0__tar.gz

findcrack-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'  # Triggers on tags like v0.1.1
+
+permissions:
+  contents: write    # Required for creating GitHub Releases
+  id-token: write    # Required for OIDC Trusted Publishing to PyPI/TestPyPI
+
+jobs:
+  release:
+    name: Build, Publish and Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for setuptools-scm to fetch all tags for version resolution
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ">=3.11"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        continue-on-error: true
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

findcrack-0.0.0/.gitignore

@@ -0,0 +1,34 @@
+# vscode
+.vscode/
+
+# model
+models/
+*.pt
+*.onnx
+*.h5
+*.pkl
+dist/
+*.whl
+
+# Python
+__pycache__/
+*.ipynb
+*.pyc
+*.pyo
+
+# Models - critical: keep large files out of git!
+checkpoints/
+*.pt
+*.onnx
+*.h5
+*.pkl
+*.bin
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Virtual environment
+.venv/
+.env

findcrack-0.0.0/.python-version

@@ -0,0 +1 @@
+3.11

findcrack-0.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: findcrack
+Version: 0.0.0
+Summary: A deep learning crack detection package supporting U-Net and DeepCrack models with PyTorch and ONNX backends.
+Author: StrikerEurika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/StrikerEurika/findcrack
+Project-URL: Repository, https://github.com/StrikerEurika/findcrack
+Project-URL: Releases, https://github.com/StrikerEurika/findcrack/releases
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: albumentations>=2.0.8
+Requires-Dist: onnxruntime>=1.27.0
+Requires-Dist: opencv-python>=4.13.0.92
+Requires-Dist: torch>=2.6.0
+Requires-Dist: torchaudio>=2.6.0
+Requires-Dist: torchvision>=0.21.0
+
+# findcrack
+
+`findcrack` is a deep learning crack detection package designed for pixel-level segmentation on high-resolution images. It supports U-Net and DeepCrack architectures, providing an easy-to-use API for inference, model caching, and multi-backend execution (PyTorch & ONNX).
+
+---
+
+## Features
+
+- **Pre-trained Model Zoo**: Fetch pre-trained model weights (e.g., `Seg_UNET_CFD_actual_v1`, `Seg_UNET_CFD_actual_v2`) dynamically on demand.
+- **Unified Backend Engine**: Seamlessly executes either PyTorch (`.pth`/`.pt`) or ONNX (`.onnx`) models using the same standard interface.
+- **Sliding-Window Inference**: Efficiently process ultra-high-resolution images by dividing them into overlapping patches.
+- **Gaussian & Average Blending**: Reconstructs the full image from patches using overlapping Gaussian blending filters to eliminate edge-seam artifacts.
+- **Test-Time Augmentation (TTA)**: Performs multi-way augmentations (original, horizontal flip, vertical flip, and rotations) to produce highly robust prediction masks.
+- **Validation Metrics**: Compute standard segmentation metrics like IoU, Dice Coefficient, Precision, Recall, and Pixel Accuracy.
+
+---
+
+## Installation
+
+You can install `findcrack` directly from source or via PyPI (once published):
+
+```bash
+# Install via pip
+pip install findcrack
+
+# Or using uv
+uv add findcrack
+```
+
+---
+
+## Quickstart
+
+Here is how to load a pre-trained model and run crack detection on a large image:
+
+```python
+import cv2
+from findcrack import CrackInferencePipeline, load_model
+
+# 1. Load a pre-trained model from the official registry (or use your own URL)
+# The weights are downloaded dynamically from GitHub releases on first use.
+model = load_model("Seg_UNET_CFD_actual_v1", device="cuda")
+
+# 2. Setup the inference pipeline
+pipeline = CrackInferencePipeline(
+    model=model,
+    device="cuda",
+    patch_size=512,
+    overlap_ratio=0.2,
+    confidence_threhold=0.5,
+    use_tta=True  # Enables multi-way Test-Time Augmentation
+)
+
+# 3. Perform inference
+results = pipeline.predict("path/to/high_res_concrete.jpg")
+
+# The results dictionary contains:
+# - results["original_image"]: Original RGB image (numpy array)
+# - results["confidence_map"]: Float probability map [0.0 - 1.0]
+# - results["binary_mask"]: Binary segmentation mask [0 or 255]
+
+# Save the output mask
+cv2.imwrite("detected_cracks.png", results["binary_mask"])
+```
+
+---
+
+## API Reference
+
+### Model Loading & Caching
+
+#### `load_model(variant: str, device: str = "cpu", force_download: bool = False, architecture = None, **kwargs)`
+Loads a model variant from the local registry or directly from a remote HTTP(S) URL.
+
+- **Parameters**:
+  - `variant`: The name of a registered variant (e.g., `"Seg_UNET_CFD_actual_v1"`) or a direct HTTP(S) URL to a weights file.
+  - `device`: Target execution device (`"cpu"`, `"cuda"`, or `"mps"`).
+  - `force_download`: If `True`, re-downloads weights even if cached locally.
+  - `architecture`: PyTorch architecture class (e.g., `UNet`, `DeepCrack`) - required only if loading a raw `.pth`/`.pt` file from a custom URL.
+
+```python
+from findcrack import load_model, UNet
+
+# Load custom model weights directly from an external URL
+model = load_model(
+    variant="https://my-domain.com/custom_unet.pth",
+    architecture=UNet,
+    device="cuda"
+)
+```
+
+#### `list_models()`
+Returns a list of all pre-trained models available in the built-in registry.
+
+#### `register_model(name: str, url: str, architecture = None, kwargs: dict = None, backend: str = "pytorch")`
+Registers a custom variant dynamically at runtime.
+
+---
+
+### Pipeline Configuration
+
+#### `CrackInferencePipeline(model, device: str = "cuda", patch_size: int = 512, overlap_ratio: float = 0.2, confidence_threhold: float = 0.5, use_tta: bool = False)`
+Handles sliding window preprocessing, execution, TTA, and patching reconstruction.
+
+---
+
+## Directory Structure
+
+```text
+src/
+└── findcrack/
+    ├── __init__.py          # Main API endpoints (load_model, CrackInferencePipeline, etc.)
+    ├── metrics.py           # Segmentation evaluation metrics (IoU, Dice, etc.)
+    ├── patching.py          # Sliding window extraction and blend reconstruction
+    ├── pipeline.py          # Crack Inference Pipeline wrapper
+    ├── preprocess.py        # Color-space CLAHE contrast enhancement & transforms
+    ├── tta.py               # Test-Time Augmentation forward pass routines
+    └── models/
+        ├── __init__.py      # Model module exports
+        ├── unet.py          # U-Net model definition
+        ├── deepcrack.py     # DeepCrack model definition
+        ├── onnx_wrapper.py  # Wrapper for running ONNX models as nn.Modules
+        └── zoo.py           # Remote weight registry and cached loaders
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License.

findcrack-0.0.0/README.md

@@ -0,0 +1,130 @@
+# findcrack
+
+`findcrack` is a deep learning crack detection package designed for pixel-level segmentation on high-resolution images. It supports U-Net and DeepCrack architectures, providing an easy-to-use API for inference, model caching, and multi-backend execution (PyTorch & ONNX).
+
+---
+
+## Features
+
+- **Pre-trained Model Zoo**: Fetch pre-trained model weights (e.g., `Seg_UNET_CFD_actual_v1`, `Seg_UNET_CFD_actual_v2`) dynamically on demand.
+- **Unified Backend Engine**: Seamlessly executes either PyTorch (`.pth`/`.pt`) or ONNX (`.onnx`) models using the same standard interface.
+- **Sliding-Window Inference**: Efficiently process ultra-high-resolution images by dividing them into overlapping patches.
+- **Gaussian & Average Blending**: Reconstructs the full image from patches using overlapping Gaussian blending filters to eliminate edge-seam artifacts.
+- **Test-Time Augmentation (TTA)**: Performs multi-way augmentations (original, horizontal flip, vertical flip, and rotations) to produce highly robust prediction masks.
+- **Validation Metrics**: Compute standard segmentation metrics like IoU, Dice Coefficient, Precision, Recall, and Pixel Accuracy.
+
+---
+
+## Installation
+
+You can install `findcrack` directly from source or via PyPI (once published):
+
+```bash
+# Install via pip
+pip install findcrack
+
+# Or using uv
+uv add findcrack
+```
+
+---
+
+## Quickstart
+
+Here is how to load a pre-trained model and run crack detection on a large image:
+
+```python
+import cv2
+from findcrack import CrackInferencePipeline, load_model
+
+# 1. Load a pre-trained model from the official registry (or use your own URL)
+# The weights are downloaded dynamically from GitHub releases on first use.
+model = load_model("Seg_UNET_CFD_actual_v1", device="cuda")
+
+# 2. Setup the inference pipeline
+pipeline = CrackInferencePipeline(
+    model=model,
+    device="cuda",
+    patch_size=512,
+    overlap_ratio=0.2,
+    confidence_threhold=0.5,
+    use_tta=True  # Enables multi-way Test-Time Augmentation
+)
+
+# 3. Perform inference
+results = pipeline.predict("path/to/high_res_concrete.jpg")
+
+# The results dictionary contains:
+# - results["original_image"]: Original RGB image (numpy array)
+# - results["confidence_map"]: Float probability map [0.0 - 1.0]
+# - results["binary_mask"]: Binary segmentation mask [0 or 255]
+
+# Save the output mask
+cv2.imwrite("detected_cracks.png", results["binary_mask"])
+```
+
+---
+
+## API Reference
+
+### Model Loading & Caching
+
+#### `load_model(variant: str, device: str = "cpu", force_download: bool = False, architecture = None, **kwargs)`
+Loads a model variant from the local registry or directly from a remote HTTP(S) URL.
+
+- **Parameters**:
+  - `variant`: The name of a registered variant (e.g., `"Seg_UNET_CFD_actual_v1"`) or a direct HTTP(S) URL to a weights file.
+  - `device`: Target execution device (`"cpu"`, `"cuda"`, or `"mps"`).
+  - `force_download`: If `True`, re-downloads weights even if cached locally.
+  - `architecture`: PyTorch architecture class (e.g., `UNet`, `DeepCrack`) - required only if loading a raw `.pth`/`.pt` file from a custom URL.
+
+```python
+from findcrack import load_model, UNet
+
+# Load custom model weights directly from an external URL
+model = load_model(
+    variant="https://my-domain.com/custom_unet.pth",
+    architecture=UNet,
+    device="cuda"
+)
+```
+
+#### `list_models()`
+Returns a list of all pre-trained models available in the built-in registry.
+
+#### `register_model(name: str, url: str, architecture = None, kwargs: dict = None, backend: str = "pytorch")`
+Registers a custom variant dynamically at runtime.
+
+---
+
+### Pipeline Configuration
+
+#### `CrackInferencePipeline(model, device: str = "cuda", patch_size: int = 512, overlap_ratio: float = 0.2, confidence_threhold: float = 0.5, use_tta: bool = False)`
+Handles sliding window preprocessing, execution, TTA, and patching reconstruction.
+
+---
+
+## Directory Structure
+
+```text
+src/
+└── findcrack/
+    ├── __init__.py          # Main API endpoints (load_model, CrackInferencePipeline, etc.)
+    ├── metrics.py           # Segmentation evaluation metrics (IoU, Dice, etc.)
+    ├── patching.py          # Sliding window extraction and blend reconstruction
+    ├── pipeline.py          # Crack Inference Pipeline wrapper
+    ├── preprocess.py        # Color-space CLAHE contrast enhancement & transforms
+    ├── tta.py               # Test-Time Augmentation forward pass routines
+    └── models/
+        ├── __init__.py      # Model module exports
+        ├── unet.py          # U-Net model definition
+        ├── deepcrack.py     # DeepCrack model definition
+        ├── onnx_wrapper.py  # Wrapper for running ONNX models as nn.Modules
+        └── zoo.py           # Remote weight registry and cached loaders
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License.

findcrack-0.0.0/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from findcrack!")
+
+
+if __name__ == "__main__":
+    main()

findcrack-0.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "findcrack"
+dynamic = ["version"]
+description = "A deep learning crack detection package supporting U-Net and DeepCrack models with PyTorch and ONNX backends."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "StrikerEurika" }
+]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "albumentations>=2.0.8",
+    "onnxruntime>=1.27.0",
+    "opencv-python>=4.13.0.92",
+    "torch>=2.6.0",
+    "torchaudio>=2.6.0",
+    "torchvision>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/StrikerEurika/findcrack"
+Repository = "https://github.com/StrikerEurika/findcrack"
+Releases = "https://github.com/StrikerEurika/findcrack/releases"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools-scm]
+write_to = "src/findcrack/_version.py"

findcrack-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

findcrack-0.0.0/src/findcrack/__init__.py

@@ -0,0 +1,20 @@
+from .pipeline import CrackInferencePipeline
+from .models import load_model, UNet, DeepCrack, list_models, register_model
+from .metrics import calculate_metrics
+from .preprocess import apply_lab_clahe
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+__all__ = [
+    "CrackInferencePipeline",
+    "load_model",
+    "UNet",
+    "DeepCrack",
+    "calculate_metrics",
+    "apply_lab_clahe",
+    "list_models",
+    "register_model",
+]

findcrack-0.0.0/src/findcrack/metrics.py

@@ -0,0 +1,23 @@
+import numpy as np
+
+def calculate_metrics(y_true: np.ndarray, y_prediction: np.ndarray, epsilon: float = 1e-7) -> dict:
+    """
+    Calculates IoU, Dice, Precision, Recall, and Pixel Accuracy.
+    """
+    
+    y_true = y_true.astype(bool)
+    y_prediction = y_prediction.astype(bool)
+    
+    # True Positives, False Positives, True Negatives, False Negatives
+    TP = np.sum(y_true & y_prediction)
+    FP = np.sum(~y_true & y_prediction)
+    FN = np.sum(y_true & ~y_prediction)
+    TN = np.sum(~y_true & ~y_prediction)
+    
+    return {
+        "IoU": TP / (TP + FP + FN + epsilon),
+        "Dice": (2 * TP) / (2 * TP + FP + FN + epsilon),
+        "Precision": TP / (TP + FP + epsilon),
+        "Recall": TP / (TP + FN + epsilon),
+        "Pixel Accuracy": (TP + TN) / (TP + TN + FP + FN + epsilon)
+    }

findcrack-0.0.0/src/findcrack/models/__init__.py

@@ -0,0 +1,16 @@
+from .unet import UNet
+from .deepcrack import DeepCrack
+from .onnx_wrapper import ONNXModelWrapper
+from .zoo import load_model, MODEL_REGISTRY, list_models, register_model
+
+__all__ = [
+    "UNet",
+    "DeepCrack",
+    "ONNXModelWrapper",
+    "load_model",
+    "MODEL_REGISTRY",
+    "list_models",
+    "register_model",
+]
+
+

findcrack-0.0.0/src/findcrack/models/deepcrack.py

@@ -0,0 +1,93 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+class DoubleConv(nn.Module):
+    """(convolution => [BN] => ReLU) * 2"""
+    def __init__(self, in_channels, out_channels):
+        super().__init__()
+        self.double_conv = nn.Sequential(
+            nn.Conv2d(in_channels, out_channels, kernel_size=3, padding=1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.ReLU(inplace=True),
+            nn.Conv2d(out_channels, out_channels, kernel_size=3, padding=1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.ReLU(inplace=True)
+        )
+
+    def forward(self, x):
+        return self.double_conv(x)
+
+
+class DeepCrack(nn.Module):
+    """
+    DeepCrack: A Deep Hierarchical Feature Learning Architecture for Crack Segmentation.
+    Fuses hierarchical convolutional features from both the encoder and decoder stages 
+    at the same scale.
+    """
+    def __init__(self, n_channels: int = 3, n_classes: int = 1):
+        super().__init__()
+        self.n_channels = n_channels
+        self.n_classes = n_classes
+
+        # Encoder (downsampling blocks)
+        self.enc1 = DoubleConv(n_channels, 64)
+        self.enc2 = DoubleConv(64, 128)
+        self.enc3 = DoubleConv(128, 256)
+        self.enc4 = DoubleConv(256, 512)
+        self.enc5 = DoubleConv(512, 512)
+
+        self.pool = nn.MaxPool2d(kernel_size=2, stride=2)
+
+        # Decoder (upsampling & concatenation blocks)
+        self.dec5 = DoubleConv(512, 512)
+        self.dec4 = DoubleConv(512 + 512, 256)
+        self.dec3 = DoubleConv(256 + 256, 128)
+        self.dec2 = DoubleConv(128 + 128, 64)
+        self.dec1 = DoubleConv(64 + 64, 64)
+
+        # Side prediction layers (maps feature channels to class channels at each scale)
+        self.side1 = nn.Conv2d(64, n_classes, kernel_size=1)
+        self.side2 = nn.Conv2d(64, n_classes, kernel_size=1)
+        self.side3 = nn.Conv2d(128, n_classes, kernel_size=1)
+        self.side4 = nn.Conv2d(256, n_classes, kernel_size=1)
+        self.side5 = nn.Conv2d(512, n_classes, kernel_size=1)
+
+        # Fusion layer that combines all 5 side predictions into the final output
+        self.fuse = nn.Conv2d(n_classes * 5, n_classes, kernel_size=1)
+
+    def forward(self, x):
+        # 1. Encoder path
+        e1 = self.enc1(x)
+        e2 = self.enc2(self.pool(e1))
+        e3 = self.enc3(self.pool(e2))
+        e4 = self.enc4(self.pool(e3))
+        e5 = self.enc5(self.pool(e4))
+
+        # 2. Decoder path (with bilinear interpolation upsampling)
+        d5 = self.dec5(e5)
+        
+        d4_up = F.interpolate(d5, size=e4.shape[2:], mode='bilinear', align_corners=True)
+        d4 = self.dec4(torch.cat([d4_up, e4], dim=1))
+
+        d3_up = F.interpolate(d4, size=e3.shape[2:], mode='bilinear', align_corners=True)
+        d3 = self.dec3(torch.cat([d3_up, e3], dim=1))
+
+        d2_up = F.interpolate(d3, size=e2.shape[2:], mode='bilinear', align_corners=True)
+        d2 = self.dec2(torch.cat([d2_up, e2], dim=1))
+
+        d1_up = F.interpolate(d2, size=e1.shape[2:], mode='bilinear', align_corners=True)
+        d1 = self.dec1(torch.cat([d1_up, e1], dim=1))
+
+        # 3. Extract side predictions and upsample to input dimensions
+        h, w = x.shape[2:]
+        s1 = F.interpolate(self.side1(d1), size=(h, w), mode='bilinear', align_corners=True)
+        s2 = F.interpolate(self.side2(d2), size=(h, w), mode='bilinear', align_corners=True)
+        s3 = F.interpolate(self.side3(d3), size=(h, w), mode='bilinear', align_corners=True)
+        s4 = F.interpolate(self.side4(d4), size=(h, w), mode='bilinear', align_corners=True)
+        s5 = F.interpolate(self.side5(d5), size=(h, w), mode='bilinear', align_corners=True)
+
+        # 4. Fuse side predictions
+        fused = self.fuse(torch.cat([s1, s2, s3, s4, s5], dim=1))
+
+        return fused

findcrack-0.0.0/src/findcrack/models/onnx_wrapper.py

@@ -0,0 +1,35 @@
+import torch
+import torch.nn as nn
+import numpy as np
+
+class ONNXModelWrapper(nn.Module):
+    """
+    Wraps an ONNX Runtime InferenceSession inside a PyTorch nn.Module.
+    This allows running inference on ONNX models using the exact same code
+    and APIs as PyTorch models, supporting both CPU/GPU tensor operations
+    and test-time augmentation (TTA) pipelines.
+    """
+    def __init__(self, model_path: str, device: str = "cpu"):
+        super().__init__()
+        import onnxruntime as ort
+        
+        # Select execution providers based on the target device
+        if device == "cuda" or (isinstance(device, torch.device) and device.type == "cuda"):
+            providers = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+        else:
+            providers = ["CPUExecutionProvider"]
+            
+        self.session = ort.InferenceSession(model_path, providers=providers)
+        self.input_name = self.session.get_inputs()[0].name
+        self.output_name = self.session.get_outputs()[0].name
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # 1. Convert PyTorch tensor to NumPy array (typically expected as float32)
+        x_np = x.detach().cpu().numpy().astype(np.float32)
+        
+        # 2. Run inference using ONNX Runtime
+        outputs = self.session.run([self.output_name], {self.input_name: x_np})
+        
+        # 3. Convert prediction back to PyTorch tensor and move to the original device
+        out_tensor = torch.from_numpy(outputs[0]).to(x.device)
+        return out_tensor