[LDCad] Aligning parts using rotation scripts

[David Manley]

1. Background

A few months ago, I wrote a Lua script for LDCad to animate the rotation of a 4 (or 3) bar linkage, posting the script to the LDraw forum. Writing that script got me thinking about writing a script which would determine the joining point for two parts, each being rotated about their own designated rotation point.

I’ve now written a version of the script. This post describes how to use the script and provides details about downloading and installing the script.


2. Expectations

The aim of the script is to provide a point-and-click mechanism to rotate parts within LDCad. Conceptually, the parts serve different purposes; some are identified as a rotation origin, some are identified as being aligned to another part and some parts are those which are being rotated. Although this post tends to use the term part, the script can also be used with sub-files.

The script provides solutions for two different scenarios

• rotating a single part to a designated alignment point
  
• rotating two parts to a join point common to both parts
  

Images from an incomplete model of set 9748-1 (a current work-in-progress) illustrate the script's capabilities.

[David Manley]

3. Single Part Rotation

Note that the functionality described in this section can be achieved using equivalent capabilities which already exist within LDCad, albeit with a slightly different approach. This functionality was added to provide a slightly simpler point-and-click approach.

Description
Four parts are required for this action, as illustrated in Figure 1:

1. a part to rotate around,
   
2. an alignment part for the part to be rotated,
   
3. a fixed part to be rotated to and
   
4. the part to be rotated
   

Figure 1 – Single Part Rotation Reference


Existing LDCad Approach

Until recently, the approach I used in LDCad is to temporarily add three extra parts, at positions which correspond to 1, 2 and 3, and then select all three parts in sequence. Via the right mouse click on the first part, I then choose the Selection Info/Show Info menu option as illustrated in Figure 2 (albeit with all other parts / sub-files hidden for the sake of clarity) …


Figure 2 – Initial part selection

… to toggle the menu item “Show info” from “No” to “Yes” (Figure 3). Once angles are being displayed, the significant angle (highlighted by the red box) can be copied to the clipboard just be clicking on the angle.


Figure 3 – Displaying angles

The next step is to apply the rotation angle to the appropriate part/sub-file. In this case (illustrated in Figure 4), the first part and the fourth part/sub-file are selected and the Manual rotation dialog invoked via its shortcut key (usually CTRL+r). Selecting the first part as well as the fourth part helps to ensure the fourth part is rotated according to the origin of the first part rather than the origin of the fourth part.


Figure 4 – Manual Rotation of part

Now for the whoops moment. I often forget which way the positive and negative value for the rotation angle cause an anti-clockwise or clockwise rotation of parts within LDCad. In this case, entering a value of 19.58 caused the part to rotate in the wrong direction so a quick undo (CTRL-z) followed by CTRL+r and making the angle a negative value (i.e. -19.58) results in the desired alignment (Figure 5).


Figure 5 – Desired part alignment

[David Manley]

Rotate one part script approach

The customer rotation scripts provide an equivalent solution for rotating a part. The scripts are accessible via the Scripts/align parts menu item (see this post for installation instructions).

The first step with the alignment functionality is to identify the rotation axis. This is achieved via the menu item Scripts/align parts/Rotation Parameters (see Figure 6). The rotation axis will default to the Y axis, so if the axis around which to rotate to align the parts is either the X or Z axis, the alignment scripts must be notified.

In Figure 6 the parts need to be rotated around the Z axis, hence the Rotation Parameter macro is run. Once selected, the axis of rotation will remain the same until the macro is re-run and a different axis of rotation selected.


Figure 6 – Rotation Axis Selection

In Figure 6, the supplementary pins which are visible in Figure 3 can be seen. They are coloured red to make it easier to distinguish them from the parts/sub-files which are really part of the model.

To use the single part rotation script, the relevant four parts need to be selected in the order as illustrated in Figure 1. Figure 7 illustrates the four parts (the three supplementary pins and the sub-file which contains the leg) selected in readiness to run the script.


Figure 7 – Single Part Rotation Part Selection

Once the parts have been selected, the open scripts/align parts menu (Figure 8) and then select the Rotate one part menu item. If any number other than four parts have been selected, a dialog window will appear that prompts with the part selection requirements to run the script.


