Official Library Specifications and Part Number Spec

[Orion Pobursky]

Discussion seems to have petered out on this 2 docs:

Official Library Part Number Specification
LDraw.org Official Parts Library Specifications

I did a proofread a few days ago and they're pretty much ready to go I think. 

I'll follow this thread and make any change you 3 propose. I'd like to finish this project out.

[Travis Cobbs]

Discussion seems to have petered out on this 2 docs:

Official Library Part Number Specification
LDraw.org Official Parts Library Specifications

I did a proofread a few days ago and they're pretty much ready to go I think. 

I'll follow this thread and make any change you 3 propose. I'd like to finish this project out.

I'd like to refrain from providing input on the parts number spec. I don't feel I have enough knowledge of it to be qualified to make good decisions. I'm happy to go along with whatever Chris and/or Roland decide regarding it.

In the other spec, I found a few things I disagree with (although none is critical):

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.

I feel that we should enforce upper case filenames to avoid confusion, but this is a fairly minor preference on my part. I'm willing to let it stand.


I don't understand why this is allowed:

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

I understand what it is saying, but I don't understand why it is allowed. Note: if we keep this section as-is, we need to add a colon to the end of the first line, and periods at the end of each of the other lines.


I think the following section should be amended:

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.

It should have an extra qualification:

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. Also, the overlapping polygons must be the same color.

Do we want to clarify that BFC NOCLIP is allowed (particularly for decorations printed on transparent parts)?


I also found a bunch of typos:

These rules have evolved over time and there may be files in the Official Library that do not conform to these rules.

Should be:

These rules have evolved over time, and there may be files in the Official Library that do not conform to these rules.

(Add required comma.)

(To avoid confusion with English grammar, comma is not a permitted character.)

Should be:

(To avoid confusion with English grammar, comma is not a permitted character.)

(Capitalize sentence, and move period inside parentheses.)

hi-res

I would prefer if this were updated:

high-res

(Using "hi" to mean "high" in this context is quite common, but it bugs me.)

(ie 1.5 not 1.500)

Should be:

(ie 1.5, not 1.500)

(Add comma. Note: see below about "ie".)

(ie 1.5 not 01.5)

Should be:

(ie 1.5, not 01.5)

(Add comma. Note: see below about "ie".)

non-conplaner vertices

Should be:

non-co-planar vertices

(Fix spelling. Also, since most of the rest of the document uses "co-planar" and not "coplanar", I added the optional dash. Given that this looks odd here, and given that both "coplanar" and "co-planar" seem to be equally correct, we might consider updating all instances of "co-planar" in the document to be "coplanar". We do want to be consistent.)

To prevent co-linear vertices in quads/triangles and concave quads every interior angle in a quad or triangle must not be greater than 179.9 degrees or smaller than 0.025 degrees.

Should be:

To prevent co-linear vertices in quads/triangles and concave quads, every interior angle in a quad or triangle must not be greater than 179.9 degrees or smaller than 0.025 degrees.

(Add comma.)

A quad considered coplaner if it is split into two triangles and both triangles are co-planar with each other.

Should be:

A quad is considered co-planar if it is split into two triangles and both triangles are co-planar with each other.

(Add "is", and fix "co-planar".)

There two ways to split a quad into two triangles and both must result in co-planar triangles.

Should be:

There are two ways to split a quad into two triangles, and both must result in co-planar triangles.

(Add "are". Add required comma.)

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 required unless justification is given by the part author.

Should be:

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 required unless justification is given by the part author.

(Split sentence into two sentences.)

This especially true for large quads where the "warp" can be seen at normal viewing magnifications.

Should be:

This is especially true for large quads where the "warp" can be seen at normal viewing magnifications.

(Add "is".)

See Official Library Part Number Specification for shortcut part number rules

Should be:

See Official Library Part Number Specification for shortcut part number rules.

(Add period.)

For assemblies without moving parts, it's simple: all parts composing the assembly are ~, and an assembly shortcut is provided (several shortcuts may be needed to account for different colour combinations).

Should be:

For assemblies without moving parts, it's simple: all parts composing the assembly are ~, and an assembly shortcut is provided. (Several shortcuts may be needed to account for different colour combinations.)

(Make parenthetical phrase a separate sentence.)

Examples include hoses, ropes, strings, springs, fabrics, rubber bands and platic sheets

Should be:

Examples include hoses, ropes, strings, springs, fabrics, rubber bands and plastic sheets.

(Add period, and correct spelling of "plastic".)

decrete

Should be:

discrete

This places them in the shortcut category and thier descriptions will follow the rules outlined for shortcuts (i.e. use of the "~" character)

Should be:

This places them in the shortcut category, and their descriptions will follow the rules outlined for shortcuts (i.e. use of the "~" character).

(Add required comma and period, and correct spelling of "their".)

Flexbible

Should be:

Flexible

Subsquent formed versions shall have a suffix added to the part number as specified in the Official Library Part Number Specification

Should be:

Subsequent formed versions shall have a suffix added to the part number as specified in the Official Library Part Number Specification.

