Ellipse

There is no built-in module that for generating an ellipse in OpenSCAD.

Either scale() or resize() may be used to modify a circle into an ellipse. See OpenSCAD User Manual/Transformations

both of these statements will create these examples:
 resize([30,10]) circle(d=20); // coerce the circle to the desired X-Y sizes
 scale([1.5,.5]) circle(d=20); // stretch or squish the circle by the given factors

Regular Polygons

There is no built-in module for generating regular polygons.

It is possible to use the special variable $fn as a parameter to the circle() module to set the number of sides of the polygon that is generated to approximate its shape.

 circle(r=1, $fn=4); // generate a square

A user defined module can generate the same shapes using some basic math and the polygon() module:

 module regular_polygon(order = 4, r=1)
   { // default parameters give a unit square
        // first divide 360 to make a vector of angles between vertices
   angles=[ for (i = [0:order-1]) i*(360/order) ];
        // use trigonometry to calculate Cartesian coordinates
   coords=[ for (th=angles) [r*cos(th), r*sin(th)] ];
   
   polygon(coords); // generate the polygon
   }
 regular_polygon(); // generate a default regular_polygon

Polygon shapes are generated by both the circle() and polygon() as if they were inscribed in a circle of the radius given and start from the first point on the positive x axis.

script for these examples
 translate([-42,  0]){circle(20,$fn=3);%circle(20,$fn=90);}
 translate([  0,  0]) circle(20,$fn=4);
 translate([ 42,  0]) circle(20,$fn=5);
 translate([-42,-42]) circle(20,$fn=6);
 translate([  0,-42]) circle(20,$fn=8);
 translate([ 42,-42]) circle(20,$fn=12);
 
 color("black"){
     translate([-42,  0,1])text("3",7,,center);
     translate([  0,  0,1])text("4",7,,center);
     translate([ 42,  0,1])text("5",7,,center);
     translate([-42,-42,1])text("6",7,,center);
     translate([  0,-42,1])text("8",7,,center);
     translate([ 42,-42,1])text("12",7,,center);
 }

Without holes

equivalent scripts for this example
 polygon(points=[[0,0],[100,0],[130,50],[30,50]]);
 polygon([[0,0],[100,0],[130,50],[30,50]], paths=[[0,1,2,3]]);
 polygon([[0,0],[100,0],[130,50],[30,50]],[[3,2,1,0]]);
 polygon([[0,0],[100,0],[130,50],[30,50]],[[1,0,3,2]]);
    
 a=[[0,0],[100,0],[130,50],[30,50]];
 b=[[3,0,1,2]];
 polygon(a);
 polygon(a,b);
 polygon(a,[[2,3,0,1,2]]);

One hole

equivalent scripts for this example
 polygon(points=[[0,0],[100,0],[0,100],[10,10],[80,10],[10,80]], paths=[[0,1,2],[3,4,5]],convexity=10);

 triangle_points =[[0,0],[100,0],[0,100],[10,10],[80,10],[10,80]];
 triangle_paths =[[0,1,2],[3,4,5]];
 polygon(triangle_points,triangle_paths,10);

The 1st path vector, [0,1,2], selects the points, [0,0],[100,0],[0,100], for the primary shape. The 2nd path vector, [3,4,5], selects the points, [10,10],[80,10],[10,80], for the secondary shape. The secondary shape is subtracted from the primary ( think difference() ). Since the secondary is wholly within the primary, it leaves a shape with a hole.

Multi hole

[Note: Requires version 2015.03] (for use of concat())

      //example polygon with multiple holes
a0 = [[0,0],[100,0],[130,50],[30,50]];     // main
b0 = [1,0,3,2];
a1 = [[20,20],[40,20],[30,30]];            // hole 1
b1 = [4,5,6];
a2 = [[50,20],[60,20],[40,30]];            // hole 2
b2 = [7,8,9];
a3 = [[65,10],[80,10],[80,40],[65,40]];    // hole 3
b3 = [10,11,12,13];
a4 = [[98,10],[115,40],[85,40],[85,10]];   // hole 4
b4 = [14,15,16,17];
a  = concat (a0,a1,a2,a3,a4);
b  = [b0,b1,b2,b3,b4];
polygon(a,b);
      //alternate 
polygon(a,[b0,b1,b2,b3,b4]);

