Libraries¶

Core Functions¶

class opensdraw.lcad_language.belt.LCadBelt¶

belt - Creates a belt function.

This function creates and returns a function that parametrizes a belt making it easier to add custom belts / chains to a MOC. Unlike the chain function this allows for (almost) arbitrary locations and orientations of the pulleys / sprockets. All units are in LDU.

Each pulley / sprocket is specified by a 4 member list consisting of (position orientation radius winding-direction).

Parameters:	position – A 3 element list specifying the location of the pulley / sprocket. orientation – A 3 element list specifying the vector perpendicular to the plane of the pulley / sprocket. radius – The radius of the pulley / sprocket in LDU. winding-direction – Which way the belt goes around the pulley / sprocket (1 = counter-clockwise, -1 = clockwise).

The belt goes around the pulleys / sprockets in the order in which they are specified, and when :continuous is t returns from the last pulley / sprocket to the first to close the loop.

When you call the created belt function you will get a 4 x 4 transform matrix which will translate to the requested position on the belt and orient to a coordinate system where the z-axis is pointing along the belt, the y-axis is in the plane of the belt and the x-axis is perpendicular to the plane of the belt, pointing in the direction of the pulley / sprocket perpendicular vector.

If you call the created belt function with the argument t it will return the length of the belt.

Additionally belt has the keyword argument:

:continuous t/nil  ; The default is t, distances will be interpreted modulo the belt length, and
                   ; the belt will go from that last pulley back to the first pulley. If nil
                   ; then negative distances will wrap around the first pulley and positive
                   ; distances will wrap around the last pulley.

Usage:

(def a-belt (belt (list (list (list 0 0 0) ; Create a belt with two pulleys.
                              (list 0 0 1) ; Pulley one is at 0,0,0 and is in the
                              1.0 1)       ; x-y plane with radius 1 and counter-clockwise
                        (list (list 4 0 0) ; winding direction.
                              (list 0 0 1) ; Pulley two is at 4,0,0 with radius 1.5.
                              1.5 1))))  

(def m (a-belt 1))                         ; m is a 4 x 4 transform matrix.
(a-belt t)                                 ; Returns the length of the belt.

class opensdraw.lcad_language.chain.LCadChain¶

chain - Creates a chain function.

This function creates and returns a function that parametrizes a chain, making it easier to add chains, tracks, etc. to a MOC. This is a simplified version of the belt function where everything is confined to the XY plane. If you just want a simple chain this is probably the function that you want to use. All units are LDU.

A chain must have at least two sprockets. Each sprocket is specified by a 4 member list consisting of (x y radius winding-direction).

Parameters:	x – The x location of the sprocket. y – The y location of the sprocket. radius – The radius of the sprocket. winding-direction – Which way the belt goes around the sprocket (1 = counter-clockwise, -1 = clockwise).

The chain goes around the sprockets in the order in which they are specified, and when :continuous is t returns from the last sprocket to the first sprocket to close the loop.

When you call the created chain function you will get a 4 x 4 transform matrix which will translate to the requested position on the chain and orient to a coordinate system where the z-axis is pointing along the chain, the y-axis is in the plane of the chain and the x-axis is perpendicular to the plane of the chain.

If you call the created chain function with the argument t it will return the length of the chain.

Additionally chain has the keyword argument:

:continuous t/nil  ; The default is t, distances will be interpreted modulo the chain length, and
                   ; the chain will go from that last sprocket back to the first sprocket. If nil
                   ; then negative distances will wrap around the first sprocket and positive
                   ; distances will wrap around the last sprocket.

Usage:

(def a-chain (chain (list (list -4 0 1 1)    ; Create a chain with two sprockets, the 1st at (-4,0) and
                          (list 4 0 1 1))))  ; the second at (4,0). Both sprockets have radius 1 and a
                                             ; counter-clockwise winding direction.
(def m (a-chain 1))                          ; m is a 4 x 4 transform matrix.
(a-chain t)                                  ; Returns the length of the chain.

class opensdraw.lcad_language.curve.LCadCurve¶

curve - Creates a curve function.

This function creates and returns a function that parametrizes a curve, specifically a cubic spline. All units are LDU.

Control points are specified by a 2 member list consisting of (position derivative).

Parameters:	position – A 3 element list specifying the location of the control point. derivative – A 3 element list specifying the derivative (tangent) of the curve as it passes through the control point.

The first control point is specified by a 3 member list consisting of (position derivative perpendicular)

