Scripting with CATIA

CATIA Version 5

Programmer’s Guide
ii Scripting with CATIA Programmer’s Guide
 ®
Special Notices ©

CATIA® is a registered trademark of DASSAULT SYSTEMES S.A. in France and other

countries.

Any of the following terms may be used in this publication. These terms are trademarks of
the International Business Machines Corporation:
AIX IBM
DB2 RISC System/6000
DB2/6000 SAA
FORTRAN/2 SQL/DS
GDDM
Any of the following terms may be used in this publication. These terms are trademarks of
the Hewlett-Packard Company:
HP HP/GL-2
HP/GL HP-UX
HP VUE HP Vectra XW
HP 9000 Series 700 SAM
Any of the following terms may be used in this publication. These terms are trademarks of
the Silicon Graphics, Inc.:
Indigo2 Onyx2
IRIX OpenGL
O2 Silicon Graphics
Octane
Any of the following terms may be used in this publication. These terms are trademarks of
the Sun Microsystems Computer Company:
HotJava Ultra1
Java Ultra2
Solaris 2.5 Ultra30
Any of the following terms may be used in this publication. These terms are trademarks of
the Microsoft Corporation:
ActiveX OLE
Excel PowerPoint
Internet Explorer VBScript for Windows NT
JScript Visual Basic
Microsoft Windows NT
Office 97 Word
Any of the following terms may be used in this publication. These terms are trademarks of
other companies or institutions:
Acrobat Reader Adobe Systems Inc.
BasicScript Summit Software Corporation
CADAM Dassault Systemes of America Corp.
Digital Personal Workstation 266i Digital Equipment Corporation
InstallShield InstallShield Software Corporation
JavaScript Netscape Communications Corporation
Netscape Navigator Netscape Communications Corporation
PostScript Adobe Systems Inc.
PROFESSIONAL CADAM Dassault Systemes of America Corp.
 PDF Adobe Systems Inc.
TIFF Aldus Corporation
UNIX UNIX System Laboratories, Inc.
Versatec Versatec, Inc.
All other company names and product names mentioned are the property of their
respective owners.

Certain portions of this product contain elements subject to copyright owned by

the following entities:
© Copyright Dassault Systemes
© Copyright Dassault Systemes of America.
© Copyright Adobe 1997.
© Copyright D-Cubed Ltd., June 1997.
© Copyright ITI 1997.
© Copyright Summit.

iv Scripting with CATIA Programmer’s Guide

Contents

Special Notices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Using This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Where to Find More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Conventions Used in this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Getting Started with Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

A Script Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Recording the Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Modifying the Generated Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Running the Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Invoking CATIA from a Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Running In-process Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Running Out-process Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Running Out-process Macros from VBA or VB5 . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Running Out-process Macros Using the Windows Scripting Host . . . . . . . . . . . . . .28
Running Out-process Macros from a Dynamic HTML Page . . . . . . . . . . . . . . . . . .30

Object Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Object Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

About Objects, Collections, Properties, and Methods . . . . . . . . . . . . . . . . . . . . .33

v
 About Inheritance and Aggregation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Some Tips about Collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Some Tips about SafeArrayVariant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Some Tips about Sub and Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

About Numbers, Literals, and Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Adding a Macro as a Command in a Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Scripting with Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Infrastructure Object Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Viewers and Viewpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Cameras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Programming Tasks and Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Creating a New Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Opening a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Closing a Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

Saving a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

Saving As a Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Setting the Application’s Window Dimensions and Location . . . . . . . . . . . . . . .61

Opening a Document and Printing it on the Default Printer . . . . . . . . . . . . . . .62

Creating a New Document, Saving and Closing It . . . . . . . . . . . . . . . . . . . . . . . .63

Using Cameras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

vi Scripting with CATIA Programmer’s Guide

 Modifying the Characteristics of a Viewpoint3D . . . . . . . . . . . . . . . . . . . . . . . . .67

Scripting with Part Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

Part Design Object Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Sketch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Geometric Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Sketch-Based Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

Prism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Hole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Revolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Stiffener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Sweep. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Boolean Shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Dress Up Shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Chamfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Draft. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Fillet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Thickness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86

Transformation Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

Repartition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

Draft Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91

Literal Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92

Programming Tasks and Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Creating Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Contents vii
 Creating a Formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Modifying a Formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Activating and Deactivating a Formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Creating a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Creating a Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Scripting with Assembly Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Assembly Design Object Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Programming Tasks and Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

Creating a Simple Assembly with Two Parts . . . . . . . . . . . . . . . . . . . . . . . . . . .110

Creating an Assembly with Components of the Same Product. . . . . . . . . . . . .114

Creating an Assembly with a Component of an External Product. . . . . . . . . .119

Producing a Bill of Materials from a Product Document . . . . . . . . . . . . . . . . .121

Scripting with Drafting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Generative Drafting Object Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Programming Tasks and Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Creating a Front View and a Projection View . . . . . . . . . . . . . . . . . . . . . . . . . .131

Creating a Section View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Creating a Detail View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Creating a Multi-Document Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Generating Dimensions From Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Updating All the Sheets of all the Drawings Contained in a Folder . . . . . . . . .140

Printing All the Sheets of all the Drawings Contained in a Folder . . . . . . . . . .142

viii Scripting with CATIA Programmer’s Guide

CATIA Object Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Contents ix
x Scripting with CATIA Programmer’s Guide
About This Book

This book describes the CATIA exposed objects and how to use them to write macros you can run
to automate your job.

It describes for each product the exposed object architecture and the main properties and methods
of these objects, how they relate, and how to use them. Basic tasks and advanced scenarios are
given as examples you can copy and customize to match your own needs.

Reference material is also provided, and each object, property, and method used in the object archi-
tecture or in the tasks and scenarios points to its reference information.

Using This Book

This book is intended to end users who want to improve their productivity in automating repetitive
tasks using macros they can write from journalized macros, from the examples supplied in this
book, or from scratch.

Where to Find More Information

You will find more information about the scripting languages and environments you can use in the
on-line information supplied by the platform vendor, or in related books such as:
• Microsoft Visual Basic Scripting Edition
• Microsoft Visual Basic for Applications
• Microsoft Visual Basic 5 Development Studio
• Summit Basic Script for UNIX

Conventions Used in this Book

Certain conventions are used in CATIA documentation to help you recognize and understand
important concepts and specifications.

xi
Preface

The object diagrams included in this book follow the UML (Unified Modeling Language) Notation
from Rational Software Corporation, and uses additional graphic conventions fully described in
Object Architecture Overview.

The following text conventions may be used:

• The titles of CATIA documents appear in this manner throughout the text.
• File -> New identifies the commands to be used.
The use of the mouse differs according to the type of action you need to perform.

Whenever you read… …use this mouse button

Select (menus, commands, geometry in graphics area, ...)

Click (icons, dialog box buttons, tabs...)
Double-click
Shift-click
Ctrl-click
Check (check boxes)

Drag
Drag and drop
Move

Right-click (to select contextual menu)

Graphic conventions are denoted as follows:

indicates the estimated time to accomplish a task.

indicates a target of a task.

indicates the prerequisites.

indicates the scenario of a task.

indicates a key point.

indicates tips.

points out a reminder.

indicates a warning.

xii Scripting with CATIA Programmer’s Guide

 Preface

indicates a forbidden action.

indicates information.

indicates the end of a task.

Conventions Used in this Book xiii

Preface

xiv Scripting with CATIA Programmer’s Guide

Getting Started with
Scripting 1
Welcome to Scripting with CATIA which will show you how to use a scripting language to access
CATIA objects to capture your own know-how and to increase your productivity. You can custom-
ize CATIA to automate repetitive tasks, and to make CATIA fit your own process.

The products that make up CATIA share the same object model which can be accessed, as well as
their own objects, by scripts written in Visual Basic with Windows NT, and scripts written in Basic
Script for UNIX.

You can write your scripts from scratch, but you can also use the journalling facility from the
Tools->Macro command that records end-user scenarios in scripts you can then use as is or mod-
ify.

We put here a simple script example, to show what is scripting with CATIA, which are the different
things to do to script, present briefly the scripting environment and dialog window, and what is jour-
nalling. This example is divided into the following parts:
• Recording the scenario
• Modifying the generated macro
• Replaying the macro

You will then find information about the scripting languages and environments, and some keys for
you if you are not familiar with writing macros in Invoking CATIA from a Scripting Language.

15
1

A Script Sample
This sample illustrates how to use scripting to automate a very simple, but repetitive user task.
We’ll first record the creation of a cylindric pad. Then we’ll modify the generated macro to create
five similar pads. Finally we’ll replay the modified macro.

16 Scripting with CATIA Programmer’s Guide

 1

Recording the Scenario

This scenario creates a circle in a sketch, and uses this sketch to create a cylindric pad.

The recorded macro is stored in a file, and not in the document.

1. Select the Tools->Macro->Start

Recording command to display
the Record Macro dialog box.

2. In the Record Macro dialog box,

click in the “Macro in” area to
“External File” to store the macro
in a file. Give a name to the
macro. To do this, click Select.
The Select External File dialog
box appears. Select or create the
appropriate file and click Open.

3. Click Start in the Record Macro

dialog box to start recording the
macro. The Stop Recording dia-
log box appears. Leave it as is
until the last step is reached.

4. Click File->New, or click on the icon, and double-click Part to create a new part. A new
part is created and a window for this part is opened.

17
1

5. Select the
xy plane
in the
specifica-
tion tree,
and
select the
sketcher
icon
to create
a sketch.

6. In the
sketcher
toolbar,
select the
circle
icon
and click
twice to
indicate
succes-
sively the
center of
the circle
and a
current
point on
the circle.

7. Click on the sketcher exit icon .

8. Select the pad icon to create a pad on the sketch.

18 Scripting with CATIA Programmer’s Guide

 1

9. In the Pad Definition dialog box,

choose a length of 10 mm and
click OK. The pad is created.

10. The pad

creation
is now
complete.

11. Click Stop Recording in the Stop

Recording dialog box, or select
Tools->Macro->Stop Record-
ing. Your macro is now stored in
the file you have selected.

Have a look at the generated macro:

Language=”VBSCRIPT”

Dim PartDocument0 As Document

Set PartDocument0 = CATIA.Documents.Add ( “Part” )

19
1

Dim Body1 As Body

Set Body1 = PartDocument0.Part.Bodies.Item ( “PartBody” )

Dim Plane2 As GeometricElement

Set Plane2 = PartDocument0.Part.GeometricElements.Item ( “xy-plane”)

Dim Sketch3 As Sketch

Set Sketch3 = Body1.Sketches.Add ( Plane2 )

Dim Factory2D4 As Factory2D

Set Factory2D4 = Sketch3.OpenEdition

Dim Circle2D5 As Circle2D

Set Circle2D5 = Factory2D4.CreateClosedCircle ( 0.000000, 0.000000,
12.000000 )

Dim Point2D6 As Point2D

Set Point2D6 = Factory2D4.CreatePoint ( 0.000000, 0.000000 )

Sketch3.CloseEdition

Dim Pad7 As Pad

Set Pad7 = PartDocument0.Part.ShapeFactory.AddNewPad( Sketch3,
10.000000 )

PartDocument0.Part.Update

We’ll detail below, line by line, what has been recorded, following the interactive steps:
1. You first put in place the recording environment by selecting the Tools->Macro->Start
Recording command, then giving a name to the macro in the Record Macro dialog box, and
clicking Start. This opens the macro file and generates the first instruction stating the scripting
language used:

Language=”VBSCRIPT”

2. Click File->New, or click on the icon, and double-click Part to create a new part. This
generates the following instructions:

Dim PartDocument0 As Document

Set PartDocument0 = CATIA.Documents.Add ( “Part” )

Dim Body1 As Body

Set Body1 = PartDocument0.Part.Bodies.Item ( “PartBody” )

A new document with the Part type is created. To do this, such a document is added to the Doc-
uments collection of the CATIA application. The PartBody of the created part is retrieved from
the Bodies collection in the part document and put in the variable Body1 for future use.
3. Select the xy plane in the specification tree:

Dim Plane2 As GeometricElement

Set Plane2 = PartDocument0.Part.GeometricElements.Item ( “xy-plane”)

20 Scripting with CATIA Programmer’s Guide

 1

The xy plane is retrieved and put in the Plane2 variable.

4. Select the sketcher icon to create a sketch:

Dim Sketch3 As Sketch

Set Sketch3 = Body1.Sketches.Add ( Plane2 )

Dim Factory2D4 As Factory2D

Set Factory2D4 = Sketch3.OpenEdition

A sketch named Sketch3 is added to the Sketches collection using this Plane2 plane. A
Factory2D is created by opening the sketch editor against the created sketch. This Factory2D
includes methods to create 2D objects.

5. In the sketcher toolbar, select the circle icon and click twice to indicate successively the
center of the circle and a current point on the circle

Dim Circle2D5 As Circle2D

Set Circle2D5 = Factory2D4.CreateClosedCircle ( 0.000000, 0.000000,
12.000000)

Dim Point2D6 As Point2D

Set Point2D6 = Factory2D4.CreatePoint ( 0.000000, 0.000000 )
The Factory2D CreateCloseCircle method is used to create the circle. It is centered at the point
(0,0) with a radius of 12 mm. The center point is created as a Point2D object.

6. Click on the sketcher exit icon .

CATIASketch3.CloseEdition

The sketch editor is closed.

7. Select the pad icon to create a pad, and in the Pad Definition dialog box, choose a length of
10 mm and click OK. The pad is created.

Dim Pad7 As Pad

Set Pad7 = PartDocument0.Part.ShapeFactory.AddNewPad ( Sketch3,
10.000000 )

PartDocument0.Part.Update

The AddNewPad method of the ShapeFactory is used to create the pad. It is created using the
sketch and the length of 10mm. The part is updated.
8. Click Stop Recording in the Stop Recording dialog box, or select Tools->Macro->Stop
Recording.
This closes the macro recording sequence and saves the macro in the selected file.

This is all what you performed interactively.

21
1

Modifying the Generated Macro

This task explains how to modify the generated macro to make it loop on the creation of five
identical cylindric pads.

1. Select the Tools->Macro->Mac-

ros... command to display the
Macro dialog box.

2. In the Macro dialog box, click in

the “Macro in” area and select
“External File”.

3. Select the name of the macro to

edit. If the recorded macro is not
already the current one, click
Select and the Select External
File dialog box appears. Click the
appropriate file name and click
Open.

22 Scripting with CATIA Programmer’s Guide

 1

4. Click Edit. Your favorite editor opens on the selected macro. The instructions written using
the bold typeface are those you need to add or modify while the others already exist in the
macro:

Language=”VBSCRIPT”
‘My macro creates five cylinders

Dim PartDocument0 As Document

Set PartDocument0 = CATIA.Documents.Add ( “Part” )

Dim Body1 As Body

Set Body1 = PartDocument0.Part.Bodies.Item ( “PartBody” )

Dim Plane2 As GeometricElement

Set Plane2 = PartDocument0.Part.GeometricElements.Item ( “xy-plane”)

x = 0
For I = 1 To 5

Dim Sketch3 As Sketch

Set Sketch3 = Body1.Sketches.Add ( Plane2 )

Dim Factory2D4 As Factory2D

Set Factory2D4 = Sketch3.OpenEdition

Dim Circle2D5 As Circle2D

Set Circle2D5 = Factory2D4.CreateClosedCircle (x, 0.000000,
12.000000)

Dim Point2D6 As Point2D

Set Point2D6 = Factory2D4.CreatePoint( x, 0.000000 )

Sketch3.CloseEdition

Dim Pad7 As Pad

Set Pad7 = PartDocument0.Part.ShapeFactory.AddNewPad ( Sketch3,
10.000000 )

PartDocument0.Part.Update

CATIA.ActiveWindow.ActiveViewer.Reframe
x = x + 25
Next
The second line of the macro begins with a single quote and is a comment which will be dis-
played in the Description area of the Macro dialog box. Then you simply need to initialize a
variable, here x, to allow for the circle center to vary, and create a loop beginning with the
For keyword and ending with the Next keyword. The For keyword specifies the counter
variable I which will take all values between 1 and 5 inclusively. Replace the first coordinate
of the center by x in the CreateClosedCircle method and in the CreatePoint method, and add
a Reframe method to display the whole scene at each step. Then increment the x value to
move the next center of 25mm from the previous one.

