Language¶

Symbols¶

t - True
nil - False
pi - 3.14159
e - 2.7182
step-offset - User settable to a number, or a function with no arguments that returns a number. This number is added to the part_step parameter of the part() function. The default value is 0.
time-index - 0..N, for creating animations.

Functions¶

class opensdraw.lcad_language.coreFunctions.Append¶

append - Add one or more elements to a list.

Usage:

(def l (list 1))  ; Create the list (1).
(append l 2)      ; The list is now (1, 2).

class opensdraw.lcad_language.coreFunctions.Aref¶

aref - Return an element of a list, vector or matrix.

Usage:

(aref (list 1 2 3) 1)           ; returns 2
(set (aref (list 1 2 3) 1) 4)   ; list is now 1, 4, 3
(aref (vector 1 2 3) 1)         ; returns 2
(set (aref (vector 1 2 3) 1) 4) ; vector is now 1, 4, 3

class opensdraw.lcad_language.coreFunctions.Block¶

block - A block of code, similar to progn in Lisp.

Usage:

(block
  (def x 15)    ; local variable x
  (def inc-x () ; function to modify x (and return the current value).
    (+ x 1))
  inc-x)        ; return the inc-x function

class opensdraw.lcad_language.coreFunctions.Concatenate¶

concatenate - Concatenate 1 or more strings.

Usage:

(concatenate "as" "df")  ; Returns "asdf".
(concatenate "as" 1)     ; Returns "as1".

class opensdraw.lcad_language.coreFunctions.Cond¶

cond - Switch statement.

Usage:

(cond
  ((= x 1) ..) ; do this if x = 1
  ((= x 2) ..) ; do this if x = 2
  ((= x 3) ..) ; do this if x = 3
  (t ..))      ; otherwise do this

class opensdraw.lcad_language.coreFunctions.Copy¶

copy - Make a copy.

Usage:

(def a (list 1 2 3) b (copy a)) ; Make two independent lists with elements 1, 2, 3.

class opensdraw.lcad_language.coreFunctions.Def¶

def - Create a variable or function.

Usage:

(def x 15) - Create the variable x with the value 15.
(def x 15 y 20) - Create x with value 15, y with value 20.
(def incf (x) (+ x 1)) - Create the function incf.

Note: You cannot create multiple functions at the same time.:

(def fn (x y)  ; Wrong. def() will think you are trying to create
 (+ x 1)       ; two symbols, the first called 'fn' and the second
 (+ y 2))      ; called '(+ x 1)' and throw a likely confusing error
               ; message.

(def fn (x y)  ; Correct.
 (block
  (+ x 1)
  (+ y 2)))

class opensdraw.lcad_language.coreFunctions.For¶

for - For statement.

Usage:

(for (i 10) ..)           ; increment i from 0 to 9.
(for (i 1 11) ..)         ; increment i from 1 to 11.
(for (i 1 0.1 5) ..)      ; increment i from 1 to 5 in steps of 0.1.
(for (i (list 1 3 4)) ..) ; increment i over the values in the list.

class opensdraw.lcad_language.coreFunctions.If¶

if - If statement.

The first argument must be t or nil.

Usage:

(if t 1 2)       ; returns 1
(if 1 2 3)       ; error
(if (= 1 1) 1 2) ; returns 1
(if x 1 0)       ; error if x is not t or nil
(if (= x 2) 3)
(if (= (fn) 0)   ; if / else
  (block 
     (fn1 1) 
     (fn2))
  (fn3 1 2))

class opensdraw.lcad_language.coreFunctions.Import¶

import - Import a module.

Module are searched for in the current working directory first, then in the library folder of the opensdraw project. The modules are assumed to be in files that end with the “.lcad” extension.

Usage:

(import mod1)      ; import mod1.lcad
(print mod1:x)     ; print the value of x in the mod1.lcad module.
(mod1:fn 1)        ; call the function fn in the mod1.lcad module.

(import mod1 mod2) ; import mod1.lcad and mod2.lcad.
(def mx mod1:x)    ; use m1 as an alternate name for mod1:x.
(print mx)         ; print the value of x in the mod1.lcad module.

(import mod1 mod2 :local) ; import mod1.lcad and mod2.lcad into the name space of current module.

class opensdraw.lcad_language.coreFunctions.Lambda¶

lambda - Create an anonymous function.

Usage:

(def fn (lambda (x) (+ x 1)))           ; Create a function and assign to symbol fn.
(fn 1)                                  ; -> 2
(def myp (lambda () (part "32524" 15))) ; Create function that creates a particular part.

