OpenSCAD User Manual/Transformations

From Wikibooks, open books for an open world
Jump to: navigation, search


Transformation affect the child nodes and as the name implies transforms them in various ways such as moving/rotating or scaling the child. Cascading transformations are used to apply a variety of transforms to a final child. Cascading is achieved by nesting statements i.e.

 transform()             e.g.  rotate([45,45,45])
   transform()                   translate([10,20,30])
     child()                       cube(10);

Note: child(...) is deprecated by children(...) in master. (2013.06 still uses child(...)).

Transformations can be applied to a group of child nodes by using '{' & '}' to enclose the subtree e.g.

 translate([0,0,-5])    or the more compact      translate([0,0,-5]) {
 {                                                 cube(10);
   cube(10);                                       cylinder(r=5,h=10);
   cylinder(r=5,h=10);                           }
 }


Advanced concept

As OpenSCAD uses different libraries to implement capabilities this can introduce some inconsistencies to the F5 preview behaviour of transformations. Traditional transforms (translate, rotate, scale, mirror & multimatrix) are performed using OpenGL in preview, while other more advanced transforms, such as resize, perform a CGAL operation, behaving like a CSG operation affecting the underlying object, not just transforming it. In particular this can affect the display of modifier characters, specifically "#" and "%", where the highlight may not display intuitively, such as highlighting the pre-resized object, but highlighting the post-scaled object.


scale[edit]

Scales its child elements using the specified vector. The argument name is optional.

Usage Example:
scale(v = [x, y, z]) { ... }
cube(10);
translate([15,0,0]) scale([0.5,1,2]) cube(10);

Image showing result of scale() transformation in OpenSCAD

resize[edit]

resize() is available since OpenSCAD 2013.06. It modifies the size of the child object to match the given x,y, and z.

There is a bug with shrinking in the 2013.06 release, that will be fixed in the next release.


Usage Example:

// resize the sphere to extend 30 in x, 60 in y, and 10 in the z directions.
resize(newsize=[30,60,10]) sphere(r=10);  

OpenSCAD Resize example ellipse

If x,y, or z is 0 then that dimension is left as-is.

// resize the 1x1x1 cube to 2x2x1
resize([2,2,0]) cube(); 

If the 'auto' parameter is set to true, it will auto-scale any 0-dimensions to match. For example.

// resize the 1x2x0.5 cube to 7x14x3.5
resize([7,0,0], auto=true) cube([1,2,0.5]);  

The 'auto' parameter can also be used if you only wish to auto-scale a single dimension, and leave the other as-is.

// resize to 10x8x1. Note that the z dimension is left alone.
resize([10,0,0], auto=[true,true,false]) cube([5,4,1]);

rotate[edit]

Rotates its child a degrees about the origin of the coordinate system or around an arbitrary axis. The argument names are optional if the arguments are given in the same order as specified above.

When a rotation is specified for multiple axes then the rotation is applied in the following order: x, y, z.

Usage:
rotate(a = deg, v = [x, y, z]) { ... }

For example, to flip an object upside-down, you might do this:

rotate(a=[0,180,0]) { ... }

The above example will rotate your object 180 degrees around the 'y' axis.

The optional argument 'v' allows you to set an arbitrary axis about which the object will be rotated.

Example with arbitrary origin.

rotate(a=45, v=[1,1,0]) { ... }

This example will rotate your object 45 degrees around the axis defined by the vector [1,1,0] i.e. 45 around X and 45 around Y.

image of result of rotate() transformation in OpenSCAD


If this is all a bit confusing, this might, or might not, help.
For the case of:

rotate([a, b, c]) { ... };

"a" is a rotation about the X axis, from the +Z axis, toward the -Y axis. NOTE: NEGATIVE Y.
"b" is a rotation about the Y axis, from the +Z axis, toward the +X axis.
"c" is a rotation about the Z axis, from the +X axis, toward the +Y axis.


Thus if "a" is fixed to zero, and "b" and "c" are manipulated appropriately, this is the spherical coordinate system.
So, to construct a cylinder from the origin to some other point (x,y,z):

length=sqrt(pow(x, 2) + pow(y, 2) + pow(z, 2));
b=acos(z/length);
c= x==0 ? 90 :(x>0 ? atan(y/x): atan(y/x)+180);
rotate([0, b, c]) cylinder(h=length, r=0.5);

rotate with a single scalar argument rotates around the Z axis. This is useful in 2D contexts where that is the only axis for rotation. For example:

rotate(45) square(10);

translate[edit]

Translates (moves) its child elements along the specified vector. The argument name is optional.

IExample

translate(v = [x, y, z]) { ... }
cube(2,center = true); 
translate([5,0,0]) 
  sphere(1,center = true);

image of result of the translate() transformation in OpenSCAD

mirror[edit]

Mirrors the child element on a plane through the origin. The argument to mirror() is the normal vector of a plane intersecting the origin through which to mirror the object.

Function signature:[edit]

mirror( [x, y, z] ) { ... }

Examples[edit]

rotate([0,0,10]) cube([3,2,1]);
mirror([1,0,0]) translate([1,0,0]) rotate([0,0,10]) cube([3,2,1]);

image of the result of the mirror() transformation in OpenSCAD

multmatrix[edit]

Multiplies the geometry of all child elements with the given 4x4 transformation matrix.

Usage: multmatrix(m = [...]) { ... }

Example (translates by [10, 20, 30]):

