New IIIF API specifications drafts published

[Jon Stroop]

The IIIF Editors are pleased to announce draft revisions of the International Image Interoperability Framework Image and Presentation (formerly 'Metadata') API specifications.

• http://iiif.io/api/image/2.0/
• http://iiif.io/api/presentation/2.0/

These releases reflect a significant amount of input from both the IIIF working groups and the larger library, archives, and museum communities following roughly a year of experience either implementing or experimenting with the previous versions.

A complete list of the changes can be found on the IIIF website:

• http://iiif.io/api/image/2.0/change-log.html
• http://iiif.io/api/presentation/2.0/change-log.html

We welcome your feedback, questions, and use cases, and encourage you to submit them to the IIIF Discussion Listserv: iiif-d...@googlegroups.com. Drafts will be kept open for comment until the beginning of August, with the goal of final release in September. However, we would appreciate feedback early in order to work on and gain consensus for any necessary changes.

Sincerely,

The IIIF Image and Presentation API Editors:
Benjamin Albritton
Michael Appleby
Robert Sanderson
Stuart Snydman
Jon Stroop
Simeon Warner

-- 
Jon Stroop
Digital Initiatives Developer/Analyst
Princeton University Library
jst...@princeton.edu

[coms...@g.harvard.edu]

Congratulations on the draft!

In developing the draft, was adding capture resolution (see: http://goo.gl/SPI9Qx) considered?

Thanks,

Bill

[Robert Casties]

On 30.05.14 02:48, coms...@g.harvard.edu wrote:
> Congratulations on the draft!

Congratulations from me too!

> In developing the draft, was adding capture resolution
> (see: http://goo.gl/SPI9Qx) considered?

I was wondering about the same thing. There is

http://iiif.io/api/annex/services/#physical-dimensions

but that's on the canvas level, right?

Cheers
Robert

> On Thursday, May 29, 2014 11:22:44 AM UTC-4, Jon Stroop wrote:
>>
>> The IIIF Editors are pleased to announce draft revisions of the
>> International Image Interoperability Framework Image and Presentation
>> (formerly 'Metadata') API specifications.
>>

>> - http://iiif.io/api/image/2.0/
>> - http://iiif.io/api/presentation/2.0/

>>
>> These releases reflect a significant amount of input from both the IIIF
>> working groups and the larger library, archives, and museum communities
>> following roughly a year of experience either implementing or experimenting
>> with the previous versions.
>>
>> A complete list of the changes can be found on the IIIF website:
>>

>> - http://iiif.io/api/image/2.0/change-log.html
>> - http://iiif.io/api/presentation/2.0/change-log.html

>>
>> We welcome your feedback, questions, and use cases, and encourage you to
>> submit them to the IIIF Discussion Listserv: iiif-d...@googlegroups.com

>> <javascript:>. Drafts will be kept open for comment until the beginning

>> of August, with the goal of final release in September. However, we would
>> appreciate feedback early in order to work on and gain consensus for any
>> necessary changes.
>>
>> Sincerely,
>>
>> The IIIF Image and Presentation API Editors:
>> Benjamin Albritton
>> Michael Appleby
>> Robert Sanderson
>> Stuart Snydman
>> Jon Stroop
>> Simeon Warner
>>
>> --
>> Jon Stroop
>> Digital Initiatives Developer/Analyst

>> Princeton University Libraryjst...@princeton.edu <javascript:>
>>
>>
>


--
Dr. Robert Casties -- Information Technology Group
Max Planck Institute for the History of Science
Boltzmannstr. 22, D-14195 Berlin
Tel: +49/30/22667-342 Fax: -299

[Simeon Warner]

Hi Robert, Bill,

This was certainly discussed at considerable length and, as Robert points out, the decision was made to include this information (via physical_dimensions [1]) in the Presentation API. The key reason behind this decision is that the canvas is the construct used to relate images to the physical world which is what resolution is about. We have purposefully kept the the Image API very lean, containing only basic technical information necessary to support client applications requesting derivatives of an image necessary for display.

The immediate use case we had in mind for understanding the physical dimensions of an object represented by an image is the display of a ruler in a presentation environment. We also considered the wide range of possible images that might be served -- from an electron micrograph through scanned pages to a galactic image -- which motivated choice of a flexible scale factor with dimensions rather something like pixels per inch/mm.

Cheers,
Simeon

[1] http://iiif.io/api/annex/services/#physical-dimensions

[coms...@g.harvard.edu]

Simeon,

Thanks for the generous reply. I appreciate it.

I wish I could convince the editors to include capture resolution. In general, libraries do not encode the physical dimensions of items in catalog records. The physical dimensions that you find (sometimes) in MARC records are almost always gross estimations, and the units and encoding vary. Not a good data source.

In contrast, virtually all images have encoded capture resolution values and these can parsed by lots of different software. Armed with only a capture resolution value, and the pixel dimensions of the image, you can dynamically draw an accurate cm or inch scale. Said again, all of our images have capture resolution values and pixel dimension values ready for the taking, while very few library resources are cataloged with accurate or easily parseable physical dimension values.

BTW, the scale would not reference pixels but only standard units, inches or cm. I think we all want to draw a standard scale, I'm just suggesting that the images in our repositories already have all the information you would need if you would just pass it along to the UI.

Best,

Bill Comstock

[Robert Sanderson]

Hi Bill,

Given the capture resolution, it seems like a mathematical transformation to determine the physical dimensions of the object ... and vice versa?  If there's something that we're missing, we'd be happy to revise the current solution.

For example, if you know that the image is 1000 pixels wide, and the capture resolution is 100 pixels per inch, then the image depicts something 10 inches wide and you can record that in the Manifest.

If the canvas has a width of (for ease of the math) 2000, then the service would look like:

{

  "service": {
    "@context": "http://iiif.io/api/annex/service/physdim/1.0/context.json",
    "profile": "http://iiif.io/api/annex/service/physdim",
    "physical_scale": 0.005,
    "physical_units": "in"
  }
}
Being Canvas width of 2000 * 0.005 = 10, in the physical units given of inches.

And in reverse:

Canvas width of 2000 * 0.005 = 10 inches;

10 inches, with a 1000 pixel image covering the canvas, is 1000 pixels per 10 inches, or 100 pixels per inch.

Does that help?

Rob

--
-- You received this message because you are subscribed to the IIIF-Discuss Google group. To post to this group, send email to iiif-d...@googlegroups.com. To unsubscribe from this group, send email to iiif-discuss...@googlegroups.com. For more options, visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
---
You received this message because you are subscribed to the Google Groups "IIIF Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Rob Sanderson

Technology Collaboration Facilitator

Digital Library Systems and Services

Stanford, CA 94305

[Tom Cramer]

Bill,

you can dynamically draw an accurate cm or inch scale.

Thanks for connecting this suggestion to a concrete use case. We've heard this from other sources, too. And, other than superimposing a scale on an image, are you aware of any other use cases where this data would be valuable / useful in an interoperable rendering environment? 

In contrast, virtually all images have encoded capture resolution values and these can parsed by lots of different software.

Can you elaborate on this? I have heard skepticism--from more than one person--that the capture resolution values that may be encoded in the technical metadata of images is a.) less than omnipresent, and to boot is b.) often incorrect. Some of this reaction seems anecdotal rather than evidence-based, though. Do you know of authoritative statistics in this realm, or can you weigh in with your own anecdotal sense as an imaging professional? 