class opensdraw.lcad_language.coreFunctions.Len¶

len - Return the length of a list.

Usage:

(len (list 1 2 3)) ; returns 3

class opensdraw.lcad_language.coreFunctions.List¶

list - Create a list.

Usage:

(list 1 2 3)  ; returns the list 1,2,3
(list)        ; an empty list

class opensdraw.lcad_language.coreFunctions.Print¶

print - Print to the console.

Usage:

(print x "=" 10)

class opensdraw.lcad_language.coreFunctions.PyImport¶

pyimport - Import a Python module and add any functions in the modules lcad_functions{} dictionary (that are instances of LCadFunction) to the current lexical environment. The module must be on the Python path (which includes the current working directory).

Usage:

(pyimport mymodule)  ; Import the Python module mymodule.py.

class opensdraw.lcad_language.coreFunctions.Set¶

set - Set the value of an existing symbol.

Usage:

(set x 15) - Set the value of x to 15.
(set x 15 y 20) - Set x to 15 and y to 20.
(set x fn) - Set x to be the function fn.

class opensdraw.lcad_language.coreFunctions.While¶

while - While loop.

Usage:

(def x 1)
(while (< x 10) .. )

Part Functions¶

class opensdraw.lcad_language.partFunctions.Comment¶

comment - Adds comments into the current group.

This different from header() in that these will appear in the body of the file along with parts, etc.. And if group has comments then the step parameter of the part() function will be ignored, so if steps are desired they’ll need to be manually created with this function.

This will add a line of text, prepended with “0 “, to the current model. Multiple calls will add multiple lines, in the same order as the calls.

Usage:

(comment "BFC INVERTNEXT")
(comment "STEP")

class opensdraw.lcad_language.partFunctions.Group¶

group - Creates a group (or sub-file) in the model.

This allows the grouping of parts to create a multi-part output file. Normally you probably want to group parts into a function, but sometimes you might want to generate output that is better formatted for tools that work on mpd files.

Note

Every model will have at least one group, main.
When created groups always have the identity transformation matrix, not the current transformation matrix.
Group names must be unique (and also not overlap with the names of any LDraw part files).

Usage:

(group "assembly1"   ; Create a group called "assembly1"
  (part ..))         ; containing a single part.

class opensdraw.lcad_language.partFunctions.Header¶

header - Adds header information to the current group.

This will add a line of text, prepended with “0 “, to the current model. Multiple calls will add multiple lines, in the same order as the calls.

Usage:

(header "FILE mymoc")
(header "Name: mymoc")
(header "Author: My Name")

class opensdraw.lcad_language.partFunctions.Line¶

line - Add a line primitive to the current group.

The arguments are (list x1 yz 1) (list x2 y2 z2).

Parameters:	x1 – x position of vertex 1. y1 – y position of vertex 1. z1 – z position of vertex 1. x2 – x position of vertex 2. y2 – y position of vertex 2. z2 – z position of vertex 2. color – (optional) line color, defaults to 16, the “main color”.

Usage:

(line (list x1 y1 z1) (list x2 y2 z2) color)    ; A line from (x1, y1, z1) to (x2, y2, z2) with color color.
(line (list x1 y1 z1) (list x2 y2 z2))          ; Same as above, but now color will be the "main color", i.e. 16.

class opensdraw.lcad_language.partFunctions.OptionalLine¶

optional-line - Add a optional line primitive to the current group.

The arguments are (list x1 yz 1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4).

Parameters:

x1 – x position of line vertex 1.
y1 – y position of line vertex 1.
z1 – z position of line vertex 1.
x2 – x position of line vertex 2.
y2 – y position of line vertex 2.
z2 – z position of line vertex 2.
x1 – x position of control vertex 1.
y1 – y position of control vertex 1.
z1 – z position of control vertex 1.
x2 – x position of control vertex 2.
y2 – y position of control vertex 2.
z2 – z position of control vertex 2.
color – (optional) line color, defaults to 16, the “main color”.

Usage:

(optional-line (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4) color) ; A optional line with vertices (x1, y1, z1), (x2, y2, z2) 
                                                                                      ; and control point vertices (x3, y3, z3), (x4, y4, z4).
(optional-line (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4))       ; Same as above, but now color will be the "main color", i.e. 16.

class opensdraw.lcad_language.partFunctions.Part¶

part - Add a part to the current group.

Parameters:	part_id – The name of the LDraw .dat file for this part. part_color – The LDraw name or id of the color. part_step – (Optional) Which building step to add the part (default = first step).

Usage:

