igv-rs — 交互式终端基因组浏览器

概览

功能特性

🧬

多轨道支持

BAM · VCF · GFF · BED · bigWig · BEDPE — 在同一视图中同步显示。

⚡

异步非阻塞 IO

自适应缩放级别渲染，在任意比例下保持 TUI 响应流畅。

🌐

浏览器实时伴侣

按 B 在浏览器中打开与 TUI 同步的 igv.js 视图。

📸

快照导出

发表级 SVG / PNG — 支持交互式保存和无头批量模式。

🎨

8 种内置主题

dark · light · paper · solarized · dracula · gruvbox — 按 t 循环切换。

🔖

命令面板

跳转到任意坐标或基因名称。Vim 风格书签 m<c> / '<c>。

快速开始

安装

从 crates.io 安装最新版本：

$ cargo install igv-rs

igv.js 浏览器伴侣已打包进二进制文件，无需额外资源。

Linux / macOS / Windows 预编译二进制文件可在 GitHub Releases 页面下载。

从源码构建：

    $ git clone https://github.com/AI4S-YB/igv-rs
    $ cargo build --release
    # 二进制文件位于 target/release/igv-rs
  

命令行

用法

    # 仅参考序列
    igv-rs reference.fa
    
    # 加载变异
    igv-rs reference.fa -v variants.vcf.gz
    
    # 加载比对
    igv-rs reference.fa -b alignments.bam -r chr1:1000-2000
    
    # 多 BAM 轨道
    igv-rs reference.fa -b sample1.bam -b sample2.bam
    
    # 注释轨道（GFF/GTF/BED/narrowPeak 按扩展名自动识别）
    igv-rs reference.fa -g genes.gff3 -b sample.bam
    
    # 信号轨道（bigWig）
    igv-rs reference.fa -s chip.bw -s input.bw -r chr1:1-10000000
    
    # 染色质环（BEDPE）
    igv-rs reference.fa -l loops.bedpe --link-min-score 5.0
    
    # 综合示例
    igv-rs reference.fa -b sample.bam -g genes.gff3 -s rna.bw -l loops.bedpe -r chr1:1000-2000
  

命令面板（: 或 g）支持坐标（chr1:1000-2000）和基因名称 — 输入已加载 GFF/GTF/BED 轨道中的 gene_name、gene_id 或 transcript_id，视图将跳转到所有匹配转录本的联合区间。

渲染

宽视图缩放行为

在较宽的缩放级别下，igv-rs 会跳过高开销的数据获取以保持响应：

视图宽度	参考序列	比对读段	变异	注释	信号	环
≤ 50 kb（碱基级）	是	是	是	转录本	是	是
50 kb – 500 kb	—	—	是	转录本	是	是
500 kb – 5 Mb	—	—	—	转录本	是	是
> 5 Mb（概览）	—	—	—	基因密度	是	是

当数据获取被限制时，页脚会显示黄色“概览”提示。bigWig 信号轨道在所有缩放级别下均可见。

导出

快照导出

保存发表级 SVG 或 PNG 图像 — 支持交互式和无头批量两种模式。

交互式（在 TUI 内）：

    # 按 S 保存当前视图
    S  →  snapshot_chr1_1000_2000.svg
    
    # 或通过命令面板指定路径 / 格式
    :snapshot path/to/figure.png
  

无头批量（不打开 TUI）：

    # 每个 BED 区域一张快照（第 4 列为文件名前缀）
    igv-rs ref.fa -b s.bam --snapshot-bed regions.bed --snapshot-out out/
    
    # 每个基因名称一张快照（需要 -g 注释）
    igv-rs ref.fa -b s.bam -g genes.gtf --snapshot-genes list.txt --snapshot-out out/
  

常用参数：--snapshot-format svg|png · --snapshot-width <px> · --snapshot-flank <fraction> · --snapshot-theme igv|tui

实时预览

浏览器视图（igv.js）

在 TUI 内按 B 启动本地 HTTP 服务器，并在默认浏览器中打开 igv.js。浏览器标签页从 TUI 当前区域开始，并实时跟随导航。

    igv-rs ref.fa -b sample.bam -g genes.gtf -l loops.bedpe
    # 在 TUI 内：
    #   B          → 打开浏览器标签页（igv.js）
    #   d / s / :gene → 浏览器同步跟随
    #   q          → 退出 TUI，关闭服务器
  

服务器绑定在 127.0.0.1 的临时端口（可通过 --serve-port 覆盖）。igv.js 已打包进二进制，离线可用。使用 --no-browser 禁用此功能。

参考

快捷键

按键	功能
`a` / `←`	向前翻页（整个视窗）
`d` / `→`	向后翻页（整个视窗）
`h`	向前平移 1/10 视窗（精细）
`l`	向后平移 1/10 视窗（精细）
`w` / `↑`	放大
`s` / `↓`	缩小
`j` / `k`	比对泳道向下 / 向上滚动
`+` / `-`	增大 / 缩小比对轨道高度
`]` / `[`	增大 / 缩小覆盖度轨道高度
`\`	切换信号轨道共享 / 独立 Y 轴
`}` / `{`	增大 / 缩小信号轨道高度
`<` / `>`	缩小 / 增大环轨道高度
`:` 或 `g`	打开命令面板（坐标或基因名称）
`m<c>`	设置书签到字母 c
`'<c>`	跳转到书签 c
`t`	循环切换主题
`S`	保存当前视图 SVG 快照
`B`	打开浏览器视图（igv.js）
`?`	切换快捷键帮助覆盖层
`q` / Ctrl-C	退出

配置

配置文件

启动时自动读取可选的 ~/.config/igv-rs/config.toml：

    [theme]
    # "dark" | "light" | "paper" | "solarized-dark" | "solarized-light"
    # | "dracula" | "gruvbox-dark"
    preset = "dark"
    
    [theme.custom]
    # 覆盖单个样式键
    "A"        = "bold green"
    "MISMATCH" = "bold white on red"
    "SIGNAL"   = "cyan"
    "LINK"     = "magenta"
    
    [serve]
    auto_open = true   # --no-browser 可覆盖
    port      = 0      # 0 = 临时端口；--serve-port 可覆盖
  

注意事项

已知限制

长按按键去抖未实现 — 建议点击而非长按导航键。
[render] 配置键（zoom_factor、nav_overlap、阈值覆盖）尚未读取。
[bookmarks] 配置表未加载 — 会话内书签功能正常。
宽视图覆盖度被隐藏而非热力图显示 — 染色体级别深度建议使用预计算 bigWig。
BAM 标签显示按标签着色时使用 Rust 的 Debug 格式（如 Int8(42) 而非 42）。
无信号轨道缓存 — 每次区域变更均重新获取 bigWig 数据。
单一信号色图 — 所有 bigWig 轨道共用 SIGNAL 主题键。
bigBed（.bb）暂不支持。
环轨道无 tabix/pairix 支持 — 超过 100 万条记录的 BEDPE 文件加载较慢。
浏览器视图仅限本机回环 — 不支持远程访问和认证令牌。