Parameters:	position – A 3 element list specifying the location of the control point. derivative – A 3 element list specifying the derivative (tangent) of the curve as it passes through the control point. perpendicular – A 3 element list specifying an approximately perpendicular vector to the derivative.

A curve must have at least 2 control points.

When you call the created curve function you will get a 4 x 4 transform matrix which will translate to the requested position on the curve and orient to a coordinate system where z is along the curve and x is perpendicular to the coordinate system as defined by the perpendicular vector provided for the 1st control point.

If you call the created curve function with the argument t it will return the length of the curve.

Additionally curve has several keyword arguments:

:auto-scale   t/nil        ; The default is t, automatically scale the derivative to
                           ; minimize the maximum curvature of the curve.
:extrapolate  t/nil        ; The default is t, distances outside of the curve will be
                           ; linearly extrapolated from the end of the curve. If nil
                           ; then the distance will be modulo the curve length.
:scale        float > 0.0  ; The multiplier for auto-scale mode, defaults to 1. This 
                           ; sets the boundaries on the auto-scale optimal
                           ; derivative search range. If you change this you probably 
                           ; want a number greater than 1.0, which is the default value.
:twist        angle        ; Additional twist along the curve, defaults to 0.

Unfortunately auto scaling is a bit slow and sometimes fails, so more work is needed..

Usage:

