diff --git a/docs/README.md b/docs/README.md index a8750a9..5f10d70 100644 --- a/docs/README.md +++ b/docs/README.md @@ -81,11 +81,69 @@ You may have to install the required dependencies: > To launch without opening your browser, add the `--server` argument to your > command. +## Explorers + +Another key component of Pan3D is its modular, web-based 3D visualization system +built using trame. This system powers a suite of focused tools called Explorers, +designed to be modular, reusable, and easily extended. Each Explorer is built +around a specific task—think of them as "one-trick ponies" with clean interfaces +tailored to their purpose. This avoids the clutter and complexity of +general-purpose tools. + +Pan3D currently includes four Explorer tools: + +- **Slice Explorer** – Navigate through 3D datasets by extracting 2D slices + along any axis. Features interactive slice controls, dual 2D/3D view modes, + and the ability to visualize slices within their 3D context using transparency + and outlines. Perfect for exploring internal structures of volumetric data. + +- **Globe Explorer** – Visualize geographic data on a realistic 3D Earth. + Projects latitude/longitude data onto a spherical surface with various texture + options (satellite imagery, topography), continental outlines, and terrain + elevation effects. Includes specialized camera controls optimized for globe + navigation. + +- **Contour Explorer** – Generate smooth contour visualizations with + color-banded regions between isolevels. Creates both filled contour bands and + contour lines, with automatic surface refinement for publication-quality + results. Ideal for visualizing scalar fields and identifying data patterns + through isosurfaces. + +- **Analytics Explorer** – Combines interactive 3D visualization with + statistical analysis powered by xCDAT. Provides multiple plot types including + zonal averages, time series, and global statistics. Features a side panel with + Plotly charts that update based on your 3D data selection, enabling deep data + exploration through both visual and quantitative analysis + +### Launching the Explorers + +Similar to the main XArray Viewer (`xr-viewer`), each explorer can be launched +from the command line: + +```bash +# Launch Slice Explorer +xr-slicer + +# Launch Globe Explorer +xr-globe + +# Launch Contour Explorer +xr-contour + +# Launch Analytics Explorer +xr-analytics +``` + +Each explorer will automatically open your default browser to `localhost:8080`. +To launch without opening your browser, add the `--server` argument to any +command. + ## Tutorials - [How to use XArray Viewer](tutorials/dataset_viewer.md) - [XArray Viewer command line](tutorials/command_line.md) - [Catalogs Tutorial](tutorials/catalogs.md) +- [How to use Pan3D Explorers](tutorials/explorers.md) - [How to use Pan3D in a Jupyter notebook](tutorials/jupyter_notebook.md) ## Examples diff --git a/docs/images/AnalyticsExplorer.png b/docs/images/AnalyticsExplorer.png new file mode 100644 index 0000000..28b2658 --- /dev/null +++ b/docs/images/AnalyticsExplorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:09d83f77ca61588b11d215c76430a4b94227c6b09a858e2651c15c63ad6273a9 +size 1282545 diff --git a/docs/images/ContourExplorer.png b/docs/images/ContourExplorer.png new file mode 100644 index 0000000..b34fcfa --- /dev/null +++ b/docs/images/ContourExplorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ac6f60fe0fca259fb865445d32425c50faaf210001a5bee45640baea5c3917e6 +size 1947095 diff --git a/docs/images/GlobeExplorer.png b/docs/images/GlobeExplorer.png new file mode 100644 index 0000000..f3ddbaf --- /dev/null +++ b/docs/images/GlobeExplorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4392ed8f1ce5a53b11fe5fefc2c1b405e6f3d2b6fd29588b1e9c5640ec77e4f6 +size 1521059 diff --git a/docs/images/SliceExplorer.png b/docs/images/SliceExplorer.png new file mode 100644 index 0000000..4c31e7f --- /dev/null +++ b/docs/images/SliceExplorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:03c79e7e27b2601204775b8bf260dd7068a59c8b888cdfb741fb99246f0b3cf4 +size 1485996 diff --git a/docs/images/common.png b/docs/images/common.png new file mode 100644 index 0000000..03e6d8b --- /dev/null +++ b/docs/images/common.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:557d254e40481597f24fd3804d82577b2f3d08d9a88eae02df7d20a89b17f08f +size 55120 diff --git a/docs/tutorials/explorers.md b/docs/tutorials/explorers.md new file mode 100644 index 0000000..508cf4e --- /dev/null +++ b/docs/tutorials/explorers.md @@ -0,0 +1,175 @@ +# Pan3D Explorers Tutorial + +## Introduction + +Pan3D provides four specialized visualization tools called Explorers, each +designed for specific data exploration tasks. These focused tools offer clean, +intuitive interfaces tailored to their purpose, avoiding the complexity of +general-purpose visualization software. + +## Getting Started + +Install Pan3D with viewer capabilities: + +```bash +pip install "pan3d[viewer]" +``` + +Each explorer can be launched from the command line with optional data sources: + +```bash +# Launch with interactive data selection +xr-slicer +xr-globe +xr-contour +xr-analytics + +# Launch with specific data +xr-slicer --xarray-file ./data.nc +xr-globe --xarray-url https://example.com/data.zarr +xr-contour --import-state ./config.json +``` + +## Slice Explorer + +**Purpose**: Navigate through 3D volumes by extracting 2D slices along any axis. + +**Best for**: Atmospheric data, medical imaging, geological surveys, or any +volumetric dataset requiring cross-sectional analysis. + +![Slice Explorer](../images/SliceExplorer.png) + +**Key Features:** + +- **Axis Slicing**: Extract 2D slices along X, Y, or Z axes +- **View Modes**: 2D orthogonal or 3D perspective visualization +- **Volume Context**: Display outline and apply transparency to 3D data +- **Dynamic Updates**: Real-time slice rendering as position changes + +**Example Use Case**: Explore temperature layers in atmospheric data by slicing +along altitude to understand thermal stratification. + +**Launch Command**: `xr-slicer` + +## Globe Explorer + +**Purpose**: Visualize geographic data on a realistic 3D Earth with accurate +projection. + +**Best for**: Climate data, oceanographic measurements, satellite observations, +or any dataset with latitude/longitude coordinates. + +![Globe Explorer](../images/GlobeExplorer.png) + +**Key Features:** + +- **Texture Options**: Satellite imagery, topography, political boundaries +- **Continental Outlines**: Overlay continent boundaries on data +- **Terrain Elevation**: Apply bump mapping for topographic effects +- **Sphere Projection**: Map latitude/longitude data to 3D globe + +**Example Use Case**: Visualize global temperature anomalies with continental +context to identify regional climate patterns. + +**Launch Command**: `xr-globe` + +## Contour Explorer + +**Purpose**: Create smooth contour visualizations with color-banded regions +between isolevels. + +**Best for**: Scalar fields, topographic data, gradient analysis, or any dataset +requiring isoline visualization. + +![Contour Explorer](../images/ContourExplorer.png) + +**Key Features:** + +- **Banded Regions**: Generate filled areas between contour levels +- **Contour Lines**: Overlay black isolines on banded regions +- **Level Control**: Set number and range of contour values +- **Surface Smoothing**: Apply loop subdivision for refined contours + +**Example Use Case**: Analyze ocean temperature at specific depths to identify +thermoclines and current patterns. + +**Launch Command**: `xr-contour` + +## Analytics Explorer + +**Purpose**: Combine 3D visualization with statistical analysis for +comprehensive data exploration. + +**Best for**: Time series analysis, spatial statistics, trend detection, or any +dataset requiring both visual and quantitative insights. + +![Analytics Explorer](../images/AnalyticsExplorer.png) + +**Key Features:** + +- **Statistical Plots**: Zonal, temporal, and global analysis charts +- **Temporal Grouping**: Aggregate data by year, month, day, or hour +- **xCDAT Integration**: Leverage climate analysis algorithms +- **Data Synchronization**: 3D view and plots update together + +**Example Use Case**: Analyze seasonal temperature patterns by combining 3D +visualization with monthly statistical plots. + +**Launch Command**: `xr-analytics` + +## Common Features + +All explorers share these capabilities: + +### Data Management + +- Load from files, URLs, or configuration states +- Support for xarray-compatible formats +- State export/import for reproducibility + +### Visualization Controls + +![Common Controls](../images/common.png) + +- **Time Navigation**: Slider, play/pause, step controls for temporal data +- **Color Mapping**: Presets, custom ranges, interactive scalar bar +- **Scale Controls**: Independent X/Y/Z scaling for different unit scales + +### Performance Tips + +- Use data stepping/striding for large datasets +- Crop to regions of interest +- Start with lower resolution, increase as needed + +## Choosing the Right Explorer + +| Explorer | Best For | +| ------------- | -------------------------------------------------------- | +| **Slice** | Volumetric data, internal structures, cross-sections | +| **Globe** | Geographic data, global patterns, Earth visualization | +| **Contour** | Value ranges, smooth gradients, publication figures | +| **Analytics** | Statistical analysis, time series, quantitative insights | + +## Integration Example + +Use explorers in Jupyter notebooks: + +```python +from pan3d.explorers.slicer import SliceExplorer + +# Create and display explorer +explorer = SliceExplorer() +await explorer.ui.ready + +# Launch the interactive explorer within jypyter notebook +explorer.ui + +# Export configuration +config = explorer.export_state() +``` + +## Additional Resources + +- [Configuration API Documentation](../api/configuration.md) +- [Jupyter Integration Tutorial](jupyter_notebook.md) +- [Command Line Reference](command_line.md)