LDraw.org - Centralized LDraw Resources

  Download | Reference | Community | Parts Library | Login

  Tutorials | Books | Documentation | Specifications | FAQ | Glossary | Help Desk

Reference: Tutorials: Creating High Quality Building Instructions

Creating High Quality Building Instructions
By: Jonathan Knudsen

[Editor's note: This tutorial was formerly named "Drawing LEGO Models." It was renamed by the LDraw.org staff to better fit the new tutorial section organization structure.]

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 realy 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? The answer is that 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. At the end, the URLs for the tools I've described are presented.

LDraw and LEdit
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.

Screenshot: LDraw featuring the arm subassembly of the Minerva robot, from The Unofficial Guide to LEGO MINDSTORMS Robots.

Screenshot: The same model, in LEdit.

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 following screen shot 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.

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 function: part modeling and model building. Individual LEGO bricks can be modeled as DAT files by assembling collection 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 following model 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 2x4 plate, and 3700.DAT, the 2 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 based on 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 (i.e. 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.

Screenshot: MLCad featuring the Minerva Arm 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 allows you to 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.

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
LDraw and MLCAD can display models, but the image quality is not great. To generate professional-looking images, like the ones in the official LEGO instructions, you'll need to use POV-Ray, a raytracer. This is a program that can create highly realistic computer-generated scenes.

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 dropdown 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
}

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

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:

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 following output:

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.

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 are satisfactory:

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>
}

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 and 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
}

And here is 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
You now 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.

For More Information
This article skims over the top of several deep subjects: part modeling, DAT files, and POV-Ray. If you'd like to learn more, there's plenty of information out there.

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.

 



  Tutorials | Books | Documentation | Specifications | FAQ | Glossary | Help Desk

© 2003 LDraw.org. See Legal Info for details.

In Memory of James Jessiman - 1971-1997