ookaboo image search via the Apache Stanbol Entityhub (was Re: [IKS] [VIE] Some VIE / Widget related issues)

[Rupert Westenthaler]

Hi Sebastian, Stanbol community, IKS project Members

Introduction
=========

This mail describes how the ookaboo (http://about.ookaboo.com/) image databank 
can be searched by using the Apache Stanbol Entityhub. 

This mail describes three different usage scenarios:

(1) search images based on name
(2) search images for entities based on name
(3). search images for given dbpedia/freebase concepts

Finally (4) provides information on how to get information on different 
available image variants (icon, thumbnail, … , large, original) for found 
images.


Test Server and ookaboo Index
========================

The ookaboo dataset is now available on the IKS server

     http://dev.iks-project.eu:8081/entityhub/site/ookaboo/

The index is also downloadable form

   http://dev.iks-project.eu/downloads/stanbol-indices/

for users that want to install it locally.

The remaining part of this Mail will provide you with examples on how to use 
the ookaboo dataset via the entityhub


UseCases
========

(1) You can use the normal find queries to find images for lables

e.g.

    curl -X POST -d "name=Bischofshofen&limit=10&offset=0" 
http://dev.iks-project.eu:8081/entityhub/site/ookaboo/find

This will directly return Images - resources of rdf:type 
http://rdf.ookaboo.com/object/Image

(2) you can search for Entities by name

    curl -X POST -d 
"name=Bischofshofen&limit=10&offset=0&field=http://rdf.ookaboo.com/object/label";
 http://dev.iks-project.eu:8081/entityhub/site/ookaboo/find

This will NOT return images but Topics - "http://rdf.ookaboo.com/object/Topic";

(2.b) you can combine Entity searches with a little LDPath magic to directly 
get the pictures for suggested Entities

    curl -X POST -d 
"name=Bischofsh*&limit=10&offset=0&field=http://rdf.ookaboo.com/object/label&ldpath=@prefix
 oo : <http://rdf.ookaboo.com/object/>; schema:name = oo:label; schema:image = 
^oo:depicts;" http://dev.iks-project.eu:8081/entityhub/site/ookaboo/find

this will return the properties

    schema:name … with the name of the Entity
    schema:image … with the images for the Entity

(3) you can search for the depictions for a known DBPedia concept

In this case you will need to use the /query endpoint, because /find only 
supports text based searches

FieldQuery (application/json)

{
    "ldpath": "@prefix oo : <http:\/\/rdf.ookaboo.com\/object\/>; schema:name = 
oo:label; schema:image = ^oo:depicts; owl:samAs;",
    "constraints": [
        {
            "type": "reference",
            "field": "http:\/\/www.w3.org\/2002\/07\/owl#sameAs",
            "value": "http:\/\/dbpedia.org\/resource\/Salzburg",
        }
    ],
    "offset": "0",
    "limit": "3",
}

The "value" of the of the "reference" constraint represents the 
DBPedia/Freebase resource you want to find images for. In the above Example it 
is set to Salzburg " http://dbpedia.org/resource/Salzburg";

The RESTful Request looks like this (assuming the above field query is stored 
in the file "./fieldQuery.json"

    curl -X POST -H "Accept: application/rdf+xml" -H 
"Content-Type:application/json" --data "@fieldQuery.json" 
http://dev.iks-project.eu:8081/entityhub/site/ookaboo/query

This will return the properties 
    schema:name … with the name of the Entity
    schema:image … with the images for the Entity
    owl:sameAs … all (dbpedia and freebase entities mapped to this ookabpoo 
topic)

(3.b) Exact Picture search

You need to know, that typically a lot of Entities are redirected to a single 
Topic (e.g "http://dbpedia.org/resource/Mirabell_Palace"; -> 
"http://dbpedia.org/resource/Salzburg";). Therefore the solution (3) will give 
you Images for most DBPedia concepts, but may return Images that do actually 
show only something related and not the requested Concept itself. 

If you only want to search for exact matches you need to use 
"http://rdf.ontology2.com/vocab#akaPrimary:akaPrimary"; instead of "owl:sameAs" 
to query. See the following fieldQuery for such an example.

{
    "ldpath": "@prefix oo : <http:\/\/rdf.ookaboo.com\/object\/>; schema:name = 
oo:label; schema:image = ^oo:depicts; owl:sameAs;",
    "constraints": [
        {
            "type": "reference",
            "field": "http:\/\/rdf.ontology2.com\/vocab#akaPrimary",
            "value": "http:\/\/dbpedia.org\/resource\/Salzburg",
        }
    ],
    "offset": "0",
    "limit": "3",
}

(4) using LDPath to query additional information about Images - resources of 
rdf:type http://rdf.ookaboo.com/object/Image

(1) directly retunes Images and (2),(2.b),(3) and (3.b) provide the images as 
values of the schema:image property. This Example now shows how to easily get 
the different versions (available image sizes)

As the Entityhub supports LDPath the easiest way is to use the 
"http://dev.iks-project.eu:8081/entityhub/site/ookaboo/ldpath"; endpoint

Here is the LDPath program I used for testing:

    @prefix oo : <http://rdf.ookaboo.com/object/>;
    title = oo:title;
    icon = oo:alternativeSize[oo:sizeCode is "sq"];
    thumbnail = oo:alternativeSize[oo:sizeCode is "t"];
    small = oo:alternativeSize[oo:sizeCode is "s"];
    medium = oo:alternativeSize[oo:sizeCode is "m"];
    large = oo:alternativeSize[oo:sizeCode is "l"];

Note: This LD-Path program requires a fix in LD-Path that is currently not yet 
available to Stanbol. So if you get an NullPointerException on your local 
installation AND you use an up-to-date Stanbol version you will need to wait 
some more days. However you can use the dev.iks-project.eu:8081 server in the 
meantime.  

You should definitely use the Web interface provided by 
"http://dev.iks-project.eu:8081/entityhub/site/ookaboo/ldpath"; to test your 
LDPath programs before using the RESTful interface.

The curl command to query the Image information for

    http://upload.wikimedia.org/wikipedia/commons/0/00/Salzburger_Stadtteile.jpg

would look like that (looks very strange because you need to URLEncode the 
LDPath)

curl -X POST -d 
"context=http://upload.wikimedia.org/wikipedia/commons/0/00/Salzburger_Stadtteile.jpg&ldpath=%40prefix%20oo%20%3A%20%3Chttp%3A%2F%2Frdf.ookaboo.com%2Fobject%2F%E%3B%20title%20%3D%20oo%3Atitle%3B%20icon%20%3D%20oo%3AalternativeSize%5Boo%3AsizeCode%20is%20%22sq%22%5D%3B%20thumbnail%20%3D%20oo%3AalternativeSize%5Boo%3AsizeCode%20is%20%22t%22%5D%3B%20small%20%3D%20oo%3AalternativeSize%5Boo%3AsizeCode%20is%20%22s%22%5D%3B%20medium%20%3D%20oo%3AalternativeSize%5Boo%3AsizeCode%20is%20%22m%22%5D%3B%20large%20%3D%20oo%3AalternativeSize%5Boo%3AsizeCode%20is%20%22l%22%5D%3B%20depicts%20%3D%20oo%3Adepicts%2Fowl%3AsameAs%3B";
 http://dev.iks-project.eu:8081/entityhub/site/ookaboo/ldpath

and returns 

 [… removed json-ld header …]
  "@subject": 
"http://upload.wikimedia.org/wikipedia/commons/0/00/Salzburger_Stadtteile.jpg";,
  "icon": "http://images.ookaboo.com/photo/sq/Salzburger_Stadtteile_sq.jpg";,
  "large": "http://images.ookaboo.com/photo/l/Salzburger_Stadtteile_l.jpg";,
  "medium": "http://images.ookaboo.com/photo/m/Salzburger_Stadtteile_m.jpg";,
  "small": "http://images.ookaboo.com/photo/s/Salzburger_Stadtteile_s.jpg";,
  "thumbnail": "http://images.ookaboo.com/photo/t/Salzburger_Stadtteile_t.jpg";,
  "title": {
    "@literal": "Districts of Salzburg",
    "@language": "en"
  }
}

Note that

* the @subject is the original
* Icon ~ 75px x 75px
* thumbnail = max 100px keeping aspect ratio


This should have provide you with all the information needed to use ookaboo. If 
any additional question arrives feel free to ask.

Happy Image Searches

best
Rupert Westenthaler