JavaScript Chart Hit-Test API

Demonstrates how to add Hit-Test on click behavior to a chart using SciChart.js, High Performance JavaScript Charts

src/drawExample.ts
import { appTheme } from "./appTheme";
import { visualiseHitTestPoint } from "./visualizeHitTest";

import {
    SciChartSurface,
    NumericAxis,
    EAxisAlignment,
    NumberRange,
    FastLineRenderableSeries,
    XyDataSeries,
    EllipsePointMarker,
    HitTestInfo,
    DpiHelper,
    EHorizontalAnchorPoint,
    EVerticalAnchorPoint,
    ECoordinateMode,
    EAnnotationLayer,
    EMultiLineAlignment,
    ETextAlignment,
    Thickness,
    NativeTextAnnotation,
} from "scichart";

// This method hit-tests the series body
export const HIT_TEST = "hitTest";
// This method hit-tests the nearest data-point
export const HIT_TEST_DATAPOINT = "hitTestDataPoint";
// This method hit-tests by searching first in X, then Y
export const HIT_TEST_X_SLICE = "hitTestXSlice";

export const drawExample = async (rootElement: string | HTMLDivElement) => {
    // Which hit-test method are we using? See below for usage
    let whichHitTestMethod = HIT_TEST_DATAPOINT;

    // Create a SciChartSurface with theme
    const { wasmContext, sciChartSurface } = await SciChartSurface.create(rootElement, {
        theme: appTheme.SciChartJsTheme,
        title: [
            "Click on the chart to demonstrate Hit-Test API",
            "Change the Hit-Test method above to see the different behaviours",
        ],
        titleStyle: {
            fontSize: 16,
            placeWithinChart: true,
            alignment: ETextAlignment.Left,
            multilineAlignment: EMultiLineAlignment.Left,
            color: appTheme.ForegroundColor + "C4",
            padding: Thickness.fromString("13 4 0 9"),
        },
    });

    // add an event listener for mouse down. You can access the actual SciChartSurface canvas as
    // follows
    sciChartSurface.domCanvas2D.addEventListener("mousedown", (mouseEvent) => {
        // Translate the point to the series viewrect before hit-testing
        // Attention!
        // We need to multiply it by DpiHelper.PIXEL_RATIO
        // DpiHelper.PIXEL_RATIO is used for High DPI and Retina screen support and also for the browser scaling
        const mousePointX = mouseEvent.offsetX * DpiHelper.PIXEL_RATIO;
        const mousePointY = mouseEvent.offsetY * DpiHelper.PIXEL_RATIO;
        // const translatedPoint = translateFromCanvasToSeriesViewRect(mousePoint, sciChartSurface.seriesViewRect);
        const HIT_TEST_RADIUS = 10 * DpiHelper.PIXEL_RATIO;

        // call renderableSeries.hitTestProvider.hitTest passing in the mouse point
        // other parameters determine the type of hit-test operation to perform
        // There are three hit-test methods which have different outcomes. We let the user choose
        let hitTestInfo: HitTestInfo;
        if (whichHitTestMethod === HIT_TEST_DATAPOINT) {
            // Hit-test the nearest data-point, searching first in X, then Y
            hitTestInfo = lineSeries.hitTestProvider.hitTestDataPoint(mousePointX, mousePointY, HIT_TEST_RADIUS);
        }
        if (whichHitTestMethod === HIT_TEST_X_SLICE) {
            // Hit-test the nearest data-point in X only (imagine a vertical slice on the chart)
            hitTestInfo = lineSeries.hitTestProvider.hitTestXSlice(mousePointX, mousePointY, HIT_TEST_RADIUS);
        }
        if (whichHitTestMethod === HIT_TEST) {
            // Hit-test in two-dimensions (slowest method but finds the nearest data-point by distance)
            hitTestInfo = lineSeries.hitTestProvider.hitTest(mousePointX, mousePointY, HIT_TEST_RADIUS);
        }

        // Log the result to console. HitTestInfo contains information about the hit-test operation
        console.log(
            `${hitTestInfo.seriesName} hit test result (${whichHitTestMethod}):\r\n` +
                ` MouseCoord=(${mousePointX}, ${mousePointY})\r\n` +
                ` Hit-Test Coord=(${hitTestInfo.xCoord}, ${hitTestInfo.yCoord})\r\n` +
                ` IsHit? ${hitTestInfo.isHit}\r\n` +
                ` Result=(${hitTestInfo.xValue}, ${hitTestInfo.yValue}) `
        );
        visualiseHitTestPoint(sciChartSurface, hitTestInfo, whichHitTestMethod, 1000);
    });

    // Continue chart setup
    //

    // Create an X,Y Axis. For this example we put y-axis on the left to demonstrate offsetting the mouse-point when hit-testing
    sciChartSurface.xAxes.add(new NumericAxis(wasmContext, { growBy: new NumberRange(0.1, 0.1) }));
    sciChartSurface.yAxes.add(
        new NumericAxis(wasmContext, {
            axisAlignment: EAxisAlignment.Left,
            growBy: new NumberRange(0.1, 0.1),
        })
    );

    // Create a Line Series with XyDataSeries and some data
    const lineSeries = new FastLineRenderableSeries(wasmContext, {
        strokeThickness: 3,
        stroke: appTheme.VividSkyBlue,
        dataSeries: new XyDataSeries(wasmContext, {
            dataSeriesName: "Line Series",
            xValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
            yValues: [0, 1, 5, 1, 20, 5, 1, 8, 9, 3],
        }),
        pointMarker: new EllipsePointMarker(wasmContext, {
            stroke: appTheme.VividSkyBlue,
            fill: appTheme.VividSkyBlue + "33",
            width: 11,
            height: 11,
        }),
    });

    // Add the line series to the SciChartSurface
    sciChartSurface.renderableSeries.add(lineSeries);

    const watermarkAnnotation = (text: string = "") => {
        return new NativeTextAnnotation({
            text,
            fontSize: 32,
            textColor: appTheme.ForegroundColor,
            x1: 0.5,
            y1: 0.5,
            opacity: 0.23,
            horizontalAnchorPoint: EHorizontalAnchorPoint.Center,
            verticalAnchorPoint: EVerticalAnchorPoint.Center,
            xCoordinateMode: ECoordinateMode.Relative,
            yCoordinateMode: ECoordinateMode.Relative,
            annotationLayer: EAnnotationLayer.BelowChart,
        });
    };

    // Add a watermark
    const theWatermark = watermarkAnnotation("METHOD: " + whichHitTestMethod + "()");
    sciChartSurface.annotations.add(theWatermark);

    // Allow changing method and updating watermark.
    const updateHitTestMethod = (hitTestMethod: string) => {
        console.log("Setting hitTestMethod " + hitTestMethod);
        whichHitTestMethod = hitTestMethod;
        theWatermark.text = "METHOD: " + hitTestMethod + "()";
    };

    return { sciChartSurface, wasmContext, controls: { updateHitTestMethod } };
};

