linear-tick

English | 中文

Draw everything on canvas with linear ticks

Installation

npm i linear-tick

Usage

Basic Usage

import { LinearTick } from 'linear-tick';

const canvas = document.getElementById('myCanvas') as HTMLCanvasElement;
const linearTick = new LinearTick();
linearTick.canvas = canvas;

linearTick.ticks = [{
    multiply: 10,
    maxDensityToShow: 3,
    drawCall: {
        init(ctx) {
            ctx.strokeStyle = 'red'
            ctx.lineWidth = 2
            ctx.beginPath()
        },
        each(ctx, store, state, params) {
            ctx.moveTo(state.x, state.y)
            ctx.lineTo(state.x, state.y + params.height)
        },
        end(ctx) { ctx.stroke() }
    }
}];

linearTick.draw();

Properties

LinearTick<STORE = Record<string, any>> class exposes the following properties:

• canvas?: HTMLCanvasElement - The canvas element
• keepSameSizeWith?: HTMLElement - If set, params.width and params.height will be calculated based on this element's size and params.pixelRatio, and automatically adjusted when the size changes
• drawNextFrame: boolean - Whether to draw on the next frame
• whenResized?: WhenResized - Action to perform when the size changes
• initStore?: () => STORE - Function to initialize custom state. If not provided, drawing will receive an empty object as store. Note: If STORE is not Record<string, any>, provide this function to ensure proper initialization.
• initDraw?: InitDrawFn<STORE> - Function executed before any drawing starts; returning null aborts the draw
• finalDraw?: FinalDrawFn<STORE> - Function executed after all drawing is completed
• ticks: LinearTickDefine<STORE>[] - Tick definitions, recommended to be sorted by multiply from small to large
• params: LinearTickParams - Parameters

Methods provided by LinearTick:

• setParams(params: Partial<LinearTickParams>) - Update parameters
• draw() - Perform drawing
• valueToCoord(value: number) - Convert a tick value to canvas pixel coordinates
• coordToValue(x: number, y: number) - Convert canvas pixel coordinates to a tick value

Tick Definition

The LinearTickDefine<STORE> interface defines the structure of a tick:

• multiply: number - Multiplier for tick values, i.e., how many values correspond to one tick
• zeroOffset?: number - Offset for tick values, e.g., with offset 3 and multiply 5, ticks will be 3, 8, 13, 18...
• maxDensityToShow?: number - Ticks will be hidden when density is greater than this value
• shy?: boolean - Whether to hide this tick when subsequent ticks overlap with it
• drawCall: LinearTickDrawCall<STORE> | LinearTickDrawCall<STORE>[] - Drawing function definition, if an array, drawn in order

The LinearTickDrawCall<STORE> interface defines the drawing functions:

• init?: InitDrawFn<STORE> - Executed before drawing starts, returns null to abort drawing
• each: DrawCallFn<STORE> - Executed for each drawing
• final?: FinalDrawFn<STORE> - Executed when drawing ends

The DrawCallFn<STORE, STATE = LinearTickDrawState, RT = void> defines the drawing function:

declare type DrawCallFn<STORE, STATE = LinearTickDrawState, RT = void> = (
    ctx: CanvasRenderingContext2D,  // Canvas context
    store: STORE,                   // Custom state
    state: Readonly<STATE>,         // Drawing state
    params: LinearTickParams,       // Parameters
) => RT
declare type InitDrawFn<STORE> = DrawCallFn<STORE, LinearTickDrawStaticState, void | null>
declare type FinalDrawFn<STORE> = DrawCallFn<STORE, LinearTickDrawStaticState>

The LinearTickDrawStaticState interface defines the drawing state:

• originX: number - Pixel coordinate of origin X used for drawing
• originY: number - Pixel coordinate of origin Y used for drawing
• firstUnit: number - The first unit index that fits on canvas (in direction vector multiples)
• lastUnit: number - The last unit index that fits on canvas
• firstValue: number - First tick value that can fit on the canvas
• lastValue: number - Last tick value that can fit on the canvas

The LinearTickDrawState interface includes the properties from LinearTickDrawStaticState and the following properties:

• x: number - X coordinate of the current drawing position
• y: number - Y coordinate of the current drawing position
• value: number - Tick value at the current drawing position

Parameters

Default parameters are available as LinearTick.defaultParams with type LinearTickParams and have the following values by default:

{
    value: 0,
    anchorX: 0,
    anchorY: 0,
    directionX: 1,
    directionY: 0,
    density: 0.1,
    width: 100,
    height: 20,
    redundancy: 1,
    minDensity: 0.02,
    maxDensity: 100,
}

The ParamsUsedWhenTrans interface defines the parameters used during the transformation process:

• value: number - Value corresponding to the anchor point
• anchorX: number - X coordinate of the anchor point on the canvas, range [0, 1], 0 is leftmost, 1 is rightmost
• anchorY: number - Y coordinate of the anchor point on the canvas, range [0, 1], 0 is topmost, 1 is bottommost
• directionX: number - X component of the unit vector, in pixels. Recommended unit vector length is 1px
• directionY: number - Y component of the unit vector
• density: number - Density, i.e., number of values per unit vector
• width: number - Drawing pixel width
• height: number - Drawing pixel height
• pixelRatio?: number - Pixel ratio. Will be set to window.devicePixelRatio if not provided

The LinearTickParams interface includes the properties from ParamsUsedWhenTrans and the following parameters:

• min?: number - Minimum value of the drawing range, ticks smaller than this will not be drawn
• max?: number - Maximum value of the drawing range, ticks larger than this will not be drawn
• redundancy: number - Number of units the visible range should be extended by to prevent missing drawings at the edges
• minDensity: number - Minimum density, i.e., number of values per unit vector when zoomed out to maximum, will limit the minimum value of density
• maxDensity: number - Maximum density, i.e., number of values per unit vector when zoomed in to minimum, will limit the maximum value of density

Responsiveness

const container = document.getElementById('container');
const linearTick = new LinearTick();
linearTick.canvas = document.getElementById('myCanvas') as HTMLCanvasElement;
linearTick.keepSameSizeWith = container;
linearTick.whenResized = WhenResized.Draw;

This setup makes the canvas automatically adjust its size and redraw when the container element's size changes.

WhenResized is an enum that defines LinearTick's behavior when the container size changes:

• DoNothing - Do nothing when the size changes
• Draw - Respond to size changes and redraw
• DrawNextFrame - Respond to size changes, but don't redraw immediately, wait until the next frame to redraw