(Add period, and correct spelling of "Subsequent".)

See Official Library Part Number Specification for sticker number rules

Should be:

See Official Library Part Number Specification for sticker number rules.

(Add period.)

where 1 stud = 20LDraw units

Should be:

where 1 stud = 20 LDraw units

(Add space.)

If the sticker is designed to be placed on the curved surface of a part or folded around the edge of a part a ‘formed’ version of the sticker part may be modelled in addition to the flat version.

Should be:

If the sticker is designed to be placed on the curved surface of a part or folded around the edge of a part, a ‘formed’ version of the sticker part may be modelled in addition to the flat version.

(Add comma.)

See Official Library Part Number Specification for sticker shortcut part number rules

Should be:

See Official Library Part Number Specification for sticker shortcut part number rules.

(Add period.)

The shortcut may not include more than one part, although that part can be a composite part (one with a "c" in the filename).

Should be:

The shortcut may not include more than one part, although that part may be a composite part (one with a "c" in the filename).

(Change "can" to "may".)

Sticker shortcuts that do not conform to this rule can remain in the Official Library and not be made obsolete

Should be:

Sticker shortcuts that do not conform to this rule can remain in the Official Library and not be made obsolete.

(Add period.)

See Official Library Part Number Specification for patterned part number rules

Should be:

See Official Library Part Number Specification for patterned part number rules.

(Add period.)

Since this printing is easily removed and LDraw parts can come in any variety, all patterned parts should based on another plain, unpatterned part in the library. This means that a plain version of the patterned part should created even if plain version has never been produced by LEGO.

Should be:

Since this printing is easily removed, and LDraw parts can come in any variety, all patterned parts should be based on another plain, unpatterned part in the library. This means that a plain version of the patterned part should be created even if a plain version has never been produced by LEGO.

(Add required comma. Add "be" twice, one before "based", the other before "created". Add "a" before "plain".)

<base part description> is the description of the non-patterned version of the part

Should be:

<base part description> is the description of the non-patterned version of the part.

(Add period.)

Errors in either one of these !KEYWORDS entries should not be cause for a hold vote on the Parts Tracker since this is simply data to make locating specific patterns easier

Should be:

Errors in either one of these !KEYWORDS entries should not be cause for a hold vote on the Parts Tracker since this is simply data to make locating specific patterns easier.

(Add period.)


Finally, some general observations:

One "etc" in the document has a period after it, while the other two don't. I believe that proper grammar requires the period, but if you don't like how that looks, the three should be consistent. Similarly, "ie" is used in a number of places without periods, and in one place with periods ("i.e."). I prefer all to have periods, but the document should be consistent.

The document is inconsistent in its use of the Oxford comma. I personally someone who favors its use, but I am willing to allow the document to go either way. However, it does need to be consistent.

The document is also inconsistent in its use of smart quotes. I think it should either always use them (except in any LDraw file examples) or never use them.

[Orion Pobursky]

I've killed all the typos you found. All etc.'s now have a period. I.e.'s are fixed. Smart quotes are replace with plain quotes. All appropriate instances now have an Oxford comma (I'm a fan as well). I got a little button happy with search and replace so I may have accidentally removed some correct commas in the process so check if you'd like.

I'll leave the technicals up to you, Chris, and Roland. I do agree with the overlap color requirement though.

[Roland Melkert]

I've killed all the typos you found. All etc.'s now have a period. I.e.'s are fixed. Smart quotes are replace with plain quotes. All appropriate instances now have an Oxford comma (I'm a fan as well). I got a little button happy with search and replace so I may have accidentally removed some correct commas in the process so check if you'd like.

I'll leave the technicals up to you, Chris, and Roland. I do agree with the overlap color requirement though.

Not being a grammar prodigy myself I had to lookup the meaning of "Oxford comma" and came across this article:
https://thefederalist.com/2019/10/01/why...d-writing/

Just fyi I don't really have a preference myself

[Orion Pobursky]

Not being a grammar prodigy myself I had to lookup the meaning of "Oxford comma" and came across this article:
https://thefederalist.com/2019/10/01/why...d-writing/

Just fyi I don't really have a preference myself

I look at it this way: it adds clarity where needed and takes away from nothing from the text. We're not writing fine poetry or the great American novel. For technical writing, clarity is key.

[Chris Dee]

Discussion seems to have petered out on this 2 docs:

Official Library Part Number Specification
LDraw.org Official Parts Library Specifications

I did a proofread a few days ago and they're pretty much ready to go I think. 

I'll follow this thread and make any change you 3 propose. I'd like to finish this project out.

Please give me a chance to review these - I have been too busy of late to contribute.

[Orion Pobursky]

Please give me a chance to review these - I have been too busy of late to contribute.

While I'd like to get this done, I want it done right. This is a hobby and real life takes precedence so take all the time you need.

P.S. I added the new Ux pattern code block to the number spec.

[Chris Dee]

Please give me a chance to review these - I have been too busy of late to contribute.

Official Library Part Number Specification

General Part Numbering - Known Part Numbers

