LDInstruction

[Stefan Frenz]

Thanks to all helping me with LDInspector. In the last weeks I wrote a new module to generate instructions from a MPD model. It is far from being complete or feature-rich like LPub3D, but for me it suits better in some situations. The generated file is a LibreOffice Draw (odg) file, so further modification is very easy and only limited by LibreOffice.

You may give it a try if you have Java installed (no need for JavaFX for this module). You only need the jar file and a context definition file LDInspector.ldi - you can use the one created by LDInspector or create one containing one line per LDraw part source like in

Code:

0 FILE LDIContext.ldi
0 LDInspector context configuration
0 Name: LDIContext.ldi
0 Author: LDInspector

0 !LDINSP PART_SOURCE [type=Directory] [origin=ofc] [dest=/path/to/ldraw/]
0 !LDINSP PART_SOURCE [type=ZIP] [origin=uno] [dest=/path/to/ldraw/Unofficial/ldrawunf.zip]

where parameter type is one of "Directory" or "ZIP" and origin is one of "ofc" (official parts) or "uno" (unofficial parts).

To start the GUI, please use

Code:

java -cp ldinstr.jar ldinsp.guisw.InstructionHelper

For a slightly modified version of the 603 model you should get an output odg file looking like the attached image:
   

To me this approach has several PROs and CONs:

• Pro: single-step processor: there are no commands having range limits ("start-end"), the commands only set parameter ("from here on").
  
• Pro: stable behavior even for large projects (tested with >320 pages and >350 steps).
  
• Pro: most options may be changed for each step (for example highlight-color etc.).
  
• Pro: real WYSIWYG for current model step, option to use and/or overwrite LDCad/MLCad ROTSTEP angles.
  
• Pro/Con: not full-featured instruction commands (no arrows, no lines, no number editing), but fully editable in LibreOffice (free placement for all items, changing of all background/frame colors, adding elements like arrows and lines, editable text and numbers).
  
• Pro/Con: focus on steps instead of pages, so (pro) you can later change steps with LDCad without risking already done layouts but (con) you have to re-run the build process to see page layout changes.
  
• Pro/Con: orthogonal projection, no option to have perspective projection.
  
• Pro/Con: completely software rendered, no OpenGL/Vulkan/DirectX acceleration (a bit slow, but no special driver/hardware/library required).
  
• Con: no WYSIWYG-gui for pages.
  

I would appreciate any feedback or even "this could be done easier using x, y or z". If there is interest in this project, the GUI will have to support the process much more than it does at the moment like hinting about options (left align, center align, right align, fixed offset), support in creating a valid LDInspector.ldi file and maybe a page-preview for multiple steps.

Best regards and thanks in advance
Stefan

[Philippe Hurbain]

Hi Stefan,
Looks like I do something wrong (problem of not mastering the subject ). When I launch LDInstruction I get

Code:

Exception in thread "main" java.lang.UnsupportedClassVersionError: ldinsp/guisw/InstructionHelper has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

...so I updated Java - or so I thought... It now says "Version 8 update 311 (build 1.8.0_311-b11)" but the error above remains the same. What do I do wrong?

[Stefan Frenz]

Hi Philippe,

thanks for trying.   The current jar-file is made for Java 11 or later. Tomorrow After some sleep I should find time to re-compile with Java 8 as target.

Best regards
Stefan

[Stefan Frenz]

I updated the snapshot jar file, it should now work with Java 8 or later.

The GUI is now marked as main class, to start it you can shorten the command line:

Code:

java -jar ldinstr.jar                                 # now sufficient
java -cp ldinstr.jar ldinsp.guisw.InstructionHelper   # working as before

In the current jar file there is a command line version integrated to generate the instruction-odg which does exactly the same as the GUI-button "build instructions":

Code:

java -cp ldinstr.jar ldinsp.instr.BuildInstructions YOUR_MPD_FILE.mpd [OUTPUT.odg]

As most of LDInspector is included, you may also use this jar file to check OMR validity:

Code:

java -cp ldinstr.jar ldinsp.tools.LDITFileChecker YOUR_MPD_FILE.mpd

And you can get the bill of material for one or more models step-by-step and sub-model-by-sub-model and summed up:

Code:

java -cp ldinstr.jar ldinsp.tools.LDITBillOfMaterial YOUR_MPD_FILE.mpd [MORE.mpd] [MORE2.mpd]

[Philippe Hurbain]

I updated the snapshot jar file, it should now work with Java 8 or later.

It works! Now I'd like to know why when I updated my Java I was not even proposed to update to Java 11 !!! (but of course that's not your problem  )

...still struggling to understand how to go from raw 603 model to your nice single page modified version...

[Stefan Frenz]

It works! Now I'd like to know why when I updated my Java I was not even proposed to update to Java 11 !!! (but of course that's not your problem  )

...still struggling to understand how to go from raw 603 model to your nice single page modified version...

Java 8 is really different to Java 9 and later, so most systems have the option to keep version 8 updated and some other (higher) version updated seperately. As my current jar file does not need JavaFX, it is now "old school" without the Java module system... Bad thing from my point of view, but unfortunately nothing we can do about. I'm happy that it worked for you now.  

For the single page version, the step/maxColumns and step/maxRows options are changed from default 1 to value 0. This can be done by inserting at each submodel

Code:

0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]

in the mpd file or setting "overwrite" checkbox and value in the GUI:
   

There are several options which clearly need some documentation... I'm working on that.

[Philippe Hurbain]

There are several options which clearly need some documentation... I'm working on that.

Maybe, yes!   Already got it working somewhat nicely though...

