SUTransformation Struct Reference

Represents a 3D (4x4) geometric transformation matrix. More...

#include <geometry.h>

Data Fields
double	values [16]
	Matrix values in column-major order. More...

Related Functions
(Note that these are not member functions.)
SU_RESULT	SUTransformationSetFromPointAndNormal (struct SUTransformation *transform, const struct SUPoint3D *point, const struct SUVector3D *normal)
	Sets the transformation based on the provided point and z-axis vector. The resulting transformation transforms points/vectors to a new coordinate system where the provided point is the new origin and the vector is the new z-axis. The other two axes in the transformed space are computed using the "Arbitrary axis algorithm". More...
SU_RESULT	SUTransformationSetFromPointAndAxes (struct SUTransformation *transform, const struct SUPoint3D *point, const struct SUVector3D *x_axis, const struct SUVector3D *y_axis, const struct SUVector3D *z_axis)
	Sets the transformation based on the provided origin and axes. More...
SU_RESULT	SUTransformationTranslation (struct SUTransformation *transform, const struct SUVector3D *vector)
	Creates a translation transformation using the given vector. More...
SU_RESULT	SUTransformationScale (struct SUTransformation *transform, double scale)
	Creates a scale transformation using the given scale value. More...
SU_RESULT	SUTransformationNonUniformScale (struct SUTransformation *transform, double x_scale, double y_scale, double z_scale)
	Creates a scale transformation using the given scale values. More...
SU_RESULT	SUTransformationScaleAboutPoint (struct SUTransformation *transform, const struct SUPoint3D *point, double scale)
	Creates a scale transformation using the given scale value and origin. More...
SU_RESULT	SUTransformationNonUniformScaleAboutPoint (struct SUTransformation *transform, const struct SUPoint3D *point, double x_scale, double y_scale, double z_scale)
	Creates a scale transformation using the given scale values and origin. More...
SU_RESULT	SUTransformationRotation (struct SUTransformation *transform, const struct SUPoint3D *point, const struct SUVector3D *vector, double angle)
	Creates a transformation given an origin, vector of rotation, and angle. More...
SU_RESULT	SUTransformationInterpolate (struct SUTransformation *transform, const struct SUTransformation *t1, const struct SUTransformation *t2, double weight)
	Performs an interpolation between two transformations. The weight determines the amount of interpolation. A weight of 0.0 would return a transformation of t1, while a weight of 1.0 would return a transformation of t2. More...
SU_RESULT	SUTransformationIsIdentity (const struct SUTransformation *transform, bool *is_identity)
	Gets whether the transformation is an identity transformation. More...
SU_RESULT	SUTransformationGetInverse (const struct SUTransformation *transform, struct SUTransformation *inverse)
	Gets the inverse transformation of the given transformation object. More...
SU_RESULT	SUTransformationGetOrigin (const struct SUTransformation *transform, struct SUPoint3D *origin)
	Gets the origin point of the given transformation object. More...
SU_RESULT	SUTransformationGetXAxis (const struct SUTransformation *transform, struct SUVector3D *x_axis)
	Gets the x axis vector of the given transformation object. More...
SU_RESULT	SUTransformationGetYAxis (const struct SUTransformation *transform, struct SUVector3D *y_axis)
	Gets the y axis vector of the given transformation object. More...
SU_RESULT	SUTransformationGetZAxis (const struct SUTransformation *transform, struct SUVector3D *z_axis)
	Gets the z_axis vector of the given transformation object. More...
SU_RESULT	SUTransformationGetZRotation (const struct SUTransformation *transform, double *z_rotation)
	Gets the rotation about the z axis from the given transformation object. More...
SU_RESULT	SUTransformationMultiply (const struct SUTransformation *transform1, const struct SUTransformation *transform2, struct SUTransformation *out_transform)
	Multiplies a transformation by another transformation. More...
