Tools to Save Your MindStorm Models

If you've done much work with Lego bricks, you've probably built some models you felt were outstanding -- good enough to save for posterity. You might have wanted to describe how to build the model for other people, or simply to rebuild it yourself some time in the future.

Lego supplies excellent instructions with their sets. These are full color, carefully drawn instructions, usually showing the parts needed for each step and including handy arrows that describe where everything goes. Being an international company, Lego makes the pictures very explicit so they don't rely on a particular language. If you own Lego sets, take some time to appreciate the instructions that Lego provides. They're extremely clear.

What about the rest of us? How can we create Lego building instructions? There are suprisingly good tools available for free on the Internet. Lego enthusiasts form a very strong community on the Internet, and some of them are good programmers too. In this article, I'll describe how you can use several of the available tools to create high-quality building instructions. See the list at the end of this article for links to these tools.

LDraw and LEdit

Figure 1. This screenshot of LDraw shows the arm subassembly from Minerva, a robot from The Unofficial Guide to Lego MindStorms Robots. (click on image to view full size)

Any story about computer-generated building instructions has to begin with LDraw and LEdit. These DOS applications were created by the late James Jessiman in 1996. LEdit is a program for creating model instruction files, while LDraw is the program that displays them. Models are described as a series of steps, and LDraw is capable of showing the model being built, one step at a time.

The next screenshot shows the same model in LEdit. At the top of the screen you can see actual lines from the model file (more on this soon). Within LEdit, you can add parts to a model, remove parts, move and rotate parts, and change the colors of parts. You can also insert markers that signify a complete step.

Figure 2. The same arm subassembly viewed in LEdit. (click on image to view full size)

LEdit and LDraw are good tools, but it takes some time to learn how to use them. LEdit, in particular, has a pretty steep learning curve. The important legacy of LEdit and LDraw is their file format, which we'll examine next.

The DAT file format

LDraw and LEdit models are stored in "DAT files," with a .dat file extension. This file format is the center of most subsequent work in the Lego modeling software world. No matter what tools you use, you may very well find yourself staring at a DAT file in a text editor someday, so a basic understanding of the format is useful.

The file format encompasses two functions:

• part modeling and
• model building.

Figure 3. Image of a two-stud Technic brick and a 2 x 4 plate, the basis for the DAT file.

Individual Lego bricks can be modeled as DAT files by assembling collections of lines and surfaces. DAT files can reference other DAT files, so a complex brick can be built up from simpler pieces. A regular brick DAT file, for example, might reference another DAT file that represents the studs, or bumps, on the brick.

A Lego model DAT file is built by referencing the individual brick DAT files that make up the model. Let's look at a simple example. The model in Figure 3 is built from two bricks

Here's the DAT file for this simple model:

0 Untitled
0 Name: simple.dat
0 Author: MLCad
0 Unofficial Model
1 14 0 0 0 1 0 0 0 1 0 0 0 1 3020.DAT
1 0 0 -24 10 1 0 0 0 1 0 0 0 1 3700.DAT
0

You can pretty much figure it out by looking at it. Every line has a type, which is just a number at the beginning of the line. A 0 indicates a comment line, something that adds information to the DAT file but doesn't add to the model itself. The two important lines begin with a 1, which imports another DAT file into the model. In this case we're using 3020.DAT, the 2 x 4 plate, and 3700.DAT, the two-stud Technic brick with the hole through it. What are all those other numbers on those lines? Those show where the imported part should be placed and how it should be rotated relative to the model.

Complex model files look a lot like this simple one, just with many more "1" lines.

The DAT files for bricks are named according to their part numbers. Most bricks have numbers molded into them; you can see these numbers if you look closely. Over the years, the online Lego community has modeled (that is, created DAT files for) more than 1,500 bricks. If you can't find a brick DAT file, sometimes friendly folks on the Internet will create it for you.

An important extension of the DAT format, the Multiple Part DAT (MPD) file, allows you to specify multiple subparts inside a single file. For example, the entire Minerva robot model is represented in a file called Minerva.mpd. Inside this file, a subassembly called MinervaArm.dat is defined. It is used as a component of the entire model.

The next generation: MLCAD

