TopSolid’Design Automation Guide

Automation Guide
TopSolid'Design

MASTER YOUR
MANUFACTURING PROCESS
Missler Software i
 TopSolid’Design Automation Guide

© 2017, Missler Software.

7, Rue du Bois Sauvage
F-91055 Evry, FRANCE
Web : http://www.topsolid.com
E-mail : [email protected]
All rights reserved.

This information is subject to change without warning.

No material may be reproduced or transmitted, regardless of the manner, electronic or mechanical means
used or purpose, without formal written consent from Missler Software.

TopSolid ® is a registered trademark of Missler Software.

TopSolid ® is a product name of Missler Software.

The information and the software contained within this document are subject to change without prior
warning and should not be construed as a commitment by Missler Software.

The software covered by this document is supplied under license, and may only be used and duplicated
in compliance with the terms of this license.

EN v7.11.

ii Missler Software
TopSolid’Design Automation Guide

Contents
Introduction............................................................................................... 1
Contents..............................................................................................................................2
Skills....................................................................................................................................2
Tools ...................................................................................................................................2
Architecture .........................................................................................................................2
Commands..........................................................................................................................3

Getting Started.......................................................................................... 5
Visual Studio Project ...........................................................................................................6
Deployment .........................................................................................................................7
Connecting ..........................................................................................................................7
Automating ..........................................................................................................................9
Version ................................................................................................................................9
Units ....................................................................................................................................9
Modifying.............................................................................................................................9

PDM.......................................................................................................... 11
Introduction .......................................................................................................................12
Identifiers...........................................................................................................................12
Revisions...........................................................................................................................12
Search by Identifiers .........................................................................................................13
Search by Universal Identifiers .........................................................................................14

Documents .............................................................................................. 17
Introduction .......................................................................................................................18
Identifiers...........................................................................................................................18
PDM ..................................................................................................................................18
Modifying...........................................................................................................................18

Elements.................................................................................................. 21
Introduction .......................................................................................................................22
Identifiers...........................................................................................................................22
Names...............................................................................................................................22
Items .................................................................................................................................22

Parameters .............................................................................................. 25
Introduction .......................................................................................................................26
Types ................................................................................................................................26
Reals .................................................................................................................................26
Smart Objects ...................................................................................................................26
User Properties .................................................................................................................27

Geometries .............................................................................................. 29
Introduction .......................................................................................................................30
Types ................................................................................................................................30

Missler Software iii

 TopSolid’Design Automation Guide

Smart Objects ...................................................................................................................31

Sketches .................................................................................................. 33
Introduction .......................................................................................................................34
Frames ..............................................................................................................................34
Topologies.........................................................................................................................34
Exploring ...........................................................................................................................35
Creating.............................................................................................................................36
Modifying...........................................................................................................................37

Shapes ..................................................................................................... 39
Introduction .......................................................................................................................40
Topologies.........................................................................................................................40

Events ...................................................................................................... 41
Introduction .......................................................................................................................42
Architecture .......................................................................................................................42
Contract Implementation ...................................................................................................42
Client Name ......................................................................................................................43
Events Handling ................................................................................................................43

Remote Access ....................................................................................... 45

Introduction .......................................................................................................................46
Architecture .......................................................................................................................46
Settings .............................................................................................................................46
Connecting ........................................................................................................................46
Events ...............................................................................................................................47

Multiple Access....................................................................................... 49
Introduction .......................................................................................................................50
Architecture .......................................................................................................................50
Processes .........................................................................................................................50
Connecting ........................................................................................................................51

Glossary .................................................................................................. 53

Index ........................................................................................................ 55

iv Missler Software
Introduction TopSolid’Design Automation Guide

Introduction

Missler Software 1
Introduction TopSolid’Design Automation Guide

Contents
This document explains how to drive TopSolid’Design (or TopSolid, for short) from another
application, to automate some frequent tasks.
Automation can often significantly increase productivity, and reduce risk of making errors, so
the investment needed to implement it is very quickly paid off by the benefits.
For instance, if your industrial process commonly requires to set the part number of all the
parts of a project according to the values found in an Excel sheet, it will be worthwhile
automating it instead of spending valuable time every time it needs doing.

Skills
This documentation makes the assumption that you are a fully trained TopSolid user, all the
usual TopSolid terminology (project, part, assembly, entity, operation, parameter...) will be
used without any explanation (you will find some in the TopSolid user documentation).
Automation is performed by writing a program, so some minimum programming skills are
required.
It is possible to use several programming languages, as far as they are compatible with
Microsoft .NET Framework, the most common being C# and Visual Basic.
This documentation makes the assumption that you are using C#, so you will need to translate
some provided code sample into your own development language if you are not using C#.

Tools
To develop and test your program, you will need some tools that are usually part of an
integrated development environment (IDE).
Several IDEs are commercially available, but this documentation makes the assumption that
you are using Microsoft Visual Studio, so again if you are using another IDE, you will need to
perform some translation when some descriptions are related to the IDE.

Architecture
Your application may be a standalone application, or an add-in to another application (like for
instance an Excel add-in), it will run in its own process, and it will drive TopSolid which is
running in its own process by an inter-process protocol called WCF (Windows Communication
Foundation).

Your Application TopSolid

WCF

Process 1

Process 2

2 Missler Software
TopSolid’Design Automation Guide Introduction

