# image_plug v0.1.0 - Table of Contents

> A pluggable Plug-based image server. Maps URLs to a canonical image processing pipeline executed via the Image library, with named, stored variants. Ships a Cloudflare Images URL provider.

## Pages

- Guides
  - [User guide](usage.md)
  - [Image sources](sources.md)
  - [Face-aware crops, zoom, and pixelation](face_aware.md)
  - [image_plug as a CDN-side service](cdn_origin.md)
  - [Cloudflare Images conformance](cloudflare_conformance.md)
  - [imgix conformance](imgix_conformance.md)
  - [Cloudinary conformance](cloudinary_conformance.md)
  - [ImageKit conformance](image_kit_conformance.md)
  - [IIIF Image API 3.0 conformance](iiif_conformance.md)

- About
  - [Image.Plug](readme.md)
  - [Changelog](changelog.md)

## Modules

- Public API
  - [Image.Plug](Image.Plug.md): The library's request entry point.
  - [Image.Plug.Admin](Image.Plug.Admin.md): HTTP admin surface for variant CRUD.
  - [Image.Plug.Capabilities](Image.Plug.Capabilities.md): Probes the local libvips build for optional encoder capabilities.
  - [Image.Plug.Error](Image.Plug.Error.md): Tagged error type returned by every public function in `Image.Plug`.
  - [Image.Plug.Pipeline](Image.Plug.Pipeline.md): The canonical, provider-neutral image-processing pipeline.
  - [Image.Plug.Provider](Image.Plug.Provider.md): Behaviour for URL-API providers.
  - [Image.Plug.Source](Image.Plug.Source.md): Reference to a source image. Produced by a provider, consumed by a
source resolver.
  - [Image.Plug.SourceResolver](Image.Plug.SourceResolver.md): Behaviour for source resolvers.
  - [Image.Plug.Variant](Image.Plug.Variant.md): A named, stored pipeline that requests can resolve by name.
  - [Image.Plug.VariantStore](Image.Plug.VariantStore.md): Behaviour for variant stores.

- Pipeline operations
  - [Image.Plug.Pipeline.Ops.Adjust](Image.Plug.Pipeline.Ops.Adjust.md): Tonal/colour adjustment operation. A consolidated bag of multiplier
fields so that adjacent adjustments fold into one op during
normalisation.
  - [Image.Plug.Pipeline.Ops.Background](Image.Plug.Pipeline.Ops.Background.md): Background fill operation. Flattens any transparency in the working
image against the given solid colour.
  - [Image.Plug.Pipeline.Ops.Blur](Image.Plug.Pipeline.Ops.Blur.md): Gaussian blur operation. Holds a libvips `sigma` value derived from
the provider's native blur parameter (Cloudflare uses 0..250).

  - [Image.Plug.Pipeline.Ops.Border](Image.Plug.Pipeline.Ops.Border.md): Border operation. Adds a coloured border of the given per-side widths
around the working image by embedding it in a larger canvas of the
border colour.

  - [Image.Plug.Pipeline.Ops.Colorspace](Image.Plug.Pipeline.Ops.Colorspace.md): Convert the image to a different colorspace.
  - [Image.Plug.Pipeline.Ops.Crop](Image.Plug.Pipeline.Ops.Crop.md): Crop operation. Extracts a sub-rectangle of the working image.
  - [Image.Plug.Pipeline.Ops.Draw](Image.Plug.Pipeline.Ops.Draw.md): Overlay/watermark operation. Wraps an ordered list of
`Image.Plug.Pipeline.Ops.Draw.Layer` structs.
  - [Image.Plug.Pipeline.Ops.Draw.Layer](Image.Plug.Pipeline.Ops.Draw.Layer.md): A single overlay layer used by `Image.Plug.Pipeline.Ops.Draw`.
  - [Image.Plug.Pipeline.Ops.DropShadow](Image.Plug.Pipeline.Ops.DropShadow.md): Drop-shadow operation. The shadow is the source's alpha