[Stefan Frenz]

...still struggling to understand how to go from raw 603 model to your nice single page modified version...

All changes are LDraw comments (type 0 lines) with "!LDINSP INSTR" or "!LDINSP INSTRSC" prefix. Every option is enclosed in brackets like [key=value]. Ordering or position of the corresponding line inside the step is not relevant, meaning: you can place every option for a step everywhere between the STEP/ROTSTEP lines. For convenience, the InstructionHelper GUI always places parameter changes at the top of the step and always in the same order, arranging corresponding options per line (e.g. "rotX" and "rotY" and "rotZ" are in one line and "step/maxColumns" and "step/maxRows" are in another line).

All parameters can be set with the GUI. No keyword has to be remembered or typed in.

The following changes inside the official omr lead to the given example (downloadable here):

• The main file has some global settings. Those are tagged with "doc/" (for the whole document) or "scope/" (options for a specific part that is not a sub-part of the current mpd file).
  

• Each sub-model has container layout information (step/maxColumns=0 and step/maxRows=0 where "0" is the special value for "auto layout to fill page").
  

• The torso with arms and hands is added as submodel, otherwise those five parts would be listed as separate parts in the pli of step 6.
  

In more detail:

Code:

0 !LDINSP INSTR [doc/dpi=150] [doc/width=29700] [doc/height=21000] [doc/margin=1000]
0 !LDINSP INSTR [doc/bgModel=CFEFFF] [doc/bgPli=BFDFFF] [doc/bgSub=FFF0CF]

First line: render images with 150 dpi, define paper width 29700/21000 and paper margin 1000 (all sizes/lengths are given in milli-centimeter, here leading to 29.7cm width and 21.0cm height (DIN A landscape) and 1cm margin).
Second line: define background colors for model (light blue), part list inventory (darker light blue) and inlined sub-steps (light yellow).

Code:

0 !LDINSP INSTRSC [scope=3626ap01.dat] [pli/rotX=15] [pli/rotY=0]
0 !LDINSP INSTRSC [scope=3641.dat] [pli/rotY=45]

Both lines are scoped (it's tagged "INSTRSC" instead of "INSTR"), each line must contain exactly one scope parameter. In those two lines, the rotation in the part list inventory (therefore keys start with "pli/") for parts 3626ap01 (head with pattern) and 3641 (wheel) is changed.

Code:

0 !LDINSP INSTR [zoom=2]
0 !LDINSP INSTR [centerX=15.58] [centerY=-7.841] [centerZ=57.228]
0 !LDINSP INSTR [rotX=30] [rotY=45] [rotZ=0]
0 !LDINSP INSTR [step/noPli=1]
0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]

All lines change the rendering parameter (no prefix) or the layout ("step/" prefix) of all following steps in this sub-file. Each sub-file starts with the default parameter set. Notable parameters here are

• step/noPli: if set to 1, the step will have no part list inventory (default 0 means "show pli")
  
• step/modelX=-2 and step/modelY=-1: place the model horizontally right aligned and vertically centered (0..n is fixed offset, -1 means "center", -2 means "right"/"bottom")
  
• step/maxColumns=0 and step/maxRows=0: either give a positive number as maximum cols/rows per page, or (indepently) value 0 means "auto".
  

The sidecar sub-file has

Code:

0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]
0 !LDINSP INSTR [inl/zoom=1.5]

The first two lines are explained above, the last line sets zoom for the inlined step to 1.5 (all values may be integer, some values like zoom may be floating point values). In the sidecar sub-file step 3 and 4 have rotation information: step 3 sets "[rotX=-30] [rotY=45] [rotZ=0]", and starting from step 4 I wanted to have back default rotation, so I had to set "[rotX=30] [rotY=45] [rotZ=0]". Setting rotZ is optional as it is not changed neither in step 3 nor step 4.

The wheel sub-file has

Code:

0 !LDINSP INSTR [inline]
0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]

The last two lines are explained above, the first line sets this complete sub-file as "inline", so on usage it will not add separate steps but instead will add an inline box in the using step.

The added body sub-file has another sub-file flag

Code:

0 !LDINSP INSTR [aspart]

This tells the instruction processor to treat the whole sub-file as single part.

[Stefan Frenz]

info: uploaded new current version snapshot (same address) to fix endless loop on some unexpected layout conditions

[Stefan Frenz]

info: again updated "current version" to fix corner case column width problems

[Stefan Frenz]

After some more tests, I took a chance to check for a technic model with integrated parts. Thank you Philippe    for your Sorter MOC which I was allowed to use therefore. Now there are at least three bugs less.

Attached is the changed mpd, only empty steps are removed and only basic LDINSTR meta commands are added:

Code:

0 !LDINSP INSTR [doc/dpi=150] [doc/width=29700] [doc/height=21000] [doc/margin=1000]
0 !LDINSP INSTR [doc/bgModel=CFEFFF] [doc/bgPli=BFDFFF] [doc/bgSub=FFF0CF]
0 !LDINSP INSTR [zoom=1]
0 !LDINSP INSTR [shiftX=2042] [shiftY=2767]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]
0 !LDINSP INSTR [pli/maxWidth=7000] [pli/maxHeight=7000]
...
0 !LDINSP INSTR [step/noPli=1]
...
0 !LDINSP INSTR [step/noPli=0]
...
0 !LDINSP INSTR [aspart]

Most commands are described above except for

• shiftX and shiftY: move the object after rendering before cropping
  
• pli/maxWidth and pli/maxHeight: set maximum size per part in part list inventory (there is one really big part)
  