Your application will in fact take the place of a "physical" user, and perform by program some
of the actions that can be manually performed using TopSolid menu commands.
The detailed reference of each method or property of TopSolid Automation API is available in
a companion document "TopSolid’Design Automation.chm" that will be called afterwards
"TopSolid Automation Help".

Commands
Users will be able to start your application directly from TopSolid by associating it to a menu
command.
This can be done in TopSolid by executing the command "Tools > Customize...", and using the
"Add a File to Execute" section.

Missler Software 3
Introduction TopSolid’Design Automation Guide

4 Missler Software
Getting Started TopSolid’Design Automation Guide

Getting Started

Missler Software 5
Getting Started TopSolid’Design Automation Guide

Visual Studio Project

To start developing an application automating some TopSolid tasks, you first need to have a
Visual Studio project, like for instance a "Windows Forms Application" that you can create
using the "File > New > Project..." command in Visual Studio:

To be able to use TopSolid automation, you will need to reference TopSolid "Automating" DLLs
that are located in TopSolid install folder:

• TopSolid.Kernel.Automating.dll (TopSolid base functionalities).

• TopSolid.Cad.Design.Automating.dll (TopSolid’Design add-in functionalities).
• TopSolid.Cad.Drafting.Automating.dll (TopSolid’Drafting add-in functionalities).

6 Missler Software
TopSolid’Design Automation Guide Getting Started

Once this is done, you will be able to use TopSolid namespaces in your application, and
usually insert the following lines at the top of your C# files:

using TopSolid.Kernel.Automating;
using TopSolid.Cad.Design.Automating;
using TopSolid.Cad.Drafting.Automating;

Deployment
TopSolid Automating DLLs are freely redistributable, you are allowed to (and in fact obliged
to!) deliver them with your application.
Usually, it is best to install them in the same folder than your ".EXE" file in your application
Setup.

Connecting
Your application must first connect to TopSolid, which is simply done by the following lines of
code:

TopSolidHost.Connect();
TopSolidDesignHost.Connect();
TopSolidDraftingHost.Connect();

Missler Software 7
Getting Started TopSolid’Design Automation Guide

If TopSolid is not running, "TopSolidHost.Connect()" will actually start it automatically.

It is often required that your application terminates when TopSolid is closed, which can be
done by using the "Exited" event exposed by the static class TopSolidHost.
When your application terminates, it must disconnect from TopSolid using the "Disconnect"
methods.
Therefore in the simplest cases, your Main program may look like this:

using System;
using System.Windows.Forms;
using TopSolid.Cad.Design.Automating;
using TopSolid.Cad.Drafting.Automating;
using TopSolid.Kernel.Automating;

namespace MyApplication
{
static class Program
{
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
TopSolidHost.Connect();
TopSolidDesignHost.Connect();
TopSolidDraftingHost.Connect();

TopSolidHost.Exited += new EventHandler(TopSolid_Exited);

Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new Form1());

TopSolidDraftingHost.Disconnect();
TopSolidDesignHost.Disconnect();
TopSolidHost.Disconnect();
}

static private void TopSolid_Exited(object sender, EventArgs e)

{
Application.Exit();
}
}
}

8 Missler Software
TopSolid’Design Automation Guide Getting Started

Automating
Once successfully connected to TopSolid, your application will be able to perform some
automation by calling methods and properties exposed in interfaces accessible as properties
of TopSolidHost, TopSolidDesignHost and TopSolidDraftingHost.
These interfaces are described in TopSolid Automation Help.
For instance, to access TopSolid documents it will be possible to use the methods and
properties of the interface IDocuments returned by the property TopSolidHost.Documents.
Getting the document currently edited will therefore be coded as follows:

DocumentId docId = TopSolidHost.Documents.EditedDocument;

Version
Once connected to TopSolid, you will be able to know its version, which is available as a
property of TopSolidHost (TopSolidHost.Version).
If the version of the connected TopSolid is anterior to the version of the automation API used
for generating your application, some methods or properties may not be used as they are not
yet available.
You will find the availability of each method or property in TopSolid Automation Help, and need
to check if they are available before using then, otherwise an exception will be thrown.

if (TopSolidHost.Version >= 706000000)

{
TopSolidHost.Application.NewMethod(); // New method in v7.6.
}

Units
Values are sent to, and received from TopSolid using the International System of Units (also
called SI units), even if they are exposed to the user using other units.
Therefore angles are in radians, lengths in meters, volumes in cubic meters, masses in
kilograms...
Coordinates of points are, like lengths, in meters.

Modifying
Your application may access TopSolid to extract some information, but it may also perform
some modification of TopSolid data.
Getting information may be done at any time, but modifying cannot.
To modify the contents of TopSolid documents, your application will have to inform TopSolid
that some modification is going to be performed before doing so by calling
TopSolidHost.Application.StartModification, and once the modification has been completed,
it will have to signal that it is finished by calling TopSolidHost.Application.EndModification.
StartModification may fail if TopSolid is not currently available (for instance if the user is
running a menu command), so your application must manage that fact.
If StartModification succeeds, TopSolid will be unavailable to the user until EndModification is
called, so your application must always call it as soon as the current modification is over.
If you forget to call EndModification, TopSolid will stay locked forever and the user will have to
kill the process and loose its modifications, therefore great care is needed!
Most of the time, the appropriate code will look like this:

Missler Software 9
Getting Started TopSolid’Design Automation Guide

if (!TopSolidHost.Application.StartModification("My Action", false)) return;

try
{
// Perform modification.

...

// End modification (success).

TopSolidHost.Application.EndModification(true, true);
}
catch
{
// End modification (failure).

TopSolidHost.Application.EndModification(false, false);
}

