Assembly Design Journaling

Preface
Basic Tasks
Glossary
Index

Dassault Systmes 1994-2000. All rights reserved.

Preface
The CATIA - Assembly Design Journaling Guide has been designed to show you how to
create assembly constraint starting from a CATIA script document. This book aims at illustrating
the several stages of creation you may encounter.
The information contained in this guide is specific to Version 5 Release 5 of the CATIA Assembly Design workbench, which operates in a WINDOWS or UNIX workstation
environment under the AIX, IRIX, SUN OS and HP-UX operating system.

Basic Tasks

CATProduct Document
Assembly Basics
Assembly Constraints

CATProduct Document
New CATProduct
Open CATProduct

Create a CATProduct Document

Definition
Creates a new assembly.

Methods
Documents.Add
Creates a document object and adds it to the documents collection.
This document becomes the active one, and a window is created to accomodate it which
becomes the active window.
Syntax
Documents.Add ( iDocType ) as Document
iDocType as String
The type of the document to be created, here a CATProduct.
= "Product"
Example
CATIA.Documents.Add ( "Product" )

Running The Macro

1. Open CATIA.
2. Load the CreateCATProduct1.CATScript macro.
3. Run the macro.

Open a CATProduct Document

Definition
Open an existing product.

Methods
Documents.Open
Opens and reads a document stored in a file, displays it in a new window, adds the document to
the documents collection and the window to the windows collection, and makes both the
document and the window the active ones.
Syntax
Documents.Add ( iFileName ) as Document
iFileName as String
The string containing the document name and path to be opened.
Example
CATIA.Documents.Open ( "C:\ProductDirectory\UserProduct.CATProduct " )

Running The Macro

1. Open CATIA.
2. Check in OpenCATProduct.CATScript the path to the Assembly Design Journaling Guide
directory sample.
3. Load the OpenCATProduct1.CATScript macro.
4. Run the macro.

Assembly Basics
Properties
Reference
Update

Properties
Definition
Assembly properties.

Properties
Connections
Returns the collection object containing the constraints of the product.
Syntax
Product.Connections as Constraints
Example
AssemblyConstraintsCollection = UserAssembly.Connections

Product
Dimensions an object as assembly.
Example
Dim UserAssembly as Product

ProductDocument
Dimensions an object as assembly document.
Example
Dim UserAssemblyDocument as ProductDocument

Reference
Definition
References features in a assembly.

Methods
CreateReferenceFromName
Returns a reference from a name.
A reference is an object that can stand for any geometrical object.
Creating references is mandatory for adding constraints between two components using Brep
elements of the representations of these components.
Syntax
CreateReferenceFromName ( iLabel ) as Reference
iLabel as String
The GenericNaming identification for an object.
This is a cryptic form for "the edge surrounded by the face extruded from line.12 of
sketch.4 and the face...").
Example
Set UserReference = CATIA.ActiveDocument.Product.CreateReferenceFromName ( )

Properties
Reference
Dimensions an object as reference.
Example
Dim UserReference as Reference

References
Dimensions an object as a references collection.
Example
Dim UserReferencesCollection as References

Update
Definition
Updates an assembly.

Methods
Update
Updates the assembly.
Syntax
Update
Example
UserAssembly.Update

Assembly Constraints
Constraints
Coincidence Constraint
Contact Constraint
Angle Constraint
Fix Constraint
Deactivate Activate Constraint

Constraints
Definition
Constraints assembly components.

Methods
AddMonoEltCst
Creates a new constraint applying to a single geometric element and adds it to the constraints
collection.
Syntax
AddMonoEltCst ( iConstraintType, iElement ) as Constraint
iConstraintType as Long
The constraint type.
See Type syntax.
iElement as Reference
The geometric element to be constrained.
Example
Set UserConstraint = CATIA.ActiveDocument.Product.Constraints.AddMonoEltCst ( 0,
UserReference )

