How to BScript


In these manual:
is used for Input-Code and
for Output-Code.


Introduction

Description

BScript is a script-based programming language for CAD applications. The language has besides control structures ( "if, then" conditions, loops, etc.) over 300 powerful commands which allow you to efficiently perform geometric calculations and programming processes of technical processes.
BScript also has an interface to Unigraphics (NX), with which on the user functions operations can be performed and graphic objects can be exchanged.

Installation of BScript

The BScript software can be used either as a standalone program (BScript.Runtime), or as an NX Add-On (BScript.NX). The BScript.NX depends on the version of NX. Currently, the following versions are available: NX_60, NX_80 and NX_85.

BScript-Window_neu

Use of Procedures

In order not to write code again and again, this can be stored in BScript procedures. These text files with the extension .bsp can be modified in any text editor.
BScript has commands to load these procedures, as well as aids for easier debugging. So a procedure can call other procedures and after their finsih the mother procedure may continue in their own code.
With ADD F=procedurename a procedure is called and the contained code is processed. The processed lines of code and possible outputs are displayed in the output window of BScript-Window. Useful commands for debugging can be found in the section "Tips for easier debugging" towards the end of this page.

Using Functions

In addition to the procedures, there is the possibility of calling features (BFunctions). While the workspace and the symbol table stay the same during the call of a procedure, the function is called in a new BScript-Instance. Therefore all needed variables and elements must be passed and all temporary elements are discarded at the end of the function.
In addition, the functions can be parallelized. In a loop several functions may be started then it may be waited for their completion in a second loop. So compute-intensive tasks can be accelerated. The exact syntax for using functions is explained in detail in the chapter "BFunctions".

BScript-Basics

Datastructures

There are two kind of data: Variables and elements. Variables are single values ​​or value groups. Elements may be groups of points, BSpline-lines, surfaces etc.

Variables

Variables are themselves defined values ​​(of any dimension) or the results of calculations or functions. They must always be initialized with a definition.
There are three types of variables: Integer (whole number), Real (real numbers) and Character (text). When you define a variable the type (:I, :R oder :C) has to be specified.
Variables can be overridden at any time and stand globally.

Attention: A symbol must always be marked by a colon before the name! First, in the definition (DEF), then at each use (see examples below).

 Example:


C Definition of an Integer:
DEF :I:L1=200
DEF :I:UT=:L1/3 ! If the result is not an integer, the rounded integer value is taken.

C Definition of a Real:
DEF :R:PLOP=18.09132008
DEF :R:R1=(200*:PI) ! PI is already pre-defined and can be used anytime.
DEF :R:W1=(360/15)
DEF :R:VT=0,-110,0 ! Definition of a 3D-vector.
C The #FF function is to convert a real value with any number of digits into a text string:
DEF :C:TX="'The radius is approximately '+#FF(':R1',6,2)"

C Definition of a Character:
DEF :C:TEXTOUTPUT="'ORDER : '+:L1+' liter wine'"

If you want to count on vectors, you do not calculate each dimension individually but can perform the operation directly with the mathematical operators:
DEF :R:V2=2*:VT

Conversion between Variable Types (Int, Real and Character)

Basically any varibale can be changed without special notation to another type in BScript:
DEF :R:A1=3.3333
DEF :I:A2=:A1 ! The value is 3
DEF :C:A3=:A1 ! The value is '3.3333'
DEF :C:A4=:A3 ! :A4=:A1
When converting from Real into Char it is recommended to use the #FF function so that the length of the text can be controlled.

Conversion between Elements and Variables

