Add mesh 3d

docs/api-reference/index.md

@@ -8,10 +8,11 @@
 .. autosummary::
    :toctree: ../generated
 
+   inspector
+   mesh3d
    plot
    slicer
    superplot
-   inspector
    scatter
    scatter3d
    xyplot
@@ -26,8 +27,8 @@
    core.Node
    core.View
    core.node
-   core.widget_node
    core.show_graph
+   core.widget_node
 ```
 
 ## Graphics
@@ -41,6 +42,7 @@
    graphics.ColorMapper
    graphics.imagefigure
    graphics.linefigure
+   graphics.mesh3dfigure
    graphics.scatterfigure
    graphics.scatter3dfigure
    graphics.tiled

docs/api-reference/pythreejs.md

@@ -10,4 +10,5 @@
    backends.pythreejs.figure.Figure
    backends.pythreejs.outline.Outline
    backends.pythreejs.scatter3d.Scatter3d
+   backends.pythreejs.mesh3d.Mesh3d
 ```

docs/user-guide/index.md

@@ -2,7 +2,7 @@
 
 ## Getting started
 
-::::{grid} 3
+::::{grid} 2
 
 :::{grid-item-card} {octicon}`desktop-download;1em`  Installation
 :link: getting-started/installation.md
@@ -14,15 +14,15 @@
 
 :::
 
+::::
+
+::::{grid} 2
+
 :::{grid-item-card} {octicon}`graph;1em`  Numpy, Pandas, and Xarray
 :link: getting-started/numpy-pandas-xarray.ipynb
 
 :::
 
-::::
-
-::::{grid} 3
-
 :::{grid-item-card} {octicon}`download;1em`  Saving figures to disk
 :link: plot-types/saving-figures.ipynb
 
@@ -95,6 +95,12 @@ getting-started/saving-figures
 
 :::
 
+:::{grid-item-card} Mesh 3D plot
+:link: plot-types/mesh3d-plot.ipynb
+:img-bottom: ../_static/plot-types/mesh3d-plot.png
+
+:::
+
 ::::
 
 ```{toctree}
@@ -109,6 +115,7 @@ plot-types/inspector-plot
 plot-types/super-plot
 plot-types/scatter-plot
 plot-types/scatter3d-plot
+plot-types/mesh3d-plot
 ```
 
 ## Custom figures

docs/user-guide/plot-types/mesh3d-plot.ipynb

@@ -0,0 +1,189 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# 3D mesh plot\n",
+    "\n",
+    "This notebook illustrates how to render 3D meshes\n",
+    "by supplying a list of vertex positions and vertex indices to construct the mesh faces."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import scipp as sc\n",
+    "import plopp as pp\n",
+    "from plopp.data import examples"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Loading mesh data\n",
+    "\n",
+    "We load a file containing the data to construct the [Utah teapot](https://en.wikipedia.org/wiki/Utah_teapot)\n",
+    "(see below for a description of the data format)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dg = sc.io.load_hdf5(examples.teapot())\n",
+    "dg"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## Creating a mesh plot\n",
+    "\n",
+    "We can now send the data to the [`mesh3d`](../../generated/plopp.mesh3d.html) function for rendering (we color the mesh according to z position):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pp.mesh3d(\n",
+    "    vertices=dg[\"vertices\"],\n",
+    "    faces=dg[\"faces\"],\n",
+    "    vertexcolors=dg[\"vertices\"].fields.z,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Adding mesh edges\n",
+    "\n",
+    "It is also possible to show the edges of the mesh using the `edgecolor` argument:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pp.mesh3d(\n",
+    "    vertices=dg[\"vertices\"],\n",
+    "    faces=dg[\"faces\"],\n",
+    "    vertexcolors=dg[\"vertices\"].fields.z,\n",
+    "    edgecolor=\"black\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## The data format\n",
+    "\n",
+    "The data used above contains a list of `vertices` (position vectors in 3d space),\n",
+    "and a list of `faces` which define how the vertices are connected to each other.\n",
+    "\n",
+    "The faces is a flat list of sequences of 3 indices that code for vertices which make up mesh triangles.\n",
+    "\n",
+    "As an example, we will construct a simple tetrahedric mesh."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "vertices = sc.vectors(\n",
+    "    dims=[\"vertices\"],\n",
+    "    values=[[-1, 0, 0], [0.7, 0, 1], [0.7, 0, -1], [0, 1.3, 0]],\n",
+    "    unit=\"m\",\n",
+    ")\n",
+    "faces = sc.array(\n",
+    "    dims=[\"faces\"],\n",
+    "    values=[\n",
+    "        # First triangle\n",
+    "        0, 1, 3,\n",
+    "        # Second triangle\n",
+    "        1, 2, 3,\n",
+    "        # Third triangle\n",
+    "        2, 0, 3,\n",
+    "        # Fourth triangle\n",
+    "        0, 2, 1,\n",
+    "    ],\n",
+    ")\n",
+    "\n",
+    "pp.mesh3d(\n",
+    "    vertices=vertices,\n",
+    "    faces=faces,\n",
+    "    edgecolor=\"black\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "You can then also add colors on the vertices:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pp.mesh3d(\n",
+    "    vertices=vertices,\n",
+    "    faces=faces,\n",
+    "    vertexcolors=vertices.fields.x,\n",
+    "    edgecolor=\"black\",\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -40,12 +40,14 @@ scipp = ["scipp"]
 all = ["scipp", "ipympl", "pythreejs", "mpltoolbox", "ipywidgets", "graphviz"]
 test = [
     "graphviz",
+    "h5py",
     "ipympl",
     "ipywidgets",
     "kaleido",
     "mpltoolbox",
     "pandas",
     "plotly",
+    "pooch",
     "pyarrow",
     "pytest",
     "pythreejs",

requirements/basetest.in

@@ -8,12 +8,14 @@
 # --- END OF CUSTOM SECTION ---
 # The following was generated by 'tox -e deps', DO NOT EDIT MANUALLY!
 graphviz
+h5py
 ipympl
 ipywidgets
 kaleido
 mpltoolbox
 pandas
 plotly
+pooch
 pyarrow
 pytest
 pythreejs