Zum Inhalt

User Manual

Terminology

Project

A virtually isolated area for each IIIF mandate that the University Library provides for an institution.

Administration interface users defined by the institute will be assigned to one or many projects and are then entitled to see and edit all information regarding the project. The contents within a project (collection, sequences and images) are organised in a tree.

Collection

Collections are used to arrange the images in a project hierarchically (similar to a folder in a file explorer). A collection could contain one or more child collections. A collection can have child collections and / or sequences.

Root Collection

Every Project has exactly one root collection (A collection with no parent collection).

Sequence

A sequence is used to store a series of images.

Image

An image which can be accessed via the IIIF API.

Task

A task is created when an action must be performed by the system that cannot be executed immediately (synchronously). The tasks are executed in the background by the system as batch process. A task can contain further sub-tasks and, if necessary, generate new tasks.

Web interface for administration

Access to the administration web interface

To get access to the administration interface for your users, please contact openscience@unibe.ch.

Users need to create a SWITCH edu-ID account. Affiliates of the University of Bern also need to link their Campus Account to the SWITCH edu-ID account. You need to provide the University of Bern email address for users with an affiliation and the main edu-ID email address for external users.

The web interface for administration can be accessed under https://iiif.ub.unibe.ch.

Click on "Sign in" on the top right corner and use your SWITCH edu-ID account to sign in.

If you don't have permission to access the web interface you will receive a 403 Forbidden error - otherwise you will see the following menu:

Projects

This menu item provides you with an overview of the projects to which you are entitled:

Action "Show"

This button opens the Project View and displays the Project Tree on the right side.

Action "Edit"

Here you can change the name and slug of your project, as well as the maximum image compression quality and the maximum edge height and width for the import.

The Slug is relevant if you want to access the IIIF Image API with the source file name of the image (See Using the IIIF Image API).

The maximum image compression quality setting is per default 92%. This optimizes the loading time of the images in the viewer and therefore requires less storage space on the IIIF server. Users will not notice any visual difference between the images. You can change this setting higher or lower, ex. maximum 100% or maximum 85%.

The maximum edge height & width of pixels for the import setting is undefined per default. This means that number of pixels in height and width available before the import is imported. If desired, you can specify a maximum number of pixels for the width or height of your images to be imported before importing.

Please note that both are maximum settings. Images that have lower value before import than the maximum value set during import will keep their original value and will not be artificially scaled up.

Recommended settings for importing: For common formats, we generally recommend importing with a maximum edge length of 10’000 pixels and the default Image Compression Quality of max. 92%. In any case, you should carry out test uploads (with different settings if necessary) before the actual upload.

Action "Delete"

Warning

This action will delete the whole project including all collections, sequences and images of this project

After clicking on "Delete" you have to confirm the action:

Project Tree

As soon as you selected a project in the projects overview page (action "Show") and as long as you are navigating trough the projects collections and sequences you will see the project tree on the right side, which indicates where you are within the project and allows you to quickly jump trough the hierarchy of the project.

Project View

This will show you the project information (id, name, slug, links to the presentation API and the root collection) and also the actions "Edit" and "Delete" which are the same as on the projects overview page.

Presentation API

The buttons will open the URL which delivers the JSON information for the root collection of the project as defined in the IIIF Presentation API v2.1 or v3.

Root collection

This link will open the information page about the root collection (See Collection View)

Action "Edit"

Here you can change the name and slug of your project.

The Slug is relevant if you want to access the IIIF Image API with the source file name of the image (See Using the IIIF Image API).

Action "Delete"

Warning

This action will delete the whole project including all collections, sequences and images of this project

After clicking on "Delete" you have to confirm the action:

Collection View

This view shows you the collection information (project, parent collection, id, name, links to the presentation API, child collections and sequences) and also the actions "Edit", "Move", "Delete", "Export image details", "Add child collection" and "Add sequence".

When the current collection is the root collection, the actions "Move" and "Delete" are not available.

When there are no images found in the collection tree starting from this collection, the "Export image details" button is not available.

Example of root collection

Example of non root collection

Project

A link to the project information (See Project View).

Parent Collection

A link to the parent collection - only if the current collection is not the root collection (See Collection View)

Id

The UUID of the current collection

Name

The name of the current collection

Presentation API

The buttons will open the URL which delivers the JSON information for the current collection as defined in the IIIF Presentation API v2.1 or v3.

Child collections

Links to child collections of the current collection (See Collection View)

