view gengetopt.in @ 408:f0a69693eaef api-inversion

The lesser of two evils, part 1.

Most of the body of audiodb_insert_datum() will apply to
"LARGE_ADB"-type insertions: checking for the right flags, checking for
enough space free, synchronizing the header.  Wouldn't it be nice if we
could reuse all that code (or at least the bits that apply) without one
horrible almost-identical cut-and-paste job (see
batchinsert_large_adb(), or if that's not compelling enough, the four
almost-identical query loops from before the Great Refactoring).

Well, yes, it would.  Sadly C makes it mildly difficult, because its
functions are explicitly typed (so we can't pass arbitrary arguments of
other types, even if they're ABI-compatible), while its macros are
textual (which makes writing and maintaining them horrible).  The
thought of a union argument was briefly entertained and then discarded
as being just Too Weird.

So, instead, (ab)use the oldest trick in the book: void *.  Define an
adb_datum_internal_t which has void * instead of double *; the intention
is that this internal data type can be constructed both from an
adb_datum_t and some notional adb_reference_t (which looks very much
like an adb_insert_t at the time of writing, with char * structure
entries representing filenames).  This adb_datum_internal_t structure is
very much an internals-only thing, so put its definition in the
internals header.

Call what was previously audiodb_insert_datum() a new function
audiodb_insert_datum_internal(), made static so that really no-one is
tempted to call it other than ourselves.  audiodb_insert_datum() is then
trivial in terms of this new function, if stupidly tedious.  (If we were
playing dangerously, we could just perform a cast, but relying on the
fact that sizeof(double *) = sizeof(void *) would almost certainly end
up biting when we least expect.

Incidental inclusion in this patch, since I noticed it at the time:
actually check for the O2_FLAG_L2NORM before scribbling all over the
l2norm table.  Somewhat unsurprisingly, there are as yet no tests to
defend against this (harmless, as it turns out) erroneous behaviour.

package "audioDB"
version "version 0.8.preview"
purpose "A feature vector database management system for content-based retrieval."

option "verbosity" v "level of detail of operational information." int typestr="detail" default="1" optional
text "\nDatabase commands are UPPER CASE. Command options are lower case.\n" 
text ""
section "Database Operations" sectiondesc="All database operations require a database argument."

option "database" d "database file required by Database commands." string typestr="filename" optional
option "adb_root" - "path prefix for database" string typestr="path" optional

section "Database Creation" sectiondesc="Creating a new database file."

option "NEW"    N "make a new (initially empty) database." dependon="database" optional
option "size"   - "size of database file (in MB)" int dependon="NEW" optional hidden
option "datasize" - "size of data table requested (in MB)" int dependon="NEW" default="1355" optional
option "ntracks" - "capacity of database for tracks" int dependon="NEW" default="20000" optional
option "datadim" - "dimensionality of stored data" int dependon="NEW" default="9" optional

section "Database Maintenance" sectiondesc="Tweaking and dumping databases."

option "DUMP"   D "output all entries: index key size." dependon="database" optional
option "output" - "output directory" string dependon="DUMP" default="audioDB.dump" optional
option "L2NORM" L "unit norm vectors and norm all future inserts." dependon="database" optional
option "POWER"  P "turn on power flag for database." dependon="database" optional
option "LISZT"  Z "LIst keyS and siZes of Tracks" dependon="database" optional
option "lisztOffset" - "LISZT track offset (0-based index)" int typestr="number" default="0" dependon="LISZT" optional
option "lisztLength" - "number of LISZT items to return" int typestr="number" default="32" dependon="LISZT" optional

section "Database Information" sectiondesc="Information about databases."

option "STATUS" S "output database information to stdout." dependon="database" optional
option "SAMPLE" - "sample statistics for database." dependon="database" optional
option "nsamples" - "number of pairwise samples to take." dependon="SAMPLE" int typestr="number" default="2000" optional

section "Database Insertion" sectiondesc="The following commands insert feature files, with optional keys and timestamps.\n"

option "INSERT"      I "add feature vectors to an existing database." dependon="features" optional
option "adb_feature_root" - "path prefix for feature files, times files and power files" string typestr="path" optional
option "features" f "binary series of vectors file {int sz:ieee double[][sz]:eof}." string typestr="filename" dependon="database" optional
option "times"    t "list of time points (ascii) for feature vectors." string typestr="filename" dependon="features" optional
option "power"    w "binary power feature file." string typestr="filename" dependon="database" optional
option "key"      k "unique identifier associated with features." string typestr="identifier" optional
text ""
option "BATCHINSERT" B "add feature vectors named in a --featureList file (with optional keys in a --keyList file) to the named database." dependon="featureList" optional
option "featureList" F "text file containing list of binary feature vector files to process, one per track" string typestr="filename" dependon="database" optional
option "timesList"   T "text file containing list of ascii --times for each --features file in --featureList." string typestr="filename" dependon="featureList" optional
option "powerList"   W "text file containing list of binary power feature file." string typestr="filename" dependon="database" optional
option "keyList"     K "text file containing list of unique identifiers associated with --features." string typestr="filename" optional

section "Database Search" sectiondesc="These commands control the retrieval behaviour.\n"

option "QUERY" Q "content-based search on --database using --features as a query. Optionally restrict the search to those tracks identified in a --keyList." values="point","track","sequence","nsequence","onetoonensequence" typestr="searchtype" dependon="database" optional
option "qpoint" p "ordinal position of query start point in --features file." int typestr="position" default="0" optional
option "exhaustive" e "exhaustive search: iterate through all query vectors in search. Overrides --qpoint." flag off hidden
option "pointnn" n "number of point nearest neighbours to use in retrieval." int typestr="numpoints" default="10" optional
option "radius"  R "radius search, returns all points/tracks/sequences inside given radius. (Overrides --pointnn)." double default="1.0" optional 
option "expandfactor" x "time compress/expand factor of result length to query length [1.0 .. 100.0]." double default="1.1" optional hidden
option "rotate"       o "rotate query vectors for rotationally invariant search." flag off hidden
option "resultlength" r "maximum length of the result list." int typestr="length" default="10" optional
option "sequencelength" l "length of sequences for sequence search." int typestr="length" default="16" optional
option "sequencehop" - "hop size of sequence window for sequence search." int typestr="hop" default="1" optional
option "absolute-threshold" - "absolute power threshold for consideration of query or target sequence (in Bels)" double optional
option "relative-threshold" - "relative power threshold between query and target sequence (in Bels)" double dependon="QUERY" optional

section "Locality-sensitive hashing (LSH) parameters" sectiondesc="These parameters control LSH indexing and retrieval\n"

option "INDEX"  X "build an index for -d database at -R radius and -l sequenceLength" dependon="radius" optional
option "lsh_w" - "width of LSH hash-function bins. " double default="4.0" dependon="INDEX" optional hidden
option "lsh_k" - "even number of independent hash functions to employ with LSH" int typestr="size" default="8" dependon="INDEX" optional
option "lsh_m" - "number of hash tables is m(m-1)/2" int typestr="size" default="5" dependon="INDEX" optional
option "lsh_N" - "number of rows per hash tables" int typestr="size" default="100000" dependon="INDEX" optional
option "lsh_b" - "number of tracks per indexing iteration" int typestr="size" default="500" dependon="INDEX" optional
option "lsh_ncols" - "number of columns (collisions) to allocate for FORMAT1 LSH serialization" int typestr="size" default="250" dependon="INDEX" optional hidden
option "lsh_exact" - "use exact evaluation of points retrieved by LSH." flag off dependon="QUERY"
option "lsh_on_disk" - "Construct LSH hash tables for on-disk query (INDEX/QUERY)" flag off
option "lsh_use_u_functions" - "use m independent hash functions combinatorically to approximate L independent hash functions." flag off

section "Normalization control parameters" sectiondesc="These parameters control the normalization of feaures at query time\n"

option "no_unit_norming" - "do not unit norm features when querying an L2Norm databases." flag off

section "Web Services" sectiondesc="These commands enable the database process to establish a connection via the internet and operate as separate client and server processes.\n"

option "SERVER" s "run as standalone web service on named port." int typestr="port" default="14475" optional
option "load_index" - "make web service with memory-resident hashtables" flag off dependon="radius"
option "client" c "run as a client using named host service." string typestr="hostname:port" optional


text "
Copyright (c) 2007-2008 Michael Casey, Christophe Rhodes
                  Goldsmiths, University of London"