matterviz 0.3.6 → 0.4.0

package/dist/plot/core/reference-line.js

@@ -0,0 +1,301 @@
+// Create indexed ref_lines, filtering out invisible ones
+export const index_ref_lines = (ref_lines) => (ref_lines ?? [])
+    .filter((line) => line.visible !== false)
+    .map((line, idx) => ({ ...line, idx }));
+// Map z-index type values to object keys
+const Z_INDEX_KEY_MAP = {
+    'below-grid': `below_grid`,
+    'below-lines': `below_lines`,
+    'below-points': `below_points`,
+    'above-all': `above_all`,
+};
+const apply_span = (start_val, end_val, span) => {
+    if (!span)
+        return [start_val, end_val];
+    return [
+        span[0] !== null ? Math.max(start_val, span[0]) : start_val,
+        span[1] !== null ? Math.min(end_val, span[1]) : end_val,
+    ];
+};
+// Group indexed ref_lines by z-index for ordered rendering
+export function group_ref_lines_by_z(lines) {
+    const groups = {
+        below_grid: [],
+        below_lines: [],
+        below_points: [],
+        above_all: [],
+    };
+    for (const line of lines) {
+        const key = Z_INDEX_KEY_MAP[line.z_index ?? `below-lines`];
+        groups[key].push(line);
+    }
+    return groups;
+}
+// Convert RefLineValue (number | Date | string) to numeric value
+export function normalize_value(value) {
+    if (typeof value === `number`)
+        return value;
+    if (value instanceof Date)
+        return value.getTime();
+    // Empty/whitespace strings are invalid (Number("") returns 0 silently)
+    if (typeof value === `string` && value.trim() === ``) {
+        console.warn(`Invalid RefLineValue: empty string, defaulting to 0`);
+        return 0;
+    }
+    // Try numeric conversion first (handles "42", "3.14", "-5")
+    const num = Number(value);
+    if (!isNaN(num))
+        return num;
+    // Then try as ISO date string (handles "2024-06-15")
+    const parsed = Date.parse(value);
+    if (!isNaN(parsed))
+        return parsed;
+    console.warn(`Invalid RefLineValue: "${value}", defaulting to 0`);
+    return 0;
+}
+// Normalize a point tuple
+export const normalize_point = (point) => [
+    normalize_value(point[0]),
+    normalize_value(point[1]),
+];
+// Clip a line segment to a rectangle using Liang-Barsky algorithm
+// Returns clipped [x1, y1, x2, y2] or null if segment is entirely outside
+function clip_segment_to_rect(p1x, p1y, p2x, p2y, x_min, x_max, y_min, y_max) {
+    const dx = p2x - p1x;
+    const dy = p2y - p1y;
+    // p values represent the direction, q values the signed distance to boundary
+    // Boundaries: left (x_min), right (x_max), bottom (y_min), top (y_max)
+    const p_vals = [-dx, dx, -dy, dy];
+    const q_vals = [p1x - x_min, x_max - p1x, p1y - y_min, y_max - p1y];
+    let [t_enter, t_leave] = [0, 1];
+    for (let idx = 0; idx < 4; idx++) {
+        if (p_vals[idx] === 0) {
+            // Line parallel to boundary
+            if (q_vals[idx] < 0)
+                return null; // Outside and parallel - no intersection
+        }
+        else {
+            const t_val = q_vals[idx] / p_vals[idx];
+            // Entering boundary
+            if (p_vals[idx] < 0)
+                t_enter = Math.max(t_enter, t_val);
+            // Leaving boundary
+            else
+                t_leave = Math.min(t_leave, t_val);
+        }
+    }
+    if (t_enter > t_leave)
+        return null; // Segment entirely outside
+    return [p1x + t_enter * dx, p1y + t_enter * dy, p1x + t_leave * dx, p1y + t_leave * dy];
+}
+// Compute the screen coordinates for a reference line
+// Returns [x1, y1, x2, y2] in pixel coordinates, or null if line is not visible
+export function resolve_line_endpoints(ref_line, { x_min, x_max, y_min, y_max, }, { x_scale, x2_scale, y_scale, y2_scale, }) {
+    // Determine which scales to use based on axis assignment
+    const active_x_scale = ref_line.x_axis === `x2` && x2_scale ? x2_scale : x_scale;
+    const active_y_scale = ref_line.y_axis === `y2` && y2_scale ? y2_scale : y_scale;
+    // Check if value is within plot bounds (for visibility)
+    const is_x_visible = (x_val) => x_val >= x_min && x_val <= x_max;
+    const is_y_visible = (y_val) => y_val >= y_min && y_val <= y_max;
+    // Apply span constraints (works for both x and y)
+    const apply_x_span = (x1, x2) => apply_span(x1, x2, ref_line.x_span);
+    const apply_y_span = (y1, y2) => apply_span(y1, y2, ref_line.y_span);
+    // Relative to data coordinate conversion
+    const to_data_x = (rel) => x_min + rel * (x_max - x_min);
+    const to_data_y = (rel) => y_min + rel * (y_max - y_min);
+    let x1_data = 0;
+    let y1_data = 0;
+    let x2_data = 0;
+    let y2_data = 0;
+    const line_type = ref_line.type;
+    if (line_type === `horizontal`) {
+        const y_val = normalize_value(ref_line.y);
+        const y_coord = ref_line.coord_mode === `relative` ? to_data_y(y_val) : y_val;
+        if (!is_y_visible(y_coord))
+            return null;
+        [x1_data, x2_data] = apply_x_span(x_min, x_max);
+        y1_data = y_coord;
+        y2_data = y_coord;
+    }
+    else if (line_type === `vertical`) {
+        const x_val = normalize_value(ref_line.x);
+        const x_coord = ref_line.coord_mode === `relative` ? to_data_x(x_val) : x_val;
+        if (!is_x_visible(x_coord))
+            return null;
+        x1_data = x_coord;
+        x2_data = x_coord;
+        [y1_data, y2_data] = apply_y_span(y_min, y_max);
+    }
+    else if (line_type === `diagonal` || line_type === `line`) {
+        // Get slope/intercept - either from props or computed from points
+        let slope;
+        let intercept;
+        let handled_as_vertical = false;
+        if (ref_line.type === `diagonal`) {
+            slope = ref_line.slope;
+            intercept = ref_line.intercept;
+        }
+        else {
+            const [p1x, p1y] = normalize_point(ref_line.p1);
+            const [p2x, p2y] = normalize_point(ref_line.p2);
+            const dx = p2x - p1x;
+            if (Math.abs(dx) < 1e-10) {
+                // Nearly vertical line - check x-bounds like we do for vertical type
+                if (!is_x_visible(p1x))
+                    return null;
+                x1_data = p1x;
+                x2_data = p1x;
+                [y1_data, y2_data] = apply_y_span(y_min, y_max);
+                handled_as_vertical = true;
+                slope = 0; // Won't be used
+                intercept = 0;
+            }
+            else {
+                slope = (p2y - p1y) / dx;
+                intercept = p1y - slope * p1x;
+            }
+        }
+        if (!handled_as_vertical) {
+            // Intersect bounds with span constraints, then clip the line segment spanning the
+            // clipped x-extent to that rect — keeps endpoints paired on y = slope·x + intercept
+            const [x_lo, x_hi] = apply_x_span(x_min, x_max);
+            const [y_lo, y_hi] = apply_y_span(y_min, y_max);
+            if (x_lo > x_hi || y_lo > y_hi)
+                return null;
+            const [y_at_lo, y_at_hi] = [slope * x_lo + intercept, slope * x_hi + intercept];
+            const seg = clip_segment_to_rect(x_lo, y_at_lo, x_hi, y_at_hi, x_lo, x_hi, y_lo, y_hi);
+            // Degenerate (single-point) result means the line only grazes a corner
+            if (!seg || (seg[0] === seg[2] && seg[1] === seg[3]))
+                return null;
+            [x1_data, y1_data, x2_data, y2_data] = seg;
+        }
+    }
+    else if (line_type === `segment`) {
+        const [p1x, p1y] = normalize_point(ref_line.p1);
+        const [p2x, p2y] = normalize_point(ref_line.p2);
+        // Determine clipping bounds (span constraints override plot bounds)
+        const clip_x_min = ref_line.x_span?.[0] ?? x_min;
+        const clip_x_max = ref_line.x_span?.[1] ?? x_max;
+        const clip_y_min = ref_line.y_span?.[0] ?? y_min;
+        const clip_y_max = ref_line.y_span?.[1] ?? y_max;
+        const clipped = clip_segment_to_rect(p1x, p1y, p2x, p2y, clip_x_min, clip_x_max, clip_y_min, clip_y_max);
+        if (!clipped)
+            return null;
+        [x1_data, y1_data, x2_data, y2_data] = clipped;
+    }
+    else {
+        return null;
+    }
+    // Convert data coordinates to screen pixels
+    const x1_px = active_x_scale(x1_data);
+    const y1_px = active_y_scale(y1_data);
+    const x2_px = active_x_scale(x2_data);
+    const y2_px = active_y_scale(y2_data);
+    // Validate that pixels are finite
+    if (!isFinite(x1_px) || !isFinite(y1_px) || !isFinite(x2_px) || !isFinite(y2_px)) {
+        return null;
+    }
+    return [x1_px, y1_px, x2_px, y2_px];
+}
+// Calculate annotation position given line endpoints and annotation config
+export function calculate_annotation_position(x1, y1, x2, y2, annotation) {
+    const position = annotation.position ?? `end`;
+    const side = annotation.side ?? `above`;
+    const offset_x = annotation.offset?.x ?? 0;
+    const offset_y = annotation.offset?.y ?? 0;
+    const gap = annotation.gap ?? 8; // pixels from line
+    const edge_padding = annotation.edge_padding ?? 4; // pixels from plot edge at start/end
+    // Fraction along line: start=0, center=0.5, end=1
+    const frac = position === `start` ? 0 : position === `center` ? 0.5 : 1;
+    // Calculate base position with edge padding applied along line direction
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const len = Math.sqrt(dx * dx + dy * dy);
+    let base_x = x1 + frac * dx;
+    let base_y = y1 + frac * dy;
+    // Apply edge padding to pull text slightly inward from plot boundaries
+    if (len > 0 && position !== `center`) {
+        const dir_x = dx / len;
+        const dir_y = dy / len;
+        // At 'end', move back toward start; at 'start', move toward end
+        const inward = position === `end` ? -edge_padding : edge_padding;
+        base_x += dir_x * inward;
+        base_y += dir_y * inward;
+    }
+    let perp_x = 0;
+    let perp_y = 0;
+    if (len > 0) {
+        // Perpendicular vector (normalized)
+        const nx = -dy / len;
+        const ny = dx / len;
+        let sign;
+        if (side === `above` || side === `below`) {
+            // In SVG, y increases downward. Flip sign if 'above' and perpendicular points down (ny > 0),
+            // or if 'below' and perpendicular points up (ny <= 0), to ensure offset is in correct direction
+            sign = (side === `above`) === ny > 0 ? -1 : 1;
+        }
+        else {
+            // left/right offset to the side of the line in screen space (right -> +x, left -> -x), stable
+            // regardless of endpoint order — vertical ref lines are stored bottom->top, which flips the
+            // perpendicular. Horizontal lines (nx == 0) fall back to right = up (-y), left = down (+y).
+            const want_right = side === `right`;
+            sign = Math.abs(nx) > 1e-9 ? (want_right ? 1 : -1) * Math.sign(nx) : want_right ? -1 : 1;
+        }
+        perp_x = sign * nx * gap;
+        perp_y = sign * ny * gap;
+    }
+    const final_x = base_x + perp_x + offset_x;
+    const final_y = base_y + perp_y + offset_y;
+    // Text anchor and baseline based on position/side
+    // For left/right sides, anchor is determined by side (text extends away from line)
+    // For above/below sides, anchor is determined by position along line
+    let text_anchor;
+    if (side === `left`) {
+        text_anchor = `end`; // text ends at gap point, extends left
+    }
+    else if (side === `right`) {
+        text_anchor = `start`; // text starts at gap point, extends right
+    }
+    else {
+        text_anchor = ({ start: `start`, end: `end`, center: `middle` }[position] ?? `middle`);
+    }
+    const dominant_baseline = ({
+        above: `auto`,
+        below: `hanging`,
+        left: `middle`,
+        right: `middle`,
+    }[side] ?? `middle`);
+    // Calculate rotation if needed (keep text readable)
+    let rotation;
+    if (annotation.rotate && len > 0) {
+        rotation = Math.atan2(dy, dx) * (180 / Math.PI);
+        if (rotation > 90)
+            rotation -= 180;
+        else if (rotation < -90)
+            rotation += 180;
+    }
+    return { x: final_x, y: final_y, text_anchor, dominant_baseline, rotation };
+}
+/** Apply span constraints or use full range as fallback */
+export const span_or = (span, range) => [span?.[0] ?? range[0], span?.[1] ?? range[1]];
+// Normalize a data value to scene coordinates (centered around 0)
+export function normalize_to_scene(value, [min_val, max_val], scene_size) {
+    const range = max_val - min_val;
+    // When range is zero (min === max), return center position
+    if (range === 0)
+        return 0;
+    return ((value - min_val) / range - 0.5) * scene_size;
+}
+// Create a function to convert user data coordinates to Three.js coordinates
+// Note: In Three.js, Y is vertical. We map:
+// - user X → Three.js X (horizontal)
+// - user Y → Three.js Z (depth/horizontal)
+// - user Z → Three.js Y (vertical)
+export function create_to_threejs(params) {
+    const { scene_x, scene_y, scene_z, x_range, y_range, z_range } = params;
+    return (user_x, user_y, user_z) => ({
+        x: normalize_to_scene(user_x, x_range, scene_x),
+        y: normalize_to_scene(user_z, z_range, scene_z), // z → Y
+        z: normalize_to_scene(user_y, y_range, scene_y), // y → Z
+    });
+}