AddBiEltCst
Creates a new constraint applying to two geometric elements and adds it to the constraints
collection.
Syntax
AddBiEltCst ( iConstraintType, iFirstElement, iSecondElement ) as Constraint
iConstraintType as Long
The constraint type.
See Type syntax.
iFirstElement as Reference
The first geometric element to be constrained.
iSecondElement as Reference
The second geometric element to be constrained.
Example
Set UserConstraint = CATIA.ActiveDocument.Product.Constraints.AddBiEltCst ( 0,
UserReference1, UserReference2 )

AddTriEltCst
Creates a new constraint applying to three geometric elements and adds it to the constraints
collection.
Syntax
AddTriEltCst ( iConstraintType, iFirstElement, iSecondElement, iThirdElement ) as
Constraint
iConstraintType as Long
The constraint type.
See Type syntax.
iFirstElement as Reference
The first geometric element to be constrained.
iSecondElement as Reference
The second geometric element to be constrained.
iThirdElement as Reference
The second geometric element to be constrained.
Example
Set UserConstraint = CATIA.ActiveDocument.Product.Constraints.AddTriEltCst ( 0,
UserReference1, UserReference2, UserReference3 )

Activate
Activates a constraint.
An activated constraint is take into account during the update process.
Syntax
Activate
Example
UserConstraint.Activate

Deactivate
Deactivates a constraint.
An deactivated constraint is not take into account during the update process.
Syntax
Deactivate
Example
UserConstraint.Deactivate

IsInactive
Indicates if a constraint is take into account during the update process.
Syntax
IsInactive as Boolean

= True, the constraint is not active

= False, the constraint is active.
Example
ConstraintActivity = UserConstraint.IsInactive

GetConstraintElement
Gets a constraint's element.
Syntax
GetConstraintElement ( iElementIndex ) as Reference
iElementIndex as Long
The index of the element of the constraint to be returned.
= 1 for the first element.
= 2 for the second element.
Notice it must not exceed the total number of elements of the constraint. See Type syntax.
Example
UserReference = UserConstraint.GetConstraintElement ( 1 )

SetConstraintElement
Sets a constraint's element.
Syntax
SetConstraintElement ( iElementIndex, iElement ) as Reference
iElementIndex as Long
The index of the element of the constraint to be replaced.
= 1 for the first element.
= 2 for the second element.
Notice it must not exceed the total number of elements of the constraint. See Type syntax.
iElement as Reference
The element to be constrained.
Example
UserConstraint.GetConstraintElement ( 2, UserReference )

GetConstraintVisuLocation
Returns the constraint's visualisation location.
When displayed on screen, the constraint is visualized as a dimension positioned close to the
constrained geometric elements.
This method retrieves the data used to position this representation within the 3D space.
Syntax
GetConstraintVisuLocation ( oAnchorPoint, oAnchorVector )
oAnchorPoint as Double

A safe array with three elements : x, y, z point coordinates where the constraint value is
displayed.
The array must be previously initialized.
oAnchorVector as Double
A safe array with three elements : x, y, z vector normal to the plane coordinates onto which
the constraint value is displayed.
The array must be previously initialized.
Example
Dim ConstraintAnchorPoint ( 2 ), ConstraintAnchorVector ( 2 ) As Double
Dim xp, yp, zp, xv, yv, zv As Double
UserConstraint.GetConstraintVisuLocation ( ConstraintAnchorPoint,
ConstraintAnchorVector )
xp = ConstraintAnchorPoint ( 0 )
yp = ConstraintAnchorPoint ( 1 )
zp = ConstraintAnchorPoint ( 2 )
xv = ConstraintAnchorVector ( 0 )
yv = ConstraintAnchorVector ( 1 )
zv = ConstraintAnchorVector ( 2 )

SetConstraintVisuLocation
Sets the constraint's visualisation location.
Syntax
SetConstraintVisuLocation ( iX, iY, iZ )
iX, iY, iZ as Double
Origin point x, y, z absolute coordinates.
Example
UserConstraint.SetConstraintVisuLocation 10.000000, 0.000000, 0.000000

