Apply Transform to Point Cloud

SUMMARY

Apply Transform to Point Cloud applies a 4x4 rigid-body (or affine) transform to every point in a point cloud.

It transforms every point's position — and its normal, if present — by transformation_matrix, rotating, translating, and/or scaling the whole point cloud at once. It's the natural next step after any of the register_point_clouds_using_* Skills, which compute exactly this kind of transform and are demonstrated feeding straight into this function in their own reference examples.

Use this Skill when you need to move, rotate, or align a point cloud into a common coordinate frame, such as after registration or pose estimation.

The Skill

from telekinesis import vitreous
import numpy as np

transformed_point_cloud = vitreous.apply_transform_to_point_cloud(
    point_cloud=point_cloud,
    transformation_matrix=np.eye(4),
)

API Reference

Full parameter and return type documentation for apply_transform_to_point_cloud.

View Reference →

Data Transfer Notice

There is no longer a fixed limit of 1 million points per request. However, very large datasets may result in slower data transfer and processing times. We are continuously optimizing performance as part of our beta program, with ongoing improvements to enhance speed and reliability.

Example

Raw Pointcloud

Unprocessed point cloud. The origin of the point cloud corresponds with the origin of the scene.

Transformed Pointcloud

The origin of the point cloud is transformed according to the transformation matrix.

The Code

"""
Demonstrates applying a 6-DOF rigid transformation (rotation + translation) to a point cloud.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def apply_transform_to_point_cloud_example():
    """
    Applies a 6-DOF rigid transformation (rotation + translation) to a point cloud.

    Transforms points using a 4x4 homogeneous transformation matrix.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/plastic_centered.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    transformed_point_cloud = vitreous.apply_transform_to_point_cloud(
        point_cloud=point_cloud,
        transformation_matrix=[
            [1, 0, 0, 15],
            [0, 1, 0, 15],
            [0, 0, 1, 5],
            [0, 0, 0, 1],
        ]
    )

    # ===================== Log ================================================
    logger.success(f"Applied transform to {point_cloud}")
    logger.success(f"Results: {transformed_point_cloud}")
    logger.info(
        f"Transformed point cloud positions shape: {transformed_point_cloud.positions.shape}"
    )
    logger.info(
        f"Transformed point cloud has normals shape: "
        f"{transformed_point_cloud.normals.shape if transformed_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Transformed point cloud has colors shape: "
        f"{transformed_point_cloud.colors.shape if transformed_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init("apply_transform_to_point_cloud_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/1-source_point_cloud")
    datatypes.visualize(
        transformed_point_cloud, entity_path="/2-transformed_point_cloud"
    )


if __name__ == "__main__":
    apply_transform_to_point_cloud_example()

Runnable examples are available in the Telekinesis examples repository.

Follow the README in that repository to set up the environment, run this specific example with:

cd telekinesis-examples
python examples/point_cloud/apply_transform_to_point_cloud.py

Parameter Configuration

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to transform
transformation_matrix	datatypes.Mat4x4 | np.ndarray | list[list[float]]	required	The 4x4 transform to apply, typically [[R | t], [0, 0, 0, 1]] — a 3x3 rotation R plus a translation t — though any invertible 4x4 matrix is accepted (not just a rigid-body transform)

Returns

Type	Description
datatypes.PointCloud	The point cloud with every point (and normal, if present) transformed by transformation_matrix. Use .positions for the transformed (N, 3) position array.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
ValueError	transformation_matrix is not shape (4, 4), is not invertible, or (for a list input) it doesn't contain only numeric elements
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, the response was not returned as an Arrow stream, or the response failed to deserialize
RequestTimeoutError	The request to the Vitreous service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Vitreous service rejected the request due to invalid or malformed input (HTTP 400/422), an unrecognized endpoint (HTTP 404), or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired (HTTP 401)
AuthenticationServiceError	The authentication service returned an invalid response, was temporarily unavailable, or timed out (HTTP 502/503/504)
ServerError	The Vitreous service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

transformation_matrix

• Controls: The rotation, translation, and/or scaling applied to every point.
• Units: N/A — a (4, 4) homogeneous transform matrix; rotation/scaling terms are dimensionless, translation terms are in meters
• Default: required — no default, must be supplied
• Typically a rigid-body transform [[R | t], [0, 0, 0, 1]] produced by a register_point_clouds_using_* Skill, or np.eye(4) for the identity (no-op) transform
• Must be shape (4, 4) and invertible — both are checked client-side, raising ValueError otherwise. A non-rigid but invertible matrix (e.g. non-uniform scale or shear) is still accepted and applied without error

TIP

Feed the output of a register_point_clouds_using_* Skill (e.g. register_point_clouds_using_point_to_point_icp) directly into transformation_matrix — that's the transform this Skill is designed to consume.

Where to Use the Skill

Common pipelines include:

• Post-registration alignment – apply the transform returned by a register_point_clouds_using_* Skill to bring a scan into a shared frame
• Multi-view fusion prep – align each view's point cloud into a common frame before combining them with add_point_clouds
• Robot coordinate conversion – move a point cloud from sensor space into robot base or world coordinates
• Pose-driven repositioning – move a point cloud to reflect a newly estimated 6-DOF pose

Alternative Skills

Skill	vs. Apply Transform to Point Cloud
scale_point_cloud	Handles only uniform scaling about a center point, with a simpler two-number interface. Use it instead of building a scaling matrix by hand when you don't also need rotation or translation.
register_point_clouds_using_point_to_point_icp	Computes the transformation_matrix this Skill applies, rather than applying one. Run it first to get a transform out of two point clouds.

When Not to Use the Skill

Do not use Apply Transform to Point Cloud when:

• You only need uniform scaling about a point — scale_point_cloud offers a simpler two-parameter interface for that specific case
• You only need to transform a subset of points — filter or segment the point cloud first, then transform the result
• You need a genuinely non-rigid deformation — this Skill applies a single linear 4x4 transform (rigid or affine) to every point, not a per-point or non-linear warp
• You don't yet have a transform to apply — compute one first, e.g. with a register_point_clouds_using_* Skill