Foreground Image Segmentation with BiRefNet

2D Vision Processing

This tutorial walks you through on how to use cornea for foreground image segmentation using BiRefNet and visualize the result in Rerun.

Segmented Image Output

Foreground segmentation result 3 using BiRefNet

Run the Foreground Segmentation with BiRefNet from Cornea

Save the script

Create a file called quickstart_birefnet_example.py anywhere on your machine and paste the following:

"""Telekinesis quickstart: extract the foreground from an image with BiRefNet.

Loads a sample image from a public URL, runs BiRefNet foreground
segmentation, and visualizes the input alongside the predicted mask
in a Rerun viewer.

Run as a script - python quickstart_birefnet_example.py
"""

import cv2
import numpy as np
import requests
import rerun as rr
import rerun.blueprint as rrb
from loguru import logger

from datatypes import datatypes
from telekinesis import cornea, pupil


# Public sample image shipped by Telekinesis (you can swap this for a local file later).
IMAGE_URL = (
    "https://telekinesis-public-assets.s3.us-east-1.amazonaws.com/screws_standing.jpg"
)


def main() -> None:
    # Download and decode JPEG bytes to BGR, then convert to RGB for datatypes.Image
    response = requests.get(IMAGE_URL, timeout=60)
    response.raise_for_status()
    image_bgr = cv2.imdecode(
        np.frombuffer(response.content, dtype=np.uint8), cv2.IMREAD_COLOR,
    )

    image_bgr = datatypes.Image(image=image_bgr, color_model="BGR")
    image = pupil.convert_image_color_space(image_bgr, source_color_space="BGR", target_color_space="RGB")
    # Wrap pixels in Telekinesis's typed Image object.
    logger.success(f"Loaded image from {IMAGE_URL}")

    # Skill call: BiRefNet returns an annotation object we convert to a plain dict for logging
    result = cornea.segment_image_using_foreground_birefnet(
        image=image,
        mask_threshold=0,
    )
    annotation = result.to_dict()
    logger.success("BiRefNet foreground segmentation complete.")

    # Opens the Rerun viewer (spawn=True).
    rr.init("telekinesis_birefnet_quickstart", spawn=True)

    # Log input image and segmented image as separate entities.
    rr.log("input", rr.Image(image.to_numpy()))
    rr.log("segmented_mask", rr.Image(annotation["labeled_mask"]))


if __name__ == "__main__":
    main()

Run the script!

python quickstart_birefnet_example.py

Free TierEvery new account starts on a free tier with credits to call the SDK — no billing details required.Create API key →

Where to Go Next?

Ready to go deeper? Browse the Telekinesis Skill Examples repository for a runnable example covering every Skill.

Skill Examples

One runnable example per Skill, across vision, 3D, hardware, and robotics.

Explore the Docs

Skills

Vision, 3D, hardware, and robotics skills — the full API reference.

Agents

Turn natural-language instructions into robot code with Tzara, the VS Code agent.

Data Engine

Generate and manage synthetic datasets for training Physical AI models.

BabyROS

Lightweight pub/sub and service primitives for building robot communication layers.

Applications

Real-world use cases: pick-and-place, palletizing, quality inspection, and more.

Support

Join Discord

Ask questions, share what you're building, and get help from the community.

Add a Skill?

Have a new Skill to be added to Telekinesis? Get in touch with us.