# Image API conformance

iiisight can **probe an Image API service** for conformance: it loads `info.json`,
issues the requests appropriate to the service's claimed compliance level, and —
for requests whose output size is predictable — verifies the server returns an
image of the **expected pixel dimensions**, not merely an HTTP 200.

Dimensions are read straight from the returned image's header (JPEG / PNG / GIF),
so there is **no image-decoding dependency** — the probe is built in.

## Probing a service

Pass an image-service base URL, an already-loaded {class}`~iiisight.ImageService`,
or a {class}`~iiisight.Canvas` (its primary image service is used):

::::{tab-set}
:::{tab-item} Async
```python
async with iiisight.AsyncClient() as client:
    report = await client.check_compliance("https://example.org/iiif/image")
```
:::
:::{tab-item} Sync
```python
with iiisight.Client() as client:
    report = client.check_compliance("https://example.org/iiif/image")
```
:::
::::

## The report

`check_compliance` returns a {class}`~iiisight.ConformanceReport`:

```python
report.claimed_level        # e.g. "level2"
report.conforms             # did every check at/below the claimed level pass?
report.summary()            # "5/6 checks passed; conforms to level2"
for check in report.failed:  # also .passed / .checks
    print(check.name, check.url, check.detail)
```

Each {class}`~iiisight.Check` records a feature (`full image`, `sizeByW`,
`regionByPx`, `regionByPct`, `rotationBy90`, a listed size), the level it belongs
to, the URL requested, whether it passed, and a human detail like
`got 500x400, expected ~500x400`.

The probe only issues requests appropriate to the claimed level (a `level0`
service is checked against `full/max` and its advertised `sizes`; `level1`/`level2`
features are checked only when claimed), so `conforms` answers *"does the server
honor the level it advertises?"*

## From the command line

```console
$ iiisight probe https://example.org/iiif/image
https://example.org/iiif/image  claimed: level2
  PASS  full image     got 6000x4000, expected ~6000x4000
  PASS  sizeByW        got 3000x2000, expected ~3000x2000
  FAIL  regionByPx     got 6000x4000, expected ~3000x2000
  ...
4/6 checks passed; does NOT conform to level2
```

Exits `0` when the service conforms, `1` when it doesn't, `2` on error. `--json`
emits the full report.

## Measuring image dimensions directly

The header reader is exposed as {func}`iiisight.image_size` if you want it:

```python
width_height = iiisight.image_size(jpeg_or_png_or_gif_bytes)   # (w, h) or None
```