LearningStudio Callout Detection Wrapper

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

Overview

This wrapper:

Accepts image input in multiple formats (URL, base64, data URL)
Gets a presigned S3 URL from API Gateway
Uploads the image directly to S3 (avoids API Gateway data transfer costs)
Starts the detection job via API Gateway (small JSON payload)
Polls for completion
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:

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

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

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

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:

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

License

Apache 2.0

Downloads last month: -; Downloads are not tracked for this model. How to track