Item
Returns a constraint using its index or its name from the Constraints collection.
Syntax
Item ( iIndex ) as Constraint
iIndex as Long
The index or the name of the constraint to retrieve from the collection of constraints.
As a numerics, this index is the rank of the constraint in the collection.
The index of the first constraint in the collection is 1, and the index of the last constraint is
Count.:
Example

Set UserConstraint = CATIA.ActiveDocument.Part.Constraints.Item ( 1 )

Remove
Returns a constraint using its index or its name from the Constraints collection.
Syntax
Remove ( iIndex ) as Constraint
iIndex as Long
The index or the name of the constraint to remove from the collection of constraints.
As a numerics, this index is the rank of the constraint in the collection.
The index of the first constraint in the collection is 1, and the index of the last constraint is
Count.:
Example
Set UserConstraint = CATIA.ActiveDocument.Part.Constraints.Remove ( 1 )

Properties
AngleSector
Gets or sets the constraint's angle (or angular) sector, for angle constraint only, Type = 6.
The geometric elements of an angle constraint (e.g. : 2 lines or 2 planes) divide the space in 4
regions which are called angle or angular sectors, numbered from 0 to 3.
By default, the constraint is created in the sector number 0.
One angle sector corresponds exactly to particular values of Dimension.Value, Side and
Orientation.
When changing the angle sector, Dimension.Value, Side and Orientation are also modified.
Syntax
AngleSector as Long
= 0, Dimension.Value = angle, Orientation = 0, Side = 0
= 1, if angle>180: Dimension.Value= angle-180, otherwise: Dimension.Value=
abs(angle)+180, Orientation = 1, Side = 0.
= 2, if angle>180: Dimension.Value = abs(540-angle), otherwise: Dimension.Value =
180-abs(angle), Orientation = 1, Side = 1.
= 3, Dimension.Value = 360-abs(angle), Orientation = 0, Side = 1.
Example
ConstraintAngleSector = UserConstraint.AngleSector
UserConstraint.AngleSector = 0

BrokenConstraintsCount
Gets the number of broken constraints from the constraints collection.
Syntax

BrokenConstraintsCount as Long
Example
BrokenConstraints = UserConstraintsCollection.BrokenConstraintsCount

Constraint
Dimensions an object as constraint.
Example
Dim UserConstraint as Constraint

Constraints
Dimensions an object as a constraints collection.
Example
Dim UserConstraintsCollection as Constraints

Dimension.Value
Gets or sets the constraint's dimension.
The dimension may be meaningless for some types of constraints such as tangency constraints,
or if the constraint is not currently checked, see Status syntax.
Syntax
Dimension.Value as Double
Example
ConstraintDimension = UserConstraint.Dimension.Value
UserConstraint.Dimension.Value = 50.00000

DistanceConfig
Gets or sets the constraint's distance configuration, for distance constraint only, Type = 1.
Distance constraints between lines and cylinders offer often more degrees of freedom to
geometry than acually desired.
This property allows user to limit these degrees of freedom without having to redefine additional
constraints.
Syntax
DistanceConfig as Long
= 0, no additional condition is set on the constraint.
= 1, in addition to being positioned at a specified distance, constrained elements are
required to be parallel.
Their orientation can be the same or opposite.
= 2, in addition to being positioned at a specified distance, constrained elements are
required to be parallel, and their orientations are required to be the same.
= 3, in addition to being positioned at a specified distance, constrained elements are
required to be parallel, and their orientations are required to be opposite.
Example

ConstraintDistanceConfiguration = UserConstraint.DistanceConfig
UserConstraint.DistanceConfig = 0

DistanceDirection
Gets or sets the distance's constraint direction.
This property is useless for constraints whose type is not Distance, Type =1.
Distance constraints may be measured along a particular direction.
This property will be used if the direction is a reference axis.
Syntax
DistanceDirection as Long
= 0, no direction has been specified. The constraint is measured as usual.
= 1, the constraint is measured along the X axis.
= 2, the constraint is measured along the Y axis.
= 3, the constraint is measured along the Z axis.
Example
ConstraintDistanceDirection = UserConstraint.DistanceDirection
UserConstraint.DistanceDirection = 0

