0
# User Interface Components
1

2
Interactive widgets and UI elements including sliders, buttons, scalar bars, legends, and measurement tools for creating interactive 3D applications. These components enable users to build sophisticated interactive visualizations with custom controls and feedback.
3

4
## Capabilities
5

6
### Interactive Controls
7

8
Slider widgets for real-time parameter adjustment and interactive control of visualization properties.
9

10
```python { .api }
11
class Slider2D:
12
    """
13
    2D slider widget for interactive parameter control.
14
    
15
    Parameters:
16
    - func: callable
17
        Function to call when slider value changes
18
    - xmin: float
19
        Minimum slider value
20
    - xmax: float
21
        Maximum slider value
22
    - value: float, optional
23
        Initial slider value
24
    - pos: int or tuple, default 4
25
        Slider position (corner index or (x,y) coordinates)
26
    - title: str, default ""
27
        Slider title text
28
    - font: str, default "Calco"
29
        Font name for text
30
    - titleSize: float, default 1
31
        Title text size
32
    - c: str or tuple, optional
33
        Slider color
34
    - alpha: float, default 1
35
        Slider transparency
36
    - showValue: bool, default True
37
        Display current value
38
    - delayed: bool, default False
39
        Delay callback until mouse release
40
    - **options: keyword arguments
41
        Additional slider options
42
    """
43
    def __init__(
44
        self, 
45
        func, 
46
        xmin, 
47
        xmax, 
48
        value=None, 
49
        pos=4, 
50
        title="", 
51
        font="Calco", 
52
        titleSize=1, 
53
        c=None, 
54
        alpha=1, 
55
        showValue=True, 
56
        delayed=False, 
57
        **options
58
    ): ...
59

60
class Slider3D:
61
    """
62
    3D slider widget embedded in the 3D scene.
63
    
64
    Parameters:
65
    - func: callable
66
        Function to call when slider value changes
67
    - xmin: float
68
        Minimum slider value
69
    - xmax: float
70
        Maximum slider value
71
    - value: float, optional
72
        Initial slider value
73
    - pos: tuple, default (0, 0, 0)
74
        3D position in scene
75
    - normal: tuple, default (0, 0, 1)
76
        Slider orientation normal
77
    - length: float, default 1
78
        Slider track length
79
    - width: float, default 0.1
80
        Slider track width
81
    - c: str or tuple, default "red"
82
        Slider color
83
    - alpha: float, default 1
84
        Slider transparency
85
    """
86
    def __init__(
87
        self, 
88
        func, 
89
        xmin, 
90
        xmax, 
91
        value=None, 
92
        pos=(0, 0, 0), 
93
        normal=(0, 0, 1), 
94
        length=1, 
95
        width=0.1, 
96
        c="red", 
97
        alpha=1
98
    ): ...
99

100
class Button:
101
    """
102
    Interactive button widget.
103
    
104
    Parameters:
105
    - func: callable
106
        Function to call when button is pressed
107
    - states: list, default ["On", "Off"]
108
        Button state labels
109
    - c: list or str, default ["white", "gray"]
110
        Button colors for each state
111
    - bc: list or str, default ["green", "red"]
112
        Border colors for each state
113
    - pos: tuple, default (0.7, 0.1)
114
        Button position (normalized coordinates)
115
    - size: int, default 24
116
        Button size
117
    - font: str, default ""
118
        Font name for button text
119
    - bold: bool, default False
120
        Use bold text
121
    - italic: bool, default False
122
        Use italic text
123
    """
124
    def __init__(
125
        self, 
126
        func, 
127
        states=["On", "Off"], 
128
        c=["white", "gray"], 
129
        bc=["green", "red"], 
130
        pos=(0.7, 0.1), 
131
        size=24, 
132
        font="", 
133
        bold=False, 
134
        italic=False
135
    ): ...
136

137
class CheckBox:
138
    """
139
    Checkbox widget for boolean input.
140
    
141
    Parameters:
142
    - label: str
143
        Checkbox label text
144
    - value: bool, default False
145
        Initial checkbox state
146
    - pos: tuple, default (0.8, 0.1)
147
        Checkbox position (normalized coordinates)
148
    - c: str or tuple, default "white"
149
        Checkbox color
150
    - bc: str or tuple, default "black"
151
        Border color
152
    - size: int, default 24
153
        Checkbox size
154
    - font: str, default ""
155
        Font name for label
156
    """
157
    def __init__(
158
        self, 
159
        label, 
160
        value=False, 
161
        pos=(0.8, 0.1), 
162
        c="white", 
163
        bc="black", 
164
        size=24, 
165
        font=""
166
    ): ...
167
```
168

