Items and Collections

A site's contents are all represented by a single resource model, distinguished by type.

Type	Role
item	One material. The basic unit of a site, carrying images, metadata and a thumbnail
collection	A grouping of items, used to organise by theme or fonds
media	An image (facsimile) attached to an item; a child resource of the item
page	A static page within the site ("About this database", etc.)
annotation	A note on an image, stored and displayed as a IIIF annotation

Resources form hierarchies via parent_id (media → item, item → collection, …).

Metadata

Each resource can carry free-form metadata. Dublin Core dcterms:* keys (e.g. dcterms:creator) are recommended. Metadata feeds search and facets (filtering).

• metadata.thumbnail — thumbnail image for listings/cards
• metadata.geo — coordinates for the map view (an array of markers [{ lat, lon, label?, count? }]). Whatever the input format, coordinates are normalized to this shape internally (like Omeka S's Mapping module): TEI fills it from geocoded standOff place-names, IIIF from navPlace, and the IIIF manifest emits it back as navPlace. A single point may also use metadata.lat / metadata.lng as before. The map page has place-name search, a place list (click to fly there), a base-map switcher (Rekichizu / Standard / GSI / GSI aerial / OpenFreeMap), a clustering on/off toggle, and marker popups that link to each place's resources and a faceted search for that place.
• body (transcription/full text) — long text that becomes full-text searchable

RDF vocabularies that assist metadata entry can be managed under "Vocabularies" in the dashboard.

Ways to register

Items are registered mainly by:

• CSV bulk import (Omeka CSVImport-compatible) — upload a CSV from the dashboard's site detail. Choose the kind — item_sets (collections) / items / media — and validate (dry-run) to preview counts and error rows before importing. Sample CSVs are downloadable
• API (programmatic) — POST /dl/{db}/resources one at a time, or POST /dl/{db}/import in bulk. See Developers

Binaries such as images are uploaded directly to S3-compatible storage using a presigned URL issued by the API. When importing a media CSV you can also pick a whole folder of images: the browser uploads each file directly and matches it to a media row by the CSV's file column (relative path or filename). You can also skip the CSV and auto-generate media rows from the selected images (choosing a parent item).

Managing an item's media (dashboard)

From "Site detail" → "Manage item media" you can open an item and, from the screen, upload & attach images, reorder pages (drag / ▲▼), toggle each page public/private, delete pages, and edit the item's title and visibility. Uploaded images are turned into IIIF automatically (PTIF conversion).

Bulk registration and editing of richer metadata (dcterms:*, etc.) beyond the title still go through the CSV import or the API.

Image upload & IIIF delivery

Uploaded images can be served through the IIIF Image API (zoom, crop and arbitrary-size tiles). From the dashboard's site detail, open "Image upload (IIIF)", pick your image files and upload — that's it.

Behind the scenes:

1. Each image is uploaded directly from the browser to S3-compatible storage (the bytes never pass through the server).
2. A server-side worker converts it to a pyramidal TIFF (PTIF) with libvips. A pyramidal TIFF stores several resolutions as tiles, so the viewer never re-reads the whole image on each zoom step — large images stay fast to pan and zoom.
3. Once conversion finishes the image becomes servable and its IIIF info.json goes live. The screen shows conversion progress and, when done, a thumbnail and a link to info.json.

Conversion runs in the background, so an image shows "converting" right after upload and flips to "done" within seconds (longer for large batches). Delivery is handled by Cantaloupe, an IIIF image server that the app fronts with an authorizing proxy (the image server itself is never exposed publicly).

Visibility is per-image. At upload time it is seeded from "the site's visibility × the linked item's visibility"; afterwards you toggle each image with 🌐/🔒 in the item media manager (toggling an item propagates to its pages). Changing the site's visibility later does not automatically update existing images.

From the API

To ingest in bulk programmatically, call POST /dl/{db}/uploads with derivative:'ptif', then presign → PUT → finalize → poll the status. See the developer docs.

3D objects

If an item's metadata carries model3d (a GLB/glTF model URL), the detail page automatically switches to a 3D viewer (<model-viewer> — drag to rotate, scroll to zoom). 3D items can live in the same database as 2D image items. Related metadata:

• model3d — URL of the 3D model (GLB). Its presence triggers the 3D viewer.
• model3dOrientation — pose correction for a raw scan ("roll pitch yaw", degrees). Optional.
• thumbnail — poster image (shown while loading).
• annotations — an array of annotations (callouts pinned to points on the model). See below.

Annotations

Put annotations in metadata.annotations to render numbered markers on the model; tapping/hovering opens the title and description. Each annotation:

{
  "id": "a1",
  "title": "Tusks", "title_en": "Tusks",
  "lead": "Mammoth tusks…", "lead_en": "Mammoth tusks…",
  "position": [x, y, z],
  "normal": [x, y, z]
}

position is a point in the model's own coordinate space and follows the pose correction. Annotations are also served as a IIIF 3D manifest (below).

IIIF manifest (3D)

A 3D item is available at /api/{account}/iiif/{db}/{id}/manifest/4 as an IIIF Presentation 4.0 draft 3D manifest (Scene + GLB + point annotations). manifest/2 and manifest/3 are fallbacks for non-3D-aware clients. See the developer docs.

Smithsonian 3D collection

There is a sample importer for the Smithsonian's Open Access (CC0) 3D objects with Japanese metadata and annotations (scripts/fetch-smithsonian-3d.ts → import:smithsonian-3d).

Public / private

Each resource has its own public/private flag (is_public). A private resource never appears in listings, search or the API, even when the site itself is public. You can keep draft items private while preparing a site before publishing.

Work in progress

The CSV column spec (Omeka CSVImport-compatible mapping), supported image formats and the IIIF derivation flow, and the TEI import procedure are yet to be documented.