Archive for API

API usage

February 23, 2007 at 10:33 am · Filed under API, Documentation

Before calling image manipulation functions (addImage(), removeImg() etc) make sure the dbId used on these calls refer to an existing database space previously created with createdb()

Comments

API Reference

February 23, 2007 at 10:18 am · Filed under API, Documentation

List of functions available through XML-RPC, JSON-RPC and SOAP.

Also refer to API usage for some best practices.

Functions
array
queryImgID(dbId,
id,
numres=12,
fast=False) Return the most similar images to the supplied one.		  
number
addImg(dbId,
id,
filename,
fileIsUrl=False) Add image to database space.		  
number
saveDb(dbId)
Save the supplied database space if the it has already been saved
with a filename (previous call to
href=”#saveDbAs”
class=”link”>saveDbAs).		  
number
saveDbAs(dbId,
filename)
Save the supplied database space if the it has already been saved
with a filename (subsequent save calls can be made to
href=”#saveDb”
class=”link”>saveDb).		  
number
loadDb(dbId,
filename)
Load the supplied single-database-space-dump into a database space
of given id.		  
number
removeImg(dbId,
id)
Remove image from database space.		  
number
resetDb(dbId)
Removes all images from a database space, frees memory, reset
statistics.		  
number
createDb(dbId)
Create new db space.		  
number
shutdownServer()
Request a shutdown of this server instance.		  
number
getDbImgCount(dbId) Return count of indexed images on database space.  
boolean
isImgOnDb(dbId,
id) Return whether image id exists on database space.		  
array
getImgDimensions(dbId,
id) Returns image original dimensions when indexed into database.		  
number
calcImgAvglDiff(dbId,
id1,
id2) Return average luminance (over three color channels) difference
ratio		  
number
calcImgDiff(dbId,
id1,
id2) Return image similarity difference ratio		  
array
getImgAvgl(dbId,
id1) Return image average color levels on the three color channels (YIQ
color system)		  
array
getDbIdsBloomFilter(dbId)
Returns a byte array (bloom filter) representing image ids on this
server instance.		  
array
getDbList()
Return list defined database spaces.		  
array
getDbImgIdList(dbId)
Return list of image ids on database space.		  
map
getDbDetailedList()
Return details for all database spaces.		  
number
saveAllDbsAs(path) Persist all existing database spaces.  
boolean
addKeywordImg(dbId,
imgId,
hash) Adds a keyword to an image.		  
bloom filter
getIdsBloomFilter(dbId)
Return bloom filter containing all images on given db id.		  
boolean
getClusterKeywords(dbId,
numClusters,
keywords)
Return whether image id exists on database space.		  
boolean
getClusterDb(dbId,
numClusters)
Return whether image id exists on database space.		  
boolean
getKeywordsPopular(dbId,
numres)
Return whether image id exists on database space.		  
boolean
getKeywordsVisualDistance(dbId,
distanceType,
keywords)
Return whether image id exists on database space.		  
array
getAllImgsByKeywords(dbId,
numres,
kwJoinType,
keywords) Return all images with the given keywords		  
array
queryImgIDFastKeywords(dbId,
imgId,
numres,
kwJoinType,
keywords) Fast query (only considers average color) for similar images
considering keywords		  
array
queryImgIDKeywords(dbId,
imgId,
numres,
kwJoinType,
keywords) Query for similar images considering keywords.		  
array
mostPopularKeywords(dbId,
imgs,
excludedKwds,
count,
mode) const int dbId, imageId_list imgs, int_vector excludedKwds, int
count, int mode		  
array
getKeywordsImg(dbId,
imgId) Returns all keywords currently associated with an image.		  
boolean
removeAllKeywordImg(dbId,
imgId) Remove all keyword associations this image has.		  
boolean
removeKeywordImg(dbId,
imgId,
hash) Remove the association of a keyword to an image		  
boolean
addKeywordsImg(dbId,
imgId,
hashes) Associate keywords to image		  
number
addDir(dbId,
path,
recurse) Visits a directory recursively and add supported images into
database space.		  
number
loadAllDbsAs(path)
Loads from disk all previously persisted database spaces.		  
number
saveAllDbs()
Persist all existing database spaces on the data file defined at
the config file settings.py		  
number
loadAllDbs()
Loads from disk all previously persisted database spaces on the
data file defined at the config file settings.py		  
boolean
removeDb(dbid) Remove a database.  
map
getGlobalServerStats()
Return the most similar images to the supplied one.		  
boolean
isValidDb(dbId)
Return whether database space id has already been defined		  
 
   
   
   
   
   
   
   
   
   
   