Figure 8 – Align Parts Menu

After the script has been run, the parts will be rotated and a dialog displayed that allows the rotation to be accepted or discarded (Figure 9).


Figure 9 – Rotate One Part Dialog

Closing the dialog by clicking Yes results in the rotation being applied to the model (Figure 10). At this point, the user should manually delete any supplementary parts being used purely to achieve the desired rotation.


Figure 10 – Model after One Part Rotation

By itself, the Rotate one part script is not much different to using the approach described earlier in the Existing LDCad Approach section. The primary difference is not having to establish and specify the rotation angle. However, the code used to rotate one part is available for re-use when attempting to align two rotating parts.

[David Manley]

4. Two part rotation

The rotation alignment script can also be used to rotate two parts and identify the points at which the parts can be connected. This scenario was the primary driver for the scripts – the single part rotation came as a consequence of implementing the two part rotation.

This description starts with a simple test case. The benefit of doing this is that the concepts can be more readily illustrated without having superfluous parts acting as a distraction.

Description

Six parts are required for the two part rotation action, as illustrated in Figure 11.

1. a part around which the first part will be rotated
   
2. an alignment part for the first part to align with the second rotating part
   
3. a part around which the second part will be rotated
   
4. an alignment part for the second part to align with the first rotating part
   
5. the first part to be rotated
   
6. the second part to be rotated
   

Figure 11 – Two part rotation, reference parts

The parts which are used for the purpose of rotation and alignment are selected first (Figure 12). The premise of selecting these parts first is that there is less “noise” from the highlighted selected parts than if the parts which are to be rotated were selected first (which could make it harder to subsequently select the rotation and alignment parts).


Figure 12 – Two part rotation, rotation and alignment selection

Once the parts to be rotated have been selected, the menu item Scripts/align parts/Rotate two parts is selected (Figure 13) …


Figure 13 – Rotate two parts menu item

… and the parts will be rotated immediately. There are usually two potential points at which the parts could be joined. Therefore, one part will be rotated to one of the positions and the other part will be rotated to the second position. A dialog is displayed allowing the user to choose which one is the desired position (Figure 14).


Figure 14 – Rotate two parts, choose alignment position

Figure 15 and Figure 16 Illustrate the difference between selecting the first and second position for this example model.


Figure 15 – Rotate two parts, first position selected


Figure 16 – Rotate two parts, second position selected

Once the parts have been rotated into the desired position, any of the rotation or alignment parts which are surplus to requirements can be deleted.

[David Manley]

5. Two Part Rotation Actual Usage

Enough with the simplistic example. Let’s see how to use the script in a more realistic way using an actual model.

Figure 17 illustrates a partial build of set 9748-1. The four rotation and alignment parts required for the two part rotation are highlighted. The two red pins are required to achieve the rotation but are not part of the model so they will be deleted once the rotation is complete.


Figure 17 – Two Part Rotation, R2D2 #1

Figure 18 shows the selection of the four rotation and alignment parts.


Figure 18 – Two Part Rotation, R2D2 #2

Figure 19 illustrates all 6 “parts” selected, immediately prior to invoke the Rotate Two parts script.


Figure 19 – Two Part Rotation, R2D2 #3

Figure 20 illustrates the two positions where the rotated parts can be aligned.


Figure 20 – Two Part Rotation, R2D2 #4

Figure 21 shows the model after the first alignment position was selected and the superfluous alignment and rotation parts (the red pins) deleted. Note the liftarms at the rear still need to be aligned …


Figure 21 – Two Part Rotation, R2D2 #5

… which can be achieved using the single part alignment, as illustrated in Figure 22. Once again, additional parts have been added to the model for rotation/alignment purposes.


Figure 22 – One Part Rotation, R2D2 #6

Figure 23 shows the placement of the liftarms after completion of the one part rotation and the deletion of the extra red rotation/alignment pins.


Figure 23 – One Part Rotation, R2D2 #7

This sample model shows how the rotation scripts support a point-and-click approach within LDCad for aligning parts, thus avoiding the need for a user to have to compute rotation angles

[David Manley]