Hit Test API Example (JavaScript)

Overview

This example demonstrates the advanced hit testing functionality provided by SciChart.js using JavaScript. It enables users to click on the chart to evaluate different hit test methods such as series.hitTestProvider.hitTestDataPoint, hitTestXSlice, and hitTest. The resulting HitTestInfo is then visualised using temporary scatter series and animated annotations.

Technical Implementation

The implementation begins by configuring a SciChartSurface with a custom theme and title settings. It installs a mousedown event listener directly onto the canvas to capture click events. The event coordinates are adjusted using DpiHelper.PIXEL_RATIO to ensure correct mapping on high DPI and retina displays. Based on the chosen hit test method, the corresponding method from the RenderableSeries Hit-Test API is invoked to determine if the mouse position targets a data point or line segment.

Features and Capabilities

  • Interactive Hit Testing: Switchable methods allow testing with different approaches such as hitTestDataPoint, which finds the nearest data point, hitTestXSlice, which focuses on vertical slices of the chart or hitTest which can find the series body.
  • Visual Feedback and Annotations: The example makes use of dynamic annotations like TextAnnotation and LineAnnotation to visually indicate hit test results, highlighting successes with messages like Hit! or miss....
  • Smooth Animations: Animations are implemented using FadeAnimation and GenericAnimation to ensure that annotations appear and disappear smoothly.

Integration and Best Practices

This example follows best practices for integrating event listeners with the SciChartSurface canvas in JavaScript. It carefully converts mouse event coordinates to chart coordinates, a technique detailed in guides on mouse event coordinate conversion. Additionally, performance is optimized by choosing the most appropriate hit test method depending on the scenario, a concept further explored in the Performance Tips & Tricks documentation.

Overall, the example provides a comprehensive demonstration of SciChart.js capabilities for interactive and animated hit testing—delivering high-performance charting without relying on additional frameworks. Developers looking to build similar interactive charts in JavaScript can refer to the linked documentation for deeper technical insights.