Add Hugging Face-ready wrapper for HitDetector model

This adds a standalone script for running inference with the HitDetector model,
originally trained using code from:

https://github.com/andrewromanenco/hit-detector

The wrapper is Hugging Face-compatible and includes a pipeline interface
for integration with the Hugging Face Hub and Spaces.

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Romanenco <andrew@romanenco.com>
+
+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.

README.md

@@ -0,0 +1,80 @@
+---
+license: mit
+library_name: hitdetector
+pipeline_tag: image-classification
+tags:
+  - pytorch
+  - sliding-window
+  - computer-vision
+  - hole-detection
+  - custom-pipeline
+---
+
+# 🎯 Hit Detector Model
+
+This PyTorch-based CNN detects holes on boards or paper using a sliding window approach. It was trained on image patches of size **24×24**. The model scans larger images with this patch size to detect regions of interest.
+
+> Holes or defects must approximately fit within a 20×20 region to be accurately detected.
+
+## 📥 Model Inputs & Outputs
+ 
+- Input: RGB or grayscale image (PIL.Image)
+- Output: Annotated PIL.Image with red (or specified color) squares highlighting detected holes
+
+![Example result](example.png)
+
+## 🚀 Quick Start
+
+### 🧠 Inference in Python
+
+```python
+from PIL import Image
+from  pipeline  import  HitDetectorPipeline
+
+pipe  =  HitDetectorPipeline("model.pt")
+
+img  = Image.open("input.png")
+result  =  pipe(img)
+result.save("output.png")
+print("✅ Output saved to output.png")
+```
+
+### 📦 Installation
+
+```bash
+pip install -r requirements.txt
+```
+## 🧪 Testing in Docker
+
+To test the model or pipeline scripts inside a clean container:
+
+```bash
+cd <project folder>
+docker run -it --rm -p 7860:7860 -v $PWD:/appx:rw romanenco/python-tool-chain /bin/bash
+cd /appx
+pip install -r requirements.txt
+python test_pipeline.py
+```
+
+You should see output.png generated as a result.
+
+### 🌐 Run Gradio UI
+
+```bash
+pip install gradio
+python app.py
+```
+
+Open [http://127.0.0.1:7860](http://127.0.0.1:7860) to test the interactive web UI.
+
+## 🛠 Retrain or Fine-Tune
+
+To retrain the model on your own dataset, use the full pipeline and tools from the [main training repo](https://github.com/andrewromanenco/hit-detector), which includes:
+
+- 📁 Tools to extract training patches from full images
+- 🧠 Training script
+- 📈 Inference script
+
+## 📄 License
+
+MIT

app.py

@@ -0,0 +1,14 @@
+import gradio as gr
+from PIL import Image
+from pipeline import HitDetectorPipeline
+
+pipe = HitDetectorPipeline("model.pt")
+
+def detect(image: Image.Image):
+    return pipe(image)
+
+gr.Interface(
+    fn=detect,
+    inputs=gr.Image(type="pil"),
+    outputs=gr.Image(type="pil"),
+    title="Hit Detector").launch(server_name="0.0.0.0", server_port=7860)

model.py

@@ -0,0 +1,29 @@
+import torch
+from torch import nn
+
+class SimpleCNN(nn.Module):
+    def __init__(self, sample_input):
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(1, 16, 3, padding=1),
+            nn.ReLU(),
+            nn.MaxPool2d(2),
+            nn.Conv2d(16, 32, 3, padding=1),
+            nn.ReLU(),
+            nn.MaxPool2d(2),
+        )
+
+        with torch.no_grad():
+            dummy_output = self.features(sample_input.unsqueeze(0))
+            self.flattened_size = dummy_output.view(1, -1).size(1)
+
+        self.classifier = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(self.flattened_size, 64),
+            nn.ReLU(),
+            nn.Linear(64, 1)
+        )
+
+    def forward(self, x):
+        x = self.features(x)
+        return self.classifier(x)

pipeline.py

@@ -0,0 +1,79 @@
+import torch
+from PIL import Image
+from torchvision import transforms
+from model import SimpleCNN
+
+PATCH_SIZE = 24
+
+def hex_to_rgb(hex_color):
+    hex_color = hex_color.strip("#")
+    return tuple(int(hex_color[i:i + 2], 16) for i in (0, 2, 4))
+
+def load_model(model_path):
+    sample_input = torch.randn(1, PATCH_SIZE, PATCH_SIZE)
+    model = SimpleCNN(sample_input)
+    model.load_state_dict(torch.load(model_path, map_location=torch.device("cpu")))
+    model.eval()
+    return model, PATCH_SIZE
+
+def run_inference(
+    model: torch.nn.Module,
+    image: Image.Image,
+    original: Image.Image,
+    color: tuple,
+    opacity: int,
+    target_label: int,
+    patch_size: int,
+    stride: int = 4
+):
+    transform = transforms.ToTensor()
+
+    width, height = image.size
+    total_patches = ((width - patch_size) // stride + 1) * ((height - patch_size) // stride + 1)
+
+    overlay = Image.new("RGBA", original.size, (0, 0, 0, 0))
+
+    done = 0
+    last_percent_reported = -1
+    for y in range(0, height - patch_size + 1, stride):
+        for x in range(0, width - patch_size + 1, stride):
+            patch = image.crop((x, y, x + patch_size, y + patch_size))
+            tensor = transform(patch).unsqueeze(0)
+            with torch.no_grad():
+                pred = model(tensor)
+                predicted_label = int(pred.item() > 0.9)
+
+            if predicted_label == target_label:
+                patch_overlay = Image.new("RGBA", (patch_size, patch_size), color + (opacity,))
+                overlay.paste(patch_overlay, (x, y), patch_overlay)
+
+            done += 1
+            percent = int(done / total_patches * 100)
+            if percent != last_percent_reported:
+                print(f"\rProgress: {percent:3d}% ", end="", flush=True)
+                last_percent_reported = percent
+
+    print("\nDone.")
+    blended = Image.alpha_composite(original.convert("RGBA"), overlay)
+    return blended.convert("RGB")
+
+
+class HitDetectorPipeline:
+    def __init__(self, model_path="model.pt", color="#FF0000", opacity=128, target_label=1):
+        self.model, self.patch_size = load_model(model_path)
+        self.color = hex_to_rgb(color)
+        self.opacity = opacity
+        self.target_label = target_label
+
+    def __call__(self, image: Image.Image) -> Image.Image:
+        grayscale = image.convert("L")
+        original = image.convert("RGB")
+        return run_inference(
+            model=self.model,
+            image=grayscale,
+            original=original,
+            color=self.color,
+            opacity=self.opacity,
+            target_label=self.target_label,
+            patch_size=self.patch_size
+        )

requirements.txt

@@ -0,0 +1,6 @@
+torch>=2.7.0,<3.0.0
+torchvision>=0.22.0,<0.23.0
+Pillow
+tqdm>=4.67.1,<5.0.0
+scikit-learn>=1.6.1,<2.0.0
+opencv-python>=4.11.0.86,<5.0.0.0

test_pipeline.py

@@ -0,0 +1,9 @@
+from PIL import Image
+from pipeline import HitDetectorPipeline
+
+pipe = HitDetectorPipeline("model.pt")
+
+img = Image.open("input.png")
+result = pipe(img)
+result.save("output.png")
+print("✅ Output saved to output.png")