6. Installation

The Lua scripts which provide the logic to achieve the part rotation are available for anyone to download (the original download has been superceded - use this link instead use the version 4 download) and use.

Assuming you have downloaded and extracted the scripts from the zip file, the suggested installation process is as follows;

1. If you are currently running LDCad, exit the program,
   
2. Locate the directory in which LDCad is installed. This will likely be something like C:\Program Files\LDCAD. Next, navigate to the sub-directory called scripts.
   
3. If you do not have a sub-directory named custom within the scripts sub-directory, create it.
   
4. Navigate to the custom sub-directory.
   
5. If you do not have sub-directories within custom named global and modules, create any that are required.
   
6. Place the script named align parts.lua into the global sub-directory. Place the script named compound_rotation.lua into the modules sub-directory.
   
7. When you next start LDCad, under the Scripts menu item, you should see a new menu item named align parts within the list of global modules.
   

2024-04-02 If you are using LDCad beta 1.7, the scripts will need to be installed into the directory "%APPDATA%\LDCad\scripts\custom"

[David Manley]

7. Other Comments/Observations

There is a reasonable degree of commonality between the code contained in these scripts and the code in the linkages.lua. This is deliberate.  Somewhere on my To Do list is an action to rewrite the linkages.lua scripts so that it uses the code within compound_rotation.lua.

I think that the part alignment logic works for all cases. However, it you encounter a situation in which they don’t appear to work as you expect, please post to this thread and I will see if I can identify the issue.

This is my second attempt at writing some Lua scripts. It seems likely that there are aspects of the scripts which can be improved. Constructive feedback is welcomed.

Roland, you are more than welcome to include/distribute these scripts as part of LDCad, should you so wish. Feel free to fold, mutilate or spindle them should the need arise.


Regards,

David

[N. W. Perry]

Wonderful! I can't wait to try it. I have one suggestion you may want to consider, regarding the selection order.

As you know, the two-part rotation is also somewhat present in LDCad using Selection Info, this time with the triangle function. But again, you have to manually copy the rotation angles and apply them yourself (although this time the program correctly decides which direction to rotate).

In LDCad's existing behavior, the selection order for this method is endpoint, rotation center, rotation center, endpoint. You could emulate this behavior in the script by simply swapping points 1 and 2 in the selection order. (I think selecting the actual parts to be moved last is a good idea.)

This would also match the behavior of Roland's custom right angle script, which is used to rotate a part so that it rests against an unknown point on a plane, such as a ladder leaning against a wall. In that script you select 1) the endpoint of the part being rotated, 2) the rotation center, and 3) a point on the plane that is normal to the rotation center.

Not a big deal, of course, just something that might make the integration more seamless.

[David Manley]

...

As you know, the two-part rotation is also somewhat present in LDCad using Selection Info, this time with the triangle function. But again, you have to manually copy the rotation angles and apply them yourself (although this time the program correctly decides which direction to rotate).

...

This would also match the behavior of Roland's custom right angle script, which is used to rotate a part so that it rests against an unknown point on a plane, such as a ladder leaning against a wall. In that script you select 1) the endpoint of the part being rotated, 2) the rotation center, and 3) a point on the plane that is normal to the rotation center.

...

I wasn't aware of the triangle function until your post! A helpful observation for me to take on board. I'll see if I receive any other feedback before making changes. Modifying the part selection order is a straight forward change (it will probably take me longer to redraw the images in this thread).

Regards,

David

[Milan Vančura]

David, I do not know how to thank you enough! I tested your script for linkage animation and it works nicely but I must say I have not spent much time with it because I was so curious about part alignment scripts. And I'm impressed how well they work - including bells and whistles like showing two possible alignment options directly in the model, without affecting later undo stack. You did a great job and  helped me with my next models a lot. Thanks again, David, for such nice Christmas present!

And for a motivation how can I help with this. Because this is such a good base it would be pity not to expand it to be helpful in more situations. For example hinges do not have any "central pivot part" your script needs. LDCAD does not allow neither user nor scripts work with snap objects, AFAIK. (And as I remember past conversations with Roland,it is not easy to implement in current LDCAD code.) So I'm thinking about some special helper parts...

