brainsmatics

brainsmatics 是一个面向神经科学数据可视化的 React 组件库，用于构建脑图谱、神经元、血管、医学影像、功能环路和 AI 辅助分析相关的前端应用。

项目提供可复用的 2D 查看组件、3D 脑数据可视化模块、医学图像加载能力、统计图表组件、上传管理组件，以及基于 Ant Design X 的 AI 对话组件。

安装

npm install brainsmatics

React 和 React DOM 是 peer dependencies，需要由业务项目安装：

npm install react react-dom

在项目中导入组件：

import { BarChart, UserUpload, Atlas, UploadComponent } from "brainsmatics/STAM";
import "brainsmatics/style.css";

快速开始

import React from "react";
import { BarChart } from "brainsmatics/STAM";
import "brainsmatics/style.css";

export default function App() {
  return (
    <BarChart
      title="脑区信号统计"
      xAxisLabel="脑区"
      yAxisLabel="数值"
      height={420}
      data={[
        { name: "MOp", value: 42 },
        { name: "SSp", value: 31 },
        { name: "VIS", value: 26 }
      ]}
      onBarClick={(item) => console.log(item)}
    />
  );
}

项目可以做什么

brainsmatics 可以用于构建神经科学方向的可视化和分析系统，主要能力包括：

• 展示 3D 标准脑图谱。
• 在同一个 Three.js 场景中展示脑区、核团、血管、神经元等对象。
• 加载并展示 SWC 神经元形态数据。
• 将用户上传的数据插入 3D 场景并进行平移、旋转、缩放、调色和透明度调整。
• 加载 .tif、.tiff 图像栈，并以体数据方式渲染。
• 加载 .nii.gz 压缩 NIfTI 体数据。
• 展示 STL、OBJ、FBX、GLB 等 3D 模型。
• 展示 JSON 格式的线、点、点云、血管、神经元和环路数据。
• 提供 2D 图像浏览、缩略图、网格视图、双视图对比和多视图布局。
• 提供柱状图、热力图、雷达图、弦图、桑基图等神经科学分析图表。
• 支持 TIFF 脑片图像配准相关工作流。
• 支持 TIFF 图像栈体积分析相关工作流。
• 提供基于 Ant Design X 的 AI 对话界面，支持 Markdown、工具调用结果和图表结果展示。
• 支持功能环路分析，包括连接关系、基因表达、突触、单神经元等数据展示。

主要导出

3D 组件

import {
  SideBar,
  PipeLine,
  Auxiliary,
  BottomTabs,
  Atlas,
  AtlasSideBar,
  AtlasBottomTabs,
  ModalLoader,
  Modal2DLoader,
  StlLoader,
  Swctree,
  Sections,
  ShowReglions,
  Carddata,
  FunctionLoop,
  FunctionLoopSwc,
  AiViewer,
  UserUpload,
  UploadComponent,
  VolumeAnalysis
} from "brainsmatics/STAM";

这些组件主要用于完整的 3D 神经科学工作台。部分组件需要宿主应用提供 Three.js 的 renderer、camera、scene、controls、图谱状态、回调函数或后端接口。

2D 组件

import {
  GridViewer,
  NavTree,
  NaviGation,
  InfoDiv,
  TwoViewer,
  Thumbnail,
  MulfiViewer,
  Distribution
} from "brainsmatics/STAM";

这些组件适合用于 2D 数据浏览、图像导航、缩略图展示、对比查看和多视图布局。

图表组件

import {
  BarChart,
  HeatmapChart,
  RadarChart,
  ChordChart,
  SankeyChart,
  ChartViewer
} from "brainsmatics/STAM";

图表组件基于 ECharts，适合展示脑区统计、连接关系、证据矩阵、功能环路结果和分析摘要。

通用组件和工具

import {
  Header,
  Button,
  scene,
  camera,
  scale,
  tranX,
  tranY,
  tranZ
} from "brainsmatics/STAM";

工具导出中包含部分 3D 模块共用的全局 Three.js 状态。

支持的数据类型

| 数据类型 | 典型用途 | | --- | --- | | .tif、.tiff | 2D 脑片配准、3D TIFF 图像栈渲染 | | .nii.gz | NIfTI 体数据渲染 | | .swc | 神经元形态和骨架展示 | | .stl、.obj、.fbx、.glb | 3D 形态模型展示 | | .json | 点、线、点云、血管、神经元、环路数据 | | .png、.jpg、.jpeg、.gif | 2D 图像平面和图像序列展示 |

地址栏参数