Unfortunately I was not able to attach the generated odg file to this post, so the generated pdf is added for convenience. If you like to generate the odg, please just call the current unstable version with

Code:

java -cp ldinstr.jar ldinsp.instr.BuildInstructions Sorter.mpd SorterInstructions.odg

[Stefan Frenz]

...and some more rotations...

[Stefan Frenz]

...some more tweaking to have page breaks at convenient steps, changed zoom from 1 to 2 to have bigger images.

I would treat this one as "ready".

[Stefan Frenz]

...to allow uploading the pdf, I had to merge two steps (wheels and cable bush)...

All instructions are explained already except for:

Code:

0 !LDINSP INSTR [step/pliBoxMaxWidth=-1]

The parameter step/pliBoxMaxWidth sets the maximum pli box width (in milli-cm) and there are two special values: default value 0 means "auto", value -1 means "don't care". With that option set, the pli will consume as much space as needed ignoring the current model image.

Code:

0 !LDINSP INSTR [highlight=1] [highlightRgb=00FF0000] [highlightWidth=2]

The parameter highlight enables (1) or disables (0) the highlighting of added parts (default: on==1). With highlighRgb the color can be changed for each step (default is red). Setting highlightWidth changes the width of highlighting (default is 1)

[Roland Melkert]

I wrote a new module to generate instructions from a MPD model.

This seems very interesting, it might actually motivate me to install Java (again) so I can give it a try.

Also nice to see someone adapting the LDCad meta line format

[Stefan Frenz]

This seems very interesting, it might actually motivate me to install Java (again) so I can give it a try.
Also nice to see someone adapting the LDCad meta line format 

I would appreciate any feedback!   And indeed for LDInspector I already had to implement the reading part of the LDCad meta line format, and it's exactly what I needed. Thanks for the blueprint.

[Stefan Frenz]

Now there is a version 0.1 packed for further reference. Thanks again to Philippe - your model removed some really relevant bugs.  

The following screenshots are taken from a built instruction:

• Screenshot_01 is taken directly without modification.
  
• After building the odg file and by the use of LibreOffice Draw, Screenshot_02 shows the inlined part assembly box moved to the right and lines with arrows added manually.
  

To have a better contrast, the dark bluish grey face color is changed to be a little bit lighter, and the edge color is changed to a very light grey. This is done by changing the values in the GUI or by adding a (LDraw standard meta colour) line in the mpd

Code:

0 !COLOUR Dark_Bluish_Grey                                      CODE  72    VALUE #646464   EDGE #D0D0D0

   

   

[Stefan Frenz]

This post explains the currently (version 0.1) available options.

• All options can be set in the InstructionHelper GUI.
  
• All mcm values are milli-cm, i.e. a value of 1 is 0.001cm, 100 is 1mm and a value of 1000 is 1cm (because of OpenDocument standard).
  
• Each model or sub-model starts with the default values (only global ones are for main model and all sub-models).
  
• Setting an option does not affect any other option, the new value is used until the option is set again (no "start-end", only "from-here-on" behavior).
  
• In the GUI, activate "overwrite" checkbox to set a value; the value entered in the box right of overwrite is used only if the overwrite checkbox is selected. If it is not selected, the greyed value in the left box is used.
  

Global parameter (prefix: "doc/") which can be set only once and may occur only in the first step of the main model:

• doc/dpi: dpi; default: 150.
  
• doc/width and doc/height: page width and height in mcm; default is 29700/2100 resulting in DIN A4 landscape.
  
• doc/margin: margin in mcm; default: 1000.
  
• doc/specialStuds: activate special studs with edge color for better contrast (default: 0 meaning "off").
  
• doc/debugInfo: activate source and debug information for each step (default: 0 meaning "off").
  
• doc/bgModel and doc/bgPli and doc/bgSub: hexadecimal rgb color value for model background (default CFEFFF light blue), part list inventory background (default BFDFFF darker light blue) and inline sub-model background (default FFF0CF light yellow).
  

Example:

Code:

0 !LDINSP INSTR [doc/dpi=150] [doc/width=29700] [doc/height=21000] [doc/margin=1000]
0 !LDINSP INSTR [doc/bgModel=CFEFFF] [doc/bgPli=BFDFFF] [doc/bgSub=FFF0CF]

Step rendering parameter (prefix: "step/") define options regarding layout and step.

• step/skip: do not show this step (default: 0 meaning "show step").
  

• step/noResult: skip the resulting step but not the included parts (default 0 meaning "show result").
  
• step/noPli: do not draw the part list inventory (default: 0 meaning "show pli").
  
• step/modelX and step/modelY: exact x/y offset of rendered model image in mcm or special values -1 meaning centered or -2 meaning right/bottom align (default: -1 meaning "center").
  
• step/newPage and step/newColumn and step/newRow: start a new page/column/row for this step (default: 0 meaning no explicit page/column/row break).
  
• step/maxColumns and step/maxRows: maximum columns/rows in the current layout container or special value 0 for automatic (default: 1 meaning exactly one step per page).
  
• step/pliBoxMaxWidth: maximum width of part list inventory box in mcm or special value 0 for automatic size or -1 for model overlay (default: 0 meaning auto; GUI name: "step/pliBMW").
  

Example:

Code:

0 !LDINSP INSTR [maxWidth=23500] [maxHeight=19000]
0 !LDINSP INSTR [zoom=1]
0 !LDINSP INSTR [rotX=30] [rotY=45] [rotZ=0]
0 !LDINSP INSTR [shiftX=-2252] [shiftY=3201]
0 !LDINSP INSTR [highlight=1] [highlightRgb=00FF0000] [highlightWidth=2]