- Tom

[coms...@g.harvard.edu]

Rob,

With the pixel dimensions of the image and the capture resolution you can determine the scale of the image, but not necessarily the size of the subject (principal object) in the image frame. Images often include surrounding borders and other elements than just the subject of the image (e.g., a book page). With the scale known, you can measure the dimensions of *any* object in the frame.

Example of an image (very common) that includes a book page, surrounding background, and a color bar: http://nrs.harvard.edu/urn-3:FHCL.HOUGH:1070823?n=5 (master image pixel dimensions: 4680 X 4984, capture res: 450 ppi)

See what I mean? The area covered in the image frame is ~ 10,4 " wide, but the subject of the image, the page, is substantially smaller.. But who cares if the user is presented with an accurate dynamic scale like the spiffy one included in Mirador? The scale would be correct and would be accurately drawn regardless of the zoom level the user has dialed in.

Users want to know the size of the object in the image, not the image frame.

Maybe we're talking past each other. Maybe I have a blind spot.

Thanks,

Bill

[coms...@g.harvard.edu]

Tom,

On Friday, May 30, 2014 5:23:03 PM UTC-4, Tom Cramer wrote:

Bill,

you can dynamically draw an accurate cm or inch scale.

Thanks for connecting this suggestion to a concrete use case. We've heard this from other sources, too. And, other than superimposing a scale on an image, are you aware of any other use cases where this data would be valuable / useful in an interoperable rendering environment? 

The scale in the frame is a big win -- the biggest win.

Also, people that want to use our images independent of our interfaces often ask us for the resolution of the images we have in our repository. Example: Publishers want to know if the image they find online will be sufficient for their publications if we provide them with the master image we have stashed in our repository. Ken Burns' production company wants to know if the image resolution of our master images can support their desire to incessantly zoom around the image in their documentaries. The HarvardX production folks want to know if the images we have in the repository will support the online courses they are building.