169
### Information Display Components
170

171
Components for displaying legends, scalar bars, and informational overlays.
172

173
```python { .api }
174
class ScalarBar:
175
    """
176
    2D scalar bar for displaying color mapping scales.
177
    
178
    Parameters:
179
    - obj: vedo object
180
        Object to create scalar bar for
181
    - title: str, default ""
182
        Scalar bar title
183
    - pos: tuple, default (0.775, 0.05)
184
        Position (normalized coordinates)
185
    - titleYOffset: int, default 15
186
        Title vertical offset
187
    - titleFontSize: int, default 12
188
        Title font size
189
    - size: tuple, default (None, None)
190
        Scalar bar size
191
    - nlabels: int, optional
192
        Number of labels
193
    - c: str or tuple, optional
194
        Text color
195
    - horizontal: bool, default False
196
        Horizontal orientation
197
    - useAlpha: bool, default True
198
        Include transparency in bar
199
    """
200
    def __init__(
201
        self, 
202
        obj, 
203
        title="", 
204
        pos=(0.775, 0.05), 
205
        titleYOffset=15, 
206
        titleFontSize=12, 
207
        size=(None, None), 
208
        nlabels=None, 
209
        c=None, 
210
        horizontal=False, 
211
        useAlpha=True
212
    ): ...
213

214
class ScalarBar3D:
215
    """
216
    3D scalar bar embedded in the scene.
217
    
218
    Parameters:
219
    - obj: vedo object
220
        Object to create scalar bar for
221
    - title: str, default ""
222
        Scalar bar title
223
    - pos: tuple, optional
224
        3D position in scene
225
    - normal: tuple, default (0, 0, 1)
226
        Bar orientation normal
227
    - sx: float, default 1
228
        Bar width
229
    - sy: float, default 8
230
        Bar height
231
    - nlabels: int, default 9
232
        Number of labels
233
    - c: str or tuple, default "black"
234
        Text color
235
    - italic: bool, default False
236
        Use italic text
237
    """
238
    def __init__(
239
        self, 
240
        obj, 
241
        title="", 
242
        pos=None, 
243
        normal=(0, 0, 1), 
244
        sx=1, 
245
        sy=8, 
246
        nlabels=9, 
247
        c="black", 
248
        italic=False
249
    ): ...
250

251
class LegendBox:
252
    """
253
    Legend box for displaying object labels and colors.
254
    
255
    Parameters:
256
    - entries: list
257
        List of (label, color) tuples
258
    - markers: list, optional
259
        Custom markers for each entry
260
    - c: str or tuple, default "black"
261
        Text color
262
    - font: str, default ""
263
        Font name
264
    - width: float, default 0.18
265
        Legend box width
266
    - height: float, optional
267
        Legend box height
268
    - pos: tuple, default "top-right"
269
        Legend position
270
    """
271
    def __init__(
272
        self, 
273
        entries, 
274
        markers=None, 
275
        c="black", 
276
        font="", 
277
        width=0.18, 
278
        height=None, 
279
        pos="top-right"
280
    ): ...
281

282
class Icon:
283
    """
284
    Display icon images in the scene.
285
    
286
    Parameters:
287
    - name: str
288
        Icon name or file path
289
    - pos: tuple, default (0.1, 0.1)
290
        Icon position (normalized coordinates)
291
    - size: float, default 0.06
292
        Icon size
293
    """
294
    def __init__(self, name, pos=(0.1, 0.1), size=0.06): ...
295
```
296

297
### Lighting Components
298

299
Lighting controls and visualization aids for scene illumination.
300