部分 3D 页面支持通过 URL query 参数恢复场景状态或加载数据。

通过 URL 加载 TIFF / NIfTI 数据

3D 页面可以通过 UploadComponent 读取以下参数，将 URL 数据作为场景文件加载，并支持选中后的位移、旋转、缩放、颜色和亮度等控制：

tiffDataPath
tiffInfo

示例：

?tiffDataPath=/staticresource/data/TIFF/test.tif&tiffInfo=%7B%22min%22%3A%7B%22x%22%3A0%2C%22y%22%3A0%2C%22z%22%3A0%7D%2C%22max%22%3A%7B%22x%22%3A11400%2C%22y%22%3A9000%2C%22z%22%3A14000%7D%2C%22max_resample%22%3A%7B%22x%22%3A1022%2C%22y%22%3A731%2C%22z%22%3A1400%7D%7D

tiffInfo 解码后格式如下：

{
  "min": { "x": 0, "y": 0, "z": 0 },
  "max": { "x": 11400, "y": 9000, "z": 14000 },
  "max_resample": { "x": 1022, "y": 731, "z": 1400 }
}

tiffDataPath 必须是浏览器可以直接 fetch 到的 .tif、.tiff、.nii 或 .nii.gz 地址。.nii/.nii.gz 会按 NiiGZ 类型加载；其他情况默认按 TIFF 类型加载。

如果 tiffInfo 中包含 min、max、max_resample，会用它们推导初始位置和缩放。tiffInfo 也可以附加或覆盖场景控制参数，例如：

{
  "file_type": "NiiGZ",
  "translateX": 0,
  "translateY": -1.5,
  "translateZ": 0,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "resolution": 10
}

恢复上传到场景中的文件

UploadComponent 可以通过以下参数恢复已共享的上传文件：

userSceneFiles

TIFF 示例：

[
  {
    "file_type": "TIFF",
    "id": "file-id-from-server",
    "original_filename": "sample.tif",
    "translateX": 0,
    "translateY": -1.5,
    "translateZ": 0,
    "scaleX": 1,
    "scaleY": 1,
    "scaleZ": 1,
    "resolution": 10
  }
]

NIfTI 示例：

[
  {
    "file_type": "NiiGZ",
    "id": "file-id-from-server",
    "original_filename": "sample.nii.gz",
    "translateX": 0,
    "translateY": -1.5,
    "translateZ": 0,
    "scaleX": 1,
    "scaleY": 1,
    "scaleZ": 1,
    "resolution": 10
  }
]

组件会通过以下接口读取上传文件：

/app-api/userDB-api/files/{id}

因此文件需要已经存在于服务端，并且处于共享状态，或者当前浏览器拥有对应的访问 key。

后端和运行环境说明

本组件库中有一部分组件是纯前端 UI 组件，也有一部分组件依赖项目后端接口和静态资源。

3D 工作台中常见的后端或静态资源路径包括：

/app-api/userDB-api/files/{id}
/app-api/neuron-reg/...
/staticresource/...

如果在其他项目中集成，需要在业务项目里配置代理或部署规则，确保这些路径能够正确访问。

3D 体数据、图谱和医学影像组件依赖浏览器 WebGL 能力。TIFF 和 NIfTI 渲染路径使用 Three.js 3D texture 或 texture array，推荐使用支持 WebGL2 的现代浏览器。

开发

安装依赖：

npm install

启动 Vite 开发服务：

npm run dev

构建组件库：

npm run build

启动 Storybook：

npm run storybook

构建 Storybook：

npm run build-storybook

发布

当前包发布到 npm 的包名是：

brainsmatics

发布前建议先构建并检查 npm 包内容：

npm run build
npm pack --dry-run

使用 npm 发布：

npm publish

也可以使用 Yarn Classic 发布：

yarn publish --force

package.json 中配置了 files 字段，因此 npm 发布时只会包含：

• dist
• package.json
• README.md
• LICENSE

这样可以避免把 .env、IDE 配置、日志、缓存、源码目录等开发文件发布到 npm。

项目结构

src/
  component/
    2d/                2D 查看器、图表、导航、缩略图
    3d/                3D 图谱、上传、AI 对话、体数据、配准模块
    common/            通用 UI 组件
    types/             公共 TypeScript 类型
    util/              公共工具和全局 Three.js 状态
  stories/             Storybook 示例
  assets/              字体、图标和静态前端资源

技术栈

• React 18
• TypeScript
• Vite
• Ant Design
• Ant Design X
• Three.js
• ECharts
• GeoTIFF
• nifti-reader-js
• Storybook

许可证

MIT