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],
    modify_inplace=False,
)

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,
        modify_inplace=False,
    )

    # ===================== 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

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to scale
scale_factor	datatypes.Float | float | int	required	Uniform scale factor. 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 meters, that scaling is performed about; points here are unaffected
modify_inplace	datatypes.Bool | bool	False	Hint for how the server reuses buffers internally while scaling. Does not mutate your local point_cloud variable either way — always use the function's return value

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	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, 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 input, invalid data, or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired
AuthenticationServiceError	The authentication service was unavailable
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. A value of 0 or a negative value is not validated by this Skill and will collapse or invert the point cloud instead of raising an error — see the warning below

center_point

• Controls: The fixed point that scaling is performed about.
• Units: Meters
• 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

modify_inplace

• Controls: A hint to the server about whether to reuse the input's buffer or allocate a new one internally while scaling. This is purely a server-side, remote-call detail.
• Units: Boolean
• Default: False
• Important: Since scale_point_cloud is a remote API call, it does not mutate your local point_cloud variable either way — always use this function's return value to get the scaled result.

WARNING

scale_factor is not validated to be positive. A value of 0 collapses every point onto center_point, and a negative value inverts the point cloud through center_point. Keep scale_factor > 0 unless that inversion is intentional.

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
• scale_factor could be zero or negative — this Skill does not validate that, and will collapse or invert the point cloud instead of raising an error
• You're relying on modify_inplace=True to mutate your local variable — it won't; this is a remote call, so only the return value carries the result either way

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.