Creating a Mirador IIIF Viewer and Putting It Online

A Comprehensive Guide to Setup, Configuration, and Deployment

Key Highlights

IIIF Resources & Manifests: Ensure your images are IIIF-compliant by preparing high-quality manifests and hosting your image content on IIIF servers.
Mirador Installation & Customization: Whether using a hosted version via iframes or a self-hosted installation, configure the viewer to meet precise requirements including layout, annotations, and themes.
Deployment & Testing: Deploy your viewer after thorough configuration, ensuring cross-browser compatibility and seamless embedding in your websites or digital projects.

Overview

Mirador is a powerful, open-source, web-based image viewer well-suited for exploring high-resolution images and complex digital collections. Utilizing the International Image Interoperability Framework (IIIF), Mirador allows zoombility, comparison, annotation, and interactive exploration of images and documents. This guide focuses on creating a Mirador IIIF viewer from scratch and deploying it online, whether you opt for a hosted version embedded via an iframe or a complete self-hosted installation.

Understanding IIIF and Mirador

IIIF (International Image Interoperability Framework) provides a standardized method for delivering images and associated metadata. By creating well-structured IIIF Presentation API manifests, you can easily serve image data to platforms like Mirador. Mirador uses these manifests to display images in an interactive environment where users can zoom, pan, annotate, and compare images side by side.

The initial step is to ensure that your source images are hosted on an image server that complies with IIIF standards, such as Cantaloupe or IIPImage. Additionally, you must generate accurate IIIF manifests, which essentially describe every detail about your images including dimensions, available resolutions, and associated metadata. Tools like the IIIF Manifest Editor or various online utilities can help create these JSON-based manifests.

Preparatory Steps for Creating a Mirador Viewer

1. Prepare Your IIIF Resources

The foundation of an effective Mirador viewer lies in well-prepared IIIF resources. To achieve this:

IIIF Image Server

Choose a robust IIIF-compatible image server (for example, Cantaloupe or IIPImage) to store and serve your high-resolution images. This server translates your digital images into a format retrievable via the IIIF API.

Generate IIIF Manifests

A IIIF Manifest is a JSON file that contains metadata, image URLs, and detailed specifications such as sizes and format. Use the following checklist:

Include metadata such as title, creator, and subject information.
Ensure proper definition of image URLs, dimensions, and available sizes.
Validate the manifest using available IIIF tools to avoid errors during rendering.

2. Setting Up Your Technical Environment

Before integrating Mirador into your project, you need a solid technical foundation:

Prepare a local or remote web server capable of serving HTML, JavaScript, and CSS files.
If needed, install additional modules or packages via npm for full customizability. Mirador’s GitHub repository offers detailed README instructions for installation.
Plan your folder structure to cleanly separate resources, configuration files, and assets.

3. Choose Your Mirador Installation Approach

There are two principal methods available:

Hosted Version via iFrame

A quick integration option is to use a hosted version of Mirador. You simply embed an iframe into your web page, pointing it to a specified manifest URL. Adjust the iframe dimensions to match your design needs.

Example iframe code:

<!-- Embed these lines in your HTML -->
<iframe width="100%" height="600" src="https://projectmirador.org/embed/?iiif-content=https://your-manifest-url.com/manifest.json"></iframe>

Self-Hosted Mirador Installation

For those seeking greater control and customization:

Clone the Mirador GitHub repository or use npm to install the latest version.
Integrate the Mirador JavaScript and CSS assets into your project folders.
Edit the configuration file (typically config.js or mirador.js), where you can set display options, themes, and default behaviors. Options include setting the default view mode (e.g., scroll, single-page, gallery) and enabling advanced features like annotations and multi-window modes.

Configuration and Customization

Mirador offers a range of customization options. The configuration files dictate how the viewer behaves and respond to user interactions. Below are some key configuration areas:

Customizing the Layout

Mirador allows you to define multiple viewing windows and adjust their arrangements dynamically. For instance, you can preload multiple IIIF manifests to allow side-by-side comparisons. Within your configuration file, you can specify the default view mode, such as:

<!-- Example Mirador configuration excerpt -->
var miradorInstance = Mirador.viewer({
  id: "mirador",
  selectedTheme: 'dark',  // Options include 'dark' or 'light'
  window: {
    defaultView: "scroll",  // Choices: 'single', 'book', 'gallery'
    sideBarOpen: true,
    sideBarPanel: "canvas",
    views: [
      { key: "single", behaviors: ["individuals", "paged"] },
      { key: "book", behaviors: ["individuals"] },
      { key: "scroll", behaviors: ["continuous"] },
      { key: "gallery" }
    ],
    windows: [
      // Populate with manifest details
    ]
  }
});

Within this setup, you can include multiple manifests by linking their URLs, thereby allowing users to switch between or view multiple images concurrently.

Themes and Appearance

