0
# Display & Visualization
1

2
Display and visualization functions with matplotlib backend support for showing images, managing active images, and synchronizing data between ImageJ and Python environments.
3

4
## Capabilities
5

6
### Image Display
7

8
Display images using matplotlib backend with customizable visualization options.
9

10
```python { .api }
11
def show(image, cmap=None):
12
    """
13
    Display a 2D image using matplotlib.
14
    
15
    Args:
16
        image: Image data (Java or Python format) that can be converted to NumPy array
17
        cmap: Matplotlib colormap name (e.g., "gray", "hot", "viridis")
18
        
19
    Raises:
20
        TypeError: If image is None
21
        ImportError: If matplotlib is not available in headless environments
22
    """
23
```
24

25
**Usage Examples:**
26

27
```python
28
import numpy as np
29

30
# Display NumPy array
31
array = np.random.rand(256, 256)
32
ij.py.show(array, cmap="gray")
33

34
# Display Java image with color mapping
35
dataset = ij.io().open("path/to/image.tif")
36
ij.py.show(dataset, cmap="viridis")
37

38
# Display processed result
39
gaussian_filtered = ij.op().filter().gauss(dataset, 2.0)
40
ij.py.show(gaussian_filtered, cmap="hot")
41

42
# Display without colormap (uses matplotlib default)
43
ij.py.show(array)
44
```
45

46
### Active Image Management
47

48
Access and manage the currently active image in ImageJ's interface.
49

50
```python { .api }
51
def active_dataset() -> "Dataset":
52
    """
53
    Get the active image as an ImageJ2 Dataset.
54
    
55
    Returns:
56
        Current active Dataset from ImageJ2's Dataset service
57
        
58
    Returns:
59
        None if no image is active
60
    """
61

62
def active_imageplus(sync: bool = True) -> "ImagePlus":
63
    """
64
    Get the active image as an ImageJ ImagePlus.
65
    
66
    Args:
67
        sync: Synchronize current ImagePlus slice if True
68
        
69
    Returns:
70
        Current active ImagePlus from original ImageJ
71
        None if no image is active or legacy support unavailable
72
    """
73

74
def active_xarray(sync=True) -> xr.DataArray:
75
    """
76
    Get the active image as an xarray DataArray.
77
    
78
    Args:
79
        sync: Synchronize current ImagePlus slice if True
80
        
81
    Returns:
82
        Active image converted to xarray.DataArray with dimension labels
83
    """
84
```
85

86
**Usage Examples:**
87

88
```python
89
# Open multiple images in ImageJ
90
ij.py.run_macro('open("/path/to/image1.tif");')
91
ij.py.run_macro('open("/path/to/image2.tif");')
92

93
# Get currently active image in different formats
94
active_ds = ij.py.active_dataset()
95
active_imp = ij.py.active_imageplus()
96
active_xr = ij.py.active_xarray()
97

98
print(f"Dataset dimensions: {active_ds.numDimensions()}")
99
print(f"ImagePlus title: {active_imp.getTitle()}")
100
print(f"xarray shape: {active_xr.shape}")
101
print(f"xarray dims: {active_xr.dims}")
102

103
# Process active image
104
if active_ds is not None:
105
    processed = ij.op().filter().gauss(active_ds, 1.5)
106
    processed_array = ij.py.from_java(processed)
107
    ij.py.show(processed_array, cmap="gray")
108
```
109

110
### Image Synchronization
111

112
Synchronize image data between ImageJ and ImageJ2 when using legacy support.
113

114
```python { .api }
115
def sync_image(imp=None):
116
    """
117
    Synchronize data between ImageJ ImagePlus and ImageJ2 Dataset/ImageDisplay.
118
    
119
    Args:
120
        imp: Specific ImagePlus to synchronize, or None for active image
121
        
122
    Note:
123
        Ensures consistency when ImagePlus data is modified via ImageProcessor
124
        without automatic Dataset/ImageDisplay synchronization
125
    """
126
```
127

128
**Usage Examples:**
129

130
```python
131
# Get active ImagePlus and modify it
132
imp = ij.py.active_imageplus()
133
if imp is not None:
134
    # Direct pixel manipulation (bypasses automatic sync)
135
    processor = imp.getProcessor()
136
    processor.invert()
137
    
138
    # Manually synchronize to ensure Dataset sees changes
139
    ij.py.sync_image(imp)
140
    
141
    # Now Dataset will reflect the inversion
142
    synced_dataset = ij.py.active_dataset()
143
    synced_array = ij.py.from_java(synced_dataset)
144
    ij.py.show(synced_array)
145

146
# Synchronize all active images
147
ij.py.sync_image()  # Syncs current active image
148
```
149

