@peter.prib/renderengine 0.14.0 → 0.15.1

package/src/charting/charts/ComboChart.js

@@ -0,0 +1,233 @@
+import { Axis } from '../Axis.js';
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { Legend } from '../Legend.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * ComboChart — multi-series chart combining different series shapes (bars,
+ * lines, and areas) sharing a common category axis with optional dual/secondary
+ * Y-axes (`yAxis: 'left'|'right'`).
+ *
+ * Data shape:
+ *   Array<{
+ *     name: string,
+ *     type?: 'bar'|'line'|'area',
+ *     yAxis?: 'left'|'right',
+ *     color?: string,
+ *     values: Array<{label: string, value: number}> | number[]
+ *   }>
+ *   OR
+ *   {
+ *     labels?: string[],
+ *     categories?: string[],
+ *     series: Array<{
+ *       name: string,
+ *       type?: 'bar'|'line'|'area',
+ *       yAxis?: 'left'|'right',
+ *       values: number[] | Array<{label: string, value: number}>
+ *     }>
+ *   }
+ */
+export class ComboChart extends Chart {
+    static chartType = 'combo';
+
+    static normalize(data, options = {}) {
+        if (!data) return { categories: [], series: [] };
+
+        let rawSeries = [];
+        let categories = options.categories ?? options.labels ?? [];
+
+        if (Array.isArray(data)) {
+            rawSeries = data;
+        } else if (typeof data === 'object') {
+            rawSeries = Array.isArray(data.series) ? data.series : [];
+            if (!categories.length) {
+                categories = data.labels ?? data.categories ?? [];
+            }
+        }
+
+        if (!rawSeries.length) return { categories: [], series: [] };
+
+        if (!categories.length) {
+            for (const s of rawSeries) {
+                if (Array.isArray(s.values) && s.values[0] && typeof s.values[0] === 'object' && 'label' in s.values[0]) {
+                    categories = [...new Set(s.values.map(v => v.label))];
+                    break;
+                }
+            }
+        }
+        if (!categories.length && Array.isArray(rawSeries[0]?.values)) {
+            categories = Array.from({ length: rawSeries[0].values.length }, (_, i) => `Cat ${i + 1}`);
+        }
+
+        const normalizedSeries = rawSeries.map((s, idx) => {
+            const name = s.name ?? `Series ${idx + 1}`;
+            const type = s.type ?? (idx === 0 ? 'bar' : 'line');
+            const yAxis = s.yAxis ?? (type === 'line' && idx > 0 && options.secondaryY ? 'right' : 'left');
+            const map = new Map();
+            if (Array.isArray(s.values)) {
+                s.values.forEach((v, i) => {
+                    if (typeof v === 'object' && v !== null && 'label' in v) {
+                        map.set(v.label, Number(v.value) || 0);
+                    } else {
+                        map.set(categories[i] ?? `#${i + 1}`, Number(v) || 0);
+                    }
+                });
+            }
+            return {
+                name,
+                type,
+                yAxis,
+                color: s.color,
+                step: s.step,
+                values: categories.map(cat => ({ label: cat, value: map.get(cat) ?? 0 })),
+            };
+        });
+
+        return { categories, series: normalizedSeries };
+    }
+
+    _render() {
+        const { categories, series } = ComboChart.normalize(this.data, this.options);
+        if (!categories.length || !series.length) return;
+
+        const options = this.options || {};
+        const leftSeries = series.filter(s => s.yAxis !== 'right');
+        const rightSeries = series.filter(s => s.yAxis === 'right');
+        const hasRight = rightSeries.length > 0;
+
+        const rightMargin = (hasRight ? 50 : 20) + (options.secondaryYAxisLabel ? 30 : 0);
+        const box = ChartBox.fromRenderer(this.renderer, { right: rightMargin });
+        const {
+            x = box.x, y = box.y, width: optWidth, height = box.height,
+            title, xAxisLabel, yAxisLabel, secondaryYAxisLabel, colors, legend: showLegend = true,
+        } = options;
+
+        const palette = new ColorPalette(colors);
+        const legendItems = series.map((s, i) => ({
+            label: s.name,
+            color: s.color ?? palette.colorAt(i),
+            marker: s.type === 'bar' ? 'square' : 'circle',
+            hidden: this._dataFilter?.has(i),
+        }));
+
+        const width = optWidth ?? (showLegend
+            ? Legend.plotWidthBeside({ x, width: box.width }, this.renderer.width, { items: legendItems })
+            : box.width);
+        const plotBox = { x, y, width, height };
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel, secondaryYAxisLabel }).draw(this.renderer, plotBox);
+
+        // Compute Left and Right domains
+        const leftVals = leftSeries.flatMap(s => s.values.map(v => v.value));
+        const rawLeftMax = leftVals.length ? Math.max(...leftVals, 1) : 1;
+        const rawLeftMin = leftVals.length ? Math.min(0, ...leftVals) : 0;
+        const leftDomain = new Axis().drawYRange(this.renderer, plotBox, rawLeftMin, rawLeftMax);
+
+        let rightDomain = { min: 0, max: 1 };
+        if (hasRight) {
+            const rightVals = rightSeries.flatMap(s => s.values.map(v => v.value));
+            const rawRightMax = rightVals.length ? Math.max(...rightVals, 1) : 1;
+            const rawRightMin = rightVals.length ? Math.min(0, ...rightVals) : 0;
+            rightDomain = new Axis().drawSecondaryYRange(this.renderer, plotBox, rawRightMin, rawRightMax);
+        }
+
+        // Draw base axis
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+
+        const visibleSeries = series.filter((s, i) => !this._dataFilter?.has(i));
+        const barSeries = visibleSeries.filter(s => s.type === 'bar');
+        const barSeriesCount = barSeries.length;
+        const categoryCount = categories.length;
+        const clusterWidth = width / categoryCount;
+        const groupGap = clusterWidth * 0.2;
+        const availableWidth = clusterWidth - groupGap;
+        const barWidth = barSeriesCount > 0 ? (availableWidth / barSeriesCount) * 0.9 : 0;
+        const barMargin = barSeriesCount > 0 ? (availableWidth / barSeriesCount) * 0.1 : 0;
+
+        const toLeftY = v => y + height - ((v - leftDomain.min) / ((leftDomain.max - leftDomain.min) || 1)) * height;
+        const toRightY = v => y + height - ((v - rightDomain.min) / ((rightDomain.max - rightDomain.min) || 1)) * height;
+        const toY = (v, yAxis) => yAxis === 'right' ? toRightY(v) : toLeftY(v);
+
+        // 1. Draw Bars first
+        categories.forEach((cat, catIdx) => {
+            const clusterX = x + catIdx * clusterWidth + groupGap / 2;
+            barSeries.forEach((s, barIdx) => {
+                const sIdx = series.indexOf(s);
+                const color = s.color ?? palette.colorAt(sIdx);
+                const val = s.values[catIdx]?.value ?? 0;
+                const zeroY = toY(0, s.yAxis);
+                const valY = toY(val, s.yAxis);
+                const barTop = Math.min(zeroY, valY);
+                const barH = Math.max(1, Math.abs(valY - zeroY));
+                const bx = clusterX + barIdx * (barWidth + barMargin);
+
+                this._datum(this.renderer.rect(bx, barTop, barWidth, barH, color, null, {
+                    tooltip: `${s.name} (${cat}): ${Axis.formatValue(val)}`,
+                }), { label: cat, series: s.name, value: val });
+
+                if (options.showValues) {
+                    this.renderer.text(Axis.formatValue(val), bx + barWidth / 2, barTop - 5, {
+                        textAnchor: this.renderer.centerTextAnchor, fontSize: '9px', fill: '#333',
+                    });
+                }
+            });
+
+            // X category labels
+            const step = Axis.categoryLabelStep(categories, width);
+            if (catIdx % step === 0) {
+                this.renderer.text(cat, clusterX + availableWidth / 2, y + height + 20, {
+                    textAnchor: this.renderer.centerTextAnchor, fontSize: '10px', fill: '#333',
+                });
+            }
+        });
+
+        // 2. Draw Area and Line series over the bars
+        const nonBarSeries = visibleSeries.filter(s => s.type !== 'bar');
+        nonBarSeries.forEach((s) => {
+            const sIdx = series.indexOf(s);
+            const color = s.color ?? palette.colorAt(sIdx);
+            const pts = categories.map((cat, catIdx) => {
+                const px = x + catIdx * clusterWidth + clusterWidth / 2;
+                const py = toY(s.values[catIdx]?.value ?? 0, s.yAxis);
+                return { px, py, val: s.values[catIdx]?.value ?? 0, cat };
+            });
+
+            if (s.type === 'area') {
+                const zeroY = toY(0, s.yAxis);
+                const areaD = 'M' + pts.map(p => `${p.px},${p.py}`).join(' L')
+                    + ` L${pts[pts.length - 1].px},${zeroY} L${pts[0].px},${zeroY} Z`;
+                const { r, g, b: bl } = palette.hexToRgb(color);
+                this.renderer.path(areaD, `rgba(${r},${g},${bl},0.28)`, null, { tooltip: s.name });
+            }
+
+            let pathD = '';
+            pts.forEach((p, i) => {
+                if (i === 0) pathD += `M${p.px},${p.py}`;
+                else if (s.step === 'before') pathD += ` V${p.py} H${p.px}`;
+                else if (s.step) pathD += ` H${p.px} V${p.py}`;
+                else pathD += ` L${p.px},${p.py}`;
+            });
+            this.renderer.path(pathD, 'none', { color, width: 2.5 });
+
+            // Vertex dots
+            pts.forEach(p => {
+                this._datum(this.renderer.circle(p.px, p.py, 3.5, color, { color: '#ffffff', width: 1.5 }, {
+                    tooltip: `${s.name} (${p.cat}): ${Axis.formatValue(p.val)}`,
+                }), { label: p.cat, series: s.name, value: p.val });
+
+                if (options.showValues) {
+                    this.renderer.text(Axis.formatValue(p.val), p.px, p.py - 8, {
+                        textAnchor: this.renderer.centerTextAnchor, fontSize: '9px', fill: color, fontWeight: 'bold',
+                    });
+                }
+            });
+        });
+
+        // 3. Legend
+        if (showLegend) {
+            Legend.beside({ x, y, width }, this.renderer.width, { items: legendItems }).draw(this.renderer);
+        }
+    }
+}

