README.md

---
tags:
- object-detection
- callout-detection
- architectural-drawings
- wrapper
library_name: custom
task: object-detection
license: apache-2.0
---

# LearningStudio Callout Detection Wrapper

Wrapper for the Lambda-based callout detection pipeline, providing EMCO-compatible API format for LearningStudio integration.

## Overview

This wrapper:
1. Accepts image input in multiple formats (URL, base64, data URL)
2. Gets a presigned S3 URL from API Gateway
3. Uploads the image directly to S3 (avoids API Gateway data transfer costs)
4. Starts the detection job via API Gateway (small JSON payload)
5. Polls for completion
6. Transforms results to EMCO-compatible format

## Architecture

```
HF Wrapper
    │
    ├─1─▶ GET /upload-url (get presigned S3 URL)
    │
    ├─2─▶ PUT image directly to S3 (free, bypasses API Gateway)
    │
    ├─3─▶ POST /detect {"job_id", "s3_url"} (tiny payload)
    │
    └─4─▶ GET /status/{job_id} (poll until complete)
```

## API Format

### Input

Accepts images in multiple formats:

```json
// HTTP URL
{"inputs": "https://example.com/image.jpg"}

// Data URL (base64 encoded)
{"inputs": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."}

// Raw base64
{"inputs": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."}
```

### Output

Returns EMCO-compatible format:

```json
{
  "predictions": [
    {
      "id": 1,
      "label": "callout",
      "class_id": 0,
      "confidence": 0.95,
      "bbox": {
        "x1": 100,
        "y1": 200,
        "x2": 300,
        "y2": 400
      }
    }
  ],
  "total_detections": 1,
  "image": "base64_encoded_image",
  "image_width": 1920,
  "image_height": 1080
}
```

### Bounding Box Format

- **Input from Lambda**: `[x, y, width, height]` (xywh format)
- **Output to LearningStudio**: `{"x1", "y1", "x2", "y2"}` (xyxy format)

The wrapper automatically converts between these formats.

## Configuration

This endpoint requires the following secrets to be configured in HuggingFace Inference Endpoint settings:

| Secret | Description |
|--------|-------------|
| `API_GATEWAY_URL` | Full URL of the API Gateway endpoint (e.g., `https://xxx.execute-api.us-east-1.amazonaws.com/dev`) |
| `API_KEY` | API key for authentication |

## Usage

### Python

```python
import requests

HF_ENDPOINT = "https://your-endpoint.endpoints.huggingface.cloud"
HF_TOKEN = "your-hf-token"

response = requests.post(
    HF_ENDPOINT,
    headers={"Authorization": f"Bearer {HF_TOKEN}"},
    json={"inputs": "https://example.com/architectural-drawing.png"}
)

result = response.json()
print(f"Found {result['total_detections']} callouts")
for pred in result["predictions"]:
    print(f"  Callout {pred['id']}: {pred['bbox']}, confidence={pred['confidence']}")
```

### cURL

```bash
curl -X POST https://your-endpoint.endpoints.huggingface.cloud \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "https://example.com/architectural-drawing.png"}'
```

## Processing Time

Typical processing time is 30-120 seconds depending on image size and complexity. The wrapper polls the backend every 5 seconds with a maximum timeout of 15 minutes.

## Error Handling

Errors are returned in a consistent format:

```json
{
  "error": "Description of the error",
  "predictions": [],
  "total_detections": 0,
  "image": ""
}
```

## License

Apache 2.0