Telar: Docs Telar: Documentación

IIIF Integration

Telar uses the International Image Interoperability Framework (IIIF) to serve high-resolution images that can be zoomed, panned, and explored in detail.

What is IIIF?

IIIF (pronounced “triple-eye-eff”) is a set of open standards for delivering high-quality, attributed digital objects online. It allows you to:

Learn more about IIIF

Option 1: Local Images

Upload your images and Telar will automatically generate IIIF tiles.

Adding Local Images

For GitHub Web Interface:

  1. Navigate to components/images/ in your repository
  2. Click Add file → Upload files
  3. Drag images into upload area
  4. Name files to match object IDs (e.g., textile-001.jpg)
  5. Commit changes

For Local Development:

  1. Add high-resolution images to components/images/
  2. Generate IIIF tiles: 
    python3 scripts/generate_iiif.py --base-url http://localhost:4001

Sheet/CSV-Driven Processing As of v0.5.0, Telar only generates IIIF tiles for objects listed in the objects tab of your Google Sheet or objects.csv, as long as these don’t have an external IIIF manifest. This is automatic - just add your images and run the script.

File Requirements

iPhone Photos Work Directly As of v0.5.0, HEIC photos from iPhones are supported natively - no manual conversion needed. The IIIF generator automatically converts them to JPEG during tile generation while preserving your original files.

Naming Convention Use simple, descriptive IDs without spaces: textile-001.jpg, ceramic-bowl-blue.jpg

How It Works

When you add an image:

  1. The IIIF generator creates tiled versions at multiple zoom levels
  2. Tiles are saved to iiif/objects/[object-id]/
  3. A manifest file describes the image structure
  4. The UniversalViewer loads tiles progressively as needed

This allows smooth zooming even on very large images.

Option 2: External IIIF Resources

Reference IIIF images from museums, libraries, and other institutions worldwide.

Finding IIIF Resources

Many institutions provide IIIF manifests:

Adding External IIIF

In your objects CSV or Google Sheet:

  1. Create an object_id (e.g., museum-textile-001)
  2. Add the IIIF manifest URL in the source_url column: 
    https://example.org/iiif/image/abc123/info.json

Manifest URL Formats

IIIF URLs typically look like:

Telar supports both formats.

Mixing Local and External

You can use both local and external IIIF images in the same project:

object_id,title,...,source_url
local-textile-001,My Textile,,,
museum-textile-002,Museum Textile,...,https://example.org/iiif/manifest.json
local-ceramic-001,My Ceramic,,,

Leave source_url blank for local images.

Metadata Auto-Population

Telar v0.4.0+ can automatically extract object metadata from IIIF manifests, reducing manual data entry and improving accuracy.

How It Works

When you provide a source_url with an IIIF manifest, Telar automatically attempts to extract:

Supported IIIF Versions

Telar supports both IIIF Presentation API versions:

The extraction system automatically detects the version and uses the appropriate metadata structure.

How to Use

Simply add the IIIF manifest URL to your objects CSV or Google Sheet. Leave other fields blank:

object_id,title,description,source_url,creator,period,location,credit
map-001,,,https://example.org/iiif/manifest.json,,,,

When the site builds, Telar will:

  1. Fetch the IIIF manifest
  2. Extract available metadata fields
  3. Populate empty fields with extracted data
  4. Use your CSV data for any fields you filled in

Override Control

Your CSV data always wins. You can:

Example - partial override:

object_id,title,description,source_url,creator,period,location,credit
map-001,My Custom Title,,https://example.org/manifest.json,,,,

Telar will:

Language Detection

Metadata extraction respects your site’s language setting (telar_language in _config.yml):

If a manifest provides multilingual metadata, Telar selects the most appropriate language for your site.

Smart Credit Detection

For the credit field, Telar uses intelligent fallback logic:

  1. Looks for “Attribution” or “Rights” fields
  2. Filters out legal boilerplate (Creative Commons URLs, rights statements)
  3. Falls back to repository name if no specific attribution found

This ensures you get meaningful credit lines, not just legal text.

Validation

During the build, Telar validates IIIF manifests:

Check your build logs for extraction status and warnings.

Build-Time Processing

Metadata extraction happens during the python3 scripts/csv_to_json.py step:

GitHub Pages: Automatic during deployment Local development: Run manually when updating manifests:

python3 scripts/csv_to_json.py

Example Workflow

  1. Find a IIIF manifest URL from a museum or library
  2. Add to your objects CSV with just the object_id and source_url
  3. Build your site
  4. Check the object page - metadata should be populated
  5. Override any fields that need adjustment

Common Metadata Fields

Different institutions use different field names. Telar searches for common variations:

For title:

For description:

For creator:

For period:

For location:

For credit:

When to Override

You might want to override extracted metadata when:

Limitations

Coordinate System

IIIF coordinates in Telar use normalized values (0-1):

Finding Coordinates

Use the built-in coordinate identification tool:

  1. Navigate to any object page
  2. Click Identify coordinates button
  3. Pan and zoom to the desired view
  4. Copy the X, Y, and Zoom values
  5. Paste into your story CSV or Google Sheet

Pro Tip The coordinate tool has a “Copy entire row” button that copies a complete CSV row template with the coordinates already filled in.

Troubleshooting

Image Not Loading

For local images:

For external IIIF:

Low Quality Display

Slow Loading

Next Steps