23
1

5. Save the macro as MyMacro.

24 Scripting with CATIA Programmer’s Guide

 1

Running the Macro

This task explains how to run the modified macro.

1. Select the Tools->Macro->Mac-

ros... command to display the
Macro dialog box.

2. Your
macro
should be
the cur-
rent one.
You just
have to
click on
Run to
run this
macro.
Here is
the result.

25
1

Invoking CATIA from a Scripting Language

Access to the CATIA object model is provided using scripts in different ways depending on the
operating system and on the applications that can share their own objects with CATIA.

CATIA is an OLE Automation server for Windows NT and allows macro record and replay for both
Windows NT and UNIX. The following summarizes CATIA scripting capabilities.
• With Windows NT:
• In-process access using Visual Basic Scripting Edition since CATIA hosts the Visual Basic
scripting engine
• Out-process access from Visual Basic for Applications via applications like those of Office
• Out-process access from Visual Basic 5 Development Studio
• Out-process access using the Windows Scripting Host and scripting languages such as VB
Script or JScript
• Out-process access from a html page
• Out-process access from a COM application accessing CATIA interfaces through the
Invoke method.
• With UNIX: in-process access using Summit’s Basic Script

The macros recorded from the Tools menu and the Record Macro dialog box use the Visual Basic
language, and not VBScript, to be compatible with Basic Script, allowing macro portability
between UNIX and Windows NT, that is a macro recorded on Windows NT can be replayed on
UNIX or the reverse. This means for example that Dim statements are recorded to declare objects
as returned values of properties or methods.

In-process access means that the script interpretation is performed in the same process as CATIA.
You usually run the macros from the Macros window triggered from the interactive Tools->Mac-
ros command. In this case, the macro is processed by CATIA just like any other command.

Out-process access means that you run the macro from another application running in another pro-
cess. In this case, the macro should first connect to CATIA to then access its data. This connection
starts CATIA if no CATIA process is being running.

You can find information about in-process and out-process access in:
• Running In-process Macros
• Running Out-process Macros

26 Scripting with CATIA Programmer’s Guide

 1

Running In-process Macros

In-process access means that the script interpretation is performed in the same process as CATIA
using the scripting engine(s) hosted by CATIA. You can run in-process macros with UNIX and
Windows NT. You have three means to run in-process macros:
1. You usually run the macros from the Macros window triggered from the interactive Tools-
>Macros command. In this case, the macro is processed by CATIA just like any other com-
mand.
2. You can start CATIA and request that a macro being executed as soon as CATIA is started
using the -macro option followed by the full path of the macro you want to run:

CNEXT -macro e:\Users\Macros\MacroToRun.CATScript

3. You can start CATIA in batch to execute a macro using the -batch option followed by the full
path of the macro you want to run:

CNEXT -batch e:\Users\Macros\BatchMacro.CATScript

27
1

Running Out-process Macros

Out-process access means that you run the macro from another application running in another pro-
cess, such as from Visual Basic for Applications associated with products such as Excel or Word, or
from Microsoft Visual Basic 5 Development Studio. You can also use the Windows Scripting Host
to run VBScript or JScript macros by simply double clicking the macro name from the Windows
desktop or Explorer, or from the command console. You can finally use VBScript or JScript macros
embedded in html pages.
The macro should first connect to CATIA to then access its data. This connection starts CATIA if
no CATIA process is being running. The script is interpreted by the scripting engine hosted by the
application from which you start the macro.

You can run out-process macros with Windows NT only.

Running Out-process Macros from VBA or VB5

This applies for scripts written in Visual Basic only

• If CATIA is already running, the macro should simply connect to CATIA using the GetOb-
ject method

Dim CATIA As Object

Set CATIA = GetObject(, “CATIA.Application”)
The first argument is left blank.
• If CATIA is not already running, the macro should start CATIA using the CreateObject
method

Dim CATIA As Object

Set CATIA = CreateObject(“CATIA.Application”)

Running Out-process Macros Using the Windows Scripting Host

Another way is to use the Windows Scripting Host. This is a language-independent scripting host
which enables scripts written in different languages such as Visual Basic, JScript, and Perl, to be
run from the Windows desktop, the Windows Explorer, or the command console.
• With Visual Basic, your script should begin by the connection to CATIA, using either Cre-
ateObject or GetObject, as follows:

Dim CATIA
Set CATIA = WScript.CreateObject(“CATIA.Application”)
or

Dim CATIA
Set CATIA = WScript.GetObject(“”, “CATIA.Application”)

28 Scripting with CATIA Programmer’s Guide

 1

• With JScript, your script should also begin by the connection to CATIA, using either Cre-
ateObject or GetObject, as follows:

var CATIA
CATIA = WScript.CreateObject(“CATIA.Application”)
or

var CATIA
CATIA = WScript.GetObject(“”, “CATIA.Application”)

Note that the GetObject method requires that its first argument be blank for both Basic Script and
JScript.

To run the macros from the Windows desktop, simply double click on the macro name. These
names are suffixed using vbs for Visual Basic, and with js for JScript.

To run the macros from the command console, use the cscript command as follows:

cscript e:\users\psr\Scripting\Sample\CATIA.js

29
1

Running Out-process Macros from a Dynamic HTML Page

You can also run macros embedded in a html page. These macros can be written in Visual Basic and
JScript. There are several ways of embedding a macro in a html page:
• The macro is written using the script tag and run when the page is loaded
• The macro is written using the script tag and is included or referenced by a form, input, body,
or a (anchor) tag.
• The macro is written using the a tag (anchor) and run as an hyperlink. This is possible with
JScript only.

30 Scripting with CATIA Programmer’s Guide

 1

Object Architecture Overview

You will find in this section how the CATIA exposed objects are described, and get information
about what you
• Object Diagrams shows you how to interpret the object diagrams and the symbols used
• About Objects, Collections, Properties, and Methods helps you understand the basic of the
object technique required by scripting
• About Inheritance and Aggregation describes the two object mechanisms you need to know to
write macros
• Some Tips about Collections gives you tips to handle collections
• Some Tips about SafeArrayVariant give you tips to handle arrays of Variants
• Some Tips about Sub and Function gives you tips to write calls to Sub and Function
• About Numbers, Literals, and Units gives you information on how the numerical values and
their related units can be used
• Adding a Macro as a Command in a Toolbar helps you customize your toolbars with icons to
run your macros.

31
 1

Object Diagrams
This section helps to make you familiar with the diagrams used to describe the objects, their main
properties and methods, and their relationships. The diagrams use the Unified Modeling Language
(UML) notation.

Application
some of the Application
Documents object’s properties
Windows
ActiveDocument ellipsis means that some
ActiveWindow properties are not shown
... Application object’s methods
Help() a collection
Quit() an object This red arrow means
an abstract object
that this terminal object is
1 the root object of another
Documents PartDocument diagram

* Document ProductDocument
1
binary association DrawingDocument Collection
association name
Parent

generalized symbol (inheritance) Object

1
Windows Abstract Object
This red arrow means * Window SpecsAndGeomWindow
that this root object is a Object To Expand
terminal object in one 1
or several diagrams Viewers
Expanded Object
multiplicity items * Viewer Diagram Caption
* means any number

You can learn from the diagram above that the Application object has properties among which four
of them are listed, and exactly two methods. The Application object aggregates two collection
objects, Documents and Windows. The Documents collection aggregates any number of Documents,
since the multiplicity is set to *. The Document object is an abstract object, and only its derived
types can actually be created, that is the PartDocument for Part Design, the ProductDocument for
Assembly Design, and the DrawingDocument for Drafting. The Windows collection aggregates any
number of Windows, which themselves aggregate one Viewers collection which aggregates any
number of Viewers. The binary association between the Window and the Document objects means
that the Document object is the parent of the Window object. Other associations without name are
aggregations.

The symbol shows that the object to which it refers, that is the object located just left of the sym-
bol, is the root of an object structure expanded in another object diagram. The symbol shows
that the root object near it can be found in one or several object diagrams as an object to expand.

32 Scripting with CATIA Programmer’s Guide

 1

About Objects, Collections, Properties, and Methods

Scripting languages such as Visual Basic rely on objects. Most pieces of data you can access are
objects. With CATIA, documents, windows, viewers, cameras, parts, sketches, pads, even lines and
curves, are represented as objects in Visual Basic. An object is depicted using a blue box in the
object diagrams, such as Object .

A collection is an object that contains other objects. Like with stamps collecting, where all objects
in the collection are stamps, a collection contains usually objects of the same type. For example a
document collection contains documents. A collection is always denoted as a plural name to help
easily recognize a collection among other objects. The document collection is thus named Docu-
ments. A collection is depicted using a yellow box in the object diagrams, such as Documents .
The collection index begins at 1, and not 0. Usually, an object in the collection is reached using its
index, but it can also be reached using the name you assign to it. This ability of referring to an
object using its name in the collection is stated in the documentation of each collection object, such
as Documents, when the index type is Variant, for example in the Item method.

A property is part of an object and helps to characterize it. For example, the Document object has
the FullName property, which stores its full name, that is the file name that contains the document
and the path to access this file. Retrieving property values of an object makes it possible to distin-
guish it among other objects of the same type. Modifying property values of an object changes the
object characteristics and implies that the object itself is thus modified. To prevent from non-
desired property modifications, an object can have read-only properties from which you can
retrieve their values, but never set them.

To retrieve or set the value of a property of a given object, write the object reference followed by a
period and the property name. For example, you can set the DocName variable with the full name
of the active document as follows:

DocName = CATIA.ActiveDocument.FullName

An object reference always starts from the root object, that is the application object which is always
set to CATIA with in-process access. Then you use the Application object’s properties to access the
objects. In this case, the application object has the ActiveDocument property which holds the
active document. You simply need to write CATIA.ActiveDocument to refer to the active doc-
ument. Then the Document object has the FullName property to hold its full name. Simply add a
period followed by FullName, and you get this full name.

In the same way, you can request to see the hidden elements of the active document by setting the
value of its SeeHiddenElements property to True, as follows:

CATIA.ActiveDocument.SeeHiddenElements = True

A method is an action that you can request an object to do. For example, you can request to save the
active document. To do this, the Document object includes the Save method. Simply request the
document to save itself as follows:

CATIA.ActiveDocument.Save

33
1

Methods have often arguments requested by the action. For example, the SaveAs method carries
out the action of saving a document with another name than the current one. This new name must
be provided to perform this action, otherwise the SaveAs method cannot work. This name is
passed as an argument of the SaveAs method. To save the active document with the name
NewName, proceed as follows:

CATIA.ActiveDocument.SaveAs “NewName”
You will find in the object reference that each method is qualified as either a Function or a Sub,
and with parentheses, even if they have no arguments, as follows:

Function NewCamera() As Camera

Sub Update()

This is a Visual Basic notation to distinguish a method that returns a value, or Function, from one
that don’t, or Sub. Note that the returned value of a Function is indicated using the As keyword.
In the example above, the NewCamera method is a Function because it returns a Camera
object. See also Some Tips about Sub and Function to know more about Sub and Function.

34 Scripting with CATIA Programmer’s Guide

 1

About Inheritance and Aggregation

Inheritance and aggregation are the two main relationship kinds between objects.

An object that inherits from another, named the AnyObject object, inherits the properties and the
methods of this AnyObject object and adds them to its own properties and methods. Inheritance
helps to specialize objects while gathering common properties and methods in the AnyObject
object. Inheritance is a iterative process, since an object can inherit from an object which itself
inherits from another object which itself inherits, and so forth, and the lowest object in the inherit-
ance tree inherits the properties and methods of all the objects above it. Inheritance is depicted
using the following symbol or in the object diagrams.

In the following diagram, the PartDocument object is a specialized document that is dedicated to
parts, and which inherits the properties and methods of the Document object. In addition, the Part-
Document object has its own properties and methods. For example, PartDocument inherits the Save
method from Document, like ProductDocument and DrawingDocument, and owns the PartNum-
ber property, which is a specific property for a part, but which does not make sense for Document.

Collection
Application PartDocument Object
1 PartNumber
Documents ...
Abstract Object
* Document ProductDocument
Object To Expand
Save()
... DrawingDocument
Expanded Object

Assume that MyPart is a PartDocument document and is the active document. You can write the
following to set its part number, and then save it:

MyPart.PartNumber = “123456789-0”
MyPart.Save()

In this example, the value of the PartNumber property owned by MyPart as a PartDocument
document is modified, and then the Save method of the Document object is executed against
MyPart.

Some objects are depicted with a blue box with an italic typeface, such as Document . These
are abstract objects. An abstract object owns properties and methods like any other object, but it
cannot be created. Only objects which inherits from it and which are not abstract objects can be cre-
ated. For example, the Document object is an abstract object which owns properties and methods
shared by all documents, but cannot be created as such. Only objects of types PartDocument, Pro-
ductDocument, and DrawingDocument which inherit from it can actually be created. The active doc-
ument referred to in the examples given in About Objects, Collections, Properties, and Methods is
necessarily an instance of one of these three types.

35
1

Aggregation is the ability of an object to contain another one. For example, the Application object
contains (aggregates) a Documents collection object. With CATIA, the aggregation of a series of
objects of the same type is usually reserved to collection objects. For example, the Documents col-
lections contains (aggregates) a series of Documents, each of them being a PartDocument, a Pro-
ductDocument or a DrawingDocument object. Aggregation is depicted using a line between the two
objects, and the number of contained objects (multiplicity). For example, Application contains one
Documents collection, which can itself contain any number of Documents, since the * symbol is
used.

36 Scripting with CATIA Programmer’s Guide

 1

Some Tips about Collections

You will find below some tips to retrieve objects in collections.

An item is retrieved from the collection using the Item method and the index of the item in the col-
lection. Usually, the argument representing the index in the Item method is a Variant. This means
that it can either represent the rank of the item in the collection or the name you assigned to this
item using the Name property. The rank in a collection begins at 1. For example, assume that the
document named MyDocument is the sixth document in the Documents collection. To retrieve this
document in the Doc variable, write:

Dim Doc As Document

Set Doc = CATIA.Documents.Item(6)

or write:

Dim Doc As Document

Set Doc = CATIA.Documents.Item(“MyDocument”)

Each collection has a Count property that holds the number of items in the collection. This is a
handy property to scan the whole collection. For example, to print the name of each document in
the collection in a message box, write:

For I = 1 To CATIA.Documents.Count
msgbox CATIA.Documents.Item(I).Name
Next

or write:

I = 0
Do
I = I + 1
msgbox CATIA.Documents.Item(I).Name
Loop Until I = CATIA.Documents.Count

or you can use the For Each instruction to scan the collection, and get rid of the counter:

For Each Doc In CATIA.Documents

msgbox Doc.Name
Next

In this case, the Doc variable is reinitialized using the current document, starting with the first one
and ending with the last one.

37
1

Some Tips about SafeArrayVariant

Many methods which return a value do not return a single value, but an array of values. For exam-
ple, the GetOrigin property of the Viewpoint3D object returns a 3D point as an array of three
coordinates. This array is returned as an output argument. You can retrieve in the MyVPOrigin
variable the origin of the 3D viewpoint of the active viewer in the active window as follows:

Dim MyVPOrigin
ReDim MyVPOrigin(2)
CATIA.ActiveWindow.ActiveViewer.Viewpoint3D.GetOrigin MyVPOrigin

You should first declare the array using the Dim statement and assign a size to the array using the
ReDim statement, and then call the GetOrigin method. Assigning a size of 2 allocates an array con-
taining three values.

To access each coordinate, you need to go deeper:

• The x coordinate is in MyVPOrigin(0)
• The y coordinate is in MyVPOrigin(1)
• The z coordinate is in MyVPOrigin(2)

Contrary to collections, a SafeArrayVariant’s index begins at 0. To set a new triplet of values, you
can write:

MyVPOrigin = Array(150, 200, 50)

CATIA.ActiveWindow.ActiveViewer.Viewpoint3D.GetOrigin MyVPOrigin

or

CATIA.ActiveWindow.ActiveViewer.Viewpoint3D.GetOrigin Array(150, 200, 50)

But to modify the y coordinate only, write:

MyVPOrigin(1) = 200
CATIA.ActiveWindow.ActiveViewer.Viewpoint3D.GetOrigin MyVPOrigin

