Expressions

24.1 Introduction

This chapter provides information on expressions.Expressions allow an application to supply a mathematical formula to be evaluated. The expressions are supplied in the form of strings. For example, the expression "position + vector(0.1, 0.0, 0.0)" evaluates the result of adding the vector (0.1, 0.0, 0.0) to the variable position, which should also be a vector.

Note: Expressions are calculated in double precision.

Evaluators can be used an inputs when performing deformation using PK_FACE_change. See Section 72.4.8, “Deformation options” for more information.

24.1.1 Standard form of an expression

PK_EXPR_sf_t is the standard form of an expression. It contains fields that specify:

the root expression
sub-expression names and definitions
constant names and values

The expression's overall value comes from evaluating the root expression.

The use of sub-expressions is optional. If you choose to use them, their names must begin with the prefix "sbx_" and consist of alphanumeric characters or underscore "_".Sub-expressions can be referenced by name in either the root_expr field or the sub_expr_defs field in the PK_EXPR_sf_t structure.

The use of constants are also optional and their names must begin with the prefix "c_" and consist of alphanumeric characters or underscore "_". A constant is referenced by its name in either the root_expr field or the sub_expr_defs field in the PK_EXPR_sf_t structure.

Note: Sub-expression and constant names are case-insensitive.

See PK_EXPR_sf_t for more information.

[back to top]

24.2 Operators

Operator	Description
+	plus (infix),
-	minus (infix), negative (unary)
*	multiply (realreal or realvector), cross product (vector*vector)
/	divide
^	power
==	equality test
!=	non-equality test
<	less than
>	greater than
<=	less than or equal to
>=	greater than or equal to
&&	logical and
\|\|	logical or
!	logical not
if condition then `action_true` else `action_false`	Evaluates to `action_true` if condition is true, else evaluates to `action_false`

24.2.1 Order of precedence

Operators have the following order of precedence:

Operators
!, - (unary negation)
^
*, /
+, - (subtraction)
< ,> , <=, >=
==, !=
&&
\|\|
Any other operator

Note: Operators listed higher in the table have higher precedence.

Operators of equal precedence such as multiplication and division are evaluated from left to right. Parentheses may be used to force the ordering of the mathematical operations.

For example:

4/2*5 evaluates to 10
4*2/5 evaluates to 1.6
4/2/5 evaluates to 0.4
4/(2*5) evaluates to 0.4

24.2.2 Contents of an expression

An expression string forms a mathematical formula consisting of identifiers combined by operators and functions. Identifiers may be:

the names of sub-expressions and constants defined in the PK_EXPR_sf_t. These are defined by the application.
the names of variable parameters specific to the context in which the expression is being used. These will be documented in the PK function using PK_EXPR_sf_t.

An object referred to by an identifier, received or returned by a function can be of type bool, integer, real, vector, or PK_ENTITY or any of its sub-classes. The form of a vector is an array of three reals.

The operators are mathematical or logical and the functions are mathematical or geometric as illustrated in the following expression string example:

position + c_offset_dist * pkx_normal(c_surf, sbx_projection)

position would be a vector variable defined by the PK function
c_offset_dist and c_surf would be names of constants
sbx_projection would be the name of a sub-expression
+, * are mathematical operators
pkx_normal is a geometric function

[back to top]

24.3 Maths functions

24.3.1 Functions that return a constant

Return type	Function	Description
real	pi()	Returns pi

24.3.2 Single-variable functions

Return type	Function	Description
real	abs (real x)	Returns absolute value of x.
real	acos (real x)	Returns inverse cosine of x.
real	acosh (real x)	Returns inverse hyperbolic cosine of x
real	asin (real x)	Returns inverse sine of x.
real	asinh (real x)	Returns inverse hyperbolic sine of x
real	atan (real x)	Returns inverse tangent of x.
real	atanh (real x)	Returns inverse hyperbolic tangent of x
real	base_angle (real x)	Returns x shifted to the base period [0,2pi).
real	ceiling (real x)	Returns immediately greater integer to x.
real	cos (real x)	Returns cosine of x.
real	cosh (real x))	Returns hyperbolic cosine of x.
real	degrees (real x)	Convert radians to degrees.
real	exp (real x)	Returns natural exponent of x.
real	floor (real x)	Returns immediately lower integer to x.
real	length (vector v)	Returns the magnitude of the supplied vector v.
real	log (real x)	Returns natural logarithm of x.
real	log10 (real x)	Returns logarithm base 10 of x.
vector	normalise (vector v)	Returns a unit vector parallel to v, of the zero vector if v has zero magnitude.
real	radians (real x)	Convert degrees to radians.
real	round (real x)	Returns x rounded to nearest integer.
integer	sign (real x)	Returns sign of x as -1 if negative, +1 if positive, or 0
real	sin (real x)	Returns sine of x.
real	sinh (real x)	Returns hyperbolic sine of x.
real	sqrt (real x)	Returns square root of x.
real	tan (real x)	Returns tangent of x.
real	tanh (real x)	Returns hyperbolic tangent of x.

