# `Image.Plug.Provider.IIIF`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/provider/iiif.ex#L1)

[IIIF Image API 3.0](https://iiif.io/api/image/3.0/) URL provider.

Recognises and parses the IIIF Image API URL form into the canonical
`Image.Plug.Pipeline` IR. Targets [Compliance Level 2](https://iiif.io/api/image/3.0/compliance/),
the level most production servers implement.

### URL form

    <mount>/<endpoint>/<identifier>/<region>/<size>/<rotation>/<quality>.<format>

Where:

* `<mount>` is whatever path prefix the plug is `forward`-mounted at
  in the host's router. Stripped before recognition.

* `<endpoint>` is an optional per-server prefix segment (e.g. `iiif/3`
  for a vanilla deployment, `image` for Wellcome Collection's server).
  Configured via the provider's `:endpoint` option.

* `<identifier>` is the source asset's identifier — typically a
  filename or content-addressed key. Percent-encoded; `%2F` separates
  sub-paths within the identifier.

* `<region>` is `full` | `square` | `<x,y,w,h>` | `pct:<x,y,w,h>`.

* `<size>` is `max` | `^max` | `<w>,` | `,<h>` | `<w>,<h>` |
  `!<w>,<h>` | `pct:<n>` and any of those forms with the `^` upscale
  prefix.

* `<rotation>` is any number `0..360`, optionally prefixed with `!`
  for mirror-then-rotate. Decimal angles are accepted.

* `<quality>` is `default` | `color` | `gray` | `bitonal`.

* `<format>` is `jpg` | `png` | `gif` | `webp` | `tif` | `jp2` | `pdf`.

Two endpoints are also defined by the spec:

* `<mount>/<endpoint>/<identifier>/info.json` — the discovery
  document. Handled by `Image.Plug.Provider.IIIF.InfoJson` (Phase 4).

* `<mount>/<endpoint>/<identifier>` — bare identifier; the spec
  requires a `303 See Other` redirect to the info.json. Currently
  returns `:malformed_url`; the redirect is on the roadmap.

### Options

* `:mount` — string path prefix this plug is mounted under.
  Defaults to `""`. Stripped from `path_info` before parsing.

* `:endpoint` — additional path segment between mount and
  identifier. Defaults to `"iiif/3"` (matching the IIIF reference
  server convention). Set to `""` for servers that publish at the
  mount root.

* `:strict?` — if `true` (default), unknown URL segments produce
  an `:malformed_url` error. If `false`, the parser is more
  permissive — useful while migrating older Image API 2.x URLs.

### Compliance

Level 2 of the IIIF Image API 3.0 spec. The full compliance matrix
ships in `guides/iiif_conformance.md`. Notable deliberate gaps:

* The `square` region form parses to a centred square crop using
  `Image.Plug.Pipeline.Ops.Crop` with computed pixel coordinates.
  Servers serve images from their own `info.json`; since this
  provider ships its own info doc (Phase 4), the computation is
  self-consistent.

* The mirror-then-rotate form (`!N`) parses into a `Rotate` op but
  the leading mirror is silently dropped. A `Flip` op for that
  case is on the roadmap.

---

*Consult [api-reference.md](api-reference.md) for complete listing*