When possible, the documents modifications performed will be undoable by the user like for
TopSolid commands.
Other types of modifications (like for instance Checking-in a document) are not undoable and
must not be performed within a StartModification / EndModification sequence.
When a method cannot be called at any time but only within or outside a StartModification /
EndModification sequence, it is usually mentioned in the "Remarks" section of its specification.

10 Missler Software
PDM TopSolid’Design Automation Guide

PDM

Missler Software 11
PDM TopSolid’Design Automation Guide

Introduction
Access to TopSolid’Pdm will be possiblle using the methods of IPdm interface returned by the
property TopSolidHost.Pdm.

Identifiers
The objects managed by TopSolid’Pdm are identified by "PDM object identifiers", represented
by the type PdmObjectId.
When you ask TopSolid for a project, or one of its folders or documents, the API will return the
information using such an identifier.
The identifier may be empty (when its property "IsEmpty" is true), in which case it does not
represent any object. This is useful as it allows to mean "no object".
For instance, when searching for a project of a specified name, if the identifier returned is
empty, it means that there is no project with that name.

Revisions
A PDM object may have several major revisions, and each major revision may have several
minor revisions, the last one being the final state.

PDM Object Final State

Major Rev. B

Minor Rev. 2

Minor Rev. 1

Minor Rev. 0

Major Rev. A

Minor Rev. 0

12 Missler Software
TopSolid’Design Automation Guide PDM

Major revisions are identified by a PdmMajorRevisionId, and minor revisions are identified by
a PdmMinorRevisionId.
It is possible to obtain the major revisions of a PDM object using the method
TopSolidHost.Pdm.GetMajorRevisions(PdmObjectId).
It is possible to obtain the minor revisions of a major revision using the method
TopSolidHost.Pdm.GetMinorRevisions(PdmMajorRevisionId).

Search by Identifiers
There are several ways of finding a specific PDM object, but the most common one is by its
identifier.
Typically, if you want to set the material of a part equal to the "Steel" standard material, your
application must first find the document defining the steel material in the "TopSolid
Mechanical" library.
To do so, you must start TopSolid in advanced mode (using the "-a" option), select the
document in the library tree, and use the "Tools > Identifiers" context command.

Missler Software 13
PDM TopSolid’Design Automation Guide

The identifier will be displayed in the "ObjectId (Automation)" field:

The PDM object identifier of the document is available as a text, that must be copied, and
used directly in the PdmObjectId constructor in your application.
For instance, here is a code sample to get the name of the steel standard material document.

PdmObjectId steelId = new PdmObjectId(

"19_79a94aa1-c547-4811-ab0f-57f623cde11f&458753_598");
if (!TopSolidHost.Pdm.Exists(steelId)) return;

string steelName = TopSolidHost.Pdm.GetName(steelId);

To be sure the document exists in the PDM of the user running your application, it is advised to
check it by using the TopSolidHost.Pdm.Exists(PdmObjectId) method, as shown in the
sample. Otherwise an exception will be thrown when attempting to use it in other methods
(typically, if there is no document corresponding to the identifier provided, the
TopSolidHost.Pdm.GetName(PdmObjectId) method would throw an exception).

Search by Universal Identifiers

When documents are transferred from one PDM to another one by replication, they keep their
identifier.
This is why the identifier of the steel material document in one PDM is the same than on any
other PDM.
When importing a package by copy, new documents are created, with new identifiers.
Therefore, if you want to find the transferred document you must use another way.
One possibility would be the name of the document, but there is a risk that another document
with the same name already exists in a project.
A more stable way is provided, by creating a unique identifier, called a "universal identifier" in
a document.
To do so, you must start TopSolid in advanced mode (using the "-a" option), and use the
"Construction > Parameters > Universal Identifier... " menu command.
You need to enter a unique domain name (for instance the name of your company), and a
name that must be unique inside that domain.
You will then be able to send such documents to other PDMs without replication, and still be
able to find them by program in your application using the
TopSolidHost.Pdm.SearchDocumentByUniversalId method.

14 Missler Software
TopSolid’Design Automation Guide PDM

PdmObjectId objectId = TopSolidHost.Pdm.SearchDocumentByUniversalId(

PdmObjectId.Empty, "Domain", "Name");

Missler Software 15
PDM TopSolid’Design Automation Guide

16 Missler Software
Documents TopSolid’Design Automation Guide

Documents

Missler Software 17
Documents TopSolid’Design Automation Guide

Introduction
Access to TopSolid documents will be possiblle using the methods of IDocuments interface
returned by the property TopSolidHost.Documents.

Identifiers
TopSolid documents are identified by "document identifiers", represented by the type
DocumentId.
When you ask TopSolid for a specified document the API will return the information using such
an identifier, and when you want to perform some action on a document you will need to give
its identifier to the API.
The identifier may be empty (when its property "IsEmpty" is true), in which case it does not
represent any document. This is useful as it allows the meaning "no document".
For instance, when getting the document being edited using the "EditedDocument" property, if
the identifier returned is empty, it means that there is no document being edited at the
moment.

DocumentId docId = TopSolidHost.Documents.EditedDocument;

if (docId.IsEmpty) return;

You may give an empty document identifier to the API by passing DocumentId.Empty as
argument.