Extruding a 3D shape from a polygon

   translate([0,-20,10]) {
       rotate([90,180,90]) {
           linear_extrude(50) {
               polygon(
                   points = [
                      //x,y
                       /*
                                  O  .
                       */
                       [-2.8,0],
                       /*
                                O__X  .
                       */
                       [-7.8,0],
                       /*
                              O
                               \
                                X__X  .
                       */
                       [-15.3633,10.30],
                       /*
                              X_______._____O
                               \         
                                X__X  .
                       */
                       [15.3633,10.30],
                       /*
                              X_______._______X
                               \             /
                                X__X  .     O
                       */
                       [7.8,0],
                       /*
                              X_______._______X
                               \             /
                                X__X  .  O__X
                       */
                       [2.8,0],
                       /*
                           X__________.__________X
                            \                   /
                             \              O  /
                              \            /  /
                               \          /  /
                                X__X  .  X__X
                       */
                       [5.48858,5.3],
                       /*
                           X__________.__________X
                            \                   /
                             \   O__________X  /
                              \            /  /
                               \          /  /
                                X__X  .  X__X
                       */
                       [-5.48858,5.3],
                                   ]
                               );
                           }
       }
   }

convexity

The convexity parameter specifies the maximum number of front sides (back sides) a ray intersecting the object might penetrate. This parameter is needed only for correct display of the object in OpenCSG preview mode and has no effect on the polyhedron rendering.

This image shows a 2D shape with a convexity of 2, as the ray indicated in red crosses the 2D shapes outside⇒inside (or inside⇒outside) a maximum of 2 times. The convexity of a 3D shape would be determined in a similar way. Setting it to 10 should work fine for most cases.

Vertical alignment

top

The text is aligned so the top of the tallest character in your text is at the given Y coordinate.

center

The text is aligned with the center of the bounding box at the given Y coordinate. This bounding box is based on the actual sizes of the letters, so taller letters and descenders will affect the positioning.

baseline

The text is aligned with the font baseline at the given Y coordinate. This is the default, and is the only option that makes different pieces of text align vertically, as if they were written on lined paper, regardless of character heights and descenders.

bottom

The text is aligned so the bottom of the lowest-reaching character in your text is at the given Y coordinate.

 text = "Align";
 font = "Liberation Sans";
 
 valign = [
   [  0, "top"],
   [ 40, "center"],
   [ 75, "baseline"],
   [110, "bottom"]
 ];
 
 for (a = valign) {
   translate([10, 120 - a[0], 0]) {
     color("red") cube([135, 1, 0.1]);
     color("blue") cube([1, 20, 0.1]);
     linear_extrude(height = 0.5) {
       text(text = str(text,"_",a[1]), font = font, size = 20, valign = a[1]);
     }
   }
 }

The text() module doesn't support multi-line text, but you can make a separate call for each line, using translate() to space them. A spacing of 1.4*size is the minimum required to prevent lines overlapping (if they include descenders). 1.6*size is approximately the default single-spacing in many word processing programs. To get evenly spaced lines, use "baseline" vertical alignment; otherwise, lines may be lower or higher depending on their contents.

Horizontal alignment

left

The text is aligned with the left side of the bounding box at the given X coordinate. This is the default.

center

The text is aligned with the center of the bounding box at the given X coordinate.

right

The text is aligned with the right of the bounding box at the given X coordinate.

 text = "Align";
 font = "Liberation Sans";
 
 halign = [
   [10, "left"],
   [50, "center"],
   [90, "right"]
 ];
 
 for (a = halign) {
   translate([140, a[0], 0]) {
     color("red") cube([115, 2,0.1]);
     color("blue") cube([2, 20,0.1]);
     linear_extrude(height = 0.5) {
       text(text = str(text,"_",a[1]), font = font, size = 20, halign = a[1]);
     }
   }
 }

textmetrics()

The textmetrics() function accepts the same parameters as text(), and returns an object describing how the text would be rendered.

The returned object has these members:

• position: the position of the lower-left corner of the generated text.
• size: the size of the generated text.
• ascent: the amount that the text extends above the baseline.
• descent: the amount that the text extends below the baseline.
• offset: the lower-left corner of the box containing the text, including inter-glyph spacing before the first glyph.
• advance: the "other end" of the text, the point at which additional text should be positioned.

   s = "Hello, World!";
   size = 20;
   font = "Liberation Serif";
   
   tm = textmetrics(s, size=size, font=font);
   echo(tm);
   translate([0,0,1]) text("Hello, World!", size=size, font=font);
   color("black") translate(tm.position) square(tm.size);