silhouette, blurred, tinted, scaled by `:opacity`, and
composited beneath the original at `(:dx, :dy)`. Maps to
ImageKit's `e-shadow=...` parameter family.
  - [Image.Plug.Pipeline.Ops.Enhance](Image.Plug.Pipeline.Ops.Enhance.md): Content-aware automatic enhancement. Maps to imgix's
`auto=enhance`, Cloudinary's `e_improve` family
(`e_improve`, `e_auto_brightness`, `e_auto_color`,
`e_auto_contrast`), and ImageKit's `e-retouch`.
  - [Image.Plug.Pipeline.Ops.Fade](Image.Plug.Pipeline.Ops.Fade.md): Alpha-gradient fade-out on one or more edges. `:edges` is
`:all` or a list drawn from `:top`, `:bottom`, `:left`,
`:right`. `:length` is either an integer pixel count or a
float fraction of the relevant dimension. Maps to
Cloudinary's `e_fade[:N]` (`N` interpreted as a percentage).

  - [Image.Plug.Pipeline.Ops.Flip](Image.Plug.Pipeline.Ops.Flip.md): Flip operation. Mirrors the working image along one or both axes.

  - [Image.Plug.Pipeline.Ops.Format](Image.Plug.Pipeline.Ops.Format.md): Output format / encoder configuration. Lives on the pipeline rather
than in the op list — there is exactly one per pipeline.
  - [Image.Plug.Pipeline.Ops.IccTransform](Image.Plug.Pipeline.Ops.IccTransform.md): ICC-profile-driven colourspace conversion. Distinct from
`Ops.Colorspace` (which uses libvips' named-interpretation
modes); this op invokes `Image.to_colorspace/3` and runs an
actual profile-based transform.
  - [Image.Plug.Pipeline.Ops.Opacity](Image.Plug.Pipeline.Ops.Opacity.md): Mid-pipeline alpha multiplier. `:factor` is in `[0.0, 1.0]`;
`1.0` is a no-op (the normaliser drops the op), `0.0` produces
a fully transparent image. Maps to Cloudinary's `o_<n>`
(where `n / 100` is passed) and ImageKit's `e-opacity:<n>`.

  - [Image.Plug.Pipeline.Ops.Orientation](Image.Plug.Pipeline.Ops.Orientation.md): EXIF orientation override. `:value` is an integer in `1..8`
per the EXIF orientation enumeration; the interpreter calls
`Image.set_orientation/2` to write the metadata field
without rotating the underlying pixels. Maps to imgix's
`or=N`.

  - [Image.Plug.Pipeline.Ops.Pixelate](Image.Plug.Pipeline.Ops.Pixelate.md): Block-style pixelation. `:scale` is the resize factor passed
to `Image.pixelate/2` — smaller values produce coarser blocks
(e.g. `0.05` = ~20-pixel blocks on a 400-pixel image). Maps
to Cloudinary's `e_pixelate[:N]` where `N` is a block size in
pixels (the provider parser converts `N → scale = 1 / N`).

  - [Image.Plug.Pipeline.Ops.PixelateFaces](Image.Plug.Pipeline.Ops.PixelateFaces.md): Pixelates only the regions of an image occupied by detected
faces, leaving the rest of the image untouched. Maps to
Cloudinary's `e_pixelate_faces[:N]`.
  - [Image.Plug.Pipeline.Ops.Posterize](Image.Plug.Pipeline.Ops.Posterize.md): Tonal-quantisation operation. `:levels` in `2..256` is the
number of distinct values per band. Maps to Cloudinary's
`e_cartoonify[:level_count]` (`level_count` defaults to `5`).

  - [Image.Plug.Pipeline.Ops.ReplaceColor](Image.Plug.Pipeline.Ops.ReplaceColor.md): Replace one colour in the image with another, with a tolerance.
  - [Image.Plug.Pipeline.Ops.Resize](Image.Plug.Pipeline.Ops.Resize.md): Resize operation. Combines target dimensions, fit mode, gravity (focal
point for cropping), upscale policy, and DPR (device pixel ratio).
  - [Image.Plug.Pipeline.Ops.Rotate](Image.Plug.Pipeline.Ops.Rotate.md): Rotation operation. Rotates the working image by `angle` degrees