(def my-curve (curve (list (list (list 0 0 0) (list 1 1 0) (list 0 0 1)) ; Create a curve going through (0,0,0), (5,0,0)
                           (list (list 5 0 0) (list 1 0 0))))            ; With derivative (1,1,0) and (1,0,0). Since we did
                                                                         ; not specify :auto-scale nil, the derivative will
                                                                         ; be scaled to create a hopefully pleasing curve.

(def m (my-curve 1))                                                     ; m is a 4 x 4 transform matrix for the
                                                                         ; curve at distance 1 along the curve.
(my-curve t)                                                             ; Returns the length of the curve.

class opensdraw.lcad_language.pulleySystem.LCadPulleySystem¶

pulley-system - Creates a pulley-system function.

This function creates and returns a function that parametrizes a pulley-system making it easier to add pulleys and string to a MOC. The function is very similar to belt(), except that the first element specifies a drum on which the string is wound and the last specifies either the end point of the string, or the direction that string goes after the last sprocket. All units are LDU.

A pulley-system must have at least two elements (including the initial drum and the final end point). Like belt, the pulleys are specified by a 4 element list consisting of (position orientation radius winding-direction).

Parameters:	position – A 3 element list specifying the location of the pulley. orientation – A 3 element list specifying the vector perpendicular to the plane of the pulley. radius – The radius of the pulley in LDU. winding-direction – Which way the string goes around the pulley (1 = counter-clockwise, -1 = clockwise).

The string goes around the pulleys in the order in which they are specified.

The initial drum is specified by the 7 element list (position orientation radius winding-direction drum-width string-thickness string-length).

Parameters:

position – A 3 element list specifying the location of the drum.
orientation – A 3 element list specifying the vector perpendicular to the plane of the drum.
radius – The radius of the drum in LDU.
winding-direction – Which way the string goes around the drum (1 = counter-clockwise, -1 = clockwise).
drum-width – The width of the drum in LDU.
string-thickness – The diameter of the string.
string-length – The amount of string wound around the drum, not the total string length.

The final end point is specified by a 2 element position list, (position/direction type).

Parameters:	position/direction – A 3 element list specifying the end point of the pulley system, or a tangent vector. type – This is either the string “point” or “tangent”.

When you call the created pulley-system function you will get a 4 x 4 transform matrix which will translate to the requested position on the string and orient to a coordinate system where the z-axis is pointing along the string, the y-axis is in the plane of the string and the x-axis is perpendicular to the plane of the string, pointing in the direction of the pulley perpendicular vector.

If you call the created pulley-system function with the argument t it will return the length of the string.

Usage:

; Drum at 0,0,0 rotating counter-clockwise in the x-y plane with radius
; 5, width 50 and 50 LDU of 1 LDU diameter string. The string then goes
; around a pulley 20,0,1 rotating counter-clockwise in the x-y plane
; with radius 5. After passing the pulley the string continues in the
; -x direction.
(def ps1 (pulley-system (list (list (list 0 0 0) (list 0 0 1) 5.0 1 5.0 1 50)
                              (list (list 20 0 1) (list 0 0 1) 5.0 1)
                              (list (list -1 0 0) "tangent"))))

; Drum at 0,0,0 rotating counter-clockwise in the x-y plane with radius
; 5, width 50 and 50 LDU of 1 LDU diameter string. The string then passes 
; through the point 20,0,0.
(def ps2 (pulley-system (list (list (list 0 0 0) (list 0 0 1) 5.0 1 5.0 1 50)
                              (list (list 20 0 0) "point"))))

(def m (ps1 1))   ; m is a 4 x 4 transform matrix.
(ps1 t)           ; Returns the length of pulley system ps1 including the 
                  ;  string on the drum.
(ps2 t)           ; Returns the length of pulley system ps2 including the
                  ;  string on the drum.

class opensdraw.lcad_language.spring.LCadSpring¶

spring - Creates a spring function.

This function creates and returns a function that parametrizes a spring making it easier to add custom springs to a MOC. All units are LDU. The spring is oriented along the z-axis.

Parameters:	length – The length of the spring. diameter – The diameter of the spring. gauge – The thickness of the spring wire. turns – The number of turns in the center part of the spring. end-turns – (optional) The number of turns at the end of the spring, default is 2.

Usage:

(import flexible-rod :locale)            ; Import the flexible-rod module.
(def a-spring (spring 40 10 1 10))       ; Create a length 40 spring with diameter 10, gauge 1 and 10 turns.
(flexible-rod a-spring 0 (a-spring t) 1) ; Draw a rod a long the path of a-spring with diameter 1.

(def a-spring (spring 40 10 1 10 1))     ; Same as above, but with only 1 turn at the end.

Extra Functions (Python)¶

These are functions that you will need to import in order to use. They can all be found in the opensdraw/library directory.

Knots¶

This module makes it easier to add a knot to your MOC.

(pyimport opensdraw.library.knots)

class opensdraw.library.knots.SheetBendKnot¶

sheet-bend-knot - Creates a sheet bend knot function.

This creates and returns a function that parametrizes a sheet bend knot. All units are LDU.

When you call the created knot function you will get a 4 x 4 transform matrix which will translate to the requested position on the knot and orient to a coordinate system where the z-axis is pointing along the knot, the x-axis is in the plane of the knot and the y-axis is perpendicular to the plane of the knot.

Parameters:	diameter – The diameter of the string. loop_size – The diameter of the loop.

Usage:

(def sbk (sheet-bend-knot 3 10)) ; A knot with 3 LDU diameter string and loop diameter of 10.
(def p1 (sbk 1))                 ; p1 is the list (x y z rx ry rz) which defines the
                                 ; knot at distance 1 along the knot.
(sbk t)                          ; Returns the length of the knot.

Overlay¶

This module make LDraw compatible images that can be overlaid on a MOC for scaling pictures. It can also be used for creating 2D (i.e. flat) stickers.

(pyimport opensdraw.library.overlay)

class opensdraw.library.overlay.Overlay¶

overlay - Create a semi-transparent LDraw compatible image from a normal image.

This function is useful for overlaying images for scaling purposes. It could also be used to create 2D stickers. The image will be in the XY plane with the upper left corner of the image at 0,0.

The function will return the highest color index that is used.

Parameters:	image – The name of the image file. scale – The conversion factor (LDU / pixel). index – The starting color index. LDraw uses color indices as high as 511, so 600+ is probably a good idea. transparency – Optional (0-255, lower is more transparent), default is 64.

Usage:

(overlay "blueprint.png" 2.0 600)

Parts Strings¶

This module lets you add parts using space delimited strings, instead of using functions like tb() and sb() from locate.lcad

(pyimport opensdraw.library.partsString)

class opensdraw.library.partsString.PartsFile¶

parts-file - Specify parts in a text file.

This lets you load parts from a text file that is formatted in the same fashion as for the parts-string() function.

Parameters:	file – A string containing the name of the file to load.

Usage:

(parts-file "parts_file.txt") ; Load parts from parts_file.txt

class opensdraw.library.partsString.PartsString¶

parts-string - Specify parts using a return delimited string.

This lets you specify parts using a return delimited string, instead of having to use a function like tb() or sb() from locate.lcad. When you have lots of parts with a relatively simple geometry this might be faster and easier. If the first line of the string contains the word “technic” then technic brick spacing will be used instead of standard brick spacing. Any line that contains 8 or 9 elements is assumed to specify a part as (x, y, z, x rotation, y rotation, z rotation, part, color, {optional} step). Other lines are ignored, including all lines that start with “;”.

Parameters:	string – The string of part locations and types.

Usage:

; 3 2x1 bricks using standard brick units.
(parts-string "0 0 0 -90 0 0 3004 Red
               0 0 1 -90 0 0 3004 Green
               0 0 2 -90 0 0 3004 Blue")

; 3 technic beam 2 using standard technic units.
(parts-string "technic
               0 2 0 90 0 0 43857 4
               0 2 1 90 0 0 43857 2
               0 2 2 90 0 0 43857 1")

Shapes¶

This module makes it easier (and faster) to create simple shapes from LDraw primitives.

(pyimport opensdraw.library.shapes)

class opensdraw.library.shapes.Axle¶

axle - Draw an axle using LDraw primitives.

Parameters:	curve – The curve that the axle should follow. start – The starting point on the curve. stop – The stopping point on the curve. orientation – (optional) Angle in degrees in the XY plane.

The axle will have the color 16.

Usage:

(axle curve 0 10) ; Draw an axle along curve from 0 to 10 (LDU).

class opensdraw.library.shapes.FlatCable¶

flat-cable - Draw a flat cable (i.e. EV3 or NXT style) using LDraw primitives.

Parameters:	curve – The curve that the cable should follow. start – The starting point on the curve. stop – The stopping point on the curve. width – The width of the cable. radius – The edge radius of the cable. orientation – (optional) Angle in degrees in the XY plane, default is 0 (the long axis of the cable is along the X axis).

The flat cable will have the color 16.

Usage:

(flat-cable curve 0 10 4 1) ; Draw a 4 LDU wide flat cable with 1 LDU radius edges.

class opensdraw.library.shapes.RibbonCable¶

ribbon-cable - Draw a ribbon cable using LDraw primitives.

Parameters:	curve – The curve that the cable should follow. start – The starting point on the curve. stop – The stopping point on the curve. strands – The number of strands in the cable. radius – The radius of a single strand in the cable. orientation – (optional) Angle in degrees in the XY plane, default is 0 (the long axis of the cable is along the X axis).

The ribbon cable will have the color 16.

Usage:

(ribbon-cable curve 0 10 4 1) ; Draw a 4 stranded ribbon cable with each strand
                              ; having a radius of 1 LDU.

class opensdraw.library.shapes.Ring¶

ring - Draw a ring using LDraw primitives.

Parameters:	m1 – Transform matrix for the first edge of the ring. v1 – Vector for the first edge of the ring. m2 – Transform matrix for the second edge of the ring. v2 – Vector for the second edge of the ring. ccw – Counterclockwise winding (t/nil).

The ring will have the color 16.

Usage:

(ring m1 v1 m2 v2 t)  ; Draw a ring with edge 1 defined by m1, v1
                      ; and edge 2 defined by m2, v2, with ccw winding.

class opensdraw.library.shapes.Rod¶

rod - Draw a rod using LDraw primitives.

Parameters:	curve – The curve that the rod should follow. start – The starting point on the curve. stop – The stopping point on the curve. radius – The radius of the rod.

The rod will have the color 16.

Usage:

(rod curve 0 10 2) ; Draw a 2 LDU diameter rod from 0 to 10 along curve.

class opensdraw.library.shapes.Tube¶

tube - Draw a tube using LDraw primitives.

Parameters:	curve – The curve that the tube should follow. start – The starting point on the curve. stop – The stopping point on the curve. inner_radius – The inner radius of the tube. outer_radius – The outer radius of the tube.

The tube will have the color 16.

Usage:

(tube curve 0 10 2 3) ; Draw a 2 LDU inner diameter, 3 LDU outer diameter 
                      ; tube from 0 to 10 along curve.

Extra Functions (LCad)¶

These are functions that you will need to import in order to use. They can all be found in the opensdraw/library directory.

cables.lcad - Rendering cables.
flexible-axle.lcad - Rendering flexible axle.
flexible-hose.lcad - Rendering flexible hoses.
flexible-rod.lcad - Rendering flexible rods.
ldu.lcad - Converting from bricks to LDU.
locate.lcad - Functions to make placing parts easier.
ribbed-hose.lcad - Rendering ribbed hoses.
triangles.lcad - Functions for calculating sides and angles of triangles.

TODO: Figure out how to import reST from non-Python code.