Quickstart

This walks through the smallest useful setup: a model with an IIIF image field, one profile, and the URLs you get back.

1. Use IIIFField on your model

IIIFField is a drop-in subclass of Django’s ImageField — swap it in on a new field, or convert an existing ImageField:

models.py
from django.db import models
from djiiif import IIIFField

class Photo(models.Model):
    title = models.CharField(max_length=200)
    image = IIIFField(upload_to="uploads/")

Because it is an ImageField, uploads, storage, width/height, and migrations all behave exactly as you already expect.

2. Define profiles

A profile is a named recipe for a IIIF Image API URL. Configure one or more in settings.py:

settings.py
IIIF_HOST = "https://images.example.org/"

IIIF_PROFILES = {
    "thumbnail": {"host": IIIF_HOST, "region": "full", "size": "150,",
                  "rotation": "0", "quality": "default", "format": "jpg"},
    "preview":   {"host": IIIF_HOST, "region": "full", "size": "600,",
                  "rotation": "0", "quality": "default", "format": "jpg"},
}

Each key becomes an attribute on .iiif. See Profiles for the typed Profile shape and per-image callables.

3. Read the URLs

Every profile is available as an attribute of the field’s .iiif accessor:

>>> photo.image.name
'uploads/sunset.jpg'

>>> photo.image.iiif.thumbnail
'https://images.example.org/uploads%2Fsunset.jpg/full/150,/0/default.jpg'

>>> photo.image.iiif.preview
'https://images.example.org/uploads%2Fsunset.jpg/full/600,/0/default.jpg'

The identifier segment (uploads%2Fsunset.jpg) is fully percent-encoded so the field name occupies a single IIIF path segment — slashes become %2F, and other reserved characters are encoded too.

In a template:

<img src="{{ photo.image.iiif.thumbnail }}">

Or with the template tag:

{% load iiiftags %}
<img src="{% iiif photo.image 'thumbnail' %}">

4. Safe on empty fields

Accessing .iiif on an empty/unset field never raises — every profile attribute returns the empty string "", so templates stay clean:

>>> blank.image.iiif.thumbnail
''

Next steps