# ShelfApi — Agent Reference

You are interacting with **ShelfApi**, a service that detects and isolates product display areas in retail photos. It works with regular shelf bays, endcap displays (kopstellingen), and checkout displays (kassameubels).

## Base URL

Production: `https://shelfapi.wiggert.nl`

## Endpoints

### POST /api/process-shelf

Upload a photo, get back the processed image with the product area isolated.

**Parameters (query string):**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `method` | string | `blur` | How to handle area outside the product region: `blur`, `black`, or `crop` |
| `correct_perspective` | bool | `true` | Warp the detected trapezoid to a rectangle |
| `correct_horizontal` | bool | `false` | Rotate image to level horizontal shelf lines |
| `detector` | string | `cnn` | Detection method: `cnn` (fast, local) or `gemini` (cloud, needs API key) |
| `output_format` | string | `jpeg` | Output format: `jpeg` or `png` |

**Request:** `multipart/form-data` with field `image` containing the photo file.

**Response:** The processed image as `image/jpeg` or `image/png`.

```bash
# Basic usage — blur masking with perspective correction
curl -X POST -F "image=@photo.jpg" \
  "http://localhost:8000/api/process-shelf" -o result.jpg

# Crop to detected region only
curl -X POST -F "image=@photo.jpg" \
  "http://localhost:8000/api/process-shelf?method=crop" -o cropped.jpg

# All corrections enabled
curl -X POST -F "image=@photo.jpg" \
  "http://localhost:8000/api/process-shelf?method=blur&correct_perspective=true&correct_horizontal=true" \
  -o result.jpg
```

### POST /api/detect-meters

Upload a photo, get back boundary detection as JSON. Useful when you need the raw boundary data without image processing.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `detector` | string | `cnn` | `cnn` or `gemini` |

**Response (JSON):**

```json
{
  "left_top_pct": 12.3,
  "left_bottom_pct": 14.1,
  "right_top_pct": 87.5,
  "right_bottom_pct": 85.9,
  "left_boundary_pct": 13.2,
  "right_boundary_pct": 86.7,
  "top_left_pct": 0.0,
  "top_right_pct": 0.0,
  "bottom_left_pct": 100.0,
  "bottom_right_pct": 100.0,
  "top_boundary_pct": 0.0,
  "bottom_boundary_pct": 100.0,
  "left_confidence": "HIGH",
  "right_confidence": "HIGH",
  "source": "cnn"
}
```

All `_pct` values are percentages. X values: 0 = left edge, 100 = right edge. Y values: 0 = top edge, 100 = bottom edge.

- `left_top_pct` / `left_bottom_pct`: x-position of left boundary at top/bottom of image
- `right_top_pct` / `right_bottom_pct`: x-position of right boundary at top/bottom of image
- `top_left_pct` / `top_right_pct`: y-position of top boundary at left/right of image
- `bottom_left_pct` / `bottom_right_pct`: y-position of bottom boundary at left/right of image
- `*_boundary_pct`: averaged values for simpler use

For regular shelf photos, top/bottom values will be 0/100 (full height). For checkout displays, they indicate where the display starts/ends vertically.

```bash
curl -X POST -F "image=@photo.jpg" "http://localhost:8000/api/detect-meters"
```

### GET /api/dataset/stats

Returns dataset statistics.

```json
{"total_images": 3814, "annotated": 3408, "verified": 880, "unannotated": 406}
```

## Usage tips

- **Default settings work well for most cases.** Just POST the image to `/api/process-shelf` and you get a blurred result with perspective correction.
- **Use `method=crop`** when you want only the product area with no surrounding context.
- **Use `correct_horizontal=true`** when shelf lines appear tilted — this rotates the image to level them.
- **The CNN detector is recommended** — it runs locally in ~50ms (CPU) and doesn't need an API key.
- **Top/bottom boundaries matter for checkout displays.** For regular shelves, the model correctly returns 0%/100% (full height).

## Photo types supported

| Type | Description | Boundaries used |
|------|-------------|-----------------|
| Shelf bay | Standard gondola section | Left/right only (top/bottom = 0/100%) |
| Endcap (kopstelling) | End-of-aisle display | Left/right only |
| Checkout display (kassameubel) | Products near register | Left/right + top/bottom |

## Integration example (Python)

```python
import httpx

SHELFAPI_URL = "http://localhost:8000"

# Process a photo
with open("shelf.jpg", "rb") as f:
    response = httpx.post(
        f"{SHELFAPI_URL}/api/process-shelf",
        files={"image": ("shelf.jpg", f, "image/jpeg")},
        params={"method": "crop"},
    )
    with open("result.jpg", "wb") as out:
        out.write(response.content)

# Get boundary data
with open("shelf.jpg", "rb") as f:
    response = httpx.post(
        f"{SHELFAPI_URL}/api/detect-meters",
        files={"image": ("shelf.jpg", f, "image/jpeg")},
    )
    detection = response.json()
    print(f"Left: {detection['left_boundary_pct']:.1f}%")
    print(f"Right: {detection['right_boundary_pct']:.1f}%")
```