🔬 Cell Type Legend ↔ UMAP Tooltip 偏移问题 — 根因分析与修复方案

📋 一、问题现象

在 Longevity & Aging Cell Atlas 的 speciesinfo.php 页面中：

• UMAP 上每个细胞根据 binary 文件中的 typeId 着色
• 右侧 Legend 列出所有 cell types，每个条目有对应色块
• 问题：点击 Legend 中的某个 cell type 后，UMAP 高亮的细胞 tooltip 显示的是另一种 cell type

🗂️ 二、数据架构

🔍 三、代码执行流 — 逐步追踪

Step 1: _extractCellTypes() — 提取 JSON Legend

// 从页面 JSON 解析出所有 cell type
this.cellTypes = [];   // 按 JSON 中出现的顺序存入数组
jsonData.forEach(item => {
    this.cellTypes.push({
        name: item.name,
        index: item.index,    // JSON 中的 index 字段 (可能 ≠ 数组下标)
        count: item.count,
        color: item.color,
        category: item.category
    });
});
// 结果: cellTypes[0].index 可能是 0, 也可能是 5, 取决于 JSON 顺序

Step 2: _detectBestOffset() — 自动检测偏移量

// 对比每个 cell type 的 count 来猜测 offset
for (let offset = -20; offset <= 20; offset++) {
    let score = 0;
    this.cellTypes.forEach(ct => {
        let mappedId = ct.index + offset;
        let binCount = binaryCounts[mappedId];  // binary 中该 ID 的细胞数
        if (差异 < 10%) score += 10;
        else score += 1;
    });
}
// 结果: offset=0, score=1140 (看似完美)
// 但这只证明 ct.index 与 binary typeId 的 COUNT 匹配
// 并不能证明 palette 颜色分配是一致的!

Step 3: _applyMapping() — 建立映射

this._idxToName = {};
this.cellTypes.forEach((ct, arrayIndex) => {
    ct.mappedId = ct.index + 0;  // offset=0
    this._idxToName[ct.mappedId] = ct.name;
});
// _idxToName[4] → "Excitatory neurons"  ✓ (name 映射是对的)
// 但 arrayIndex 和 mappedId 的关系被忽略了!

Step 4: Legend 渲染 BUG 所在

this.cellTypes.forEach((ct, arrayIndex) => {
    // 色块颜色 = palette[arrayIndex]
    ctx.fillStyle = this.palette[arrayIndex];  // 用数组下标取色!
    ctx.fillRect(...);
    // 文字
    ctx.fillText(ct.name, ...);
});

// 所以 Legend 中:
// arrayIndex=0 → "B cells"           → palette[0] 🔴
// arrayIndex=1 → "T cells"           → palette[1] 🔵
// arrayIndex=2 → "Excitatory neurons" → palette[2] 🟢
// arrayIndex=4 → "Pericytes"         → palette[4] 🟠

Step 5: UMAP 渲染 BUG 所在

cells.forEach(cell => {
    let typeId = cell.typeId;  // 从 binary 读取, 例如 4
    ctx.fillStyle = this.palette[typeId];  // 用 typeId 取色!
    ctx.fillRect(cell.x, cell.y, ...);
});

// 所以 UMAP 中:
// typeId=4 的细胞 → palette[4] 🟠
// 但 typeId=4 实际是 "Excitatory neurons"
// Legend 里 "Excitatory neurons" 却是 palette[2] 🟢

Step 6: Tooltip 显示

onHover(cell) {
    let name = this._idxToName[cell.typeId];  // 这个是对的: typeId=4 → "Excitatory neurons"
    tooltip.show(name);
}
// 但用户看到的颜色是 palette[typeId]=🟠
// 对应 Legend 中 arrayIndex=4 → "Pericytes" 🟠
// 所以用户 觉得 hover 的是 Pericytes 的颜色区域

🎯 四、根因确认

✅ 五、修复方案

核心思路：统一使用 mappedId 作为 palette 索引，确保 Legend 和 UMAP 取到相同颜色。

// ============================================
// 修复: Legend 渲染部分
// 搜索 Legend 渲染的 forEach 循环
// ============================================

// ❌ 修改前 (Bug):
this.cellTypes.forEach((ct, i) => {
    ctx.fillStyle = this.palette[i];           // 用 arrayIndex
    // ... 绘制色块和文字
});

// ✅ 修改后 (Fix):
this.cellTypes.forEach((ct, i) => {
    ctx.fillStyle = this.palette[ct.mappedId];  // 用 mappedId, 与 UMAP 一致
    // ... 绘制色块和文字
});

