Image API

Image API הוא ממשק RESTFul שמאפשר שליפת העתקים דיגיטליים מסוג תמונה וכן מידע אודותם.
תיעוד הממשק המלא נמצא כאן: http://iiif.io/api/image/2.1

למעשה, בכל פנייה מיוצרת עבורכם, tailor-made and on-the-fly, תמונה שעונה על בקשתכם!

תוכן העניינים

בעמוד זה תמצאו תיאור של שני השירותים הבאים:

• Image Request Service
• Image Information Service

הקדמה

לפני בקשת התמונה עליכם לבקש metadata אודות התמונה, באמצעות השירות Image Information (שירות המפורט בחלק השני של עמוד זה). שירות זה מספק מידע חשוב כמו גודל התמונה המקורית וכן מפרט מה ניתן לבקש מה-Image API ומה לא ניתן. לדוגמה, האם ניתן לבקש סיבוב (rotation) ואם כן איזה סוג (רק בכפולות של 90 או כל ערך), מה הגודל המקסימלי של תמונה שניתן לבקש וכו'.

אחר כך, כל שנותר לכם הוא לבקש את התמונה עצמה באמצעות השירות Image Request.
שימו לב! ישנן מגבלה גלובלית לגודל תמונה (פרמטר size) של 576 פיקסלים.
כדי להציג תמונה גדולה יותר, עליכם לבקש אותה ב-tiles. למעשה, אנו מעודדים אתכם להשתמש ב-tiles תמיד.
מה הרעיון של tiles? לפרוס אתהבקשה של התמונה ל-9 tiles (לדוגמה), כאשר כל tile זו בקשת נפרדת מה-Image API. גודל tile אידאלי הוא 256x256 פיקסלים. בקשת חיתוך התמונה ל-tile מתבצעת באמצעות שימוש בפרמטר region (ראו להלן).
משיכת תמונה גדולה באמצעות חלוקתה לתמונות קטנות (tiles) מאפשרת חוויית משתמש טובה יותר.

Image Request Service

קלט

הפנייה אליו נעשית באופן הבא:

http://iiif.nli.org.il/IIIFv21/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

identifier

מזהה ההעתק הדיגיטלי שרוצים לגשת אליו.
בפועל, אתם תקבלו את ה-URL המלא של הגישה ל-Image API מוטמע בתול ה-Manifest כאשר פרמטר זה יהיה מצויין מראש.

region

האיזור של התמונה שאתם רוצים לקבל.
בדרך כלל תרצו לבקש אחד מהשניים:

• full - לקבל בפלט את כל התמונה
• x,y,w,h - ציון נקודה עפ"י פיקסלים (x,y) וממנה שטח נבחר בפיקסלים (w,h). דבר זה שימושי כאשר מבקשים tile התמונה.
  דוגמה: 0,0,250,250
• pct:x,y,w,h - ציון נקודה (x,y) תוך שימוש באחוזים ולא בפיקסלים וממנה שטח נבחר באחוזים.
  דוגמה: pct:50,0,50,50 - משמעו להתחיל בנקודה שהיא באמצע רוחב התמונה (50%) אך בחלק העליון ביותר (0%), ומשם לקחת חצי מרוחב התמונה המקורי(50%) וחצי מאורך התמונה המקורי (50%)

size

מימדי התמונה שאתם רוצים לקבל (width,height).

אפשרויות נפוצות:

• ,w - ציון רוחב התמונה המבוקש בלבד. המערכת תשמר את הפרופורציה של התמונה ותחליט מה הגובה באופן אוטומטי.
• h, - ציון גובה התמונה המבוקש בלבד. המערכת תשמר את הפרופורציה של התמונה ותחליט מה הרוחב באופן אוטומטי.
• w,h! - ציון גובה ורוחב התמונה תוך בקשה לשמור על פרופורציה (תו סימן קריאה). בפועל, תוחזר התמונה הגדולה ביותר שמימדיה קטנים או שווים למצויין בבקשה.

שימו לב! לא ניתן לבקש גדלים שחורגים מ-576 פיקסלים. לכן, יש לרנדר את הבקשה שלכם ע"י tiles באמצעות שימוש בפרמטר region (ראו הסבר כללי בתחילת עמוד זה)

rotation

סיבוב התמונה (במעלות) עם כיוון השעון
שימו לב! ניתן לבצע "מראה" ע"י הוספת ! לפני הערך של הסיבוב

• 0 - ללא סיבוב
• 90
• 180
• 270
• 0! - ללא סיבוב תוך ביצוע "מראה"
• 90! - סיבוב ב-90 מעלות + "מראה"

quality

האם רוצים לקבל את התמונה בצבעים המקוריים (default) או בצבעי אפור (gray).לרוב כמובן שתשתמשו ב-default.

format

פורמט התמונה שברצונכם לקבל. כיום אנחנו תומכים רק ב-JPG.

פלט

Stream של תמונה, כבקשתכם.

במקרה של שגיאה, תקבלו חיווי שגיאה (לדוגמה, HTTP Code 404 אם הפריט לא קיים או HTTP Code 403 אם אסורה הגישה לפריט בשל מגבלת זכויות יוצרים וכו') ובגוף התשובה יהיה XML בפורמט הבא:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
<parameter>default_message</parameter>
<text>The referenced record does not exist in our database</text>
</error>

בדוגמה זו, שגיאה עבור גישה למזהה דף שאינו קיים במערכת.

דוגמאות שימוש

שימוש ב-tiles

גודל tile מקובל הוא 256X256 פיקסלים תוך שמירה על פרופורציה (כלומר, אחת הפאות תהיה 256 והשנייה 256 או קטנה יותר, בהתאמה).
דוגמה לבקשה של תמונה גדולה בחלוקה ל-4 tiles (בדרך כלל תחלקו את הפריט שלכם ליותר tiles, זוהי רק דוגמה בסיסית):

http://iiif.nli.org.il/IIIFv21/FL7070748/pct:0,0,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:0,50,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:50,0,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:50,50,50/256,/0/default.jpg

דוגמאות נוספות

שימושים נוספים:

בקשת העתק דיגיטלי של פריט ברוחב 300 פיקסלים (גובה התמונה מחושב אוטומטית כדי לשמור על פרופורציה)

http://iiif.nli.org.il/IIIFv21/FL7070748/full/300,/0/default.jpg

בקשת העתק דיגיטלי של פריט בגודל מסגרת של 300x100 פיקסלים, תוך שמירה על פרופורציה (תו סימן קריאה). המשמעות היא, המערכת תחזיר את הפריט הגדול ביותר שניתן שלא עובר את הגודל 300x100 תוך שמירה על פרופורציה.

http://iiif.nli.org.il/IIIFv21/FL7070748/full/!300,100/0/default.jpg

בקשת העתק דיגיטלי של פריט בגודל מסגרת של 300x100 בדיוק (אין שמירה על פרופורציה).

http://iiif.nli.org.il/IIIFv21/FL7070748/full/300,100/0/default.jpg