1. Introduction / Opening WelDX Files#

1.1. Introduction#

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. 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. In this tutorial series, we will only focus on reading from already existing files. How to write and modify a WelDX file will be covered in a follow up-series.

Note that we will only cover the most common features and not all possible tools the weldx package provides. For more in-depth information, read the dedicated API tutorials or have a look at the API documentation page.

1.2. Jupyter notebooks and online documentation#

All tutorials are written as jupyter notebooks so that you can always run and test the code on your local machine. You can find them in the tutorials subdirectory of our GitHub repository. To learn how to install the weldx package and all required dependencies to run the tutorials, visit the installation guide page of our online documentation.

All tutorials are also contained on the “Getting Started” page of the online documentation so that you can read a nicely rendered version online.

However, we strongly recommend to run and read the tutorials in a running jupyter-lab session. Some features like interactive plots can only be displayed correctly by a jupyter server. 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. This will start a virtual machine with everything set up correctly that you can access through your browser.

1.3. Opening and navigating through WelDX Files#

1.3.1. Opening a WelDX File#

The first lesson we will learn is how to open a WelDX file and to get an overview of its content. Opening a file using the weldx package is rather simple. First we import the WeldxFile class from weldx:

# download the example file for this tutorial

from util import download_tutorial_input_file

download_tutorial_input_file(print_status=False)

from weldx import WeldxFile

WelDX files usually have the extension .weldx or .wx, but any other is also possible as long as the content is valid. For the purpose of this tutorial series, we will deal with a single file called single_pass_weld.wx. To open it, simply create a new instance of the WeldxFile class and pass the file path to it:

wxfile = WeldxFile("single_pass_weld.wx")

/home/docs/checkouts/readthedocs.org/user_builds/weldx/conda/latest/lib/python3.9/site-packages/asdf/asdf.py:336: AsdfWarning: File 'file:///home/docs/checkouts/readthedocs.org/user_builds/weldx/checkouts/latest/doc/src/tutorials/single_pass_weld.wx' was created with extension URI 'asdf://weldx.bam.de/weldx/extensions/weldx-0.1.1' (from package weldx==0.6.0), which is not currently installed
  warnings.warn(msg, AsdfWarning)

1.3.2. Inspecting the file content in a Jupyter session#

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. The output might vary if you are running the classic notebook environment or a Jupyter-Lab environment. In the latter case, you will get an interactive, clickable tree view to navigate through the file content. Uncomment the code in the next cell to try it out:

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

# wxfile.header()

1.3.3. Inspecting the File content with pure Python#

You can also utilize the header method to visualize the file content when using weldx in a pure Python script. This will print the human-readable part of the file that is stored in YAML format directly to console. However, while the interactive output in a jupyter notebook is quite handy, the console output can get pretty large. This might be simply too much information if you just want to get a simple overview of the file content.

Alternatively, we can get a quick overview over the top level items of the file structure by using the info method:

wxfile.info()

root (dict)
├─TCP (LocalCoordinateSystem)
├─coordinate_systems (CoordinateSystemManager)
├─equipment (list)
│ ├─[0] (MeasurementEquipment)
│ ├─[1] (MeasurementEquipment)
│ └─[2] (MeasurementEquipment)
├─measurements (list)
│ ├─[0] (Measurement)
│ ├─[1] (Measurement)
│ ├─[2] (Measurement)
│ └─[3] (Measurement)
├─process (dict)
│ ├─shielding_gas (ShieldingGasForProcedure)
│ ├─weld_speed (TimeSeries)
│ ├─welding_process (GmawProcess)
│ └─welding_wire (dict)
│   ├─class (str)
│   ├─diameter (Quantity)
│   └─wx_user (dict)
│     ├─charge id (str)
│     └─manufacturer (str)
├─reference_timestamp (Timestamp)
├─welding_current (TimeSeries)
├─welding_voltage (TimeSeries)
├─workpiece (dict)
│ ├─base_metal (dict)
│ │ ├─common_name (str)
│ │ └─standard (str)
│ └─geometry (dict)
│   ├─groove_shape (VGroove)
│   └─seam_length (Quantity)
└─wx_user (dict)
  ├─WID (int)
  ├─operator (str)
  └─project (str)

The info method lists the internal file structure converted to python objects. 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. For example, we can see that the item groove_shape is an VGroove object, that we can access as follows:

groove = wxfile["workpiece"]["geometry"]["groove_shape"]
print(type(groove))

<class 'weldx.welding.groove.iso_9692_1.VGroove'>

The output confirms that the object we got is truly of type VGroove. 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.

1.4. Conclusion#

This concludes the first tutorial about opening and navigating through WelDX Files. You should now be able to read any given WelDX file and to inspect its structure. In the next tutorials, we will learn how to access the actual data and what we can do with it.

NEXT TUTORIAL >>