# Using the 2D Subsystem

## 2D Primitives

All 2D primitives can be transformed with 3D transformations. Usually used as part of a 3D extrusion. Although infinitely thin, they are rendered with a 1 thickness.

### square

Creates a square at the origin of the coordinate system. When center is true the square will be centered on the origin, otherwise it is created in the first quadrant. The argument names are optional if the arguments are given in the same order as specified in the parameters

Parameters

size
Decimal or 2 value array. If a single number is given, the result will be a square with sides of that length. If a 2 value array is given, then the values will correspond to the lengths of the X and Y sides. Default value is 1.
center
Boolean. This determines the positioning of the object. If true, object is centered at (0,0). Otherwise, the square is placed in the positive quadrant with one corner at (0,0). Defaults to false.

Example

```square ([2,2],center = true);
```

### circle

Creates a circle at the origin of the coordinate system. The argument name is optional.

Parameters

Decimal. This is the radius of the circle. The resolution of the circle will be based on the size of the circle. If you need a small, high resolution circle you can get around this by making a large circle, then scaling it down by an appropriate factor, or you could set \$fn or other special variables. Default value is 1.
Decimal. This is the diameter of the circle. The resolution of the circle will be based on the size of the circle. If you need a small, high resolution circle you can get around this by making a large circle, then scaling it down by an appropriate factor, or you could set \$fn or other special variables. Default value is 1.

(NOTE: d is only available in versions later than 2014.03. Debian is currently know to be behind this)

Examples

```circle();  // uses default radius, r=1
```
```circle(r = 10);
circle(d = 20);
```
```scale([1/100, 1/100, 1/100]) circle(200); // this will create a high resolution circle with a 2mm radius
circle(2, \$fn=50); // Another way to create a high-resolution circle with a radius of 2.
```

### polygon

Create a polygon with the specified points and paths.

Parameters

points
vector of 2 element vectors, ie. the list of points of the polygon
paths
Either a single vector, enumerating the point list, ie. the order to traverse the points, or, a vector of vectors, ie a list of point lists for each seperate curve of the polygon. The latter is required if the polygon has holes. The parameter is optional and if omitted the points are assumed in order. (The 'pN' components of the paths vector are 0-indexed references to the elements of the points vector.)
convexity
Integer. Number of "inward" curves, ie. expected path crossings of an arbitraty line through the polygon. See below.

Usage

```polygon(points = [ [x, y], ... ], paths = [ [p1, p2, p3..], ...], convexity = N);
```

Example

```polygon(points=[[0,0],[100,0],[0,100],[10,10],[80,10],[10,80]], paths=[[0,1,2],[3,4,5]]);
```
Polygon example

In this example, we have 6 points (three for the "outer" triangle, and three for the "inner" one). We connect each one with two 2 path. In plain English, each element of a path must correspond to the position of a point defined in the points vector, e.g. "1" refers to [100,0].

