OpenSCAD User Manual/WIP

Work in Progress

Overview

This section contains documentation about ongoing work which is available as experimental features in snapshot versions of OpenSCAD or not yet integrated at all and pending in a branch or pull-request at the OpenSCAD github repository.

Information listed here is mainly intended to help people using and testing the experimental features to provide feedback. It's likely that there are changes to the API and behavior of the features before those are officially released.

NOTE: If the feature mentioned here is already included in the snapshot builds, it's normally also required to enable the feature in the Preferences dialog!

Roof

roof() generates a chamfer of 45° over 2D child polygons. It is constructed via voronoi or straight point mesh generation.

roof(method = ["straight" | "voronoi"], convexity = N) { children };

parameters:

method

"straight" or "voronoi". The "voronoi" (default) setting produces rounded curves where the polygon corners are concave. For convex polygons, there is no difference between "straight" and "voronoi".

convexity

Integer. The convexity parameter specifies the maximum number of faces a ray intersecting the object might penetrate. This parameter is needed only for correct display of the object in OpenCSG preview mode. It has no effect on the polyhedron rendering. For display problems, setting it to 10 should work fine for most cases.

default values: roof();    yields:  roof(method = "voronoi", convexity = 1);

$fa=1; $fs=0.4;
intersection() {
  cube([100,100,2],true);
  scale([1,1,3]) roof(convexity=6) text("Wow");
}

Text Metrics / Font Metrics

textmetrics

textmetrics() returns information about the size and positioning that would be applied to text if laid out as specified by its arguments.

Parameters

The parameters to textmetrics() are exactly the same as the parameters to text().

Return value

The return value from textmetrics() is an object with these properties:

position an [x,y] pair giving the lower left corner of the smallest box that would completely surround the text.

size an [x,y] pair giving the size of that box.

ascent the vertical distance (normally positive) from the baseline of the text to the highest point in the text.

descent the vertical distance (normally zero or negative) from the baseline of the text to the lowest point in the text.

offset an [x,y] pair giving the distance from the origin to the starting point of the baseline of the text. This value is normally [0,0] but can be non-zero when using non-default alignments.

advance an [x,y] pair giving the distance from the starting point for this text to the starting point for a subsequent piece of text. Informally, it says how far the pen should be moved before starting the next piece of text. This value is directly helpful only with default alignments - horizontal text aligned left/baseline and vertical text aligned center/top.

Note: as with any array, you can use an object-like ".x" or ".y" to refer to the two entries in [x,y] pairs. Thus you can refer to either obj.size[0] or obj.size.x to get the X dimension of the text.

Information returned by textmetrics() function.

Sample output (reformatted for readability):

 ECHO: {
   position = [2.2784, -5.7728];
   size = [87.0362, 24.8832];
   ascent = 19.1104;
   descent = -5.7728;
   offset = [0, 0];
   advance = [89.5186, 0];
 }

fontmetrics

fontmetrics() returns information about the specified font and size.

The arguments to fontmetrics() are the size and font name.

Parameters

size the font size font the font name

Return value

The return value from fontmetrics() is an object with these properties:

nominal an object with ascent and descent properties describing the "usual" ascent and descent of the font. For most fonts, this will be the ascent of upper-case letters and the descent of lower-case letters with descenders.

max an object with ascent and descent properties describing the maximum ascent and descent of the font.

interline gives, as a positive number, the designed inter-line spacing for the font.

font an object with members family and style that gives the name and style of the selected font. These may not be the same as the name supplied, if the specified font is not available, or if a generic name like "sans" or "serif" is specified, or if only a style is specified.

Module Literals / Module References

module literals / module references

A module_reference is a type of variable that refers to a module

Module literal and module reference syntax

The module_reference is initialised using a module_literal. In the following snippet my_cube is the module_reference and module cube([2,3,4]) is the module_literal. A module literal is an expression which is syntactically identified by being prefixed with the module keyword.

Syntax in detail

There are several ways to define a module reference, depending on what you want to do.

Simple syntax

In this syntax you define the module exactly as you want to see it output.

// Create a reference to a cube module my_cube = module cube([2,3,4]);

The above code creates the variable my_cube but doesn't instantiate it, so there will be no output in the graphics window. To instantiate the module you use the existing syntax that you use with modules.

// Instantiate the module through the module reference my_cube();

Instantiated module reference

Alias syntax

In this variation, the name of the module reference is just another name for the module.

my_cylinder = module cylinder;

To instantiate the module, the alias takes exactly the same arguments as the module it aliases

my_cylinder(h=20, r=10, center=true);

Instantiated module reference

Arguments forwarding syntax

In another form you provide arguments to the module_literal. The arguments are forwarded to the original module.

my_cylinder = module(height) cylinder(h = height, r=10, center=true);

In this case you call the reference with the modified arguments

my_cylinder(20);

Instantiated module reference

Anonymous module syntax without arguments

In the final forms you can create an anonymous module_literal and initialise the reference to it.
( Note that in this form there must be a semicolon after the closing curly brace )

my_shapes = module { cube(2,center = true); translate([5,0,0]) sphere(1,center = true); };

The module can be instantiated in the usual way.

my_shapes();

Instantiated module reference

Anonymous module syntax with arguments

The anonymous module form can of course also take arguments

my_rotated_square = module ( r, s) { rotate(r) square(s);};

The module reference is instantiated in the usual way.

my_rotated_square(45,10);

Instantiated module reference

Instantiating a module via an expression

Module literals can be stored in arrays and returned from functions In these cases it can be inconvenient to assign them to a symbol before invoking them. You can instantiate an expression resolving to a module_literal by encasing the expression before the instantiation arguments, in brackets.

//------------- // n is an integer index between 0 and 3 // choose_shape returns the shape given by the index function choose_shape(n) = let (ar = [ module cube([5,20,30]), module sphere(r = 6 , $fn = 20), module cylinder(d = 15, h = 20, $fn = 30) ]) ar[n]; //-------------- // instantiate the chosen module (choose_shape(2))(); // choose the cylinder

Further examples

For more advanced uses of module_literals and module references see https://github.com/kwikius/openscad/tree/module_literal_v3/examples/ModuleLiterals

Persistent Cache

Introduction

The cache data of rendered geometries in OpenSCAD is limited to the life-span of the application. This feature provides a solution for the persistent storage of rendered geometries. All the rendered geometries are serialized using boost serialization library and pushed into local filesystem cache or into the Redis database according user preferences.

How to use redis for cache?

• Download and install Redis database
• Download Hiredis release version 0.14.1 or above from, build and install it.
• The source code of this feature is not merged yet. It is available in this PR https://github.com/openscad/openscad/pull/3316. Clone and build this PR.
• Start the Redis-server and make a note of IP address, port number, and password if any from it's config file.
• GUI MODE: Open the preferences dialog and move to the advance tab. enable the checkbox persistent cache using Redis. fill in the config details and close the preferences dialog.

Persistent cache for openscad

• CLI MODE: a new option cache is added to OpenSCAD. The usage of this option in the case of Redis is shown below.

          example: ""--cache=redis,127.0.0.1,6379,foobared""

• That's it, now OpenSCAD is ready to use Redis for caching.

How to use local cache?

• GUI MODE: Open the preferences dialog and move to the advance tab. enable the Local cache checkbox.
• CLI MODE: This is another variant in cache option. The usage of this option is shown below.

          example: ""--cache=file""

• That's it, now OpenSCAD is ready to use local filesystem for caching.