[LSC] LDraw File Spec - Initial public comments

[William Howard]

The following is a grouped and summarised list of comments made on Lugnet to the proposed LDraw File Spec.  Following it are the original comments extracted from the posts

1) General
----------
a) Change "standard by which most create virtual LEGO® models" to "standard by which most create LEGO® models on the computer"

b) Inconsistencies between line type 1 being called a "Sub-file reference" and a "file reference"

c) Details on the line type 1 search order

d) File Type section needs dividing into Official and Unofficial

e) Common verticies paragraph needs a diagram


2) Character encoding
---------------------
a) The character encoding of files should be specified


3) Filenames
------------
a) Remove "The requirement for LDraw files to conform to the DOS 8.3 filename convention has been removed."

b) The spec should not define what is permitted in an official filename (ie part file), but this text should be moved to the library header spec

c) Prohibit spaces in filenames

d) Filenames should be quoted

e) Specific characters should be disallowed/allowed not discouraged


4) Comment lines
----------------
a) Deprecate the form "0 <comment>"


5) Matrix operations
--------------------
a) Needs explicit examples

b) Mention column/row major orientation

c) Don't mention column/row major orientation

d) Give matrix example(s) and mathematical example

e) A more neutral way of displaying a matrix like simply: [a b c 0] [d e f 0] [g h i 0] [x y z 1]


6) Concave quads
----------------
a) Allow concave quads


7) Vertex winding
-----------------
a) Mandate CW or CCW


8) Axis orientation
-------------------
a) Explain the "handedness" of the axis

b) Explain that -y is up


9) Meta commands
----------------
a) META commands can do a lot and it should be stated at the beginning.

b) "0 BFC CERTIFY CW" effects all following lines.

c) "Write/Print" should note that this is not allowed in official parts files

d) Move the meta-commands into their own document

e) Remove "!" from the official spec.

f) Mandate "!" for official metas and strongly suggest it for unofficial ones



---------------------------------
ORIGINAL (ABRIDGED) COMMENTS FOLLOW


GENERAL
=======
Purpose: "standard by which most create virtual LEGO® models"
    Due to past personal conflicts and missteps too lengthly to get in to here,
consider changing to "standard by which most create LEGO® models on the
computer"

5. Line Types - in the summary at the top of page 3 you call Type 1 the
"Sub-file reference" , but at the bottom of page 3 you state "Line type 1 is a
file reference." Is there a reason these two descriptions are different?

A paragraph about line type 1 reference search order would be helpful, 
but it might be outside the documents scope.

"File Type"
In the way your wrote this artikel it is very confusing for newbees.
It should be divided in two portions.
Official and Unofficial
Official is NOT free-format but Unofficial is.

Line Types: Line Type 4
    I think the common verticies paragraph needs a visual example.



CHARACTER ENCODING
==================
1. Character encoding - for a file spec, not specifying this seems potentially
problematic. Every text file has a character encoding, whether or not it's been
explicitly stated. If you save a text file and haven't taken any special steps
to specify it, it will most likely use whatever your "default" encoding is for
the computer you are using.

And if you open a text file and don't specify the encoding,  your default
encoding will be used. This can cause problems when say someone in Greece saves
a part file and sends it to someone in the US. 

Since all the parts files in the official LDRAW repository are already saved in
a specific character encoding, why not specify what that is in the spec?



FILENAMES
=========
LDraw Files: File Name: "The requirement for LDraw files to conform to the DOS
8.3 filename convention has been removed."
    Define what the spec is and not what it is not.  Consider removing this line
as it is extraneous.

LDraw Files: File Name: "Official LDraw filenames ..."
    This whole sentence should be removed and placed in a separate document
defining official library standards.

2. Filenames - why just "discourage" use of white space in file names? Why not
prohibit it?


>   While at it, please disallow spaces in filenames in line type 1.

This is why so many novice computer users think that computers are hard to use.
Developers make arbitrary (and totally unnecessary) restrictions like this, and
then don't understand when the users complain.  They tell the users that they
are wrong.  Well, I'm here to tell you, spaces in filenames are a fact of life,
and not supporting them in your software is bad.  Disallowing them in a general
file spec like this is, in my opinion, totally unconscionable

Ok, the whitespace debate has gone on long enough.  It's been years
now!  Someone in the LSC needs to step up and really define what's an
acceptable filename, whitespace and all.  Personally I think since
MLCad is established, popular, and pretty much frozen the
specification should probably just codify whatever it accepts.  It's
not what I'd have implemented, but it'll do

My reason is simply consistency: spaces are used to  
separate fields, but when it comes to file names, spaces are part of  
the field.

I'd be ok with spaces in file names if the entire file name had to  
be quoted if it had spaces, so it would be something like: 1 16 0 0 0  
1 0 0 0 1 0 0 0 1 "my model.dat" but I'm not sure how others feel  
about it.

Also, the part where it lists what characters are allowed should  
be more clear and list what's allowed and what's not instead of  
simply discouraging some characters. I don't think discouraging  
something should be in the spec, the way I see it a spec is a set of  
rules and should only define what's allowed



COMMENT LINES
=============
Line Types: Line Type 0
    I think the form "0 <comment>" should be depreciated and stated as such in
the spec.

3. Comment lines - if the "//" is the preferred usage, why not just get rid of
the other usage? It won't break anything, if both forms are acceptable now. (And
if they're not both acceptable now, then there are programs already broken.)
Tightening up the spec makes it simpler, which is always a good thing.



