2.1 Introduction

This chapter explains fundamental concepts that you need to understand in order to use Parasolid. The information in this chapter is vital to understanding Parasolid and you should read and understand it.

[back to top]

2.2 Entity classes, tokens and tags

Parasolid models are made up of many different items, or entities. For example, a part consisting of a single cylindrical body contains (at least):

one body
two regions
two shells
three faces
four loops
four fins
two edges
three surfaces
two curves

It might also contain some attributes or groups, and further surfaces, curves and points used as construction geometry.

Generally speaking, an entity is any identifiable component of a model. Any model can be represented as a network of entities linked in complex relationships.

Entities are grouped into three main types. Figure 2-1 shows the entities available in a body, together with some of the relationships between them. A more detailed description of the entity hierarchy is available in Section 2.4.

Figure 2-1 The entities of the Kernel model

For more information about the entities available in Parasolid, and the relationships between them, see Chapter 3, "Model Structure".

[back to top]

2.2.1 Tokens

Every entity has one or more classes associated with it. Classes are specified and reported using tokens which are defined as constant values in the include file parasolid_tokens.h .

Token names in the PK Interface are either of the form

PK_ <CLASS>_ <text>, or
PK_ <text>_ <text>

where <CLASS> is an upper case string denoting the entity class that the token applies to, and <text> is a lower case string that describes the meaning of the token. Tokens that have no <CLASS> specified may apply to more than one class.

Any given entity may be associated with several different classes. This collection of classes specifies what sort of entity it is. The number of classes associated varies from entity to entity, as they constitute a hierarchical classification.

For example a given surface may be classified successively as:

PK_CLASS_geom - geometric, the overall class to which surfaces belong
PK_CLASS_surf - a surface, a subclass of PK_CLASS_geom
PK_CLASS_cone - conical, a subclass of PK_CLASS_surf

Tokens are used in two ways:

Tokens are passed to the kernel to specify information; for example, the class of an entity or a class of parameter
Tokens are passed to the kernel to specify optional arguments; for example, to perform a unite boolean operation, you need to specify the token PK_boolean_unite_c in a PK function call.
The kernel returns tokens when identifying an object; for example, PK_BODY_ask_type (which classifies a given body) might return PK_BODY_type_solid_c (to denote a bounded body with finite volume)

Tokens are listed in the PK Interface Programming Reference Manual (Part 2 - Interface Structures, Tokens & Error Codes):

Note: In general, tags and geometric parameters are common to both the PK and KI interfaces. PK error codes and KI ifails differ on occasions.

Using token names and values in your code

Tokens also have numerical values that are for use with the Kernel Interface Driver. Since these numerical values may change in future versions, you should use only token names in your code. These will continue to work even if the numerical value changes.

However, with the exception of error tokens (PK_ERROR_sf_t), you cannot interrogate the PK itself for token names: PK functions only return the numerical values, which you can compare against the names published in the following places:

Appendix A, "PK Tokens (Numeric)" in PK Interface Programming Reference Manual, Part 2
Appendix B, "PK Tokens (Alphabetic)" in PK Interface Programming Reference Manual, Part 2
The file parasolid_tokens.h

[back to top]

2.2.2 Tags

Tags are used to identify particular entities within a session for Parasolid to work on. They are also used by the kernel to return entities from the model to your application.

Every entity in a model has a tag associated with it. A tag is created by the kernel when the entity is created or enquired about. Each tag in a session is unique, so that every entity can be identified. However, tags are not consistent across different sessions: if the same entities are loaded into a different Parasolid session, they are not necessarily assigned the same tags.

Tags are held in integer variables which PK functions use as pointers to entities.

Lifetime of a tag

A tag only has meaning (is alive) while the entity to which it refers still exists in internal memory. If an entity is:

explicitly deleted
implicitly deleted (e.g. a superfluous edge between two faces is merged away)
deleted by rolling the modeler back to a point before the entity was created
lost because the modeling session is stopped

then its tag is considered dead. It is your application's responsibility to know what tags it is holding. If dead tags are passed to the PK then it traps them and returns the error PK_ERROR_not_an_entity (if argument checking is enabled). PK_ENTITY_is can be used to determine whether a particular tag is alive or dead.

The null tag

There is a special constant tag called PK_ENTITY_null, which is defined in the include file parasolid_kernel.h . It is a tag to which no entity corresponds, and its principal use is that various PK functions return it when there is no appropriate entity to return.

For example, when requesting the tag of the surface attached to a face; if the face has no corresponding surface, the function returns PK_ENTITY_null.

