Points3D

Represents a 3D point cloud comprising positions and optional per-point normals and colors. This datatype serves as the primary input and output for point-cloud operations within the Telekinesis ecosystem, including filtering, segmentation, and registration.

Field

Required

Field	Type	Description
positions	ArrayLike	3D positions; shape (N, 3), dtype float32.

Optional

Field	Type	Description
normals	ArrayLike	3D normals; shape (N, 3), dtype float32. Must match number of positions if provided.
colors	Rgba32ArrayLike	Colors; length 1 or N, dtype uint8, shape (N, 4).

Methods

Method	Description
to_numpy(attribute)	Returns the given attribute as a NumPy array. attribute: one of "positions" → shape (N, 3) float32, "normals" → shape (N, 3) float32, or "colors" → shape (N, 4) uint8 (if present).

Example

From the datatypes examples:

import numpy as np
from datatypes import datatypes
from loguru import logger

# ------------------------------------------------
# 1. Create Points3D instance
# ------------------------------------------------
input_positions = np.array([
    [0, 0, 0],
    [1, 0, 0],
    [0, 1, 0],
    [0, 0, 1],
], dtype=np.float32)

input_colors = np.array([
    [255, 0, 0, 255],
    [0, 255, 0, 255],
    [0, 0, 255, 255],
    [255, 255, 0, 255],
], dtype=np.uint8)

input_normals = np.array([
    [0, 0, 1],
    [0, 0, 1],
    [0, 0, 1],
    [0, 0, 1],
], dtype=np.float32)

points = datatypes.Points3D(
    positions=input_positions,
    normals=input_normals,
    colors=input_colors,
)

# ------------------------------------------------
# 2. Access data via to_numpy
# ------------------------------------------------
positions = points.to_numpy("positions")
colors = points.to_numpy("colors")
normals = points.to_numpy("normals")

logger.info("Points3D to_numpy positions shape={}", positions.shape)
logger.info("Points3D to_numpy colors shape={}", colors.shape if colors is not None else None)
logger.info("Points3D to_numpy normals shape={}", normals.shape if normals is not None else None)