|
|
|
Orion Pobursky / $14 | |
| LDraw.Org File Specification 1.0.0 Describing Virtual LEGO® Bricks and Models Note: This Document is a work in progress Last Revised - 26Jun03 Table of Contents Purpose LDraw Files Line Types Line Type 0 Line Type 1 Line Type 2 Line Type 3 Line Type 4 Line Type 5 Colors Meta Commands Step Write/Print Clear Pause Save File Type Category Keywords Other Meta Commands MPD Files Rules for Official Part Files Purpose Describing LEGO® bricks and models in a virtual environment is a challenging prospect. In 1995 James Jessiman developed just such a system with is his LDraw program and file format. Since then the LDraw file format has grown to be the standard by which most create virtual LEGO® models. The aim of this document is to compile and consolidate James’s original file specification with the additions made since. LDraw Files
Every line of the file contains one command. Every command is independent of other lines. There is no line length restriction. Every command starts with a number, called a line type. The function and format of the line is determined by the line type. Line Types The line type of a line is the first number on the line. The line types are:
Line Type 0 Line type 0 has two uses. One use is a comment the other is as a Meta command. If the first line of a file is a line type 0 the remainder of the line is considered the file title. This overrides any Meta commands on that line. A comment line is formatted: 0 <comment> Where <comment> is any string Meta Commands A Meta command is a statement used to tell an LDraw compatible program to do something. There are currently many official Meta commands and almost as many unofficial Meta commands. In a Meta command, a keyword follows the line type in the line. The keyword must be in all caps. The generic Meta line format is: 0 <meta command> <additional parameters> Where:
Line Type 1 Line type 1 is a file reference. The generic format is: 1 <color> x y z a b c d e g f h i <file> Where:
Line type 2 is a line drawn between two points. The generic format is: 2 <color> x1 y1 z1 x2 y2 z2 Where:
Line Type 3 Line type 3 is a filled triangle drawn between three points. The generic format is: 3 <color> x1 y1 z1 x2 y2 z2 x3 y3 z3 Where:
Line type 4 is a filled quadrilateral drawn between four points. The generic format is: 4 <color> x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4 Where:
Line type 5 is a filled conditional or optional line. This 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. The generic format is: 5 <color> x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4 Where:
Say we have an optional line at the point below 2. The other points are 3 and 1. In this case the line would not be drawn since points 1 and 3 are not on the same side of the line below 2. Now say we have an optional line at the point below 3. The other points are 2 and 4. The line would be drawn since 2 and 4 are on the same side of the line below 3. In the case of the picture above the only lines that are drawn would be those below 3 and 7. This serves to “outline” the edges of the cylinder, which is the intent of optional lines. Colors Colors in LDraw are defined by a number. The allowable numbers are 1-16, 24, 32-47, 256-511. The numbers 1-15 are the core colors. They are:
Colors 256-512 are dithered colors. Only line type 1 is allowed to use colors 256-512. Basically colors 256-512 are the combination of two of the core colors. The way this is accomplished is: <dithered color> = (<core color 1> * 16) + <core color 2> + 256 Example, if you want to combine Black (color 0) and Red (Color 4): (0 * 16) + 4 + 256 = 260 Colors 16 and 24 are special colors. Color 16 is the ‘current color’, whatever color the line type 1 was that referenced the file. Color 24 is the complement color to the current color. Line type 2 is typically color 24. The combinations are:
The complement for the dithered colors is the complement for the first color of the two colors used to determine the dithered color number. For example: 260 = (0 * 16) + 4 + 256 the complement is the complement of color 0, color 8 Additional Colors In addition to the core colors the LDraw.org community has defined a number of additional colors. LDLite Colors Colors 17-23 and 25-28 were define by the program LDLite and have since been adopted by most LDraw.org compatible programs. The list of colors follows:
Dithered Color Replacements A few of the dithered colors have been redefined as metal/rubber colors. The list of these follows:
Meta Commands The Meta commands documented here explain the behavior exhibited in ldraw.exe. For other LDraw compatible viewers refer to the documentation of the program you are using. (Ed. Note: This clearly needs to be changed for the LDraw 1.0.0 spec) Step Marks the end of a building step
The Step command causes the program to stop until the Enter key is pressed. Additionally a bitmap of the currently displayed model will be save to the LDRAWBITMAP directory Write/Print Displays a message
<message> is a string of any length. This message is not saved on any bitmaps. Clear Clears the screen
This command causes all previous drawn files and line types to be cleared. Any following lines are drawn as normal. Pause Pauses the drawing of a file
This command stops the further parsing of lines until the Enter key is pressed. Save Saves a bitmap of the current drawing
Save a bitmap of the current drawing in the LDRAWBITMAP directory. This command does not cause the program to pause. File Type Indicates the type of file (model, part, etc), and if it is part of the LDraw.org Parts Library.
This meta-statement should appear as the last line of the primary file header. 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:
+ = 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 line type should be considered case-insensitive and free-format. Category Classifies a file according to a category
This command is used almost exclusively in part files. A file can have only one category statement. <categoryname> can only be one of the following values:
If a part file has no category command, the category is assumed to be the first word in the file title. Keywords Adds additional classifying words to a file
The keywords command is essentially a laundry list of words that further describe the file. Like the category command, this command is used almost exclusively in part files. The list of words after the KEYWORD command can be space or comma delimited. The words the list should not also occur in the file title. Other Meta Commands The following is a list of other Meta Commands. These commands are documented and maintained by the owner of their respective programs. The URLs listed are the last known good links to that product. This list is not intended as a limit but merely to prevent overlap. MPD commands: FILE <name> NOFILESee the MPD file section MLCad (http://www.lm-software.com/mlcad/) ROTSTEP (<x-angle> <y-angle> <z-angle> [(REL'|ADD'|ABS)] '| END) BACKGROUND <filename> BUFEXCHG (A-H) (STORE '| RETRIEVE) GHOST <LDRAW line> GROUP <n> <name> MLCAD BGT <group name> MLCAD SKIP_BEGIN MLCAD SKIP_END ROTATION CENTER <x><y><z> "<name>" ROTATION CONFIG <Rotation ID> <Visible Flag> ROTATION AXLE MLCAD SPRING MLCAD FLEXHOSE MLCAD RUBBER_BELTLPub (http://www.users.qwest.net/~kclague/LPub/index.htm) PLIST BEGIN SUB <fname> PLIST BEGIN IGN PLIST END BI BEGIN GRAYED BI ENDLSynth (http://www.users.qwest.net/~kclague/lsynth/index.htm) SYNTH BEGIN (RIBBED_TUBE |
FLEXIBLE_TUBE |
FLEX_CABLE |
RIGID_TUBE |
ELECTRIC_CABLE |
PNEUMATIC_TUBE |
FLEXIBLE_AXLE |
FIBER_OPTIC_CABLE |
RUBBER_BAND |
CHAIN |
PLASTIC_TREAD |
RUBBER_TREAD)
SYNTH END
SYNTH (INSIDE | OUTSIDE | CROSS | SHOW | HIDE)
SYNTHESIZED BEGIN
SYNTHESIZED END
L3P (http://www.hassings.dk/l3/l3p.html)
L3P IFPOV L3P IFNOTPOV L3P ELSEPOV L3P ENDPOVLDLite (http://ldlite.sourceforge.net/) COLOR TRANSLATE ROTATE SCALE TRANSFORM COLORNAME POINT MATRIX CMDLINE <line>The following are documented in the LDraw Language Extension for Clipping BFC [(CERTIFY|NOCERTIFY)] [(CLIP|NOCLIP)] [(CW|CCW)] [INVERTNEXT]Adding New META Commands Here are some guidelines LDraw.org compatible program developers should consider when add new META command functionality to their programs:
MPD Files MPD files are files with many LDraw.org file format files in a single file. This allows for ease in posting or emailing a model made up of many subparts. The MPD file uses 2 Meta Commands, only one of which is commonly used. The common statement is 0 FILE, the less common statement is 0 NOFILE. To create a MPD file simply include the code for each individual file in the MPD file. At the beginning of each file’s text, insert a FILE meta-statement. This separates and names the files. The end of each file, or just the last file in the MPD, may be marked with a 0 NOFILE line. The NOFILE command is only required if the file’s contents are followed by non-LDraw content (such as the poster’s signature lines). In order to support the inclusion of LDraw files in message systems (like email), any text lines before the first FILE statement will be discarded. It is considered to be an error for any LDraw code (other than comment lines) to appear before the first 0 FILE statement. Also, no LDraw commands should appear after a NOFILE meta-statement, and before the next FILE meta-statement. When an MPD file is used to store a multi-file model, the first file in the MPD is treated as the ‘main model’ -- all other files in the MPD will only be rendered if they are referenced by the main model, directly or indirectly. So far, there are no clear scoping or namespace rules on MPD files. If you put a file named stud.dat in your MPD file, don’t be surprised to see your stud.dat file appear on the top of every single brick in your scene. MPD Meta Statements FILE
<model> is the name of the following LDraw file. NOFILE
There are no options or parameters. |
|
Primary content in this document is © Orion Pobursky. All other text, images, or trademarks in this document are the intellectual property of their respective owners. |
| |
©2005 LUGNET. All rights reserved. - hosted by steinbruch.info GbR |