OMR Spec - Updated 8/14

[Orion Pobursky]

Here's the latest draft. Discuss!! (Note: there is a quote bug that's removing the text between <>. Be aware of that and restore the text if needed)
--
The Offical Model Repository Specification
Version: 0.2 (will turn 1.0.0 upon ratification by the LSC)
Author: Orion Pobursky

Purpose:
--------
The Official Model Repository (OMR) is a database of file in the LDraw File Format describing models that are released as sets by Lego®. For consistency between models and ease of indexing by software, a standard for the file headers, names, and hierarchy in the OMR is needed. This document will outline the extra requirements (in addition to those set forth in the current LDraw File Format specification) for a model to be included in the OMR

Base Requirements:
------------------
All files in the model will conform to the current LDraw File Format

Base File Naming:
-----------------
Each model in the OMR will consist of several files that are packaged together into a single MPD file. For sets that include instructions for multiple models, each model will have its own MPD file. Each MPD for the set will be named in the following manner:

<Set Number>( <Optional Specifier> )-[main or alt<Number>]

Where:
<Set Number>: the number assigned on the container of the set
<Optional Specifier>: Sometimes different sets with the same number are released, the specifier will be a single digit number, in parentheses, that is different between different sets, to distinguish these sets from one another.
[main or alt<Number>]: The main model of the instructions (i.e. the model featured on the cover of the container) will have the word "main". For sets that feature more than one model on the front of the container (e.g. the Creator line), the largest or most prominent model is the main model. For alternate models that are detailed in instructions, the word "alt" and a single digit number starting at 1 will be used. For playsets or other sets where there are multiple models that are part of an integral whole, all of the submodels will be contained in the main model MPD.

Example:
Set 4896 - Roaring Roadsters. This creator set has 3 models in the instructions. The roadster is featured prominently on the box. 4896 is the only set with that number. Therefore:
Roadster MPD: 4896-main.mpd
Dragster MPD: 4896-alt1.mpd
etc...

MPD File Structure:
-------------------
The MPD will conform to the MPD File Specification.

The naming of the individual files in the MPD is up to the discretion of the author with the following guidance:
- A logical naming scheme is highly desired.
- Individual models in the set (e.g a vehicle or minifig) shall have their own separate file inside the MPD.
- Minifig file name should have the name of the character, if known
- The <MPD Filename> is required to be prepended to the file name of each individual file in the MPD

The only unofficial parts allowed to be referenced in the model files are those currently residing on the LDraw.org Parts Tracker. No part files shall be contained in the MPD.

File Headers:
-------------
Each individual model file in the MPD must have a standard header format.

Standard Header:
0 FILE <MPD Filename> - <Filename>.ldr
0 <MPD Filename> - <File Desciption>
0 Name: <MPD Filename> - <Filename>.ldr
0 Author: <Author Name>
0 !LDRAW_ORG Official Model Repository
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !THEME Theme name
0 !KEYWORDS words, more words,…,
0 !KEYWORDS words in second row, …, final words

0 !HISTORY YYYY-MM-DD [<Author Name>] Free text description of change. This can wrap to a
0 !HISTORY YYYY-MM-DD [<Author Name>e] second row with the same date if necessary. However authors should lean toward writing longer
0 !HISTORY YYYY-MM-DD [<Author Name>e] single !HISTORY lines(and not feel constrained to the historic 80-character limit on line length)

Where:
<MPD Filename>: The name of the containing MPD
<Filename>: The name of the file
<Author Name>: The name of the author. Real full name are highly desired but not required. If the full name is not provided, a first or last name, with or with out initials, is requested.

Optional commands are !THEME, !KEYWORDS, and !HISTORY

META commands:
--------------
The only META commands allowed in the model file are those associated with the header, 0 FILE (for MPD support) and 0 STEP. STEP commands not specifically required but they are highly desired. If included, the step commands should follow the instructions as closely as possible.

[Philippe Hurbain]

> The only unofficial parts allowed to be referenced
> in the model files are those currently residing on
> the LDraw.org Parts Tracker. No part files shall
> be contained in the MPD.

I may have missed a part of this discussion (I am connected on & off these days, and mainly off!) but I am seriously annoyed by the above sentence, since even parts on Tracker may change in ways that will completely break the model. Why not include unofficial parts in the MPD? OMR policy coud even state that files can be updated by anyone to replace unofficial parts from models when they become official.

[Orion Pobursky]

I want parts created for an OMR model to be fed into the PT. The only way I could think of to force this is the above. If you have a better way, let me know.

[Philippe Hurbain]

Nice goal, problem is that even parts on PT do change or get renamed. That's why I suggest that unofficial parts use in OMR models be added to PT AND included in MPD.

[Roland Melkert]