When you don’t know the size of an array, use the UBound property. It returns the rank of the high-
est element in the array. For example the following example returns 2 in Highestrank:

Highestrank = MyVPOrigin.UBound

38 Scripting with CATIA Programmer’s Guide

 1

Some Tips about Sub and Function

A method exposed by an objects is called by Visual Basic:
• a Sub if it doesn’t return any value
• a Function if its does.

Be careful when the methods requests arguments. To pass arguments to a Sub with Visual Basic
Script, do not use parentheses as follows:

Object.Sub arg1, arg2, arg3

But use parentheses with a Function:

Dim ReturnedObject As AnyObject

Set ReturnedObject = Object.Function (arg1, arg2, arg3)

You must use Dim and Set only if the returned value is an object, but not if it is a character string
or a number. Nevertheless, character string and number defined as CATIA literals are objects and
Set must be used if a Function returns a literal object.

39
1

About Numbers, Literals, and Units

Numerical values stored and internally handled for computations are expressed using the MKSA
unit system. Nevertheless, the user interface can be set to display and get values from the end user
according to another unit system which better match your needs or habits.

The parameter values you can set using macros must be expressed using the MKSA unit system,
since the user interface filter does not exist when you run macros. This also ensures your macros
portability. There is one exception: the literals.
Literals are specific objects that represent a parameter with a given type. For example, the Length
object is dedicated to store a length, but its state of object brings more that the simple value storage.
The Length object derives from the Dimension object, and thus inherits from it the Valuate-
FromString method. This method allows the value stored in the Length object to be valuated
using a figure and a unit. For example, valuate the radius of a face fillet using the Radius property
of the FaceFillet object which aggregates a Length object to store this radius:

MyFaceFillet.Radius.ValuateFromString(“5.08mm”)

The character string is interpreted as a value of 5.08 expressed in mm. You can enter a decimal
value since the Dimension object derives from the RealParam object which allows for real values to
be set. You may want to enter inches instead. Simply write:
MyHole.Diameter.ValuateFromString(“2in”)

The available unit symbols you can use are those listed in the Units tab-page of the Tools-
>Options menu. The RealParam and the IntParam objects provide to their derived objects the
Value method which sets or returns the value expressed in the MKSA unit system, except for
length expressed in millimeters and angles expressed in decimal degrees.

40 Scripting with CATIA Programmer’s Guide

 1

Adding a Macro as a Command in a Toolbar

You can easily customize your toolbars by adding icons to trigger your favorite macros. This
reduces the macro access time for the macros you often run.
This task explains how to add a macro as a command in a toolbar.

1. Select the Tools->Macro->Mac-

ros... command to display the
Macro dialog box, and select the
macro you want to add to make
sure that the directory path of the
file containing the requested
macro is concatenated with those
recognized by CATIA. Then click
Cancel

2. Select
Tools-
>Cus-
tomize,
then the
Com-
mands
tab, and
Macros.
Drag the
macro
name to
the tool-
bar you
wish. The
default
icon
is used

41
1

3. To select
another
icon than
the
default
one, click
Show
Proper-
ties, and
browse
the cur-
rently
used
icons by
clicking

.
Select the
appropri-
ate icon
and drag
the
macro
name.

4. You can also use the icon browser

by clicking .

42 Scripting with CATIA Programmer’s Guide

Scripting with Infrastructure
2
This part contains information about the objects shared by all applications, and their relationships.
Basic programming tasks common to all applications are also included.
• Infrastructure Object Architecture
• Programming Tasks and Scenarios.

43
2

Infrastructure Object Architecture

The objects that are common to all CATIA products are shown on the following diagram:

Application Collection
1
Documents PartDocument Object

* Document ProductDocument Abstract Object

1
DrawingDocument Object To Expand
1
Selection Expanded Object
Parent

1 Camera2D
Cameras
1
* Camera Viewpoint2D

Camera3D
1
1 Viewpoint3D
Windows

* Window SpecsAndGeomWindow
1
Viewers Viewer2D SpecsViewer
1
* Viewer Viewpoint2D

Viewer3D
1
Viewpoint3D
1
SystemService
1
LightSources

* LightSource

These objects are shared by all CATIA products. The root object is the Application, which aggre-
gates, or includes, Documents, a Document collection, and Windows, a Window collection. A collec-
tion is an object that gathers objects of the same type and is denoted as a plural name. Documents
gathers Document objects and provides methods for managing individual documents in the collec-
tion.The documents belong to one of the three types, that is the PartDocument, the ProductDocu-
ment, and the DrawingDocument. Windows gathers Window objects, and provides methods for
managing individual windows in the collection.

44 Scripting with CATIA Programmer’s Guide

 2

In addition to this functional view, we can superimpose another view to help understand some basic
mechanisms:

Collection AnyObject Collection

Application Application
Name Name Object
Parent Parent
Count Abstract Object
Application
Documents Object To Expand
Document
Windows Expanded Object
Camera
Viewers
Window
Cameras
Viewer
LightSources
SystemService

Selection

LightSource

Viewpoint2D

Viewpoint3D

All objects, and not only those shown in this diagram, except collections, derive from the AnyObject
abstract object which supplies the Application, Name, and Parent properties. You can then use
these properties and this method against any object, since any object features them. All collections
derive from the Collection abstract object which supplies in addition the Count property.

The Application property returns the application to which an object belongs. When running in-pro-
cess macros, there is only one application named CATIA. The Name properties allows any object to
be assigned a name. The Parent property allows the parent object to be retrieved, the parent object
being the object which aggregates the current one. The Count property of the Collection object
returns the number of items in the collection. In addition, a Collection object can supply an Item, an
Add, and a Remove method.

45
2

Application

Application Collection
Documents
Windows Object
ActiveDocument
ActiveWindow Abstract Object
...
Help() Object To Expand
Quit()
1 Expanded Object
Documents
1
Windows
1
SystemService

The root object for all CATIA macros is Application. This corresponds to the CATIA frame win-
dow. The CATIA application is always named CATIA for in-process access, and you should only
refer to it since it already exists when you run an in-process macro. The application aggregates, or
includes, a document collection accessed using the Documents property, and a window collection
accessed using the Windows property. The document collection stores the currently opened docu-
ments and the window collection stores the currently opened windows for these documents. The
active document is the document opened in the active window, that is the window in which the end-
user is currently working. They are accessed using the ActiveDocument and the ActiveWindow
properties respectively.

The Application object has other properties, such as FileSearchOrder which allows a pathname
concatenation searched for when opening files to be set or retrieved. As the application represents
the frame window, you can set the frame dimensions and location using the properties Width,
Height, Left and Top respectively, with values expressed in screen pixels.

The Application object aggregates also a SystemService object which provides the Environ method
to get the value of a given environment variable.

46 Scripting with CATIA Programmer’s Guide

 2

Documents

Documents
Collection
Add()
Item() Object
Open() PartDocument
Abstract Object
* Document ProductDocument
Selection Object To Expand
Cameras Drawing
... Expanded Object
Activate()
Close()
NewWindow()
Save()
SaveAs()
1
Selection
1
Cameras

The Document is the object which stores your application data on disk. A document is either created
empty using the File->New command or using the Add method of the Documents collection, or
opened from a file using the File->Open command or using the Open method of the Documents
collection. CATIA provides access to three document types: the PartDocument, the ProductDocu-
ment, and the DrawingDocument. The Document abstract object gathers the properties and methods
common to all actual document types. When a document is created or opened, it is automatically
set as the active document and displayed in a window which automatically becomes the active win-
dow. A document aggregates the current object or set of objects in the Selection object, and Cam-
eras, a camera collection.

47
2

Windows

Windows Collection
Arrange()
Item() Object

* Window SpecsAndGeomWindow Abstract Object

Viewers Object To Expand

ActiveViewer
...
Expanded Object
Activate()
Close()
NewWindow()
PrintOut()
PrintToFile()
...
1
Viewers

The Windows collection gathers Window objects which make the link with the windowing system
and display documents in a viewable form, mainly in 3D or 2D modes, or as a specification tree in
graph or tree mode. Windows in a collection can be arranged in the frame. A Viewers collection
enables the window to display the application data in the appropriate modes using viewers. A Spec-
sAndGeomWindow object features altogether a 2D or a 3D viewer and a specification tree viewer. A
window can be activated, that is becomes the active one, using the Activate method. This implies
that the document displayed is this window is also activated if it was not, and that subsequent inter-
actions will affect it until another window is activated instead. The Viewers property returns the
aggregated Viewers collection, and the ActiveViewer property returns the active viewer in the
window.

48 Scripting with CATIA Programmer’s Guide

 2

Viewers and Viewpoints

Viewers Viewer2D SpecsViewer

Viewpoint2D Layout
Item()
1
* Viewpoint2D
Viewer
Zoom Collection
FullScreen
Width GetOrigin()
Height PutOrigin() Object
Activate()
CaptureToFile() Viewer3D Abstract Object
Reframe() Viewpoint3D
Update() LightSources Object To Expand
ZoomIn() NearLimit
ZoomOut() FarLimit Expanded Object
NewCamera() ...
GetBackgroundColor()
PutBackgroundColor() 1
Viewpoint3D
Zoom
ProjectionMode
FocusDistance
FieldOfView
GetOrigin()
PutOrigin()
GetSightDirection()
PutSightDirection()
GetUpDirection()
PutUpDirection()

1
LightSources
Item()
Add()
Remove()

* LightSource
GetDirection()
PutDirection()

A Viewer is used to display a document according to a given viewpoint and display options.
Depending on the document type, the following viewers can be found in a window:
• PartDocument: a Viewer3D for the part 3D objects and/or a SpecsViewer for the part specifica-
tion tree
• ProductDocument: a Viewer3D for the assembly 3D objects and/or a SpecsViewer for the
assembly specification tree

49
2

• DrawingDocument: a Viewer2D for the drawing sheets and/or a SpecsViewer for the drawing
specification tree.

When the window displays both a Viewer3D and a SpecsViewer, or one or several Viewer2Ds and a
SpecsViewer, it is a SpecsAndGeomWindow. You can activate a given viewer in a multi-viewer win-
dow, fit all the scene in the viewer, update the display, zoom in and out, and capture the contents of
the viewer as an image file.
Display options depend on the viewer type. All viewers share display options such as the back-
ground color and the display on the whole screen or in a smaller window. In addition, Viewer3Ds
allow for different lighting modes and for modifying lighting intensity, and for depth effects, navi-
gation styles, rendering modes, and clipping modes.

A viewpoint holds complementary data for viewers. A Viewpoint2D defines the origin of the scene
to display, expressed in model units, and a zoom factor to apply for display. A Viewpoint3D holds in
addition the sight and up directions, the target, the field of view, and projection modes.

UpDirection

SightDirection
Origin
FieldOfView Target
NearLimit
FocusDistance

FarLimit

50 Scripting with CATIA Programmer’s Guide

 2

Cameras

Cameras Camera2D Collection

Item() Viewpoint2D
Remove() Object
1
Viewpoint2D
* Camera Zoom
Abstract Object

Type GetOrigin() Object To Expand

PutOrigin()

Expanded Object
Camera3D
Viewpoint3D
1
Viewpoint3D
Zoom
ProjectionMode
FocusDistance
FieldOfView
GetOrigin()
PutOrigin()
GetSightDirection()
PutSightDirection()
GetUpDirection()
PutUpDirection()

A Camera is the persistent form of a viewpoint. You can create a camera from the current viewpoint
using the NewCamera method of the Viewer object. The camera name is assigned by CATIA:
Camera00, Camera01, and so forth, and the created camera is placed at the end of the camera col-
lection of the active document and is displayed in the Named Views dialog box of the View menu.
You can rename the cameras you create with your own names using the Name property. A created
camera can then be assigned to a viewer to make its own viewpoint change to this of the camera.
Two kinds of cameras exist: the Camera2D for 2D viewpoints, that is for DrawingDocument
objects, and the Camera3D for 3D viewpoints representing the real world, that is for PartDocument
and ProductDocument objects. A Camera2D stores a Viewpoint2D object and a Camera3D stores a
Viewpoint3D object.

51
2

Programming Tasks and Scenarios

The programming tasks and scenarios supplied here help you understand how to create macros that
you can run inside CATIA or from another application, and using which macro programming lan-
guage and environment. The scenarios covered are the following:

Scenarios Language and Environment

Creating a New Document VB Script or Basic Script

Opening a Document VB Script or Basic Script

Closing a Document VB Script or Basic Script

Saving a Document VB Script or Basic Script

Saving As a Document VB Script or Basic Script

Setting the Application’s Window Dimensions and VB Script or Basic Script

Location

Opening a Document and Printing it on the Default VB Script or Basic Script

Printer

Creating a New Document, Saving and Closing It VB Script or Basic Script

Using Cameras VB Script or Basic Script

Modifying the Characteristics of a Viewpoint3D VB Script or Basic Script

52 Scripting with CATIA Programmer’s Guide

 2

Creating a New Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a new document. It is the programming equivalent of the File-
>New command.
To address the application from an in-process macro, use the name CATIA.

1. Declare the language to use

Language = “VBScript”

2. Create the new document. To do this, use the Add method of the Documents collection which
creates the document and adds it as the last item of the collection. You must specify its type.
It can be a part, an assembly, or a drawing. Use then Part, Product, or Drawing type
respectively as argument of the Add method.

Dim NewDocument As Document

Set NewDocument = CATIA.Documents.Add(“Part”)

This single statement creates a new part document that can be further referenced using the
NewDocument variable, adds it to the Documents collection, creates and displays a window
for this document, and makes it the active document and its window the active window.

The resulting macro is as follows.

Language = “VBScript”
Dim NewDocument As Document
Set NewDocument = CATIA.Documents.Add(“Part”)

This example uses the Add method of the Documents collection.

53
2

Opening a Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to open a document. It is the programming equivalent of the File->Open
command.
To address the application from an in-process macro, use the name CATIA.

1. Declare the language to use

Language = “VBScript”

2. Open the document. To do this, use the Open method of the Documents collection which
opens a document given its full pathname and adds it as the last item of the collection.

Dim Doc As Document

Set Doc = CATIA.Documents.Open(“e:\Parts\DocumentToOpen.CATPart”)

This single statement opens the document stored in the file whose pathname is e:\Parts\Doc-
umentToOpen.CATPart that can be further referenced using the Doc variable, adds it to the
Documents collection, creates and displays a window for this document, and makes it the
active document and its window the active window.

The resulting macro is as follows.

Language = “VBScript”
Dim Doc As Document
Set Doc = CATIA.Documents.Open(“e:\Parts\DocumentToOpen.CATPart”)

This example uses the Open method of the Documents collection.

54 Scripting with CATIA Programmer’s Guide

 2

Closing a Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to close a document. It is the programming equivalent of the File->Close
command.
To address the application from an in-process macro, use the name CATIA.

1. Declare the language to use

Language = “VBScript”

2. Close the document. To do this, use the Close method of the Document object. To close a
document, you need to designate it. Use one of the three following ways:
a. The document to be closed is the active one. Use the ActiveDocument property of the
CATIA application

CATIA.ActiveDocument.Close()

b. You already assigned a variable to handle the document. Assume this variable is Doc.
You simply use this variable

Doc.Close()

c. You have assigned a name to the document using the Name property. You can retrieve
this document from the document collection using the Item method with the name you
assigned as argument

CATIA.Documents.Item(“TheNameIAssignedToTheDocument”).Close()

You could also replace the name by the rank of the document in the collection.
Each of these statements closes the designated document. This means that the document is
removed from the Documents collection, and that all the windows that contain it are also
closed and removed from the Windows collection.

If the document has been modified and thus needs to be saved, a prompt is issued before closing and
freezes the macro, requesting a user input to save or not the document. To prevent from this, save the
document beforehand, or test if the document needs to be saved using the Saved property of the Docu-
ment object and save it if appropriate. To close a document even if it needs to be saved without saving
it, set the DisplayFileAlerts property of the Application object to False. This prevents from issuing the
saving prompt. Setting DisplayFileAlerts to False make the macro strictly apply the method, such as
Close closes and doesn’t save, Save overwrites the existing document, and so on.

55
2

The resulting macro is as follows.

