简介：seisplotjs 是一套面向地震数据处理与可视化开发者的 JavaScript 模块库，适合具备一定前端基础、需要在地震学项目中快速实现数据解析与绘图的工程师和研究人员。它围绕 FDSN Web 服务构建，涵盖数据链路协议、日期时间选择控件、经纬度距离计算、可用性查询、数据中心注册表查询，以及地震图、地震事件、台站通道等子模块，并集成 OregonDSP 实现离散傅立叶变换，配合 d3 完成频谱绘制。资源包共 184 个文件，以 83 个 js 源码、60 个 html 示例页、14 个 css 样式为主，另含 sac、mseed、staxml、sacpz 等地震数据样本及少量 Python 脚本，压缩包约 1.02MB，目录按子模块划分，便于按需查阅与二次开发。目前已有 319 人学习下载。借助这些示例与源码，读者可掌握从数据请求、格式解析到波形与频谱渲染的完整链路，并参考现成页面快速搭建自己的地震数据展示工具。

1. seisplotjs 到底解决什么问题：从一段地震波形到可交互网页

如果你手头有一批 MiniSEED 或 SAC 格式的地震波形，想把它放到浏览器里让人缩放、量取震相到时、叠加台站分布，传统做法是后端渲染成图片再传给前端。这条路能走通，但交互性差、每次改参数都要重新出图，遇到长波形或高采样率数据时后端压力也不小。seisplotjs 就是冲着这个场景来的：一个纯 JavaScript 模块，把地震数据的解析、处理和绘制都搬到浏览器端完成。它面向的是做地震监测、台网数据展示、科研波形浏览的开发者，尤其是那些已经有一套数据服务、只想在前端快速搭出可交互波形界面的人。核心能力可以拆成三块——解析常见地震数据格式、对波形做时间轴和量纲上的处理、用 Canvas 或 SVG 把结果画出来。下面按“先搞清楚它怎么组织数据，再动手跑通最小示例，最后处理真实数据里的坑”这条线展开。

2. 解析层怎么工作：MiniSEED、SAC 与数据对象模型

2.1 为什么浏览器端解析地震数据不是简单事

地震数据格式和普通 JSON 不一样。MiniSEED 是二进制流，记录头段里塞了台站名、通道名、采样率、起始时间、采样点数，数据段之间还可能不连续；SAC 虽然结构相对固定，但也是二进制加头段。浏览器里没有现成的文件系统，读进来的 ArrayBuffer 需要自己按字节偏移去取字段。seisplotjs 的做法是提供一组解析器，把不同格式统一转成内部的数据对象，通常是Seismogram或Timeseries这类结构，里面包含时间范围、采样率、数据数组和元信息。这样上层绘制代码不用关心原始格式，只面对统一接口。

常见做法是先用fetch把数据取成ArrayBuffer，再交给对应的解析函数。这里有个容易忽略的点：MiniSEED 一个文件里可能包含多个数据段，解析结果应该是数组而不是单个对象。如果你直接拿第一个段去画，后面段的数据就丢了，波形会出现断档。

2.2 用 fetch 加解析器读一个 MiniSEED 文件

下面这段代码演示从网络加载一个 MiniSEED 文件并解析成波形对象。注意miniseed解析器返回的是数组，需要遍历处理。

// 引入 seisplotjs 的 miniseed 解析模块 import { parse } from 'seisplotjs-miniseed'; async function loadMiniSEED(url) { // 取二进制数据，不能按文本读 const response = await fetch(url); const arrayBuffer = await response.arrayBuffer(); // 解析成数据段数组，每个元素包含 header 和 data const segments = parse(arrayBuffer); // 过滤掉空段，并按起始时间排序 const validSegments = segments .filter(seg => seg.data && seg.data.length > 0) .sort((a, b) => a.header.startTime - b.header.startTime); console.log(`共解析出 ${validSegments.length} 个数据段`); validSegments.forEach((seg, i) => { console.log(`段 ${i}: 台站 ${seg.header.station}, 通道 ${seg.header.channel}, ` + `采样率 ${seg.header.sampleRate}, 点数 ${seg.data.length}`); }); return validSegments; } loadMiniSEED('/data/example.mseed').catch(err => { console.error('解析失败:', err); });

