Telekinesis Agentic Skill Library

Appearance

Calculate Image PCA ​

SUMMARY

Calculate Image PCA computes principal component analysis on a binary mask and returns a visualization.

PCA finds the centroid, eigenvectors, eigenvalues, and principal angle of the mask. The output image shows the mask with the centroid and principal axis overlaid, useful for shape orientation analysis, alignment, and morphological characterization of binary regions.

Use this Skill when you want to analyze the principal orientation and centroid of a binary mask.

The Skill ​

python
from telekinesis import pupil

result_image = pupil.calculate_image_pca(image=image)

API Reference

Example ​

Input Image

Input image

Original binary mask

Output

Output image

Mask with centroid and principal axis overlaid

The Code ​

python
from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load image
filepath = str(DATA_DIR / "images" / "gear_with_texture.jpg")
image = io.load_image(filepath=filepath, as_binary=True, binary_method="fixed")
logger.success(f"Loaded image from {filepath}")

# Compute PCA on binary mask
binary_mask = image.to_numpy()
centroid, eigenvectors, eigenvalues, angle = pupil.calculate_image_pca(image=image)
centroid = centroid.to_numpy()
eigenvectors = eigenvectors.to_numpy()
eigenvalues = eigenvalues.to_numpy()
angle = angle.value

The Explanation of the Code ​

The code begins by importing the necessary modules: pupil for image processing operations, io for data handling, pathlib for path management, and loguru for logging.

python
from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

Next, a binary mask is loaded from a .jpg file using the io.load_image function. The image is loaded as binary using as_binary=True, which is required for PCA computation on foreground pixels.

python
DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load binary image
filepath = str(DATA_DIR / "images" / "gear_with_texture.jpg")
image = io.load_image(filepath=filepath, as_binary=True, binary_method="fixed")

The main operation uses the calculate_image_pca Skill from the pupil module. This Skill computes principal component analysis on a binary mask, returning centroid, eigenvectors, eigenvalues, and principal angle for shape orientation analysis.

python
centroid, eigenvectors, eigenvalues, angle = pupil.calculate_image_pca(image=image)

Finally, the results are converted to NumPy arrays using to_numpy() for further processing, visualization, or downstream tasks.

python
centroid = centroid.to_numpy()
eigenvectors = eigenvectors.to_numpy()
eigenvalues = eigenvalues.to_numpy()
angle = angle.value

This operation is particularly useful in robotics and vision pipelines for shape orientation analysis, alignment, morphological characterization, and quality inspection, where analyzing the principal orientation and centroid of a binary mask is required.

Running the Example ​

Runnable examples are available in the Telekinesis examples repository. Follow the README in that repository to set up the environment. Once set up, you can run this specific example with:

bash
cd telekinesis-examples
python examples/pupil_examples.py --example calculate_image_pca

How to Tune the Parameters ​

The calculate_image_pca Skill has no tunable parameters. It operates on a binary mask and returns a visualization image with the centroid and principal axis overlaid. Ensure the input is binary (foreground/background) for correct PCA computation.

Where to Use the Skill in a Pipeline ​

Calculate Image PCA is commonly used in the following pipelines:

  • Shape orientation analysis - Determine the principal axis of binary regions
  • Alignment - Align objects by their principal direction
  • Morphological characterization - Extract centroid and orientation for shape descriptors
  • Quality inspection - Verify part orientation in manufacturing

Related skills to build such a pipeline:

  • calculate_image_centroid: Get centroid only (no visualization)
  • filter_image_using_morphological_erode: Clean binary masks before PCA
  • align_image_circle_center: Alternative alignment method using circles

When Not to Use the Skill ​

Do not use Calculate Image PCA when:

  • You're working with grayscale or color images (Convert to binary first)
  • You need 3D orientation (Use point cloud PCA instead)
  • The mask has multiple disconnected regions (PCA analyzes the combined region)