Custom styling can be applied through CSS and custom theme files. Adjusting colours, toggles, and view transitions may be necessary to align the viewer with your overall website design. Mirador supports themes that can quickly switch between dark and light modes, thus aiding accessibility and user experience.

Annotation and Interaction Features

One of Mirador’s key strengths is its support for annotations. Through specific plugins and configuration settings, you can enable users to annotate sections of an image, add comments, or share their findings. This can be particularly useful for scholarly research, digital archives, and educational projects.

Deployment, Testing, and Embedding

Deploying Your Mirador Viewer

After configuration, the next stage is to host your viewer online. Here are the typical deployment strategies:

Using GitHub Pages

GitHub Pages offers a free and straightforward way to host HTML projects. Upload your HTML, JavaScript, and CSS files to your GitHub repository, and enable the GitHub Pages feature. Once published, your viewer is available to the public via a dedicated URL.

Other Hosting Services

Alternatively, you can use traditional web hosts or cloud-based platforms like AWS, Heroku, or Netlify to deploy your site. The key is to ensure that all assets and configuration details are correctly served so that the viewer can retrieve IIIF resources properly.

Testing the Viewer

Comprehensive testing is fundamental to ensure seamless functionality across different browsers and devices:

Check that IIIF manifests load correctly without errors.
Validate interactive features such as zoom, pan, and annotation to ensure responsiveness.
Test embedded iframes or standalone pages to confirm that the configuration settings reflect correctly in the user interface.
Ensure compatibility with mobile devices if responsiveness is part of your design vision.

Embedding Mirador in Other Webpages

If you prefer embedding your viewer within an existing website, the iframe method is an efficient approach. Simply add an iframe element pointing to your Mirador installation’s URL, ensuring that the URL in the src attribute correctly references your IIIF manifest parameters.

Workflow Summary Table

Step	Action	Details
1	Prepare IIIF Resources	Create IIIF compliant image manifests using an IIIF server and validate JSON files.
2	Set Up Environment	Ensure you have a working web server, local development environment, and dependencies installed.
3	Select Installation Method	Opt for either embedding via an iframe (hosted version) or a full self-hosted installation with repository cloning.
4	Configure Mirador	Edit configuration files to specify themes, layout, annotations, and manifest URLs.
5	Deploy	Upload your project to GitHub Pages, AWS, or similar hosting, ensuring asset paths are correctly set.
6	Test & Embed	Conduct thorough testing across devices and browsers; use iframes for integration in other pages if needed.

Additional Considerations

Documentation and Community Support

The IIIF and Mirador communities are vibrant and active. Engaging with documentation and community forums can help you troubleshoot issues, gain insights into advanced configuration options, and share ideas with fellow developers and archivists.

Consider joining mailing lists, attending webinars, or participating in online Q&A sessions that focus on IIIF implementations and the evolving nuances of interactive digital collections.

Ensuring Accessibility and Usability

When deploying any digital viewer, accessibility should be a top priority. Double-check that your Mirador viewer supports keyboard navigation, alternative text for images, and responsive design. A widely accessible digital repository will increase audience engagement and accommodate users with varying needs.

Integration with Other Services

Mirador can be used in tandem with other digital services and scholarly tools. Its modularity allows integration with annotation platforms, digital asset management systems, and even literary analysis tools. This integration empowers curators and researchers by providing a comprehensive interface to explore image resources alongside associated textual and metadata records.

Maintenance and Updates

Digital projects are often long-term undertakings. Establishing a maintenance plan ensures that your Mirador viewer remains up-to-date with security patches, compatibility updates, and evolving IIIF standards. Regular updates to the IIIF manifests and testing your viewer post-update can prevent interruptions in service and guarantee a consistently high-quality user experience.

Practical Example: Step-by-Step Walkthrough

For a practical perspective, let’s walk through a simplified process:

Step 1: Generate Your Manifest

Use the IIIF Manifest Editor or similar online tools to generate your manifest. Verify that the manifest contains all necessary metadata. Store the generated manifest URL in a safe location.

Step 2: Choose Your Hosting Option

If you are short on time or prefer simplicity, use the hosted version via an iframe. Otherwise, download and set up Mirador by cloning it from GitHub. Modify the configuration file to incorporate your manifest URL.

Step 3: Configure Your Viewer

Edit the Mirador configuration settings as needed. Customize the viewer’s layout to include multiple windows if you want to compare images side by side. Enable additional functionalities such as annotations or different viewing modes.

Step 4: Deploy and Test

Deploy your project on a web hosting service and test its functionality. Confirm that all interactive elements like zoom, panning, and navigation work on various devices and browsers. Adjust configurations if testing reveals any issues.

Step 5: Embed or Share

Once satisfied, embed the viewer into your existing website using an iframe, or share the URL of your hosted Mirador setup with your audience. This not only enhances digital engagement but also expands the reach of your visual collections.