LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org


Vismach is a simulator to show 3D previews of a physical machine. The function an screenshots are presented below, for a tutorial, look at the bottom of the page.

Vismach.py is a python library to draw objects in a simulation window. It is located in /usr/lib/pymodules/python2.6/vismach.py (or, for Run-in-place systems, src/lib/python). The simultion itself is a script, based on vismach.py. The scripts are located in /usr/bin (Hal components). The .hal file of your machine in your /home/user/linuxcnc/config/yourmachine loads this script with "loadusr" al a HAL component and connects the axis. Following important things are described in the script:

At the moment, these simulations are available:

Classes defined in vismach.py

Details about functions can be found from vismach.py itself and the already existing examples. For first experiments one might just have a look at 5axisgui, where geometry is generated with simple boxes. Scaragui shows how to load .obj files. A short summary of the classes follows:

Transform/place Objects:

Example for object "ram":

ram = Translate([ram], 0,0,150)

Create Geometry

table = Collection([

	crotary,    # relation to previous object
	Box(-150,-50, 81, 150, 50, 100),
	Box(-150,-40, 75, 150, 40, 81),

Define joints as rotating/translating axis

further classes


upload:puma_vismach.png upload:hbm-vismach-ss1.png upload:hbm-vismach-ss2.png

Note: You can navigate in the simulation window by moving your mouse and holding one button:

By the way - does anyone know how to scale these images in the wiki?

upload:scara_vismach.png upload:hexapod_sim3.png

Vismach can be used to verify motions that don't show up in AXIS preview, such as custom kinematics or m-codes. This screenshot shows a "virtual rotary table" using the C-axis. upload:rotatekins.png Another example on what one can do with LinuxCNC (ex Enhanced Machine Controller) and Vismach help. upload:Dab_Tetrapod.png

Set up your own Simulation

Setting up a Simulation is basically done in following steps. To get familiar how it is done, you should start below to see how the scripting an d debugging works.

  1. Use a CAD and export .obj or .stl files for each axis consisting the geometry. The files can be produced using [FreeCAD]: Model the solid for each axis, create a mesh and [export] it as .obj or .stl.
  2. Create a *gui file for your machine in /usr/bin an make it executable
  3. Read the geometry files with your script using the class AsciiOBJ or AsciiSTL. Define the axis (geometry, position, color, hal connection)
  4. Connect the script to your machine in .hal file with "loadusr" and the needed connections.

get familiar with HAL

The Simulator is loaded as Hal Component. Open a terminal and type:

$ halrun
Then you will get the command interface for HAL. Type:
loadusr 5axisgui
A Window with the 5 axis simulation should appear (it is not connectetd to AXIS, so you can't do anything with it now, than view it). To test the connection with Hal you might try following commands:
halcmd: show pin
halcmd: show param
halcmd: show sig
When you are ready you can unload the module again using and return to the normal shell:
halcmd: unloadusr 5axisgui
halcmd: exit
Now go to your /home/usr/linuxcnc/config/your_machine folder and edit the .hal file. Add at the bottom the line:
loadusr -W  5axisgui
The -W option tells Axis to wait for the simulator. Now start AXIS with your machine configuration. This time the 5axisgui window will appear with it (again it is not connectetd to a controller, so you can't do anything with it now, than view it).

set up own script

Type in a Terminal (where "my_machine stands" for your deserved name):
sudo su
cp /usr/bin/5axisgui /usr/bin/my_machine_gui
chmod +x /usr/bin/my_machine_gui
This will copy the 5axisgui script to a new file an makes it executable. Go to your /home/usr/linuxcnc/config/your_machine folder and edit the .hal file. Go to the bottom. Remove the line:
loadusr -W  5axisgui
Add the lines:
loadusr -W  my_machine_gui

net j0 axis.0.joint-pos-fb => my_machine_gui.joint0
net j1 axis.1.joint-pos-fb => my_machine_gui.joint1
net j2 axis.2.joint-pos-fb => my_machine_gui.joint2

This will load your script. Using the "net" command, it will connect the Feedback Signal of your machines joints 0,1 and 2 to the script 5axisgui for every joint. Save it and open Axis with your machine config - the window should pop up again. This time, you should be able to move something in the simulator, when controlling the machine with the key arrows. Of course - that's not your machine, and it might move anything. Close LinuxCNC.

edit the script file

Type in a Terminal:
sudo gedit /usr/bin/my_machine_gui
The following shows a script with the basics:


#import needed python libs
from vismach import *
import hal
import math
import sys

#define HAL pins that can be connected in the .hal file of the machine
#to work propper, 7 pins have to be defined and connected to a geometry
#this file is for demonstration only
#enter the name of your file in the line below, where your_machine_gui stands; don't remove the " "
c = hal.component("your_machine_gui")
c.newpin("joint0", hal.HAL_FLOAT, hal.HAL_IN)

# geometry, placement, joints, colour
tooltip = Capture()

part = Collection([tooltip,Box(-100,-100,200, 100,100,900)])
part = HalRotate([part],c,"joint0",1,0,0,1)

work = Capture()
table = Collection([work,Box(-500,-500,-400, 500,500,-450)])

#model() and main() have a certain structure you always have to use 
model = Collection([part, table])
main(model, tooltip, work, 1500)

You might copy it in your editor, save it and test it from the terminal with:

loadusr my_machine_gui
There seem to be further issues I don't understand right now: Although this works from terminal using halcmnd, I can't load this script from AXIS without crashing. Seems to be some details which might be found out from vismach.py. It has nothing to do with the connection from Axis to the script made in the . hal file of your machine. Feel free to improve our knowledge and document it here :) The good thing is that it works with following script, where 7 joints are defined (seem to be always 7 in the other scripts - I just don't know why):


#this file works for me and can be loaded with axis
#all pins are connected, the part ram ist connected to 3 degrees of freedom respectively to 4 joints as dummy

from vismach import *
import hal
import math
import sys

c = hal.component("5axisgui")
c.newpin("joint0", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("joint1", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("joint2", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("joint3", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("joint4", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("joint5", hal.HAL_FLOAT, hal.HAL_IN)
c.newpin("tool_length", hal.HAL_FLOAT, hal.HAL_IN)

tooltip = Capture()
tool = Collection([HalTranslate([tooltip], c, "tool_length", 0,0,-1)])

tool = Collection([tool, CylinderY(-100,75, -10,75)])
tool = HalRotate([tool],c,"joint4",1,0,-1,0)

wrist = Collection([tool, Box(-50,-100,0, 50,-25,100)])
wrist = HalRotate([wrist],c,"joint5",1,0,0,1)

ram = Collection([wrist,Box(-100,-100,200, 100,100,900)])
ram = HalTranslate([ram],c,"joint2",0,0,1)
ram = Collection([ram,Box(-100,100,350, 100,200,550)])
ram = HalTranslate([ram],c,"joint0",1,0,0)
ram = Collection([ram,Box(-800,200,350, 800,400,550)])
ram = HalTranslate([ram],c,"joint1",0,1,0)
ram = Collection([ram, Box(800,1000,-1000, 1000,-1000,-900)])

work = Capture()
table = Collection([work,Box(-500,-500,-400, 500,500,-450)])

model = Collection([ram, table])
main(model, tooltip, work, 1500)

Beeing this far, you might change the geometry in the script (use .stl or .obj import), the placement of the parts and the type of joint (translation/roatation and their direction/axis). You can connect tool parameters like the length to the simulation. Look into the other example simulations in /usr/bin and in the config files of the examples to see how it is done. The puma560gui is a good start point, because well commented and not to complexe.

btw: the original 5axis gui has some errors. if you add small blocks onto the parts to be rotated, you'll discover the wrong bits rotate. since its round you dont notice. so, adding markers is a good thing!

.stl or .obj import

Note that the AsciiOBJ class searches for the last # (which means comment) to start reading the file. Files generated with freecad don't include comment at the beginning, so you manually have to add a #.

The functions are used this way:

part = AsciiOBJ(filename="path/to/OBJ_file.obj")

To do


Quick links to vismach movies

[9 axis gantry]
[circular interpolation tilted]
[DMG style AB axis, like a knucklehead mill but for workpiece tilting under std cartesian machine]
[7axis hole drill edm, shows use of STL objects ( the turbine blades ) and resuse of object by instancing them]
[shuttle style rack ATC ( rack moves in &out of work area) with tool in chuck morphing to whats in pod]

example 9 axis code with notes explaining some call, some limitations
enough joints where you can see a coding pattern of how to add another

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
This page is read-only. Follow the BasicSteps to edit pages. | View other revisions
Last edited October 12, 2014 9:55 pm by Tjtr33 (diff)
Published under a Creative Commons License