(part "32524" 13)           ; Technic Beam 7, LDraw color 13.
(part '32524' "yellow")     ; Technic Beam 7, LDraw color yellow.
(part "32524" "yellow" 10)  ; Technic Beam 7, LDraw color yellow, step 10.
(part "32524" "0x2808080")  ; Technic Beam 7, direct color (gray).

class opensdraw.lcad_language.partFunctions.Quadrilateral¶

quadrilateral - Add a quadrilateral primitive to the current group.

The arguments are (list x1 yz 1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4).

Parameters:

x1 – x position of vertex 1.
y1 – y position of vertex 1.
z1 – z position of vertex 1.
x2 – x position of vertex 2.
y2 – y position of vertex 2.
z2 – z position of vertex 2.
x3 – x position of vertex 3.
y3 – y position of vertex 3.
z3 – z position of vertex 3.
x4 – x position of vertex 4.
y4 – y position of vertex 4.
z4 – z position of vertex 4.
color – (optional) fill color, defaults to 16, the “main color”.

You should probably also specify a winding order using the header() function.

Example:

(header "BFC CERTIFY CCW")

Usage:

(quadrilateral (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4) color) ; A quadrilateral with vertices (x1, y1, z1), (x2, y2, z2), (x3, y3, z3), (x4, y4, z4).
(quadrilateral (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3) (list x4 y4 z4))       ; Same as above, but now color will be the "main color", i.e. 16.

class opensdraw.lcad_language.partFunctions.Triangle¶

triangle - Add a triangle primitive to the current group.

The arguments are (list x1 yz 1) (list x2 y2 z2) (list x3 y3 z3).

Parameters:	x1 – x position of vertex 1. y1 – y position of vertex 1. z1 – z position of vertex 1. x2 – x position of vertex 2. y2 – y position of vertex 2. z2 – z position of vertex 2. x3 – x position of vertex 3. y3 – y position of vertex 3. z3 – z position of vertex 3. color – (optional) fill color, defaults to 16, the “main color”.

You should probably also specify a winding order using the header() function.

Example:

(header "BFC CERTIFY CCW")

Usage:

(triangle (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3) color)  ; A triangle with vertices (x1, y1, z1), (x2, y2, z2), (x3, y3, z3).
(triangle (list x1 y1 z1) (list x2 y2 z2) (list x3 y3 z3)         ; Same as above, but now color will be the "main color", i.e. 16.

Comparison Functions¶

class opensdraw.lcad_language.comparisonFunctions.Equal(name)¶

=

Usage:

(= 1 1)     ; t
(= 1 2)     ; nil
(= 2 2 2 2) ; t
(= "a" "a") ; t

class opensdraw.lcad_language.comparisonFunctions.Ne(name)¶

!=

Usage:

(!= 2 1) ; t

class opensdraw.lcad_language.comparisonFunctions.Gt(name)¶

>

Usage:

(> 2 1) ; t

class opensdraw.lcad_language.comparisonFunctions.Ge(name)¶

>=

Usage:

(>= 2 1) ; t

class opensdraw.lcad_language.comparisonFunctions.Lt(name)¶

<

Usage:

(< 2 1) ; nil

class opensdraw.lcad_language.comparisonFunctions.Le(name)¶

<=

Usage:

(<= 2 1) ; nil

Logical Functions¶

class opensdraw.lcad_language.logicFunctions.And(name)¶

and - And statement.

Usage:

(and (< 1 2) (< 2 3)) ; t
(and (fn x) nil)      ; nil

class opensdraw.lcad_language.logicFunctions.Or(name)¶

or - Or statement.

Usage:

(or (< 1 2) (> 1 3))  ; t
(or (fn x) t)         ; t
(or nil nil)          ; nil

class opensdraw.lcad_language.logicFunctions.Not(name)¶

not - Not statement.

Usage:

(not t)  ; nil
(not ()) ; t

Type Functions¶

class opensdraw.lcad_language.typeFunctions.IsBoolean(name)¶

boolean? - Returns t/nil if argument is a boolean.

Usage:

(boolean? nil) ; t
(boolean? 1)   ; nil

class opensdraw.lcad_language.typeFunctions.IsMatrix(name)¶

matrix? - Returns t/nil if argument is a matrix.

Usage:

(matrix? (matrix 0 0 0 0 0 0)) ; t
(matrix? (vector 0 0 0))       ; nil

class opensdraw.lcad_language.typeFunctions.IsNumber(name)¶

number? - Returns t/nil if argument is a number.

Usage:

(number? 1)   ; t
(number? "a") ; nil

class opensdraw.lcad_language.typeFunctions.IsString(name)¶

string? - Returns t/nil if argument is a string.

Usage:

(string? 1)   ; nil
(string? "a") ; t

class opensdraw.lcad_language.typeFunctions.IsVector(name)¶

vector? - Returns t/nil if argument is a vector.

Usage:

(vector? (matrix 0 0 0 0 0 0)) ; nil
(vector? (vector 0 0 0))       ; t     

Geometry Functions¶

class opensdraw.lcad_language.geometryFunctions.CrossProduct¶

cross-product - Return the cross product of two vectors.

Parameters:	v1 – The first vector. v2 – The second vector. normalize – t/nil (Optional) Normalize the result vector, default is t.

Usage:

(cross-product (vector 1 0 0) (vector 0 1 0))     ; Returns (vector 0 0 1)
(cross-product (vector 1 0 0) (vector 0 2 0) nil) ; Returns (vector 0 0 2)

class opensdraw.lcad_language.geometryFunctions.DotProduct¶

dot-product - Return the dot product of two vectors.

Parameters:	v1 – The first vector. v2 – The second vector. normalize – t/nil (Optional) Normalize the result vector, default is t.

Usage:

(dot-product (vector 1 0 0) (vector 1 0 0))     ; Returns 1.
(dot-product (vector 1 0 0) (vector 0 1 0))     ; Returns 0.
(dot-product (vector 2 0 0) (vector 1 0 0) nil) ; Returns 2.

class opensdraw.lcad_language.geometryFunctions.Matrix¶

matrix - Return a 4 x 4 transform matrix.

The matrix is a numpy array. There are 4 different ways to call this function:

With (list x y z a b c d e f g h i) as defined here: http://www.ldraw.org/article/218.html#lt1

Parameters:	x – translation in x in LDU. y – translation in y in LDU. z – translation in z in LDU. a – m(0,0) b – m(0,1) c – m(0,2) d – m(1,0) e – m(1,1) f – m(1,2) g – m(2,0) h – m(2,1) i – m(2,2)

With (list x y z rx ry rz)

Parameters:	x – translation in x in LDU. y – translation in y in LDU. z – translation in z in LDU. rx – rotation around the x-axis in degrees. ry – rotation around the y-axis in degrees. rz – rotation around the z-axis in degrees.

With (list p-vec x-vec y-vec z-vec)

Parameters:	p-vec – translation vector in LDU. x-vec – x vector of the coordinate system. y-vec – y vector of the coordinate system. z-vec – z vector of the coordinate system.

The vectors x-vec, y-vec, z-vec should be orthogonal to each other. They will be normalized to length 1.

With another matrix, in which case a copy will be made.

Parameters:	m – 4 x 4 transformation matrix.

Usage:

(def m1 (matrix (list x y z a b c d e f g h i))) ; All the coefficients.
(def m2 (matrix (list x y z rx ry rz))           ; Translation & rotation values.
(def m3 (matrix (list (list 0 0 10)              ; 4 lists or vectors.
                      (list 1 0 0) 
                      (list 0 1 0) 
                      (list 0 0 1))))
(def m4 (matrix m1))                             ; m4 is a copy of m1.

class opensdraw.lcad_language.geometryFunctions.Mirror¶

mirror - Mirror child elements on a plane through the origin.

The arguments are (list mx my mz), or (vector mx my mz).

Parameters:	mx – mirror on x axis. my – mirror on y axis. mz – mirror on z axis.

Usage:

(mirror (list 1 0 0) ..) ; mirrors on the x axis.

class opensdraw.lcad_language.geometryFunctions.Rotate¶

rotate - Rotate child elements.

Add a rotation to the current transformation matrix, rotation is done first around z, then y and then x. Parts added inside a rotate block have this transformation applied to them.

The arguments are (list ax ay az), or (vector ax ay az).

Parameters:	ax – Amount to rotate around the x axis in degrees. ay – Amount to rotate around the y axis in degrees. az – Amount to rotate around the z axis in degrees.

Usage:

(rotate (list 0 0 90) .. )
(rotate (vector 0 0 90) .. )

class opensdraw.lcad_language.geometryFunctions.Scale¶

scale - Scale child elements.

Add scale terms to the current transformation matrix. Parts inside a scale block have this transformation applied to them. This is probably not a good idea for standard parts, but it seems to be used with some part primitives.

The arguments are (list sx sy sz), or (vector sx sy sz).

Parameters:	sx – Scale in x. sy – Scale in y. sz – Scale in z.

Usage:

(scale (list 2 1 1) .. )  ; stretch by a factor of two in the x dimension.

class opensdraw.lcad_language.geometryFunctions.Transform¶

transform - Transform child elements.

Transform child elements with a 4 x 4 transform matrix. This function is called in exactly the same way as the matrix() function.

Usage:

(transform (list x y z a b c d e f g h i) ; All the coefficients.
 ..)
(transform (list x y z rx ry rz)          ; Translate to x, y, z and rotate by rx, ry, rz.
 ..)
(transform m                              ; m is a 4x4 transform matrix.
 ..)

class opensdraw.lcad_language.geometryFunctions.Translate¶

translate - Translate child elements.

Add a translation to the current transformation matrix. Parts inside a translate block have this transformation applied to them.

The arguments are (list dx dy dz), or (vector dx dy dz).

Parameters:	dx – Displacement in x in LDU. dy – Displacement in y in LDU. dz – Displacement in z in LDU.

Usage:

(translate (list 0 0 5) .. )

class opensdraw.lcad_language.geometryFunctions.Vector¶

vector - Create a 4 element vector.

This is a numpy array. It can be used in place of a list for most of the geometry functions like rotate() and translate(). You can also multiply it with 4 x 4 transformation matrices.

Parameters:	e1 – The first element in the vector. e2 – The second element in the vector. e3 – The third element in the vector. e4 – (Optional) The fourth element in the vector, defaults to 1.0.

Usage:

(def v (vector 0 0 5))  ; Create the vector [0 0 5 1]
(translate v .. )       ; Translate by 5 LDU in z.
(* mat v)               ; Multiply the vector with the 4 x 4 matrix mat.

Math Functions¶

class opensdraw.lcad_language.mathFunctions.Absolute(name)¶

abs

Return the absolute value of a number.

Usage:

(abs 2)  ; 2
(abs -2) ; 2

class opensdraw.lcad_language.mathFunctions.Plus(name)¶

+

Add together two or more numbers, vectors or matrices.

Usage:

(+ 10 20 y) ; 30 + y

class opensdraw.lcad_language.mathFunctions.Minus(name)¶

-

Subtract one or more numbers, vectors or matrices from the first number, vector or matrix.

Usage:

(- 50 20 y) ; -30 - y
(- 50)      ; -50

class opensdraw.lcad_language.mathFunctions.Multiply(name)¶

*

Multiply two or more numbers, vectors or matrices. If the first number is a matrix, then multiplication will be done using matrix multiplication, i.e. (* mat vec) will return a vector and (* mat mat) will return a matrix.

Usage:

(* 2 2 y) ; 4 * y

class opensdraw.lcad_language.mathFunctions.Divide(name)¶

/

Divide the first number, vector or matrix by one or more additional numbers, vectors or matrices. Vectors and matrices are divided pointwise.

Usage:

(/ 4 2) ; 2

class opensdraw.lcad_language.mathFunctions.Modulo(name)¶

%

Return remainder of the first number divided by the second number.

Usage:

(% 10 2) ; 0

All the functions in the python math library are also available:

Usage:

(cos x)
(sin x)
(degrees (atan2 2 3))
...

Random Number Functions¶

class opensdraw.lcad_language.randomNumberFunctions.RandSeed(name)¶

rand-seed - Initialize the random number generator.

Usage:

(rand-seed 10)

class opensdraw.lcad_language.randomNumberFunctions.RandChoice(name)¶

rand-choice - Return a random element from a list.

Usage:

(rand-choice (list 1 2 3)) ; return 1,2 or 3.
(rand-choice (list a b)) ; return a or b

class opensdraw.lcad_language.randomNumberFunctions.RandGauss(name)¶

rand-gauss - Return a gaussian distributed random number. This can be called with either 0 or 2 arguments.

Usage:

(rand-gauss)      ; mean = 0, standard deviation = 1.0
(rand-gauss 1 10) ; mean = 1, standard deviation = 10.0

class opensdraw.lcad_language.randomNumberFunctions.RandInteger(name)¶

rand-integer - Return a random integer

Usage:

(rand-integer 0 100) ; random integer between 0 and 100.
(rand-integer 2 30)  ; random integer between 2 and 30.

class opensdraw.lcad_language.randomNumberFunctions.RandUniform(name)¶

rand-uniform - Return a uniformly distributed random number. This can be called with either 0 or 2 arguments.

Usage:

(rand-uniform)      ; distributed on 0 - 1.
(rand-uniform 1 10) ; distributed on 1 - 10.