逻辑说明：fetch拿到的是Response，必须用arrayBuffer()而不是text()，否则二进制会被破坏。parse函数内部按 MiniSEED 块结构逐块读取，每个块固定 512 字节头段加数据记录。返回的segments里，header.startTime通常是Date对象或时间戳，排序是为了后续拼接时顺序正确。参数方面，sampleRate单位是 Hz，data是Float32Array或普通数组，取决于解析器实现。如果解析结果为空，先检查文件是不是真的 MiniSEED，有些服务端会把 SAC 数据错误地标成.mseed后缀。

2.3 数据对象模型与时间轴对齐

解析出来的段不能直接画，因为不同段的起始时间可能不连续，采样率也可能不同。seisplotjs 内部通常有一个Seismogram类，负责把多个段合并成一条连续时间轴。合并逻辑是：以最早起始时间为零点，按采样率计算每个采样点的时间偏移，遇到空洞就插入null或 NaN。这一步很关键，否则画出来的波形时间轴是错的，量取震相到时也会偏。

我一般会先检查段之间的时间间隔。如果两个段之间差了超过一个采样周期，就认为有数据空洞。处理空洞时，可以选择在空洞处断开绘制，或者用直线连接，前者更诚实，后者好看但会误导。seisplotjs 的绘制层通常支持传入一个Seismogram对象，内部已经处理好了时间映射。如果你自己拼数据，记得把startTime和sampleRate设对，否则绘制时横轴刻度会乱。

3. 绘制层怎么落地：Canvas 波形图与交互缩放

3.1 从数据到像素：时间轴和振幅轴的映射

绘制波形本质上是把（时间，振幅）映射到（x，y）像素坐标。时间轴映射需要知道当前视窗的时间范围和画布宽度，振幅轴映射需要知道数据的最大值和最小值，或者用固定量纲。seisplotjs 的绘制模块通常提供一个Seismograph或WaveformPlot类，你给它一个容器元素和数据对象，它内部计算映射并调用 Canvas API 画线。

一个常见需求是让用户用鼠标滚轮缩放时间轴。实现方式是监听wheel事件，根据滚轮方向调整视窗的起止时间，然后重绘。重绘时不需要重新解析数据，只需要重新计算映射。这里有个性能点：如果数据点有几万个，每帧都遍历全部点画线会卡。优化方法是根据当前视窗宽度做降采样，比如每像素取一个振幅极值，这样绘制点数从几万降到几百。

3.2 最小可运行的波形绘制示例

下面代码用 Canvas 画一条简单波形，并支持滚轮缩放。为了聚焦绘制逻辑，数据用模拟的正弦波加噪声。

