Mirror Structures across any plane

[Oliver Hope 261]

This tutorial will show you how to use the BTH building aids mirror tool to mirror a group of entities across a plane.
This is one of the more powerful tools IMO, so stick through the scary maths language builders, I believe in you! 
BTH building aids main page.

Video Version
Coming soon? Hopefully?

Introducing the problem

Before we get into the tutorial let's look at an example of where this is useful and some possibly simpler solutions.

Lets look at this greenhouse, if we want to mirror the roof and posts it is easy to select them, duplicate, rotate 180^o on the y-axis (green) and reposition it.

That was easy but its not always as simple as rotating around an axis. 
Lets take a look at a boat hull made by the talented @Yo HasLEGO which I will be using to demonstrate using the mirror tools.

Here we can see one-half of the hull. If we try to rotate as in the previous example, it doesn't matter what axis we rotate it on, we won't be able to mirror it.

You could try rotating each layer separately, this works okay for the top layer, there is just one block at the stern that is problematic but that could be fixed manually fairly easily.
However, as soon as we go further down the hull where there are more curves, this method really falls apart.

 

The mirror Tool

Let's see how to use the mirror tool to make mirroring this boat hull possible. There are 2 mirror tools one camed 'Mirror' and the other named 'Mirror templates enabled'. Mirroring all the entities is not a simple process so a few complex parameters are required to use the 1st option, however, I have created a bunch of templates for commonly used entities to make it much easier to use. I'll first show how to use the option with templates enabled.

Mirroring with Templates

Step 1
Create a group with all the entities you want to mirror (this just makes selecting them easier)

Step 2
Place the mirror tool in position, the entities will be reflected across the trigger zone plane (the local XY plane of the trigger zone)

Step 3
Add all entities of a single type to the entity label. (Use ctrl double click to select all entities of a type).

Step 4
Open the script in the label (Use shift + alt + double click to quickly open a script in a group), select the tile in the 'entity mirror template' parameter and select the block shape from the drop-down list. The dimensions are given in XYZ order and are multiples of 0.375, ie the 2x1x2 block is an entity with the dimension of 0.75x0.375x0.75. (Side note, Iv been checking through the templates and I seem to have made a mistake with some of the formats but they still kinda work, ill try fix them at some point)
The entities I have selected in the above image are 2x1x4 so I have selected this template.

Step 5
Repeat steps 2 - 4 with each different entity type in your build. There are cases where you can use the same mirror tool for different entity types, see important notes point 1.

Step 6
Test your world to check that everything is generated correctly. See the following tutorial to learn how to create a composition of the generated section and use it in your world. Using generated structures (video tutorial)

If you have sharp eyes you will notice I haven't done the sloped blocks at the end of the boat, oops.

@Yo HasLEGO was then able to bring both sides of the hull together for his catamaran, looks how great it looks! (Still a WIP)

Important notes

 

• The templates are based on the wooden blocks, most entities of the same shape have the same origin and orientation and therefore they can be mirrored using the same mirror tool. For example:
  
• However, some have different orientations and most of the time this will be problematic:
  

So what happens if there isn't a template for a block I want to use? This is where the other Mirror tool comes into play.

Advanced Mirror Tool

This tool is very similar to the previous one, the only difference is that you need to provide an entity centre offset and an entity mirror plane normal. These parameters can be found on the entity label in the mirror group.
Do the same steps described above but instead of step 4 follow the instructions below.

Entity Center
This is a vector describing where the centre of the entity is relative to the entity's origin. NB: Ensure the vector is in the local space of the entity and remember to use minus for direction.
Here is an example using a simple 2x1x4 block (there is already a template for this, but it's easy to demonstrate on)

Entity mirror plane normal
This one is a little more complex but bare with me. We need to find a plane over which the entity is symmetrical, some objects have multiple planes, you can use any of them.
This block is asymmetric on the XY plane, notice how the x and y-axis are parallel to the orange plane, this is why it's called the XY plane. It's also symmetric about the XZ plane and YZ plane.

The parameter asks for a normal to the plane, in maths a normal is a vector ('arrow') that is perpendicular to a plane, in the first example we can see that the z-axis is perpendicular to the plane therefore the normal is 0,0,1 ( it could also be (0,0,456) or (0,0,-87) but let's keep it normal, pun very much intended.)

NB: As with the entity centre remember to do everything in the local space relative to the entity.

How about a more complex example. This block is not symmetric about either of the 3 basic plans (XY, XZ, YZ), however, it is about this plane at a 45-degree angle.

To find a normal to this plane imagine a perpendicular arrow and what the coordinates of that arrowhead must be. In this terrible paint image the black arrow is the normal. A normal vector is a direction vector therefore its position is irrelevant, note how I have moved the origin but kept the same orientation.

Remember that if any entity types have the same entity centre offset AND entity mirror plane normal you can use the same mirror tool for both those entity types a good example of this is these two wall signs.

A few examples of entities that do not have a symmetry plane, note that you may be able to get satisfactory examples using the closest plane.

Edited June 23, 2022 by Oliver Hope