Scripting API

Back

Using scripting we can show/hide objects, move them, change their color, animate them and the list goes on. It is meant to show more complex things / events, what we cannot visualize using the basic functionalities. The scripting is a design time API, made for the creator of the presentation. Therefore it is not available for the viewer, because the recipient of the presentation can be anyone, even with no, or minimal technical background. He/she still should be able to view the presentation and use all of its functionalities. Therefore the presentation has to offer an easy-to-use, almost self-explanatory user interface. But we also want to make the creator’s life easier: the scripting language is tailor-made for this service with simplicity in mind.

The smallest accessible object is the volume. This is essentially the content of one geometry file. For example a project involves 150 STL files, it makes 150 volumes. Even if an STL file includes more volumes, they will be handled as a single volume.
In order to do anything with a volume, we have to select them. Then all subsequent operations (move, animation, etc.) are executed on the selected volumes. The selection status does not change with the execution of any command. It will change only, if another selection command has been issued. Here is a small example, when we move the 6th volume by 50 (model length units) in Y direction: sfv,6,6,1 mt,0,60,0 After executing this sequence, the 6th volume remains selected, so issuing another command, like changing the color to red will be executed again on the 6th volume: cs,255,0,0

The scripts are placed into the project file under the [SCRIPTS] section. The section is divided into blocks. A block begins with the block header, which is a string between the less-than sigh and the greater-than sign. The block header is the string, which appears in the top menu under the “Manual” item as sub-menu item(s). For example:

First step

Then the string "First step" appears in the sub-menu. There is a special block header, the The script in this block will be executed at the beginning all other scripts. This special block header will not appear in the sub-menu. This is where the script items are in the top menu on desktop:

The four square buttons on the bottom are for the scripts. The first opens the pop-up menu. The second plays the previous script. The third plays the current script again. The last plays the next script. There is a narrow space between the menu items and the right edge of the screen: this is the scroll bar section where we can safely tap and slide on the screen without accidentally touching one of the script buttons. The pop-up menu can be closed by the lowest “Close” button, or by the “X” button on the top right.

After this introduction here is the description of all commands:

Commands

The available script commands are grouped into the below functions:

Command Argument(s) Description Remark
sv Min,Max,Increment select by Volume id The simple select is essentially: also select
ss Min,Max,Increment select by volume Set id
sl NAME select by volume set Label
sc R,G,B select by Color
sg NAME select by Group name
uv Min,Max,Increment unselect by Volume id Simple unselect
us Min,Max,Increment unselect by volume Set id
ul NAME unselect by volume set Label
uc R,G,B unselect by Color
ug NAME unselect by Group name
sfv Min,Max,Increment select from full by Volume id From full: makes a new selection regardless what was selected before
sfs Min,Max,Increment select from full by volume Set id
sfl NAME select from full by volume set Label
sfc R,G,B select from full by Color
sfg NAME select from full by Group name
srv Min,Max,Increment reselect by Volume id Reselect: selects only from the already selected
srs Min,Max,Increment reselect by volume Set id
srl NAME reselect by volume set Label
src R,G,B reselect by Color
srg NAME reselect by Group name
suv Min,Max,Increment unselect by Volume id Unselect: removes selection
sus Min,Max,Increment unselect by volume Set id
sul NAME unselect by volume set Label
suc R,G,B unselect by Color
sug NAME unselect by Group name
sav Min,Max,Increment also select by Volume id Also select: additionally selects
sas Min,Max,Increment also select by volume Set id
sal NAME also select by volume set Label
sac R,G,B also select by Color
sag NAME also select by Group name
sa select All Selects everything, regardless what is selected so far
si select Invert Flips selection of all volumes
sn select None Unselects everything, regardless what is selected so far
ua unselect All
Volumes are the content of the geometry files. Numbering (ID) begins with 1.
If only one volume to be selected by its ID, then the "Min" and the "Max" fields are equal and the "Increment" is 1. For example selecting only the 18th volume: sfv,18,18,1
Volume set labels are in the first column of the [COLORS] section in the project file. Not case sensitive.
Volume set IDs are the number of the volume set label. Volume set ID begins with 1.
Colors are defined by RGB components ranging between 0..255
Group name is a string variable which identifies a set of volumes. Groups are created by the grouping commands (see later). Not case sensitive.
Example: select the first 50 volumes: sfv,1,50,1
Command Argument(s) Description Remark
di display Invert
da display All
dh display None
ds display Show Works on the selected volumes
dh display Hide

Example: show all volumes regardless of current selection: da

Controls the color of the volumes. All color commands work on the selected volumes.