SU_RESULT	SUTransformationIsMirrored (const struct SUTransformation *transform, bool *is_mirrored)
	Returns true if transformation has been mirrored. More...

Detailed Description

Represents a 3D (4x4) geometric transformation matrix.

Matrix values are in column-major order. The transformation is stored as:

    -     -
    | R T |
M = | 0 w |
    -     -

where:

• M is a 4x4 matrix
• R is a 3x3 sub-matrix. It is the rotation part
• T is a 3x1 sub-matrix. It is the translation part
• w is a scalar. It is 1/scale.

Friends And Related Function Documentation

SU_RESULT SUTransformationGetInverse ( const struct SUTransformation *  transform, struct SUTransformation *  inverse  )

related

Gets the inverse transformation of the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	inverse	The inverse transformation object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if inverse is NULL
• SU_ERROR_INVALID_ARGUMENT if the transform cannot be inverted

SU_RESULT SUTransformationGetOrigin ( const struct SUTransformation *  transform, struct SUPoint3D *  origin  )

related

Gets the origin point of the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	origin	The origin point to be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if origin is NULL

SU_RESULT SUTransformationGetXAxis ( const struct SUTransformation *  transform, struct SUVector3D *  x_axis  )

related

Gets the x axis vector of the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	x_axis	The x axis vector to be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if x_axis is NULL

SU_RESULT SUTransformationGetYAxis ( const struct SUTransformation *  transform, struct SUVector3D *  y_axis  )

related

Gets the y axis vector of the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	y_axis	The y axis vector to be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if y_axis is NULL

SU_RESULT SUTransformationGetZAxis ( const struct SUTransformation *  transform, struct SUVector3D *  z_axis  )

related

Gets the z_axis vector of the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	z_axis	The z_axis vector to be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if z_axis is NULL

SU_RESULT SUTransformationGetZRotation ( const struct SUTransformation *  transform, double *  z_rotation  )

related

Gets the rotation about the z axis from the given transformation object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	z_rotation	The rotation to be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if z_rotation is NULL

SU_RESULT SUTransformationInterpolate ( struct SUTransformation *  transform, const struct SUTransformation *  t1, const struct SUTransformation *  t2, double  weight  )

related

Performs an interpolation between two transformations. The weight determines the amount of interpolation. A weight of 0.0 would return a transformation of t1, while a weight of 1.0 would return a transformation of t2.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The result of the interpolation.
[in]	t1	The first transformation object.
[in]	t2	The second transformation object.
[in]	weight	The weight determines the amount of interpolation from t1 to t2.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if t1 or t2 is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_OUT_OF_RANGE if weight is not between 0.0 and 1.0

SU_RESULT SUTransformationIsIdentity ( const struct SUTransformation *  transform, bool *  is_identity  )

related

Gets whether the transformation is an identity transformation.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform	The transformation object.
[out]	is_identity	Whether the transformation is identity.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if transform is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if is_identity is NULL

SU_RESULT SUTransformationIsMirrored ( const struct SUTransformation *  transform, bool *  is_mirrored  )

related

Returns true if transformation has been mirrored.

Since

SketchUp 2019, API 7.0

Parameters

[in]	transform	The transform object.
[out]	is_mirrored	Indicates if mirrored.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if is_mirrored is NULL
• SU_ERROR_NULL_POINTER_INPUT if transform is NULL

SU_RESULT SUTransformationMultiply ( const struct SUTransformation *  transform1, const struct SUTransformation *  transform2, struct SUTransformation *  out_transform  )

related

Multiplies a transformation by another transformation.

Since

SketchUp 2018, API 6.0

Parameters

[in]	transform1	The transformation object to be multiplied.
[in]	transform2	The transformation object to multiply by.
[out]	out_transform	The result of the matrix multiplication [transform1 * transform2].

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if out_transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if transform1 or transform2 is NULL

SU_RESULT SUTransformationNonUniformScale ( struct SUTransformation *  transform, double  x_scale, double  y_scale, double  z_scale  )