yields (reformatted for readability):

   ECHO: {
       position = [0.7936, -4.2752];
       size = [149.306, 23.552];
       ascent = 19.2768;
       descent = -4.2752;
       offset = [0, 0];
       advance = [153.09, 0];
   }

fontmetrics()

The fontmetrics() function accepts a font size and a font name, both optional, and returns an object describing global characteristics of the font.

Parameters

size

Decimal, optional. The size of the font, as described above for text().

font

String, optional. The name of the font, as described above for text().

Note that omitting the size and/or font may be useful to get information about the default font.

Returns an object:

• nominal: usual dimensions for a glyph:
  • ascent: height above the baseline
  • descent: depth below the baseline
• max: maximum dimensions for a glyph:
  • ascent: height above the baseline
  • descent: depth below the baseline
• interline: design distance from one baseline to the next
• font: identification information about the font:
  • family: the font family name
  • style: the style (Regular, Italic, et cetera)

   echo(fontmetrics(font="Liberation Serif"));

yields (reformatted for readability):

   ECHO: {
       nominal = {
           ascent = 12.3766;
           descent = -3.0043;
       };
       max = {
           ascent = 13.6312;
           descent = -4.2114;
       };
       interline = 15.9709;
       font = {
           family = "Liberation Serif";
           style = "Regular";
       };
   }


Category:Book:OpenSCAD User Manual#Using%20the%202D%20Subsystem%20

Parameters For Linear Extrusion

height

a non-negative integer, default 100, giving the length of the extrusion

center

a boolean, default false, that, when true, causes the resulting solid to be vertically centered at the X-Y plane.

convexity

a non-negative integer, default 1, giving a measure of the complexity of the generated surface. See the Section on Convexity later on this page.

twist

a signed decimal, default 0.0, specifying how many degrees of twist to apply between the start and end faces of the extrusion. 180 degrees is a half twist, 360 is all the way around, and so on.

v - twist axis vector

a vector of 3 signed decimal values, default [0,0,1], used as an eigen vector specifying the axis of rotation for the twist. [Note: Requires version Development snapshot]

scale

a non-negative, decimal value, default 1.0, greater than 0.0, that specifies the factor by which the end face should be scaled up, or down, in size from that of the start face.

a vector containing these values in this order

[

slices

a non-negative integer value that acts on the extruded surface as $fn does, but which is not applied to the child 2D shape.

segments

Similar to slices but adding points on the polygon's segments without changing the polygon's shape.

$fn

the special variable but applied only to the extrusion

$fs

the special variable but applied only to the extrusion

$fa

the special variable but applied only to the extrusion

]

Notes

1. centering the extrusion only affects its vertical position. Its X-Y position is always set by the projection of its starting face.
2. A Scale Factor greater than one increases the size of the extrusion's end face, while a value greater than 0.0 and less than 1 shrink it. A value of 0.0 causes the end face to degenerate to a point, turning the extrusion into a pyramid, cone, or complex pointy shape according to what the starting shape is.
3. the twist is applied, by default, as a rotation about the Z Axis. When the start face is at the origin a twist creates a spiral out of any corners of the child shape. If the start face is translated away from the origin the twist creates a spring shape.
4. positive twist rotates clockwise, negative twist the opposite.
5. when the twist axis vector "v" is tilted away from the Z axis the twist is applied between the start and end faces without making them normal to the axis. They remain as flat shapes parallel to the X-Y plane and the twisted surfaces are thus distorted from what they would be normally. To have it otherwise it would be necessary to form the twisted extrusion on the Z Axis and then rotate it into position.
6. all the parameters need to be given as named as the addition of the "v" vector parameter causes a error when only positional parameters are given

A Unit Circle with No Twist

Generate an extrusion from a circle 2 units along the X Axis from the origin, centered vertically on the X-Y plane, with no twist. The extrusion appears to have a pentagonal cross-section because the extrusion's child is a 2D circle with the default value for $fn.

linear_extrude(height = 10, center = true, convexity = 10, twist = 0)
    translate([2, 0, 0])
        circle(r = 1);

A Unit Circle Twisted Left 100 Degrees

The same circle, but now with 100 degrees of counter-clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = -100)
    translate([2, 0, 0])
        circle(r = 1);

A Unit Circle Twisted Right 100 Degrees

