visualifyjs 2.5.3 → 3.0.0

package/docs/docs/3d-visualization.md

@@ -0,0 +1,374 @@
+<!-- Load 3D visualization examples from external script to avoid docsify parsing issues -->
+<script src="./static/js/3d-viz-examples.js"></script>
+
+# 3D Visualization
+
+Visualify.js supports 3D visualization through ECharts GL and Three.js integration.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [ECharts GL 3D Charts](#echarts-gl-3d-charts)
+  - [Scatter3D](#scatter3d)
+  - [Bar3D](#bar3d)
+  - [Surface3D](#surface3d)
+  - [Line3D](#line3d)
+- [Three.js Integration](#threejs-integration)
+- [WebGL Support](#webgl-support)
+- [Performance Considerations](#performance-considerations)
+
+---
+
+## Overview
+
+Visualify.js provides two approaches to 3D visualization:
+
+1. **ECharts GL** - For standard 3D charts (scatter, bar, surface, line)
+2. **Three.js** - For custom 3D scenes and advanced visualizations
+
+Both libraries are loaded on-demand to minimize initial bundle size.
+
+---
+
+## ECharts GL 3D Charts
+
+### Scatter3D
+
+Create interactive 3D scatter plots with x, y, z dimensions.
+
+<!-- tabs:start -->
+
+#### **Output**
+
+<div id="scatter3d-example" style="height: 400px;">
+    <p>Loading 3D Scatter Plot... (requires WebGL support)</p>
+</div>
+
+#### **Configuration**
+
+```json
+{
+  "type": "scatter3d",
+  "title": "3D Scatter Plot Example",
+  "data": {
+    "x": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    "y": [10, 15, 8, 20, 12, 18, 22, 16, 14, 25],
+    "z": [5, 8, 12, 7, 9, 11, 6, 13, 10, 15]
+  },
+  "xAxis3D": { "name": "X Dimension", "type": "value" },
+  "yAxis3D": { "name": "Y Dimension", "type": "value" },
+  "zAxis3D": { "name": "Z Dimension", "type": "value" },
+  "grid3D": {
+    "boxWidth": 100,
+    "boxDepth": 80,
+    "viewControl": {
+      "autoRotate": true,
+      "autoRotateSpeed": 10
+    }
+  },
+  "visualMap": {
+    "dimension": 2,
+    "max": 25,
+    "inRange": {
+      "color": ["#313695", "#4575b4", "#74add1", "#abd9e9", "#e0f3f8"]
+    }
+  }
+}
+```
+
+<!-- tabs:end -->
+
+#### Configuration Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data.x` | Array | X-axis data values |
+| `data.y` | Array | Y-axis data values |
+| `data.z` | Array | Z-axis data values |
+| `xAxis3D` | Object | X-axis configuration (name, type, min, max) |
+| `yAxis3D` | Object | Y-axis configuration |
+| `zAxis3D` | Object | Z-axis configuration |
+| `grid3D.viewControl.autoRotate` | Boolean | Enable auto-rotation |
+| `visualMap` | Object | Color mapping based on dimension |
+
+---
+
+### Bar3D
+
+Create 3D bar charts for volumetric data visualization.
+
+<!-- tabs:start -->
+
+#### **Output**
+
+<div id="bar3d-example" style="height: 400px;">
+    <p>Loading 3D Bar Chart... (requires WebGL support)</p>
+</div>
+
+#### **Configuration**
+
+```json
+{
+  "type": "bar3d",
+  "title": "3D Bar Chart Example",
+  "data": [
+    [0, 0, 10], [0, 1, 20], [0, 2, 15],
+    [1, 0, 25], [1, 1, 30], [1, 2, 20],
+    [2, 0, 15], [2, 1, 25], [2, 2, 35]
+  ],
+  "xAxis3D": {
+    "type": "category",
+    "data": ["A", "B", "C"]
+  },
+  "yAxis3D": {
+    "type": "category",
+    "data": ["X", "Y", "Z"]
+  },
+  "zAxis3D": { "type": "value" },
+  "grid3D": {
+    "boxWidth": 200,
+    "boxDepth": 80,
+    "light": {
+      "main": { "intensity": 1.2, "shadow": true }
+    }
+  },
+  "shading": "lambert"
+}
+```
+
+<!-- tabs:end -->
+
+#### Configuration Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | Array | Array of [x, y, z] values |
+| `xAxis3D.type` | String | `"category"` for discrete values |
+| `yAxis3D.type` | String | `"category"` for discrete values |
+| `shading` | String | `"lambert"` for realistic lighting |
+| `grid3D.light` | Object | Lighting configuration |
+
+---
+
+### Surface3D
+
+Create 3D surface plots for continuous data visualization.
+
+<!-- tabs:start -->
+
+#### **Output**
+
+<div id="surface3d-example" style="height: 400px;">
+    <p>Loading 3D Surface Plot... (requires WebGL support)</p>
+</div>
+
+#### **Configuration**
+
+```json
+{
+  "type": "surface3d",
+  "title": "3D Surface Plot Example",
+  "data": {
+    "x": [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5],
+    "y": [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5],
+    "z": [
+      [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.4, 0.3, 0.2, 0.1, 0],
+      [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1],
+      [0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2],
+      [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3],
+      [0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.8, 0.7, 0.6, 0.5, 0.4],
+      [0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 0.9, 0.8, 0.7, 0.6, 0.5],
+      [0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.8, 0.7, 0.6, 0.5, 0.4],
+      [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3],
+      [0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2],
+      [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1],
+      [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.4, 0.3, 0.2, 0.1, 0]
+    ]
+  },
+  "xAxis3D": { "type": "value" },
+  "yAxis3D": { "type": "value" },
+  "zAxis3D": { "type": "value" },
+  "grid3D": {
+    "viewControl": { "autoRotate": true }
+  },
+  "visualMap": {
+    "show": true,
+    "dimension": 2,
+    "min": 0,
+    "max": 1.0,
+    "inRange": {
+      "color": ["#313695", "#4575b4", "#74add1", "#abd9e9", "#e0f3f8", "#ffffbf", "#fee090", "#fdae61", "#f46d43", "#d73027", "#a50026"]
+    }
+  }
+}
+```
+
+<!-- tabs:end -->
+
+#### Configuration Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data.x` | Array | X-axis grid values |
+| `data.y` | Array | Y-axis grid values |
+| `data.z` | 2D Array | Height values (z[x][y]) |
+| `visualMap` | Object | Color gradient for height values |
+
+---
+
+### Line3D
+
+Create 3D line charts for trajectory visualization.
+
+```json
+{
+  "type": "line3d",
+  "title": "3D Line Chart",
+  "data": [
+    [0, 0, 0],
+    [1, 2, 3],
+    [2, 4, 2],
+    [3, 6, 5],
+    [4, 8, 4],
+    [5, 10, 7]
+  ],
+  "xAxis3D": { "type": "value" },
+  "yAxis3D": { "type": "value" },
+  "zAxis3D": { "type": "value" },
+  "grid3D": {
+    "viewControl": {
+      "projection": "perspective",
+      "autoRotate": false
+    }
+  },
+  "lineStyle": {
+    "width": 4,
+    "color": "#5470c6"
+  }
+}
+```
+
+---
+
+## Three.js Integration
+
+For custom 3D scenes beyond standard charts, Visualify.js provides Three.js integration through `@react-three/fiber`.
+
+### Basic Three.js Scene
+
+```json
+{
+  "type": "threejs",
+  "scene": {
+    "camera": {
+      "position": [0, 0, 100],
+      "fov": 75,
+      "near": 0.1,
+      "far": 1000
+    },
+    "lights": [
+      {
+        "type": "ambient",
+        "color": "#ffffff",
+        "intensity": 0.5
+      },
+      {
+        "type": "directional",
+        "position": [10, 10, 10],
+        "castShadow": true
+      }
+    ],
+    "objects": [
+      {
+        "type": "mesh",
+        "geometry": {
+          "type": "box",
+          "width": 10,
+          "height": 10,
+          "depth": 10
+        },
+        "material": {
+          "type": "standard",
+          "color": "#ff0000"
+        },
+        "position": [0, 0, 0],
+        "rotation": [0, 0.5, 0]
+      }
+    ]
+  },
+  "controls": "orbit",
+  "animation": {
+    "autoRotate": true,
+    "speed": 0.01
+  }
+}
+```
+
+---
+
+## WebGL Support
+
+3D charts require WebGL support. Visualify.js automatically detects WebGL availability and shows a fallback message if not supported.
+
+### Browser Compatibility
+
+| Browser | Version | WebGL Support |
+|---------|---------|---------------|
+| Chrome | 9+ | ✓ Full |
+| Firefox | 4+ | ✓ Full |
+| Safari | 5.1+ | ✓ Full |
+| Edge | 12+ | ✓ Full |
+| IE | 11 | ⚠ Limited |
+
+### Fallback Behavior
+
+If WebGL is not supported:
+1. A user-friendly error message is displayed
+2. The chart container shows fallback content
+3. Console warnings provide debugging information
+
+---
+
+## Performance Considerations
+
+### Large Datasets
+
+For datasets with 10,000+ points:
+- Use `sampling` or `progressive` rendering
+- Consider level-of-detail (LOD) techniques
+- Enable `large` mode in ECharts GL
+
+```json
+{
+  "type": "scatter3d",
+  "data": { ... },
+  "series": [{
+    "type": "scatter3D",
+    "large": true,
+    "largeThreshold": 2000,
+    "progressive": 400,
+    "progressiveThreshold": 3000
+  }]
+}
+```
+
+### Lazy Loading
+
+3D libraries are loaded on-demand:
+- ECharts GL loads when first 3D chart is rendered
+- Three.js loads when ThreeScene component is used
+- No impact on initial page load if no 3D charts are present
+
+### Memory Management
+
+- WebGL contexts are automatically cleaned up when charts unmount
+- Dispose geometries, materials, and textures properly
+- Use `cleanupWebGL()` utility for manual cleanup if needed
+
+---
+
+## See Also
+
+- [Configuration Reference](./configuration/visualify-json.md)
+- [CLI Commands](./cli/commands.md)
+- [Migration Guide](./migration/v3-migration.md)

package/docs/docs/CLI.md

@@ -1,34 +1,303 @@
-# CLI tools for Visualify
-
-## Description
-
-The Visualify.CLI command line interface organizes spatial data using R-tree, 
-for efficient data searching and loading. 
-By this means, data portals created by Visualifyjs are able to handle large-scale databases.
-
-## Installation
-
-```bash
-npm install -g @visualify/cli
-```
-
-## Usage
-
-To use Visualify.CLI, you can run the following command:
-
--   init [path] - Create new documentation
--   serve [path] - Run local server to preview site
--   start [path] - Start a web server to serve the specified path
--   load-json <path> - Load points from JSON file
--   mapping [options] <path> - Create a mapping with optional keys
--   rtree2d [options] <path> - Create a 2D R-tree
--   help [command] - display help for command
-
-```bash
-visualify --help
-
-visualify init --help
-visualify serve --help
-visualify start --help
-visualify load-json --help
-```
+# CLI Reference
+
+Visualify.js provides a unified command-line interface for documentation, data visualization, and development workflows.
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g visualify
+```
+
+### Local Installation
+
+```bash
+npm install --save-dev visualify
+npx visualify --help
+```
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `dev` | Start development server with HMR |
+| `docs` | Build and serve documentation |
+| `portal` | Start data portal server |
+| `init` | Initialize a new Visualify project |
+| `edit` / `editor` | Launch visual configuration editor |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-v, --version` | Display version number |
+| `-h, --help` | Display help information |
+| `--verbose` | Enable verbose logging |
+
+## Command Details
+
+### `dev` - Development Server
+
+Start a development server with Hot Module Replacement (HMR).
+
+```bash
+visualify dev [mode]
+```
+
+**Arguments:**
+- `mode` - Development mode: `auto`, `docs`, or `portal` (default: `auto`)
+
+**Options:**
+- `-p, --port <number>` - Port number (default: 3000)
+- `-h, --host <host>` - Host to bind to (default: `localhost`)
+
+**Examples:**
+
+```bash
+# Auto-detect mode based on project structure
+visualify dev
+
+# Start docs dev server
+visualify dev docs
+
+# Start portal dev server on custom port
+visualify dev portal --port 8080
+```
+
+### `docs` - Documentation
+
+Build and serve static documentation.
+
+```bash
+visualify docs [action]
+```
+
+**Arguments:**
+- `action` - Action to perform: `build`, `serve`, or `deploy` (default: `serve`)
+
+**Options:**
+- `-p, --port <number>` - Port for serve mode (default: 3000)
+- `-o, --output <dir>` - Output directory for build (default: `dist/docs`)
+
+**Examples:**
+
+```bash
+# Serve docs with live reload
+visualify docs serve
+
+# Build static documentation
+visualify docs build
+
+# Build to custom directory
+visualify docs build --output ./site
+```
+
+### `portal` - Data Portal
+
+Start the data portal server for spatial data visualization.
+
+```bash
+visualify portal [action]
+```
+
+**Arguments:**
+- `action` - Action to perform: `dev`, `build`, or `start` (default: `dev`)
+
+**Options:**
+- `-p, --port <number>` - Port number (default: 3000)
+- `-d, --data <path>` - Path to data directory
+
+**Examples:**
+
+```bash
+# Start portal dev server
+visualify portal dev
+
+# Build portal for production
+visualify portal build
+
+# Start production server
+visualify portal start --port 8080
+```
+
+### `init` - Initialize Project
+
+Create a new Visualify project with boilerplate files.
+
+```bash
+visualify init [path]
+```
+
+**Arguments:**
+- `path` - Project directory path (default: current directory)
+
+**Options:**
+- `-t, --template <name>` - Project template: `docs`, `portal`, or `full` (default: `docs`)
+- `-f, --force` - Overwrite existing files
+
+**Examples:**
+
+```bash
+# Initialize docs project in current directory
+visualify init
+
+# Create new portal project
+visualify init my-portal --template portal
+
+# Force overwrite existing project
+visualify init ./project --force
+```
+
+**Templates:**
+
+- `docs` - Documentation site with Docsify
+- `portal` - Data portal with spatial visualization
+- `full` - Full-featured project with both docs and portal
+
+### `edit` / `editor` - Visual Editor
+
+Launch the visual configuration editor for creating and editing charts.
+
+```bash
+visualify edit [file]
+```
+
+**Aliases:** `editor`
+
+**Arguments:**
+- `file` - Configuration file to edit (optional)
+
+**Options:**
+- `-p, --port <number>` - Editor server port (default: 3456)
+- `-h, --host <host>` - Host to bind to (default: `localhost`)
+- `--no-open` - Do not open browser automatically
+
+**Examples:**
+
+```bash
+# Start editor with new configuration
+visualify edit
+
+# Edit existing configuration file
+visualify edit ./my-chart.json
+
+# Start on custom port without opening browser
+visualify edit --port 8080 --no-open
+```
+
+## Configuration File
+
+Create a `visualify.json` or `.visualify.json` file to configure default options:
+
+```json
+{
+  "mode": "auto",
+  "port": 3000,
+  "host": "localhost",
+  "docs": {
+    "title": "My Documentation",
+    "theme": "vue"
+  },
+  "portal": {
+    "dataPath": "./data",
+    "rtreeEnabled": true
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mode` | string | `"auto"` | Default mode: `auto`, `docs`, `portal` |
+| `port` | number | `3000` | Default server port |
+| `host` | string | `"localhost"` | Default host |
+| `docs.title` | string | `"Documentation"` | Documentation site title |
+| `docs.theme` | string | `"vue"` | Docsify theme name |
+| `portal.dataPath` | string | `"./data"` | Path to data files |
+| `portal.rtreeEnabled` | boolean | `true` | Enable spatial indexing |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VISUALIFY_PORT` | Default port override |
+| `VISUALIFY_HOST` | Default host override |
+| `VISUALIFY_VERBOSE` | Enable verbose logging (set to `1` or `true`) |
+| `VISUALIFY_HMR` | Enable HMR (set to `1` or `true`) |
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# 1. Initialize new project
+visualify init my-project --template full
+cd my-project
+
+# 2. Start development server
+visualify dev
+
+# 3. Edit configuration visually
+visualify edit
+
+# 4. Build for production
+visualify docs build
+visualify portal build
+```
+
+### Legacy Commands
+
+The following legacy commands from `@visualify/cli` have been integrated into the unified CLI:
+
+| Legacy | New Equivalent | Notes |
+|--------|----------------|-------|
+| `serve` | `dev` or `docs serve` | Use `dev` for development |
+| `start` | `portal start` | Start production portal |
+| `load-json` | Portal data import | Use portal UI or API |
+| `mapping` | Portal configuration | Configure in `visualify.json` |
+| `rtree2d` | Automatic | Enabled by default in portal |
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Try a different port
+visualify dev --port 8080
+```
+
+### Permission Denied
+
+```bash
+# Fix npm permissions
+sudo chown -R $(whoami) ~/.npm
+
+# Or use npx without global install
+npx visualify dev
+```
+
+### Command Not Found
+
+```bash
+# Verify installation
+npm list -g visualify
+
+# Reinstall if needed
+npm install -g visualify
+```
+
+## Getting Help
+
+```bash
+# General help
+visualify --help
+
+# Command-specific help
+visualify dev --help
+visualify docs --help
+visualify portal --help
+visualify init --help
+visualify edit --help
+```