related

Creates a scale transformation using the given scale values.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	x_scale	The x-axis scale value for the transformation.
[in]	y_scale	The y-axis scale value for the transformation.
[in]	z_scale	The z-axis scale value for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if x_scale, y_scale, or z_scale are NULL

SU_RESULT SUTransformationNonUniformScaleAboutPoint ( struct SUTransformation *  transform, const struct SUPoint3D *  point, double  x_scale, double  y_scale, double  z_scale  )

related

Creates a scale transformation using the given scale values and origin.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	point	The point specifying the translation component of the transformation.
[in]	x_scale	The x-axis scale value for the transformation.
[in]	y_scale	The y-axis scale value for the transformation.
[in]	z_scale	The z-axis scale value for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if point, x_scale, y_scale, or z_scale are NULL

SU_RESULT SUTransformationRotation ( struct SUTransformation *  transform, const struct SUPoint3D *  point, const struct SUVector3D *  vector, double  angle  )

related

Creates a transformation given an origin, vector of rotation, and angle.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The calculated transformation.
[in]	point	The point specifying the translation component of the transformation.
[in]	vector	The vector about which rotation will occur.
[in]	angle	The rotation in radians for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if point or vector is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_OUT_OF_RANGE if weight is not between 0.0 and 1.0

SU_RESULT SUTransformationScale ( struct SUTransformation *  transform, double  scale  )

related

Creates a scale transformation using the given scale value.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	scale	The scale value for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

SU_RESULT SUTransformationScaleAboutPoint ( struct SUTransformation *  transform, const struct SUPoint3D *  point, double  scale  )

related

Creates a scale transformation using the given scale value and origin.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	point	The point specifying the translation component of the transformation.
[in]	scale	The scale value for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if point or scale are NULL

SU_RESULT SUTransformationSetFromPointAndAxes ( struct SUTransformation *  transform, const struct SUPoint3D *  point, const struct SUVector3D *  x_axis, const struct SUVector3D *  y_axis, const struct SUVector3D *  z_axis  )

related

Sets the transformation based on the provided origin and axes.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	point	The point specifying the translation component of the transformation.
[in]	x_axis	The 3D vector specifying the x-axis for the transformation. This is treated as a unit vector, so any scaling will be ignored.
[in]	y_axis	The 3D vector specifying the y-axis for the transformation. This is treated as a unit vector, so any scaling will be ignored.
[in]	z_axis	The 3D vector specifying the z-axis for the transformation. This is treated as a unit vector, so any scaling will be ignored.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if point, x_axis, y_axis, or z_axis are NULL

SU_RESULT SUTransformationSetFromPointAndNormal ( struct SUTransformation *  transform, const struct SUPoint3D *  point, const struct SUVector3D *  normal  )

related

Sets the transformation based on the provided point and z-axis vector. The resulting transformation transforms points/vectors to a new coordinate system where the provided point is the new origin and the vector is the new z-axis. The other two axes in the transformed space are computed using the "Arbitrary axis algorithm".

Since

SketchUp 2017, API 5.0

Parameters

[out]	transform	The transformation to be set.
[in]	point	The point specifying the translation component of the transformation.
[in]	normal	The 3D vector specifying the rotation component of the transformation. This is treated as a unit vector, so any scaling will be ignored.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if point or normal are NULL

SU_RESULT SUTransformationTranslation ( struct SUTransformation *  transform, const struct SUVector3D *  vector  )

related

Creates a translation transformation using the given vector.

Since

SketchUp 2018, API 6.0

Parameters

[out]	transform	The transformation to be set.
[in]	vector	The 3D vector specifying the translation for the transformation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
• SU_ERROR_NULL_POINTER_INPUT if vector is NULL

Field Documentation

double SUTransformation::values[16]

Matrix values in column-major order.

---

The documentation for this struct was generated from the following files:

• SketchUpAPI/geometry.h
• SketchUpAPI/geometry/transformation.h