clockwise.
  - [Image.Plug.Pipeline.Ops.Rounded](Image.Plug.Pipeline.Ops.Rounded.md): Rounded-corners mask operation. `:radius` is the corner
radius in pixels. The atom `:max` produces a fully circular /
pill-shaped result (radius = half the shorter dimension).
Maps to Cloudinary's `r_<n>` and `r_max`.

  - [Image.Plug.Pipeline.Ops.Segment](Image.Plug.Pipeline.Ops.Segment.md): Subject-segmentation placeholder operation. Cloudflare's `segment=foreground`
isolates the subject and replaces the background with transparency.
  - [Image.Plug.Pipeline.Ops.Sepia](Image.Plug.Pipeline.Ops.Sepia.md): Sepia tone operation. `:strength` is a `[0.0, 1.0]` blend
factor between the identity (`0.0`) and the full sepia matrix
(`1.0`). Maps to imgix's `sepia=N` (`N / 100`) and Cloudinary's
`e_sepia[:N]` (`N / 100`, default full sepia).

  - [Image.Plug.Pipeline.Ops.Sharpen](Image.Plug.Pipeline.Ops.Sharpen.md): Edge-enhancement operation. Holds a libvips `sigma` value derived
from the provider's native sharpen parameter (Cloudflare uses 0..10).

  - [Image.Plug.Pipeline.Ops.Tint](Image.Plug.Pipeline.Ops.Tint.md): Single-colour tinted-monochrome operation.
  - [Image.Plug.Pipeline.Ops.Trim](Image.Plug.Pipeline.Ops.Trim.md): Trim operation. Removes border pixels from the working image.
  - [Image.Plug.Pipeline.Ops.Vignette](Image.Plug.Pipeline.Ops.Vignette.md): Radial vignette darkening operation. `:strength` is in
`[0.0, 1.0]` and matches `Image.vignette/2`'s argument of
the same name. Maps to Cloudinary's `e_vignette[:N]`
(`N / 100`, default `0.5`).

- Cloudflare provider
  - [Image.Plug.Provider.Cloudflare](Image.Plug.Provider.Cloudflare.md): Cloudflare Images URL provider.
  - [Image.Plug.Provider.Cloudflare.Options](Image.Plug.Provider.Cloudflare.Options.md): Parses the comma-separated `<options>` segment of a Cloudflare
Images URL into a canonical `Image.Plug.Pipeline`.
  - [Image.Plug.Provider.Cloudflare.URL](Image.Plug.Provider.Cloudflare.URL.md): URL-shape recognition for the Cloudflare Images URL grammar.

- Default source resolvers
  - [Image.Plug.SourceResolver.Composite](Image.Plug.SourceResolver.Composite.md): Source resolver that dispatches by `Image.Plug.Source.kind` to a
configured set of per-kind resolvers.
  - [Image.Plug.SourceResolver.File](Image.Plug.SourceResolver.File.md): Source resolver that reads images from a configured root directory.
  - [Image.Plug.SourceResolver.HTTP](Image.Plug.SourceResolver.HTTP.md): Source resolver that streams images from `http(s)://` URLs.

- Default variant stores
  - [Image.Plug.VariantStore.ETS](Image.Plug.VariantStore.ETS.md): In-memory ETS-backed implementation of `Image.Plug.VariantStore`.
  - [Image.Plug.VariantStore.Persistence](Image.Plug.VariantStore.Persistence.md): Behaviour for persisting variants across application restarts.
  - [Image.Plug.VariantStore.Persistence.File](Image.Plug.VariantStore.Persistence.File.md): JSON-on-disk variant persistence backend.

- Internals
  - [Image.Plug.Cache](Image.Plug.Cache.md): HTTP-cache helpers used by `Image.Plug`.
  - [Image.Plug.FaceAware](Image.Plug.FaceAware.md): Face-aware crop, zoom, and pixelation, gated on the optional
