LeoCAD: Assemblies, reference models & parts...

The LDraw system uses a hierarchical structure where files reference one another to build complexity.

• Part Files (.dat): These are the building blocks of the LDraw Parts Library. They contain the specific geometric data (lines, triangles, and quadrilaterals) for a single LEGO element. Official parts are maintained on the Parts Tracker.
• Model/Assembly Files (.ldr): These files represent a collection or "assembly" of parts. Instead of containing raw geometry, they contain references to .dat part files, specifying their position, orientation, and color.
• Multi-Part Document Files (.mpd): A more advanced assembly format that allows multiple assemblies (sub-models) and parts to be stored within a single text file. This is commonly used for complex sets that require organized building steps.

So creating a single (large) object, like a big building, this system works well.
Depending on complexity, 'sub models' could be used for different reasons:

• Need multiple copies of the same 'sub model', within the same master model. Model this (sub model.ldr) once and use it multiple times in the master model (New Model.ldr by default).
• During the build of a complex model, a 'sub model' could be build on itselves and when finished, it could be inserted into the master object, acting as a single piece.

For the most objects this works well.

But how to create an assembly, containing:

• Parts & sub-models, and
• References to other models?

Method 1a: 'Manual sub-models'... (no external references)

Suppose, you want to create a city, with multiple pre-build buildings, cars etc (.ldr/.mpd) and want to link to these buildings, instead of coping every instance as a 'sub model'?

Within LeoCAD (25.09) the 'Submodels' dialog screen is having a 'submodel-export' function, it's not possible to import a 'sub model'.
It's also not (directly) possible to link to external files (.ldr/.mpd)...

Work around: within Windows, multiple instances of LeoCAD could be opened. So within a "new model.mpd" file, a new 'sub-model' could be created and then the content of a 2nd LeoCAD instance could be copied into this new sub-model. Resulting into:

• In this case, we make a copy of the data, it's not a reference.
  So if the 'source model' changes/updates, the copied information will not be updated.
• Using a Mac, multiple instances of LeoCAD does not seem to work at all...