PDM
More precisely, the document identifier corresponds to a specific minor revision of a PDM
object of type TopSolid document, when a new revision is produced, it will have a new
identifier.
It is possible to obtain the document corresponding to the last minor revision of a PDM
TopSolid document using the method TopSolidHost.Documents.GetDocument(PdmObjectId).
Reciprocally, it is possible to obtain the PDM object corresponding to a specific document
using the method TopSolidHost.Documents.GetPdmObject(DocumentId).
It is possible to obtain the document corresponding to a specific minor revision of a PDM
TopSolid document using the method
TopSolidHost.Documents.GetMinorRevisionDocument(PdmMinorRevisiontId).
Reciprocally, it is possible to obtain the PDM minor revision corresponding to a specific
document using the method TopSolidHost.Documents.GetPdmMinorRevision(DocumentId).

Modifying
Every time your application needs to modify a document, it will have to ensure that the
document is in a modifiable state by calling TopSolidHost.Documents.EnsureIsDirty, bearing
in mind that this could fail when for instance it is checked-out by another user in a client-server
PDM situation.
Typically, every time you want to modify the document being edited, you will have to code
something like this:

// Get edited document.

if (!TopSolidHost.IsConnected) return;
DocumentId docId = TopSolidHost.Documents.EditedDocument;

18 Missler Software
TopSolid’Design Automation Guide Documents

if (docId.IsEmpty) return;

// Start modification.

if (!TopSolidHost.Application.StartModification("My Action", false)) return;

// Modify document.

try
{
// Make document modifiable.

TopSolidHost.Documents.EnsureIsDirty(ref docId);

// Perform document modification.

...

// End modification (success).

TopSolidHost.Application.EndModification(true, true);
}
catch
{
// End modification (failure).

TopSolidHost.Application.EndModification(false, false);
}

Care must be taken when using document identifiers, and in particular attention paid to the
fact that when a document that has just been saved is modified, a new revision is created,
which will have a new document identifier.
This is why the method "EnsureIsDirty" that makes sure that a document is in a modifiable
state before performing modifications uses the "ref" keyword for the argument.

// Here "docId" represents a specific revision of a TopSolid document.

TopSolidHost.Documents.EnsureIsDirty(ref docId);

// Here "docId" may have been modified to represent a new revision

// of the document that may have been created if needed.

If the document identifier was also stored in another variable than "docId", using that out-of-
date value to modify the document after calling this method would lead to a bug, as it would
correspond to the read-only previous revision of the document.

Missler Software 19
Documents TopSolid’Design Automation Guide

20 Missler Software
Elements TopSolid’Design Automation Guide

Elements

Missler Software 21
Elements TopSolid’Design Automation Guide

Introduction
Basically, a TopSolid document contains elements, that may be of different kinds: entities,
operations...
Access to TopSolid elements will be possiblle using the methods of IElements interface
returned by the property TopSolidHost.Elements.

Identifiers
Elements are identified by "element identifiers", represented by the type ElementId.
When you ask TopSolid for a specified element the API will return the information using such
an identifier, and when you want to perform some action on an element you will need to give
its identifier to the API.
The identifier may be empty (when its property "IsEmpty" is true), in which case it does not
represent any element. This is useful as it allows to mean "no element".
You may give an empty element identifier to the API by passing ElementId.Empty as
argument.
An element always belongs to a specific document, which identifier may be obtained by the
property "DocumentId" of the element identifier.

Names
In TopSolid, some elements have got a name which is unique in the document, this in
particular is the case for parameters, or other simple entities created using the "Construction"
menu (points, axes, planes, ...).
It is often needed to retrieve such elements by program, this can be done using the method
SearchByName().
The name of system elements is translated into the user’s local language in the user interface,
so to find them using the SearchByName() method you need to know their "real" name before
translation.
This can be done by launching TopSolid in advanced mode (with the "-a" command line
option), and using the advanced contextual command "System Name..." available in the
"Others" sub-menu when selecting a system element.
For instance, thanks to this command you will find out that the real name of the absolue frame
of a part document is "$TopSolid.Kernel.DB.D3.Documents.ElementName.AbsoluteFrame"!

Items
It is sometimes needed to identify a subpart of an element, for instance an edge or a face of a
shape entity.
These element subparts are called "element items", they will be identified by "item labels",
represented by the type ItemLabel.
The item label identifies the item within the element, which is supposed to be already known,
therefore an element item is in fact completely identified by specifying the pair (ElementId,
ItemLabel), "ElemenId" specifying the element, and "ItemLabel" specifying the item within the
element.
The pair (ElementId, ItemLabel) is encapsulated into the dedicated type ElementItemId called
element item identifier.
When you ask TopSolid for a specified element item the API will return the information using
an element item identifier, and when you want to perform some action on an element item you
will need to give its element item identifier to the API.
Here is a code sample that gets the edges connected to a specified shape face:

22 Missler Software
TopSolid’Design Automation Guide Elements

// Get face identifier.

ElementItemId faceId;

...

// Get edges connected to the face.

List<ElementItemId> edgeIds = TopSolidHost.Shapes.GetFaceEdges(faceId);

Missler Software 23
Elements TopSolid’Design Automation Guide

24 Missler Software
Parameters TopSolid’Design Automation Guide

Parameters

Missler Software 25
Parameters TopSolid’Design Automation Guide

Introduction
Some of the most frequent tasks to automate involve getting or setting the value of document
parameters.
This will be possiblle using the methods of IParameters interface returned by the property
TopSolidHost.Parameters.
Parameters are entities, and therefore elements, they are identified using element identifiers.
It is possible to get all the parameters of the parameters folder of a document using the
method "GetParameters".
When looking for a parameter knowing its name, it is faster to get it directly using the method
IElements.SearchByName().
Some frequently used system parameters may be obtained by a dedicated method, like
GetAuthorParameter() which gets the parameter "Author" of a document.

