Include <"filename.csg">

This is a type of geometry file exported from OpenSCAD using a subset of its programming language. As such the shapes described by it may be imported into a program using the include <filename.csg> statement.

It is also a format recognized by the import() module .

Import() Object Module

This is an Object Module that imports data, text, or geometry for use in the model. The file extension is used to determine how the imported data is handled.

Normally modules cannot return a value when called, but if the import-function feature is enabled in Preferences-Features the data imported from certain of the file formats may be assigned to a variable for further processing.

3D Geometry Formats

All of the formats that may be exported may also be imported

STL ASCII

STL Binary

OFF

OBJ

AMF (deprecated)

3MF

2D Geometry Formats

DXF

PDF

Scalable Vector Graphics (SVG) format

was imported by import_SVG()

Data formats

• JSON [Note: Requires version Development snapshot]
• number matrix as text

Other

• CSG solid geometry format of OpenSCAD programming language
• PNG use an image to apply a height-map using the surface()

Parameters

<file>

A string containing the path to file.:If the give path is not absolute, it is resolved relative to the importing script. Note that when using include<> with a script that uses import(), this is relative to the script doing the include<>.

<center>

Boolean. If true, the center of the object is placed at the origin. [Note: Requires version Development snapshot]

<convexity>

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

<id>

String. For SVG import only, the id of an element or group to import. Optional. [Note: Requires version Development snapshot]

<layer>

For DXF and SVG import only, specify a specific layer to import. Optional.

$fn

Double. The number of polygon segments to use when converting circles, arcs, and curves to polygons. [Note: Requires version Development snapshot]

$fa

Double. The minimum angle step to use when converting circles and arcs to polygons. [Note: Requires version Development snapshot]

$fs

Double. The minimum segment length to use when converting circles and arcs to polygons. [Note: Requires version Development snapshot]:

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, or replace the backslashes with forward slashes.)

data = import("data.json"); // for data formats the file content is assigned to a variable

Read a layer of a 2D DXF file and create a 3D shape.

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

 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

 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

Importing JSON

This requires enabling import-function feature in development build. If you import a file with the suffix "json" or "csv", import returns a JSON-object datatype which there is not a way to express as a literal value -- it can only be imported.

Note: Files with the ".csv" file suffix are also treated as JSON files, though these formats are not the same -- a CSV file saved from a spreadsheet program cannot be used here.

/* input file contains:

{"people":[{"name":"Helen", "age":19}, {"name":"Chris", "age":32}]}
*/
t = import("people.json");
echo(t);
people = t.people;
for(i=[0:len(people)-1]) {
	person = people[i];
	echo(str(person.name, ": ", person.age));
}

Which results in this output:

ECHO: { people = [{ age = 19; name = "Helen"; }, { age = 32; name = "Chris"; }]; }
ECHO: "Helen: 19"
ECHO: "Chris: 32"

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 needed only for correct display of the object in OpenCSG preview mode and has no effect on the final rendering.

Text file format

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.

Images

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

Examples

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:

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

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

Example 3a: surface(invert = false)

Example 3b: surface(invert = true)

Example 3: Using surface() with a PNG image as heightmap input.