Detect Objects Using YOLOX

SUMMARY

Detect Objects Using YOLOX detects objects using YOLOX and returns COCO-style detection results with category ids from the COCO 80-class label set.

This Skill is designed for fast and reliable object detection in scenarios such as real-time object monitoring and warehouse or logistics inspection. For example, identifying boxes, pallets, forklifts, or workers in warehouse environments.

Use this Skill when you want to detect and label objects using COCO 80-class categories as fast as possible.

The Skill

from telekinesis import retina

detection_results = retina.detect_objects_using_yolox(
    image=image,
    score_threshold=0.80,
    nms_threshold=0.45,
)

API Reference

Full parameter and return type documentation for detect_objects_using_yolox.

View Reference →

Example

Input Image

Original image

Detected Objects

Detected objects with bounding boxes, labels and scores.

The Code

"""
Detect objects using YOLOX.
"""

from loguru import logger
import rerun as rr

from telekinesis import retina, constants, datatypes


def detect_objects_using_yolox_example():
    """
    Detect objects using YOLOX.

    Runs YOLOX object detection on an image and returns object detections using datatype
    `COCOObjectDetectionResults`
    """
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/warehouse_2.jpg"
    image = datatypes.Image.from_url(url=image_url)
    logger.info(f"Loaded {image} from the URL: {image_url}")

    # ===================== Run Skill ==========================================
    detection_results = retina.detect_objects_using_yolox(
        image=image,
        score_threshold=0.80,
        nms_threshold=0.45,
    )

    # ===================== Log ================================================
    logger.success(f"Detected objects in {image} using YOLOX.")
    logger.success(f"Results: {detection_results}")

    categories = constants.get_coco_categories(model="yolox")
    logger.info(f"YOLOX categories: {categories}")

    logger.info(f"All detected object bounding boxes: {detection_results.bboxes}")
    logger.info(f"All detected object scores: {detection_results.scores}")
    logger.info(f"All detected object category IDs: {detection_results.category_ids}")

    # Indexed objects are of type the single `COCOObjectDetectionResult`
    logger.info(f"Detected object at index 0: {detection_results[0]}")
    logger.info(f"Detected object at index 0 bounding box: {detection_results[0].bbox}")
    logger.info(f"Detected object at index 0 score: {detection_results[0].score}")
    logger.info(
        f"Detected object at index 0 category ID: {detection_results[0].category_id}"
    )
    logger.info(
        f"Detected object at index 0 category name: {categories[detection_results[0].category_id]}"
    )

    # ===================== Visualization  (Optional) ======================
    rr.init("detect_objects_using_yolox_example", spawn=True)
    datatypes.visualize(image, entity_path="/image")
    datatypes.visualize(detection_results, entity_path="/image/overlayed_detections")


if __name__ == "__main__":
    detect_objects_using_yolox_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/detection/detect_objects_using_yolox.py

Parameter Configuration

Key	Type	Default	Description
image	datatypes.Image | np.ndarray | list	required	Input image. Supported shapes are (H, W), (H, W, 1), or (H, W, 3) — 4-channel (alpha) images are not supported
score_threshold	datatypes.Float | float | int	0.25	Minimum confidence score required for a detection to be returned
nms_threshold	datatypes.Float | float | int	0.45	IoU threshold used by non-maximum suppression to merge overlapping detections

INFO

detect_objects_using_yolox returns detections only — it does not return category names. Look up names separately with constants.get_coco_categories(model="yolox"), indexed by category_id. YOLOX predicts contiguous COCO category ids (0–79), unlike RF-DETR's sparse ids, so this lookup is a direct index either way.

Returns

Type	Description
datatypes.COCOObjectDetectionResults	The detected objects. Access the grouped arrays via .bboxes (shape (N, 4), [x, y, w, h]), .scores (shape (N,)), and .category_ids (shape (N,)), or index a single detection with detections[i] to get its .bbox, .score, and .category_id.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
ValueError	image has an unsupported shape, or score_threshold/nms_threshold is outside the valid 0.0–1.0 range
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 Retina service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Retina 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 Retina service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

YOLOX has two tunable parameters.

score_threshold

• Controls: The minimum confidence score required for a detection to be returned.
• Default: 0.25
• Increase → fewer, higher-confidence detections (reduces false positives)
• Decrease → more detections kept, including lower-confidence ones (improves recall for small, partially occluded, or hard-to-detect objects)
• Typical range: 0.3–0.9

nms_threshold

• Controls: The IoU (overlap) threshold used by non-maximum suppression to merge overlapping detections of the same object.
• Default: 0.45
• Increase → keeps more overlapping boxes (higher recall, potentially more duplicates)
• Decrease → suppresses duplicates more aggressively (cleaner output, potentially lower recall)
• Typical range: 0.3–0.6

TIP

Best practice: Start with score_threshold=0.80 and nms_threshold=0.45. Lower score_threshold toward the library default of 0.25 if true objects are being missed; raise it if you see false positives. Adjust nms_threshold next to balance duplicate suppression against recall.

Where to Use the Skill

Common pipelines include:

• Real-time object monitoring – Detecting and labeling objects in video frames
• Warehouse and logistics inspection – Fast object localization and category labeling for operations

Alternative Skills

Skill	vs. Detect Objects Using YOLOX
detect_objects_using_rfdetr	Use RF-DETR when you need stronger global context modeling and can trade speed for quality.
detect_objects_using_qwen / detect_objects_using_grounding_dino	Use these when the objects you need aren't in the fixed 80-class COCO set that YOLOX is trained on.

When Not to Use the Skill

Do not use Detect Objects Using YOLOX when:

• Maximum accuracy on complex scenes is the top priority (RF-DETR may perform better on difficult cases)
• Objects are heavily occluded and require stronger global reasoning
• Latency is not a concern and you prefer transformer-based detectors for quality