{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3D Geometries\n",
    "\n",
    "## Introduction\n",
    "\n",
    "In this tutorial we will describe how to create 3 dimensional structures that are based on one or more 2d profiles.\n",
    "We assume that you already know how to create 2d profiles using the `weldx` package.\n",
    "If this is not the case, please read the corresponding tutorial first.\n",
    "\n",
    "You will learn:\n",
    "\n",
    "- about the `Trace` class\n",
    "- how to define a 3 dimensional geometry using the `Geometry` class\n",
    "- how to specify geometries with varying cross sections using the `VariableProfile` class\n",
    "\n",
    "Before we start, run the following code cells to include everything we need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from mpl_toolkits.mplot3d import Axes3D  # noqa: F401 unused import\n",
    "\n",
    "import weldx.transformations as tf\n",
    "from weldx import Q_\n",
    "from weldx.geometry import (\n",
    "    Geometry,\n",
    "    LinearHorizontalTraceSegment,\n",
    "    Profile,\n",
    "    RadialHorizontalTraceSegment,\n",
    "    Shape,\n",
    "    Trace,\n",
    "    VariableProfile,\n",
    "    linear_profile_interpolation_sbs,\n",
    ")\n",
    "from weldx.transformations import LocalCoordinateSystem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Trace\n",
    "\n",
    "The `Trace` class describes an arbitrary path through the 3 dimensional space.\n",
    "It is build from multiple segments that need to be passed to it when we create the `Trace`.\n",
    "Currently there are 2 segment types available: the `LinearHorizontalTraceSegment` that represents a straight line and\n",
    "the `RadialHorizontalTraceSegment` which describes a circular path.\n",
    "Both segment types have in common that the `z`-value remains constant and that they are free from torsion.\n",
    "\n",
    "Let's create one instance of each segment type.\n",
    "All you need to specify when creating a `LinearHorizontalTraceSegment` is its length:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "line_segment = LinearHorizontalTraceSegment(length=Q_(10, \"cm\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it.\n",
    "The `RadialHorizontalTraceSegment` needs a little bit more information.\n",
    "You need to provide its radius, rotation angle and if the rotation is clockwise or counter-clockwise:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "arc_segment = RadialHorizontalTraceSegment(\n",
    "    radius=Q_(15, \"cm\"), angle=Q_(90, \"degree\"), clockwise=True\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have some segments, we can create a `Trace`.\n",
    "It expects a single segment or a list of segments as first argument.\n",
    "The individual segments get attached to each other in the same order as they are attached to the list.\n",
    "Each segment except for the first one gets its start orientation and coordinates from the end of the previous segment.\n",
    "The initial orientation and coordinates of the `Trace` can be provided in form of a `LocalCoordinateSystem` as optional\n",
    "second argument during the creation of the class instance.\n",
    "If you omit the second parameter, the `Trace` starts at the origin and is oriented in positive x-direction.\n",
    "\n",
    "\n",
    "Here is an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "trace = Trace([line_segment, arc_segment, line_segment])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can plot our `Trace` using the `plot` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "trace.plot(raster_width=Q_(2, \"cm\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's provide a initial coordinate system that is rotated by 45 degrees around the y-axis and see how that affects the\n",
    "result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "lcs_rot = LocalCoordinateSystem(\n",
    "    tf.WXRotation.from_euler(\"y\", Q_(45, \"degree\")).as_matrix()\n",
    ")\n",
    "trace_rot = Trace([line_segment, arc_segment, line_segment], lcs_rot)\n",
    "trace_rot.plot(raster_width=Q_(2, \"cm\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Linear and radial trace segments already cover a lot of use cases but they are far from being enough to cover all\n",
    "possible needs.\n",
    "If you need more than those two basic segment types, there are two options.\n",
    "The first one is to implement your own segment type.\n",
    "This is discussed in detail in another tutorial.\n",
    "> TODO: Add link to tutorial once it is written\n",
    "\n",
    "The second option, that you should prefer is the `TODO: SOME_FANCY_NAME_SEGMENT`.\n",
    "It enables you to describe the course of the trace segment with a mathematical function.\n",
    "> TODO: Continue once the segment type is implemented"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Describing a 3d geometry\n",
    "\n",
    "The simplest possible way to describe a 3 dimensional geometry using the `weldx.geometry` package is to create a 2d\n",
    "`Profile` and extrude it into 3d.\n",
    "The class that performs this action is called `Geometry`.\n",
    "It expects a `Profile` that defines the cross section as first argument and a `Trace` that describes\n",
    "the extrusion path as second one.\n",
    "Since we already have created a `Trace` all that is missing is a `Profile`.\n",
    "So let's create one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "shape_right = Shape().add_line_segments(\n",
    "    Q_([[10, 8], [5, 8], [1, 2], [1, 0], [10, 0]], \"cm\")\n",
    ")\n",
    "shape_left = shape_right.reflect_across_line(Q_([0, 0], \"cm\"), Q_([0, 1], \"cm\"))\n",
    "profile = Profile([shape_left, shape_right])\n",
    "profile.plot(raster_width=\"1cm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can create and plot our `Geometry`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "geometry = Geometry(profile=profile, trace_or_length=trace)\n",
    "geometry.plot(\n",
    "    profile_raster_width=Q_(0.25, \"cm\"),\n",
    "    trace_raster_width=Q_(10, \"cm\"),\n",
    "    show_wireframe=False,\n",
    ")\n",
    "trace.plot(raster_width=Q_(1, \"cm\"), axes=plt.gca(), fmt=\"r-\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Geometries with varying cross section\n",
    "\n",
    "The `VariableProfile` class gives us the opportunity to handle 3 dimensional geometries with a varying cross section.\n",
    "It can be used instead of a `Profile` during the creation of the `Geometry` class.\n",
    "Three pieces of information are necessary to create a `VariableProfile`.\n",
    "\n",
    "First a list of profiles is required.\n",
    "This list represents \"snapshots\" of known cross sections along the extrusion path.\n",
    "\n",
    "The second piece of information is a list of numbers that has the same number of elements as the list of profiles.\n",
    "Each of those numbers defines a coordinate on a 1 dimensional axis for the profile with the same list index.\n",
    "Their magnitude can be chosen arbitrarily with the exception that the first entry has to be 0 and the list items must be\n",
    "in ascending order.\n",
    "Due to the previously mentioned association between the coordinates/numbers and the profiles, the profiles are ordered\n",
    "by ascending coordinates.\n",
    "When you pass a `VariableProfile` to a `Geometry`, its first profile is used as the initial profile at the start of\n",
    "the `Trace` and the last as the one at the end.\n",
    "This relation enables the `Geometry` class to establish a linear coordinate transformation between the coordinates you\n",
    "specified in the `VariableProfile` and the corresponding position on the trace.\n",
    "For example, if you use three profiles with the coordinates `[0, 25, 100]` and your `Trace` has a length of $40 mm$,\n",
    "then the second profile occurs after $10 mm$ on the `Trace`.\n",
    "\n",
    "The last thing we need to provide in order to create a `VariableProfile` is how the space between two profiles gets\n",
    "interpolated.\n",
    "We pass this information is form of a list that contains the corresponding interpolation functions.\n",
    "For each pair of profiles we need to specify an interpolation where the first list entry is associated with the first\n",
    "pair, the second entry with the second pair and so on.\n",
    "The number of list items is therefore one less than the number of profiles.\n",
    "\n",
    "Lets have look at an example after this rather long text section. First, we define two more profiles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "shape_right_2 = Shape().add_line_segments(\n",
    "    Q_([[10, 8], [5, 8], [5, 2], [5, 0], [10, 0]], \"cm\")\n",
    ")\n",
    "shape_left_2 = shape_right_2.reflect_across_line(Q_([0, 0], \"cm\"), Q_([0, 1], \"cm\"))\n",
    "profile_2 = Profile([shape_left_2, shape_right_2])\n",
    "\n",
    "shape_right_3 = Shape().add_line_segments(\n",
    "    Q_([[10, 12], [2, 12], [4, 4], [4, 0], [10, 0]], \"cm\")\n",
    ")\n",
    "shape_left_3 = shape_right_3.reflect_across_line(Q_([0, 0], \"cm\"), Q_([0, 1], \"cm\"))\n",
    "profile_3 = Profile([shape_left_3, shape_right_3])\n",
    "\n",
    "\n",
    "profile.plot(raster_width=Q_(1, \"cm\"), label=\"Profile 1\")\n",
    "profile_2.plot(raster_width=Q_(1, \"cm\"), label=\"Profile 2\", ax=plt.gca())\n",
    "profile_3.plot(raster_width=Q_(1, \"cm\"), label=\"Profile 3\", ax=plt.gca())\n",
    "plt.gca().legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we create a `VariableProfile`, pass it to a new `Geometry` and plot it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "v_profile = VariableProfile(\n",
    "    [profile_3, profile_2, profile],\n",
    "    Q_([0, 40, 100], \"cm\"),\n",
    "    [linear_profile_interpolation_sbs, linear_profile_interpolation_sbs],\n",
    ")\n",
    "\n",
    "geometry_vp = Geometry(profile=v_profile, trace_or_length=trace)\n",
    "geometry_vp.plot(profile_raster_width=Q_(0.25, \"cm\"), trace_raster_width=Q_(8, \"cm\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom interpolation schemes\n",
    "\n",
    "You might notice that we used a interpolation function called `linear_profile_interpolation_sbs`.\n",
    "The \"sbs\" stands for \"segment-by-segment\".\n",
    "It interpolates all of the profile segments linearly in the order as they appear in both involved profiles.\n",
    "So you need to assure that the segments are ordered accordingly in both profiles.\n",
    "It also requires that the number of segments is identical and it only works with the `LineSegment`.\n",
    "\n",
    "You might wonder what alternative functions are provided, but currently there are none.\n",
    "The reason is that as soon as you start thinking about it, there are so many options that need to be considered that\n",
    "don't have a unique solution that fits all use cases.\n",
    "To circumvent this issue, we provide the possibility to use custom interpolation functions.\n",
    "All that you need to do in order to use your own interpolation scheme is to define a python\n",
    "function with the following interface:\n",
    "\n",
    "~~~\n",
    "def custom_interpolation(Profile, Profile, float) -> Profile\n",
    "~~~\n",
    "\n",
    "\n",
    "The `float` parameter is a weighting factor representing the position on the trace segment between both profiles.\n",
    "The `Geometry` class will pass values between `0` and `1` where `0` is the beginning of the segment and associates with\n",
    "the first passed `Profile`.\n",
    "In conclusion, a value of `1` represents the end of the segment and is associated with the second `Profile`.\n",
    "What you do with this information is up to you.\n",
    "All that matters is that the function returns a valid `Profile` in the end.\n",
    "\n",
    "Lets create an example interpolation that returns the first passed profile for weighting factors below `0.4` and the\n",
    "second one otherwise:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "def my_interp(p0, p1, weight):\n",
    "    if weight < 0.4:\n",
    "        return p0\n",
    "    return p1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Now we just create a `VariableProfile` with our new interpolation, combine it with a linear `Trace` inside of a\n",
    "`Geometry` and plot it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "v_profile_custom_interp = VariableProfile(\n",
    "    [profile_3, profile_2], Q_([0, 1], \"mm\"), my_interp\n",
    ")\n",
    "trace_custom_interp = Trace(LinearHorizontalTraceSegment(\"20cm\"))\n",
    "geometry_custom_interp = Geometry(v_profile_custom_interp, trace_custom_interp)\n",
    "\n",
    "geometry_custom_interp.plot(profile_raster_width=\"0.25cm\", trace_raster_width=\"2cm\")"
   ]
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}