Document Model

The document model provides classes for constructing IIIF Presentation API resources from images, 3D models, annotations, and hierarchical collections.

File Resources

class timeatlas.DocumentModel.FileReference[source]

Bases: UUIDEntity, RDE

Reference to a file resource with a unique identifier.

path_name

Path to the referenced file.

Type:: str

path_name: str

get_image_metadata()[source]

Extract image metadata using PIL.

Returns:

Dictionary with ‘width’, ‘height’, and ‘format’ keys.

Raises:

IOError – If the file cannot be opened or read.
ValueError – If the file is not a valid image.

Return type:

dict

generate_page_from_file_reference(uuid_manager, label, range_idx)[source]

Generate a Page object from the file reference.

Extracts image metadata using PIL and creates a Page object.

Parameters:

uuid_manager (UUIDManager) – Manager for generating unique identifiers.
label (MultiLingualValue) – Multi-language label for the page.
range_idx (int) – Index position within a range or sequence.

Returns:

Page object with the file reference as its object_ref.

Raises:

IOError – If the image file cannot be opened.
ValueError – If the file is not a valid image.

Return type:

Page

get_model_metadata()[source]

Extract 3D model metadata based on file extension.

Returns:: Dictionary with ‘format’ key containing the MIME type.
Return type:: dict

Note

3D models don’t have standardized metadata extraction like images, so format is determined from file extension.

generate_model_from_file_reference(uuid_manager, label)[source]

Generate a Model object from the file reference.

Extracts model format from file extension and creates a Model object.

Parameters:

uuid_manager (UUIDManager) – Manager for generating unique identifiers.
label (MultiLingualValue) – Multi-language label for the model.

Returns:

Model object with the file reference as its object_ref.

Return type:

Model

__init__(id, path_name)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
path_name (str)

Return type:

None

Selectors and Annotations

class timeatlas.DocumentModel.SelectorType[source]

Bases: Enum

Enumeration of Web Annotation selector types for targeting regions.

POINT: Point selector for single coordinate (x, y).

SVG: SVG path selector for complex polygon regions.

XYWH: Rectangle selector defined by x, y, width, height.

POINT = 'PointSelector'

SVG = 'SvgSelector'

XYWH = 'SquareSelector'

class timeatlas.DocumentModel.Selector[source]

Bases: object

Web Annotation selector for targeting specific regions in a resource.

Supports three selector types: POINT (single coordinate), SVG (polygon path), and XYWH (rectangular region).

type: The selector type (POINT, SVG, or XYWH).

value: Coordinate data - tuple[int,int] for POINT, list[tuple[int,int]] for SVG, tuple[int,int,int,int] for XYWH.

source: The resource URI being targeted.

Raises:: ValueError – If value format doesn’t match the selector type requirements.

__init__(tpe, value, source)[source]

Parameters:

tpe (SelectorType)
value (tuple[int, int] | list[tuple[int, int]] | tuple[int, int, int, int])
source (str)

generate_selector_template()[source]

Generate Web Annotation selector JSON structure.

Returns:: Dictionary or string representing the selector in Web Annotation format. For POINT and SVG types, returns a SpecificResource dict. For XYWH, returns a Media Fragment URI string.
Raises:: ValueError – If selector type is not recognized.
Return type:: dict

class timeatlas.DocumentModel.Annotation[source]

Bases: UUIDEntity, RDE

Web Annotation for commenting on or linking resources.

Represents a W3C Web Annotation with optional text content, historical record reference, spatial selector, and external resource links.

lang

Language code for the annotation value (e.g., ‘en’, ‘fr’).

Type:: str | None

value

HTML text content of the annotation.

Type:: str | None

hr_id

Historical record identifier reference.

Type:: object | None

selector

Optional Selector for targeting a specific region.

Type:: timeatlas.DocumentModel.Selector | None

external_resource

URI of an external linked resource.

Type:: str | None

Raises:: ValueError – If language/value pairs are incomplete, or if required fields are missing.

lang: str | None = None

value: str | None = None

hr_id: object | None = None

selector: Selector | None = None

external_resource: str | None = None

to_iiif(uuid_manager, canvas_id, canvas_type='Canvas')[source]

Convert annotation to IIIF Presentation API format.

Parameters:

uuid_manager (UUIDManager) – Manager for generating unique identifiers.
canvas_id (str) – The canvas or resource ID being annotated.
canvas_type (str) – Type of the target resource (default: “Canvas”).