To read the content of workspace member, there are some WS-functions ( #WS.. ) available. So e.g. individual points of an element are enqueried (#WSGG) or calculations may be performed (e.g. the average of a column (#WSAVG)).
Conversely, the variables can be used directly in the definition of elements .

 Example:

C Definition of 2 points (as variable):
DEF :R:P1=0,0,0
DEF :R:P2=100,100,100

C Definition of an point-element with these 2 points:
ESTA ND=SRAIGHTLINE_1
E G=:P1
E G=:P2
EEND

C Transformation of the element with the transformation-element TT
TRAFOR NE=STRAIGHTLINE_1 NT=TT

C Put back the points into variables:
DEF :R:P1_T=#WSGG(‘SRAIGHTLINE_1,1)
DEF :R:P2_T=#WSGG(‘SRAIGHTLINE_1,2)

Elements (Fields)

Elements consist of a line with the definition of the element (ESTA), then any number of rows with the content of the element (starts with (E G=) and ends with a final line (EEND).

 Example:

ESTA ND=TEST LGRU=3
E G=-100,0,0
E G=0,100,0
E G=100,0,0
E G=0,170,0
E G=-100,0,0
EEND
ESTA_col
The default BScript structure is red, the one defined by the user is dyed green.

Next we open a Circle-Line-Element (structure from any chronology of straight line segments and arcs). Within an element not every line has to be structured the same. The straight sections need only X/Y-coordinates, while the circular arcs additionally need a radius and start- or end angle:

 Example:

KGSTA ND=LINIE ICL=1 ! ICL is an option of the line (for the meaning see manual)
KG X=10 Y=50
KG X=40 Y=70
KG X=70 Y=70 R=12 FIS=180
KG X=90 Y=70 R=12 FIE=0
KG X=150 Y=70
KG X=130 Y=50 R=-20
KG X=85 Y=30 R=10
KG X=35 Y=40 R=-25
KGEND ! Here we close the element.

The following animation shows the gradually formation of the element:
KG-Element Animation

So then the element looks in NX:
KG

BScript has several commands for handling elements.
Here a short selection:
TYPE : The element is listet with the command TYPE (for the corresponding output, see the example "Accessing the Workspace " in Chap. "Internal Memory"). If it is a large element, the output can be restricted with the help of tags.
EDIT : With this command individual values ​​or whole groups of an element can be changed.
COPY : With COPY existing elements may be copied.
SET : Several elements can be stored together in one set. This is useful for example for exporting results in text or binary files or the processing of many similar elements by means of a loop.
See the examples in the chapter "Examples of Commands and Functions."
The use of commands is in its chapter, as well as in the Manual accurately described.

Storage Options

Internal Storage

Each generated memory structure - elements and variables - is cached for the duration of BScript session. Elements end up in the workspace variable in the symbol table (see figure in Chapter BScript-Window) .
All in workspace and in the variable list contained elements and variables can be saved together in a file by using the command SNAPSHOT,W (write).
To read these stored files, the command SNAPSHOT,R (read) is used.

 Example:

DIR ! Lists all elements/variables of the workspace directory.
TYPE NE=TEST ! Shows the content of the workspace element TEST

These two input lines cause the following output:


DIR

Elementname Element Type Group Length # of Groups

LINIE BCurve 4 57
TEST BPoints 3 5

Number of objects : 2

TYPE NE=TEST

BPoints TEST
------------

Points :

Part 1
1 -100.000000 0.000000 0.000000
2 0.000000 100.000000 0.000000
3 100.000000 0.000000 0.000000
4 0.000000 170.000000 0.000000
5 -100.000000 0.000000 0.000000

Number of groups : 5
Number of parts : 1
 Example:

DEF,P NP=:R1 ! Output Variable-Content (see commands)
DEF,P NP=:VT
DEF,P NP=:TX
DEF,D ! Output Variable-Table (see commands)

BScript Output:


DEF,P NP=:R1

R1 628.318530717959
DEF,P NP=:VT

Table of Variables :

Name Value
VT 0
VT(2) -110
VT(3) 0

DEF,P NP=:TX

TX The radius is approximately 628.32
DEF,D

Table of Variables :

Name Value
$CURRENTPROCEDURE
$DEFDIR C:\Program Files\Siemens\NX80\UGII
$NOWAIT false
$PROGRAM CSharp
$VERSION 1.3.6.15971
E 2.71828182845905
L1 200
PI 3.14159265358979
R1 628.318530717959
TEXTOUTPUT ORDER : 200 liter wine
VT 0
VT(2) -110
VT(3) 0
W1 24

Externel Storage

Elements and sets can be written in text- or binary files using the SAVE command. Variables do not know a command for storage, as they can be relatively easily recapitulated. If certain variables still have to be stored, they can be written into an element and then be stored.
(ESTA ND=VAR / E G=:VARIABLE / EEND / SAVE,B NE=VAR F=Variable.bin)
With LOAD elements may be reloaded from data files.

Geometry Elements

Point

A single point can be either a symbol (3D vector) or be defined as BPoint element with only one group. When with the point especially vector calculations are made, the first method is recommended if geometrical calculations shall be made (e.g. distance on surfaces) it needs the second variant.

Point Set

A point set defines a group of points which have a relationship. The number of points can be freely selected (there are also empty points amounts possible) and may change during the program sequence as well.
It is also possible to define point sets with a group length (LGRU) greater than 3. In this case, the first 3 values ​​have to define x, y and z and then additional information may be saved.

Straight Line Element/Vectorelement

This element expands the point set by a direction vector for each point. The element consequently has a fixed length of 6 groups (x,y,z,vx,vy,vz).

Plane

The plane in the space is defined by a point in space and the normal vector of the plane. To perform calculations on the plane, additionally a local direction vx is defined. The extension of the plane is infinite.
The plane is saved in the format x, y, z, vnx, vny, vnz, vlx, vly, vlz.
In addition, it is possible to define a limited level as BSpline surface with 4 grid points (command EBN,B).

Cylinder

Cone

Torus

BSpline-Elements

Free-form elements in BScript are based on the B-Spline theory. To work with BScript, this theory does not need to be understood, however, for higher geometric calculations it is useful.
It is important to note that B-Spline elements always have a U/V-grid, which forms a local (non-linear!) coordinate system of the element.

The following document offers an overview of BSpline theory.


Control Structures

BScript knows two kind of different control structures: Commands and Functions.
Gross may subdivide it as follows:
Commands access (mostly) at elements and include geometric calculations/transformations, BScript controllers, organizations of workspace, graphical outputs and NX controls. As the code looks like this:
COMMAND,OPTION TAG1=value1 TAG2=value2 .... Thereby the number and need for options and tags varies from command to command, and depending on the desired use.
Functions access (mostly) at variables and include mathematical calculations, vector calculations (at BSplines), and access to the contents of elements in the workspace. As the code looks like this:
OUTPUT = #FUNKTION(PARAMETER1,PARAMETER2,...)

Commands

The structure of a command using the example ABST (Distance from points to curves/planes.):

ABST,B NF=FDS NE=PUN ND=APUN NDUV=UVP
FDS
Name of the Input-Curve
PUN
Name of the Input-Pointarray
APUN
Name of the new generated Output-Element
UVP
Name of the new generated Output-UV-Pointset
,B
Option of the command. In this case, it causes points outside the boundary of the area are ignored.
NF NE ND NDUV
Tags means of which in- and outputs are given the command.

It is not always necessarily to indivate all the tags. In certain cases, an option requires additional tags, see Manual. As a memory aid should be mentioned: NE - name of the Existing element, ND - name of the D efining element.
Examples of using of Loops and of Flow Control are in Chap. "Examples for Commands and Functions".

#-Functions

The structure of a Function using the example #BCTANVU (Calculate a tangent vector of a curve with a given U-value):

DEF :R:VT = #BCTANVU(’LINE’,0.26)
LINE
Name of the Input-Surface
0.26
U-Value on the curve

 

Attention:
Must be entered an element name in a function (not with variables!), so it always needs single quotes )!

A group of functions allow access to the workspace.
So, e.g. individual items or values ​​in elements, the number of entries of an element or extreme values ​​may be enquired.
Here is an example in which the maximum value from the second column (=Y-value) of the element LINE is queried.

DEF :R:YMAX = #WSMAX(’LINE ’,2)
LINE
Name of the Input-Curve
2
Index of the value column

 

Attention: BScript counts from 1!

The function names seem a little cryptic at first time. With a little practice, the required function can be found easily, because the letters mostly stand for important components of the function.
The function #WSGSNN means "from WorkSpace Get from a Set the element-Name of the N'th element".
All BScript-Functions are described in the Manual.

BFunctions

todo


Remarks and Useful Tips

Unwritten Law

  1. BScript-Code is written only in capital letters. (However, the script analyzer is not case-sensitive.)
  2. Variable- and Elementnames are built at least of 3 characteres. Exceptions are only within a small loop used names and running numbers.
  3. Running numbers are usually described as :I, :J, :K.
  4. It's worth it, if the name of elements show which kind they are: for example, S... for surfaces, L... for lines/curves, P... for point sets.

Tips for a nice Code

  1. Each BScript-Routine should have headers with the names of the routine, of the programmer, date and project in it.
  2. Commands as ADD and LOAD should be called at the beginning of the routine.
  3. Within the loop (DO) it's recommended that the rows are engaged with blanks, so that the code is easier to read. Furthermore it shal be engaged after IF/ELSE, ESTA, KSTA, KGSTA und GSTA. Also at each command building some sort of bracket.
  4. Bscript Code should be divided by headings as simple as possible to understand.
  5. To use the code with comments, a ! is used after the code, or a C.
    C Section to calculate circle elements.
    DEF :R:R1=(200*:PI) ! Radius of the circle. 
  6. As BScript procedures can be relatively long, it is worth to break down the code with intertitles.
    C -------------------------------
    C SETTINGS FOR SUCTION SIDE
    C -------------------------------
    

Attention: Never use tabs!

Attention: A blank in front of a comment-C causes an error!

Tips for an easier Debugging

BScript contains some commands for debugging:
WAIT,I interrupts the work of the routine and allows the user to check if the process is running correctly. With the input ADD,C in the console the process is continuing. If you add in the WAIT-line a unique !-comment, it is easily to be seen where in the code you have just stopped. The command ECHO AUS or ECHO EIN stops or starts the replay of the processed code in the console. The repeated display of loops can be avoided and the processing speed can be increased. Before a routine is called again, the commands DEL,ALL and UGDEL,ALL should be executed to clear the workspace or the NX display.

Tips for more Fun with BScript

The practice of SoftART has shown that the editor UltraEdit or Notepad++ fits the best for programming with BScript. He provides useful tools such as the Block-Edit-Mode, Keyboard-Shortcuts and voice based Text-Coloring.
If you can work with UltraEdit you can receive the BScript-Word file from us, which is inking your code after BScript-Rules and can significantly improve the overview in your routines!

BScript Manual

On SoftART's Homepage there is the whole BScript-Manual wherein all commands and functions are explained.

Examples for Commands and Functions

The following examples are designed so that they can be inserted directly via copy/paste into the BScript window. These are typical examples of applications, which occur frequently.

UGPART,C NE=WORK.PRT
FILE,D NE=WORK.PRT
UGPART,L F=D:\Temp\NX_Start.prt
WAIT T=1
UGPART,S F=WORK.PRT
UGLAYER N=1
DO REPEAT=:NB :I:I=1
DEF :R:VVAL=(:I-1)/(: NB-1)
DEF :C:NAME=”’LINE_’+:I”
EXTRA,V NF=EFLA ND=:NAME V=:VVAL
SET,A ND=LINESET NE=:NAME
DEF :I:I=:I+1
ENDDO

#FF() ! Attention: The decimal point counts as a place! To fill the parameters meaningful, it is therefore useful to know the approximate number of length. ! #FF rounds ! Total number very high, then cut with #STRTRIM (). Or find out in advance position of the point with #STRLEN and #LOCATE.

WRITE T=“‘PI with 10 positions after decimal point is the same as ‘+#FF(:PI,12,10)“
Here is an example in which by means of a loop, the sum of all the Z-values ​​of any elements in a set is added.

ESTA ND=TEST1 LGRU=3       ! First we define 3 elements.
E G=-100,0,50
E G=0,100,20
EEND

ESTA ND=TEST2 LGRU=3
E G=100,0,80
E G=0,170,0
E G=-100,0,30
EEND

ESTA ND=TEST3 LGRU=3
E G=0,100,-10
E G=50,180,40
E G=100,0,0
E G=0,120,0
EEND

SET ND=TESTSET NE=TEST1,TEST2,TEST3     ! Insert elements in a set

DEF :R:SUMVAL=0                         ! Initialise the sum
DEF :I:NSE=#WSNSE(TESTSET)           ! Number of elements in a set

DO REPEAT=:NSE :I:I=1                ! Loop (:NSE number of loops)
DEF :C:NAME=#WSGSNN('TESTSET',:I)       ! Name of the n-th elemet
DEF :R:VAL=#WSSUM(:NAME,3)              ! 3. value of the der 1. value group
DEF :R:SUMVAL=:SUMVAL+:VAL              ! Add :VAL to :SUMVAL
DEF :I:I=:I+1                           ! Increase control variable
ENDDO

DEF,P NP=:SUMVAL                        ! Output result. Here: 210
DEF :C:CLASS="undefined"
IF C=(:SUMVAL>0)       ! Definition of :SUMVAL see Example for Loops
DEF :C:CLASS="positiv"
ELSE
DEF :C:CLASS="negativ"
ENDIF

DEF,P NP=:CLASS

C The IF block works, but noted the possibility: SUMVAL = 0 not. Therefore two IF - blocks are nested:

DEF :C:CLASS="undefined"
IF C=(:SUMVAL>0)       ! Definition of :SUMVAL see Example for Loops
DEF :C:CLASS="positiv"
ELSE
IF C=(:SUMVAL=0)
DEF :C:CLASS="null"
ELSE
DEF :C:CLASS="negativ"
ENDIF
ENDIF

DEF,P NP=:CLASS


Exercises

Top