Placeholder Thumbnail Specification
Purpose
As we have pointed out in PicurlConcept, a Placeholder Thumbnail represents the original high-resolution image not just in a visual way. It also inherits its metadata (EXIF and IPTC), which allows advanced image searches using picurl or other metadata managing tools. For Photos hosted on photosharing platforms, picurl also does some Metadata conversion, e.g. Flickr tags get converted are converted to IPTC keywords).
Special picurl directives (see below) allow picurl the retrieval of original versions, albums or other advanced information.
Placeholder Thumbnail format and location
For the sake of performance, picurl currently doesn't create thumbnails of indexed photos by itself. Instead it knows two different methods to obtain them:
- extracting an embedded thumbnail from the image (EXIF header, Note: by default all digital still cameras embed a thumbnail to their photos.)
- fetching external thumbnail files: picurl can auto-detect the presence of an external thumbnail file, if its url can be derived from the source image url (e.g. by adding suffixes).
The great advantage of these methods is that picurl only needs to read/download some kilobytes of data, whereas size of the source image can be a few megabytes. If picurl created the thumbnail by itself, it would have to download the entire source image.
One small disadvantage is that the dimensions/quality of the fetched thumbnails can vary. So we can only impose minimum format requirements:
- the minimum size of the thumbnail should be 100x75 pixels
- the thumbnail should show the entire photo content - no cropped thumbnails (e.g. quadratic)
All thumbnails are stored in the store checkout folder (usually in the home directory of the user).
The metadata structure of Placeholder Thumbnails
Metadata inherited from the original image
The Placeholder Thumbnail inherits EXIF and IPTC Metadata Fields from the original image. When the original image is hosted on Flickr/Picasa, the following metadata translation is done:
Flickr:
- Image Caption -> IPTC Headline
- Image Description -> IPTC Caption
- Tags -> IPTC Keywords
- Upload Date -> IPTC Digitization Time
- License -> IPTC Copyright string (together with Flickr User Name/Real Name)
- Geo Information -> Exif/GPS Coordinates
- Original Dimensions -> Exif/ImageWidth Exif/ImageLength (possible conflict with JPEG Marker?)
- Photoset -> picurl Album Directive
Picasa:
TBD
picurl RSS - embedding picurl-specific data in the placeholder thumbnails
picurl doesn't only copy metadata to the placeholder thumbnail, but also needs to store some picurl-specific data within the thumbnail, e.g. where to find download and/or preview urls of the photo. Furthermore we want to support multiple versions of a photo (same visual content, but in different file formats). Therefore we need a way to "group" these versions together. One last requirement is to make our xml data structure as standard-conforming as possible. One way to accomplish this is a rss 2.0 module.
Location for the RSS module string
The picurl RSS module string is stored in the Exif.Photo.!UserComment Field. It doesn't include any RSS/XML preamble as it is intented to be inserted in a full RSS feed later.
Namespace declaration
The namespace for picurl RSS is defined as: http://picurl.org/picurl-rss.
This namespace IS NOT saved in the placeholder thumbnails, but it has to be included later in the RSS header, when the data is inserted in an RSS feed, e.g.
<rss version="2.0" xmlns:picurl="http://picurl.org/picurl-rss/">
Primary Elements
<picurl:set>
<picurl:set> is a sub-element of <item>. It is used to group more <picurl:photo> elements that contain the same visual content, but in different representations (e.g. different resolution or file format). <picurl:set> is mandatory, and must thus also be used when there is only one <picurl:photo>.
<picurl:photo>
this element holds all picurl-specific metadata of a photo in its attributes. By "picurl-specific" we mean all metadata that can't be stored in EXIF or IPTC fields.
<picurl:photo
url="http://example.com/photos/myphoto.jpg"
previewurl="http://example.com/photos/show_myphoto.html"
type="image/jpeg"
width = "3200"
height = "2400"
size="1203283"
phc = "957f1586c5d69e8f172f2ec0f4c17511972590fc"
storetype="online"
indexdate = "Fri, 22 Apr 2008 20:23:11 GMT"/>
url specifies the direct download url of the photo file. For local urls use the file:// scheme.
previewurl refers to a ressource where a low-res version of the photo is available for preview purposes. This can be e.g. a flickr photo page or a preview page of some photo gallery software. The previewurl may also point to directly to a low-res version of the image intended for preview purposes.
type: states the MIME type of the photo.
width, height: width and height of the photo in pixels.
size: the filesize of the photoin bytes.
phc: is the post-header-checksum of the photo
storetype (online | offline | removeable): defines if the image is stored at an online or offline computer (webserver vs. local PC) or at some removeable media.
indexdate: describes when picurl created this placeholder thumbnail. we need this to avoid unnecessary downloads (If-Modified-Since-Request).
The following attributes are mandatory: url, type, width, height, phc, storetype, indexdate
Optional Elements
The following elements are optional and may appear as sub-elements of <picurl:set>. Since a set contains references to multiple versions of the same image, these elements apply to all <picurl:photo> nodes.
<picurl:rating>: allows the rating of the photo regarding different criteria.
<picurl:rating scheme="urn:stars">5</picurl:rating>
a rating scheme that allows the user to assign 0-5 stars to a photo.
<picurl:rating scheme="urn:action">edit</picurl:rating>
allows the user to assign different tasks to a photo. Valid actions are:
- edit: tell picurl to open this photo in a photo editor on demand
- select: permanentely save this photo as selected
- hide: hide this photo from inclusion in rss feeds
<picurl:rating scheme="urn:icra">r (cz 1 lz 1 nz 1 oz 1 vz 1)</picurl:rating>
includes an ICRA rating (explicit content) to the placeholder thumbnail
Examples
picurl RSS fragment saved in a placeholder thumbnail file (without linebreaks):
<?xml version="1.0" encoding="utf-8"?>
<picurl:set>
<picurl:photo
url="http://example.com/photos/myphoto.jpg"
previewurl="http://example.com/show_myphoto.html"
type="image/jpeg"
width="3200"
height="2400"
size="1203283"
phc="957f1586c5d69e8f172f2ec0f4c17511972590fc"
storetype="online"
indexdate="Fri, 22 Apr 2008 20:23:11 GMT"/>
<picurl:photo
url="file://c:/myphotos/myphoto_edited.tif"
type="image/tiff"
width="2000"
height="1500"
size="7223221"
phc="f00a577956645153fd9b161d772c6f5c1026e435"
storetype="offline"
indexdate="Sun, 24 Apr 2008 12:13:01 GMT"/>
<picurl:rating scheme="urn:stars">4</picurl:rating>
</picurl:set>
The same fragment embeded to a RSS feed:
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="xsl/feed.xsl"?>
<rss version="2.0" xmlns:picurl="http://picurl.org/picurl-rss/">
<channel>
<title>Contents of http://example.com/photos</title>
<link>http://example.com/photos</link>
<description>1 indexed photos at http://example.com/photos </description>
<generator>picurl 0.0.3</generator>
<docs>http://blogs.law.harvard.edu/tech/rss</docs>
<item>
<title>This is either the IPTC.Headline or the filename</title>
<link>http://example.com/myphoto.jpg</link>
<description>This is IPTC.Caption</description>
<picurl:set>
<picurl:photo
url="http://example.com/photos/myphoto.jpg"
previewurl="http://example.com/show_myphoto.html"
type="image/jpeg"
width="3200"
height="2400"
size="1203283"
phc="957f1586c5d69e8f172f2ec0f4c17511972590fc"
storetype="online"
indexdate="Fri, 22 Apr 2008 20:23:11 GMT"/>
<picurl:photo
url="file://c:/myphotos/myphoto_edited.tif"
type="image/tiff"
width="2000"
height="1500"
size="7223221"
phc="f00a577956645153fd9b161d772c6f5c1026e435"
storetype="offline"
indexdate="Sun, 24 Apr 2008 12:13:01 GMT"/>
<picurl:rating scheme="urn:stars">4</picurl:rating>
</picurl:set>
</item>
</channel>
</rss>