Language = “VBScript”
‘Use one of the following statements
CATIA.ActiveDocument.Close()
Doc.Close()
CATIA.Documents.Item(“TheNameIAssignedToTheDocument”).Close()

This example uses the Close method of the Document object, the ActiveDocument and the
Documents properties of the Application object, and the Item method of the Documents collec-
tion.

56 Scripting with CATIA Programmer’s Guide

 2

Saving a Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to save a document. It is the programming equivalent of the File->Save
command.

To address the application from an in-process macro, use the name CATIA.

1. Declare the language to use

Language = “VBScript”

2. Save the document. To do this, use the Save method of the Document object. To save a doc-
ument, you need to designate it. Use one of the three following ways:
a. The document to be saved is the active one. Use the ActiveDocument property of the
CATIA application

CATIA.ActiveDocument.Save()

b. You already assigned a variable to handle the document. Assume this variable is Doc.
You simply use this variable

Doc.Save()

c. You have assigned a name to the document using the Name property. You can retrieve
this document from the document collection using the Item method with the name you
assigned as argument

CATIA.Documents.Item(“TheNameIAssignedToTheDocument”).Save()

You could also replace the name by the rank of the document in the collection.
Each of these statements saves the designated document. If the document was newly created
and was never saved, use the SaveAs method instead. This is detailed in Saving As a Docu-
ment.

The resulting macro is as follows.

Language = “VBScript”
‘Use one of the following statements
CATIA.ActiveDocument.Save()
Doc.Save()
CATIA.Documents.Item(“TheNameIAssignedToTheDocument”).Save()

This example uses the Save method of the Document object, the ActiveDocument and the
Documents property of the Application object, and the Item method of the Documents collec-
tion.

57
2

58 Scripting with CATIA Programmer’s Guide

 2

Saving As a Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to save the active document with a new name or location. It is the program-
ming equivalent of the File->SaveAs command.
To address the application from an in-process macro, use the name CATIA.

1. Declare the language to use

Language = “VBScript”

2. Save the active document with a new name. To do this, use the SaveAs method of the Docu-
ment object. To save a document, you need to designate it. Use one of the three following
ways:
a. The document to be saved is the active one. Use the ActiveDocument property of the
CATIA application

CATIA.ActiveDocument.SaveAs(“e:\Users\Part\NewName.CATPart”)

b. You already assigned a variable to handle the document. Assume this variable is Doc.
You simply use this variable

Doc.SaveAs(“e:\Users\Part\NewName.CATPart”)

c. You have assigned a name to the document using the Name property. You can retrieve
this document from the document collection using the Item method with the name you
assigned as argument

CATIA.Documents.Item(“TheNameIAssignedToTheDocu-
ment”).SaveAs(“e:\Users\Part\NewName.CATPart”)

You could also replace the name by the rank of the document in the collection.
Each of these statements saves the designated document in specified the folder with the
NewName name.

The resulting macro is as follows.

Language = “VBScript”
‘Use one of the following statements
CATIA.ActiveDocument.SaveAs(“e:\Users\Part\NewName.CATPart”)
Doc.SaveAs(“e:\Users\Part\NewName.CATPart”)
CATIA.Documents.Item(“TheNameIAssignedToTheDocu-
ment”).SaveAs(“e:\Users\Part\NewName.CATPart”)

59
2

This example uses the SaveAs method of the Document object, the ActiveDocument and the
Documents property of the Application object, and the Item method of the Documents collec-
tion.

60 Scripting with CATIA Programmer’s Guide

 2

Setting the Application’s Window Dimensions and Location

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to set the frame window size and location. It is the programming equivalent
of interactions you perform with the mouse by dragging a side of the window to extend or reduce
it, or by dragging the window top strip to move it.
To address the application from an in-process macro, use the name CATIA. Values are expressed
in screen pixels. The window location is determined by the location of its upper left corner, and
the origin is located at the screen upper left corner.

1. Declare the language to use

Language = “VBScript”

2. Set the window width to 500 pixels and the window height to 400 pixels

CATIA.Width = 500
CATIA.Height = 400

3. Set the window location at point (150, 50)

CATIA.Left = 150
CATIA.Top = 50

The resulting macro is as follows.

Language = “VBScript”
CATIA.Width = 500
CATIA.Height = 400
CATIA.Left = 150
CATIA.Top = 50

This example uses the Width, Height, Left and Top properties of the Application object.

61
2

Opening a Document and Printing it on the Default Printer

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to open a part and print it on the default printer. It is the programming
equivalent of File->Open plus Immediate Print
You need to know the part name you want to print, and have a default printer defined. We assume
here to print the part named PartToPrint contained in e:\Parts

1. Declare the language to use

Language = “VBScript”

2. Open the PartToPrint part you want as the current document

Dim Doc As Document

Set Doc = CATIA.Documents.Open(“e:\Parts\PartToPrint.CATPart”)

As soon as the part is opened, it is automatically set as the active document and displayed in
the active window. This active window is stored as a property of the application, named
ActiveWindow.

3. Request printing the part, that is the active window contents, on the default printer

CATIA.ActiveWindow.PrintOut()

4. Close the active document.

CATIA.ActiveDocument.Close()

The resulting macro is as follows.

Language = “VBScript”
Dim Doc As Document
Set Doc = CATIA.Documents.Open(“e:\Parts\PartToPrint.CATPart”)
CATIA.ActiveWindow.PrintOut()
CATIA.ActiveDocument.Close()

This example uses the Open method of the Documents collection object, the PrintOut method
of the Window object, and the ActiveWindow and ActiveDocument properties of the Applica-
tion object.

62 Scripting with CATIA Programmer’s Guide

 2

Creating a New Document, Saving and Closing It

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a new part, save it with a given name, get some of its properties,
and close it. It is the programming equivalent of File->New , File->SaveAs , and File-
>Close .
We assume here to save the part we name PartToSave in e:\Parts

1. Declare the language to use

Language = “VBScript”

2. Create the part:

CATIA.Documents.Add(“Part”)
As soon as the part is created, it is automatically set as the active document and displayed in
the active window. This active window is stored as a property of the application, named
ActiveWindow.

3. Query if the part needs to be saved and save it if necessary to the disk file Part-
ToSave.CATPart.

If (CATIA.ActiveDocument.Saved)
CATIA.ActiveDocument.SaveAs(“e:\Parts\PartToSave.CATPart”)
End If

4. Retrieve the document fullname and print it in a message box

msgbox CATIA.ActiveDocument.FullName, vbOKOnly

5. Retrieve the document path and print it in a message box

msgbox CATIA.ActiveDocument.Path, vbOKOnly

6. Retrieve whether or not the document is read only and print it in a message box

msgbox CATIA.ActiveDocument.ReadOnly, vbOKOnly

7. Close the document

CATIA.ActiveDocument.Close()

63
2

The resulting macro is as follows.

Language = “VBScript”
CATIA.Documents.Add(“Part”)
If (CATIA.ActiveDocument.Saved) Then
CATIA.ActiveDocument.SaveAs(“e:\Parts\PartToSave.CATPart”)
End If
msgbox CATIA.ActiveDocument.FullName, vbOKOnly
msgbox CATIA.ActiveDocument.Path, vbOKOnly
msgbox CATIA.ActiveDocument.ReadOnly, vbOKOnly
CATIA.ActiveDocument.Close()

This example uses the Add method of the Documents collection object, the ActiveDocument
properties of the Application object, the Saved, FullName, Path, and ReadOnly properties,
and the SaveAs, and Close methods of the Document object.

64 Scripting with CATIA Programmer’s Guide

 2

Using Cameras

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to open a part, save the active viewpoint, and display the part according to
the viewpoints stored in the provided cameras, then restore the stored viewpoint. It is the pro-
gramming equivalent of File->Open plus View->Named Views, and successively selecting
the supplied cameras and applying their viewpoints from the corresponding dialog box.

You need to know the part name you want to open. We assume here that the part is named
MyPart.CATPart and is contained in e:\Parts

1. Declare the language to use

Language = “VBScript”

2. Open the MyPart part you want as the current document

Dim MyDoc As Document

Set MyDoc = CATIA.Documents.Open(“e:\Parts\MyPart.CATPart”)
As soon as the part is opened, it is automatically set as the active document and displayed in
the active window. This active window is stored as a property of the application, named
ActiveWindow.
Dim MyViewer As Viewer
Set MyViewer = CATIA.ActiveWindow.ActiveViewer

3. Save the active viewpoint as a camera

MyViewer.NewCamera()
The camera created is named camera000 by default, if no other camera was created before.
You can rename it:
MyDoc.Cameras.Item(“camera000”).Name = “MyCamera“

4. Apply the different cameras. This consists in successively assigning the cameras’ 3D view-
points to this of the active viewer

MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* iso”).Viewpoint3D

MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* front”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* back”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* top”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* bottom”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* left”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* right”).Viewpoint3D

5. Restore the stored viewpoint

MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“MyCamera”).Viewpoint3D

65
2

The resulting macro is as follows.

Language = “VBScript”
Dim MyDoc As Document
Set MyDoc = CATIA.Documents.Open(“e:\Parts\MyPart.CATPart”)
Dim MyViewer As Viewer
Set MyViewer = CATIA.ActiveWindow.ActiveViewer
MyViewer.NewCamera()
MyDoc.Cameras.Item(“camera000”).Name = “MyCamera“
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* iso”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* front”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* back”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* top”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* bottom”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* left”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“* right”).Viewpoint3D
MyViewer.Viewpoint3D = MyDoc.Cameras.Item(“MyCamera”).Viewpoint3D

This example uses the Open method of the Documents collection object, the ActiveWindow and
ActiveDocument properties of the Application object, the NewCamera method of the Viewer
object, the Viewpoint3D property of the Viewer3D object, and the Item method of the Cameras
collection object.

66 Scripting with CATIA Programmer’s Guide

 2

Modifying the Characteristics of a Viewpoint3D

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to open a part, and modify the different characteristics of the 3D viewpoint,
that is the origin, the sight direction, and the up direction. It is the programming equivalent of
File->Open plus the programming equivalent of interactions you perform with the mouse by
zooming, panning, and rotating, and/or modifying the viewpoint by using View->Modify.

You need to know the part name you want to print. We assume here that the part is named
MyPart.CATPart and is contained in e:\Parts

1. Declare the language to use

Language = “VBScript”

2. Open the MyPart part you want as the current document

Dim MyDoc As Document

Set MyDoc = CATIA.Documents.Open(“e:\Parts\MyPart.CATPart”)
As soon as the part is opened, it is automatically set as the active document and displayed in
the active window. The 3D viewpoint of the active viewer of this active window is referred to
in the VP variable.
Dim VP As Viewpoint3D
Set VP = CATIA.ActiveWindow.ActiveViewer.ViewPoint3D

3. Set new values for the origin coordinates

VP.PutOrigin Array(200., 0., 0.)

At this stage, the viewpoint origin has changed, but not the display. To take the modification
into account, the Update method should be executed against the active viewer.
CATIA.ActiveWindow.ActiveViewer.Update()

4. Set new values for the up direction components

VP.PutUpDirection Array(0., 0., 1.)

Execute the Update method against the active viewer to update the display
CATIA.ActiveWindow.ActiveViewer.Update()

5. Set new values for the sight direction components

VP.PutSightDirection Array(0., -1., 0.)

Execute the Update method against the active viewer to update the display
CATIA.ActiveWindow.ActiveViewer.Update()

67
2

The resulting macro is as follows.

Language = “VBScript”
Dim MyDoc As Document
Set MyDoc = CATIA.Documents.Open(“e:\Parts\MyPart.CATPart”)
Dim VP As Viewpoint3D
Set VP = CATIA.ActiveWindow.ActiveViewer.Viewpoint3D
VP.PutOrigin Array(200., 0., 0.)
CATIA.ActiveWindow.ActiveViewer.Update()
VP.PutUpDirection Array(0., 0., 1.)
CATIA.ActiveWindow.ActiveViewer.Update()
VP.PutSightDirection Array(0., -1., 0.)
CATIA.ActiveWindow.ActiveViewer.Update()

This example uses the Open method of the Documents collection object, the ActiveWindow and
ActiveDocument properties of the Application object, the PutOrigin, PutUpDirection, and
PutSightDirection properties of the Viewpoint3D object, the Viewpoint3D property and the
Update method of the Viewer3D object, this method being inherited from the Viewer object.

68 Scripting with CATIA Programmer’s Guide

Scripting with Part Design
3
This part contains information about the Part Design objects, and their relationships. Basic pro-
gramming tasks for Part Design are also included.
• Part Design Object Architecture
• Programming Tasks and Scenarios.

69
3

Part Design Object Architecture

The Part Design main objects are shown on the following diagram:

PartDocument Collection
1 CurrentShape
Part CurrentBody Object
XYPlane 1
1 YZPlane 1 Abstract Object
OriginElements ZXPlane 1 Plane
1 Object To Expand
GeometricElements

* Expanded Object
GeometricElement
1 MainBody
Bodies
1
* Body
1

1
Sketches

* Sketch
1
Shapes
1
* Shape
1
Constraints

* Constraint
1
Relations

* Relation
1
Parameters

* Parameter
1
Factory3D
1
ShapeFactory

70 Scripting with CATIA Programmer’s Guide

 3

The PartDocument object aggregates, or includes, the part tree structure starting with the Part
object located at the top of the part specification tree. Among these objects, we find first objects and
collections you can also find in the part specification tree. These objects are:
• the three planes XY, YZ, and ZX you can retrieve from the OriginElement object using the
Part’s OriginElement property
• the 3D elements you can create as reference to position your 3D objects and stored in a Geo-
metricElements collection you can retrieve using the GeometricElements property
• the bodies you create, starting with the main body and stored in the Bodies collection you can
retireve using the Part’s Bodies property. These bodies contains the part’s geometry

In addition, the Part object aggregates:

• the constraints you can set to your 3D objects and stored in the Constraints collection you can
retrieve using the Part’s Constraints property
• the relations between parameters stored in a Relations collection you can retrieve using the
Part’s Relations property
• the parameters stored in a Parameters collection you can retrieve usin the Part’s Parameters
property
• the factories: a Factory3D object to create 3D reference elements and a ShapeFactory object to
create shapes. You can retrieve these factories using the Part’s Factory3D and ShapeFactory
properties respectively.

The following diagram details the main properties and methods of these objects.

71
3

PartDocument 1 Bodies Collection

MainBody
Part MainBody
Add() Object
1 Item()
Part Abstract Object
1
OriginElements * Body
GeometricElements 1 Sketches Object To Expand
Bodies
Constraints
Current Body Shapes
Relations 1 Expanded Object
Parameters Sketches
Factory3D
ShapeFactory Add()
CurrentBody Item()
CurrentShape
... * Sketch
Update()
... 1
Shapes
1

Item()

1 OriginElements
Current Shape * Shape
1 1
PlaneXY XYPlane
YZPlane 1
PlaneYZ
ZXPlane 1 Plane
PlaneZX
1
GeometricElements

* GeometricElement
1
Constraints

* Constraint
1
Relations

* Relation
1
Parameters

* Parameter
1
Factory3D
1
ShapeFactory

72 Scripting with CATIA Programmer’s Guide

 3

The Bodies collection includes Body objects, one being the main body returned by the MainBody
property of the collection. The part has in addition a current body and a current shape, returned or
set using the CurrentBody and the CurrentShape properties of the Part object respectively. The cur-
rent body is the body in which a new shape is added when using the ShapeFactory object. The cur-
rent shape is the shape of the current body after which a new shape is added in the specification tree
when using the shape factory. You then need to make current the appropriate body and shape before
using the shape factory.

The other collections can be classified in two categories:

1. The collections that only contains objects and have methods to retrieve and possibly remove
them, but leave the dedicated factories for object creation, such as Sketches, GeometricEle-
ments, and Shapes
2. The collections that also have methods to create the objects they contain, such as Constraints,
Relations, and Parameters.

73
3

Sketch
The Sketch object is described in the the following diagram.

Sketch Collection
GeometricElements
Constraints Object
Factory2D
... Abstract Object
OpenEdition()
CloseEdition()
Object To Expand
Factory2D
Factory2D
Expanded Object
CreatePoint()
CreateLine()
1 CreateCircle()
...
1
GeometricElements

* GeometricElement
1
Constraints