Inline sub-model parameter (prefix: "inl/") define options regarding inlined models:

• inl/zoom: special inline zoom factor which is applied as factor.
  
• inl/boxMaxWidth: maximum width of inlined sub-model box in mcm or special value 0 for automatic size or -1 for model overlay (default: -1 meaning overlay).
  

Example:

Code:

0 !LDINSP INSTR [inl/zoom=1.5]

Model rendering parameter (no prefix) and part list inventory rendering parameter (prefix: "pli/"):

• maxWidth and maxHeight: width and height of rendered image in mcm (default for model: 20000 and 14000, default for pli: 5000 and 7000).
  
• lineWidth: width of edge lines (default: 1).
  
• shadeWeight: factor to shade colors depending on absolute angle (default: 5.4).
  
• zoom: model zoom.
  
• centerX and centerY and centerZ: move center of model before rendering in LDraw coordinates (default: all 0).
  
• rotX and rotY and rotZ: rotate model before rendering in degrees (default: 30/45/0 for model, 30/-45/0 for pli).
  
• shiftX and shiftY: move rendered model image in mcm (default: 0/0).
  
• highlight and highlightRgb and highlightWidth: define highlighting for parts added in the current step if highlight=1: highlightRgb is hexadecimal color (default FF0000 red), highlightWidth is width of highlighting (default 1); if highlight=0 other parameters are ignored.
  

Example for model:

Code:

0 !LDINSP INSTR [maxWidth=23500] [maxHeight=19000]
0 !LDINSP INSTR [lineWidth=2]
0 !LDINSP INSTR [zoom=1.5]
0 !LDINSP INSTR [shiftX=3064] [shiftY=-1235]
0 !LDINSP INSTR [highlight=1] [highlightRgb=FF0000] [highlightWidth=4]

Example for pli:

Code:

0 !LDINSP INSTR [pli/maxWidth=9000] [pli/maxHeight=9000]
0 !LDINSP INSTR [pli/zoom=0.3]

Additionally, the first step of a sub-model may contain at most one of the following two parameters:

• inline: add steps of this model as inlined sub-steps in an inline-sub-model-box.
  
• aspart: treat this sub-model as part, do not add steps nor inline box.
  

Example:

Code:

0 !LDINSP INSTR [inline]

Colors can be defined with standard LDraw colour meta, example:

Code:

0 !COLOUR Black                                                 CODE   0    VALUE #1B2A34   EDGE #D0D0D0
0 !COLOUR Green                                                 CODE   2    VALUE #00852B   EDGE #D0D0D0
0 !COLOUR Dark_Bluish_Grey                                      CODE  72    VALUE #646464   EDGE #D0D0D0

Scoped pli-instructions define parameters for not-included (meaning: standard LDraw) parts, example:

Code:

0 !LDINSP INSTRSC [scope=2462.dat] [pli/rotY=0]
0 !LDINSP INSTRSC [scope=4186.dat] [pli/rotX=90] [pli/rotY=0]

[Stefan Frenz]

This post shows another small example: the omr model 1972 is slightly changed (see mpd file attached to this post), resulting in six pages which are fully editable in LibreOffice. Of course the hoses in step 9 may be replaced, but shown here is the unmodified generated odg output:

   

   

   

   

   

   

[Stefan Frenz]

...updated current version to support part replacement in part list inventory.

For included sub-models, in the first step add something like

Code:

0 !LDINSP INSTR [tg/replace=76348.dat]

For not-included (external) parts/models this must be scoped:

Code:

0 !LDINSP INSTRSC [scope=3022.dat] [tg/replace=76348.dat]

With this option the hoses in step 9 look nicer in the pli:
   

[Stefan Frenz]

here is a small how to get from a small model like 40190 to a single sided instruction like this:

   

Way 1: use the GUI.

1. Load the file and check/adjust global settings like dpi and page size according to your needs (default is DIN A4 landscape / 150 dpi).

   

2. In the main model step 1 enable "noResult" overwrite and set "noResult" value to "on".

   

3. In the car sub-model step 1 enable "step/modelX" overwrite and set its value to "-2" (right align). Also enable "step/maxCols." and "step/maxRows" and set their values to "0" (automatic column and row layout).

   

4+5. In the wheel sub-model and 93589p01 sub-part root (above step 1) activate overwrite "aspart" and set value to "on".

   
   

Way 2: insert meta lines in mpd.

1+2. In the first step of the main file, set dpi, page size and switch result to off by adding

Code:

0 !LDINSP INSTR [doc/dpi=300] [doc/width=29700] [doc/height=21000] [doc/margin=1000]
0 !LDINSP INSTR [doc/bgModel=CFEFFF] [doc/bgPli=BFDFFF] [doc/bgSub=FFF0CF]
0 !LDINSP INSTR [step/noResult=1]

3. In the first step of the car sub-model set zoom, right align and layout by adding

Code:

0 !LDINSP INSTR [zoom=1.3]
0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]

4+5. In the wheel sub-model and 93589p01 part sub-model set aspart option by adding

Code:

0 !LDINSP INSTR [aspart]

That's it, have fun.

[Stefan Frenz]

the current version allows splitting the pli/inline/model container into separate boxes via new boolean parameter step/split. This results in top-down alignment of pli/inline/model, for example helpful in step 10 of model 40191 (modified version attached):

   

[Philippe Hurbain]

the current version allows splitting the pli/inline/model container into separate boxes via new boolean parameter step/split. This results in top-down alignment of pli/inline/model, for example helpful in step 10 of model 40191 (modified version attached):