Types
TopSolid manages many types of parameters, most of them being accessible through
Automation.
The supported types are listed in the enumeration ParameterType.
It is possible to know the type of a parameter using the method GetParameterType().
It is possible to get or set the value of a parameter of type "Xyz" by the methods
GetXyzValue() and SetXyzValue().

Reals
One of the most used type is the real parameter, which is used to represent a real value with a
unit, like "8.5mm".
The type of unit (Length, Mass, ...) of the parameter and the specific unit used to expose it to
the user defined by its symbol ("mm", "kg", ...) may be obtained using the GetRealUnit()
method.
The value of the parameter given by the GetRealValue() method is in SI units.
It is possible to access the available units using the IUnits interface returned by the property
TopSolidHost.Units.

Smart Objects
In TopSolid, when for instance creating an offset point at a specified distance from a specified
origin point in a specified direction, it is possible to enter different types of values for the
distance.
One can:
• enter a basic real value like "10mm",
• give the name of a length parameter, like "d",
• enter a formula mixing basic values and parameters like "2 * d + 5mm",
• select a circular edge, meaning the diameter of the circle,
• ...
Therefore it must be possible to do the same by program when automating this task.
To do so, instead of using simple objects like "double" or "int" as arguments, new types of
objects will be available, called smart objects.
For instance, to specify the offset distance, a SmartReal will be used.
A SmartReal may be of different types, as defined by the enumeration SmartRealType.
Here is a code sample showing the construction of several types of SmartReal:

26 Missler Software
TopSolid’Design Automation Guide Parameters

SmartReal real;

// Basic value of type Length equal to 0.5 meter.

real = new SmartReal(UnitType.Length, 0.5);

// Associative value of "d" parameter.

real = new SmartReal(TopSolidHost.Elements.SearchByName(docId, "d"));

// Formula value equal to "d + 3mm", "d" being a parameter.

real = new SmartReal(UnitType.Length, "d + 3mm");

Like for reals, there will be smart "versions" of other types of values like SmartIntegers,
SmartBooleans...

User Properties
Some parameters may correspond to user properties, that are defined in a dedicated type of
document (see User’s Guide).
Here is a code sample showing how to create, if needed, and set the value of a user property
text parameter in a document:

// Get user property definition document.

PdmObjectId userPropertyObjectId =
TopSolidHost.Pdm.SearchDocumentByUniversalId(
PdmObjectId.Empty, "Domain", "Name");
if (userPropertyObjectId.IsEmpty) return;
DocumentId userPropertyDocId = TopSolidHost.Documents.GetDocument(
userPropertyObjectId);

// Get or create user property parameter.

ElementId param = TopSolidHost.Parameters.SearchUserPropertyParameter(

docId, userPropertyDocId);

if (param.IsEmpty)
{
param = TopSolidHost.Parameters.CreateUserPropertyParameter(
docId, userPropertyDocId);
}

// Set parameter value.

TopSolidHost.Parameters.SetTextValue(param, "New Value");

Missler Software 27
Parameters TopSolid’Design Automation Guide

28 Missler Software
Geometries TopSolid’Design Automation Guide

Geometries

Missler Software 29
Geometries TopSolid’Design Automation Guide

Introduction
Access to TopSolid simple 2-dimensional (2D) and 3-dimensional (3D) geometric entities will
be possiblle using the methods of IGeometries2D and IGeometries3D interfaces returned by
the properties TopSolidHost.Geometries2D and TopSolidHost.Geometries3D.
2D geometry will be found in 2D documents like "Draft" or "2D Model".
3D geometry will be found in 3D documents like "Part", "Assembly" or "3D Model".

Types
To receive from and send to TopSolid geometric information, several useful structures are
provided, they are divided into 2D and 3D types.

2D geometry

• Vector2D: 2D vector.
• Direction2D: 2D direction, defined by a 2D unit vector.
• Point2D: 2D point.
• Axis2D: 2D axis.
• Frame2D: 2D frame.
• Transform2D: 2D transform.

3D geometry

• Vector3D: 3D vector.
• Direction3D: 3D direction, defined by a 3D unit vector.
• Point3D: 3D point.
• Axis3D: 3D axis.
• Plane3D: 3D plane.
• Frame3D: 3D frame.
• Transform3D: 3D transform.

Operators

Useful operators are provided for these geometric types, they allow to write clearer and more
compact code.
For instance, the middle point between two existing points may be computed like this:

Point3D p1, p2;

...
Point3D pm = (p1 + p2) / 2;

Also, finding a point at a specific local coordinate on an axis, may be coded as folow:

Axis3D ax;
double x;
...

30 Missler Software
TopSolid’Design Automation Guide Geometries

Point3D px = ax.Origin + x * ax.Direction;

Sample

Here is a code sample that gets the geometry of a linear edge of a shape:

// Get edge identifier.

ElementItemId edgeId;

...

// Get linear edge geometry.

if (TopSolidHost.Shapes.GetEdgeCurveType(edgeId) !=
CurveType.Line) return;

Axis3D axis;
TopSolidHost.Shapes.GetEdgeLineCurve(edgeId, out axis);

