0
# Utility Functions
1

2
Data conversion and tensor processing utilities for preparing data for TensorBoard visualization. These functions handle format conversion, figure processing, tensor manipulation, and data validation for optimal TensorBoard compatibility.
3

4
## Capabilities
5

6
### Figure Conversion
7

8
Convert matplotlib figures and plots to image arrays suitable for TensorBoard visualization.
9

10
```python { .api }
11
def figure_to_image(figures, close: bool = True):
12
    """
13
    Convert matplotlib figure(s) to numpy image array(s).
14

15
    Parameters:
16
    - figures: Matplotlib figure object or list of figures
17
    - close: Whether to close the figure(s) after conversion (default: True)
18

19
    Returns:
20
    numpy.ndarray: Image array in CHW format (channels, height, width)
21
                   If input is list, returns list of arrays
22
    """
23
```
24

25
### Tensor Conversion
26

27
Convert various tensor types and formats to numpy arrays with proper shape and data type handling.
28

29
```python { .api }
30
def make_np(x):
31
    """
32
    Convert various tensor types to numpy arrays.
33
    Handles PyTorch tensors, numpy arrays, lists, and scalar values.
34

35
    Parameters:
36
    - x: Input data (torch.Tensor, numpy.ndarray, list, or scalar)
37

38
    Returns:
39
    numpy.ndarray: Converted numpy array
40
    """
41

42
def check_nan(array):
43
    """
44
    Check for NaN and Inf values in array and handle them.
45

46
    Parameters:
47
    - array: Input numpy array
48

49
    Returns:
50
    numpy.ndarray: Array with NaN/Inf values handled (replaced with 0)
51
    """
52
```
53

54
### Format Conversion
55

56
Convert tensors between different data formats required by TensorBoard visualization components.
57

58
```python { .api }
59
def convert_to_HWC(tensor, input_format: str):
60
    """
61
    Convert tensor to HWC (Height, Width, Channels) format.
62

63
    Parameters:
64
    - tensor: Input tensor (numpy.ndarray or torch.Tensor)
65
    - input_format: Current format ('CHW', 'HW', 'NCHW', 'NHWC', etc.)
66

67
    Returns:
68
    numpy.ndarray: Tensor in HWC format
69
    """
70

71
def convert_to_NTCHW(tensor, input_format: str):
72
    """
73
    Convert tensor to NTCHW (Batch, Time, Channels, Height, Width) format for videos.
74

75
    Parameters:
76
    - tensor: Input tensor (numpy.ndarray or torch.Tensor)
77
    - input_format: Current format ('NTHWC', 'NCHW', 'TCHW', etc.)
78

79
    Returns:
80
    numpy.ndarray: Tensor in NTCHW format
81
    """
82
```
83

84
### Image Grid Creation
85

86
Create image grids from batches of images for compact visualization.
87

88
```python { .api }
89
def make_grid(I, ncols: int = 8):
90
    """
91
    Create a grid of images from a batch of images.
92

93
    Parameters:
94
    - I: Input images tensor/array (N, C, H, W) or (N, H, W)
95
    - ncols: Number of columns in the grid (default: 8)
96

97
    Returns:
98
    numpy.ndarray: Image grid array
99
    """
100
```
101

102
### Embedding Utilities
103

104
Utilities for creating embedding visualizations with metadata and sprite images.
105

106
```python { .api }
107
def make_mat(matlist, save_path: str):
108
    """
109
    Create embedding matrix file for TensorBoard projector.
110

111
    Parameters:
112
    - matlist: List of embedding vectors
113
    - save_path: Path to save the matrix file
114
    """
115

116
def make_sprite(label_img, save_path: str):
117
    """
118
    Create sprite image for embedding visualization.
119

120
    Parameters:
121
    - label_img: Images corresponding to embedding points
122
    - save_path: Path to save the sprite image
123
    """
124

125
def make_tsv(metadata, save_path: str, metadata_header=None):
126
    """
127
    Create metadata TSV file for embedding labels.
128

129
    Parameters:
130
    - metadata: List of labels/metadata for each embedding point
131
    - save_path: Path to save the TSV file
132
    - metadata_header: Optional header for metadata columns
133
    """
134

135
def append_pbtxt(metadata_path: str, save_path: str):
136
    """
137
    Append projector configuration to pbtxt file.
138

139
    Parameters:
140
    - metadata_path: Path to metadata TSV file
141
    - save_path: Path to save projector config
142
    """
143
```
144

145
## Usage Examples
146

147
### Figure to Image Conversion
148

149
```python
150
import matplotlib.pyplot as plt
151
import numpy as np
152
from tensorboardX.utils import figure_to_image
153
from tensorboardX import SummaryWriter
154

155
# Create matplotlib figure
156
fig, ax = plt.subplots(figsize=(8, 6))
157
x = np.linspace(0, 10, 100)
158
y = np.sin(x)
159
ax.plot(x, y)
160
ax.set_title('Sine Wave')
161

162
# Convert to image array
163
img_array = figure_to_image(fig, close=True)
164

165
# Log to TensorBoard
166
writer = SummaryWriter()
167
writer.add_image('Plot', img_array, 0)
168
writer.close()
169
```
170

171
### Tensor Format Conversion
172

173
```python
174
import torch
175
import numpy as np
176
from tensorboardX.utils import convert_to_HWC, make_np
177

178
# PyTorch tensor in CHW format
179
tensor = torch.randn(3, 64, 64)
180

181
# Convert to numpy
182
np_array = make_np(tensor)
183

184
# Convert to HWC format for certain visualizations
185
hwc_array = convert_to_HWC(np_array, 'CHW')
186

187
print(f"Original shape: {tensor.shape}")     # torch.Size([3, 64, 64])
188
print(f"NumPy shape: {np_array.shape}")      # (3, 64, 64)
189
print(f"HWC shape: {hwc_array.shape}")       # (64, 64, 3)
190
```
191