[`:image_vision`](https://hex.pm/packages/image_vision)
dependency.
  - [Image.Plug.Options](Image.Plug.Options.md): Validated, frozen configuration for `Image.Plug`.
  - [Image.Plug.Pipeline.Encoder](Image.Plug.Pipeline.Encoder.md): Serialises a transformed `Vix.Vips.Image` into bytes for the HTTP
response.
  - [Image.Plug.Pipeline.Interpreter](Image.Plug.Pipeline.Interpreter.md): Executes a normalised pipeline against an open `Vix.Vips.Image`.
  - [Image.Plug.Pipeline.Normaliser](Image.Plug.Pipeline.Normaliser.md): Reorders, folds, and validates a pipeline so that two requests with
the same semantic effect produce identical fingerprints — and so
that order-sensitive libvips operations land in a position where
they actually work.
  - [Image.Plug.Provider.Cloudinary](Image.Plug.Provider.Cloudinary.md): Cloudinary URL provider.
  - [Image.Plug.Provider.Cloudinary.Options](Image.Plug.Provider.Cloudinary.Options.md): Parses a [Cloudinary transform string](https://cloudinary.com/documentation/transformation_reference)
into a canonical `Image.Plug.Pipeline`.
  - [Image.Plug.Provider.Cloudinary.Signing](Image.Plug.Provider.Cloudinary.Signing.md): Cloudinary-flavoured URL signing.
  - [Image.Plug.Provider.Cloudinary.URL](Image.Plug.Provider.Cloudinary.URL.md): URL-shape recognition for the [Cloudinary delivery URL grammar](https://cloudinary.com/documentation/transformation_reference).
  - [Image.Plug.Provider.IIIF](Image.Plug.Provider.IIIF.md): [IIIF Image API 3.0](https://iiif.io/api/image/3.0/) URL provider.
  - [Image.Plug.Provider.IIIF.InfoJson](Image.Plug.Provider.IIIF.InfoJson.md): Builds the IIIF Image API 3.0 [Image Information document](https://iiif.io/api/image/3.0/#5-image-information)
(`info.json`) for a given source.
  - [Image.Plug.Provider.IIIF.Options](Image.Plug.Provider.IIIF.Options.md): Parses the four IIIF Image API 3.0 option segments
(`region / size / rotation / quality.format`) into a canonical
`Image.Plug.Pipeline`.
  - [Image.Plug.Provider.IIIF.URL](Image.Plug.Provider.IIIF.URL.md): Recognises [IIIF Image API 3.0](https://iiif.io/api/image/3.0/)
URL forms in `Plug.Conn.path_info` and returns a structured result
the higher-level provider dispatches on.
  - [Image.Plug.Provider.ImageKit](Image.Plug.Provider.ImageKit.md): ImageKit URL provider.
  - [Image.Plug.Provider.ImageKit.Options](Image.Plug.Provider.ImageKit.Options.md): Parses an [ImageKit transform string](https://imagekit.io/docs/transformations)
into a canonical `Image.Plug.Pipeline`.
  - [Image.Plug.Provider.ImageKit.Signing](Image.Plug.Provider.ImageKit.Signing.md): ImageKit-flavoured HMAC URL signing.
  - [Image.Plug.Provider.ImageKit.URL](Image.Plug.Provider.ImageKit.URL.md): URL-shape recognition for the [ImageKit URL grammar](https://imagekit.io/docs/transformations).
  - [Image.Plug.Provider.Imgix](Image.Plug.Provider.Imgix.md): Imgix URL provider.
  - [Image.Plug.Provider.Imgix.Options](Image.Plug.Provider.Imgix.Options.md): Parses an [imgix](https://docs.imgix.com/en/latest/apis/rendering)
query string into a canonical `Image.Plug.Pipeline`.
  - [Image.Plug.Provider.Imgix.Signing](Image.Plug.Provider.Imgix.Signing.md): Imgix-flavoured HMAC URL signing.
  - [Image.Plug.Provider.Imgix.URL](Image.Plug.Provider.Imgix.URL.md): URL-shape recognition for the [imgix URL grammar](https://docs.imgix.com/en/latest/setup/serving-images).
  - [Image.Plug.Signing](Image.Plug.Signing.md): HMAC signing and verification for `Image.Plug` request URLs.