File Extensions
LDraw Model files carry either the extension LDR (default) or DAT. LDraw Part Files carry the extension DAT.
Text-Based
LDraw files are plain text. Each line is a single command, and each line is independent. Only a few commands are used in the file format. Specific commands are identified by the first number on the line, which is called the line-type. The contents and format of the rest of the line depend on the line-type. No length-limit on command lines is known.
Line types
Each line in the file is a single command. The first number on each line is the line type, valid values are 0 through 5, with the following meanings:
- 0:
- comment or meta-command
- 1:
- Part-file reference
- 2:
- Line
- 3:
- Triangle
- 4:
- Quadrilateral
- 5:
- Draws a line between the first two points, if the last two points
are on the same side of that line.
If the line type for a line is not a valid value, the line is ignored.
Meta-commands require a keyword to follow the line-type. These keywords must be in all-caps, and you should assume that if the meta-command doesn't require more information, you shouldn't give it any additional information.
Commands
Here is a complete list of LDraw drawing- and meta-commands:
- Model Title
- Step
- Write
- Clear
- Pause
- Save
- Comment
- File Type
- Part
- Line
- Triangle
- Quadrilateral
- Conditional-Line
And here are the details of each command. Meta-commands are listed first, with the "real" commands after. The command-names are wholly made up by me, I don't have any "official" names for these things.
- Model Title.
-
The descriptive name of the model- or part-file.
- Line format:
0 title-text
where title-text is whatever you want to name your model.
- This is a meta-command, sort of. If the first line in a file
has line-type 0, the remainder of that line will be considered the
title for the file (at least for parts files). This overrides any
meta-commands on the line.
- Step meta-command.
-
Marks the end of a building step.
- Line format:
0 STEP
- This command will cause LDraw (ldraw.exe) to stop until you press
<enter>, and it will cause LDraw to save the current image into a
bitmap file in the
ldraw\bitmap directory. These two
effects are controlled by the -M command line option (see
ldraw.doc for info on -M).
- Write meta-command.
-
Displays a message at the top of the screen.
- Line format:
0 WRITE message-text
- or:
0 PRINT message-text
where message-text is whatever you want displayed on the screen.
The displayed message is not saved in the image-bitmap files.
Clear meta-command.
Clears the screen.
- Line format:
0 CLEAR
Useful for advanced model files. Don't forget to redraw all the
parts you just erased by using this command.
Pause meta-command.
Causes LDraw to stop until you press <enter>.
- Line format:
0 PAUSE
This is like the Step command, but it does not save bitmaps, and it
is not affected by the -M command line option.
Save meta-command.
Causes LDraw (ldraw.exe) to save the current image in a bitmap.
- Line format:
0 SAVE
This is also like the Step command, but it does not cause LDraw to
pause, and it is not affected by the -M command line
option.
File Type meta-command.
Indicates the type of file (model, part, etc), and if it is part of
the LDraw.org Parts Library.
-
Line format:
-
0 LDRAW_ORG type update-tag
or: 0 Official LCAD type update-tag
or: 0 Unofficial type
or: 0 Un-official type
This meta-statement should appear as the last line of the primary
file header (that is, the first lines in the file, with the Model
Title, Name: and Author: lines). The first format (LDRAW_ORG) is
the current standard for files in the official parts library.
Older files still carry the second (Official LCAD) format.
The valid values for the type field are:
- Part *
- Element -
- Subpart *
- Sub-part -
- Primitive *
- Shortcut *
- Alias *
- Cross-reference +
- Model -
- Submodel -
- File -
- Hi-Res Primitive -
- * = values currently in use for official part files.
- + = obsolete code, still appears on some official files.
- - = only used in unofficial files
Some older official files do not include a type code on their
File Type line. Unofficial files may have a variety of values
after the initial tag. In particular, the type values of Element,
Model, and Submodel may be used.
The exact format of the File Type line has changed over time.
In general, this linetype should be considered case-insensitive
and free-format.
Part command.
Inserts a part defined in another LDraw file.
- Line format:
1 colour x y z a b c d e f g h i part.dat
where
- colour is a colour code: 0-15, 16, 24, 32-47, 256-511
- x, y, z is the position of the part
- a - i are orientation & scaling parameters (see below for
more on this)
- part.dat is the filename of the included file
Parts may located in the p\, parts\, or
models\ subdirectories (under the ldraw\
directory). They may also be located in the current directory. James
has arranged the directories so that p\ contains elements
that are intended to be used as part of elements (such as
stud.dat). The parts\ directory contains
finished parts, ready to be used in construction models. And the
models\ directory contains construction models.
Part files can also include Part commands. There don't seem to be a
specific limit to how deep these references can go.
Line command.
Draws a line between two points.
- Line format:
2 colour x1 y1 z1 x2 y2 z2
where
- colour is a colour code: 0-15, 16, 24, 32-47, 256-511
- x1, y1, z1 is the position of the first point
- x2, y2, z2 is the position of the second point
Triangle command.
Draws a filled triangle between three points.
- Line format:
3 colour x1 y1 z1 x2 y2 z2 x3 y3 z3
where
- colour is a colour code: 0-15, 16, 24, 32-47, 256-511
- x1, y1, z1 is the position of the first point
- x2, y2, z2 is the position of the second point
- x3, y3, z3 is the position of the third point
Quadrilateral command.
Draws a four-sided, filled shape between four points.
- Line format:
4 colour x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4
where
- colour is a colour code: 0-15, 16, 24, 32-47, 256-511
- x1, y1, z1 is the position of the first point
- x2, y2, z2 is the position of the second point
- x3, y3, z3 is the position of the third point
- x4, y4, z4 is the position of the fourth point
Conditional-Line command.
Draws a line between the first two points, if the projections of the
last two points onto the screen are on the same side of an imaginary
line through the projections of the first two points onto the screen.
- Line format:
5 colour x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4
where
- colour is a colour code: 0-15, 16, 24, 32-47, 256-511
- x1, y1, z1 is the position of the first point
- x2, y2, z2 is the position of the second point
- x3, y3, z3 is the position of the third point
- x4, y4, z4 is the position of the fourth point
Colours
Colours are outlined in LEDIT.DOC. Two special values are 16 and 24. 16 is the 'current colour', i.e., whatever colour was specified on the type 1 line which caused the current line to be executed. Colour 24 is a complementary colour to the current colour, usually the bright/dark complementary shade. So if the current colour is dark blue, colour 24 would give bright blue.
Also, colours 256 through 511 are dithered. So if you want to combine colours J and K, figure your colour value as
colour = (J * 16) + K + 256
The complementary colour of J is used as the complementary colour of the dithered value. So you can control the edge colour (somewhat) by switching J and K.
Format of Linetype 1
The Part command (linetype 1) has some unique features that require special
attention. This section makes more sense if you're familiar with matrix
math. It makes much more sense if you're familiar with using matrix math
in graphic modeling.
- Line Format:
1 colour x y z a b c d e f g h i part.dat
Fields a through i are orientation & scaling parameters, which can be used in 'standard' 3D transformation matrices. Fields x, y and z also fit into this matrix:
| a d g 0 |
| b e h 0 |
| c f i 0 |
| x y z 1 |
so that every point (x, y ,z) gets transformed to (x', y', z') :
x' = a*x + b*y + c*z + x
y' = d*x + e*y + f*z + y
z' = g*x + h*y + i*z + z
or, in matrix-math style:
| a d g 0 |
| X' Y' Z' 1 | = | X Y Z 1 | x | b e h 0 |
| c f i 0 |
| x y z 1 |
Explanation of Conditional Lines (Linetype 5)
Here is an example using the conditional line command. If we try to approximate
a (cylindrical) stud with a hexagonal prism we have something like this:
1___________2
/ \
/ \
6/ \3
|\ /|
| \ / |
| \5___________4/ |
\ | | /
\ | | /
\|___________|/
- The line below 1 should not be drawn because 6 and 2 are on
different sides.
- The line below 2 should not be drawn because 1 and 3 are on
different sides.
- The line below 3 should be drawn because 2 and 4 are on the
same side.
- The line below 4 should not be drawn because 3 and 5 are on
different sides.
- The line below 5 should not be drawn because 4 and 6 are on
different sides.
- The line below 6 should be drawn
because 5 and 1 are on the same side.
resulting in the following drawing:
1___________2
/ \
/ \
6/ \3
|\ /|
| \ / |
| \5___________4/ |
\ /
\ /
\_____________/
For questions, contact Steve Bliss.