package/src/charting/charts/ContourChart.js

@@ -0,0 +1,310 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Axis } from '../Axis.js';
+
+/**
+ * ContourChart — 2D isoband and isoline contour plot on regular scalar grids
+ * using marching squares.
+ *
+ * Data forms:
+ *   - 2D array of numbers: `number[][]` (rows are Y, columns are X)
+ *   - Object: `{ grid: number[][], xValues?: number[], yValues?: number[] }`
+ *   - Flat array: `Array<{x: number, y: number, value: number}>`
+ *
+ * Options:
+ *   - levels: number (count of contour levels, default 8) or number[] of explicit thresholds
+ *   - colorScale: string[] (gradient stops, default 9-stop spectral)
+ *   - filled: boolean (default true — draw filled isoband cells)
+ *   - showLines: boolean (default true — draw marching-squares isolines)
+ *   - showLabels: boolean (default true — draw numeric value on contour lines)
+ *   - lineColor: string (default 'rgba(0,0,0,0.35)')
+ *   - lineWidth: number (default 1)
+ *   - legend: boolean (default true — draw color bar legend)
+ *   - title, xAxisLabel, yAxisLabel: string
+ */
+export class ContourChart extends Chart {
+    static chartType = 'contour';
+
+    static DEFAULT_COLOR_SCALE = [
+        '#313695', '#4575b4', '#74add1', '#abd9e9',
+        '#e0f3f8', '#fee090', '#fdae61', '#f46d43', '#d73027',
+    ];
+
+    /** Normalize various input shapes to `{ grid: number[][], xValues: number[], yValues: number[] }`. */
+    static normalizeData(raw) {
+        if (!raw) return { grid: [[]], xValues: [], yValues: [] };
+
+        if (Array.isArray(raw) && Array.isArray(raw[0])) {
+            const nrows = raw.length;
+            const ncols = raw[0].length;
+            const xValues = Array.from({ length: ncols }, (_, i) => i);
+            const yValues = Array.from({ length: nrows }, (_, i) => i);
+            return { grid: raw, xValues, yValues };
+        }
+
+        if (raw.grid && Array.isArray(raw.grid)) {
+            const nrows = raw.grid.length;
+            const ncols = raw.grid[0]?.length || 0;
+            const xValues = raw.xValues || Array.from({ length: ncols }, (_, i) => i);
+            const yValues = raw.yValues || Array.from({ length: nrows }, (_, i) => i);
+            return { grid: raw.grid, xValues, yValues };
+        }
+
+        if (Array.isArray(raw) && raw.length > 0 && typeof raw[0] === 'object' && 'x' in raw[0] && 'y' in raw[0]) {
+            const xSet = Array.from(new Set(raw.map(d => d.x))).sort((a, b) => a - b);
+            const ySet = Array.from(new Set(raw.map(d => d.y))).sort((a, b) => a - b);
+            const xIndex = new Map(xSet.map((x, i) => [x, i]));
+            const yIndex = new Map(ySet.map((y, i) => [y, i]));
+
+            const grid = Array.from({ length: ySet.length }, () => new Array(xSet.length).fill(0));
+            for (const d of raw) {
+                const r = yIndex.get(d.y);
+                const c = xIndex.get(d.x);
+                if (r !== undefined && c !== undefined) {
+                    grid[r][c] = d.value ?? d.z ?? 0;
+                }
+            }
+            return { grid, xValues: xSet, yValues: ySet };
+        }
+
+        return { grid: [[]], xValues: [], yValues: [] };
+    }
+
+    /** Compute marching squares line segments for a scalar grid at threshold T. */
+    static marchingSquares(grid, xCoords, yCoords, threshold) {
+        const nrows = grid.length;
+        if (nrows < 2) return [];
+        const ncols = grid[0].length;
+        if (ncols < 2) return [];
+
+        const segments = [];
+
+        // Linear interpolation helper between two values and their positions
+        const interp = (v1, v2, p1, p2) => {
+            if (Math.abs(v2 - v1) < 1e-9) return (p1 + p2) / 2;
+            const t = (threshold - v1) / (v2 - v1);
+            return p1 + t * (p2 - p1);
+        };
+
+        for (let r = 0; r < nrows - 1; r++) {
+            const y0 = yCoords[r];
+            const y1 = yCoords[r + 1];
+
+            for (let c = 0; c < ncols - 1; c++) {
+                const x0 = xCoords[c];
+                const x1 = xCoords[c + 1];
+
+                const vTL = grid[r][c];
+                const vTR = grid[r][c + 1];
+                const vBR = grid[r + 1][c + 1];
+                const vBL = grid[r + 1][c];
+
+                let mask = 0;
+                if (vTL >= threshold) mask |= 1;
+                if (vTR >= threshold) mask |= 2;
+                if (vBR >= threshold) mask |= 4;
+                if (vBL >= threshold) mask |= 8;
+
+                if (mask === 0 || mask === 15) continue;
+
+                const top = [interp(vTL, vTR, x0, x1), y0];
+                const right = [x1, interp(vTR, vBR, y0, y1)];
+                const bottom = [interp(vBL, vBR, x0, x1), y1];
+                const left = [x0, interp(vTL, vBL, y0, y1)];
+
+                switch (mask) {
+                    case 1:  // TL
+                    case 14: // TR, BR, BL
+                        segments.push([top, left]);
+                        break;
+                    case 2:  // TR
+                    case 13: // TL, BR, BL
+                        segments.push([top, right]);
+                        break;
+                    case 3:  // TL, TR
+                    case 12: // BR, BL
+                        segments.push([left, right]);
+                        break;
+                    case 4:  // BR
+                    case 11: // TL, TR, BL
+                        segments.push([right, bottom]);
+                        break;
+                    case 5: { // TL, BR (saddle)
+                        const center = (vTL + vTR + vBR + vBL) / 4;
+                        if (center >= threshold) {
+                            segments.push([left, top]);
+                            segments.push([right, bottom]);
+                        } else {
+                            segments.push([left, bottom]);
+                            segments.push([top, right]);
+                        }
+                        break;
+                    }
+                    case 6:  // TR, BR
+                    case 9:  // TL, BL
+                        segments.push([top, bottom]);
+                        break;
+                    case 7:  // TL, TR, BR
+                    case 8:  // BL
+                        segments.push([left, bottom]);
+                        break;
+                    case 10: { // TR, BL (saddle)
+                        const center = (vTL + vTR + vBR + vBL) / 4;
+                        if (center >= threshold) {
+                            segments.push([top, right]);
+                            segments.push([bottom, left]);
+                        } else {
+                            segments.push([top, left]);
+                            segments.push([bottom, right]);
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+        return segments;
+    }
+
+    _render() {
+        const { grid, xValues, yValues } = ContourChart.normalizeData(this.data);
+        const options = this.options || {};
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            levels = 8,
+            colorScale = ContourChart.DEFAULT_COLOR_SCALE,
+            filled = true,
+            showLines = true,
+            showLabels = true,
+            lineColor = 'rgba(0,0,0,0.3)',
+            lineWidth = 1,
+            legend = true,
+            title, xAxisLabel, yAxisLabel,
+        } = options;
+
+        const nrows = grid.length;
+        const ncols = grid[0]?.length || 0;
+        if (nrows < 2 || ncols < 2) return;
+
+        let vMin = Infinity;
+        let vMax = -Infinity;
+        for (let r = 0; r < nrows; r++) {
+            for (let c = 0; c < ncols; c++) {
+                const v = grid[r][c];
+                if (v < vMin) vMin = v;
+                if (v > vMax) vMax = v;
+            }
+        }
+        if (vMin === vMax) {
+            vMin -= 1;
+            vMax += 1;
+        }
+
+        const plotW = legend ? width - 60 : width;
+        const plotH = height;
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, { x, y, width: plotW, height: plotH });
+
+        // Calculate explicit threshold levels
+        const thresholds = Array.isArray(levels)
+            ? levels.slice().sort((a, b) => a - b)
+            : Array.from({ length: levels }, (_, i) => vMin + ((i + 1) / (levels + 1)) * (vMax - vMin));
+
+        const xMin = xValues[0];
+        const xMax = xValues[ncols - 1];
+        const yMin = yValues[0];
+        const yMax = yValues[nrows - 1];
+
+        const xRange = (xMax - xMin) || 1;
+        const yRange = (yMax - yMin) || 1;
+
+        const toScreenX = (xv) => x + ((xv - xMin) / xRange) * plotW;
+        const toScreenY = (yv) => y + plotH - ((yv - yMin) / yRange) * plotH;
+
+        const screenXCoords = xValues.map(toScreenX);
+        const screenYCoords = yValues.map(toScreenY);
+
+        // 1. Filled isoband cells
+        if (filled) {
+            for (let r = 0; r < nrows - 1; r++) {
+                const yTop = Math.min(screenYCoords[r], screenYCoords[r + 1]);
+                const cellH = Math.abs(screenYCoords[r + 1] - screenYCoords[r]);
+
+                for (let c = 0; c < ncols - 1; c++) {
+                    const xLeft = Math.min(screenXCoords[c], screenXCoords[c + 1]);
+                    const cellW = Math.abs(screenXCoords[c + 1] - screenXCoords[c]);
+
+                    // Average cell corner value to determine cell color
+                    const avgVal = (grid[r][c] + grid[r][c + 1] + grid[r + 1][c] + grid[r + 1][c + 1]) / 4;
+                    const color = ColorPalette.scaleColor(colorScale, vMin, vMax, avgVal);
+
+                    this.renderer.rect(xLeft, yTop, cellW + 0.5, cellH + 0.5, color, null, {
+                        tooltip: `Value: ${Axis.formatValue(avgVal)}`,
+                    });
+                }
+            }
+        }
+
+        // 2. Isolines & labels via marching squares
+        if (showLines) {
+            thresholds.forEach((threshold, tIdx) => {
+                const segments = ContourChart.marchingSquares(grid, screenXCoords, screenYCoords, threshold);
+                if (!segments.length) return;
+
+                let pathData = '';
+                segments.forEach(([p1, p2]) => {
+                    pathData += `M${p1[0].toFixed(1)},${p1[1].toFixed(1)} L${p2[0].toFixed(1)},${p2[1].toFixed(1)} `;
+                });
+
+                if (pathData) {
+                    this.renderer.path(pathData.trim(), 'none', { color: lineColor, width: lineWidth });
+                }
+
+                // Add contour label along middle segment if showLabels is enabled
+                if (showLabels && segments.length > 2) {
+                    const midSeg = segments[Math.floor(segments.length / 2)];
+                    const labelX = (midSeg[0][0] + midSeg[1][0]) / 2;
+                    const labelY = (midSeg[0][1] + midSeg[1][1]) / 2;
+                    const formatted = Axis.formatValue(threshold);
+
+                    this.renderer.text(formatted, labelX, labelY, {
+                        textAnchor: 'middle',
+                        verticalAlign: 'middle',
+                        fontSize: '9px',
+                        fill: '#222',
+                        stroke: '#fff',
+                        strokeWidth: 2,
+                    });
+                }
+            });
+        }
+
+        // 3. Axes
+        const axis = new Axis();
+        axis.drawXRange(this.renderer, { x, y, width: plotW, height: plotH }, xMin, xMax);
+        axis.drawYRange(this.renderer, { x, y, width: plotW, height: plotH }, yMin, yMax);
+
+        // 4. Color bar legend
+        if (legend) {
+            const barX = x + plotW + 20;
+            const barW = 14;
+            const barY = y;
+            const barH = plotH;
+            const numStops = 20;
+            const sliceH = barH / numStops;
+
+            for (let i = 0; i < numStops; i++) {
+                const val = vMax - (i / (numStops - 1)) * (vMax - vMin);
+                const color = ColorPalette.scaleColor(colorScale, vMin, vMax, val);
+                this.renderer.rect(barX, barY + i * sliceH, barW, sliceH + 0.5, color, null);
+            }
+            this.renderer.rect(barX, barY, barW, barH, 'none', { color: '#888', width: 1 });
+
+            // Max, Mid, Min ticks
+            this.renderer.text(Axis.formatValue(vMax), barX + barW + 4, barY + 4, { textAnchor: 'start', fontSize: '9px', fill: '#444' });
+            this.renderer.text(Axis.formatValue((vMin + vMax) / 2), barX + barW + 4, barY + barH / 2, { textAnchor: 'start', verticalAlign: 'middle', fontSize: '9px', fill: '#444' });
+            this.renderer.text(Axis.formatValue(vMin), barX + barW + 4, barY + barH - 2, { textAnchor: 'start', fontSize: '9px', fill: '#444' });
+        }
+    }
+}

package/src/charting/charts/DonutChart3D.js

@@ -0,0 +1,13 @@
+import { PieChart3D } from './PieChart3D.js';
+
+/**
+ * DonutChart3D — extruded 3D tilted doughnut chart with inner hole cylinder wall,
+ * outer cylinder skirt, radial cut walls, exploded slices, and hover pull-out.
+ */
+export class DonutChart3D extends PieChart3D {
+    static chartType = 'donut3D';
+
+    constructor(renderer, data, options = {}) {
+        super(renderer, data, { innerRadiusRatio: 0.5, ...options });
+    }
+}