0
# Command Line Interface
1

2
Kimimaro provides a comprehensive command-line interface for skeletonization, visualization, and file format conversion without requiring Python programming knowledge.
3

4
## Installation and Setup
5

6
After installing kimimaro, the `kimimaro` command becomes available:
7

8
```bash
9
pip install kimimaro
10
pip install "kimimaro[all]"  # For full CLI functionality including visualization
11
```
12

13
## Capabilities
14

15
### Main Skeletonization Command
16

17
Skeletonize input volumes and save results as SWC files.
18

19
```bash { .api }
20
kimimaro forge <input_file> [options]
21
```
22

23
#### Parameters
24

25
**Required:**
26
- `<input_file>`: Path to labeled volume file (.npy format)
27

28
**Optional Parameters:**
29
- `--scale FLOAT`: Rolling ball invalidation scale multiplier (default: 4)
30
- `--const FLOAT`: Minimum invalidation radius in physical units (default: 10)  
31
- `--pdrf-scale INT`: Penalty distance field scale factor (default: 100000)
32
- `--pdrf-exponent INT`: Penalty field exponent (default: 8)
33
- `--soma-detect FLOAT`: Soma detection threshold in physical units (default: 750)
34
- `--soma-accept FLOAT`: Soma acceptance threshold in physical units (default: 1100)
35
- `--soma-scale FLOAT`: Soma invalidation scale multiplier (default: 2)
36
- `--soma-const FLOAT`: Soma invalidation constant in physical units (default: 300)
37
- `--anisotropy TUPLE3`: Physical voxel dimensions as x,y,z (default: "1,1,1")
38
- `--dust INT`: Skip connected components smaller than this (default: 1000)
39
- `--max-paths INT`: Maximum paths to trace per object (default: None)
40
- `-p, --parallel INT`: Number of processes to use (default: 1)
41
- `-o, --outdir TEXT`: Output directory for SWC files (default: "kimimaro_out")
42
- `--progress`: Show progress bar
43
- `--fill-holes` / `--no-fill-holes`: Fill holes in shapes (default: True)
44
- `--fix-avocados`: Use heuristics to combine nuclei with cell bodies
45
- `--fix-borders`: Center skeleton where shape contacts border
46
- `--fix-branches`: Improve quality of branched shapes (default: True)
47

48
#### Usage Examples
49

50
```bash
51
# Basic skeletonization
52
kimimaro forge neurons.npy --progress
53

54
# Advanced parameters for high-resolution EM data
55
kimimaro forge em_segmentation.npy \
56
  --scale 2.0 \
57
  --const 500 \
58
  --anisotropy 8,8,30 \
59
  --soma-detect 1000 \
60
  --soma-accept 3500 \
61
  --parallel 8 \
62
  --progress \
63
  --outdir results/skeletons
64

65
# Optimized for speed
66
kimimaro forge large_volume.npy \
67
  --dust 2000 \
68
  --max-paths 100 \
69
  --parallel 16 \
70
  --no-fill-holes \
71
  --progress
72
```
73

74
### Visualization
75

76
View and visualize SWC files and labeled volumes.
77

78
```bash { .api }
79
kimimaro view <filename> [options]
80
```
81

82
#### Parameters
83

84
- `<filename>`: File to visualize (.swc, .npy, or .ckl format)
85
- `--port INT`: Port for web viewer (npy files only, default: 8080)
86
- `--color-by TEXT`: Skeleton coloring scheme (default: 'r')
87
  - `r`: Color by radius
88
  - `c`: Color by connected components  
89
  - `x`: Color by cross-sectional area (if available)
90

91
#### Usage Examples
92

93
```bash
94
# View skeleton file
95
kimimaro view skeleton_1234.swc
96

97
# View segmentation volume
98
kimimaro view neurons.npy --port 8081
99

100
# View skeleton with component coloring
101
kimimaro view neuron.swc --color-by c
102
```
103

104
### Format Conversion
105

106
Convert between different skeleton and image formats.
107

108
#### Binary Image to SWC
109

110
Convert binary skeleton images to SWC format.
111

112
```bash { .api }
113
kimimaro swc from <input_files...>
114
```
115

116
#### Usage Examples
117

118
```bash
119
# Convert single binary skeleton
120
kimimaro swc from skeleton_binary.tiff
121

122
# Convert multiple files
123
kimimaro swc from skel1.npy skel2.npy skel3.tiff
124
```
125

126
#### SWC to Binary Image
127

128
Convert SWC files to binary image format.
129

130
```bash { .api }
131
kimimaro swc to <input_files...> [options]
132
```
133

134
#### Parameters
135

136
- `<input_files...>`: One or more SWC files to convert
137
- `--format TEXT`: Output format (default: "npy")
138
  - `npy`: NumPy binary format
139
  - `tiff`: TIFF image format
140