150
### Window and Display Management
151

152
Access ImageJ's window management system for controlling image displays.
153

154
```python { .api }
155
# Through ImageJ2 gateway properties
156
@property
157
def WindowManager():
158
    """Access to original ImageJ WindowManager class for display management."""
159
```
160

161
**Usage Examples:**
162

163
```python
164
# Access WindowManager for display control
165
wm = ij.WindowManager
166

167
# Get list of open image windows
168
image_titles = wm.getImageTitles()
169
print(f"Open images: {list(image_titles)}")
170

171
# Get specific image by title
172
imp = wm.getImage("image.tif")
173
if imp is not None:
174
    print(f"Image size: {imp.getWidth()}x{imp.getHeight()}")
175

176
# Close all images
177
wm.closeAllWindows()
178

179
# Check if any images are open
180
if wm.getImageCount() > 0:
181
    print(f"{wm.getImageCount()} images currently open")
182
else:
183
    print("No images open")
184
```
185

186
### Advanced Display Features
187

188
Integration with ImageJ2's display system for complex visualization scenarios.
189

190
**UI Service Integration:**
191

192
```python
193
# Access ImageJ2 UI services through gateway
194
ui_service = ij.ui()
195

196
# Show ImageJ2 user interface (in interactive mode)
197
ui_service.showUI()
198

199
# Check UI state
200
is_headless = ui_service.isHeadless()
201
is_visible = ui_service.isVisible()
202

203
print(f"Headless mode: {is_headless}")
204
print(f"UI visible: {is_visible}")
205
```
206

207
**Display Service Usage:**
208

209
```python
210
# Create and show ImageJ2 displays
211
dataset = ij.py.to_dataset(np.random.rand(256, 256))
212

213
# Create display through ImageJ2
214
display = ij.display().createDisplay("My Dataset", dataset)
215

216
# Access display properties
217
display_name = display.getName()
218
is_displaying = display.isDisplaying(dataset)
219

220
print(f"Display name: {display_name}")
221
print(f"Is displaying dataset: {is_displaying}")
222
```
223

224
### Matplotlib Integration
225

226
PyImageJ's display system integrates with matplotlib for Python-native visualization.
227

228
**Custom Visualization:**
229

230
```python
231
import matplotlib.pyplot as plt
232

233
# Get image data
234
dataset = ij.io().open("path/to/image.tif")
235
image_array = ij.py.from_java(dataset)
236

237
# Custom matplotlib visualization
238
fig, axes = plt.subplots(1, 2, figsize=(12, 5))
239

240
# Original image
241
axes[0].imshow(image_array, cmap='gray')
242
axes[0].set_title('Original')
243
axes[0].axis('off')
244

245
# Processed version
246
filtered = ij.op().filter().gauss(dataset, 2.0)
247
filtered_array = ij.py.from_java(filtered)
248
axes[1].imshow(filtered_array, cmap='gray')
249
axes[1].set_title('Gaussian Filtered')
250
axes[1].axis('off')
251

252
plt.tight_layout()
253
plt.show()
254
```
255

256
### Deprecated Display Methods
257

258
Legacy methods maintained for backward compatibility.
259

260
```python { .api }
261
def window_manager():
262
    """
263
    Deprecated: Use ij.WindowManager instead.
264
    Access to ImageJ's WindowManager class.
265
    """
266
```
267

268
## Display Considerations
269

270
### Environment Compatibility
271

272
- **Headless Mode**: `ij.py.show()` requires matplotlib, not ImageJ GUI
273
- **GUI Mode**: Images appear in both ImageJ windows and matplotlib figures
274
- **Interactive Mode**: Manual control over when GUI elements appear
275

276
### Performance Tips
277

278
- **Large Images**: Consider downsampling for display: `image[::4, ::4]`
279
- **3D Data**: Extract 2D slices for visualization: `volume[:, :, slice_idx]`
280
- **Memory**: Display operations create copies; original data unchanged
281

282
### Error Handling
283

284
Common display issues:
285

286
- **No Display Backend**: Ensure matplotlib backend is available in headless environments
287
- **Image Format**: Some Java image types may need explicit conversion
288
- **Synchronization**: Manual sync required after direct ImageProcessor modifications
289
- **Window Focus**: ImageJ windows may not automatically gain focus in some environments