Now let's look at the next step beyond LEdit. I like to use a Windows program called MLCAD. (There are other options, but this is the one I know about.) The bottom line is that MLCAD is a souped-up DAT or MPD file editor. But you can also think of it as a specialized computer-aided design (CAD) tool. MLCAD shows several different models at once and lets you move pieces around using the mouse. It also shows a portion of the DAT or MPD file you're working on and provides palettes of bricks to make it easy to find the right piece.

Figure 4. The same Minerva arm model in MLCAD, a Windows DAT/MPD file editor. (click on image to view full size)

Using MLCAD, you can build complex models quickly. It gets a little sluggish after you've added a lot of pieces, but it's still usable.

Important Glue: l3p

The gap between the world of DAT files and the world of POV-Ray is filled by a little DOS utility called l3p, developed by Lars Hassing. The usage is pretty simple: Just supply a DAT file and l3p creates a POV-Ray file for you. For example, the two-brick model we looked at before can be converted like this:

l3p simple.dat

l3p will chug a little and create a simple.pov file which can be immediately rendered in POV-Ray.

There are a couple of things you should know about l3p. First, it can only deal with eight-character filenames. Second, there are a couple of command-line options that I find useful. The -b option allows you to specify a background color (as red, green, and blue components) for the model. I usually use white, like this:

l3p -b1,1,1 simple.dat

Finally, the -o option specifies that if the POV-Ray file already exists, it should be overwritten:

l3p -b1,1,1 -o simple.dat

POV-Ray

To create a scene in POV-Ray, just load the .pov file. It will show up in POV-Ray's text editor. You can choose an image size from the drop-down list on the toolbar. Then click the Run button and sit back while your scene is drawn.

POV-Ray has its own language for describing scenes and how they should be drawn. Without knowing the entire language, there are some things you can tweak. The camera angle and the lighting are the most important adjustments.

The camera angle is defined in a block near the end of the .pov file generated by l3p. Here's a typical example:

camera {
#declare PCT = 0; // Percentage further away
  #declare STEREO = 0; // Normal view
  //#declare STEREO =  degrees(atan2(1,12))/2; // Left view
  //#declare STEREO = -degrees(atan2(1,12))/2; // Right view
  location vaxis_rotate(<55.3377,-33.905,-43.7907> +
               PCT/100.0*<44.4925,-36.328,-44.4925>,
               <-1616.32,-3959.17,1616.32>,STEREO)
  sky      -y
  right    -4/3*x
  look_at  <10.8452,2.423,0.701839>
  angle    67.3801
  //orthographic
}

Perspective

The default view is a perspective view, which ends up looking like this:

Figure 5. Default, perspective view of the two bricks shown in Figure 3.

This is not really what we want for the building instructions. Instead, I use something called an orthographic view. It's not as realistic, but it shows the same piece the same size in different places in the model. In general, it's easier to interpret for building models than a perspective view. (Official Lego instructions use an orthographic view.) To see the orthographic view, just uncomment the orthographic keyword by removing the two slashes from its front:

camera {
   #declare PCT = 0; // Percentage further away
   #declare STEREO = 0; // Normal view
   //#declare STEREO =  degrees(atan2(1,12))/2; // Left view
   //#declare STEREO = -degrees(atan2(1,12))/2; // Right view
   location vaxis_rotate(<55.3377,-33.905,-43.7907> +
     PCT/100.0*<44.4925,-36.328,-44.4925>,
     <-1616.32,-3959.17,1616.32>,STEREO)
   sky      -y
   right    -4/3*x
   look_at  <10.8452,2.423,0.701839>
   angle    67.3801
   orthographic
}

Now our model looks like this:

Figure 6. Orthographic view of the same two bricks.

Camera position

Figure 7. Same model after substituting straight coordinates for vaxis data. Bricks appear too far away (small).

Now we need to monkey with the camera angle so we can see the whole model. The two things we want to change are the location and look_at keywords. l3p automatically sets up look_at to point at the center of your model, so you don't usually need to adjust it drastically. I don't really understand the vaxis_rotate stuff that l3p puts in for location, so I generally take it out and substitute straight coordinates, like this:

camera {
   location <100, -100, -100>
   sky      -y
   right    -4/3*x
   look_at  <10, 0, 0>
   angle    67.3801
   orthographic
}