Smart Objects
We have already seen that it was possible to provide associative real values using SmartReal
objects, but smart objects also exist for the geometry.
So there will be a smart version of the "Point3D" type called "SmartPoint3D", a smart version
of the "Axis3D" type called "SmartAxis3D",...
Therefore, it will be possible for instance to create by program an offset point at a distance "d
+ 10mm" from the point "Point 1" in the direction of the absolute X axis as follows:

SmartPoint3D smartOrigin = new SmartPoint3D(

TopSolidHost.Elements.SearchByName(docId, "Point 1"));

SmartDirection3D smartDirection = new SmartDirection3D(

TopSolidHost.Geometries3D.GetAbsoluteXAxis(docId), false);

SmartReal smartDistance = new SmartReal(UnitType.Length, "d + 10mm");

TopSolidHost.Geometries3D.CreateOffsetPoint(docId, smartOrigin,
smartDirection, smartDistance);

Missler Software 31
Geometries TopSolid’Design Automation Guide

32 Missler Software
Sketches TopSolid’Design Automation Guide

Sketches

Missler Software 33
Sketches TopSolid’Design Automation Guide

Introduction
Access to TopSolid 2D and 3D sketch entities will be possible using the methods of
ISketches2D and ISketches3D interfaces returned by the properties
TopSolidHost.Sketches2D and TopSolidHost.Sketches3D.
The 2D sketches embedded into 3D documents are considered as being 2D, so they will be
accessed using the ISketches2D interface.
Therefore, in a 3D document, the 3D sketches are obtained using
TopSolidHost.Sketches3D.GetSketches(), and the 2D sketches are obtained using
TopSolidHost.Sketches2D.GetSketches().

Frames
A sketch has got a definition frame that may be obtained by the method GetFrame(), all the
geometry contained in the sketch is defined in that frame (i.e. when you get the coordinates of
a point in the sketch, they are relative to that frame).
In the case of a 2D sketch embedded into a 3D document, its 2D frame will be replaced by a
3D plane obtained by the method GetPlane().
Therefore, here is how to get the absolute 2D coordinates of the point (X=0, Y=100mm) of 2D
sketch in a 2D document:

Point2D sketchPoint = new Point2D(0, 0.1);

Frame2D sketchFrame = TopSolidHost.Sketches2D.GetFrame(sketchId);

Point2D absolutePoint = sketchFrame.ToAbsolute(sketchPoint);

And, here is how to get the absolute 3D coordinates of the point (X=0, Y=100mm) of 2D
sketch in a 3D document:

Point2D sketchPoint = new Point2D(0, 0.1);

Plane3D sketchPlane = TopSolidHost.Sketches2D.GetPlane(sketchId);

Point3D absolutePoint = sketchPlane.ToAbsolute(sketchPoint);

Topologies
The sketch structure is described using topological items, or "topologies" for short, some of
them having an attached geometry:

• A vertex with a geometrical point attached.

• A segment with a geometrical curve attached.
• A profile is a succession of connected segments.
• A section is bounded by one or more profiles.

34 Missler Software
TopSolid’Design Automation Guide Sketches

Segments Vertices

Profiles Section

Exploring
Here is a sample that scans the profiles of a 2D sketch in a 3D document, and creates points
at each segment of type line or circular arc midpoint.

ElementId sketch = ...

List<Point2D> midpoints = new List<Point2D>();

List<ElementItemId> profiles = TopSolidHost.Sketches2D.GetProfiles(sketch);

foreach (ElementItemId profile in profiles)

