Scale Point Cloud

SUMMARY

Scale Point Cloud applies uniform scaling to a point cloud about a specified center point.

Every point's position is multiplied by scale_factor relative to center_point, following p' = scale_factor * (p - center_point) + center_point. Points exactly at center_point stay fixed; every other point moves proportionally closer to or farther from it.

Use this Skill when you want to resize a point cloud uniformly while preserving its relative geometry, such as normalizing a CAD-derived model to real-world scale.

The Skill

from telekinesis import vitreous

scaled_point_cloud = vitreous.scale_point_cloud(
    point_cloud=point_cloud,
    scale_factor=0.3,
    center_point=[0.0, 0.0, 0.0],
)

API Reference

Full parameter and return type documentation for scale_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.

Scaled Pointcloud

Scaled pointcloud.
Parameters: scale = 0.3

The Code

"""
Demonstrates scaling a point cloud uniformly about a center point.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def scale_point_cloud_example():
    """
    Scales a point cloud uniformly about a center point.

    Multiplies all point coordinates by a scale factor relative to a center.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/relay_2_raw.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    scaled_point_cloud = vitreous.scale_point_cloud(
        point_cloud=point_cloud,
        center_point=[0.0, 0.0, 0.0],
        scale_factor=0.3,
    )

    # ===================== Log ================================================
    logger.success(
        f"Scaled {point_cloud} about center point [0.0, 0.0, 0.0] with scale factor 0.3"
    )
    logger.success(f"Results: {scaled_point_cloud}")
    logger.info(
        f"Scaled point cloud positions shape: {scaled_point_cloud.positions.shape}"
    )
    logger.info(
        f"Scaled point cloud has normals shape: "
        f"{scaled_point_cloud.normals.shape if scaled_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Scaled point cloud has colors shape: "
        f"{scaled_point_cloud.colors.shape if scaled_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init("scale_point_cloud_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/1-input_point_cloud")
    datatypes.visualize(scaled_point_cloud, entity_path="/2-scaled_point_cloud")


if __name__ == "__main__":
    scale_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/scale_point_cloud.py

Parameter Configuration

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to scale
scale_factor	datatypes.Float | float | int	required	Uniform scale factor. Must be > 0. Values > 1.0 enlarge the point cloud, values < 1.0 shrink it, and 1.0 leaves it unchanged
center_point	datatypes.Vector3D | np.ndarray | list[float]	required	The 3D point [x, y, z], in the point cloud's coordinate units, that scaling is performed about; points here are unaffected

Returns

Type	Description
datatypes.PointCloud	The point cloud with every point scaled about center_point. Use .positions for the scaled (N, 3) position array.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above), or (for a list center_point) it contains a non-numeric element
ValueError	scale_factor is not greater than 0, or center_point does not have exactly 3 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

scale_factor

• Controls: How much every point moves toward or away from center_point.
• Units: Dimensionless multiplier
• Default: required — no default, must be supplied
• Increase → enlarges the point cloud
• Decrease (toward 0) → shrinks it
• Typical range: 0.01–100.0 — use 0.1–0.5 to shrink, 0.5–2.0 for moderate scaling, 2.0–10.0 to enlarge significantly
• A value of exactly 1.0 leaves the cloud unchanged. Must be > 0, or a ValueError is raised — a zero or negative value is rejected rather than collapsing or inverting the point cloud

center_point

• Controls: The fixed point that scaling is performed about.
• Units: The point cloud's own coordinate units
• Default: required — no default, must be supplied
• Typically the point cloud's own centroid (from calculate_point_cloud_centroid), so the object scales about its own center rather than the world origin
• Must have exactly 3 elements, or a ValueError is raised

Where to Use the Skill

Common pipelines include:

• CAD-to-real-world normalization – rescale a CAD-derived point cloud to match measured real-world dimensions
• Unit conversion – convert a point cloud between millimeter, centimeter, and meter scales
• Simulation preparation – resize captured objects to match a simulator's expected scale
• Synthetic data augmentation – generate scaled variants of an object for training or testing downstream Skills

Alternative Skills

Skill	vs. Scale Point Cloud
apply_transform_to_point_cloud	Applies a general 4x4 matrix, so it can do non-uniform scaling, rotation, and translation together. Use it when uniform scaling about one center isn't enough.

When Not to Use the Skill

Do not use Scale Point Cloud when:

• You need non-uniform scaling (a different factor per axis) — use apply_transform_to_point_cloud with a matrix that has different diagonal terms instead
• You need to translate or rotate the point cloud — use apply_transform_to_point_cloud instead
• You need non-positive scaling — scale_factor must be > 0; a zero or negative value raises a ValueError rather than collapsing or inverting the point cloud

TIP

Use calculate_point_cloud_centroid to get a natural center_point so the object scales about its own center rather than an arbitrary point like the origin.