Busy on some other project, but I'll come back soon Looks more and more awesome.
One question, do you intend to allow to add a global BOM (or maybe it already exists?)

[Stefan Frenz]

BOM is on about second position of my ToDo list   together with model title page. I'm still fiddling how to express my wishes to the program, and I would like to have not only "plain" BOM but BOM for building sections. Maybe some kind of a table? Still thinking how to tell the program... Or is this useless at all?

[Stefan Frenz]

Now there is a version 0.2 packed for further reference.

Main changes:

• Added part replace option tg/replace for pli parts.
  
• Added container split option step/split for top-down and separate container box layout.
  
• Added direct GUI-feedback for wrong input (background becomes red).
  
• Added part-list per step for easier access.
  
• Fixed major bug if page is overfull.
  

[Gerald Lasser]

BOM is on about second position of my ToDo list   together with model title page. I'm still fiddling how to express my wishes to the program, and I would like to have not only "plain" BOM but BOM for building sections. Maybe some kind of a table? Still thinking how to tell the program... Or is this useless at all?

I think a BOM in a list style is definately also a good idea, may be even a BL Style wanted List.
FOr the Classic-Lego-Instruction Style BOM, I would wish for a possibility to "sort" eventually parts by myself to get a space efficient layout.

[Stefan Frenz]

I would wish for a possibility to "sort" eventually parts by myself to get a space efficient layout.

Thanks for your input. As everything is generated into an OpenDocument Draw file, one could re-sort as needed afterwards, but this is kind of painful for many parts. I was thinking of the sorting categories width, height, color, LDraw part number, LDraw part description; so there could be an option to define in which order those categories should be applied.

Do you have an idea how to express your sorting wish?

I could even think of a small source code API like this:

Code:

int diff=o1.getColId()-o2.getColId();
if (diff!=0) return diff;
String o1d=o1.getDescription(ctx);
String o2d=o2.getDescription(ctx);
if (o1d!=null && o2d!=null) return o1.getDescription(ctx).compareTo(o2.getDescription(ctx));
return o1.getName().compareTo(o2.getName());

which is the sorting algorithm for the pli (meaning: first sort by color id, then by description, then by LDraw id)... But I have the strong feeling that this would be over-engineering and so it would not really be usefull.

[Stefan Frenz]

Do you have an idea how to express your sorting wish?

Another idea: specify the parts in the exact order you would like to have them printed and a small routine that prints all commands with a default sorting...?

[Stefan Frenz]

So this is the first attempt to have a BOM:

for 603:
   

for 1972:
   

Not yet implemented is a table style with part description right besides the image.

Command to insert is at the moment:

Code:

0 !LDINSP INSTRCMD [cmd=bom]

I'm not sure about the sorting. What about sort parameter? This would be like this:

Code:

0 !LDINSP INSTRCMD [cmd=bom] [sort=color,description,width]
0 !LDINSP INSTRCMD [cmd=bom] [sort=w,c,d]

Printing text is still a nightmare because of unknown width: at the moment, text is included "as text" in my program, only opening the file in Draw will show the resulting text width. Hmmmmmm.

[Stefan Frenz]

BOM-option with description (example shows 603):

   

At the moment, reserved width for text has to be specified and is fixed, resulting in cropped text (like in last part of left column: "... with 1 Centre Stud"). The text is still "there", but "not visible", i.e. editing with LibreOffice Draw (or any other odg capable processor) will show the complete text and allows reformatting.

In my code there is still some inconvenience in text handling (for example wrong y-align of "1x Plate 2 x 2"). I will have to spend more time on this which is not abundantly available at the moment.   I need to pack some more Christmas brick gifts...

I think a BOM in a list style is definately also a good idea, may be even a BL Style wanted List.

Would the currently available list styles (option 1: image with amount below like in previous post, option 2: image with amount and description aside like in this post) meet your use cases?

[Philippe Hurbain]

I played a little more with LDInstructions, and of course I get more questions...
- It seems that the page break when there is a new submodel is inserted AFTER the first step of that submodel. I expected the break to occur before that step.
- Is there a way to apply common settings to all submodel of a file? I used a vertical model, and having to change each assembly max size from landscape to portrait is a bit daunting... Question applies also to change each submodel to multi-step per page.

[Stefan Frenz]

- It seems that the page break when there is a new submodel is inserted AFTER the first step of that submodel. I expected the break to occur before that step.

Hm. I would expect that, too.   Maybe the sub-model has only maximum of 1 row? Maybe the current container on the page is not full before the first step of the submodel, so if it has enough space and the container allows placing another step... Would you mind mailing me your test file so I can dig into it?

- Is there a way to apply common settings to all submodel of a file? I used a vertical model, and having to change each assembly max size from landscape to portrait is a bit daunting... Question applies also to change each submodel to multi-step per page.

At the moment the GUI represents only options that the backend understands 1:1, but there are some options (like mentioned col/row layout and maxSize parameter as well as highlighting or linewidth) that clearly should be set-able once for all submodels. To set options in all submodels by GUI is on the ToDo list but not implemented yet - I'm still thinking about some "treat this as default" as separate option (like "doc/maxWidth") which would make this GUI feature needless.

PS: still fiddling with details of the BOM...

[Stefan Frenz]

the BOM, text and break commands are now available in the current version, the attached 603 example generates these two pages:
   
   

There is a new LDINSP-meta: INSTRCMD. This takes exactly one cmd option (at the moment: break, text or bom) and options dependent on the command. Examples:

Code:

...
0 !LDINSP INSTRCMD [cmd=break] [column]
0 !LDINSP INSTRCMD [cmd=bom]
0 !LDINSP INSTRCMD [cmd=break] [page]
0 !LDINSP INSTRCMD [cmd=text] [text=SideCar]
0 !LDINSP INSTRCMD [cmd=bom] [part=603-1 - sidecar.ldr] [zoom=1.3] [description] [textwidth=10500] [sort=color,description,width,height,name]
0 !LDINSP INSTRCMD [cmd=break] [column]
0 !LDINSP INSTRCMD [cmd=text] [text=MiniFig]
0 !LDINSP INSTRCMD [cmd=bom] [part=603-1 - minifig.ldr] [zoom=1.3] [description] [textwidth=10500] [sort=color,description,width,height,name]
...

• cmd=break: insert a break, possible flags are: [column], [row], [page] (default).
  
• cmd=text: insert a text heading (do not use brackets [] in the text parameter, this would break the meta parameter syntax).
  
• cmd=bom: insert a bom. Default is small list style with image above amount (right side of first example page). You may specify sort order, used is only first character of each word, so "color" is the same as "colour" is the same as "c" is the same as "clown". You may limit the BOM to a submodel with option part. You may specify flag [description] to change style to have a description right of the image (second example page). In this style you may specify the textwidth, otherwise this will default to 9000.
  

At the moment, the INSTRCMD is handled well by the GUI, but there is no GUI to insert/edit/remove INSTRCMD metas (on the ToDo list).

[Stefan Frenz]

...current version updated again and clarified options in previous post...

[Stefan Frenz]

There is a new current version of LDInstruction that does not interfere with generated LDCad path file content. All previous versions of the GUI store LDInstruction commends illegally between re-generated lines, so they are are removed on LDCad save (as stated by LDCad). Starting with this LDInstruction version the GUI stores meta lines before the re-generated lines, so they persist LDCad load-generate-save. Thank you to Philippe for the test model.

[Philippe Hurbain]

There is a new current version of LDInstruction that does not interfere with generated LDCad path file content.

FYI the link above refers to your hard disk instead of your website

[Stefan Frenz]

*oooops* thank you! I modified the wrong link.

[Stefan Frenz]

Now there is a version 0.3 packed for further reference.

Main changes:

• Added instruction commands, available are: text, break and bom.
  
• Redesigned text handling, updated pli/inline box layout.
  
• Fixed center of model step center in some corner cases.
  

Parameter for [cmd=text]:

• required [text=YOUR_TEXT]
  

Parameter for [cmd=break]:

• optional exactly one of [column] or [row] or [page] (if not given, default is [page]).
  

Parameter for [cmd=bom]:

• optional [part=SUBFILE.ldr] to limit BOM to the given subfile (if not given, default is complete file).
  
• optional [zoom=123.4] to specify part zoom in BOM (if not given, default is 1.0).
  
• optional [maxWidth=1234] and [maxHeight=1234] to specify maximum render width and height in mcm (if not given, default is 5000/7000).
  
• optional [cols=12] and [rows=12] to specify maximum columns and rows (if not given, default 0 meaning "auto" is used).
  
• optional [sort=c,d,w,h,n] to change sort order (default color, description, width, height, name).
  
• optional [description] to change from simple list (image above amount) to list with description (image left of amount and description).
  
• optional [textwidth=1234] to specify description width only if list with description is used (if not given, default is 9000).
  

The GUI has some basic instruction editing feature, but it does not support via suggesting instruction command names or parameter options (somewhere down on ToDo list).

[Stefan Frenz]

The current version allows some new things:

• [step/vLines=0/1] and [step/hLines=0/1]: vertical and horizontal helper lines to guide building order in complex layouts.
  
• [step/annotate=0/1]: add annotations for axles and tiles.
  
• [step/pliSort=SORTORDER]: sort parts in PLI (for SORTORDER, see BOM sort parameter).
  
• [step/donePage=0/1] and [step/doneRow=0/1] and [step/doneCol=0/1]: insert a page/row/col break after the current step (instead of "new..." which inserts the break before the current step).
  
• Most parameters can be prefixed by "default/" to set this parameter for all subfiles.
  
• Print warning if color-independent parts (submodels without color 16/24) are used in different colors (as they will appear for each used color).
  

Additional GUI changes:

• Button "Reset file": remove all LDINSTR meta lines.
  
• Button "Cleanup file": remove all effectless local LDINSTR options.
  
• Steps with local options are now marked in the part tree.
  

[Stefan Frenz]

examples for PLI options:

default:

  Screenshot_01_default.png (Size: 11.54 KB / Downloads: 125)

change sort order via [step/pliSort=...]:

  Screenshot_02_sort.png (Size: 11.52 KB / Downloads: 124)

again change sort order via [step/pliSort=...], limit pli box width via [step/pliBoxMaxWidth=...], enable annotations via [step/annotate=1]:

  Screenshot_03_sortAnnotateSize.png (Size: 12.62 KB / Downloads: 122)

[Stefan Frenz]

Layout example, built from attached mpd:
   

[Stefan Frenz]

Thank you, Philippe, for your very helpful feedback and your test file.  

As result, the current version has some new features:

• [colorOrder=ABC] to specify the color-sort-order; ids must be separated by "," and can be merged into the same ranking by "+" (e.g. "0+256,3,4")
  
• [step/equalWidth=0/1] to make width of all columns in one container the same.
  
• [step/fillWidth=0/1] to to make multi-column container use the complete available width.
  
• New command "dirbom" to build a BOM manually (if you want the BOM to be in special order, want to replace parts or set special part rendering parameters, want to ensure page/column breaks...).
  