// ============================================
// 修复: 在 _applyMapping() 中新增反查表
// ============================================

// ✅ 新增:
this._typeIdToArrayIndex = {};
this.cellTypes.forEach((ct, arrayIndex) => {
    ct.mappedId = ct.index + this._offset;
    this._idxToName[ct.mappedId] = ct.name;
    this._typeIdToArrayIndex[ct.mappedId] = arrayIndex;  // 新增反查
});

// ============================================
// 修复: UMAP 渲染部分
// ============================================

// ❌ 修改前 (Bug):
ctx.fillStyle = this.palette[cell.typeId];

// ✅ 修改后 (Fix):
let aidx = this._typeIdToArrayIndex[cell.typeId];
ctx.fillStyle = this.palette[aidx !== undefined ? aidx : cell.typeId];

// ============================================
// 修复: 在 _applyMapping() 末尾添加
// ============================================

// ✅ 按 mappedId 重排，使 arrayIndex === mappedId
let reordered = new Array(this.cellTypes.length);
this.cellTypes.forEach(ct => {
    if (ct.mappedId >= 0 && ct.mappedId < reordered.length) {
        reordered[ct.mappedId] = ct;
    }
});
// 填补空位（mappedId 超出范围或有空洞时）
let spare = this.cellTypes.filter(ct =>
    ct.mappedId < 0 || ct.mappedId >= reordered.length || reordered[ct.mappedId] !== ct
);
let si = 0;
for (let i = 0; i < reordered.length; i++) {
    if (!reordered[i] && si < spare.length) {
        reordered[i] = spare[si++];
    }
}
this.cellTypes = reordered.filter(Boolean);

// 这样之后 palette[arrayIndex] === palette[mappedId]，全部代码都不需要改

🔧 六、如何在 speciesinfo.php 中定位需修改的代码

在 speciesinfo.php 中搜索以下关键词来定位具体代码行：

✔️ 七、修复后验证方法

📦 八、可直接使用的 JavaScript Patch

如果不想修改原始代码，可以在 speciesinfo.php 的 </body> 前插入以下 <script> 标签：

<script>
// =============================================
// Cell Type Legend ↔ UMAP 颜色修复补丁
// 放在页面底部, 在 GeneViewer 初始化之后执行
// =============================================
(function patchCellTypeMapping() {
    // 等待 viewer 初始化完成
    var checkInterval = setInterval(function() {
        // 尝试找到 viewer 实例 (根据实际变量名调整)
        var viewer = window.geneViewer || window.viewer || window.gv;
        if (!viewer || !viewer.cellTypes || viewer.cellTypes.length === 0) return;
        clearInterval(checkInterval);

        console.log('[Patch] 开始修复 cellType 颜色映射...');

        // 方法: 按 mappedId 重新排列 cellTypes 数组
        // 使得 arrayIndex === mappedId, 从而 palette[arrayIndex] === palette[typeId]
        var maxId = 0;
        viewer.cellTypes.forEach(function(ct) {
            var mid = (ct.mappedId !== undefined) ? ct.mappedId : ct.index;
            if (mid > maxId) maxId = mid;
        });

        var reordered = new Array(maxId + 1);
        var unplaced = [];

        viewer.cellTypes.forEach(function(ct) {
            var mid = (ct.mappedId !== undefined) ? ct.mappedId : ct.index;
            if (mid >= 0 && mid <= maxId && !reordered[mid]) {
                reordered[mid] = ct;
            } else {
                unplaced.push(ct);
            }
        });

        // 填补空位
        var ui = 0;
        for (var i = 0; i <= maxId; i++) {
            if (!reordered[i] && ui < unplaced.length) {
                reordered[i] = unplaced[ui++];
            }
        }

        viewer.cellTypes = reordered.filter(Boolean);

        // 验证
        var fixed = 0, total = viewer.cellTypes.length;
        viewer.cellTypes.forEach(function(ct, i) {
            var mid = (ct.mappedId !== undefined) ? ct.mappedId : ct.index;
            if (i === mid) fixed++;
        });

        console.log('[Patch] 修复完成: ' + fixed + '/' + total + ' 个 cellType 的 arrayIndex === mappedId');

        // 触发重绘 (根据实际方法名调整)
        if (viewer.renderLegend) viewer.renderLegend();
        if (viewer.render) viewer.render();
        if (viewer.draw) viewer.draw();
        if (viewer.refresh) viewer.refresh();

    }, 500);
})();
</script>

📝 总结