Mode
Gets or sets the constraint's driving mode.
For constraint types supporting the concept of value, such as distance constraints, the driving
mode tells whether the constraint value actually drives the geometry position, or, conversely, is
driven by it.
Syntax
Mode as Long
= 0, the constraint mode, the value assigned to the constraint drives the actual position of
the constrained geometry.
= 1, the measure mode, the constraint value only reflects what can be observed from the
actual position of the constrained geometry.
Example
ConstraintMode = UserConstraint.Mode
UserConstraint.Mode = 1

Orientation
Gets or sets the constraint's orientation.
This is used for constraints that involve two geometric elements and specifies the orientation for
the second geometric element with regard to the first one, when several possible orientations are
all satisfying the constraint.
Syntax
Orientation as Long
= 0, the characteristic vectors associated to the constrained elements have same
orientation.

= 1, the characteristic vectors associated to the constrained elements have opposite

orientation.
= 2, the relative orientation of the characteristic vectors associated to the constrained
elements is not specified.
Example
ConstraintOrientation = UserConstraint.Orientation
UserConstraint.Orientation = 0

Side
Gets or sets the constraint's side.
Some constraint types need to relatively position the constrained geometries, when several
possible configurations are all satisfying the constraint.
Syntax
Side as Long
= 0, the first constrained element characteristic vector points towards the second
constrained element.
Arithmetic sign of constraint value is ignored, only its absolute value is taken into account.
= 1, the first constrained element characteristic vector points is opposite to the second
constrained element.
Arithmetic sign of constraint value is ignored, only its absolute value is taken into account.
= 2, the arithmetic sign of constraint value specifies where the second element lies with
regard to the first one: a positive value means in the direction of first constrained element
characteristic vector, a negative value in the opposite direction.
= 3, Arithmetic sign of constraint value specifies where second element lies with regard to
first one: a negative value means in the direction of first constrained element characteristic
vector, a positive value in the opposite direction.
= 4, the relative positionning of constrained elements is not defined.
Example
ConstraintSide = UserConstraint.Side
UserConstraint.Side = 1

Status
Gets the constraint's status.
The constraint's status is a diagnosis if the constraint is checked.
Syntax
Status as Long
= 0, the constraint is checked.
= 1, the constraint is strongly not checked (e.g. distance constraint between two planes,
which are not currently parallel).
= 2, the constraint is not checked because of the wrong orientation or side of its geometric
elements (e.g. planes are parallel and at the specified distance, but their orientation is
inverted with respect to the one specified by the constraint).
= 3, the constraint is not checked because of its value (e.g. planes are parallel and at the

specified orientation and side but not at the specified distance).

= 4, the constraint is not checked because of the wrong type of its geometric elements
(e.g. angle between a point and a plane).
= 5, the constraint is not checked because a geometric element is missing.
Example
ConstraintStatus = UserConstraint.Status

Type
Gets or sets the constraint's type.
Syntax
Type as Long
= 0, Fix only with AddMonoEltCst.
= 1, Distance only with AddBiEltCst.
= 2, Coincidence only with AddBiEltCst.
= 6, Angle only with AddBiEltCst.
= 7, Planar Angle only with AddTriEltCst .
= 8, Parallelism only with AddBiEltCst.
= 11, Perpendicularity only with AddBiEltCst.
= 20, Surfacic Contact only with AddBiEltCst.
= 21, Lineic Contact Angle only with AddBiEltCst .
= 22, Point Contact only with AddBiEltCst.
= 25, Annular Contact only with AddBiEltCst.
Example
ConstraintType = UserConstraint.Type
UserConstraint.Type = 1

UnUpdatedConstraintsCount
Gets the number of not updated constraints from the constraints collection.
Syntax
BrokenConstraintsCount as Long
Example
BrokenConstraints = UserConstraintsCollection.BrokenConstraintsCount