package/dist/plot/core/scales.d.ts

@@ -0,0 +1,48 @@
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
+import type { Point, ScaleType, TimeInterval } from '..';
+import type { ScaleContinuousNumeric, ScaleTime } from 'd3-scale';
+export type TicksOption = number | number[] | TimeInterval | Record<number, string>;
+export interface ArcsinhScale {
+    (value: number | Date): number;
+    domain(): [number, number];
+    domain(domain: [number, number]): ArcsinhScale;
+    range(): [number, number];
+    range(range: [number, number]): ArcsinhScale;
+    invert(value: number): number;
+    copy(): ArcsinhScale;
+    ticks(count?: number): number[];
+    threshold: number;
+}
+export type PlotScaleFn = ScaleContinuousNumeric<number, number> | ScaleTime<number, number> | ArcsinhScale;
+export declare function scale_arcsinh(threshold?: number): ArcsinhScale;
+export declare function generate_arcsinh_ticks(min: number, max: number, threshold?: number, count?: number): number[];
+export declare function create_scale(scale_type: ScaleType, domain: [number, number], output_range: [number, number]): ScaleContinuousNumeric<number, number> | ArcsinhScale;
+export declare const create_time_scale: (domain: [number, number], output_range: [number, number]) => ScaleTime<number, number, never>;
+export declare function generate_ticks(domain: [number, number], scale_type: ScaleType, ticks_option: TicksOption | undefined, scale_fn: PlotScaleFn, // D3 scale function with .ticks() method
+options?: {
+    format?: string;
+    default_count?: number;
+    interval_padding?: number;
+}): number[];
+export declare function calculate_domain(values: number[], scale_type?: ScaleType): [number, number];
+export declare function get_nice_data_range(points: Point[], get_value: (p: Point) => number, limits: [number | null, number | null], scale_type: ScaleType, padding_factor: number, is_time?: boolean): [number, number];
+export declare function generate_log_ticks(min: number, max: number, ticks_option?: TicksOption): number[];
+export declare function get_tick_label(tick_value: number, ticks_option: TicksOption | undefined): string | null;
+export declare function create_color_scale(color_scale_config: {
+    type?: ScaleType;
+    scheme?: D3ColorSchemeName | D3InterpolateName;
+    value_range?: [number, number];
+} | string, auto_color_range: [number, number]): ((value: number) => string) & {
+    domain: {
+        (): [number, number];
+        (new_domain: [number, number]): ((value: number) => string) & /*elided*/ any;
+    };
+};
+export declare function create_size_scale(config: {
+    type?: ScaleType;
+    radius_range?: [number, number];
+    value_range?: [number, number];
+}, all_size_values: (number | null)[]): import("d3-scale").ScaleLinear<number, number, never> | (((value: number) => number) & {
+    domain: () => [number, number];
+    range: () => [number, number];
+});