svelte-plots-basic 2.5.8 → 3.0.1

package/src/3d/Segments.svelte

@@ -1,68 +1,84 @@
-<script>
-   /****************************************************
-   * Segments for 3D plot                              *
-   * --------------------                              *
-   * shows a series of line segments on the plot       *
-   *****************************************************/
+<!--
+@component Adds a series with line segments.
 
-   import { cbind } from 'mdatools/arrays';
-   import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
+   Main properties:
+   - `xStart` - vector or array with x-coordinates of starting points.
+   - `xEnd` -  or array with x-coordinates of end points.
+   - `yStart` - vector or array with y-coordinates of starting points.
+   - `yEnd` - vector or array with y-coordinates of end points.
+   - `zStart` - vector or array with z-coordinates of starting points.
+   - `zEnd` - vector or array with z-coordinates of end points.
+   - `lineColor` - color of segment lines, default: `Colors.PRIMARY`.
+   - `lineType` -  type of segment lines (`1` - solid, `2` - dashed, `3` - dotted, `4` - dashdot).
+   - `lineWidth` - width (thickness) of segment lines in pixels, default: `1`.
+   - `className` - CSS class name of the SVG group, default: `'series-seg'`.
+   - `title` - title of the segment series group.
+   - `onclick` - function (callback) to be called when user clicks on any segment.
 
+   Example:
+   ```jsx
+   <script>
+      import { Axes, Segments } from 'svelte-plots-basic/3d';
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+      const xStart = [1, 2, 3, 4];
+      const xEnd = [1, 2, 3, 4];
+      const yStart = [-2, -1, 0, -1, -2];
+      const yEnd = [2, 1, 0, 1, 2];
+      const zStart = [1, 2, 3, 4];
+      const zEnd = [1, 2, 3, 4];
+   </script>
 
-   export let title = '';
-	export let xStart;
-   export let xEnd;
-   export let yStart;
-   export let yEnd;
-   export let zStart;
-   export let zEnd;
+   <Axes limX={[0, 5]} limY={[-3, 3]} >
+      <Segments {xStart} {yStart} {zStart} {xEnd} {yEnd} {zEnd} lineColor="red" lineType={3} />
+   </Axes>
+   ```
+-->
+<script>
+   import { cbind } from 'mdatools/arrays';
+   import { getContext } from 'svelte';
+   import { Colors, LINE_STYLES } from '../constants';
+   import { checkCoords, transform3D } from '../methods';
 
-   export let lineColor = Colors.PRIMARY;
-   export let lineType = 1;
-   export let lineWidth = 1;
 
-   // get axes context and reactive variables needed to compute coordinates
-   const axes = getContext('axes');
-   const scale = axes.scale;
-   const tM = axes.tM;
-   const isOk = axes.isOk;
+   let {
+	   xStart,
+      xEnd,
+      yStart,
+      yEnd,
+      zStart,
+      zEnd,
+      lineColor = Colors.PRIMARY,
+      lineType = 1,
+      lineWidth = 1,
+      title = '',
+   } = $props();
 
-   let x1, y1, x2, y2 = undefined;
-   $: {
-      if ($isOk) {
 
-         [x1, y1] = axes.transform(
-            cbind(
-               checkCoords(xStart, 'Segments'),
-               checkCoords(yStart, 'Segments'),
-               checkCoords(zStart, 'Segments')
-            ), $tM
-         );
+   // check user defined coordinates
+   const ux1 = $derived(checkCoords(xStart, 'Segments (3D)'));
+   const uy1 = $derived(ux1 ? checkCoords(yStart, 'Segments (3D)', ux1.length) : null);
+   const uz1 = $derived(uy1 ? checkCoords(zStart, 'Segments (3D)', ux1.length) : null);
 
-         [x2, y2] = axes.transform(
-            cbind(
-               checkCoords(xEnd, 'Segments'),
-               checkCoords(yEnd, 'Segments'),
-               checkCoords(zEnd, 'Segments')
-            ), $tM
-         );
+   const ux2 = $derived(uz1 ? checkCoords(xEnd, 'Segments (3D)', ux1.length) : null);
+   const uy2 = $derived(ux1 ? checkCoords(yEnd, 'Segments (3D)', ux1.length) : null);
+   const uz2 = $derived(uy1 ? checkCoords(zEnd, 'Segments (3D)', ux1.length) : null);
 
-      }
-   }
+   // combine world coordinates to matrices
+   const uW1 = $derived(ux1 && uy1 && uz1 ? cbind(ux1, uy1, uz1) : null);
+   const uW2 = $derived(ux2 && uy2 && uz2 ? cbind(ux2, uy2, uz2) : null);
+
+   // get axes context and compute screen coordinates
+   const axes = getContext('axes');
+   const s1 = $derived(uW1 ? transform3D(uW1, axes.tM()) : null);
+   const s2 = $derived(uW2 ? transform3D(uW2, axes.tM()) : null);
 
