Transform
- class nvisii.transform(*args, **kwargs)
The “Transform” component places an entity into the scene. These transform components represent a scale, a rotation, and a translation, in that order. These transform components also keep track of the previous frame scale, rotation, and translation, which can optionally be used for creating motion blur and for temporal effects like reprojection.
- property thisown
The membership flag
- static create(*args, **kwargs)
Constructs a transform with the given name.
- Parameters
name (string) – A unique name for this transform.
scale (
vec3, optional) – The initial scale of the transform, applied first.rotation (
quat, optional) – The initial scale of the transform, applied after scale.position (
vec3, optional) – The initial position of the transform, applied after rotation.
- Return type
Transform- Returns
a reference to a transform component
- static create_from_matrix(*args, **kwargs)
Constructs a transform with the given name, initializing with the given matrix.
- Parameters
name (string) – A unique name for this transform.
matrix – The initial local to world transformation to be applied
- Return type
Transform- Returns
a reference to a transform component
- static get(name)
- Parameters
name (string) – The name of the transform to get
- Return type
Transform- Returns
a transform who’s name matches the given name
- static get_count()
- Return type
int
- Returns
the number of allocated transforms
- get_name()
- Return type
string
- Returns
the name of this component
- get_id()
- Return type
int
- Returns
the unique integer ID for this component
- static get_name_to_id_map()
- Return type
std::map< std::string,uint32_t,std::less< std::string >,std::allocator< std::pair< std::string const,uint32_t > > >
- Returns
A map whose key is a transform name and whose value is the ID for that transform
- static remove(name)
- Parameters
name (string) – The name of the transform to remove
- static initialize_factory(max_components)
Allocates the tables used to store all transform components
- is_initialized()
- Return type
boolean
- Returns
True the current transform is a valid, initialized transform, and False if the transform was cleared or removed.
- static clear_all()
Clears any existing transform components.
- static are_any_dirty()
- Return type
boolean
- Returns
True if any the transform has been modified since the previous frame, and False otherwise
- static get_dirty_transforms()
- Return type
std::set< nvisii::Transform * >
- Returns
a list of transforms that have been modified since the previous frame
- to_string()
- Return type
string
- Returns
a json string representation of the current component
- transform_direction(direction, previous=False)
Transforms direction from local to parent. This operation is not affected by scale or position of the transform. The returned vector has the same length as the input direction.
- transform_point(point, previous=False)
Transforms position from local to parent. Note, affected by scale. The opposite conversion, from parent to local, can be done with Transform.inverse_transform_point
- transform_vector(vector, previous=False)
Transforms vector from local to parent. This is not affected by position of the transform, but is affected by scale. The returned vector may have a different length that the input vector.
- inverse_transform_direction(direction, previous=False)
Transforms a direction from parent space to local space. The opposite of Transform.transform_direction. This operation is unaffected by scale.
- Parameters
point – The direction to apply the inverse transform to.
previous (boolean, optional) – If true, uses the previous transform as the transform to apply.
- Return type
- Returns
The transformed direction.
- inverse_transform_point(point, previous=False)
Transforms position from parent space to local space. Essentially the opposite of Transform.transform_point. Note, affected by scale.
- inverse_transform_vector(vector, previous=False)
Transforms a vector from parent space to local space. The opposite of Transform.transform_vector. This operation is affected by scale.
- Parameters
point – The vector to apply the inverse transform to.
previous (boolean, optional) – If true, uses the previous transform as the transform to apply.
- Return type
- Returns
The transformed vector.
- look_at(*args, **kwargs)
Rotates the transform so the forward vector points at the target’s current position. Then it rotates the transform to point its up direction vector in the direction hinted at by the parentUp vector.
- rotate_around(point, quaternion, previous=False)
Rotates the transform through the provided quaternion, passing through the provided point in parent coordinates. This modifies both the position and rotation of the transform.
- set_transform(transformation, decompose=True, previous=False)
Sets an optional additional transform, useful for representing normally unsupported transformations like sheers and projections.
- Parameters
transformation (
mat4) – a 4 by 4 column major transformation matrixdecompose (boolean, optional) – attempts to use the technique described in “Graphics Gems II: Decomposing a Matrix Into Simple Transformations” to represent the transform as a user controllable translation, rotation, and scale. If a sheer is detected, or if the decomposition failed, this will fall back to a non-decomposed transformation, and user controllable translation, rotation, and scale will be set to identity values.
previous (boolean, optional) – If true, edits the previous translation, rotation, and scale.
- get_rotation(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous rotation.
- Return type
- Returns
A quaternion rotating the transform from local to parent
- set_rotation(newRotation, previous=False)
Sets the rotation of the transform from local to parent via a quaternion
- Parameters
newRotation (
quat) – The new rotation quaternion to set the current transform quaternion to.previous (boolean, optional) – If true, edits the previous rotation.
- set_angle_axis(angle, axis, previous=False)
Sets the rotation of the transform from local to parent using an axis in local space to rotate about, and an angle in radians to drive the rotation.
- Parameters
angle (float) – The angle (in radians) to rotate.
axis (
vec3) – The axis to rotate about.previous (boolean, optional) – If true, edits the previous rotation.
- add_rotation(additionalRotation, previous=False)
Adds a rotation to the existing transform rotation from local to parent via a quaternion.
- Parameters
additionalRotation (
quat) – The rotation quaternion apply to the existing transform quaternion.previous (boolean, optional) – If true, edits the previous rotation.
- add_angle_axis(angle, axis, previous=False)
Adds a rotation to the existing transform rotation from local to parent using an axis in local space to rotate about, and an angle in radians to drive the rotation
- Parameters
angle (float) – The angle (in radians) to rotate the current transform quaterion by.
axis (
vec3) – The axis to rotate about.previous (boolean, optional) – If true, edits the previous rotation.
- get_position(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-space position.
- Return type
- Returns
a position vector describing where this transform will be translated to in its’ parent’s space.
- get_right(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-space right vector.
- Return type
- Returns
a vector pointing right relative to the current transform placed in its’ parent’s space.
- get_up(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-space up vector.
- Return type
- Returns
a vector pointing up relative to the current transform placed in its’ parent’s space.
- get_forward(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-space forward vector.
- Return type
- Returns
a vector pointing forward relative to the current transform placed in its’ parent’s space.
- get_world_position(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous world-space position.
- Return type
- Returns
a position vector describing where this transform will be translated to in world-space.
- get_world_right(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous world-space right vector.
- Return type
- Returns
a vector pointing right relative to the current transform placed in world-space.
- get_world_up(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous world-space up vector.
- Return type
- Returns
a vector pointing up relative to the current transform placed in world-space.
- get_world_forward(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous world-space forward vector.
- Return type
- Returns
a vector pointing forward relative to the current transform placed in world-space.
- set_position(newPosition, previous=False)
Sets the position vector describing where this transform should be translated to when placed in its parent space.
- Parameters
newPosition (
vec3) – The new position to set the current transform position to.previous (boolean, optional) – If true, edits the previous position.
- add_position(additionalPosition, previous=False)
Adds to the current the position vector describing where this transform should be translated to when placed in its parent space.
- Parameters
additionalPosition (
vec3) – The position (interpreted as a vector) to add onto the current transform position.previous (boolean, optional) – If true, edits the previous position.
- get_scale(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous scale.
- Return type
- Returns
the scale of this transform from local to parent space along its right, up, and forward directions respectively
- set_scale(newScale, previous=False)
Sets the scale of this transform from local to parent space along its right, up, and forward directions respectively.
- Parameters
newScale (
vec3) – The new scale to set the current transform scale to.previous (boolean, optional) – If true, edits the previous scale.
- add_scale(additionalScale, previous=False)
Adds to the current the scale of this transform from local to parent space along its right, up, and forward directions respectively
- Parameters
additionalScale (
vec3) – The scale to add onto the current transform scale.previous (boolean, optional) – If true, edits the previous scale.
- set_linear_velocity(velocity, frames_per_second=1.0, mix=0.0)
Sets the linear velocity vector describing how fast this transform is translating within its parent space. Causes motion blur.
- Parameters
velocity (
vec3) – The new linear velocity to set the current transform linear velocity to, in meters per second.frames_per_second (float, optional) – Used to convert meters per second into meters per frame. Useful for animations.
- set_angular_velocity(velocity, frames_per_second=1.0, mix=0.0)
Sets the angular velocity vector describing how fast this transform is rotating within its parent space. Causes motion blur.
- Parameters
velocity (
quat) – The new angular velocity to set the current transform angular velocity to, in radians per second.frames_per_second (float, optional) – Used to convert radians per second into scale per frame. Useful for animations.
- set_scalar_velocity(velocity, frames_per_second=1.0, mix=0.0)
Sets the scalar velocity vector describing how fast this transform is scaling within its parent space. Causes motion blur.
- Parameters
velocity (
vec3) – The new scalar velocity to set the current transform scalar velocity to, in additional scale per secondframes_per_second (float, optional) – Used to convert additional scale per second into additional scale per frame. Useful for animations.
- clear_motion()
Resets any “previous” transform data, effectively clearing any current motion blur.
- get_parent_to_local_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-to-local matrix.
- Return type
- Returns
the final matrix transforming this object from it’s parent coordinate space to it’s local coordinate space
- get_local_to_parent_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous local-to-parent matrix.
- Return type
- Returns
the final matrix transforming this object from it’s local coordinate space to it’s parents coordinate space
- get_local_to_parent_translation_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous local-to-parent translation matrix.
- Return type
- Returns
the final matrix translating this object from it’s local coordinate space to it’s parent coordinate space
- get_local_to_parent_scale_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous local-to-parent scale matrix.
- Return type
- Returns
the final matrix translating this object from it’s local coordinate space to it’s parent coordinate space
- get_local_to_parent_rotation_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous local-to-parent rotation matrix.
- Return type
- Returns
the final matrix rotating this object in it’s local coordinate space to it’s parent coordinate space
- get_parent_to_local_translation_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-to-local translation matrix.
- Return type
- Returns
the final matrix translating this object from it’s parent coordinate space to it’s local coordinate space
- get_parent_to_local_scale_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-to-local scale matrix.
- Return type
- Returns
the final matrix scaling this object from it’s parent coordinate space to it’s local coordinate space
- get_parent_to_local_rotation_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous parent-to-local rotation matrix.
- Return type
- Returns
the final matrix rotating this object from it’s parent coordinate space to it’s local coordinate space
- set_parent(parent)
Set the parent of this transform, whose transformation will be applied after the current transform.
- Parameters
parent (
Transform) – The transform component to constrain the current transform to. Any existing parent constraint is replaced.
- clear_parent()
Removes the parent-child relationship affecting this node.
- add_child(child)
Add a child to this transform, whose transformation will be applied before the current transform.
- Parameters
child (
Transform) – The child transform component to constrain to the current transform. Any existing parent constraint is replaced.
- remove_child(child)
Removes a child transform previously added to the current transform.
- Parameters
child (
Transform) – The constrained child transform component to un-constrain from the current transform. Any existing parent constraint is replaced.
- get_world_to_local_matrix(previous=False)
- Parameters
previous (boolean, optional) – If true, returns the previous world-to-local matrix.
- Return type
- Returns
a matrix transforming this component from world space to its local space, taking all parent transforms into account.