Notice: In order to get a 3D object, you either extrude a 2D polygon (linear or (rotation ) or directly use the polyhedron primitive solid. When using extrusion to form solids, its important to realize that the winding direction of the polygon is significant. If a polygon is wound in the wrong direction with respect to the axis of rotation, the final solid (after extrusion) may end up invisible. This problem can be checked for by flipping the polygon using scale([-1,1]) (assuming that extrusion is being done about the Z axis as it is by default).

Notice: Althought the 2D drawing commands operate in axes labeled as X and Y, the extrusion commands implicitly translate these objects in X-Z coordinates and rotate about the Z axis.

Example:

``` polygon([[0,0],[10,90],[11,-10]], convexity = N);
```

convexity

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

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

### import_dxf

DEPRECATED: The import_dxf() module will be removed in future releases. Use import() instead.

Read a DXF file and create a 2D shape.

Example

```linear_extrude(height = 5, center = true, convexity = 10)
import_dxf(file = "example009.dxf", layer = "plate");
```

## Text

### Text

[Note: Requires version 2014.QX(see [1])]

Create text using fonts installed on the local system or provided as separate font file.

Parameters

text
String. The text to generate.
size
Decimal. The generated text will have approximately an ascent of the given value (height above the baseline). Default is 10.
Note that specific fonts will vary somewhat and may not fill the size specified exactly, usually slightly smaller.
font
String. The name of the font that should be used. This is not the name of the font file, but the logical font name (internally handled by the fontconfig library). A list of installed fonts can be obtained using the font list dialog (Help -> Font List).
halign
String. The horizontal alignment for the text. Possible values are "left", "center" and "right". Default is "left".
valign
String. The vertical alignment for the text. Possible values are "top", "center", "baseline" and "bottom". Default is "baseline".
spacing
Decimal. Factor to increase/decrease the character spacing. The default value of 1 will result in the normal spacing for the font, giving a value greater than 1 will cause the letters to be spaced further apart.
direction
String. Direction of the text flow. Possible values are "ltr" (left-to-right), "rtl" (right-to-left), "ttb" (top-to-bottom) and "btt" (bottom-to-top). Default is "ltr".
language
String. The language of the text. Default is "en".
script
String. The script of the text. Default is "latin".

Example

Example 1: Result.
```text("OpenSCAD");
```

Note

To allow specification of particular Unicode characters you can specify them in a string with the following escape codes;

\x03 - single hex character (only allowed values are 01h - 7fh)

\u0123 - unicode char with 4 hexadecimal digits (note: Lowercase)

\U012345 - unicode char with 6 hexadecimal digits (note: Uppercase)

Example

```t="\u20AC10 \u263A"; // 10 euro and a smilie
```

### Using fonts

Fonts are specified by their logical name. In addition a style parameter can be added to select a specific font style like "bold" or "italic".

The font list dialog shows the font name and the font style for each available font. For reference, the dialog also displays the location of the font file.

OpenSCAD includes the fonts Liberation Mono, Liberation Sans, Libration Sans Narrow and Liberation Serif. Hence, as fonts in general differ by platform type, use of these included fonts is likely to be portable across platforms.

For common/casual text usage, the specification of one of these fonts is recommended for this reason. Liberation Sans is the default font to encourage this.

In addition to the installed fonts, it's possible to add project specific font files. Supported font file formats are TrueType Fonts (*.ttf) and OpenType Fonts (*.otf). The files need to be registered with use<>.

``` use <ttf/paratype-serif/PTF55F.ttf>
```

After the registration, the font will also be listed in the font list dialog, so in case logical name of a font is unknown, it can be looked up there are it was registered.

Example

Example 2: Result.
``` square(10);

translate([15, 15]) {
}

translate([15, 0]) {
text("OpenSCAD", font = "Liberation Sans:style=Bold Italic");
}
```

### Alignment

#### Vertical alignment

top
The text is aligned with the top of the bounding box at the given Y coordinate.
center
The text is aligned with the center of the bounding box at the given Y coordinate.
baseline
The text is aligned with the font baseline at the given Y coordinate. This is the default.
bottom
The text is aligned with the bottom of the bounding box 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]);
}
}
}
```

#### 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]);
}
}
}
```

## 3D to 2D Projection

Using the `projection()` function, you can create 2d drawings from 3d models, and export them to the dxf format. It works by projecting a 3D model to the (x,y) plane, with z at 0. If `cut=true`, only points with z=0 will be considered (effectively cutting the object), with `cut=false`, points above and below the plane will be considered as well (creating a proper projection).

Then you can do a 'cut' projection, which gives you the 'slice' of the x-y plane with z=0.

```projection(cut = true) example002();
```

You can also do an 'ordinary' projection, which gives a sort of 'shadow' of the object onto the xy plane.

```projection(cut = false) example002();
```

Another Example

