0
# GUI Components
1

2
Interactive visualization and user interface components for image display, user interaction, and real-time visualization of computer vision results.
3

4
## Capabilities
5

6
### Image Display Window
7

8
Interactive window for displaying images with overlay capabilities and user interaction support.
9

10
```python { .api }
11
class image_window:
12
    """Interactive image display window with overlay support."""
13
    
14
    def __init__(self, img=None, title: str = None):
15
        """
16
        Create image display window.
17
        
18
        Args:
19
            img: Optional initial image to display
20
            title: Optional window title
21
        """
22
    
23
    def set_image(self, img):
24
        """
25
        Display image in window.
26
        
27
        Args:
28
            img: Image to display (numpy array or dlib image)
29
        """
30
    
31
    def set_title(self, title: str):
32
        """
33
        Set window title.
34
        
35
        Args:
36
            title: Window title text
37
        """
38
    
39
    def add_overlay(self, objects, color):
40
        """
41
        Add visual overlays to the displayed image.
42
        
43
        Args:
44
            objects: Objects to overlay (rectangles, lines, circles, detections)
45
            color: Overlay color (RGB tuple or color name)
46
        """
47
    
48
    def add_overlay_circle(self, center: point, radius: int, color):
49
        """
50
        Add circle overlay to image.
51
        
52
        Args:
53
            center: Circle center point
54
            radius: Circle radius in pixels
55
            color: Circle color
56
        """
57
    
58
    def clear_overlay(self):
59
        """Remove all overlays from the image display."""
60
    
61
    def wait_until_closed(self):
62
        """Block execution until the window is closed by user."""
63
    
64
    def is_closed(self) -> bool:
65
        """
66
        Check if window has been closed.
67
        
68
        Returns:
69
            True if window is closed, False otherwise
70
        """
71
    
72
    def get_next_double_click(self) -> point:
73
        """
74
        Wait for user to double-click in window.
75
        
76
        Returns:
77
            Point where user double-clicked
78
        """
79
    
80
    def wait_for_keypress(self, key):
81
        """
82
        Wait for specific key to be pressed.
83
        
84
        Args:
85
            key: Key to wait for (character or key code)
86
        """
87
    
88
    def get_next_keypress(self, get_keyboard_modifiers: bool = False):
89
        """
90
        Get next keypress from user.
91
        
92
        Args:
93
            get_keyboard_modifiers: Whether to return modifier key states
94
        
95
        Returns:
96
            Key pressed, optionally with modifier states
97
        """
98
```
99

100
### Keyboard Input Support
101

102
Enumerations and utilities for handling keyboard input and special keys.
103

104
```python { .api }
105
class non_printable_keyboard_keys:
106
    """Enumeration of special keyboard keys."""
107
    
108
    KEY_BACKSPACE: int
109
    KEY_SHIFT: int
110
    KEY_CTRL: int
111
    KEY_ALT: int
112
    KEY_PAUSE: int
113
    KEY_CAPS_LOCK: int
114
    KEY_ESC: int
115
    KEY_PAGE_UP: int
116
    KEY_PAGE_DOWN: int
117
    KEY_END: int
118
    KEY_HOME: int
119
    KEY_LEFT: int
120
    KEY_UP: int
121
    KEY_RIGHT: int
122
    KEY_DOWN: int
123
    KEY_INSERT: int
124
    KEY_DELETE: int
125
    KEY_SCROLL_LOCK: int
126
    KEY_F1: int
127
    KEY_F2: int
128
    KEY_F3: int
129
    KEY_F4: int
130
    KEY_F5: int
131
    KEY_F6: int
132
    KEY_F7: int
133
    KEY_F8: int
134
    KEY_F9: int
135
    KEY_F10: int
136
    KEY_F11: int
137
    KEY_F12: int
138

139
class keyboard_mod_keys:
140
    """Keyboard modifier key states."""
141
    
142
    KBD_MOD_NONE: int      # No modifiers
143
    KBD_MOD_SHIFT: int     # Shift key pressed
144
    KBD_MOD_CONTROL: int   # Ctrl key pressed
145
    KBD_MOD_ALT: int       # Alt key pressed
146
    KBD_MOD_META: int      # Meta/Windows key pressed
147
    KBD_MOD_CAPS_LOCK: int # Caps lock active
148
    KBD_MOD_NUM_LOCK: int  # Num lock active
149
    KBD_MOD_SCROLL_LOCK: int # Scroll lock active
150
```
151

152
**Usage Examples:**
153

154
### Basic Image Display
155
```python
156
import dlib
157
import cv2
158

159
# Load and display image
160
img = cv2.imread("photo.jpg")
161
win = dlib.image_window(img, "My Photo")
162

163
# Keep window open
164
win.wait_until_closed()
165
```
166

167
### Interactive Face Detection Visualization
168
```python
169
import dlib
170
import cv2
171

172
# Initialize face detector
173
detector = dlib.get_frontal_face_detector()
174

175
# Load image
176
img = cv2.imread("group_photo.jpg")
177
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
178

179
# Detect faces
180
faces = detector(gray)
181

182
# Create display window
183
win = dlib.image_window(img, "Face Detection Results")
184

185
# Add face overlays
186
for face in faces:
187
    win.add_overlay(face, "red")
188

189
# Add custom circle overlay
190
if len(faces) > 0:
191
    center = dlib.center(faces[0])
192
    win.add_overlay_circle(center, 50, "blue")
193

194
# Wait for user to close
195
win.wait_until_closed()
196
```
197