Another improvement is using current coordination system instead of the global one. To make script works for setups rotated in any way - just select a part, press "O" to get local coordination system, and continue with the script as usual.

[Milan Vančura]

Another improvement is using current coordination system instead of the global one. To make script works for setups rotated in any way - just select a part, press "O" to get local coordination system, and continue with the script as usual.

OK, I was not able to find this in API reference easily, so I return to thisafter Christmas. Thanks again, David, and enjoy Christmas too!

[David Manley]

Another improvement is using current coordination system instead of the global one. To make script works for setups rotated in any way - just select a part, press "O" to get local coordination system, and continue with the script as usual.

Hi Milan,

thank you for your feedback and kind words.

In truth, requiring the user to explicitly set the axis of rotation as opposed to rotating around the appropriate axis for the current camera was a bit of laziness on my part. I imagine that I could use the LDCad API to work out the appropriate axis. However, making the axis user selectable meant it was less code/easier code for this initial release and thus I could release the code sooner. I'll add improved axis rotation to the To Do list for a subsequent release!

Regards,

David

[Roland Melkert]

LDCAD does not allow neither user nor scripts work with snap objects, AFAIK. (And as I remember past conversations with Roland,it is not easy to implement in current LDCAD code.)

It is actually partial available in LDCad 1.6 (a leftover from my experiments which I forgot to remove).
The current 1.7 version has it all commented out, but I might put it back in again when picking 1.7 development up in my coming vacation.

Another improvement is using current coordination system instead of the global one. To make script works for setups rotated in any way - just select a part, press "O" to get local coordination system, and continue with the script as usual.

This is something I can easily add, so I will add it to the ldc.view ( http://www.melkert.net/LDCad/docs/scriptAPI2#view ) object in the upcoming version.

It will only return the current matrix, as the LDCad api is supposed to be (very) low level only.

[Milan Vančura]

Thank you for this couple of great messages, Roland. I'm ready to test snap objects and give you feedback from user POV: having chance to work with snap objects is a base for several features I have in my mind for such a time... And many of them, I believe, are even easy to implement IF having an access to snap objects.


API to grid matrix makes David's script much more useful because not everything is aligned to original XYZ system, esp. in Technic models. With this API (and David's script using it), it becomes a matter of one click and one keypress for the user: select the base part and press 'O'.

David: this is how we can bend hinges as well, using your script together with my new helper part axis.dat.
a video of hinge bending using David's script

[Milan Vančura]

Ah, sorry for forgetting the part itself. Here it is. It works with clip-bar pair, old 3-2 fingers hinge, hinge brick and new hinge plate - and everything what uses these kind of hinge connections. We may add more, of course. And, in future, maybe we will not need any help parts at all, we will be able to select snap objects directly. But, until then, this helper does its job.

Installation: put axis.dat in your directory with unofficial parts and rename shadow_axis.dat as axis.dat in your directory with unofficial shadow files, as set in your LDCAD configuration.

[Roland Melkert]

Installation: put axis.dat in your directory with unofficial parts and rename shadow_axis.dat as axis.dat in your directory with unofficial shadow files, as set in your LDCAD configuration.

It being an unofficial helper part, you can also put the snap meta's in the part itself (no shadow needed).

LDCad processes parts as a single file after appending the shadow content to it.

[Milan Vančura]

It being an unofficial helper part, you can also put the snap meta's in the part itself (no shadow needed).

LDCad processes parts as a single file after appending the shadow content to it.

Thanks, Roland, for this detail. The merged file is attached to this message.

For me, this part makes an important improvement to David's script because, so far, I did not know any way how to bend hinges in LDCAD like it was possible in SR3D editor. What about adding David's script to the LDCAD default set of scripts? Maybe with this axis part as well? Or should I improve the axis part somehow? Add more snap infos?

BTW, the axis part has its usage in different cases as well, for example illustrations like this one. Maybe we can add it to Helper parts when/if the standard for them is agreed.

[Magnus Forsberg]

Error loading submodel 1 4-4edge.dat.
File: C:\Users\...\Downloads\1226\axis.lddptmp
Line #37
Line: 1 16  0 -12.5 2.5  0 1 0  0 0 0.5  1 0 0  1 4-4edge.dat