multmatrix(m = [ [1, 0, 0, 10],
                 [0, 1, 0, 20],
                 [0, 0, 1, 30],
                 [0, 0, 0,  1]
               ]) cylinder();

Example (rotates by 45 degrees in XY plane and translates by [10,20,30]):

angle=45;
multmatrix(m = [ [cos(angle), -sin(angle), 0, 10],
                [sin(angle), cos(angle), 0, 20],
                [0, 0, 1, 30],
                [0, 0, 0,  1]
              ]) union() {
   cylinder(r=10.0,h=10,center=false);
   cube(size=[10,10,10],center=false);
}

More?[edit]

Learn more about it here:

color[edit]

Displays the child elements using the specified RGB color + alpha value. This is only used for the F5 preview as CGAL and STL (F6) do not currently support color. The alpha value will default to 1.0 (opaque) if not specified.

Function signature:[edit]

color( [r, g, b, a] ) { ... }
color( [r, g, b], a=1.0 ) { ... } // since v. 2011.12 (?)
color( colorname, a=1.0 ) { ... } // since v. 2011.12

Note that the r, g, b, a values are limited to floating point values in the range [0,1] rather than the more traditional integers { 0 ... 255 }. However, nothing prevents you to using R, G, B values from {0 ... 255} with appropriate scaling: color([ R/255, G/255, B/255 ]) { ... }

Since version 2011.12, colors can also be defined by name (case insensitive). For example, to create a red sphere, you can write color("red") sphere(5);. Alpha is specified as an extra parameter for named colors: color("Blue",0.5) cube(5);

The available color names are taken from the World Wide Web consortium's SVG color list. A chart of the color names is as follows,
(note that both spellings of grey/gray including slategrey/slategray etc are valid):

Purples
Lavender
Thistle
Plum
Violet
Orchid
Fuchsia
Magenta
MediumOrchid
MediumPurple
BlueViolet
DarkViolet
DarkOrchid
DarkMagenta
Purple
Indigo
DarkSlateBlue
SlateBlue
MediumSlateBlue
Pinks
Pink
LightPink
HotPink
DeepPink
MediumVioletRed
PaleVioletRed
Blues
Aqua
Cyan
LightCyan
PaleTurquoise
Aquamarine
Turquoise
MediumTurquoise
DarkTurquoise
CadetBlue
SteelBlue
LightSteelBlue
PowderBlue
LightBlue
SkyBlue
LightSkyBlue
DeepSkyBlue
DodgerBlue
CornflowerBlue
RoyalBlue
Blue
MediumBlue
DarkBlue
Navy
MidnightBlue
Reds
IndianRed
LightCoral
Salmon
DarkSalmon
LightSalmon
Red
Crimson
FireBrick
DarkRed
Greens
GreenYellow
Chartreuse
LawnGreen
Lime
LimeGreen
PaleGreen
LightGreen
MediumSpringGreen
SpringGreen
MediumSeaGreen
SeaGreen
ForestGreen
Green
DarkGreen
YellowGreen
OliveDrab
Olive
DarkOliveGreen
MediumAquamarine
DarkSeaGreen
LightSeaGreen
DarkCyan
Teal
Oranges
LightSalmon
Coral
Tomato
OrangeRed
DarkOrange
Orange
Yellows
Gold
Yellow
LightYellow
LemonChiffon
LightGoldenrodYellow
PapayaWhip
Moccasin
PeachPuff
PaleGoldenrod
Khaki
DarkKhaki
Browns
Cornsilk
BlanchedAlmond
Bisque
NavajoWhite
Wheat
BurlyWood
Tan
RosyBrown
SandyBrown
Goldenrod
DarkGoldenrod
Peru
Chocolate
SaddleBrown
Sienna
Brown
Maroon
Whites
White
Snow
Honeydew
MintCream
Azure
AliceBlue
GhostWhite
WhiteSmoke
Seashell
Beige
OldLace
FloralWhite
Ivory
AntiqueWhite
Linen
LavenderBlush
MistyRose
Grays
Gainsboro
LightGrey
Silver
DarkGray
Gray
DimGray
LightSlateGray
SlateGray
DarkSlateGray
Black

Example[edit]

A 3-D multicolor sine wave

Here's a code fragment that draws a wavy multicolor object

 for(i=[0:36]) {
   for(j=[0:36]) {
     color( [0.5+sin(10*i)/2, 0.5+sin(10*j)/2, 0.5+sin(10*(i+j))/2] )
     translate( [i, j, 0] )
     cube( size = [1, 1, 11+10*cos(10*i)*sin(10*j)] );
   }
 }

Being that -1<=sin(x)<=1 then 0<=(1/2 + sin(x)/2)<=1 , allowing for the RGB components assigned to color to remain within the [0,1] interval.

Chart based on "Web Colors" from Wikipedia

minkowski[edit]

A box and a cylinder
Minkowski sum of the box and cylinder

Displays the minkowski sum of child nodes.

Usage example:

Say you have a flat box, and you want a rounded edge. There are many ways to do this, but minkowski is very elegant. Take your box, and a cylinder:

$fn=50;
cube([10,10,1]);
cylinder(r=2,h=1);

Then, do a minkowski sum of them:

$fn=50;
minkowski()
{
 cube([10,10,1]);
 cylinder(r=2,h=1);
}

hull[edit]

Two cylinders
Convex hull of two cylinders

Displays the convex hull of child nodes.

Usage example:

hull() {
   translate([15,10,0]) circle(10);
   circle(10);
 }