New tutorials

CHANGELOG.rst

@@ -198,6 +198,9 @@ added
 
 -  added support for parsing temperature deltas with ``Δ°`` notation
    `[#565] <https://github.com/BAMWelDX/weldx/pull/565>`__.
+-  new tutorial series that introduces the most important WelDX features
+   step by step based on a full example file
+   `[#555] <https://github.com/BAMWelDX/weldx/pull/555>`__.
 
 -  `WeldxFile.info` to print a quick content overview to the stdout.
    `[#576] <https://github.com/BAMWelDX/weldx/pull/576>`__.

doc/conf.py

@@ -20,6 +20,10 @@
 import sys
 import typing
 
+from sphinx.util.logging import getLogger
+
+logger = getLogger("weldx_sphinx_conf")
+
 
 def _workaround_imports_typechecking():
     """Load some packages needed for type annotations."""
@@ -52,13 +56,71 @@ def _prevent_sphinx_circular_imports_bug():
 
 import weldx.visualization  # load visualization (currently no auto-import in pkg).
 
+tutorials_dir = (pathlib.Path(__file__).parent / "./tutorials").absolute()
+
+
 # -- copy tutorial files to doc folder -------------------------------------------------
-tutorials_dir = pathlib.Path("./tutorials")
+def _copy_tut_files():
+    # TODO: git move tutorial files to tutorials_dir, then delete this function
+    logger.info("tutorials dir: %s", tutorials_dir)
+    _exts = ("*.ipynb", "*.py")
+    tutorial_files = []
+    for ext in _exts:
+        tutorial_files.extend(pathlib.Path("./../tutorials/").glob(ext))
+    for f in tutorial_files:
+        shutil.copy(f, tutorials_dir)
+
+
+_copy_tut_files()
+
+
+tutorials_dir = (pathlib.Path(__file__).parent / "./tutorials").absolute()
+logger.info("tutorials dir: %s", tutorials_dir)
+# TODO: git move tutorial files to tutorials_dir!
 tutorial_files = pathlib.Path("./../tutorials/").glob("*.ipynb")
 for f in tutorial_files:
     shutil.copy(f, tutorials_dir)
 
 
+def download_tutorial_input_file():
+    from urllib.request import urlretrieve
+
+    url = "https://github.com/BAMWelDX/IIW2021_AA_CXII/blob/weldx_0.5.0/single_pass_weld.weldx?raw=true"
+    sha256sum = "29e4f11ef1185f818b4611860842ef52d386ad2866a2680257950f160e1e098a"
+
+    def hash_path(path):
+        import hashlib
+
+        h = hashlib.sha256()
+        with open(path, "rb") as fh:
+            h.update(fh.read())
+        return h.hexdigest()
+
+    dest = tutorials_dir / "single_pass_weld.wx"
+
+    # check if existing files matches desired one.
+    if dest.exists():
+        hash_local = hash_path(dest)
+        if hash_local == sha256sum:
+            logger.info(f"File %s already downloaded.", dest)
+            return
+
+    # does not exist or hash mismatched, so download it.
+    logger.info("trying to download: %s", url)
+    out_file, header = urlretrieve(url, dest)
+    sha256sum_actual = hash_path(out_file)
+    if not sha256sum_actual == sha256sum:
+        raise RuntimeError(
+            f"hash mismatch:\n actual = \t{sha256sum_actual}\n"
+            f"desired = \t{sha256sum}"
+        )
+
+    logger.info("download successful.")
+
+
+download_tutorial_input_file()
+
+
 # -- Project information -----------------------------------------------------
 _now = datetime.datetime.now().year
 

doc/tutorials.rst

@@ -2,6 +2,24 @@
  Getting Started
 #################
 
+************************
+Working with WelDX files
+************************
+
+This tutorial series teaches you step by step how to access the data
+stored inside of an existing WelDX file. Furthermore, it demonstrates
+the main features of the `weldx` Python package that help you with
+data processing and visualization.
+
+.. toctree::
+   :numbered:
+   :maxdepth: 1
+   :caption: Welding examples
+
+   tutorials/01_01_introduction
+   tutorials/01_02_time_dependent_data
+
+
 ******************
  Welding Examples
 ******************

tutorials/.gitignore

@@ -1 +1,2 @@
 example.asdf
+*.weldx

tutorials/01_01_introduction.ipynb