Error loading submodel 1 4-4disc.dat.
File: C:\Users\...\Downloads\1226\axis.lddptmp
Line #38
Line: 1 16  0 -12.5 2.5  0 -1 0  0 0 -0.5  1 0 0  1 4-4disc.dat


There's a single 1 to much in those lines.

[Milan Vančura]

There's a single 1 to much in those lines.

Ah, such a stupid mistake of mine, thank you for pointing this out, Magnus.
I attach a new version which is, I hope, both better looking and with more readable source.

I made no changes in snap info so it still snaps to hinges types mentioned above. It works for me and expands David's script capabilities exactly in a way I looked for. I'm interested both in your experience and your tips for this helper part improvement.

For example, the naming of the "subpart" definitely does not follow any convenience simply because I do not know them, I'm not a part author. I just try my best to help But this is the last point, I believe - if there is an interest to add this part (and subpart) to standard helper parts (and when the Standard Committee agrees on them). So far, please test this and tell us tips for improvements or your experiences or that I made another stupid mistake etc.

[David Manley]

8 Align parts / Linkage Animations, revised

This is a follow-up to provide information about revised scripts for aligning parts and the linkages animation. The appropriate scripts can be downloaded from BrickSafe (use this link for an updated download that removes a bug from the two parts rotation script) and installed as per the original description albeit that the installation will also install the script linkages.lua into the sub-directory named global.

8.1 Align Parts / Rotation around current view plane

The only changes related to aligning parts is changes to the align parts / Rotation Parameters dialog. Two “choice” dialogs now exist. The first (see Figure 24) allows aligning the parts according to the currently active view plane.


Figure 24 – Rotate around view plane option

Note that if the current view plane option is selected, ensure that when a part alignment macro is invoked the appropriate view plane is active. Otherwise, your results may not be as expected.

8.2 Part Selection Sequence

The second dialog displayed when the Rotation Parameters dialog is invoked is shown in Figure 25. This allows a user to decide the sequence that parts are to be selected when running the part alignment script. If you don’t like the default option, make a one-time change to the script align parts.lua and change the initial value of the variable part_selection_order_option_mi.


Figure 25 – Alignment Part Selection Sequence

8.3 Linkage Animation Changes

The Linkages animation have been modified in a couple of ways. Firstly (and hopefully invisible to anyone), the animations now make use of the same compound rotation.lua code module as that used by the part alignment scripts. There are a number of other changes and additions which are perhaps more visible.

If  you install the linkages module as a custom/global script, your LDCad menu structure will look something like that shown in Figure 26.


Figure 26 - Linkages added to scripts Global menu

8.4 Linkage Menu Change

Logic has been added for a crank-slider animation. As there are now multiple animations available, a menu option named Choose linkage animation has been added for the user to identify which animation they want to run (refer to Figure 27). Selecting this menu option causes the dialog shown in Figure 28 to be displayed.


Figure 27 - Linkage menu


Figure 28 - Animation selection

Further menu options allow for;

• identifying which parts are involved in the animation (menu option Pick the animation parts which was previously named 4 bar linkage selection)
  
• identifying the sequence in which the animation parts are being selected (Figure 29). This is equivalent to that for the part alignment logic (refer to section 8.2) but is pertinent to the linkage animations.
  

Figure 29 - Animation part selection sequence

8.5 Crank Slider Animation

Code has been added for the animation of a crank-slider mechanism. The default part selection sequence is illustrated in Figure 30. The axes have been highlighted in the screenshot to illustrate which axis will be used when the animation is run using the current view plane as the rotation axis.


Figure 30 - Crank Slider Default Part Selection Sequence

The model used in this animation was authored by Walt White and is available on rebrickable.com.

The result of running the animation is shown here:

[David Manley]

8.6 Crank Slider Animation Caveats


Two caveats are applicable with the Crank Slider animation;