Personally I think including unofficial parts will bloat things up. Over the years it will also suppress the by then official version.

[Philippe Hurbain]

Roland Melkert Wrote:
-------------------------------------------------------
> Personally I think including unofficial parts will
> bloat things up.
Yes, but imho it's much better than to have an unusable model!!!

> Over the years it will also
> suppress the by then official version.
No, MPD included parts remain there, they don't become part of user's LDraw library. The added bonus is that models are immediately usable without messing with unofficial parts.

[Roland Melkert]

Philippe "Philo" Hurbain Wrote:
> > Over the years it will also
> > suppress the by then official version.
> No, MPD included parts remain there, they don't
> become part of user's LDraw library. The added
> bonus is that models are immediately usable
> without messing with unofficial parts.

I mean for example if you had "0 FILE 3001.dat" inside the mpd, all references to 3001.dat inside the mpd's submodels will use that version, even if there is also one in /parts.

[Willy Tschager]

Orion Pobursky Wrote:
-------------------------------------------------------
> META commands:
> --------------
> The only META commands allowed in the model file
> are those associated with the header, 0 FILE (for
> MPD support) and 0 STEP. STEP commands not
> specifically required but they are highly desired.
> If included, the step commands should follow the
> instructions as closely as possible.

All META commands are allowed in the model file but not specifically required. Nonetheless they are highly desired and if
included, the STEP, LPUB and LSYNTH commands should follow the instructions as closely as possible.

w.

[Willy Tschager]

This draft needs desperately an example for the MPD as well as the subfiles. Kind of the examples added to the parts header:

http://www.ldraw.org/Article398.html

w.

[Willy Tschager]

Orion Pobursky Wrote:
> 0 !LICENSE Redistributable under CCAL version 2.0
> : see CAreadme.txt

We have to upgrade to 3.0:

http://creativecommons.org/licenses/by/3.0/

w.

[Travis Cobbs]

Orion Pobursky Wrote:
-------------------------------------------------------
> META commands:
> --------------
> The only META commands allowed in the model file
> are those associated with the header, 0 FILE (for
> MPD support) and 0 STEP. STEP commands not
> specifically required but they are highly desired.
> If included, the step commands should follow the
> instructions as closely as possible.

I haven't been following this discussion fully, so perhaps what I'm about to say has already been hashed out. However, I think this is short-sighted. It completely precludes the possibility of a LPub-optimized file, and also disallows other potentially useful meta-commands. For example, it seems to me that the !LDVIEW BBOX_IGNORE meta-command could be useful for train set models. Train MOCs were actually why I created that meta-command (at a user's request).

[Tore Eriksson]

Roland Melkert Wrote:

> I mean for example if you had "0 FILE 3001.dat"
> inside the mpd, all references to 3001.dat inside
> the mpd's submodels will use that version, even if
> there is also one in /parts.


That's exactly why an unofficial part insid a OMR model should also have an unique name, like "315-3_3001.dat", or maybe just "Unofficial_3001.dat".

/Tore

[Jude Parrill]

I have a question, and forgive me if this has been answered elsewhere, but it feels like it should these things should probably be enumerated in the official spec as well.

What is the policy regarding parts currently unavailable both officially and unofficially?

What I mean to say is, say you're building a set and come to a piece you cannot find officially or unofficially, what is the acceptable/appropriate action to take? For example say you're building a set and come across a 2x2 45 slope brick with pattern that is currently unavailable. Do you substitute a plain version? Do you find the pattern that is closest to the one that is supposed to be used (which may be rather subjective)? Furthermore, what if no acceptable part can be found. For example, you're building a set for which a particular part has never been developed, in any form? Do you simply skip the part altogether? What if it is a vital/obvious piece, without which the set looks entirely incomplete? Following on this notion, apply the same questions towards minifigs. Let's say I was building the 6212 X-Wing Fighter. Currently, the Chewbacca minifig piece is unavailable in any form. Do I create the basic "brown torso and legs" minifig with no head which would look completely bizarre and out of place, or do I simply skip the minifig altogether?

Additionally, it seems prudent that there should be some way of documenting which parts have been substituted or skipped why, so that those who download it will know the problems. Also, if done correctly, it could be used as a way of "highlighting" sets which are in need of upgrade once the part(s) needed become available, so that the set could be improved and re-released in a timely and efficient manner.

Now, personally, I have my own way of handling and documenting these things for the sets I build, but I'm not entirely convinced they're the best. Generally speaking, for parts, I'll substitute "plain" versions where available and otherwise skip them. For minifigs, if insufficient parts are available for the minifig to be recognizable (I realize this is subjective), it is skipped entirely. All data on missing/unavailable parts are documented in a seperate text file, which admittedly is probably not the best way to handle this.