301
```python { .api }
302
class Light:
303
    """
304
    Light source for scene illumination.
305
    
306
    Parameters:
307
    - pos: tuple, default (1, 1, 1)
308
        Light position coordinates
309
    - focalPoint: tuple, default (0, 0, 0)
310
        Point the light is focused on
311
    - deg: float, default 180
312
        Light cone angle in degrees
313
    - c: str or tuple, default "white"
314
        Light color
315
    - intensity: float, default 1
316
        Light intensity
317
    """
318
    def __init__(
319
        self, 
320
        pos=(1, 1, 1), 
321
        focalPoint=(0, 0, 0), 
322
        deg=180, 
323
        c="white", 
324
        intensity=1
325
    ): ...
326
```
327

328
### Coordinate Systems and References
329

330
Components for displaying coordinate systems, axes, and reference frames.
331

332
```python { .api }
333
class Axes:
334
    """
335
    Coordinate axes display.
336
    
337
    Parameters:
338
    - obj: vedo object, optional
339
        Object to create axes for
340
    - xtitle: str, default "x"
341
        X-axis label
342
    - ytitle: str, default "y"
343
        Y-axis label
344
    - ztitle: str, default "z"
345
        Z-axis label
346
    - xrange: tuple, optional
347
        X-axis range
348
    - yrange: tuple, optional
349
        Y-axis range
350
    - zrange: tuple, optional
351
        Z-axis range
352
    - c: str or tuple, default "black"
353
        Axes color
354
    - alpha: float, default 1
355
        Axes transparency
356
    - tips: bool, default True
357
        Show arrow tips
358
    - labels: bool, default True
359
        Show axis labels
360
    """
361
    def __init__(
362
        self, 
363
        obj=None, 
364
        xtitle="x", 
365
        ytitle="y", 
366
        ztitle="z", 
367
        xrange=None, 
368
        yrange=None, 
369
        zrange=None, 
370
        c="black", 
371
        alpha=1, 
372
        tips=True, 
373
        labels=True
374
    ): ...
375

376
class RendererFrame:
377
    """
378
    Frame around the renderer viewport.
379
    
380
    Parameters:
381
    - c: str or tuple, default "black"
382
        Frame color
383
    - alpha: float, default 1
384
        Frame transparency
385
    - lw: float, default 1
386
        Frame line width
387
    - padding: float, default 0
388
        Frame padding
389
    """
390
    def __init__(self, c="black", alpha=1, lw=1, padding=0): ...
391
```
392

393
### Measurement and Analysis Tools
394

395
Interactive tools for measuring distances, angles, and other geometric properties.
396

397
```python { .api }
398
class Ruler2D:
399
    """
400
    2D ruler for measuring distances on screen.
401
    
402
    Parameters:
403
    - p1: tuple
404
        First point (screen coordinates)
405
    - p2: tuple
406
        Second point (screen coordinates)
407
    - units: str, default ""
408
        Measurement units label
409
    - c: str or tuple, default "black"
410
        Ruler color
411
    - alpha: float, default 1
412
        Ruler transparency
413
    - lw: float, default 1
414
        Line width
415
    """
416
    def __init__(self, p1, p2, units="", c="black", alpha=1, lw=1): ...
417

418
class Ruler3D:
419
    """
420
    3D ruler for measuring distances in world coordinates.
421
    
422
    Parameters:
423
    - p1: tuple
424
        First 3D point
425
    - p2: tuple
426
        Second 3D point
427
    - units: str, default ""
428
        Measurement units label
429
    - c: str or tuple, default "black"
430
        Ruler color
431
    - alpha: float, default 1
432
        Ruler transparency
433
    - lw: float, default 2
434
        Line width
435
    """
436
    def __init__(self, p1, p2, units="", c="black", alpha=1, lw=2): ...
437

438
class DistanceTool:
439
    """
440
    Interactive distance measurement tool.
441
    
442
    Parameters:
443
    - c: str or tuple, default "red"
444
        Tool color
445
    - lw: float, default 2
446
        Line width
447
    - units: str, default ""
448
        Measurement units
449
    """
450
    def __init__(self, c="red", lw=2, units=""): ...
451

452
class SplineTool:
453
    """
454
    Interactive spline creation and editing tool.
455
    
456
    Parameters:
457
    - points: list, optional
458
        Initial control points
459
    - pc: str or tuple, default "red"
460
        Point color
461
    - lc: str or tuple, default "blue"
462
        Line color
463
    - alpha: float, default 1
464
        Tool transparency
465
    """
466
    def __init__(self, points=None, pc="red", lc="blue", alpha=1): ...
467
```
468

