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

```bash
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
```python
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
```python
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.