{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4182dcd6",
   "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",
    "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": "ae81c166",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "nbsphinx": "hidden",
    "tags": []
   },
   "outputs": [],
   "source": [
    "# download the example file for this tutorial\n",
    "\n",
    "from util import download_tutorial_input_file\n",
    "\n",
    "download_tutorial_input_file(print_status=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36c514ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "from weldx import WeldxFile"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3ec375b",
   "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": "630bd97c",
   "metadata": {},
   "outputs": [],
   "source": [
    "wxfile = WeldxFile(\"single_pass_weld.wx\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d183782",
   "metadata": {},
   "source": [
    "### Inspecting the file content in a Jupyter session\n",
    "\n",
    "If you are running a jupyter notebook, you can use the `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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d7ac29d4",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# wxfile.header()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "988d0409",
   "metadata": {},
   "source": [
    "### Inspecting the File content with pure Python\n",
    "\n",
    "You can also utilize the `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": "9863459a",
   "metadata": {},
   "outputs": [],
   "source": [
    "wxfile.info()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85eb6e37",
   "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": "b5d960ec",
   "metadata": {},
   "outputs": [],
   "source": [
    "groove = wxfile[\"workpiece\"][\"geometry\"][\"groove_shape\"]\n",
    "print(type(groove))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84a697ce",
   "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": "078d2b27",
   "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.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}