-   $: lineStyleStr = `stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${axes.LINE_STYLES[$scale][lineType-1]}`;
+   const lineStyleStr = $derived(`stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scale()][lineType-1]}`);
 </script>
 
-<g class="series series_segment" data-title="{title}" style={lineStyleStr}>
-{#if $isOk && x1 !== undefined && y1 !== undefined && x2 !== undefined && y2 !== undefined}
-   {#each x1 as v, i}
-      <line vector-effect="non-scaling-stroke" x1={x1[i]} x2={x2[i]} y1={y1[i]} y2={y2[i]} />
+<g class="series series-segments" data-title={title} style={lineStyleStr}>
+{#if s1 && s2}
+   {#each s1.x as v, i}
+      <line x1={s1.x[i]} x2={s2.x[i]} y1={s1.y[i]} y2={s2.y[i]} />
    {/each}
 {/if}
 </g>

package/src/3d/TextLabels.svelte

@@ -1,72 +1,86 @@
-<script>
-   /****************************************************
-   * TextLabels for 3D plots                           *
-   * -----------------------                           *
-   * shows a series of text labels on the plot         *
-   *****************************************************/
+<!--
+@component Adds a series of text labels at given coordinates.
+
+   Main properties:
+   - `xValues` - array of vector with x-coordinates of the points.
+   - `yValues` - array of vector with y-coordinates of the points.
+   - `zValues` - array of vector with z-coordinates of the points.
+   - `labels` - array with labels.
+   - `faceColor` - face (fill) color of the markers, default: `'transparent'`.
+   - `borderColor` - color markers' borders, default: `Colors.PRIMARY`.
+   - `borderWidth` - width (thickness) of the markers' borders in pixels, default: `1`.
+   - `textSize` - size of the markers in em, default: `1`.
+   - `title` - title of the line series group.
+
+   Example:
+   ```jsx
+   <script>
+      import { Axes, TextLabels } from 'svelte-plots-basic/3d';
+
+      const xValues = [-3, -2, -1, 0, 1, 2, 3];
+      const yValues = [ 9,  4,  1, 0, 1, 4, 9];
+      const zValues = [-3, -2, -1, 0, 1, 2, 3];
+      const labels = ["A", "B", "C", "D", "E", "F", "G"];
+   </script>
 
+   <Axes limX={[-4, 4]} limY={[-2, 10]} limZ={[-4, 4]}>
+      <TextLabels {xValues} {yValues} {zValues} {labels} />
+   </Axes>
+   ```
+-->
+<script>
    import { cbind } from 'mdatools/arrays';
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
-
+   import { Colors } from '../constants';
+   import { checkCoords, transform3D } from '../methods';
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   let {
+      title = '',
+	   xValues,
+      yValues,
+      zValues,
+      labels,
+      faceColor = Colors.PRIMARY_TEXT,
+      borderColor = 'transparent',
+      borderWidth = 0,
+      textSize = 1,
+      className = 'series-textlabel',
+      fontWeight = 'normal'
+   } = $props();
 
-   export let title = '';
-	export let xValues;
-   export let yValues;
-   export let zValues;
-   export let labels;
 
-   export let faceColor = Colors.PRIMARY_TEXT;
-   export let borderColor = 'transparent';
-   export let borderWidth = 0;
-   export let textSize = 1;
-   export let className = 'series_textlabel';
+   const ux = $derived(checkCoords(xValues, 'TextLabels (3D)'));
+   const uy = $derived(ux ? checkCoords(yValues, 'TextLabels (3D)', ux.length) : null);
+   const uz = $derived(uy ? checkCoords(zValues, 'TextLabels (3D)', uy.length) : null);
+   const U = $derived(ux && uy && uz ? cbind(ux, uy, uz) : null);
 
+   const l = $derived.by(() => {
+      if(Array.isArray(labels) && labels.length !== ux.length ) {
+         console.error('TextLabels: labels provided as an array should have the same number of elements as number of coordinates.');
+         return null;
+      }
+      return labels;
+   });
 
    // get axes context and reactive variables needed to compute coordinates
    const axes = getContext('axes');
-   const tM = axes.tM;
-   const isOk = axes.isOk;
-
-   // compute screen coordinates
-   let x, y = undefined;
-   $: {
-      if ($isOk) {
-
-         [x, y] = axes.transform(
-            cbind(
-               checkCoords(xValues, 'TextValues'),
-               checkCoords(yValues, 'TextValues'),
-               checkCoords(zValues, 'TextValues')
-            ), $tM
-         );
-
-         if (Array.isArray(labels) && labels.length !== x.length ) {
-            throw('TextLabels: number of elements in "labels" does not match number of coordinates.')
-         }
-      }
-   }
+   const s = $derived(U && l ? transform3D(U, axes.tM()) : null);
 
    // styles for the elements
-   $: textStyleStr = `dominant-baseline:middle;fill:${faceColor};stroke-width:${borderWidth}px;stroke:${borderColor};
-      font-size:${textSize}em; text-anchor:middle;`;
+   const textStyleStr = $derived(`dominant-baseline:middle;fill:${faceColor};stroke-width:${borderWidth}px;stroke:${borderColor};
+      font-size:${textSize}em; text-anchor:middle;font-weight:${fontWeight}`);
 </script>
 
-{#if $isOk && x !== undefined && y !== undefined}
+{#if s}
 <g class="series {className}" title={title} style={textStyleStr} >
 
    {#if typeof labels === 'string'}
-   {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={0} dy={0}>{@html labels}</text>
+   {#each s.x as v, i}
+      <text data-id={i} x={s.x[i]} y={s.y[i]} dx={0} dy={0}>{@html l}</text>
    {/each}
    {:else}
    {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={0} dy={0}>{@html labels[i]}</text>
+      <text data-id={i} x={s.x[i]} y={s.y[i]} dx={0} dy={0}>{@html l[i]}</text>
    {/each}
    {/if}
 </g>

package/src/3d/XAxis.svelte

@@ -1,123 +1,46 @@
+<!--
+@component Adds x-axis with ticks, label, etc.
+
+   Main properties:
+   - `label` - text label for the axis (optional).
+   - `showGrid` - logical, show or not vertical grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limX`).
+   - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
+   - `lineColor` - color of axis line, default: `Colors.DARKGRAY`.
+   - `gridColor` - color of axis grid line, default: `Colors.MIDDLEGRAY`.
+   - `textColor` - color of axis text labels, default: `Colors.DARKGRAY`.
+
+   Example:
+   ```jsx
+   <script>
+      import {Axes, XAxis} from 'svelte-plots-basic/3d';
+   </script>
+   <Axes>
+      // all other plotting components are here
+      <XAxis label="X" showGrid={true} />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * X-Axis for 3D plots                               *
-   * --------------------                              *
-   * shows x-axis and its elements (ticks, grid, etc.) *
-   *****************************************************/
-
-   import { cbind, matrix, Vector } from 'mdatools/arrays';
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { getAxisTicks } from '../Utils.js';
-   import Axis from './Axis.svelte';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-   export let slot = 'xaxis';         // slot the component must be placed in
-   export let ticks = undefined;      // vector with numeric tick positions in plot units
-   export let tickLabels = ticks;     // vector with labels for each tick
-   export let showGrid = false;       // logical, show or not grid lines
-   export let title = '';             // axis title
-
-   export let lineColor = Colors.DARKGRAY;
-   export let gridColor = Colors.MIDDLEGRAY;
-   export let textColor = Colors.DARKGRAY;
+   import { Colors } from '../constants';
 
+   let {
+      ticks,                           // vector with numeric tick positions in plot units
+      tickLabels = ticks,              // vector with labels for each tick
+      showGrid = false,                // logical, show or not grid lines
+      label = '',                      // axis label
+      lineColor = Colors.DARKGRAY,
+      gridColor = Colors.MIDDLEGRAY,
+      textColor = Colors.DARKGRAY,
+   } = $props();
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   if (slot !== 'xaxis') {
-      throw('Component XAxis must have "slot=\'xaxis\'" attribute.');
-   }
 
    // get axes context and adjust x margins
    const axes = getContext('axes');
-
-   // get reactive variables needed to compute coordinates
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const zLim = axes.zLim;
-   const scale = axes.scale;
-   const isOk = axes.isOk;
-
-   // prepare variables for coordinates
-   let titleCoords = [];
-   let grid1 = [];
-   let grid2 = [];
-   let axisLine = [];
-   let tickCoords = [];
-
-   // compute tick x-coordinates
-   $: if ($isOk) {
-      const dX = ($xLim[1] - $xLim[0]) / 100; // 1% of axis size
-      const ticksX = getAxisTicks(ticks, $xLim, axes.TICK_NUM[$scale], true);
-      const tickNum = ticksX.length;
-
-      // compute tick y-coordinates (middle, up and bottom)
-      const dY = ($yLim[1] - $yLim[0]) / 100; // 1% of axis size
-      const ticksY  = Vector.fill($yLim[0], tickNum);
-      const ticksY1 = ticksY.subtract(dY * 1.5);
-      const ticksY2 = ticksY.add(dY * 1.5);
-      const ticksY3 = ticksY.subtract(dY * 5);
-
-      // tick z-coordinates (middle, up and bottom)
-      const dZ = ($zLim[1] - $zLim[0]) / 100; // 1% of axis size
-      const ticksZ  = Vector.fill($zLim[0], tickNum);
-      const ticksZ1 = ticksZ.subtract(dZ * 1.5);
-      const ticksZ2 = ticksZ.add(dZ * 1.5);
-      const ticksZ3 = ticksZ.subtract(dZ * 2);
-
-      // coordinates for the ends of grid
-      const gridYEnd = Vector.fill($yLim[1], tickNum);
-      const gridZEnd = Vector.fill($zLim[1], tickNum);
-
-      // tick labels
-      tickLabels = (ticks === undefined || tickLabels === undefined) ? ticksX.v : tickLabels;
-      if (tickLabels.length !== ticksX.length) {
-         throw Error('XAxis: "tickLabels" must be a array of the same size as ticks.');
-      }
-
-      // combine all coordinates together
-      grid1 = [
-         cbind(ticksX, ticksY, ticksZ),
-         cbind(ticksX, gridYEnd, ticksZ)
-      ];
-
-      grid2 = [
-         cbind(ticksX, ticksY, ticksZ),
-         cbind(ticksX, ticksY2, gridZEnd)
-      ];
-
-      axisLine = [
-         matrix([$xLim[0], $yLim[0], $zLim[0]], 1, 3),
-         matrix([$xLim[1], $yLim[0], $zLim[0]], 1, 3)
-      ]
-
-      tickCoords = [
-         cbind(ticksX, ticksY, ticksZ),   // middle point
-         cbind(ticksX, ticksY2, ticksZ),  // middle point with positive shift along Y
-         cbind(ticksX, ticksY, ticksZ2),  // middle point with positive shift along Z
-         cbind(ticksX, ticksY1, ticksZ1),  // middle point with negative shift along Y and Z
-         cbind(ticksX, ticksY3, ticksZ3)  // middle point with negative shift along Y and Z for ticks
-      ];
-
-      // here we do not need to make a matrix as the three values will be used as vectors
-      titleCoords = [
-         [$xLim[1] + 3 * dX], [$yLim[0] - 2 * dY], [$zLim[0] - 2 * dZ]
-      ];
-   }
+   $effect(() => {
+      axes.setXAxis({show: true, ticks, tickLabels, showGrid, label, lineColor, gridColor, textColor});
+   });
 </script>
 
-{#if $isOk && axisLine.length > 0}
-<Axis
-   className="mdaplot__xaxis"
-   {title} {lineColor} {gridColor} {textColor} {titleCoords}
-   {showGrid} {grid1} {grid2} {axisLine} {tickCoords} {tickLabels}
-/>
-{/if}
 

package/src/3d/YAxis.svelte

@@ -1,123 +1,46 @@
+<!--
+@component Adds y-axis with ticks, label, etc.
+
+   Main properties:
+   - `label` - text label for the axis (optional).
+   - `showGrid` - logical, show or not vertical grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limX`).
+   - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
+   - `lineColor` - color of axis line, default: `Colors.DARKGRAY`.
+   - `gridColor` - color of axis grid line, default: `Colors.MIDDLEGRAY`.
+   - `textColor` - color of axis text labels, default: `Colors.DARKGRAY`.
+
+   Example:
+   ```jsx
+   <script>
+      import {Axes, YAxis} from 'svelte-plots-basic/3d';
+   </script>
+   <Axes>
+      // all other plotting components are here
+      <YAxis label="Y" showGrid={true} />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Y-Axis for 3D plots                               *
-   * --------------------                              *
-   * shows y-axis and its elements (ticks, grid, etc.) *
-   *****************************************************/
-
-   import { cbind, matrix, Vector } from 'mdatools/arrays';
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { getAxisTicks } from '../Utils.js';
-   import Axis from './Axis.svelte';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-   export let slot = 'yaxis';         // slot the component must be placed in
-   export let ticks = undefined;      // vector with numeric tick positions in plot units
-   export let tickLabels = ticks;     // vector with labels for each tick
-   export let showGrid = false;       // logical, show or not grid lines
-   export let title = '';             // axis title
-
-   export let lineColor = Colors.DARKGRAY;
-   export let gridColor = Colors.MIDDLEGRAY;
-   export let textColor = Colors.DARKGRAY;
+   import { Colors } from '../constants';
 
+   let {
+      ticks,                           // vector with numeric tick positions in plot units
+      tickLabels = ticks,              // vector with labels for each tick
+      showGrid = false,                // logical, show or not grid lines
+      label = '',                      // axis label
+      lineColor = Colors.DARKGRAY,
+      gridColor = Colors.MIDDLEGRAY,
+      textColor = Colors.DARKGRAY,
+   } = $props();
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   if (slot !== 'yaxis') {
-      throw('Component YAxis must have "slot=\'yaxis\'" attribute.');
-   }
 
    // get axes context and adjust x margins
    const axes = getContext('axes');
-
-   // get reactive variables needed to compute coordinates
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const zLim = axes.zLim;
-   const scale = axes.scale;
-   const isOk = axes.isOk;
-
-   // prepare variables for coordinates
-   let titleCoords = [];
-   let grid1 = [];
-   let grid2 = [];
-   let axisLine = [];
-   let tickCoords = [];
-
-   // compute tick x-coordinates
-   $: if ($isOk) {
-      const dY = ($yLim[1] - $yLim[0]) / 100; // 1% of axis size
-      const ticksY = getAxisTicks(ticks, $yLim, axes.TICK_NUM[$scale], true);
-      const tickNum = ticksY.length;
-
-      // compute tick y-coordinates (middle, up and bottom)
-      const dX = ($xLim[1] - $xLim[0]) / 100; // 1% of axis size
-      const ticksX  = Vector.fill($xLim[0], tickNum);
-      const ticksX1 = ticksX.subtract(dX * 1.5);
-      const ticksX2 = ticksX.add(dX * 1.5);
-      const ticksX3 = ticksX.subtract(dX * 3);
-
-      // tick z-coordinates (middle, up and bottom)
-      const dZ = ($zLim[1] - $zLim[0]) / 100; // 1% of axis size
-      const ticksZ  = Vector.fill($zLim[0], tickNum);
-      const ticksZ1 = ticksZ.subtract(dZ * 1.5);
-      const ticksZ2 = ticksZ.add(dZ * 1.5);
-      const ticksZ3 = ticksZ.subtract(dZ * 2);
-
-      // coordinates for the ends of grid
-      const gridXEnd = Vector.fill($xLim[1], tickNum);
-      const gridZEnd = Vector.fill($zLim[1], tickNum);
-
-      // tick labels
-      tickLabels = (ticks === undefined || tickLabels === undefined) ? ticksY.v : tickLabels;
-      if (tickLabels.length !== ticksY.length) {
-         throw Error('YAxis: "tickLabels" must be a array of the same size as ticks.');
-      }
-
-      // combine all coordinates together
-      grid1 = [
-         cbind(ticksX, ticksY, ticksZ),
-         cbind(gridXEnd, ticksY, ticksZ)
-      ];
-
-      grid2 = [
-         cbind(ticksX, ticksY, ticksZ),
-         cbind(ticksX, ticksY, gridZEnd)
-      ];
-
-      axisLine = [
-         matrix([$xLim[0], $yLim[0], $zLim[0]], 1, 3),
-         matrix([$xLim[0], $yLim[1], $zLim[0]], 1, 3)
-      ]
-
-      tickCoords = [
-         cbind(ticksX, ticksY, ticksZ),   // middle point
-         cbind(ticksX2, ticksY, ticksZ),  // middle point with positive shift along X
-         cbind(ticksX, ticksY, ticksZ2),  // middle point with positive shift along Z
-         cbind(ticksX1, ticksY, ticksZ1),  // middle point with negative shift along X and Z
-         cbind(ticksX3, ticksY, ticksZ3)  // middle point with negative shift along X and Z for ticks
-      ];
-
-      // here we do not need to make a matrix as the three values will be used as vectors
-      titleCoords = [
-         [$xLim[0] - 2 * dX], [$yLim[1] + 3 * dY], [$zLim[0] - 2 * dZ]
-      ];
-   }
+   $effect(() => {
+      axes.setYAxis({show: true, ticks, tickLabels, showGrid, label, lineColor, gridColor, textColor});
+   });
 </script>
 
-{#if $isOk && axisLine.length > 0}
-<Axis
-   className="mdaplot__yaxis"
-   {title} {lineColor} {gridColor} {textColor} {titleCoords}
-   {showGrid} {grid1} {grid2} {axisLine} {tickCoords} {tickLabels}
-/>
-{/if}