Command Line Interface

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

Installation and Setup

After installing kimimaro, the kimimaro command becomes available:

pip install kimimaro
pip install "kimimaro[all]"  # For full CLI functionality including visualization

Capabilities

Main Skeletonization Command

Skeletonize input volumes and save results as SWC files.

kimimaro forge <input_file> [options]

Parameters

Required:

• <input_file>: Path to labeled volume file (.npy format)

Optional Parameters:

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

Usage Examples

# Basic skeletonization
kimimaro forge neurons.npy --progress

# Advanced parameters for high-resolution EM data
kimimaro forge em_segmentation.npy \
  --scale 2.0 \
  --const 500 \
  --anisotropy 8,8,30 \
  --soma-detect 1000 \
  --soma-accept 3500 \
  --parallel 8 \
  --progress \
  --outdir results/skeletons

# Optimized for speed
kimimaro forge large_volume.npy \
  --dust 2000 \
  --max-paths 100 \
  --parallel 16 \
  --no-fill-holes \
  --progress

Visualization

View and visualize SWC files and labeled volumes.

kimimaro view <filename> [options]

Parameters

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

Usage Examples

# View skeleton file
kimimaro view skeleton_1234.swc

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

# View skeleton with component coloring
kimimaro view neuron.swc --color-by c

Format Conversion

Convert between different skeleton and image formats.

Binary Image to SWC

Convert binary skeleton images to SWC format.

kimimaro swc from <input_files...>

Usage Examples

# Convert single binary skeleton
kimimaro swc from skeleton_binary.tiff

# Convert multiple files
kimimaro swc from skel1.npy skel2.npy skel3.tiff

SWC to Binary Image

Convert SWC files to binary image format.

kimimaro swc to <input_files...> [options]

Parameters

• <input_files...>: One or more SWC files to convert
• --format TEXT: Output format (default: "npy")
  • npy: NumPy binary format
  • tiff: TIFF image format

Usage Examples

# Convert to NumPy format
kimimaro swc to neuron_1234.swc

# Convert to TIFF format
kimimaro swc to neuron_1234.swc --format tiff

# Convert multiple files
kimimaro swc to *.swc --format npy

License Information

Display license information for the library.

kimimaro license

Complete Workflow Examples

Basic Neuron Processing

# 1. Skeletonize a volume
kimimaro forge neurons.npy \
  --anisotropy 16,16,40 \
  --scale 1.5 \
  --const 300 \
  --progress \
  --outdir neuron_skeletons

# 2. View results
kimimaro view neuron_skeletons/12345.swc

# 3. Convert to binary format for analysis
kimimaro swc to neuron_skeletons/*.swc --format npy

High-Resolution EM Processing

# Process high-resolution electron microscopy data
kimimaro forge em_segmentation.npy \
  --anisotropy 4,4,30 \
  --scale 2.0 \
  --const 200 \
  --soma-detect 500 \
  --soma-accept 2000 \
  --parallel 12 \
  --dust 500 \
  --fill-holes \
  --fix-avocados \
  --progress \
  --outdir em_skeletons

# Visualize volume and results
kimimaro view em_segmentation.npy --port 8080 &
kimimaro view em_skeletons/large_neuron.swc --color-by x

Batch Processing

# Process multiple volumes in parallel
for volume in *.npy; do
  echo "Processing $volume"
  kimimaro forge "$volume" \
    --anisotropy 16,16,40 \
    --parallel 8 \
    --progress \
    --outdir "skeletons_$(basename $volume .npy)" &
done
wait

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

File Format Support

Input Formats (forge command)

• .npy: NumPy array files (primary format)

Input Formats (view command)

• .swc: SWC skeleton files
• .npy: NumPy labeled volumes
• .ckl: Crackle compressed volumes (requires crackle-codec)

Input Formats (swc from command)

• .npy: Binary skeleton arrays
• .tiff: Binary skeleton images (requires tifffile)

Output Formats

• .swc: SWC skeleton format (standard neuromorphology format)
• .npy: NumPy binary arrays
• .tiff: TIFF images (requires tifffile)

Performance Tips

Memory Optimization

• Use --dust parameter to skip small objects
• Limit --max-paths for very branched objects
• Consider processing subvolumes for very large datasets

Speed Optimization

• Use --parallel with number of CPU cores
• Disable --fill-holes if not needed
• Increase --dust threshold to skip artifacts
• Use --no-fix-branches for simple morphologies

Quality Optimization

• Enable --fill-holes for better reconstruction
• Use --fix-avocados for cellular morphologies
• Enable --fix-borders when processing image chunks
• Tune --soma-detect and --soma-accept for your data

Troubleshooting

Common Issues

"No such file or directory"

• Check input file path and format
• Ensure file is in NumPy (.npy) format for forge command

"ModuleNotFoundError: No module named 'microviewer'"

• Install visualization dependencies: pip install "kimimaro[view]"

"Cannot allocate memory"

• Reduce parallelism with --parallel 1
• Increase --dust threshold
• Process smaller subvolumes

Very slow processing

• Check if --fill-holes is needed
• Increase --dust threshold
• Use --parallel for multi-core processing
• Consider --max-paths limit for highly branched objects

Poor skeleton quality

• Adjust --scale and --const parameters
• Enable --fix-branches and --fix-borders
• Check --anisotropy matches your data
• Use --fill-holes if shapes have artifacts

License Command

Display the software license information.

kimimaro license

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