24.3.3 Two-variable functions

Return type	Function	Description
real	atan2 (real y, real x)	Returns angle of (x,y) turned from +x axis.
real	ceiling (real x, real y)	Returns x rounded up to the nearest integer multiple of y.
real	dot (vector v0, vector v1)	Returns the dot product (v0 . v1).
real	element (vector v, integer index)	Returns the index-th component of the supplied vector v. The index must be 1, 2 or 3.
real	floor (real x, real y)	Returns x rounded down to the nearest integer multiple of y.
real	mod (real x, real y)	Returns x modulo y.
real	nthroot (real x, real y)	Returns the y-th root of x.
real	round (real x, real y)	Returns x rounded the nearest integer multiple of y.

24.3.4 Variadic functions

Return type	Function	Description
real	avg (real x0, ... )	Returns mean average of the supplied arguments.
real	max (real x0, ... )	Returns maximum of the supplied arguments.
real	min (real x0, ... )	Returns minimum of the supplied arguments.
vector	vector (real x, real y, real z)	Creates a vector value.

[back to top]

24.4 Modelling functions

Return type	Function	Description
real	pkx_arc_length (PK_ENTITY_t entity, vector start, vector end)	Evaluates the arc length of an edge or curve between the supplied start and end positions.The entity may be an edge or curve.The start and end must lie on the curve.
vector	pkx_closest_position (PK_ENTITY_t entity, vector position)	Finds the global minimum separation between the supplied entity and position. The function returns a point on the entity that is the minimum separation distance from the position. The entity may be a body, face, edge, fin, vertex, surface, curve, or point.
vector	pkx_normal (PK_ENTITY_t entity, vector position, bool `is_parameters` = false)	Evaluates the normal on a face or surface, at the supplied position.The entity may be a face or surface. If the entity is a face, the function evaluates on the face's surface, taking into account the face orientation. If the optional argument `is_parameters` is set to false (the default), then the position is a three space point, which must lie on the surface. If `is_parameters` is set to true, then the position will be interpreted as u and v parameters on the surface, supplied as the first and second components of the vector respectively.
vector	pkx_parameters (PK_GEOM_t geom, vector position)	Finds the parameter(s) of the supplied position on a curve or surface.The geom may be a curve or surface. For a curve, the parameter t is returned as the vector (t, 0, 0). For a surface, the parameters u and v are returned as the vector (u, v, 0).The position must lie on the curve or surface.
vector	pkx_position (PK_GEOM_t geom, vector parameters)	Evaluates a point on the curve or surface, at the supplied parameters.The geom may be a curve or surface. For a curve, the parameter should be supplied as the first component of the parameters vector. For a surface, the u and v parameters should be supplied as the first and second components of the parameters vector respectively.
vector	pkx_tangent (PK_ENTITY_t entity, vector position, bool `is_parameters` = false	Evaluates the tangent on an edge, fin or curve, at the supplied position The entity may be an edge, fin or curve. If the entity is an edge or fin, the function evaluates on the edge's or fin's geometry, taking into account the edge or fin orientation. If the optional argument `is_parameters` is set to false (the default), then the position is a three space point, which must lie on the curve. If `is_parameters` is set to true, then the position will be interpreted as the parameter on the curve, supplied as the first component of the vector

[back to top]

24.5 Examples

Expression string	Description
abs(-3.0)	Returns the absolute value of -3.0, i.e., 3.0
min(3,7,1,9,14)	Returns the minimum of the supplied values, i.e, 1
if x>0 then sin(x) else 0	Returns sin(x) for positive x, else returns 0
position + 0.1*pkx_normal(face, position)	Offsets the supplied position by a distance 0.1 in the direction of the face normal at the position

An example involving sub-expressions and constants is as follows:

Expression	Expression string
Root expression	position + c_offset_dist * pkx_normal(c_s0, sbx_projection)
sbx_projection	pkx_closest_position(c_s0, position)

This example expression offsets the position by a distance c_offset_dist in the direction of the normal of the surface with tag c_s0 at the point sbx_projection. sbx_projection is the closest point on the surface to the position. In this example, c_s0 and c_offset_dist are supplied as constants in the PK_EXPR_sf_t standard form.

[back to top]

<<< Reading and Writing Parasolid Data

Chapters

Introduction To Model Interrogation >>>