This produces the output in Figure 7.

Usually I adjust the location and look_at numbers by trial and error until the model is framed well and displayed at an angle I like. While you're adjusting these things, you should use a small image size setting in POV-Ray so it doesn't take forever to render each frame. To really speed things up while you're fiddling with the camera angle, you might consider changing the QUAL setting at the very beginning of the .pov file you're working on. Setting QUAL to 0 displays every brick as its bounding box, which makes rendering very fast.

Figure 8. Same model after changing camera location to bring model "closer."

The above model is too far away, so I will adjust the camera location vector by multiplying it with a scalar. This moves the camera closer or farther from the model without changing any of the angles.

camera {
   location .6 * <100, -100, -100>
   sky      -y
   right    -4/3*x
   look_at  <10, 0, 0>
   angle    67.3801
   orthographic
}

The results (Figure 8) are satisfactory.

Lighting

Once you've got the camera angle just the way you want it, it's time to start playing with the lights. In the image above, the lighting is not very good. The forward face of the black brick is not lighted well; it's hard to see the hole. Worse than that, however, there are too many shadows. For building instructions, we want the lighting to be very simple.

l3p creates three lights in your .pov file. These are specified just after the camera section, and look something like this:

light_source {
   <0,-61.3755,-51.3755>  // Latitude,Longitude,Radius: 45,0,72.656
   color rgb <1,1,1>
}
light_source {
   <54.492,-46.328,31.461>  // Latitude,Longitude,Radius: 30,120,72.656
   color rgb <1,1,1>
}
light_source {
   <-31.461,-72.9219,18.164>  // Latitude,Longitude,Radius: 60,-120,72.656
   color rgb <1,1,1>
}

Figure 9. Same model after repositioning lights.

Basically all you need to do is move the lights until your model is lighted the way you want. Here I've moved them so there's one in front of the model, one on the front side, and one behind and above the hole in the black brick. The shadowless keyword is used to specify a light source that illuminates but casts no shadows.

light_source {
   <25,-100,-50>
   color rgb <1,1,1>
}
light_source {
   <-50,-50,-50>
   color rgb <1,1,1>
   shadowless
}
light_source {
   <10,-25,25>
   color rgb <1,1,1>
   shadowless
}

Figure 9 shows the result of the new lighting.

Lighting is tricky. You will need to practice for a while until you get things the way you want them.

Creating building instructions

Now you understand how to create a high-quality image of a Lego model. Creating a whole series of instructions is just a tedious repetition of these basic steps. To create the online instructions for the robots from my book (http://www.oreilly.com/catalog/lmstorms/building/), for example, I followed these steps:

1. I use MLCAD to create an MPD file for the entire model.
2. Using a text editor, I cut and paste from the original MPD to create a DAT or MPD file representing each step in building the model.
3. I also use a text editor to pull out the parts needed for each step. Then I edit the parts files in MLCAD to lay them out nicely.
4. The step files and parts files are converted to .pov files using l3p.
5. Inside POV-Ray, I edit the camera angle and lights for the completed model until I am happy. Then I copy the camera and lights settings to each step file. I modify the camera and lights slightly and apply the new settings to each of the parts files. For complex models, some steps have to show different views of the model, so these have to be adjusted separately.
6. For certain pieces, like tires or treads, the default materials don't look right. By default, l3p makes all the bricks look shiny, but tires and treads need to look like rubber. For this, I manually create a new material and substitute it in for the tires and treads.
7. I use POV-Ray's file queue to render all of the step and parts files while I go to have lunch.
8. Then I crop each image using Adobe PhotoDeluxe. I would use a real tool like Photoshop or GIMP, but I don't have either one.
9. I add text to the parts images using PhotoDeluxe.
10. I save all the images as JPEGs.
11. Then I use Netscape Composer to create the HTML pages containing the images.

It's a tedious process, but I'm very pleased with the results.

Jonathan Knudsen is an author at O'Reilly & Associates. His books include The Unofficial Guide to Lego MindStorms Robots, Java 2D Graphics, and Java Cryptography.

Discuss this article in the O'Reilly Network MindStorms Forum.

Return to the O'Reilly Network Hub.

Copyright © 2007 O'Reilly Media, Inc.