inventorado7 Claude Opus 4.5 commited on
Commit
00bac91
·
1 Parent(s): 62ed07d

Add GROUT Gradio app for grout line segmentation

Browse files

- U-Net with EfficientNet-B3 encoder
- Sliding window inference (default) for full resolution
- Model loaded from HuggingFace Hub
- Adjustable threshold and overlay options

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Files changed (3) hide show
  1. README.md +21 -1
  2. app.py +373 -0
  3. requirements.txt +6 -0
README.md CHANGED
@@ -11,4 +11,24 @@ license: mit
11
  short_description: Grout line detection for complex tessellated mosaics
12
  ---
13
 
14
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11
  short_description: Grout line detection for complex tessellated mosaics
12
  ---
13
 
14
+ # GROUT: Geometric Reasoning Over Unstructured Tessellations
15
+
16
+ Automatic grout line segmentation for mosaic images using deep learning.
17
+
18
+ ## Model
19
+
20
+ - **Architecture:** U-Net with EfficientNet-B3 encoder
21
+ - **Training:** Zero-shot transfer from synthetic mosaic data
22
+ - **Input:** RGB images of any size
23
+ - **Output:** Binary mask of grout lines
24
+
25
+ ## Features
26
+
27
+ - **Sliding Window Inference:** Process large images at full resolution
28
+ - **Multiple Geometry Support:** Works with Voronoi, Running Bond, and Vermiculatum patterns
29
+ - **Adjustable Threshold:** Fine-tune detection sensitivity
30
+
31
+ ## Links
32
+
33
+ - [GitHub Repository](https://github.com/advancedtech-sk/GROUT)
34
+ - [Model Weights](https://huggingface.co/advancedtech-sk/GROUT)
app.py ADDED
@@ -0,0 +1,373 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ GROUT: Geometric Reasoning Over Unstructured Tessellations
3
+ Gradio interface for mosaic grout line segmentation.
4
+
5
+ GitHub: https://github.com/advancedtech-sk/GROUT
6
+ """
7
+ import gradio as gr
8
+ import numpy as np
9
+ import cv2
10
+ import torch
11
+ import torch.nn as nn
12
+ from PIL import Image
13
+ from typing import Tuple
14
+ from huggingface_hub import hf_hub_download
15
+
16
+ # Try to import segmentation_models_pytorch
17
+ try:
18
+ import segmentation_models_pytorch as smp
19
+ except ImportError:
20
+ raise ImportError("Please install segmentation-models-pytorch: pip install segmentation-models-pytorch")
21
+
22
+
23
+ # ==================== Configuration ====================
24
+ class Config:
25
+ """Model configuration - must match training config."""
26
+ IMG_SIZE = 512
27
+ ENCODER = 'efficientnet-b3'
28
+ IN_CHANNELS = 3
29
+ NUM_CLASSES = 1
30
+ PREDICTION_THRESHOLD = 0.5
31
+ MEAN = [0.485, 0.456, 0.406]
32
+ STD = [0.229, 0.224, 0.225]
33
+
34
+ # Model repository
35
+ MODEL_REPO = "advancedtech-sk/GROUT"
36
+ MODEL_FILENAME = "grout_b3_zeroshot_v1.pth"
37
+
38
+
39
+ # ==================== Model Building ====================
40
+ def build_model(encoder: str, in_channels: int, num_classes: int):
41
+ """Build U-Net model with specified encoder."""
42
+ model = smp.Unet(
43
+ encoder_name=encoder,
44
+ encoder_weights=None,
45
+ in_channels=in_channels,
46
+ classes=num_classes,
47
+ activation=None,
48
+ )
49
+ return model
50
+
51
+
52
+ def load_model(device: str = 'cpu'):
53
+ """Load trained model from Hugging Face Hub."""
54
+ model = build_model(
55
+ encoder=Config.ENCODER,
56
+ in_channels=Config.IN_CHANNELS,
57
+ num_classes=Config.NUM_CLASSES,
58
+ )
59
+
60
+ # Download model from Hugging Face Hub
61
+ model_path = hf_hub_download(
62
+ repo_id=Config.MODEL_REPO,
63
+ filename=Config.MODEL_FILENAME
64
+ )
65
+
66
+ checkpoint = torch.load(model_path, map_location=device, weights_only=False)
67
+
68
+ if 'model_state_dict' in checkpoint:
69
+ model.load_state_dict(checkpoint['model_state_dict'])
70
+ else:
71
+ model.load_state_dict(checkpoint)
72
+
73
+ model.to(device)
74
+ model.eval()
75
+ return model
76
+
77
+
78
+ # ==================== Inference ====================
79
+ def preprocess_patch(image: np.ndarray) -> torch.Tensor:
80
+ """Preprocess a patch for inference (no resizing)."""
81
+ image = image.astype(np.float32) / 255.0
82
+ image = (image - np.array(Config.MEAN)) / np.array(Config.STD)
83
+ tensor = torch.from_numpy(image).permute(2, 0, 1).unsqueeze(0).float()
84
+ return tensor
85
+
86
+
87
+ def preprocess_image(image: np.ndarray) -> torch.Tensor:
88
+ """Preprocess image for inference with resize."""
89
+ image = cv2.resize(image, (Config.IMG_SIZE, Config.IMG_SIZE))
90
+ return preprocess_patch(image)
91
+
92
+
93
+ def post_process_mask(mask: np.ndarray) -> np.ndarray:
94
+ """Apply basic post-processing to clean up the mask."""
95
+ kernel = np.ones((3, 3), np.uint8)
96
+ mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
97
+ mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
98
+ return mask
99
+
100
+
101
+ def create_overlay(image: np.ndarray, mask: np.ndarray, color: Tuple[int, int, int] = (0, 255, 0), alpha: float = 0.5) -> np.ndarray:
102
+ """Create overlay of mask on original image."""
103
+ overlay = image.copy()
104
+ mask_bool = mask > 127
105
+ overlay[mask_bool] = (
106
+ overlay[mask_bool] * (1 - alpha) +
107
+ np.array(color) * alpha
108
+ ).astype(np.uint8)
109
+ return overlay
110
+
111
+
112
+ @torch.no_grad()
113
+ def predict_resize(model, image: np.ndarray, device: str = 'cpu', threshold: float = 0.5) -> Tuple[np.ndarray, np.ndarray]:
114
+ """Run inference using resize method."""
115
+ original_size = image.shape[:2]
116
+
117
+ # Preprocess with resize
118
+ input_tensor = preprocess_image(image).to(device)
119
+
120
+ # Inference
121
+ output = model(input_tensor)
122
+ prob = torch.sigmoid(output).squeeze().cpu().numpy()
123
+
124
+ # Threshold to binary
125
+ binary_mask = (prob > threshold).astype(np.uint8) * 255
126
+
127
+ # Resize back to original size
128
+ binary_mask = cv2.resize(binary_mask, (original_size[1], original_size[0]), interpolation=cv2.INTER_NEAREST)
129
+ prob_resized = cv2.resize(prob, (original_size[1], original_size[0]))
130
+
131
+ # Post-process
132
+ processed_mask = post_process_mask(binary_mask)
133
+
134
+ return prob_resized, processed_mask
135
+
136
+
137
+ @torch.no_grad()
138
+ def predict_sliding_window(model, image: np.ndarray, device: str = 'cpu', threshold: float = 0.5,
139
+ patch_size: int = 512, overlap: int = 64) -> Tuple[np.ndarray, np.ndarray]:
140
+ """Run inference using sliding window for large images."""
141
+ h, w = image.shape[:2]
142
+
143
+ # If image is small enough, use resize method
144
+ if h <= patch_size and w <= patch_size:
145
+ return predict_resize(model, image, device, threshold)
146
+
147
+ # Create output arrays
148
+ prob_map = np.zeros((h, w), dtype=np.float32)
149
+ count_map = np.zeros((h, w), dtype=np.float32)
150
+
151
+ stride = patch_size - overlap
152
+
153
+ # Calculate patch positions
154
+ patches_y = list(range(0, max(1, h - patch_size + 1), stride))
155
+ if h > patch_size and (h - patch_size) % stride != 0:
156
+ patches_y.append(h - patch_size)
157
+ if not patches_y:
158
+ patches_y = [0]
159
+
160
+ patches_x = list(range(0, max(1, w - patch_size + 1), stride))
161
+ if w > patch_size and (w - patch_size) % stride != 0:
162
+ patches_x.append(w - patch_size)
163
+ if not patches_x:
164
+ patches_x = [0]
165
+
166
+ # Process each patch
167
+ for y in patches_y:
168
+ for x in patches_x:
169
+ # Extract patch
170
+ y_end = min(y + patch_size, h)
171
+ x_end = min(x + patch_size, w)
172
+ patch = image[y:y_end, x:x_end]
173
+
174
+ # Pad if needed
175
+ if patch.shape[0] < patch_size or patch.shape[1] < patch_size:
176
+ padded = np.zeros((patch_size, patch_size, 3), dtype=patch.dtype)
177
+ padded[:patch.shape[0], :patch.shape[1]] = patch
178
+ patch = padded
179
+
180
+ # Preprocess and predict
181
+ input_tensor = preprocess_patch(patch).to(device)
182
+ output = model(input_tensor)
183
+ prob = torch.sigmoid(output).squeeze().cpu().numpy()
184
+
185
+ # Accumulate (only the valid region)
186
+ valid_h = y_end - y
187
+ valid_w = x_end - x
188
+ prob_map[y:y_end, x:x_end] += prob[:valid_h, :valid_w]
189
+ count_map[y:y_end, x:x_end] += 1
190
+
191
+ # Average overlapping predictions
192
+ prob_map = prob_map / np.maximum(count_map, 1)
193
+
194
+ # Threshold to binary mask
195
+ binary_mask = (prob_map > threshold).astype(np.uint8) * 255
196
+
197
+ # Post-process
198
+ processed_mask = post_process_mask(binary_mask)
199
+
200
+ return prob_map, processed_mask
201
+
202
+
203
+ # ==================== Gradio Interface ====================
204
+ # Global model variable
205
+ MODEL = None
206
+ DEVICE = 'cuda' if torch.cuda.is_available() else 'cpu'
207
+
208
+
209
+ def load_model_on_startup():
210
+ """Load model when app starts."""
211
+ global MODEL
212
+ try:
213
+ MODEL = load_model(DEVICE)
214
+ print(f"Model loaded successfully on {DEVICE}")
215
+ except Exception as e:
216
+ print(f"Error loading model: {e}")
217
+
218
+
219
+ def segment_grout(
220
+ input_image: np.ndarray,
221
+ inference_mode: str = "Sliding Window (Quality)",
222
+ threshold: float = 0.5,
223
+ overlap: int = 64,
224
+ overlay_color: str = "Green",
225
+ overlay_opacity: float = 0.5,
226
+ ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, str]:
227
+ """
228
+ Main inference function for Gradio.
229
+ """
230
+ if MODEL is None:
231
+ raise gr.Error("Model not loaded. Please refresh the page.")
232
+
233
+ if input_image is None:
234
+ raise gr.Error("Please upload an image.")
235
+
236
+ # Ensure RGB format
237
+ if len(input_image.shape) == 2:
238
+ input_image = cv2.cvtColor(input_image, cv2.COLOR_GRAY2RGB)
239
+ elif input_image.shape[2] == 4:
240
+ input_image = cv2.cvtColor(input_image, cv2.COLOR_RGBA2RGB)
241
+
242
+ h, w = input_image.shape[:2]
243
+
244
+ # Select inference method
245
+ if inference_mode == "Resize (Fast)":
246
+ prob, mask = predict_resize(MODEL, input_image, DEVICE, threshold)
247
+ mode_used = f"Resize: {w}x{h} -> {Config.IMG_SIZE}x{Config.IMG_SIZE} -> {w}x{h}"
248
+ else: # Sliding Window (Quality) - default
249
+ prob, mask = predict_sliding_window(MODEL, input_image, DEVICE, threshold,
250
+ patch_size=Config.IMG_SIZE, overlap=overlap)
251
+ mode_used = f"Sliding Window: {w}x{h}, patch={Config.IMG_SIZE}, overlap={overlap}"
252
+
253
+ # Color mapping
254
+ colors = {
255
+ "Green": (0, 255, 0),
256
+ "Red": (255, 0, 0),
257
+ "Blue": (0, 0, 255),
258
+ "Yellow": (255, 255, 0),
259
+ "Cyan": (0, 255, 255),
260
+ "Magenta": (255, 0, 255),
261
+ }
262
+ color = colors.get(overlay_color, (0, 255, 0))
263
+
264
+ # Create overlay
265
+ overlay = create_overlay(input_image, mask, color=color, alpha=overlay_opacity)
266
+
267
+ # Create probability heatmap
268
+ heatmap = cv2.applyColorMap((prob * 255).astype(np.uint8), cv2.COLORMAP_JET)
269
+ heatmap = cv2.cvtColor(heatmap, cv2.COLOR_BGR2RGB)
270
+
271
+ return mask, overlay, heatmap, mode_used
272
+
273
+
274
+ # Create Gradio interface
275
+ def create_demo():
276
+ """Create the Gradio demo interface."""
277
+
278
+ with gr.Blocks(title="GROUT: Geometric Reasoning Over Unstructured Tessellations", theme=gr.themes.Soft()) as demo:
279
+ gr.Markdown(
280
+ """
281
+ # GROUT: Geometric Reasoning Over Unstructured Tessellations
282
+
283
+ Upload an image of a mosaic to detect and segment the grout lines between tiles.
284
+
285
+ **Model:** U-Net with EfficientNet-B3 encoder trained on synthetic mosaic data.
286
+
287
+ [GitHub Repository](https://github.com/advancedtech-sk/GROUT) | [Model Weights](https://huggingface.co/advancedtech-sk/GROUT)
288
+
289
+ ---
290
+ """
291
+ )
292
+
293
+ with gr.Row():
294
+ with gr.Column():
295
+ input_image = gr.Image(label="Input Image", type="numpy")
296
+
297
+ with gr.Group():
298
+ gr.Markdown("### Inference Settings")
299
+ inference_mode = gr.Radio(
300
+ choices=["Sliding Window (Quality)", "Resize (Fast)"],
301
+ value="Sliding Window (Quality)",
302
+ label="Inference Mode",
303
+ info="Sliding Window preserves full resolution, Resize is faster"
304
+ )
305
+ threshold = gr.Slider(
306
+ minimum=0.1,
307
+ maximum=0.9,
308
+ value=0.5,
309
+ step=0.05,
310
+ label="Detection Threshold",
311
+ info="Lower = more sensitive, Higher = more strict"
312
+ )
313
+ overlap = gr.Slider(
314
+ minimum=0,
315
+ maximum=256,
316
+ value=64,
317
+ step=16,
318
+ label="Patch Overlap (Sliding Window)",
319
+ info="Higher = smoother results, slower processing"
320
+ )
321
+
322
+ with gr.Group():
323
+ gr.Markdown("### Visualization Settings")
324
+ overlay_color = gr.Dropdown(
325
+ choices=["Green", "Red", "Blue", "Yellow", "Cyan", "Magenta"],
326
+ value="Green",
327
+ label="Overlay Color"
328
+ )
329
+ overlay_opacity = gr.Slider(
330
+ minimum=0.1,
331
+ maximum=1.0,
332
+ value=0.5,
333
+ step=0.1,
334
+ label="Overlay Opacity"
335
+ )
336
+
337
+ segment_btn = gr.Button("Segment Grout Lines", variant="primary")
338
+
339
+ with gr.Column():
340
+ output_mask = gr.Image(label="Grout Mask (Binary)")
341
+ output_overlay = gr.Image(label="Overlay on Original")
342
+ output_heatmap = gr.Image(label="Probability Heatmap")
343
+ mode_info = gr.Textbox(label="Mode Used", interactive=False)
344
+
345
+ segment_btn.click(
346
+ fn=segment_grout,
347
+ inputs=[input_image, inference_mode, threshold, overlap, overlay_color, overlay_opacity],
348
+ outputs=[output_mask, output_overlay, output_heatmap, mode_info],
349
+ )
350
+
351
+ gr.Markdown(
352
+ """
353
+ ---
354
+ **Inference Modes:**
355
+ - **Sliding Window (Quality):** Processes image in overlapping 512x512 patches, preserves full resolution
356
+ - **Resize (Fast):** Resizes image to 512x512, faster but may lose detail on large images
357
+
358
+ **Tips:**
359
+ - For large images (>512px), Sliding Window gives best quality
360
+ - Increase overlap for smoother results at patch boundaries
361
+ - The heatmap shows model confidence (red = high, blue = low)
362
+ - Lower threshold for faint grout lines, higher for cleaner results
363
+ """
364
+ )
365
+
366
+ return demo
367
+
368
+
369
+ # Main entry point
370
+ if __name__ == "__main__":
371
+ load_model_on_startup()
372
+ demo = create_demo()
373
+ demo.launch()
requirements.txt ADDED
@@ -0,0 +1,6 @@
 
 
 
 
 
 
 
1
+ torch
2
+ torchvision
3
+ segmentation-models-pytorch
4
+ opencv-python-headless
5
+ numpy
6
+ huggingface_hub