// 假设已有一个 canvas 元素，id 为 waveform const canvas = document.getElementById('waveform'); const ctx = canvas.getContext('2d'); // 模拟数据：采样率 100Hz，时长 10 秒 const sampleRate = 100; const duration = 10; const totalSamples = sampleRate * duration; const data = new Float32Array(totalSamples); for (let i = 0; i < totalSamples; i++) { const t = i / sampleRate; data[i] = Math.sin(2 * Math.PI * 2 * t) + (Math.random() - 0.5) * 0.3; } // 视窗时间范围，单位秒 let viewStart = 0; let viewEnd = duration; function draw() { const width = canvas.width; const height = canvas.height; ctx.clearRect(0, 0, width, height); // 计算视窗内对应的采样点索引 const startIdx = Math.floor(viewStart * sampleRate); const endIdx = Math.min(Math.ceil(viewEnd * sampleRate), totalSamples); const visibleSamples = endIdx - startIdx; // 找振幅极值用于纵向缩放 let maxAmp = 0.001; for (let i = startIdx; i < endIdx; i++) { maxAmp = Math.max(maxAmp, Math.abs(data[i])); } ctx.beginPath(); ctx.strokeStyle = '#1a73e8'; ctx.lineWidth = 1; for (let px = 0; px < width; px++) { // 每个像素对应的时间 const t = viewStart + (px / width) * (viewEnd - viewStart); const idx = Math.floor(t * sampleRate); if (idx < 0 || idx >= totalSamples) continue; const x = px; const y = height / 2 - (data[idx] / maxAmp) * (height / 2 - 10); if (px === 0) ctx.moveTo(x, y); else ctx.lineTo(x, y); } ctx.stroke(); // 画时间轴刻度 ctx.fillStyle = '#333'; ctx.font = '12px sans-serif'; for (let s = Math.ceil(viewStart); s <= viewEnd; s++) { const x = ((s - viewStart) / (viewEnd - viewStart)) * width; ctx.fillText(`${s}s`, x + 2, height - 4); } } // 滚轮缩放 canvas.addEventListener('wheel', (e) => { e.preventDefault(); const zoomFactor = e.deltaY > 0 ? 1.2 : 0.8; const center = (viewStart + viewEnd) / 2; const halfRange = ((viewEnd - viewStart) / 2) * zoomFactor; viewStart = Math.max(0, center - halfRange); viewEnd = Math.min(duration, center + halfRange); draw(); }); draw();

逻辑说明：draw函数先根据视窗时间算出可见采样点范围，然后逐像素找对应采样点。这里为了简单，每个像素只取一个采样点，实际工程中应该取该像素对应时间段内的最大值和最小值，画成竖线，这样高频波形不会因为抽样而失真。maxAmp用于纵向归一化，保证波形在画布内。滚轮事件里zoomFactor控制缩放速度，center保持缩放中心在视窗中间。参数方面，canvas.width和canvas.height建议按设备像素比设置，否则高分屏上会模糊。如果波形画出来是一条直线，先检查maxAmp是不是太小导致纵向放大过度，或者数据本身全是零。

3.3 叠加台站分布与震相标记

实际地震数据展示往往不止一条波形。常见做法是在波形图上方或旁边画一个地图，标出台站位置，点击台站时高亮对应波形。seisplotjs 本身不包含地图库，但可以和其他地图库配合，把台站经纬度转成屏幕坐标。另一个需求是标记震相到时，比如 P 波、S 波。实现方式是在波形图上画竖线，位置由时间决定。如果波形支持缩放，标记线也要跟着动，所以标记应该存成时间值而不是像素值，每次重绘时重新计算 x 坐标。

我一般会把震相标记做成一个数组，每个元素包含time、label、color。绘制时遍历数组，把时间映射到 x 像素，画竖线和文字。注意文字不要重叠，如果多个标记时间接近，可以错开 y 坐标。这些交互细节在 seisplotjs 的示例里通常有体现，但需要自己根据项目调整。

4. 处理真实数据时的避坑与排查

4.1 波形显示为空白或一条直线

现象：解析成功，控制台有数据，但画布上什么都没有。原因通常是振幅归一化除了零，或者数据数组里全是 NaN。MiniSEED 解析时如果头段里的采样率读错，比如把 100 读成 0，后续计算会出问题。解决：在绘制前打印data的前几个值和maxAmp，确认数据有效。如果maxAmp是 0，检查数据是否真的全零，或者解析时字节偏移错了。

4.2 时间轴刻度与真实时间对不上

现象：波形形状对，但横轴显示的时间不是数据实际起始时间。原因是没有把数据段的startTime传给绘制层，绘制层默认从 0 开始。解决：解析后把header.startTime转成Date对象，绘制时用这个时间作为时间轴零点。如果多个段起始时间不同，合并时要按最早时间对齐，其他段的时间偏移要加上去。

