Docs Documentación

Self-Hosted Images

If you have your own images — photographs, scans of documents, maps — you can upload them directly to your Telar site. Telar automatically converts them into zoomable, high-resolution tiles so viewers can explore every detail.

This process uses a technology called IIIF (International Image Interoperability Framework) behind the scenes, but you don’t need to understand IIIF to use self-hosted images. Just upload your files and Telar handles the rest.

Adding images

Each image needs to match an object defined in your spreadsheet. The filename (without its extension) must match the object’s object_id.

For example, if your spreadsheet has an object with object_id = textile-001, name your image file textile-001.jpg.

From the GitHub web interface:

  1. Navigate to components/images/ in your repository
  2. Click Add file > Upload files
  3. Drag your images into the upload area
  4. Make sure filenames match your object IDs
  5. Commit changes

For local development:

  1. Place your images in components/images/
  2. Generate the IIIF tiles: 
    python3 scripts/generate_iiif.py --base-url http://localhost:4001

Telar only generates tiles for objects listed in your spreadsheet that don’t already have an external IIIF source. This is automatic — just add your images and they’ll be processed during the next build.

Supported file formats

iPhone photos work directly. HEIC photos from iPhones are supported natively — no need to convert them first. Telar converts them to JPEG automatically during tile generation while keeping your originals.

Naming tip. Use simple, descriptive IDs without spaces or special characters: textile-001.jpg, ceramic-bowl-blue.jpg

How it works

When you add an image and build your site:

  1. Telar 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 viewer loads tiles progressively — only the visible area at the current zoom level, not the entire image

This allows smooth zooming even on very large images.

Coordinate system

Telar uses normalized coordinates (values from 0 to 1) to describe positions within an image:

You use these coordinates in your story steps to tell Telar where to zoom in on each image.

Finding coordinates

Each object page includes a built-in coordinate picker:

  1. Navigate to any object page on your site
  2. Click the Identify coordinates button
  3. Pan and zoom to the view you want
  4. Copy the X, Y, and Zoom values
  5. Paste them into your story spreadsheet or CSV

The coordinate tool has a Copy entire row button that copies a complete row template with the coordinates already filled in — ready to paste into your spreadsheet.

Troubleshooting

Image not loading

Low quality display

Slow loading

See also