SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Data Fields | Related Functions
SUTransformation Struct Reference

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

`#include <SketchUpAPI/geometry.h>`

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

## Related Functions
(Note that these are not member functions.)
enum SUResult | 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...
enum SUResult | 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...
enum SUResult | SUTransformationTranslation (struct SUTransformation *transform, const struct SUVector3D *vector)
| Creates a translation transformation using the given vector. More...
enum SUResult | SUTransformationScale (struct SUTransformation *transform, double scale)
| Creates a scale transformation using the given scale value. More...
enum SUResult | SUTransformationNonUniformScale (struct SUTransformation *transform, double x_scale, double y_scale, double z_scale)
| Creates a scale transformation using the given scale values. More...
enum SUResult | SUTransformationScaleAboutPoint (struct SUTransformation *transform, const struct SUPoint3D *point, double scale)
| Creates a scale transformation using the given scale value and origin. More...
enum SUResult | 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...
enum SUResult | 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...
enum SUResult | 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...
enum SUResult | SUTransformationIsIdentity (const struct SUTransformation *transform, bool *is_identity)
| Gets whether the transformation is an identity transformation. More...
enum SUResult | SUTransformationGetInverse (const struct SUTransformation *transform, struct SUTransformation *inverse)
| Gets the inverse transformation of the given transformation object. More...
enum SUResult | SUTransformationGetOrigin (const struct SUTransformation *transform, struct SUPoint3D *origin)
| Gets the origin point of the given transformation object. More...
enum SUResult | SUTransformationGetXAxis (const struct SUTransformation *transform, struct SUVector3D *x_axis)
| Gets the x axis vector of the given transformation object. More...
enum SUResult | SUTransformationGetYAxis (const struct SUTransformation *transform, struct SUVector3D *y_axis)
| Gets the y axis vector of the given transformation object. More...
enum SUResult | SUTransformationGetZAxis (const struct SUTransformation *transform, struct SUVector3D *z_axis)
| Gets the z_axis vector of the given transformation object. More...
enum SUResult | SUTransformationGetZRotation (const struct SUTransformation *transform, double *z_rotation)
| Gets the rotation about the z axis from the given transformation object. More...
enum SUResult | SUTransformationMultiply (const struct SUTransformation *transform1, const struct SUTransformation *transform2, struct SUTransformation *out_transform)
| Multiplies a transformation by another transformation. More...
enum SUResult | 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

enum SUResult 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

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

- SketchUpAPI/geometry.h
- SketchUpAPI/geometry/transformation.h