* Constraint
Centerline
Line2D
AbsoluteAxis
Axis2D

The Sketch object contains 2D geometric elements that define the sketch. These elements are cre-
ated using the Factory2D object and contained in a GeometricElements collection aggregrated by
the sketch. To create 2D geometric elements, you need first to “open the sketch edition” using the
OpenEdition method that returns the Factory2D object which supplies the appropriate methods to
create 2D geometric elements. Once you have finished creating 2D geometric elements, “close the
sketch edition” using the CloseEdition method. These two methods correspond to the commands
that let you interactively enter and leave the sketch. You can set constraints to the 2D
geometric elements using the methods supplied by the Constraints collection aggregated to the
sketch.

74 Scripting with CATIA Programmer’s Guide

 3

Geometric Elements
The geometric elements are described in the the following diagram.

GeometricElement
GeometricType
Plane

Geometry3D Line Circle2D

Point Line2D

Ellipse2D
Curve2D
Hyperbola2D

Parabola2D
StartPoint

EndPoint

Geometry2D Spline2D

Points
1 1 Control
2..*
Point2D ControlPoint2D

Axis2D
VerticalReference
HorizontalReference Line2D

The GeometricElement object is the abstract object from which derive all the others. It provides the
GeometricType property which returns the type of the geometric element to which it is applied. The
Geometry2D and Geometry 3D objects are abstract objects without any property.

The 3D geometric elements available are the Plane, the Line and the Point, and can be created to be
used as reference elements in the for the part and retrieved using its GeometricElements property.

The 2D geometric elements are used in sketches. The Curve2D object gathers the curve common
properties and methods.

75
3

Constraints

Constraints
BrokenConstraintsCount
UnUpdatedConstraintsCount
AddMonoEltCst()
AddBiEltCst()
AddTriEltCst()
Item()
Remove()

* Constraint
Type
Dimension
Mode
Side
Orientation
DistanceConfig
ReferenceAxis
Status
AngleSector
GetConstraintVisuLocation()
SetConstraintVisuLocation()

0..1
Dimension
Dimension

The Constraints collection provides methods to create constraints. A constraint can constrain one,
two or three elements. The number of broken and unupdated constraints can be retrieved from the
collection. A given constraint is defined using properties to set its type, its mode, its side and orien-
tation, its dimension and configuration, its reference axis, and its status. The type of a constraint
defines its nature, that is how the constraint works, and how many elements can be involved in
defining the constraint. The constraint status indicates if the constraint is valid, if something goes
wrong with the constraint, or if the constraint is broken. Other properties make sense for certain
types of constraints only (DistanceConfig or AngleSector for example). The constraint visualiza-
tion location can be set or retrieved in the 3D space using the two methods GetConstraintVisuLoca-
tion and SetConstraintVisuLocation.

76 Scripting with CATIA Programmer’s Guide

 3

Shapes

Shape

SketchBasedShape
Sketch

BooleanShape
Body

DressUpShape

TransformationShape

Shapes are classified into those built on a sketch, such as a pad or a hole, those which represent
boolean operations, such as a split or an intersection, those which are used to dress-up sketch-based
shapes, such as a fillet or a chamfer, and finally those which transform an original shape, transform
meaning here duplicates, such as mirror and pattern.

77
3

Sketch-Based Shapes

SketchBasedShape
Sketch

Relies on
Sketch

Prism

Hole

Revolution

Stiffener

Sweep

Sketch-based shapes rely obviously on sketches, and the Sketch property sets or retrieves the sketch
associated with the shape. The Prism abstract object federates properties and methods for the Pad
and the Pocket objects.

Prism

Extrusion
Pad direction orientation
Prism
DirectionType Pocket First limit
DirectionOrientation
IsSymmetric Extrusion
FirstLimit direction
SecondLimit
GetDirection
SetDirection Sketch to extrude
Is limited by 2 Normal or not
Limit
{ordered}
FirstLimit Second limit
SecondLimit

The Prism object provides to the Pad or to the Pocket the extrusion direction set or retrieved thanks
to the SetDirection or GetDirection methods. This extrusion direction can be normal to the sketch
plane or not. This is expressed using the CatPrismExtrusionDirection enumeration in the Direction-
Type property. The extrusion direction has an orientation expressed using the CatPrismOrientation
enumeration in the DirectionOrientation property. The Pad or the Pocket object can be symmetric to

78 Scripting with CATIA Programmer’s Guide

 3

the skecth plane. This is stored in the IsSymmetric property. Finally, the pad or the pocket has two
limits stored in the FirstLimit and SecondLimit properties as Limit objects. The Pad and the Pocket
objects do not hold specific properties or methods.

Hole

Hole Diameter Origin

Type
Diameter
Depth
HeadDiameter
HeadDepth Direction
HeadAngle
AnchorMode
BottomType
BottomAngle
BottomLimit Origin
ThreadingMode
ThreadingDepth
HeadDiameter
Reverse()
GetOrigin()
SetOrigin()
GetDirection()
SetDirection() Diameter
Diameter
Depth
Defines depth 2
Length HeadAngle
and diameter
HeadDiameter
HeadDepth
For counter... 2 For counterbore, counterdrilled,
Length and countersunk holes only.
HeadAngle
For counter... 1 For tapered, counterdrilled, and
Angle countersunk holes only.
BottomAngle
Defines angle 1 For VBottom holes only.
Angle
BottomLimit
Is limited by 1 For BilndHole and ThruHole
Limit only.
ThreadDepth
Defines thread 1 For threaded holes only.
Length

79
3

Revolution

Groove
Revolution
FirstAngle Shaft
SecondAngle

Is limited by 2
Angle
{ordered}

Stiffener

Stiffener
Thickness
IsSymmetric
ReverseDepth()

Is thick of 1
Length

Sweep

Rib
Sweep
CenterCurve Slot

Is centered on 1
Sketch

80 Scripting with CATIA Programmer’s Guide

 3

Boolean Shapes

BooleanShape
BooleanShape
Body

Is inserted 1
Body

Add

Assemble

Intersect

Remove

Split
SplittingPlane

Splits along
Plane

81
3

Dress Up Shapes

DressUpShape

Chamfer

Draft

Fillet

Scaling

Shell

Thickness

Chamfer

Chamfer
Mode
Propagation
Orientation
Angle
Length1
Length2
ElementsToChamfer
AddElementToChamfer()
WithdrawElementToChamfer()

Chamfer angle 1
Angle
Chamfer lengths 2
{ordered}
Length
Collection of 1
elements to chamfer References

* Reference

82 Scripting with CATIA Programmer’s Guide

 3

Draft

Draft
Mode
PartingElement
DraftDomains

Parting element 1
Reference
Collection of 1
draft domains DraftDomains

* DraftDomain

83
3

Fillet

Fillet

FaceFillet
Radius
FirstFace
SecondFace

Fillet radius 1
Length
Faces to fillet 2
Reference
{ordered}

TritangentFillet
FirstFace
SecondFace
FaceToRemove

Faces to fillet 3
Reference
{ordered}

ConstRadEdgeFillet
ObjectToFillet
EdgesToKeep
Radius
AddObjectToFillet()
EdgeFillet ...
Builds on 2
References
ObjectToFillet
EdgesToKeep * Reference
Fillet radius 1
Length
Radius
VarRadEdgeFillet
EdgesToFillet
ImposedVertices
FilletVariation
ImposedVertexRadius()
...
Builds on 2
References
EdgesToFillet
ImposedVertices * Reference

84 Scripting with CATIA Programmer’s Guide

 3

Scaling

Scaling
Mode
Factor
ScalingSupport

Scaling factor 1
RealParam
Scaling support 1
Reference

Shell

Shell
InternalThickness
ExternalThickness
FaceToRemove
AddFaceToRemove()
WithdrawFaceToRemove()

Thicknesses 2
{ordered}
Length
Collection of 1
faces to remove References

* Reference

85
3

Thickness

Thickness
Offset
FacesToThicken
AddFaceToThicken()
WithdrawFaceToThicken()

Offset 1
Length
Collection of 1
faces to thicken References

* Reference

86 Scripting with CATIA Programmer’s Guide

 3

Transformation Shapes

TransformationShape

Mirror
MirroringPlane

Mirrors in 1
Plane

RectPattern
FirstDirectionRepartition
SecondDirectionRepartition
FirstDirection
SecondDirection
FirstDirectionRow
Pattern SecondDirectionRow
ItemToCopy ...
RotationAngle Direction repartitions 2
LinearRepartition
Directions 2
Reference
Direction rows 2
IntParam

CircPattern
RadialRepartition
AngularRepartition
RotationAxis
Rotationcenter
AngularDirectionRow
RadialDirectionRow
...
Radial repartition 1
LinearRepartition
Agular repartition 1
AngularRepartition
Rotation axis 1
Reference
Rotation center 1
Reference
Direction rows 2
IntParam
Pattern to reproduce
CATIABase

Rotates
Angle

87
3

Repartition

AngularRepartition
AngularSpacing
Repartition Angular spacing 1
Angle
InstancesCount
LinearRepartition
Spacing

Spacing 1
Length
Count 1
IntParam

88 Scripting with CATIA Programmer’s Guide

 3

Limit

Limit
LimitingElement
Dimension
LimitMode
LimitingElement 1
Reference
Dimension 1
Length

89
3

Draft Domain

DraftDomain
DraftAngle
Support
NeutralElement
...
AddSupportToDraft
RemoveSupportToDraft
Draft angle 1
Angle
Neutral element 1
Reference
Support 1
References

* Reference

90 Scripting with CATIA Programmer’s Guide

 3

Relations

Relation
Value
Comment
Family
Activated
Activate()
Deactivate()

Check

Formula

Program

91
3

Literal Objects

Parameter
OptionalRelation
ReadOnly
Is constrained by
Relation

Length
RealParam Dimension
Value ValuateFromString Angle
IntParam
Value

BoolParam
Value

StrParam
Value

92 Scripting with CATIA Programmer’s Guide

 3

Programming Tasks and Scenarios

The programming tasks and scenarios supplied here help you understand how to create macros that
you can run inside CATIA or from another application, and using which macro programming lan-
guage and environment. The scenarios covered are the following::

Scenarios Language and Environment

Creating Parameters VB Script or Basic Script

Creating a Formula VB Script or Basic Script

Modifying a Formula VB Script or Basic Script

Activating and Deactivating a Formula VB Script or Basic Script

Creating a Program VB Script or Basic Script

Creating a Check VB Script or Basic Script

93
3

Creating Parameters

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create parameters.

The active document is assumed to be a part.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the active document and the collection of parameters associated with the part

Dim myDoc As Document

Set myDoc = CATIA.ActiveDocument
Dim myParamCol As Parameters
Set myParamCol = myDoc.Part.Parameters

3. Create an empty string parameter to store the material of the part, name it and value it

Dim myMaterial As Parameter

Set myMaterial = myParamCol.CreateString(““, ““)
myMaterial.Rename “material”
myMaterial.Value = “steel”

4. Create a dimension parameter set to 0 to store the height of the pad, name it and value it

Dim myHeight As Parameter

Set myHeight = myParamCol.CreateDimension(““,“LENGTH”, 0)
myHeight.Rename “maximum height”
myHeight.Value = 50

5. Create an integer parameter set to 0 to store the part number, name it and value it

Dim myNumber As Parameter

Set myNumber = myParamCol.CreateInteger(““, 0)
myNumber.Rename “number”
myNumber.Value = 25

6. Create a boolean parameter set to True to store the part number, name it and value it

Dim isChecked As Parameter

Set isChecked = myParamCol.CreateBoolean(““, True)
isChecked.Rename “check status”
isChecked.Value = False

94 Scripting with CATIA Programmer’s Guide

 3

The resulting macro is as follows.

Language = “VBScript“
Dim myDoc As Document
Set myDoc = CATIA.ActiveDocument
Dim myParamCol As Parameters
Set myParamCol = myDoc.Part.Parameters
Dim myMaterial As Parameter
Set myMaterial = myParamCol.CreateString(“material“, ““)
myMaterial.Rename “material”
myMaterial.Value = “steel”
Dim myHeight As Parameter
Set myHeight = myParamCol.CreateDimension(““,“LENGTH”, 0)
myHeight.Rename “maximum height”
myHeight.Value = 50
Dim myNumber As Parameter
Set myNumber = myParamCol.CreateInteger(““, 0)
myNumber.Rename “number”
myNumber.Value = 25
Dim isChecked As Parameter
Set isChecked = myParamCol.CreateBoolean(““, True)
isChecked.Rename “check status”
isChecked.Value = False

95
3

Creating a Formula

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a formula which computes the height of a pad by dividing by two
a length constraint set on one of the element of the sketch on which the pad is built.
You need a plane.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the main body of the active document and the pad named Pad.1 in this main body

Dim mainBody As Body

Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)

3. Create a formula named Formula.1 with an empty comment, which output value is the
pad height (its first limit dimension). The height is computed using half of the value of a dis-
tance constraint set to the sketch on which the pad is built, named PadLength

Dim myFormula As Formula

Set myFormula = CATIA.ActiveDocument.Part.Relations.CreateFormula(
“Formula.1”, ““, myPad.FirstLimit.Dimension, “PadLength/2”)

The resulting macro is as follows.

Language = “VBScript“
Dim mainBody As Body
Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)
Dim myFormula As Formula
Set myFormula = CATIA.ActiveDocument.Part.Relations.CreateFormula( “For-
mula.1”, “”, myPad.FirstLimit.Dimension, “PadLength/2”)

96 Scripting with CATIA Programmer’s Guide

 3

Modifying a Formula

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to modify the formula created in Creating a Formula to now compute the
height of the pad by adding the values of two length constraints set on two elements of the sketch
on which the pad is built.
You need a plane.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the main body of the active document and the pad named Pad.1 in this main body

Dim mainBody As Body

Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)

3. Retrieve the formula named Formula.1

Dim myFormula As Formula

Set myFormula = CATIA.ActiveDocument.Part.Relations.Item(“For-
mula.1”)

4. Modify the formula. The new output value is computed by adding the values of two distance
constraints set to the sketch on which the pad is built, named PadLength and PadWidth

myFormula.Modify “PadLength + PadWidth”

The resulting macro is as follows.

Language = “VBScript“
Dim mainBody As Body
Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)
Dim myFormula As Formula
Set myFormula = CATIA.ActiveDocument.Part.Relations.Item(“Formula.1”)
myFormula.Modify “PadLength + PadWidth”

97
3

Activating and Deactivating a Formula

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to deactivate a formula, then set a parameter previously computed by the
formula, and possibly activate then formula again. The same could apply to a program or a
check.
The formula is assumed to exist already and controls the height of a pad contained in the active
part document.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the formula named Formula.1 from the part of the active document

Dim myPart As Part

Set myPart = CATIA.ActiveDocument.Part
Dim myFormula As Formula
Set myFormula = myPart.Relations.Item(“Formula.1”)

3. Deactivate the formula. From now on, the formula is not used any more to compute its out-
put parameter

myFormula.Deactivate

4. Retrieve the pad and set the height of the pad named Pad.1 to a value of 35. The pad height is
no longer controlled by the formula, but has the constant value you set. Nevertheless the for-
mula remains in the part.

Dim myBody As Body

Set myBody = myPart.Bodies.MainBody
Dim myPad As Pad
Set myPad = myBody.Shapes.Item(“Pad.1”)
myPad.FirstLimit.Dimension.Value = 35
If you want afterwards control the pad height again using the formula, simply activate the
formula
myFormula.Activate

5. Deactivate the formula. From now on, the formula is not used any more to compute its out-
put parameter

myFormula.Deactivate

98 Scripting with CATIA Programmer’s Guide

 3

The resulting macro is as follows.

Language = “VBScript“
Dim myPart As Part
Set myPart = CATIA.ActiveDocument.Part
Dim myFormula As Formula
Set myFormula = myPart.Relations.Item(“Formula.1”)
myFormula.Deactivate
Dim myBody As Body
Set myBody = myPart.Bodies.MainBody
Dim myPad As Pad
Set myPad = myBody.Shapes.Item(“Pad.1”)
myPad.FirstLimit.Dimension.Value = 35
myFormula.Activate

99
3

Creating a Program

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a program.

The active document contains a pad named Pad.1 which is a cuboid..

