Understanding Planes

[Paul8043]

In the next section a tutorial will follow which tries to explain some specific properties of planes.

Please review the contents. Let me know whether this information is considered to be useful.

It is a bit lengthy, so I encourage the reader to stay tuned up to the end.

[Paul8043]

Understanding Planes

1. Orientation of the Axes

The orientation of the axes is easy to remember, it follows the right-hand-rule. The thumb points to the x-axis (colored red), the trigger finger points to the y-axis (colored green), and the middle finger points to the z-axis (colored blue). This arrangement remains fix all the time.

The axis indicator of OCP-CAD-Viewer shows where the axes point to. Try to press the view-icons on the upper right corner.

button	x-axis	y-axis	z-axis
iso-view	front-right	back-right	top
front-view	right	back	top
back-view	left	front	top
top-view	right	top	front
bottom-view	right	bottom	back
left-view	back	left	top
right-view	front	right	top

The z-axis pointes mostly to top, except for front-view and back-view.

2. How is a Plane visualized?

A plane has no bounds in x-direction and y-direction, it spans an infinite area. Not so easy to visualize such a thing. Let us make the experiment. Run the code-snippet below:

"""
File: plane.py
"""

from build123d import *
from ocp_vscode import *

set_port(3939)

plane = Plane.XY
name  = "Plane.XY"

print(f"name={name}:origin={plane.origin}:z_dir={plane.z_dir}:x_dir={plane.x_dir}")

show_all()

In the OCP-CAD-Viewer we will see the following output:

A plane is rendered similiar like the axis-indicator, but larger and without arrows. This might be unexpected. Why should a 2D-plane get rendered as a 3D-cross? At the first glance you cannot see where the flat plane is located! This needs further explanation. The blue line is the normal-vector of the plane and the plane itself is spanned between the red and green line.

How to distinguish between the 3D-Axes-Cross and a plane which might be positioned on the same location? Try to activate the Axes-Icon on the Icon-Bar of the OCP-CAD-Viewer. The lines of the Axes are thinner and somewhat longer:

All planes are rendered this way with 3 orthogonal lines colored in red, green and blue. Only the orientation of the 3 axes may change. But for all variants the right-hand-rule is fulfilled all the time.

3. Predefined Planes

After spending some time with "readthedocs" and trying to run some of the examples you may look into further details. The Cheat Sheet is a good source for more information. There, you can click on "Plane" to learn more about planes. You will be confronted with this table which shows all pre-defined planes (available as class-methods):

Name	x_dir	y_dir	z_dir	alias
XY	+x	+y	+z
YX	+y	+x	-z
ZX	+z	+x	+y
XZ	+x	+z	-y
ZY	+z	+y	-x
YZ	+y	+z	+x
front	+x	+z	-y	same as XZ
back	-x	+z	+y
top	+x	+y	+z	same as XY
bottom	+x	-y	-z
right	+y	+z	+x	same as YZ
left	-y	+z	-x

This table is not easy to digest. Let us start with the planes labelled with uppercase letters. Plane.XY is the simplest one, everybody knows this plane and knows its orientation. X belongs to the first coordinate, Y to belongs to the second coordinate. The missing letter, in this case Z, belongs to the normal-vector. But the naming does not give any hints about the orientation of the normal-vector (2 choices). Only with the help of this table we can find out that for Plane.XY the normal-vector points to +z. Plane.YX is a flipped Plane.XY where the coordinates and normal-vector (pointing now to -z) are flipped. In exactly this way we can have a look at all other uppercase planes.

Plane.XY:

Plane.YX:

Plane.ZX:

Plane.XZ:

Plane.ZY:

Plane.YZ:

There are also 6 named planes (bottom, top, left, right, front, back). Imagine that there is cube centered at the origin (0,0,0) and you go to the end of the axes, then you can see the wanted face of the cube. From -X you see the left face, from +X the right face, from -Y you see front face, from +Y you see the back face, from -Z you see the bottom face, from +Z you see the top face. This is exactly what the view-buttons are doing. Here I have used the term face instead of plane. For the moment consider a face as the finite portion of an infinite plane.