Command Argument(s) Description Remark
cs R,G,B color Set Sets color to arguments
cb R,G,B color Brighten Increase RGB components by arguments
cd R,G,B color Darken Decrease RGB components by arguments
cm R,G,B color Mix Blend current RGB components by arguments
cp R,G,B,RATIO color Proportional mix Blend current RGB components by arguments proportionally
cr color Reset Resets color to original value

Example: show all volumes regardless of current selection: da

Controls the position and the extension of the volumes. Distances are interpreted in the model length unit in the global cartesian system.

Command Argument(s) Description Remark
mt X,Y,Z Translate
mi X,Y,Z Inflate Scale volumes by individual scale factors (center point: CoG)
ms X,Y,Z,UX,UY,UZ Scale Scale volumes by individual scale factors (center point: first 3 parameters)
mz SCALEFACTOR Zoom Scale volumes by a uniform scale factor (center point: CoG)
me SCALEFACTOR Explosion Move volumes by their displacement vectors in the exploded view
mb IREF1,IREF2 Between reference frames Reference frames are defined by the IC command
mr Reset Back to latest snapshot position
mo back to Original position

CoG: Center of gravity of the given volume

Using reference frames you can rotate and translate volume(s) in the same time

Example: translate the selected volumes by 30 (model length unit) in Z direction: mt,0,0,30

Controls the position and the extension of the volumes. Distances are interpreted in the model length unit in the global cartesian system.

Command Argument(s) Description Remark
rb X,Y,Z,ROTX,ROTY,ROTZ rotate By X,Y,Z are the pivot point coordinates
ro rotate back to Original position Same effect as the "mo" command

Example: rotate selected volumes around the pivot point 10,20,30 by 55 degrees around the Y axis: rb,10,20,30,0,55,0

Controls the camera position and orientation. Distances are interpreted in the model length unit in the global cartesian system. Angles are in degrees.

Command Argument(s) Description Remark
va X,Y,ZOOM,ROTX,ROTY,ROTZ view All Pan, zoom, rotate in one command
vp X,Y view Pan Horizontal and vertical pan
vz ZOOM view Zoom Zoom: original value is 0. Positive: zoom out
vr ROTX,ROTY,ROTZ view Rotate Camera orientation around X, Y and Z axes (degrees)
vf SCALEFACTOR,FORCEDVISIBLEFIT view Fit See remarks below
vo view Original Interactive equivalent: top menu -> Orig. view

Scalefactor: zoom to full extents: 1. Recommended for fit to screen: 90% (0.9)

Forcedvisiblefit: if yes (1), then the wireframe is not taken into account. If no (0), then the wireframe is fit

Example: zoom in to 60 (zoom in: negative): vz,-60

Controls the camera position and orientation. Distances are interpreted in the model length unit in the global cartesian system. Angles are in degrees.

Command Argument(s) Description Remark
am X,Y,Z Motion Move in X, Y and Z directions
ar X,Y,Z,ROTX,ROTY,ROTZ Rotation Rotation around the axes. X, Y and Z: pivot point coordinates
ab R,G,B Blinking Sudden change of color between the original and this
ac R,G,B Color change Smooth change of color between the original and this
az SCALEMIN,SCALEMAX Zoom Uniform scaling. Center point: CoG
as X,Y,Z,MinX,MinY,MinZ,MaxX,MaxY,MaxZ Scale Scaling from a point by individual scale factors
ai MinX,MinY,MinZ,MaxX,MaxY,MaxZ Inflate Scaling from center of gravity by individual scale factors
ae Explode Explosion as defined in the project file [VOLUMES] section
av X,Y,ZOOM,ROTX,ROTY,ROTZ View Camera motion (pan + zoom + rotate)
af SCALEFACTOR,FORCEDVISIBLEFIT Fit Fit to screen. See remarks below.
ao move back to Original position Original position: where the model is when the file is opened
amb FRAME1,FRAME2 move Between reference frames Reference frames are defined by the IC command
at animate Trigger Starts the animation

Zoom: scaling between a minimum and maximum factor (1: current size). Center point is the CoG (center of gravity) of the given volume.

Scale: Scaling where the center point is defined by the first 3 parameters. The minimum and maximum scale factors are defined in all directions individually.

Inflate: Scaling where the center point is the CoG of the given volume. The minimum and maximum scale factors are defined in all directions individually.

Colors are defined by RGB components ranging between 0..255

Scalefactor: zoom to full extents: 1. Recommended for fit to screen: 90% (0.9)