Coincidence Constraint
Definition
Creates a coincidence constraint between two assembly components.

Running The Macro

1. Open the CoincidenceConstraint.CATProduct document.

2. Load the CoincidenceConstraint2.CATScript macro.

3. Run the macro.

Contact Constraint
Definition
Creates a contact constraint between two assembly components.

Running The Macro

1. Open the ContactConstraint1.CATProduct document.

2. Load the ContactConstraint1.CATScript macro.

3. Run the macro.

Angle Constraint
Definition
Creates an angle constraint between two assembly components.

Running The Macro

1. Open the AngleConstraint1.CATProduct document.

2. Load the AngleConstraint1.CATScript macro.

3. Run the macro.

Fix Constraint
Definition
Creates a fix constraint on one assembly component.

Running The Macro

1. Open the FixConstraint1.CATProduct document.

2. Load the FixConstraint1.CATScript macro.

3. Run the macro.

Deactivate Activate Constraint

Definition
Deactivates or activates an assembly constraint.

Running The Macro

1. Open the DeactivateActivateConstraint1.CATProduct document.

2. Load the DeactivateConstraint1.CATScript macro.

3. Run the macro.

4. Load the ActivateConstraint1.CATScript macro.

5. Run the macro

Glossary
A
active component

A selected component currently being edited. This component is

underlined in the specification tree.

active object

An object currently being edited.

angle constraint

A constraint used to define an angle or parallelism between two

geometric elements.

assembly

An entity composed of various components which have been positioned

relative to each other.

B
bill of material

A list of data about the properties of the components contained in the

active component.

C
child component

One or more components originating from a single component. Compare

parent component.

coincidence
constraint

A constraint used to align two geometric elements, or get them to

coincide.

component

A reference integrated in an assembly. A component possesses

characteristics related to how it is integrated in an assembly (for
example, its relative location in an assembly).

constraint

A geometrical or dimensional relation between several geometric

elements of different components. It may be used to define the
positioning of components.

context-specific
representation

A hierarchical design of an assembly in a specific context (for example:

engineering or manufacturing).

contact constraint A constraint used to define a contact area between two elements
(tangent or coincident).

F
fixed component

A component for which all degrees of freedom are locked, in relation to

the parent component.

G
geometric element The geometric elements which can be constrained in the Assembly
workbench are:
point
line
plane (or plane surface from a model)
sphere
cone
cylinder

L
leaf component

The last component at the end of each branch of the specification tree.

M
manipulation

A freehand translation or rotation of a component with the mouse.

model

A CATIA Version 4 model.

O
offset constraint

A constraint used to define a distance or an offset between two

geometric elements.

P
parent component A component that is hierarchically just above one or more components.
Compare child component
part

Within the Assembly workbench, it is either a part of the Part Design

workbench, or a 3D entity whose geometry is contained in a model.

primary child
component

One or more components originating from the first level under the active
component.

product

A 3D entity which contains several components.

R
reference

A product or part with its own characteristics. Compare component.

representation

See context specific representation.

S
search order

A hierarchical set of paths used when searching for the files included in
the assembly. The search begins with the first path, and stops when the
file is found.

snap

Projects a geometric element onto another one.

subassembly

An assembly contained within another assembly.

U
update

In the Assembly workbench, updates the position of the constrained

components so as to satisfy the constraint requirements.

Index
A
Activate
AddBiEltCst
AddMonoEltCst
AddTriEltCst
AngleSector

B
BrokenConstraintsCount

C
Connections
Constraint
Constraints
CreateReferenceFromName

D
Deactivate
Dimension.Value
DistanceConfig
DistanceDirection
Documents.Open

G
GetConstraintElement
GetConstraintVisuLocation

I
IsInactive
Item

M
Mode

O
Orientation

P
Product
ProductDocument

R
Reference
References
Remove

S
SetConstraintElement
SetConstraintVisuLocation
Side
Status

T
Type

U
UnUpdatedConstraintsCount
Update