iqdb - Image Query Database system piespy@gmail.com Distributed under the terms of the GNU General Public License, see the file COPYING for details. 1) Compiling - install either the libGD+libpng+libjpeg, or the ImageMagick dev package Using GD, on Debian: libgd2-xpm-dev libpng12-dev libjpeg62-dev Using ImageMagick, on Debian: libmagick9-dev, on Fedora: ImageMagick-devel) - check the top of the Makefile for settings - run make - if it fails, fix the Makefile or something 2) Running The iqdb program has two operating modes: database maintenance and query server. The maintenance mode is to update image databases: add and remove images, set image properties and retrieve database stats. The query server mode listens on a TCP port for query commands and returns matching image IDs. a) Maintenance Two major modes of calling the maintenance mode: $ iqdb add foo.db This mode expects a list of image IDs and filenames on stdin, in this format: [ ]: The ID is the image ID in hexadecimal. If width and height are not specified, the values from the filename are used instead. The filename can be any image format supported by ImageMagick; the image will be resized to 128x128 and added to the database. Duplicate IDs are ignored. Note that iqdb does not remember the filename associated with an image ID, you are responsible for keeping track of that. It refers to an image exclusively by the ID. A more complex mode allows add, removing, updating and querying images for multiple databases at once: $ iqdb command foo.db bar.db baz.db This mode expects commands on stdin. For a full list see do_commands() in iqdb.cpp. The argument refers to the database on the command line, with the first argument being dbid=0. Commands of particular interest are: add [ ]: See above. remove Remove the given image from the DB. rehash This commands updates the coefficient bucket sizes. It is normally not needed, and is inefficient because it needs to read in the entire database. (As a special feature, `iqdb rehash foo.db' can be used to upgrade an old version of the DB.) done Quit and save all databases to their original file. quit Quit and save all databases to their original file. The maintenance commands (see listen mode below) are also supported in command mode, but perhaps not very useful here. Changes are automatically saved in the original file upon EOF on stdin, or when sending the "done now" or "quit now" commands. DO NOT interrupt the program with Ctrl-C or similar until the database is closed or it may become corrupted. b) Server mode In query server mode, iqdb loads the databases into memory in read-only mode to allow the fastest image queries. No database modifications are possible. $ iqdb listen [IP:]port [-r] [-d=] [-s...] foo.db bar.db baz.db Listens on the given IP:port (default localhost if no IP given) for commands, after loading the given databases. If -r is specified and the port is currently in use by another instance of iqdb, it will load the database and then terminate that instance, to reduce the downtime while loading the databases (and to leave the old server running in the rare case that it should crash while starting up). The debug level may be set with -d. The -s option allows limiting iqdb queries to the given source IPs. This is useful if you cannot bind iqdb to localhost, for instance because the query script and iqdb run on different hosts. Then you can limit iqdb requests to the host where the script is running. Note that you should probably also specify "-s" with the IP as given to the listen argument, to allow requests from the local host, for instance to add images to the database and to make the -r option work. $ iqdb listen2 [IP:]port [options...] foo.db bar.db baz.db Same as above, but listens on the given port and one port below it (i.e. if port 5588 is specified, also listens on 5587). The lower port is higher priority and all pending requests are serviced before the other port. Of particular interest are the following commands: query Find numres images most similar to given filename. If the filename starts with ':', use e.g. "./filename" to disambiguate it from the literal image data query below. Flags is a bitmask: 0 = normal operation 1 = file contains a sketch, use different weights 2 = force grayscale match, discard color information 8 = consider image width as set ID instead and return only the best match for each set 16= discard common coefficients (those present in at least 10% of all images), this finds a near-identical match much faster but the non-matching images have less similarity query <:size> As above, but if the filename argument starts with ':', the given number of bytes of literal image data starts on the next line after the command. This allows querying without first writing the image data to a file, and to query images that don't locally exist on the host running the iqdb server. multi_query [+ +...] multi_query [+ +...] <:size> Merge query results from multiple databases. This adjusts the individual scores to deal with varying similarity noise levels in different databases (the noise level depends on the number of images in the DB and how self-similar they are). query_opt