Function Details

queryImgID(dbId,
id,
numres=12,
fast=False)

  

Return the most similar images to the supplied one.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
  • numres (number) - Number of results to return. The target image is on the result
    list.
Returns: array
array of arrays: [[image id 1, score],[image
id 2, score],[image id 3, score], …]

addImg(dbId,
id,
filename,
fileIsUrl=False)

  

Add image to database space. Image file is read, processed and
indexed. After this indexing is done, image can be removed from file
system.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id. The image located on filename will be indexed
    and from now on should be refered to isk-daemon as this supplied
    id.
  • filename (string) - Physical full file path for the image to be indexed. Should be
    in one of the supported formats (’jpeg’, ‘jpg’, ‘gif’, ‘png’,
    ‘rgb’, ‘pbm’, ‘pgm’, ‘ppm’, ‘tiff’, ‘tif’, ‘rast’, ‘xbm’, ‘bmp’).
    For better results image should have dimension of at least
    128×128. Thumbnails are ok. Bigger images will be scaled down to
    128×128.
  • fileIsUrl (boolean) - if true, filename is interpreted as an HTTP url and the remote
    image it points to downloaded and saved to a temporary location
    (same directory where database file is) before being added to
    database.
Returns: number
1 in case of success.

saveDb(dbId)

  

Save the supplied database space if the it has already been saved with
a filename (previous call to
href=”#saveDbAs”
class=”link”>saveDbAs). NOTE: This operation should be used
for exporting single database spaces. For regular server instance
database persistance, use
href=”#saveAllDbs”
class=”link”>saveAllDbs and
href=”#loadAllDbs”
class=”link”>loadAllDbs.

Parameters:
  • dbId (number) - Database space id.
Returns: number
1 in case of success.

saveDbAs(dbId,
filename)

  

Save the supplied database space if the it has already been saved with
a filename (subsequent save calls can be made to
href=”#saveDb”
class=”link”>saveDb).

Parameters:
  • dbId (number) - Database space id.
  • filename (string) - Target filesystem full path of the file where data should be
    stored at. NOTE: This data file contains a single database
    space and should be used for import/export purposes only. Do not
    try to load it with a call to
    href=”#loadAllDbs”
    class=”link”>loadAllDbs.
Returns: number
1 in case of success.

loadDb(dbId,
filename)

  

Load the supplied single-database-space-dump into a database space of
given id. An existing database space with the given id will be completely
replaced.

Parameters:
  • dbId (number) - Database space id.
  • filename (string) - Target filesystem full path of the file where data is stored
    at. NOTE: This data file contains a single database space
    and should be used for import/export purposes only. Do not try to
    load it with a call to
    href=”#loadAllDbs”
    class=”link”>loadAllDbs and vice versa.
Returns: number
dbId in case of success.

removeImg(dbId,
id)

  

Remove image from database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: number
1 in case of success.

resetDb(dbId)

  

Removes all images from a database space, frees memory, reset
statistics.

Parameters:
  • dbId (number) - Database space id.
Returns: number
1 in case of success.

createDb(dbId)

  

Create new db space. Overwrite database space statistics if one with
supplied id already exists.

Parameters:
  • dbId (number) - Database space id.
Returns: number
dbId in case of success

shutdownServer()

  

Request a shutdown of this server instance.

Returns: number
always 1

getDbImgCount(dbId)

  

Return count of indexed images on database space.

Parameters:
  • dbId (number) - Database space id.
Returns: number
image count

isImgOnDb(dbId,
id)

  

Return whether image id exists on database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: boolean
true if image id exists

getImgDimensions(dbId,
id)

  

Returns image original dimensions when indexed into database.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: array
array in the form [width, height]

calcImgAvglDiff(dbId,
id1,
id2)

  

Return average luminance (over three color channels) difference
ratio

Parameters:
  • dbId (number) - Database space id.
  • id1 (number) - Target image 1 id.
  • id2 (number) - Target image 2 id.
Returns: number
float representing difference. The smaller, the most
similar.