You can also use projection to get a 'side view' of an object. Let's take example002, and move it up, out of the X-Y plane, and rotate it:

```translate([0,0,25]) rotate([90,0,0]) example002();
```

Now we can get a side view with projection()

```projection() translate([0,0,25]) rotate([90,0,0]) example002();
```

## 2D to 3D Extrusion

It is possible to use extrusion commands to convert 2D objects to 3D objects. This can be done with the built-in 2D primitives, like squares and circles, but also with arbitrary polygons.

### Linear Extrude

Linear Extrusion is a modeling operation that takes a 2D polygon as input and extends it in the third dimension. This way a 3D shape is created.

#### Usage

```linear_extrude(height = fanwidth, center = true, convexity = 10, twist = -fanrot, slices = 20, scale = 1.0) {...}
```

You must use parameter names due to a backward compatibility issue.

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.

#### Twist

Twist is the number of degrees of through which the shape is extruded. Setting the parameter twist = 360 will extrude through one revolution. The twist direction follows the left hand rule.

0° of Twist

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

-100° of Twist

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

100° of Twist

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

-500° of Twist

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

#### Center

Center determines if the object is centered on the Z-axis after extrusion, so it does not extrude up and down from the center as you might expect.

center = true

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

center = false

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

#### Mesh Refinement

The slices parameter can be used to improve the output.

```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.

```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);
```

### Rotate Extrude

A rotational extrusion is a Linear Extrusion with a twist, literally. Unfortunately, it can not be used to produce a helix for screw threads as the 2D outline must be normal to the axis of rotation, ie they need to be flat in 2D space.

The 2D shape needs to be either completely on the positive or negative side of the X axis. If the shape crosses the X axis a warning will be shown in the console windows and the rotate_extrude() will be ignored.

#### 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 that the 2D shape is composed of will improve the quality of the mesh, but take 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);
```

#### Extruding a Polygon

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

Here is a simple polygon and its (fine-grained: `\$fn=200`) rotational extrusion (profile and lathe). (Note it has been rotated 90 degrees to show how the rotation will look, 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]] );
```

### Description of extrude parameters

#### Extrude parameters for all extrusion modes

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

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

#### Extrude parameters for linear extrusion only

 height The extrusion height center If true the solid will be centered after extrusion twist The extrusion twist in degrees slices Similar to special variable \$fn without being passed down to the child 2D shape. scale Scales the 2D shape by this value over the height of the extrusion.

## DXF Extrusion

With the import() and extrusion statements it is possible to convert 2D objects read from DXF files to 3D objects.

### Linear Extrude

Example of linear extrusion of a 2D object imported from a DXF file.

```linear_extrude(height = fanwidth, center = true, convexity = 10)
import (file = "example009.dxf", layer = "fan_top");
```

### Rotate Extrude

Example of rotational extrusion of a 2D object imported from a DXF file.

```rotate_extrude(convexity = 10, twist = -fanrot)
import (file = "example009.dxf", layer = "fan_side", origin = fan_side_center);
```

### Getting Inkscape to work

Inkscape is an open source drawing program. Tutorials for transferring 2d DXF drawings from Inkscape to OpenSCAD are available here:

### Description of extrude parameters

#### Extrude parameters for all extrusion modes

 scale FIXME convexity Integer. The convexity parameter specifies the maximum number of front sides (back sides) a ray intersecting the object might penetrate. This parameter is only needed for correctly displaying the object in OpenCSG preview mode and has no effect on the polyhedron rendering. See diagram below. file The name of the DXF file to extrude [DEPRECATED] layer The name of the DXF layer to extrude [DEPRECATED] origin [x,y] coordinates to use as the drawing's center, in the units specified in the DXF file [DEPRECATED]

#### Extrude parameters for linear extrusion only

 height The extrusion height center If true, extrusion is half up and half down. If false, the section is extruded up. twist The extrusion twist in degrees slices FIXME

#### Convexity

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