Sequences

Links to the sequences of the current collection (See Sequence View)

Action "Edit"

Here you can change the name of the collection.

Action "Move"

When clicking on this button, you will see a pop-up with a tree view of all the collections in the project (except the current one). To move the current collection, click on one of the displayed ones and it will be moved there as a child.

Action "Delete"

Warning

This action will delete the whole collection including all children,sequences and images of this collection

After clicking on "Delete" you have to confirm the action:

Action "Export image details"

Clicking on "Export image details" will generate a CSV with the image details for all images found inside sequences of this collection and in all sequences of successor collections (going down the whole collection tree from this collection on).

Action "Add child collection"

This action adds a new collection as child to the current collection.

Action "Add sequence"

This action adds a new sequence to the current collection.

Sequence View

This view shows you the sequence information (project, parent collection, id, name, number of images, links to the presentation API and containing images) and also the actions "Edit", "Move", "Delete" and "Export image details".

Project

A link to the project information (See Project View).

Collection

A link to the parent collection (See Collection View).

Id

The UUID of the current sequence

Name

The name of the current sequence

# Images

The number of images in the current sequence

Presentation API

The buttons will open the URL which delivers the JSON information for the current sequence (manifest) as defined in the IIIF Presentation API v2.1 or v3.

Images

Links to the images of the current collection (See Image View).

Action "Edit"

Here you can change the name of the sequence.

Action "Move"

When clicking on this button, you will see a pop-up with a tree view of all the collections in the project. To move the current sequence, click on one of the displayed collections and it will be moved there as a child.

Action "Delete"

Warning

This action will delete the whole sequence including all images of this sequence

After clicking on "Delete" you have to confirm the action:

Action "Export image details"

Clicking on "Export image details" will generate a CSV with the image details for all images inside the current sequence.

Image View

This view shows you the image information (project, parent collection, parent sequence, id, source file name, source file size, generated JPEG sizes, links to the image API) and the image itself.

Project

A link to the project information (See Project View).

Collection

A link to the parent collection of the sequence containing the current image (See Collection View).

Sequence

A link to the sequence containing the current image (See Sequence View)

Id

The UUID of the current image

Source file name

The name of the originally imported file

Source file size

The file size of the originally imported file

Generated JPEG sizes

The file size of the generated high quality JPEG files.

There are four pre-generated files: 100%, 75%, 50%, 25% (resolution)

Image API (info)

The buttons will open the URL which delivers the JSON information for the current image (info) as defined in the IIIF Image API v2.1 or v3.

Full image

The buttons will open the URL which delivers the full image in the highest available resolution as defined in the IIIF Image API v2.1 or v3.

Action "Delete"

Warning

This action will delete the current image and its four pre-generated files from the sequence and storage

After clicking on "Delete" you have to confirm the action:

Tasks

This menu item provides you with the possibility to create an import task and getting an overview over the open, completed and failed tasks for the projects you are entitled for.

Whenever the system needs to perform an action that cannot be executed immediately (synchronously), a task is created for this purpose. A task can contain further sub-tasks and, if necessary, generate new tasks.

The administration interface user can generate explicitly an import task and implicitly image deletion tasks (by deleting a sequence, collection or project which contains one or more images).

Create a new import task

This functionality is used to import image files which you delivered on the share or to upload metadata from a csv file on your local system.

