Flexible Part 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

Path Content METAs

Path content metas are used to define bendable parts inside a dedicated subfile. Based upon a collection of 0 !PATH_ lines the LDraw editor will be able to generate many kinds of flexible parts for use in your models. In order to also view those models correctly in other LDraw viewer/editor software that do not support these METAs, plain LDraw fallback code is encouraged to be added to the generated subfile.

The PATH_POINT META

The path point meta is used to define a point the generated path must pass through in a certain way. If multiple point metas are present the path will follow the order of line placement.

Point metas must only be used in the header and optionally kept grouped together.

Example

0 !PATH_POINT [type=bezier] [posOri=-110 0 0 1 0 0 0 1 0 0 0 1] [prevCPDist=25] [nextCPDist=25] [cirR=25] [cirDir=xyCW] [prevYRoll=0] [nextYRoll=0]

Properties

Property	Type	Default	Description
type	enum	bezier	Sets the point type, must be ether bezier or circle. Bezier points are used to guide the path through the center of this point using two control points, one in front and one behind it using the y axis of the points coordinate system (given by posOri). Circle points are used to guide the path around the center of this point on a 2D plane using a custom radius.
posOri	LDraw matrix		Position and orientation of this point. The orientation part is very important as it guides the path's direction using its local Y-axis.
prevCPDist	float	25.0	Defines the control point 'in front of' this point by setting the distance (over the local Y-axis) to it in relation to the point's center. This point's previous control point will be used by the previous path point next control point in order to do the bezier calculations for the line segment between them.
nextCPDist	float	25.0	Defines the control point 'next to' this point by setting the distance (over the local Y-axis) to it in relation to the point's center. This point's next control point will be used together width the previous control point of the next path point to do the bezier calculations for the line segment between them.
cirR	float	25.0	Sets the radius of the path guidance circle. Only used if the point type is circle.
cirDir	enum	xyCW	Used to select the 2D plane and winding direction this circle path point must use to guide the path around its center. Must be one of the following: xyCW: Clockwise around the local xy plane. xyCCW: Counter clockwise around the local xy plane. zyCW: Clockwise around the local zy plane. zyCCW: Counter clockwise around the local zy plane. Only used if the point type is circle.
prevYRoll	float	0.0	Sets the roll (in degrees) around the paths Y-axis the path donor is required to have before following the local circle arc. Needed when e.g. working with a square shaped rubber band to guide it from e.g. a bush onto a beveled wheel. Only used if the point type is circle.
nextYRoll	float	0.0	Sets the roll (in degrees) around the paths Y-axis the path donor is required to have before leaving the local circle arc. Needed when e.g. working with a square shaped rubber band to guide it from e.g. a beveled wheel onto a bush. Only used if the point type is circle.

The PATH_CAP META

The path cap meta is used to add static (sub)parts to a flexible part. This is usually reserved for the outer endings of the generate part e.g. the studs at both endings of a wire.

Cap metas must only be used in the header and optionally kept grouped together.

Example

0 !PATH_CAP [group=start] [color=16] [posOri=-170 8 0 1 0 0 0 1 0 0 0 1] [part=165.dat] [extraLen=0mm]

Properties

Property	Type	Default	Description
group	enum		Group is used to assign this cap to one of the groups available for this flexible part. It must be set to one of the following: start: All things that make up the starting point of a flexible part. This is usually a cap and the first path point. end: All things that make up the end point of a flexible part. This is usually a cap and the last path point.
color	ldrawColNr	16	Color to use given LDraw part with.
posOri	ldraw matrix		Position and orientation of the cap's part.
part	ldrawRef		LDraw part to use as a cap.
extraLen	unit	0mm	Can be used to state the captions length, can be used to corrected the total path length when the caption parts include e.g. part of the flexible donor structure themselves.

The PATH_ANCHOR META

The anchor meta is (optionally) used to force a custom center using the automatic path content groups. This might be needed for start and or end groups if the containing cap or path point isn't suitable or logically. There can only be one anchor meta per group type inside any path content subfile.

Anchor metas must only be used in the header and optionally kept grouped together.

Example

0 !PATH_ANCHOR [group=start] [posOri=-110 24 0 1 0 0 0 1 0 0 0 1]

Properties

Property	Type	Default	Description
group	enum		Group is used to assign this anchor to one of the groups available for this flexible part. It must be set to one of the following: start: All things that make up the starting point of a flexible part. This is usually a cap and the first path point. end: All things that make up the end point of a flexible part. This is usually a cap and the last path point. It is not allowed to set group to something another anchor is already set to.
posOri	ldraw matrix		Position and orientation of the anchor.

The PATH_SKIN META

The path skin meta is used to define how to fill/flesh out (part of) the path taken through the given point(s). There should be at least one skin meta in every path content subfile. It is allowed to use multiple skin metas. The total available path length will be divided amount multiple skin metas depending on their segments (seg*) related properties.

