tests/README.md

FoundationPose Tests

This directory contains test scripts for the FoundationPose HuggingFace API.

Test Data

Reference images for test objects are stored in reference/target_cube/.

Running Tests

Test Against HuggingFace Space

cd /path/to/foundationpose
/path/to/training/.venv/bin/python tests/test_estimator.py

The test uses the Gradio client to connect to the deployed API.

Test Coverage

test_estimator.py tests:

1. API client initialization
2. Object initialization via API (reference-based)
3. Pose estimation on query images

Current Status

CAD-Based Mode: ✅ Fully Implemented

• Requires a 3D mesh file (.obj, .stl, .ply)
• Provides accurate 6D pose estimation
• Use the CAD-Based initialization tab in the Gradio interface

Model-Free Mode: ⚠️ Not Yet Implemented

• Would require 3D reconstruction from reference images (photogrammetry)
• For now, use photogrammetry tools (Meshroom, COLMAP) to create a mesh first
• Then use CAD-Based mode with the generated mesh

API Usage

The deployed Space provides two Gradio API endpoints:

CAD-Based Initialization

from gradio_client import Client, handle_file

client = Client("https://gpue-foundationpose.hf.space")

result = client.predict(
    object_id="my_object",
    mesh_file=handle_file("object.obj"),
    reference_files=[handle_file(f) for f in image_files],  # Optional
    fx=500.0, fy=500.0, cx=320.0, cy=240.0,
    api_name="/gradio_initialize_cad"
)

Pose Estimation

result = client.predict(
    object_id="my_object",
    query_image=handle_file("query.jpg"),
    fx=500.0, fy=500.0, cx=320.0, cy=240.0,
    api_name="/gradio_estimate"
)

Known Issues

1. Model-Free Mode: Reference-only initialization is not yet supported. A 3D mesh is required.
2. Test Results: Current tests will return "No poses detected" because they don't provide a mesh file.