1. The slide axis must be on the same relative horizontal axis as that formed by the line segment of the crank rotation and crank alignment parts when at their “zero” position. If there is a horizontal offset, the animation will not be correct.
   
   The code currently contains some commented out code to try to work out any horizontal displacement between the slider axis and crank rotation/crank alignment axis. This is far from finished and has been commented out to enable me to release this version of the scripts. There is an alternative way, which is to require an additional point on the slider to be selected but my gut instinct says that this is a cop out and surely there is a derivation of the horizontal displacement using trigonometry.
   
   
2. If using the current viewing plane to derive the axis of rotation, make sure the correct one is active when the animation is run. “Interesting” animations can result otherwise.
   
   
   

8.7 Conclusion

Anyone is welcome to fold, mutilate or spindle these scripts to suit their own means.

If someone wants to work out the necessary logic for calculating the horizontal displacement related to the Crank Slider animation, please do so!

Please let me know if you encounter any issues with the scripts by posting to this thread.

Regards,

David

[Max Martin Richter]

I wonder if there will be an exact solution for this area at set 8829:
   

I tried to find it by hand but it seems my brain capacity is limited 

/Max

[David Manley]

I wonder if there will be an exact solution for this area at set 8829:


I tried to find it by hand but it seems my brain capacity is limited 

/Max

There's some challenging angles in there (LDraw model obtained from Technicopdia) :



My code is (in effect) simply drawing circles in 2D space. Solving it for this model looks like it would need some kind of (having Google-d it earlier today) Jacobian Inverse Kinematics solver. Way beyond the capabilities of the part alignment script.

David

[N. W. Perry]

There's some challenging angles in there (LDraw model obtained from Technicopdia) :

My code is (in effect) simply drawing circles in 2D space. Solving it for this model looks like it would need some kind of (having Google-d it earlier today) Jacobian Inverse Kinematics solver. Way beyond the capabilities of the part alignment script.

Yikes.   1994 was certainly quite the year for this kind of stuff!

But as long as there's only a single solution, then it should be solvable just with triangles…shouldn't it? I'm sort of tempted, but I think I'll take a little break from Technic for the moment. :-)

[Max Martin Richter]

It would be quite enough, to have solution for this.
I wonder how this was done 1994.
/Max

[Orion Pobursky]

It would be quite enough, to have solution for this.
I wonder how this was done 1994.
/Max

I would imagine hand drawn (maybe on a computer, maybe not) since LDD pro didn't exist.

[David Manley]

8 Align parts / Linkage Animations, revised

This is a follow-up to provide information about revised scripts for aligning parts and the linkages animation. The appropriate scripts can be downloaded from BrickSafe and installed as per the original description albeit that the installation will also install the script linkages.lua into the sub-directory named global.

A follow up-post, three years later.

I trialed the part rotation alignment script in LDCad 1.7 beta today and discovered the following

1. in Windows, the custom scripts now need to be installed into the directory "%APPDATA%\LDCad\scripts\custom". This is a change from LDCad 1.6, when the scripts needed to be installed into "C:\Program Files\LDCad\scripts\custom" (or whichever directory you installed LDCad into).
   
2. there was a bug in the two parts rotation, introduced when adding the ability to rotate around the current view plane. Up until now, it looks like it would only ever work when the current view plane was the Y plane. This bug has been corrected.
   

The amended scripts are available for download from BrickSafe (replaced with download containing one more code tweak).

Regards,

David

[Edit: updated with new link to v4 of script)

[Cam's Bricks]

It would be quite enough, to have solution for this.
I wonder how this was done 1994.
/Max

This can be calculated by hand and then input into the computer. LEGO especially in 1994 seems like the kind of company that would do that.

[Roland Melkert]

in Windows, the custom scripts now need to be installed into the directory "%APPDATA%\LDCad\scripts\custom". This is a change from LDCad 1.6, when the scripts needed to be installed into "C:\Program Files\LDCad\scripts\custom" (or whichever directory you installed LDCad into).

The location of the scrips hasn't changed between 1.6 and 1.7 it seems you installed the 'standalone' version of 1.6 into your program files folder which is not recommended on Windows 7 and later.

This because LDCad.exe will look for a LDCad.cfg file at start, this file will tell it where to put/get user data. When the cfg is not there (the case for the standalone version) it will keep everything inside the same folder as the exe.