Before you start importing, make sure that the **project settings** are correctly adjusted for your project. How to customize your project settings and corresponding recommendations can be found at [project[(#projects).

First, select the type of data you want to import (Images or Metadata), the project to which you want to import the data and finally click on "Next".

Images import task

Note

See Image files delivery for more information on how to prepare and deliver your image files.

If you selected "images" in previous step, in this step you need to select the path of your folder on the file delivery share. Depending on how you prepared your image files you need to specify a sequence.

If you want to override existing images, check the "Override Images" box - otherwise the system will not import existing images but create a warning for each such image in the corresponding task.

Click "Start" to add a new import task for your import to the Task overview.

Metadata import task

Note

See CSV Import for more information on how to prepare and deliver your metadata.

If you selected "metadata" in the previous step, now you need to select the file on your system containing the metadata you want to import. Click on "Choose File" to continue.

After clicking on "Choose File" your system will open a file explorer. Navigate to the desired file and select it.

After selecting the desired file in the file explorer, the file name should appear on the form bar. Now click on "Start" to complete the metadata import task creation.

Task overview

Here you get an overview of all tasks in the projects for which you are entitled.

By clicking on the corresponding columns, you can change the sorting. By clicking on the filter icon, you get the possibility to filter the tasks according to certain criteria.

By clicking on the linked TaskID you will get to the corresponding Task view.

Task view

This view shows you the tasks information (Id, State, IsRunning, Started, Modified, Path, Logs and Subtasks).

The Task view for an incompleted import task will also provide you with a button to cancel the task.

Id

The Id of the Task in the database.

State

The current state of the task.

Possible states are

  • New (Task was created but not started yet)
  • Started (Task was started)
  • Subtasks (Task is waiting for sub-tasks completion)
  • Successful (Task was finished successful)
  • Interrupted (Task was canceled by user)
  • Failed (Task execution failed)

IsRunning

Indicates if the task is currently running or not.

Started

Date and time when the task was first started.

Modified

Date an time when the task information was last modified.

When the task is in state "Successful", "Interrupted" or "Failed" - this is the date and time when the task finally stopped running.

Path

The path associated with the Task (e.g. the import folder for the import task; the path to the source image file for an image validation or image creation task).

Logs

Here you will find task specific log entries. A log entry can have the following types:

  • (info) Info: Just gives you neutral information of some kind (e.g. task started)

  • (tick) Success: Something in the task was successful (e.g. file validation, image generation)

  • (warning) Warning: Something in the task needs your attention, task itself (and parent task) can still be successful

  • (error) Error: Something in the task went wrong, task itself (and parent task) will be failed

Subtasks

This list behaves exactly as the list described under task overview but contains only sub-tasks of the current task.

Storage

This view shows you the storage usage information per project you are entitled for (Current usage and avg usage per year).

Image files delivery

Access to the delivery folder

To get access to the delivery folder for your users, please contact itsupport.ub@unibe.ch.

Users need to have an existing Campus Account at the University of Bern. Users need to use their Campus Account credentials to connect to the delivery folder on the Campus Storage share.

Operating System Path to the delivery folder
Windows \\nas-ub.unibe.ch\ub-iiif\delivery
Linux, Mac smb://nas-ub.unibe.ch/ub-iiif/delivery

Prepare a delivery for an import

Warning

Important note about naming of your image files

You can name your image files as you like but the name of an image file needs to be unique within a project. As example you can not have two files named image001.tif within a project.

Import of multiple images to a specific sequence

  • Create the sequence if it does not already exist. (See Collection View).
  • Prepare a folder on your storage which contains all images you want to import to a specific sequence. This folder must not have any subfolders.
  • Use Bagger to create a BagIt compatible folder on your storage.
  • Choose a meaningful name for the BagIt folder, we recommend to use the project slug (See Project view) as prefix (e.g. my-project_first_import_test).
  • Move the folder created with Bagger to the delivery folder
  • Create a new import task for your project, select the transferred folder and don't forget to select the sequence in which you want to import the images (See Create a new import task).

Import of multiple images to multiple sequences

  • Prepare a folder on your storage
  • Create a hierarchy of subfolders containing the names of the desired collections. Create subfolders with the names of the desired sequences and place the images to be imported there - these subfolders must not contain any further subfolders. There is no need to create a folder with the name of the root collection, the previously created folder can be considered as root.
    Example of such a hierarchy:

    ./prepared-folder
        ./Collection 1
            ./Sequence 1
                ./seq1_image001.tif
                ./seq1_image002.tif
                ./seq1_image003.tif
        ./Collection 1
            ./Sub-Collection 1
                ./Sequence 2
                    ./seq2_image001.tif
                    ./seq2_image002.tif
                ./Sequence 3
                    ./seq3_imageA.tif
                    ./seq3_imageB.tif
                    ./seq3_imageC.tif
                    ./seq3_imageD.tif
            ./Sub-Collection 3
                ./Sequence 4
                    ./seq4_image.tif
        ./Sequence 5           <= Note: this sequence will be in the root collection
            ./seq5_1.tif
            ./seq5_2.tif
            ./seq5_3.tif
    

  • Use Bagger to create a BagIt compatible folder on your storage.

  • Choose a meaningful name for the BagIt folder, we recommend to use the project slug (See Project view) as prefix (e.g. my-project_first_import_test).
  • Move the folder created with Bagger to the delivery folder
  • Create a new import task for your project, and select the transferred folder (See Create a new import task).

Info

During the import the system will lookup collections and sequences by folder name. If a collection or sequence is not found the system will create a new one with the folder name.

What is BagIt?

BagIt is a set of hierarchical file system conventions designed to support disk-based storage and network transfer of arbitrary digital content. A \"bag\" consists of a \"payload\" (the arbitrary content) and \"tags\", which are metadata files intended to document the storage and transfer of the bag. A required tag file contains a manifest listing every file in the payload together with its corresponding checksum. The name, BagIt, is inspired by the \"enclose and deposit\" method, sometimes referred to as \"bag it and tag it\".

Source: https://en.wikipedia.org/wiki/BagIt

Use Bagger to create a BagIt compatible folder

See https://github.com/LibraryOfCongress/bagger for downloading and starting the Library of congress Bagger application.

  • Open the Bagger application
  • Click on the "Create Bag in Place" Icon
  • Click on the "..." Icon behind "Select Date"
  • Open the prepared folder (See Prepare a delivery for an import), ensure you are inside the folder. And click on "Open"
  • Click on "OK"
  • The bag is created and you will receive a success message, click on the "OK" button
  • The Bagger window is now updated
  • If you open the prepared folder in the file explorer you will now see, that there is a "data" folder where your prepared files/folder where moved and you will see the text files created by Bagger.
  • Close the Bagger software and move the prepared folder to the file delivery folder (See Access to the delivery folder)
  • After transfer of the prepared folder you can start the import (See Create a new import task)

Known Bagger problems

Negative time

It seems that Bagger won't accept negative file created or modified time stamps.

Depending on your operating system, Bagger won't accept date time stamps which are too old.

E.g. on Linux the time stamps are saved in an integer which represents the seconds gone from 01.01.1970 00:00:00 (UTC). Time stamps before this date/time are represented with a negative integer.

This can happen, when the creation date of the scanned item itself is saved in the creation or modified time stamp of the created file.

In this case you need to update the time stamps of your files.

Special characters in the path to the prepared folder

It seems that Bagger won't be able to open a prepared folder when there are some special characters in the path (e.g. if the path is in a OneDrive folder). In this case move your prepared to your local disk and ensure that there are no special characters in the path. We also recommend that you only use A-Z, a-z, 0-9, - and _ in the name of your prepared folder.

Metadata

CSV Import

A Metadata import task can only be started from an existing .csv file on your system. Each "csv" row will result in a presentation property. Each row must have exactly 6 fields in the following exact order: target entity, property name, label id, language, label name and the value.

Warning

An entry will be overridden if a new imported entry has the same target, property name, label id and language!

Target Entity Field

The target entity field must not be empty. The possible values are "Root" which targets the root project's collection, the name or the id (uuid) of a IIIFResource entity. IIIFResource entities are the following: Project, Collections, Sequences and Images. The name of a IIIFResource entity can be retrieved directly from the "show" interface.

Warning

Projects are IIIFResource entites, however metadata import is yet not available.

Property Name Field

The name of the presentation property to be added. Every property must have a non-blank name field. To ensure consistency the allowed property name field values are predetermined, namely: navdate, profile, requiredStatement, rights, thumbnail, behavior, viewingHint, logo, description, attribution, license, label, metadata and viewingDirection.

Label Id Field

The label identifier of the property to be added. Properties may need a label id. Label Ids are used to group properties which need translations for label names. For example: The metadata property, which always need all field to not be blank should be specified, for the root collection would need be redacted in the .csv file for german and english translations in the following fashion:

Root, metadata, writer_label_id, de, Schriftsteller, Goethe Root, metadata, writer_label_id, en, Writer, Goethe

This allows the redactor to add multiple translations for the value and label name fields by matching the property's label id. All properties which require a label id field also require the language the label name fields to not be blank. The properties (Property Name) which require the label id field to not be blank are: metadata.

Language Field

The language abbreviation of the value or/and the label name field. Properties may need a language field. Properties which do not need/allow for the language field to be added exist only once (are thus unique) for the whole IIIFRessource and no additional translation can be added.

The properties (Property Name) which require a language value are: requiredStatement, rights, thumbnail, behavior, viewingHint, logo, description, attribution, license, label and metadata. The properties (Property Name) which do not allow for a language are: navdate, profile and viewingDirection.

Label Name Field

The translated label name of the property to be added. Every property (Propert Name) which requires a label id field also requires the label name field to not be blank. See Label Id Field to find an example of how to redact label name translations.

The properties (Property Name) which require the label name field to not be blank are: metadata.

Value Field

The value of the presentation property to be added. This entry must not be blank for every presentation property added. The value field can represent a translation, if the language field is required, otherwise it represents a unique value.

Visualize Metadata

At the bottom of each IIIFResource View page, you can find all the properties belonging to the IIIFResource entity.

Property entries with no translations ad no label translations are displayed in a single line:

Property entries with multiple translations are displayed with an "eye" icon:

To see all entries (redacted translations), click on the "eye" icon and all translations will be displayed:

For nested presentation properties, which also required a translated label, you can click first on the "eye" icon to display all labels:

Subsequently click on the "eye" icon at the right of the desired label in order to visualize its translations:

Manual Import

Add To Existing Property

You can add translations or label at every nesting level of your presentation properties:

For example, in the figure above you can add a new label by clicking on the "+" icon on the right of the "metadata" line. Moreover, you can also add new translations to the "creator" label, by clicking on the "+" icon to the right of the "metadata" "creator".

New Property

Presentation properties can also be added one-by-one using the admin interface. At the bottom of the overview of each IIIFResource there is an "Add Property" button.

After you click on "Add Property" a drop-down menu, containing all allowed properties, appear to select the property you desire to add. Select the desired property you'd like to add and press "OK".

Now you will be redirected to a form which allows you to fill all required fields. See CSV Import to check the constraints for each presentation property.

Fill All fields and press "Save" to persist your new property.

Automatically Generated Properties

Each IIIFResource, expect for projects, the label property is automatically generated at import with a default value and a default language. You can always add new translations to the label property or modify the default value, however there always have to be at least one label entry, thus you cannot delete the label property if only one translation is stored.

Using the IIIF Image API

Image Request

Info

See the IIIF Image API reference v2.1 or v3.0 for further details on the URI syntax (region, size, rotation, quality and format).

The IIIF Image API URI for requesting an image defines the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

For the University Library IIIF Server, the {scheme}://{server} part is https://iiif.ub.unibe.ch followed by /image/{version} as {prefix} where version is either v2.1 or v3.0. For the following examples we will use v3.0 as {version} (https://iiif.ub.unibe.ch/image/v3.0/...)

There are two ways on the University Library IIIF Server to call a specific image:

Info

When using the variant with the project slug and image source file name, a HTTP redirect to the first variant (image identifier) will be created. This means for every such request to the image API the browser has to do a second request. This causes a minimal delay (microseconds) on each request and increases the load on the web server. We recommend to use the first variant whenever possible.

Image Information Request

Info

See the IIIF Image API reference v2.1 or v3.0 for further details on the URI syntax.

The IIIF Image API URI for requesting an image defines the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/info.json

For the University Library IIIF Server, the {scheme}://{server} part is https://iiif.ub.unibe.ch followed by /image/{version} as {prefix} where version is either v2.1 or v3.0. For the following examples we will use v3.0 as {version} (https://iiif.ub.unibe.ch/image/v3.0/...)

There are two ways on the University Library IIIF Server to call a specific image information:

Warning

When using the variant with the project slug and image source file name, a HTTP redirect to the first variant (image identifier) will be created. This means for every such request to the image API the browser has to do a second request. This causes a minimal delay (microseconds) on each request and increases the load on the web server. We recommend to use the first variant whenever possible.

Using the IIIF Presentation API

Info

The University Library IIIF Server provides a rudimentary presentation API. At the moment we are extending the functionality of our presentation API to allow metadata enrichment.

The JSON-LD representation of a collection can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/collection/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0).

The {id} is the ID of the collection which can be found in the Collection View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/collection/691e6e0c-afc2-4f17-aee5-d9f88be15865/

The JSON-LD representation of a sequence (also called "Manifest") can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/manifest/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0). The {id} is the ID of the sequence which can be found in the Sequence View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/manifest/78285e64-0b86-4010-99f2-6c14b100432d/

The JSON-LD representation of a canvas can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/canvas/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0).

The {id} is the ID of the image displayed on the canvas which can be found in the Image View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/canvas/e61b22ed-3d94-4322-9633-e4b9a3df1def/

Info

According to the IIIF Presentation API specifications, it is theoretically possible to place multiple images of different sizes on a canvas.

However, the University Library IIIF server always delivers a canvas in the 100% size of the image on which the respective image is placed in the same size.

Zurück zum Seitenanfang