Maintained by: The LDraw.org Standards Committee
Author: The LDraw.org Standards Committee
Writers: William Howard [4]
Contributors: Many

Table of Contents

Purpose [5]
LDraw Files [6]
Numeric Precision and Format [7]
Co-planar Tolerance [8]
Colinear Tolerance/Concave Quads [9]
Duplicate Line Types [10]
Overlapping and Intersecting Line Types [11]
Matrix restrictions [12]
Colour restrictions [13]
META Commands [14]
  Header Meta Commands [15]
  Body Meta Commands [16]
Generated line types [17]
Sticker Shortcuts [18]
Line Termination [19]
LDConfig.ldr [20]

Purpose

This document describes additional restrictions to the LDraw File Format 1.0.0 specification for official parts. Unless contradicted by this document all details within the LDraw File Format 1.0.0 specification apply to official parts.

LDraw Files

File Name

Filenames must not be longer than 25 characters (including the extension) and must only contain the following characters: a-z, A-Z, 0-9, _, and - (to avoid confusion with English grammar, comma is not a permitted character). While both upper and lower case letters are permitted in filenames, filenames are case-insensitive. Currently, all official parts are issued with upper-case only names.

Extension

All files in the LDraw Parts Library are required to carry the .DAT extension.

Numeric Precision and Format

Precision

In general, three decimal places are sufficient for parts, sub-parts and primitives representing portions of parts that are not intended to be scaled (for example, studs, pegs, peg-holes, clips, hinge ends, etc). Four decimal places should be used for hi-res primitives and any primitives designed to be scaled (for example, cylinder sections, boxes, rectangles, discs, edges, etc) as this allows such primitives to be scaled by a factor of ten while still preserving three decimal places of accuracy. The primitives reference [21] indicates which primitive families are not supposed to be scaled.

Format

Trailing zeros must be removed (ie 1.5 not 1.500). Leading zeros unless immediately before the decimal point must be removed (ie 1.5 not 01.5). The leading zero before the decimal point is optional (ie 0.5 and .5 are both valid).

Co-planar Tolerance

A quad (line type 4) must be planar, meaning that if it is split into two triangles, both triangles will be co-planar with each other. There are always two ways to split a quad into two triangles, and both must result in co-planar triangles. The triangles are considered co-planar if the angle between their surface normals is less than or equal to 3 degrees, however, an angle of less than 1 degree is strongly recommended, especially for large quads where the "warp" can be seen in the part at normal viewing magnifications. (Note: Parts already in the library or certified on the tracker are not to be re-submitted just to fix any co-planar violations.)

Colinear Tolerance/Concave Quads

A quad (line type 4) or triangle (line type 3) must not have aligned vertices. Additionally, quads should always be convex. (Concave quads should be split into two triangles.) To avoid concave quads, as well as aligned vertices in triangles and quads, every interior angle in a quad or triangle must not be greater than 179.9 degrees or smaller than 0.025 degrees. (Note: Parts already in the library or certified on the tracker are not to be re-submitted just to fix any colinear violations.)

Duplicate Line Types

Identical sub-files (line type 1) are not permitted.

Identical lines and conditional lines are not permitted. The order of end points is not considered when checking for identical lines (line types 2 and 5). Control points are not considered when checking for identical conditional lines (line type 5).

Identical triangles and quads are not permitted. The ordering of vertex points is not considered when checking for identical polygons (line types 3 and 4).

Overlapping and Intersecting Line Types

All or part of a line (line type 2) may not overlap all or part of any other line (line type 2).

All or part of a conditional line (line type 5) may not overlap all or part of any other conditional line (line type 5).

Part (but not all) of a conditional line (line type 5) may overlap all (but not part) of a line (line type 2).

Consider the line A-B-C-D

If AB and CD need to be conditional lines and BC a line, it is acceptable to define this as a line BC and a single conditional line AD

If AC needs to be a line and just CD needs to be a conditional line, it is not acceptable to define the conditional line as either AD or BD

If AD is a line, there are no valid conditional lines along the length of AD

Lines (line type 2 or 5) may intersect any other line (line type 2 or 5).

Every effort must be made to remove overlapping co-planar polygons (line type 3 or 4). Where overlapping polygons are unavoidable, the overlap must be kept to the absolute minimum.

Every effort must be made to remove intersecting (non co-planar) polygons (line type 3 or 4). Where intersecting polygons are unavoidable, the intersection(s) must be kept to the absolute minimum.

Note: Primitives that overlap/intersect other primitives or polygons (line type 3 or 4), provided that the overlap is small, are considered acceptable. The intention is not to force part authors to in-line primitives. However, there may be some cases where it is better to use (say) a 3-8cyli and a quad than a 1-2cyli; case-by-case decisions are left to the parts review process.

Matrix restrictions

The matrix specified for sub-files (line type 1) must not be singular nor contain columns or rows of all zeros.

Colour restrictions

Polygons (line types 3 and 4) must not use colour 24.

Lines (line types 2 and 5) should not use colour 16.

There are two cases where use of colour 16 for lines is acceptable,

where a line is being used for fine detail within a pattern and that pattern is re-used within many parts (and hence sub-parted) in different colours (for example, sub-part s/973p11a.dat)

