OpenSCAD User Manual/WIP

Work in ProgressEdit

OverviewEdit

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!

InputdriverEdit

IntroductionEdit

[Note: Requires version 2019.05]


The inputdriver allows a user the use of things like a gamepad or a 3D-Mouse in OpenSCAD.

Currently, the following drivers are in development:

  • HIDAPI - Used on MacOS and Windows - needs the USB IDs / it works on Linux too, but needs additional privileges, so it's not ideal for the user
  • Joystick driver - uses the Linux joystick device (currently fixed /dev/input/js0)
  • SpaceNav driver - using the spacenavd daemon
  • DBus driver - Linux only / not for actual devices but for remote control
  • QGamepad - used for Cross-platform joystick support - This seems to require some additional configuration on Qt level currently, so it needs some more work to make it easy to use

The default axes mapping is for 3D-mices.

How to try it outEdit

The inputdriver is currently part of the current development snapshots and nightly builds.

Therefor, they can be found here: http://www.openscad.org/downloads.html#snapshots

Joystick and gamepadsEdit

linuxEdit

 
Almost any controller that your Linux computer recognizes should work

The JoystickInputDriver is using the device /dev/input/js0.

Under Ubuntu Linux, you need the packet joystick for joystick support.

QGamepad can also be used, but is not recommended as the QGamepad Driver makes assumptions about the Gamepad that might not be true.

WindowsEdit

 
QGamepad works well with XBox 360 controllers

Under Windows, you can use QGamepad as a driver. QGamepad works best with an XBox 360 controller.

3D-MouseEdit

LinuxEdit

On Linux, the easiest way with the Space Mouse Wireless is interestingly to go though the Joystick driver that is normally enabled on most systems.

SpacenavEdit

Spacenav is also supported. http://spacenav.sourceforge.net/ https://wiki.archlinux.org/index.php/3D_Mouse#Open_Source_Drivers

sudo apt-get spacenavd

On debian:

sudo apt install libspnav-dev 

(requires restart)

HIDAPIEdit

For using the hidapi, you can run openscad with root privileges. However, this is not recommend, but maybe helpful for temporary trouble shooting.

Much better is to figure out which vendor id and product id your device has and add a udev rule. To figure out which vendor and product id your product has, you can use lusb.

How the relevant line of lsusb may look like:

Bus 002 Device 006: ID 046d:c627 Logitech, Inc. 3Dconnexion Space Explorer 3D Mouse

Some hints:

  * https://stackoverflow.com/questions/3738173/why-does-pyusb-libusb-require-root-sudo-permissions-on-linux/32022908#32022908

WindowsEdit

OpenSCAD interacts directly with the 3D Mouse using the HIDAPI.

Therefore, the driver from the device manufacturer is not required. If the driver of the device manufacturer is installed, the driver has to be stopped, so that OpenSCAD can claim the device.

There are different ways to stop the driver. In your start menu you should have a folder 3Dconnexion and in there "Stop Driver".

You can also try

"C:\Program Files\3Dconnexion\3DxWare\3DxWinCore64\3DxService.exe" -shutdown

Mac OSEdit

As with other platforms, you have to disable the native 3DConnexion drivers completely, as OpenSCAD does not use them.

To enable the built-in driver for the SpaceMouse, go to Preferences → Axes, turn on the HIDAPI setting, and restart OpenSCAD.

The following devices have been tested and are known to work with OpenSCAD on MacOS Mohave:

  • SpaceMouse Compact (USB)
  • SpaceMouse Wireless

DBusEdit

The D-Bus driver can be used for remote controlling OpenSCAD. This is mainly intended for programmers. It can for example be used to write a custom input driver.

Debug and testingEdit

For debugging and testing, D-Feet can be used. OpenSCAD can be found on the Session Bus under org.openscad.OpenSCAD.

qdbus is NOT recommended, as it has issues with some of the more complex data structures.

ExampleEdit

An example for QT/C++ can be found under this page.

Camera SystemEdit

Note that OpenSCAD's camera behavior and system does not operate in a standard way. Via DBus, you are directly interacting with OpenSCAD's camera. Note that the camera system and thus this is interface could be refactored at some point.

ActionsEdit

Please note that the actions exposed Via dbus are mostly the ones from the Menu Bar of OpenSCAD. Keep in mind, that the menu bar might change at some point and that compatibility with the dbus driver is not of concern.

FAQEdit

Which button is which?Edit

Open the preferences, then go to the button tab then press the button you want to assign. The text next to the relevant ComboBox appears in red, bold text.

View is driftingEdit

If your view is drifting, please re-calibrate the neutral position and deadzone of your input device. This can be done within OpenSCAD or with the tools of the operating system.

Where are my settings stored?Edit

See this page.

Y+Viewport-rel-translation (VRT) Channel is not responding to inputEdit

You are in orthogonal view. Please change it to perspective to see what it does. Or look in the bottom left corner, where translate = changes. This is not a bug, this is a very specific feature. When you map zoom to one axis and Y+Viewport-rel-translation to an other while in perspective view, you should get the vertigo effect.

Most users use zoom as it works in both orthogonal and perspective. Before you wonder why you can map two axis to zoom: Game controllers have two shoulder buttons.

Yes, this has little to no real world use, but the inputdriver is about giving as much control to the user as possible.

Persistent CacheEdit

IntroductionEdit

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?Edit

  • 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?Edit

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