• New directive concept, at the moment only directive "pli" is available to build pli manually (if you want the PLI..., see "dirbom").
  
• Added tooltips for most options in the GUI.
  

[Stefan Frenz]

Examples for "color sorting" and "explicit pli".

default color order is ascending color id:

   

same sort rank for black and rubber black via "0+256,..." (rubber black and black are treated to be equal for sorting)

Code:

0 !LDINSP INSTR [doc/colorOrder=0+256,1,4,7,14]

   

different sort rank for all colors via "0,256,..." (only tire position differs: now rubber black is after black)

Code:

0 !LDINSP INSTR [doc/colorOrder=0,256,1,4,7,14]

   

default pli for minifig in step 6:

  Screenshot_4_defaultPLI.png (Size: 6.47 KB / Downloads: 101)

explicit pli (as all parts in step 6 are in different colors, this re-sorting could be done also by changing the color order, but color order is global; additionally with INSTRDIR "pli" the complete appearance of the pli can be changed including part name, zoom, rotation or part count, skipping parts or adding different ones)

Code:

0 !LDINSP INSTRDIR [type=pli] [part=3815c01.dat] [color=0] [count=1]
0 !LDINSP INSTRDIR [type=pli] [part=603-1 - body.ldr] [color=4] [count=1]
0 !LDINSP INSTRDIR [type=pli] [part=3626ap01.dat] [color=14] [count=1] [rotX=15.0] [rotY=0.0]
0 !LDINSP INSTRDIR [type=pli] [part=3842a.dat] [color=1] [count=1]

  Screenshot_5_explicitPLI.png (Size: 6.44 KB / Downloads: 104)

explicit pli with [newLine] option

Code:

0 !LDINSP INSTRDIR [type=pli] [part=3815c01.dat] [color=0] [count=1]
0 !LDINSP INSTRDIR [type=pli] [part=603-1 - body.ldr] [color=4] [count=1]
0 !LDINSP INSTRDIR [type=pli] [part=3626ap01.dat] [color=14] [count=1] [newLine] [rotX=15.0] [rotY=0.0]
0 !LDINSP INSTRDIR [type=pli] [part=3842a.dat] [color=1] [count=1]

  Screenshot_6_explicitPLInewLine.png (Size: 6.53 KB / Downloads: 102)

[Jaco van der Molen]

OK, this looks very nice! I will certainly give it a try.

[Stefan Frenz]

I would happy to read about what you like and what you are missing

[Stefan Frenz]

There is a new current version which now supports explicit pli annotation (or as before: automatic ones) and supports explicit bom description text (or as before: default text with amount and part description).

Each pli directive can have the new parameter "annotate" like this

Code:

0 !LDINSP INSTRDIR [type=pli] [part=3001.dat] [color=15] [count=3] [annotate=Test]

This will be rendered as:

  Screenshot_1.png (Size: 4.17 KB / Downloads: 76)

Each bom command (complete bom or direct bom) can have the new parameter "text" like this

Code:

0 !LDINSP INSTRCMD [cmd=bom] [textwidth=9000] [text=%ax %n in %c\n%d]

where the text is plain text with the following substitutions:

• \n becomes a new line
  
• %n becomes the plain part name (e.g. "3001")
  
• %N becomes the full part name (e.g. "3001.dat")
  
• %c becomes the color name (e.g. "white" - can be replaced appropriate color file)
  
• %C becomes the color id (e.g. "15")
  
• %a becomes the count
  
• %d becomes the part description (e.g. "Plate 2 x 4")
  

Using a format string "%ax %n in %c\n%d", a section of the bom of 603 looks like this:

  Screenshot_2.png (Size: 21.6 KB / Downloads: 76)

[Stefan Frenz]

There is a new current version which now supports a new command "image" to add an arbitrary model/step image. The GUI now has better help while editing commands and directives.

So for example, adding a title page can be done by adding something like

Code:

0 !LDINSP INSTRCMD [cmd=image] [before] [maxWidth=19000] [maxHeight=27700] [zoom=2.0] [shiftX=-1100.0] [shiftY=2200.0]
0 !LDINSP INSTRCMD [cmd=break] [before] [page]

in the first step of the main model. In the given example, the page is in portrait orientation, the model will be zoomed by factor 2.0 and shifted -1100/2200 to avoid cutting relevant pixels off.

[Stefan Frenz]

Thank you, Philippe, for your very helpful feedback and your test file.  

With Philippe's permission, I would like to point out the main steps to get instructions like these:

1. Define default parameters, especially the zoom factor (and inl/zoom for inlined sub-models) has large impact. Here: zoom is between 1.5 and 1.8, the page layout is portrait instead of landscape, automatic annotation for PLI is enabled.
   
2. Enable "debugInfo" switch to have a backlink from the created instructions to your model.
   
3. Move "real" single parts into sub-files, for example technic joint parts or minifigure torsos.
   
4. Activate "aspart" switch for all top-level inlined parts like motors with cables (only the top-level ldr needs "aspart" switch to be turned on). Here for example for technic turntable and torso with hands.
   
5. Activate "inline" switch for small sub-models which are to small to have their own step. Here for example in step 58.
   
6. Define PLI/BOM replacement parts, for example to cables and hoses in non-buckled version. Here for example for technic joint parts in step 67, the motor with cable in step 28.
   
7. Build instructions.
   
8. Change render-parameters where needed, explicitly define PLI/inline box width.
   
9. Maybe temporarily enable "step/info" switch to have more information, for example about created PLI boxes. This helps if you want to define the PLI parts manually, perhaps if in a single step there are sub-models and additional single parts combined, like in step 24.
   
