matterviz 0.3.1 → 0.3.3

package/dist/plot/utils/label-placement.js

@@ -1,20 +1,148 @@
 import { is_time_scale } from '../types';
-import { forceCollide, forceLink, forceManyBody, forceSimulation } from 'd3-force';
-function parse_font_size(size_str) {
+const DEFAULT_WEIGHTS = {
+    overlap: 30,
+    marker: 100,
+    leader_cross: 10,
+    leader_text: 8,
+    distance: 0.5,
+    bounds: 100,
+};
+export function parse_font_size(size_str) {
     if (!size_str)
         return 12;
-    const match = size_str.match(/^(\d+(?:\.\d+)?)(px|em|rem)?$/);
+    const match = /^(\d+(?:\.\d+)?)(px|em|rem)?$/.exec(size_str);
     if (!match)
         return 12;
     const value = parseFloat(match[1]);
     return match[2] === `em` || match[2] === `rem` ? value * 16 : value;
 }
+// === Geometry helpers ===
+export function rect_overlap_area(a, b) {
+    const ox = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
+    const oy = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+    return ox * oy;
+}
+export function rect_circle_overlap(rect, cx, cy, radius) {
+    // Inflate rect by radius to create an exclusion zone around the marker
+    const left = rect.x - radius;
+    const top = rect.y - radius;
+    const right = rect.x + rect.w + radius;
+    const bottom = rect.y + rect.h + radius;
+    if (cx < left || cx > right || cy < top || cy > bottom)
+        return 0;
+    // Penalty proportional to how deep the marker center is inside the exclusion zone
+    const dx = Math.min(cx - left, right - cx);
+    const dy = Math.min(cy - top, bottom - cy);
+    return Math.min(dx, dy) + radius;
+}
+export function segments_intersect(ax1, ay1, ax2, ay2, bx1, by1, bx2, by2) {
+    const d1x = ax2 - ax1, d1y = ay2 - ay1;
+    const d2x = bx2 - bx1, d2y = by2 - by1;
+    const cross = d1x * d2y - d1y * d2x;
+    if (Math.abs(cross) < 1e-10)
+        return false;
+    const t_val = ((bx1 - ax1) * d2y - (by1 - ay1) * d2x) / cross;
+    const u_val = ((bx1 - ax1) * d1y - (by1 - ay1) * d1x) / cross;
+    return t_val > 0 && t_val < 1 && u_val > 0 && u_val < 1;
+}
+export function segment_rect_intersects(sx1, sy1, sx2, sy2, rect) {
+    const rx = rect.x, ry = rect.y, rx2 = rx + rect.w, ry2 = ry + rect.h;
+    return (segments_intersect(sx1, sy1, sx2, sy2, rx, ry, rx2, ry) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx2, ry, rx2, ry2) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx, ry2, rx2, ry2) ||
+        segments_intersect(sx1, sy1, sx2, sy2, rx, ry, rx, ry2));
+}
+export function rect_out_of_bounds_area(rect, bounds) {
+    let penalty = 0;
+    if (rect.x < bounds.min_x)
+        penalty += (bounds.min_x - rect.x) * rect.h;
+    if (rect.y < bounds.min_y)
+        penalty += (bounds.min_y - rect.y) * rect.w;
+    if (rect.x + rect.w > bounds.max_x)
+        penalty += (rect.x + rect.w - bounds.max_x) * rect.h;
+    if (rect.y + rect.h > bounds.max_y)
+        penalty += (rect.y + rect.h - bounds.max_y) * rect.w;
+    return penalty;
+}
+// 8 candidate positions around anchor: R, TR, T, TL, L, BL, B, BR
+// Positions are top-left corner of the label bounding box.
+// All positions keep a full `offset` gap from the marker edge.
+export function generate_candidates(ax, ay, point_radius, label_w, label_h, gap) {
+    const offset = point_radius + gap;
+    return [
+        { x: ax + offset, y: ay - label_h + offset / 2 }, // R  (baseline just below center)
+        { x: ax + offset, y: ay - label_h - offset / 2 }, // TR
+        { x: ax - label_w / 2, y: ay - label_h - offset }, // T
+        { x: ax - label_w - offset, y: ay - label_h - offset / 2 }, // TL
+        { x: ax - label_w - offset, y: ay - label_h + offset / 2 }, // L  (baseline just below center)
+        { x: ax - label_w - offset, y: ay + offset / 2 }, // BL
+        { x: ax - label_w / 2, y: ay + offset }, // B
+        { x: ax + offset, y: ay + offset / 2 }, // BR
+    ];
+}
+// Compute energy delta when only label at `changed_idx` moves
+export function compute_delta_energy(labels, anchors, changed_idx, old_state, new_state, weights, bounds) {
+    let delta = 0;
+    const anchor = anchors[new_state.anchor_idx];
+    const old_cx = old_state.x + old_state.w / 2, old_cy = old_state.y + old_state.h / 2;
+    const new_cx = new_state.x + new_state.w / 2, new_cy = new_state.y + new_state.h / 2;
+    // Distance penalty change
+    delta +=
+        weights.distance *
+            (Math.hypot(new_cx - anchor.x, new_cy - anchor.y) -
+                Math.hypot(old_cx - anchor.x, old_cy - anchor.y));
+    // Bounds penalty change
+    delta +=
+        weights.bounds *
+            (rect_out_of_bounds_area(new_state, bounds) - rect_out_of_bounds_area(old_state, bounds));
+    // Marker overlap change (all markers)
+    for (const marker of anchors) {
+        delta +=
+            weights.marker *
+                (rect_circle_overlap(new_state, marker.x, marker.y, marker.radius) -
+                    rect_circle_overlap(old_state, marker.x, marker.y, marker.radius));
+    }
+    // Pairwise interactions with all other labels
+    for (let jdx = 0; jdx < labels.length; jdx++) {
+        if (jdx === changed_idx)
+            continue;
+        const other = labels[jdx];
+        const anchor_j = anchors[other.anchor_idx];
+        const other_cx = other.x + other.w / 2, other_cy = other.y + other.h / 2;
+        // Label-label overlap delta
+        delta +=
+            weights.overlap *
+                (rect_overlap_area(new_state, other) - rect_overlap_area(old_state, other));
+        // Leader line crossing delta (changed label's leader vs other's leader)
+        const old_cross = segments_intersect(anchor.x, anchor.y, old_cx, old_cy, anchor_j.x, anchor_j.y, other_cx, other_cy);
+        const new_cross = segments_intersect(anchor.x, anchor.y, new_cx, new_cy, anchor_j.x, anchor_j.y, other_cx, other_cy);
+        if (new_cross !== old_cross)
+            delta += (new_cross ? 1 : -1) * weights.leader_cross;
+        // Changed label's leader crossing other label's rect
+        const old_text = segment_rect_intersects(anchor.x, anchor.y, old_cx, old_cy, other);
+        const new_text = segment_rect_intersects(anchor.x, anchor.y, new_cx, new_cy, other);
+        if (new_text !== old_text)
+            delta += (new_text ? 1 : -1) * weights.leader_text;
+        // Other label's leader crossing changed label's rect
+        const old_other = segment_rect_intersects(anchor_j.x, anchor_j.y, other_cx, other_cy, old_state);
+        const new_other = segment_rect_intersects(anchor_j.x, anchor_j.y, other_cx, other_cy, new_state);
+        if (new_other !== old_other)
+            delta += (new_other ? 1 : -1) * weights.leader_text;
+    }
+    return delta;
+}
+// === Main export ===
 export function compute_label_positions(filtered_series, config, scales, bounds) {
-    const { width, height, pad } = bounds;
     const { x_scale_fn, y_scale_fn, y2_scale_fn, x_axis } = scales;
-    const label_nodes = [];
-    const anchor_nodes = [];
-    const links = [];
+    const { width, height, pad } = bounds;
+    const plot_bounds = {
+        min_x: pad.l,
+        min_y: pad.t,
+        max_x: width - pad.r,
+        max_y: height - pad.b,
+    };
+    // Collect all label data in a single pass
+    const label_infos = [];
     for (const series of filtered_series) {
         for (const pt of series.filtered_data ?? []) {
             if (!pt.point_label?.auto_placement || !pt.point_label.text)
@@ -23,70 +151,106 @@ export function compute_label_positions(filtered_series, config, scales, bounds)
                 ? x_scale_fn(new Date(pt.x))
                 : x_scale_fn(pt.x);
             const ay = (series.y_axis === `y2` ? y2_scale_fn : y_scale_fn)(pt.y);
-            const id = `${pt.series_idx}-${pt.point_idx}`;
             const font_size = parse_font_size(pt.point_label.font_size);
-            const w = pt.point_label.text.length * font_size * 0.6 + 10;
-            const h = font_size * 1.2;
-            const r = pt.point_style?.radius ?? 3;
-            label_nodes.push({
-                id,
-                anchor_x: ax,
-                anchor_y: ay,
-                point_node: pt,
-                label_width: w,
-                label_height: h,
-                x: ax + (pt.point_label.offset?.x ?? 5),
-                y: ay + (pt.point_label.offset?.y ?? r + h / 2 + 3),
+            const label_w = pt.point_label.text.length * font_size * 0.6 + 10;
+            const label_h = font_size * 1.2;
+            const radius = pt.point_style?.radius ?? 3;
+            label_infos.push({
+                id: `${pt.series_idx}-${pt.point_idx}`,
+                anchor: { x: ax, y: ay, radius },
+                width: label_w,
+                height: label_h,
+                candidates: generate_candidates(ax, ay, radius, label_w, label_h, 4),
             });
-            anchor_nodes.push({ id: `anchor-${id}`, fx: ax, fy: ay, point_radius: r });
-            links.push({ source: id, target: `anchor-${id}` });
         }
     }
-    if (label_nodes.length === 0)
+    const num_labels = label_infos.length;
+    if (num_labels === 0)
         return {};
-    if (config.max_labels && label_nodes.length > config.max_labels) {
-        return Object.fromEntries(label_nodes.map((n) => [n.id, { x: n.x ?? 0, y: n.y ?? 0 }]));
+    // Fallback: too many labels, just offset to the right with bounds clamping
+    if (config.max_labels && num_labels > config.max_labels) {
+        return Object.fromEntries(label_infos.map((info) => [
+            info.id,
+            {
+                x: Math.min(Math.max(info.anchor.x + 5, plot_bounds.min_x), plot_bounds.max_x - info.width),
+                y: Math.min(Math.max(info.anchor.y, plot_bounds.min_y), plot_bounds.max_y - info.height),
+            },
+        ]));
     }
-    const sim = forceSimulation([...label_nodes, ...anchor_nodes])
-        .force(`link`, forceLink(links).id((d) => d.id).distance(config.link_distance)
-        .strength(config.link_strength))
-        .force(`collide`, forceCollide().radius((n) => {
-        const l = n;
-        const a = n;
-        return l.label_width
-            ? Math.sqrt(l.label_width ** 2 + l.label_height ** 2) / 2 + 2
-            : (a.point_radius ?? 0) + 2;
-    }).strength(config.collision_strength))
-        .force(`charge`, forceManyBody().strength((n) => {
-        const a = n;
-        return a.point_radius !== undefined && a.fx !== undefined
-            ? -(config.charge_strength ?? 50)
-            : 0;
-    }).distanceMax(config.charge_distance_max ?? 30));
-    sim.stop().tick(config.placement_ticks);
-    const [min_dist, max_dist] = config.link_distance_range ?? [null, null];
-    const result = {};
-    for (const node of label_nodes) {
-        const node_x = node.x ?? 0;
-        const node_y = node.y ?? 0;
-        let x = Math.max(pad.l + node.label_width / 2, Math.min(width - pad.r - node.label_width / 2, node_x));
-        let y = Math.max(pad.t + node.label_height / 2, Math.min(height - pad.b - node.label_height / 2, node_y));
-        if (min_dist || max_dist) {
-            const dx = x - node.anchor_x;
-            const dy = y - node.anchor_y;
-            const dist = Math.hypot(dx, dy);
-            if (max_dist && dist > max_dist) {
-                const s = max_dist / dist;
-                x = node.anchor_x + dx * s;
-                y = node.anchor_y + dy * s;
+    const weights = { ...DEFAULT_WEIGHTS, ...config.weights };
+    const anchors = label_infos.map((info) => info.anchor);
+    // Greedy initialization: pick best candidate per label
+    const labels = [];
+    for (let idx = 0; idx < num_labels; idx++) {
+        const { candidates, width: lw, height: lh, anchor } = label_infos[idx];
+        let best_candidate = candidates[0];
+        let best_score = Infinity;
+        for (const candidate of candidates) {
+            const test_rect = { x: candidate.x, y: candidate.y, w: lw, h: lh };
+            let score = weights.bounds * rect_out_of_bounds_area(test_rect, plot_bounds);
+            for (const placed of labels) {
+                score += weights.overlap * rect_overlap_area(test_rect, placed);
+            }
+            for (const marker of anchors) {
+                score +=
+                    weights.marker * rect_circle_overlap(test_rect, marker.x, marker.y, marker.radius);
             }
-            else if (min_dist && dist > 0 && dist < min_dist) {
-                const s = min_dist / dist;
-                x = node.anchor_x + dx * s;
-                y = node.anchor_y + dy * s;
+            score +=
+                weights.distance *
+                    Math.hypot(candidate.x + lw / 2 - anchor.x, candidate.y + lh / 2 - anchor.y);
+            if (score < best_score) {
+                best_score = score;
+                best_candidate = candidate;
             }
         }
-        result[node.id] = { x, y };
+        labels.push({ x: best_candidate.x, y: best_candidate.y, w: lw, h: lh, anchor_idx: idx });
+    }
+    // Simulated annealing
+    const sa_iterations = config.sa_iterations ?? 2000;
+    const total_steps = sa_iterations * num_labels;
+    const cooling_rate = 1 / total_steps;
+    // Seeded pseudo-random for deterministic results
+    let rng_state = 42;
+    const next_random = () => {
+        rng_state = (rng_state * 1664525 + 1013904223) & 0x7fffffff;
+        return rng_state / 0x7fffffff;
+    };
+    // Reusable scratch objects to avoid allocations in the hot loop
+    const old_scratch = { x: 0, y: 0, w: 0, h: 0, anchor_idx: 0 };
+    const new_scratch = { x: 0, y: 0, w: 0, h: 0, anchor_idx: 0 };
+    const copy_state = (dst, src) => {
+        dst.x = src.x;
+        dst.y = src.y;
+        dst.w = src.w;
+        dst.h = src.h;
+        dst.anchor_idx = src.anchor_idx;
+    };
+    for (let step = 0; step < total_steps; step++) {
+        const temperature = Math.max(0.001, 1.0 - step * cooling_rate);
+        const label_idx = Math.floor(next_random() * num_labels);
+        const current = labels[label_idx];
+        copy_state(old_scratch, current);
+        copy_state(new_scratch, current);
+        // 70% try a candidate position, 30% small perturbation
+        if (next_random() < 0.7) {
+            const candidate = label_infos[label_idx].candidates[Math.floor(next_random() * label_infos[label_idx].candidates.length)];
+            new_scratch.x = candidate.x;
+            new_scratch.y = candidate.y;
+        }
+        else {
+            const max_shift = 30 * temperature + 5;
+            new_scratch.x += (next_random() - 0.5) * 2 * max_shift;
+            new_scratch.y += (next_random() - 0.5) * 2 * max_shift;
+        }
+        const delta = compute_delta_energy(labels, anchors, label_idx, old_scratch, new_scratch, weights, plot_bounds);
+        if (delta < 0 || next_random() < Math.exp(-delta / (temperature * 10 + 0.1))) {
+            current.x = new_scratch.x;
+            current.y = new_scratch.y;
+        }
     }
-    return result;
+    // Return label center positions (matching existing API)
+    return Object.fromEntries(labels.map((label, idx) => [
+        label_infos[idx].id,
+        { x: label.x + label.w / 2, y: label.y + label.h / 2 },
+    ]));
 }

package/dist/plot/utils/series-visibility.js

@@ -44,7 +44,7 @@ export function handle_legend_double_click(series, idx, prev_visibility) {
     const check_series = prev_visibility ? series.slice(0, prev_visibility.length) : series;
     const is_isolated = check_series.every((srs, srs_idx) => {
         const in_group = label ? srs.label === label : srs_idx === idx;
-        return in_group ? srs.visible ?? true : !(srs.visible ?? true);
+        return in_group ? (srs.visible ?? true) : !(srs.visible ?? true);
     });
     // Restore from isolation
     if (is_isolated && prev_visibility) {
@@ -56,8 +56,7 @@ export function handle_legend_double_click(series, idx, prev_visibility) {
         };
     }
     // Isolate series
-    const new_prev = prev_visibility ??
-        (current.filter(Boolean).length > 1 ? [...current] : null);
+    const new_prev = prev_visibility ?? (current.filter(Boolean).length > 1 ? [...current] : null);
     return {
         series: series.map((srs, srs_idx) => {
             const in_group = label ? srs.label === label : srs_idx === idx;

package/dist/plot/utils.d.ts

@@ -0,0 +1 @@
+export declare function calc_auto_range(values: number[]): [number, number];

package/dist/plot/utils.js

@@ -0,0 +1,14 @@
+export function calc_auto_range(values) {
+    const finite_values = values.filter(Number.isFinite);
+    if (finite_values.length === 0)
+        return [0, 1];
+    let [min_value, max_value] = [finite_values[0], finite_values[0]];
+    for (const value of finite_values) {
+        if (value < min_value)
+            min_value = value;
+        else if (value > max_value)
+            max_value = value;
+    }
+    const padding = (max_value - min_value) * 0.05 || 0.5;
+    return [min_value - padding, max_value + padding];
+}