View source for Part Snapping Language Extension

== Specification ==
'''Maintained by''': The LDraw.org Standards Committee

'''Writer''': Roland Melkert, Orion Pobursky

'''Revision''': 1, XX-XXX-XXXX

Author's Note: This is a unofficial specification, not yet ratified by the LSC

===Part snapping metas===

Part snapping metas are currently exclusively used combined with shadow library files in order to add extra information to LDraw part files. This information is needed by LDCad to calculate possible 'LEGO like' part placement positions.

These metas basically describe hotspots and their shapes which then will be used to test against each other while adding a new part to the current model. This will be done for all snap info on both the source and destination brick(s) in order to find the best / closest match (e.g. an axle pin into a beam hole).

====The SNAP_CLEAR meta====

The clear meta is used to flush all or part of the inherited snap information gathered for the current part file so far. This meta might be needed to replace inherited information in order to extend it or increase its detail. Like e.g. information obtained from an axle primitive because that primitive is used as part of a bigger shape inside this file.

‘‘‘Example’’’

<code><nowiki>0 !SNAP_CLEAR [id=axleHole]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
| id
| string
|  
| Used to only clear information obtained from snap info using the given freely named ID. Leave it empty to clear all information for the current part.
|}

====The SNAP_INCL meta====

The include meta is used to add the information from another shadow library file to this part too. This is done non recursively.

‘‘‘Example’’’

<code><nowiki>0 !SNAP_INCL [ref=connhole.dat] [pos=-50 10 0] [ori=0 -1 0 0 0 -1 1 0 0] [grid=C 1 C 3 20 20]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
| ID
| string
|  
| Optional identifier which can be used in clear metas to optionally drop this meta's information in higher level parts using it.
|-
| pos
| vector
|  
| Position of the included information / object.
|-
| ori
| 3x3 matrix
|  
| Orientation transformation to apply to the included information / object.
|-
| scale
| vector
|  
| Optional scaling vector to apply to the included information / object
|-
| ref
| ldrawRef
|  
| Reference to the source shadow library file. Must only use local part references.
|-
| grid
| mixed array
|  
| 
Defines a grid pattern to use for multiple placement / inclusion of the referenced file. The grid uses the orientation stated in the ori parameter. As LDraw part data is Y-axis orientated only the X and Z grid stepping values need to be given like so:

Xcnt Zcnt Xstep Zstep for example: 4 8 20 20 which could be used to make a 4x8 grid of e.g. studs.

Optionally each count value can be preceded by a C character indicating the grid should be centered on that axis. If no C is given the axis will add to the pos parameter. For example to center the 4x8 grid around its pos parameter use: C 4 C 8 20 20
|}

====The snap cylinder meta====

The cylinder meta is the main workhorse among the snap info metas. This because it describes holes and pens which is what LEGO is all about. If you take a good look at some LEGO bricks you'll notice all of them have similar interlocking holes and pens. The only real difference between them are the diameters and pattern of the hole/pens shapes (like the side of a key). It is this information that the cylinder meta tries to capture in order to calculate matching pairs.

‘‘‘Example’’’

<code><nowiki>0 !LDCAD SNAP_CYL [id=connhole] [gender=F] [caps=none] [secs=R 8 2 R 6 16 R 8 2] [center=true] [slide=true] [pos=0 0 0] [ori=1 0 0 0 1 0 0 0 1]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
| ID
| string
|  
| Optional identifier which can be used in clear metas to optionally drop this meta's information in higher level parts using it.
|-
| group
| string
|  
| optional group identifier. Can be used to limit potential matches to only snap info having the same group string. Can be used to prevent unwanted matches when very complicated shapes are involved e.g. click rotation holes etc.
|-
| pos
| vector
|  
| Position of this shape.
|-
| ori
| 3x3 matrix
|  
| Orientation of this shape.
|-
| scale
| enum
| none
| 
Defines how scaled references to the master (official) part should be handled information inheritance wise. Must be one of the following:

none: If scaling is detected this information will not be inherited by the higher level part.

YOnly: The information will only be inherited if scaling is limited to the Y-axis, if X and or Z is scaled the info will not be inherited.

ROnly: The information will only be inherited if scaling is limited to the cylinder's radius (usually x and z) given its done symmetrical. If the info is scaled in any other way it will not be inherited.

YandR: The information will only be inherited if YOnly or ROnly rules apply.

|-
| mirror
| enum
| cor
| 
Defines how mirrored references to the master (official) part should be handled information inheritance wise. Must be one of the following:

none: If mirroring is detected this information will not be inherited by the higher level part.

cor: If mirroring is detected the snap information will be corrected by flipping one of the radius axis'.

|-
| gender
| enum
| male
| Sets the gender of the cylinder shape M for male (pen) and F for female (hole).
|-
| secs
| mixed array
|  
| 
Describes the shape of the hole (along the neg Y-axis) or pen by a sequence of shape variants, radius's and lengths. The info must be given in blocks of: shapeVariant radius length where shapeVariant must be one of the following:

R: Round.

A: Axle.

S: Square.

_L: Flexible radius wise extension to the previous block's specs. This will be needed for e.g. the tip of an technic connector pin. Although it is slightly larger it allows for (temporary) compression while sliding the pin inside e.g. a beam hole.

L_: Same as _L but as an extension to the next section instead of the previous one.