141
#### Usage Examples
142

143
```bash
144
# Convert to NumPy format
145
kimimaro swc to neuron_1234.swc
146

147
# Convert to TIFF format
148
kimimaro swc to neuron_1234.swc --format tiff
149

150
# Convert multiple files
151
kimimaro swc to *.swc --format npy
152
```
153

154
### License Information
155

156
Display license information for the library.
157

158
```bash { .api }
159
kimimaro license
160
```
161

162
## Complete Workflow Examples
163

164
### Basic Neuron Processing
165

166
```bash
167
# 1. Skeletonize a volume
168
kimimaro forge neurons.npy \
169
  --anisotropy 16,16,40 \
170
  --scale 1.5 \
171
  --const 300 \
172
  --progress \
173
  --outdir neuron_skeletons
174

175
# 2. View results
176
kimimaro view neuron_skeletons/12345.swc
177

178
# 3. Convert to binary format for analysis
179
kimimaro swc to neuron_skeletons/*.swc --format npy
180
```
181

182
### High-Resolution EM Processing
183

184
```bash
185
# Process high-resolution electron microscopy data
186
kimimaro forge em_segmentation.npy \
187
  --anisotropy 4,4,30 \
188
  --scale 2.0 \
189
  --const 200 \
190
  --soma-detect 500 \
191
  --soma-accept 2000 \
192
  --parallel 12 \
193
  --dust 500 \
194
  --fill-holes \
195
  --fix-avocados \
196
  --progress \
197
  --outdir em_skeletons
198

199
# Visualize volume and results
200
kimimaro view em_segmentation.npy --port 8080 &
201
kimimaro view em_skeletons/large_neuron.swc --color-by x
202
```
203

204
### Batch Processing
205

206
```bash
207
# Process multiple volumes in parallel
208
for volume in *.npy; do
209
  echo "Processing $volume"
210
  kimimaro forge "$volume" \
211
    --anisotropy 16,16,40 \
212
    --parallel 8 \
213
    --progress \
214
    --outdir "skeletons_$(basename $volume .npy)" &
215
done
216
wait
217

218
# Convert all results to TIFF for visualization software
219
find . -name "*.swc" -exec kimimaro swc to {} --format tiff \;
220
```
221

222
## File Format Support
223

224
### Input Formats (forge command)
225
- `.npy`: NumPy array files (primary format)
226

227
### Input Formats (view command)  
228
- `.swc`: SWC skeleton files
229
- `.npy`: NumPy labeled volumes
230
- `.ckl`: Crackle compressed volumes (requires crackle-codec)
231

232
### Input Formats (swc from command)
233
- `.npy`: Binary skeleton arrays
234
- `.tiff`: Binary skeleton images (requires tifffile)
235

236
### Output Formats
237
- `.swc`: SWC skeleton format (standard neuromorphology format)
238
- `.npy`: NumPy binary arrays
239
- `.tiff`: TIFF images (requires tifffile)
240

241
## Performance Tips
242

243
### Memory Optimization
244
- Use `--dust` parameter to skip small objects
245
- Limit `--max-paths` for very branched objects
246
- Consider processing subvolumes for very large datasets
247

248
### Speed Optimization
249
- Use `--parallel` with number of CPU cores
250
- Disable `--fill-holes` if not needed
251
- Increase `--dust` threshold to skip artifacts
252
- Use `--no-fix-branches` for simple morphologies
253

254
### Quality Optimization
255
- Enable `--fill-holes` for better reconstruction
256
- Use `--fix-avocados` for cellular morphologies
257
- Enable `--fix-borders` when processing image chunks
258
- Tune `--soma-detect` and `--soma-accept` for your data
259

260
## Troubleshooting
261

262
### Common Issues
263

264
**"No such file or directory"**
265
- Check input file path and format
266
- Ensure file is in NumPy (.npy) format for forge command
267

268
**"ModuleNotFoundError: No module named 'microviewer'"**
269
- Install visualization dependencies: `pip install "kimimaro[view]"`
270

271
**"Cannot allocate memory"**
272
- Reduce parallelism with `--parallel 1`
273
- Increase `--dust` threshold
274
- Process smaller subvolumes
275

276
**Very slow processing**
277
- Check if `--fill-holes` is needed
278
- Increase `--dust` threshold
279
- Use `--parallel` for multi-core processing
280
- Consider `--max-paths` limit for highly branched objects
281

282
**Poor skeleton quality**  
283
- Adjust `--scale` and `--const` parameters
284
- Enable `--fix-branches` and `--fix-borders`
285
- Check `--anisotropy` matches your data
286
- Use `--fill-holes` if shapes have artifacts
287

288
### License Command
289

290
Display the software license information.
291

292
```bash { .api }
293
kimimaro license
294
```
295

296
Prints the complete GPL-3.0-or-later license text to the console.