4.3 大数据量下页面卡顿

现象：加载几十分钟的高采样率数据后，缩放和拖动明显掉帧。原因是每帧遍历全部采样点。解决：实现降采样，按当前视窗宽度计算每个像素对应的时间段，取该段内的最大值和最小值画竖线。这样绘制点数等于像素数，和总数据量无关。另外，解析和绘制可以放到 Web Worker 里，避免阻塞主线程。

4.4 跨域请求被浏览器拦截

现象：本地打开 HTML 文件，用fetch请求远程数据时控制台报 CORS 错误。原因：浏览器同源策略限制。解决：数据服务端需要设置Access-Control-Allow-Origin头，或者把数据文件和 HTML 放在同一个域下。开发阶段可以用本地服务器代理，但不要在前端代码里硬编码代理地址。

4.5 不同格式的时间字段含义混淆

现象：SAC 和 MiniSEED 解析出来的起始时间差了几秒或几十年。原因：SAC 头段里的时间参考年份可能是 1970 或 1900，而 MiniSEED 用 UTC 时间戳。解决：统一转成 JavaScriptDate对象时，注意年份基准。SAC 的nzyear字段如果是两位数，需要判断世纪。我一般会在解析后打印startTime.toISOString()确认。

5. 进阶技巧：用降采样和分层绘制撑住长波形交互

长波形交互的核心矛盾是数据量和渲染速度。假设有一条 24 小时、100Hz 的波形，总共 864 万个采样点。如果每帧都画全部点，浏览器肯定扛不住。我的做法是分两层：底层用降采样后的概览波形，上层用当前视窗内的原始数据。概览波形只在数据加载时计算一次，每个像素存一个最大值和一个最小值，数据量降到几千个点。当用户缩放时，如果视窗时间范围大于某个阈值（比如 10 秒），就画概览波形；小于阈值时，再取原始数据画细节。

降采样的实现可以用一个循环，按像素宽度把数据分段，每段找极值。下面是一个简化的降采样函数：

function downsample(data, sampleRate, pixelsPerSecond) { // 计算每个像素对应多少个采样点 const samplesPerPixel = Math.max(1, Math.floor(sampleRate / pixelsPerSecond)); const result = []; for (let i = 0; i < data.length; i += samplesPerPixel) { let min = Infinity; let max = -Infinity; const end = Math.min(i + samplesPerPixel, data.length); for (let j = i; j < end; j++) { if (data[j] < min) min = data[j]; if (data[j] > max) max = data[j]; } result.push({ min, max, startIdx: i }); } return result; }

这个函数返回每个像素段的极值，绘制时每个像素画一条从min到max的竖线。pixelsPerSecond根据当前画布宽度和视窗时间范围算出来。参数调整上，samplesPerPixel至少为 1，否则会丢点。如果数据里有 NaN，极值计算会得到 NaN，需要先过滤或替换。

另一个技巧是分层绘制到离屏 Canvas。把概览波形画到一个隐藏的 Canvas 上，交互时只重绘上层细节，底层直接drawImage贴过来。这样缩放时不用重新计算概览。离屏 Canvas 的尺寸和主画布一致，数据更新时重新生成。注意内存占用，长波形的概览数据虽然点数少，但如果同时打开多个文件，还是建议用完就释放。

验证降采样是否正确，可以对比降采样前后波形的包络。如果降采样后波形明显变细或丢失峰值，说明samplesPerPixel太大。我一般会先用 1 秒每像素试，再根据视觉效果调整。最后，别忘了在缩放时更新视窗范围后重新计算降采样参数，否则放大后还是用旧的概览数据，细节就出不来。这些经验都是我在实际项目里反复调出来的，希望帮到你。

本文还有配套的精品资源，点击获取