when a sub-part pattern leaves a narrow gap of base-part colour around the pattern(for example, see sub-part s/973p11b.dat)

All colour numbers used in part files must be present in LDConfig.ldr, with the exception of pattern/sticker geometry, which may use Direct Colours (see LDraw Spec [22]).

The following should go at the end of the Colours section of the official 1.0 LDraw spec.

Direct Colours

Direct Colours are colour numbers that represent RGB values using the form 0x2RRGGBB, where RRGGBB is the exact RGB value in hexadecimal notation. For example, 0x2008000 would produce dark green with RGB of (0 red, 128 green, 0 blue). All letters (A-F) used in the specification of RGB values must be in upper case.

LDraw compatible visualization applications shall be capable of displaying Direct RGB Values from Patterned Parts that contain these colours. For applications that support part authoring, it is recommended that the program provide a graphical aid for choosing a Direct RGB Value. The use of Direct RGB Values is discouraged in model authoring. Therefore, applications that support model authoring should favour colours from LDConfig.ldr.

Blended Colours

LDraw compatible visualization applications that once supported dithered colours should continue to do so in the display of parts and models that may contain a dithered colour code. However, dithered colours have been made obsolete and will not be contained within any new official parts. These colours should be removed from any graphical aids for choosing colours, and should not be added to any new graphical aids for choosing colours. New applications are not required to support these colours.

These "dithered" colours are defined based on a modification of ldraw.exe's original behavior that uses RGB blending instead of dithering. The original ldraw.exe drew them as a 50/50 checkerboard dither of two of its standard 16 colours. Since modern computers all support true colour, they will instead be drawn as a blend of the two input colors, which is calculated as the average of two original ldraw.exe colours.

The two input colour indexes are calculated as follows:

n1 = (nb - 256) / 16
n2 = (nb - 256) mod 16

where

n1 is the index of input colour 1, nb is the index of the blended color, and n2 is the index of input colour 2.

Once n1 and n2 are determined, the colour of the blended colour is calculated using the following equations:

Rb = (R1 + R2) / 2
Gb = (G1 + G2) / 2
Bb = (B1 + B2) / 2

where

Rb, Gb, Bb are the red, green, and blue components of the blended colour; R1, G1, B1 are the red, green, and blue components of the first input colour; and R2, G2, B2 are the red, green, and blue components of the second input colour.

The red, green, and blue components of the original 16 ldraw.exe colours are as follows:

0: 51, 51, 51
1: 0, 51, 178
2: 0, 127, 51
3: 0, 181, 166
4: 204, 0, 0
5: 255, 51, 153
6: 102, 51, 0
7: 153, 153, 153
8: 102, 102, 88
9: 0, 128, 255
10: 51, 255, 102
11: 171, 253, 249
12: 255, 0, 0
13: 255, 176, 204
14: 255, 229, 0
15: 255, 255, 255

Going the other direction, the blended colour's colour code is calculated using the following equation:

nb = n1 * 16 + n2 + 256

where

nb is the index of the blended colour, n1 is the index of the first input colour, and n2 is the index of the second input colour.

This is the end of the LDraw spec portion.

META Commands

(See also List of Official META Commands [23].)

Header Meta Commands

Official parts must conform to the Official Library Header Specification [24].

Body Meta Commands

Only the following meta commands are permitted in the body of official parts:

• 0 // style comments
• BFC CW
• BFC CCW
• BFC CLIP
• BFC CLIP CW
• BFC CLIP CCW
• BFC NOCLIP
• BFC INVERTNEXT

Legacy parts may not conform to these rules. Legacy parts (including those already on the Parts Tracker) should not be edited solely for the purpose of making them conform. However, if the part is changed for any other reason, non-conformant lines must be updated.

Generated line types

Lines and polygons generate by a utility program (such as LSynth) must conform to this specification. The meta commands used to generate the line types may be left in the part file provided they are correctly commented out. It is desirable to add a comment to mark the end of the generated section.

Sticker Shortcuts

Shortcuts that consist of one part (which may be a composite part) and one or more stickers are allowed in the official library. Such shortcuts will have a filename consisting of the part number for the part, followed by a "d", followed by a two-digit number that starts at 01 and increases with each new part/sticker shortcut. If the sticker is applied to a composite part, the full composite part filename will be used before the d. For example, the first sticker/part shortcut created for part 30185c01.dat would have a filename of 30185c01d01.dat. The following restrictions apply:

• The shortcut may not include more than one part, although that part can be a composite part (one with a "c" in the filename).
• The sticker(s) must entirely fit on the part, with no portions of the sticker(s) extending beyond the boundaries of the part.
• The sticker(s) must be applied in the same location(s) as shown in the instructions for the official LEGO model from which the sticker(s) originate(s).

Line Termination

All lines in the file must use the standard DOS/Windows line termination of <CR><LF> (carriage return/line feed). The last two bytes of the file must be <CR><LF>. (In other words, there must be a <CR><LF> line terminator at the end of the last line in the file.)

LDConfig.ldr

LDConfig.ldr will only contain colours that have at some point in time been used by LEGO as the non-painted colour of materials used in LEGO-branded toys, plus ldraw.exe's special colour codes 16 and 24. This includes materials such as the metal track for 9V train tracks, but does not include the colours of paint used to decorate parts or ink used on stickers.