So far so good, but this is only half of the battle, or more precisely only a quarter! If you take the position from +Z and looking down to the cube, you see definitely the wanted face (top), but it is unclear how the plane is oriented. You can rotate the plane in 4 directions (-x,+x,-y,+y)! So, the single entry for top in our table is only a quarter of the truth.

Name	x_dir	y_dir	z_dir	alias
XY	+x	+y	+z
top	+x	+y	+z	same as XY
???	+y	-x	+z
???	-x	-y	+z
???	-y	+x	+z

I have entered the additional 3 top alternatives. The line labelled with Name="top" is the expected orientation of most people. The orienation is chosen that local x goes to the right and local y goes to the top.

Before we look more deeply into these alternatives, we should make us more aware how planes are defined.

The first one for "top" is simple, just call:

plane = Plane.top

For the other 3 you have to call a constructor which allows to control individually each parameter:

plane = Plane(origin=(0,0,0),z_dir=(0,0,+1),x_dir=(0,+1,0))   # x_dir points to +y
plane = Plane(origin=(0,0,0),z_dir=(0,0,+1),x_dir=(-1,0,0))   # x_dir points to -x
plane = Plane(origin=(0,0,0),z_dir=(0,0,+1),x_dir=(0,-1,0))   # x_dir points to -y

Always start with the origin, in our case (0,0,0), then take care for the z_dir (normal-vector) which has the common value (0,0,+1) for our example, and the last thing is the value for x_dir (here we have 4 choices). Be aware that the parameter are defined in the order (origin, x_dir, z_dir). If you use named parameters, you can change the order as in the lines above. Also be aware that there is no definition for y_dir. All the axes obey the right-hand-rule. As soon as 2 of them are defined, the third is implicitely defined, too. This is the reason why y_dir is not part of the game!

Up to now we do not have good abbreviations for the additional planes marked with "???".

Let us try to use a more speaking notation:
Even, a plane is a 2D-object, we could use 3 letters for the name. Negative axes get lowercase letters, and positive axes get uppercase letters. Then the previous table would look like:

Name	x_dir	y_dir	z_dir	alias
XYZ	+x	+y	+z
top	+x	+y	+z	same as XYZ
YxZ	+y	-x	+z
xyZ	-x	-y	+z
yXZ	-y	+x	+z

The advantage would be: You can immediately see what is behind the first coordinate, what is behind the second coordinate, and where the normal-vector points. And the whole naming is compatible with the python-identifier-syntax. The drawback would be: such names are cryptic and not so easy to remember. And it looks very much that this table has many entries. We try it and decide later whether this might be an useful approach!

Planes can be placed directly somewhere into the 3D-space. This is what we did in previous examples. But it is also possible to attach a plane to a face of a more complicated object. And most likely you will be confronted with an example that shows a cube with some extrusions. The small example below shows what happens, if x_dir is not set correctly. Try to uncomment the plane-lines, only one at a time, to see where the cylinder moves around. Sometimes it looks like lx and ly are mixed up or that the sign of a coordinate is wrong. The behavior is very weird! The point is, the coordinates are correct, but x_dir has not the right value.

"""
File: x-dir.py
"""

from build123d import *
from ocp_vscode import *

set_port(3939)

b = Box(100,100,100)
front  = b.faces().sort_by(Axis.Y)[0]
back   = b.faces().sort_by(Axis.Y)[-1]
left   = b.faces().sort_by(Axis.X)[0]
right  = b.faces().sort_by(Axis.X)[-1]
bottom = b.faces().sort_by(Axis.Z)[0]
top    = b.faces().sort_by(Axis.Z)[-1]

lx = 20
ly = 30
#plane = Plane(top,x_dir=(+1,0,0))  # expected direction
#plane = Plane(top,x_dir=(0,+1,0))
plane = Plane(top,x_dir=(-1,0,0)) # weird direction
#plane = Plane(top,x_dir=(0,-1,0))
c = plane*Pos(lx,ly)*Circle(10)
e = extrude(c,20)

show_all()

Here x_dir has the expected value (+1,0,0):

Here X-dir has a weird value (-1,0,0):

