igv-rs — Interactive Terminal Genome Viewer

Overview

Features

🧬

Multi-track

BAM · VCF · GFF · BED · bigWig · BEDPE — all in one synchronized view.

⚡

Async non-blocking IO

Adaptive zoom-level rendering keeps the TUI responsive at any scale.

🌐

Live browser companion

Press B to open igv.js in your browser, synced to the TUI view.

📸

Snapshot export

Publication-quality SVG / PNG — interactive or headless batch mode.

🎨

8 built-in themes

dark · light · paper · solarized · dracula · gruvbox — cycle with t.

🔖

Command palette

Jump to any coordinate or gene name. Vim-style bookmarks with m<c> / '<c>.

Getting Started

Install

Install the latest release from crates.io:

$ cargo install igv-rs

The igv.js browser companion is bundled into the binary — no extra assets required.

Pre-built binaries for Linux / macOS / Windows are attached to each GitHub Release.

Build from source:

    $ git clone https://github.com/AI4S-YB/igv-rs
    $ cargo build --release
    # binary at target/release/igv-rs
  

CLI

Usage

    # Reference only
    igv-rs reference.fa
    
    # With variants
    igv-rs reference.fa -v variants.vcf.gz
    
    # With alignments
    igv-rs reference.fa -b alignments.bam -r chr1:1000-2000
    
    # Multiple BAM tracks
    igv-rs reference.fa -b sample1.bam -b sample2.bam
    
    # Annotations (GFF/GTF/BED/narrowPeak auto-detected by extension)
    igv-rs reference.fa -g genes.gff3 -b sample.bam
    
    # Signal tracks (bigWig)
    igv-rs reference.fa -s chip.bw -s input.bw -r chr1:1-10000000
    
    # Chromatin loops (BEDPE)
    igv-rs reference.fa -l loops.bedpe --link-min-score 5.0
    
    # Everything at once
    igv-rs reference.fa -b sample.bam -g genes.gff3 -s rna.bw -l loops.bedpe -r chr1:1000-2000
  

The command palette (: or g) accepts coordinates (chr1:1000-2000) and gene names — type any gene_name, gene_id, or transcript_id from a loaded GFF/GTF/BED track and the view jumps to the union span of all matching transcripts.

Rendering

Wide-zoom Behavior

At wider zoom levels igv-rs skips expensive fetches to stay responsive:

View Width	Reference	Reads	Variants	Annotations	Signals	Links
≤ 50 kb (per-base)	yes	yes	yes	transcripts	yes	yes
50 kb – 500 kb	—	—	yes	transcripts	yes	yes
500 kb – 5 Mb	—	—	—	transcripts	yes	yes
> 5 Mb (overview)	—	—	—	gene density	yes	yes

The footer shows a yellow "overview" hint when fetches are gated. bigWig signal tracks remain visible at every zoom level.

Export

Snapshot Export

Save publication-quality SVG or PNG figures — interactive or headless batch.

Interactive (inside the TUI):

    # Press S to save current view
    S  →  snapshot_chr1_1000_2000.svg
    
    # Or use the command palette for a custom path / format
    :snapshot path/to/figure.png
  

Headless batch (no TUI opened):

    # One snapshot per BED region (col 4 = filename stem)
    igv-rs ref.fa -b s.bam --snapshot-bed regions.bed --snapshot-out out/
    
    # One snapshot per gene name (requires -g)
    igv-rs ref.fa -b s.bam -g genes.gtf --snapshot-genes list.txt --snapshot-out out/
  

Common flags: --snapshot-format svg|png · --snapshot-width <px> · --snapshot-flank <fraction> · --snapshot-theme igv|tui

Live Preview

Browser View (igv.js)

Press B inside the TUI to launch a local HTTP server and open igv.js in your default browser. The browser tab starts at the TUI's current region and follows your navigation in real time.

    igv-rs ref.fa -b sample.bam -g genes.gtf -l loops.bedpe
    # inside the TUI:
    #   B          → opens browser tab (igv.js)
    #   d / s / :gene → browser follows
    #   q          → exits TUI, shuts down server
  

The server binds to 127.0.0.1 on an ephemeral port (override with --serve-port). igv.js is bundled into the binary — browser view works offline. Disable with --no-browser.

Reference

Keybindings

Key	Action
`a` / `←`	Page backward (one full window)
`d` / `→`	Page forward (one full window)
`h`	Move backward 1/10 window (fine pan)
`l`	Move forward 1/10 window (fine pan)
`w` / `↑`	Zoom in
`s` / `↓`	Zoom out
`j` / `k`	Scroll alignment lanes down / up
`+` / `-`	Grow / shrink alignment-track height
`]` / `[`	Grow / shrink coverage-track height
`\`	Toggle signal shared / per-track Y-scale
`}` / `{`	Grow / shrink signal-track height
`<` / `>`	Shrink / grow link-track height
`:` or `g`	Open command palette (coordinate or gene name)
`m<c>`	Set bookmark to letter c
`'<c>`	Jump to bookmark c
`t`	Cycle theme
`S`	Save SVG snapshot of current view
`B`	Open browser view (igv.js)
`?`	Toggle keybinding help overlay
`q` / Ctrl-C	Quit

Configuration

Optional ~/.config/igv-rs/config.toml is read at startup:

    [theme]
    # "dark" | "light" | "paper" | "solarized-dark" | "solarized-light"
    # | "dracula" | "gruvbox-dark"
    preset = "dark"
    
    [theme.custom]
    # Override individual style keys
    "A"        = "bold green"
    "MISMATCH" = "bold white on red"
    "SIGNAL"   = "cyan"
    "LINK"     = "magenta"
    
    [serve]
    auto_open = true   # --no-browser overrides
    port      = 0      # 0 = ephemeral; --serve-port overrides
  

Caveats

Known Limitations

Held-key debounce not implemented — tap rather than hold navigation keys.
[render] config keys (zoom_factor, nav_overlap, threshold overrides) not yet read.
[bookmarks] config table not loaded — in-session bookmarks work fully.
Coverage at wide zoom is hidden, not heat-mapped — use a precomputed bigWig for chromosome-scale depth.
BAM tag display uses Rust's Debug formatting (e.g. Int8(42) instead of 42) when coloring by tag.
No signal-track caching — every region change re-fetches bigWig.
Single signal colormap — all bigWig tracks share the SIGNAL theme key.
bigBed (.bb) not yet supported.
No tabix / pairix for link tracks — BEDPE files >1M records load slowly.
Browser view is loopback-only — no remote access, no auth tokens.