# Images & tiles

iiisight's tile-aware Image API support is one of its two capabilities that exist
nowhere else in Python (async fetching is the other). Given a manifest's image
service, it loads `info.json`, builds spec-correct URLs, and computes the tile
grid — handling the v2/v3 differences for you.

## Loading an image service

A `Canvas.image_service` carries only what the manifest embedded (usually an id
and profile). To get tiles and sizes, fetch its `info.json` with `load_info()` —
an explicit network call:

::::{tab-set}
:::{tab-item} Async
```python
async with iiisight.AsyncClient() as client:
    manifest = await client.fetch_manifest(url)
    service = await client.load_info(manifest.canvases[0])   # or pass an ImageService
    print(service.width, service.height, service.compliance_level, service.loaded)
```
:::
:::{tab-item} Sync
```python
with iiisight.Client() as client:
    manifest = client.fetch_manifest(url)
    service = client.load_info(manifest.canvases[0])
    print(service.width, service.height, service.compliance_level, service.loaded)
```
:::
::::

## Building URLs

{meth}`~iiisight.ImageService.url` assembles an Image API URL. `size="max"` is
emitted as `full` for a v2 service and `max` for a v3 one — the most common
v2/v3 footgun, handled automatically.

```python
service.url()                                          # full / max region+size
service.url(region="0,0,100,100", size="100,")         # a specific region
service.url(rotation="90", quality="gray", fmt="png")
service.thumbnail_url(width=400)                        # prefers an advertised size
```

## Computing tiles

{meth}`~iiisight.ImageService.tile_grid` enumerates the tile requests covering the
whole image at a given scale factor, with correct edge-tile clamping. Each
{class}`~iiisight.Tile` has `region`, `size`, and a ready-to-fetch `url`.

```python
for tile in service.tile_grid(scale_factor=4):
    print(tile.region, tile.size, tile.url)

all_tiles = service.tile_pyramid()   # every advertised scale factor
```

Requesting a scale factor the service does not advertise raises
{class}`~iiisight.UnknownScaleFactor`; calling `tile_grid` before `load_info`
raises {class}`~iiisight.ImageServiceNotLoaded`.

## Fetching image bytes

```python
data = await client.fetch_region(service, region="0,0,512,512", size="256,")
# sync: data = client.fetch_region(service, region="0,0,512,512", size="256,")
```

## Parsing an info.json you already have

```python
service = iiisight.parse_info(info_json_dict)   # pure, no I/O
```