10. Maybe add vertical and/or horizontal lines, like on page 2 and 3.
    
11. Go back to step 3 until satisfied. Unfortunately this is very iterative, but can be limited if you focus first on the rendered images, then the PLI boxes, then the page layout.
    
12. Disable "debugInfo" switch and do a last rendering.
    
13. Fine-tune in ODG-editor like LibreOffice to add real-world images, more text or page numbers, move inline-boxes and add arrows. Here: title page is designed outside LDInstruction.
    

As long as there is only one step on one page, this should be straight forward. But if there are multiple steps on one page or even two columns (for example here: steps 1-9), the rendered image size has large impact on page breaks.

Everything can be done in the GUI. But if you like to know what is done internally, the following snippets show interesting lines that were added to the LDraw file:

Code:

0 !LDINSP INSTR [doc/dpi=150]
0 !LDINSP INSTR [doc/width=21000] [doc/height=29700] [doc/margin=1000]
0 !LDINSP INSTR [doc/bgModel=CFEFFF] [doc/bgPli=BFDFFF] [doc/bgSub=FFF0CF]
0 !LDINSP INSTR [default/maxWidth=20000] [default/maxHeight=14000]
0 !LDINSP INSTR [default/lineWidth=1]
0 !LDINSP INSTR [default/zoom=1.5]
...
0 !LDINSP INSTR [default/inl/zoom=1.5]
0 !LDINSP INSTRSC [scope=11478.dat] [pli/rotY=45]
...
0 !LDINSP INSTRSC [scope=41677.dat] [pli/rotY=45]
0 !LDINSP INSTRSC [scope=6632.dat] [pli/rotY=45]
0 !LDINSP INSTR [maxWidth=14000] [maxHeight=20000]
0 !LDINSP INSTR [centerX=0] [centerY=-36.626] [centerZ=-12]
...
0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/vLines=1] [step/hLines=1]
0 !LDINSP INSTR [step/maxColumns=1] [step/maxRows=0]
0 !LDINSP INSTRCMD [cmd=image] [before] [maxHeight=27700] [zoom=2.0] [shiftX=-1100.0] [maxWidth=19000] [shiftY=2200.0]
0 !LDINSP INSTRCMD [cmd=break] [before] [page]
0 !LDINSP INSTRCMD [cmd=text] [before] [text=Santa Clock (c) Philippe Hurbain]
...
0 !LDINSP INSTR [rotX=30] [rotY=-135] [rotZ=0]
0 !LDINSP INSTR [step/noResult=0]
0 !LDINSP INSTR [step/modelX=-1] [step/modelY=-1]
...
0 !LDINSP INSTRDIR [type=pli] [part=10928.dat] [color=72] [count=1]
...
0 !LDINSP INSTR [highlight=1] [highlightRgb=00FF00] [highlightWidth=1]
0 !LDINSP INSTR [step/pliBoxMaxWidth=0]
...
0 !LDINSP INSTR [rotX=30] [rotY=-135] [rotZ=0]
0 !LDINSP INSTR [highlight=1] [highlightRgb=FF0000] [highlightWidth=1]
...
0 !LDINSP INSTRCMD [cmd=break] [page]
0 !LDINSP INSTRCMD [cmd=bom] [maxWidth=10000] [sort=color,width,description,height,name]
0 !LDINSP INSTRCMD [cmd=text] [text=Santa Clock]
0 !LDINSP INSTRCMD [cmd=text] [text=(c) Philippe Hurbain]
...
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]
0 !LDINSP INSTR [step/pliBoxMaxWidth=5500]
...
0 !LDINSP INSTR [step/modelX=-2] [step/modelY=-1]
0 !LDINSP INSTR [step/newRow=1]
0 !LDINSP INSTR [step/vLines=1] [step/hLines=1]
0 !LDINSP INSTR [step/maxColumns=0] [step/maxRows=0]
0 !LDINSP INSTR [step/fillWidth=1]
0 !LDINSP INSTR [step/pliBoxMaxWidth=3900]
...
0 !LDINSP INSTR [step/pliSort=h,c,d,w,n]
0 !LDINSP INSTR [pli/maxWidth=7000] [pli/maxHeight=7000]
...
0 !LDINSP INSTR [tg/replace=76348.dat]
...
0 !LDINSP INSTR [aspart]
...
0 !LDINSP INSTR [inline]

[Stefan Frenz]

The current version has some new features to fade out previous steps:

• fadeoutRgb: rgb value as fadeout target (default FFFFFF: white)
  
• fadeoutFacesPercent: integer value 0..100 specifying the fadeout impact towards fadeoutRgb (default 0: no fadeout)
  
• fadeoutTransPercent: integer value 0..100 specifying the transparency multiplier (default 0: transparency not changed)
  

Fadeout and highlighting are independent and combinable, some examples are shown below.

Default (standard highlighting, no fadeout):
   

Standard highlighting, 50% fadeout towards FFFFFF:
   

Standard highlighting, 75% fadeout towards FFFFFF, 75% transparency:
   

No highlighting, 75% fadeout towards 7F7F7F, 75% transparency:
   

Different fadeout values may support understanding a building step with hidden elements like step 57 in Philippe's Santa clock:
Standard highlighting, 65% fadeout towards FFFFFF, 85% transparency for step 57 only:
   

[Cam's Bricks]

I have downloaded this and looked at the various examples but I cannot seem to get anything like the examples. I am coming from LPub3D so please excuse my ignorance but Is there no way to see each page in the program? 

I am also not seeing any PLI or an easy way to create callouts or effectively use submodels.