📄 library.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<head>
<title>Usage of this Library</title>
</head>
<body bgcolor=white>
<h1>Usage of this Library</h1>
<hr>
<ul>
<li><a href="#preliminaries">Preliminaries</a></li>
<li><a href="#features">Features</a>
<ol>
<li><a href="#dynamic">Dynamic construction methods</a>
<ul>
<li>Creating an empty index file.</li>
<li>Opening an existing index file.</li>
<li>Closing an index file.</li>
<li>Storing a data point into an index file.</li>
<li>Removing a data point from an index file.</li>
</ul>
</li>
<li><a href="#static">Static construction method</a>
<ul>
<li>Building an index for a given data set.</li>
</ul>
</li>
<li><a href="#search">Search methods</a>
<ul>
<li>Running nearest-neighbor search with an index.</li>
<li>Running colored nearest-neighbor search with an index.</li>
<li>Running range search with an index.</li>
</ul>
</li>
<li><a href="#misc">Miscellaneous methods</a>
<ul>
<li>Obtaining profile information of an index manipulation.</li>
</ul>
</li>
</ol>
</li>
</ul>
<hr>
<a name="preliminaries"></a><h2>Preliminaries</h2>
<ul>
<li><b>C++ and C language interfaces are provided.</b>
<blockquote>
The major part of this library is written in C++. In addition, the
interface for the C language programs is also provided.
</blockquote>
<li><b>Java-like convention is used.</b>
<blockquote>
In order to enhance the readability and maintainability of the source
code, this library is written in Java-like convention. For example,
when we allocate an object of the class `<code>Foo</code>' and invoke
its method `<code>bar</code>', then we write the following code:
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++)
{
/* variable declaration
*
* NOTE:
* Variables are allocated only for referencing objects.
*/
Foo foo;
/*
* object allocation
*
* NOTE:
* An object is instantiated by the special function
* whose name is the concatenation of the prefix `new_'
* and the class name `Foo'.
* The standard operator `new' is not used here.
*/
foo = new_Foo();
/* method invocation */
foo.bar();
/*
* NOTE:
* The allocated object will be deleted automatically based on
* the reference count.
*/
}
(C )
{
/*
* variable declaration
*
* NOTE:
* When using the C language interface, the class `Foo' is
* represented by the structure whose name is the
* concatenation of the class name `Foo' and the suffix `St'.
*/
FooSt *foo;
/* object allocation */
foo = FooSt_allocate();
/* method invocation */
FooSt_bar(foo);
/*
* NOTE:
* When using the C language interface, allocated objects
* must be deleted explicitly.
*/
FooSt_free(foo);
}
</pre>
</td></tr></table>
</blockquote>
<p>
When using the C++ language interface, the object is allocated through
`<code>new_Foo()</code>'. This expression is not equivalent to
`<code>new Foo()</code>' which invokes the operator
`<code>new</code>'. The function `<code>new_Foo()</code>' is a special
function which instantiates an object of the class `<code>Foo</code>'.
This special constructor enables us to have the Java semantics for the
object instantiation, i.e., variables are allocated only for
referencing objects and instantiated objects are automatically
reclaimed on losing references to themselves.
</p>
</blockquote>
</li>
<li><b>Header files</b>
<blockquote>
<blockquote>
<pre>
(C++) HnSRTree/HnSRTreeFile.hh
(C ) HnSRTree/HnSRTreeFileSt.h
</pre>
</blockquote>
This library has two language interfaces:
the C++ language interface and the C language interface.
The header file `HnSRTreeFile.hh' is provided for the C++
users and `HnSRTreeFileSt.h' is for the C users.
</blockquote>
</li>
<li><b>Libraries</b>
<blockquote>
<blockquote>
<pre>
(C++ and C) libHnSRTree.a
</pre>
</blockquote>
Although this library has the C language interface, the body of this
library is written in C++. Therefore, a C++ linker is required to link
your object files with this library even if your object files are
compiled only with the C compiler.
</blockquote>
</ul>
<hr>
<a name="features"></a><h2>Features</h2>
<a name="dynamic"></a><h3>1. Dynamic construction methods</h3>
<ul>
<li><a name="create"></a><b>Creating an empty index.</b>
<blockquote>
The following functions create an index file and return the pointer to
a data structure associated with that file.
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++) HnSRTreeFile new_HnSRTreeFile(const char *path,
int dimension,
int attributeSize,
const HnProperties &properties);
(C ) HnSRTreeFileSt *HnSRTreeFileSt_create(const char *path,
int dimension,
int attributeSize,
const HnPropertiesSt *properties);
path : the name of an index file.
dimension : the dimensionality of the search space.
attributeSize : the size of an attribute associated with each data
point (in bytes).
properties : properties of the index.
</pre>
</td></tr>
</table>
See also <a href="classes.html#HnProperties">HnProperties</a>.
</blockquote>
<p>
The argument `<code>attributeSize</code>' determines the size of an
attribute associated with each data point. The current implementation
allocates a fixed-size attribute for each data point stored in an
index file. The attribute can be used to store additional information
on each data point, e.g., the identifier, the label, etc. Thus, the
value of the argument `<code>attributeSize</code>' needs to be large
enough to contain the information to be stored along with data points.
For example, if you want to store 4-byte integers in the attribute
field, the value of the argument `<code>attributeSize</code>' must be
4 at least; if you want to store character strings whose length is up
to 128 bytes (including the null terminator), the value of the
argument `<code>attributeSize</code>' must be equal to or greater than
128. The smaller attribute size makes the index file more
compact. Therefore, it is recommended to make the attribute size as
small as possible.
</p>
<p>
The last argument `<code>properties</code>' is the set of label-value
pairs, whose data type is the class <a
href="classes.html#HnProperties">HnProperties</a>. This argument is
used to override the default properties of the index file. If you want
to use the default properties, the following null values can be set to
the argument `<code>properties</code>':
</p>
<blockquote>
<pre>
(C++) HnProperties::null
(C ) NULL
</pre>
</blockquote>
<p>
The following properties can be specified through the argument
`<code>properties</code>'.
</p>
<blockquote>
<pre>
HnSRTreeBlockSize : the size of a block (or bucket).
(8192 by default)
HnSRTreeSplitFactor : the minimum utilization factor of a block.
(specified in percent)
(40 by default)
HnSRTreeReinsertFactor : the percentage of entries to be reinserted on
a forced reinsertion.
(30 by default)
</pre>
</blockquote>
<p>
For convenience, the labels of the above properties are defined as
macros in the header file as follows:
</p>
<blockquote>
<pre>
#define HnSRTreeBlockSize "HnSRTreeBlockSize"
#define HnSRTreeSplitFactor "HnSRTreeSplitFactor"
#define HnSRTreeReinsertFactor "HnSRTreeReinsertFactor"
</pre>
</blockquote>
<p>
You can use the above macros instead of the character string
constants.
</p>
</blockquote>
</li>
<li><b>Opening an existing index file for reading or updating.</b>
<blockquote>
The following functions open an existing index file for reading or
updating.
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++) HnSRTreeFile new_HnSRTreeFile(const char *path, const char *mode);
(C ) HnSRTreeFileSt *HnSRTreeFileSt_open(const char *path, const char *mode);
path : the name of an index file.
mode : the access mode for opening an index file.
</pre>
</td></tr>
</table>
</blockquote>
<p>
The argument `<code>mode</code>' specifies the access mode for opening
an index file. Mode <code>"r"</code> is for reading and mode <code>"rw"</code>
is for updating.
Upon successful completion, the function returns an object of the
class `<code>HnSRTreeFile</code>' (or `<code>HnSRTreeFileSt *</code>')
which is associated with the opened index file. Otherwise, the
following constants are returned and the global variable
`<code>errno</code>' is set to indicate the error.
<blockquote>
<pre>
(C++ ) HnSRTreeFile::null
(C ) NULL
</pre>
</blockquote>
</blockquote>
</li>
<li><b>Closing an index file.</b>
<blockquote>
The following functions close an index file.
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++) void file.close(void);
(C ) void HnSRTreeFileSt_close(HnSRTreeFileSt *file);
file : the pointer to a data structure associated with an index file.
</pre>
</td></tr>
</table>
</blockquote>
</blockquote>
</li>
<li><b>Storing a data point into an index file.</b>
<blockquote>
The following functions store a point into an index file.
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++) void file.store(const HnPoint &point,
const HnDataItem &dataItem);
(C ) void HnSRTreeFileSt_store(HnSRTreeFileSt *file,
const HnPointSt *point,
const HnDataItemSt *dataItem);
file : the pointer to a data structure associated with
an index file.
point : a point being stored.
dataItem : an attribute being stored with the point.
</pre>
</td></tr>
</table>
See also <a href="classes.html#HnPoint">HnPoint</a>,
<a href="classes.html#HnDataItem">HnDataItem</a>.
</blockquote>
The current implementation imposes no restriction on the duplication
of points and attributes. This reduces the overhead of insertion since
the duplication test is avoided. The same point-attribute pairs can be
stored in an index file. The duplication of point-attribute pairs does
not harm the functionality of this library.
</blockquote>
</li>
<li><b>Removing a data point from an index file.</b>
<blockquote>
The following functions remove a point from an index file.
<blockquote>
<table border=1 bgcolor=lightyellow cellpadding=10>
<tr><td>
<pre>
(C++) void file.remove(const HnPoint &point,
const HnDataItem &dataItem);
(C ) void HnSRTreeFileSt_remove(HnSRTreeFileSt *file,
const HnPointSt *point,
const HnDataItemSt *dataItem);
file : the pointer to a data structure associated with an index file.
point : a point being removed.
dataItem : an attribute being removed.
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -