Every application that provides 3D modelling, rendering, and animation has to select the technologies to adapt to its purposes. This section is presenting the issues that the choices made for OpenSCAD bring to the user, and discuss how to take advantage of them while mitigating their weaknesses.

The preview render works by presuming an eye point looking towards the objects in view, dividing up the viewport into pixels, and reviewing every shape as to the pixels it will be drawn in.

The math definition of each curved shape is combined with the smoothness parameters to calculate how to sub-divide curves into lines (2D) or polygons (3D). Preview makes a list of the polygons that face the eye point and then, using the geometry of each polygon and the position of the eye point, projects the polygon onto the viewport to calculate which pixels the polygon is visible in. If the part of the polygon in a particular pixel is closer to the eye than any previously considered a color value is calculated and replaces the value for the given pixel.

This process is called Z-Buffering where the "Z" is the distance in a projection space from the eye point to a point on a surface in the view.

Convexity is a parameter for a number of Object Modules. It is an integer with a default of one (1) that works as a measure of complexity based on the maximum number of sides a viewer might see looking at a shape.

The preview rendering mode uses convexity to be sure that it "paints" each pixel correctly for each shape. The full rendering operation uses a different method that ignores convexity.

There is fuller explanation on the OpenCSG site in the Usage section.

The preview render "looks" at each shape through the pixels of the viewport to know what to paint. When the object is simple, showing a single surface to the eye point, it only needs to check the surface once for each pixel.

For instance, the convexity of a sphere needs only to be one (1) as only one surface can be seen from any view point. But a shape with folds, holes, and bumps will have a variable number of surfaces when viewed from different points around it. From some positions a torus will present one surface, but looking at it edge on the near part covers the far side of the hole, thus the render needs to always check for two surfaces in each pixel, and convexity must be 2.

In general the convexity value must be as large as the maximum number of surface crossings that may be seen viewing from the "worst case position".

This 2D shape has a convexity of 2, as there is at least one ray (the red line) that passes through its boundary twice. If convexity was at the default 1 the rendering process would stop at the first intersection, possibly missing second part of the curve.

Note: Arbitrarily setting convexity to a high value may solve some preview rendering issues, at the expense of slowing preview rendering, possibly even causing the app to lock up.

[Note: Requires version 2019.05]

This Special Variable may be interrogated to know in which rendering mode the script is being run.

When in OpenCSG preview mode (F5) $preview is true. Doing a render (F6) it is false.

Tip: $fn should not be used to globally control how curved shapes are sub-divided, $fa & $fs do a better job

The render() module operates differently from either rendering mode. The value of $preview is undetermined in this snippet:

render(){
    $fn = $preview ? 12 : 72;
    sphere(r = 1);
}

The tessellation result is the same regardless.

Command Line Operation

When using the command line to render $preview is only true when exporting a PNG image. For all other forms of output ( STL, DXF, SVG, CSG, and ECHO files ) it is false. It can be forced true using the -D command line option.

Examples

$preview can be used to model in reduced detail but have fully smoothed curved surfaces the final rendered result:

FNspecial = $preview ? 12 : 72;
sphere(r = 1, $fn=FNspecial );

Best Practice: The $fn argument to the module is used so that no other shapes are affected.

Another use could be to show a complex part assembled during preview but spread out and positioned for 3D printing during rendering.

OR: When horizontal features require support in 3D printing the object may be previewed without the support structures, but rendered with them, then exported to STL for printing.

This module may be used to force tessellation for all shapes. Its use is described in the Syntactic Modules section