LDraw is the name for James Jessiman's CAD system for modelling LEGO creations. It started as a very simple DOS application with a simple text-based file format. Today, LDraw is not just an application but a system, with the LDraw file format being used by many third party editors (such as LeoCAD and MLCad), model viewers, converters and renderers.

The LDraw file format

LDraw's file format is traditionally known by its .DAT extension. Recently the extension was changed to .LDR to prevent ambiguity. Older applications were hardcoded to use .DAT, so the two currently exist in parallel.

The format is so simple that, with either patience or genius, you can could even create LDraw models in a text editor. Geeks love the format, because it is perfect for grokking with Perl. Here's an example of an LDraw model file


0 An example LDraw model
0 Author: TallRoo
1  4  0   0  0    0  0 -1 0 1 0 1 0 0  3622.DAT
1  4  0   0  -60  0  0 -1 0 1 0 1 0 0  3622.DAT
1  4  40  0  20   -1 0 0  0 1 0 0 0 -1 3622.DAT
1  4  40  0  -30  -1 0 0  0 1 0 0 0 -1 3622.DAT
1  4  40  0  -80  -1 0 0  0 1 0 0 0 -1 3622.DAT
0 STEP                
1  4  130 0  0    -1 0 0  0 1 0 0 0 -1 3063.DAT
1  4  150 0  0    0  0 -1 0 1 0 1 0 0  3063.DAT
1  4  150 0  -20  1  0 0  0 1 0 0 0 1  3063.DAT
1  4  130 0  -60  -1 0 0  0 1 0 0 0 -1 3063.DAT
1  4  140 0  -80  -1 0 0  0 1 0 0 0 -1 3010.DAT
0 STEP

Each row represents a new piece, a comment or a step. The example model above uses only 3 different parts, which might give you a clue as to what it looks like. Part 3622 is a 1 x 3 brick. 3063 is a round 2 x 2 corner brick and 3010 is a 1 x 4 brick

Each column means something different. Here's the last line of the model again, with a key to each column's meaning.

1  4  140 0  -80  -1 0 0  0 1 0 0 0 -1 3010.DAT
A  B  C   D  E    |<-------F-------->| G
  1. Line type (0 = comment, 1 = new piece)
  2. Colour (see below for colour values)
  3. X coordinate
  4. Y coordinate
  5. Z coordinate
  6. Rotation matrix
  7. Part filename
A line beginning with a 0 is a comment. However, some comments have special meaning. The most commonly used 'special' comment is "0 STEP". Steps are used to separate building instructions, in the same way that real LEGO building instructions consist of building steps. Multiple parts may be added to the model in each step.

So each piece is added to the model in turn, with pauses possibly being added (depending on the application used) at each STEP point. Each piece's colour is set, along with its coordinates and orientation. Interestingly, the coordinate system used in LDraw files is different to what you might be expecting. The XZ plane represents the floor, while (negative) Y is used as 'up'. This is why the value for the Y coordinate, and not the Z coordinate, is 0 in all of the pieces in this flat example model.

The final column tells the application what part is being added, with a unique part number being assigned to each LEGO part. There are around 700 unique parts today. As new pieces are added to the LEGO universe, LDraw needs to have its parts library updated. To make this easy, the pieces are held as files in the LDraw/parts directory.

Parts are composed of primitives, such as box, stud, cylinder, ring, edge etc. Primitives are also externalised as files, in the LDraw/P directory. Some of the primitives are actually made up of other primitives. Stud, for instance, is a compound primitive composed of 2 edges, a cylinder and a disc.

Part and primitive files always use the .DAT extension (never .LDR, even in this new age of .LDR models). Regular parts updates containing the newest files are available from LDraw.org. It is also possible, via the LDraw website, to track the progress of new parts as they are submitted to the community and approved. 'Unofficial parts', which have not yet been approved by the LDraw community's voting process, are downloadable individually or as a zip.

Colours

These values are honoured by all editors, viewers and utilities which use the LDraw system.
  1. Black
  2. Blue
  3. Green
  4. Dark cyan
  5. Red
  6. Magenta
  7. Brown
  8. Grey
  9. Dark grey
  10. Light blue
  11. Light green
  12. Cyan
  13. Light red
  14. Pink
  15. Yellow
  16. White
  17. Null-colour
For transparent colours, add 32.
  1. Transparent black
  2. Transparent blue
  3. Transparent green
  4. Transparent dark cyan
  5. Transparent red
  6. Transparent magenta
  7. Transparent brown
  8. Transparent grey
  9. Transparent dark grey
  10. Transparent light blue
  11. Transparent light green
  12. Transparent cyan
  13. Transparent light red
  14. Transparent pink
  15. Transparent yellow
  16. Transparent white
While not all of these colours are used in LEGO pieces, not all of the real-world LEGO colours are covered here either. As conventions about higher-value colours are being arrived at, some editors currently treat values greater than 47 differently.

Applications

The LDraw download contains two DOS-based applications, LEdit and LDraw.
  • LEdit editor

    The LDraw editor, LEdit (LEDIT.EXE), deserves its own writeup, so I will not cover it in too much depth here. Essentially, it is a DOS based interactive modelling program which allows you to place, move rotate and colour LEGO parts in a 3D model. It is reasonably powerful and easy to use. If you have the patience to understand its controls, you will find it a relatively useful modelling tool. The lack of mouse input frustrates many beginners, as does its dated DOS-y appearance.

    Fortunately, several GUI LDraw-compatible editors have emerged which are able to use LDraw's .DAT/.LDR format.

  • LDraw viewer

    The LDraw viewer (LDRAW.EXE) is another DOS based application. It acts as the sister to LEdit, allowing models to be displayed in a DOS window.

    The filename of the model you wish to view is supplied as a command line argument. Like LEdit, the LDraw viewer does not have mouse support. At first glance the LDraw viewer looks very limited. It is true that it has almost no interactivity (the only thing you can do at runtime is to press Enter to display the next step in a multi-part model) but it does actually have some useful command line options. The model can be viewed at different resolutions, against a different background colour and from different angles and zooms. The drawing mode can be changed from the default (pause after each step) to continuous (don't pause) and even to a mode which saves each building step as a bitmap.

    As with LEdit, LDraw has been rather superceded by newer, more user-friendly, viewing utilities which use the LDraw file format. Generally speaking, the newer viewers are able to render the model much more realistically and support many interactive features, such as shading and lighting options, wireframe mode, real-time rotation and so on.

LDraw resources

Some popular URLs
  • http://www.LDraw.org/
    - LDraw downloads and news. Includes links to newer generation editors/utilities/renderers/
  • http://www.LDraw.org/faq/
    - LDraw FAQ
  • http://www.ldraw.org/memorial/archive/howto.txt
    - LEdit primer
  • http://library.thinkquest.org/20551/home.html
    - LEdit tutorial

The first person to correctly /msg me with a description of my example model looks like will have a piece of LEGO posted to them.