Region visualisation

It is sometimes useful to visualise the region we defined, either to make sure it is what we thought or to use it in more complex plots. In this tutorial, we show some basic as well as some more advanced ways of customising our plots.

We are going to use the same region we used in the previous tutorial:

\[p_{1} = (0, 0, 0)\]

\[p_{2} = (l_{x}, l_{y}, l_{z})\]

import discretisedfield as df  # df is here chosen to be an alias for discretisedfield

p1 = (0, 0, 0)
p2 = (100e-9, 50e-9, 20e-9)

region = df.Region(p1=p1, p2=p2)

There are two main ways how we can visualise objects in discretisedfield:

1. Using matplotlib (static 2D plots, usually with some tricks to make them look 3D)

2. Using k3d (interactive 3D plots)

All matplotlib method names start with mpl, whereas all k3d plots start with k3d. We will first have a look at simple plotting using both matplotlib and k3d and later look at how we can pass different parameters to change them.

Basic plotting

To get a quick matploltlib “3D” plot of the region, we call mpl:

region.mpl()

Without passing any parameters to mpl function, some default settings are chosen. We can see that matplotlib is not good in showing the right proportions of the region. More precisely, we know that the region is much thinner in the z-direction, but that is not the impression we get from the plot. This is the main disadvatage of mpl.

Now, we can ask our region object for an interactive k3d plot:

region.k3d()

This is now an interactive plot, which we can zoom, rotate, etc. In addition, a small contol panel is shown in the top-right corner, where we can modify some of the plot’s properties. The region is now shown in right proportions.

Advanced plotting

Here we explore what parameters we can pass to mpl and k3d functions. Let us start with mpl.

mpl

The default plot is:

region.mpl()

If we want to change the figure size, we can pass figsize parameter. Its value must be a lenth-2 tuple, with the first element being the size in the horizontal direction, whereas the second element is the size in the vertical direction.

region.mpl(figsize=(10, 5))

The color of the lines depicting the region we can choose by passing color argument. color must be a valid matplotlib color. For instance, it can be an RGB hex-string (online converter).

region.mpl(color="#9400D3")

discretisedfield automatically chooses the SI prefix (nano, micro, etc.) it is going to use to divide the axes with and show those units on the axes. Sometimes (e.g. for thin films), discretisedfield does not choose the SI prefix we expected. In those cases, we can explicitly pass it using multiplier argument. multiplier can be passed as \(10^{n}\), where \(n\) is a multiple of 3 (…, -6, -3, 0, 3, 6,…). For instance, if multiplier=1e-6 is passed, all axes will be divided by \(1\,\mu\text{m}\) and \(\mu\text{m}\) units will be used as axis labels.

region.mpl(multiplier=1e-6)

If we want to save the plot, we pass filename and region object is going to show and save the plot in our working directory as a PDF.

region.mpl(filename="my-region-plot.pdf")

mpl region plot is based on `matplotlib.pyplot.plot function <https://matplotlib.org/3.2.1/api/_as_gen/matplotlib.pyplot.plot.html>`__. Therefore, any parameter accepted by it can be passed. For instance:

region.mpl(marker="o", linestyle="dashed")

Finally, we show how to expose the axes on which the region is plotted, so that we can customise them. We do that by creating the axes ourselves and then passing them to mpl function.

import matplotlib.pyplot as plt

# Create the axes
fig = plt.figure(figsize=(8, 5))
ax = fig.add_subplot(111, projection="3d")

# Add the region to the axes
region.mpl(ax=ax)

# Customise the axes
ax.set_xlabel("length")
ax.set_ylabel("width")
ax.set_zlabel("height")

Text(0.5, 0, 'height')

This way, by exposing the axes and passing any allowed matplotlib.pyplot.plot argument, we can customise the plot any way we like (as long as it is allowed by matplotlib).

k3d

Default k3d plot is:

region.k3d()

If we want to change the color, we can pass color argument. It has to be an int.

region.k3d(color=654321)

Similar to the mpl plot, we can change the axes multiplier.

region.k3d(multiplier=1e-6)

k3d plot is based on k3d.voxels, so any parameter accepted by it can be passed. For instance:

region.k3d(opacity=0.2)

We can also expose k3d.Plot object and customise it.

import k3d

# Expose plot object
plot = k3d.plot()
plot.display()

# Add region to the plot
region.k3d(plot=plot)

# Customise the plot
plot.axes = [r"\text{length}", r"\text{width}", r"\text{height}"]

This way, we can modify the plot however we want (as long as k3d allows it).