How to BScript
In these manual:
is used for Input-Code and
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.
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.
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.
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.
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".
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 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 (
: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:
Basically any varibale can be changed without special notation to another type in BScript:
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.
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 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 (
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:
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.
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
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)
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 126.96.36.19971 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
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)
LOAD elements may be reloaded from data files.
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.
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.
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).
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).
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.
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,...)
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
- Name of the Input-Curve
- Name of the Input-Pointarray
- Name of the new generated Output-Element
- Name of the new generated Output-UV-Pointset
- 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".
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)
- Name of the Input-Surface
- U-Value on the curve
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)
- Name of the Input-Curve
- 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.
#WSGSNN means "from WorkSpace Get from a Set the element-Name of the N'th element".
All BScript-Functions are described in the Manual.
- BScript-Code is written only in capital letters. (However, the script analyzer is not case-sensitive.)
- Variable- and Elementnames are built at least of 3 characteres. Exceptions are only within a small loop used names and running numbers.
- Running numbers are usually described as
:I, :J, :K.
- 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
- Each BScript-Routine should have headers with the names of the routine, of the programmer, date and project in it.
- Commands as
LOADshould be called at the beginning of the routine.
- 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.
- Bscript Code should be divided by headings as simple as possible to understand.
- To use the code with comments, a
!is used after the code, or a
C Section to calculate circle elements. DEF :R:R1=(200*:PI) ! Radius of the circle.
- 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
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!
On SoftART's Homepage there is the whole BScript-Manual wherein all commands and functions are explained.
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
Example: Extract V-const. Lines of a Plane and saves them into a Set.
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)“
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