The same circle, but now with 100 degrees of clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = 100)
    translate([2, 0, 0])
        circle(r = 1);

A Unit Circle Twisted Into a Spiral

The same circle, but made into a spiral by 500 degrees of counter-clockwise twist.

linear_extrude(height = 10, center = true, convexity = 10, twist = -500)
    translate([2, 0, 0])
        circle(r = 1);

Center

With center=false, the default, the extrusion is based on the X-Y plane and rises up in the positive Z direction.

When true it is centered vertically at the X-Y plane, as seen here:

Mesh Refinement

The slices parameter defines the number of intermediate points along the Z axis of the extrusion. Its default increases with the value of twist. Explicitly setting slices may improve the output refinement. Additional the segments parameter adds vertices (points) to the extruded polygon resulting in smoother twisted geometries. Segments need to be a multiple of the polygon's fragments to have an effect (6 or 9.. for a circle($fn=3), 8,12.. for a square() ).

linear_extrude(height = 10, center = false, convexity = 10, twist = 360, slices = 100)
translate([2, 0, 0])
circle(r = 1);

The special variables $fn, $fs and $fa can also be used to improve the output. If slices is not defined, its value is taken from the defined $fn value.

linear_extrude(height = 10, center = false, convexity = 10, twist = 360, $fn = 100)
translate([2, 0, 0])
circle(r = 1);

Scale

Scales the 2D shape by this value over the height of the extrusion. Scale can be a scalar or a vector:

 linear_extrude(height = 10, center = true, convexity = 10, scale=3)
 translate([2, 0, 0])
 circle(r = 1);

 linear_extrude(height = 10, center = true, convexity = 10, scale=[1,5], $fn=100)
 translate([2, 0, 0])
 circle(r = 1);

Note that if scale is a vector, the resulting side walls may be nonplanar. Use twist=0 and the slices parameter to avoid asymmetry.

 linear_extrude(height=10, scale=[1,0.1], slices=20, twist=0)
 polygon(points=[[0,0],[20,10],[20,-10]]);

Usage

rotate_extrude(angle = 360, start=0, convexity = 2) {...}

In 2021.01 and previous, you must use parameter names due to a backward compatibility issue.

convexity : If the extrusion fails for a non-trival 2D shape, try setting the convexity parameter (the default is not 10, but 10 is a "good" value to try). See explanation further down.

angle [Note: Requires version 2019.05] : Defaults to 360. Specifies the number of degrees to sweep, starting at the positive X axis. The direction of the sweep follows the Right Hand Rule, hence a negative angle sweeps clockwise.

start [Note: Requires version Development snapshot] : Defaults to 0 if angle is specified, and 180 if not. Specifies the starting angle of the extrusion, counter-clockwise from the positive X axis.

$fa : minimum angle (in degrees) of each fragment.

$fs : minimum circumferential length of each fragment.

$fn : fixed number of fragments in 360 degrees. Values of 3 or more override $fa and $fs

$fa, $fs and $fn must be named parameters. click here for more details,.

Examples

→

A simple torus can be constructed using a rotational extrude.

rotate_extrude(convexity = 10)
    translate([2, 0, 0])
        circle(r = 1);

Mesh Refinement

→

Increasing the number of fragments composing the 2D shape improves the quality of the mesh, but takes longer to render.

rotate_extrude(convexity = 10)
    translate([2, 0, 0])
        circle(r = 1, $fn = 100);

→

The number of fragments used by the extrusion can also be increased.

rotate_extrude(convexity = 10, $fn = 100)
    translate([2, 0, 0])
        circle(r = 1, $fn = 100);

Using the parameter angle (with OpenSCAD versions 2016.xx), a hook can be modeled .

eps = 0.01;
translate([eps, 60, 0])
    rotate_extrude(angle=270, convexity=10)
        translate([40, 0]) circle(10);
rotate_extrude(angle=90, convexity=10)
    translate([20, 0]) circle(10);
translate([20, eps, 0])
    rotate([90, 0, 0]) cylinder(r=10, h=80+eps);

Extruding a Polygon

Extrusion can also be performed on polygons with points chosen by the user.

Here is a simple polygon and its 200 step rotational extrusion. (Note it has been rotated 90 degrees to show how the rotation appears; the rotate_extrude() needs it flat).

rotate([90,0,0])        polygon( points=[[0,0],[2,1],[1,2],[1,3],[3,4],[0,5]] );

