Metadata-Version: 2.4
Name: pan3d
Version: 1.1.10
Summary: Utility package for processing and visualizing 3D datasets
Author: Kitware Inc.
License: Apache Software License
License-File: LICENSE
Keywords: Application,Framework,Interactive,Python,Web
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: aiohttp
Requires-Dist: requests>=2.31
Requires-Dist: vtk>=9.4.2
Requires-Dist: xarray[io,parallel]>=2023.8
Provides-Extra: all
Requires-Dist: gcsfs>=2024.2; extra == 'all'
Requires-Dist: intake-esgf>=2024.1; extra == 'all'
Requires-Dist: intake-esm>=2023.11; extra == 'all'
Requires-Dist: intake-xarray>=0.7; extra == 'all'
Requires-Dist: intake==0.7.0; extra == 'all'
Requires-Dist: s3fs>=2024.2; extra == 'all'
Requires-Dist: trame-client>=3.9.1; extra == 'all'
Requires-Dist: trame-plotly>=3.1.0; extra == 'all'
Requires-Dist: trame-vtk>=2.8.15; extra == 'all'
Requires-Dist: trame-vtklocal>=0.12.2; extra == 'all'
Requires-Dist: trame-vuetify>=3.0.1; extra == 'all'
Requires-Dist: trame>=3.9; extra == 'all'
Requires-Dist: zarr<3; extra == 'all'
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest>=6; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: esgf
Requires-Dist: intake-esgf>=2024.1; extra == 'esgf'
Provides-Extra: pangeo
Requires-Dist: gcsfs>=2024.2; extra == 'pangeo'
Requires-Dist: intake-esm>=2023.11; extra == 'pangeo'
Requires-Dist: intake-xarray>=0.7; extra == 'pangeo'
Requires-Dist: intake==0.7.0; extra == 'pangeo'
Requires-Dist: s3fs>=2024.2; extra == 'pangeo'
Requires-Dist: zarr<3; extra == 'pangeo'
Provides-Extra: viewer
Requires-Dist: trame-client>=3.9.1; extra == 'viewer'
Requires-Dist: trame-plotly>=3.1.0; extra == 'viewer'
Requires-Dist: trame-vtk>=2.8.15; extra == 'viewer'
Requires-Dist: trame-vtklocal>=0.12.2; extra == 'viewer'
Requires-Dist: trame-vuetify>=3.0.1; extra == 'viewer'
Requires-Dist: trame>=3.9; extra == 'viewer'
Description-Content-Type: text/markdown

# Pan3D

<img style="display: inline-block;" src="https://media.githubusercontent.com/media/Kitware/pan3d/main/docs/images/kitware.svg" alt="Kitware Logo" href="https://kitware.com" width="100">

[![Documentation Status][docs-image]][docs-link]
[![Binder][binder-image]][binder-link]
[![Build Status][GHAction-image]][GHAction-link]
[![PyPI Version][pypi-v-image]][pypi-v-link]
[![License][apache-license-image]][license-link]

Pan3D aims to be an utility package for viewing and processing a wide variety of
multidimensional datasets. Any dataset that can be interpreted with
[xarray][xarray-link] can be explored and rendered with Pan3D. [Read The
Doc][docs-link] is available for additional information.

XArray Viewer is a Pan3D application focused on geospatial rendering use cases.
This is a graphical user interface leveraging the Pan3D infrastructure to help
geospatial scientists explore data.

![](images/xr-viewer-esgf-00.jpg)

For an introduction to this project, check out our [blog post][blog-post-link].

## Installation

To install requirements for the Pan3D VTK mesh builder class only:

    pip install pan3d

To install requirements for the graphical user interface (viewers + explorers):

    pip install "pan3d[viewer]"

**Optional**: to install requirements for Pangeo and ESGF catalogs,
respectively:

    pip install "pan3d[pangeo]"

    pip install "pan3d[esgf]"

**Recommended**: To install all requirements, including optional packages:

    pip install "pan3d[all]"

## Quick Start

`xr-viewer` is the main entrypoint for launching XArray Viewer locally. Below
are some example usages.

To launch XArray Viewer without a target dataset to browse XArray examples:

    xr-viewer

To launch XArray Viewer with a local path to a target dataset:

    xr-viewer --xarray-file ./examples/example_dataset.nc

To launch XArray Viewer with a remote URL to a target dataset:

    xr-viewer --xarray-url https://host.org/link/to/dataset.zarr

To launch XArray Viewer with a compatible configuration file (see
[examples][examples-link]):

    xr-viewer --import-state ./examples/example_config_xarray.json

To launch the Catalog browser will allow you to query the Pangeo and ESGF
Dataset Catalogs (see [Catalogs Tutorial](tutorials/catalogs.md)) depending on
the available dependencies:

    xr-catalog

You may have to install the required dependencies:

    pip install "pan3d[pangeo]"
    pip install "pan3d[esgf]"

> The `xr-viewer` entrypoint will automatically launch your default browser to
> open `localhost:8080`.
>
> 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

Pan3D comes with a set of example configuration files and example Jupyter
notebooks in the [examples][examples-link] folder. You can checkout the
repository to run these locally, or you can use the [Pan3D Binder
instance][binder-link] to run these examples.

<!-- Links -->

[docs-image]: https://readthedocs.org/projects/pan3d/badge/?version=latest
[docs-link]: https://pan3d.readthedocs.io/en/latest
[binder-image]: https://mybinder.org/badge_logo.svg
[binder-link]:
  https://mybinder.org/v2/gh/Kitware/pan3d/main?labpath=examples%2Fjupyter
[GHAction-image]: https://github.com/Kitware/pan3d/workflows/Test/badge.svg
[GHAction-link]:
  https://github.com/Kitware/pan3d/actions?query=event%3Apush+branch%3Amain
[pypi-v-image]: https://img.shields.io/pypi/v/pan3d.svg
[pypi-v-link]: https://pypi.org/project/pan3d/
[apache-license-image]: https://img.shields.io/badge/license-Apache%202-blue.svg
[license-link]: https://raw.githubusercontent.com/Kitware/pan3d/main/LICENSE
[xarray-link]: https://docs.xarray.dev/en/stable/user-guide/io.html
[blog-post-link]:
  https://www.kitware.com/kitware-introduces-pan3d-a-collaborative-interoperable-visualization-tool/
[examples-link]: https://github.com/Kitware/pan3d/tree/main/examples