Please add '(Design ID)' after 'part number'.

General Part Numbering - Part Numbers vs. Element IDs

Please add 'Hence you will not find 4109995 in the LDraw parts library.

General Part Numbering - Unknown Part Numbers

I think the note should mention that the previous rule was for three-digit parts numbers for consistency with the Quick Reference Table. It does need to mention the x-prefix whilst these parts were in development.

General Part Numbering - Mould Variants/Different Versions or Parts with the Same Number

Please change '3626A.DAT and 3626B.DAT' to '3626a.dat and 3626b.dat'.

General Part Numbering - Subparts

Please add 'Where there is extensive shared geometry, subparts may be used by parent parts with a different main number.'.
Please replace 'stored in the \s subdirectory' with 'stored in the parts\s subdirectory'.

General Part Numbering - Primitives

For clarity, please use 'components' rather then 'subparts'.
Please insert 'stored in the \p subdirectory'.
I think there needs to be something to cover the p\8 and p\48 subdirectories, particularly the need for p\8\stud.... versions of p\stud primitives and the need for stu2... alias to all stud... files.

Probably all uses of the backslash directory separator could be changed to a forward slash as MS Windows is ambivalent these days.

I think there needs to be another section in General Part Numbering to cover the use of alpha suffices for corrections in geometry or
numbering errors.

I think there needs to be another section in General Part Numbering to cover the ....kNN flexible part components (komponents).

I think there needs to be another section in General Part Numbering to cover the 'third party' parts numbers (tNNNN). Thaye are mentioned in the Quick Reference Table.

Shortcut (Assembly) Part Numbering - General Shortcut Part Numbering

Please lowcase the C in CNN.

Shortcut (Assembly) Part Numbering - Shortcuts with More Than One Physical Configuration

Please lowcase the F in -Fnn and -F1.

Patterned Part Numbering - General Patterned Part Numbering

Please change 'for the part' to 'for the pattern'.

Patterned Part Numbering - Patterned Part Code

This table changes frequently and is not subject to the note at the foot of the document, i.e. changes are not subject to LSB ratification. Maybe it needs to reside outside of this document, and probably be script-generated (for the same source as used by ptpatterns.cgi).

Sticker part numbering - Formed Stickers Parts

Please lowcase the C in CNN.

Sticker part numbering - Sticker Shortcuts

Please lowcase the D in DNN.

Part Numbering Quick Reference Table

Please switch the casing (n to N) and filename elements to lowcase.

Do we need a section to cover the naming conventions for files in parts\textures, parts\s\textures and p\textures?

LDraw.org Official Parts Library Specifications

General File Content - NUmbers - Precision

Please change 'sub-parts' to 'subparts' to match nomenclature elsewhere..
 
General File Content - META Commands - Back Face Culling (BFC)

Is it true that parts need to be CCW. I though parts could be CW or CCW, but primitives must be CCW.

General File Content - Geometry - Co-planar/Co-linear Tolerance and Concave Quads

In para 3, please correct 'co-planer' to 'co-planar'.

Do we want to say somewhere that isolated primitives should not be used in patterns, i.e. a disc surrounded by an ndis is fine, but a disc alone would generate gaps in hi-res mode.

Relately, do we want to mention the special use of ering.dat

[Orion Pobursky]

Everything above is added/corrected with these comments:

- If you make a similar script to ptreleases or an auto generated file on the server that I can reference, adding an always-to-date pattern code table is easy.

Do we want to say somewhere that isolated primitives should not be used in patterns, i.e. a disc surrounded by an ndis is fine, but a disc alone would generate gaps in hi-res mode.

Relately, do we want to mention the special use of ering.dat

I think these are more authoring technique. That said, I'll leave the LSB to make the final decision.

[Chris Dee]

Everything above is added/corrected with these comments:

- If you make a similar script to ptreleases or an auto generated file on the server that I can reference, adding an always-to-date pattern code table is easy.




I think these are more authoring technique. That said, I'll leave the LSB to make the final decision.

Thanks. I'll get back to you on the pattern code table.

In General Part Numbering - Subparts, there is a spurious '>' and the backslashes could be changed to forward slashes.

[Orion Pobursky]

I'd like to get these ratified. I wanted to get it done before the update but that didn't happen but we now have time before the next one to change thing to conform.  We can add more stuff later if we'd like but there's enough new things and clarification that we should at least get those in place so I can retire the old documents.

[Chris Dee]

I'd like to get these ratified. I wanted to get it done before the update but that didn't happen but we now have time before the next one to change thing to conform.  We can add more stuff later if we'd like but there's enough new things and clarification that we should at least get those in place so I can retire the old documents.

I am happy with these as they stand.

Is someone building a list of non-conforming parts?

[Travis Cobbs]

I am happy with these as they stand.

Is someone building a list of non-conforming parts?

I created a separate call for votes for each draft.

[Orion Pobursky]

Is someone building a list of non-conforming parts?

Now that most of my projects are done (these 2 specs, reorganizing the main site, refactoring and improving 3D viewer code), I can work on this.