Some basic usage of the od program is documented on this page.
This information is not exhaustive nor always up-to-date. See the help output of od for more information:
od --help
Contents:
Separate indices for a set of png images in a directory foo can be created with:
cd foo od --create=foo.toc --debug=1 *.png
The keypoints and descriptors for each image are stored to files named IMAGENAME.png.bin
, and the indices to files named IMAGENAME.png.idx
and IMAGENAME.png.xml
.
Alternatively, a joint index for the images can be created as follows:
od --create=foo.toc --index=foo.idx --debug=1 *.png
The joint index will be stored to files foo.idx
and foo.idx.xml
.
The detector and descriptor to be used can be selected using the --detector and --descriptor switches. The default values for both are "surf"
. See the help output of od for the lists of supported detectors and descriptors.
A joint index with filtered keypoints can be created using the --filter=threshold,filtername switch like this:
od --create=foo-filt.toc --index=foo-filt.idx --filter=67,cluster_100.txt --debug=1 *.png
With the --filter switch, the imagewise keypoints and descriptors are stored to files named IMAGENAME.FILTERSTR.bin
, where IMAGENAME refers to the original name of the image (including the suffix) and FILTERSTR is a filter-specific string (see the list of filters below). FILTERSTR can also be set on the command line as the third parameter for the filter switch: --filter=threshold,filtername,FILTERSTR.
The parameter threshold is always an integer whose meaning depends on the used filter (see below).
The parameter filtername is used to select the filter to be used, using string matching (see below). It is also the name of a real input file containing the filter data, if an input file is needed for the filter in question.
Currently there are four alternative filters: random, Hessian, SVM-based, and clustering-based filter:
"random"
. No input file needed. The threshold is is divided by 100.0 and then interpreted as a probability. Default filter string: "rndfilt"
."hessian"
. No input file needed. The threshold is interpreted as the number of keypoints that are left for each image. Default filter string: "hessfilt"
."svm"
. Also, filtername should match to a LIBSVM-format SVM model file. The threshold is is divided by 100.0 and then interpreted as a probability threshold between 0 and 1. Default filter string: "svmfilt"
."filt"
.
By default, the query images in matching are scaled down with a factor specified by ObjectDetection::DEFAULT_SCALING_FACTOR and blurred slightly to reduce the number of keypoints. The scaling can be controlled with --scale=X and the blurring can be disabled with --noblur. In Analysis mode, there can also be multiple scales that are tested one-by-one until a match is found. These scales are set as --scale=X,Y,Z.
When using separate indices, the default behaviour is to stop the process when a good-enough match is found. This is controlled by the thresholds ObjectDetection::MATCHING_NMATCHES_TH and ObjectDetection::MATCHING_NSURVIVORS_TH. Exhaustive searches can be turned on with --exhaustive.
Matching query images query1.jpg
and query2.jpg
to a created database foo.toc:
od --match=foo.toc --debug=1 query1.jpg query2.jpg
The above command will use the index specified when foo.toc
was created. A different index can be used by specifying it with the --index switch. Using separate indices can be forced with --index=noindex.
The query images can be matched to multiple databases by listing them all in the --index switch separated with commas:
od --match=foo.toc,bar.toc --debug=1 query1.jpg query2.jpg
Alternatively, the databases can be listed in a separate file, which is then given with the --matchlist switch:
od --matchlist=foobar.lst --debug=1 query1.jpg query2.jpg
The above two commands are equivalent if the contents of foobar.lst
is:
2 foo.toc bar.toc
The matching can be performed to a set of query images with known correct matches to analyse the matching accuracy with the --analyse switch:
od --match=foo.toc --analyse=queryimages.lst --debug=1
The images to analyse in the above command are listed in the queryimages.lst
file, in which each query image is followed by its correct matches (one or more) on the same line:
3 query1.jpg 8.png query2.jpg 14.png query3.jpg 5a.png 5b.png
For further analysis, the number of times each descriptor in the database is successfully matched can be recorded with the --analysekps switch:
od --match=foo.toc --analyse=queryimages.lst --analysekps=0,queryimages.kps --debug=1
The first digit in --analysekps speficies whether (0) all matches or (1) only matches surviving after the homography tests should be recorded.
The program is started in the SOAP server mode with the --soap switch:
od --match=foo.toc --soap --debug=1
By default, --soap uses the port 10000. This can be changed to X with --soap=X.
The SOAP functionality can also be tested without a database with --soapdummy or --soapdummy=X. These start a SOAP server which returns a dummy response for the SOAP requests.
If no query images are specified, images grabbed from a webcam are matched instead (press 's' to take a picture, 'q' to quit):
od --match=foo.toc --debug=1
The program quits if no webcams are found.
A prerecorded video can be used as input with the --video switch:
od --match=foo.toc --debug=1 --video=input.avi
In all of the above examples, the switch --debug=1 is used, which shows some basic information about the processing. More detailed information is shown with --debug=2. Without the --debug switch only minimal output is produced.