MATRIX ORIENTATION
==================

>From all the comments around matrix manipulation it is clear that this part 

of the specification is ambiguous and so needs further consideration.

I think it would be helpful to mention the used matrix in line type 1 is 
row orientated (more clearly then 'standard matrix').

I think the original suggestion that we mention that it is in row-major format
is valid.  I agree that the fact that OpenGL (almost certainly one of the top
two most used 3D APIs on the planet) uses column major format is a good reason
to specify that LDraw uses row-major format, instead of just saying "standard".
It just proves that "standard" in this context is ambiguous.

The following two matrices are equivalent:

| a d g 0 |    | a b c x |

| b e h 0 |    | d e f y |

| c f i 0 |    | g h i z |

| x y z 1 |    | 0 0 0 1 |

The first is "column major", the second is "row major".


> | a d g x |    | a b c 0 |

> | b e h y |    | d e f 0 |

> | c f i z |    | g h i 0 |

> | 0 0 0 1 |    | x y z 1 |

The first one here is a column major and the second is a row major  
matrix, and you are right, they are not the same as the previous 2.

I think a full worked through example would do the specs a lot of good. If I
understand right the line
  1 c x y z a b c d e f g h i part.dat
transforms any point by the operation
  (u, v, w)->(x+a*u+b*v+c*w, y+d*u+e*v+f*w, z+g*u+h*v+i*w)
With it spelled out explicitly like that a programmer can use whatever internal
format they like.

Saying something like lines "1 col x y z a b c d e f g h i name"  
have a matrix with translation = x y z, X axis = a b c, Y axis = d e  
f and Z axis  = g h i should be enough and would avoid going into the  
whole column/row major issue.

If you really want to include a 4x4 matrix like the ones you  
posted then you need to clarify if it is a column or row major  
matrix. I'd prefer to go with a more neutral way of displaying a  
matrix like simply: [a b c 0] [d e f 0] [g h i 0] [x y z 1], this  
would avoid the entire row/column issue because you can read it as a  
column major or row major matrix.

I believe there's no need to mention column/row major at all in  
the specs, and it would be great to avoid it to reduce confusion.


> LDraw is a stand alone specification, so what OpenGL expects is not relevent.

> The LDraw specification must specify what its coordinate and matricies formats

> mean, especially when derived from a string of numbers all on one line.

I agree, and believe that both my proposed "sample matrices" as well as Tim's
"transformation equation" will go into the final spec.

I'm quite satisfied with your dual format explanation.  It is simple and
concise.



CONCAVE QUADS
=============
Line Types: Line Type 4
    I'm hesitant to disallow concave quads.  There's nothing technically wrong
with them and a good chunk of the current official library doesn't conform.

I'm not sure yet what we on the LSC will decide with respect to concave quads.
It may be that we'll change that paragraph to a recommendation.  I personally
don't like them, but I can see Orion's point

Keep in mind, the original LDraw tool treats concave quads as triangles,
effectively ignoring the contained vertex.

So, by the 0.27 "spec", concave quads are inappropriate.  Which can be
translated as they are disallowed, but the renderer copes as it can.



VERTEX WINDING
==============
7. Why doesn't the main spec mandate consistent vertex windings? Either CC or
CCW, but at least make them all the same. Or at least the same withing a given
file. If it's a problem with inconsistent windings in the current parts files,
can't they be updated via a batch script to use consistent windings?



AXES ORIENTATION
================
I think the document must explain x, y and z.  If I remember
correctly above the origin, y is negative

Good point.  You are correct that -y is "up".  I don't see that anywhere in the
spec, and it's quite important.

Also important is the fact that LDraw's model world is in a right-handed
coordinate system. 

I'm open to suggestions on
the exact wording on this section, but I suspect that we can copy from the
authors' guide document, which I believe already describes this



META COMMANDS
=============
Also the "0 BFC CERTIFY CW" effects all other 
following lines. It would be better to explain, that all linetypes 
(except linetype 0) are separate from all other non linetype 0 lines.

META commands can do a lot and it should be stated at the beginning. As 
I started I was confused by exact this (see above) lines.

"Write/Print"
Please add a note that this is not allowed in official parts files on 
the PT.

In the meta command section there are numerous references to other 'meta 
command' documents. Isn't it 'cleaner' to move the whole meta command 
section to a new document and merge it with the other meta documents. 
This to keep things together. Or move it to a document 'basic meta 
commands'. And reference to it just like the other meta documents in a 
single list. This list will then become the meta commands section in 
this document.

8. The write, print, clear, pause, and save commands don't seem to really belong
in a file that describes geometry. I understand they were used in the early
LDraw days, but today, are any modern applications using these commands during
the rendering process? If not, why not remove them?

Line Types: Line Type 0: Meta Commands
    I'm concerned with adding the "!" to the official spec.  What about 3rd
party metas that don't use "!".  If a 3rd party program has metas that don't
start with "!" then technically that program can't claim LDraw.org spec
compatibility.  I recommend mandating it for official metas and strongly
suggesting it for unofficial ones.  You might want to add a note that if an
unofficial meta were ever to become officially adopted it would be required to
have a "!".

4. Meta commands - I'm curious, what backwards-compatibility issues are there
with having some files NOT use the "!" for meta-commands? Since you control the
spec and the parts files, can't you update whatever few official commands that
do not start with a "!" to include it?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://five.pairlist.net/pipermail/lsc/attachments/20070904/9031c241/attachment.htm>