4. Making the Plane-Table complete

For the named planes we have 4 additional variants. I do not want to bore the reader with more screen-dumps. But it should be clear now, how these screen-dumps are generated. You can do it for your own, that will help you to increase your understanding of planes!

Let us complete the Plane-Table, just to make sure that everything is covered and considered.

Name	x_dir	y_dir	z_dir	alias
top	+x	+y	+z
XYZ	+x	+y	+z	same as top
YxZ	+y	-x	+z
xyZ	-x	-y	+z
yXZ	-y	+x	+z
bottom	+x	-y	-z
Xyz	+x	-y	-z	same as bottom
yxz	-y	-x	-z
xYz	-x	+y	-z
YXz	+y	+x	-z
front	+x	+z	-y
XZy	+x	+z	-y	same as front
Zxy	+z	-x	-y
xzy	-x	-z	-y
zXy	-z	+x	-y
back	-x	+z	+y
xZY	-x	+z	+y	same as back
ZXY	+z	+x	+y
XzY	+x	-z	+y
zxY	-z	-x	+y
right	+y	+z	+x
YZX	+y	+z	+x	same as right
ZyX	+z	-y	+x
yzX	-y	-z	+x
zYX	-z	+y	+x
left	-y	+z	-x
yZx	-y	+z	-x	same as left
ZYx	+z	+y	-x
Yzx	+y	-z	-x
zyx	-z	-y	-x

Never thought that 3 axes and a 2D-plane could create such a large complexity!

This table has 6*4=24 entries. I do not want to propose that all entries should get a class-method. The information would be overwhelming and most people do not like to learn such a long list. However for understanding planes this table is of elementary significance.

After my first contact with Build123d I wanted to design a reference-cube for my 3D-printer. I just wanted to extrude the name of the side into the material. Thought this should be a simple task, but it was not. The letters did not appear at the desired place. This was too difficult for a newbie-task. But now, after learning the plane-table I understand what went wrong. You need to know what is behind x_dir, y_dir and z_dir!

The creation of the full-blown plane-table took me a few days. But whatever you plan to do, to keep the overview over the plane-orientation remains a challenging task. Seems to look-up something in the plane-table is a frequent action.

What to do to reduce the amount of time needed for this operation?

5. Use a Plane-Lookup-Tool (PLT) for setting-up Planes

Instead of doing look-ups in the plane-table, I have set up a hardware-tool that allows you to attach a plane within a few seconds. You can see the value for x_dir and y_dir almost instantaneously!

Plane-Lookup-Tool:

Dowels are used for the axes of the cube. They are colored in red, green and blue. Long dowels belong to the positive axes, short dowels belong to the negative axes. The X on the plate corresponds to x_dir and Y to y_dir. The in the hole in the middle of the plate belongs z_dir (going from the plate to your nose!). The plate can be moved easily to all faces. And you can always see where x_dir is located and y_dir, too. No further need to consult the plane-table any more!

BTW, the wooden version took me about 2 hours to build.

6. Appendix: Color-Encoding of Faces

If the default color-encoding of a face is used, e.g. with show_all(). The face is colored grey, if you are looking in the direction of the normal-vector, in the opposite direction the face is colored pink.

"""
File: face-color.py
"""

from build123d import *
from ocp_vscode import *

set_port(3939)

b = Box(100,100,100)
front  = b.faces().sort_by(Axis.Y)[0]
back   = b.faces().sort_by(Axis.Y)[-1]
left   = b.faces().sort_by(Axis.X)[0]
right  = b.faces().sort_by(Axis.X)[-1]
bottom = b.faces().sort_by(Axis.Z)[0]
top    = b.faces().sort_by(Axis.Z)[-1]

show_all()

This can easily be verified by opening the cube, just disable top and bottom. Then you can see how the cube looks from inside.

In most cases the normal-vector of a face is identical with the normal-vector of the attached plane. But it is also possible to attach a plane in counter-direction! This might be the case, if some work has to done from inside the cube! The Plane-Lookup-Tool will also cover this strange arrangement, just flip the plate, then the z_dir points to the center of the cube.