Calculate Axis-Aligned Bounding Box

SUMMARY

Calculate Axis-Aligned Bounding Box computes the smallest 3D box, aligned with the world's X/Y/Z axes, that contains every point in a point cloud.

It works directly off the point cloud's positions (normals and colors are ignored), returning the box's minimum corner plus its size along each axis. Because the box stays aligned with the world axes rather than rotating to fit the object, it is fast to compute and always well-defined, but it is not a tight fit for an object that is rotated relative to those axes.

Use this Skill when you want a fast, always-defined estimate of a point cloud's spatial extent and object orientation doesn't matter.

The Skill

from telekinesis import vitreous

bounding_box = vitreous.calculate_axis_aligned_bounding_box(point_cloud=point_cloud)

API Reference

Full parameter and return type documentation for calculate_axis_aligned_bounding_box.

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

Note: For Bounding Box comparison look at Calculate Oriented Bounding Box .

Raw Sensor Input

Unprocessed point cloud captured directly from the sensor. Shows full resolution, natural noise, and uneven sampling density.

Calculated Axis Aligned Oriented Bounding Box

Point cloud with axis aligned bounding box

The Code

"""
Demonstrates computing the axis-aligned bounding box (AABB) of a point cloud.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def calculate_axis_aligned_bounding_box_example():
    """
    Computes the axis-aligned bounding box (AABB) of a point cloud.

    Finds the smallest box aligned with coordinate axes that contains all points.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/can_vertical_1_raw_preprocessed.ply"
    # By default, the point cloud will be cached in the user cache directory for future runs.
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    axis_aligned_bounding_box = vitreous.calculate_axis_aligned_bounding_box(
        point_cloud=point_cloud
    )

    # ===================== Log =================================================
    logger.success(f"Calculated axis-aligned bounding box for {point_cloud}")
    logger.success(f"Results: {axis_aligned_bounding_box}")
    logger.info(f"Axis-aligned bounding box data: {axis_aligned_bounding_box.data}")
    logger.info(f"Axis-aligned bounding box shape: {axis_aligned_bounding_box.shape}")
    logger.info(f"Axis-aligned bounding box center: {axis_aligned_bounding_box.center}")
    logger.info(
        f"Axis-aligned bounding box size (height, width, depth): "
        f"{axis_aligned_bounding_box.height}, "
        f"{axis_aligned_bounding_box.width}, "
        f"{axis_aligned_bounding_box.depth}"
    )
    logger.info(f"Axis-aligned bounding box volume: {axis_aligned_bounding_box.volume}")

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


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

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to bound. Only positions are used; normals/colors are ignored.

Returns

Type	Description
datatypes.Box3D	The bounding box [min_x, min_y, min_z, width, height, depth] (the box's minimum corner plus its size along each axis, in meters). Use .data for the raw (6,) array, .center for the box center [cx, cy, cz], .width/.height/.depth for its per-axis size, and .volume for width * height * depth (cubic meters).

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
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

calculate_axis_aligned_bounding_box takes only point_cloud — there is nothing to tune. The box is fully determined by the min/max of the input positions along each axis, so the only way to change the result is to change the input point cloud itself.

If the box looks too large or noisy, the point cloud itself is usually the cause — a handful of outlier points far from the object will stretch the box to include them. Clean the input first with filter_point_cloud_using_statistical_outlier_removal or isolate the object first with cluster_point_cloud_using_dbscan before computing the box.

Where to Use the Skill

Common pipelines include:

• Per-cluster extent estimation – computing a quick bounding box for each object after cluster_point_cloud_using_dbscan separates a scene into individual objects
• Region-of-interest definition – using .center/.width/.height/.depth to define a crop or filter region for filter_point_cloud_using_bounding_box
• Coarse collision or containment checks – checking whether two objects' extents overlap without needing their exact orientation
• Quick size/volume reporting – using .volume to flag objects that are unexpectedly too small or too large before further processing

Alternative Skills

Skill	vs. Calculate Axis-Aligned Bounding Box
calculate_oriented_bounding_box	Lets the box rotate to fit the point cloud, giving a tighter box for a rotated or elongated object at higher compute cost. Use it whenever the object's orientation matters or the AABB looks much larger than the object itself.
calculate_point_cloud_centroid	Returns only the mean position, not size. Use it when you don't need extent information at all — an AABB's .center is not the same value as the centroid for a non-uniformly-distributed point cloud.

When Not to Use the Skill

Do not use Calculate Axis-Aligned Bounding Box when:

• Object orientation matters — e.g., for grasp planning or pose estimation. Use calculate_oriented_bounding_box instead.
• The object is significantly rotated relative to the world axes — the box will include large empty regions around the object.
• You need the tightest possible fit regardless of orientation — an AABB is, by construction, not tight for a rotated object.

TIP

If .volume looks much larger than you'd expect for the object, that's usually a sign the object is rotated relative to the world axes (or that outlier points are stretching the box). Try calculate_oriented_bounding_box and compare its .volume to confirm.