rotate_extrude($fn=200) polygon( points=[[0,0],[2,1],[1,2],[1,3],[3,4],[0,5]] );

→→

For more information on polygons, please see: 2D Primitives: Polygon.

Orientation

If you're making a round 360 degree extrusion, it doesn't matter where it starts. If, on the other hand, you're using $fn to make an extrusion with some specific number of sides, it can matter. With an odd number of sides, there will be a vertex on either the left or the right, and a side opposite it.

With angle not specified, the extrusion starts along the negative X axis, to the left of the origin. With an odd number of sides, there is a vertex on the left and a side on the right. (Note that this is inconsistent with the behavior for angle less than 360, and with the behavior for circle and other round primitives.)

With angle specified, and not equal to 360, the extrusion starts along the positive X axis, to the right of the origin.

For 2021.01 and earlier, if angle is equal to 360, the extrusion starts along the negative X axis, as for angle not being specified.

For the development snapshot, if angle is 360, the extrusion starts along the positive X axis, as for other cases where angle is specified. Explicitly specifying angle=360 thus yields results consistent with other round primitives.

A future release may change this behavior so that when angle is not specified the extrusion starts along the positive X axis, making all of these cases consistent.

start directly controls the start point. [Note: Requires version Development snapshot]

Parameters Used In All Extrusions

convexity

an integer that works as a measure of complexity based on the maximum number of sides a ray might penetrate as it passes through a shape.

OpenSCAD uses OpenCSG to render objects in preview mode using the Goldfeather algorithm which takes account of convexity to calculate which parts of a shape to render. The algorithm that generates the mesh for the full rendering operation uses a different method so this parameter that ignores convexity.

The preview render works by presuming an eye point from which rays are emitted towards the objects in view, which are then reflected back to the eye point with information about what to display in each pixel. When a shape may have parts hidden from view by a fold or opening the preview algorithm must process along each ray until it can be sure that it it has processed all the surfaces that the eye might see from its view point.

The details of how convexity is used are fully explained on the OpenCSG site in the Usage section but the gist is that the algorithm needs to be informed that it must work harder on more complex shapes. For instance, the convexity of a sphere is one and the convexity of a torus is two. It is certainly possible that from some view points every ray from the eye faces only a single surface, which is certainly true for the sphere. But from a viewpoint well off the torus central axis rays can pass through its front and back parts so a given pixel may need to show the front most face, or the back part of the doughnut, or the background. A value of convexity greater than the default 1 informs the renderer of the need to be more careful in its work.

This 2D shape has a convexity of 2, as there is at least one ray (the red line) that passes through its boundary twice on its way to or from the eye point. If convexity was at the default 1 the rendering process would stop at the first crossing and the possibility of that pixel needing to show the crossing at the other surface will not be evaluated, leading to faults in the preview image.

3D shapes are evaluated in the same way, higher convexity being needed when a ray might pass through many internal surfaces on its way to the view point. Arbitrarily setting convexity to 10 should solve most preview rendering issues, at the expense of slowing preview rendering. When a model has several convoluted shapes values more than 15 can slow rendering to the point of freezing the application.

Parameters For Linear Extrusion

height

a non-negative integer, default 100, giving the length of the extrusion

center

a boolean, default false, that, when true, causes the resulting solid to be vertically centered at the X-Y plane.

twist

a signed decimal, default 0.0, specifying how many degrees of twist to apply between the start and end faces of the extrusion

scale

a non-negative, decimal value, default 1.0, greater than 0.0, that specifies the factor by which the end face should be scaled up, or down, in size from that of the start face.

a vector containing these values in this order

[

slices

a non-negative integer value that acts on the extruded surface as $fn does, but which is not applied to the child 2D shape.

segments

Similar to slices but adding points on the polygon's segments without changing the polygon's shape.

$fn

the special variable but applied only to the extrusion

$fs

the special variable but applied only to the extrusion

$fa

the special variable but applied only to the extrusion

]

Note

1. centering the extrusion only affects its vertical position. Its X-Y position is always set by its starting face.
2. A Scale Factor greater than one increases the size of the extrusion's end face, while a value greater than 0.0 and less than 1 shrink it. A value of 0.0 causes the end face to degenerate to a point, turning the extrusion into a pyramid, cone, or complex pointy shape according to what the starting shape is. Category:Book:OpenSCAD User Manual#Using%20the%202D%20Subsystem%20