{
List<ElementItemId> segments = TopSolidHost.Sketches2D.GetProfileSegments(
profile);

foreach (ElementItemId segment in segments)

{
// Find parameter of midpoint.

double ts, te;

TopSolidHost.Sketches2D.GetSegmentCurveRange(segment,
out ts, out te);
double tm = (ts + te) / 2.0;

Missler Software 35
Sketches TopSolid’Design Automation Guide

// Find line or circular arc midpoint.

CurveType curveType = TopSolidHost.Sketches2D.GetSegmentCurveType(

segment);

switch (curveType)
{
case CurveType.Line:

Axis2D axis;
TopSolidHost.Sketches2D.GetSegmentLineCurve(
segment, out axis);
midpoints.Add(axis.Origin + tm * axis.Direction);
break;

case CurveType.Circle:

Frame2D frame;
double r;
TopSolidHost.Sketches2D.GetSegmentCircleCurve(
segment, out frame, out r);
midpoints.Add(frame.Origin + r * (
Math.Cos(tm) * frame.XDirection
+ Math.Sin(tm) * frame.YDirection));
break;
}
}

// Create midpoints.

Plane3D sketchPlane = TopSolidHost.Sketches2D.GetPlane(sketch);

foreach (Point2D midpoint in midpoints)

{
TopSolidHost.Geometries3D.CreatePoint(doc,
sketchPlane.ToAbsolute(midpoint));
}

Creating
It is possible to create a sketch by program, several methods are available depending on the
situation:

• To create a 2D sketch in a 2D document:

TopSolidHost.Sketches2D.CreateSketchIn2D

36 Missler Software
TopSolid’Design Automation Guide Sketches

• To create a 2D sketch in a 3D document:

TopSolidHost.Sketches2D.CreateSketchIn3D

• To create a 3D sketch in a 3D document:

TopSolidHost.Sketches3D.CreateSketch

Modifying
It is also possible to modify a sketch by program using several available methods, but before
calling them it is necessary to call the following one (in the case of a 2D sketch, otherwise
replace "2D" by "3D"):

TopSolidHost.Sketches2D.StartModification(inSketchId);

Once the modification is complete, it is necessary to say so by calling the following method:

TopSolidHost.Sketches2D.EndModification();

Here is for instance a sample showing how to make a rectangular profile in an existing 2D
sketch.

// Start sketch modification.

TopSolidHost.Sketches2D.StartModification(inSketchId);

// Create vertices.

ElementItemId vertex1Id = TopSolidHost.Sketches2D.CreateVertex(new

Point2D(inXMin, inYMin));
ElementItemId vertex2Id = TopSolidHost.Sketches2D.CreateVertex(new
Point2D(inXMax, inYMin));
ElementItemId vertex3Id = TopSolidHost.Sketches2D.CreateVertex(new
Point2D(inXMax, inYMax));
ElementItemId vertex4Id = TopSolidHost.Sketches2D.CreateVertex(new
Point2D(inXMin, inYMax));

// Create segments.

ElementItemId segment1Id = TopSolidHost.Sketches2D.CreateLineSegment(vertex1Id,

vertex2Id);
ElementItemId segment2Id = TopSolidHost.Sketches2D.CreateLineSegment(vertex2Id,
vertex3Id);
ElementItemId segment3Id = TopSolidHost.Sketches2D.CreateLineSegment(vertex3Id,
vertex4Id);

Missler Software 37
Sketches TopSolid’Design Automation Guide

ElementItemId segment4Id = TopSolidHost.Sketches2D.CreateLineSegment(vertex4Id,

vertex1Id);

// Create profile.

List<ElementItemId> segmentIds = new List<ElementItemId>();

segmentIds.Add(segment1Id);
segmentIds.Add(segment2Id);
segmentIds.Add(segment3Id);
segmentIds.Add(segment4Id);

ElementItemId profileId = TopSolidHost.Sketches2D.CreateProfile(segmentIds);

// End sketch modification.

TopSolidHost.Sketches2D.EndModification();

38 Missler Software
Shapes TopSolid’Design Automation Guide

Shapes

Missler Software 39
Shapes TopSolid’Design Automation Guide

Introduction
Access to TopSolid shapes entities will be possible using the methods of IShapes interface
returned by the property TopSolidHost.Shapes.

Topologies
The shape structure is described using topological items, or "topologies" for short, some of
them having an attached geometry:

• A vertex with a geometrical point attached.

• An edge with a geometrical curve attached.
• A face with a geometrical surface attached.

Edges Vertices

Faces

40 Missler Software
Events TopSolid’Design Automation Guide

Events

Missler Software 41
Events TopSolid’Design Automation Guide

Introduction
Most automating applications will "tell" TopSolid what to do, but sometimes it could be useful
to "listen" to TopSolid and react to some actions performed by the user.
This is possible using events, as described in this chapter.

Architecture
Basically, it is the same principle than for automating TopSolid, but reversed: when an event
occurs, TopSolid will use WCF to call your application, which is required to provide a specified
WCF service.

WCF
Your Application TopSolid

Process 1 WCF (events)

Process 2

TopSolid is just letting you know that something happened, it will not wait for any answer from
your application, as all event methods are "one-way" (see WCF definition for one-way calls if
needed):

Contract Implementation
TopSolid events are defined as WCF service contract interfaces that need to be implemented
in your application.
For instance, to manage documents events, you need to implement IDocumentsEvents in a
class:

class DocumentsEventsHost : IDocumentsEvents

{
public void OnDocumentEditingStarted(DocumentId inDocumentId)
{
string name = TopSolidHost.Documents.GetName(inDocumentId);
MessageBox.Show(name, "Start Editing");
}

public void OnDocumentEditingEnded(DocumentId inDocumentId)

{
string name = TopSolidHost.Documents.GetName(inDocumentId);
MessageBox.Show(name, "End Editing");
}

42 Missler Software
TopSolid’Design Automation Guide Events

Client Name
To manage events, your application must provide a name when connecting to TopSolid:
So, instead of just typing:

TopSolidHost.Connect();

You will need to provide a name, for instance "MyApplication":

TopSolidHost.Connect("MyApplication");

Your application will then not be an anonymous client, but a named client connected to
TopSolid.
This client name cannot change during the connection, and may later be obtained using the
following property:

TopSolidHost.ClientName

While an application is connected to TopSolid with a specified name, it will not be possible for
other applications to connect to TopSolid using the same name, therefore this name should be
as unique as possible...

Events Handling
Once connected with a name, it is possible to start handling some events by simply calling the
TopSolidHost method dedicated to that type of events.
For instance for documents events:

TopSolidHost.HandleDocumentsEvents(typeof(DocumentsEventsHost));

This methods makes a new instance of your DocumentsEventsHost class that will receive the
events.
Once this method is called, and until disconnect from TopSolid, when an event occurs in
TopSolid, the corresponding method will be called in the DocumentsEventsHost object that
has been created by this method.

Missler Software 43
Events TopSolid’Design Automation Guide

44 Missler Software
Remote Access TopSolid’Design Automation Guide

Remote Access

Missler Software 45
Remote Access TopSolid’Design Automation Guide

Introduction
Since TopSolid v7.9, it is possible to drive TopSolid from another application running on a
different machine, this is called "remote automation".
This chapter explains how to proceed to perform such operation.

Architecture
Basically, it is the same principle than for normal TopSolid automation, but it uses TCP
protocol that allows communication between two separate machines connected to the same
network.

WCF (TCP)
Your Application TopSolid

Machine 1

Machine 2

Settings
TopSolid options must be set to allow remote access, as this is not the default setting.
In the "General" section of "Tools > Options", in the "Automation" group, the "Manage remote
access" mode must be checked.
Also, if the default communication port number is not convenient, it may be changed.
TopSolid must then be restarted.
Sometimes a firewall may be blocking the specified port communication, it is then required to
adjust its configuration.

Connecting
When connecting to a remote TopSolid, it is required to call TopSolidHost.DefineConnection
method first, to provide the IP address of the machine on the network running TopSolid, and
the port number used in TopSolid settings (for instance 192.168.7.145 and 8090).

TopSolidHost.DefineConnection("192.168.7.145", 8090, null, 0);

Afterwards, any of the TopSolidHost.Connect methods may be called.

Unlike when perfoming automation on a single machine, it will not be possible to automatically
start TopSolid, which must already be running on its machine at connection time.

46 Missler Software
TopSolid’Design Automation Guide Remote Access

Events
It is also possible to manage events using remote access.
In that case a port must be chosen (and unblocked in the firewall) on the machine running your
application.
When defining the connection, it is then required to provide the IP address of your machine as
well as the port number to use (for instance 192.168.7.153 and 8091).

TopSolidHost.DefineConnection("192.168.7.145", 8090, "192.168.7.153",

8091);

Sometimes a computer may have several network cards (for instance Ethernet + WiFi), so
care must be taken to provide the right IP address as seen from the machine running TopSolid
on the network.

Missler Software 47
Remote Access TopSolid’Design Automation Guide

48 Missler Software
Multiple Access TopSolid’Design Automation Guide

Multiple Access

Missler Software 49
Multiple Access TopSolid’Design Automation Guide

Introduction
Since TopSolid v7.10, it is possible for an automating application to drive several TopSolid
processes running at the same time on the same machine, or on another machine (remote
access).
This chapter explains how to proceed to perform such operation.

Architecture
Basically, it is the same principle than for single access TopSolid automation, but instead of
using the static class TopSolidHost to connect to a unique TopSolid, one must have one
TopSolidHostInstance object per TopSolid process to connect to.

Instance 1
TopSolid

Process 2
Your Application

Process 1
Instance 2
TopSolid

Process 3

Processes
When running several TopSolid processes on the same machine than the automating
application, they must be started with the command-line argument "-pipeName <name>",
where <name> must be different on each process as it is used to make a specific Windows
named pipe.
For instance: "TopSolid -pipeName TS1".
To connect to one of these processes, the PipeName property of the TopSolidHostInstance
object must be set to the same value before calling a "Connect" method.
When running several TopSolid processes on a different machine than the automating
application (remote access), they must be started with the command-line argument "-tcpPort
<port number>", where <port number> is the TCP port number to use and must be different on
each process.
For instance: "TopSolid -tcpPort 8095".
To connect to one of these processes, the DefineConnection method of the
TopSolidHostInstance object must be called with the same host port value before calling a
"Connect" method.

50 Missler Software
TopSolid’Design Automation Guide Multiple Access

Usually, it will also be required to have different PDM connections on each TopSolid, and
therefore use the "-pdm" command-line argument, as described in the User’s Guide.

Connecting
Here is some example showing how to connect to two TopSolid processes on the local
machine.

TopSolidHostInstance tsHost1 = new TopSolidHostInstance();

TopSolidDesignHostInstance tsDesignHost1 = new TopSolidDesignHostInstance(tsHost1);

tsHost1.PipeName = "TS1";
tsHost1.Connect();
tsDesignHost1.Connect();

tsHost1.Exited += new EventHandler(TopSolid1_Exited);

TopSolidHostInstance tsHost2 = new TopSolidHostInstance();

TopSolidDesignHostInstance tsDesignHost2 = new TopSolidDesignHostInstance(tsHost2);

tsHost2.PipeName = "TS2";
tsHost2.Connect();
tsDesignHost2.Connect();

tsHost2.Exited += new EventHandler(TopSolid2_Exited);

...

Missler Software 51
Multiple Access TopSolid’Design Automation Guide

52 Missler Software
Glossary TopSolid’Design Automation Guide

Glossary

Missler Software 53
Glossary TopSolid’Design Automation Guide

The definitions of key terms used in this document are listed below.

2D: 2-dimensional geometry.

3D: 3-dimensional geometry.

API: Acronym of "Application Programming Interface", set of specified rules and conventions
that allow a software to communicate with another software.

IDE: Acronym of "Integrated Development Environment".

WCF: Acronym of "Windows Communication Foundation", technology developed by Microsoft

to allow two different processes to communicate.

54 Missler Software
TopSolid’Design Automation Guide Index

Index
A
API 3
Automation 2
C
C# 2
D
DocumentId 18
E
Edge 40
ElementId 22
ElementItemId 22
Events 42
F
Face 40
I
IDE 2
ItemLabel 22
M
Microsoft .NET Framework 2
Microsoft Visual Studio 2
P
PdmMajorRevisionId 13
PdmMinorRevisionId 13
PdmObjectId 12
Profile 34
S
Section 34
Segment 34
Smart object 26
T
Topology 34, 40
TopSolid 2
TopSolid Automation Help 3
TopSolid’Design 2
TopSolid’Design Automation.chm 3
U
Universal Identifier 14
V
Vertex 34, 40
Visual Basic 2

Missler Software 55
Index TopSolid’Design Automation Guide

W
WCF 2

56 Missler Software