1. Declare the language to use

Language = “VBScript“

2. Retrieve the main body of the active document and the pad named Pad.1 in this main body

Dim mainBody As Body

Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)

3. Create a program named Program.1 with an empty comment, which computes the pad
height (its first limit dimension) and mass. The height of the pad is computed by adding the
values of two length constraints set on the sketch (a rectangle), named PadLength and
PadWidth, on which the pad is built.

Dim myProgram As Rule

Set myProgram = CATIA.ActiveDocument.Part.Relations.CreateProgram(
“Program.1”, “Computes height and mass“, “Height=PadLength+PadWidth
Mass=PadLength*PadWidth*Height*Density”)

The resulting macro is as follows.

Language = “VBScript“
Dim mainBody As Body
Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)
Dim myProgram As Rule
Set myProgram = CATIA.ActiveDocument.Part.Relations.CreateProgram( “Pro-
gram.1”, “Computes height and mass”, “Height=PadLength+PadWidth
Mass=PadLength*PadWidth*Height*Density”)

100 Scripting with CATIA Programmer’s Guide

 3

Creating a Check

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a check.

You need a plane.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the main body of the active document and the pad named Pad.1 in this main body

Dim mainBody As Body

Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)

3. Create a check named Check.1 with a comment, which checks that the pad length is
greater than 10mm. The pad length is a distance constraint set to the sketch on which the pad
is built

Dim myCheck As Check

Set myCheck = CATIA.ActiveDocument.Part.Relations.CreateCheck(
“Check.1”, “Check that length > 10“, “PadLength>10”)

The resulting macro is as follows.

Language = “VBScript“
Dim mainBody As Body
Set mainBody = CATIA.ActiveDocument.Part.Bodies.MainBody
Dim myPad As Pad
Set myPad = mainBody.Shapes.Item(“Pad.1”)
Dim myCheck As Check
Set myCheck = CATIA.ActiveDocument.Part.Relations.CreateCheck(
“Check.1”, “Check that length > 10“, “PadLength>10”)

101
3

102 Scripting with CATIA Programmer’s Guide

Scripting with Assembly
Design 4
This part contains information about the Assembly Design objects, and their relationships. Assem-
bly Design programming tasks are also included.
• Assembly Design Object Architecture
• Programming Tasks and Scenarios.

103
4

Assembly Design Object Architecture

The Assembly Design objects are shown on the following diagram:

ProductDocument Collection

1
Product * Object

1 Abstract Object
Products
1 Object To Expand
Constraints

* Constraint Expanded Object

1
Position
1
Move

The ProductDocument object aggregates, or includes, a product tree structure starting with a single
product, named the root product, which includes a collection of products. Each of the products of
this collection can itself include a collection of products, and so forth.

Each product is positioned in the 3D space thanks to the Position object which represents the prod-
uct’s 3D-axis system expressed with respect to the assembly’s 3D-axis system. The Move object
allows the object moving. Constraints can be set to constrain the product’s position and move.

The following diagram shows such a tree structure for a (simple) car.

104 Scripting with CATIA Programmer’s Guide

 4

CarAssembly The part document

Car The root product

CarParts The root product’s collection of products

Body A product and its collection

of products
BodyParts

Roof
Products that can
LeftFrontDoor also have each
its own collection
Bonnet of products

PowerTrain

PowerTrainParts

Engine

EngineParts

Cylinderhead
Products that can
Cylinder also have each
its own collection
of products
Carter

Coupling
Products that can
GearBox also have each
its own collection
Rear Axle of products

RearAxleParts
Products that can
LeftRearWheel also have each
its own collection
RightRearWheel of products

A given product, such as the cylinder head or the gear box, is in fact a product component of a prod-
uct reference. This product reference is neither accessible using macros nor from interactive com-
mands. It is nevertheless created when you create a product component. Products that appear

105
4

duplicated, such as the wheels, can be product components pointing to the same product reference.
In this example, the LeftRearWheel and RightRearWheel objects can be two product components of a
single wheel product reference. Creating references enables consistency management. When a
modification is brought to a product, such as its part number, or its master shape representation
which we’ll see below, the modification is brought through a component to the reference, and is
propagated to all the components which point to this reference.
The following diagram gives additional details about the Assembly Design objects.

ProductDocument Collection
Product
Object
Root Product 1
Product *
Abstract Object

Contained Products
Products
Connections
Position Object To Expand
Move
...
Expanded Object
AddMasterShapeRepresentation()
RemoveMasterShapeRepresentation()
GetMasterShapeRepresentation()
...
Contains Product 0..1
Collection
Products
AddNewProduct()
AddComponent()
AddExternalComponent()
...
Positioning Constraints 1
Constraints

* Constraint
Is positioned at 1
Position
GetComponents()
SetComponents()
Can be moved by 1
Move
MovableObject
Apply()

The root product is retrieved by the ProductDocument object using its Product property. Each
product, starting with the root product, may include a Products collection which gathers all the
products just below this product in the product tree structure. This collection is built using the Add-
NewProduct, AddComponent and AddExternalComponent methods:
• AddNewProduct creates both a reference to the product and a component in the ProductDocu-
ment

106 Scripting with CATIA Programmer’s Guide

 4

• AddComponent creates a product component from a product reference already existing in the
ProductDocument, that is a product component of a product already created in any of the Prod-
ucts collection of the ProductDocument using the AddNewProduct method
• AddExternalComponent creates a product component using the root product of another Pro-
ductDocument.

Each product reference can have a master shape representation which defines its geometry, material
properties, and so forth, and used to display or print it, and maybe more, for example to analyze or
manufacture it. This is optional, but is often required to represent actual products. This master
shape representation is shared by all the components pointing to this product reference, and can be
a CATIA Version 4 model, a CATIA Version 5 part, a VRML file, or whatever format supported by
CATIA Version 5. The methods AddMasterShapeRepresentation, RemoveMasterSha-
peRepresentation, and GetMasterShapeRepresentation manage the master shape repre-
sentation.

Each product component in the tree structure is positioned in the space according to the position of
its own 3D-axis system with respect to the product document’s 3D axis-system, this position being
possibly determined according to positioning constraints relative to the product above it in the tree
structure. This means that each product component is positioned with respect to the root product
according to a cascading position combination from the root product to the current product across
the product tree structure. Its position can be set or retrieved using the Position property, what-
ever the constraints applied. The Move property allows a movable object retrieval to move the prod-
uct as required by a move operation while ensuring that the positioning constraints are matched.
The movable object returned is the product object itself, meaning that a product is movable, but
with some other applications, this could be different. For example, the movable object returned
from an edge in a pad is the whole pad, since the edge cannot be moved alone and is linked to the
other edges and faces in the pad. The actual move is performed using the Apply method. This
method takes a table with twelve items as input which define the move. This table contains the
move matrix elements and has the following structure, assuming that M is the table identifier:

M(0)=Ux M(3)=Vx M(6)=Wx M(9)=Tx

M(1)=Uy M(4)=Vy M(7)=Wy M(10)=Ty
M(2)=Uz M(5)=Vz M(8)=Wz M(11)=Tz

The first nine items represent an axis rotation, and the last three a translation. It expresses the prod-
uct 3D-axis system (T,U,V,W) with respect to the root product 3D-axis system(O,xy,z), where:
• Ux, Uy and Uz are the components of the U vector with respect to (O,x,y,z)
• Vx, Vy and Vz are the components of the V vector with respect to (O,x,y,z)
• Wx, Wy and Wz are the components of the W vector with respect to (O,x,y,z)
• Tx, Ty and Tz are the coordinates of the new origin T with respect to (O,x,y,z)

107
4

V
U
z

O
x y

108 Scripting with CATIA Programmer’s Guide

 4

Programming Tasks and Scenarios

The programming tasks and scenarios supplied here help you understand how to create macros that
you can run inside CATIA or from another application, and using which macro programming lan-
guage and environment. The scenarios covered are the following:

Scenarios Language and Environment

Creating a Simple Assembly with Two Parts VB Script or Basic Script

Creating an Assembly with Components of the Same VB Script or Basic Script

Product

Creating an Assembly with a Component of an External VB Script or Basic Script

Product
Producing a Bill of Materials from a Product Document VB Script or Basic Script

109
4

Creating a Simple Assembly with Two Parts

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create an assembly in a product document using two parts. The product
tree structure is as follows:
ProductDoc The part document

RootProduct The root product

RootChildren The root product’s collection of products

ChildProduct1 The first product

ChildProduct2 The second product

The two parts should exist before running this macro. Assume that Part1.CATPart contains a
cuboid and is the master representation of ChildProduct1, and that Part2.CATPart contains a
cylinder and is the master representation of ChildProduct2. Note that there is no master represen-
tation for the root product.

1. Declare the language to use

Language = “VBScript”

2. Create the ProductDocument object by adding a document with the Product type to the doc-
ument collection of the CATIA application

Dim ProductDoc As Document

Set ProductDoc = CATIA.Documents.Add(“Product”)

3. Retrieve the root product

Dim RootProduct As Product

Set RootProduct = ProductDoc.Product

4. Declare the root product’s part number and name

RootProduct.PartNumber = “Root”
RootProduct.Name = “The_Root_Product”

5. Retrieve the product’s collection of the root product

Dim RootChildren As Products

Set RootChildren = RootProduct.Products

110 Scripting with CATIA Programmer’s Guide

 4

6. Add a new product in the collection. This adds both a product reference and a product com-
ponent.

Dim ChildProduct1 As Product

Set ChildProduct1 = RootChildren.AddNewProduct(“Child_1_Type”)
The argument of the AddNewProduct method is the product type. Note that you can supply
it or leave it blank. In the latter case, it is defaulted to product_i, where i is the first integer
leaved free by the preceding product creations. Here it would be defaulted to product_1. This
product type cannot be modified afterwards.
7. Declare the part number and name for this product

ChildProduct1.PartNumber = “Child_001”
ChildProduct1.Name = “1st_Child”

8. Add a representation to this product using Part1.CATPart and reframe the viewer to display
the part completely