Currently staff have to look up this information by logging into the repository. Passing this data through the API would (potentially) make it easier for staff to answer these questions, or (better) the information might be made available in interfaces so users can answer these questions without our assistance.

 

In contrast, virtually all images have encoded capture resolution values and these can parsed by lots of different software.

Can you elaborate on this? I have heard skepticism--from more than one person--that the capture resolution values that may be encoded in the technical metadata of images is a.) less than omnipresent, and to boot is b.) often incorrect. Some of this reaction seems anecdotal rather than evidence-based, though. Do you know of authoritative statistics in this realm, or can you weigh in with your own anecdotal sense as an imaging professional? 

There is some truth in this. WE are very careful to encode our capture resolutions accurately, meticulously. However, if you aren't careful to write the correct resolution value into the images you are creating, the camera software will typically dump in a random, meaningless, misleading value. For example, I just opened up an image I photographed on the weekend with my inexpensive Samsung camera and it reports the image resolution to be 300 dpi. 

Also, capture resolution values are really only meaningful for 2D images -- the vast majority of what we photograph in libraries. For an image of a 3D object or scene, there is no correct capture resolution value. If someone told you that an image of a vase was 300 dpi, it wouldn't make sense because the subject of the image has surfaces that are at captured at various distances from the camera.

FYI: The MIX, samplingFrequencyUnit element has three possible values: cm, in, and "no absolute value".

-- Bill

[Simeon Warner]

On 5/30/14 9:36 PM, coms...@g.harvard.edu wrote:
> Tom,
>
> On Friday, May 30, 2014 5:23:03 PM UTC-4, Tom Cramer wrote:
> Bill,
>
>> you can dynamically draw an accurate cm or inch scale.
>
> Thanks for connecting this suggestion to a concrete use case. We've
> heard this from other sources, too. And, other than superimposing a
> scale on an image, are you aware of any other use cases where this
> data would be valuable / useful in an interoperable rendering
> environment?
>
> The scale in the frame is a big win -- the biggest win.
>
> Also, people that want to use our images independent of our interfaces
> often ask us for the resolution of the images we have in our repository.
> Example: Publishers want to know if the image they find online will be
> sufficient for their publications if we provide them with the master
> image we have stashed in our repository. Ken Burns' production company
> wants to know if the image resolution of our master images can support
> their desire to incessantly zoom around the image in their
> documentaries. The HarvardX production folks want to know if the images
> we have in the repository will support the online courses they are building.

In all three of these use cases I think the things that are required are
the pixel dimensions of the image and information about intended use
(printed size in the publication case; desired resolution at desired
zoom in zoom case) -- the capture resolution would be used only to
determine number of pixels in combination with original physics size.
Pixel dimensions are of course part of the Image API.

I think we adopted something very similar to MIX except that the IIIF
Presentation API assumes square pixels whereas MIX accounts for the
possibility of non-square pixels. From the example your April post [1]:

<mix:mix xmlns:mix="http://www.loc.gov/mix/v20">
...
<mix:SpatialMetrics>
<mix:samplingFrequencyUnit>cm</mix:samplingFrequencyUnit>
<mix:xSamplingFrequency>
<mix:numerator>118</mix:numerator>
<mix:denominator>1</mix:denominator>
</mix:xSamplingFrequency>
<mix:ySamplingFrequency>
<mix:numerator>118</mix:numerator>
<mix:denominator>1</mix:denominator>
</mix:ySamplingFrequency>
</mix:SpatialMetrics>

we'd have:

physicalWidth = imageWidth * ( denominator / numerator ) in
samplingFrequencyUnit

or using the numbers in the example

physicalWidth (cm) = imageWidth / 118 (cm)

cf. in IIIF [2] we have:

physicalWidth = width * scale_factor in physical_units

where physicalWidth of the capture area (where meaningful) is not given
in either case but can be deduced from the other values.

I think we should consider making this equation explicit in the spec to
avoid any possible confusion about which way round the scale factor is.
Have created issue [3].

I'm curious what the use case for the "no absolute value" value of
samplingFrequencyUnit in MIX is. I can't quite wrap my head around what
the samplingFrequency would mean in that case.

Cheers,
Simeon

[1]
https://groups.google.com/forum/#!msg/iiif-discuss/uut9voeev_E/mC7eXGYMcjoJ
[2] http://iiif.io/api/annex/services/#physical-dimensions
[3] https://github.com/IIIF/iiif.io/issues/209