@rm-graph/core 0.1.8 → 0.1.10

package/README.md

@@ -13,25 +13,19 @@ npm install @rm-graph/core
 ## Usage
 
 ```typescript
-import { createLineChart, createBarChart, createAreaChart } from '@rm-graph/core';
+import { createColumn3DChart, createPRPDChart } from '@rm-graph/core';
 
-// Create a line chart
-const chart = await createLineChart('container-id', {
+// Create a 3D column chart
+const chart = await createColumn3DChart('container-id', {
   theme: 'dark',
-  series: [
-    {
-      name: 'Revenue',
-      data: [100, 150, 120, 180, 200],
-    },
-  ],
-  xAxis: { title: 'Month' },
-  yAxis: { title: 'Amount ($)' },
+  data: [[45, 1500, 1], [90, 2200, 2], [180, 1800, 3]],
+  xAxisTitle: 'Phase Angle (°)',
+  yAxisTitle: 'Amplitude (mVp)',
+  zAxisTitle: 'Cycle',
 });
 
 // Update data
-chart.setData([
-  { name: 'Revenue', data: [200, 250, 220, 280, 300] },
-]);
+chart.setData([[50, 1600, 1], [95, 2300, 2]]);
 
 // Change theme
 chart.setOptions({ theme: 'light' });
@@ -42,9 +36,58 @@ chart.destroy();
 
 ## Chart Types
 
-- `createLineChart` - Line charts with optional points
-- `createBarChart` - Bar/column charts with grouping and stacking
-- `createAreaChart` - Area charts with gradient fills
+### `createColumn3DChart`
+
+3D column/bar chart for phase-resolved data visualization. Built on SciChart 3D with WebGL rendering.
+
+```typescript
+import { createColumn3DChart } from '@rm-graph/core';
+import type { Column3DDataPoint, Column3DChartStats } from '@rm-graph/core';
+
+const chart = await createColumn3DChart('container-id', {
+  data: [[45, 1500, 1], [90, 2200, 2], [180, 1800, 3]],
+  xAxisTitle: 'Phase Angle (°)',
+  yAxisTitle: 'Amplitude (mVp)',
+  zAxisTitle: 'Cycle',
+  xRange: { min: 0, max: 360 },
+  yRange: { min: 0, max: 5000 },
+  zRange: { min: 0, max: 50 },
+  barFill: '#52aaf2',
+  barOpacity: 0.95,
+  showSineWave: true,
+  enableCameraClamping: true,
+  onStatsChange: (stats: Column3DChartStats) => {
+    console.log('Pulse Count:', stats.pulseCount, 'Peak:', stats.peakValue);
+  },
+});
+
+// Update data
+chart.setData([[50, 1600, 1], [95, 2300, 2]]);
+
+// Change camera preset
+chart.setCameraPreset(0); // Top view
+
+// Reset camera
+chart.resetCamera();
+
+// Take screenshot
+chart.captureScreenshot('chart-screenshot');
+
+// Cleanup
+chart.destroy();
+```
+
+**Data format**: `[phaseAngle, amplitude, cycle]` - each tuple represents a 3D column bar.
+
+**Key features**: Camera presets, orbit rotation with clamping, sine wave overlay, zoom control, screenshot export, statistics tracking.
+
+### `createPRPDChart`
+
+Phase Resolved Partial Discharge heatmap visualization.
+
+**Data format**: `[phaseAngle, amplitude, count]` - each tuple represents pulse density at a given position.
+
+**Key features**: Heatmap color coding, sine wave overlay, resolution modes, windowing support, screenshot export.
 
 ## Theming
 

package/dist/index.d.mts

@@ -164,6 +164,26 @@ declare function createSurface3DChart(container: HTMLElement | string, config: S
 
 /** Data point for 3D column chart [x, y, z] */
 type Column3DDataPoint = [number, number, number];
+/** Unit of measurement options */
+type UnitOfMeasurement = "mVp" | "mVrms" | "dBm" | "dB" | number;
+/** Camera preset positions */
+interface CameraPreset {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Chart statistics */
+interface Column3DChartStats {
+    pulseCount: number;
+    peakValue: number;
+}
 /** Configuration for 3D Column Chart */
 interface Column3DChartConfig extends ChartConfig {
     /** Array of [x, y, z] data points */
@@ -217,7 +237,37 @@ interface Column3DChartConfig extends ChartConfig {
     sineWaveCenter?: number;
     /** Sine wave amplitude range */
     sineWaveAmplitude?: number;
+    /** Unit of measurement */
+    unitOfMeasurement?: UnitOfMeasurement;
+    /** Enable camera clamping to restrict camera movement */
+    enableCameraClamping?: boolean;
+    /** Maximum camera radius */
+    maxCameraRadius?: number;
+    /** Minimum camera radius */
+    minCameraRadius?: number;
+    /** Minimum yaw angle in degrees (horizontal). Default -179. */
+    minYaw?: number;
+    /** Maximum yaw angle in degrees (horizontal). Default 179. */
+    maxYaw?: number;
+    /** Minimum pitch angle in degrees (vertical). Default 0. */
+    minPitch?: number;
+    /** Maximum pitch angle in degrees (vertical). Default 88. */
+    maxPitch?: number;
+    /** Camera preset positions */
+    cameraPresets?: CameraPreset[];
+    /** Use cylinder point markers instead of columns */
+    useCylinderMarkers?: boolean;
+    /** Callback when stats change */
+    onStatsChange?: (stats: Column3DChartStats) => void;
 }
+/** Default camera presets */
+declare const DEFAULT_CAMERA_PRESETS: CameraPreset[];
+/** Unit of measurement labels */
+declare const UOM_LABELS: Record<number | string, string>;
+/** Convert mVrms to dBm */
+declare function mVrmsToDbm(mVrms: number): number;
+/** Convert mVp to dB */
+declare function mVpToDb(mVp: number): number;
 /**
  * 3D Column/Bar Chart implementation using SciChart
  */
@@ -229,7 +279,12 @@ declare class Column3DChart {
     private config;
     private dataSeries;
     private columnSeries;
+    private sineSeries;
     private isDestroyed;
+    private stats;
+    private cameraClampingEnabled;
+    private initialCameraPosition;
+    private initialCameraTarget;
     constructor(config: Column3DChartConfig);
     /**
      * Initialize the chart in the given container
@@ -239,6 +294,16 @@ declare class Column3DChart {
      * Create the SciChart 3D surface
      */
     private createSurface;
+    /**
+     * Setup camera clamping to restrict camera movement.
+     * Yaw snaps to boundaries: >100 → -180, >=0 → 0 (keeps view in -180..0 range).
+     * Pitch clamped to [0, 89]. Radius clamped to [495, 805].
+     */
+    private setupCameraClamping;
+    /**
+     * Setup axes with proper configuration
+     */
+    private setupAxes;
     /**
      * Add column data to the chart
      */
@@ -267,6 +332,26 @@ declare class Column3DChart {
         y: number;
         z: number;
     }): void;
+    /**
+     * Set camera to a preset position
+     */
+    setCameraPreset(presetIndex: number): void;
+    /**
+     * Reset camera to initial position
+     */
+    resetCamera(): void;
+    /**
+     * Update Y axis range
+     */
+    setYAxisRange(min: number, max: number): void;
+    /**
+     * Update Z axis range (cycle range)
+     */
+    setZAxisRange(min: number, max: number): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): Column3DChartStats;
     /**
      * Update chart options
      */
@@ -275,6 +360,11 @@ declare class Column3DChart {
      * Get the SciChart surface for advanced operations
      */
     getSurface(): SciChart3DSurface | null;
+    /**
+     * Notify SciChart that the container has resized so the WebGL canvas
+     * adjusts to the new dimensions. Call after maximize / minimize.
+     */
+    resize(): void;
     /**
      * Destroy and clean up
      */
@@ -284,7 +374,7 @@ declare class Column3DChart {
      */
     getConfig(): Column3DChartConfig;
     /**
-     * Check if chart is ready (initialized and not destroyed)
+     * Check if chart is ready
      */
     isReady(): boolean;
 }
@@ -479,4 +569,4 @@ declare function configureSciChart(options: {
     wasmUrl?: string;
 }): void;
 
-export { BaseChart, ChartConfig, ChartEventMap, ChartInstance, Column3DChart, type Column3DChartConfig, type Column3DDataPoint, DataPoint, PRPDChart, PRPDChartConfig, PRPDChartStats, PRPDDataPoint, PRPDResolutionLabel, PRPDWindowingRegion, SeriesData, Surface3DChart, Surface3DChartConfig, ThemeConfig, VERSION, calculateDataRange, clamp, configureSciChart, createColumn3DChart, createPRPDChart, createSurface3DChart, debounce, deepMerge, extractXValues, extractYValues, formatNumber, generateId, hexToRgba, lerp, normalizeDataPoints, parseSize, throttle };
+export { BaseChart, type CameraPreset, ChartConfig, ChartEventMap, ChartInstance, Column3DChart, type Column3DChartConfig, type Column3DChartStats, type Column3DDataPoint, DEFAULT_CAMERA_PRESETS, DataPoint, PRPDChart, PRPDChartConfig, PRPDChartStats, PRPDDataPoint, PRPDResolutionLabel, PRPDWindowingRegion, SeriesData, Surface3DChart, Surface3DChartConfig, ThemeConfig, UOM_LABELS, type UnitOfMeasurement, VERSION, calculateDataRange, clamp, configureSciChart, createColumn3DChart, createPRPDChart, createSurface3DChart, debounce, deepMerge, extractXValues, extractYValues, formatNumber, generateId, hexToRgba, lerp, mVpToDb, mVrmsToDbm, normalizeDataPoints, parseSize, throttle };

package/dist/index.d.ts

@@ -164,6 +164,26 @@ declare function createSurface3DChart(container: HTMLElement | string, config: S
 
 /** Data point for 3D column chart [x, y, z] */
 type Column3DDataPoint = [number, number, number];
+/** Unit of measurement options */
+type UnitOfMeasurement = "mVp" | "mVrms" | "dBm" | "dB" | number;
+/** Camera preset positions */
+interface CameraPreset {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Chart statistics */
+interface Column3DChartStats {
+    pulseCount: number;
+    peakValue: number;
+}
 /** Configuration for 3D Column Chart */
 interface Column3DChartConfig extends ChartConfig {
     /** Array of [x, y, z] data points */
@@ -217,7 +237,37 @@ interface Column3DChartConfig extends ChartConfig {
     sineWaveCenter?: number;
     /** Sine wave amplitude range */
     sineWaveAmplitude?: number;
+    /** Unit of measurement */
+    unitOfMeasurement?: UnitOfMeasurement;
+    /** Enable camera clamping to restrict camera movement */
+    enableCameraClamping?: boolean;
+    /** Maximum camera radius */
+    maxCameraRadius?: number;
+    /** Minimum camera radius */
+    minCameraRadius?: number;
+    /** Minimum yaw angle in degrees (horizontal). Default -179. */
+    minYaw?: number;
+    /** Maximum yaw angle in degrees (horizontal). Default 179. */
+    maxYaw?: number;
+    /** Minimum pitch angle in degrees (vertical). Default 0. */
+    minPitch?: number;
+    /** Maximum pitch angle in degrees (vertical). Default 88. */
+    maxPitch?: number;
+    /** Camera preset positions */
+    cameraPresets?: CameraPreset[];
+    /** Use cylinder point markers instead of columns */
+    useCylinderMarkers?: boolean;
+    /** Callback when stats change */
+    onStatsChange?: (stats: Column3DChartStats) => void;
 }
+/** Default camera presets */
+declare const DEFAULT_CAMERA_PRESETS: CameraPreset[];
+/** Unit of measurement labels */
+declare const UOM_LABELS: Record<number | string, string>;
+/** Convert mVrms to dBm */
+declare function mVrmsToDbm(mVrms: number): number;
+/** Convert mVp to dB */
+declare function mVpToDb(mVp: number): number;
 /**
  * 3D Column/Bar Chart implementation using SciChart
  */
@@ -229,7 +279,12 @@ declare class Column3DChart {
     private config;
     private dataSeries;
     private columnSeries;
+    private sineSeries;
     private isDestroyed;
+    private stats;
+    private cameraClampingEnabled;
+    private initialCameraPosition;
+    private initialCameraTarget;
     constructor(config: Column3DChartConfig);
     /**
      * Initialize the chart in the given container
@@ -239,6 +294,16 @@ declare class Column3DChart {
      * Create the SciChart 3D surface
      */
     private createSurface;
+    /**
+     * Setup camera clamping to restrict camera movement.
+     * Yaw snaps to boundaries: >100 → -180, >=0 → 0 (keeps view in -180..0 range).
+     * Pitch clamped to [0, 89]. Radius clamped to [495, 805].
+     */
+    private setupCameraClamping;
+    /**
+     * Setup axes with proper configuration
+     */
+    private setupAxes;
     /**
      * Add column data to the chart
      */
@@ -267,6 +332,26 @@ declare class Column3DChart {
         y: number;
         z: number;
     }): void;
+    /**
+     * Set camera to a preset position
+     */
+    setCameraPreset(presetIndex: number): void;
+    /**
+     * Reset camera to initial position
+     */
+    resetCamera(): void;
+    /**
+     * Update Y axis range
+     */
+    setYAxisRange(min: number, max: number): void;
+    /**
+     * Update Z axis range (cycle range)
+     */
+    setZAxisRange(min: number, max: number): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): Column3DChartStats;
     /**
      * Update chart options
      */
@@ -275,6 +360,11 @@ declare class Column3DChart {
      * Get the SciChart surface for advanced operations
      */
     getSurface(): SciChart3DSurface | null;
+    /**
+     * Notify SciChart that the container has resized so the WebGL canvas
+     * adjusts to the new dimensions. Call after maximize / minimize.
+     */
+    resize(): void;
     /**
      * Destroy and clean up
      */
@@ -284,7 +374,7 @@ declare class Column3DChart {
      */
     getConfig(): Column3DChartConfig;
     /**
-     * Check if chart is ready (initialized and not destroyed)
+     * Check if chart is ready
      */
     isReady(): boolean;
 }
@@ -479,4 +569,4 @@ declare function configureSciChart(options: {
     wasmUrl?: string;
 }): void;
 
-export { BaseChart, ChartConfig, ChartEventMap, ChartInstance, Column3DChart, type Column3DChartConfig, type Column3DDataPoint, DataPoint, PRPDChart, PRPDChartConfig, PRPDChartStats, PRPDDataPoint, PRPDResolutionLabel, PRPDWindowingRegion, SeriesData, Surface3DChart, Surface3DChartConfig, ThemeConfig, VERSION, calculateDataRange, clamp, configureSciChart, createColumn3DChart, createPRPDChart, createSurface3DChart, debounce, deepMerge, extractXValues, extractYValues, formatNumber, generateId, hexToRgba, lerp, normalizeDataPoints, parseSize, throttle };
+export { BaseChart, type CameraPreset, ChartConfig, ChartEventMap, ChartInstance, Column3DChart, type Column3DChartConfig, type Column3DChartStats, type Column3DDataPoint, DEFAULT_CAMERA_PRESETS, DataPoint, PRPDChart, PRPDChartConfig, PRPDChartStats, PRPDDataPoint, PRPDResolutionLabel, PRPDWindowingRegion, SeriesData, Surface3DChart, Surface3DChartConfig, ThemeConfig, UOM_LABELS, type UnitOfMeasurement, VERSION, calculateDataRange, clamp, configureSciChart, createColumn3DChart, createPRPDChart, createSurface3DChart, debounce, deepMerge, extractXValues, extractYValues, formatNumber, generateId, hexToRgba, lerp, mVpToDb, mVrmsToDbm, normalizeDataPoints, parseSize, throttle };