Persistence of tags

Many modeling operations result in entities being created, deleted, or changed. Changes such as these have implications on what happens to the tags attached to those entities: sometimes new tags must be created, and sometimes old tags are deleted. A set of rules governs this tag persistence.

The general rules for face tag persistence can be summarized as follows:

If a face shrinks (truncated), then its tag persists.
If a face is split into several faces, then one of the resulting faces has the tag of the original face, and all other tags are new.

These rules apply equally to edge tag persistence.

Note: Tag persistence is disabled if normal attribute callbacks are registered and used. See Section 46.3, "Callback functions" for more information.

[back to top]

2.2.3 Operations on tokens and tags

The following operations can be performed on tokens:

Pass a token to a PK function in an argument that is defined to accept such a token.
Compare two tokens for equality.

Only certain operations are meaningful on tags and tag variables:

Tags are created only within the kernel. Your application can acquire them only by calling particular PK functions which are defined to return tags in certain arguments.
In order to specify which entities in the model to operate on, your application passes tags to the kernel. These must be tags that have previously been provided by the kernel, and they must still be alive.
Tags may be freely copied and saved within your application (as integer variables). This could be used, for example, as a lookup mechanism to map between your entities and Parasolid entities.
Tags can be compared for equality using the ordinary integer operators == and != .

If two tags are numerically equal then they are associated with the same entity in the model.
If two distinct entities coincide precisely in model space (e.g. two points are the same, but are different entities), they do not have equal tags.

It is meaningless to perform arithmetic on tags, or to construct tags in any way other than by obtaining them from the kernel.

[back to top]

2.2.4 Identifiers

Identifiers are integer values that are automatically attached to all entities within a body, except for fins and the body itself. All identifiers are unique within a given body (in contrast to tags, which are unique within the whole session). In addition, identifiers are saved when a part is archived (in contrast to tags, which are not), so identifiers can be stored in an external database with a part key to keep a handle on a particular entity.

Identifiers may have negative values, but are never zero. They are created when:

an entity is created within a part
an entity is moved from one part to another (and its old identifier is thrown away)
an entity which did not belong to a part is attached to one (e.g. when adding construction geometry)

For more information on identifiers, together with a more detailed comparison with tags, see Section 42.2.4, "Identifiers".

[back to top]

2.2.5 User fields

These allow your application to store a single field of information with all entities, such as a pointer into the application's data structure. User fields are of a fixed length and are attached to every entity in a model.

[back to top]

2.3 Getting started with the PK interface

In order to use Parasolid, your application code must contain:

Calls to PK functions as part of its modeling system,
Definitions for frustrum functions that are themselves called by Parasolid.

Before your application can use the modeler, you must first supply a frustrum (as described in Getting Started With Parasolid), and then call PK_SESSION_start to invoke modeler. PK_SESSION_start has options that allow you to choose whether to create a journal file, and whether parts are saved and retrieved with user fields.

When your application has finished using the modeler, it is stopped using PK_SESSION_stop. Calls to PK_SESSION_start and PK_SESSION_stop mark the beginning and end of a kernel session.

For full details of the frustrum, see the Downward Interfaces manual.

Note: The program examples in the Parasolid documentation set are written in C, but apply to any language used to call the PK.

[back to top]

2.3.1 Prototyping Parasolid code

It is easy to prototype code in order to see its performance before incorporating it into your application code:

If you are developing under Windows NT, you can use PS/Workshop to prototype code.
Alternatively, you can use the Kernel Interface Driver (KID) to prototype code.

PS/Workshop is a Windows NT application that is available on the Parasolid Resource Library CD. Accompanying documentation can be found with the application.

KID is a LISP-based package that is available on the Parasolid Code CD. KID should also be used to reproduce faults in the kernel for reporting to technical support. KID is documented in the KID Manual.

Note: You can load models into PS/Workshop and KID that were created using another Parasolid-powered application, provided that the application does not use a later version of Parasolid than yours.

[back to top]

2.4 PK interface functions

PK interface functions are organized according to the main object or class of item on which they operate. These categories can in turn be organized hierarchically into sub-classes. The functions fall into the following scheme:

Function category	Description
CLASS	Navigating the class hierarchy
SESSION	Session management
ERROR	Error handling
MEMORY	Memory management
PARTITION PMARK MARK DELTA	Rollback mechanism

Note: Partitions, pmarks, and marks can also be considered entities in that they can all have tags. However, they are included in the table above because they are not entities that relate directly to models.

Entity classes are organized into a class hierarchy:

Entity classes				Description
ENTITY				Tagged model entities
	ATTRIB			Attributes
	ATTDEF			Attribute definitions
	GROUP			Groups
	TRANSF			Transformations
	TOPOL			Topological entities
		PART		Complete parts
			BODY	Bodies
			ASSEMBLY	Assemblies
		REGION		3-space regions
		SHELL		Shells bounding regions
		FACE		Faces
		LOOP		Loops bounding faces
		EDGE		Edges linking faces
		FIN		One side of an edge
		VERTEX		Vertices linking edges
	GEOM			Geometric entities
		SURF		Surfaces
		CURVE		Curves
		POINT		Points

SURF and CURVE also have a number of subclasses, omitted from the table above for simplicity.

[back to top]

2.4.1 Specific function syntax

All PK functions have names of the form PK_ <OBJECT>_ <text>, where

<OBJECT> is the (upper case) entity class that the function operates on, and
<text> is usually a (lower case) verb/noun combination that describes the operation.

Some of the most common function names are constructed from a standard set of verbs, shown below:

Verb	Description	Example Function
create	create an entity	PK_ATTRIB_create_empty
make	create from entity of another class	PK_CONE_make_solid_body
delete	delete an entity	PK_ENTITY_delete_attribs
set	store a value or values	PK_ATTRIB_set_doubles
ask	retrieve a stored value	PK_FACE_ask_body
is	query condition	PK_ENTITY_is_curve
find/eval	compute a value	PK_FIN_find_curve_parameter

Every function has a fixed set of arguments: some are used to supply data, and others are used to return information. Arguments must never be used for both purposes; if a pointer to the same memory space is passed as both input and output arguments, the function's behavior is undefined . Input arguments are never modified as a result of the PK function call.

In some functions, arrays of returned data are optional. Parasolid does not attempt to compute or return this information if the NULL pointer is passed as the pointer for the returned array.

[back to top]

2.4.2 Arguments to PK functions

Argument types are simple values, arrays, and structures built from the following list of primitive types:

Type	Description
int	the usual C convention for an integer
double	the usual C convention for a double precision floating point number
char*	the usual C convention for a null-terminated character string
PK_LOGICAL_t	true or false, with values 1 and 0 respectively: #define PK_LOGICAL_true 1 #define PK_LOGICAL_false 0
PK_VECTOR_t	a 3-space vector with co-ordinate fields (3 doubles): typedef struct {double coord[3];} PK_VECTOR_t;
PK_VECTOR1_t	same as PK_VECTOR_t, but it must be a unit vector (enforced by argument checking)
PK_INTERVAL_t	a real interval ordered low/high (2 doubles): typedef struct {double value[2];} PK_INTERVAL_t;
PK_BOX_t	a rectangular box aligned with the world co-ordinate axes, representing the minimum and maximum extremes of the box (6 doubles): typedef struct {double coord[6];} PK_BOX_t;
PK_UV_t	a surface parameter pair of u and v co-ordinates: typedef struct {double param[2];} PK_UV_t;
PK_UVBOX_t	a surface parameter space box: typedef struct {double param[4];} PK_UVBOX_t;

Options for a PK function must be passed collectively to the function using an options structure. Every option in the options structure must be specified explicitly, even if you do not intend "using" it as such. To make this task easier, a macro is available for each option structure that initializes its fields to standard default values. Your application should call the relevant macro, and then change the settings of individual options before passing the structure to the function. For more information on using option structures, see Chapter 1, "PK Interface Programming Concepts", in the PK Interface Programming Reference Manual, (Part 1 - Functions).

[back to top]

2.4.3 Error handling

Every PK function returns an error code as the function value. If this value is PK_ERROR_no_errors, the function has completed successfully and the application can proceed. If it is any other value, the function has failed to complete, and your application must deal with this error in a suitable way. There are two strategies available for dealing with such errors:

Your application can examine the error code of each function call and take any required corrective action.
Your application can gain further control over error handling by registering an error handler, which is invoked whenever a PK error is raised (just before the function is about to return)

You must choose only one of these strategies. You cannot mix the two strategies.

Note: Neither of these error handling strategies deals with the situation where a PK function returns successfully, but the operation itself fails. In this case, the function returns a token in its return structure that describes the nature of the failure, and you must use this token to take appropriate action in your application code.

If you wish, your application can also register signal handlers with the operating system to deal with run-time errors and/or user interrupts.

For more information about error handling, see Chapter 59, "Error Handling".

[back to top]

<<< Introduction to Parasolid

Chapters

Model Structure >>>