469
### Information and Annotation Tools
470

471
Tools for displaying contextual information and interactive annotations.
472

473
```python { .api }
474
class Hover:
475
    """
476
    Display information when hovering over objects.
477
    
478
    Parameters:
479
    - obj: vedo object
480
        Object to attach hover information to
481
    - c: str or tuple, default "black"
482
        Text color
483
    - bc: str or tuple, default "yellow"
484
        Background color
485
    - alpha: float, default 1
486
        Information box transparency
487
    - font: str, default ""
488
        Font name
489
    """
490
    def __init__(self, obj, c="black", bc="yellow", alpha=1, font=""): ...
491

492
class Flagpost:
493
    """
494
    Flag-style annotation pointing to specific locations.
495
    
496
    Parameters:
497
    - txt: str
498
        Flag text
499
    - pos: tuple
500
        3D position to point to
501
    - height: float, default 1
502
        Flag pole height
503
    - s: float, default 1
504
        Flag size
505
    - c: str or tuple, default "red"
506
        Flag color
507
    - bc: str or tuple, default "white"
508
        Background color
509
    - alpha: float, default 1
510
        Flag transparency
511
    """
512
    def __init__(
513
        self, 
514
        txt, 
515
        pos, 
516
        height=1, 
517
        s=1, 
518
        c="red", 
519
        bc="white", 
520
        alpha=1
521
    ): ...
522
```
523

524
## Usage Examples
525