ChildProduct1.AddMasterShapeRepresentation(“e:\Parts\Part1.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()

9. Add another product to the root product’s collection. This adds both a product reference and
a product component

Dim ChildProduct2 As Product

Set ChildProduct2 = RootChildren.AddNewProduct(“Child_2_Type”)

10. Declare the part number and name for this product

ChildProduct2.PartNumber = “Child_002”
ChildProduct2.Name = “2nd_Child”

11. Add a representation to this product using Part2.CATPart and reframe the viewer

ChildProduct2.AddMasterShapeRepresentation(“e:\Parts\Part2.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()
Note that we don’t add any positioning information. The parts are then located at the place
where they were designed, and the root product’s axis system and the parts’ axis systems
coincide.

111
4

The resulting macro is as follows.

Language = “VBScript”
Dim ProductDoc As Document
Set ProductDoc = CATIA.Documents.Add(“Product”)
Dim RootProduct As Product
Set RootProduct = ProductDoc.Product
RootProduct.PartNumber = “Root”
RootProduct.Name = “The_Root_Product”
Dim RootChildren As Products
Set RootChildren = RootProduct.Products
Dim ChildProduct1 As Product
Set ChildProduct1 = RootChildren.AddNewProduct(“Child_1_Type”)
ChildProduct1.PartNumber = “Child_001”
ChildProduct1.Name = “1st_Child”
ChildProduct1.AddMasterShapeRepresentation(“e:\Parts\Part1.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()
Dim ChildProduct2 As Product
Set ChildProduct2 = RootChildren.AddNewProduct(“Child_2_Type”)
ChildProduct2.PartNumber = “Child_002”
ChildProduct2.Name = “2nd_Child”
ChildProduct2.AddMasterShapeRepresentation(“e:\Parts\Part2.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()

112 Scripting with CATIA Programmer’s Guide

 4

This example uses the Add method of the Documents collection to create the product document,
the Product property of the ProductDocument object to retrieve the root product, the Part-
Number property of the Product object to create a part number for the two products, the Name
property of the AnyObject object from which the Product object inherits to assign them a
name, the AddMasterShapeRepresentation method of the Products object to associate a
part to each of the products and enable their display, the Products property of the Product
object to retrieve the product collection of the root product, and the AddNewProduct method of
the Products object to add the child product to the root product’s collection. Here is the result.

For each product, its part number, such as Child_001, is displayed first and its name, such as
1st_Child, is displayed between parentheses in the product tree. The product’s master representa-
tion, such as Part1, is displayed attached to the product at a lower level.

113
4

Creating an Assembly with Components of the Same Product

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create an assembly in a product document using two parts. The root prod-
uct is the steam ship Titanic, comprising five products: the hull and the four identical funnels.
The first funnel is added as a new product and the three others are created from it.The product
tree structure is as follows:

ProductDoc The part document

Titanic The root product

TitanicProducts The root product’s collection of products

Hull

Funnel1

Funnel2 The products

Funnel3

Funnel4

This task shows you in addition how to position components in the 3D space.

The two parts should exist before running this macro. Assume that Hull.CATPart is the mas-
ter representation for the hull, and Funnel.CATPart the one of the funnel.

1. Declare the language to use

Language = “VBScript”

2. Create the ProductDocument object by adding a document with the Product type to the doc-
ument collection of the CATIA application

Dim ProductDoc As Document

Set ProductDoc = CATIA.Documents.Add(“Product”)

3. Retrieve the Titanic as the root product

Dim Titanic As Product

Set Titanic = ProductDoc.Product

114 Scripting with CATIA Programmer’s Guide

 4

4. Declare the Titanic’s part number and name

Titanic.PartNumber = “Titanic”
Titanic.Name = “Steam_Ship_Titanic”

5. Retrieve the product’s collection of the Titanic

Dim TitanicProducts As Products

Set TitanicProducts = Titanic.Products

6. Add the hull as a new component in the collection with its part number and name

Dim Hull As Product

Set Hull = TitanicProducts.AddNewProduct(“Hull_Type”)
Hull.PartNumber = “Titanic’s_Hull”
Hull.Name = “Unsinkable_Hull”

7. Add a master shape representation to the hull using Hull.CATPart and reframe the
viewer

Hull.AddMasterShapeRepresentation(“e:\Parts\Hull.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()
Note that we don’t add any positioning information. The part is then located at the place
where it was designed.

8. Add the first funnel to the Titanic’s product collection, with part number and name

Dim Funnel1 As Product

Set Funnel1 = TitanicProducts.AddNewProduct(“Funnel_Type”)
Funnel1.PartNumber = “Titanic’s_Funnel”
Funnel1.Name = “Fore_Funnel”

9. Add a master shape representation to the funnel using Funnel.CATPart

Funnel1.AddMasterShapeRepresentation(“e:\Parts\Funnel.CATPart”)

115
4

10. Define the positioning parameters for Funnel1

Dim Matrix(11)
Matrix(0) = 1.0
Matrix(1) = 0.0
Matrix(2) = 0.0
Matrix(3) = 0.0
Matrix(4) = 1.0
Matrix(5) = 0.0
Matrix(6) = 0.0
Matrix(7) = 0.0
Matrix(8) = 1.0
Matrix(9) = 110.0
Matrix(10) = 20.0
Matrix(11) = 20.0
We just translate Funnel1 using the vector (110,20,20) to place the fore funnel on top of the
hull and in with its bottom center on the longitudinal axis of the hull.

11. Apply the move to Funnel1’s movable object

Funnel1.Move.Apply(Matrix)

12. Add a second component using the created component Funnel1

Dim Funnel2 As Product

Set Funnel2 = TitanicProducts.AddComponent(Funnel1)
Funnel2.Name = “Second_Funnel”
Matrix(9) = 80.0
Funnel2.Move.Apply(Matrix)
Note that we don’t add a master shape representation to this component, since its takes it
from the reference created with Funnel1.

13. Add a third component of Funnel

Dim Funnel3 As Product

Set Funnel3 = TitanicProducts.AddComponent(Funnel1)
Funnel3.Name = “Third_Funnel”
Matrix(9) = 50.0
Funnel3.Move.Apply(Matrix)

14. Add a fourth component of Funnel

Dim Funnel4 As Product

Set Funnel4 = TitanicProducts.AddComponent(Funnel1)
Funnel4.Name = “Aft_Funnel”
Matrix(9) = 80.0
Funnel4.Move.Apply(Matrix)

116 Scripting with CATIA Programmer’s Guide

 4

The resulting macro is as follows.

Language = “VBScript”
Dim ProductDoc As Document
Set ProductDoc = CATIA.Documents.Add(“Product”)
Dim Titanic As Product
Set Titanic = ProductDoc.Product
Titanic.PartNumber = “Titanic”
Titanic.Name = “Steam_Ship_Titanic”
Dim TitanicProducts As Products
Set TitanicProducts = Titanic.Products
Dim Hull As Product
Set Hull = TitanicProducts.AddNewProduct(“Hull_Type”)
Hull.PartNumber = “Titanic’s_Hull”
Hull.Name = “Unsinkable_Hull”
Hull.AddMasterShapeRepresentation(“e:\Parts\Hull.CATPart”)
CATIA.ActiveWindow.ActiveViewer.Reframe()
Dim Funnel1 As Product
Set Funnel1 = TitanicProducts.AddNewProduct(“Funnel_Type”)
Funnel1.PartNumber = “Titanic’s_Funnel”
Funnel1.Name = “Fore_Funnel”
Funnel1.AddMasterShapeRepresentation(“e:\Parts\Funnel.CATPart”)
Dim Matrix(11)
Matrix(0) = 1.0
Matrix(1) = 0.0
Matrix(2) = 0.0
Matrix(3) = 0.0
Matrix(4) = 1.0
Matrix(5) = 0.0
Matrix(6) = 0.0
Matrix(7) = 0.0
Matrix(8) = 1.0
Matrix(9) = 110.0
Matrix(10) = 20.0
Matrix(11) = 20.0
Funnel1.Move.Apply(Matrix)
Dim Funnel2 As Product
Set Funnel2 = TitanicProducts.AddComponent(Funnel1)
Funnel2.Name = “Second_Funnel”
Matrix(9) = 80.0
Funnel2.Move.Apply(Matrix)
Dim Funnel3 As Product
Set Funnel3 = TitanicProducts.AddComponent(Funnel1)
Funnel3.Name = “Third_Funnel”
Matrix(9) = 50.0
Funnel3.Move.Apply(Matrix)
Dim Funnel4 As Product
Set Funnel4 = TitanicProducts.AddComponent(Funnel1)
Funnel4.Name = “Aft_Funnel”
Matrix(9) = 20.0
Funnel4.Move.Apply(Matrix)

117
4

This example uses the Add method of the Documents collection to create the product document,
the Product property of the ProductDocument object to retrieve the root product, the Part-
Number property of the Product object to create a part number for the root product and the
Name property of the AnyObject object from which the Product object inherits to assign the
root product a name. Then the hull is added as a component using the AddNewProduct method
of the Products collection, and a master shape representation is assigned to it using the
AddMasterShapeRepresentation method of the Products collection. The same applies to
the first funnel. It is positioned in the space using the matrix defined and the Move property of the
Product object which retrieves a Move object to which the Apply method is applied. Then the
three other funnels are created as components using the reference created by the first funnel
thanks to the AddComponent method of the Products collection. For each funnel, the matrix is
modified and the funnel is positioned as the first one.

118 Scripting with CATIA Programmer’s Guide

 4

Creating an Assembly with a Component of an External Product

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to include in an existing assembly a new component which is already the
root product of another product document.
The product document is assumed to be the active document. The product document to add is
already opened. The added component is added to the root product collection.

1. Declare the language to use

Language = “VBScript”

2. Retrieve the ProductDocument from which the bill of materials is to be extracted. It is

assumed that it is the active document.

Dim ProductDoc As Document

Set ProductDoc = CATIA.ActiveDocument

3. Retrieve the root product

Dim Root A Product

Set Root = ProductDoc.Product

4. Retrieve the root product collection of products

Dim RootCol As Products

Set RootCol = Root.Products

5. Add a new component from the already opened product document ExtDoc

Dim NewComponent As Product

Set NewComponent = RootCol.AddExternalComponent(ExtDoc)

The resulting macro is as follows.

Language = “VBScript”
Dim ProductDoc As Document
Set ProductDoc = CATIA.ActiveDocument
Dim Root A Product
Set Root = ProductDoc.Product
Dim RootCol As Products
Set RootCol = Root.Products
Dim NewComponent As Product
Set NewComponent = RootCol.AddExternalComponent(ExtDoc)

119
4

This example uses the ActiveDocument method of the Application object to retrieve the
active document, the Product property of the ProductDocument object to retrieve the root
product, and the Products property of the Product object to retrieve the collection of product
of the root product, and the AddExternalComponent method of the Products collection to
add the root product of the already opened product document ExtDoc as a component of the root
product collection.

120 Scripting with CATIA Programmer’s Guide

 4

Producing a Bill of Materials from a Product Document

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to extract a bill of materials from a product document.

This macro should be applied to the product document created using the macro described in Cre-
ating an Assembly with Components of the Same Product.

1. Declare the language to use

Language = “VBScript”

2. Retrieve the ProductDocument from which the bill of materials is to be extracted. It is

assumed that it is the active document, just created by the macro described in Creating an
Assembly with Components of the Same Product.

Dim ProductDoc As Document

Set ProductDoc = CATIA.ActiveDocument

3. Retrieve the Titanic as the root product

Dim Titanic As Product

Set Titanic = ProductDoc.Product

4. Extract the bill of materials and put it in a text file

Titanic.ExtractBOM(catFileTypeText, e:\BOM\TitanicBOM.txt)

The resulting macro is as follows.

Language = “VBScript”
Dim ProductDoc As Document
Set ProductDoc = CATIA.ActiveDocument
Dim Titanic As Product
Set Titanic = ProductDoc.Product
Titanic.ExtractBOM(catFileTypeText, e:\BOM\TitanicBOM.txt)

121
4

This example uses the ActiveDocument method of the Application object to retrieve the
active document, the Product property of the ProductDocument object to retrieve the root
product, and the ExtractBOM method of the Product object to extract the bill of materials. The
extracted bill of materials is as follows

Compute Date : Mon May 04 16:20:26 1998

Used Search Order :

1 : c:\temp
2 : e:\users\psr
3 : e:\users\mry
4 : c:\temp

=======================================================================
=========
= Bill of Material :
Titanic =
=======================================================================
=========

+----------+----------------------+-------+---------------------+------
--------+
| Qty | Part Number | type | Nomenclature |
Revision |
+----------+----------------------+-------+---------------------+------
--------+
| 1 | Titanic’s_Hull |
part | | |
| 4 | Titanic’s_Funnel |
part | | |
+----------+----------------------+-------+---------------------+------
--------+

===================================
= Recapitulation Of : Titanic =
= Different Parts : 2 =
= Total Parts : 5 =
===================================

+----------+----------------------+
| Qty | Part Number |
+----------+----------------------+
| 1 | Titanic’s_Hull |
| 4 | Titanic’s_Funnel |
+----------+----------------------+

122 Scripting with CATIA Programmer’s Guide

Scripting with Drafting
5
This part contains information about the Generative Drafting objects, and their relationships. Gen-
erative Drafting programming tasks are also included.
• Generative Drafting Object Architecture
• Programming Tasks and Scenarios.

123
5

Generative Drafting Object Architecture

The Generative Drafting objects are shown on the following diagram:

Collection

Object

DrawingDocument Abstract Object

1
DrawingSheets Object To Expand
* DrawingSheet Expanded Object
1
DrawingViews

* DrawingView Reference View

DrawingView
1
1
DrawingViewGenerativeBehavior
Parent View

Document to draw 1
Document

The Drawing objects build a cascading aggregation architecture. The DrawingDocument object
includes a DrawingSheets collection. Each DrawingSheet of this collection includes a DrawingViews
collection to store its DrawingView objects. A DrawingView object handled by the Generative Draft-
ing is generated from a document and aggregates a DrawingViewGenerativeBehavior object which
contains the appropriate data to generate the drawing view, such as the document that the drawing
view represents, and possibly another drawing view called the parent view and used to define addi-
tional useful information. For example, a left view is not a left view alone, but is a left view with
respect to another view called the front view. This front view is the parent view for the left view. It
defines the contents of the left view, and how to see this contents, that is as if the user looked the
scene represented by this front view from the left.

The drawing view can also be linked to its parent view for alignment purpose, and this link is called
reference. This is the case of a left view linked to a front view. This reference is always and only an
alignment reference to help position the drawing view with respect to its reference drawing view.
For example, the left view is positioned at the right of the front view according to the ISO standard,
and to the left of the front view according to the ANSI standard, in both cases on a horizontal line
with respect to the front view. This alignment reference can be deactivated.

Let’s detail these objects.

124 Scripting with CATIA Programmer’s Guide

 5

DrawingDocument Collection
Sheets
1
Object
DrawingSheets
ActiveSheet Abstract Object
Add()
Remove() Object To Expand
Item()
Expanded Object
* DrawingSheet
Views
Activate()
Update()
GenerateDimensions()
1
DrawingViews
ActiveView
Add()
Remove()
Item()

* DrawingView

The DrawingDocument object aggregates its DrawingSheets collection and you can retrieve it thanks
to the Sheets property. When a drawing document is active, it has always an active sheet you can
retrieve from the DrawingSheets collection using the ActiveSheet property. The active sheet is
the sheet you are working in. Like many collections, the drawing sheet collection supplies the Add,
Remove, and Item method to manage the sheets in the collection. The DrawingSheet object aggre-
gates its DrawingViews collection and you can retrieve it thanks to the Views property. In the active
drawing sheet, there is always an active drawing view. This is the one you are working in, or in
which you can work, and is surrounded using a red dashed frame. You can activate the drawing
view you want using the Activate method. The Update method updates all the drawing views of
the drawing sheet according to the modification brought to the document(s) represented in these
drawing views. The GenerateDimensions method generates dimensions, in all the views of the
drawing sheet which contains documents with constraints, such as constraints in sketches, in 3D
parts, between 3D primitives, and assembly constraints, for each constraint of the following type:
distance, length, angle, radius, and diameter. The drawing view collection lets you retrieve the
active view using the ActiveView property. Like many collections, the drawing view collection
supplies the Add, Remove, and Item methods to manage the views in the collection.

The drawing view and related objects are as follows.

125
5

Reference View
DrawingView DrawingView
x 1
y
Scale
Angle
GenerativeBehavior Collection
ReferenceView
Activate() Object
AlignedWithReferenceView()
UnAlignedWithReferenceView()
IsGenerative() Abstract Object

1 Object To Expand
DrawingViewGenerativeBehavior
Document
ParentView Expanded Object
HiddenLineMode
SetProjectionPlane()
GetProjectionPlane()
GetProjectionPlaneNormal()
DefineFrontView()
DefineIsometricView()
DefineProjectionView()
DefineSectionView()
DefineCircularDetailView()
DefineAuxiliaryView()
Update()
ParentView

Document to draw 1
Document

The drawing view is placed in the drawing sheet using the following properties:

A drawing sheet A drawing view

y
Angle

The drawing sheet The drawing view

axis system axis system

126 Scripting with CATIA Programmer’s Guide

 5

The x, y, and Angle properties are used to place the drawing view in the drawing sheet. The draw-
ing view has also a Scale property which determines its size in the drawing sheet with respect to
the 3D document represented. The GenerativeBehavior property retrieves the DrawingViewGen-
erativeBehavior object associated with the drawing view, and you can get or set the reference view
thanks to the ReferenceView property.

Using the Activate method, you can make the drawing view the active one. The AlignedWith-
ReferenceView and UnAlignedWithReferenceView methods enable you to align and deacti-
vates the alignment with respect to the reference view. The IsGenerative methods returns
whether the drawing view is generated from a document.

The DrawingViewGenerativeBehavior object includes additional parameters to fully define the draw-
ing view. First, it includes a link to the represented document using its Document property. Then it
includes a link to the parent view, if any, thanks to the ParentView property. It also includes the
DefinexxxView methods to define views according to the different available types. The Set-
ProjectionPlane, GetProjectionPlane, and GetProjectionPlaneNormal methods man-
age the drawing view projection plane. The drawing view projection plane is usually defined when
the drawing view is created, either by setting it explicitly for a front view or an isometric view, or
by deducing it from the one of the parent view for the other views.

Let’s now detail the different type of views.

A drawing view can be used as a parent view for other drawing views. When you create a drawing
view, for example from a part, you first create a front view, and then you can create a left, right, top,
or bottom drawing view from this front view. The left, right, top, or bottom view is called a projec-
tion view. The front view is used as a parent view to determine how the document is projected in the
projection view. For example, left means projecting the part on a vertical plane which is perpendic-
ular to the front view projection plane, and which is seen from the left.

A drawing view is strongly linked to its parent view. If the parent view is updated because the doc-
ument it displays has changed, or if you change its scale, all the drawing views which have this
view as parent view are changed accordingly.

127
5

left view
projection plane

left

front
front view left view

The drawing sheet

front view
projection plane

The front view is also used as a reference by the left view for positioning. If you want to move the
left view, it is constrained to move horizontally to remain a left view of the front view. The left view
can access its reference view by means of the ReferenceView property.

The following table summarizes the different view types along with their ability to have a parent
view and if this parent view can also be a reference view.

View Types Parent View Reference View Creation Method

Front View No No DefineFrontView
Isometric View No No DefineIsometricView
Projection View Yes Yes DefineProjectionView
Section View Yes Yes DefineSectionView
Detail View Yes No DefineCircularDetailView
Auxiliary View Yes Yes DefineAuxiliaryView

A front view or an isometric view are defined using the components of the two vectors defining its
projection plane in the 3D space.

The other views are all defined by giving the DrawingViewGenerativeBehavior object of their parent
view, and additional information:
• a projection view is defined using a view type which can be left, right, top, or bottom using the
CatProjViewType enumeration.
• a section view or section cut is defined using a section profile in the parent view and passed as
an array of point coordinates expressed with respect to the parent view axis system. Other
information is required, namely the section type, that is whether the section is a section cut or a
section view, the profile type, that is whether the section is aligned or offset, and the drawn side

128 Scripting with CATIA Programmer’s Guide

 5

of the section. This drawn side is determined as follows: the parent view is rotated clockwise or
counterclockwise around the first segment of the section profile oriented from its start point to
its end point.

Section view represents

section seen from this Counterlockwise
side on the parent view Section profile
Start point End point
Section profile
Clockwise
Start point End point 1st segment

1st segment Section view represents

section seen from that
side on the parent view

Parent view Parent view

• a detail view is defined from a parent view and using a clipping circle
• an auxiliary view is defined from a parent view and using a line which defines the trace of the
auxiliary view projection plane in the parent view.

129
5

Programming Tasks and Scenarios

The programming tasks and scenarios supplied here help you understand how to create macros that
you can run inside CATIA or from another application, and using which macro programming lan-
guage and environment. The scenarios covered are the following:

Scenarios Language and Environment

Creating a Front View and a Projection View VB Script or Basic Script

Creating a Section View VB Script or Basic Script

Creating a Detail View VB Script or Basic Script

Creating a Multi-Document Drawing VB Script or Basic Script

Generating Dimensions From Constraints VB Script or Basic Script

Updating All the Sheets of all the Drawings Contained in VB Script only
a Folder

Printing All the Sheets of all the Drawings Contained in VB Script only
a Folder

130 Scripting with CATIA Programmer’s Guide

 5

Creating a Front View and a Projection View

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a front view in the XY plane from a part, and then a projection
view.
The part document is opened in the macro.

1. Declare the language to use

Language = “VBScript“

2. Open the part

Dim PartToDraw As Document

Set PartToDraw = CATIA.Documents.Open(“e:\Users\Parts\MyPart.CAT-
Part“)

3. Create a drawing document. It becomes the active one

Dim MyDrawing As Document

Set MyDrawing = CATIA.Documents.Add(“Drawing”)

4. Retrieve the active sheet

Dim MySheet As DrawingSheet

Set MySheet = MyDrawing.Sheets.ActiveSheet

5. Create a front view in the active sheet

Dim MyFrontView As DrawingView

Set MyFrontView = MySheet.Views.Add(“Front View“)

6. Retrieve the front view generative behavior

Dim MyFrontViewGB As DrawingViewGenerativeBehavior

Set MyFrontViewGB = MyFrontView.GenerativeBehavior

7. Declare the part to draw in this front view

MyFrontViewGB.Document = PartToDraw

8. Define this view as an actual front view with the XY plane as projection plane

MyFrontViewGB.DefineFrontView 1, 0, 0, 0, 1, 0

131
5

9. Create another view named Left View

Dim MyLeftView As DrawingView

Set MyLeftView = MySheet.Views.Add(“Left View“)

10. Define it as a left view of the front view

MyLeftView.GenerativeBehavior.DefineProjectionView MyFrontViewGB,
catLeftView

The resulting macro is as follows.

Language = “VBScript“
Dim PartToDraw As Document
Set PartToDraw = CATIA.Documents.Open(“e:\Users\Parts\MyPart.CATPart“)
Dim MyDrawing As Document
Set MyDrawing = CATIA.Documents.Add(“Drawing”)
Dim MySheet As DrawingSheet
Set MySheet = MyDrawing.Sheets.ActiveSheet
Dim MyFrontView As DrawingView
Set MyFrontView = MySheet.Views.Add(“Front View“)
Dim MyFrontViewGB As DrawingViewGenerativeBehavior
Set MyFrontViewGB = MyFrontView.GenerativeBehavior
MyFrontViewGB.Document = PartToDraw
MyFrontViewGB.DefineFrontView 1, 0, 0, 0, 1, 0
Dim MyLeftView As DrawingView
Set MyLeftView = MySheet.Views.Add(“Left View“)
MyLeftView.GenerativeBehavior.DefineProjectionView MyFrontViewGB,
catLeftView

132 Scripting with CATIA Programmer’s Guide

 5

Creating a Section View

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a section view from an existing view.

The drawing document is already opened and active.

1. Declare the language to use

Language = “VBScript“

2. Retrieve the active drawing document.

Dim MyDrawing As Document

Set MyDrawing = CATIA.ActiveDocument

3. Retrieve the active sheet

Dim MySheet As DrawingSheet

Set MySheet = MyDrawing.Sheets.ActiveSheet

4. Retrieve the view you want to use as reference for the section view

Dim RefView As DrawingView

Set RefView = MySheet.Views.Item(“Front View”)

5. Retrieve the generative behavior for this reference view

Dim RefViewGB As DrawingViewGenerativeBehavior

Set RefViewGB = RefView.GenerativeBehavior

6. Create a view named Section View in the active sheet

Dim MySectionView As DrawingView

Set MySectionView = MySheet.Views.Add(“Section View“)

7. Retrieve the Section View generative behavior

Dim MySectionViewGB As DrawingViewGenerativeBehavior

Set MySectionViewGB = MySectionView.GenerativeBehavior

133
5

8. Define the profile to use for sectioning the reference view with four points

Dim SectionProfile(7)
SectionProfile(0) = -50
SectionProfile(1) = 160
SectionProfile(2) = -50
SectionProfile(3) = 30
SectionProfile(4) = 75
SectionProfile(5) = 30
SectionProfile(6) = 75
SectionProfile(7) = -50

9. Define the view named Section View as an actual section view of the reference view

MySectionViewGB.DefineSectionView SectionProfile, catSectionView, 0,

RefViewGB

The resulting macro is as follows.

Language = “VBScript“
Dim MyDrawing As Document
Set MyDrawing = CATIA.ActiveDocument
Dim MySheet As DrawingSheet
Set MySheet = MyDrawing.Sheets.ActiveSheet
Dim RefView As DrawingView
Set RefView = MySheet.Views.Item(“Front View”)
Dim RefViewGB As DrawingViewGenerativeBehavior
Set RefViewGB = RefView.GenerativeBehavior
Dim MySectionView As DrawingView
Set MySectionView = MySheet.Views.Add(“Section View“)
Dim MySectionViewGB As DrawingViewGenerativeBehavior
Set MySectionViewGB = MySectionView.GenerativeBehavior
Dim SectionProfile(7)
SectionProfile(0) = -50
SectionProfile(1) = 160
SectionProfile(2) = -50
SectionProfile(3) = 30
SectionProfile(4) = 75
SectionProfile(5) = 30
SectionProfile(6) = 75
SectionProfile(7) = -50
MySectionViewGB.DefineSectionView SectionProfile, “SectionView”,
“Aligned“, 0, RefViewGB

134 Scripting with CATIA Programmer’s Guide

 5

Creating a Detail View

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a section view from an existing view.

The drawing document is already opened and active.

1. Declare the language to use

Language = “VBScript“

2. Create a drawing document. It becomes the active one

Dim MyDrawing As Document

Set MyDrawing = CATIA.ActiveDocument

3. Retrieve the active sheet

Dim MySheet As DrawingSheet

Set MySheet = MyDrawing.Sheets.ActiveSheet

4. Retrieve the view you want to use as reference for the detail view, for example the front view

Dim RefView As DrawingView

Set RefView = MySheet.Views.Item(“Front View”)

5. Retrieve the generative behavior for this reference view

Dim RefViewGB As DrawingViewGenerativeBehavior

Set RefViewGB = RefView.GenerativeBehavior

6. Create a view named Detail View in the active sheet

Dim MyDetailView As DrawingView

Set MyDetailView = MySheet.Views.Add(“Detail View“)

7. Retrieve the Detail View generative behavior

Dim MyDetailViewGB As DrawingViewGenerativeBehavior

Set MyDetailViewGB = MyDetailView.GenerativeBehavior

8. Define the view named Detail View as an actual detail view of the reference view by giving a
point by its two coordinates, a radius, and the generative behavior object of the reference
view

MyDetailViewGB.DefineCircularDetailView 60, 40, 150, RefViewGB

135
5

The resulting macro is as follows.

Language = “VBScript“
Dim MyDrawing As Document
Set MyDrawing = CATIA.ActiveDocument
Dim MySheet As DrawingSheet
Set MySheet = MyDrawing.Sheets.ActiveSheet
Dim RefView As DrawingView
Set RefView = MySheet.Views.Item(“Front View”)
Dim RefViewGB As DrawingViewGenerativeBehavior
Set RefViewGB = RefView.GenerativeBehavior
Dim MyDetailView As DrawingView
Set MyDetailView = MySheet.Views.Add(“Detail View“)
Dim MyDetailViewGB As DrawingViewGenerativeBehavior
Set MyDetailViewGB = MyDetailView.GenerativeBehavior
MyDetailViewGB.DefineCircularDetailView 60, 40, 150, RefViewGB

136 Scripting with CATIA Programmer’s Guide

 5

Creating a Multi-Document Drawing

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to create a drawing using two different documents.

The part document is opened in the macro.

1. Declare the language to use

Language = “VBScript“

2. Open the part to draw

Dim PartToDraw As Document

Set PartToDraw = CATIA.Documents.Open(“e:\Users\Parts\MyPart.CAT-
Part“)

3. Open the product to draw

Dim ProductToDraw As Document

Set ProductToDraw = CATIA.Documents.Open(“e:\Users\Products\MyProd-
uct.CATProduct“

4. Create a drawing document. It becomes the active one

Dim MyDrawing As Document

Set MyDrawing = CATIA.Documents.Add(“Drawing”)

5. Retrieve the active sheet

Dim MySheet As DrawingSheet

Set MySheet = MyDrawing.Sheets.ActiveSheet

6. Create the front view for the part

Dim MyFrontView1 As DrawingView

Set MyFrontView1 = MySheet.Views.Add(“Part Front View“)

7. Retrieve the generative behavior for this front view

Dim MyFrontView1GB As DrawingViewGenerativeBehavior

Set MyFrontView1GB = MyFrontView1.GenerativeBehavior

8. Declare the part to draw in this front view

MyFrontView1GB.Document = PartToDraw

137
5

9. Define this view as an actual front view with the XY plane as projection plane

MyFrontViewGB1.DefineFrontView 1, 0, 0, 0, 1, 0

10. Create the front view for the product

Dim MyFrontView2 As DrawingView

Set MyFrontView2 = MySheet.Views.Add(“Product Front View“)

11. Retrieve the generative behavior for this front view

Dim MyFrontView2GB As DrawingViewGenerativeBehavior

Set MyFrontView2GB = MyFrontView2.GenerativeBehavior

12. Declare the product to draw in this front view

MyFrontView2GB.Document = ProductToDraw

13. Define this view as an actual front view with the ZX plane as projection plane

MyFrontView2GB.DefineFrontView 0, 0, 1, 1, 0, 0

The resulting macro is as follows.

Language = “VBScript“
Dim PartToDraw As Document
Set PartToDraw = CATIA.Documents.Open(“e:\Users\Parts\MyPart.CATPart“)
Dim ProductToDraw As Document
Set ProductToDraw = CATIA.Documents.Open(“e:\Users\Products\MyProd-
uct.CATProduct“
Dim MyDrawing As Document
Set MyDrawing = CATIA.Documents.Add(“Drawing”)
Dim MySheet As DrawingSheet
Set MySheet = MyDrawing.Sheets.ActiveSheet
Dim MyFrontView1 As DrawingView
Set MyFrontView1 = MySheet.Views.Add(“Part Front View“)
Dim MyFrontView1GB As DrawingViewGenerativeBehavior
Set MyFrontView1GB = MyFrontView1.GenerativeBehavior
MyFrontViewGB1.Document = PartToDraw
MyFrontViewGB1.DefineFrontView 1, 0, 0, 0, 1, 0
Dim MyFrontView2 As DrawingView
Set MyFrontView2 = MySheet.Views.Add(“Product Front View“)
Dim MyFrontView2GB As DrawingViewGenerativeBehavior
Set MyFrontView2GB = MyFrontView2.GenerativeBehavior
MyFrontView2GB.Document = ProductToDraw
MyFrontView2GB.DefineFrontView 1, 0, 0, 0, 1, 0

138 Scripting with CATIA Programmer’s Guide

 5

Generating Dimensions From Constraints

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to generate dimensions in a drawing document from the constraints set in
the referenced document(s).
The dimensions are generated in the active sheet of the active document, supposed to be a draw-
ing document.

1. Declare the language to use

Language = “VBScript“

2. Create a drawing document. It becomes the active one

Dim MyDrawing As Document

Set MyDrawing = CATIA.ActiveDocument

3. Retrieve the active sheet

Dim MySheet As DrawingSheet

Set MySheet = MyDrawing.Sheets.ActiveSheet

4. Generate the dimensions from the constraints

MySheet.GenerateDimensions()

The resulting macro is as follows.

Language = “VBScript“
Dim MyDrawing As Document
Set MyDrawing = CATIA.ActiveDocument
Dim MySheet As DrawingSheet
Set MySheet = MyDrawing.Sheets.ActiveSheet
MySheet.GenerateDimensions()

139
5

Updating All the Sheets of all the Drawings Contained in a Folder

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to update all the sheets of all the drawing documents contained in a given
folder according to the modifications performed in the documents they refer to since their cre-
ation or last update.
The folder scanned contains any documents, and only drawing documents are processed.

1. Declare the language to use

Language = “VBScript“

2. Set the file alerts to False

CATIA.DisplayFileAlerts = False

3. Request the end user to enter the appropriate folder name using an input box

path = InputBox(“Update drawings in: ”, “Drawing Update“,

“e:\Users\Drawings\“)
The first string is the text displayed in the input box, the second is the input box title, and the
third is the default value displayed in the input field when the input box is displayed.

4. Create the ActiveX object which handles folders

Dim folderHandler As Object

Set folderHandler = CreateObject(“Scripting.FileSystemObject”)

5. Retrieve the folder to process from its input path

Dim folder As Object

Set folder = folderHandler.GetFolder(path)

140 Scripting with CATIA Programmer’s Guide

 5

6. Loop on the files in the folder

For Each file in folder.Files

If file.Type = “CATIA Drawing” Then
Dim doc As Document
Set doc = CATIA.Documents.Open(file.Path)
Dim sheetcol As DrawingSheets
Set sheetcol = doc.Sheets
For I = 1 To sheetcol.Count
sheetcol.Item(I).Update()
Next
doc.Save()
doc.Close()
End If
Next

The resulting macro is as follows.

Language = “VBScript“
CATIA.DisplayFileAlerts = False
path = InputBox(“Update drawings in: ”, “Drawing Update“,
“e:\Users\Drawings\“)
Dim folderHandler As Object
Set folderHandler = CreateObject(“Scripting.FileSystemObject”)
Dim folder As Object
Set folder = folderHandler.GetFolder(path)
For Each file in folder.Files
If file.Type = “CATIA Drawing” Then
Dim doc As Document
Set doc = CATIA.Documents.Open(file.Path)
Dim sheetcol As DrawingSheets
Set sheetcol = doc.Sheets
For I = 1 To sheetcol.Count
sheetcol.Item(I).Update()
Next
doc.Save()
doc.Close()
End If
Next

141
5

Printing All the Sheets of all the Drawings Contained in a Folder

The resulting macro can be run in-process only. Refer to Running Out-process Macros to run it
out-process with Windows NT.

This task shows how to print all the sheets of all the drawing documents contained in a given
directory on the default printer.
The folder scanned contains any documents, and only drawing documents are printed.

1. Declare the language to use

Language = “VBScript“

2. Set the file alerts to False

CATIA.DisplayFileAlerts = False

3. Request the end user to enter the appropriate folder name using an input box

path = InputBox(“Print drawings in: ”, “Drawing Printing“,

“e:\Users\Drawings\“)
The first string is the text displayed in the input box, the second is the input box title, and the
third is the default value displayed in the input field when the input box is displayed.

4. Create the ActiveX object which handles folders

Dim folderHandler As Object

Set folderHandler = CreateObject(“Scripting.FileSystemObject”)

5. Retrieve the folder to process from its input path

Dim folder As Object

Set folder = folderHandler.GetFolder(path)

6. Loop on the files in the folder

For Each file in folder.Files

If file.Type = “CATIA Drawing” Then
Dim doc As Document
Set doc = CATIA.Documents.Open(file.Path)
Dim sheetcol As DrawingSheets
Set sheetcol = doc.Sheets
For Each sheet In sheetcol
sheet.Activate()
CATIA.ActiveWindow.PrintOut()
Next
doc.Close()
End If
Next

142 Scripting with CATIA Programmer’s Guide

 5

The resulting macro is as follows.

Language = “VBScript“
CATIA.DisplayFileAlerts = False
path = InputBox(“Print drawings in: ”, “Drawing Printing“,
“e:\Users\Drawings\“)
Dim folderHandler As Object
Set folderHandler = CreateObject(“Scripting.FileSystemObject”)
Dim folder As Object
Set folder = folderHandler.GetFolder(path)
For Each file in folder.Files
If file.Type = “CATIA Drawing” Then
Dim doc As Document
Set doc = CATIA.Documents.Open(file.Path)
Dim sheetcol As DrawingSheets
Set sheetcol = doc.Sheets
For Each sheet In sheetcol
sheet.Activate()
CATIA.ActiveWindow.PrintOut()
Next
doc.Close()
End If
Next

143
5

144 Scripting with CATIA Programmer’s Guide

CATIA Object Reference
6
You can access from this page to the CATIA object reference which provides reference information
for all the CATIA objects you can access, and for all other components such as the enumerated
types.

145
6

146 Scripting with CATIA Programmer’s Guide

 G

Glossary

A
application The root object that aggregates all the others in the CATIA object model
exposed for scripting.

C
collection An object that contains a set of objects of the same type.

D
document A common unit of data (typically a file) used in user tasks and exchanged
between users.

document window A window that provides a primary view of a document (typically its content).

J
journalling Recording user command sequences as macros coded using a scripting lan-
guage such as Visual Basic, to make it possible to replay them when required,
or to modify them to create other replayable macros.

M
macro A block of instructions that can be run. Synonym of script.

method A behavior associated with an object and implemented as a function or a sub-

routine.

147
 O
object The basic component of the CATIA exposed model for scripting. An object
stands for an entity you are used to handle through the end user interface, such
as a document, a window, a pad, a hole, or a circle. An object can expose prop-
erties and methods.

P
property A named attribute of an object.

S
script A block of instructions that can be run. Synonym of macro.

scripting engine A program that allows for scripting. Visual Basic Scripting Engine is hosted by
CATIA to allow for in-process access.

V
variable A named storage location that contains data a script or macro can modify.

148 Scripting with CATIA Programmer’s Guide