OpenSCAD User Manual/STL Import and Export

< OpenSCAD User Manual

Import and ExportEdit

A prime ingredient of any 3D design flow is the ability to import from and export to other tools. The STL file format is currently the most common format used.

0% developed  as of November 17, 2009 ImportEdit

importEdit

Imports a file for use in the current OpenSCAD model. OpenSCAD currently supports import of DXF, OFF and STL (both ASCII and Binary) files.

NOTE: The file extension is used to determine which type.

   OpenSCAD can export files as  STL, OFF, AMF, DXF, SVG, CSG OR PNG(Image).
   
   These file types created by OpenSCAD, or others, can be imported as follows:
  
   STL, OFF and DXF are imported using import().
   CSG can be imported using include<> or loaded like an SCAD file
   PNG can be imported using surface()
   There are open pull requests for SVG and AMF, which require a bit more work/testing.
   The file suffix is used to determine type.


Parameters

<file> 
A string containing the path to the STL, OFF or DXF file.
<convexity> 
An 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.
import("example012.stl", convexity=3);
import("D:\\Documents and Settings\\User\\My Documents\\Gear.stl", convexity=3);
(Windows users must "escape" the backslashes by writing them doubled.)

ConvexityEdit

Openscad convexity.jpg

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.

NotesEdit

In the latest version of OpenSCAD, import() is now used for importing both 2D (DXF for extrusion) and 3D (STL) files.


If you want to render the imported STL file later, you have to make sure that the STL file is "clean". This means that the mesh has to be manifold and should not contain holes nor self-intersections. If the STL is not clean, you might get errors like:


 CGAL error in CGAL_Build_PolySet: CGAL ERROR: assertion violation!
 Expr: check_protocoll == 0
 File: /home/don/openscad_deps/mxe/usr/i686-pc-mingw32/include/CGAL/Polyhedron_incremental_builder_3.h
 Line: 199

or

 CGAL error in CGAL_Nef_polyhedron3(): CGAL ERROR: assertion violation!
 Expr: pe_prev->is_border() || !internal::Plane_constructor<Plane>::get_plane(pe_prev->facet(),pe_prev->facet()->plane()).is_degenerate()
 File: /home/don/openscad_deps/mxe/usr/i686-pc-mingw32/include/CGAL/Nef_3/polyhedron_3_to_nef_3.h
 Line: 253

In order to clean the STL file, you have the following options:

- use http://wiki.netfabb.com/Semi-Automatic_Repair_Options . This will repair the holes but not the self-intersections.

- use netfabb basic. This free software doesnt have the option to close holes nor can it fix the self-intersections

- use MeshLab, This free software can fix all the issues


Using MeshLab, you can do:

- Render - Show non Manif Edges

- Render - Show non Manif Vertices

- if found, use Filters - Selection - Select non Manifold Edges or Select non Manifold Vertices - Apply - Close. Then click button 'Delete the current set of selected vertices...' or check http://www.youtube.com/watch?v=oDx0Tgy0UHo for an instruction video. The screen should show "0 non manifold edges", "0 non manifold vertices"


Next, you can click the icon 'Fill Hole', select all the holes and click Fill and then Accept. You might have to redo this action a few times.

Use File - Export Mesh to save the STL.

import_dxfEdit

DEPRECATED: Will be removed in future releases. Use import() instead.

Read a DXF file and create a 2D shape.

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


import_stlEdit

DEPRECATED: Will be removed in future releases. Use import() instead.

Imports an STL file for use in the current OpenSCAD model

import_stl("example012.stl", convexity = 5);

SurfaceEdit

Surface reads Heightmap information from text or image files. Surface can read PNG files.

Parameters

file 
String. The path to the file containing the heightmap data.
center 
Boolean. This determines the positioning of the generated object. If true, object is centered in X- and Y-axis. Otherwise, the object is placed in the positive quadrant. Defaults to false.
invert 
Boolean. Inverts how the color values of imported images are translated into height values. This has no effect when importing text data files. Defaults to false. [Note: Requires version 2015.03]
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 final rendering.

Text file formatEdit

The format for text based heightmaps is a matrix of numbers that represent the height for a specific point. Rows are mapped to the Y-axis, columns to the X axis. The numbers must be separated by spaces or tabs. Empty lines and lines starting with a # character are ignored.

ImagesEdit

[Note: Requires version 2015.03]

Currently only PNG images are supported. Alpha channel information of the image is ignored and the height for the pixel is determined by converting the color value to Grayscale using the linear luminance for the sRGB color space (Y = 0.2126R + 0.7152G + 0.0722B). The gray scale values are scaled to be in the range 0 to 100.

ExamplesEdit

Example 1:

//surface.scad
surface(file = "surface.dat", center = true, convexity = 5);
%translate([0,0,5])cube([10,10,10], center =true);
#surface.dat
10 9 8 7 6 5 5 5 5 5 
9 8 7 6 6 4 3 2 1 0 
8 7 6 6 4 3 2 1 0 0
7 6 6 4 3 2 1 0 0 0
6 6 4 3 2 1 1 0 0 0
6 6 3 2 1 1 1 0 0 0
6 6 2 1 1 1 1 0 0 0
6 6 1 0 0 0 0 0 0 0
3 1 0 0 0 0 0 0 0 0
3 0 0 0 0 0 0 0 0 0

Result:

Openscad surface example x1.png

Example 2

 // example010.dat generated using octave:
 // d = (sin(1:0.2:10)' * cos(1:0.2:10)) * 10;
 // save("example010.dat", "d");
 intersection() {
   surface(file = "example010.dat", center = true, convexity = 5);
   rotate(45, [0, 0, 1]) surface(file = "example010.dat", center = true, convexity = 5); 
 }

Openscad surface example x2.png

Example 3:

[Note: Requires version 2015.03]

// Example 3a
scale([1, 1, 0.1])
  surface(file = "smiley.png", center = true);
// Example 3b
scale([1, 1, 0.1])
  surface(file = "smiley.png", center = true, invert = true);
Input image
Input image
Surface output
Example 3a: surface(invert = false)
Surface output inverted
Example 3b: surface(invert = true)
Example 3: Using surface() with a PNG image as heightmap input.

0% developed  as of November 17, 2009 STL ExportEdit

ExportEdit

After rendering with F6, the "File --> Export" menu can be used to export as STL, OFF, AMF, DXF, SVG, CSG OR PNG (Image).

Be sure to check the console window for err messages.

   STL, OFF and DXF are imported using import().
   CSG can be imported using include<> or loaded like an SCAD file
   PNG can be imported using surface()
   There are open pull requests for SVG and AMF, which require a bit more work/testing.
   The file suffix is used to determine type.

STL ExportEdit

To export your design, select "Export as STL..." from the "File --> Export" menu, then enter a filename in the ensuing dialog box. Don't forget to add the ".stl" extension.

Trouble shooting:

After compile and render GCAL (F6), you may see that your design is simple: no. That's bad news.

See line 8 in the following output from OpenSCAD 2010.02:

Parsing design (AST generation)...
Compiling design (CSG Tree generation)...
Compilation finished.
Rendering Polygon Mesh using CGAL...
Number of vertices currently in CGAL cache: 732
Number of objects currently in CGAL cache: 12
   Top level object is a 3D object:
   Simple:         no                <*****************
   Valid:         yes
   Vertices:       22
   Halfedges:      70
   Edges:          35
   Halffacets:     32
   Facets:         16
   Volumes:         2
Total rendering time: 0 hours, 0 minutes, 0 seconds
Rendering finished.

When you try to export this to .STL you will get a message like:

Object isn't a valid 2-manifold! Modify your design..

"Manifold" means that it is "water tight" and that there are no holes in the geometry. In a valid 2-manifold each edge must connect exactly two facets. That means that the program must be able to connect a face with an object. E.g. if you use a cube of height 10 to carve out something from a wider cube of height 10, it is not clear to which cube the top or the bottom belongs. So make the small extracting cube a bit "longer" (or "shorter"):

difference() {
	// original
	cube (size = [2,2,2]);
	// object that carves out
	# translate ([0.5,0.5,-0.5]) {
	    cube (size = [1,1,3]);	
	}
}
Correct use of difference

Here is a more tricky little example taken from the OpenSCAD Forum (retrieved 15:13, 22 March 2010 (UTC)):

module example1() {
		cube([20, 20, 20]);
		translate([-20, -20, 0]) cube([20, 20, 20]);
		cube([50, 50, 5], center = true);
	}
module example2() {
		cube([20.1, 20.1, 20]);
		translate([-20, -20, 0]) cube([20.1, 20.1, 20]);
		cube([50, 50, 5], center = true);
	}

Example1 would render like this:

A not valid 2-manifold cube (simple = no)

The example1 module is not a valid 2-manifold because both cubes are sharing one edge. They touch each other but do not intersect.

Example2 is a valid 2-manifold because there is an intersection. Now the construct meets the 2-manifold constraint stipulating that each edge must connect exactly two facets.

Pieces you are subtracting must extend past the original part. (OpenSCAD Tip: Manifold Space and Time, retrieved 18:40, 22 March 2010 (UTC)).

For reference, another situation that causes the design to be non-exportable is when two faces that are each the result of a subtraction touch. Then the error message comes up.

difference () {
   cube ([20,10,10]);
   translate ([10,0,0]) cube (10);
}
difference () {
   cube ([20,10,10]);
   cube (10);
}

simply touching surfaces is correctly handled.

translate ([10,0,0]) cube (10);
cube (10);