So the good thing: all object files are: self-contained, no missing-references, no circular references...
The bad thing using 'the work around': redundant data → unnecessary large files & updates needs to happen in multiple files. The work around is a lot of work and not working for Mac users at all. (I'm using a Python script, for importing/exporting sub-models.)

Method 1b: 'File - Merge'... (no external references)

Okay, while writing this blog, I found out about the 'File-Merge' option... If you have an model file open and merge a 2nd file, all 'sub-models' of the 2nd file will be copied into the first. So basically the same result like method 1a, but way more simple...

And after a File-Save action, all duplicated 'sub-model' names will be 'updated'.

LDraw - Under the hood

Within the LDraw system it's possible to create a "Sub-file reference", inside an model file (.ldr/.mpd), using a line:
"1 <colour> x y z a b c d e f g h i <file>"

• 1: LDraw knows, the next data is a 'sub-file reference'.
• <colour>: <file> could be shown in specific color.
• x y z: Position of the object.
• a...i: Rotation matrix of object
• <file>: Filename of object.

So it's possible to create a "New Model.ldr" in LeoCAD and then use a text editor, inserting one or more references to existing object(s). This example file contains 4 references to 4 different buildings:

0
0 Name: New Model.ldr
0 Author:
1 7 0 0 0 1 0 0 0 1 0 0 0 1 ref_buildings/ADDO_01.ldr
1 7 1000 0 1000 1 0 0 0 1 0 0 0 1 ref_buildings/ADDO_02.ldr
1 7 0 0 1000 1 0 0 0 1 0 0 0 1 ref_buildings/ADDO_03.ldr
1 7 1000 0 0 1 0 0 0 1 0 0 0 1 ref_buildings/ADDO_04.ldr

The good news:

• It's possible to refer to an external models (.ldr/.mpd)
  Could even refer to objects inside subfolders:
  • In this case it's a sub folder "ref_buildings".
  • Official documentation also refers to the "LDRAW\MODELS" (library) path, for storing sub-models. But this is (currently) not working for LeoCAD.
• The reference models are still accessible & updatable.
  (Needs to be opened in separate LeoCAD instance.)
• LeoCAD is also showing referenced buildings, click the "In Use" parts list.
  (This is only true for the active 'sub-model'.)
  (These references parts are also showing up twice, in the "All parts" list.)

The downside:

• Need to use a text editor, making this a bit harder for some users.
• All the parts are now added directly into the 'workspace' of the new model.
  (And the position/orientation of the references are basically randomly chosen.)

Two other methods crossing my mind, creating external references in a different way:

Method 2: External references, using sub-models...

2a. Instead of 'inserting' external models directly in the 'modeling' environment, refer to these models inside a 'sub-model'.

2b. And instead of creating a long list of external 'models' inside this 'sub model', let's refer to one external file, which contains a list of external 'models'.

In the best case:

• Only one 'reference model' (.ldr) has to be updated, when new objects are available.
• The models themselves, could still be edited in a different LeoCAD instance.
• Current LeoCAD instance is showing all instances of this 'sub-model' in the "In Use" list.
  (Although this long "In Use" list is not available in other 'sub-models', unless they are copied there.)
• Current LeoCAD instance (.mpd) needs one reference 'sub-model', containing the 'reference model.ldr'.
  This still needs to be added using a text editor.
• Sharing a model: requires to include the reference (sub-foler+) files too.

Does it work? Let's try... Results:

• 2a: Does work:
  • LeoCAD recognizes 1 layer of 'external references'.
• 2b: Does not work:
  • LeoCAD only recognize the first 'external model' as "In Use". The deeper external references are 'just' parts inside this 'sub-model'.
  • Naming starts to be an issue. For instance "New Model.ldr" is now used both in the 'master' assembly, but also in the reference model. So when showing the reference model, also the master is shown. The 2nd layer of referenced files are not shown.
  • When naming is solved, the results are better, but these 2nd layer parts are still considered as one 'external sub-model'.

Method 3: External references, using .dat files...

Another way is using these external models as 'parts'. So by creating 'part definitions', the "Sub-file reference" could refer to the model (.ldr) files. In this case:

• The objects could show up in the category list, if the right filters are used.
• The 'part definition file' is just a placeholder to the specific model (.ldr) file.
  So the models themselves, could still be edited in the normal way.
  This still needs to be using a text editor.
• The reference models needs to be stored, so the library is able to find them, inside the library folder.
• Sharing a model, these 'additional' part files needs to be copied into the right folders too...

From experience: It's already difficult to update 1 'static' custom library with just a few users.

Does it work? I did not try. From the 'model-sharing' point of view: Don't go this road.

Summary:

Results of these different methods:

Method:	Data stored:	Pros:	Cons:
1a/b. Many sub-models.	Inside sub-models.	One file, containing all data. Sharing: easy.	Redundancy, etc
2a. One sub-model, w. many references.	One sub-model, with many references to external 'single' models.	Ref. models could be copied into the master object, while still being a reference. Ref. models are still editable, in seperate LeoCAD instances.	Sharing assemblies: needs to copy references files (& sub-folders) too.
2b. One sub-model, w. reference to file with references.	One sub-model, with reference to external model, having many external models.	Clean data structure: only one list of external object to be updated.	Difficulties, with duplicate naming of 'sub-models'... Does not work.
3. Creating 'part' definitions (.dat).	Inside LDraw library.	Easy 'model' selection, by categorisation.	Sharing assemblies: too complex. "LDraw/Model" not recognized by LeoCAD.

Currently I'm using method 1, having many "Multi-part docs (*.mpd)", sometimes containing many unique 'sub-models (*.ldr)'. This works well for storing/organizing this data. But using all potential buildings inside a new model, was not handy, without using the "Merge" function. Still the biggest downside for this method: the difference between a copy and a reference...

Using assemblies, reference models & parts:

To work like real CAD systems, method 2a is the way to go. Way of Working:

• (Preparation LeoCAD): store some separate models.
• LeoCAD: Prepare 'the scene' .mpd-file.
• LeoCAD: Add empty sub-models.
• Text editor: For each sub-model, add one reference model.
• LeoCAD: Inside the "New Model", add parts and/or reference models the way you like.

Maybe I'll switch over to 2a at different point in time...