How should we handle references to multiple images?

[HadrienGardeur]

Currently, we have at least two use cases for Guided Navigation Objects that reference two or more images at a time:

• full spread (where we reference two images) or a panel across a spread (where we reference two fragments in two different images)
• and the img role in ARIA that can be used to indicate that multiple images should be presented together

When I started working on this project again, I initially thought that introducing a new property (spread) that allows more than one URI reference would be the right way to handle this, but I'm not sure that's the case anymore. This early proposal is currently available at: https://github.com/readium/guided-navigation?tab=readme-ov-file#potential-format-for-spread

I'm increasingly tempted to just rethink what's allowed in imgref and provide more specific semantics using role.

Example 1: A manga where we display a full spread before focusing on a panel across the spread

{
  "role": ["spread"],
  "imgref": ["page1.jpg", "page2.jpg"],
  "children": [
    {
      "role": ["panel"],
      "imgref": ["page1.jpg#xywh=percent:0,0,100,30", "page2.jpg#xywh=percent:0,0,100,30"]
    }
  ]
}

Example 2: img role in ARIA parsed as a Guided Navigation Object for read aloud

<div role="img" aria-label="Description of the overall image">
  <img src="graphic1.png" alt="" />
  <img src="graphic2.png" />
</div>

{
  "role": ["image"],
  "imgref": ["graphic1.png", "graphic2.png"],
  "description": "Description of the overall image"
}

I guess this could open up similar questions for textref and audioref, but let's just focus on imgref for now.

[llemeurfr]

Making imgref an array would open a can of worms (not speaking about the string/array morphing I hate):

• Is there a specific role (or set of roles, I see both "spread" and "image" in the samples) that triggers a specific processing of an array?
• what if the role does not correspond to the presence of such array?

I prefer the "spread" approach, which contains an array of "imgref" and does not require a specific role to trigger a specific behavior. If a role is added, "page" is my best bet in this case (which would remove a value from #1).

{
  "role": ["page"],
  "spread": [
    "page2.jpg", 
    "page3.jpg"
  ]
  "children": [
    {
      "role": ["panel"]
      "spread": [
        "page2.jpg#xywh=percent:0,0,100,20",
        "page3.jpg#xywh=percent:0,0,100,20"
      ]
    }
  ]
} 

[HadrienGardeur]

My main concern about the spread property is that it's currently called "spread" and not something else.

We also have a spread role and there are use cases for that over a single image and multiple images.

Example 1: Spread represented using a single image that covers both pages

"readingOrder": [
   {
    "href": "cover.jpg",
    "type": "image/jpeg",
    "rel": "cover"
    "properties": {
      "page": "right"
    }
  },
  {
    "href": "spread.jpg",
    "type": "image/jpeg",
    "properties": {
      "page": "center"
    }
  }
]

"guided": [
  {
    "role": ["cover"]
    "imgref": "cover.jpg"
  },
  {
    "role": ["spread"]
    "imgref": "spread.jpg",
    "children": [
      {
        "role": ["panel"],
        "imgref": "spread.jpg#xywh=percent:0,0,100,20"
      }
    ]
  }
]

Example 2: Spread represented using two images

"readingOrder": [
   {
    "href": "cover.jpg",
    "type": "image/jpeg",
    "rel": "cover"
    "properties": {
      "page": "right"
    }
  },
  {
    "href": "page1.jpg",
    "type": "image/jpeg",
    "properties": {
      "page": "right"
    }
  },
  {
    "href": "page2.jpg",
    "type": "image/jpeg",
    "properties": {
      "page": "left"
    }
  }
]

"guided": [
  {
    "role": ["cover"]
    "imgref": "cover.jpg"
  },
  {
    "role": ["spread"]
    "spread": ["page1.jpg", "page2.jpg"],
    "children": [
      {
        "role": ["panel"],
        "spread": ["page1.jpg#xywh=percent:0,0,100,20", "page2.jpg#xywh=percent:0,0,100,20"]
      }
    ]
  }
]

Is there a specific role (or set of roles, I see both "spread" and "image" in the samples) that triggers a specific processing of an array?

I wouldn't phrase it that way.

I'd say that there are roles where we need to allow multiple image references. This would apply to image and region in the general list of roles as well as all the dedicated roles that we would introduce for comics (spread, page, panelGroup, panel at the very least).

In our JSON Schema, we could easily limit the presence of this property for referencing multiple images to objects using these roles.