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

0 !SNAP_CLEAR [id=axleHole]

Properties

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

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]

Properties

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_CYL 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

0 !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]

Properties

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_CLP 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

0 !SNAP_CLP [radius=4] [length=8] [pos=0 0 0] [ori=1 0 0 0 1 0 0 0 1] [center=true]

Properties

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_FGR meta

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

Example

0 !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]

Properties

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_GEN 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

0 !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]

Properties

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.