OpenSCAD User Manual/The OpenSCAD User Interface

User Interface

Main Window of OpenSCAD with a small program generating the OpenSCAD-Logo.

The user interface of OpenSCAD has three parts

The viewing area
The console window
The text editor

Viewing area

Preview and rendering output goes into the viewing area. Using the Show Axes menu entry an indicator for the coordinate axes can be enabled.

Console window

Status information, warnings and errors are displayed in the console window.

During a render a progress-bar is displayed at the bottom of the console. It includes a Cancel button to stop the render.

A render can be cancel using the X button at the end of the progress bar.

Text editor

The built-in text editor provides basic editing features like text search & replace and also supports syntax highlighting. There are predefined color schemes that can be selected in the Preferences dialog.

OpenSCAD Editor with Find / Replace functionality.

Interactive modification of the numerical value

It is possible to change a numeric value in the source code and observe the result in real time.

Placing the cursor after a digit and pressing Alt+ up arrow or Alt + down arrow will increment or decrement the chosen digit. The object is re-rendered and displayed in preview mode after each change of the selected number in the source code. The cursor is moved after the next digit by Alt + right arrow, the further decimal digits are added when needed by moving the cursor after the last digit on the right side. The cursor is moved left behind the most significant digits of the number by Alt + left arrow.

NOTE: On MacOS, use Option + Shift instead of Alt.

Key	Description
`Alt` + `Up Arrow`	Increment the numeric value to the left of the cursor and preview the object.
`Alt` + `Down Arrow`	Decrement the numeric value to the left of the cursor and preview the object.
`Alt` + `Left Arrow`	Move the cursor left to more significant digit.
`Alt` + `Right Arrow`	Move the cursor right to less significant digit, eventually add one more decimal digit.

View navigation

The viewing area is navigated primarily using the mouse:

Action	Icons	Description
rotating the view		Dragging with the left mouse button rotates the view along the axes of the viewing area. It preserves the vertical axis' direction. Double-click the left button to set the point of rotation.
rotating the view	`⇧ Shift` +	Dragging with the left mouse button when the shift key is pressed rotates the view along the vertical axis and the axis pointing towards the user.
moving the viewing area		Dragging with the right mouse button moves the viewing area.
zooming		Using the scroll wheel
		Dragging with the middle mouse button
	`⇧ Shift` +	Dragging with the right or middle mouse button and the shift key pressed
	`⇧ Shift` +
	`+` and `-`	The keys `+` and `-`
show/hide rotation center	`Ctrl`+`3`	Turn on or off the graphic showing the center of rotation. (It is always in the center of the viewing area).
rotation reset	`Ctrl`+`0`	Rotation can be reset using the shortcut `Ctrl`+`0`.
translation reset	`Ctrl` + `⇧ Shift`+`0`	Translation can be reset using the shortcut `Ctrl`+`⇧ Shift`+`0`.

View setup

The viewing area can be configured to use different rendering methods and other options using the View menu. Most of the options described here are available using shortcuts as well.

Render modes

OpenCSG (F9)

This method produces instantaneous results, but has low frame rates when working with highly nonconvex objects.

Selecting the OpenCSG mode using F9 switches to the last generated OpenCSG view, but does not re-evaluate the source code. You may want to use the Compile function (F5, found in the Design menu) to re-evaluate the source code, build the OpenCSG objects and then switch to OpenCSG view.

Implementation Details

In OpenCSG mode, the OpenCSG library is used for generating the visible model. This library uses advanced OpenGL features (2.0) like the Z buffer and does not require an explicit description of the resulting mesh – instead, it tracks how objects are to be combined. For example, when rendering a spherical dent in a cube, it first renders the cube on the graphics card and then render the sphere, but instead of using the Z buffer to hide the parts of the sphere that are covered by the cube, it renders only those parts of the sphere, visually resulting in a cube with a spherical dent.

CGAL (Surfaces and Grid, F10 and F11)

This method might need some time when first used with a new program, but then has higher frame rates.

As before with OpenCSG, F10 and F11 enable only CGAL display mode and don't update the underlying objects; for that, use the Compile and Render function (F6, found in the Design menu).

To combine the benefits of those two display methods, you can selectively wrap parts of your program in a render function and force them to be baken into a mesh even with OpenCSG mode enabled.

Implementation Details

The acronym CGAL refers to The Open Source Computational Geometry Algorithms Library.

In CGAL mode, the CGAL library is used to compute the mesh of the root object, which is then displayed using simple OpenGL.

View options

Show Edges (Ctrl+1)

The difference between the CGAL and OpenCSG approaches can be seen at edges created by boolean operations.

If Show Edges is enabled, both OpenCSG and CGAL mode render edges as well as faces; CGAL even shows vertices. In CGAL grid mode, this option has no effect.

Enabling this option shows the difference between OpenCSG and CGAL quite clearly: While in CGAL mode you see an edge drawn everywhere it "belongs", OpenCSG does not show edges resulting from boolean operations – this is because they were never explicitly calculated but are just where one object's Z clipping begins or ends.

Show Axes (Ctrl+2)

If Show Axes is enabled, the origin of the global coordinate system is indicated by an orthogonal axes indicator. Additionally, a smaller axes indicator with axes names are shown in the lower left corner of the viewing area. The smaller axes indicator is marked x, y, z and coloured red, green, blue respectively.

Show Crosshairs (Ctrl+3)

If Show Crosshairs is enabled, the center of the viewport is indicated by four lines pointing in the room diagonal directions of the global coordinate system. This is useful when aligning the viewing area to a particular point in the model to keep it centered on screen during rotation.

Animation

The Animate option adds an animation bar to the lower edge of the screen. As soon as FPS and Steps are set (reasonable values to begin with are 10 and 100, respectively), the current Time is incremented by 1/Steps, FPS times per second, until it reaches 1, when it wraps back to 0.

Every time Time is changed, the program is re-evaluated with the variable $t set to the current time. Read more about how $t is used in section Other_Language_Features.

View alignment

The menu items Top, Bottom, …, Diagonal and Center (Ctrl+4, Ctrl+5, …, Ctrl+0, Ctrl+Shift+0) align the view to the global coordinate system.

Top, Bottom, Left, Right, Front and Back align it in parallel to the axes, the Diagonal option aligns it diagonally as it is aligned when OpenSCAD starts.

The Center option puts the coordinate center in the middle of the screen (but not rotate the view).

By default, the view is in Perspective mode, meaning that distances far away from the viewer appear shorter, as seen in the real world eyes or cameras. When the view mode is changed to Orthogonal, visible distances do not depend on the camera distance (the view simulates a camera at an infinite distance with an infinite focal length). This is especially useful in combination with the Top etc. options described above, as these orthogonal views result in a 2D images similar to what one would see in an engineering drawing.