Skin metas must only be used in the header and optionally kept grouped together.

Example

0 !PATH_SKIN [donCol=16] [donOri=1 0 0 0 1 0 0 0 1] [donPart=3001.dat] [donYSize=100%] [donCen=absCen] [donCenYOfs=0] [donFinScale=fitDon2Seg] [donPlace=refsDyn] [donYAlign=0] [donInline=false] [segSize=100%] [segSizeTol=5%] [segsCnt=0] [segsGrp=0] [segsMaxMerge=1] [segsMrgAng=0] [segsEdgeDelKind=keepFirstLeft]

Properties

Property	Type	Default	Description
donCol	ldrawColNr	16	Color to use with the given donor part.
donOri	3x3 matrix		Rotation of the donor part. donOri act as a correction of the donor's own orientation in order to make the part Y-axis oriented. This because the donor part will be 'smeared' along the path in its local (after this correction) Y direction.
donPart	ldrawRef		Set the LDraw file to use for filling out the path. Any LDraw file is allowed here but in practice you want to limit usage to simple parts.
donYSize	unit	100%	This is used to set the base donor size in its Y direction. If for example the donor part is a tube section with a height of 2ldu could stretch (y-axis only) that using this option to e.g. 10ldu en large it times e..g 4 by using 400%.
donCen	enum	absCen	Used to choose the working center of the donor part. This option uses the donor as it is after the orientation corrections. It must be one of the following: partCen: Use the part origin. absCen: Use the absolute center of the part. absYCen: Use the part origin for the X and Z axis, but use the absolute center of its Y-axis. absXZCen: Use the absolute center of the X and Z axis, but use the part origin for the Y-axis.
donCenYOfs	float	0.0	Define an additional offset to the Y part of the donor (after donOri, donYSize and donCen corrections) to be used.
donFinScale	enum	fitDon2Seg	Controls how the donor is scaled before placement in a segment. It must be set to one of the following: none: No additional scaling. fitDon2Seg: Stretch/shrink the donor result to exactly fit the destination segment. Do note this might (partly) override some of the other don* scaling related parameters which could result in an unexpected end result.
donPlace	enum	refsDyn	Selects the placement / generation method. Must be one of the following: refsStat: Donors are placed using the calculated center (after donYAling correction) at the starting point of segments using that locations local path orientation. refsDyn: Donors are placed using the calculated center (after donYAling correction) at the center segements using that locations (interpolated) local path orientation. deform: The donor mesh is deformed in such a way it follows the path's curve as a result any fallback code will have the full recursive (transformed) source of the donor part for each segment it is used on. The deform method results in extremely smooth flexible parts but it might also result in very large LDraw files.
donYAlign	integer	0	Sets an alignment correction to use on the calculated donor center before placing a donor at a path segment. A negative number will shift the donor to the left by multiples of its Y length. So -1 will move it a full length to the left. A positive number will do the same to the right. 0 means no change will be made.
donInline	boolean	false	Determines if the generator will try to inline the donor file instead of referring to it directly while creating the segment fallback code. In-lining the donor file removes dependency on it and might increase portability of the fallback code. The donor will only be in-lined if it is entirely made out of type 1 lines.
segSize	unit	100%	Controls the length of individual segments along the resulting path. Each segment on the path will be filled out with a single donor part instance. Setting the segment size therefore controls how many times the donor might be used to fill out the path. Be care full when setting the segment size while using the deform method as it will greatly influence the resulting fallback file size. You can supply the segment size in ldu, mm or as a percentage of donYSize.
segSizeTol	unit	5%	Controls the amount of scaling allowed upon segments in order to fill rest space. If for example the segments size is 10 and the whole path has a length of 111, resulting in 11 segments, the remaining length of 1 will be spread over the 11 segments by scaling them slightly. Use this option to limit the amount of scaling to prevent e.g. noticeable distortions in the donor part. tolerance can be given in a static ldu, mm or a percentage of the calculated segment size it self.
segsCnt	integer	0	Used to set optionally set a fixed number of segments. 0 means unlimited segments can be used in order to construct the path. If a non zero value is given only a portion of the path will be filled out using this skin meta's options. This option can be used to limit the visible length of a flexible part and make room for other skin metas on the path.
segsGrp	integer	0	Used to group segments resulting from different skin metas. If set to 0 no grouping will be done and each skin meta will fill out its assigned space in order of the skin meta lines. If set to non zero skin metas using the same group number will alternate (zip together) their segments making possible e.g. color patterns.
segsMaxMerge	integer	1	In order to try and reduce the fallback code segments which are in a straight line of each other could optionally be joined into a single segment resulting in less donor placements. this option is only useful when the donor uses final scaling other wise you will end up with (large) gaps in your path.
segsMrgAng	float	0.0	optionally lets you define the maximum angle (in degrees) between two segments in order to deem them to be inline of each other. 0.0 indicates the internal (version depended) hard coded default should be used. Use this option with case as a large angle might cause alignment problems.
segsEdgeDelKind	enum	keepFirstLeft	Controls what to do with overlapping conditional lines while using the deform placement method. Must be one of the following: keepFirstLeft: Remove the left ones except for the first segment. keepLastRight: Remove the right ones except for the last segment. keepAll: Remove nothing, keep them all.