198
### Interactive Point Selection
199
```python
200
import dlib
201
import cv2
202

203
# Load image
204
img = cv2.imread("image.jpg")
205
win = dlib.image_window(img, "Click points")
206

207
print("Double-click to select points. Press ESC to finish.")
208

209
points = []
210
while True:
211
    # Get user input
212
    key_pressed = win.get_next_keypress()
213
    
214
    if key_pressed == dlib.non_printable_keyboard_keys.KEY_ESC:
215
        break
216
    
217
    # Check for double-click
218
    if not win.is_closed():
219
        try:
220
            point = win.get_next_double_click()
221
            points.append(point)
222
            
223
            # Add circle at clicked point
224
            win.add_overlay_circle(point, 5, "green") 
225
            print(f"Selected point: ({point.x}, {point.y})")
226
        except:
227
            pass
228

229
print(f"Selected {len(points)} points")
230
win.wait_until_closed()
231
```
232

233
### Real-time Detection Visualization
234
```python
235
import dlib
236
import cv2
237

238
# Initialize detector and window
239
detector = dlib.get_frontal_face_detector()
240
win = dlib.image_window(title="Live Face Detection")
241

242
# Video capture
243
cap = cv2.VideoCapture(0)
244

245
try:
246
    while True:
247
        ret, frame = cap.read()
248
        if not ret:
249
            break
250
        
251
        # Detect faces
252
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
253
        faces = detector(gray)
254
        
255
        # Display frame
256
        win.set_image(frame)
257
        win.clear_overlay()
258
        
259
        # Add face overlays
260
        for face in faces:
261
            win.add_overlay(face, "red")
262
        
263
        # Check if window closed
264
        if win.is_closed():
265
            break
266
        
267
        # Check for ESC key
268
        try:
269
            key = win.get_next_keypress()
270
            if key == dlib.non_printable_keyboard_keys.KEY_ESC:
271
                break
272
        except:
273
            pass
274

275
finally:
276
    cap.release()
277
```
278

279
### Advanced Overlay Visualization
280
```python
281
import dlib
282
import cv2
283

284
# Load image and initialize models
285
img = cv2.imread("face.jpg")
286
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
287

288
detector = dlib.get_frontal_face_detector()
289
predictor = dlib.shape_predictor("shape_predictor_68_face_landmarks.dat")
290

291
# Detect face and landmarks
292
faces = detector(gray)
293
win = dlib.image_window(img, "Face Analysis")
294

295
if len(faces) > 0:
296
    face = faces[0]
297
    landmarks = predictor(gray, face)
298
    
299
    # Add face rectangle overlay
300
    win.add_overlay(face, "red")
301
    
302
    # Add landmark points
303
    for i in range(landmarks.num_parts()):
304
        point = landmarks.part(i)
305
        win.add_overlay_circle(point, 2, "green")
306
    
307
    # Add eye regions with different colors
308
    left_eye_points = [landmarks.part(i) for i in range(36, 42)]
309
    right_eye_points = [landmarks.part(i) for i in range(42, 48)]
310
    
311
    # Create eye bounding rectangles
312
    left_eye_rect = dlib.rectangle(
313
        min(p.x for p in left_eye_points) - 10,
314
        min(p.y for p in left_eye_points) - 10,
315
        max(p.x for p in left_eye_points) + 10,
316
        max(p.y for p in left_eye_points) + 10
317
    )
318
    
319
    right_eye_rect = dlib.rectangle(
320
        min(p.x for p in right_eye_points) - 10,
321
        min(p.y for p in right_eye_points) - 10,
322
        max(p.x for p in right_eye_points) + 10,
323
        max(p.y for p in right_eye_points) + 10
324
    )
325
    
326
    win.add_overlay(left_eye_rect, "blue")
327
    win.add_overlay(right_eye_rect, "blue")
328
    
329
    # Add nose tip highlight
330
    nose_tip = landmarks.part(30)
331
    win.add_overlay_circle(nose_tip, 5, "yellow")
332

333
print("Press any key to close...")
334
win.get_next_keypress()
335
```
336

337
### Multi-Window Display
338
```python
339
import dlib
340
import cv2
341
import numpy as np
342

343
# Load image
344
img = cv2.imread("image.jpg")
345
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
346

347
# Create multiple processing results
348
blurred = dlib.gaussian_blur(gray, sigma=2.0)
349
edges = dlib.sobel_edge_detector(gray)
350
binary = dlib.threshold_image(gray)
351

352
# Display in separate windows
353
win_original = dlib.image_window(img, "Original")
354
win_blurred = dlib.image_window(blurred, "Blurred")
355
win_edges = dlib.image_window(edges[0], "Edges") # Horizontal gradients
356
win_binary = dlib.image_window(binary, "Binary")
357

358
# Wait for any window to close
359
while not (win_original.is_closed() or win_blurred.is_closed() or 
360
           win_edges.is_closed() or win_binary.is_closed()):
361
    try:
362
        # Check for keypress in any window
363
        win_original.wait_for_keypress(' ')
364
        break
365
    except:
366
        pass
367
```
368

369
The GUI components provide essential interactive capabilities for computer vision applications, enabling real-time visualization, user interaction, and debugging of image processing algorithms. The image_window class is particularly valuable for prototyping, demonstrations, and interactive analysis tools.