Skip to content

SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.

5.9 KB
Raw Blame
import uPlot, { Series } from 'uplot';

import { DEFAULT_FOCUS_PROXIMITY_VALUE } from '../../constants';
import { PlotMode } from '../../config/types';
import type { UPlotConfigBuilder } from '../../config/UPlotConfigBuilder';
import { Quadtree } from '../../utils/quadtree';
import {
	resolveHit,
	resolvePointDiameter,
	resolveSizeDomain,
	SizeDomain,
} from './geometry';
import {
	DEFAULT_HOVER_TOLERANCE_PX,
	DEFAULT_SCATTER_POINT_SIZE,
	ScatterHit,
	ScatterPluginOptions,
	ScatterSeriesData,
} from './types';

export const SCATTER_FACETS: Series.Facet[] = [
	{ scale: 'x', auto: true },
	{ scale: 'y', auto: true },
];

const HIDDEN_BBOX: uPlot.BBox = { left: -10, top: -10, width: 0, height: 0 };

const TWO_PI = 2 * Math.PI;

/** CSS pixels between a hovered disc and the outline ring drawn around it. */
const HOVER_RING_GAP_PX = 3;
const HOVER_RING_WIDTH_PX = 2;

/** uPlot ceils a cursor point's left/top but not its size; snap so the ring stays centred. */
function snapToPixel(start: number, length: number): [number, number] {
	const snapped = Math.floor(start);
	return [snapped, length + (start - snapped) * 2];
}

export function getSeriesStroke(u: uPlot, seriesIdx: number): string {
	const { stroke } = u.series[seriesIdx];
	const color = typeof stroke === 'function' ? stroke(u, seriesIdx) : stroke;
	return typeof color === 'string' ? color : '';
}

/** uPlot caches built paths on the series; the field is internal to it. */
type SeriesWithPaths = Series & { _paths?: Series.Paths | null };

export interface ScatterPlugin {
	pathBuilder: Series.PathBuilder;
	/** Hover by disc rather than by nearest x: mode 2 has no shared x to scan. */
	cursor: uPlot.Cursor;
	hooks: {
		drawClear: (u: uPlot) => void;
		destroy: (u: uPlot) => void;
	};
	getHit: () => ScatterHit | null;
}

export function createScatterPlugin({
	pointSize = DEFAULT_SCATTER_POINT_SIZE,
	hoverTolerance = DEFAULT_HOVER_TOLERANCE_PX,
}: ScatterPluginOptions = {}): ScatterPlugin {
	let tree: Quadtree<ScatterHit> | null = null;
	let hit: ScatterHit | null = null;

	// Spans every series; cached per dataset.
	let cachedData: uPlot.AlignedData | null = null;
	let cachedDomain: SizeDomain | null = null;

	function getSizeDomain(u: uPlot): SizeDomain | null {
		if (cachedData !== u.data) {
			cachedDomain = resolveSizeDomain(u.data);
			cachedData = u.data;
		}
		return cachedDomain;
	}

	const pathBuilder: Series.PathBuilder = (u, seriesIdx, idx0, idx1) => {
		const path = new Path2D();
		const sizes = (u.data[seriesIdx] as unknown as ScatterSeriesData)[2];
		const domain = getSizeDomain(u);
		const { pxRatio } = uPlot;

		uPlot.orient(
			u,
			seriesIdx,
			(
				_series,
				dataX,
				dataY,
				scaleX,
				scaleY,
				valToPosX,
				valToPosY,
				xOff,
				yOff,
				xDim,
				yDim,
				_moveTo,
				_lineTo,
				_rect,
				arc,
			) => {
				const xMin = scaleX.min ?? -Infinity;
				const xMax = scaleX.max ?? Infinity;
				const yMin = scaleY.min ?? -Infinity;
				const yMax = scaleY.max ?? Infinity;

				for (let i = idx0; i <= idx1; i++) {
					const x = dataX[i];
					const y = dataY[i];
					if (
						x == null ||
						y == null ||
						x < xMin ||
						x > xMax ||
						y < yMin ||
						y > yMax
					) {
						continue;
					}

					const diameter =
						resolvePointDiameter(sizes?.[i], domain, pointSize) * pxRatio;
					const radius = diameter / 2;
					const cx = valToPosX(x, scaleX, xDim, xOff);
					const cy = valToPosY(y, scaleY, yDim, yOff);

					path.moveTo(cx + radius, cy);
					arc(path, cx, cy, radius, 0, TWO_PI);

					tree?.add({
						x: cx - radius - u.bbox.left,
						y: cy - radius - u.bbox.top,
						w: diameter,
						h: diameter,
						seriesIndex: seriesIdx,
						dataIndex: i,
					});
				}
			},
		);

		return { stroke: path, fill: path, clip: null };
	};

	const cursor: uPlot.Cursor = {
		// Selection would set the dashboard time range; neither axis is time here.
		drag: { x: false, y: false, setScale: false },
		dataIdx: (u, seriesIdx): number | null => {
			// uPlot asks series 1..n in order on every cursor move; resolve once.
			if (seriesIdx === 1) {
				const { left = -1, top = -1 } = u.cursor;
				const { pxRatio } = uPlot;
				hit =
					tree && left >= 0 && top >= 0
						? resolveHit(
								tree,
								left * pxRatio,
								top * pxRatio,
								hoverTolerance * pxRatio,
							)
						: null;
			}
			return hit?.seriesIndex === seriesIdx ? hit.dataIndex : null;
		},
		points: {
			bbox: (_u, seriesIdx): uPlot.BBox => {
				if (hit?.seriesIndex !== seriesIdx) {
					return HIDDEN_BBOX;
				}
				const { pxRatio } = uPlot;
				const inset = HOVER_RING_GAP_PX + HOVER_RING_WIDTH_PX;
				const [left, width] = snapToPixel(
					hit.x / pxRatio - inset,
					hit.w / pxRatio + inset * 2,
				);
				const [top, height] = snapToPixel(
					hit.y / pxRatio - inset,
					hit.h / pxRatio + inset * 2,
				);
				return { left, top, width, height };
			},
			fill: (): string => 'transparent',
			stroke: getSeriesStroke,
			width: (): number => HOVER_RING_WIDTH_PX,
		},
		// uPlot only measures series that returned a data index, i.e. the hit one.
		focus: { prox: DEFAULT_FOCUS_PROXIMITY_VALUE, dist: (): number => 0 },
	};

	return {
		pathBuilder,
		cursor,
		hooks: {
			drawClear: (u: uPlot): void => {
				tree = new Quadtree<ScatterHit>(0, 0, u.bbox.width, u.bbox.height);
				// The tree holds only what the path builder drew, so force a rebuild.
				u.series.forEach((series, index) => {
					if (index > 0) {
						(series as SeriesWithPaths)._paths = null;
					}
				});
			},
			destroy: (): void => {
				tree = null;
				hit = null;
				cachedData = null;
				cachedDomain = null;
			},
		},
		getHit: (): ScatterHit | null => hit,
	};
}

export function applyScatterPlugin(
	builder: UPlotConfigBuilder,
	plugin: ScatterPlugin,
): void {
	builder.setMode(PlotMode.Faceted);
	builder.setCursor(plugin.cursor);
	builder.addHook('drawClear', plugin.hooks.drawClear);
	builder.addHook('destroy', plugin.hooks.destroy);
}