The PATH_LENGTH META

The path length meta is used to constrain the length of the path and or to define a real life (official library) counter part for the maximum length. When multiple length metas are present the constraint closest to the true length of the path will be applied in order to e.g. map path content to static LDraw files.

Length metas must only be used in the header and optionally kept grouped together.

Example

0 !PATH_LENGTH [lenTarget=50mm] [lenMargin=2%] [partName=some.dat] [partDescr=50 mm pneuhose]

Properties

Property	Type	Default	Description
lenTarget	unit	0	The maximum allowed path length this meta can be used for.
lenMargin	unit	0	The amount a path's length might differ from the true constrains in order to still qualify. This helps prevent unwanted exclusions and compensates for stretchable parts (e.g. rubber bands). The margin can be given in ldu, mm or a percentage upon the lenTarget value.
partName	ldrawRef		LDraw part which represents the static version of a path which matches this metas constrains. Currently this reference is never loaded so it does not have to exists. future versions of LDCad might use it in e.g. part usage overviews etc.
partDescr	string		Description to use for the given partName. Currently nothing is done with this value but future versions of LDCad might use it when e.g. the partName LDraw file can not be found (is virtual)

Spring Content METAs

Spring content metas are used to define parts which include a movable spring inside a dedicated subfile. Based upon a collection of 0 !SPRING_ lines a LDraw compliant editor will be able to generate many kinds of spring oriented parts for use in your models. In order to also view those models correctly in other LDraw viewer/editor software a generated meta can be used to add plain LDraw fallback code to the subfile.

The SPRING_POINT META

The spring point meta is used to define at most two points using different group settings. These are the points the generated spring will connect using one or more section metas.

Point metas must only be used in the header and optionally kept grouped together.

Example

0 !SPRING_POINT [group=start] [posOri=0 24 0 1 0 0 0 1 0 0 0 1]

Properties

Property	Type	Default	Description
group	enum		Group is used to assign this point to one of the automatic groups available for spring parts. It must be set to one of the following: start: This point represents the start or bottom of the spring. end: This point represents the end or top of the spring. It is not allowed to set group to something another point is already set to.
posOri	LDraw matrix		Position and location of this spring point.

The SPRING_CAP META

The cap meta is used to add static part(s) to ether the start or end of the spring oriented part.

Example

0 !SPRING_CAP [group=start] [color=16] [posOri=0 24 0 1 0 0 0 1 0 0 0 1] [part=3005.dat]

Properties

Property	Type	Default	Description
group	enum		Group is used to assign this cap to one of the automatic groups available for spring parts. It must be set to one of the following: start: This cap connects to the start or bottom of the spring. end: This cap connects to the end or top of the spring.
color	ldrawColNr	16	Color to use for this cap part.
posOri	LDraw matrix		Position and location of this cap part.
part	ldrawRef		LDraw part to use for this cap. Can be anything but in practice it should be a single LDraw part as it might hurt render performance otherwise.

The SPRING_ANCHOR META

The anchor meta is used to force a custom center (and orientation) for one of the spring related groups. There can only be one anchor meta per group type in any spring content subfile.

Anchor metas must only be used in the header and optionally kept grouped together.

Example

0 !SPRING_ANCHOR [group=start] [posOri=0 48 0 1 0 0 0 1 0 0 0 1]

Properties

Property	Type	Default	Description
group	enum		Group is used to assign this cap to one of the automatic groups available for spring parts. It must be set to one of the following: start: This cap connects to the start or bottom of the spring. end: This cap connects to the end or top of the spring.
posOri	LDraw matrix		Position and location of this anhor.

The SPRING_SECTION META

The section meta is used to define the appearance of (part of) the spring wire connecting the two spring points. At least one section meta should be present. When multiple section metas are given the available spring length will be divided among them based on the proportion property.

Section metas must only be used in the header and optionally kept grouped together.

Example

0 !SPRING_SECTION [windingCnt=5] [proportion=1]

Properties

Property	Type	Default	Description
windingCnt	float	5.0	Number of windings around the springs' Y-direction this meta should make within the available length.
proportion	integer	1	Defines the portion of the total spring length this section controls. If set to 0 the wire will be wound tightly and this section's length depends on the number of windings and wire thickness. If set to non zero the available length will be calculated by taking the leftover length (spring length minus the length used by zero proportion sections) divided by the sum of all proportion values multiplied by this meta's proportional value. For example imagine having a spring of length 100 using 4 section metas. If one of those sections uses a proportion of 2 and the other three use 1 the resulting section lengths will be: 40 (2 5ths), 20 (1 5th), 20 and 20.