| --- |
| 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 |
|
|