calcImgDiff(dbId,
id1,
id2)

  

Return image similarity difference ratio

Parameters:
  • dbId (number) - Database space id.
  • id1 (number) - Target image 1 id.
  • id2 (number) - Target image 2 id.
Returns: number
float representing difference. The smaller, the most
similar.

getImgAvgl(dbId,
id1)

  

Return image average color levels on the three color channels (YIQ
color system)

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
  • numres (number) - The y intercept of the line.
Returns: array
array of arrays: [[image id 1, score],[image
id 2, score],[image id 3, score], …]

getDbIdsBloomFilter(dbId)

  

Returns a byte array (bloom filter) representing image ids on this
server instance.

Not yet implemented

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
  • numres (number) - The y intercept of the line.
Returns: array
array of arrays: [[image id 1, score],[image
id 2, score],[image id 3, score], …]

getDbList()

  

Return list defined database spaces.

Returns: array
array of db space ids

getDbImgIdList(dbId)

  

Return list of image ids on database space.

Parameters:
  • dbId (number) - Database space id.
Returns: array
array of image ids

getDbDetailedList()

  

Return details for all database spaces.

Returns: map
map key is database space id, associated value is array with
[getImgCount, queryCount, lastQueryPerMin, queryMinCount,
queryMinCur, lastAddPerMin, addMinCount, addMinCur, addCount,
addSinceLastSave, lastId, lastSaveTime, fileName ]

saveAllDbsAs(path)

  

Persist all existing database spaces.

Parameters:
  • path (string) - Target filesystem full path of the file where data is stored
    at.
Returns: number
total db spaces written

addKeywordImg(dbId,
imgId,
hash)

  

Adds a keyword to an image.

Parameters:
  • dbId (number) - Database space id.
  • imgId (number) - Target image id.
  • hash (number) - Keyword id.
Returns: boolean
true if operation was succesful

getIdsBloomFilter(dbId)

  

Return bloom filter containing all images on given db id.

Parameters:
  • dbId (number) - Database space id.
Returns: bloom filter
bloom filter containing all images on given db id.

getClusterKeywords(dbId,
numClusters,
keywords)

  

Return whether image id exists on database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: boolean
true if image id exists

getClusterDb(dbId,
numClusters)

  

Return whether image id exists on database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: boolean
true if image id exists

getKeywordsPopular(dbId,
numres)

  

Return whether image id exists on database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: boolean
true if image id exists

getKeywordsVisualDistance(dbId,
distanceType,
keywords)

  

Return whether image id exists on database space.

Parameters:
  • dbId (number) - Database space id.
  • id (number) - Target image id.
Returns: boolean
true if image id exists

getAllImgsByKeywords(dbId,
numres,
kwJoinType,
keywords)

  

Return all images with the given keywords

Parameters:
  • dbId (number) - Database space id.
  • kwJoinType (number), Logical, operator, for, target, keywords (string @param keywords comma separated list of keyword ids. An
    empty string will return random images.) - 1 for AND, 0 for OR
Returns: array
array of image ids

queryImgIDFastKeywords(dbId,
imgId,
numres,
kwJoinType,
keywords)

  

Fast query (only considers average color) for similar images
considering keywords

Parameters:
  • dbId (number) - Database space id.
  • kwJoinType (number), logical, operator, for, keywords (string @param keywords comma separated list of keyword ids. An
    empty string will return random images.) - 1 for AND, 0 for OR
Returns: array
array of arrays: [[image id 1, score],[image
id 2, score],[image id 3, score], …]

queryImgIDKeywords(dbId,
imgId,
numres,
kwJoinType,
keywords)

  

Query for similar images considering keywords. The input keywords are
used for narrowing the search space.

Parameters:
  • dbId (number) - Database space id.
  • kwJoinType (number), logical, operator, for, keywords (string @param keywords comma separated list of keyword ids. An
    empty string will return random images.) - 1 for AND, 0 for OR
Returns: array
array of arrays: [[image id 1, score],[image
id 2, score],[image id 3, score], …]

mostPopularKeywords(dbId,
imgs,
excludedKwds,
count,
mode)

  

const int dbId, imageId_list imgs, int_vector excludedKwds, int count,
int mode

Returns the most frequent keywords associated with a given set of
images