Forcedvisiblefit: if yes (1), then the wireframe is not taken into account. If no (0), then the wireframe is fit

Example: animate motion in to 40 (model length unit) in Y direction: am,0,40,0

Controls the visibility of the wireframe.

Command Argument(s) Description Remark
fs wireframe Show
fh wireframe Hide

The wireframe is all of the sharp edges of the whole model. In interactive mode it can be turned on/off by clicking on the first item of the top menu (Edges on/off)

Example: turn on the wireframe: fs

Controls the visibility of the wireframe.

Command Argument(s) Description Remark
po 0, or 1 One way action If yes (1), then the animation happens only in one direction, if not (0), then both ways
pw TIME Wait Interrupts the execution for "TIME" seconds
pp TIME animate Period Periodic time (1 / frequency) of the animation
pf FREQUENCY animation Frequency Frequency (1 / periodic time) of the animation
pn LOOPS Number of loops The animation happens this many times, then stops
ph Halt Stops the animation
pc 0, or 1 Come back after animation When the animation is finished, the volume comes back to original position (1), or not (0)
ps Snapshot: store actual position Stores current position and it can be used as reference
pr timing Reset Reset timing controls to their default values. See remarks below.

The wireframe is all of the sharp edges of the whole model. In interactive mode it can be turned on/off by clicking on the first item of the top menu (Edges on/off)

Example: turn on the wireframe: fs

Creates and modifies group(s). A group is one, or more volumes.

Command Argument(s) Description Remark
gc NAME group Create Creates a group from the selected volumes
gr NAME group Redefine Overwrites a group using the selected volumes
gs NAME group Show Shows the volumes in the given group
gh NAME group Hide Hides the volumes in the given group
gd NAME group Delete Deletes a group (only the group entry is deleted, the volumes remain unchanged)
gp group Purge Deletes all group entries (again, the volumes remain unchanged)

A group is essentially a set of volumes

A volume can be included in multiple groups in the same time

The name field is a string, which is not case sensitive, therefore if a group is defined as FASTENERS (gc,FASTENERS) then we can refer to this as FASTENERS, Fasteners, fasteners, fAstENerS, it’s all the same

At the beginning no group is defined

Groups can only be defined and manipulated using scripting

Groups behave the same way as volume sets (which are defined in the project file [VOLUMES] section)

Example: create a group an call it "Plates": gc,Plates

Creates and modifies group(s). A group is one, or more volumes.

Command Argument(s) Description Remark
wth STRING Window header caption 1 (see picture below)
wtm STRING Message 2 (see picture below)
wt1 STRING Close button caption 3 (see picture below)
wr window Reset Resets the captions to their default values
ws window Show
wh window Hide

Window properties are defined in the configuration file ([DIALOG] section).

Examples:

  • Set the window header caption to "Title": wth,Title

  • Set the window message to "Text to show": wtm,Text to show

  • Set the close button caption to "Close": wt1,Close

Multi-line messages are possible; HTML syntax applies. Separate the lines with <br>

Command Argument Description Remark
ic ID,X1,Y1,Z1,X2,Y2,Z2,X3,Y3,Z3 inertial reference frame Create Use 0 for ID if unsure, then take the return value as ID
itg ID,X,Y,Z inertial reference frame translate Global Global: global cartesian
itl ID,X,Y,Z inertial reference frame translate Local Local: local cartesian
irg ID,ROTX,ROTY,ROTZ inertial reference frame rotate Global Global: global cartesian
irl ID,ROTX,ROTY,ROTZ inertial reference frame rotate Local Local: local cartesian
id ID inertial reference frame Duplicate Make a copy at the same location
ie ID inertial reference frame Erase Delete a given frame
ip inertial reference frame Purge Delete all

Creates and modifies group(s). A group is one, or more volumes.

Command Argument(s) Description Remark
tms marker Show Shows marker of the visible volumes
tmh marker Hide Hides marker of the visible volumes
tls label Show Shows labels of the visible volumes (works only if the markers are already visible)
tlh label Hide Hides all labels
trs ID remark Show Shows a custom message
trh ID remark Hide Hides a custom message
tas alpha blending Set Set simple alpha blending on the selected volumes
tao alpha blending Off Turns off alpha blending on the selected volumes
taf alpha blending Flip Flips alpha blending on the selected volumes

Markers: interactive equivalent: Top menu → Settings → Markers on/off

Labels: interactive equivalent: clicking on a marker

Custom messages are defined in the configuration file ([REMARKS] → REMARK*). Numbering begins with 1

Example: show the second custom message: trs,2

Technology photo created by freepik - www.freepik.com