For example a plain stud can be described using a single block: R 8 4 while a technic beam hole needs three: R 8 2 R 6 16 R 8 2.

|-
| caps
| enum
| one
| 
Defines the ends of the shape, must be one of the following:

none: The shape is open ended. e.g. a male axle or female beam hole.

one: The shape has one closed ending, which one depends on the gender. For male shapes it will be A (bottom) and for female shapes it will be B (top).

two: The shape is closed (blocked) at both sides. e.g. the male bar of a minifig suitcase handle.

A: The bottom is closed / blocked. e.g. a stud.

B: The top is closed / blocked. e.g. an anti stud.

|-
| grid
| mixed array
|  
| 
Defines a grid pattern to use for multiple placement of this cylindrical shape. The grid uses the orientation stated in the ori parameter. As all snap info is Y-axis orientated only the X and Z grid stepping values need to be given like so:

Xcnt Zcnt Xstep Zstep for example: 4 8 20 20 which could be used to make a 4x8 grid of e.g. studs.

Optionally each count value can be preceded by a C character indicating the grid should be centered on that axis. If no C is given the axis will add to the pos parameter. For example to center the 4x8 grid around it's pos parameter use: C 4 C 8 20 20

|-
| center
| boolean
| false
| Indicates if this cylinder shape should be centered at its position or not.
|-
| slide
| boolean
| false
| 
Indicates if this cylinder shape should be considered 'smooth' enough to make sliding of matching parts possible. If ether part of a matched pair of snap info metas has the slide option set to true the user will be able to slide them together. If not it will just 'snap'.

Be careful while setting this option as it can cause unwanted sliding of e.g. a stud inside an anti stud. In practice it is best to limit the slide=true value to things you know will slide most of the time (e.g. clips, bush and gear parts etc).
|}

====The snap clip meta====

The clip meta is used to describe all clip like shapes. Clips are always of the female gender and will be tested against male cylinder shapes.

‘‘‘Example’’’

<code><nowiki>0 !LDCAD SNAP_CLP [radius=4] [length=8] [pos=0 0 0] [ori=1 0 0 0 1 0 0 0 1] [center=true]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
ID
| string
|  
| See cylinder meta.
pos
| vector
|  
| See cylinder meta.
ori
| 3x3 matrix
|  
| See cylinder meta.
radius
| float
| 4.0
| Inner radius of the clip while in rest.
length
| float
| 8.0
| Length or width of the clip's (partial) hole.
center
| boolean
|  
| See cylinder meta.
slide
| boolean
|  
| See cylinder meta.
scale
| enum
| none
| See cylinder meta.
mirror
| enum
| none
| See cylinder meta.
|}

====The snap fingers meta====

The fingers meta is used to describe all the interlocking finger like shapes. finger shapes will only be tested among them selves.

‘‘‘Example’’’

<code><nowiki>0 !LDCAD SNAP_FGR [group=lckHng] [genderOfs=M] [seq=4.5 8 4.5] [radius=6] [center=true] [pos=-30 10 0] [ori=1 0 0 0 0 1 0 -1 0]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
ID
| string
|  
| See cylinder meta.
group
| string
|  
| See cylinder meta.
pos
| vector
|  
| See cylinder meta.
ori
| 3x3 matrix
|  
| See cylinder meta.
genderOfs
| enum
| male
| Indicates the gender of the first finger of the shape, must be ether M for male or F for female.
seq
| float array
|  
| Defines the width of each finger by a sequence of floats.
radius
| float
|  
| Outer radius of the finger (tip). these are usually beveled and thus the main snapping parameter.
center
| boolean
|  
| See cylinder meta.
scale
| enum
| none
| See cylinder meta.
mirror
| enum
| none
| See cylinder meta.
|}

====The snap generic meta====

The generic meta is used to describe very oddly shaped things which in practice only have a few counter parts. Things like electric plugs and window glass etc.

Matching is done only among generic metas themselves based on the group name alone. But the bounding information will influence the best candidate selection when multiple pairs are located closely together.

‘‘‘Example’’’

<code><nowiki>0 !LDCAD SNAP_GEN [group=nxtc] [gender=M] [pos=0 -1.5 1.5] [ori=1 0 0 0 0 1 0 -1 0] [bounding=box 12.5 16.5 8]</nowiki></code>

‘‘‘Properties’’’

{| class="wikitable"
|-
! Property
! Type
! Default
! Description
|-
ID
| string
|  
| See cylinder meta.
group
| string
|  
| See cylinder meta.
pos
| vector
|  
| See cylinder meta.
ori
| 3x3 matrix
|  
| See cylinder meta.
gender
| enum
| male
| See cylinder meta.
bounding
| mixed array
|  
| 
Defines a bounding shape which will be used in the 'best pair candidate' calculations. Is needed because the positional alone will might cause unwanted matches otherwise. There are several types of bounding shapes, namely:

pnt: Single point / no bounding box, no extra info needed.

box: Box defined by its following x, y, and z radius', for example: box 10 8 10

cube: Cube defined by a following (half) size, for example: cube 8

cyl: Cylinder defined by a following radius and length, for example: cyl 8 20

sph: Sphere defined by a following radius, for example: sph 8

scale
| enum
| none
| See cylinder meta.
mirror
| enum
| none
| See cylinder meta.