Returns:

Dictionary containing IIIF annotation in Presentation API format.

Return type:

dict

to_dict()[source]

Convert annotation to a dictionary representation.

Returns:: Dictionary containing annotation attributes.
Return type:: dict

__init__(id, lang=None, value=None, hr_id=None, selector=None, external_resource=None)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
lang (str | None)
value (str | None)
hr_id (object | None)
selector (Selector | None)
external_resource (str | None)

Return type:

None

IIIF Resources

class timeatlas.DocumentModel.Page[source]

Bases: UUIDEntity, RDE

Represents a page or canvas in an IIIF document.

A page contains an image or other visual resource with dimensions, format, and optional annotations.

label

Multi-language label for the page.

Type:: timeatlas.RDEModel.MultiLingualValue

format

MIME type of the resource (e.g., ‘image/jpeg’).

Type:: str

range_idx

Index position within a range or sequence.

Type:: int

height

Height of the resource in pixels.

Type:: int

width

Width of the resource in pixels.

Type:: int

object_ref

Path or reference to the image file.

Type:: str | timeatlas.DocumentModel.FileReference

annotations

Optional list of annotations on this page.

Type:: list[timeatlas.DocumentModel.Annotation] | None

label: MultiLingualValue

format: str

range_idx: int

height: int

width: int

object_ref: str | FileReference

annotations: list[Annotation] | None = None

to_iiif(uuid_manager, url_prefix)[source]

Convert page to IIIF Presentation API Canvas format.

Parameters:

uuid_manager (UUIDManager) – Manager for generating unique identifiers.
url_prefix (str) – Base URL prefix for the IIIF image service.

Returns:

Dictionary containing IIIF Canvas in Presentation API v3 format.

Raises:

ValueError – If object_ref is a FileReference ().

Return type:

dict

to_dict()[source]

Convert page to a dictionary representation.

Returns:: Dictionary containing page attributes.
Return type:: dict

__init__(id, label, format, range_idx, height, width, object_ref, annotations=None)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
label (MultiLingualValue)
format (str)
range_idx (int)
height (int)
width (int)
object_ref (str | FileReference)
annotations (list[Annotation] | None)

Return type:

None

class timeatlas.DocumentModel.Model[source]

Bases: UUIDEntity, RDE

Represents a 3D model resource in IIIF.

label

Multi-language label for the model.

Type:: timeatlas.RDEModel.MultiLingualValue

format

MIME type of the 3D model (e.g., ‘model/gltf-binary’).

Type:: str

object_ref

Path or reference to the 3D model file.

Type:: str | timeatlas.DocumentModel.FileReference

label: MultiLingualValue

format: str

object_ref: str | FileReference

annotations: list[Annotation] | None = None

to_iiif(uuid_manager)[source]

Convert 3D model to IIIF Presentation API Scene format.

Parameters:: uuid_manager (UUIDManager) – Manager for generating unique identifiers.
Returns:: Dictionary containing IIIF Scene in Presentation API v4 format.
Raises:: ValueError – If object_ref is a FileReference (only string paths supported).
Return type:: dict

__init__(id, label, format, object_ref, annotations=None)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
label (MultiLingualValue)
format (str)
object_ref (str | FileReference)
annotations (list[Annotation] | None)

Return type:

None

class timeatlas.DocumentModel.Document[source]

Bases: UUIDEntity, RDE

Represents an IIIF Manifest containing pages or 3D models.

A document is the primary unit for presenting a sequence of canvases/scenes with optional navigational structures.

label

Multi-language label for the document.

Type:: timeatlas.RDEModel.MultiLingualValue

items

List of pages (2D images) or models (3D scenes).

Type:: list[timeatlas.DocumentModel.Page | timeatlas.DocumentModel.Model]

structures

Optional hierarchical structure (table of contents/ranges).

Type:: dict | None

label: MultiLingualValue

items: list[Page | Model]

structures: dict | None = None

to_iiif(uuid_manager, url_prefix, presentation_version='3')[source]

Convert document to IIIF Presentation API Manifest format.

Parameters:

uuid_manager (UUIDManager) – Manager for generating unique identifiers.
label – Multi-language label dictionary.
url_prefix (str) – Base URL prefix for the IIIF image service.
presentation_version (str) – IIIF Presentation API version (‘3’ or ‘4’).

Returns:

Dictionary containing complete IIIF Manifest.

Return type:

dict

to_iiif_manifest_item(url_prefix, with_thumbnail=True)[source]

Convert document to a simplified IIIF Manifest reference.

Useful for including in Collection items arrays.

Parameters:

url_prefix (str) – Base URL prefix for the IIIF image service.
with_thumbnail (bool) – Whether to include thumbnail information.

Returns:

Dictionary with basic manifest metadata (id, type, label, optional thumbnail).

Return type:

dict

to_dict()[source]

Convert document to a dictionary representation.

Returns:: Dictionary containing document attributes and items.
Return type:: dict

__init__(id, label, items, structures=None)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
label (MultiLingualValue)
items (list[Page | Model])
structures (dict | None)

Return type:

None

class timeatlas.DocumentModel.Collection[source]

Bases: UUIDEntity, RDE

Represents an IIIF Collection containing documents or sub-collections.

Collections provide hierarchical organization of IIIF Manifests and other collections for browsing and discovery.

label

Multi-language label for the collection.

Type:: timeatlas.RDEModel.MultiLingualValue

items

List of documents (manifests) or nested collections.

Type:: list[timeatlas.DocumentModel.Document | timeatlas.DocumentModel.Collection]

presentation_version: IIIF Presentation API version for the collection (default: ‘3’).

label: MultiLingualValue

items: list[Document | Collection]

to_iiif_manifest_item(url_prefix, with_thumbnail=True)[source]

Convert a nested collection to a compact IIIF collection reference.

Parameters:

url_prefix (str)
with_thumbnail (bool)

Return type:

dict

to_iiif(url_prefix, with_thumbnails=True, presentation_version='3')[source]

Convert collection to IIIF Presentation API Collection format.

Parameters:

uuid – Unique identifier for the collection.
url_prefix (str) – Base URL prefix for the IIIF image service.
with_thumbnails (bool) – Whether to include thumbnails for items.
presentation_version (str)

Returns:

Dictionary containing IIIF Collection in Presentation API v3 format.

Return type:

dict

to_dict()[source]

Convert collection to a dictionary representation.

Returns:: Dictionary containing collection attributes and items.
Return type:: dict

__init__(id, label, items)

Parameters:

id (UUID | str | tuple[UUIDManager, str] | None)
label (MultiLingualValue)
items (list[Document | Collection])

Return type:

None

Helper Functions

timeatlas.DocumentModel.int_tuple_list_to_svg_string(tpl)[source]

Convert a list of integer coordinate tuples to an SVG path string.

Parameters:: tpl (list[tuple[int, int]]) – List of (x, y) coordinate tuples defining a closed polygon path.
Returns:: SVG string with a closed path element.
Return type:: str

Example

>>> int_tuple_list_to_svg_string([(270, 1900), (1530, 1900), (1530, 1610)])
"<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'><g><path d='M270,1900 L1530,1900 L1530,1610 L270,1900' /></g></svg>"

Note

Understanding the SVG path command: https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths

timeatlas.DocumentModel.multiindex_to_nested_dict(df)[source]

Convert a DataFrame with MultiIndex to a nested OrderedDict.

Recursively processes each level of the MultiIndex to create a hierarchical dictionary structure, with the final level containing canvas_id values.

Parameters:: df (DataFrame) – DataFrame with MultiIndex to convert.
Returns:: Nested OrderedDict representing the MultiIndex hierarchy.
Return type:: OrderedDict

Note

Source: https://gist.github.com/dcragusa/1235704accde2152faa37113cafa95c0 (simplified)

timeatlas.DocumentModel.ordered_dict_to_iiif_toc_structure(d, lan, val, range_id_pref)[source]

This function returns the IIIF ToC structure from the ordered dict. the ordered dict should be in the format “{“lvl1_label”: {“lvl2_label”: … {“lvln_label”: [canvas_id1, canvas_id2,…,canvas_idn] }…}}. Accepts multiple leveld dict.

Parameters:

d (OrderedDict)
lan (str)
val (str)
range_id_pref (str)

Return type:

dict

timeatlas.DocumentModel.url_encoded_iiif_image_url(prefix_url, path)[source]

Generate a URL-encoded IIIF image URL.

Parameters:

prefix_url (str) – The base URL prefix for the IIIF image service.
path (str) – The image path to be URL-encoded.

Returns:

Complete IIIF image URL with URL-encoded path.

Return type:

str