526
```python
527
import vedo
528
import numpy as np
529

530
# Create interactive visualization with UI components
531
plt = vedo.Plotter(title="Interactive 3D Scene")
532

533
# Add main 3D objects
534
sphere = vedo.Sphere(pos=(0, 0, 0), r=1, c='red')
535
box = vedo.Box(pos=(2, 0, 0), c='blue')
536
plt.add(sphere, box)
537

538
# Add interactive sliders
539
def update_sphere_radius(widget, event):
540
    r = widget.GetRepresentation().GetValue()
541
    sphere.scale(r)
542

543
def update_box_position(widget, event):
544
    x = widget.GetRepresentation().GetValue()
545
    box.pos(x, 0, 0)
546

547
radius_slider = vedo.Slider2D(
548
    update_sphere_radius,
549
    xmin=0.5, xmax=2.0, value=1.0,
550
    pos=4, title="Sphere Radius",
551
    showValue=True
552
)
553

554
position_slider = vedo.Slider2D(
555
    update_box_position,
556
    xmin=-3, xmax=3, value=2.0,
557
    pos=3, title="Box X Position",
558
    c='blue'
559
)
560

561
# Add 3D slider embedded in scene
562
def rotate_objects(widget, event):
563
    angle = widget.GetRepresentation().GetValue()
564
    sphere.rotate_z(angle - sphere.info.get('last_angle', 0))
565
    sphere.info['last_angle'] = angle
566

567
rotation_slider = vedo.Slider3D(
568
    rotate_objects,
569
    xmin=0, xmax=360, value=0,
570
    pos=(0, -3, 0), length=4,
571
    c='green', title="Rotation"
572
)
573

574
# Add control buttons
575
def toggle_visibility(obj, state):
576
    if state:
577
        sphere.alpha(1)
578
        box.alpha(1)
579
    else:
580
        sphere.alpha(0.3)
581
        box.alpha(0.3)
582

583
visibility_button = vedo.Button(
584
    toggle_visibility,
585
    states=["Visible", "Faded"],
586
    c=["white", "gray"],
587
    pos=(0.1, 0.9)
588
)
589

590
# Add checkbox for wireframe mode
591
def toggle_wireframe(obj, state):
592
    if state:
593
        sphere.wireframe()
594
        box.wireframe()
595
    else:
596
        sphere.wireframe(False)
597
        box.wireframe(False)
598

599
wireframe_checkbox = vedo.CheckBox(
600
    "Wireframe Mode",
601
    value=False,
602
    pos=(0.1, 0.8)
603
)
604

605
# Add scalar bar (requires scalar data)
606
# Generate some scalar data for demonstration
607
points = sphere.points()
608
distances = np.linalg.norm(points, axis=1) 
609
sphere.pointdata['distance'] = distances
610

611
scalar_bar = vedo.ScalarBar(
612
    sphere,
613
    title="Distance from Origin",
614
    pos=(0.85, 0.1),
615
    titleFontSize=14
616
)
617

618
# Add 3D scalar bar
619
scalar_bar_3d = vedo.ScalarBar3D(
620
    sphere,
621
    title="3D Scale",
622
    pos=(4, 0, 0),
623
    sy=2
624
)
625

626
# Create legend for objects
627
legend_entries = [
628
    ("Red Sphere", "red"),
629
    ("Blue Box", "blue"),
630
    ("Green Slider", "green")
631
]
632

633
legend = vedo.LegendBox(
634
    legend_entries,
635
    width=0.15,
636
    pos="top-left"
637
)
638

639
# Add coordinate axes
640
axes = vedo.Axes(
641
    sphere,
642
    xtitle="X axis",
643
    ytitle="Y axis", 
644
    ztitle="Z axis",
645
    c='black'
646
)
647

648
# Add lighting
649
key_light = vedo.Light(
650
    pos=(5, 5, 5),
651
    focalPoint=(0, 0, 0),
652
    intensity=1.2,
653
    c='white'
654
)
655

656
fill_light = vedo.Light(
657
    pos=(-3, 2, 3),
658
    focalPoint=(0, 0, 0),
659
    intensity=0.6,
660
    c='lightblue'
661
)
662

663
# Add measurement tools
664
ruler = vedo.Ruler3D(
665
    sphere.center(), box.center(),
666
    units="units",
667
    c='yellow',
668
    lw=3
669
)
670

671
# Add information display
672
hover_info = vedo.Hover(
673
    sphere,
674
    c='black',
675
    bc='lightyellow'
676
)
677

678
# Add flag annotation
679
flag = vedo.Flagpost(
680
    "Important Point",
681
    pos=(0, 0, 1),
682
    height=1.5,
683
    c='orange'
684
)
685

686
# Measurement and analysis tools
687
distance_tool = vedo.DistanceTool(c='purple', units='cm')
688

689
# Create spline editing tool
690
control_points = [(0, -2, 0), (1, -2, 1), (2, -2, 0), (3, -2, -1)]
691
spline_tool = vedo.SplineTool(
692
    points=control_points,
693
    pc='red',
694
    lc='blue'
695
)
696

697
# Add all components to the plotter
698
plt.add([
699
    radius_slider, position_slider, rotation_slider,
700
    visibility_button, wireframe_checkbox,
701
    scalar_bar, scalar_bar_3d, legend, axes,
702
    key_light, fill_light, ruler, hover_info, flag,
703
    distance_tool, spline_tool
704
])
705

706
# Add renderer frame
707
frame = vedo.RendererFrame(c='black', lw=2)
708
plt.add(frame)
709

710
# Add icon
711
icon = vedo.Icon("home", pos=(0.95, 0.95), size=0.04)
712
plt.add(icon)
713

714
# Show interactive scene
715
plt.show()
716

717
# Example of programmatic UI updates
718
def animate_scene():
719
    """Demonstrate programmatic control of UI elements."""
720
    for i in range(100):
721
        # Update slider values programmatically
722
        radius_slider.SetValue(1 + 0.5 * np.sin(i * 0.1))
723
        position_slider.SetValue(2 * np.cos(i * 0.05))
724
        
725
        # Update object properties
726
        sphere.color(i % 10)  # Cycle through colors
727
        
728
        # Update measurements
729
        new_ruler = vedo.Ruler3D(
730
            sphere.center(), box.center(),
731
            units="dynamic",
732
            c='red'
733
        )
734
        
735
        plt.render()
736
        
737
animate_scene()
738
```