From 32a2dd85cf98987499e643eb6abf2c81a256fa21 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Thu, 19 Sep 2024 09:46:20 +0200
Subject: [PATCH] describe data format in notebook

---
 docs/user-guide/plot-types/mesh3d-plot.ipynb | 78 +++++++++++++++++++-
 1 file changed, 75 insertions(+), 3 deletions(-)

diff --git a/docs/user-guide/plot-types/mesh3d-plot.ipynb b/docs/user-guide/plot-types/mesh3d-plot.ipynb
index 08a837d1..71538bfb 100644
--- a/docs/user-guide/plot-types/mesh3d-plot.ipynb
+++ b/docs/user-guide/plot-types/mesh3d-plot.ipynb
@@ -30,7 +30,8 @@
    "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)."
+    "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)."
    ]
   },
   {
@@ -51,7 +52,7 @@
    "source": [
     "## Creating a mesh plot\n",
     "\n",
-    "We can now send the data to the `mesh3d` function for rendering (we color the mesh according to z position):"
+    "We can now send the data to the [`mesh3d`](../../generated/plopp.mesh3d.html) function for rendering (we color the mesh according to z position):"
    ]
   },
   {
@@ -89,7 +90,78 @@
     "    vertices=dg[\"vertices\"],\n",
     "    faces=dg[\"faces\"],\n",
     "    vertexcolors=dg[\"vertices\"].fields.z,\n",
-    "    edgecolor='black',\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",
     ")"
    ]
   }