192
### Video Format Conversion
193

194
```python
195
import numpy as np
196
from tensorboardX.utils import convert_to_NTCHW
197
from tensorboardX import SummaryWriter
198

199
# Video tensor in NTHWC format (batch, time, height, width, channels)
200
video = np.random.rand(2, 10, 64, 64, 3)
201

202
# Convert to NTCHW format required by TensorBoard
203
video_ntchw = convert_to_NTCHW(video, 'NTHWC')
204

205
# Log video to TensorBoard
206
writer = SummaryWriter()
207
writer.add_video('Sample_Video', video_ntchw[0:1], fps=5)  # First video in batch
208
writer.close()
209

210
print(f"Original shape: {video.shape}")        # (2, 10, 64, 64, 3)
211
print(f"NTCHW shape: {video_ntchw.shape}")     # (2, 10, 3, 64, 64)
212
```
213

214
### Image Grid Creation
215

216
```python
217
import numpy as np
218
from tensorboardX.utils import make_grid
219
from tensorboardX import SummaryWriter
220

221
# Batch of images (N, C, H, W)
222
images = np.random.rand(16, 3, 32, 32)
223

224
# Create grid with 4 columns
225
grid = make_grid(images, ncols=4)
226

227
# Log grid to TensorBoard
228
writer = SummaryWriter()
229
writer.add_image('Image_Grid', grid, 0)
230
writer.close()
231

232
print(f"Original batch shape: {images.shape}")  # (16, 3, 32, 32)
233
print(f"Grid shape: {grid.shape}")              # Grid dimensions
234
```
235

236
### NaN/Inf Handling
237

238
```python
239
import numpy as np
240
from tensorboardX.utils import check_nan, make_np
241

242
# Array with problematic values
243
data = np.array([1.0, 2.0, np.nan, np.inf, -np.inf, 5.0])
244

245
# Clean the data
246
clean_data = check_nan(data)
247

248
print(f"Original: {data}")      # [1.0, 2.0, nan, inf, -inf, 5.0]
249
print(f"Cleaned: {clean_data}") # [1.0, 2.0, 0.0, 0.0, 0.0, 5.0]
250
```
251

252
### Embedding Visualization Setup
253

254
```python
255
import numpy as np
256
from tensorboardX.embedding import make_mat, make_sprite, make_tsv, append_pbtxt
257
from tensorboardX import SummaryWriter
258

259
# Generate embedding data
260
embeddings = np.random.randn(1000, 128)  # 1000 points, 128 dimensions
261
labels = [f'class_{i%10}' for i in range(1000)]
262
images = np.random.rand(1000, 28, 28)  # Corresponding images
263

264
# Save embedding files
265
make_mat(embeddings, 'embeddings.tsv')
266
make_tsv(labels, 'metadata.tsv')
267
make_sprite(images, 'sprite.png')
268
append_pbtxt('metadata.tsv', 'projector_config.pbtxt')
269

270
# Add to TensorBoard
271
writer = SummaryWriter('logs/embeddings')
272
writer.add_embedding(
273
    embeddings,
274
    metadata=labels,
275
    label_img=images,
276
    tag='MNIST_Embeddings'
277
)
278
writer.close()
279
```
280

281
### Batch Processing with Utilities
282

283
```python
284
import numpy as np
285
from tensorboardX.utils import make_np, convert_to_HWC, figure_to_image
286
from tensorboardX import SummaryWriter
287
import matplotlib.pyplot as plt
288

289
def process_batch_for_tensorboard(data_batch, format='CHW'):
290
    """Process a batch of data for TensorBoard logging."""
291
    processed = []
292
    
293
    for item in data_batch:
294
        # Convert to numpy
295
        np_item = make_np(item)
296
        
297
        # Convert format if needed
298
        if format == 'HWC':
299
            np_item = convert_to_HWC(np_item, 'CHW')
300
        
301
        processed.append(np_item)
302
    
303
    return processed
304

305
# Example usage
306
batch = [np.random.rand(3, 64, 64) for _ in range(5)]
307
processed_batch = process_batch_for_tensorboard(batch, format='HWC')
308

309
writer = SummaryWriter()
310
for i, img in enumerate(processed_batch):
311
    writer.add_image(f'Processed_Image_{i}', img, 0, dataformats='HWC')
312
writer.close()
313
```
314

315
## Type Compatibility
316

317
The utility functions handle multiple input types:
318

319
### Tensor Types
320
- **PyTorch tensors**: `torch.Tensor` (CPU and CUDA)
321
- **NumPy arrays**: `numpy.ndarray`
322
- **Lists**: Python lists and nested lists
323
- **Scalars**: Python floats, integers
324

325
### Format Strings
326
- **Image formats**: 'CHW', 'HWC', 'HW'
327
- **Batch formats**: 'NCHW', 'NHWC', 'NHW'
328
- **Video formats**: 'NTCHW', 'NTHWC', 'TCHW', 'THWC'
329

330
### Data Type Handling
331
- Automatic dtype conversion for TensorBoard compatibility
332
- Normalization for image data (0-1 or 0-255 ranges)
333
- Proper handling of edge cases (empty arrays, single pixels, etc.)
334

335
## Performance Notes
336

337
- **Memory efficiency**: Functions avoid unnecessary copying when possible
338
- **Format detection**: Automatic format detection for common tensor shapes
339
- **Batch processing**: Optimized for processing multiple items efficiently
340
- **Error handling**: Graceful handling of malformed input data