Returns: array
array of keyword ids and frequencies: [kwd1_id, kwd1_freq,
kwd2_id, kwd2_freq, ...]

getKeywordsImg(dbId,
imgId)

  

Returns all keywords currently associated with an image.

Parameters:
  • dbId (number) - Database space id.
  • imgId (number) - Target image id.
Returns: array
array of keyword ids

removeAllKeywordImg(dbId,
imgId)

  

Remove all keyword associations this image has.

Known issue: keyword based queries will continue to consider the image
to be associated to this keyword until the database is saved and
restored.

Parameters:
  • dbId (number) - Database space id.
  • imgId (number) - Target image id.
Returns: boolean
true if operation succeeded

removeKeywordImg(dbId,
imgId,
hash)

  

Remove the association of a keyword to an image

Known issue: keyword based queries will continue to consider the image
to be associated to this keyword until the database is saved and
restored.

Parameters:
  • dbId (number) - Database space id.
  • imgId (number) - Target image id.
  • hash (number) - Keyword id.
Returns: boolean
true if operation succeeded

addKeywordsImg(dbId,
imgId,
hashes)

  

Associate keywords to image

Parameters:
  • dbId (number) - Database space id.
  • imgId (number) - Target image id.
  • hashes (list of number) - Keyword hashes to associate
Returns: boolean
true if image id exists

addDir(dbId,
path,
recurse)

  

Visits a directory recursively and add supported images into database
space.

Parameters:
  • dbId (number) - Database space id.
  • path (string) - Target filesystem full path of the initial dir.
  • recurse (number) - 1 if should visit recursively
Returns: number
count of images succesfully added

loadAllDbsAs(path)

  

Loads from disk all previously persisted database spaces. (File
resulting from a previous call to
href=”#saveAllDbs”
class=”link”>saveAllDbs).

Parameters:
  • path (string) - Target filesystem full path of the file where data is stored
    at.
Returns: number
total db spaces read

saveAllDbs()

  

Persist all existing database spaces on the data file defined at the
config file settings.py

Returns: number
count of persisted db spaces

loadAllDbs()

  

Loads from disk all previously persisted database spaces on the data
file defined at the config file settings.py

Returns: number
count of persisted db spaces

removeDb(dbid)

  

Remove a database. All images associated with it are also removed.

Returns: boolean
true if succesful

getGlobalServerStats()

  

Return the most similar images to the supplied one.

Returns: map
key is stat name, value is value. Keys are ['isk-daemon
uptime', 'Number of databases', 'Total memory usage', 'Resident
memory usage', 'Stack memory usage']

isValidDb(dbId)

  

Return whether database space id has already been defined

Parameters:
  • dbId (number) - Database space id.
Returns: boolean
True if exists

Comments

Introduction to API client libraries

February 22, 2007 at 9:34 pm · Filed under API, Documentation

Inside the docs directory of the latest release you can find client examples and libraries for Java, Python and PHP. Inside each of these you may also find a directory for some of the available technologies for communicating to an isk-daemon (XML-RPC, SOAP, etc).

Details for the POX (Plain Old XML over HTTP POST) interface are available on the directory “POX_details“. This includes XML Schema definitions and some XML command examples.

Comments

Example Java XML-RPC client project

February 22, 2007 at 12:33 am · Filed under API, Documentation, Examples

Java eclipse project with necessary xml-rpc libs included. This example project connects to an isk-daemon instance running on localhost using XML-RPC and performs basic commands like creating database spaces and adding images to it.

Download: iskClientJavaXMLRPC rev 557

Comments

POX: API calls using XML+HTTP

November 11, 2006 at 4:56 pm · Filed under API, Documentation

Among other remote procedure call technologies, the image similarity database daemon is capable of handling commands and queries through HTTP requests with POST payloads consisting of pure XML data.

WARNING: this communication interface is deprecated. New functionalities not listed below will not be available through the XML+HTTP interface on future versions .

Check the set of XML examples of API usage under docs/POX_details/pox-examples.txt for getting an idea of how to:

  • reply for a query for similar images
  • request for populating images found on the images repository on disk
  • reply for a request for populating the similarity database with new images
  • query the database for images similar to an image found on the database.

Notice that images are identified by a numeric ID supplied by you. These same IDs are used for replying back to you similarity search results.

If you want more details check the XML Schema for the API (docs/POX_details/isk.xsd)

Comments