@@ -0,0 +1,214 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "ccc0d43e",
+   "metadata": {},
+   "source": [
+    "# Introduction / Opening WelDX Files\n",
+    "\n",
+    "[NEXT TUTORIAL >>](01_02_time_dependent_data.ipynb)\n",
+    "\n",
+    "## Introduction\n",
+    "\n",
+    "This tutorial is the first one of a whole series that has the purpose to teach you how to work with WelDX files using the `weldx` Python package.\n",
+    "In each tutorial, we will focus on a small feature set and learn step by step how you can find, extract and process data stored in a WelDX file.\n",
+    "In this tutorial series, we will only focus on reading from already existing files.\n",
+    "How to write and modify a WelDX file will be covered in a follow up-series.\n",
+    "\n",
+    "Note that we will only cover the most common features and not all possible tools the `weldx` package provides.\n",
+    "For more in-depth information, read the dedicated API tutorials or have a look at the [API documentation](https://weldx.readthedocs.io/en/latest/api.html) page.\n",
+    "\n",
+    "## Jupyter notebooks and online documentation\n",
+    "\n",
+    "All tutorials are written as jupyter notebooks so that you can always run and test the code on your local machine.\n",
+    "You can find them in the `tutorials` subdirectory of [our GitHub repository](https://github.com/BAMWelDX/weldx).\n",
+    "To learn how to install the `weldx` package and all required dependencies to run the tutorials, visit the [installation guide](https://weldx.readthedocs.io/en/latest/install.html) page of our [online documentation](https://weldx.readthedocs.io/en/latest/index.html).\n",
+    "\n",
+    "All tutorials are also contained on the [\"Getting Started\"](https://weldx.readthedocs.io/en/latest/tutorials.html) page of the [online documentation](https://weldx.readthedocs.io/en/latest/index.html) so that you can read a nicely rendered version online.\n",
+    "\n",
+    "However, we strongly recommend to run and read the tutorials in a running jupyter-lab session.\n",
+    "Some features like interactive plots can only be displayed correctly by a jupyter server.\n",
+    "In case you don't have the `weldx` package or jupyter-lab installed yet but want to test the tutorial code, you can click on the binder link button that can be found at the top of each tutorial in the online version of the documentation.\n",
+    "This will start a virtual machine with everything set up correctly that you can access through your browser.\n",
+    "\n",
+    "## Opening and navigating through WelDX Files\n",
+    "\n",
+    "### Opening a WelDX File\n",
+    "\n",
+    "The first lesson we will learn is how to open a WelDX file and to get an overview of its content.\n",
+    "Opening a file using the `weldx` package is rather simple.\n",
+    "First we import the `WeldxFile` class from weldx:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cef1473c",
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    },
+    "tags": [
+     "hide-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import util\n",
+    "\n",
+    "util.download_tutorial_input_file()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1998289e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from weldx import WeldxFile"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d2512d5",
+   "metadata": {},
+   "source": [
+    "WelDX files usually have the extension `.weldx` or `.wx`, but any other is also possible as long as the content is valid.\n",
+    "For the purpose of this tutorial series, we will deal with a single file called `single_pass_weld.wx`.\n",
+    "To open it, simply create a new instance of the `WeldxFile` class and pass the file path to it:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d5d15d00",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "wxfile = WeldxFile(\"single_pass_weld.wx\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e2149464",
+   "metadata": {},
+   "source": [
+    "### Inspecting the file content in a Jupyter session\n",
+    "\n",
+    "If you are running a jupyter notebook, you can use the `show_asdf_header` method of `WeldxFile` to get a nicely rendered overview of the file content. \n",
+    "The output might vary if you are running the classic notebook environment or a Jupyter-Lab environment.\n",
+    "In the latter case, you will get an interactive, clickable tree view to navigate through the file content.\n",
+    "Uncomment the code in the next cell to try it out:\n",
+    "\n",
+    "> HINT: Remember that you can start a jupyter-lab version of this notebook in our online documentation by clicking at the binder link at the start of this tutorial"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "02fd01f3",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "# wxfile.show_asdf_header()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "eb01080d",
+   "metadata": {},
+   "source": [
+    "### Inspecting the File content with pure Python\n",
+    "\n",
+    "You can also utilize the `show_asdf_header` method to visualize the file content when using weldx in a pure Python script.\n",
+    "This will print the human-readable part of the file that is stored in [YAML format](https://yaml.org/) directly to console.\n",
+    "However, while the interactive output in a jupyter notebook is quite handy, the console output can get pretty large.\n",
+    "This might be simply too much information if you just want to get a simple overview of the file content.\n",
+    "\n",
+    "Alternatively, we can get a quick overview over the top level items of the file structure by using the `info` method:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aea068a2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "wxfile.info()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7d67f644",
+   "metadata": {},
+   "source": [
+    "The `info` method lists the internal file structure converted to python objects.\n",
+    "This makes it easy to identify where we find a specific piece of information, how to access it and which object type we can expect.\n",
+    "For example, we can see that the item `groove_shape` is an `VGroove` object, that we can access as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "203c0c09",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "groove = wxfile[\"workpiece\"][\"geometry\"][\"groove_shape\"]\n",
+    "print(type(groove))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1f46a1f4",
+   "metadata": {},
+   "source": [
+    "The output confirms that the object we got is truly of type `VGroove`.\n",
+    "We will discuss in more detail in the upcoming tutorials, what you can do with the individual objects that you may find in a `WeldxFile`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1ad993d7",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "This concludes the first tutorial about opening and navigating through WelDX Files.\n",
+    "You should now be able to read any given WelDX file and to inspect its structure.\n",
+    "In the next tutorials, we will learn how to access the actual data and what we can do with it.\n",
+    "\n",
+    "[NEXT TUTORIAL >>](01_02_time_dependent_data.ipynb)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "",
+   "language": "python",
+   "name": ""
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}